web3-mev-error-decoder

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.

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

npm install web3-mev-error-decoder

or

yarn add web3-mev-error-decoder

Requires Node.js >= 20 and ethers v6 and/or viem v2 as peer dependencies.

Quick start — decode a thrown error (ethers v6)

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)

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

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

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:

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:

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:

// 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