era

Documentation

Overview

Copyright 2023 The go-ethereum Authors This file is part of go-ethereum.

go-ethereum is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

go-ethereum is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with go-ethereum. If not, see <http://www.gnu.org/licenses/>.

Index

• Variables
• func ComputeAccumulator(hashes []common.Hash, tds []*big.Int) (common.Hash, error)
• func Filename(network string, epoch int, root common.Hash) string
• func ReadDir(dir, network string) ([]string, error)
• type Builder
  • func NewBuilder(w io.Writer) *Builder
  • func (b *Builder) Add(block *types.Block, receipts types.Receipts, td *big.Int) error
  • func (b *Builder) AddRLP(header, body, receipts []byte, number uint64, hash common.Hash, ...) error
  • func (b *Builder) Finalize() (common.Hash, error)
• type Era
  • func From(f ReadAtSeekCloser) (*Era, error)
  • func Open(filename string) (*Era, error)
  • func (e *Era) Accumulator() (common.Hash, error)
  • func (e *Era) Close() error
  • func (e *Era) Count() uint64
  • func (e *Era) GetBlockByNumber(num uint64) (*types.Block, error)
  • func (e *Era) InitialTD() (*big.Int, error)
  • func (e *Era) Start() uint64
• type Iterator
  • func NewIterator(e *Era) (*Iterator, error)
  • func (it *Iterator) Block() (*types.Block, error)
  • func (it *Iterator) BlockAndReceipts() (*types.Block, types.Receipts, error)
  • func (it *Iterator) Error() error
  • func (it *Iterator) Next() bool
  • func (it *Iterator) Number() uint64
  • func (it *Iterator) Receipts() (types.Receipts, error)
  • func (it *Iterator) TotalDifficulty() (*big.Int, error)
• type RawIterator
  • func NewRawIterator(e *Era) (*RawIterator, error)
  • func (it *RawIterator) Error() error
  • func (it *RawIterator) Next() bool
  • func (it *RawIterator) Number() uint64
• type ReadAtSeekCloser

Variables

var (
	TypeVersion            uint16 = 0x3265
	TypeCompressedHeader   uint16 = 0x03
	TypeCompressedBody     uint16 = 0x04
	TypeCompressedReceipts uint16 = 0x05
	TypeTotalDifficulty    uint16 = 0x06
	TypeAccumulator        uint16 = 0x07
	TypeBlockIndex         uint16 = 0x3266

	MaxEra1Size = 8192
)

Functions

func ComputeAccumulator

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

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

func Filename

func Filename(network string, epoch int, root common.Hash) string

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

func ReadDir

func ReadDir(dir, network string) ([]string, error)

ReadDir reads all the era1 files in a directory for a given network. Format: <network>-<epoch>-<hexroot>.era1

Types

type Builder

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

Builder is used to create Era1 archives of block data.

Era1 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 Era1 file follows closely the structure of an Era file which contains consensus Layer data (and as a byproduct, EL data after the merge).

The structure can be summarized through this definition:

era1 := Version | block-tuple* | other-entries* | Accumulator | BlockIndex
block-tuple :=  CompressedHeader | CompressedBody | CompressedReceipts | TotalDifficulty

Each basic element is its own entry:

Version            = { type: [0x65, 0x32], data: nil }
CompressedHeader   = { type: [0x03, 0x00], data: snappyFramed(rlp(header)) }
CompressedBody     = { type: [0x04, 0x00], data: snappyFramed(rlp(body)) }
CompressedReceipts = { type: [0x05, 0x00], data: snappyFramed(rlp(receipts)) }
TotalDifficulty    = { type: [0x06, 0x00], data: uint256(header.total_difficulty) }
AccumulatorRoot    = { type: [0x07, 0x00], data: accumulator-root }
BlockIndex         = { type: [0x32, 0x66], data: block-index }

Accumulator is computed by constructing an SSZ list of header-records of length at most 8192 and then calculating the hash_tree_root of that list.

header-record := { block-hash: Bytes32, total-difficulty: Uint256 }
accumulator   := hash_tree_root([]header-record, 8192)

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 beginning of the record. The total number of block entries in the file is recorded with count.

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

func NewBuilder

func NewBuilder(w io.Writer) *Builder

NewBuilder returns a new Builder instance.

func (*Builder) Add

func (b *Builder) Add(block *types.Block, receipts types.Receipts, td *big.Int) error

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

func (*Builder) AddRLP

func (b *Builder) AddRLP(header, body, receipts []byte, number uint64, hash common.Hash, td, difficulty *big.Int) error

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

func (*Builder) Finalize

func (b *Builder) Finalize() (common.Hash, error)

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

type Era

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

Era reads and Era1 file.

func From

func From(f ReadAtSeekCloser) (*Era, error)

From returns an Era backed by f.

func Open

func Open(filename string) (*Era, error)

Open returns an Era backed by the given filename.

func (*Era) Accumulator

func (e *Era) Accumulator() (common.Hash, error)

Accumulator reads the accumulator entry in the Era1 file.

func (*Era) Close

func (e *Era) Close() error

func (*Era) Count

func (e *Era) Count() uint64

Count returns the total number of blocks in the Era1.

func (*Era) GetBlockByNumber

func (e *Era) GetBlockByNumber(num uint64) (*types.Block, error)

func (*Era) InitialTD

func (e *Era) InitialTD() (*big.Int, error)

InitialTD returns initial total difficulty before the difficulty of the first block of the Era1 is applied.

func (*Era) Start

func (e *Era) Start() uint64

Start returns the listed start block.

type Iterator

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

Iterator wraps RawIterator and returns decoded Era1 entries.

func NewIterator

func NewIterator(e *Era) (*Iterator, error)

NewRawIterator returns a new Iterator instance. Next must be immediately called on new iterators to load the first item.

func (*Iterator) Block

func (it *Iterator) Block() (*types.Block, error)

Block returns the block for the iterator's current position.

func (*Iterator) BlockAndReceipts

func (it *Iterator) BlockAndReceipts() (*types.Block, types.Receipts, error)

BlockAndReceipts returns the block and receipts for the iterator's current position.

func (*Iterator) Error

func (it *Iterator) Error() error

Error returns the error status of the iterator. It should be called before reading from any of the iterator's values.

func (*Iterator) Next

func (it *Iterator) Next() bool

Next moves the iterator to the next block entry. It returns false when all items have been read or an error has halted its progress. Block, Receipts, and BlockAndReceipts should no longer be called after false is returned.

func (*Iterator) Number

func (it *Iterator) Number() uint64

Number returns the current number block the iterator will return.

func (*Iterator) Receipts

func (it *Iterator) Receipts() (types.Receipts, error)

Receipts returns the receipts for the iterator's current position.

func (*Iterator) TotalDifficulty

func (it *Iterator) TotalDifficulty() (*big.Int, error)

TotalDifficulty returns the total difficulty for the iterator's current position.

type RawIterator

type RawIterator struct {
	Header          io.Reader
	Body            io.Reader
	Receipts        io.Reader
	TotalDifficulty io.Reader
	// contains filtered or unexported fields
}

RawIterator reads an RLP-encode Era1 entries.

func NewRawIterator

func NewRawIterator(e *Era) (*RawIterator, error)

NewRawIterator returns a new RawIterator instance. Next must be immediately called on new iterators to load the first item.

func (*RawIterator) Error

func (it *RawIterator) Error() error

Error returns the error status of the iterator. It should be called before reading from any of the iterator's values.

func (*RawIterator) Next

func (it *RawIterator) Next() bool

Next moves the iterator to the next block entry. It returns false when all items have been read or an error has halted its progress. Header, Body, Receipts, TotalDifficulty will be set to nil in the case returning false or finding an error and should therefore no longer be read from.

func (*RawIterator) Number

func (it *RawIterator) Number() uint64

Number returns the current number block the iterator will return.

type ReadAtSeekCloser

type ReadAtSeekCloser interface {
	io.ReaderAt
	io.Seeker
	io.Closer
}