RLP (Recursive Length Prefix)

4.1.0 · active · verified Thu Apr 09

RLP (Recursive Length Prefix) is a serialization format used extensively in Ethereum to encode arbitrarily nested arrays of binary data. The `rlp` Python library provides efficient functions for encoding Python objects (byte strings, integers, lists/tuples of these) into RLP byte strings and decoding them back. It is actively maintained by the Ethereum project. The current version is 4.1.0.

Warnings

breaking The output of `rlp.decode` now *always* returns bytes for byte-string elements (or integers for encoded numbers). In versions prior to 3.0.0, it might have returned `str` on Python 2 or behaved inconsistently regarding string types. This change enforces consistency with Python 3 byte strings.
Fix: Ensure your code expects `bytes` objects for string-like data after decoding. Use `decoded_item.decode('utf-8')` if you need a Python `str`.
gotcha When encoding, all string-like elements within lists or directly passed to `rlp.encode` must be byte strings (`bytes`). Passing a Python `str` (e.g., `'hello'`) will result in a `TypeError`.
Fix: Always convert `str` to `bytes` using `my_string.encode('utf-8')` (or another appropriate encoding) before passing to `rlp.encode`.
gotcha Be aware of the difference between encoding an integer and encoding a byte string representation of that integer. `rlp.encode(1)` results in `b'\x01'` (RLP for integer 1). `rlp.encode(b'\x01')` results in `b'\x81\x01'` (RLP for a byte string of length 1, whose value is `b'\x01'`). Decoding these yields `1` and `b'\x01'` respectively.
Fix: Understand RLP's type differentiation. If you intend to encode a number, pass an `int`. If you intend to encode raw bytes, pass `bytes`.
gotcha The RLP encodings for an empty list and an empty byte string are distinct. `rlp.encode([])` results in `b'\xc0'`. `rlp.encode(b'')` results in `b'\x80'`. They will decode back to `[]` and `b''` respectively. Confusing these can lead to incorrect data interpretation.
Fix: Explicitly use `[]` for an empty list and `b''` for an empty byte string to ensure the correct RLP encoding is generated.

Install

pip install rlp Install stable version

Imports

encode
```
from rlp import encode
```
The `encode` function is directly available at the top-level `rlp` module.
decode
```
from rlp import decode
```
The `decode` function is directly available at the top-level `rlp` module.
Serializable
```
from rlp import Serializable
```
While `Serializable` is part of the 'sedes' (serialization/deserialization) module internally, it is exposed directly from the top-level `rlp` package for convenience.

Quickstart

This quickstart demonstrates basic RLP encoding and decoding of byte strings, integers, and nested lists. It highlights how the library handles different data types automatically. Note that all string inputs must be byte strings (`b'...'`).

import rlp

# Encode a simple byte string
encoded_string = rlp.encode(b'ethereum')
print(f"Encoded 'ethereum': {encoded_string}")

# Decode it back
decoded_string = rlp.decode(encoded_string)
print(f"Decoded back: {decoded_string}")

# Encode a list of byte strings and integers
data = [b'dog', b'cat', b'elephant', 0, 15, 12345]
encoded_list = rlp.encode(data)
print(f"\nEncoded list: {encoded_list}")

# Decode the list
decoded_list = rlp.decode(encoded_list)
print(f"Decoded list: {decoded_list}")

# Encoding nested lists
nested_data = [b'a', [b'b', b'c'], [b'd', [b'e', b'f']]]
encoded_nested = rlp.encode(nested_data)
print(f"\nEncoded nested: {encoded_nested}")

decoded_nested = rlp.decode(encoded_nested)
print(f"Decoded nested: {decoded_nested}")

view raw JSON →