trie

package
v1.2.0-fork6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 30, 2023 License: LGPL-3.0 Imports: 26 Imported by: 0

README

based on github.com/ethereum/go-ethereum/trie v1.7.3 tag

Documentation

Overview

Package trie implements Merkle Patricia Tries.

Index

Constants

This section is empty.

Variables

View Source 
var ErrAlreadyProcessed = errors.New("already processed")

ErrAlreadyProcessed is returned by the trie sync when it's requested to process a node it already processed previously.

View Source 
var ErrNotRequested = errors.New("not requested")

ErrNotRequested is returned by the trie sync when it's requested to process a node it did not request.

Functions

func CacheMisses 

func CacheMisses() int64

CacheMisses retrieves a global counter measuring the number of cache misses the trie had since process startup. This isn't useful for anything apart from trie debugging purposes.

func CacheUnloads 

func CacheUnloads() int64

CacheUnloads retrieves a global counter measuring the number of cache unloads the trie did since process startup. This isn't useful for anything apart from trie debugging purposes.

func DeriveRoot 

func DeriveRoot(list DerivableList) meter.Bytes32

func VerifyProof 

func VerifyProof(rootHash meter.Bytes32, key []byte, proofDb DatabaseReader) (value []byte, err error, nodes int)

VerifyProof checks merkle proofs. The given proof must contain the value for key in a trie with the given root hash. VerifyProof returns an error if the proof contains invalid trie nodes or the wrong value.

Types

type Compacter 

type Compacter interface {
	// Compact flattens the underlying data store for the given key range. In essence,
	// deleted and overwritten versions are discarded, and the data is rearranged to
	// reduce the cost of operations needed to access them.
	//
	// A nil start is treated as a key before all keys in the data store; a nil limit
	// is treated as a key after all keys in the data store. If both is nil then it
	// will compact entire data store.
	Compact(start []byte, limit []byte) error
}

Compacter wraps the Compact method of a backing data store.

type Database 

type Database interface {
	DatabaseReader
	DatabaseWriter
}

Database must be implemented by backing stores for the trie.

type DatabaseReader 

type DatabaseReader interface {
	Get(key []byte) (value []byte, err error)
	Has(key []byte) (bool, error)
}

DatabaseReader wraps the Get method of a backing store for the trie.

type DatabaseWriter 

type DatabaseWriter interface {
	// Put stores the mapping key->value in the database.
	// Implementations must not hold onto the value bytes, the trie
	// will reuse the slice across calls to Put.
	Put(key, value []byte) error
}

DatabaseWriter wraps the Put method of a backing store for the trie.

type DerivableList 

type DerivableList interface {
	Len() int
	GetRlp(i int) []byte
}

type Iterator 

type Iterator struct {
	Key   []byte // Current data key on which the iterator is positioned on
	Value []byte // Current data value on which the iterator is positioned on
	Err   error
	// contains filtered or unexported fields
}

Iterator is a key-value trie iterator that traverses a Trie.

func NewIterator 

func NewIterator(it NodeIterator) *Iterator

NewIterator creates a new key-value iterator from a node iterator

func (*Iterator) Next 

func (it *Iterator) Next() bool

Next moves the iterator forward one key-value entry.

type KeyValueStater 

type KeyValueStater interface {
	// Stat returns a particular internal stat of the database.
	Stat(property string) (string, error)
}

type KeyValueStore 

type KeyValueStore interface {
	DatabaseReader
	DatabaseWriter
	Compacter
	KeyValueStater
}

type MissingNodeError 

type MissingNodeError struct {
	NodeHash meter.Bytes32 // hash of the missing node
	Path     []byte        // hex-encoded path to the missing node
}

MissingNodeError is returned by the trie functions (TryGet, TryUpdate, TryDelete) in the case where a trie node is not present in the local database. It contains information necessary for retrieving the missing node.

func (*MissingNodeError) Error 

func (err *MissingNodeError) Error() string

type NodeIterator 

type NodeIterator interface {
	// Next moves the iterator to the next node. If the parameter is false, any child
	// nodes will be skipped.
	Next(bool) bool
	// Error returns the error status of the iterator.
	Error() error

	// Hash returns the hash of the current node.
	Hash() meter.Bytes32
	// Parent returns the hash of the parent of the current node. The hash may be the one
	// grandparent if the immediate parent is an internal node with no hash.
	Parent() meter.Bytes32
	// Path returns the hex-encoded path to the current node.
	// Callers must not retain references to the return value after calling Next.
	// For leaf nodes, the last element of the path is the 'terminator symbol' 0x10.
	Path() []byte

	// Leaf returns true iff the current node is a leaf node.
	// LeafBlob, LeafKey return the contents and key of the leaf node. These
	// method panic if the iterator is not positioned at a leaf.
	// Callers must not retain references to their return value after calling Next
	Leaf() bool
	LeafBlob() []byte
	LeafKey() []byte
}

NodeIterator is an iterator to traverse the trie pre-order.

func NewDifferenceIterator 

func NewDifferenceIterator(a, b NodeIterator) (NodeIterator, *int)

NewDifferenceIterator constructs a NodeIterator that iterates over elements in b that are not in a. Returns the iterator, and a pointer to an integer recording the number of nodes seen.

func NewUnionIterator 

func NewUnionIterator(iters []NodeIterator) (NodeIterator, *int)

NewUnionIterator constructs a NodeIterator that iterates over elements in the union of the provided NodeIterators. Returns the iterator, and a pointer to an integer recording the number of nodes visited.

type PruneIterator 

type PruneIterator interface {
	// Next moves the iterator to the next node. If the parameter is false, any child
	// nodes will be skipped.
	Next(bool) bool
	// Error returns the error status of the iterator.
	Error() error

	// Hash returns the hash of the current node.
	Hash() meter.Bytes32
	// Parent returns the hash of the parent of the current node. The hash may be the one
	// grandparent if the immediate parent is an internal node with no hash.
	Parent() meter.Bytes32
	// Path returns the hex-encoded path to the current node.
	// Callers must not retain references to the return value after calling Next.
	// For leaf nodes, the last element of the path is the 'terminator symbol' 0x10.
	Path() []byte

	// Leaf returns true iff the current node is a leaf node.
	// LeafBlob, LeafKey return the contents and key of the leaf node. These
	// method panic if the iterator is not positioned at a leaf.
	// Callers must not retain references to their return value after calling Next
	Leaf() bool
	LeafBlob() []byte
	LeafKey() []byte

	Get([]byte) ([]byte, error) // get value from cache or db
}

type PruneStat 

type PruneStat struct {
	Nodes        int // count of state trie nodes on target trie
	Accounts     int // count of accounts on the target trie
	StorageNodes int //  count of storage nodes on target trie

	PrunedNodes        int    // count of pruned nodes
	PrunedNodeBytes    uint64 // size of pruned nodes on target trie
	PrunedStorageNodes int    // count of pruned storage nodes
	PrunedStorageBytes uint64 // size of pruned storage on target trie
}

Iterator is a key-value trie iterator that traverses a Trie.

func (*PruneStat) String 

func (s *PruneStat) String() string

type Pruner 

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

func NewPruner 

func NewPruner(db KeyValueStore, dataDir string) *Pruner

NewIterator creates a new key-value iterator from a node iterator

func (*Pruner) Compact 

func (p *Pruner) Compact()

func (*Pruner) InitForStatePruning 

func (p *Pruner) InitForStatePruning(geneStateRoot, snapStateRoot meter.Bytes32, snapNum uint32)

func (*Pruner) PrintStats 

func (p *Pruner) PrintStats()

func (*Pruner) Prune 

func (p *Pruner) Prune(root meter.Bytes32, batch kv.Batch) *PruneStat

prune the trie at block height

func (*Pruner) PruneIndexTrie 

func (p *Pruner) PruneIndexTrie(blockNum uint32, blockHash meter.Bytes32, batch kv.Batch) *PruneStat

prune the state trie with given root

func (*Pruner) Scan 

func (p *Pruner) Scan(root meter.Bytes32) *TrieDelta

prune the state trie with given root

func (*Pruner) ScanIndexTrie 

func (p *Pruner) ScanIndexTrie(blockHash meter.Bytes32) *TrieDelta

prune the state trie with given root

type SecureTrie 

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

SecureTrie wraps a trie with key hashing. In a secure trie, all access operations hash the key using blake2b-256. This prevents calling code from creating long chains of nodes that increase the access time.

Contrary to a regular trie, a SecureTrie can only be created with New and must have an attached database. The database also stores the preimage of each key.

SecureTrie is not safe for concurrent use.

func NewSecure 

func NewSecure(root meter.Bytes32, db Database, cachelimit uint16) (*SecureTrie, error)

NewSecure creates a trie with an existing root node from db.

If root is the zero hash or the blake2b-256 hash of an empty string, the trie is initially empty. Otherwise, New will panic if db is nil and returns MissingNodeError if the root node cannot be found.

Accessing the trie loads nodes from db on demand. Loaded nodes are kept around until their 'cache generation' expires. A new cache generation is created by each call to Commit. cachelimit sets the number of past cache generations to keep.

func (*SecureTrie) Commit 

func (t *SecureTrie) Commit() (root meter.Bytes32, err error)

Commit writes all nodes and the secure hash pre-images to the trie's database. Nodes are stored with their blake2b hash as the key.

Committing flushes nodes from memory. Subsequent Get calls will load nodes from the database.

func (*SecureTrie) CommitTo 

func (t *SecureTrie) CommitTo(db DatabaseWriter) (root meter.Bytes32, err error)

CommitTo writes all nodes and the secure hash pre-images to the given database. Nodes are stored with their blake2b hash as the key.

Committing flushes nodes from memory. Subsequent Get calls will load nodes from the trie's database. Calling code must ensure that the changes made to db are written back to the trie's attached database before using the trie.

func (*SecureTrie) Copy 

func (t *SecureTrie) Copy() *SecureTrie

func (*SecureTrie) Delete 

func (t *SecureTrie) Delete(key []byte)

Delete removes any existing value for key from the trie.

func (*SecureTrie) Get 

func (t *SecureTrie) Get(key []byte) []byte

Get returns the value for key stored in the trie. The value bytes must not be modified by the caller.

func (*SecureTrie) GetKey 

func (t *SecureTrie) GetKey(shaKey []byte) []byte

GetKey returns the sha3 preimage of a hashed key that was previously used to store a value.

func (*SecureTrie) Hash 

func (t *SecureTrie) Hash() meter.Bytes32

func (*SecureTrie) NodeIterator 

func (t *SecureTrie) NodeIterator(start []byte) NodeIterator

NodeIterator returns an iterator that returns nodes of the underlying trie. Iteration starts at the key after the given start key.

func (*SecureTrie) Root 

func (t *SecureTrie) Root() []byte

func (*SecureTrie) TryDelete 

func (t *SecureTrie) TryDelete(key []byte) error

TryDelete removes any existing value for key from the trie. If a node was not found in the database, a MissingNodeError is returned.

func (*SecureTrie) TryGet 

func (t *SecureTrie) TryGet(key []byte) ([]byte, error)

TryGet returns the value for key stored in the trie. The value bytes must not be modified by the caller. If a node was not found in the database, a MissingNodeError is returned.

func (*SecureTrie) TryUpdate 

func (t *SecureTrie) TryUpdate(key, value []byte) error

TryUpdate associates key with value in the trie. Subsequent calls to Get will return value. If value has length zero, any existing value is deleted from the trie and calls to Get will return nil.

The value bytes must not be modified by the caller while they are stored in the trie.

If a node was not found in the database, a MissingNodeError is returned.

func (*SecureTrie) Update 

func (t *SecureTrie) Update(key, value []byte)

Update associates key with value in the trie. Subsequent calls to Get will return value. If value has length zero, any existing value is deleted from the trie and calls to Get will return nil.

The value bytes must not be modified by the caller while they are stored in the trie.

type StateAccount 

type StateAccount struct {
	Balance      *big.Int
	Energy       *big.Int
	BoundBalance *big.Int
	BoundEnergy  *big.Int
	Master       []byte // master address
	CodeHash     []byte // hash of code
	StorageRoot  []byte // merkle root of the storage trie
}

func (*StateAccount) DiffString 

func (a *StateAccount) DiffString(b *StateAccount) string

func (*StateAccount) String 

func (a *StateAccount) String() string

type StateBloom 

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

stateBloom is a bloom filter used during the state conversion(snapshot->state). The keys of all generated entries will be recorded here so that in the pruning stage the entries belong to the specific version can be avoided for deletion.

The false-positive is allowed here. The "false-positive" entries means they actually don't belong to the specific version but they are not deleted in the pruning. The downside of the false-positive allowance is we may leave some "dangling" nodes in the disk. But in practice the it's very unlike the dangling node is state root. So in theory this pruned state shouldn't be visited anymore. Another potential issue is for fast sync. If we do another fast sync upon the pruned database, it's problematic which will stop the expansion during the syncing. TODO address it @rjl493456442 @holiman @karalabe.

After the entire state is generated, the bloom filter should be persisted into the disk. It indicates the whole generation procedure is finished.

func NewStateBloomFromDisk 

func NewStateBloomFromDisk(filename string) (*StateBloom, error)

NewStateBloomFromDisk loads the state bloom from the given file. In this case the assumption is held the bloom filter is complete.

func NewStateBloomWithSize 

func NewStateBloomWithSize(size uint64) (*StateBloom, error)

newStateBloomWithSize creates a brand new state bloom for state generation. The bloom filter will be created by the passing bloom filter size. According to the https://hur.st/bloomfilter/?n=600000000&p=&m=2048MB&k=4, the parameters are picked so that the false-positive rate for mainnet is low enough.

func (*StateBloom) Commit 

func (bloom *StateBloom) Commit(filename, tempname string) error

Commit flushes the bloom filter content into the disk and marks the bloom as complete.

func (*StateBloom) Contain 

func (bloom *StateBloom) Contain(key []byte) (bool, error)

Contain is the wrapper of the underlying contains function which reports whether the key is contained. - If it says yes, the key may be contained - If it says no, the key is definitely not contained.

func (*StateBloom) Delete 

func (bloom *StateBloom) Delete(key []byte) error

Delete removes the key from the key-value data store.

func (*StateBloom) Put 

func (bloom *StateBloom) Put(key []byte) error

Put implements the KeyValueWriter interface. But here only the key is needed.

type StateSnapshot 

type StateSnapshot struct {
	Accounts map[string][]byte
	Storages map[string]map[string][]byte
}

func NewStateSnapshot 

func NewStateSnapshot() *StateSnapshot

func (*StateSnapshot) AddStateTrie 

func (ts *StateSnapshot) AddStateTrie(root meter.Bytes32, db Database)

func (*StateSnapshot) SaveStateToFile 

func (ts *StateSnapshot) SaveStateToFile(prefix string) bool

type SyncResult 

type SyncResult struct {
	Hash meter.Bytes32 // Hash of the originally unknown trie node
	Data []byte        // Data content of the retrieved node
}

SyncResult is a simple list to return missing nodes along with their request hashes.

type Trie 

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

Trie is a Merkle Patricia Trie. The zero value is an empty trie with no database. Use New to create a trie that sits on top of a database.

Trie is not safe for concurrent use.

func New 

func New(root meter.Bytes32, db Database) (*Trie, error)

New creates a trie with an existing root node from db.

If root is the zero hash or the blake2b hash of an empty string, the trie is initially empty and does not require a database. Otherwise, New will panic if db is nil and returns a MissingNodeError if root does not exist in the database. Accessing the trie loads nodes from db on demand.

func (*Trie) Commit 

func (t *Trie) Commit() (root meter.Bytes32, err error)

Commit writes all nodes to the trie's database. Nodes are stored with their blake2b hash as the key.

Committing flushes nodes from memory. Subsequent Get calls will load nodes from the database.

func (*Trie) CommitTo 

func (t *Trie) CommitTo(db DatabaseWriter) (root meter.Bytes32, err error)

CommitTo writes all nodes to the given database. Nodes are stored with their blake2b hash as the key.

Committing flushes nodes from memory. Subsequent Get calls will load nodes from the trie's database. Calling code must ensure that the changes made to db are written back to the trie's attached database before using the trie.

func (*Trie) Delete 

func (t *Trie) Delete(key []byte)

Delete removes any existing value for key from the trie.

func (*Trie) Get 

func (t *Trie) Get(key []byte) []byte

Get returns the value for key stored in the trie. The value bytes must not be modified by the caller.

func (*Trie) Hash 

func (t *Trie) Hash() meter.Bytes32

Hash returns the root hash of the trie. It does not write to the database and can be used even if the trie doesn't have one.

func (*Trie) NodeIterator 

func (t *Trie) NodeIterator(start []byte) NodeIterator

NodeIterator returns an iterator that returns nodes of the trie. Iteration starts at the key after the given start key.

func (*Trie) Prove 

func (t *Trie) Prove(key []byte, fromLevel uint, proofDb DatabaseWriter) error

Prove constructs a merkle proof for key. The result contains all encoded nodes on the path to the value at key. The value itself is also included in the last node and can be retrieved by verifying the proof.

If the trie does not contain a value for key, the returned proof contains all nodes of the longest existing prefix of the key (at least the root node), ending with the node that proves the absence of the key.

func (*Trie) Root 

func (t *Trie) Root() []byte

Root returns the root hash of the trie. Deprecated: use Hash instead.

func (*Trie) SetCacheLimit 

func (t *Trie) SetCacheLimit(l uint16)

SetCacheLimit sets the number of 'cache generations' to keep. A cache generation is created by a call to Commit.

func (*Trie) TryDelete 

func (t *Trie) TryDelete(key []byte) error

TryDelete removes any existing value for key from the trie. If a node was not found in the database, a MissingNodeError is returned.

func (*Trie) TryGet 

func (t *Trie) TryGet(key []byte) ([]byte, error)

TryGet returns the value for key stored in the trie. The value bytes must not be modified by the caller. If a node was not found in the database, a MissingNodeError is returned.

func (*Trie) TryUpdate 

func (t *Trie) TryUpdate(key, value []byte) error

TryUpdate associates key with value in the trie. Subsequent calls to Get will return value. If value has length zero, any existing value is deleted from the trie and calls to Get will return nil.

The value bytes must not be modified by the caller while they are stored in the trie.

If a node was not found in the database, a MissingNodeError is returned.

func (*Trie) Update 

func (t *Trie) Update(key, value []byte)

Update associates key with value in the trie. Subsequent calls to Get will return value. If value has length zero, any existing value is deleted from the trie and calls to Get will return nil.

The value bytes must not be modified by the caller while they are stored in the trie.

type TrieAccount 

type TrieAccount struct {
	StateAccount
	Raw        []byte
	RawStorage map[meter.Bytes32][]byte
	Code       []byte
}

type TrieDelta 

type TrieDelta struct {
	Nodes        int    // count of added nodes
	Bytes        uint64 // count of added bytes
	StorageNodes int    //  count of added storage nodes on target trie
	StorageBytes uint64 // count of added storage bytes
	CodeCount    int
	CodeBytes    uint64
}

type TrieSnapshot 

type TrieSnapshot struct {
	Bloom    *StateBloom
	Accounts map[meter.Address]*TrieAccount
}

func NewTrieSnapshot 

func NewTrieSnapshot() *TrieSnapshot

func (*TrieSnapshot) AddTrie 

func (ts *TrieSnapshot) AddTrie(root meter.Bytes32, db Database)

func (*TrieSnapshot) Has 

func (ts *TrieSnapshot) Has(key meter.Bytes32) bool

func (*TrieSnapshot) LoadFromFile 

func (ts *TrieSnapshot) LoadFromFile(prefix string) bool

func (*TrieSnapshot) SaveToFile 

func (ts *TrieSnapshot) SaveToFile(prefix string) bool

func (*TrieSnapshot) String 

func (ts *TrieSnapshot) String() string

type TrieSync 

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

TrieSync is the main state trie synchronisation scheduler, which provides yet unknown trie hashes to retrieve, accepts node data associated with said hashes and reconstructs the trie step by step until all is done.

func NewTrieSync 

func NewTrieSync(root meter.Bytes32, database DatabaseReader, callback TrieSyncLeafCallback) *TrieSync

NewTrieSync creates a new trie data download scheduler.

func (*TrieSync) AddRawEntry 

func (s *TrieSync) AddRawEntry(hash meter.Bytes32, depth int, parent meter.Bytes32)

AddRawEntry schedules the direct retrieval of a state entry that should not be interpreted as a trie node, but rather accepted and stored into the database as is. This method's goal is to support misc state metadata retrievals (e.g. contract code).

func (*TrieSync) AddSubTrie 

func (s *TrieSync) AddSubTrie(root meter.Bytes32, depth int, parent meter.Bytes32, callback TrieSyncLeafCallback)

AddSubTrie registers a new trie to the sync code, rooted at the designated parent.

func (*TrieSync) Commit 

func (s *TrieSync) Commit(dbw DatabaseWriter) (int, error)

Commit flushes the data stored in the internal membatch out to persistent storage, returning th enumber of items written and any occurred error.

func (*TrieSync) Missing 

func (s *TrieSync) Missing(max int) []meter.Bytes32

Missing retrieves the known missing nodes from the trie for retrieval.

func (*TrieSync) Pending 

func (s *TrieSync) Pending() int

Pending returns the number of state entries currently pending for download.

func (*TrieSync) Process 

func (s *TrieSync) Process(results []SyncResult) (bool, int, error)

Process injects a batch of retrieved trie nodes data, returning if something was committed to the database and also the index of an entry if processing of it failed.

type TrieSyncLeafCallback 

type TrieSyncLeafCallback func(leaf []byte, parent meter.Bytes32) error

TrieSyncLeafCallback is a callback type invoked when a trie sync reaches a leaf node. It's used by state syncing to check if the leaf node requires some further data syncing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.