Nethereum.RLP 5.8.0

Nethereum.RLP

Recursive Length Prefix (RLP) encoding and decoding for Ethereum data serialization.

Overview

Nethereum.RLP implements Ethereum's primary data serialization format. RLP encodes arbitrarily nested arrays of binary data into a compact byte representation. It is used throughout Ethereum for encoding transactions, blocks, state tries, and network messages.

Key Features

• Encode Elements: Encode single items (bytes, strings, integers) to RLP format
• Encode Lists: Encode collections and nested structures to RLP format
• Decode RLP: Deserialize RLP-encoded data back to elements or collections
• Type Conversions: Extension methods for encoding/decoding int, BigInteger, and string types
• Ethereum Compatibility: Full compliance with Ethereum's RLP specification

Installation

dotnet add package Nethereum.RLP

Dependencies

• Nethereum.Hex - Hexadecimal encoding/decoding

Key Concepts

What is RLP?

RLP (Recursive Length Prefix) is a space-efficient encoding method for arbitrarily nested arrays of binary data. It is the main encoding method used to serialize objects in Ethereum.

Key Principles:

• RLP only encodes structure (nested arrays)
• Atomic data types (integers, strings) are encoded as byte arrays
• Integers are represented in big-endian binary form
• Zero-valued bytes are trimmed from the front of integers

RLP Encoding Rules

Single Bytes (0x00 - 0x7f)

For a single byte whose value is in the [0x00, 0x7f] range, that byte is its own RLP encoding.

// Character 'd' (0x64) encodes as itself
RLP.EncodeElement(new byte[] { 0x64 }); // Result: [0x64]

Short Strings (0-55 bytes)

If a string is 0-55 bytes long, the RLP encoding consists of a single byte with value 0x80 plus the length of the string, followed by the string.

// "dog" = 3 bytes
// Encoded as: 0x83 (0x80 + 3) + "dog" bytes
// Result: 0x83646f67

Long Strings (>55 bytes)

If a string is more than 55 bytes long, the RLP encoding consists of:

• Single byte with value 0xb7 plus the length of the length
• The length of the string
• The string itself

// 56-byte string encodes with 0xb8 prefix
// 0xb8 (0xb7 + 1) + 0x38 (length = 56) + string bytes

Short Lists (0-55 bytes total payload)

Lists with total payload 0-55 bytes use a single byte with value 0xc0 plus the length, followed by concatenated RLP encodings of items.

// ["cat", "dog"]
// Encoded: 0xc8 + RLP("cat") + RLP("dog")

Long Lists (>55 bytes total payload)

Lists with payload >55 bytes use 0xf7 plus length-of-length encoding, similar to long strings.

RLP Elements

• RLPItem: Represents a single encoded value (byte array)
• RLPCollection: Represents a list of RLP elements (can contain RLPItems or nested RLPCollections)

Quick Start

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// Encode a string
string text = "dog";
byte[] textBytes = text.ToBytesForRLPEncoding();
byte[] encoded = RLP.EncodeElement(textBytes);
// Result: 0x83646f67

// Encode an integer
int number = 1000;
byte[] numberBytes = number.ToBytesForRLPEncoding();
byte[] encodedNum = RLP.EncodeElement(numberBytes);
// Result: 0x8203e8

// Encode a list
string[] items = { "cat", "dog" };
byte[][] itemBytes = items.ToBytesForRLPEncoding();
byte[][] encodedItems = new byte[itemBytes.Length][];
for (int i = 0; i < itemBytes.Length; i++)
{
    encodedItems[i] = RLP.EncodeElement(itemBytes[i]);
}
byte[] encodedList = RLP.EncodeList(encodedItems);
// Result: 0xc88363617483646f67

// Decode RLP
IRLPElement decoded = RLP.Decode(encoded);
string decodedText = decoded.RLPData.ToStringFromRLPDecoded();
// Result: "dog"

Usage Examples

Example 1: Encoding Strings

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// Empty string
string empty = "";
byte[] emptyBytes = empty.ToBytesForRLPEncoding();
byte[] encoded = RLP.EncodeElement(emptyBytes);
// Result: 0x80

// Single character
string single = "d";
byte[] singleBytes = single.ToBytesForRLPEncoding();
byte[] encodedSingle = RLP.EncodeElement(singleBytes);
// Result: 0x64 (single byte in range 0x00-0x7f encodes as itself)

// Short string
string dog = "dog";
byte[] dogBytes = dog.ToBytesForRLPEncoding();
byte[] encodedDog = RLP.EncodeElement(dogBytes);
Assert.Equal("83646f67", encodedDog.ToHex());

// Decode back
IRLPElement decoded = RLP.Decode(encodedDog);
string decodedStr = decoded.RLPData.ToStringFromRLPDecoded();
Assert.Equal("dog", decodedStr);

Example 2: Encoding Integers

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// Zero encodes as empty byte array
int zero = 0;
byte[] zeroBytes = zero.ToBytesForRLPEncoding();
byte[] encodedZero = RLP.EncodeElement(zeroBytes);
// Result: 0x80 (empty byte array)

// Small integer (< 128)
int small = 15;
byte[] smallBytes = small.ToBytesForRLPEncoding();
byte[] encodedSmall = RLP.EncodeElement(smallBytes);
// Result: 0x0f (single byte in range encodes as itself)

// Medium integer
int medium = 1000;
byte[] mediumBytes = medium.ToBytesForRLPEncoding();
byte[] encodedMedium = RLP.EncodeElement(mediumBytes);
Assert.Equal("8203e8", encodedMedium.ToHex());

// Decode back
IRLPElement decoded = RLP.Decode(encodedMedium);
int decodedInt = decoded.RLPData.ToIntFromRLPDecoded();
Assert.Equal(1000, decodedInt);

Example 3: Encoding BigInteger

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;
using System.Numerics;

// Large BigInteger
byte[] hexBytes = "100102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
    .HexToByteArray();
BigInteger bigInt = hexBytes.ToBigIntegerFromRLPDecoded();

byte[] bigIntBytes = bigInt.ToBytesForRLPEncoding();
byte[] encoded = RLP.EncodeElement(bigIntBytes);
Assert.Equal(
    "a0100102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
    encoded.ToHex()
);

// Decode back
IRLPElement decoded = RLP.Decode(encoded);
BigInteger decodedBigInt = decoded.RLPData.ToBigIntegerFromRLPDecoded();
Assert.Equal(bigInt, decodedBigInt);

Example 4: Encoding Lists

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// Empty list
byte[][] emptyList = new byte[0][];
byte[] encodedEmpty = RLP.EncodeList(emptyList);
Assert.Equal("c0", encodedEmpty.ToHex());

RLPCollection decodedEmpty = RLP.Decode(encodedEmpty) as RLPCollection;
Assert.Equal(0, decodedEmpty.Count);

// Short string list
string[] strings = { "cat", "dog" };
byte[][] stringBytes = strings.ToBytesForRLPEncoding();

// Encode each element
byte[][] encodedElements = new byte[stringBytes.Length][];
for (int i = 0; i < stringBytes.Length; i++)
{
    encodedElements[i] = RLP.EncodeElement(stringBytes[i]);
}

// Encode the list
byte[] encodedList = RLP.EncodeList(encodedElements);
Assert.Equal("c88363617483646f67", encodedList.ToHex());

// Decode back
RLPCollection decodedList = RLP.Decode(encodedList) as RLPCollection;
Assert.Equal("cat", decodedList[0].RLPData.ToStringFromRLPDecoded());
Assert.Equal("dog", decodedList[1].RLPData.ToStringFromRLPDecoded());

Example 5: Encoding Long Strings

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// String longer than 55 bytes
string longString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit"; // 56 bytes
byte[] longBytes = longString.ToBytesForRLPEncoding();
byte[] encoded = RLP.EncodeElement(longBytes);

// Result starts with 0xb8 (0xb7 + 1 for length-of-length)
// followed by 0x38 (length = 56 in hex)
// followed by the string bytes
Assert.Equal(
    "b8384c6f72656d20697073756d20646f6c6f722073697420616d65742c20636f6e7365637465747572206164697069736963696e6720656c6974",
    encoded.ToHex()
);

// Decode back
IRLPElement decoded = RLP.Decode(encoded);
string decodedStr = decoded.RLPData.ToStringFromRLPDecoded();
Assert.Equal(longString, decodedStr);

Example 6: Mixed List with Long String

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// List containing short and long strings
string short = "cat";
string long = "Lorem ipsum dolor sit amet, consectetur adipisicing elit";
string[] mixed = { short, long };

byte[][] mixedBytes = mixed.ToBytesForRLPEncoding();

// Encode each element
byte[][] encodedElements = new byte[mixedBytes.Length][];
for (int i = 0; i < mixedBytes.Length; i++)
{
    encodedElements[i] = RLP.EncodeElement(mixedBytes[i]);
}

// Encode the list
byte[] encodedList = RLP.EncodeList(encodedElements);
Assert.Equal(
    "f83e83636174b8384c6f72656d20697073756d20646f6c6f722073697420616d65742c20636f6e7365637465747572206164697069736963696e6720656c6974",
    encodedList.ToHex()
);

// Decode back
RLPCollection decoded = RLP.Decode(encodedList) as RLPCollection;
Assert.Equal("cat", decoded[0].RLPData.ToStringFromRLPDecoded());
Assert.Equal(long, decoded[1].RLPData.ToStringFromRLPDecoded());

Example 7: Multiple String List

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// List with three short strings
string[] animals = { "dog", "god", "cat" };
byte[][] animalBytes = animals.ToBytesForRLPEncoding();

byte[][] encodedElements = new byte[animalBytes.Length][];
for (int i = 0; i < animalBytes.Length; i++)
{
    encodedElements[i] = RLP.EncodeElement(animalBytes[i]);
}

byte[] encodedList = RLP.EncodeList(encodedElements);
Assert.Equal("cc83646f6783676f6483636174", encodedList.ToHex());

// Decode and verify
RLPCollection decoded = RLP.Decode(encodedList) as RLPCollection;
for (int i = 0; i < animals.Length; i++)
{
    Assert.Equal(animals[i], decoded[i].RLPData.ToStringFromRLPDecoded());
}

Example 8: Working with Raw Bytes

using Nethereum.RLP;
using Nethereum.Hex.HexConvertors.Extensions;

// Encode raw byte array
byte[] data = new byte[] { 0x01, 0x02, 0x03, 0x04 };
byte[] encoded = RLP.EncodeElement(data);

// Decode
IRLPElement decoded = RLP.Decode(encoded);
byte[] decodedBytes = decoded.RLPData;

Assert.Equal(data, decodedBytes);

// Empty byte array
byte[] empty = new byte[0];
byte[] encodedEmpty = RLP.EncodeElement(empty);
Assert.Equal("80", encodedEmpty.ToHex());

IRLPElement decodedEmpty = RLP.Decode(encodedEmpty);
Assert.Null(decodedEmpty.RLPData); // Empty encodes/decodes as null

API Reference

RLP Class

Main class for encoding and decoding RLP data.

public class RLP
{
    // Constants
    public const byte OFFSET_SHORT_LIST = 0xc0;
    public static readonly byte[] EMPTY_BYTE_ARRAY = new byte[0];
    public static readonly byte[] ZERO_BYTE_ARRAY = { 0 };

    // Encoding
    public static byte[] EncodeElement(byte[] srcData);
    public static byte[] EncodeList(params byte[][] elements);

    // Decoding
    public static IRLPElement Decode(byte[] data);
    public static IRLPElement Decode(byte[] data, int position);

    // Utilities
    public static int ByteArrayToInt(byte[] bytes);
    public static byte[] IntToByteArray(int value);
}

IRLPElement Interface

Base interface for RLP elements.

public interface IRLPElement
{
    byte[] RLPData { get; }
}

RLPItem Class

Represents a single RLP-encoded value.

public class RLPItem : IRLPElement
{
    public byte[] RLPData { get; }
}

RLPCollection Class

Represents a list of RLP elements (can be nested).

public class RLPCollection : List<IRLPElement>, IRLPElement
{
    public byte[] RLPData { get; }

    // List operations via base class
    public int Count { get; }
    public IRLPElement this[int index] { get; }
}

Conversion Extension Methods

Extensions for converting types to/from RLP encoding.

public static class ConvertorForRLPEncodingExtensions
{
    // Encoding (to bytes for RLP)
    public static byte[] ToBytesForRLPEncoding(this int number);
    public static byte[] ToBytesForRLPEncoding(this long number);
    public static byte[] ToBytesForRLPEncoding(this BigInteger bigInteger);
    public static byte[] ToBytesForRLPEncoding(this string str);
    public static byte[][] ToBytesForRLPEncoding(this string[] strings);

    // Decoding (from RLP bytes)
    public static int ToIntFromRLPDecoded(this byte[] bytes);
    public static long ToLongFromRLPDecoded(this byte[] bytes);
    public static BigInteger ToBigIntegerFromRLPDecoded(this byte[] bytes);
    public static string ToStringFromRLPDecoded(this byte[] bytes);

    // Utilities
    public static byte[] TrimZeroBytes(this byte[] bytes);
}

Related Packages

Used By (Consumers)

RLP is used throughout Nethereum for Ethereum data encoding:

• Nethereum.Signer - Transaction and message signing uses RLP encoding
• Nethereum.Model - Transaction and block models use RLP
• Nethereum.Util - Address derivation uses RLP encoding
• Nethereum.Merkle.Patricia - Patricia Merkle Trie uses RLP for nodes
• Nethereum.RPC - Some RPC methods work with RLP-encoded data
• Nethereum.Consensus - Consensus layer data structures use RLP

Dependencies

• Nethereum.Hex - Hexadecimal encoding/decoding for displaying RLP data

Important Notes

Encoding Behavior

Empty Values

• Empty string/byte array encodes as 0x80
• Decoded empty value returns null
• Zero integer encodes as 0x80 (empty byte array)

var empty = RLP.EncodeElement(new byte[0]);
// Result: 0x80

var decoded = RLP.Decode(empty);
// Result: decoded.RLPData == null

Single Bytes

Single bytes in range 0x00-0x7f encode as themselves:

// Character 'd' (0x64) encodes as itself
var encoded = RLP.EncodeElement(new byte[] { 0x64 });
// Result: [0x64]

Big-Endian Encoding

All integers are encoded in big-endian format with leading zeros trimmed:

int value = 1000; // 0x000003e8
var bytes = value.ToBytesForRLPEncoding();
// Result: [0x03, 0xe8] (leading zeros removed)

Threshold Values

The RLP specification uses specific threshold values:

• 56 bytes: Threshold between short and long item encoding
  • 0-55 bytes: Use single-byte length prefix (0x80-0xb7 or 0xc0-0xf7)
  • 56+ bytes: Use length-of-length prefix (0xb8+ or 0xf8+)

Decoding Collections

When decoding, check the element type:

var decoded = RLP.Decode(encoded);

if (decoded is RLPCollection collection)
{
    // It's a list - iterate items
    foreach (var item in collection)
    {
        var value = item.RLPData;
    }
}
else
{
    // It's a single item
    var value = decoded.RLPData;
}

Null vs Empty

• Decoded empty items return null for RLPData
• Check for null before using decoded data:

var decoded = RLP.Decode(encoded);
string str = decoded.RLPData?.ToStringFromRLPDecoded() ?? "";

Common Use Cases

Transaction Encoding

Ethereum transactions are RLP-encoded:

// Transaction: [nonce, gasPrice, gasLimit, to, value, data, v, r, s]
var transaction = new List<byte[]>
{
    nonce.ToBytesForRLPEncoding(),
    gasPrice.ToBytesForRLPEncoding(),
    gasLimit.ToBytesForRLPEncoding(),
    to.HexToByteArray(),
    value.ToBytesForRLPEncoding(),
    data.HexToByteArray(),
    v.ToBytesForRLPEncoding(),
    r,
    s
};

var encodedElements = transaction.Select(RLP.EncodeElement).ToArray();
var rlpTransaction = RLP.EncodeList(encodedElements);

Block Header Encoding

Block headers use RLP for hashing:

// Block header fields encoded as RLP list
var headerFields = new List<byte[]>
{
    parentHash,
    unclesHash,
    beneficiary,
    stateRoot,
    transactionsRoot,
    receiptsRoot,
    logsBloom,
    difficulty.ToBytesForRLPEncoding(),
    number.ToBytesForRLPEncoding(),
    gasLimit.ToBytesForRLPEncoding(),
    gasUsed.ToBytesForRLPEncoding(),
    timestamp.ToBytesForRLPEncoding(),
    extraData,
    mixHash,
    nonce
};

var encodedHeader = RLP.EncodeList(
    headerFields.Select(RLP.EncodeElement).ToArray()
);

Additional Resources

• Ethereum RLP Specification
• Ethereum Wiki - RLP
• Ethereum Yellow Paper (Appendix B - RLP)
• Nethereum Documentation