or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-abi-decoder

Nodejs and Javascript library for decoding data params and events from ethereum transactions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/abi-decoder@2.4.x

To install, run

npx @tessl/cli install tessl/npm-abi-decoder@2.4.0

index.mddocs/

ABI Decoder

ABI Decoder is a JavaScript library for decoding transaction data parameters and event logs from Ethereum blockchain transactions. It provides comprehensive ABI (Application Binary Interface) decoding capabilities for both Node.js and browser environments, enabling developers to interpret smart contract method calls and event emissions.

Package Information

  • Package Name: abi-decoder
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install abi-decoder

Core Imports

const abiDecoder = require('abi-decoder');

For browser environments:

<script src="bower_components/abi-decoder/dist/abi-decoder.js"></script>

Basic Usage

const abiDecoder = require('abi-decoder');

// Add ABI definitions for contracts you want to decode
const contractABI = [
  {
    "inputs": [{"type": "address[]", "name": "_owners"}, {"type": "uint256", "name": "_required"}],
    "name": "create",
    "type": "function"
  },
  {
    "inputs": [{"indexed": false, "type": "address", "name": "sender"}],
    "type": "event",
    "name": "ContractInstantiation"
  }
];

abiDecoder.addABI(contractABI);

// Decode transaction input data
const txData = "0x53d9d910..."; // transaction input data
const decodedMethod = abiDecoder.decodeMethod(txData);

// Decode event logs from transaction receipt
const logs = [/* log objects from transaction receipt */];
const decodedLogs = abiDecoder.decodeLogs(logs);

Architecture

ABI Decoder is built around several key components:

  • State Management: Internal state object storing registered ABIs and method ID mappings
  • ABI Processing: Functions for adding/removing ABI definitions and generating method signatures using SHA3 hashing
  • Method Decoding: Transaction input data decoder using web3-eth-abi for parameter extraction and type conversion
  • Event Log Decoding: Event log decoder handling both indexed and non-indexed parameters from transaction receipts
  • Type System: Comprehensive type handling including uint/int conversion to strings, address normalization, and ABIEncoderV2 tuple support

Capabilities

ABI Management

Add ABI

Registers ABI definitions for smart contracts to enable decoding of their method calls and events.

/**
 * Add ABI definitions to the decoder
 * @param {Array} abiArray - Array of ABI objects defining contract interfaces
 * @throws {Error} If abiArray is not an array
 */
function addABI(abiArray);

Usage Example:

const contractABI = [
  {
    "inputs": [{"type": "address", "name": "to"}, {"type": "uint256", "name": "value"}],
    "name": "transfer",
    "type": "function"
  }
];

abiDecoder.addABI(contractABI);

Remove ABI

Removes previously registered ABI definitions from the decoder.

/**
 * Remove ABI definitions from the decoder
 * @param {Array} abiArray - Array of ABI objects to remove
 * @throws {Error} If abiArray is not an array
 */
function removeABI(abiArray);

Important Notes:

  • Only removes method signatures from the internal method ID mapping
  • Does not remove ABIs from the saved ABIs array returned by getABIs()
  • Limitation: May not work correctly with complex ABIEncoderV2 tuple types due to inconsistent signature generation compared to addABI

Get ABIs

Retrieves all currently registered ABI definitions.

/**
 * Get all currently stored ABI definitions
 * @returns {Array} Array of all registered ABI objects
 */
function getABIs();

Get Method IDs

Returns the internal mapping of method signatures to ABI objects.

/**
 * Get mapping of method signatures to ABI objects
 * @returns {Object} Object with method IDs as keys and ABI objects as values
 */
function getMethodIDs();

Transaction Data Decoding

Decode Method

Decodes transaction input data into human-readable method call information.

/**
 * Decode transaction input data into method call information
 * @param {string} data - Hex-encoded transaction input data (starts with 0x)
 * @returns {Object|undefined} Decoded method object or undefined if method not found
 */
function decodeMethod(data);

Return Format:

interface DecodedMethod {
  name: string;           // Method name
  params: Array<{
    name: string;         // Parameter name
    value: any;           // Decoded parameter value
    type: string;         // Parameter type (uint256, address, etc.)
  }>;
}

Usage Example:

const txData = "0x53d9d9100000000000000000...";
const decoded = abiDecoder.decodeMethod(txData);

if (decoded) {
  console.log(`Method: ${decoded.name}`);
  decoded.params.forEach(param => {
    console.log(`${param.name} (${param.type}): ${param.value}`);
  });
}

Type Handling:

  • uint/int types: Converted to string representation for precision
  • address types: Normalized to lowercase
  • Arrays: Element-wise processing for uint/int and address arrays
  • Complex types: Full support for ABIEncoderV2 tuples and nested structures

Event Log Decoding

Decode Logs

Decodes event logs from transaction receipts into human-readable event information.

/**
 * Decode event logs from transaction receipts
 * @param {Array} logs - Array of log objects from transaction receipt
 * @returns {Array} Array of decoded event objects
 */
function decodeLogs(logs);

Return Format:

interface DecodedLog {
  name: string;           // Event name
  address: string;        // Contract address that emitted the event
  events: Array<{
    name: string;         // Parameter name
    type: string;         // Parameter type
    value: any;           // Decoded parameter value
  }>;
}

Usage Example:

// From web3.js transaction receipt
web3.eth.getTransactionReceipt(txHash, (error, receipt) => {
  if (!error) {
    const decodedLogs = abiDecoder.decodeLogs(receipt.logs);
    
    decodedLogs.forEach(log => {
      console.log(`Event: ${log.name} from ${log.address}`);
      log.events.forEach(event => {
        console.log(`${event.name} (${event.type}): ${event.value}`);
      });
    });
  }
});

Event Processing:

  • Indexed parameters: Retrieved from log topics
  • Non-indexed parameters: Decoded from log data using web3-eth-abi
  • Type normalization: Addresses lowercased, uint/int converted to strings
  • Filtering: Automatically filters out logs without topics or unrecognized events

Types

Log Object Structure

Expected structure for log objects passed to decodeLogs:

interface LogObject {
  data: string;           // Hex-encoded log data
  topics: string[];       // Array of log topics (event signature + indexed params)
  address: string;        // Contract address that emitted the log
}

ABI Object Structure

Standard Ethereum ABI format for functions and events:

interface ABIFunction {
  type: "function";
  name: string;
  inputs: Array<{
    name: string;
    type: string;
    components?: Array<{  // For tuple types (ABIEncoderV2)
      name: string;
      type: string;
    }>;
  }>;
}

interface ABIEvent {
  type: "event";
  name: string;
  inputs: Array<{
    name: string;
    type: string;
    indexed: boolean;
  }>;
}

Error Handling

The library throws errors in the following cases:

  • Invalid ABI format: When addABI() or removeABI() receive non-array input
  • Decoding failures: When underlying web3-eth-abi functions fail due to malformed data

Error Handling Example:

try {
  abiDecoder.addABI(invalidABI);
} catch (error) {
  console.error('Failed to add ABI:', error.message);
}

// decodeMethod returns undefined for unrecognized methods
const decoded = abiDecoder.decodeMethod(unknownData);
if (!decoded) {
  console.log('Method not found in registered ABIs');
}

Dependencies

The library depends on:

  • web3-eth-abi: Low-level ABI encoding/decoding operations
  • web3-utils: SHA3 hashing and BigNumber utilities

These dependencies are automatically installed with the package.