@getomnichain/omnichain 0.2.1 → 0.3.1

package/docs/CONNECTIONS.md

@@ -0,0 +1,33 @@
+# Chain connection surface (0.3.0)
+
+Every wire-level operation a consumer needs is on `Chain` or its typed subclasses — no `ethers` / `@solana/web3.js` / `@solana/spl-token` import required in consumer code.
+
+## Escape-hatch → SDK expression
+
+| Old pattern | 0.3.0 SDK expression |
+|---|---|
+| `chain.getProvider().broadcastTransaction(hex)` | `chain.broadcast(hex)` |
+| `chain.getProvider().getTransactionCount(addr, 'pending')` | `chain.getPendingNonce(addr)` |
+| `chain.getProvider().getCode(addr)` + custom `0xef0100` parse | `chain.getDelegation(addr)` |
+| `chain.getProvider().call(tx)` | `chain.call({ to, data, ... })` |
+| `chain.getProvider().estimateGas(tx)` | `chain.call({ to, data, ..., estimateGas: true })` |
+| `chain.getConnection().sendRawTransaction(bytes, opts)` | `chain.broadcast(bytes, opts)` |
+| `chain.getConnection().getAccountInfo(pk)` | `chain.getAccountInfo(pk)` |
+| `chain.getConnection().getMultipleAccountsInfo(pks)` | `chain.getAccountInfo(pks)` (batch overload) |
+| `getAssociatedTokenAddressSync(mint, owner)` + `getAccount(...)` | `chain.getTokenAccount(owner, mint)` |
+| `chain.getConnection().getAddressLookupTable(alt)` | `chain.fetchAddressLookupTable(alt)` |
+| Compile `MessageV0` + build tx from raw instructions | `chain.createUnsignedTransaction({ payer, instructions, addressLookupTables? })` |
+| Build type-4 tx by hand with ethers RLP | `chain.createUnsignedTransaction({ from, to, data, authorizationList })` |
+| Compute EIP-7702 digest by hand | `chain.buildAuthorizationDigest({ delegate, nonce, chainId })` |
+| Custom Jito HTTP client | `chain.submitJitoBundle(bytes[])` + `chain.getBundleStatus(bundleId)` |
+| Consumer-side receipt-poll loop | `chain.getTransactionStatus(hash, { wait: true, timeoutMs })` |
+| Multiple `getTransactionStatus` calls | `chain.getTransactionStatus([hash1, hash2, ...])` batch |
+
+## Feature-gated surfaces
+
+- **EIP-7702**: requires `EvmChain` constructor with `supports7702: true`. Methods on non-flagged chains throw `ChainError(FeatureNotSupported)`.
+- **Jito**: requires `SolanaChain` constructor with `jito: { url, auth? }`. `broadcast({ via: 'jito' })`, `submitJitoBundle`, `getBundleStatus` all throw `FeatureNotSupported` when `chain.jito === null`.
+
+## Error taxonomy
+
+New `ChainErrorKinds` values: `BroadcastRejected`, `NonceTooLow`, `InsufficientFunds`, `BlockhashExpired`, `SimulationFailed`, `TransactionTooLarge`, `FeatureNotSupported`. Discriminator helpers: `isBlockhashExpiredError`, `isSimulationError`, `isNonceError`, `isTransactionTooLargeError`.

package/docs/EIP7702.md

@@ -0,0 +1,77 @@
+# EIP-7702 (type-4) transactions
+
+Opt-in per chain: pass `supports7702: true` to the `EvmChain` constructor. Methods below throw `ChainError(FeatureNotSupported)` on unflagged chains.
+
+## Flow
+
+```ts
+import { EvmChain } from '@getomnichain/omnichain';
+
+const chain = new EvmChain({
+  chainId: 1,
+  name: 'Mainnet',
+  blockTimeSeconds: 12,
+  nativeSymbol: 'ETH',
+  explorerBaseUrl: 'https://etherscan.io',
+  rpcUrl: process.env.MAINNET_RPC_URL,
+  supports7702: true,
+});
+
+// 1. Read current delegate (nullable)
+const current = await chain.getDelegation(userAddress);
+// current === null | { delegate: '0x...' }
+
+// 2. Compute the authorization digest for the wallet to sign.
+//
+// SELF-DELEGATION SUBTLETY: when the tx sender IS the authority (as in this
+// example, from == userAddress AND the authorization is for userAddress),
+// the authorization nonce must be `pendingNonce + 1n` — the sender's nonce
+// is incremented BEFORE the authorization list is processed. Using
+// pendingNonce here would silently fail on-chain: the tx lands, gas is
+// spent, no delegation is installed, and getDelegation returns null with
+// no error surfaced.
+//
+// For third-party-sponsored 7702 (relayer sends, authority is a different
+// account), use the authority's pendingNonce as-is.
+const pendingNonce = await chain.getPendingNonce(userAddress);
+const authNonce = pendingNonce + 1n;
+const digest = chain.buildAuthorizationDigest({
+  delegate: newDelegateAddress,
+  nonce: authNonce,
+  chainId: 1,
+});
+
+// 3. Wallet signs the digest externally
+const signature = await wallet.signRaw(digest);  // returns { r, s, yParity }
+
+// 4. Build the type-4 tx via the general primitive
+const unsigned = await chain.createUnsignedTransaction({
+  from: userAddress,
+  to: userAddress,                       // 7702 self-call to establish delegation
+  data: '0x',
+  authorizationList: [{
+    chainId: 1,
+    address: newDelegateAddress,   // ethers TransactionLike shape
+    nonce: authNonce,
+    signature,
+  }],
+});
+
+// 5. Sign + broadcast
+const signedHex = await wallet.signTransaction(unsigned);
+const txHash = await chain.broadcast(signedHex);
+
+// 6. Wait for inclusion
+const status = await chain.getTransactionStatus(txHash, { wait: true, timeoutMs: 30_000 });
+```
+
+## Guards
+
+- `authorizationList` must be non-empty when provided (`InvalidArgument`).
+- Every `authorizationList[i].chainId` must match `chain.chainId`. Cross-chain replay guard. **EIP-7702 permits `chainId = 0` as a "any chain" wildcard, but the SDK rejects it** — a chainId=0 authorization is replayable on every EVM chain forever, which is the exact hazard the guard exists to prevent.
+- `supports7702 === false` → `FeatureNotSupported` before any wire call.
+- `getDelegation` parses ONLY `0xef0100<20-byte-delegate>` (exact 24-byte code). Any other shape returns `null`.
+
+## Digest formula
+
+`keccak256(0x05 || rlp([chainId, delegate, nonce]))` per the EIP.

package/docs/JITO.md

@@ -0,0 +1,41 @@
+# Solana Jito bundles
+
+Opt-in per chain: pass `jito: { url, auth? }` to the `SolanaChain` constructor. Methods below throw `ChainError(FeatureNotSupported)` when `chain.jito === null`.
+
+## Single-tx via broadcast
+
+```ts
+import { SolanaChain } from '@getomnichain/omnichain';
+
+const chain = new SolanaChain({
+  ...init,
+  jito: { url: 'https://mainnet.block-engine.jito.wtf/api/v1/bundles' },
+});
+
+// Broadcast a single signed tx as a 1-tx Jito bundle.
+// Returns the base58-encoded transaction signature (NOT the bundle id).
+const sig = await chain.broadcast(signedBytes, { via: 'jito' });
+const status = await chain.getTransactionStatus(sig, { wait: true });
+```
+
+`broadcast({ via: 'jito' })` submits the transaction as a 1-tx bundle and returns the tx **signature** (the base58 of the first 64 bytes of the serialized transaction). The signature is the same value `chain.getTransactionStatus` accepts — the two APIs are consistent. The corresponding bundle id is a wire-level detail owned by the SDK and not surfaced through this path.
+
+## Multi-tx bundle
+
+For a real multi-tx bundle the bundle id is meaningful. Use `submitJitoBundle` explicitly:
+
+```ts
+const bundleId = await chain.submitJitoBundle([signedTx1, signedTx2, signedTx3]);
+const status = await chain.getBundleStatus(bundleId);
+// { bundleId, state: 'Pending' | 'Landed' | 'Failed', slot?, err? }
+```
+
+`getBundleStatus` accepts a single id OR an array (batch polling):
+
+```ts
+const [a, b, c] = await chain.getBundleStatus(['id1', 'id2', 'id3']);
+```
+
+## Bundle composition + tip strategy
+
+Consumer-owned. The SDK exposes wire-level submit + status only. Tip instructions (e.g. `SystemProgram.transfer` to a Jito tip account) must be composed into the transactions before signing.

package/docs/MULTI_RPC.md

@@ -0,0 +1,28 @@
+# Multi-endpoint RPC config
+
+Both `EvmChain` and `SolanaChain` constructors accept an optional `rpcUrls?: string[]` field alongside `rpcUrl?: string`.
+
+## 0.3.0 status — single-entry only
+
+**`rpcUrls` accepts at most ONE entry in 0.3.0.** Passing a longer list throws `ChainError(InvalidArgument)` at construction time. The field ships as a stable API surface; automatic failover-retry lands in a follow-up release. Consumers pinning `rpcUrls: [primary]` today will benefit as soon as retry-on-transport-error ships.
+
+```ts
+new EvmChain({ ..., rpcUrls: [process.env.ARBITRUM_PRIMARY_RPC_URL!] });   // OK
+new EvmChain({ ..., rpcUrls: [primary, backup] });                          // throws — deferred
+```
+
+## Precedence
+
+`rpcUrl` (single) → `rpcUrls[0]` → env-var chain → `defaultRpcUrl` (Solana only).
+
+When `rpcUrls` is non-empty but every entry is blank, resolution throws `ChainError(RpcNotConfigured)`. **The SDK never silently falls back to a URL that isn't in the configured list or env fallback chain.**
+
+## URL redactor
+
+All error messages / thrown `ChainError.message` / logs pass through a redactor that strips:
+- Query params ending in `key`, `token`, `secret` (`apiKey`, `api-key`, `api_key`, `key`, `access-token`, `secret`)
+- `Authorization: Bearer <token>` (case-insensitive)
+- Path-embedded keys under `/vN/` or `/api/` (≥16 alphanumeric or `_/-`)
+- Full-URL match on known providers — Alchemy, Infura, QuickNode, Helius, Ankr, Blast, dRPC — collapses to `<scheme>://<host>/<redacted>`
+
+Keyed URLs never appear in logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getomnichain/omnichain",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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",