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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 multicall-error-decoder contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# web3-mev-error-decoder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Multicall batching with per-call revert decoding, a custom error & revert reason decoder for **ethers v6** and **viem**, `waitForTransaction` with timeout and replacement handling, and RPC fallback providers with liveliness checks.
+
+Built for **web3 developers**, **smart-contract engineers**, and builders of **MEV bots**, **sniper bots**, **arbitrage bots** and DeFi dashboards that need reliable transaction error decoding and resilient RPC infrastructure.
+
+[![npm version](https://img.shields.io/npm/v/web3-mev-error-decoder.svg)](https://www.npmjs.com/package/web3-mev-error-decoder)
+[![license](https://img.shields.io/npm/l/web3-mev-error-decoder.svg)](LICENSE)
+
+## Why you need this
+
+If you run an MEV bot, a sniper bot, an arbitrage bot or any dApp that batches on-chain calls, you know the pain:
+
+- `CALL_EXCEPTION: execution reverted` with **no revert data** and no idea why the transaction failed
+- Multicall batches where **one failing call kills the whole batch** and you can't tell which one or why
+- Solidity **custom errors** (`0xabc12345...`) that your ABI doesn't decode
+- `Panic(uint256)` codes (`0x4e487b71`) that mean nothing to your logs
+- Transactions stuck because a public RPC is rate-limiting or behind
+- `waitForTransaction` hanging forever on dropped or replaced transactions
+
+**web3-mev-error-decoder** solves all of the above in one small, dependency-light package.
+
+## Features
+
+- **Decode revert reasons** (`Error(string)`) — including from aggregated **multicall** results, with per-call revert data
+- **Decode Solidity custom errors** through any ABI you provide (human-readable signature + args)
+- **Decode `Panic(uint256)` codes** into human-readable reasons (assert, overflow, division by zero, etc.)
+- **viem-compatible error extraction** — understands `error.data`, nested `error.data` and `cause` chains
+- **Replay mined reverted transactions** via `eth_call` to recover the original revert reason
+- **Multicall batching** for ethers v6 and viem with graceful per-call failure handling
+- **`waitForTransaction`** with timeout and replacement-transaction handling
+- **RPC fallback providers** with automatic liveliness checks and rotation
+- Zero runtime bloat: peer deps are `ethers` and/or `viem` — use one or both
+
+## Install
+
+```bash
+npm install web3-mev-error-decoder
+```
+
+or
+
+```bash
+yarn add web3-mev-error-decoder
+```
+
+Requires Node.js >= 20 and [`ethers`](https://www.npmjs.com/package/ethers) v6 and/or [`viem`](https://www.npmjs.com/package/viem) v2 as peer dependencies.
+
+## Quick start — decode a thrown error (ethers v6)
+
+```ts
+import { ErrorDecoder } from 'web3-mev-error-decoder';
+
+const decoder = new ErrorDecoder({
+  // ABIs that may contain custom errors (optional)
+  abis: [myContractAbi],
+});
+
+try {
+  await contract.myMethod();
+} catch (error) {
+  const decoded = await decoder.decode(error);
+  console.log(decoded.type);        // ErrorType.REVERT | CUSTOM | PANIC | ...
+  console.log(decoded.reason);      // human-readable reason
+  console.log(decoded.args);        // decoded custom error args
+}
+```
+
+## Decode raw revert data (multicall results)
+
+```ts
+import { decodeRevertData } from 'web3-mev-error-decoder';
+
+const decoded = decodeRevertData(revertDataHex, [myContractAbi]);
+// -> { type, reason, fragment, args, signature }
+```
+
+Perfect for **multicall** / **aggregate3** batch results where each call can individually revert and you need to know exactly which call failed and why — the core requirement of MEV bots, sniper bots and arbitrage bots that must react to failures in the same block.
+
+## Decode a mined reverted transaction
+
+```ts
+import { ErrorDecoder } from 'web3-mev-error-decoder';
+
+const decoder = new ErrorDecoder();
+
+// replays the transaction via eth_call at the latest block
+const decoded = await decoder.getRevertReason(provider, txHash);
+```
+
+## Decoded error types
+
+| Type | Trigger | Example |
+|---|---|---|
+| `REVERT` | `Error(string)` revert reason | `"Insufficient balance"` |
+| `CUSTOM` | ABI-known custom error | `Unauthorized(address)` with args |
+| `PANIC` | Solidity `Panic(uint256)` | `"Arithmetic overflow"` |
+| `EMPTY` | Reverted with no data | `"reverted (no revert data)"` |
+| `USER_REJECT` | Wallet rejection | `"User rejected the request"` |
+| `RPC` | Transport / node errors | `"rate limit exceeded"` |
+| `UNKNOWN` | Anything else | raw data preserved |
+
+## Multicall batching
+
+```ts
+import { Multicaller } from 'web3-mev-error-decoder/multicall';
+```
+
+Batch hundreds of calls through a Multicall3-style aggregate contract. Failed calls are surfaced **individually** with fully decoded revert data instead of failing the whole batch — so your bot can keep running with partial results and only skip the broken routes.
+
+## waitForTransaction with timeout & replacement
+
+Stop hanging on stuck transactions:
+
+```ts
+import { waitForTransaction } from 'web3-mev-error-decoder/transaction';
+
+const receipt = await waitForTransaction({
+  provider,
+  hash: txHash,
+  timeoutMs: 30_000,        // bail out after 30s
+  replacement: { /* bump gas and re-submit */ },
+});
+```
+
+Typical use: **sniper bots** and **arbitrage bots** racing mempool competition where a transaction must be replaced or abandoned quickly.
+
+## RPC fallback providers
+
+Never get stuck on a rate-limited public RPC again:
+
+```ts
+import { FallbackProvider } from 'web3-mev-error-decoder/provider';
+```
+
+Automatic failover across multiple RPC endpoints with liveliness checks, so your bot's error decoder and transaction pipeline keep working when a node goes down.
+
+## Works with ethers v6 and viem
+
+Use it with either stack — or both:
+
+```ts
+// ethers v6
+import { ErrorDecoder } from 'web3-mev-error-decoder';
+
+// viem-compatible error extraction is built in
+```
+
+## Who is this for
+
+- **MEV bot developers** — searchers, builders, sandwich/liquidation strategies that need per-call failure decoding inside multicall batches
+- **Sniper & arbitrage bot developers** — fast failure triage to reroute or drop failing opportunities
+- **Smart-contract engineers** — decoding custom errors and panics during integration testing and incident response
+- **dApp / DeFi frontend teams** — turning cryptic wallet and RPC errors into actionable messages
+- **Infrastructure engineers** — resilient RPC fallback and transaction replacement pipelines
+
+## API
+
+- `ErrorDecoder` — class with `decode(error)`, `decodeData(data, error?)`, `getRevertReason(provider, txHash)`, `getTransactionError(receipt)`
+- `decodeRevertData(data, abis?, error?)` — stateless one-shot decoder
+- `defaultErrorHandlers` — built-in handler chain, extendable via `additionalErrorHandlers`
+- `Multicaller` — multicall batching (ethers v6 / viem)
+- `waitForTransaction` — timeout + replacement handling
+- `SimpleFallbackProvider` / viem fallback transports — RPC failover
+
+## License
+
+[MIT](LICENSE)

package/dist/error-decoder/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const ERROR_STRING_PREFIX = "0x08c379a0";
+export declare const PANIC_CODE_PREFIX = "0x4e487b71";
+/** Standard panic (assert) codes from Solidity. */
+export declare const panicCodes: Record<number, string>;
+export declare function panicErrorCodeToReason(code: bigint): string | null;

package/dist/error-decoder/constants.js

@@ -0,0 +1,19 @@
+export const ERROR_STRING_PREFIX = '0x08c379a0'; // keccak256("Error(string)") selector
+export const PANIC_CODE_PREFIX = '0x4e487b71'; // keccak256("Panic(uint256)") selector
+/** Standard panic (assert) codes from Solidity. */
+export const panicCodes = {
+    0x00: 'Generic panic',
+    0x01: 'Assert() has failed',
+    0x11: 'Arithmetic operation underflowed or overflowed outside of an unchecked block',
+    0x12: 'Division or modulo division by zero',
+    0x21: 'Tried to convert to an invalid enum value',
+    0x22: 'Storage byte array that is incorrectly encoded',
+    0x31: 'Method is called on an empty POP array',
+    0x32: 'Array index that is out of bounds',
+    0x41: 'Allocation of too much memory or creation of an array which is too large',
+    0x51: 'Called a zero-initialized variable of an internal function type',
+};
+export function panicErrorCodeToReason(code) {
+    return panicCodes[Number(code)] ?? null;
+}
+//# sourceMappingURL=constants.js.map

package/dist/error-decoder/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/error-decoder/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC,CAAC,sCAAsC;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC,CAAC,uCAAuC;AAEtF,mDAAmD;AACnD,MAAM,CAAC,MAAM,UAAU,GAA2B;IAChD,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,qBAAqB;IAC3B,IAAI,EAAE,8EAA8E;IACpF,IAAI,EAAE,qCAAqC;IAC3C,IAAI,EAAE,2CAA2C;IACjD,IAAI,EAAE,gDAAgD;IACtD,IAAI,EAAE,wCAAwC;IAC9C,IAAI,EAAE,mCAAmC;IACzC,IAAI,EAAE,0EAA0E;IAChF,IAAI,EAAE,iEAAiE;CACxE,CAAC;AAEF,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC;AAC1C,CAAC"}

package/dist/error-decoder/decoder.d.ts

@@ -0,0 +1,43 @@
+import { TransactionReceipt, TransactionResponse } from 'ethers';
+import type { AbiLike } from '../types.js';
+import type { DecodedError, ErrorHandler } from './types.js';
+/**
+ * Decodes contract errors:
+ *  - `Error(string)` revert reasons
+ *  - Solidity `Panic(uint256)` codes
+ *  - custom errors via the ABIs you provide
+ *  - user rejection and JSON-RPC transport errors
+ */
+export declare class ErrorDecoder {
+    private readonly errorHandlers;
+    private readonly errorInterface;
+    constructor(errorInterfaces?: ReadonlyArray<AbiLike>, opts?: {
+        additionalErrorHandlers?: ErrorHandler[];
+    });
+    /**
+     * Decode a thrown error. Understands:
+     *  - ethers `CALL_EXCEPTION` (sync `.call` revert)
+     *  - errors carrying a `receipt` (mined reverted transaction), which are replayed via `eth_call`
+     *    to recover the revert data
+     *  - any error object with `data` / nested `error.data` / `cause` chain (viem-compatible)
+     */
+    decode(error: unknown): Promise<DecodedError>;
+    /**
+     * Decode raw revert data directly (e.g. from a failed `eth_call` or from a
+     * multicall per-item return data).
+     */
+    decodeData(data: string | undefined, error?: Error): DecodedError;
+    /**
+     * Recover the revert reason of a mined reverted transaction by replaying it
+     * via `eth_call` at the latest block. Returns a decoded error.
+     */
+    getRevertReason(provider: {
+        getTransaction: (hash: string) => Promise<TransactionResponse | null>;
+        call: (tx: any) => Promise<any>;
+    }, txHash: string): Promise<DecodedError>;
+    /** Replay a reverted receipt to get the original error (or null if unrecoverable). */
+    getTransactionError(receipt: TransactionReceipt): Promise<Error | null>;
+    private getContractOrTransactionError;
+}
+/** Convenience: decode raw revert data without constructing an ErrorDecoder. */
+export declare function decodeRevertData(data: string | undefined, abis?: ReadonlyArray<AbiLike>, error?: Error): DecodedError;

package/dist/error-decoder/decoder.js

@@ -0,0 +1,98 @@
+import { callRequestFromTx, extractRevertData, mergeAbis } from '../utils.js';
+import { defaultErrorHandlers } from './handlers.js';
+import { unknownErrorResult } from './results.js';
+/**
+ * Decodes contract errors:
+ *  - `Error(string)` revert reasons
+ *  - Solidity `Panic(uint256)` codes
+ *  - custom errors via the ABIs you provide
+ *  - user rejection and JSON-RPC transport errors
+ */
+export class ErrorDecoder {
+    errorHandlers;
+    errorInterface;
+    constructor(errorInterfaces, opts = {}) {
+        this.errorInterface =
+            errorInterfaces && errorInterfaces.length > 0 ? mergeAbis(errorInterfaces) : undefined;
+        this.errorHandlers = [...defaultErrorHandlers, ...(opts.additionalErrorHandlers ?? [])];
+    }
+    /**
+     * Decode a thrown error. Understands:
+     *  - ethers `CALL_EXCEPTION` (sync `.call` revert)
+     *  - errors carrying a `receipt` (mined reverted transaction), which are replayed via `eth_call`
+     *    to recover the revert data
+     *  - any error object with `data` / nested `error.data` / `cause` chain (viem-compatible)
+     */
+    async decode(error) {
+        if (!(error instanceof Error)) {
+            return unknownErrorResult({ reason: error?.message ?? 'Invalid error' });
+        }
+        const targetError = await this.getContractOrTransactionError(error);
+        const data = extractRevertData(targetError);
+        return this.decodeData(data, targetError);
+    }
+    /**
+     * Decode raw revert data directly (e.g. from a failed `eth_call` or from a
+     * multicall per-item return data).
+     */
+    decodeData(data, error) {
+        for (const handler of this.errorHandlers) {
+            if (handler.predicate(data, error ?? new Error())) {
+                return handler.handle(data, { errorInterface: this.errorInterface, error: error ?? new Error() });
+            }
+        }
+        return unknownErrorResult({ data, reason: error?.message ?? 'Unexpected error' });
+    }
+    /**
+     * Recover the revert reason of a mined reverted transaction by replaying it
+     * via `eth_call` at the latest block. Returns a decoded error.
+     */
+    async getRevertReason(provider, txHash) {
+        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) {
+            return unknownErrorResult({ reason: 'Transaction not found' });
+        }
+        let data;
+        try {
+            await provider.call(callRequestFromTx(tx));
+            // Call succeeded — the chain state has moved on; cannot reproduce revert.
+            data = undefined;
+        }
+        catch (e) {
+            data = extractRevertData(e);
+        }
+        return this.decodeData(data);
+    }
+    /** Replay a reverted receipt to get the original error (or null if unrecoverable). */
+    async getTransactionError(receipt) {
+        if (receipt.status !== 0)
+            return null;
+        const provider = receipt.provider;
+        const tx = await provider.getTransaction(receipt.hash);
+        if (!tx)
+            return null;
+        try {
+            await provider.call(callRequestFromTx(tx));
+            return null; // call succeeded — would not have reverted now
+        }
+        catch (e) {
+            return e;
+        }
+    }
+    async getContractOrTransactionError(error) {
+        const receipt = error.receipt;
+        if (!receipt || receipt.status !== 0)
+            return error;
+        const replayed = await this.getTransactionError(receipt);
+        return replayed ?? error;
+    }
+}
+/** Convenience: decode raw revert data without constructing an ErrorDecoder. */
+export function decodeRevertData(data, abis, error) {
+    return new ErrorDecoder(abis).decodeData(data, error);
+}
+//# sourceMappingURL=decoder.js.map

package/dist/error-decoder/decoder.js.map

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

package/dist/error-decoder/enums.d.ts

@@ -0,0 +1,9 @@
+export declare enum ErrorType {
+    EmptyError = "EmptyError",
+    RevertError = "RevertError",
+    PanicError = "PanicError",
+    CustomError = "CustomError",
+    UserRejectError = "UserRejectError",
+    RpcError = "RpcError",
+    UnknownError = "UnknownError"
+}

package/dist/error-decoder/enums.js

@@ -0,0 +1,11 @@
+export var ErrorType;
+(function (ErrorType) {
+    ErrorType["EmptyError"] = "EmptyError";
+    ErrorType["RevertError"] = "RevertError";
+    ErrorType["PanicError"] = "PanicError";
+    ErrorType["CustomError"] = "CustomError";
+    ErrorType["UserRejectError"] = "UserRejectError";
+    ErrorType["RpcError"] = "RpcError";
+    ErrorType["UnknownError"] = "UnknownError";
+})(ErrorType || (ErrorType = {}));
+//# sourceMappingURL=enums.js.map

package/dist/error-decoder/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../src/error-decoder/enums.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,SAQX;AARD,WAAY,SAAS;IACnB,sCAAyB,CAAA;IACzB,wCAA2B,CAAA;IAC3B,sCAAyB,CAAA;IACzB,wCAA2B,CAAA;IAC3B,gDAAmC,CAAA;IACnC,kCAAqB,CAAA;IACrB,0CAA6B,CAAA;AAC/B,CAAC,EARW,SAAS,KAAT,SAAS,QAQpB"}

package/dist/error-decoder/handlers.d.ts

@@ -0,0 +1,32 @@
+import { ErrorType } from './enums.js';
+import type { DecodedError, ErrorHandler, ErrorHandlerInput } from './types.js';
+export declare class EmptyErrorHandler implements ErrorHandler {
+    predicate(data: string | undefined): boolean;
+    handle(data: string | undefined): DecodedError;
+}
+export declare class RevertErrorHandler implements ErrorHandler {
+    predicate(data: string | undefined): boolean;
+    handle(data: string | undefined): DecodedError;
+}
+export declare class PanicErrorHandler implements ErrorHandler {
+    predicate(data: string | undefined): boolean;
+    handle(data: string | undefined): DecodedError;
+}
+export declare class CustomErrorHandler implements ErrorHandler {
+    predicate(data: string | undefined): boolean;
+    handle(data: string | undefined, { errorInterface }: ErrorHandlerInput): DecodedError;
+}
+export declare class RevertedWithoutDataHandler implements ErrorHandler {
+    predicate(data: string | undefined, error: Error): boolean;
+    handle(_data: string | undefined, { error }: ErrorHandlerInput): DecodedError;
+}
+export declare class UserRejectionHandler implements ErrorHandler {
+    predicate(data: string | undefined, error: Error): boolean;
+    handle(_data: string | undefined, { error }: ErrorHandlerInput): DecodedError;
+}
+export declare class RpcErrorHandler implements ErrorHandler {
+    predicate(data: string | undefined, error: Error): boolean;
+    handle(_data: string | undefined, { error }: ErrorHandlerInput): DecodedError;
+}
+export declare const defaultErrorHandlers: ErrorHandler[];
+export { ErrorType };

package/dist/error-decoder/handlers.js

@@ -0,0 +1,131 @@
+import { AbiCoder, ErrorFragment } from 'ethers';
+import { ERROR_STRING_PREFIX, PANIC_CODE_PREFIX, panicErrorCodeToReason } from './constants.js';
+import { ErrorType } from './enums.js';
+import { customErrorResult, emptyErrorResult, panicErrorResult, revertErrorResult, rpcErrorResult, unknownErrorResult, userRejectErrorResult, } from './results.js';
+export class EmptyErrorHandler {
+    predicate(data) {
+        return data === '0x';
+    }
+    handle(data) {
+        return emptyErrorResult({ data, reason: 'reverted (no revert data)' });
+    }
+}
+export class RevertErrorHandler {
+    predicate(data) {
+        return !!data && data.startsWith(ERROR_STRING_PREFIX);
+    }
+    handle(data) {
+        if (!data)
+            return unknownErrorResult({ reason: 'Unknown error returned', data });
+        const encodedReason = data.slice(ERROR_STRING_PREFIX.length);
+        const abi = AbiCoder.defaultAbiCoder();
+        try {
+            const fragment = ErrorFragment.from('Error(string)');
+            const args = abi.decode(fragment.inputs, `0x${encodedReason}`);
+            const reason = args[0];
+            return revertErrorResult({ data, fragment, reason, args });
+        }
+        catch {
+            return unknownErrorResult({ reason: 'Unknown error returned', data });
+        }
+    }
+}
+export class PanicErrorHandler {
+    predicate(data) {
+        return !!data && data.startsWith(PANIC_CODE_PREFIX);
+    }
+    handle(data) {
+        if (!data)
+            return unknownErrorResult({ reason: 'Unknown panic error', data });
+        const encodedReason = data.slice(PANIC_CODE_PREFIX.length);
+        const abi = AbiCoder.defaultAbiCoder();
+        try {
+            const fragment = ErrorFragment.from('Panic(uint256)');
+            const args = abi.decode(fragment.inputs, `0x${encodedReason}`);
+            const reason = panicErrorCodeToReason(args[0]) ?? 'Unknown panic code';
+            return panicErrorResult({ data, fragment, reason, args });
+        }
+        catch {
+            return unknownErrorResult({ reason: 'Unknown panic error', data });
+        }
+    }
+}
+export class CustomErrorHandler {
+    predicate(data) {
+        return (!!data &&
+            data !== '0x' &&
+            !data.startsWith(ERROR_STRING_PREFIX) &&
+            !data.startsWith(PANIC_CODE_PREFIX));
+    }
+    handle(data, { errorInterface }) {
+        if (!data)
+            return unknownErrorResult({ reason: 'Unknown error', data });
+        let fragment = null;
+        let reason = null;
+        let args = null;
+        let signature = null;
+        if (errorInterface) {
+            try {
+                const parsed = errorInterface.parseError(data);
+                if (parsed) {
+                    fragment = parsed.fragment;
+                    reason = parsed.name;
+                    args = parsed.args;
+                    signature = parsed.fragment.format();
+                }
+            }
+            catch {
+                // no matching fragment in the provided ABI
+            }
+        }
+        return customErrorResult({ data, fragment, reason, args, signature });
+    }
+}
+export class RevertedWithoutDataHandler {
+    predicate(data, error) {
+        return !data && !!error?.message && /revert/i.test(error.message);
+    }
+    handle(_data, { error }) {
+        return emptyErrorResult({
+            data: null,
+            reason: error.message?.includes('execution reverted')
+                ? 'execution reverted (no revert data)'
+                : 'reverted (no revert data)',
+        });
+    }
+}
+export class UserRejectionHandler {
+    predicate(data, error) {
+        return !data && !!error?.message && /reject(ed)?/i.test(error.message);
+    }
+    handle(_data, { error }) {
+        return userRejectErrorResult({
+            data: null,
+            reason: error.message ?? 'The transaction was rejected',
+        });
+    }
+}
+export class RpcErrorHandler {
+    predicate(data, error) {
+        return (!data &&
+            !!error.message &&
+            !error.message.includes('rejected transaction') &&
+            error.code !== undefined);
+    }
+    handle(_data, { error }) {
+        const rpcError = error;
+        const reason = rpcError.info?.error?.message ?? rpcError.shortMessage ?? rpcError.message;
+        return rpcErrorResult({ name: rpcError.code, reason });
+    }
+}
+export const defaultErrorHandlers = [
+    new EmptyErrorHandler(),
+    new RevertErrorHandler(),
+    new PanicErrorHandler(),
+    new CustomErrorHandler(),
+    new RevertedWithoutDataHandler(),
+    new UserRejectionHandler(),
+    new RpcErrorHandler(),
+];
+export { ErrorType };
+//# sourceMappingURL=handlers.js.map

package/dist/error-decoder/handlers.js.map

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

package/dist/error-decoder/index.d.ts

@@ -0,0 +1,7 @@
+export * from './enums.js';
+export * from './constants.js';
+export * from './results.js';
+export * from './handlers.js';
+export * from './decoder.js';
+export * from './viem.js';
+export type { DecodedError, ErrorHandler, ErrorHandlerInput } from './types.js';

package/dist/error-decoder/index.js

@@ -0,0 +1,7 @@
+export * from './enums.js';
+export * from './constants.js';
+export * from './results.js';
+export * from './handlers.js';
+export * from './decoder.js';
+export * from './viem.js';
+//# sourceMappingURL=index.js.map

package/dist/error-decoder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/error-decoder/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/error-decoder/results.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorFragment, Result } from 'ethers';
+import type { DecodedError } from './types.js';
+type ErrorResultFormatterParam = {
+    data?: string | null;
+    reason?: string | null;
+    args?: Result | null;
+    fragment?: ErrorFragment | null;
+    selector?: string | null;
+    name?: string | null;
+    signature?: string | null;
+};
+export declare const emptyErrorResult: (p: ErrorResultFormatterParam) => DecodedError;
+export declare const userRejectErrorResult: (p: ErrorResultFormatterParam) => DecodedError;
+export declare const revertErrorResult: (p: ErrorResultFormatterParam) => DecodedError;
+export declare const unknownErrorResult: (p: ErrorResultFormatterParam) => DecodedError;
+export declare const panicErrorResult: (p: ErrorResultFormatterParam) => DecodedError;
+export declare const customErrorResult: (p: ErrorResultFormatterParam) => DecodedError;
+export declare const rpcErrorResult: (p: ErrorResultFormatterParam) => DecodedError;
+export {};