feat: ExecutionError utils

[0xpolarzero]

Would love to get some ExecutionError/EvmError utils for classifying and decoding raw hex data returned from a failed transaction into a human-readable output.

If this fits into ox, I'll be happy to open a PR to implement!

Some context below:

Proposal: ExecutionError/EvmError module — standard EVM-error decoding

Problem

Every client (Geth, Reth, Anvil, Hardhat, …) returns execution failures differently. A few examples:

Node	Panic tagged as	JSON-RPC code for REVERT	Decoding depth
reth	Halt (not revert)	-32000	Error(string) + basic custom errors via Alloy
geth	Revert	-32000	Error(string) and Panic(uint256) via UnpackRevert
Anvil	Revert	-32603	Aggressive (Error, Panic, all custom errors)

Yet the raw revert data always follows one of four ABI patterns:

selector	kind	payload
empty	Empty revert	–
0x08c379a0	Error(string)	UTF-8 reason
0x4e487b71	Panic(uint256)	panic code
anything else	Custom error	ABI-encoded args

Ox lacks a single helper that turns this hex blob into something human-readable.

---

API sketch

This could roughly look like this:

namespace ExecutionError {
  export type Decoded = {
    type: 'empty' | 'revert' | 'panic' | 'custom';
    message?: string;            // Error(string)
    panicCode?: bigint;          // Panic(uint256)
    panicDescription?: string;   // "division by zero", etc.
    customSignature?: string;    // 4-byte selector
    args?: unknown[];            // decoded with ABI if supplied
  };

  /** Decode raw error hex (0x…) into a unified structure. */
  export function decode(
    data: Hex | Bytes | string,
    abi?: Abi   // optional contract ABI for custom errors
  ): Decoded;
}

Implementation notes

• Essentially uses ox utilities (Hex, Bytes, AbiParameters, AbiError).

• Map known panic codes (0x01, 0x11, 0x12, …) to Solidity descriptions, which doesn't need to be guessed.

• If abi is provided, it can fully decode the error.

Reference

• reth RevertError definition and doc-comment (reth.rs)
• Alloy example showing RevertReason::decode (alloy.rs)
• Go-ethereum abi.UnpackRevert docs line (pkg.go.dev)
• geth VM comment: “ErrExecutionReverted means revert-and-keep-gas-left” (gist.github.com)
• Foundry issue on expanding RevertDecoder support (github.com)
• Foundry book: message-less reverts and cheat-code semantics (book.getfoundry.sh)

---

Quick example

const out = Error.decode(
  '0x08c379a000000000…',           // tx failure data
);
console.log(out);  // { type: 'revert', message: 'ERC20: transfer amount exceeds balance' }

This would basically allow to trade the returned data for a unified error object, with a known format, regardless of the client implementation.

Link to deep research with o3