rlp

Documentation

Overview

Package rlp implements the RLP serialization format.

The purpose of RLP (Recursive Linear Prefix) qis to encode arbitrarily nested arrays of binary data, and RLP is the main encoding method used to serialize objects in Ethereum. The only purpose of RLP is to encode structure; encoding specific atomic data types (eg. strings, ints, floats) is left up to higher-order protocols; in Ethereum integers must be represented in big endian binary form with no leading zeroes (thus making the integer value zero be equivalent to the empty byte array).

RLP values are distinguished by a type tag. The type tag precedes the value in the input stream and defines the size and kind of the bytes that follow.

Index

• Variables
• func Decode(r io.Reader, val interface{}) error
• type ByteReader
• type Decoder
• type Kind
  • func (k Kind) String() string
• type Stream
  • func NewListStream(r io.Reader, len uint64) *Stream
  • func NewStream(r io.Reader) *Stream
  • func (s *Stream) Bytes() ([]byte, error)
  • func (s *Stream) Decode(val interface{}) error
  • func (s *Stream) Kind() (kind Kind, size uint64, err error)
  • func (s *Stream) List() (size uint64, err error)
  • func (s *Stream) ListEnd() error
  • func (s *Stream) Reset(r io.Reader)
  • func (s *Stream) Uint() (uint64, error)

Examples

• Decode
• Stream

Variables

var (
	// EOL is returned when the end of the current list
	// has been reached during streaming.
	EOL = errors.New("rlp: end of list")

	// Other errors
	ErrExpectedString = errors.New("rlp: expected String or Byte")
	ErrExpectedList   = errors.New("rlp: expected List")
	ErrElemTooLarge   = errors.New("rlp: element is larger than containing list")
)

Functions

func Decode

func Decode(r io.Reader, val interface{}) error

Decode parses RLP-encoded data from r and stores the result in the value pointed to by val. Val must be a non-nil pointer. If r does not implement ByteReader, Decode will do its own buffering.

Decode uses the following type-dependent decoding rules:

If the type implements the Decoder interface, decode calls DecodeRLP.

To decode into a pointer, Decode will set the pointer to nil if the input has size zero or the input is a single byte with value zero. If the input has nonzero size, Decode will allocate a new value of the type being pointed to.

To decode into a struct, Decode expects the input to be an RLP list. The decoded elements of the list are assigned to each public field in the order given by the struct's definition. If the input list has too few elements, no error is returned and the remaining fields will have the zero value. Recursive struct types are supported.

To decode into a slice, the input must be a list and the resulting slice will contain the input elements in order. As a special case, if the slice has a byte-size element type, the input can also be an RLP string.

To decode into a Go string, the input must be an RLP string. The bytes are taken as-is and will not necessarily be valid UTF-8.

To decode into an unsigned integer type, the input must also be an RLP string. The bytes are interpreted as a big endian representation of the integer. If the RLP string is larger than the bit size of the type, Decode will return an error. Decode also supports *big.Int. There is no size limit for big integers.

To decode into an interface value, Decode stores one of these in the value:

[]interface{}, for RLP lists
[]byte, for RLP strings

Non-empty interface types are not supported, nor are booleans, signed integers, floating point numbers, maps, channels and functions.

Example

input, _ := hex.DecodeString("C90A1486666F6F626172")

type example struct {
	A, B    uint
	private uint // private fields are ignored
	String  string
}

var s example
err := Decode(bytes.NewReader(input), &s)
if err != nil {
	fmt.Printf("Error: %v\n", err)
} else {
	fmt.Printf("Decoded value: %#v\n", s)
}

Output:

Decoded value: rlp.example{A:0xa, B:0x14, private:0x0, String:"foobar"}

Types

type ByteReader

type ByteReader interface {
	io.Reader
	io.ByteReader
}

ByteReader must be implemented by any input reader for a Stream. It is implemented by e.g. bufio.Reader and bytes.Reader.

type Decoder

type Decoder interface {
	DecodeRLP(*Stream) error
}

Decoder is implemented by types that require custom RLP decoding rules or need to decode into private fields.

The DecodeRLP method should read one value from the given Stream. It is not forbidden to read less or more, but it might be confusing.

type Kind

type Kind int

Kind represents the kind of value contained in an RLP stream.

const (
	Byte Kind = iota
	String
	List
)

func (Kind) String

func (k Kind) String() string

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream can be used for piecemeal decoding of an input stream. This is useful if the input is very large or if the decoding rules for a type depend on the input structure. Stream does not keep an internal buffer. After decoding a value, the input reader will be positioned just before the type information for the next value.

When decoding a list and the input position reaches the declared length of the list, all operations will return error EOL. The end of the list must be acknowledged using ListEnd to continue reading the enclosing list.

Stream is not safe for concurrent use.

Example

input, _ := hex.DecodeString("C90A1486666F6F626172")
s := NewStream(bytes.NewReader(input))

// Check what kind of value lies ahead
kind, size, _ := s.Kind()
fmt.Printf("Kind: %v size:%d\n", kind, size)

// Enter the list
if _, err := s.List(); err != nil {
	fmt.Printf("List error: %v\n", err)
	return
}

// Decode elements
fmt.Println(s.Uint())
fmt.Println(s.Uint())
fmt.Println(s.Bytes())

// Acknowledge end of list
if err := s.ListEnd(); err != nil {
	fmt.Printf("ListEnd error: %v\n", err)
}

Output:

Kind: List size:9
10 <nil>
20 <nil>
[102 111 111 98 97 114] <nil>

func NewListStream

func NewListStream(r io.Reader, len uint64) *Stream

NewListStream creates a new stream that pretends to be positioned at an encoded list of the given length.

func NewStream

func NewStream(r io.Reader) *Stream

NewStream creates a new stream reading from r. If r does not implement ByteReader, the Stream will introduce its own buffering.

func (*Stream) Bytes

func (s *Stream) Bytes() ([]byte, error)

Bytes reads an RLP string and returns its contents as a byte slice. If the input does not contain an RLP string, the returned error will be ErrExpectedString.

func (*Stream) Decode

func (s *Stream) Decode(val interface{}) error

Decode decodes a value and stores the result in the value pointed to by val. Please see the documentation for the Decode function to learn about the decoding rules.

func (*Stream) Kind

func (s *Stream) Kind() (kind Kind, size uint64, err error)

Kind returns the kind and size of the next value in the input stream.

The returned size is the number of bytes that make up the value. For kind == Byte, the size is zero because the value is contained in the type tag.

The first call to Kind will read size information from the input reader and leave it positioned at the start of the actual bytes of the value. Subsequent calls to Kind (until the value is decoded) will not advance the input reader and return cached information.

func (*Stream) List

func (s *Stream) List() (size uint64, err error)

List starts decoding an RLP list. If the input does not contain a list, the returned error will be ErrExpectedList. When the list's end has been reached, any Stream operation will return EOL.

func (*Stream) ListEnd

func (s *Stream) ListEnd() error

ListEnd returns to the enclosing list. The input reader must be positioned at the end of a list.

func (*Stream) Reset

func (s *Stream) Reset(r io.Reader)

Reset discards any information about the current decoding context and starts reading from r. If r does not also implement ByteReader, Stream will do its own buffering.

func (*Stream) Uint

func (s *Stream) Uint() (uint64, error)

Uint reads an RLP string of up to 8 bytes and returns its contents as an unsigned integer. If the input does not contain an RLP string, the returned error will be ErrExpectedString.