DOCSEARCHbyAlgolia
Submit Docs

ethabi

repository·master·Indexed 19 days ago

https://github.com/rust-ethereum/ethabi

A Rust library for encoding and decoding Ethereum Application Binary Interface (ABI) data, enabling conversion between high-level types and the raw hex format used by the Ethereum Virtual Machine (EVM). It includes the ethabi-cli tool for command-line encoding/decoding of contract calls, parameters, and event logs, as well as the ethabi-derive crate for generating type-safe Rust interfaces for Solidity contracts, functions, and events.

Tokens
11.4K
Snippets
35
Records
48
Agent score
68%

What's inside ethabi

  1. Use ethabi-cli to encode ABI calls

    master

    The ethabi encode command allows you to generate hex-encoded data for function calls or raw parameters.

    Encode function calls from a JSON ABI

    Use encode function <abi-path> <function-name-or-signature> to load a function definition from a JSON file and encode its arguments.

    Encode raw parameters

    Use encode params to encode values based on inline type definitions using the -v <type> <param> flag.

    # Encode parameters inline
ethabi encode params -v bool 1

# Encode a function from a JSON ABI file
ethabi encode function examples/test.json foo -p 1

  3. Use ethabi-cli to decode ABI data

    master

    The ethabi decode command allows you to turn hex data back into human-readable formats.

    Decode raw parameters

    Use decode params with the -t <type> flag to specify the expected types for the hex data.

    Decode function outputs

    Use decode function <abi-path> <function-name-or-signature> <data> to decode data using a specific function definition from a JSON ABI.

    Decode event logs

    Use decode log <abi-path> <event-name-or-signature> to decode event logs. You can provide topics using the -l <topic> flag.

    # Decode raw parameters
ethabi decode params -t bool 0000000000000000000000000000000000000000000000000000000000000001

# Decode function output from a JSON ABI
ethabi decode function ./examples/foo.json bar 0000000000000000000000000000000000000000000000000000000000000001

# Decode an event log
ethabi decode log ./examples/event.json Event -l 0000000000000000000000000000000000000000000000000000000000000001 0000000000000000000000004444444444444444444444444444444444444444

  4. Parse raw logs into structured data using ParseLog

    master

    The ParseLog trait provides a standard interface for types (typically event definitions) that can transform a RawLog into a structured Log type.

    To implement this for your own event types, define an associated type Log and implement the parse_log method:

    fn parse_log(&self, log: RawLog) -> Result<Self::Log>;

  5. Manage contract functions, events, and logs

    master

    The ethabi public API exports several key abstractions for interacting with Ethereum smart contracts:

    • Contract: Represents a smart contract, containing its Functions, Events, and Constructor.
    • Function: Represents a specific contract function.
    • Event: Represents a contract event.
    • Log: Represents a log entry, including LogFilter and LogParam for filtering and parsing.
    • Topic and TopicFilter: Used for filtering logs based on event topics.
    • ParamType: Defines the type of an ABI parameter.
    • Param: Represents an actual value of a specific ParamType.
    • StateMutability: Defines whether a function is view, pure, or modifies state.

  6. Generate contract function interfaces with the Function derive macro

    master

    The ethabi-derive package provides a Function struct that can be used to generate type-safe Rust modules for interacting with Ethereum smart contract functions. By calling .generate() on a Function instance, you produce a TokenStream that defines a new module named after the function (in snake_case).

    This generated module provides several key utilities:

    • encode_input(...): Encodes function arguments into ethabi::Bytes using generic type constraints (e.g., T0: Into<ethabi::Address>).
    • decode_output(output: &[u8]): Decodes raw bytes from a contract call into the expected Rust return types.
    • call(...): A convenience method that returns both the encoded input bytes and a Decoder instance for the output.
    • Decoder: A struct implementing ethabi::FunctionOutputDecoder for the specific function's return types.
    // Note: This is a conceptual representation of how the generated code is used.
// The actual usage involves using the derive macro on a struct or using the Function generator.

// Example of what the generated module looks like in practice:
// If you have a function named 'hello' with an Address input and Uint output:

// hello::encode_input(some_address);
// let output_bytes = ...;
// let result: ethabi::Uint = hello::decode_output(&output_bytes)?; 
// let (input, decoder) = hello::call(some_address);

  7. How event filtering works in generated code

    master

    When using the generated filter function, you provide values for the indexed parameters of the event. The generated code wraps these values into an ethabi::RawTopicFilter.

    If a parameter is not provided or you want to match any value, you can use wildcard_filter(), which internally uses ethabi::Topic::Any for all indexed slots.

    Example of using a specific filter:

    // Assuming 'foo' is an indexed Address parameter
let filter = many::filter(some_address);

  8. Decode ABI call results and parameters

    master

    The ethabi CLI can decode hex-encoded data back into human-readable formats using three different methods:

    Decode a function output

    Use decode function. Requires the ABI file, the function name or signature, and the hex-encoded data.

    Decode raw parameters

    Use decode params. Requires the types (e.g., -t uint256) and the hex-encoded data.

    Decode an event log

    Use decode log. Requires the ABI file, the event name or signature, the topics (hex-encoded), and the event data.

    Note on Topics: For event logs, use the -l flag to specify one or more topics.

    # Decode a function output from an ABI file
ethabi decode function ./contract.abi transfer(address,uint256) 0x...

# Decode raw parameters
ethabi decode params -t bool -t uint256 00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000064

# Decode an event log
ethabi decode log ./contract.abi Transfer -l 0xtopic1 0xtopic2 0xdata

  9. Encode ABI calls and parameters

    master

    The ethabi CLI provides two ways to encode data: using a JSON ABI file to encode specific contract functions, or providing types inline to encode raw parameters.

    Encode a contract function

    Use the encode function command. You must provide the path to the ABI file and either the function name or the full signature. Use -p to provide the parameter values.

    Encode raw parameters

    Use the encode params command. You must provide pairs of types and values using the -v flag.

    Note on Lenient Mode: Using the --lenient flag allows for shorter representations of input parameters (e.g., using 1 for true or decimal forms for numbers).

    # Encode a function from an ABI file
ethabi encode function ./contract.abi transfer(address,uint256) -p 0x123... 100

# Encode raw parameters with types
ethabi encode params -v bool true -v uint256 100

# Encode raw parameters using lenient mode (decimal numbers)
ethabi encode params -v uint256 100 --lenient

  10. Examples of ethabi encoding and decoding

    master

    Common usage patterns for the ethabi CLI tool.

    # Encode a boolean
ethabi encode params -v bool 1

# Encode multiple types (bool, string, bool)
ethabi encode params -v bool 1 -v string gavofyork -v bool 0

# Encode an array of booleans
ethabi encode params -v bool[] [1,0,false]

# Encode a tuple (string, bool, string)
ethabi encode params -v '(string,bool,string)' '(test,1,cyborg)'

# Decode a boolean
ethabi decode params -t bool 0000000000000000000000000000000000000000000000000000000000000001

# Decode a tuple
ethabi decode params -t '(string,bool,string)' 0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000674657374000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000066379626f72670000000000000000000000000000000000000000000000000000000000000000

  11. Configure `EthabiContract` via `ethabi_contract_options`

    master

    The EthabiContract derive macro accepts a helper attribute ethabi_contract_options to configure how the contract is generated.

    Currently, it supports the following option:

    OptionTypeDescription
    pathStringThe relative path to the ABI JSON file, resolved from the CARGO_MANIFEST_DIR

    Syntax Example: #[ethabi_contract_options(path = "path/to/abi.json")]

  12. Reference: ethabi-cli commands and options

    master

    The ethabi-cli provides several commands for encoding and decoding Ethereum ABI data.

    Usage:
    ethabi encode function <abi-path> <function-name-or-signature> [-p <param>]... [-l | --lenient]
    ethabi encode params [-v <type> <param>]... [-l | --lenient]
    ethabi decode function <abi-path> <function-name-or-signature> <data>
    ethabi decode params [-t <type>]... <data>
    ethabi decode log <abi-path> <event-name-or-signature> [-l <topic>]... <data>
    ethabi -h | --help

Options:
    -h, --help         Display this message and exit.
    -l, --lenient      Allow short representation of input params.

Commands:
    encode             Encode ABI call.
    decode             Decode ABI call result.
    function           Load function from json ABI file.
    params             Specify types of input params inline.
    log                Decode event log.