era

README

era utility

This repository stores some utility commands for interogating Era files, as well as generic e2store and era go libraries.

Documentation

Index

• Variables
• func ComputeAccumulator(hashes [][]byte, tds []*big.Int) ([]byte, error)
• func Filename(epoch int, network string) string
• type Builder
  • func NewBuilder(w io.WriteSeeker, start uint64, td *big.Int) *Builder
  • func (b *Builder) Add(block, receipts, hash []byte, td *big.Int) error
  • func (b *Builder) Finalize() error
• type Reader
  • func NewReader(r io.ReadSeekCloser) *Reader
  • func (r *Reader) Accumulator() ([]byte, error)
  • func (r *Reader) Close() error
  • func (r *Reader) Count() (uint64, error)
  • func (r *Reader) Read() ([]byte, []byte, error)
  • func (r *Reader) ReadBlock(n uint64) ([]byte, error)
  • func (r *Reader) ReadBlockAndReceipts(n uint64) ([]byte, []byte, error)
  • func (r *Reader) Start() (uint64, error)
  • func (r *Reader) TotalDifficulty() (*big.Int, error)

Variables

var (
	TypeVersion           uint16 = 0x3265
	TypeCompressedBlock   uint16 = 0x03
	TypeCompressedReceipt uint16 = 0x04
	TypeAccumulator       uint16 = 0x05
	TypeTotalDifficulty   uint16 = 0x06
	TypeBlockIndex        uint16 = 0x3266

	MaxEraBatchSize = 8192
)

Functions

func ComputeAccumulator

func ComputeAccumulator(hashes [][]byte, tds []*big.Int) ([]byte, error)

ComputeAccumulator calculates the SSZ hash tree root of the Era accumulator of header records.

func Filename

func Filename(epoch int, network string) string

Filename returns a recognizable Era-formatted file name for the specified epoch and network.

Types

type Builder

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

Builder is used to create Era archives of block data.

Era files are themselves e2store files. For more information on this format, see https://github.com/status-im/nimbus-eth2/blob/stable/docs/e2store.md.

The overall structure of an Era file can be summarized with this definition:

era := Version | block-tuple* | other-entries* | Accumulator | StartTD | BlockIndex
block-tuple :=  CompressedBlock | CompressedReceipts

Each basic element is its own entry:

Version            = { type: [0x65, 0x32], data: nil }
CompressedBlock    = { type: [0x03, 0x00], data: snappyFramed(rlp(block)) }
CompressedReceipts = { type: [0x04, 0x00], data: snappyFramed(rlp(receipts)) }
Accumulator        = { type: [0x05, 0x00], data: hash_tree_root(blockHashes, 8192) }
StartTD            = { type: [0x06, 0x00], data: uint256(startingTotalDifficulty) }
BlockIndex         = { type: [0x32, 0x66], data: block-index }

BlockIndex stores relative offsets to each compressed block entry. The format is:

block-index := starting-number | index | index | index ... | count

starting-number is the first block number in the archive. Every index is a defined relative to index's location in the file. The total number of block entries in the file is recorded in count.

Due to the accumulator size limit of 8192, the maximum number of blocks in an Era batch is also 8192.

func NewBuilder

func NewBuilder(w io.WriteSeeker, start uint64, td *big.Int) *Builder

NewBuilder returns a new Builder instance. start is the first block number in the Era and td is the total difficulty of the chain before the first block is applied.

func (*Builder) Add

func (b *Builder) Add(block, receipts, hash []byte, td *big.Int) error

Add writes a compressed block entry and compressed receipts entry to the underlying e2store file.

func (*Builder) Finalize

func (b *Builder) Finalize() error

Finalize computes the accumulator and block index values, then writes the corresponding e2store entries.

type Reader

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

Reader reads an Era archive. See Builder documentation for a detailed explanation of the Era format.

func NewReader

func NewReader(r io.ReadSeekCloser) *Reader

NewReader returns a new Reader instance.

func (*Reader) Accumulator

func (r *Reader) Accumulator() ([]byte, error)

Accumulator reads the accumulator entry in the Era file.

func (*Reader) Close

func (r *Reader) Close() error

Close implements a closer.

func (*Reader) Count

func (r *Reader) Count() (uint64, error)

Count returns the total number of blocks in the Era.

func (*Reader) Read

func (r *Reader) Read() ([]byte, []byte, error)

Read reads one (block, receipts, error) tuple from an Era archive.

func (*Reader) ReadBlock

func (r *Reader) ReadBlock(n uint64) ([]byte, error)

ReadBlock reads the block number n from the Era archive. The method returns error if the Era file is malformed, the request is out-of-bounds, as determined by the block index, or if the block number at the calculated offset doesn't match the requested.

func (*Reader) ReadBlockAndReceipts

func (r *Reader) ReadBlockAndReceipts(n uint64) ([]byte, []byte, error)

The method returns error if the Era file is malformed, the request is out-of-bounds, as determined by the block index, or if the block number at the calculated offset doesn't match the requested.

func (*Reader) Start

func (r *Reader) Start() (uint64, error)

Start returns the listed start block.

func (*Reader) TotalDifficulty

func (r *Reader) TotalDifficulty() (*big.Int, error)

TotalDifficulty reads the total difficulty entry in the Era file.