RLP Decoding

Decode RLP-encoded bytes back to data structures

Try it Live

Run RLP examples in the interactive playground

RLP Decoding

Decode RLP-encoded bytes back to data structures with comprehensive validation and error handling.

Overview

RLP decoding parses compact byte representations back into nested data structures. The decoder performs comprehensive validation to ensure canonical encoding and prevent malformed input attacks.

Key Features:

• Canonical validation - Rejects non-minimal encodings
• Depth limiting - Prevents stack overflow on deeply nested data
• Stream support - Decode multiple values from a byte stream
• Detailed errors - Clear error messages for debugging

decode

Decodes RLP-encoded bytes into data structures.

Decoding Algorithm

RLP decoder uses the first byte (prefix) to determine data type and length:

Prefix Ranges

// Prefix byte determines encoding type:
// 0x00-0x7f: Single byte (value itself)
// 0x80-0xb7: Short string (0-55 bytes)
// 0xb8-0xbf: Long string (56+ bytes)
// 0xc0-0xf7: Short list (0-55 bytes total)
// 0xf8-0xff: Long list (56+ bytes total)

Single Byte (0x00-0x7f)

Bytes with value < 0x80 encode as themselves:

import { Rlp } from 'tevm'

const encoded = new Uint8Array([0x7f])
const result = Rlp.decode(encoded)
// => { data: { type: 'bytes', value: Uint8Array([0x7f]) }, remainder: Uint8Array([]) }

const zero = new Uint8Array([0x00])
const result = Rlp.decode(zero)
// => { data: { type: 'bytes', value: Uint8Array([0x00]) }, remainder: Uint8Array([]) }

Short String (0x80-0xb7)

Length encoded in prefix: length = prefix - 0x80

import { Rlp } from 'tevm'

// Empty string
const empty = new Uint8Array([0x80])
const result = Rlp.decode(empty)
// => { data: { type: 'bytes', value: Uint8Array([]) }, remainder: Uint8Array([]) }

// 3-byte string
const bytes = new Uint8Array([0x83, 1, 2, 3])
const result = Rlp.decode(bytes)
// 0x83 - 0x80 = 3 bytes
// => { data: { type: 'bytes', value: Uint8Array([1, 2, 3]) }, remainder: Uint8Array([]) }

// 55-byte string (maximum short form)
const max = new Uint8Array([0xb7, ...Array(55).fill(0x42)])
const result = Rlp.decode(max)
// 0xb7 - 0x80 = 55 bytes

Long String (0xb8-0xbf)

Length-of-length encoding: lengthOfLength = prefix - 0xb7

import { Rlp } from 'tevm'

// 56-byte string (minimum long form)
const min = new Uint8Array([0xb8, 56, ...Array(56).fill(0x42)])
const result = Rlp.decode(min)
// 0xb8 - 0xb7 = 1 (length needs 1 byte)
// Next byte: 56 = actual length
// => { data: { type: 'bytes', value: Uint8Array(56).fill(0x42) }, remainder: Uint8Array([]) }

// 256-byte string (length needs 2 bytes)
const large = new Uint8Array([0xb9, 0x01, 0x00, ...Array(256).fill(0x42)])
const result = Rlp.decode(large)
// 0xb9 - 0xb7 = 2 (length needs 2 bytes)
// Next 2 bytes: [0x01, 0x00] = 256
// => { data: { type: 'bytes', value: Uint8Array(256).fill(0x42) }, remainder: Uint8Array([]) }

Short List (0xc0-0xf7)

Total payload length in prefix: length = prefix - 0xc0

import { Rlp } from 'tevm'

// Empty list
const empty = new Uint8Array([0xc0])
const result = Rlp.decode(empty)
// => { data: { type: 'list', value: [] }, remainder: Uint8Array([]) }

// List with 2 single bytes
const list = new Uint8Array([0xc2, 0x01, 0x02])
const result = Rlp.decode(list)
// 0xc2 - 0xc0 = 2 bytes total payload
// => {
//   data: {
//     type: 'list',
//     value: [
//       { type: 'bytes', value: Uint8Array([1]) },
//       { type: 'bytes', value: Uint8Array([2]) }
//     ]
//   },
//   remainder: Uint8Array([])
// }

// List with encoded strings
const strings = new Uint8Array([0xc7, 0x82, 1, 2, 0x83, 3, 4, 5])
const result = Rlp.decode(strings)
// 0xc7 - 0xc0 = 7 bytes payload
// Contains: [0x82, 1, 2] (3 bytes) and [0x83, 3, 4, 5] (4 bytes)

Long List (0xf8-0xff)

Length-of-length encoding: lengthOfLength = prefix - 0xf7

import { Rlp } from 'tevm'

// List with 60 bytes total payload
const items = Array(30).fill([0x01, 0x02]).flat()
const long = new Uint8Array([0xf8, 60, ...items])
const result = Rlp.decode(long)
// 0xf8 - 0xf7 = 1 (length needs 1 byte)
// Next byte: 60 = payload length

// List with 256 bytes total payload
const large = new Uint8Array([0xf9, 0x01, 0x00, ...Array(256).fill(0x01)])
const result = Rlp.decode(large)
// 0xf9 - 0xf7 = 2 (length needs 2 bytes)
// Next 2 bytes: [0x01, 0x00] = 256

Decoding Patterns

Extract Transaction Data

Decode transaction bytes and extract fields:

import { Rlp } from 'tevm'

// Legacy transaction RLP
const txBytes = new Uint8Array([...])  // RLP-encoded transaction
const result = Rlp.decode(txBytes)

if (result.data.type === 'list') {
  const [nonce, gasPrice, gas, to, value, data, v, r, s] = result.data.value

  // Each field is a bytes data structure
  if (nonce.type === 'bytes') {
    console.log('Nonce:', nonce.value)
  }
  if (to.type === 'bytes') {
    console.log('To:', to.value)
  }
}

Recursive Flattening

Flatten nested lists to extract all byte values:

import { Rlp } from 'tevm'

const nested = new Uint8Array([...])  // Deeply nested RLP
const result = Rlp.decode(nested)

// Flatten recursively extracts all bytes
const allBytes = Rlp.flatten(result.data)
// => Array of { type: 'bytes', value: Uint8Array }

for (const item of allBytes) {
  console.log('Bytes:', item.value)
}

Stream Decoding

Decode multiple RLP values from a stream:

import { Rlp } from 'tevm'

function* decodeStream(bytes: Uint8Array) {
  let remainder = bytes

  while (remainder.length > 0) {
    const result = Rlp.decode(remainder, true)
    yield result.data
    remainder = result.remainder
  }
}

// Use stream decoder
const stream = new Uint8Array([0x01, 0x02, 0x03, 0x04])
for (const data of decodeStream(stream)) {
  console.log('Decoded:', data)
}
// Outputs each byte as separate data structure

Validate and Extract

Decode with validation and type checking:

import { Rlp } from 'tevm'

function decodeTransaction(bytes: Uint8Array) {
  const result = Rlp.decode(bytes)

  // Must be a list
  if (result.data.type !== 'list') {
    throw new Error('Transaction must be RLP list')
  }

  // Must have 9 fields (legacy tx)
  if (result.data.value.length !== 9) {
    throw new Error('Invalid transaction field count')
  }

  // Must consume all bytes
  if (result.remainder.length > 0) {
    throw new Error('Extra data after transaction')
  }

  return result.data
}

Canonical Validation

RLP decoder enforces canonical encoding rules to prevent malleability:

Non-canonical Single Byte

Single bytes < 0x80 must not have a length prefix:

import { Rlp } from 'tevm'

// Invalid: single byte 0x7f with prefix
const invalid = new Uint8Array([0x81, 0x7f])
try {
  Rlp.decode(invalid)
} catch (error) {
  // Error: NonCanonicalSize
  // Single byte < 0x80 should not be prefixed
}

// Valid: 0x7f encodes as itself
const valid = new Uint8Array([0x7f])
const result = Rlp.decode(valid)  // OK

Non-canonical Short Form

Strings < 56 bytes must use short form:

import { Rlp } from 'tevm'

// Invalid: 3-byte string using long form
const invalid = new Uint8Array([0xb8, 0x03, 1, 2, 3])
try {
  Rlp.decode(invalid)
} catch (error) {
  // Error: NonCanonicalSize
  // String < 56 bytes should use short form
}

// Valid: 3-byte string in short form
const valid = new Uint8Array([0x83, 1, 2, 3])
const result = Rlp.decode(valid)  // OK

Leading Zeros

Length encodings must not have leading zeros:

import { Rlp } from 'tevm'

// Invalid: length with leading zero
const invalid = new Uint8Array([0xb9, 0x00, 0x38, ...Array(56).fill(0x42)])
try {
  Rlp.decode(invalid)
} catch (error) {
  // Error: LeadingZeros
  // Length encoding has leading zeros
}

// Valid: minimal length encoding
const valid = new Uint8Array([0xb8, 56, ...Array(56).fill(0x42)])
const result = Rlp.decode(valid)  // OK

Length Mismatches

Declared length must match actual data:

import { Rlp } from 'tevm'

// Invalid: declared 5 bytes but only 3 provided
const invalid = new Uint8Array([0x85, 1, 2, 3])
try {
  Rlp.decode(invalid)
} catch (error) {
  // Error: InputTooShort
  // Expected 6 bytes, got 4
}

// Invalid: list length mismatch
const invalid = new Uint8Array([0xc5, 0x01, 0x02])  // Says 5 bytes but only 2
try {
  Rlp.decode(invalid)
} catch (error) {
  // Error: InputTooShort
}

Error Handling

Comprehensive error handling for malformed input:

import { Rlp } from 'tevm'

// Empty input
try {
  Rlp.decode(Bytes())
} catch (error) {
  console.error('InputTooShort: Cannot decode empty input')
}

// Extra data (non-stream mode)
try {
  const bytes = new Uint8Array([0x01, 0x02])
  Rlp.decode(bytes, false)
} catch (error) {
  console.error('InvalidRemainder: Extra data after decoded value: 1 bytes')
}

// Invalid prefix
try {
  // No such thing as 0xff prefix in current spec
  Rlp.decode(new Uint8Array([0xff, 0x00]))
} catch (error) {
  console.error('UnexpectedInput: Invalid RLP prefix')
}

// Recursion depth exceeded
try {
  // Create deeply nested structure (> 32 levels)
  let nested = new Uint8Array([0xc0])  // Empty list
  for (let i = 0; i < 40; i++) {
    nested = new Uint8Array([0xc1, ...nested])  // Wrap in list
  }
  Rlp.decode(nested)
} catch (error) {
  console.error('RecursionDepthExceeded: Maximum recursion depth 32 exceeded')
}

// Incomplete data
try {
  const incomplete = new Uint8Array([0x83, 1, 2])  // Says 3 bytes, only has 2
  Rlp.decode(incomplete)
} catch (error) {
  console.error('InputTooShort: Expected 4 bytes, got 3')
}

Error Types Reference

Error	Cause	Fix
InputTooShort	Not enough bytes for declared length	Provide complete data
InvalidRemainder	Extra bytes after value (non-stream)	Use stream=true or trim input
NonCanonicalSize	Non-minimal length encoding	Use canonical encoding
LeadingZeros	Length has leading zero bytes	Remove leading zeros from length
InvalidLength	List payload length mismatch	Fix list item encodings
RecursionDepthExceeded	Nested > 32 levels deep	Reduce nesting depth
UnexpectedInput	Invalid prefix or format	Check input is valid RLP

Performance Considerations

Depth Limiting

Maximum recursion depth is 32 to prevent stack overflow:

import { Rlp } from 'tevm'

// This is fine (depth = 3)
const shallow = [[[new Uint8Array([1])]]]
const encoded = Rlp.encode(shallow)
const decoded = Rlp.decode(encoded)  // OK

// This will fail (depth > 32)
const deep = Array(40).fill(null).reduce(
  (acc) => [acc],
  new Uint8Array([1])
)
const encoded = Rlp.encode(deep)
try {
  Rlp.decode(encoded)
} catch (error) {
  // RecursionDepthExceeded
}

Stream Mode Efficiency

Use stream mode to avoid re-parsing when decoding multiple values:

import { Rlp } from 'tevm'

// Inefficient: decode + re-decode remainder
const data = new Uint8Array([0x01, 0x02, 0x03])
const first = Rlp.decode(data.slice(0, 1))
const second = Rlp.decode(data.slice(1, 2))
const third = Rlp.decode(data.slice(2, 3))

// Efficient: stream mode
let remainder = data
const values = []
while (remainder.length > 0) {
  const result = Rlp.decode(remainder, true)
  values.push(result.data)
  remainder = result.remainder
}

Validation Overhead

Canonical validation adds minimal overhead but catches malformed inputs:

// Decode validates:
// - Canonical encoding (minimal representation)
// - Length consistency (declared vs actual)
// - Depth limits (max 32 levels)
// - No leading zeros in lengths
// - Proper prefix ranges

// This ensures decoded data can be safely re-encoded
const decoded = Rlp.decode(bytes)
const reencoded = Rlp.encode(decoded.data)
// reencoded === bytes (if canonical)

Round-trip Encoding

Decode and re-encode produces identical bytes (for canonical input):

import { Rlp } from 'tevm'

// Original data
const original = new Uint8Array([0x83, 1, 2, 3])

// Decode
const decoded = Rlp.decode(original)

// Re-encode
const reencoded = Rlp.encode(decoded.data)

// Should match original (if canonical)
console.log(original.every((b, i) => b === reencoded[i]))  // true

// Compare bytes
function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
  if (a.length !== b.length) return false
  return a.every((byte, i) => byte === b[i])
}

console.log(bytesEqual(original, reencoded))  // true

Non-canonical input will be normalized on re-encoding:

import { Rlp } from 'tevm'

// This would fail to decode (non-canonical)
// But if we had non-canonical that somehow got through:
// const nonCanonical = new Uint8Array([0x81, 0x7f])

// After decode and re-encode, becomes canonical:
// const canonical = Rlp.encode(decoded.data)
// => Uint8Array([0x7f])  // Canonical form

Related

• Encoding - Encode data to RLP format
• Types - RLP data type system
• Algorithm - Specification details
• Usage Patterns - Real-world examples