@getomnichain/omnichain 0.2.0

package/docs/solana.md

@@ -0,0 +1,220 @@
+# Solana for EVM developers
+
+A focused guide for someone who already knows EVM well. We map every concept to its EVM
+counterpart, then explain what's different.
+
+## TL;DR mapping
+
+| EVM concept | Solana counterpart | Note |
+|---|---|---|
+| Account (address) | Account (Pubkey, 32-byte ed25519) | Base58 string, no checksum |
+| ETH balance on account | Lamports owned by the *system program* | `connection.getBalance(pubkey)` |
+| ERC-20 token | SPL Token (mint) | Mint is a Solana address |
+| ERC-20 balance | Associated Token Account (**ATA**) holding the balance | Wallet does NOT hold token balances directly |
+| Transaction | Transaction (legacy or **VersionedTransaction**) | A bundle of *instructions* |
+| Calldata | Instructions calling Programs | One tx may contain N instructions targeting different programs |
+| `msg.sender` | Account signers list | Multiple signers per tx; first signer is the fee payer |
+| Nonce | Recent blockhash + last valid block height | No per-account monotonic nonce — blockhash expiry replaces it |
+| Gas units | Compute Units (CU), default 200k per ix | `ComputeBudgetProgram.setComputeUnitLimit(...)` |
+| Gas price | Base fee (5,000 lamports per signature) + **priority fee** in microlamports/CU | Set via `ComputeBudgetProgram.setComputeUnitPrice(...)` |
+| EIP-1559 priority fee | Same idea — `setComputeUnitPrice` is the lever | No `maxFeePerGas` cap; the price you set IS the price |
+| Replace-by-fee (RBF) | Not supported | Once submitted, you can't bump. Just sign a higher-fee tx with the *same* blockhash within its validity window. |
+| Mempool | Leader's local mempool | Not consensus mempool; tx flows directly to current/next leader |
+| `eth_chainId` | Genesis block hash (CAIP-2 `solana:<first-32-of-hash>`) | Synthetic negative chainIds: mainnet `-2000`, testnet `-2001`, devnet `-2002` (matches omnichain-py `chain_ids.py`). The pre-v0 `-100/-101/-102` scheme is **NOT** registered as aliases — `networkTypeOf(-100)` throws `ChainError(ChainNotSupported)` at validation. Consumers must run `migrateLegacySolanaChainId(id)` on persisted rows *before* the value enters the SDK. |
+| Finality | `processed → confirmed → finalized` | We use `confirmed` for status reads (~12 slots ≈ 5 s) |
+| Block time | ~12 s | ~0.4 s |
+
+## Accounts are everything
+
+The single biggest difference: **all state lives in accounts**. There is no "contract storage
+slot" model. Every piece of mutable data — token balances, NFT metadata, user preferences,
+swap pools — is its own Solana account, owned by some program.
+
+```
+Account {
+  pubkey:    Pubkey   // base58 32-byte ed25519 public key
+  lamports:  u64      // native SOL balance (in 1e-9 units)
+  owner:     Pubkey   // the program that controls this account's data
+  data:      bytes    // the program decides the layout
+  executable: bool    // true for programs themselves
+  rent_epoch: u64     // legacy
+}
+```
+
+`owner` is the killer concept. A "user wallet" is owned by the **System Program**
+(`11111111111111111111111111111111`). When the System Program owns an account, *only* it can
+move that account's lamports. That's why `SystemProgram.transfer({fromPubkey, toPubkey,
+lamports})` is the only way to move SOL between wallets — the System Program is the program
+that knows how to debit `from` and credit `to`.
+
+For SPL tokens, the **SPL Token Program** (`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`) owns
+the token accounts. Two flavours: classic SPL Token (above) and **Token-2022**
+(`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`). They're separate program IDs with mostly
+overlapping instruction layouts. **You must use the right program ID** for the mint at hand.
+The SDK reads the mint account's `owner` field to figure out which.
+
+## Transactions are instruction lists
+
+A Solana transaction is `Vec<Instruction>` plus signers and a recent blockhash. Each
+instruction is `{ program_id, accounts: Vec<Account>, data: Vec<u8> }`. The program_id field
+routes execution to a specific program; `data` is the instruction-specific calldata; `accounts`
+declares every account the instruction reads or writes (Solana is **explicit about side effects**
+— if you don't list an account in `accounts`, the instruction can't touch it).
+
+```ts
+// EVM mental model — one call per tx:
+contract.transfer(to, amount);
+
+// Solana mental model — N instructions, each calling a program:
+new TransactionBuilder([
+  ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }),
+  ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1000 }),  // priority fee
+  createAssociatedTokenAccountInstruction(payer, ata, owner, mint, programId), // create-ATA if missing
+  createTransferCheckedInstruction(sourceAta, mint, destAta, owner, amount, decimals, [], programId),
+]);
+```
+
+Multiple instructions execute **atomically**: if any one fails (program error, account
+constraint violation, missing signer), the whole transaction is rolled back. Solana's
+equivalent of "revert" is `InstructionError` with a program-defined code.
+
+### MessageV0 (VersionedTransaction)
+
+Legacy transactions allow up to ~35 unique accounts before exceeding the 1232-byte tx limit.
+**MessageV0** (versioned) supports Address Lookup Tables (ALTs) that pack repeated accounts
+into 1-byte indices, raising the practical limit to hundreds. The depositron chain SDK
+always emits MessageV0; legacy is essentially deprecated.
+
+## Native SOL transfer
+
+```ts
+import { SystemProgram, VersionedTransaction, MessageV0, Connection } from '@solana/web3.js';
+
+const connection = new Connection(rpcUrl, 'confirmed');
+const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+const message = MessageV0.compile({
+  payerKey: senderPk,
+  instructions: [SystemProgram.transfer({ fromPubkey: senderPk, toPubkey: receiverPk, lamports: 1_000_000n })],
+  recentBlockhash: blockhash,
+});
+const tx = new VersionedTransaction(message);
+tx.sign([senderKeypair]);
+const signature = await connection.sendRawTransaction(tx.serialize());
+```
+
+That `signature` IS the transaction hash. Solana txs are uniquely identified by the
+first signature (base58, 88 chars).
+
+## SPL token transfer — the ATA gotcha
+
+A wallet `Owner` doesn't hold token X directly. Instead, the wallet has one **Associated
+Token Account** (ATA) per (mint, program_id) pair. The ATA address is a deterministic PDA
+(Program-Derived Address) of `(owner, mint, token_program_id)`. You always have to:
+
+1. Derive `source_ata = ATA(sender, mint, program)`.
+2. Derive `dest_ata = ATA(recipient, mint, program)`.
+3. If `dest_ata` doesn't exist on chain, **prepend** a `createAssociatedTokenAccount` ix to
+   the tx (the sender pays ~0.00203 SOL rent-exempt deposit, locked in the ATA forever).
+4. Add `transferChecked(source_ata, mint, dest_ata, sender, amount, decimals, programId)`.
+
+`transferChecked` is preferred over `transfer` because it includes the mint and decimals in
+the instruction — the program verifies them, defeating "wrong-decimals" UI attacks. Use
+`transferChecked` everywhere.
+
+## Priority fees
+
+There is no `maxPriorityFeePerGas` / `maxFeePerGas` split. Two knobs:
+
+- `setComputeUnitLimit(units)` — your declared budget. Charged for whichever is smaller:
+  actual CU used or this limit. Default cap is 200k per ix, max 1.4M per tx.
+- `setComputeUnitPrice(microLamports)` — price per CU. **This is the priority fee.** A value
+  of 1000 microlamports/CU at a 200k limit costs `0.0002 SOL = 200k × 1000 / 1e9`.
+
+Depositron maps its `Priority` enum:
+
+| Priority | microLamports per CU |
+|---|---|
+| `SLOW`   | 0 |
+| `NORMAL` | 100 |
+| `FAST`   | 1000 |
+
+## No nonce — blockhash expiry instead
+
+You include a **recent blockhash** in every transaction. The validator accepts the tx only if
+the blockhash is still within ~150 slots (~1 minute) of the current tip. After that, the tx is
+permanently invalid; you can't re-submit. To "retry" you rebuild with a fresh blockhash.
+
+This is depositron's "PSBT-replay-impossible" property for free — once a Solana tx expires, it
+can't be revived. The trade-off: you can't pre-sign + delay submission for >1 minute.
+
+## Status polling
+
+`getSignatureStatus(sig)` returns `{ confirmationStatus: 'processed'|'confirmed'|'finalized',
+err: null|object }`. Depositron treats `confirmed | finalized` as terminal success
+(or terminal failure if `err` is set). `processed` means "leader saw it" but not yet voted on
+by the cluster — we keep polling.
+
+`getTransaction(sig, { commitment: 'confirmed', maxSupportedTransactionVersion: 0 })` returns
+the full receipt: slot, meta.fee (in lamports), meta.preBalances / postBalances (per account
+SOL deltas) and meta.preTokenBalances / postTokenBalances (per ATA token deltas). The SDK
+decodes these into a `NestedBalanceChanges` — the same nested Map shape EVM emits —
+and returns a `SolanaTransactionStatus` (extends `TransactionStatus`) with `fees:
+SolanaTransactionFees` alongside. Wallet keys are the raw base58 (case-sensitive).
+
+Fallback path when `getTransaction` returns null:
+- `getSignatureStatus` yields no value at all → `NotFound`.
+- `getSignatureStatus` reports `finalized`/`confirmed` with `err` set →
+  `SolanaTransactionStatus.failed` with `fees: null` (settled-but-
+  unfetchable — fees can't be reconstructed from sig-status alone).
+- `getSignatureStatus` reports `processed` or is otherwise settled
+  without `err` → `Pending` so consumers keep polling rather than
+  treating a settled deposit as NotFound.
+- If `getTransaction` returns a body but `tx.meta === null` → `Pending`
+  as well.
+
+Consumers should treat Solana `NotFound` as retryable, not terminal —
+signature-status can lag full-tx availability on a heavily load-
+balanced RPC.
+
+The `balanceChangesExcludingFees(nativeAsset)` helper strips Solana's fee_payer debit
+from the emitted changes for callers who want gross-of-fee movements. It validates that
+`nativeAsset` matches this chain's native token (`chainId` match + empty `identifier`)
+and throws `ChainError(InvalidArgument)` otherwise.
+
+## Wallet derivation (BIP44 ed25519)
+
+Depositron derives Solana keypairs via SLIP-0010 `m/44'/501'/{account}'/0'`. `501` is the
+SLIP-44 coin type for SOL. **Unlike EVM, Solana uses ed25519, not secp256k1**, so we use the
+`ed25519-hd-key` package — `ethers.HDNodeWallet` won't work (it produces secp256k1 keys).
+
+```ts
+import { derivePath } from 'ed25519-hd-key';
+import { Keypair } from '@solana/web3.js';
+import * as bip39 from 'bip39';
+
+const seed = await bip39.mnemonicToSeed(mnemonic);
+const { key } = derivePath(`m/44'/501'/${index}'/0'`, seed.toString('hex'));
+const kp = Keypair.fromSeed(key); // 32-byte ed25519 seed → keypair
+const address = kp.publicKey.toBase58();
+```
+
+Phantom and Solflare default to `m/44'/501'/0'/0'` for "account 0", incrementing the third
+component for "account 1", "account 2", etc. (NOT the address_index slot — Solana wallets
+typically expose ACCOUNT index, not address index).
+
+## Common attacks / footguns
+
+- **Wrong token program**: SPL Token vs Token-2022 — using the wrong program ID for a mint
+  causes `IncorrectProgramId`. Always read the mint account's `owner` to decide.
+- **ATA already exists but wrong type**: a recipient may have a Token account that ISN'T the
+  associated one (legacy or another wallet's). `transferChecked` to a non-ATA still works as
+  long as it's owned by the recipient and the correct mint, but depositron always uses ATAs.
+- **Dust attacks via SPL Token-2022 hooks**: Token-2022 supports "transfer hooks" — programs
+  that run on every transfer of that mint. A malicious mint can do near-arbitrary work in the
+  hook. We don't inspect mints for hooks; treat each mint as an opaque external program.
+- **Rent**: every account on Solana pays ~0.00089 SOL per 128 bytes per epoch unless it has
+  enough lamports to be "rent-exempt". ATAs are 165 bytes → ~2039 lamports rent-exempt
+  deposit. When you create an ATA, the payer pays this deposit; it's recoverable by closing
+  the ATA later.
+- **No revert reason strings**: Solana program errors are codes (`u32`), not strings. Programs
+  document them; depositron passes `code: 'REVERTED'` for failed status.

package/docs/utxo.md

@@ -0,0 +1,364 @@
+# UTXO chains (Bitcoin / Litecoin / Dogecoin)
+
+`UtxoChain` is the generic base for any Bitcoin-derived UTXO network. It
+handles the whole transfer pipeline — UTXO fetch, branch-and-bound coin
+selection, PSBT construction with `nonWitnessUtxo` on every input,
+RBF sequencing, OP_RETURN memos.
+
+`BtcChain extends UtxoChain` adds Bitcoin-only concerns (inscription /
+rune / rare-sat filtering).
+
+## Files
+
+### Generic UTXO layer
+
+- [utxo_chain.ts](../utxo/utxo_chain.ts) — `UtxoChain extends Chain`
+- [utxo_network_params.ts](../utxo/utxo_network_params.ts) — `UtxoNetworkParams`, SLIP-44 coin ids, derivation purposes, dust default, RBF sequence
+- [unsigned_utxo_transaction.ts](../utxo/unsigned_utxo_transaction.ts) — `UnsignedUtxoTransaction { psbtBase64, selectedInputs, feeSats, inputsToSign, … }`
+- [utxo.ts](../utxo/utxo.ts) — `UnspentTransactionOutput`, `RawTransactionView`, `FeeEstimate`, `AddressBalance`
+- [script.ts](../utxo/script.ts) — `detectScriptType`, `buildOpReturnScript`, `scriptTypeForAddress`
+- [fee.ts](../utxo/fee.ts) — per-script-type vByte tables, fee math
+- [coin_selection.ts](../utxo/coin_selection.ts) — branch-and-bound + accumulator fallback over effective-value
+- [ecc.ts](../utxo/ecc.ts) — one-time `initEccLib(tinySecp256k1)` for Taproot
+- [tools/](../utxo/tools) — 5 role interfaces (see below)
+- [utxo_chains.ts](../utxo/utxo_chains.ts) — `utxoChainFromCoin` / `utxoChainFromSlip44` dispatchers
+
+### Per-coin implementations
+
+- [btc/](../utxo/btc) — Bitcoin (mainnet/testnet/signet/regtest) + asset indexes
+- [ltc/](../utxo/ltc) — Litecoin (mainnet/testnet) via `coininfo`
+- [doge/](../utxo/doge) — Dogecoin (mainnet/testnet) via `coininfo`
+
+## Role-provider interfaces
+
+`UtxoChain` doesn't talk to any one provider — it depends on five small
+interfaces. A single concrete tool (like `BitcoinCoreTool`) can implement
+all five, or you can wire different providers per role:
+
+| Interface | Method | Default impls |
+|---|---|---|
+| [`UtxoProvider`](../utxo/tools/utxo_provider.ts) | `getUtxos`, `getAddressBalance` | `BitcoinCoreTool`, `EsploraTool` |
+| [`UtxoRawTransactionProvider`](../utxo/tools/raw_transaction_provider.ts) | `getRawTransactionHex`, `getRawTransactionHexBatch`, `getTransaction` | `BitcoinCoreTool`, `EsploraTool` |
+| [`UtxoFeeEstimator`](../utxo/tools/fee_estimator.ts) | `getFeeEstimate(targetBlocks)` | `BitcoinCoreTool` (estimatesmartfee), `EsploraTool` (Esplora `/fee-estimates`) |
+| [`UtxoBroadcaster`](../utxo/tools/broadcaster.ts) | `broadcast(rawHex)` | `BitcoinCoreTool` (sendrawtransaction), `EsploraTool` (POST `/tx`) |
+| [`UtxoChainTipProvider`](../utxo/tools/chain_tip_provider.ts) | `getChainTipHeight()` | `BitcoinCoreTool` (getblockcount), `EsploraTool` (`/blocks/tip/height`) |
+
+Mix-and-match example:
+
+```ts
+const core = new BitcoinCoreTool({ /* … */ });
+const esplora = new EsploraTool({
+  baseUrl: 'https://mempool.space/api',
+  params: BITCOIN_MAINNET_PARAMS,
+});
+
+const chain = bitcoinMainnetChain({
+  chainId: -1n,
+  utxoProvider: esplora,   // Esplora handles arbitrary addresses without import
+  rawTxProvider: core,     // Core's batch RPC fetches multiple parent txs in one round-trip
+  feeEstimator: esplora,   // mempool.space has good fee estimates
+  broadcaster: core,       // broadcast locally
+  chainTipProvider: esplora,
+});
+```
+
+## Constructing a Bitcoin chain
+
+```ts
+import {
+  bitcoinMainnetChain,
+  bitcoinTestnetChain,
+  bitcoinSignetChain,
+  bitcoinRegtestChain,
+  BitcoinCoreTool,
+  EsploraTool,
+  BITCOIN_MAINNET_PARAMS,
+} from 'src/modules/chain';
+
+const core = new BitcoinCoreTool({
+  baseUrl: 'http://localhost:8332',
+  user: 'rpcuser',
+  password: 'rpcpassword',
+  params: BITCOIN_MAINNET_PARAMS,
+  wallet: 'hot',              // RPC routes to `/wallet/hot/`
+  importTimestamp: 'now',     // descriptor import without rescan (default)
+  watchOnlyLabel: 'pluton',   // label applied to imported descriptors
+});
+
+const btc = bitcoinMainnetChain({
+  chainId: -1n,
+  utxoProvider: core,
+  rawTxProvider: core,
+  feeEstimator: core,
+  broadcaster: core,
+  chainTipProvider: core,
+});
+```
+
+The chain registers itself with `NetworkType.BTC` in the global network-type
+registry when constructed, so `addressFor(-1, 'bc1q…')` will return a
+`BtcAddress` afterwards.
+
+### Litecoin
+
+```ts
+import { litecoinMainnetChain, litecoinTestnetChain } from 'src/modules/chain';
+
+const ltc = litecoinMainnetChain({
+  chainId: -10n,
+  utxoProvider: ltcCore,
+  rawTxProvider: ltcCore,
+  feeEstimator: ltcCore,
+  broadcaster: ltcCore,
+  chainTipProvider: ltcCore,
+});
+```
+
+LTC supports BIP-44/49/84 (no Taproot). Network params come from
+`coininfo.litecoin.main.toBitcoinJS()`.
+
+### Dogecoin
+
+```ts
+import { dogecoinMainnetChain } from 'src/modules/chain';
+
+const doge = dogecoinMainnetChain({
+  chainId: -20n,
+  // … same 5 role providers …
+});
+```
+
+DOGE supports only BIP-44 (no segwit). Dust is `1_000_000` sats — DOGE's
+network floor, much higher than BTC's 546.
+
+### Generic dispatcher
+
+If you'd rather not import the per-coin factory:
+
+```ts
+import { utxoChainFromCoin } from 'src/modules/chain';
+
+const chain = utxoChainFromCoin({
+  coin: 'bitcoin',            // 'bitcoin-testnet' | 'bitcoin-signet' | 'bitcoin-regtest'
+                              // 'litecoin' | 'litecoin-testnet'
+                              // 'dogecoin' | 'dogecoin-testnet'
+  chainId: -1n,
+  utxoProvider, rawTxProvider, feeEstimator, broadcaster, chainTipProvider,
+});
+```
+
+`utxoChainFromSlip44(coinId, isMainnet, opts)` exists too if you've got
+SLIP-44 coin IDs to dispatch on.
+
+## Building a transfer
+
+The `Chain` API works the same as EVM, with the BTC subclass accepting
+extra options (`feeRateSatsPerVByte`, `excludeInscriptions`, etc.):
+
+```ts
+const unsigned = await btc.createTransferUnsignedTransaction({
+  from: senderAddr,
+  to: recipientAddr,
+  tokenIdentifier: 'NATIVE',           // BTC has no non-native tokens
+  amount: 50_000_000n,                  // 0.5 BTC in sats
+  feeRateSatsPerVByte: 10,              // override; otherwise asks feeEstimator
+  rbfEnabled: true,                     // default true → sequence = 0xFFFFFFFD
+  memo: 'invoice-#123',                 // optional, emits an OP_RETURN output
+  excludeInscriptions: true,            // optional, requires inscriptionIndex configured
+});
+
+// unsigned is an UnsignedUtxoTransaction:
+unsigned.psbtBase64                    // base64-encoded PSBT (BIP-174)
+unsigned.selectedInputs                // UTXOs picked by coin selection
+unsigned.feeSats                       // computed fee
+unsigned.feeRateSatsPerVByte           // rate used
+unsigned.estimatedVBytes
+unsigned.totalInputSats
+unsigned.totalOutputSats
+unsigned.changeAddress                 // null if change was absorbed into the fee
+unsigned.inputsToSign                  // Record<address, inputIndex[]> for non-HD signers
+```
+
+The PSBT carries `witnessUtxo` *and* `nonWitnessUtxo` on every input —
+this is intentional. Legacy inputs need `nonWitnessUtxo` for correctness;
+SegWit/Taproot inputs technically don't, but hardware wallets like Trezor
+and Phantom demand it. Populating both is the safe default.
+
+## Signing
+
+The chain module never holds keys. You hand the PSBT to whatever signs
+it — a user's wallet, a hardware device, an external service. For
+testing or for protocol-controlled wallets that talk to Bitcoin Core:
+
+```ts
+// Sign via Bitcoin Core's wallet (it has the keys for sender's address):
+const processed = await rpc('walletprocesspsbt', [unsigned.psbtBase64]);
+// processed.complete === true if Core signed every input
+
+// Finalize → raw transaction hex:
+const finalized = await rpc('finalizepsbt', [processed.psbt]);
+// finalized.complete === true if all inputs are now scriptSig/witness-ready
+// finalized.hex is broadcast-ready
+```
+
+## Broadcasting
+
+```ts
+const result = await btc.broadcaster.broadcast(finalized.hex);
+// result.txid: '<64-hex>'
+```
+
+## Address validation
+
+```ts
+btc.validateWalletAddress('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4'); // true
+btc.validateWalletAddress('tb1q…');                                       // false on mainnet
+btc.validateTokenIdentifier('NATIVE');                                    // true
+```
+
+All five address types are supported per chain: P2PKH (`1…`), P2SH
+(`3…`), P2WPKH (`bc1q…` 42-char bech32), P2WSH (`bc1q…` 62-char bech32),
+P2TR (`bc1p…` bech32m).
+
+## Asset filtering (Bitcoin only)
+
+To avoid accidentally spending UTXOs that carry inscriptions, runes, or
+rare sats, wire one or more asset indexes into the chain:
+
+```ts
+import { OrdiscanIndex, UnisatIndex } from 'src/modules/chain';
+
+const ordiscan = new OrdiscanIndex({ apiKey: process.env.ORDISCAN_API_KEY! });
+const unisat   = new UnisatIndex({ apiKey: process.env.UNISAT_API_KEY! });
+
+const btc = bitcoinMainnetChain({
+  chainId: -1n,
+  utxoProvider: core, rawTxProvider: core, feeEstimator: core,
+  broadcaster: core, chainTipProvider: core,
+  inscriptionIndex: unisat,    // UniSat is inscription-only
+  runeIndex: ordiscan,         // Ordiscan covers runes
+  rareSatIndex: ordiscan,      // Ordiscan covers rare sats
+});
+```
+
+Then, per call, the caller opts into the filter:
+
+```ts
+const unsigned = await btc.createTransferUnsignedTransaction({
+  from: senderAddr,
+  to: recipientAddr,
+  tokenIdentifier: 'NATIVE',
+  amount: 50_000_000n,
+  excludeInscriptions: true,
+  excludeRunes: true,
+  excludeRareSats: true,
+});
+```
+
+Each `excludeXxx: true` is validated against the configured index **before**
+any HTTP call — explicit request without the corresponding index throws
+fail-fast with a clear message:
+
+```
+BtcChain ...: excludeRunes requested but no runeIndex was configured
+```
+
+If all three flags are off / omitted (default), the chain doesn't consult
+any index. If all three are on, the chain queries each index once per
+sender address (parallel) and unions the tainted outpoint set before
+coin selection sees the UTXOs.
+
+### Picking an asset-index provider
+
+- **`OrdiscanIndex`** ([ordiscan.tool.ts](../utxo/btc/tools/ordiscan.tool.ts)) — implements all three asset interfaces. Three separate endpoints per address, fanned out in parallel.
+- **`UnisatIndex`** ([unisat.tool.ts](../utxo/btc/tools/unisat.tool.ts)) — implements only `BtcInscriptionIndex`. Paginated.
+- Both require an API key.
+- For mainnet, prefer Ordiscan if you need rune/rare-sat coverage; for inscription-only filtering, UniSat is cheaper.
+
+You can split per-concern: inscriptions from UniSat (cheaper), runes from
+Ordiscan, etc. The interface system enforces that you can't accidentally
+plug UniSat into a rune slot — `UnisatIndex` doesn't implement `BtcRuneIndex`.
+
+## Coin selection
+
+Branch-and-bound first (exact-match within `cost_of_change`, no change
+output emitted) → accumulator (largest-first) fallback. Effective value
+math: each UTXO's worth is `valueSats − inputVBytes * feeRate`, so the
+selector doesn't pick UTXOs that cost more to spend than they're worth.
+
+If change after fee would be under dust (546 sats by default), the
+selector absorbs the surplus into the fee instead of emitting a sub-dust
+change output that the network would reject.
+
+Missing vs Bitcoin Core's full algorithm: knapsack fallback,
+`OutputGroup` privacy (treating multi-UTXO same-address as one atomic
+spend). See the [bitcoin-coin-selection][bcs] Python port for what a
+faithful re-implementation looks like.
+
+[bcs]: https://github.com/jamesob/bitcoin-coin-selection
+
+## Bitcoin Core wallet integration
+
+`BitcoinCoreTool` uses `listunspent` against a loaded wallet (faster than
+`scantxoutset`, but the wallet has to "know" each address):
+
+- On first `getUtxos(address)`, calls `getaddressinfo` to check if Core
+  already knows the address (`ismine` / `iswatchonly`).
+- If not, runs `importdescriptors` with `timestamp: 'now'` (no rescan;
+  configurable via `importTimestamp`) and the `watchOnlyLabel` label.
+- Caches the watched-address set in-process so subsequent calls skip
+  the check.
+
+For `getrawtransaction` fetches (parent-tx hydration during PSBT
+construction), the tool sends a **single array-body POST** with all
+txids, taking advantage of Bitcoin Core's JSON-RPC batch protocol. One
+round-trip regardless of how many parents the tx has.
+
+## Esplora integration
+
+`EsploraTool` works against Blockstream's Esplora API or any compatible
+implementation (mempool.space is a fork). No wallet, no rescan, no
+import — anyone-can-query against arbitrary addresses. Trade-off:
+public Esplora caps `/address/{addr}/utxo` at 500 UTXOs.
+
+## Testing
+
+| Spec | Verifies |
+|---|---|
+| `btc_address.spec.ts` | Address validation across all 5 types × 4 networks |
+| `script.spec.ts` | Script-type detection + OP_RETURN builder |
+| `fee.spec.ts` | Per-script vByte tables, effective-value math |
+| `coin_selection.spec.ts` | BnB + accumulator + change-absorbed-into-fee + multi-UTXO |
+| `btc_chain.spec.ts` | Full PSBT round-trip with `FakeBtcTool` (in-memory provider) |
+| `ordinal_filter.spec.ts` | Asset filter on/off + explicit-error semantics |
+| `bitcoin_core_batch.spec.ts` | JSON-RPC array-body batching shape |
+| `bitcoin_core_listunspent.spec.ts` | listunspent + auto-import flow |
+| `unisat.spec.ts` | UniSat pagination + error handling |
+| `test/integration/btc_regtest.e2e-spec.ts` | **Real Bitcoin Core regtest** — builds → signs → broadcasts a PSBT round-trip, including an OP_RETURN memo case and an insufficient-funds case |
+
+### Running the regtest e2e
+
+```bash
+npm test -- test/integration/btc_regtest.e2e-spec.ts \
+  --config ./test/jest-e2e.json --runInBand
+```
+
+Spins up `ruimarinho/bitcoin-core:24-alpine` via testcontainers (no host
+config needed beyond Docker being installed). First run pulls the image
+(~50 MB); subsequent runs are ~38 s total.
+
+## Adding another UTXO chain (e.g. Bitcoin Cash)
+
+1. Add the coin to SLIP-44 mapping in [utxo_network_params.ts](../utxo/utxo_network_params.ts).
+2. Create `chain/utxo/bch/`:
+   - `network_params.ts` — pull `coininfo.bitcoincash.main.toBitcoinJS()`,
+     set `supportedDerivationPurposes` (BCH typically only BIP-44),
+     define wallet-address regex.
+   - `bch_chains.ts` — factory functions taking `chainId` + role
+     providers, calling `new UtxoChain({ params: BCH_MAINNET_PARAMS, … })`.
+3. Add `export * from './bch';` to [utxo/index.ts](../utxo/index.ts).
+4. Extend the [utxoChainFromCoin](../utxo/utxo_chains.ts) dispatcher.
+
+For chains where you need extra concerns (BCH doesn't have inscriptions
+but has e.g. SLP tokens), follow the BTC pattern — extend `UtxoChain`
+with a chain-specific subclass that adds the extra abstractions.

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@getomnichain/omnichain",
+  "version": "0.2.0",
+  "description": "Multi-chain SDK for EVM, Solana, UTXO (BTC/LTC/DOGE/DASH/ZEC/BCH), TON, and Tron. TypeScript parity port of omnichain-py.",
+  "keywords": [
+    "omnichain",
+    "blockchain",
+    "evm",
+    "ethereum",
+    "solana",
+    "bitcoin",
+    "utxo",
+    "ton",
+    "tron",
+    "sdk",
+    "multichain",
+    "web3"
+  ],
+  "homepage": "https://github.com/getomnichain/omnichain#readme",
+  "bugs": "https://github.com/getomnichain/omnichain/issues",
+  "license": "MIT",
+  "author": "getomnichain",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getomnichain/omnichain.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./evm": {
+      "types": "./dist/evm/index.d.ts",
+      "default": "./dist/evm/index.js"
+    },
+    "./solana": {
+      "types": "./dist/solana/index.d.ts",
+      "default": "./dist/solana/index.js"
+    },
+    "./utxo": {
+      "types": "./dist/utxo/index.d.ts",
+      "default": "./dist/utxo/index.js"
+    },
+    "./ton": {
+      "types": "./dist/ton/index.d.ts",
+      "default": "./dist/ton/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js",
+    "release": "bash scripts/release.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.98.0",
+    "axios": "^1.7.0",
+    "bitcoinjs-lib": "^7.0.1",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "coininfo": "^5.2.1",
+    "decimal.js": "^10.4.3",
+    "ethers": "^6.13.0",
+    "js-sha3": "^0.9.3",
+    "tiny-secp256k1": "^2.2.3"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.13.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}