snapshot

Documentation

Overview

Package snapshot implements a journalled, dynamic state dump.

Index

• Variables
• func CheckDanglingStorage(chaindb ethdb.KeyValueStore) error
• func CheckJournalAccount(db ethdb.KeyValueStore, hash common.Hash) error
• func FullAccountRLP(data []byte) ([]byte, error)
• func GenerateAccountTrieRoot(it AccountIterator) (common.Hash, error)
• func GenerateStorageTrieRoot(account common.Hash, it StorageIterator) (common.Hash, error)
• func GenerateTrie(snaptree *Tree, root common.Hash, src ethdb.Database, dst ethdb.KeyValueWriter) error
• func ParseGeneratorStatus(generatorBlob []byte) string
• func SlimAccountRLP(nonce uint64, balance *big.Int, root common.Hash, codehash []byte) []byte
• type Account
  • func FullAccount(data []byte) (Account, error)
  • func SlimAccount(nonce uint64, balance *big.Int, root common.Hash, codehash []byte) Account
• type AccountIterator
• type Config
• type Iterator
• type Snapshot
• type StorageIterator
• type Tree
  • func New(config Config, diskdb ethdb.KeyValueStore, triedb *trie.Database, ...) (*Tree, error)
  • func (t *Tree) AccountIterator(root common.Hash, seek common.Hash) (AccountIterator, error)
  • func (t *Tree) Cap(root common.Hash, layers int) error
  • func (t *Tree) Disable()
  • func (t *Tree) DiskRoot() common.Hash
  • func (t *Tree) Journal(root common.Hash) (common.Hash, error)
  • func (t *Tree) Rebuild(root common.Hash)
  • func (t *Tree) Snapshot(blockRoot common.Hash) Snapshot
  • func (t *Tree) Snapshots(root common.Hash, limits int, nodisk bool) []Snapshot
  • func (t *Tree) StorageIterator(root common.Hash, account common.Hash, seek common.Hash) (StorageIterator, error)
  • func (t *Tree) Update(blockRoot common.Hash, parentRoot common.Hash, ...) error
  • func (t *Tree) Verify(root common.Hash) error

Variables

var (

	// ErrSnapshotStale is returned from data accessors if the underlying snapshot
	// layer had been invalidated due to the chain progressing forward far enough
	// to not maintain the layer's original state.
	ErrSnapshotStale = errors.New("snapshot stale")

	// ErrNotCoveredYet is returned from data accessors if the underlying snapshot
	// is being generated currently and the requested data item is not yet in the
	// range of accounts covered.
	ErrNotCoveredYet = errors.New("not covered yet")

	// ErrNotConstructed is returned if the callers want to iterate the snapshot
	// while the generation is not finished yet.
	ErrNotConstructed = errors.New("snapshot is not constructed")
)

Functions

func CheckDanglingStorage

func CheckDanglingStorage(chaindb ethdb.KeyValueStore) error

CheckDanglingStorage iterates the snap storage data, and verifies that all storage also has corresponding account data.

func CheckJournalAccount

func CheckJournalAccount(db ethdb.KeyValueStore, hash common.Hash) error

CheckJournalAccount shows information about an account, from the disk layer and up through the diff layers.

func FullAccountRLP

func FullAccountRLP(data []byte) ([]byte, error)

FullAccountRLP converts data on the 'slim RLP' format into the full RLP-format.

func GenerateAccountTrieRoot

func GenerateAccountTrieRoot(it AccountIterator) (common.Hash, error)

GenerateAccountTrieRoot takes an account iterator and reproduces the root hash.

func GenerateStorageTrieRoot

func GenerateStorageTrieRoot(account common.Hash, it StorageIterator) (common.Hash, error)

GenerateStorageTrieRoot takes a storage iterator and reproduces the root hash.

func GenerateTrie

func GenerateTrie(snaptree *Tree, root common.Hash, src ethdb.Database, dst ethdb.KeyValueWriter) error

GenerateTrie takes the whole snapshot tree as the input, traverses all the accounts as well as the corresponding storages and regenerate the whole state (account trie + all storage tries).

func ParseGeneratorStatus

func ParseGeneratorStatus(generatorBlob []byte) string

func SlimAccountRLP

func SlimAccountRLP(nonce uint64, balance *big.Int, root common.Hash, codehash []byte) []byte

SlimAccountRLP converts a state.Account content into a slim snapshot version RLP encoded.

Types

type Account

type Account struct {
	Nonce    uint64
	Balance  *big.Int
	Root     []byte
	CodeHash []byte
}

Account is a modified version of a state.Account, where the root is replaced with a byte slice. This format can be used to represent full-consensus format or slim-snapshot format which replaces the empty root and code hash as nil byte slice.

func FullAccount

func FullAccount(data []byte) (Account, error)

FullAccount decodes the data on the 'slim RLP' format and return the consensus format account.

func SlimAccount

func SlimAccount(nonce uint64, balance *big.Int, root common.Hash, codehash []byte) Account

SlimAccount converts a state.Account content into a slim snapshot account

type AccountIterator

type AccountIterator interface {
	Iterator

	// Account returns the RLP encoded slim account the iterator is currently at.
	// An error will be returned if the iterator becomes invalid
	Account() []byte
}

AccountIterator is an iterator to step over all the accounts in a snapshot, which may or may not be composed of multiple layers.

type Config

type Config struct {
	CacheSize  int  // Megabytes permitted to use for read caches
	Recovery   bool // Indicator that the snapshots is in the recovery mode
	NoBuild    bool // Indicator that the snapshots generation is disallowed
	AsyncBuild bool // The snapshot generation is allowed to be constructed asynchronously
}

Config includes the configurations for snapshots.

type Iterator

type Iterator interface {
	// Next steps the iterator forward one element, returning false if exhausted,
	// or an error if iteration failed for some reason (e.g. root being iterated
	// becomes stale and garbage collected).
	Next() bool

	// Error returns any failure that occurred during iteration, which might have
	// caused a premature iteration exit (e.g. snapshot stack becoming stale).
	Error() error

	// Hash returns the hash of the account or storage slot the iterator is
	// currently at.
	Hash() common.Hash

	// Release releases associated resources. Release should always succeed and
	// can be called multiple times without causing error.
	Release()
}

Iterator is an iterator to step over all the accounts or the specific storage in a snapshot which may or may not be composed of multiple layers.

type Snapshot

type Snapshot interface {
	// Root returns the root hash for which this snapshot was made.
	Root() common.Hash

	// Account directly retrieves the account associated with a particular hash in
	// the snapshot slim data format.
	Account(hash common.Hash) (*Account, error)

	// AccountRLP directly retrieves the account RLP associated with a particular
	// hash in the snapshot slim data format.
	AccountRLP(hash common.Hash) ([]byte, error)

	// Storage directly retrieves the storage data associated with a particular hash,
	// within a particular account.
	Storage(accountHash, storageHash common.Hash) ([]byte, error)
}

Snapshot represents the functionality supported by a snapshot storage layer.

type StorageIterator

type StorageIterator interface {
	Iterator

	// Slot returns the storage slot the iterator is currently at. An error will
	// be returned if the iterator becomes invalid
	Slot() []byte
}

StorageIterator is an iterator to step over the specific storage in a snapshot, which may or may not be composed of multiple layers.

type Tree

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

Tree is an Ethereum state snapshot tree. It consists of one persistent base layer backed by a key-value store, on top of which arbitrarily many in-memory diff layers are topped. The memory diffs can form a tree with branching, but the disk layer is singleton and common to all. If a reorg goes deeper than the disk layer, everything needs to be deleted.

The goal of a state snapshot is twofold: to allow direct access to account and storage data to avoid expensive multi-level trie lookups; and to allow sorted, cheap iteration of the account/storage tries for sync aid.

func New

func New(config Config, diskdb ethdb.KeyValueStore, triedb *trie.Database, root common.Hash) (*Tree, error)

New attempts to load an already existing snapshot from a persistent key-value store (with a number of memory layers from a journal), ensuring that the head of the snapshot matches the expected one.

If the snapshot is missing or the disk layer is broken, the snapshot will be reconstructed using both the existing data and the state trie. The repair happens on a background thread.

If the memory layers in the journal do not match the disk layer (e.g. there is a gap) or the journal is missing, there are two repair cases:

• if the 'recovery' parameter is true, memory diff-layers and the disk-layer will all be kept. This case happens when the snapshot is 'ahead' of the state trie.
• otherwise, the entire snapshot is considered invalid and will be recreated on a background thread.

func (*Tree) AccountIterator

func (t *Tree) AccountIterator(root common.Hash, seek common.Hash) (AccountIterator, error)

AccountIterator creates a new account iterator for the specified root hash and seeks to a starting account hash.

func (*Tree) Cap

func (t *Tree) Cap(root common.Hash, layers int) error

Cap traverses downwards the snapshot tree from a head block hash until the number of allowed layers are crossed. All layers beyond the permitted number are flattened downwards.

Note, the final diff layer count in general will be one more than the amount requested. This happens because the bottom-most diff layer is the accumulator which may or may not overflow and cascade to disk. Since this last layer's survival is only known *after* capping, we need to omit it from the count if we want to ensure that *at least* the requested number of diff layers remain.

func (*Tree) Disable

func (t *Tree) Disable()

Disable interrupts any pending snapshot generator, deletes all the snapshot layers in memory and marks snapshots disabled globally. In order to resume the snapshot functionality, the caller must invoke Rebuild.

func (*Tree) DiskRoot

func (t *Tree) DiskRoot() common.Hash

DiskRoot is a external helper function to return the disk layer root.

func (*Tree) Journal

func (t *Tree) Journal(root common.Hash) (common.Hash, error)

Journal commits an entire diff hierarchy to disk into a single journal entry. This is meant to be used during shutdown to persist the snapshot without flattening everything down (bad for reorgs).

The method returns the root hash of the base layer that needs to be persisted to disk as a trie too to allow continuing any pending generation op.

func (*Tree) Rebuild

func (t *Tree) Rebuild(root common.Hash)

Rebuild wipes all available snapshot data from the persistent database and discard all caches and diff layers. Afterwards, it starts a new snapshot generator with the given root hash.

func (*Tree) Snapshot

func (t *Tree) Snapshot(blockRoot common.Hash) Snapshot

Snapshot retrieves a snapshot belonging to the given block root, or nil if no snapshot is maintained for that block.

func (*Tree) Snapshots

func (t *Tree) Snapshots(root common.Hash, limits int, nodisk bool) []Snapshot

Snapshots returns all visited layers from the topmost layer with specific root and traverses downward. The layer amount is limited by the given number. If nodisk is set, then disk layer is excluded.

func (*Tree) StorageIterator

func (t *Tree) StorageIterator(root common.Hash, account common.Hash, seek common.Hash) (StorageIterator, error)

StorageIterator creates a new storage iterator for the specified root hash and account. The iterator will be move to the specific start position.

func (*Tree) Update

func (t *Tree) Update(blockRoot common.Hash, parentRoot common.Hash, destructs map[common.Hash]struct{}, accounts map[common.Hash][]byte, storage map[common.Hash]map[common.Hash][]byte) error

Update adds a new snapshot into the tree, if that can be linked to an existing old parent. It is disallowed to insert a disk layer (the origin of all).

func (*Tree) Verify

func (t *Tree) Verify(root common.Hash) error

Verify iterates the whole state(all the accounts as well as the corresponding storages) with the specific root and compares the re-computed hash with the original one.