web3-mev-error-decoder 0.0.0-stage → 0.1.0

package/dist/provider/fallback.d.ts

@@ -0,0 +1,37 @@
+import { JsonRpcApiProvider, Network, type JsonRpcError, type JsonRpcPayload, type JsonRpcResult, type Networkish } from 'ethers';
+export interface FallbackProviderEntry {
+    provider: JsonRpcApiProvider;
+    /** Per-call timeout in ms. Default: 10_000. */
+    timeout?: number;
+    /** Retries against the same provider before moving to the next. Default: 0. */
+    retries?: number;
+}
+export interface SimpleFallbackProviderOptions {
+    entries: FallbackProviderEntry[];
+    network?: Networkish;
+    /**
+     * When true, `eth_sendRawTransaction` is broadcast to every provider and the
+     * first success wins. Default: false.
+     */
+    broadcastToAll?: boolean;
+    /** Default per-call timeout. Default: 10_000. */
+    defaultTimeout?: number;
+}
+/**
+ * Minimal RPC fallback provider for ethers v6.
+ *
+ * Requests are tried against providers in order, preferring the last provider
+ * that worked; each attempt is bounded by a timeout. Blockchain-level errors
+ * (INSUFFICIENT_FUNDS, CALL_EXCEPTION, ...) are thrown immediately instead of
+ * being retried against the next provider.
+ */
+export declare class SimpleFallbackProvider extends JsonRpcApiProvider {
+    #private;
+    readonly entries: FallbackProviderEntry[];
+    constructor(options: SimpleFallbackProviderOptions);
+    /** Index of the provider currently preferred (last known-good). */
+    get preferredIndex(): number;
+    _detectNetwork(): Promise<Network>;
+    _send(payload: JsonRpcPayload | Array<JsonRpcPayload>): Promise<Array<JsonRpcResult | JsonRpcError>>;
+}
+export declare function isBlockchainLevelError(error: unknown): boolean;

package/dist/provider/fallback.js

@@ -0,0 +1,120 @@
+import { JsonRpcApiProvider, Network, } from 'ethers';
+import { withTimeout, getErrorMessage } from '../utils.js';
+/**
+ * Minimal RPC fallback provider for ethers v6.
+ *
+ * Requests are tried against providers in order, preferring the last provider
+ * that worked; each attempt is bounded by a timeout. Blockchain-level errors
+ * (INSUFFICIENT_FUNDS, CALL_EXCEPTION, ...) are thrown immediately instead of
+ * being retried against the next provider.
+ */
+export class SimpleFallbackProvider extends JsonRpcApiProvider {
+    entries;
+    #preferred = 0;
+    #broadcastToAll;
+    #defaultTimeout;
+    constructor(options) {
+        const { entries, network } = options;
+        if (!entries.length) {
+            throw new Error('SimpleFallbackProvider: at least one provider is required');
+        }
+        super(network, network ? { staticNetwork: Network.from(network) } : { batchMaxCount: 1, batchStallTime: 0 });
+        this.entries = entries;
+        this.#broadcastToAll = options.broadcastToAll ?? false;
+        this.#defaultTimeout = options.defaultTimeout ?? 10_000;
+        this._start();
+    }
+    /** Index of the provider currently preferred (last known-good). */
+    get preferredIndex() {
+        return this.#preferred;
+    }
+    async _detectNetwork() {
+        for (const entry of this.entries) {
+            try {
+                return await entry.provider.getNetwork();
+            }
+            catch {
+                // try the next provider
+            }
+        }
+        throw new Error('SimpleFallbackProvider: could not detect network on any provider');
+    }
+    async _send(payload) {
+        const payloads = Array.isArray(payload) ? payload : [payload];
+        return Promise.all(payloads.map((p) => this.#sendSingle(p)));
+    }
+    async #sendSingle(payload) {
+        if (this.#broadcastToAll && payload.method === 'eth_sendRawTransaction') {
+            return this.#broadcast(payload);
+        }
+        const ordered = this.#ordered();
+        let lastError;
+        for (const entry of ordered) {
+            const timeout = entry.timeout ?? this.#defaultTimeout;
+            const retries = entry.retries ?? 0;
+            for (let attempt = 0; attempt <= retries; attempt++) {
+                try {
+                    const result = await withTimeout(entry.provider.send(payload.method, payload.params), timeout);
+                    this.#preferred = this.entries.indexOf(entry);
+                    return { jsonrpc: '2.0', id: payload.id, result };
+                }
+                catch (e) {
+                    lastError = e;
+                    if (isBlockchainLevelError(e))
+                        break;
+                }
+            }
+        }
+        return {
+            jsonrpc: '2.0',
+            id: payload.id,
+            error: {
+                code: lastError?.code ?? -32000,
+                message: `SimpleFallbackProvider: all providers failed: ${getErrorMessage(lastError)}`,
+            },
+        };
+    }
+    async #broadcast(payload) {
+        const params = payload.params;
+        const results = await Promise.allSettled(this.entries.map((e) => withTimeout(e.provider.send(payload.method, params), e.timeout ?? this.#defaultTimeout)));
+        const firstOk = results.find((r) => r.status === 'fulfilled');
+        if (firstOk) {
+            return { jsonrpc: '2.0', id: payload.id, result: firstOk.value };
+        }
+        const firstRejected = results.find((r) => r.status === 'rejected');
+        const err = firstRejected?.reason;
+        return {
+            jsonrpc: '2.0',
+            id: payload.id,
+            error: {
+                code: err?.code ?? -32000,
+                message: getErrorMessage(err),
+            },
+        };
+    }
+    #ordered() {
+        const { entries } = this;
+        return [...entries.slice(this.#preferred), ...entries.slice(0, this.#preferred)];
+    }
+}
+/**
+ * Errors caused by the transaction itself (not by the RPC) should stop the
+ * failover loop — the next RPC will fail the same way.
+ */
+const BLOCKCHAIN_ERROR_PATTERNS = [
+    'insufficient funds',
+    'nonce',
+    'replacement transaction underpriced',
+    'already known',
+    'execution reverted',
+    'out of gas',
+    'intrinsic gas',
+    'invalid sender',
+    'max fee per gas',
+    'gas price below',
+];
+export function isBlockchainLevelError(error) {
+    const message = getErrorMessage(error).toLowerCase();
+    return BLOCKCHAIN_ERROR_PATTERNS.some((pattern) => message.includes(pattern));
+}
+//# sourceMappingURL=fallback.js.map

package/dist/provider/fallback.js.map

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

package/dist/provider/index.d.ts

@@ -0,0 +1,7 @@
+export { SimpleFallbackProvider, isBlockchainLevelError } from './fallback.js';
+export type { FallbackProviderEntry, SimpleFallbackProviderOptions } from './fallback.js';
+export { FallbackProvider } from './fallback-full.js';
+export { FallbackProviderError, DEFAULT_RETRIES, DEFAULT_TIMEOUT, RETRY_DELAY, ALWAYS_SUPPORTED_METHODS, DEFAULT_FALLBACK_OPTIONS, isBlockchainError, isAlreadyKnownError, providerSupportsMethod, filterProvidersByMethod, filterValidProviders, getBlockNumber, getBlockNumberWithTimeout, getBlockNumbersAndMedian, } from './fallback-full.js';
+export type { ProviderConfig, LoggingOptions, FallbackProviderOptions, } from './fallback-full.js';
+export { createViemFallbackTransport, createViemFallbackClient, probeRpcEndpoints, } from './viem-fallback.js';
+export type { RpcProbeResult, ViemFallbackTransportOptions, ViemFallbackClientOptions, } from './viem-fallback.js';

package/dist/provider/index.js

@@ -0,0 +1,5 @@
+export { SimpleFallbackProvider, isBlockchainLevelError } from './fallback.js';
+export { FallbackProvider } from './fallback-full.js';
+export { FallbackProviderError, DEFAULT_RETRIES, DEFAULT_TIMEOUT, RETRY_DELAY, ALWAYS_SUPPORTED_METHODS, DEFAULT_FALLBACK_OPTIONS, isBlockchainError, isAlreadyKnownError, providerSupportsMethod, filterProvidersByMethod, filterValidProviders, getBlockNumber, getBlockNumberWithTimeout, getBlockNumbersAndMedian, } from './fallback-full.js';
+export { createViemFallbackTransport, createViemFallbackClient, probeRpcEndpoints, } from './viem-fallback.js';
+//# sourceMappingURL=index.js.map

package/dist/provider/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAG/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,WAAW,EACX,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/provider/viem-fallback.d.ts

@@ -0,0 +1,47 @@
+import { type Chain, type PublicClient, type Transport } from 'viem';
+export interface RpcProbeResult {
+    url: string;
+    ok: boolean;
+    chainId?: number;
+    blockNumber?: bigint;
+    latencyMs?: number;
+    error?: string;
+}
+/**
+ * Probe JSON-RPC endpoints: reachability, chain id, block number and latency.
+ * Results are sorted best-first (matching chain id, then lowest latency);
+ * failed probes go last. Useful to order the transports handed to
+ * `createViemFallbackTransport`.
+ */
+export declare function probeRpcEndpoints(urls: readonly string[], opts?: {
+    expectedChainId?: number;
+    timeout?: number;
+}): Promise<RpcProbeResult[]>;
+export interface ViemFallbackTransportOptions {
+    /** RPC URLs to fail over between. Order matters: first is preferred. */
+    urls: readonly string[];
+    /** Optional WebSocket URLs placed in front of the HTTP transports. */
+    webSocketUrls?: readonly string[];
+    /** Per-request timeout in ms. Default: 10_000. */
+    timeout?: number;
+    /** Retries per transport. Default: 2. */
+    retryCount?: number;
+    /** Enable viem's automatic ranking by latency. Default: true. */
+    rank?: boolean;
+    /** Custom webSocket/http factory override (testing). */
+    transportFactory?: (url: string, kind: 'http' | 'ws') => Transport;
+}
+/**
+ * Build a viem `fallback` transport over a list of RPC URLs, with per-URL
+ * timeout/retry configuration. This is the viem counterpart of
+ * `FallbackProvider` / `SimpleFallbackProvider` for ethers.
+ */
+export declare function createViemFallbackTransport(opts: ViemFallbackTransportOptions): Transport;
+export interface ViemFallbackClientOptions extends ViemFallbackTransportOptions {
+    /** Target chain (e.g. mainnet from 'viem/chains'). Required unless you pass `transport` yourself. */
+    chain?: Chain;
+    /** Polling interval for watch utilities, in ms. */
+    pollingInterval?: number;
+}
+/** Convenience builder: a viem PublicClient backed by a fallback transport. */
+export declare function createViemFallbackClient(opts: ViemFallbackClientOptions): PublicClient;

package/dist/provider/viem-fallback.js

@@ -0,0 +1,69 @@
+import { createPublicClient, fallback, http, webSocket } from 'viem';
+/**
+ * Probe JSON-RPC endpoints: reachability, chain id, block number and latency.
+ * Results are sorted best-first (matching chain id, then lowest latency);
+ * failed probes go last. Useful to order the transports handed to
+ * `createViemFallbackTransport`.
+ */
+export async function probeRpcEndpoints(urls, opts = {}) {
+    const timeout = opts.timeout ?? 5_000;
+    const results = await Promise.all(urls.map(async (url) => {
+        const started = Date.now();
+        try {
+            const client = createPublicClient({ transport: http(url, { timeout, retryCount: 0 }) });
+            const [chainId, blockNumber] = await Promise.all([client.getChainId(), client.getBlockNumber()]);
+            return {
+                url,
+                ok: true,
+                chainId,
+                blockNumber,
+                latencyMs: Date.now() - started,
+                error: opts.expectedChainId != null && chainId !== opts.expectedChainId ? 'chain id mismatch' : undefined,
+            };
+        }
+        catch (e) {
+            return { url, ok: false, error: e?.message ?? String(e) };
+        }
+    }));
+    return results.sort((a, b) => {
+        if (a.ok !== b.ok)
+            return a.ok ? -1 : 1;
+        const aMatch = a.error === undefined;
+        const bMatch = b.error === undefined;
+        if (aMatch !== bMatch)
+            return aMatch ? -1 : 1;
+        return (a.latencyMs ?? Infinity) - (b.latencyMs ?? Infinity);
+    });
+}
+/**
+ * Build a viem `fallback` transport over a list of RPC URLs, with per-URL
+ * timeout/retry configuration. This is the viem counterpart of
+ * `FallbackProvider` / `SimpleFallbackProvider` for ethers.
+ */
+export function createViemFallbackTransport(opts) {
+    const { urls, webSocketUrls = [], timeout = 10_000, retryCount = 2, rank = true, transportFactory, } = opts;
+    if (urls.length === 0 && webSocketUrls.length === 0) {
+        throw new Error('createViemFallbackTransport: at least one URL is required');
+    }
+    const make = transportFactory ?? ((url, kind) => kind === 'ws'
+        ? webSocket(url, { timeout, retryCount })
+        : http(url, { timeout, retryCount }));
+    const transports = [
+        ...webSocketUrls.map((url) => make(url, 'ws')),
+        ...urls.map((url) => make(url, 'http')),
+    ];
+    return fallback(transports, {
+        rank,
+        retryCount,
+    });
+}
+/** Convenience builder: a viem PublicClient backed by a fallback transport. */
+export function createViemFallbackClient(opts) {
+    const { chain, pollingInterval, ...transportOpts } = opts;
+    return createPublicClient({
+        chain,
+        transport: createViemFallbackTransport(transportOpts),
+        pollingInterval,
+    });
+}
+//# sourceMappingURL=viem-fallback.js.map

package/dist/provider/viem-fallback.js.map

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

package/dist/transaction/ethers.d.ts

@@ -0,0 +1,27 @@
+import { type Provider, type Signer, type TransactionReceipt, type TransactionRequest, type TransactionResponse } from 'ethers';
+import type { AbiLike } from '../types.js';
+import type { DecodedError } from '../error-decoder/types.js';
+import { type DecodedLog, type WaitForTransactionOptions, type WaitForTransactionResult } from './types.js';
+/**
+ * Wait for a transaction with timeout, confirmation count, replacement
+ * notification, decoded logs, and automatic revert decoding.
+ */
+export declare function waitForTransaction(opts: WaitForTransactionOptions & {
+    provider: Provider;
+}): Promise<WaitForTransactionResult>;
+/** Send a transaction via a signer, then wait with full decode/timeout handling. */
+export declare function sendAndConfirm(signer: Signer, tx: TransactionRequest, opts?: {
+    confirmations?: number;
+    timeout?: number;
+    abis?: Record<string, AbiLike>;
+    throwOnRevert?: boolean;
+}): Promise<WaitForTransactionResult & {
+    response: TransactionResponse;
+}>;
+/**
+ * Recover + decode the revert reason of a (possibly mined) reverted transaction
+ * by replaying it via `eth_call`.
+ */
+export declare function getRevertReason(provider: Provider, txHash: string, abis?: ReadonlyArray<AbiLike>): Promise<DecodedError>;
+/** Decode logs of a receipt using the provided ABI map. */
+export declare function decodeReceiptLogs(receipt: TransactionReceipt, abis?: Record<string, AbiLike>): DecodedLog[];

package/dist/transaction/ethers.js

@@ -0,0 +1,97 @@
+import { isError, } from 'ethers';
+import { callRequestFromTx, extractRevertData, toInterface } from '../utils.js';
+import { ErrorDecoder } from '../error-decoder/index.js';
+import { TransactionRevertedError, TransactionTimeoutError, } from './types.js';
+/**
+ * Wait for a transaction with timeout, confirmation count, replacement
+ * notification, decoded logs, and automatic revert decoding.
+ */
+export async function waitForTransaction(opts) {
+    const { provider, hash, confirmations = 1, timeout = 120_000, abis, onReplaced, throwOnRevert = true, } = opts;
+    let receipt;
+    try {
+        receipt = await provider.waitForTransaction(hash, confirmations, timeout);
+    }
+    catch (e) {
+        if (isError(e, 'TRANSACTION_REPLACED')) {
+            onReplaced?.({
+                reason: e.reason,
+                replacement: e.replacement ?? null,
+                receipt: e.receipt ?? null,
+            });
+        }
+        throw e;
+    }
+    if (!receipt) {
+        throw new TransactionTimeoutError(hash, timeout);
+    }
+    if (receipt.status === 0) {
+        const decoded = await getRevertReason(provider, hash, abis ? Object.values(abis) : undefined);
+        if (throwOnRevert) {
+            throw new TransactionRevertedError(receipt, decoded, hash);
+        }
+        return { receipt, logs: [], decodedError: decoded };
+    }
+    return { receipt, logs: decodeReceiptLogs(receipt, abis) };
+}
+/** Send a transaction via a signer, then wait with full decode/timeout handling. */
+export async function sendAndConfirm(signer, tx, opts = {}) {
+    const response = await signer.sendTransaction(tx);
+    const provider = response.provider ?? signer.provider;
+    if (!provider)
+        throw new Error('Signer has no provider to wait on');
+    const result = await waitForTransaction({
+        provider,
+        hash: response.hash,
+        confirmations: opts.confirmations,
+        timeout: opts.timeout,
+        abis: opts.abis,
+        throwOnRevert: opts.throwOnRevert,
+    });
+    return { ...result, response };
+}
+/**
+ * Recover + decode the revert reason of a (possibly mined) reverted transaction
+ * by replaying it via `eth_call`.
+ */
+export async function getRevertReason(provider, txHash, abis) {
+    const receipt = await provider.getTransactionReceipt(txHash);
+    if (receipt && receipt.status === 1) {
+        throw new Error('Transaction succeeded — there is no revert reason');
+    }
+    const tx = await provider.getTransaction(txHash);
+    if (!tx) {
+        throw new Error(`Transaction ${txHash} not found`);
+    }
+    let data;
+    let callError;
+    try {
+        await provider.call(callRequestFromTx(tx));
+        // Call succeeded — state has moved on; cannot reproduce the revert.
+    }
+    catch (e) {
+        data = extractRevertData(e);
+        callError = e;
+    }
+    return new ErrorDecoder(abis).decodeData(data, callError);
+}
+/** Decode logs of a receipt using the provided ABI map. */
+export function decodeReceiptLogs(receipt, abis) {
+    if (!abis)
+        return [];
+    const out = [];
+    for (const log of receipt.logs) {
+        const abi = abis[log.address.toLowerCase()];
+        if (!abi)
+            continue;
+        try {
+            const parsed = toInterface(abi).parseLog({ topics: [...log.topics], data: log.data });
+            out.push({ log, name: parsed?.name ?? null, args: parsed?.args?.toArray() ?? [] });
+        }
+        catch {
+            out.push({ log, name: null });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=ethers.js.map

package/dist/transaction/ethers.js.map

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

package/dist/transaction/index.d.ts

@@ -0,0 +1,21 @@
+import type { PublicClient } from 'viem';
+import type { Provider } from 'ethers';
+import { waitForTransaction as waitForTransactionEth, sendAndConfirm, getRevertReason, decodeReceiptLogs } from './ethers.js';
+import { waitForTransactionViem, sendAndConfirmViem, decodeViemReceiptLogs } from './viem.js';
+import { TransactionRevertedError, TransactionTimeoutError, type DecodedLog, type ReplacedInfo, type WaitForTransactionOptions, type WaitForTransactionResult } from './types.js';
+export interface UnifiedWaitOptions {
+    /** ethers v6 provider. */
+    provider?: Provider;
+    /** viem public client. Takes precedence if both are given. */
+    client?: PublicClient;
+    hash: string;
+    confirmations?: number;
+    timeout?: number;
+    abis?: Record<string, any>;
+    onReplaced?: (info: any) => void;
+    throwOnRevert?: boolean;
+}
+/** Unified waitForTransaction: works with an ethers provider or a viem client. */
+export declare function waitForTransaction(opts: UnifiedWaitOptions): Promise<WaitForTransactionResult>;
+export { waitForTransactionEth, waitForTransactionViem, sendAndConfirm, sendAndConfirmViem, getRevertReason, decodeReceiptLogs, decodeViemReceiptLogs, TransactionRevertedError, TransactionTimeoutError, };
+export type { WaitForTransactionOptions, WaitForTransactionResult, DecodedLog, ReplacedInfo };

package/dist/transaction/index.js

@@ -0,0 +1,31 @@
+import { waitForTransaction as waitForTransactionEth, sendAndConfirm, getRevertReason, decodeReceiptLogs, } from './ethers.js';
+import { waitForTransactionViem, sendAndConfirmViem, decodeViemReceiptLogs, } from './viem.js';
+import { TransactionRevertedError, TransactionTimeoutError, } from './types.js';
+/** Unified waitForTransaction: works with an ethers provider or a viem client. */
+export async function waitForTransaction(opts) {
+    if (opts.client) {
+        return waitForTransactionViem({
+            client: opts.client,
+            hash: opts.hash,
+            confirmations: opts.confirmations,
+            timeout: opts.timeout,
+            abis: opts.abis,
+            onReplaced: opts.onReplaced,
+            throwOnRevert: opts.throwOnRevert,
+        });
+    }
+    if (opts.provider) {
+        return waitForTransactionEth({
+            provider: opts.provider,
+            hash: opts.hash,
+            confirmations: opts.confirmations,
+            timeout: opts.timeout,
+            abis: opts.abis,
+            onReplaced: opts.onReplaced,
+            throwOnRevert: opts.throwOnRevert,
+        });
+    }
+    throw new Error('waitForTransaction: provide either `provider` (ethers) or `client` (viem)');
+}
+export { waitForTransactionEth, waitForTransactionViem, sendAndConfirm, sendAndConfirmViem, getRevertReason, decodeReceiptLogs, decodeViemReceiptLogs, TransactionRevertedError, TransactionTimeoutError, };
+//# sourceMappingURL=index.js.map

package/dist/transaction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transaction/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,kBAAkB,IAAI,qBAAqB,EAC3C,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,wBAAwB,EACxB,uBAAuB,GAKxB,MAAM,YAAY,CAAC;AAepB,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAwB;IAC/D,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,OAAO,sBAAsB,CAAC;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;SAClC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,OAAO,qBAAqB,CAAC;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;SAClC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;AAC/F,CAAC;AAED,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,GACxB,CAAC"}

package/dist/transaction/types.d.ts

@@ -0,0 +1,46 @@
+import type { TransactionReceipt } from 'ethers';
+import type { AbiLike } from '../types.js';
+import type { DecodedError } from '../error-decoder/types.js';
+/** A log decoded against the user-provided ABI map. */
+export interface DecodedLog {
+    /** Raw log object (ethers or viem shaped). */
+    log: any;
+    /** Event name, if matched. */
+    name: string | null;
+    /** Parsed event arguments. */
+    args?: unknown[];
+}
+export interface ReplacedInfo {
+    reason: 'repriced' | 'replaced' | 'cancelled';
+    replacement?: unknown | null;
+    receipt?: unknown | null;
+}
+export declare class TransactionRevertedError extends Error {
+    readonly receipt: unknown;
+    readonly decoded: DecodedError;
+    readonly hash: string;
+    constructor(receipt: unknown, decoded: DecodedError, hash: string);
+}
+export declare class TransactionTimeoutError extends Error {
+    readonly hash: string;
+    constructor(hash: string, timeoutMs: number);
+}
+export interface WaitForTransactionOptions {
+    hash: string;
+    /** Confirmations to wait for. Default: 1. */
+    confirmations?: number;
+    /** Timeout in ms. Default: 120_000. */
+    timeout?: number;
+    /** Map of contract address (lowercased) -> ABI, used to decode logs and custom errors. */
+    abis?: Record<string, AbiLike>;
+    /** Called when the tx is replaced / repriced / cancelled. */
+    onReplaced?: (info: ReplacedInfo) => void;
+    /** Throw `TransactionRevertedError` when the tx reverts. Default: true. */
+    throwOnRevert?: boolean;
+}
+export interface WaitForTransactionResult {
+    receipt: TransactionReceipt | unknown;
+    logs: DecodedLog[];
+    /** Present when throwOnRevert=false and the tx reverted. */
+    decodedError?: DecodedError;
+}

package/dist/transaction/types.js

@@ -0,0 +1,21 @@
+export class TransactionRevertedError extends Error {
+    receipt;
+    decoded;
+    hash;
+    constructor(receipt, decoded, hash) {
+        super(`Transaction reverted: ${decoded.reason ?? 'unknown reason'}`);
+        this.name = 'TransactionRevertedError';
+        this.receipt = receipt;
+        this.decoded = decoded;
+        this.hash = hash;
+    }
+}
+export class TransactionTimeoutError extends Error {
+    hash;
+    constructor(hash, timeoutMs) {
+        super(`Timed out waiting for transaction ${hash} after ${timeoutMs}ms`);
+        this.name = 'TransactionTimeoutError';
+        this.hash = hash;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/transaction/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transaction/types.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,OAAO,CAAU;IACjB,OAAO,CAAe;IACtB,IAAI,CAAS;IAEtB,YAAY,OAAgB,EAAE,OAAqB,EAAE,IAAY;QAC/D,KAAK,CAAC,yBAAyB,OAAO,CAAC,MAAM,IAAI,gBAAgB,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,IAAI,CAAS;IACtB,YAAY,IAAY,EAAE,SAAiB;QACzC,KAAK,CAAC,qCAAqC,IAAI,UAAU,SAAS,IAAI,CAAC,CAAC;QACxE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/transaction/viem.d.ts

@@ -0,0 +1,29 @@
+import type { PublicClient, WalletClient, TransactionReceipt as ViemReceipt } from 'viem';
+import type { AbiLike } from '../types.js';
+import type { DecodedError } from '../error-decoder/types.js';
+import { TransactionTimeoutError, type DecodedLog, type WaitForTransactionOptions, type WaitForTransactionResult } from './types.js';
+/**
+ * Wait for a transaction with timeout, confirmations, replacement callback,
+ * decoded logs, and automatic revert decoding.
+ */
+export declare function waitForTransactionViem(opts: WaitForTransactionOptions & {
+    client: PublicClient;
+}): Promise<WaitForTransactionResult>;
+/** Send a transaction via a wallet client, then wait with full decode/timeout handling. */
+export declare function sendAndConfirmViem(wallet: WalletClient, request: any, opts?: {
+    publicClient?: PublicClient;
+    confirmations?: number;
+    timeout?: number;
+    abis?: Record<string, AbiLike>;
+    throwOnRevert?: boolean;
+}): Promise<WaitForTransactionResult & {
+    hash: string;
+}>;
+/**
+ * Recover + decode the revert reason of a mined reverted transaction for viem
+ * by replaying it via `publicClient.call`.
+ */
+export declare function getRevertReasonViem(client: PublicClient, txHash: string, abis?: ReadonlyArray<AbiLike>): Promise<DecodedError>;
+/** Decode logs of a viem receipt using the provided ABI map (parsed with ethers Interface). */
+export declare function decodeViemReceiptLogs(receipt: ViemReceipt, abis?: Record<string, AbiLike>): DecodedLog[];
+export { TransactionTimeoutError };