@getomnichain/omnichain 0.2.0

package/dist/solana/unsigned_solana_transaction.js

@@ -0,0 +1,26 @@
+import { PublicKey } from '@solana/web3.js';
+import { NetworkType } from "../network_type.js";
+import { UnsignedTransaction } from "../unsigned_transaction.js";
+export class UnsignedSolanaTransaction extends UnsignedTransaction {
+    transaction;
+    feePayer;
+    recentBlockhash;
+    lastValidBlockHeight;
+    instructions;
+    constructor(init) {
+        super(init.chainId, NetworkType.SOLANA);
+        this.transaction = init.transaction;
+        this.feePayer = init.feePayer;
+        this.recentBlockhash = init.recentBlockhash;
+        this.lastValidBlockHeight = init.lastValidBlockHeight;
+        this.instructions = init.instructions;
+    }
+    /** Serializes the message (without signatures). Useful for off-line signers / tests. */
+    messageBytes() {
+        return this.transaction.message.serialize();
+    }
+    get feePayerPubkey() {
+        return new PublicKey(this.feePayer);
+    }
+}
+//# sourceMappingURL=unsigned_solana_transaction.js.map

package/dist/solana/unsigned_solana_transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsigned_solana_transaction.js","sourceRoot":"","sources":["../../solana/unsigned_solana_transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgD,MAAM,iBAAiB,CAAC;AAE1F,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAoBjE,MAAM,OAAO,yBAA0B,SAAQ,mBAAmB;IACvD,WAAW,CAAuB;IAClC,QAAQ,CAAS;IACjB,eAAe,CAAS;IACxB,oBAAoB,CAAS;IAC7B,YAAY,CAA2B;IAEhD,YAAY,IAAmC;QAC7C,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;QAC5C,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,CAAC;QACtD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACxC,CAAC;IAED,wFAAwF;IACxF,YAAY;QACV,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IAC9C,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/token.d.ts

@@ -0,0 +1,35 @@
+export declare abstract class Token {
+    readonly chainId: number;
+    readonly symbol: string;
+    readonly identifier?: string;
+    readonly decimals: number;
+    protected constructor(chainId: number, symbol: string, identifier: string | undefined, decimals: number);
+    isNative(): boolean;
+    /**
+     * Identity is `(chainId, symbol, identifier)` — decimals is deliberately
+     * NOT part of equality. Mirrors omnichain-py/base/base.py:60-65
+     * (`AbstractAsset.__eq__`).
+     *
+     * **Do NOT use `equals` as a precondition for amount scaling** — two Token
+     * instances can compare equal while disagreeing on decimals. For that
+     * safety check use `strictEquals(other)` (which includes decimals).
+     *
+     * For identifier-only comparison (ignoring both symbol drift and decimals),
+     * use `sameAsset(other)`.
+     */
+    equals(other: Token): boolean;
+    /**
+     * Strict equality including `decimals`. Use before parseUnits-style
+     * conversions where a mismatched decimals would silently mis-scale amounts.
+     */
+    strictEquals(other: Token): boolean;
+    /**
+     * Identifier-only equality — same chain + same contract address / mint /
+     * native marker, regardless of symbol drift (e.g. `'USDT'` vs `'USD₮0'`
+     * for Arbitrum USDT). Useful for registry / lookup paths where the
+     * consumer might not know the canonical symbol.
+     */
+    sameAsset(other: Token): boolean;
+    toString(): string;
+}
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../token.ts"],"names":[],"mappings":"AAEA,8BAAsB,KAAK;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,SAAS,aACP,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM;IAoBlB,QAAQ,IAAI,OAAO;IAInB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAQ7B;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAInC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIhC,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/token.js

@@ -0,0 +1,62 @@
+import { ChainError, ChainErrorKinds } from "./errors.js";
+export class Token {
+    chainId;
+    symbol;
+    identifier;
+    decimals;
+    constructor(chainId, symbol, identifier, decimals) {
+        if (!Number.isInteger(chainId)) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, 'Token chainId must be an integer');
+        }
+        if (!symbol) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, 'Token symbol is required');
+        }
+        if (!Number.isInteger(decimals) || decimals < 0) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, 'Token decimals must be a non-negative integer');
+        }
+        this.chainId = chainId;
+        this.symbol = symbol;
+        this.identifier = identifier;
+        this.decimals = decimals;
+    }
+    isNative() {
+        return this.identifier === undefined;
+    }
+    /**
+     * Identity is `(chainId, symbol, identifier)` — decimals is deliberately
+     * NOT part of equality. Mirrors omnichain-py/base/base.py:60-65
+     * (`AbstractAsset.__eq__`).
+     *
+     * **Do NOT use `equals` as a precondition for amount scaling** — two Token
+     * instances can compare equal while disagreeing on decimals. For that
+     * safety check use `strictEquals(other)` (which includes decimals).
+     *
+     * For identifier-only comparison (ignoring both symbol drift and decimals),
+     * use `sameAsset(other)`.
+     */
+    equals(other) {
+        return (this.chainId === other.chainId &&
+            this.symbol === other.symbol &&
+            this.identifier === other.identifier);
+    }
+    /**
+     * Strict equality including `decimals`. Use before parseUnits-style
+     * conversions where a mismatched decimals would silently mis-scale amounts.
+     */
+    strictEquals(other) {
+        return this.equals(other) && this.decimals === other.decimals;
+    }
+    /**
+     * Identifier-only equality — same chain + same contract address / mint /
+     * native marker, regardless of symbol drift (e.g. `'USDT'` vs `'USD₮0'`
+     * for Arbitrum USDT). Useful for registry / lookup paths where the
+     * consumer might not know the canonical symbol.
+     */
+    sameAsset(other) {
+        return this.chainId === other.chainId && this.identifier === other.identifier;
+    }
+    toString() {
+        return `Token[chainId=${this.chainId}, symbol=${this.symbol}, identifier=${this.identifier ?? 'NATIVE'}, decimals=${this.decimals}]`;
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,OAAgB,KAAK;IAChB,OAAO,CAAS;IAChB,MAAM,CAAS;IACf,UAAU,CAAU;IACpB,QAAQ,CAAS;IAE1B,YACE,OAAe,EACf,MAAc,EACd,UAA8B,EAC9B,QAAgB;QAEhB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,UAAU,CAAC,eAAe,CAAC,eAAe,EAAE,kCAAkC,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,UAAU,CAAC,eAAe,CAAC,eAAe,EAAE,0BAA0B,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,UAAU,CAClB,eAAe,CAAC,eAAe,EAC/B,+CAA+C,CAChD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAY;QACjB,OAAO,CACL,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;YAC9B,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;YAC5B,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CACrC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,KAAY;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC;IAChE,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,KAAY;QACpB,OAAO,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAC;IAChF,CAAC;IAED,QAAQ;QACN,OAAO,iBAAiB,IAAI,CAAC,OAAO,YAAY,IAAI,CAAC,MAAM,gBAAgB,IAAI,CAAC,UAAU,IAAI,QAAQ,cAAc,IAAI,CAAC,QAAQ,GAAG,CAAC;IACvI,CAAC;CACF"}

package/dist/ton/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ton_address.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/ton/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../ton/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/ton/index.js

@@ -0,0 +1,2 @@
+export * from "./ton_address.js";
+//# sourceMappingURL=index.js.map

package/dist/ton/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../ton/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/ton/ton_address.d.ts

@@ -0,0 +1,10 @@
+import { NetworkType } from '../network_type.ts';
+import { Address } from '../address.ts';
+export declare class TonAddress extends Address {
+    constructor(raw: string);
+    canonical(): string;
+    get networkType(): NetworkType;
+    private static assertValid;
+    private static assertUserFriendlyChecksum;
+}
+//# sourceMappingURL=ton_address.d.ts.map

package/dist/ton/ton_address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ton_address.d.ts","sourceRoot":"","sources":["../../ton/ton_address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAOxC,qBAAa,UAAW,SAAQ,OAAO;gBACzB,GAAG,EAAE,MAAM;IAKvB,SAAS,IAAI,MAAM;IAInB,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED,OAAO,CAAC,MAAM,CAAC,WAAW;IAY1B,OAAO,CAAC,MAAM,CAAC,0BAA0B;CAc1C"}

package/dist/ton/ton_address.js

@@ -0,0 +1,53 @@
+import { NetworkType } from "../network_type.js";
+import { Address } from "../address.js";
+const TON_USER_FRIENDLY_REGEX = /^[A-Za-z0-9_-]{48}$/;
+const TON_RAW_REGEX = /^-?\d+:[a-fA-F0-9]{64}$/;
+const USER_FRIENDLY_BYTE_LENGTH = 36;
+const CRC_POLYNOMIAL = 0x1021;
+export class TonAddress extends Address {
+    constructor(raw) {
+        super(raw);
+        TonAddress.assertValid(raw);
+    }
+    canonical() {
+        return this.raw;
+    }
+    get networkType() {
+        return NetworkType.TON;
+    }
+    static assertValid(raw) {
+        if (typeof raw !== 'string') {
+            throw new Error(`Invalid TON address: not a string`);
+        }
+        if (TON_RAW_REGEX.test(raw))
+            return;
+        if (TON_USER_FRIENDLY_REGEX.test(raw)) {
+            TonAddress.assertUserFriendlyChecksum(raw);
+            return;
+        }
+        throw new Error(`Invalid TON address: "${raw}"`);
+    }
+    static assertUserFriendlyChecksum(userFriendly) {
+        const bytes = Buffer.from(userFriendly.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+        if (bytes.length !== USER_FRIENDLY_BYTE_LENGTH) {
+            throw new Error(`Invalid TON address: "${userFriendly}"`);
+        }
+        const claimedCrc = (bytes[34] << 8) | bytes[35];
+        const computedCrc = crc16CcittXmodem(bytes.subarray(0, 34));
+        if (claimedCrc !== computedCrc) {
+            throw new Error(`Invalid TON address checksum: "${userFriendly}"`);
+        }
+    }
+}
+function crc16CcittXmodem(bytes) {
+    let crc = 0;
+    for (const byte of bytes) {
+        crc ^= byte << 8;
+        for (let bit = 0; bit < 8; bit++) {
+            crc =
+                (crc & 0x8000) !== 0 ? ((crc << 1) ^ CRC_POLYNOMIAL) & 0xffff : (crc << 1) & 0xffff;
+        }
+    }
+    return crc;
+}
+//# sourceMappingURL=ton_address.js.map

package/dist/ton/ton_address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ton_address.js","sourceRoot":"","sources":["../../ton/ton_address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AACtD,MAAM,aAAa,GAAG,yBAAyB,CAAC;AAChD,MAAM,yBAAyB,GAAG,EAAE,CAAC;AACrC,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,MAAM,OAAO,UAAW,SAAQ,OAAO;IACrC,YAAY,GAAW;QACrB,KAAK,CAAC,GAAG,CAAC,CAAC;QACX,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,WAAW,CAAC,GAAG,CAAC;IACzB,CAAC;IAEO,MAAM,CAAC,WAAW,CAAC,GAAW;QACpC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO;QACpC,IAAI,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACtC,UAAU,CAAC,0BAA0B,CAAC,GAAG,CAAC,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,GAAG,CAAC,CAAC;IACnD,CAAC;IAEO,MAAM,CAAC,0BAA0B,CAAC,YAAoB;QAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CACvB,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAClD,QAAQ,CACT,CAAC;QACF,IAAI,KAAK,CAAC,MAAM,KAAK,yBAAyB,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,yBAAyB,YAAY,GAAG,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC5D,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,kCAAkC,YAAY,GAAG,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,KAAiB;IACzC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC;QACjB,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;YACjC,GAAG;gBACD,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,cAAc,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/transaction_status.d.ts

@@ -0,0 +1,140 @@
+import { Decimal } from 'decimal.js';
+import { Token } from './token.ts';
+/**
+ * Exact `Decimal → bigint minor-units` conversion. Uses `toFixed(decimals,
+ * ROUND_DOWN)` — this path is NOT bounded by `Decimal.precision` — plus
+ * a string shift, so `new Decimal('123.456789012345678901')` with
+ * `decimals=18` yields exactly `123456789012345678901n` instead of the
+ * `.mul(1e18).trunc()` path's rounded-then-truncated `123456789012345678900n`.
+ * Verified against decimal.js 10.6.0.
+ */
+export declare function hrDecimalToMinorUnits(hr: Decimal, decimals: number): bigint;
+/**
+ * Exact `bigint minor-units → decimal-string` for human-readable display.
+ * Bypasses `Decimal.div` (also precision-bounded at 20), so
+ * `AssetBalanceChange.fromMr(123_456_789_012_345_678_901n, 18)` renders
+ * as `"123.456789012345678901"` — no wei lost.
+ */
+export declare function minorUnitsToHrString(mr: bigint, decimals: number): string;
+export declare const TransactionStatusTypes: {
+    readonly Success: "Success";
+    readonly Failed: "Failed";
+    readonly Pending: "Pending";
+    readonly NotFound: "NotFound";
+};
+export type TransactionStatusType = (typeof TransactionStatusTypes)[keyof typeof TransactionStatusTypes];
+/**
+ * Stable identity key for a token in `NestedBalanceChanges`. Uses
+ * `(chainId, identifier)` — matches `Token.sameAsset` identity. `symbol`
+ * comes from a live `contract.symbol()` on EVM and falls back to
+ * `UNKNOWN_<hex>` on RPC failure, so keying on it produces different keys
+ * for the same asset across transient RPC health. `decimals` is likewise
+ * omitted (already dropped in iter 1) — Solana `uiTokenAmount.decimals`
+ * variance would otherwise split one asset into two non-cancelling rows.
+ * `symbol`/`decimals` are preserved on the stored entry's `token` for display.
+ */
+export declare function assetHashOf(token: Token): string;
+export interface AssetBalanceChangeEntry {
+    token: Token;
+    change: AssetBalanceChange;
+}
+export type NestedBalanceChanges = Map<string, Map<string, AssetBalanceChangeEntry>>;
+/**
+ * Per-(wallet, asset) balance delta. Source of truth is `balanceChangeMr`
+ * (bigint minor units) — exact and native to every on-chain representation.
+ *
+ * Wave 2B adds the Python-parity `balanceChangeHr: Decimal` accessor as a
+ * lazy getter derived from `mr / 10^decimals`. Storage flip vs Python
+ * (which stores `balance_change_hr: Decimal` and computes `mr` in the
+ * constructor): decimal.js defaults to 20 significant digits, so
+ * 18-decimal amounts ≥ ~100 tokens silently truncate on Decimal → bigint
+ * round-trip. Storing bigint keeps every wei/lamport/satoshi exact; the
+ * Decimal getter inherits decimal.js precision limits but never influences
+ * `.balanceChangeMr` on read.
+ */
+export declare class AssetBalanceChange {
+    readonly balanceChangeMr: bigint;
+    readonly decimals: number;
+    constructor(balanceChangeMr: bigint, decimals: number);
+    static zero(decimals?: number): AssetBalanceChange;
+    static fromMr(balanceChangeMr: bigint, decimals: number): AssetBalanceChange;
+    /**
+     * Python-parity factory (`AssetBalanceChange.__init__` in
+     * `base/base.py:239-247` takes `balance_change_hr: Decimal`). Accepts a
+     * `Decimal` directly or any string/number that `new Decimal(...)`
+     * parses. Rounds sub-minor-unit fractional bits DOWN matching Python's
+     * `hr_to_mr`. Uses the exact string-shift path (`toFixed(decimals,
+     * ROUND_DOWN)` + digit concat) rather than `.mul(10^d).trunc()` — the
+     * `.mul` route is precision-bounded by decimal.js's 20-sig-digit
+     * default and would round the last wei on 18-decimal amounts ≥
+     * ~100 tokens.
+     */
+    static fromHr(balanceChangeHr: Decimal | string | number, decimals: number): AssetBalanceChange;
+    /**
+     * Human-readable amount as a `Decimal` — mirrors Python's
+     * `AbstractAssetBalanceChange.balance_change_hr`. Derived lazily from
+     * the bigint source-of-truth via an EXACT string-shift path
+     * (`minorUnitsToHrString`) so the returned `Decimal` carries every
+     * wei/lamport/satoshi. Note: consumers reading the `Decimal` and
+     * feeding it back through decimal.js arithmetic (`.mul`, `.div`)
+     * may still lose precision at decimal.js's 20-sig-digit default —
+     * for exact reconciliation stay on `balanceChangeMr`.
+     */
+    get balanceChangeHr(): Decimal;
+    /**
+     * Sum two changes. Uses `this.decimals` for the result — mirrors Python
+     * `AbstractAssetBalanceChange.__add__` (base/base.py:239-311) which
+     * uses `self._decimals`. No decimals-mismatch check; consumers that
+     * care compare `.decimals` themselves before adding.
+     */
+    add(other: AssetBalanceChange): AssetBalanceChange;
+    /**
+     * Merge `change` into `balanceChanges[wallet][assetHash]`. Mirrors
+     * Python `AssetBalanceChange.upsert` (base/base.py:255-287): mutating,
+     * returns void; zero-net collapses both the asset row and the wallet
+     * row (when the wallet's inner map empties); on non-zero-net merge the
+     * newer `change.decimals` wins (Python uses `change._decimals`, not
+     * `existing._decimals`).
+     *
+     * No decimals-mismatch throw. Python does not check either — the newer
+     * change's decimals silently win. Consumers with a decimals-consistency
+     * requirement enforce it externally.
+     */
+    static upsert(balanceChanges: NestedBalanceChanges, wallet: string, token: Token, change: AssetBalanceChange): void;
+    toString(): string;
+}
+export interface TransactionErrorInfo {
+    code?: string;
+    reason?: string;
+}
+export interface TransactionStatusInit {
+    chainId: number;
+    status: TransactionStatusType;
+    inclusionAt?: Date | null;
+    error?: TransactionErrorInfo | null;
+    balanceChanges?: NestedBalanceChanges | null;
+}
+export declare abstract class TransactionStatus {
+    readonly chainId: number;
+    readonly status: TransactionStatusType;
+    readonly inclusionAt: Date | null;
+    readonly error: TransactionErrorInfo | null;
+    readonly balanceChanges: NestedBalanceChanges | null;
+    protected constructor(init: TransactionStatusInit);
+}
+export declare function isSuccess(s: TransactionStatus): s is TransactionStatus & {
+    balanceChanges: NestedBalanceChanges;
+    error: null;
+};
+export declare function isFailed(s: TransactionStatus): s is TransactionStatus & {
+    balanceChanges: null;
+    error: TransactionErrorInfo;
+};
+export declare function isPending(s: TransactionStatus): s is TransactionStatus & {
+    balanceChanges: null;
+    error: null;
+};
+export declare function isNotFound(s: TransactionStatus): s is TransactionStatus & {
+    balanceChanges: null;
+};
+//# sourceMappingURL=transaction_status.d.ts.map

package/dist/transaction_status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction_status.d.ts","sourceRoot":"","sources":["../transaction_status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CASzE;AAED,eAAO,MAAM,sBAAsB;;;;;CAKzB,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,OAAO,sBAAsB,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEhD;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,MAAM,oBAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC;AAErF;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAWrD,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAE,MAAU,GAAG,kBAAkB;IAIrD,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB;IAI5E;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,CACX,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAC1C,QAAQ,EAAE,MAAM,GACf,kBAAkB;IAyCrB;;;;;;;;;OASG;IACH,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,kBAAkB,GAAG,kBAAkB;IAIlD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CACX,cAAc,EAAE,oBAAoB,EACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,kBAAkB,GACzB,IAAI;IAkCP,QAAQ,IAAI,MAAM;CAMnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpC,cAAc,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC9C;AAED,8BAAsB,iBAAiB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAErD,SAAS,aAAa,IAAI,EAAE,qBAAqB;CAwElD;AAED,wBAAgB,SAAS,CACvB,CAAC,EAAE,iBAAiB,GACnB,CAAC,IAAI,iBAAiB,GAAG;IAAE,cAAc,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,CAEhF;AAED,wBAAgB,QAAQ,CACtB,CAAC,EAAE,iBAAiB,GACnB,CAAC,IAAI,iBAAiB,GAAG;IAAE,cAAc,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAEhF;AAED,wBAAgB,SAAS,CACvB,CAAC,EAAE,iBAAiB,GACnB,CAAC,IAAI,iBAAiB,GAAG;IAAE,cAAc,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,CAEhE;AAED,wBAAgB,UAAU,CACxB,CAAC,EAAE,iBAAiB,GACnB,CAAC,IAAI,iBAAiB,GAAG;IAAE,cAAc,EAAE,IAAI,CAAA;CAAE,CAEnD"}

package/dist/transaction_status.js

@@ -0,0 +1,271 @@
+import { Decimal } from 'decimal.js';
+import { ChainError, ChainErrorKinds } from "./errors.js";
+/**
+ * Exact `Decimal → bigint minor-units` conversion. Uses `toFixed(decimals,
+ * ROUND_DOWN)` — this path is NOT bounded by `Decimal.precision` — plus
+ * a string shift, so `new Decimal('123.456789012345678901')` with
+ * `decimals=18` yields exactly `123456789012345678901n` instead of the
+ * `.mul(1e18).trunc()` path's rounded-then-truncated `123456789012345678900n`.
+ * Verified against decimal.js 10.6.0.
+ */
+export function hrDecimalToMinorUnits(hr, decimals) {
+    // toFixed always emits a plain decimal representation (never scientific).
+    // ROUND_DOWN = 1 truncates toward zero, matching Python's `hr_to_mr`.
+    const fixed = hr.toFixed(decimals, Decimal.ROUND_DOWN);
+    const negative = fixed.startsWith('-');
+    const unsigned = negative ? fixed.slice(1) : fixed;
+    const dot = unsigned.indexOf('.');
+    const intPart = dot === -1 ? unsigned : unsigned.slice(0, dot);
+    const fracPart = dot === -1 ? '' : unsigned.slice(dot + 1);
+    const padded = fracPart.padEnd(decimals, '0').slice(0, decimals);
+    const digits = (intPart + padded).replace(/^0+(?=\d)/, '') || '0';
+    const mag = BigInt(digits);
+    return negative ? -mag : mag;
+}
+/**
+ * Exact `bigint minor-units → decimal-string` for human-readable display.
+ * Bypasses `Decimal.div` (also precision-bounded at 20), so
+ * `AssetBalanceChange.fromMr(123_456_789_012_345_678_901n, 18)` renders
+ * as `"123.456789012345678901"` — no wei lost.
+ */
+export function minorUnitsToHrString(mr, decimals) {
+    const negative = mr < 0n;
+    const digits = (negative ? -mr : mr).toString();
+    if (decimals === 0)
+        return negative ? `-${digits}` : digits;
+    const padded = digits.padStart(decimals + 1, '0');
+    const intPart = padded.slice(0, padded.length - decimals);
+    const fracPart = padded.slice(padded.length - decimals).replace(/0+$/, '');
+    const s = fracPart.length === 0 ? intPart : `${intPart}.${fracPart}`;
+    return negative ? `-${s}` : s;
+}
+export const TransactionStatusTypes = {
+    Success: 'Success',
+    Failed: 'Failed',
+    Pending: 'Pending',
+    NotFound: 'NotFound',
+};
+/**
+ * Stable identity key for a token in `NestedBalanceChanges`. Uses
+ * `(chainId, identifier)` — matches `Token.sameAsset` identity. `symbol`
+ * comes from a live `contract.symbol()` on EVM and falls back to
+ * `UNKNOWN_<hex>` on RPC failure, so keying on it produces different keys
+ * for the same asset across transient RPC health. `decimals` is likewise
+ * omitted (already dropped in iter 1) — Solana `uiTokenAmount.decimals`
+ * variance would otherwise split one asset into two non-cancelling rows.
+ * `symbol`/`decimals` are preserved on the stored entry's `token` for display.
+ */
+export function assetHashOf(token) {
+    return `${token.chainId}_${token.identifier ?? ''}`;
+}
+/**
+ * Per-(wallet, asset) balance delta. Source of truth is `balanceChangeMr`
+ * (bigint minor units) — exact and native to every on-chain representation.
+ *
+ * Wave 2B adds the Python-parity `balanceChangeHr: Decimal` accessor as a
+ * lazy getter derived from `mr / 10^decimals`. Storage flip vs Python
+ * (which stores `balance_change_hr: Decimal` and computes `mr` in the
+ * constructor): decimal.js defaults to 20 significant digits, so
+ * 18-decimal amounts ≥ ~100 tokens silently truncate on Decimal → bigint
+ * round-trip. Storing bigint keeps every wei/lamport/satoshi exact; the
+ * Decimal getter inherits decimal.js precision limits but never influences
+ * `.balanceChangeMr` on read.
+ */
+export class AssetBalanceChange {
+    balanceChangeMr;
+    decimals;
+    constructor(balanceChangeMr, decimals) {
+        if (!Number.isInteger(decimals) || decimals < 0) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `AssetBalanceChange decimals must be a non-negative integer, got ${decimals}`);
+        }
+        this.balanceChangeMr = balanceChangeMr;
+        this.decimals = decimals;
+    }
+    static zero(decimals = 0) {
+        return new AssetBalanceChange(0n, decimals);
+    }
+    static fromMr(balanceChangeMr, decimals) {
+        return new AssetBalanceChange(balanceChangeMr, decimals);
+    }
+    /**
+     * Python-parity factory (`AssetBalanceChange.__init__` in
+     * `base/base.py:239-247` takes `balance_change_hr: Decimal`). Accepts a
+     * `Decimal` directly or any string/number that `new Decimal(...)`
+     * parses. Rounds sub-minor-unit fractional bits DOWN matching Python's
+     * `hr_to_mr`. Uses the exact string-shift path (`toFixed(decimals,
+     * ROUND_DOWN)` + digit concat) rather than `.mul(10^d).trunc()` — the
+     * `.mul` route is precision-bounded by decimal.js's 20-sig-digit
+     * default and would round the last wei on 18-decimal amounts ≥
+     * ~100 tokens.
+     */
+    static fromHr(balanceChangeHr, decimals) {
+        // Nested-copy-safe: for Decimal-shaped objects use string round-trip
+        // via toString() (exact and always reparseable), not `instanceof`
+        // which fails on a Decimal from a duplicated decimal.js copy in
+        // the consumer tree. Strings and numbers go straight through
+        // decimal.js's own constructor.
+        let hr;
+        try {
+            if (typeof balanceChangeHr === 'object' &&
+                balanceChangeHr !== null &&
+                typeof balanceChangeHr.toFixed === 'function' &&
+                typeof balanceChangeHr.toString === 'function') {
+                hr = new Decimal(balanceChangeHr.toString());
+            }
+            else {
+                hr = new Decimal(balanceChangeHr);
+            }
+        }
+        catch (err) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `AssetBalanceChange.fromHr: unparseable input ${String(balanceChangeHr)}`, undefined, err instanceof Error ? err : undefined);
+        }
+        if (!hr.isFinite()) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `AssetBalanceChange.fromHr: input must be finite (got ${hr.toString()})`);
+        }
+        if (!Number.isInteger(decimals) || decimals < 0) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `AssetBalanceChange.fromHr: decimals must be a non-negative integer (got ${decimals})`);
+        }
+        return new AssetBalanceChange(hrDecimalToMinorUnits(hr, decimals), decimals);
+    }
+    /**
+     * Human-readable amount as a `Decimal` — mirrors Python's
+     * `AbstractAssetBalanceChange.balance_change_hr`. Derived lazily from
+     * the bigint source-of-truth via an EXACT string-shift path
+     * (`minorUnitsToHrString`) so the returned `Decimal` carries every
+     * wei/lamport/satoshi. Note: consumers reading the `Decimal` and
+     * feeding it back through decimal.js arithmetic (`.mul`, `.div`)
+     * may still lose precision at decimal.js's 20-sig-digit default —
+     * for exact reconciliation stay on `balanceChangeMr`.
+     */
+    get balanceChangeHr() {
+        return new Decimal(minorUnitsToHrString(this.balanceChangeMr, this.decimals));
+    }
+    /**
+     * Sum two changes. Uses `this.decimals` for the result — mirrors Python
+     * `AbstractAssetBalanceChange.__add__` (base/base.py:239-311) which
+     * uses `self._decimals`. No decimals-mismatch check; consumers that
+     * care compare `.decimals` themselves before adding.
+     */
+    add(other) {
+        return new AssetBalanceChange(this.balanceChangeMr + other.balanceChangeMr, this.decimals);
+    }
+    /**
+     * Merge `change` into `balanceChanges[wallet][assetHash]`. Mirrors
+     * Python `AssetBalanceChange.upsert` (base/base.py:255-287): mutating,
+     * returns void; zero-net collapses both the asset row and the wallet
+     * row (when the wallet's inner map empties); on non-zero-net merge the
+     * newer `change.decimals` wins (Python uses `change._decimals`, not
+     * `existing._decimals`).
+     *
+     * No decimals-mismatch throw. Python does not check either — the newer
+     * change's decimals silently win. Consumers with a decimals-consistency
+     * requirement enforce it externally.
+     */
+    static upsert(balanceChanges, wallet, token, change) {
+        const hash = assetHashOf(token);
+        let perWallet = balanceChanges.get(wallet);
+        if (!perWallet) {
+            perWallet = new Map();
+            balanceChanges.set(wallet, perWallet);
+        }
+        const existing = perWallet.get(hash);
+        if (!existing) {
+            // Symmetric with the zero-net merge branch below: don't create a
+            // "no change" row for a zero delta. balanceChangesExcludingFees
+            // can hit this when a fee_payer with no existing row is credited
+            // with fee_lamports === 0n (subsidised chains). If the perWallet
+            // Map was just created for this insert, drop it to keep the
+            // container empty.
+            if (change.balanceChangeMr === 0n) {
+                if (perWallet.size === 0)
+                    balanceChanges.delete(wallet);
+                return;
+            }
+            perWallet.set(hash, { token, change });
+            return;
+        }
+        const netMr = existing.change.balanceChangeMr + change.balanceChangeMr;
+        if (netMr === 0n) {
+            perWallet.delete(hash);
+            if (perWallet.size === 0)
+                balanceChanges.delete(wallet);
+            return;
+        }
+        perWallet.set(hash, {
+            token,
+            change: new AssetBalanceChange(netMr, change.decimals),
+        });
+    }
+    toString() {
+        // Emit both the exact bigint (never lossy) and the human-readable
+        // string derived via minorUnitsToHrString (also exact — no decimal.js
+        // rounding). Neither field can drop wei.
+        return `[change:${minorUnitsToHrString(this.balanceChangeMr, this.decimals)}(hr) / ${this.balanceChangeMr}(mr)]`;
+    }
+}
+export class TransactionStatus {
+    chainId;
+    status;
+    inclusionAt;
+    error;
+    balanceChanges;
+    constructor(init) {
+        const { chainId, status } = init;
+        const inclusionAt = init.inclusionAt ?? null;
+        const error = init.error ?? null;
+        const balanceChanges = init.balanceChanges ?? null;
+        switch (status) {
+            case TransactionStatusTypes.Success:
+                if (balanceChanges === null) {
+                    throw new ChainError(ChainErrorKinds.InvalidArgument, `TransactionStatus(Success) requires balanceChanges; chainId=${chainId}`);
+                }
+                if (error !== null) {
+                    throw new ChainError(ChainErrorKinds.InvalidArgument, `TransactionStatus(Success) must have null error; chainId=${chainId}`);
+                }
+                break;
+            case TransactionStatusTypes.Failed:
+                if (balanceChanges !== null) {
+                    throw new ChainError(ChainErrorKinds.InvalidArgument, `TransactionStatus(Failed) must have null balanceChanges; chainId=${chainId}`);
+                }
+                if (error === null) {
+                    throw new ChainError(ChainErrorKinds.InvalidArgument, `TransactionStatus(Failed) requires error; chainId=${chainId}`);
+                }
+                break;
+            case TransactionStatusTypes.NotFound:
+                if (balanceChanges !== null) {
+                    throw new ChainError(ChainErrorKinds.InvalidArgument, `TransactionStatus(NotFound) must have null balanceChanges; chainId=${chainId}`);
+                }
+                break;
+            case TransactionStatusTypes.Pending:
+                if (balanceChanges !== null) {
+                    throw new ChainError(ChainErrorKinds.InvalidArgument, `TransactionStatus(Pending) must have null balanceChanges; chainId=${chainId}`);
+                }
+                if (error !== null) {
+                    throw new ChainError(ChainErrorKinds.InvalidArgument, `TransactionStatus(Pending) must have null error; chainId=${chainId}`);
+                }
+                break;
+            default: {
+                const _exhaustive = status;
+                throw new ChainError(ChainErrorKinds.InvalidArgument, `Unknown TransactionStatusType: ${String(_exhaustive)}`);
+            }
+        }
+        this.chainId = chainId;
+        this.status = status;
+        this.inclusionAt = inclusionAt;
+        this.error = error;
+        this.balanceChanges = balanceChanges;
+    }
+}
+export function isSuccess(s) {
+    return s.status === TransactionStatusTypes.Success;
+}
+export function isFailed(s) {
+    return s.status === TransactionStatusTypes.Failed;
+}
+export function isPending(s) {
+    return s.status === TransactionStatusTypes.Pending;
+}
+export function isNotFound(s) {
+    return s.status === TransactionStatusTypes.NotFound;
+}
+//# sourceMappingURL=transaction_status.js.map