@pulsadev/tx-decoder

Decode any EVM transaction calldata into human-readable format — with or without an ABI.

Pass calldata and get back the function name, signature, and decoded arguments. If you don't have the ABI, the package automatically queries 4byte.directory to resolve the selector. Zero dependencies.

Features

• ABI-optional decoding — provide an ABI for exact decoding, or let 4byte.directory resolve unknown selectors
• Calldata decoding — function name, signature, and decoded arguments from raw calldata
• Event log decoding — decode indexed and non-indexed parameters from transaction logs
• Error decoding — Error(string), Panic(uint256), and custom ABI errors
• Sync + async API — decodeCalldataSync for known ABIs, decodeCalldata for automatic lookup
• 4byte.directory integration — automatic selector and event topic resolution with built-in caching
• Zero dependencies — pure TypeScript, ~25 KB bundled, ESM + CJS
• Works everywhere — Node.js, Deno, Bun, browsers

Install

npm install @pulsadev/tx-decoder

Quick Start

With ABI (synchronous)

import { decodeCalldataSync } from '@pulsadev/tx-decoder'

const abi = [{
  type: 'function',
  name: 'transfer',
  inputs: [
    { type: 'address', name: 'to' },
    { type: 'uint256', name: 'amount' },
  ],
  outputs: [{ type: 'bool', name: '' }],
  stateMutability: 'nonpayable',
}]

const result = decodeCalldataSync(calldata, abi)
// {
//   selector: '0xa9059cbb',
//   signature: 'transfer(address,uint256)',
//   functionName: 'transfer',
//   args: { to: '0xd8dA...6045', amount: 1000000n },
//   rawArgs: ['0xd8dA...6045', 1000000n]
// }

Without ABI (automatic 4byte lookup)

import { decodeCalldata } from '@pulsadev/tx-decoder'

// No ABI needed — selector is resolved via 4byte.directory
const result = await decodeCalldata(calldata)
// {
//   selector: '0xa9059cbb',
//   signature: 'transfer(address,uint256)',
//   functionName: 'transfer',
//   args: { param0: '0xd8dA...6045', param1: 1000000n },
//   rawArgs: ['0xd8dA...6045', 1000000n]
// }

API

Calldata Decoding

// Async — auto-resolves unknown selectors via 4byte.directory
const result = await decodeCalldata(data, {
  abi?: AbiItem[],          // optional ABI (tried first)
  fetchSignature?: boolean, // enable/disable 4byte lookup (default: true)
  fourByteUrl?: string,     // custom 4byte API URL
})

// Sync — requires ABI, no network calls
const result = decodeCalldataSync(data, abi)

Event Log Decoding

import { decodeLog, decodeLogSync } from '@pulsadev/tx-decoder'

// Async — with optional 4byte topic lookup
const event = await decodeLog(log.topics, log.data, { abi })
// { eventName: 'Transfer', signature: 'Transfer(address,address,uint256)', args: { from, to, value } }

// Sync — requires ABI
const event = decodeLogSync(log.topics, log.data, abi)

Error Decoding

import { decodeError } from '@pulsadev/tx-decoder'

const error = await decodeError(revertData, { abi })
// Built-in: { errorName: 'Error', args: { reason: 'Insufficient balance' } }
// Panic:   { errorName: 'Panic', args: { code: 0x11n, reason: 'Arithmetic overflow/underflow' } }
// Custom:  { errorName: 'InsufficientOutputAmount', args: { amountOut: 500n, amountOutMin: 1000n } }

4byte.directory Lookup

import { lookupSelector, lookupEventTopic } from '@pulsadev/tx-decoder'

// Lookup function signature by selector
const entries = await lookupSelector('a9059cbb')
// [{ name: 'transfer', signature: 'transfer(address,uint256)', inputs: [...] }]

// Lookup event signature by topic hash
const events = await lookupEventTopic('0xddf252ad...')

Utilities

import { keccak256, selector, eventTopic } from '@pulsadev/tx-decoder'

keccak256('transfer(address,uint256)')     // full 32-byte hash
selector('transfer(address,uint256)')      // first 4 bytes
eventTopic('Transfer(address,address,uint256)') // '0x' + full hash

Why @pulsadev/tx-decoder

| | @pulsadev/tx-decoder | abi-decoder | whatsabi | ethers/viem | |--|:--:|:--:|:--:|:--:| | ABI-optional decoding | ✅ | ❌ | ❌ | ❌ | | 4byte.directory auto | ✅ | ❌ | ❌ | ❌ | | Calldata decoding | ✅ | ✅ | ❌ | ✅ | | Event decoding | ✅ | ✅ | ❌ | ✅ | | Error decoding | ✅ | ❌ | ❌ | partial | | Standalone | ✅ 0 deps | ❌ web3 | ✅ | ❌ | | TypeScript | ✅ | ❌ | ✅ | ✅ | | MIT license | ✅ | ❌ GPL | ✅ | ✅ | | ESM + CJS | ✅ | ❌ CJS | ✅ | ✅ | | Maintained | ✅ | ❌ 5yr | ✅ | ✅ |

License

MIT © Yuto Nakamura