@getomnichain/omnichain 0.2.0 → 0.3.0

package/dist/cjs/evm/evm_chain.js

@@ -0,0 +1,1109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvmChain = void 0;
+exports.decodeRevertData = decodeRevertData;
+const ethers_1 = require("ethers");
+const network_type_ts_1 = require("../network_type.js");
+const chain_base_ts_1 = require("../chain.base.js");
+const errors_ts_1 = require("../errors.js");
+const priority_ts_1 = require("../priority.js");
+const evm_gas_estimate_ts_1 = require("./evm_gas_estimate.js");
+const transaction_status_ts_1 = require("../transaction_status.js");
+const evm_transaction_status_ts_1 = require("./evm_transaction_status.js");
+const evm_address_ts_1 = require("./evm_address.js");
+const evm_token_ts_1 = require("./evm_token.js");
+const unsigned_evm_transaction_ts_1 = require("./unsigned_evm_transaction.js");
+// Priority profile mirrors omnichain-py/impl/evm/base.py:440-444
+// (`_FEE_PRIORITY_PROFILE`): the reward-percentile is used for the 1559
+// path (get_1559_fees's reward_percentile arg); the legacy multiplier
+// applies ONLY when supportsEip1559 is false (Python does not fall back
+// to the multiplier on the 1559 path).
+const PRIORITY_REWARD_PERCENTILE = {
+    [priority_ts_1.Priority.SLOW]: 25,
+    [priority_ts_1.Priority.NORMAL]: 50,
+    [priority_ts_1.Priority.FAST]: 75,
+};
+// Legacy gas-price multiplier per priority tier — for the legacy branch only.
+// Expressed as basis points × 100 so integer bigint arithmetic works.
+const GAS_MULTIPLIER_PCT = {
+    [priority_ts_1.Priority.SLOW]: 100n,
+    [priority_ts_1.Priority.NORMAL]: 120n,
+    [priority_ts_1.Priority.FAST]: 150n,
+};
+// Empty-reward fallback tip: 2 gwei — matches Python `Web3.to_wei(2, 'gwei')`
+// at impl/evm/base.py:1124.
+const EMPTY_REWARD_FALLBACK_TIP = 2000000000n;
+// Number of latest blocks sampled by eth_feeHistory. Python default 10
+// (impl/evm/base.py:1099).
+const FEE_HISTORY_BLOCK_COUNT = 10;
+// Final-tip percentile picked across the sampled blocks after sorting.
+// Python default 90.0 (impl/evm/base.py:1102).
+const FINAL_TIP_PERCENTILE = 90;
+// TS-only safety floor applied to any suggested gas price / tip. Python does
+// NOT enforce a minimum: `sorted_tips[idx]` can be 0 on quiet L2 blocks.
+// Silently unmineable transactions are unacceptable for a signing SDK, so
+// TS clamps to 0.05 gwei.
+const MIN_GAS_PRICE_FLOOR = 50000000n;
+function atLeast(n, min) {
+    return n < min ? min : n;
+}
+const ERC20_TRANSFER_TOPIC = evm_transaction_status_ts_1.ERC20_TRANSFER_TOPIC;
+const ERC20_ABI = [
+    'function balanceOf(address owner) view returns (uint256)',
+    'function decimals() view returns (uint8)',
+    'function symbol() view returns (string)',
+    'function transfer(address to, uint256 value)',
+];
+const ERC20_INTERFACE = new ethers_1.Interface(ERC20_ABI);
+class EvmChain extends chain_base_ts_1.Chain {
+    rpcUrl;
+    rpcUrls;
+    supportsEip1559;
+    hasL1Fee;
+    /**
+     * Default gas limit for native transfers. Matches Python's public attribute
+     * at `impl/evm/base.py:495` — v0 does not consume it inside the TS SDK
+     * (see `createTransferUnsignedTransaction`) but exposes it so consumers
+     * building their own transfer paths get identical numbers to Python. Wired
+     * into the SDK-owned transfer builder in a follow-up branch.
+     */
+    nativeTransferGasLimit;
+    /**
+     * Legacy `eth_gasPrice` multiplier for native transfers on non-1559 chains.
+     * Matches Python's public attribute at `impl/evm/base.py:496`. Same
+     * "declarative for consumers, unused internally in v0" note as
+     * `nativeTransferGasLimit`.
+     */
+    nativeTransferGasMultiplier;
+    supports7702;
+    _nativeToken;
+    _provider = null;
+    _resolvedRpcUrl = null;
+    constructor(init) {
+        // Conflict guard — refuse to construct an EvmChain over a chainId that
+        // the static family seeds have already registered as non-EVM. Prevents
+        // the case where `new EvmChain({ chainId: 728126428, … })` would silently
+        // succeed and then contradict `addressFor(728126428, …)` /
+        // `networkTypeOf(728126428)` (both return TRON). Mirrors
+        // `registerNonEvmChain`'s throw-on-conflict guard.
+        const existing = (0, network_type_ts_1.tryNetworkTypeOf)(init.chainId);
+        if (existing !== undefined && existing !== network_type_ts_1.NetworkType.EVM) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `chainId ${init.chainId} is registered as ${existing}; refusing to construct EvmChain for it`, { chainId: init.chainId });
+        }
+        super(init.chainId, init.name, network_type_ts_1.NetworkType.EVM, init.blockTimeSeconds, init.nativeSymbol, init.explorerBaseUrl);
+        this.rpcUrl = init.rpcUrl;
+        this.rpcUrls = init.rpcUrls ?? [];
+        if (this.rpcUrls.length > 1) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `EvmChainInit.rpcUrls accepts only ONE endpoint in 0.3.0 (got ${this.rpcUrls.length}). Automatic failover retry is deferred to a follow-up release; passing >1 endpoint would silently discard entries.`, { chainId: init.chainId });
+        }
+        this.supportsEip1559 = init.supportsEip1559 ?? true;
+        this.hasL1Fee = init.hasL1Fee ?? false;
+        this.nativeTransferGasLimit = init.nativeTransferGasLimit ?? 21000;
+        this.nativeTransferGasMultiplier = init.nativeTransferGasMultiplier ?? 1.4;
+        this.supports7702 = init.supports7702 ?? false;
+        this._nativeToken = evm_token_ts_1.EvmToken.native(init.chainId, init.nativeSymbol, init.nativeDecimals ?? 18);
+        // NOTE: no `registerNonEvmChain(id, EVM)` call — a module-scope write on
+        // 48 pre-baked chains would let a consumer's earlier
+        // `registerNonEvmChain(id, COSMOS)` turn `import '@getomnichain/omnichain'`
+        // into a permanently-poisoned module. Conflict detection lives in a
+        // single place: `registerNonEvmChain` reads `tryNetworkTypeOf` (which
+        // synthesizes EVM for positive-unregistered ids), so claiming a positive
+        // id for a non-EVM family requires `unregisterChain(id)` first.
+    }
+    get nativeToken() {
+        return this._nativeToken;
+    }
+    getErc20Token(symbol, contractAddress, decimals) {
+        // `EvmToken.erc20` → `new EvmToken` normalizes the identifier internally;
+        // no need to checksum here as well.
+        return evm_token_ts_1.EvmToken.erc20(this.chainId, symbol, contractAddress, decimals);
+    }
+    getProvider() {
+        if (this._provider)
+            return this._provider;
+        const rpcUrl = this.readRpcUrl();
+        this._resolvedRpcUrl = rpcUrl;
+        this._provider = new ethers_1.JsonRpcProvider(rpcUrl);
+        return this._provider;
+    }
+    /**
+     * Suggest gas fees for a priority tier. Mirrors Python's `_resolve_gas_pricing`
+     * dispatch (impl/evm/base.py:807-833):
+     *
+     *   - legacy chains (`supportsEip1559 === false`): scale `eth_gasPrice` by
+     *     the priority tier's legacy multiplier.
+     *   - 1559 chains: sample eth_feeHistory across the last 10 blocks at the
+     *     tier's reward percentile, sort, pick the p90 across blocks. On empty
+     *     rewards, use 2 gwei. On RPC failure, bubble as `ChainError(RpcError)`
+     *     (Python bubbles too — no defensive fallback).
+     */
+    async suggestGas(priority) {
+        const provider = this.getProvider();
+        if (!this.supportsEip1559) {
+            const mult = GAS_MULTIPLIER_PCT[priority];
+            // Direct `eth_gasPrice` — one round-trip, matches Python
+            // impl/evm/base.py:831-833. Avoids getFeeData's implicit
+            // `getBlock("latest")` + potential `eth_maxPriorityFeePerGas` extra
+            // calls, and dodges the trap where getFeeData's maxFeePerGas is
+            // `2×baseFee + tip` (not a legacy price) — using that as the legacy
+            // gasPrice would 3-4× overpay.
+            let gasPriceHex;
+            try {
+                gasPriceHex = (await provider.send('eth_gasPrice', []));
+            }
+            catch (err) {
+                throw this.rpcError('legacy eth_gasPrice transport failed', err);
+            }
+            let providerHint;
+            try {
+                providerHint = BigInt(gasPriceHex);
+            }
+            catch {
+                // Genuinely unparseable response — bubble as RpcError so on-call
+                // triage sees the RPC returned nonsense, not "0 gas price".
+                throw this.rpcError(`legacy eth_gasPrice returned unparseable response`, new Error(`could not parse ${String(gasPriceHex)} as bigint`));
+            }
+            // Zero-or-negative gasPrice: clamp up to MIN_GAS_PRICE_FLOOR, mirroring
+            // the 1559 branch's floor-on-sub-floor-tips behavior (evm_chain.ts:307).
+            // Python (`impl/evm/base.py:831-833`) multiplies whatever `eth_gasPrice`
+            // returns and never throws; the TS floor is the safety measure that
+            // prevents an unmineable suggestion. Consistent policy across branches.
+            const base = providerHint > 0n ? providerHint : MIN_GAS_PRICE_FLOOR;
+            const scaled = atLeast((base * mult) / 100n, MIN_GAS_PRICE_FLOOR);
+            // Legacy chains: only `gasPrice` is authoritative — matches Python
+            // (`impl/evm/base.py:830-833` returns `EvmGasPricing(gas_price=...)`).
+            // Populating maxFeePerGas/maxPriorityFeePerGas as duplicates would let
+            // a consumer build a type-2 tx paying the full gasPrice as a tip on
+            // top of base fee.
+            return new evm_gas_estimate_ts_1.EvmGasEstimate({ kind: 'legacy', gasPrice: scaled });
+        }
+        // 1559 path — mirrors omnichain-py get_1559_fees (impl/evm/base.py:1098-1132).
+        // NB: Python reads `base_fee_per_gas` from `eth_getBlock("latest")` (line
+        // 1109-1110); TS reuses `feeHistory.baseFeePerGas[-1]` — the JSON-RPC
+        // "next block projection", up to ±12.5% off. Deliberate: saves an RPC
+        // round-trip. (See the local SINAN questions doc for the upstream
+        // discussion — TS uses feeHistory's projection to skip the extra RPC.)
+        const rewardPercentile = PRIORITY_REWARD_PERCENTILE[priority];
+        let raw;
+        // Narrow try — only the RPC call. Response-shape and parse errors are
+        // distinct from transport failures and get a distinct ChainError kind.
+        try {
+            raw = (await provider.send('eth_feeHistory', [
+                `0x${FEE_HISTORY_BLOCK_COUNT.toString(16)}`,
+                'latest',
+                [rewardPercentile],
+            ]));
+        }
+        catch (err) {
+            throw this.rpcError('eth_feeHistory transport failed', err);
+        }
+        // Narrow parse — only the shape checks + BigInt() coercions can throw
+        // for structural reasons here. `EvmGasEstimate` construction and the
+        // pure-arithmetic tip selection happen outside so that a defect there
+        // isn't mislabelled as an RPC-response malformed error.
+        let latestBaseFee;
+        let tips;
+        try {
+            const baseFees = raw.baseFeePerGas;
+            if (!Array.isArray(baseFees) || baseFees.length === 0) {
+                throw new Error('missing baseFeePerGas');
+            }
+            latestBaseFee = BigInt(baseFees[baseFees.length - 1] ?? '0x0');
+            const rewardRows = Array.isArray(raw.reward) ? raw.reward : [];
+            tips = rewardRows
+                .map((row) => (Array.isArray(row) ? row[0] : undefined))
+                .filter((v) => typeof v === 'string')
+                .map((v) => BigInt(v));
+        }
+        catch (err) {
+            // Distinct from the RpcError raised by the provider.send catch above:
+            // parse/shape failures indict the response, not the transport. Routed
+            // through rpcError() so the URL sanitizer scrubs the response body.
+            throw this.rpcError(`eth_feeHistory response malformed`, err);
+        }
+        let selectedTip;
+        if (tips.length === 0) {
+            selectedTip = EMPTY_REWARD_FALLBACK_TIP;
+        }
+        else {
+            const sortedTips = [...tips].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+            const idx = Math.min(Math.floor((sortedTips.length * FINAL_TIP_PERCENTILE) / 100), sortedTips.length - 1);
+            selectedTip = sortedTips[idx] ?? 0n;
+        }
+        // TS safety floor — Python doesn't clamp (see MIN_GAS_PRICE_FLOOR).
+        const finalTip = atLeast(selectedTip, MIN_GAS_PRICE_FLOOR);
+        // Safety buffer: base fee can climb 12.5%/block; caller may wait multiple blocks.
+        const maxFeePerGas = latestBaseFee * 2n + finalTip;
+        return new evm_gas_estimate_ts_1.EvmGasEstimate({
+            kind: 'eip1559',
+            maxPriorityFeePerGas: finalTip,
+            maxFeePerGas,
+        });
+    }
+    readRpcUrl() {
+        if (this.rpcUrl && this.rpcUrl.trim().length > 0)
+            return this.rpcUrl.trim();
+        if (this.rpcUrls.length > 0) {
+            for (const candidate of this.rpcUrls) {
+                if (candidate && candidate.trim().length > 0)
+                    return candidate.trim();
+            }
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcNotConfigured, `${this.name}: rpcUrls was supplied but every entry is blank; refusing to fall back to env or public defaults`, { chainId: this.chainId });
+        }
+        const env = globalThis.process?.env;
+        const candidates = envCandidatesFor(this.name, this.chainId);
+        for (const key of candidates) {
+            const value = env?.[key];
+            if (value && value.trim().length > 0)
+                return value.trim();
+        }
+        throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcNotConfigured, `${this.name} RPC URL is not configured (pass rpcUrl, rpcUrls at construction, or set one of: ${candidates.join(', ')})`, { chainId: this.chainId, envCandidates: candidates });
+    }
+    rpcHost() {
+        const url = this._resolvedRpcUrl ?? this.rpcUrl;
+        if (!url)
+            return undefined;
+        try {
+            const u = new URL(url);
+            return `${u.protocol}//${u.host}`;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    getWalletExplorerUrl(address) {
+        return `${this.explorerBaseUrl}/address/${address}`;
+    }
+    getTokenExplorerUrl(tokenIdentifier) {
+        if (tokenIdentifier === undefined) {
+            return this.explorerBaseUrl;
+        }
+        return `${this.explorerBaseUrl}/token/${tokenIdentifier}`;
+    }
+    getTransactionExplorerUrl(txHash) {
+        const prefixed = txHash.startsWith('0x') ? txHash : `0x${txHash}`;
+        return `${this.explorerBaseUrl}/tx/${prefixed}`;
+    }
+    validateAddress(raw) {
+        try {
+            new evm_address_ts_1.EvmAddress(raw);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    normalizeAddressOrThrow(raw, field) {
+        const body = raw.replace(/^0[xX]/, '');
+        try {
+            return (0, ethers_1.getAddress)(`0x${body}`);
+        }
+        catch (err) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM address for ${field}: ${raw}`, { chainId: this.chainId, address: raw }, err instanceof Error ? err : undefined);
+        }
+    }
+    validateTokenIdentifier(raw) {
+        if (raw === undefined)
+            return true;
+        return this.validateAddress(raw);
+    }
+    async getBalance(owner, tokenIdentifier) {
+        if (!this.validateAddress(owner)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM address: ${owner}`, {
+                chainId: this.chainId,
+                address: owner,
+            });
+        }
+        if (!this.validateTokenIdentifier(tokenIdentifier)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidTokenIdentifier, `Invalid EVM token identifier: ${tokenIdentifier}`, { chainId: this.chainId, identifier: tokenIdentifier });
+        }
+        const provider = this.getProvider();
+        try {
+            if (tokenIdentifier === undefined) {
+                return await provider.getBalance(owner);
+            }
+            const contract = new ethers_1.Contract(tokenIdentifier, ERC20_ABI, provider);
+            return (await contract.balanceOf(owner));
+        }
+        catch (err) {
+            throw this.rpcError(`Failed to read balance for ${owner}`, err);
+        }
+    }
+    async createTransferUnsignedTransaction(req) {
+        if (!this.validateAddress(req.to)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid recipient address: ${req.to}`, {
+                chainId: this.chainId,
+                address: req.to,
+            });
+        }
+        if (req.from !== undefined && !this.validateAddress(req.from)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid sender address: ${req.from}`, {
+                chainId: this.chainId,
+                address: req.from,
+            });
+        }
+        if (!this.validateTokenIdentifier(req.tokenIdentifier)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidTokenIdentifier, `Invalid token identifier: ${req.tokenIdentifier}`, { chainId: this.chainId, identifier: req.tokenIdentifier });
+        }
+        // gasPricing is on the CreateTransferRequest interface (Python
+        // parity) but per-chain wiring is deferred to a follow-up card.
+        // Rejecting it here rather than silently ignoring — a money knob
+        // that fails open is worse than not shipping it.
+        if (req.gasPricing !== undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, 'CreateTransferRequest.gasPricing is not yet consumed by EvmChain (Phase 2 follow-up). Use ethers tx builder options directly for now.', { chainId: this.chainId });
+        }
+        // isFullBalance is on the CreateTransferRequest interface (Python
+        // parity) but needs a fee-reserve computation before it can be
+        // safely wired — sending `value = balance` on native leaves 0 for
+        // gas → guaranteed insufficient-funds; on SPL it leaves 0 for rent.
+        // Deferred to a follow-up card that lands the estimated-fee subtract.
+        if (req.isFullBalance === true) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, 'CreateTransferRequest.isFullBalance is not yet supported on EvmChain — pass `amount` or `amountHr` explicitly and reserve fees yourself.', { chainId: this.chainId });
+        }
+        // Only fetch decimals when amountHr is the input form — avoids two
+        // extra eth_calls on every bigint-amount transfer. Native path uses
+        // the SDK-declared decimals; ERC-20 path uses a STRICT resolver
+        // that throws on RPC failure (the defensive fallback to decimals=0
+        // would silently produce a wildly wrong minor-units amount).
+        let tokenDecimals = 0;
+        if (req.amountHr !== undefined) {
+            tokenDecimals =
+                req.tokenIdentifier === undefined
+                    ? this._nativeToken.decimals
+                    : await this.resolveErc20DecimalsStrict(req.tokenIdentifier);
+        }
+        const resolved = (0, chain_base_ts_1.resolveTransferAmount)(req, tokenDecimals);
+        const amountMr = resolved.kind === 'exact' ? resolved.amountMr : 0n;
+        if (req.tokenIdentifier === undefined) {
+            return new unsigned_evm_transaction_ts_1.UnsignedEvmTransaction({
+                chainId: this.chainId,
+                from: req.from,
+                to: req.to,
+                value: amountMr,
+                data: '0x',
+            });
+        }
+        const data = ERC20_INTERFACE.encodeFunctionData('transfer', [req.to, amountMr]);
+        return new unsigned_evm_transaction_ts_1.UnsignedEvmTransaction({
+            chainId: this.chainId,
+            from: req.from,
+            to: req.tokenIdentifier,
+            value: 0n,
+            data,
+        });
+    }
+    async getChainTipHeight() {
+        try {
+            return await this.getProvider().getBlockNumber();
+        }
+        catch (err) {
+            throw this.rpcError('Failed to read chain tip', err);
+        }
+    }
+    async broadcast(signed, opts) {
+        if (opts && opts.signal !== undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.FeatureNotSupported, `EVM broadcast: signal is not honored in 0.3.0 (silently ignoring would let a caller conclude 'not sent' while the tx still lands). Cancellation returns in 0.3.1.`, { chainId: this.chainId });
+        }
+        let hex;
+        if (typeof signed === 'string') {
+            const stripped = signed.startsWith('0x') ? signed.slice(2) : signed;
+            if (!/^[0-9a-fA-F]+$/.test(stripped) || stripped.length % 2 !== 0 || stripped.length === 0) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `EVM broadcast: signed transaction must be 0x-prefixed hex or Uint8Array (got malformed string of length ${signed.length})`, { chainId: this.chainId });
+            }
+            hex = `0x${stripped}`;
+        }
+        else {
+            if (signed.length === 0) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `EVM broadcast: signed transaction bytes are empty`, { chainId: this.chainId });
+            }
+            hex = (0, ethers_1.hexlify)(signed);
+        }
+        try {
+            const resp = await this.getProvider().broadcastTransaction(hex);
+            return resp.hash;
+        }
+        catch (err) {
+            const rawMsg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+            if (/already[-_ ]?known|known\s+transaction|transaction[-_ ]?already[-_ ]?known|already\s+in\s+(?:the\s+)?(?:mempool|pool)|already[-_ ]?present/.test(rawMsg)) {
+                // Node "already known" is authoritative for THAT node's mempool —
+                // the identical signed bytes are pending or landed. Return the
+                // deterministic hash so the consumer stays on the polling path.
+                // Do NOT gate on a follow-up getTransaction read: load-balanced
+                // providers (Alchemy/Infura/QuickNode round-robin) routinely serve
+                // the confirmation read from a different backend that has not yet
+                // seen the pending tx → null → falsely-terminal BroadcastRejected
+                // → consumer re-signs against a fresh nonce → double-send while
+                // the original is live. If the tx really never lands, the
+                // consumer's getTransactionStatus poll will surface NotFound and
+                // the safe-broadcast rule (re-broadcast same bytes, never re-sign)
+                // still applies. Matches SolanaChain/UtxoChain already-known paths.
+                return (0, ethers_1.keccak256)(hex);
+            }
+            throw this.classifyBroadcastError(err);
+        }
+    }
+    async getPendingNonce(address) {
+        if (!this.validateAddress(address)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM address for getPendingNonce: ${address}`, { chainId: this.chainId, address });
+        }
+        const normalized = this.normalizeAddressOrThrow(address, 'getPendingNonce.address');
+        try {
+            const n = await this.getProvider().getTransactionCount(normalized, 'pending');
+            return BigInt(n);
+        }
+        catch (err) {
+            throw this.rpcError(`Failed to read pending nonce for ${normalized}`, err, { address: normalized });
+        }
+    }
+    async getDelegation(address) {
+        if (!this.supports7702) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.FeatureNotSupported, `EVM chain ${this.name} was not initialized with supports7702: true`, { chainId: this.chainId });
+        }
+        try {
+            (0, ethers_1.getAddress)(address);
+        }
+        catch (err) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM address: ${address}`, { chainId: this.chainId, address }, err instanceof Error ? err : undefined);
+        }
+        let code;
+        try {
+            code = await this.getProvider().getCode(address);
+        }
+        catch (err) {
+            throw this.rpcError(`Failed to read code for ${address}`, err, { address });
+        }
+        if (!code.startsWith('0x'))
+            return null;
+        const stripped = code.slice(2).toLowerCase();
+        if (stripped.length !== 46)
+            return null;
+        if (!stripped.startsWith('ef0100'))
+            return null;
+        return { delegate: (0, ethers_1.getAddress)(`0x${stripped.slice(6)}`) };
+    }
+    async call(req) {
+        if (!this.validateAddress(req.to)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM 'to' address for call: ${req.to}`, { chainId: this.chainId, address: req.to });
+        }
+        if (req.from !== undefined && !this.validateAddress(req.from)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM 'from' address for call: ${req.from}`, { chainId: this.chainId, address: req.from });
+        }
+        if (!/^0x([0-9a-fA-F]{2})*$/.test(req.data)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `EvmCallRequest.data must be 0x-prefixed even-length hex`, { chainId: this.chainId });
+        }
+        const provider = this.getProvider();
+        const tx = {
+            to: this.normalizeAddressOrThrow(req.to, 'call.to'),
+            data: req.data,
+            from: req.from === undefined ? undefined : this.normalizeAddressOrThrow(req.from, 'call.from'),
+            value: req.value,
+        };
+        if (req.estimateGas && req.blockTag !== undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `EvmChain.call: blockTag is not honored when estimateGas: true (ethers v6 eth_estimateGas has no block-tag plumbing). Split the call: use estimateGas without blockTag, or drop estimateGas to run eth_call at the tag.`, { chainId: this.chainId });
+        }
+        try {
+            if (req.estimateGas) {
+                const g = await provider.estimateGas(tx);
+                return { gasEstimate: BigInt(g) };
+            }
+            const result = await provider.call(req.blockTag !== undefined ? { ...tx, blockTag: req.blockTag } : tx);
+            return { result };
+        }
+        catch (err) {
+            const strCode = ethersErrCode(err);
+            const rawData = err.data
+                ?? err.info?.error?.data;
+            const revertData = typeof rawData === 'string' && /^0x[0-9a-fA-F]*$/.test(rawData) ? rawData : undefined;
+            if (strCode === 'CALL_EXCEPTION' || revertData !== undefined) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.SimulationFailed, (0, errors_ts_1.sanitizeMessage)(`eth_${req.estimateGas ? 'estimateGas' : 'call'} on ${req.to} reverted`, this._resolvedRpcUrl), { chainId: this.chainId, revertData }, (0, errors_ts_1.sanitizeCause)(err, this._resolvedRpcUrl));
+            }
+            if (strCode === 'INSUFFICIENT_FUNDS') {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InsufficientFunds, (0, errors_ts_1.sanitizeMessage)(`eth_${req.estimateGas ? 'estimateGas' : 'call'} on ${req.to}: insufficient funds`, this._resolvedRpcUrl), { chainId: this.chainId }, (0, errors_ts_1.sanitizeCause)(err, this._resolvedRpcUrl));
+            }
+            throw this.rpcError(`eth_${req.estimateGas ? 'estimateGas' : 'call'} on ${req.to} failed`, err);
+        }
+    }
+    buildAuthorizationDigest(input) {
+        if (!this.supports7702) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.FeatureNotSupported, `EVM chain ${this.name} was not initialized with supports7702: true`, { chainId: this.chainId });
+        }
+        if (input.chainId !== this.chainId) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `Authorization chainId ${input.chainId} does not match ${this.chainId}. Cross-chain replay guard: chainId=0 wildcards are rejected by default.`, { chainId: this.chainId });
+        }
+        if (input.nonce < 0n) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `Authorization nonce must be >= 0`, { chainId: this.chainId });
+        }
+        let normalizedDelegate;
+        try {
+            normalizedDelegate = (0, ethers_1.getAddress)(input.delegate);
+        }
+        catch (err) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `buildAuthorizationDigest: delegate is not a valid EVM address: ${input.delegate}`, { chainId: this.chainId, address: input.delegate }, err instanceof Error ? err : undefined);
+        }
+        const rlp = (0, ethers_1.encodeRlp)([
+            (0, ethers_1.toBeArray)(BigInt(input.chainId)),
+            normalizedDelegate,
+            (0, ethers_1.toBeArray)(input.nonce),
+        ]);
+        const payload = (0, ethers_1.concat)(['0x05', rlp]);
+        return (0, ethers_1.getBytes)((0, ethers_1.keccak256)(payload));
+    }
+    async createUnsignedTransaction(req) {
+        if (req && req.signal !== undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.FeatureNotSupported, `EVM createUnsignedTransaction: signal is not honored in 0.3.0 (silently ignoring would let a caller conclude 'not built' while the blockhash fetch/build proceeds against stale state). Cancellation returns in 0.3.1.`, { chainId: this.chainId });
+        }
+        if (!req.from) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, 'CreateEvmUnsignedTransactionRequest.from is required', { chainId: this.chainId });
+        }
+        if (!this.validateAddress(req.from)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM 'from' address (fails EIP-55 checksum or byte length): ${req.from}`, { chainId: this.chainId, address: req.from });
+        }
+        if (!req.to) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, 'CreateEvmUnsignedTransactionRequest.to is required', { chainId: this.chainId });
+        }
+        if (!this.validateAddress(req.to)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Invalid EVM 'to' address (fails EIP-55 checksum or byte length): ${req.to}`, { chainId: this.chainId, address: req.to });
+        }
+        if (req.data !== undefined && !/^0x([0-9a-fA-F]{2})*$/.test(req.data)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `CreateEvmUnsignedTransactionRequest.data must be a 0x-prefixed even-length hex string`, { chainId: this.chainId });
+        }
+        if (req.authorizationList !== undefined) {
+            if (!Array.isArray(req.authorizationList) || req.authorizationList.length === 0) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, 'authorizationList must be a non-empty array when provided', { chainId: this.chainId });
+            }
+            if (!this.supports7702) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.FeatureNotSupported, `EVM chain ${this.name} was not initialized with supports7702: true`, { chainId: this.chainId });
+            }
+            for (let i = 0; i < req.authorizationList.length; i++) {
+                const auth = req.authorizationList[i];
+                if (auth.chainId !== this.chainId) {
+                    throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `Authorization[${i}].chainId ${auth.chainId} does not match ${this.chainId}. Cross-chain replay guard: chainId=0 wildcards are rejected by default.`, { chainId: this.chainId });
+                }
+                if (!this.validateAddress(auth.address)) {
+                    throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `Authorization[${i}].address is not a valid EVM address: ${auth.address}`, { chainId: this.chainId, address: auth.address });
+                }
+                if (typeof auth.nonce !== 'bigint' || auth.nonce < 0n) {
+                    throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `Authorization[${i}].nonce must be a non-negative bigint (got ${typeof auth.nonce})`, { chainId: this.chainId });
+                }
+                const sig = auth.signature;
+                if (!sig || typeof sig !== 'object'
+                    || typeof sig.r !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(sig.r)
+                    || typeof sig.s !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(sig.s)
+                    || (sig.yParity !== 0 && sig.yParity !== 1)) {
+                    throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `Authorization[${i}].signature must be { r: 0x + 64-hex, s: 0x + 64-hex, yParity: 0 | 1 }`, { chainId: this.chainId });
+                }
+                const rBig = BigInt(sig.r);
+                const sBig = BigInt(sig.s);
+                if (rBig === 0n || sBig === 0n) {
+                    throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `Authorization[${i}].signature: r and s must both be non-zero`, { chainId: this.chainId });
+                }
+                // EIP-2 low-s canonical form. An authorization with s > secp256k1n/2
+                // is silently rejected by the EVM at execution — tx lands, gas is
+                // spent, no delegation installed. Catch at build time.
+                const SECP256K1_HALF_N = 0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0n;
+                if (sBig > SECP256K1_HALF_N) {
+                    throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `Authorization[${i}].signature.s violates EIP-2 low-s canonical form (s must be <= secp256k1n/2). Non-canonical authorizations are silently skipped by the EVM.`, { chainId: this.chainId });
+                }
+            }
+        }
+        if (!this.supportsEip1559 && (req.maxFeePerGas !== undefined || req.maxPriorityFeePerGas !== undefined)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `EVM chain ${this.name} is legacy (supportsEip1559=false); maxFeePerGas/maxPriorityFeePerGas are not accepted. Use gasPrice via UnsignedEvmTransaction consumers.`, { chainId: this.chainId });
+        }
+        const emittedType = req.authorizationList !== undefined ? 4 : this.supportsEip1559 ? 2 : 0;
+        return new unsigned_evm_transaction_ts_1.UnsignedEvmTransaction({
+            chainId: this.chainId,
+            from: this.normalizeAddressOrThrow(req.from, 'createUnsignedTransaction.from'),
+            to: this.normalizeAddressOrThrow(req.to, 'createUnsignedTransaction.to'),
+            value: req.value ?? 0n,
+            data: req.data ?? '0x',
+            type: emittedType,
+            authorizationList: req.authorizationList,
+            gasLimit: req.gasLimit,
+            nonce: req.nonce,
+            maxFeePerGas: req.maxFeePerGas,
+            maxPriorityFeePerGas: req.maxPriorityFeePerGas,
+        });
+    }
+    classifyBroadcastError(err) {
+        const rpc = this._resolvedRpcUrl;
+        const strCode = ethersErrCode(err);
+        const numCode = errCode(err);
+        const rawMsg = err instanceof Error ? err.message : String(err);
+        const msg = rawMsg.toLowerCase();
+        const safeCause = (0, errors_ts_1.sanitizeCause)(err, rpc);
+        if (strCode === 'NONCE_EXPIRED' || msg.includes('nonce too low') || msg.includes('nonce_too_low') || msg.includes('nonce has already been used')) {
+            return new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.NonceTooLow, (0, errors_ts_1.sanitizeMessage)(`EVM broadcast rejected: nonce too low on ${this.name}`, rpc), { chainId: this.chainId, rpcHost: this.rpcHost() }, safeCause);
+        }
+        if (strCode === 'INSUFFICIENT_FUNDS' || msg.includes('insufficient funds')) {
+            return new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InsufficientFunds, (0, errors_ts_1.sanitizeMessage)(`EVM broadcast rejected: insufficient funds on ${this.name}`, rpc), { chainId: this.chainId, rpcHost: this.rpcHost() }, safeCause);
+        }
+        if (strCode === 'REPLACEMENT_UNDERPRICED' || msg.includes('replacement') || msg.includes('underpriced')) {
+            return new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.BroadcastRejected, (0, errors_ts_1.sanitizeMessage)(`EVM broadcast rejected on ${this.name} (replacement/known-nonce)`, rpc), { chainId: this.chainId, rpcHost: this.rpcHost() }, safeCause);
+        }
+        const rateLimitCodes = new Set([-32005, -32007, -32016, -32029, 429]);
+        if (numCode !== undefined && rateLimitCodes.has(numCode)) {
+            return this.rpcError(`EVM broadcast rate-limited on ${this.name}`, err);
+        }
+        const transportSignals = /econnreset|econnrefused|econnaborted|etimedout|enotfound|network request failed|fetch failed|socket hang up|too\s+many\s+requests|rate.?limit|network error/;
+        const httpStatus = err.info?.status
+            ?? err.status;
+        const isTransportHttp = typeof httpStatus === 'number' && (httpStatus === 429 || httpStatus === 502 || httpStatus === 503 || httpStatus === 504);
+        if (transportSignals.test(msg) || isTransportHttp
+            || strCode === 'NETWORK_ERROR' || strCode === 'SERVER_ERROR' || strCode === 'TIMEOUT') {
+            return this.rpcError(`EVM broadcast transport failure on ${this.name}`, err);
+        }
+        // Default terminal: any unrecognized rejection is a node reject, NOT a
+        // transient transport failure. This matches Solana/UTXO defaults and
+        // prevents a relayer retry-loop from re-broadcasting a permanently-
+        // invalid tx forever.
+        return new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.BroadcastRejected, (0, errors_ts_1.sanitizeMessage)(`EVM broadcast rejected on ${this.name}`, rpc), { chainId: this.chainId, rpcHost: this.rpcHost() }, safeCause);
+    }
+    async getTransactionStatus(txHash, opts) {
+        if (Array.isArray(txHash)) {
+            return runBatchStatus(txHash, (h, batchSignal) => {
+                const composedSignal = opts?.signal
+                    ? anySignal(opts.signal, batchSignal)
+                    : batchSignal;
+                return this.getSingleTransactionStatus(h, { ...opts, signal: composedSignal });
+            });
+        }
+        return this.getSingleTransactionStatus(txHash, opts);
+    }
+    async getSingleTransactionStatus(txHash, opts) {
+        if (opts?.confirmations !== undefined && opts.confirmations > 1 && !opts.wait) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `getTransactionStatus: confirmations > 1 requires wait: true (a single status read cannot enforce block depth)`, { chainId: this.chainId, txHash });
+        }
+        if (!opts?.wait)
+            return this.getTransactionStatusOnce(txHash);
+        if (opts.signal?.aborted) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `getTransactionStatus aborted before first poll`, { chainId: this.chainId, txHash });
+        }
+        if (opts.timeoutMs === undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `getTransactionStatus: wait: true requires an explicit timeoutMs. Unbounded polling would pin an RPC worker + connection forever if the tx is dropped.`, { chainId: this.chainId, txHash });
+        }
+        if (opts.timeoutMs < 0) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `getTransactionStatus: timeoutMs must be >= 0`, { chainId: this.chainId, txHash });
+        }
+        const deadline = Date.now() + opts.timeoutMs;
+        const pollMs = Math.max(500, this.blockTimeSeconds * 1000);
+        const minConfirmations = Math.max(1, opts.confirmations ?? 1);
+        let last;
+        while (true) {
+            last = await this.getTransactionStatusOnce(txHash);
+            if (last.status === 'Success' || last.status === 'Failed') {
+                if (minConfirmations <= 1)
+                    return last;
+                let tip;
+                try {
+                    tip = await this.getProvider().getBlockNumber();
+                }
+                catch (err) {
+                    throw this.rpcError(`Failed to read chain tip for confirmations check`, err, { txHash });
+                }
+                const depth = last.blockNumber === null ? 0 : tip - last.blockNumber + 1;
+                if (depth >= minConfirmations)
+                    return last;
+                if (Date.now() >= deadline) {
+                    throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, `getTransactionStatus timed out after ${opts.timeoutMs}ms with only ${depth} confirmation(s); required ${minConfirmations}. Consumer must NOT credit as final.`, { chainId: this.chainId, txHash });
+                }
+            }
+            else if (Date.now() >= deadline) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, `getTransactionStatus timed out after ${opts.timeoutMs}ms; last observed status was ${last.status}. Consumer must NOT credit as final AND must NOT re-sign — the tx may still land. Re-broadcast the same signed bytes or continue polling with the same txHash.`, { chainId: this.chainId, txHash });
+            }
+            await interruptibleSleep(pollMs, opts.signal);
+            if (opts.signal?.aborted) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `getTransactionStatus aborted mid-poll`, { chainId: this.chainId, txHash });
+            }
+        }
+    }
+    async getTransactionStatusOnce(txHash) {
+        const provider = this.getProvider();
+        let tx = null;
+        let receipt = null;
+        try {
+            [tx, receipt] = await Promise.all([
+                provider.getTransaction(txHash),
+                provider.getTransactionReceipt(txHash),
+            ]);
+        }
+        catch (err) {
+            throw this.rpcError(`Failed to read tx ${txHash}`, err, { txHash });
+        }
+        if (tx === null && receipt === null)
+            return evm_transaction_status_ts_1.EvmTransactionStatus.notFound(this.chainId, null);
+        if (receipt === null)
+            return evm_transaction_status_ts_1.EvmTransactionStatus.pending(this.chainId);
+        // Receipt exists but the tx body doesn't — real race on load-balanced/
+        // pruned RPC endpoints where getTransactionReceipt succeeds while
+        // getTransactionByHash returns null. `tx.value` and `tx.to` are load-
+        // bearing for the native transfer legs of decodeBalanceChanges; falling
+        // back to `?? 0n` / `?? null` would emit a Success with a silently
+        // truncated balanceChanges map (recipient row missing entirely,
+        // sender debit off by the transfer value). Python parity: omnichain-py's
+        // impl/evm/base.py accesses `tx.value` directly and blows up on a
+        // missing body. TS returns Pending — receipt-only is transient node
+        // state; the consumer's next poll will land on a node with the full tx.
+        if (tx === null)
+            return evm_transaction_status_ts_1.EvmTransactionStatus.pending(this.chainId);
+        const succeeded = receipt.status === 1;
+        // Parallelize the two independent post-receipt lookups: getBlock (for
+        // inclusionAt) and the OP-stack raw-receipt fetch (for l1Fee). Both
+        // depend only on receipt.blockNumber / txHash, not on each other.
+        const [inclusionAt, l1Fee] = await Promise.all([
+            (async () => {
+                try {
+                    const block = await provider.getBlock(receipt.blockNumber);
+                    if (block?.timestamp !== undefined) {
+                        return new Date(Number(block.timestamp) * 1000);
+                    }
+                    return null;
+                }
+                catch {
+                    // leave null — a 1970-01-01 sentinel would silently pass
+                    // through consumer SLA/age math as a real inclusion time.
+                    return null;
+                }
+            })(),
+            (async () => {
+                // OP-stack rollups charge an L1 data fee (`l1Fee` on the raw
+                // receipt). ethers v6 strips it in its parsed TransactionReceipt
+                // shape, so a second raw fetch is required. Gated on `hasL1Fee`.
+                // Return undefined for "provider did not surface it" (either
+                // hasL1Fee=false or the raw send failed/omitted the field) —
+                // tracked separately from "l1Fee is genuinely 0n" so
+                // fees.l1FeeWei reflects presence, not value.
+                if (!this.hasL1Fee)
+                    return undefined;
+                try {
+                    const raw = (await provider.send('eth_getTransactionReceipt', [txHash]));
+                    const rawL1 = raw?.l1Fee;
+                    if (rawL1 === undefined || rawL1 === null)
+                        return undefined;
+                    if (typeof rawL1 === 'bigint')
+                        return rawL1;
+                    if (typeof rawL1 === 'number')
+                        return BigInt(rawL1);
+                    if (typeof rawL1 === 'string' && rawL1.length > 0)
+                        return BigInt(rawL1);
+                    return undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })(),
+        ]);
+        // gasLimit: the sender-set limit from tx.gasLimit. `null` when the tx
+        // body isn't available (pruned/receipt-only) — falling back to
+        // receipt.gasUsed here would fabricate a "100% utilization" that
+        // consumers can't distinguish from a real observation.
+        const fees = new evm_transaction_status_ts_1.EvmTransactionGasFees({
+            gasLimit: tx?.gasLimit ?? null,
+            gasLimitUsed: receipt.gasUsed,
+            effectiveGasPrice: receipt.gasPrice,
+            gasPrice: tx?.gasPrice ?? undefined,
+            maxFeePerGas: tx?.maxFeePerGas ?? undefined,
+            maxPriorityFeePerGas: tx?.maxPriorityFeePerGas ?? undefined,
+            l1FeeWei: l1Fee,
+        });
+        if (!succeeded) {
+            const errorInfo = await extractRevertInfo(provider, tx, receipt);
+            return evm_transaction_status_ts_1.EvmTransactionStatus.failed({
+                chainId: this.chainId,
+                inclusionAt,
+                error: errorInfo,
+                fees,
+                blockNumber: receipt.blockNumber,
+            });
+        }
+        // Only allocated on the Success path — failed txs carry logs: null.
+        const logs = (receipt.logs ?? []).map((l) => new evm_transaction_status_ts_1.EvmParsedTransactionLog(l.address, [...l.topics], l.data));
+        const nativeValue = tx?.value ?? 0n;
+        let balanceChanges;
+        try {
+            balanceChanges = await this.decodeBalanceChanges({
+                from: tx ? tx.from : (receipt.from ?? ''),
+                to: tx?.to ?? receipt.to ?? null,
+                value: nativeValue,
+                gasCost: fees.totalNativeDebitWei,
+                receipt,
+            });
+        }
+        catch (err) {
+            if (err instanceof errors_ts_1.ChainError)
+                throw err;
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.TransactionDecodeFailed, `Failed to decode receipt logs for tx ${txHash}`, { chainId: this.chainId, txHash, rpcHost: this.rpcHost() }, err);
+        }
+        return evm_transaction_status_ts_1.EvmTransactionStatus.successful({
+            chainId: this.chainId,
+            inclusionAt,
+            balanceChanges,
+            logs,
+            fees,
+            blockNumber: receipt.blockNumber,
+        });
+    }
+    async decodeBalanceChanges(args) {
+        const { from, to, value, gasCost, receipt } = args;
+        if (!receipt || !Array.isArray(receipt.logs)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.TransactionDecodeFailed, 'Receipt is missing required fields', { chainId: this.chainId, txHash: receipt?.hash, rpcHost: this.rpcHost() });
+        }
+        const rawChanges = new Map();
+        const fromAddr = (from ?? '').toLowerCase();
+        const toAddr = to ? to.toLowerCase() : null;
+        // Sender's native debit = value + gasCost (matches Python
+        // impl/evm/base.py:_get_balance_changes fee-inclusive semantics).
+        // Credit toAddr whenever value>0 — for self-transfers (from===to) the
+        // per-(wallet,token) netting in upsert cancels the +value against the
+        // -value component of the debit, leaving the -gasCost we actually want.
+        if (fromAddr) {
+            addRaw(rawChanges, fromAddr, '', -(value + gasCost));
+        }
+        if (value > 0n && toAddr) {
+            addRaw(rawChanges, toAddr, '', value);
+        }
+        const tokenContracts = new Set();
+        const transferLogs = [];
+        for (const log of receipt.logs) {
+            if (log.topics.length !== 3)
+                continue;
+            if (log.topics[0].toLowerCase() !== ERC20_TRANSFER_TOPIC)
+                continue;
+            const contractAddr = log.address.toLowerCase();
+            const logFrom = `0x${log.topics[1].slice(26)}`.toLowerCase();
+            const logTo = `0x${log.topics[2].slice(26)}`.toLowerCase();
+            let amount;
+            try {
+                amount = BigInt(log.data);
+            }
+            catch {
+                continue;
+            }
+            tokenContracts.add(contractAddr);
+            transferLogs.push({ contract: contractAddr, from: logFrom, to: logTo, amount });
+        }
+        const tokensByContract = new Map();
+        const resolved = await Promise.all([...tokenContracts].map((addr) => this.resolveErc20TokenDefensive(addr).then((t) => ({ addr, token: t }))));
+        for (const { addr, token } of resolved)
+            tokensByContract.set(addr, token);
+        for (const t of transferLogs) {
+            // Symmetric with the native path: always add both legs. Self-transfer
+            // nets to zero at the per-(wallet, contract) map level and is dropped
+            // by the `delta === 0n` filter below — the explicit gate here would
+            // over-suppress the credit if a future decoder gained non-cancelling
+            // side effects.
+            addRaw(rawChanges, t.from, t.contract, -t.amount);
+            addRaw(rawChanges, t.to, t.contract, t.amount);
+        }
+        const result = new Map();
+        for (const [wallet, perTokenAddr] of rawChanges) {
+            for (const [tokenAddr, delta] of perTokenAddr) {
+                if (delta === 0n)
+                    continue;
+                const token = tokenAddr === '' ? this._nativeToken : tokensByContract.get(tokenAddr);
+                if (!token)
+                    continue;
+                transaction_status_ts_1.AssetBalanceChange.upsert(result, wallet, token, transaction_status_ts_1.AssetBalanceChange.fromMr(delta, token.decimals));
+            }
+        }
+        return result;
+    }
+    async resolveErc20TokenDefensive(contractAddress) {
+        const checksum = (() => {
+            try {
+                return new evm_address_ts_1.EvmAddress(contractAddress).toChecksum();
+            }
+            catch {
+                return contractAddress;
+            }
+        })();
+        const placeholder = () => new evm_token_ts_1.EvmToken(this.chainId, `UNKNOWN_${checksum.slice(2, 8)}`, checksum, 0);
+        let provider;
+        try {
+            provider = this.getProvider();
+        }
+        catch {
+            return placeholder();
+        }
+        const contract = new ethers_1.Contract(contractAddress, ERC20_ABI, provider);
+        try {
+            const [symbol, decimals] = await Promise.all([
+                contract.symbol(),
+                contract.decimals(),
+            ]);
+            return new evm_token_ts_1.EvmToken(this.chainId, symbol, checksum, Number(decimals));
+        }
+        catch {
+            return placeholder();
+        }
+    }
+    /**
+     * STRICT decimals resolver for the transfer builder — throws
+     * `ChainError(RpcError)` on any failure to reach the contract.
+     * Used exclusively when converting `amountHr: Decimal` →
+     * `amountMr: bigint`, where a defensive fallback to `decimals=0`
+     * would silently sign a transaction for a wildly wrong amount
+     * (e.g. `1.5 USDC` → `1n` minor units instead of `1_500_000n`).
+     * The receipt-decoder still uses the defensive variant, since a
+     * placeholder token there is a display concern, not a money one.
+     */
+    async resolveErc20DecimalsStrict(contractAddress) {
+        const provider = this.getProvider();
+        const contract = new ethers_1.Contract(contractAddress, ERC20_ABI, provider);
+        try {
+            const decimals = (await contract.decimals());
+            return Number(decimals);
+        }
+        catch (err) {
+            throw this.rpcError(`Failed to read ERC-20 decimals for ${contractAddress}`, err);
+        }
+    }
+    rpcError(message, cause, extra = {}) {
+        const sanitizedMessage = (0, errors_ts_1.sanitizeMessage)(`${message}: ${stringifyErr(cause)}`, this._resolvedRpcUrl);
+        return new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, sanitizedMessage, { chainId: this.chainId, rpcHost: this.rpcHost(), ...extra }, (0, errors_ts_1.sanitizeCause)(cause, this._resolvedRpcUrl));
+    }
+}
+exports.EvmChain = EvmChain;
+function addRaw(container, wallet, tokenAddr, delta) {
+    let perToken = container.get(wallet);
+    if (!perToken) {
+        perToken = new Map();
+        container.set(wallet, perToken);
+    }
+    perToken.set(tokenAddr, (perToken.get(tokenAddr) ?? 0n) + delta);
+}
+const ERROR_STRING_SELECTOR = '0x08c379a0';
+const PANIC_UINT256_SELECTOR = '0x4e487b71';
+const ABI_CODER = ethers_1.AbiCoder.defaultAbiCoder();
+function decodeRevertData(data) {
+    if (typeof data !== 'string' || data.length < 10)
+        return undefined;
+    const selector = data.slice(0, 10).toLowerCase();
+    const payload = '0x' + data.slice(10);
+    if (selector === ERROR_STRING_SELECTOR) {
+        try {
+            const reason = ABI_CODER.decode(['string'], payload)[0];
+            return typeof reason === 'string' ? reason : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (selector === PANIC_UINT256_SELECTOR) {
+        try {
+            const code = ABI_CODER.decode(['uint256'], payload)[0];
+            return typeof code === 'bigint' ? `Panic(0x${code.toString(16)})` : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+async function extractRevertInfo(provider, tx, receipt) {
+    if (!tx)
+        return { code: 'REVERTED' };
+    try {
+        await provider.call({
+            from: tx.from,
+            to: tx.to ?? undefined,
+            data: tx.data,
+            value: tx.value,
+            blockTag: receipt.blockNumber,
+        });
+        return { code: 'REVERTED' };
+    }
+    catch (err) {
+        const data = err?.data ??
+            err?.info?.error?.data;
+        const reason = typeof data === 'string' ? decodeRevertData(data) : undefined;
+        return reason !== undefined ? { code: 'REVERTED', reason } : { code: 'REVERTED' };
+    }
+}
+function stringifyErr(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+const BATCH_STATUS_CONCURRENCY = 8;
+async function runBatchStatus(items, fetchOne) {
+    const results = new Array(items.length);
+    const ac = new AbortController();
+    let cursor = 0;
+    const workers = [];
+    const spawn = async () => {
+        while (!ac.signal.aborted) {
+            const idx = cursor++;
+            if (idx >= items.length)
+                return;
+            try {
+                results[idx] = await fetchOne(items[idx], ac.signal);
+            }
+            catch (err) {
+                ac.abort();
+                throw err;
+            }
+        }
+    };
+    const workerCount = Math.min(BATCH_STATUS_CONCURRENCY, items.length);
+    for (let i = 0; i < workerCount; i++)
+        workers.push(spawn());
+    await Promise.all(workers);
+    return results;
+}
+function anySignal(a, b) {
+    if (typeof AbortSignal.any === 'function')
+        return AbortSignal.any([a, b]);
+    const ac = new AbortController();
+    const onAbort = () => ac.abort();
+    if (a.aborted || b.aborted)
+        ac.abort();
+    else {
+        a.addEventListener('abort', onAbort, { once: true });
+        b.addEventListener('abort', onAbort, { once: true });
+    }
+    return ac.signal;
+}
+async function interruptibleSleep(ms, signal) {
+    if (signal?.aborted)
+        return;
+    await new Promise((resolve) => {
+        const t = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            resolve();
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function errCode(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const e = err;
+    const candidates = [
+        typeof e.code === 'number' ? e.code : undefined,
+        e.error?.code,
+        e.info?.error?.code,
+        typeof e.code === 'string' && /^-?\d+$/.test(e.code) ? e.code : undefined,
+    ];
+    for (const raw of candidates) {
+        if (typeof raw === 'number')
+            return raw;
+        if (typeof raw === 'string' && /^-?\d+$/.test(raw))
+            return Number(raw);
+    }
+    return undefined;
+}
+function ethersErrCode(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const e = err;
+    return typeof e.code === 'string' ? e.code : undefined;
+}
+function envCandidatesFor(name, chainId) {
+    const normalized = name.replace(/ /g, '_').toUpperCase() + '_RPC_URL';
+    return [normalized, `EVM_${chainId}_RPC_URL`];
+}
+//# sourceMappingURL=evm_chain.js.map