Codecs - Encoders and Decoders

Ethereum Contract ABIv2

For a definitive reference to the Ethereum contract ABIv2 specification, visit the solidity documentation.

eth.codecs.abi.encode(schema: str, value: Any) → bytes

Encode a value according to an ABI schema.

Parameters

schema – An ABI type string.
value – The value to encode.

Example

>>> encode("uint256", 42).hex()
'000000000000000000000000000000000000000000000000000000000000002a'
>>> encode("int128", -42).hex()
'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffd6'

Returns

The encoded value.

Raises

EncodeError – If value, or an element thereof, is not encodable.
ParseError – If schema is an invalid ABI type.

eth.codecs.abi.decode(schema: str, value: bytes, **kwargs) → Any

Decode a value according to an ABI schema.

Parameters

schema – An ABI type string.
value – The value to decode.
**kwargs – Additional keyword arguments to pass on to ABI type decoder functions.

Keyword Arguments

checksum (bool) – Whether to checksum encode decoded address values, defaults to True.

Example

>>> decode("uint256", encode("uint256", 42))
42
>>> decode("int128", encode("int128", -42))
-42

Returns

The decoded value.

Raises

DecodeError – If value, or an element thereof, is not decodable.
ParseError – If schema is an invalid ABI type.

Hypothesis Strategies

eth.codecs.abi.strategies.schema: hypothesis.strategies.SearchStrategy[str]

Generates a valid ABIv2 type schema (type string).

Example

>>> from eth.codecs.abi.strategies import schema as st_schema
>>> st_schema.example()
'(bytes18,uint168,bool,int240[])[3]'

eth.codecs.abi.strategies.value(schema: str) → hypothesis.strategies.SearchStrategy[Any]

Generate a valid ABIv2 encodable value for a given type schema.

Parameters: schema (str) – A valid ABIv2 type string.
Returns: An encodable value for the given schema.

Example

>>> from eth.codecs.abi.strategies import value as st_value
>>> st_value("(uint256,uint8,address[2])").example()
(163, 227, ['0x67BeeB3dCFa0498B362315501258878eCbE5DeC9', '0x67BeeB3dCFa0498B362315501258878eCbE5DeC9'])

eth.codecs.abi.strategies.schema_and_value(st_type: hypothesis.strategies.SearchStrategy | None) → hypothesis.strategies.SearchStrategy[tuple[str, Any]]

Generate a valid ABIv2 type schema and an encodable value for it.

If the st_type parameter is supplied, schemas will be generated using the supplied search strategy.

Parameters: st_type (hypothesis.strategies.SearchStrategy) – A search strategy which generates eth.codecs.abi.nodes.ABITypeNode
Returns: A tuple containing a valid ABIv2 type schema and a valid encodable value.

Example

>>> from eth.codecs.abi.strategies import schema_and_value as st_schema_and_value
>>> st_schema_and_value().example()
('bool[2][]', [[False, True], [False, False], [False, False], [False, True], [True, False], [True, False]])
>>> from eth.codecs.abi.strategies.nodes import Fixed as st_fixed
>>> st_schema_and_value(st_fixed).example()
('fixed96x75', Decimal('-1.6503499995656503835410387807E-47'))

Command Line Interface

The eth.codecs.abi package provides a simple command line interface for encoding and decoding values.

$ python -m eth.codecs.abi encode '(uint256[2])' '[[3, 3]]'
0x00000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000003
$ python -m eth.codecs.abi encode string '"Hello World!"'
0x000000000000000000000000000000000000000000000000000000000000000c48656c6c6f20576f726c6421
$ python -m eth.codecs.abi decode bytes4 '0x1232345800000000000000000000000000000000000000000000000000000000'
0x12323458

The value to be encoded/decoded should be quoted as a string to prevent any argument parsing errors.

Utilities

Additional encoder and decoder functions.

eth.codecs.utils.checksum_encode(addr: Union[str, bytes]) → str

Checksum encode an address.

See EIP-55.

Parameters

addr – The address to checksum encode.

Returns

The checksum encoded address.

Raises

TypeError – If addr argument is not an instance of str or bytes.
ValueError – If addr contains non-hexadecimal characters or is not the proper length.