contract-decode

Contract Decode — EVM Error & Calldata Decoder

Decode EVM contract function selectors, custom errors, calldata, and revert data.

Trigger

• Keywords: revert, selector, 4byte, calldata, decode, custom error, execution reverted, abi decode
• Message contains 0x + 8+ hex chars (selector or revert data)

When NOT to Use

• Standard Error(string) revert already handled by your codebase
• Non-EVM chain errors
• Only need error code definitions (not hex decoding)

Input Parsing

Extract from user input:

Field	Source	Example
revertData	Error data or user-pasted hex	0xaca553e4
calldata	Transaction data	0x5e15c749000...1c05
contractAddr	Contract address	0x5874...f064
chainId	Chain identifier	1 (Ethereum mainnet)

Workflow

Step 1: Classify input → Step 2: Local fast decode → Step 3: ABI query → Step 4: Precise decode → Report

Step 1: Classify Input

Length	Classification	Next Step
4 bytes (0x + 8 hex)	Pure selector	Step 2
> 4 bytes, with selector prefix	Calldata or revert data	Step 2 + Step 3
Contract address	Need ABI first	Step 3

Step 2: Local Fast Decode (no external dependencies)

Try in order:

2a. Standard error decode

Selector	Type	Decode Method
0x08c379a0	Error(string)	cast abi-decode "Error(string)" <data>
0x4e487b71	Panic(uint256)	cast abi-decode "Panic(uint256)" <data> → lookup panic code

Panic code reference:

Code	Meaning
0x00	generic compiler panic
0x01	assert failure
0x11	arithmetic overflow
0x12	division by zero
0x21	enum conversion
0x22	storage encoding
0x31	pop empty array
0x32	array out of bounds
0x41	too much memory
0x51	zero function pointer

2b. Selector lookup (cast) — optional, skip if cast not installed

timeout 5 cast 4byte <selector>

If cast is unavailable or crashes, fall back to Step 3 API query.

Step 3: External API Query

See references/apis.md for full endpoints and parameters.

Query strategy:

Has contract address? → 3a. ABI path (precise) → get ABI → Step 4
No contract address?  → 3b. Selector DB path (candidates) → get signature candidates

3a. ABI path (has contract address + chainId)

1. Sourcify (free, no key) → get full ABI JSON
2. Etherscan v2 (needs key, free tier 3 req/s) → get ABI JSON
3. If proxy → get implementation address → re-query ABI

3b. Selector DB path (no contract address or ABI query failed)

1. 4byte.directory API → may return multiple candidates
2. Multiple candidates → mark confidence: low, list all possibilities

Step 4: Precise Decode

With ABI, use cast (if available):

# Decode revert data (needs ABI file)
cast decode-error <revert_data> --abi <abi_file>

# Decode calldata
cast decode-calldata <calldata> --abi <abi_file>

# Or decode with signature directly
cast calldata-decode "functionName(type1,type2)" <calldata>

Without ABI but with signature candidates:

cast abi-decode "functionName(type1,type2)" <data_without_selector>

Output Format

## Contract Decode Report

| Field | Value |
|-------|-------|
| Type | function call / revert error / event |
| Selector | `0x5e15c749` |
| Signature | `finalizeWithdrawal(uint256)` |
| Decoded Args | `tokenId: 7173` |
| Confidence | High (verified ABI) / Medium (selector DB) / Low (multiple candidates) |
| Source | Sourcify / Etherscan / 4byte.directory / cast |
| Contract | `0x5874...f064` |
| Chain | Ethereum Mainnet (chainId: 1) |

### Raw Data

- Revert: `0xaca553e4`
- Calldata: `0x5e15c749000...1c05`

Multiple candidates:

### Ambiguous Candidates

| # | Signature | Confidence |
|---|-----------|------------|
| 1 | `WithdrawalRequestDoesNotExist()` | Likely (context match) |
| 2 | `SomeOtherError()` | Unlikely |

References

File	Purpose	When to Read
references/apis.md	API endpoints, parameters, rate limits	Before Step 3

Verification

• Input correctly classified (selector / calldata / revert data)
• Local fast decode attempted (Error/Panic/cast)
• External query returned results or marked as failed
• Confidence level indicated
• Multiple candidates listed (if any)

Examples

Input: Decode 0xaca553e4
Action: 4 bytes → selector → cast 4byte → 4byte.directory → return candidate signatures

Input: What is this revert data 0x08c379a0000...
Action: selector = Error(string) → local cast abi-decode → return error message

Input: Decode this with contract 0x5874..., chainId 1, revert data 0xaca553e4
Action: Has contract + chainId → Sourcify ABI → cast decode-error → precise decode