@getomnichain/omnichain 0.3.6 → 0.5.1

package/CHANGELOG.md

@@ -8,7 +8,77 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-_Nothing yet. Add entries here as PRs merge; on release, rename this section to `[X.Y.Z] — YYYY-MM-DD` and open a fresh empty `[Unreleased]` above it._
+## [0.5.1] — 2026-09-22
+
+Surfaces Solana finality on `SolanaTransactionStatus` (RIN-296, SDK half of RIN-285). Non-blocking pollers can now read one status snapshot and see how close to finality a tx is, matching the pattern EVM (`blockNumber` + tip derivation) and UTXO (RIN-195's carried `confirmations`) already use.
+
+### Added
+
+- **`SolanaTransactionStatus.slot: number | null`** — from `getTransaction`'s `slot` on the success path; from `getSignatureStatus`'s `slot` on the ledger-pruned fallback.
+- **`SolanaTransactionStatus.confirmations: number | null`** — the raw RPC count for non-final states, normalised to the exported `SOLANA_FINALIZED_CONFIRMATIONS = 32` when the RPC returns `null` (rooted, per the Solana RPC contract). `null` when the sig-status read was unavailable.
+- **`SolanaTransactionStatus.confirmationStatus: 'processed' | 'confirmed' | 'finalized' | null`** — the raw RPC string.
+- **`SolanaTransactionStatus.signers: readonly string[]`** — base58 signer keys in message order (the first `header.numRequiredSignatures` `staticAccountKeys`). Mirrors omnichain-py `signer_keys = account_keys[: header.num_required_signatures]` at `impl/solana/base.py:1175`. Empty on the ledger-pruned fallback and on `notFound`.
+- **`SOLANA_FINALIZED_CONFIRMATIONS = 32`** — exported constant.
+- **`SolanaConfirmationStatus`** — union of the three RPC states.
+
+### Changed
+
+- **`SolanaChain.getTransactionStatus`** fires `getTransaction` and `getSignatureStatus` in parallel via `Promise.allSettled` (RIN-296 D1) — the common Success case pays one round-trip of latency instead of two. Sig-status failure on the Success path degrades the four new fields to `null`/`[]` rather than failing the whole read (D2). The ledger-pruned Pending branch carries whatever finality it has (D3).
+
+### Note
+
+- No `blockNumber` field. Solana slots are not block heights (skipped slots exist) and `getChainTipHeight` returns a block height (0.3.3 fix); consumers deriving finality from `blockNumber` on other families must gate Solana on `confirmations`.
+- **Additive only.** All new fields optional in the init with safe defaults (`null` / `[]`); every pre-0.5.1 `SolanaTransactionStatus.successful/failed/pending/notFound` call site compiles unchanged.
+- **Note on version bump.** RIN-285 R4 specifies a **minor** bump. This release ships as a **patch** (0.5.0 → 0.5.1) per requester decision. Under SemVer this is a documented divergence — the change is additive to the public surface (new optional fields, new exported constant/type) and a minor bump would be more strictly correct.
+
+---
+
+## [0.5.0] — 2026-09-21
+
+Adds a single canonical bidirectional map between omnichain chain ids and Rango's uppercase `blockchains[].name` identifiers. Removes the need for downstream consumers that talk to Rango to maintain their own partial copies of the mapping.
+
+### Added
+
+- **`CHAIN_ID_TO_RANGO_NAME: ReadonlyMap<number, string>`** on `rango_chain_names.ts` — primary map for every omnichain chain that appears in Rango's `/meta`. Sourced from `GET https://public-api.rango.exchange/basic/meta`, snapshot dated 2026-09-21.
+- **`RANGO_NAME_TO_CHAIN_ID: ReadonlyMap<string, number>`** — the inverse map, keyed by uppercase name.
+- **`NOT_ON_RANGO: ReadonlySet<number>`** — explicit "not on Rango" decisions for testnets + mainnet chains omnichain declares but Rango's `/meta` does not carry (e.g. `MANTLE`, `OPBNB`, `SEI_EVM`, `WORLD_CHAIN`, `WANCHAIN`, `ABSTRACT`, `INK`, `BOB`, `ZKLINK_NOVA`, `TEMPO`). Each id must appear in the map or here; the coverage test fails otherwise, and `prepublishOnly` now runs the suite so an undecided chain id cannot ship.
+- **`rangoNameForChainId(chainId)`** and **`chainIdForRangoName(name)`** — accessors. The name-side normalises `trim() + toUpperCase()` and returns `undefined` for any non-string input, so callers looping over untrusted Rango feed rows can skip bad entries instead of aborting.
+- **Fixture** `test/fixtures/rango_meta_blockchains.json` — compact wrapper `{fetchedAt, source, blockchains: [{name, chainId, type}, …]}` of Rango's `/meta`, ~8 KB. The map's substance is verified against it: every mapped name exists, every positive-id row's parsed `chainId` (hex `0x…` or decimal) equals the omnichain id, every non-positive mapped id lives on the family predicate the fixture type implies (`SOLANA→isSolana`, `SUI→isSui`, `XRPL→isXrpl`, `STELLAR→isStellar`, `TON→isTon`, `TRANSFER→isUtxo`; TRON is positive and covered by the hex check), and no `NOT_ON_RANGO` id is actually present in the fixture. Refreshing the map becomes "replace fixture, rerun tests."
+- **Tests** in `test/rango_chain_names.spec.ts`: bijection, no-duplicate names, name-format invariant (`/^[A-Z0-9_]+$/`), critical anchors (BTC=-1, SOLANA=-2000, ETH, BSC, ARBITRUM, BASE, LINEA, AVAX_CCHAIN, LTC, DOGE, BCH, TRON), case/whitespace normalisation, unknown-and-non-string handling, disjoint map/`NOT_ON_RANGO`, exhaustive `chain_ids.ts` coverage, and the three fixture-backed feed checks.
+
+### Note
+
+- Aliases (alternate Rango spellings for the same chain) are out of scope. If a consumer hits one in the wild, opening a follow-up to add it is a separate decision.
+
+---
+
+## [0.4.0] — 2026-09-16
+
+Brings TS `UtxoTransactionStatus` in line with the Python SDK's already-shipped UTXO shape: per-input `{address, value}` surfaced, and `balanceChanges` becomes net per-address (matching EVM/Solana). Every hydration detail lives in the per-tool provider, mirroring Python's `AbstractUtxoTool.get_tx`.
+
+### Added
+
+- **`UtxoTransaction` interface** on `utxo/utxo.ts` — the intermediate type returned by the tool layer, mirroring Python's `class UtxoTransaction`: `{ inputs, outputs, netChangesHr: Record<string, Decimal>, size, vsize, confirmations, confirmationDatetime }`.
+- **`UtxoTransactionInput` type** — `{ txid, vout, scriptPubkeyHex, address, valueSats, valueBtcHr, coinbase? }`. Both `valueSats` (bigint, `@deprecated`) and `valueBtcHr` (Decimal) are populated this release; the deprecated `valueSats` is scheduled for removal in a future major, with `valueBtcHr` renamed → `value` at that point to align with Python. Mirrors the `AssetBalanceChange.balanceChangeMr`/`Hr` idiom.
+- **`UtxoRawTransactionProvider.getTransactionWithInputs(txid)`** — new provider method returning a fully-hydrated `UtxoTransaction`. Every adapter is responsible for hydration per its API, matching Python's per-tool approach.
+- **`EsploraTool.getTransactionWithInputs`** — parses inline `vin[*].prevout` from Esplora's `/tx/{txid}` response; zero extra RPCs.
+- **`BitcoinCoreTool.getTransactionWithInputs`** — hydrates via a hybrid path that works on every Core version: whichever verbosity the caller requests (`bitcoinCoreVerbose?: 1 | 2`, default `1`), the adapter uses any `vin[*].prevout` the response inlines and runs a batched `getrawtransaction verbose=1` walk for the vins that do not carry a prevout (older Core, mempool txs, pruned-block txs, Core < 25). Zero extra RPCs when block undo data is available; N extra otherwise. Matches Python's `impl/utxo/tools/bitcoin_core.py:453` cost profile on the fallback path. Setting `bitcoinCoreVerbose: 2` on Core ≥ 25 is the recommended production configuration for confirmed-heavy status polling.
+- **`UtxoTransactionStatus.inputs`** — `readonly UtxoTransactionInput[] | null`. Populated when the provider tool hydrated every non-coinbase input; `null` (with `inputsUnresolvedReason: 'pending'`) on `Pending` statuses whose provider skips hydration.
+- **`UtxoTransactionStatus.inputsUnresolvedReason`** — `'provider_error' | 'parent_missing' | 'pending' | null`.
+- **`UtxoInputsUnresolvedReason`** type on `utxo/utxo.ts`.
+- **8 new RIN-226 unit tests** covering: inputs order + dual units, net semantics on a mixed-owner tx, self-send fee-only debit, no legacy accessor, hydration failure → thrown `RpcError`, coinbase input shape, `Pending` + hydration unavailable, `valueSats`/`valueBtcHr` agreement.
+
+### Changed (breaking on the UTXO surface)
+
+- **`UtxoTransactionStatus.balanceChanges`** is now **net per-address** (from `UtxoTransaction.netChangesHr`) on `Success` statuses — inputs debited, outputs credited. Previously gross output credits per receiving address. Matches `EvmTransactionStatus`, `SolanaTransactionStatus`, Python's UTXO status, and Clydner's BlockCypher parser.
+- On confirmed + hydration failure, `UtxoChain.getTransactionStatus` **throws `ChainError(RpcError)`** rather than returning a `Success` with `null` balance changes (preserves the base `TransactionStatus(Success)` invariant that requires `balanceChanges` present).
+- Rewrote the `UtxoTransactionStatus` class docstring — the "gross output credits" caveat and the "`inputs` … comes back in the 2C UTXO port" TODO are removed.
+- No `outputCreditsByAddress()` accessor and no `grossOutputCreditsLegacy` field: deposit detectors that only need who-got-credited iterate `status.outputs[]` directly (Python has neither).
+
+### Note
+
+- Migration: consumers that summed positive UTXO credits from `balanceChanges` need to switch to iterating `status.outputs[]` per address. A hot-wallet withdrawal that previously read as a large positive credit (from the change output) now reads as a net debit for the fee — the correct sign.
+- Companion cards to file: rango-intents BTC-8 workaround deletion (drop `enrichInputTxFromChain` and the parent-tx resolver; consume `status.inputs` + iterate `status.outputs[]` for deposit detection) and Clydner BlockCypher-parser netting (drop the parser's own netting or document why it stays because it ingests BlockCypher payloads directly, not SDK statuses).
 
 ---
 
@@ -324,6 +394,15 @@ Initial npm release of `@getomnichain/omnichain`. Replaces prior vendored-submod
 
 ---
 
+[0.5.1]: https://github.com/getomnichain/omnichain/releases/tag/v0.5.1
+[0.5.0]: https://github.com/getomnichain/omnichain/releases/tag/v0.5.0
+[0.4.0]: https://github.com/getomnichain/omnichain/releases/tag/v0.4.0
+[0.3.6]: https://github.com/getomnichain/omnichain/releases/tag/v0.3.6
+[0.3.5]: https://github.com/getomnichain/omnichain/releases/tag/v0.3.5
+[0.3.4]: https://github.com/getomnichain/omnichain/releases/tag/v0.3.4
+[0.3.3]: https://github.com/getomnichain/omnichain/releases/tag/v0.3.3
+[0.3.2]: https://github.com/getomnichain/omnichain/releases/tag/v0.3.2
+[0.3.1]: https://github.com/getomnichain/omnichain/releases/tag/v0.3.1
 [0.3.0]: https://github.com/getomnichain/omnichain/releases/tag/v0.3.0
 [0.2.1]: https://github.com/getomnichain/omnichain/releases/tag/v0.2.1
 [0.2.0]: https://github.com/getomnichain/omnichain/releases/tag/v0.2.0

package/dist/cjs/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./errors.js"), exports);
 __exportStar(require("./is_address.decorator.js"), exports);
 __exportStar(require("./network_type.js"), exports);
 __exportStar(require("./priority.js"), exports);
+__exportStar(require("./rango_chain_names.js"), exports);
 __exportStar(require("./token.js"), exports);
 __exportStar(require("./transaction_status.js"), exports);
 __exportStar(require("./unsigned_transaction.js"), exports);

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,+CAA6B;AAC7B,uDAAqC;AACrC,+DAA6C;AAC7C,kDAAgC;AAChC,iDAA+B;AAC/B,8CAA4B;AAC5B,4DAA0C;AAC1C,oDAAkC;AAClC,gDAA8B;AAC9B,6CAA2B;AAC3B,0DAAwC;AACxC,4DAA0C;AAC1C,iDAA+B;AAC/B,oDAAkC;AAClC,iDAA+B;AAC/B,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,+CAA6B;AAC7B,uDAAqC;AACrC,+DAA6C;AAC7C,kDAAgC;AAChC,iDAA+B;AAC/B,8CAA4B;AAC5B,4DAA0C;AAC1C,oDAAkC;AAClC,gDAA8B;AAC9B,yDAAuC;AACvC,6CAA2B;AAC3B,0DAAwC;AACxC,4DAA0C;AAC1C,iDAA+B;AAC/B,oDAAkC;AAClC,iDAA+B;AAC/B,kDAAgC"}

package/dist/cjs/rango_chain_names.js

@@ -0,0 +1,209 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOT_ON_RANGO = exports.RANGO_NAME_TO_CHAIN_ID = exports.CHAIN_ID_TO_RANGO_NAME = void 0;
+exports.rangoNameForChainId = rangoNameForChainId;
+exports.chainIdForRangoName = chainIdForRangoName;
+const C = __importStar(require("./chain_ids.js"));
+const MAX_RANGO_NAME_LENGTH = 64;
+/**
+ * Bidirectional lookup between omnichain chain ids and Rango's canonical
+ * uppercase blockchain names (the `blockchains[].name` field of Rango's
+ * `/meta` response).
+ *
+ * TypeScript-only module — no `omnichain-py` counterpart. `chain_ids.ts`
+ * mirrors the Python catalogue, but the Rango-name mapping is a
+ * TS-consumer concern and does not exist on the Python side.
+ *
+ * Source of truth: `GET https://public-api.rango.exchange/basic/meta`.
+ * The snapshot backing this module lives at
+ * `test/fixtures/rango_meta_blockchains.json`; its `fetchedAt` field is
+ * the single source-of-date. Refresh via `npm run rango:refresh`.
+ *
+ * Downstream consumers that talk to Rango should import from here
+ * instead of maintaining a local copy. `test/rango_chain_names.spec.ts`
+ * fails the suite whenever `chain_ids.ts` gains a new id that is
+ * neither mapped here nor listed in `NOT_ON_RANGO`, so a new chain
+ * forces an explicit decision. That suite runs on every PR/push via
+ * `.github/workflows/test.yml` and on `npm publish` via
+ * `prepublishOnly`. When the `test` check is required on `main` via
+ * branch protection, consumers vendoring omnichain from `main` inherit
+ * that check as their guarantee; until then, the workflow signals but
+ * does not block.
+ *
+ * Aliases (alternate spellings Rango may use in other endpoints) are
+ * deliberately out of scope; if a consumer hits one, add it as a
+ * separate decision.
+ */
+exports.CHAIN_ID_TO_RANGO_NAME = new Map([
+    [C.CHAIN_ID_BITCOIN_MAINNET, 'BTC'],
+    [C.CHAIN_ID_LITECOIN_MAINNET, 'LTC'],
+    [C.CHAIN_ID_DOGECOIN_MAINNET, 'DOGE'],
+    [C.CHAIN_ID_DASH_MAINNET, 'DASH'],
+    [C.CHAIN_ID_ZCASH_MAINNET, 'ZCASH'],
+    [C.CHAIN_ID_BITCOIN_CASH_MAINNET, 'BCH'],
+    [C.CHAIN_ID_SOLANA_MAINNET, 'SOLANA'],
+    [C.CHAIN_ID_SUI_MAINNET, 'SUI'],
+    [C.CHAIN_ID_XRPL_MAINNET, 'XRPL'],
+    [C.CHAIN_ID_STELLAR_MAINNET, 'STELLAR'],
+    [C.CHAIN_ID_TON_MAINNET, 'TON'],
+    [C.CHAIN_ID_TRON_MAINNET, 'TRON'],
+    [C.CHAIN_ID_ETHEREUM, 'ETH'],
+    [C.CHAIN_ID_OPTIMISM, 'OPTIMISM'],
+    [C.CHAIN_ID_CRONOS, 'CRONOS'],
+    [C.CHAIN_ID_BNB_CHAIN, 'BSC'],
+    [C.CHAIN_ID_OKX_CHAIN, 'OKC'],
+    [C.CHAIN_ID_GNOSIS, 'GNOSIS'],
+    [C.CHAIN_ID_UNICHAIN, 'UNICHAIN'],
+    [C.CHAIN_ID_POLYGON, 'POLYGON'],
+    [C.CHAIN_ID_MONAD, 'MONAD'],
+    [C.CHAIN_ID_SONIC, 'SONIC'],
+    [C.CHAIN_ID_SHIMMER, 'SHIMMER'],
+    [C.CHAIN_ID_XLAYER, 'XLAYER'],
+    [C.CHAIN_ID_FANTOM, 'FANTOM'],
+    [C.CHAIN_ID_BOBA, 'BOBA'],
+    [C.CHAIN_ID_ZKSYNC, 'ZKSYNC'],
+    [C.CHAIN_ID_STABLE, 'STABLE'],
+    [C.CHAIN_ID_HYPER_EVM, 'HYPEREVM'],
+    [C.CHAIN_ID_METIS, 'METIS'],
+    [C.CHAIN_ID_POLYGON_ZKEVM, 'POLYGONZK'],
+    [C.CHAIN_ID_MOONBEAM, 'MOONBEAM'],
+    [C.CHAIN_ID_MOONRIVER, 'MOONRIVER'],
+    [C.CHAIN_ID_SONEIUM, 'SONEIUM'],
+    [C.CHAIN_ID_CITREA, 'CITREA'],
+    [C.CHAIN_ID_MEGA_ETH, 'MEGAETH'],
+    [C.CHAIN_ID_ZETACHAIN, 'ZETA_CHAIN'],
+    [C.CHAIN_ID_BASE, 'BASE'],
+    [C.CHAIN_ID_IOTA_EVM, 'IOTA'],
+    [C.CHAIN_ID_PLASMA, 'PLASMA'],
+    [C.CHAIN_ID_MODE, 'MODE'],
+    [C.CHAIN_ID_ARBITRUM, 'ARBITRUM'],
+    [C.CHAIN_ID_CELO, 'CELO'],
+    [C.CHAIN_ID_AVALANCHE_C_CHAIN, 'AVAX_CCHAIN'],
+    [C.CHAIN_ID_LINEA, 'LINEA'],
+    [C.CHAIN_ID_BERA_CHAIN, 'BERACHAIN'],
+    [C.CHAIN_ID_BLAST, 'BLAST'],
+    [C.CHAIN_ID_TAIKO, 'TAIKO'],
+    [C.CHAIN_ID_SCROLL, 'SCROLL'],
+    [C.CHAIN_ID_KATANA, 'KATANA'],
+    [C.CHAIN_ID_ZORA, 'ZORA'],
+    [C.CHAIN_ID_AURORA, 'AURORA'],
+]);
+/**
+ * Inverse of `CHAIN_ID_TO_RANGO_NAME`, keyed by uppercase name.
+ * Prefer `chainIdForRangoName` for case- and whitespace-tolerant lookup.
+ */
+exports.RANGO_NAME_TO_CHAIN_ID = new Map(Array.from(exports.CHAIN_ID_TO_RANGO_NAME, ([id, name]) => [name, id]));
+/**
+ * Explicit decisions for chain ids omnichain declares but Rango's `/meta`
+ * does not carry, verified against the same snapshot as
+ * `CHAIN_ID_TO_RANGO_NAME`.
+ *
+ * Every id in `chain_ids.ts` must appear in either `CHAIN_ID_TO_RANGO_NAME`
+ * or here; the coverage test fails the PR check and `npm publish` (via
+ * `prepublishOnly`) otherwise. Adding an id to `chain_ids.ts` without a
+ * decision is a bug.
+ *
+ * Grouped by reason:
+ *   - Testnets/devnets Rango's `/meta` intentionally omits.
+ *   - Mainnet EVM chains not on Rango's `/meta` as of the snapshot; add to
+ *     `CHAIN_ID_TO_RANGO_NAME` once Rango starts publishing them.
+ */
+exports.NOT_ON_RANGO = new Set([
+    // testnets/devnets — Rango's /meta never carries these.
+    C.CHAIN_ID_BITCOIN_TESTNET,
+    C.CHAIN_ID_BITCOIN_SIGNET,
+    C.CHAIN_ID_SOLANA_TESTNET,
+    C.CHAIN_ID_SOLANA_DEVNET,
+    C.CHAIN_ID_SUI_TESTNET,
+    C.CHAIN_ID_SUI_DEVNET,
+    C.CHAIN_ID_XRPL_TESTNET,
+    C.CHAIN_ID_STELLAR_TESTNET,
+    C.CHAIN_ID_TON_TESTNET,
+    C.CHAIN_ID_TRON_SHASTA,
+    C.CHAIN_ID_GOERLI,
+    C.CHAIN_ID_SEPOLIA,
+    C.CHAIN_ID_CELO_SEPOLIA,
+    // Mainnet, absent from /meta as of the fixture snapshot — move to the map when Rango publishes them.
+    C.CHAIN_ID_OPBNB,
+    C.CHAIN_ID_WORLD_CHAIN,
+    C.CHAIN_ID_WANCHAIN,
+    C.CHAIN_ID_SEI_EVM,
+    C.CHAIN_ID_ABSTRACT,
+    C.CHAIN_ID_TEMPO,
+    C.CHAIN_ID_MANTLE,
+    C.CHAIN_ID_INK,
+    C.CHAIN_ID_BOB,
+    C.CHAIN_ID_ZKLINK_NOVA,
+]);
+/**
+ * Rango's canonical uppercase blockchain name for a given omnichain chain
+ * id, or `undefined` when the chain is not on Rango, when the input is not
+ * a real number (`NaN`), or when it is `null` / `undefined`.
+ *
+ * `bigint` input is rejected at runtime and returns `undefined`. Callers
+ * bridging from `ethers` v6's `Network.chainId: bigint` should narrow with
+ * `Number(x)` and check `Number.isSafeInteger` first.
+ */
+function rangoNameForChainId(chainId) {
+    if (typeof chainId !== 'number' || Number.isNaN(chainId))
+        return undefined;
+    return exports.CHAIN_ID_TO_RANGO_NAME.get(chainId);
+}
+/**
+ * Omnichain chain id for a Rango blockchain name. Input is normalised
+ * (`trim()` + `toUpperCase()`) so `' bsc '`, `'BSC'`, `'Bsc'` all resolve
+ * to `56`. Returns `undefined` for an unknown name, for any non-string
+ * input, for raw input longer than 64 characters (rejected before any
+ * per-character work — the bound is several times the longest name in
+ * the snapshot, so it is a DoS guard, not a contract), or for input
+ * carrying non-ASCII characters (Unicode-aware `toUpperCase` folds
+ * `'ſ' → 'S'`
+ * and `'ı' → 'I'`, which would resolve homoglyph inputs to real chain
+ * ids — the accessor fails closed instead). Callers looping over
+ * untrusted Rango feed rows can skip bad entries without a `TypeError`.
+ */
+function chainIdForRangoName(name) {
+    if (typeof name !== 'string')
+        return undefined;
+    if (name.length > MAX_RANGO_NAME_LENGTH)
+        return undefined;
+    for (let i = 0; i < name.length; i++) {
+        if (name.charCodeAt(i) > 0x7f)
+            return undefined;
+    }
+    return exports.RANGO_NAME_TO_CHAIN_ID.get(name.trim().toUpperCase());
+}
+//# sourceMappingURL=rango_chain_names.js.map

package/dist/cjs/rango_chain_names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rango_chain_names.js","sourceRoot":"","sources":["../../rango_chain_names.ts"],"names":[],"mappings":"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"}

package/dist/cjs/solana/solana_chain.js

@@ -587,56 +587,85 @@ class SolanaChain extends chain_base_ts_1.Chain {
         catch {
             scrubUrl = null;
         }
-        let tx;
-        try {
-            tx = await connection.getTransaction(txHash, {
+        // RIN-296 D1: fetch `getTransaction` and `getSignatureStatus` in
+        // parallel so the common (Success) case pays one round-trip of
+        // latency instead of two. `getSignatureStatus` populates the four
+        // new finality fields (slot / confirmations / confirmationStatus /
+        // signers) on the status; `slot` and `signers` also come from
+        // `getTransaction` when it succeeds.
+        const [txResult, sigResult] = await Promise.allSettled([
+            connection.getTransaction(txHash, {
                 commitment: 'confirmed',
                 maxSupportedTransactionVersion: 0,
-            });
-        }
-        catch (err) {
+            }),
+            connection.getSignatureStatus(txHash, { searchTransactionHistory: true }),
+        ]);
+        if (txResult.status === 'rejected') {
+            const err = txResult.reason;
             const rawMsg = err instanceof Error ? err.message : String(err);
             throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, (0, errors_ts_1.sanitizeMessage)(`Failed to read Solana tx ${txHash}: ${rawMsg}`, scrubUrl), { chainId: this.chainId, txHash }, (0, errors_ts_1.sanitizeCause)(err, scrubUrl));
         }
+        const tx = txResult.value;
+        // RIN-296 D2: sig-status failure on the Success path degrades to
+        // `null` fields rather than throwing — a working tx read must not
+        // fail because a metadata enrichment call failed.
+        const sigValue = sigResult.status === 'fulfilled' ? (sigResult.value?.value ?? null) : null;
+        const confirmationStatus = extractSolanaConfirmationStatus(sigValue?.confirmationStatus);
+        const confirmations = normaliseSolanaConfirmations(sigValue);
         if (!tx) {
-            // Full tx not fetchable; fall back to signature status. Consume BOTH
-            // fields (`confirmationStatus` + `err`) — the previous fix that
-            // always returned Pending on settled-but-unfetchable let a settled-
-            // FAILED tx poll indefinitely.
-            let sig;
-            try {
-                sig = await connection.getSignatureStatus(txHash, { searchTransactionHistory: true });
-            }
-            catch (err) {
+            // Full tx not fetchable; use signature status. Consume BOTH fields
+            // (`confirmationStatus` + `err`) — always returning Pending on
+            // settled-but-unfetchable would let a settled-FAILED tx poll
+            // indefinitely.
+            if (sigResult.status === 'rejected') {
+                const err = sigResult.reason;
                 const rawMsg = err instanceof Error ? err.message : String(err);
                 throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, (0, errors_ts_1.sanitizeMessage)(`Failed to read Solana signature status ${txHash}: ${rawMsg}`, scrubUrl), { chainId: this.chainId, txHash }, (0, errors_ts_1.sanitizeCause)(err, scrubUrl));
             }
-            if (!sig || !sig.value)
+            if (!sigValue)
                 return solana_transaction_status_ts_1.SolanaTransactionStatus.notFound(this.chainId);
-            const settled = sig.value.confirmationStatus === 'finalized' ||
-                sig.value.confirmationStatus === 'confirmed';
-            if (settled && sig.value.err) {
-                // Fees are not reconstructable from a sig-status only — factory
-                // now accepts fees: null for exactly this case.
+            const slot = sigValue.slot ?? null;
+            const settled = confirmationStatus === 'finalized' || confirmationStatus === 'confirmed';
+            if (settled && sigValue.err) {
                 return solana_transaction_status_ts_1.SolanaTransactionStatus.failed({
                     chainId: this.chainId,
                     inclusionAt: null,
-                    error: { code: 'REVERTED', reason: JSON.stringify(sig.value.err) },
+                    error: { code: 'REVERTED', reason: JSON.stringify(sigValue.err) },
                     fees: null,
+                    slot,
+                    confirmations,
+                    confirmationStatus,
                 });
             }
             // settled-Success without a fetchable body OR still propagating —
             // keep polling. NotFound here would misreport a settled deposit.
-            return solana_transaction_status_ts_1.SolanaTransactionStatus.pending(this.chainId);
+            // RIN-296 D3: pass finality through so consumers polling on
+            // Pending see the tx's position toward finality.
+            return solana_transaction_status_ts_1.SolanaTransactionStatus.pending(this.chainId, {
+                slot,
+                confirmations,
+                confirmationStatus,
+            });
         }
+        // RIN-296 R2: `slot` and `signers` are read from the `getTransaction`
+        // response the SDK already fetches. `signers` = the first
+        // `numRequiredSignatures` static account keys, matching
+        // omnichain-py `signer_keys = account_keys[: header.num_required_signatures]`.
+        const slot = tx.slot;
+        const accounts = tx.transaction.message.staticAccountKeys.map((k) => k.toBase58());
+        const signers = accounts.slice(0, tx.transaction.message.header.numRequiredSignatures);
         if (!tx.meta) {
             // A returned tx without meta is a valid RPC response shape (some
             // very old txs or unusual nodes). Report Pending so consumers keep
             // polling rather than throwing from a status read; matches the
             // _decodeBalanceChanges guard at the same file.
-            return solana_transaction_status_ts_1.SolanaTransactionStatus.pending(this.chainId);
+            return solana_transaction_status_ts_1.SolanaTransactionStatus.pending(this.chainId, {
+                slot,
+                confirmations,
+                confirmationStatus,
+                signers,
+            });
         }
-        const accounts = tx.transaction.message.staticAccountKeys.map((k) => k.toBase58());
         const feePayer = accounts[0] ?? '';
         if (feePayer.length === 0) {
             throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.TransactionDecodeFailed, `Solana tx ${txHash} has no fee_payer account`, { chainId: this.chainId, txHash });
@@ -659,6 +688,10 @@ class SolanaChain extends chain_base_ts_1.Chain {
                 inclusionAt,
                 error: { code: 'REVERTED', reason: JSON.stringify(tx.meta.err) },
                 fees,
+                slot,
+                confirmations,
+                confirmationStatus,
+                signers,
             });
         }
         // Wrap the decoder so a malformed uiTokenAmount.amount / pre/postBalance
@@ -679,6 +712,10 @@ class SolanaChain extends chain_base_ts_1.Chain {
             inclusionAt,
             balanceChanges,
             fees,
+            slot,
+            confirmations,
+            confirmationStatus,
+            signers,
         });
     }
     async getChainTipHeight() {
@@ -1297,6 +1334,33 @@ function signatureBase58FromBytes(txBytes) {
     return bs58encode(sigBytes);
 }
 const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+/**
+ * Narrow `getSignatureStatuses` `confirmationStatus` (a raw string) to
+ * the known union, falling back to `null` for unknown values so a
+ * future upstream widening doesn't lie about the type.
+ */
+function extractSolanaConfirmationStatus(raw) {
+    if (raw === 'processed' || raw === 'confirmed' || raw === 'finalized')
+        return raw;
+    return null;
+}
+/**
+ * Normalise `getSignatureStatuses` `value.confirmations` to a monotone
+ * count consumers can gate on. Per the RPC contract, `null` means
+ * rooted (past `finalized`); the SDK maps that to
+ * {@link SOLANA_FINALIZED_CONFIRMATIONS} so `confirmations >= threshold`
+ * checks behave the way callers expect. Passing a null `sigValue`
+ * (sig-status unavailable — a metadata-enrichment failure on the
+ * success path) returns `null` so consumers can distinguish "unknown"
+ * from any real count.
+ */
+function normaliseSolanaConfirmations(sigValue) {
+    if (sigValue === null)
+        return null;
+    if (sigValue.confirmations !== null)
+        return sigValue.confirmations;
+    return solana_transaction_status_ts_1.SOLANA_FINALIZED_CONFIRMATIONS;
+}
 function parseSolanaSignature(raw) {
     const hexCandidate = raw.startsWith('0x') ? raw.slice(2) : raw;
     if (/^[0-9a-fA-F]+$/.test(hexCandidate) && hexCandidate.length === 128) {