or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

@ethersproject/rlp

RLP (Recursive-Length Prefix) is a serialization method used throughout the Ethereum ecosystem to encode arbitrarily nested arrays of binary data. This package provides complete implementation of RLP encoding and decoding for JavaScript/TypeScript applications.

RLP Specification: Based on the official Ethereum RLP specification

Package Information

Package Name: @ethersproject/rlp
Package Type: npm
Language: TypeScript
Installation: npm install @ethersproject/rlp

Core Imports

import { encode, decode } from "@ethersproject/rlp";

For CommonJS:

const { encode, decode } = require("@ethersproject/rlp");

Basic Usage

import { encode, decode } from "@ethersproject/rlp";

// Encoding simple data
const encoded = encode("hello");
console.log(encoded); // "0x8568656c6c6f"

// Encoding nested arrays
const encodedArray = encode(["cat", ["puppy", "cow"], "horse"]);
console.log(encodedArray); // RLP-encoded hex string

// Decoding RLP data
const decoded = decode("0x8568656c6c6f");
console.log(decoded); // "0x68656c6c6f"

// Decoding nested structures
const decodedArray = decode(encodedArray);
console.log(decodedArray); // ["0x636174", ["0x7075707079", "0x636f77"], "0x686f727365"]

Capabilities

RLP Encoding

Converts JavaScript objects and arrays into RLP-encoded hex strings following the Ethereum RLP specification.

/**
 * Encodes a JavaScript value into RLP format
 * @param object - The value to encode (arrays, strings, or BytesLike data)
 * @returns Hex string representing the RLP-encoded data
 * @throws ArgumentError if object is not BytesLike when expected
 */
function encode(object: any): string;

Supported Input Types:

Arrays: Nested arrays of any depth containing encodable values
Strings: UTF-8 strings (converted to bytes automatically)
BytesLike: Hex strings, Uint8Array, Buffer, or other byte-like data
Numbers: Automatically converted to byte representation

RLP Encoding Rules:

Single bytes (0x00-0x7f): Encoded as themselves
Short strings (0-55 bytes): Length prefix + data
Long strings (56+ bytes): Length-of-length prefix + length + data
Short lists (0-55 bytes total): List prefix + concatenated encoded items
Long lists (56+ bytes total): List prefix + length encoding + concatenated items

Usage Examples:

// String encoding
const str = encode("hello");
// Result: "0x8568656c6c6f"

// Array encoding
const arr = encode(["cat", "dog"]);
// Result: RLP-encoded array as hex string

// Nested array encoding
const nested = encode([["inner", "array"], "outer"]);
// Result: RLP-encoded nested structure

// Hex string encoding
const hex = encode("0x1234");
// Result: RLP-encoded hex data

// Mixed data types
const mixed = encode(["string", "0xabcd", ["nested", "items"]]);
// Result: RLP-encoded mixed structure

RLP Decoding

Parses RLP-encoded data back into JavaScript structures with full type preservation and error validation.

/**
 * Decodes RLP-encoded data back into JavaScript structures
 * @param data - RLP-encoded data as hex string, Uint8Array, or other BytesLike
 * @returns Decoded JavaScript object/array structure
 * @throws BUFFER_OVERRUN for malformed data
 * @throws ArgumentError for invalid RLP data
 */
function decode(data: BytesLike): any;

Return Types:

Strings: Decoded as hex strings (e.g., "0x68656c6c6f")
Arrays: Nested arrays maintaining original structure
Mixed Structures: Preserves nesting and data type relationships

Error Handling:

BUFFER_OVERRUN: When RLP data is truncated or malformed
ArgumentError: When input data is not valid RLP format
Detailed error messages for debugging malformed data

Usage Examples:

// Basic string decoding
const decoded = decode("0x8568656c6c6f");
// Result: "0x68656c6c6f" (hex representation of "hello")

// Array decoding
const arrayData = encode(["cat", "dog"]);
const decodedArray = decode(arrayData);
// Result: ["0x636174", "0x646f67"] (hex representations)

// Nested structure decoding
const nestedData = encode([["inner"], "outer"]);
const decodedNested = decode(nestedData);
// Result: [["0x696e6e6572"], "0x6f75746572"]

// Error handling
try {
  decode("0x invalid");
} catch (error) {
  // Handles ArgumentError for invalid RLP data
}

try {
  decode("0xc1"); // Incomplete list
} catch (error) {
  // Handles BUFFER_OVERRUN for truncated data
}

Types

/**
 * Represents data that can be converted to bytes
 * Imported from @ethersproject/bytes
 */
type BytesLike = string | Uint8Array | ArrayLike<number>;

Error Handling

The library uses @ethersproject/logger for consistent error reporting:

ArgumentError: Thrown when input parameters are invalid or unsupported
BUFFER_OVERRUN: Thrown when RLP data is malformed, truncated, or contains invalid length prefixes
Detailed Context: Error messages include specific information about what went wrong and where

Common Error Scenarios:

// Invalid input type for encoding
try {
  encode(new Date()); // Unsupported type
} catch (error) {
  // ArgumentError: "RLP object must be BytesLike"
}

// Malformed RLP data for decoding
try {
  decode("0xc2c1"); // Invalid nested structure
} catch (error) {
  // BUFFER_OVERRUN: "child data too short"
}

// Incomplete RLP data
try {
  decode("0xb8"); // Missing length and data
} catch (error) {
  // BUFFER_OVERRUN: "data array too short"
}

// Invalid RLP data format
try {
  decode("0x8568656c6c6f41"); // Extra bytes
} catch (error) {
  // ArgumentError: "invalid rlp data"
}

Integration with Ethereum Ecosystem

This package is part of the ethers.js ecosystem and is commonly used for:

Transaction Encoding: Serializing transaction data for Ethereum
Block Header Encoding: Encoding block header information
Merkle Patricia Trie: Data serialization for Ethereum's state trie
Contract Data: Encoding complex data structures for smart contracts
Network Protocol: Serializing data for Ethereum network communication

Example Ethereum Usage:

import { encode, decode } from "@ethersproject/rlp";

// Transaction component encoding
const txData = [
  "0x09", // nonce
  "0x4a817c800", // gasPrice
  "0x5208", // gasLimit
  "0x3535353535353535353535353535353535353535", // to
  "0x0de0b6b3a7640000", // value
  "0x" // data
];

const encodedTx = encode(txData);
// Result: RLP-encoded transaction ready for signing

// Decoding received RLP data
const receivedRlp = "0x..."; // From network or storage
const decodedTx = decode(receivedRlp);
// Result: Array of transaction components