@getomnichain/omnichain 0.2.0

package/docs/README.md

@@ -0,0 +1,273 @@
+# omnichain
+
+A service-agnostic abstraction layer for talking to blockchain networks. One
+shape (`Chain`, `Token`, `Address`, `UnsignedTransaction`) covers EVM
+(Ethereum / Arbitrum / Base / BNB / …), UTXO (Bitcoin / Litecoin /
+Dogecoin), Solana, and TON, with the same call surface regardless of
+underlying network.
+
+This repository is the canonical source for the SDK. It is consumed by
+sister services (depositron, pluton-back-end, gasless) as a git submodule
+mounted at each service's own `chain` directory.
+
+## What's in here
+
+| Concept | File | Purpose |
+|---|---|---|
+| `Chain` | [chain.base.ts](../chain.base.ts) | Abstract base for any chain — exposes `getBalance`, `createTransferUnsignedTransaction`, `getTransactionStatus`, address/token validation, explorer URLs |
+| `Token` | [token.ts](../token.ts) | Abstract base for an on-chain asset — `chainId`, `symbol`, `identifier` (or `NATIVE_TOKEN_IDENTIFIER`), `decimals` |
+| `Address` | [address.ts](../address.ts) | Abstract address with `canonical()` + `networkType` |
+| `UnsignedTransaction` | [unsigned_transaction.ts](../unsigned_transaction.ts) | Abstract base for an unsigned tx; per-chain subclasses add the bytes |
+| `NetworkType` | [network_type.ts](../network_type.ts) | Enum (`EVM`, `COSMOS`, `TON`, `SOLANA`, `BTC`) + `registerNonEvmChain(chainId, type)` registry |
+| `TransactionStatus` | [transaction_status.ts](../transaction_status.ts) | Abstract base — chainId, status, inclusionAt, error, balanceChanges. Per-network subclasses: `EvmTransactionStatus` (+logs, +fees), `SolanaTransactionStatus` (+fees), `UtxoTransactionStatus` (+outputs, +vsize, +confirmations, +fees) |
+| `AssetBalanceChange` | [transaction_status.ts](../transaction_status.ts) | Per-(wallet, asset) balance delta. `.balanceChangeMr: bigint` is the source of truth; `.balanceChangeHr: Decimal` is a lazy accessor derived via exact string-shift (never loses wei). `.fromHr(hr, decimals)` factory for Python-parity construction. `NestedBalanceChanges = Map<wallet, Map<assetHash, {token, change}>>` |
+| `AbstractGasPricing` + subclasses | [abstract_gas_pricing.ts](../abstract_gas_pricing.ts), [evm/evm_gas_pricing.ts](../evm/evm_gas_pricing.ts), [solana/solana_gas_pricing.ts](../solana/solana_gas_pricing.ts), [utxo/utxo_gas_pricing.ts](../utxo/utxo_gas_pricing.ts) | Python-parity explicit-fee override types. `GasPricingType = FeePriority \| AbstractGasPricing`. Type surface only in Wave 2B — per-chain builders don't consume `CreateTransferRequest.gasPricing` yet |
+| `Priority` | [priority.ts](../priority.ts) | Shared `Priority` enum (`SLOW`/`NORMAL`/`FAST`) used by per-chain `suggestGas` / `suggestFeeRate` / `suggestPriorityFeeMicroLamports` |
+| `ChainError` | [errors.ts](../errors.ts) | Module-internal error with a `kind` discriminator |
+| `addressFor(chainId, raw)` | [address.factory.ts](../address.factory.ts) | Network-aware address constructor |
+
+## Per-chain implementations
+
+| Network | Where | What it is |
+|---|---|---|
+| **EVM** (Ethereum, Arbitrum, Base, BNB, …) | [evm/](../evm) | `EvmChain` over `ethers.js` v6 + ERC-20 support — see [evm.md](./evm.md) |
+| **UTXO** (Bitcoin, Litecoin, Dogecoin + testnets) | [utxo/](../utxo) | `UtxoChain` + `BtcChain` over `bitcoinjs-lib` v7 + `coininfo` — see [utxo.md](./utxo.md) |
+| **Solana** (mainnet, devnet, testnet) | [solana/](../solana) | `SolanaChain` over `@solana/web3.js` v1 + SPL Token / Token-2022 — see [solana.md](./solana.md) |
+| **TON** | [ton/](../ton) | `TonAddress` only (no full chain yet) |
+
+## Quickstart
+
+### Construct a chain instance
+
+```ts
+import { arbitrumChain } from '@getomnichain/omnichain';
+
+const arb = arbitrumChain('https://arb1.arbitrum.io/rpc');
+await arb.getBalance('0xabc…', /* tokenIdentifier */ 'NATIVE');
+```
+
+For BTC:
+
+```ts
+import {
+  bitcoinMainnetChain,
+  BitcoinCoreTool,
+  BITCOIN_MAINNET_PARAMS,
+} from '@getomnichain/omnichain';
+
+const core = new BitcoinCoreTool({
+  baseUrl: 'http://localhost:8332',
+  user: 'user',
+  password: 'pass',
+  params: BITCOIN_MAINNET_PARAMS,
+  wallet: 'pluton-hot-wallet',
+});
+
+const btc = bitcoinMainnetChain({
+  chainId: -1,
+  utxoProvider: core,
+  rawTxProvider: core,
+  feeEstimator: core,
+  broadcaster: core,
+  chainTipProvider: core,
+});
+```
+
+For Solana:
+
+```ts
+import { SolanaMainnet, Priority } from '@getomnichain/omnichain';
+
+const cuMicroLamports = await SolanaMainnet.suggestPriorityFeeMicroLamports(Priority.NORMAL);
+const balance = await SolanaMainnet.getBalance('5gUu…');
+```
+
+### Network-aware fee suggestion (Priority)
+
+Each chain owns its own fee-suggestion math; the consumer just passes a
+`Priority` and signs whatever envelope is returned.
+
+| Chain | Method | Result | RPC call under the hood |
+|---|---|---|---|
+| EVM (`supportsEip1559`) | `chain.suggestGas(priority)` | `EvmGasEstimate { maxFeePerGas, maxPriorityFeePerGas }` | Single `eth_feeHistory` call at percentile `{SLOW:25, NORMAL:50, FAST:75}` over 10 blocks; sort tips + pick p90; 2 gwei fallback if reward rows empty; `MIN_GAS_PRICE_FLOOR` (0.05 gwei) clamp on the returned tip; RPC failure bubbles as `ChainError(RpcError)` (no defensive fallback) |
+| EVM (legacy — `!supportsEip1559`) | `chain.suggestGas(priority)` | `EvmGasEstimate { gasPrice }` only — `maxFee*` fields **undefined** (Python parity) | `eth_gasPrice` × `{SLOW:1.0, NORMAL:1.2, FAST:1.5}`; clamped up to `MIN_GAS_PRICE_FLOOR`. Consumers that always sign EIP-1559 must dispatch on `supportsEip1559` or use `isLegacyGasEstimate` and fall back to a type-0 transaction on these chains. |
+| BTC / UTXO | `chain.suggestFeeRate(priority)` | `number` (sats/vByte) | `feeEstimator.getFeeEstimate(targetBlocks)` with `FAST:1, NORMAL:3, SLOW:6` |
+| Solana | `chain.suggestPriorityFeeMicroLamports(priority)` | `number` (microlamports/CU) | `getRecentPrioritizationFees({ lockedWritableAccounts: [] })` percentiles `{SLOW:p25, NORMAL:p50, FAST:p90}`; `0` on a quiet cluster |
+
+### Build a transfer
+
+The unified entry point is `Chain.createTransferUnsignedTransaction(req)`,
+where `req` is the same shape for every chain:
+
+```ts
+const unsigned = await chain.createTransferUnsignedTransaction({
+  from: senderAddress,
+  to: recipientAddress,
+  tokenIdentifier: 'NATIVE',            // or an ERC-20 / SPL / etc. identifier
+  amount: 1_000_000n,                   // smallest unit (wei / sats / lamports)
+  memo: 'optional UTF-8 memo',          // BTC: emits OP_RETURN; EVM: ignored
+});
+```
+
+The returned object is a chain-specific subclass of `UnsignedTransaction`:
+
+- EVM → `UnsignedEvmTransaction` (`{ to, value, data, chainId }`)
+- UTXO → `UnsignedUtxoTransaction` (`{ psbtBase64, selectedInputs, feeSats, inputsToSign, … }`)
+- Solana → `UnsignedSolanaTransaction` (`{ transaction: VersionedTransaction, … }`)
+
+Signers (wallets, hardware devices, the protocol itself) take this and
+sign it externally; the chain module **does not hold keys** and **does not
+read environment variables** for credentials.
+
+### Check transaction status
+
+```ts
+import { isSuccess } from '@getomnichain/omnichain';
+
+const status = await chain.getTransactionStatus(txHash);
+// EvmTransactionStatus | SolanaTransactionStatus | UtxoTransactionStatus
+// Base fields: { chainId, status, inclusionAt, error, balanceChanges }
+// Subclass extras vary per chain (see the type table above).
+
+if (isSuccess(status)) {
+  // balanceChanges is now Map<wallet, Map<assetHash, {token, change}>>
+  for (const [wallet, perAsset] of status.balanceChanges) {
+    for (const { token, change } of perAsset.values()) {
+      // balanceChangeMr is the exact source of truth (bigint minor units);
+      // balanceChangeHr is a lazy Decimal accessor for display (Wave 2B).
+      console.log(wallet, token.symbol, change.balanceChangeMr, change.balanceChangeHr.toFixed());
+    }
+  }
+}
+```
+
+**Wallet-key case normalization** — the wallet key used in
+`NestedBalanceChanges` is chain-specific: EVM addresses are lowercased,
+Solana keys are the raw base58 (case-sensitive), UTXO keys are the raw
+provider-returned address (bech32 lower-case in practice; providers
+don't uppercase). If you do `status.balanceChanges.get(userAddress)`
+directly, normalise `userAddress` to the same form (`toLowerCase()` for
+EVM).
+
+## Error model
+
+All errors thrown by this module are `ChainError` with a typed
+`kind` field — see [errors.ts](../errors.ts):
+
+- `NotSupported`, `RpcError`, `RpcChainIdMismatch`, `TransactionDecodeFailed`,
+  `InvalidAddress`, `InvalidTokenIdentifier`, `RpcNotConfigured`
+
+Use `isChainError(err, ChainErrorKinds.InvalidAddress)` to narrow.
+
+## NetworkType registry
+
+Some addresses look identical across networks (e.g. all `0x…` 20-byte hex
+addresses are valid EVM-shaped, but a real EVM-vs-non-EVM dispatch needs
+context). The module maintains a small registry mapping `chainId →
+NetworkType` (`network_type.ts`).
+
+Behavior in v0:
+
+- **Static seeds at module load** (from `chain_ids.ts`): BTC family
+  (`-1/-2/-3`), Solana family (`-2000/-2001/-2002`), TON family
+  (`-4000/-4001`), Tron family (`728126428/2494104990`).
+- **`networkTypeOf(chainId)`**: returns the registered NetworkType if
+  present. For unregistered positive ids returns `EVM`. For unregistered
+  negative ids throws `ChainError(ChainNotSupported)` — fail-closed so a
+  stale `-100` doesn't silently misroute.
+- **`tryNetworkTypeOf(chainId)`**: non-throwing sibling; returns
+  `undefined` on unregistered negatives.
+- **`registerNonEvmChain(id, type)`**: idempotent for same type; throws
+  `ChainError(InvalidArgument)` on conflict. Since positive ids
+  synthesize EVM by default, claiming a positive id for a non-EVM
+  family requires `unregisterChain(id)` first.
+- **`unregisterChain(id)`** + **`networkTypeRegistrations()`**: escape
+  hatch and diagnostics.
+- Chain constructors (`SolanaChain`, `UtxoChain`) self-register in
+  their constructors. `EvmChain` does NOT self-register (its 48
+  pre-baked entries at module load would otherwise turn a consumer's
+  earlier `registerNonEvmChain(sameId, OTHER)` into an unrecoverable
+  import-time crash).
+
+`addressFor(chainId, raw)` reads from this registry via `networkTypeOf`
+and dispatches to the appropriate `Address` subclass — currently EVM,
+Solana, BTC, TON. TRON and COSMOS families throw `ChainNotSupported`
+(no Address parser yet).
+
+## Chain IDs
+
+- **EVM chains** use real EVM `chainId` values (1, 42161, 8453, 56, …).
+- **Non-EVM chains** — the SDK now owns a reserved negative-ID range,
+  matching `omnichain-py/chain_ids.py`:
+  - BTC family: `-1` mainnet, `-2` testnet, `-3` signet
+  - LTC `-10`, DOGE `-12`, DASH `-14`, ZEC `-16`, BCH `-18` (mainnets only — testnets for these families are not defined in v0)
+  - Solana `-2000` mainnet, `-2001` testnet, `-2002` devnet
+  - TON `-4000` mainnet, `-4001` testnet
+  Consumers **should not** invent overlapping negative IDs for their own
+  chains. `registerNonEvmChain` throws `ChainError(InvalidArgument)` on
+  family conflict. Notable overlap: TON's native `global_id = -3` collides
+  with BTC signet in this SDK — use `CHAIN_ID_TON_TESTNET` (`-4001`) for
+  TON.
+
+## Boundary: this module reads env only for RPC URL resolution
+
+Constructors take plain config objects (`baseUrl`, `user`, `password`,
+`rpcUrl`, …). The **one** exception is RPC URL fallback resolution:
+`EvmChain.readRpcUrl` and `SolanaChain.readRpcUrl` will read
+`<NAME>_RPC_URL` / `EVM_<chainId>_RPC_URL` / `SOLANA_<chainId>_RPC_URL`
+env vars if no `rpcUrl` was passed at construction. Adding a
+`process.env` read anywhere else in this SDK is a review-blocker.
+
+## Adding a new chain
+
+### New EVM chain
+Add a factory function to [evm/evm_chains.ts](../evm/evm_chains.ts):
+
+```ts
+export const POLYGON_CHAIN_ID = 137;
+export const Polygon = new EvmChain({
+  chainId: POLYGON_CHAIN_ID,
+  name: 'Polygon',
+  blockTimeSeconds: 2,
+  explorerBaseUrl: 'https://polygonscan.com',
+  nativeSymbol: 'MATIC',
+  // rpcUrl is optional. When omitted, the SDK resolves via env-var fallback:
+  //   POLYGON_RPC_URL, then EVM_137_RPC_URL, then throws RpcNotConfigured.
+});
+```
+
+The RPC URL precedence for every `EvmChain` is:
+
+1. `rpcUrl` passed at construction (wins).
+2. `<NAME_UPPERCASE_UNDERSCORED>_RPC_URL` env var (e.g. `POLYGON_RPC_URL`).
+3. `EVM_<chainId>_RPC_URL` env var.
+4. Throws `ChainError(RpcNotConfigured)` on first RPC call.
+
+Solana is similar but has a required `defaultRpcUrl` that acts as the final
+fallback instead of throwing — see [solana.md](./solana.md).
+
+### New UTXO chain
+See [utxo.md](./utxo.md) — define `UtxoNetworkParams` (use `coininfo` for
+network bytes), write a factory under the appropriate subdirectory.
+
+### New chain family entirely (Cosmos, Aptos, etc.)
+Add `Foo` enum value to [network_type.ts](../network_type.ts), create
+`foo/` with `FooChain extends Chain`, `FooAddress extends Address`,
+`UnsignedFooTransaction extends UnsignedTransaction`. Wire into
+[address.factory.ts](../address.factory.ts).
+
+## Testing layout
+
+| Spec | What it verifies |
+|---|---|
+| [test/](../test) | Address factory + registry + cross-chain glue |
+| [evm/test/](../evm/test) | EVM address parsing + EVM chain RPC mocks + `suggestGas` percentile / fallback / legacy paths |
+| [solana/test/](../solana/test) | Solana address validators + `suggestPriorityFeeMicroLamports` percentile / empty-cluster |
+| [utxo/btc/test/](../utxo/btc/test) | BTC parsing, fee math, coin selection, chain transfer round-trip with mocked providers + `suggestFeeRate` targetBlocks mapping |
+| `<consumer>/test/integration/` | Live-network smoke checks belong in the consuming service, not this SDK |
+
+## See also
+
+- [evm.md](./evm.md) — EVM chains and ERC-20
+- [utxo.md](./utxo.md) — Bitcoin / Litecoin / Dogecoin, fee estimation, asset filtering
+- [solana.md](./solana.md) — Solana, SPL Token, Token-2022, priority-fee model

package/docs/evm.md

@@ -0,0 +1,205 @@
+# EVM chains
+
+`EvmChain` covers any Ethereum-compatible chain (Mainnet, Arbitrum, Base,
+BNB, Polygon, …). It wraps `ethers.js` v6 for RPC and ERC-20 transfers.
+
+## Files
+
+- [evm_chain.ts](../evm/evm_chain.ts) — `EvmChain extends Chain`
+- [evm_address.ts](../evm/evm_address.ts) — `EvmAddress extends Address`; EIP-55 checksum-aware
+- [evm_token.ts](../evm/evm_token.ts) — `EvmToken extends Token`; native + ERC-20
+- [evm_chains.ts](../evm/evm_chains.ts) — per-chain factories (`arbitrumChain`, `baseChain`, `bnbChain`)
+- [evm_tokens.ts](../evm/evm_tokens.ts) — predefined token instances per chain
+- [unsigned_evm_transaction.ts](../evm/unsigned_evm_transaction.ts) — `UnsignedEvmTransaction` with `{ chainId, to, value, data, from? }`
+
+## Constructing a chain
+
+Each chain has a factory function that takes an optional `rpcUrl`. If
+omitted, falls back to the `<CHAIN>_RPC_URL` env var, then to
+`http://127.0.0.1:8545`.
+
+```ts
+import { arbitrumChain, baseChain, bnbChain } from 'src/modules/chain';
+
+const arb = arbitrumChain('https://arb1.arbitrum.io/rpc');
+const base = baseChain(); // reads BASE_RPC_URL
+```
+
+For chains without a pre-built factory, construct `EvmChain` directly:
+
+```ts
+import { EvmChain } from 'src/modules/chain';
+
+const polygon = new EvmChain({
+  chainId: 137n,
+  name: 'Polygon',
+  blockTimeSeconds: 2,
+  explorerBaseUrl: 'https://polygonscan.com',
+  nativeSymbol: 'MATIC',
+  rpcUrl: process.env.POLYGON_RPC_URL!,
+});
+```
+
+Use `EvmChain.create(init)` instead of `new EvmChain(...)` to verify the
+RPC actually serves the chainId you declared:
+
+```ts
+const arb = await EvmChain.create({ chainId: 42161n, /* ... */ });
+// throws ChainError(RpcChainIdMismatch) if the RPC reports a different chainId
+```
+
+## Tokens
+
+```ts
+import { EvmToken } from 'src/modules/chain';
+
+const ethArb = EvmToken.native(42161n, 'ETH');
+const usdcArb = EvmToken.erc20(
+  42161n,
+  'USDC',
+  '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+  6
+);
+```
+
+ERC-20 identifiers are normalized to EIP-55 checksum form. Constructing
+with a mixed-case address that fails the checksum throws.
+
+## Predefined tokens
+
+[evm_tokens.ts](../evm/evm_tokens.ts) exports common stablecoins per
+chain — e.g. `ARBITRUM_USDC`, `BASE_USDC`. Use these instead of typing
+addresses by hand where possible.
+
+## Addresses
+
+```ts
+import { EvmAddress } from 'src/modules/chain';
+
+const addr = new EvmAddress('0xabc…');     // throws if not 20 bytes of hex
+addr.canonical();                          // lowercase, '0x'-prefixed
+addr.toChecksum();                         // EIP-55 mixed case
+```
+
+If a caller passes a mixed-case address that doesn't match the EIP-55
+checksum, the constructor throws — this catches typos before they reach
+the chain.
+
+## Transfers
+
+```ts
+const unsigned = await arb.createTransferUnsignedTransaction({
+  from: '0xsender…',
+  to:   '0xrecipient…',
+  tokenIdentifier: 'NATIVE',          // or USDC's checksum address
+  amount: 1_000_000_000_000_000_000n, // 1 ETH = 1e18 wei
+});
+// unsigned: UnsignedEvmTransaction { chainId, to, value, data, from? }
+```
+
+For ERC-20 transfers, set `tokenIdentifier` to the token's contract
+address. The chain emits the calldata for the standard `transfer(to,
+value)` selector against that contract:
+
+```ts
+const unsigned = await arb.createTransferUnsignedTransaction({
+  from: senderAddr,
+  to: recipientAddr,
+  tokenIdentifier: ARBITRUM_USDC.identifier,
+  amount: 5_000_000n, // 5 USDC (6 decimals)
+});
+// unsigned.to === ARBITRUM_USDC.identifier
+// unsigned.data === '0xa9059cbb...' (transfer(address,uint256) selector + args)
+```
+
+Sign with whatever you'd normally use for EVM (ethers wallet, hardware
+wallet, MPC service). The chain module never touches keys.
+
+## Balances
+
+```ts
+const ethBalance  = await arb.getBalance('0xabc…', 'NATIVE');
+const usdcBalance = await arb.getBalance('0xabc…', ARBITRUM_USDC.identifier);
+// returns bigint in wei / smallest token unit
+```
+
+For unknown ERC-20s, the chain auto-resolves `decimals()` and `symbol()`
+from the contract on first balance call and caches the result.
+
+## Transaction status
+
+```ts
+const status = await arb.getTransactionStatus(txHash);
+// EvmTransactionStatus (extends TransactionStatus):
+//   status:         'Pending' | 'Success' | 'Failed' | 'NotFound'
+//   inclusionAt:    Date | null
+//   error:          TransactionErrorInfo | null
+//   balanceChanges: NestedBalanceChanges | null
+//                   = Map<walletLowercase, Map<assetHash, {token, change}>>
+//   logs:           EvmParsedTransactionLog[] | null
+//   fees:           EvmTransactionGasFees | null
+//                     .gasLimitUsed, .effectiveGasPrice, .totalGasInWei
+//                     .l1FeeWei (OP-stack rollups only)
+//                     .totalNativeDebitWei = totalGasInWei + (l1FeeWei ?? 0)
+```
+
+For ERC-20 transfers, `decodeBalanceChanges` decodes `Transfer(from, to, value)`
+logs into the nested balance-change map. On OP-stack rollups
+(Optimism/Base/Unichain/WorldChain/Boba/Sonic) the sender's native debit
+includes the receipt's `l1Fee` — this is exposed on `fees.l1FeeWei` and
+folded into the sender's `balanceChanges` row so the emitted delta
+matches the on-chain net.
+
+`Failed` status carries `balanceChanges: null` per Python parity — the
+gas that was burned is still on `fees.totalNativeDebitWei` and consumers
+reconstruct sender debits from there for reverted transactions.
+
+## Registry / wiring
+
+The `ChainRegistry` auto-loads EVM chains from `config.yaml` on module
+init — see [chain.config.ts](../chain.config.ts) for the schema. Each
+entry needs at least one provider:
+
+```yaml
+chains:
+  "42161":
+    name: Arbitrum
+    blockTimeSeconds: 0.25
+    explorerBaseUrl: https://arbiscan.io
+    nativeSymbol: ETH
+    providers:
+      - name: ankr
+        url: https://rpc.ankr.com/arbitrum/${ANKR_API_KEY}
+```
+
+To register at runtime instead:
+
+```ts
+@Injectable()
+export class MyService {
+  constructor(private readonly chains: ChainRegistry) {}
+  
+  init() {
+    const polygon = new EvmChain({ /* … */ });
+    this.chains.register(polygon);
+  }
+}
+```
+
+## Address validation
+
+```ts
+arb.validateWalletAddress('0xabc…');       // true / false
+arb.validateTokenIdentifier('NATIVE');     // true
+arb.validateTokenIdentifier('0xUSDC…');    // true if valid EVM address
+arb.validateTokenIdentifier('not-hex');    // false
+```
+
+## Cross-chain address parsing
+
+```ts
+import { addressFor } from 'src/modules/chain';
+
+const a = addressFor(42161, '0xabc…');     // EvmAddress
+const b = addressFor(-1,    'bc1q…');      // BtcAddress (BTC registered → -1)
+```