eth-abi

5.2.0 · active · verified Thu Apr 09

The `eth-abi` library, currently at version 5.2.0, provides low-level Python utilities for converting Python values to and from Solidity's binary Application Binary Interface (ABI) format. It is a core component within the Ethereum development ecosystem, offering functionalities for encoding Python values into ABI-compliant bytes and decoding ABI bytes back into Python values for smart contract interaction. The library maintains an active release cadence with frequent updates, including bug fixes, new features, and Python version support, with major versions typically released annually or biannually.

Warnings

breaking Version 5.0.0 of `eth-abi` dropped support for Python 3.7. Users on older Python versions will need to upgrade their environment or stick to `eth-abi` versions < 5.0.0.
Fix: Upgrade Python to version 3.8 or higher, or pin `eth-abi<5.0.0`.
breaking Upcoming version 6.0.0 (currently in beta) will drop support for Python 3.8 and 3.9. Plan for future Python environment upgrades if targeting this version.
Fix: Upgrade Python to version 3.10 or higher when migrating to `eth-abi` v6.0.0.
gotcha The `decode` function defaults to `strict=True`, which performs validations such as ensuring data is padded to a multiple of 32 bytes and that padding bytes are zero. However, Solidity's ABI decoder operates with a behavior equivalent to `strict=False`, which ignores some of these validations. This difference can lead to unexpected errors if not handled, particularly when decoding data from contracts that might not adhere strictly to padding rules.
Fix: When decoding data from smart contracts, consider setting `strict=False` in the `decode` function if encountering padding or zero-byte validation errors, as this often aligns with how Solidity handles ABI decoding. Example: `decode(abi_types, encoded_data, strict=False)`.
gotcha Understanding the Ethereum ABI specification is crucial for correctly using `eth-abi`. Complex types (like dynamic arrays, strings, and tuples) have specific encoding rules, including how their data is positioned (head/tail mechanism) and padded to 32-byte boundaries. Misunderstanding these rules can lead to incorrect encoding or decoding.
Fix: Refer to the official Solidity ABI specification and `eth-abi` documentation for detailed explanations of type encoding and decoding rules, especially for dynamic and nested types.
gotcha Contract ABIs (Application Binary Interfaces) are not stored on the blockchain itself. To interact with a smart contract using `eth-abi` (or any web3 library), you need to obtain the contract's ABI from external sources. Common sources include block explorers (like Etherscan for verified contracts), the contract's official GitHub repository, or by compiling the contract's source code yourself.
Fix: Always ensure you have the correct and complete ABI for the target smart contract. If an ABI is unavailable or incorrect, interactions with the contract will fail or yield erroneous results.

Install

pip install eth-abi Install latest version

Imports

encode
```
from eth_abi import encode
```
Main function for encoding Python values into ABI bytes.
decode
```
from eth_abi import decode
```
Main function for decoding ABI bytes into Python values.
registry
```
from eth_abi import registry
```
Used for customizing encoding/decoding behavior for ABI types.

Quickstart

This quickstart demonstrates the core functionality of `eth-abi`: encoding a list of Python values (integers, addresses, booleans, strings) into a single ABI-compliant `bytes` object, and then decoding that `bytes` object back into a tuple of Python values. It also shows a simple `uint256` encoding/decoding example.

from eth_abi import encode, decode

# Define ABI types and corresponding Python values
abi_types = ['uint256', 'address', 'bool', 'string']
python_values = [123, '0x5B38Da6a701c568545dCfcB03FcB875f56beddC4', True, 'Hello eth-abi']

# Encode Python values into ABI-compliant bytes
encoded_data = encode(abi_types, python_values)
print(f"Encoded data: {encoded_data.hex()}")

# Decode ABI-compliant bytes back into Python values
decoded_values = decode(abi_types, encoded_data)
print(f"Decoded values: {decoded_values}")

# Example with a simple uint256
encoded_uint = encode(['uint256'], [1])
decoded_uint = decode(['uint256'], b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01')
print(f"Decoded single uint: {decoded_uint}")

view raw JSON →