@ethereumjs/rlp

@ethereumjs/rlp v10

Recursive Length Prefix encoding for Node.js and the browser.

RLP serializes nested byte arrays — the wire format behind Ethereum transactions, blocks, and trie nodes. This package exposes a small encode / decode API plus lightweight byte helpers that do not depend on @ethereumjs/util.

Runnable examples live in examples/.

Table of Contents

• Installation
• Getting Started
• Scalar Input Types
• Stream Decoding
• CLI
• Browser
• API
• EthereumJS
• License

Installation

npm install @ethereumjs/rlp

Install with -g if you want to use the CLI.

Getting Started

// ./examples/encodeDecode.ts

import { RLP } from '@ethereumjs/rlp'

const nestedList = [[], [[]], [[], [[]]]]
const encoded = RLP.encode(nestedList)
const decoded = RLP.decode(encoded)

console.log(`Encoded ${encoded.length} bytes`)
console.log(`Decoded top-level is array: ${Array.isArray(decoded)}`)

RLP.encode() accepts nested arrays of scalars (see below) and always returns a Uint8Array. RLP.decode() returns a NestedUint8Array — nested lists of Uint8Array leaves.

Scalar Input Types

Strings, numbers, bigint, and 0x-prefixed hex are accepted on encode. Each scalar becomes a byte string in the output.

// ./examples/scalarTypes.ts

import { RLP, utils } from '@ethereumjs/rlp'

const { bytesToHex } = utils

// Strings, numbers, bigint, and 0x-prefixed hex all encode to Uint8Array output
console.log(`encode('dog'): ${bytesToHex(RLP.encode('dog'))}`)
console.log(`encode(15): ${bytesToHex(RLP.encode(15))}`)
console.log(`encode(15n): ${bytesToHex(RLP.encode(15n))}`)
console.log(`encode('0x01'): ${bytesToHex(RLP.encode('0x01'))}`)
console.log(`encode(['cat','dog']): ${bytesToHex(RLP.encode(['cat', 'dog']))}`)

Stream Decoding

Pass stream: true to decode only the first RLP item and receive the unconsumed remainder. Useful when a buffer holds multiple back-to-back RLP values.

The package also exports RLP.utils (hexToBytes, bytesToHex, utf8ToBytes, concatBytes) for byte work without pulling in @ethereumjs/util.

// ./examples/decodeStream.ts

import { RLP, utils } from '@ethereumjs/rlp'

const { bytesToHex, concatBytes, hexToBytes } = utils

// Stream mode decodes the first RLP item and returns the remainder buffer
const buffer = concatBytes(RLP.encode(1), RLP.encode('hello'), RLP.encode([2, 3]))

let decoded = RLP.decode(buffer, true)
console.log(`item 1: ${bytesToHex(decoded.data as Uint8Array)}`)

decoded = RLP.decode(decoded.remainder, true)
console.log(`item 2: ${new TextDecoder().decode(decoded.data as Uint8Array)}`)

decoded = RLP.decode(decoded.remainder, true)
const list = decoded.data as Uint8Array[]
console.log(`item 3: [${list.map((x) => bytesToHex(x)).join(', ')}]`)
console.log(`remainder length: ${decoded.remainder.length}`)

// utils: hex ↔ bytes without pulling in @ethereumjs/util
console.log(`hexToBytes('0x05'): ${bytesToHex(hexToBytes('0x05'))}`)

By default, decode() throws if trailing bytes remain after the first RLP sequence.

CLI

When installed globally:

rlp encode '<JSON string>'
rlp decode <0x-prefixed hex string>

Examples:

• rlp encode '5' → 0x05
• rlp encode '[5]' → 0xc105
• rlp encode '["cat", "dog"]' → 0xc88363617483646f67
• rlp decode 0xc88363617483646f67 → ["cat","dog"]

Browser

We provide hybrid ESM/CJS builds for all our libraries. With the v10 breaking release round from Spring 2025, all libraries are "pure-JS" by default and we have eliminated all hard-wired WASM code. Additionally we have substantially lowered the bundle sizes, reduced the number of dependencies, and cut out all usages of Node.js-specific primitives (like the Node.js event emitter).

It is easily possible to run a browser build of one of the EthereumJS libraries within a modern browser using the provided ESM build. For a setup example see ./examples/browser.html.

API

RLP.encode(input)

RLP-encodes an Array, Uint8Array, string, number, bigint, or null/undefined and returns a Uint8Array.

RLP.decode(input, stream?)

Decodes an RLP-encoded Uint8Array, Array, or string. Returns a Uint8Array or NestedUint8Array. With stream: true, returns { data, remainder } and decodes only the first sequence.

RLP.utils

• hexToBytes(hex) — parse a hex string (with or without 0x) to Uint8Array
• bytesToHex(bytes) — format bytes as a 0x-prefixed hex string
• utf8ToBytes(str) — encode a UTF-8 string to bytes
• concatBytes(...arrays) — concatenate byte arrays

Types: Input, NestedUint8Array, Decoded. See source.

EthereumJS

The EthereumJS GitHub organization and its repositories are managed by members of the former Ethereum Foundation JavaScript team and the broader Ethereum community. If you want to join for work or carry out improvements on the libraries see the developer docs for an overview of current standards and tools and review our code of conduct.

License

MPL-2.0