eth-abi

By default, the StringDecoder uses errors='strict', which causes a UnicodeDecodeError if a string contains bytes that are not valid UTF-8.

To handle malformed strings, you can register new type names that use a different handle_string_errors strategy. This is done by registering the standard TextStringEncoder paired with a StringDecoder configured with one of the following Python error handling options:

• surrogateescape
• ignore
• replace
• backslashreplace

Note: This customization is only available for decoding operations.

from eth_abi import decode, encode
from eth_abi.decoding import StringDecoder
from eth_abi.encoding import TextStringEncoder
from eth_abi.registry import registry

# Setup a malformed string for testing
test_string = encode(["string"], ["cat"])
bad_string = test_string[:65] + b"\xff" + test_string[66:]

# Register custom handlers
registry.register(
    "surrogateescape_string",
    TextStringEncoder,
    StringDecoder(handle_string_errors="surrogateescape")
)
registry.register(
    "backslashreplace_string",
    TextStringEncoder,
    StringDecoder(handle_string_errors="backslashreplace")
)

# Use the custom types to decode without error
assert decode(["surrogateescape_string"], bad_string) == ("c\udcfft",)
assert decode(["backslashreplace_string"], bad_string) == ("c\\xfft",)

# Cleanup
registry.unregister('surrogateescape_string')
registry.unregister('backslashreplace_string')

If you need to add new types or modify existing type support without affecting the global default registry, you can create a new ABIRegistry instance, register your custom coders, and pass that registry to an ABICodec instance. This allows you to use the standard encoding and decoding API with your custom type definitions.

from eth_abi.codec import ABICodec
from eth_abi.exceptions import EncodingError, DecodingError
from eth_abi.registry import ABIRegistry

# Define and register the coders
NULL_ENCODING = b'\x00' * 32

def encode_null(x):
    if x is not None:
        raise EncodingError('Unsupported value')
    return NULL_ENCODING

def decode_null(stream):
    if stream.read(32) != NULL_ENCODING:
        raise DecodingError('Not enough data or wrong data')
    return None

registry = ABIRegistry()
registry.register('null', encode_null, decode_null)

# Use the custom registry with ABICodec
codec = ABICodec(registry)

# Encoding/Decoding works with the custom type
assert codec.encode(['null'], [None]) == NULL_ENCODING
(decoded_null_val,) = codec.decode(['null'], NULL_ENCODING)
assert decoded_null_val is None

For types that require parameters extracted from the type string (e.g., null2 where 2 is a width), you should register custom classes that inherit from BaseEncoder and BaseDecoder.

To implement this pattern:

1. Matcher Function: Instead of a literal string, pass a function to registry.register that returns True if the type string matches (e.g., lambda x: x.startswith('null')).
2. from_type_str Class Method: Implement this method on both classes to parse the type string and return an instance of the class with the necessary settings.
3. Settings via __init__: Any keyword arguments passed to the constructor via from_type_str are automatically assigned to class properties of the same name (inherited from BaseCoder).
4. encode and decode: Implement these methods to perform the actual logic using the instance's settings.
5. validate_value: For BaseEncoder subclasses, implement this method to allow is_encodable to check compatibility without performing a full encoding.

from eth_abi.decoding import BaseDecoder
from eth_abi.encoding import BaseEncoder
from eth_abi.exceptions import EncodingError, DecodingError
from eth_abi.registry import registry
from eth_abi import encode, decode

NULL_ENCODING = b'\x00' * 32

class EncodeNull(BaseEncoder):
    word_width = None

    @classmethod
    def from_type_str(cls, type_str, registry):
        # Extract width from 'null2' -> 2
        word_width = int(type_str[4:])
        return cls(word_width=word_width)

    def encode(self, value):
        self.validate_value(value)
        return NULL_ENCODING * self.word_width

    def validate_value(self, value):
        if value is not None:
            raise EncodingError('Unsupported value')

class DecodeNull(BaseDecoder):
    word_width = None

    @classmethod
    def from_type_str(cls, type_str, registry):
        word_width = int(type_str[4:])
        return cls(word_width=word_width)

    def decode(self, stream):
        byts = stream.read(32 * self.word_width)
        if byts != NULL_ENCODING * self.word_width:
            raise DecodingError('Not enough data or wrong data')
        return None

# Register using a matcher function and a label for easy unregistering
registry.register(
    lambda x: x.startswith('null'),
    EncodeNull,
    DecodeNull,
    label='null',
)

# Usage
assert encode(['null2'], [None]) == NULL_ENCODING * 2
(decoded_null_val,) = decode(['null2'], NULL_ENCODING * 2)
assert decoded_null_val is None

# Cleanup
registry.unregister('null')

The eth-abi library uses a central registry to route encoding and decoding operations. You can add support for new, simple ABI types by registering two callables (one for encoding and one for decoding) to a specific type string. This works for exact matches and when the type appears within compound types (like tuples).

Note: The registry will raise an exception if more than one registration matches a query. Ensure your custom types do not conflict with existing ones.

from eth_abi.exceptions import EncodingError, DecodingError
from eth_abi.registry import registry
from eth_abi import encode, decode

# 1. Define the logic
NULL_ENCODING = b'\x00' * 32

def encode_null(x):
    if x is not None:
        raise EncodingError('Unsupported value')
    return NULL_ENCODING

def decode_null(stream):
    if stream.read(32) != NULL_ENCODING:
        raise DecodingError('Not enough data or wrong data')
    return None

# 2. Register the type string
registry.register('null', encode_null, decode_null)

# 3. Use it
assert encode(['null'], [None]) == NULL_ENCODING
(decoded_null_val,) = decode(['null'], NULL_ENCODING)
assert decoded_null_val is None

# Cleanup
registry.unregister('null')