sd0xdev 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)
- Sourcify (free, no key) → get full ABI JSON
- Etherscan v2 (needs key, free tier 3 req/s) → get ABI JSON
- If proxy → get implementation address → re-query ABI
3b. Selector DB path (no contract address or ABI query failed)
- 4byte.directory API → may return multiple candidates
- 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