Documentation ¶
Overview ¶
Package trie implements Merkle Patricia Tries.
Index ¶
- Variables
- func AssertTrieConsistency(t testing.TB, root common.Hash, a, b *Database, ...)
- func CorruptTrie(t *testing.T, trieDB *Database, root common.Hash, n int)
- func FillAccounts(t *testing.T, trieDB *Database, root common.Hash, numAccounts int, ...) (common.Hash, map[*keystore.Key]*types.StateAccount)
- func FillTrie(t *testing.T, numKeys int, keySize int, testTrie *Trie) ([][]byte, [][]byte)
- func GenerateTrie(t *testing.T, trieDB *Database, numKeys int, keySize int) (common.Hash, [][]byte, [][]byte)
- func VerifyProof(rootHash common.Hash, key []byte, proofDb ethdb.KeyValueReader) (value []byte, err error)
- func VerifyRangeProof(rootHash common.Hash, firstKey []byte, lastKey []byte, keys [][]byte, ...) (bool, error)
- type Config
- type Database
- func (db *Database) Cap(limit common.StorageSize) error
- func (db *Database) Commit(node common.Hash, report bool, callback func(common.Hash)) error
- func (db *Database) Dereference(root common.Hash)
- func (db *Database) DiskDB() ethdb.KeyValueStore
- func (db *Database) EncodedNode(h common.Hash) node
- func (db *Database) Insert(hash common.Hash, size int, node node)
- func (db *Database) InsertPreimages(preimages map[string][]byte)
- func (db *Database) Nodes() []common.Hash
- func (db *Database) Preimage(hash common.Hash) []byte
- func (db *Database) RawNode(h common.Hash) ([]byte, error)
- func (db *Database) Reference(child common.Hash, parent common.Hash)
- func (db *Database) Size() (common.StorageSize, common.StorageSize)
- func (db *Database) WritePreimages(limit common.StorageSize) error
- type Iterator
- type LeafCallback
- type MissingNodeError
- type NodeIterator
- type SecureTrie
- func (t *SecureTrie) Commit(onleaf LeafCallback) (common.Hash, int, error)
- func (t *SecureTrie) Copy() *SecureTrie
- func (t *SecureTrie) Delete(key []byte)
- func (t *SecureTrie) Get(key []byte) []byte
- func (t *SecureTrie) GetKey(shaKey []byte) []byte
- func (t *SecureTrie) Hash() common.Hash
- func (t *SecureTrie) NodeIterator(start []byte) NodeIterator
- func (t *SecureTrie) Prove(key []byte, fromLevel uint, proofDb ethdb.KeyValueWriter) error
- func (t *SecureTrie) TryDelete(key []byte) error
- func (t *SecureTrie) TryGet(key []byte) ([]byte, error)
- func (t *SecureTrie) TryGetNode(path []byte) ([]byte, int, error)
- func (t *SecureTrie) TryUpdate(key, value []byte) error
- func (t *SecureTrie) TryUpdateAccount(key []byte, acc *types.StateAccount) error
- func (t *SecureTrie) Update(key, value []byte)
- type StackTrie
- func (st *StackTrie) Commit() (h common.Hash, err error)
- func (st *StackTrie) Hash() (h common.Hash)
- func (st *StackTrie) MarshalBinary() (data []byte, err error)
- func (st *StackTrie) Reset()
- func (st *StackTrie) TryUpdate(key, value []byte) error
- func (st *StackTrie) UnmarshalBinary(data []byte) error
- func (st *StackTrie) Update(key, value []byte)
- type Trie
- func (t *Trie) Commit(onleaf LeafCallback) (common.Hash, int, error)
- func (t *Trie) Copy() *Trie
- func (t *Trie) Delete(key []byte)
- func (t *Trie) Get(key []byte) []byte
- func (t *Trie) Hash() common.Hash
- func (t *Trie) NodeIterator(start []byte) NodeIterator
- func (t *Trie) Owner() common.Hash
- func (t *Trie) Prove(key []byte, fromLevel uint, proofDb ethdb.KeyValueWriter) error
- func (t *Trie) Reset()
- func (t *Trie) TryDelete(key []byte) error
- func (t *Trie) TryGet(key []byte) ([]byte, error)
- func (t *Trie) TryGetNode(path []byte) ([]byte, int, error)
- func (t *Trie) TryUpdate(key, value []byte) error
- func (t *Trie) TryUpdateAccount(key []byte, acc *types.StateAccount) error
- func (t *Trie) Update(key, value []byte)
Constants ¶
This section is empty.
Variables ¶
var ErrCommitDisabled = errors.New("no database for committing")
Functions ¶
func AssertTrieConsistency ¶
func AssertTrieConsistency(t testing.TB, root common.Hash, a, b *Database, onLeaf func(key, val []byte) error)
AssertTrieConsistency ensures given trieDB [a] and [b] both have the same non-empty trie at [root]. (all key/value pairs must be equal)
func CorruptTrie ¶
CorruptTrie deletes every [n]th trie node from the trie given by [root] from the trieDB. Assumes that the trie given by root can be iterated without issue.
func FillAccounts ¶
func FillAccounts( t *testing.T, trieDB *Database, root common.Hash, numAccounts int, onAccount func(*testing.T, int, types.StateAccount) types.StateAccount, ) (common.Hash, map[*keystore.Key]*types.StateAccount)
FillAccounts adds [numAccounts] randomly generated accounts to the secure trie at [root] and commits it to [trieDB]. [onAccount] is called if non-nil (so the caller can modify the account before it is stored in the secure trie). returns the new trie root and a map of funded keys to StateAccount structs.
func FillTrie ¶
FillTrie fills a given trie with [numKeys] number of keys, each of size [keySize] returns inserted keys and values FillTrie reads from rand and the caller should call rand.Seed(n) for deterministic results
func GenerateTrie ¶
func GenerateTrie(t *testing.T, trieDB *Database, numKeys int, keySize int) (common.Hash, [][]byte, [][]byte)
GenerateTrie creates a trie with [numKeys] key-value pairs inside of [trieDB]. Returns the root of the generated trie, the slice of keys inserted into the trie in lexicographical order, and the slice of corresponding values. GenerateTrie reads from rand and the caller should call rand.Seed(n) for deterministic results
func VerifyProof ¶
func VerifyProof(rootHash common.Hash, key []byte, proofDb ethdb.KeyValueReader) (value []byte, err error)
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.
func VerifyRangeProof ¶
func VerifyRangeProof(rootHash common.Hash, firstKey []byte, lastKey []byte, keys [][]byte, values [][]byte, proof ethdb.KeyValueReader) (bool, error)
VerifyRangeProof checks whether the given leaf nodes and edge proof can prove the given trie leaves range is matched with the specific root. Besides, the range should be consecutive (no gap inside) and monotonic increasing.
Note the given proof actually contains two edge proofs. Both of them can be non-existent proofs. For example the first proof is for a non-existent key 0x03, the last proof is for a non-existent key 0x10. The given batch leaves are [0x04, 0x05, .. 0x09]. It's still feasible to prove the given batch is valid.
The firstKey is paired with firstProof, not necessarily the same as keys[0] (unless firstProof is an existent proof). Similarly, lastKey and lastProof are paired.
Expect the normal case, this function can also be used to verify the following range proofs:
- All elements proof. In this case the proof can be nil, but the range should be all the leaves in the trie.
- One element proof. In this case no matter the edge proof is a non-existent proof or not, we can always verify the correctness of the proof.
- Zero element proof. In this case a single non-existent proof is enough to prove. Besides, if there are still some other leaves available on the right side, then an error will be returned.
Except returning the error to indicate the proof is valid or not, the function will also return a flag to indicate whether there exists more accounts/slots in the trie.
Note: This method does not verify that the proof is of minimal form. If the input proofs are 'bloated' with neighbour leaves or random data, aside from the 'useful' data, then the proof will still be accepted.
Types ¶
type Config ¶
type Config struct { Cache int // Memory allowance (MB) to use for caching trie nodes in memory Preimages bool // Flag whether the preimage of trie key is recorded }
Config defines all necessary options for database.
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
Database is an intermediate write layer between the trie data structures and the disk database. The aim is to accumulate trie writes in-memory and only periodically flush a couple tries to disk, garbage collecting the remainder.
The trie Database is thread-safe in its mutations and is thread-safe in providing individual, independent node access.
func NewDatabase ¶
func NewDatabase(diskdb ethdb.KeyValueStore) *Database
NewDatabase creates a new trie database to store ephemeral trie content before its written out to disk or garbage collected. No read cache is created, so all data retrievals will hit the underlying disk database.
func NewDatabaseWithConfig ¶
func NewDatabaseWithConfig(diskdb ethdb.KeyValueStore, config *Config) *Database
NewDatabaseWithConfig creates a new trie database to store ephemeral trie content before its written out to disk or garbage collected. It also acts as a read cache for nodes loaded from disk.
func (*Database) Cap ¶
func (db *Database) Cap(limit common.StorageSize) error
Cap iteratively flushes old but still referenced trie nodes until the total memory usage goes below the given threshold.
func (*Database) Commit ¶
Commit iterates over all the children of a particular node, writes them out to disk, forcefully tearing down all references in both directions. As a side effect, all pre-images accumulated up to this point are also written.
func (*Database) Dereference ¶
Dereference removes an existing reference from a root node.
func (*Database) DiskDB ¶
func (db *Database) DiskDB() ethdb.KeyValueStore
DiskDB retrieves the persistent storage backing the trie database.
func (*Database) EncodedNode ¶
EncodedNode returns a formatted [node] when given a node hash. If no node exists, nil is returned. This function will return the metaroot.
func (*Database) Insert ¶
insert inserts a collapsed trie node into the memory database. The blob size must be specified to allow proper size tracking. All nodes inserted by this function will be reference tracked and in theory should only used for **trie nodes** insertion.
func (*Database) InsertPreimages ¶
InsertPreimages writes a map of new trie node preimages to the memory database if it's yet unknown.
The method will NOT make a copy of the provided slice, only use if the preimage will NOT be changed later on.
func (*Database) Nodes ¶
Nodes retrieves the hashes of all the nodes cached within the memory database. This method is extremely expensive and should only be used to validate internal states in test code.
func (*Database) Preimage ¶
Preimage retrieves a cached trie node pre-image from memory. If it cannot be found cached, the method queries the persistent database for the content.
func (*Database) RawNode ¶
RawNode retrieves an encoded cached trie node from memory. If it cannot be found cached, the method queries the persistent database for the content. This function will not return the metaroot.
func (*Database) Reference ¶
Reference adds a new reference from a parent node to a child node. This function is used to add reference between internal trie node and external node(e.g. storage trie root), all internal trie nodes are referenced together by database itself.
func (*Database) Size ¶
func (db *Database) Size() (common.StorageSize, common.StorageSize)
Size returns the current storage size of the memory cache in front of the persistent database layer.
func (*Database) WritePreimages ¶
func (db *Database) WritePreimages(limit common.StorageSize) error
WritePreimages writes all preimages to disk if more than [limit] are currently in memory.
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. Note that the value returned by the iterator is raw. If the content is encoded (e.g. storage value is RLP-encoded), it's caller's duty to decode it.
type LeafCallback ¶
LeafCallback is a callback type invoked when a trie operation reaches a leaf node.
The paths is a path tuple identifying a particular trie node either in a single trie (account) or a layered trie (account -> storage). Each path in the tuple is in the raw format(32 bytes).
The hexpath is a composite hexary path identifying the trie node. All the key bytes are converted to the hexary nibbles and composited with the parent path if the trie node is in a layered trie.
It's used by state sync and commit to allow handling external references between account and storage tries. And also it's used in the state healing for extracting the raw states(leaf nodes) with corresponding paths.
type MissingNodeError ¶
type MissingNodeError struct { Owner common.Hash // owner of the trie if it's 2-layered trie NodeHash common.Hash // hash of the missing node Path []byte // hex-encoded path to the missing node // contains filtered or unexported fields }
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
func (*MissingNodeError) Unwrap ¶ added in v0.8.15
func (err *MissingNodeError) Unwrap() error
Unwrap returns the concrete error for missing trie node which allows us for further analysis outside.
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() common.Hash // 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() common.Hash // 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 // NodeBlob returns the rlp-encoded value of the current iterated node. // If the node is an embedded node in its parent, nil is returned then. NodeBlob() []byte // Leaf returns true iff the current node is a leaf node. Leaf() bool // LeafKey returns the key of the leaf. The method panics if the iterator is not // positioned at a leaf. Callers must not retain references to the value after // calling Next. LeafKey() []byte // LeafBlob returns the content of the leaf. The method panics if the iterator // is not positioned at a leaf. Callers must not retain references to the value // after calling Next. LeafBlob() []byte // LeafProof returns the Merkle proof of the leaf. The method panics if the // iterator is not positioned at a leaf. Callers must not retain references // to the value after calling Next. LeafProof() [][]byte // AddResolver sets an intermediate database to use for looking up trie nodes // before reaching into the real persistent layer. // // This is not required for normal operation, rather is an optimization for // cases where trie nodes can be recovered from some external mechanism without // reading from disk. In those cases, this resolver allows short circuiting // accesses and returning them from memory. // // Before adding a similar mechanism to any other place in Geth, consider // making trie.Database an interface and wrapping at that level. It's a huge // refactor, but it could be worth it if another occurrence arises. AddResolver(ethdb.KeyValueReader) }
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 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 keccak256. 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 ¶
NewSecure creates a trie with an existing root node from a backing database and optional intermediate in-memory node pool.
If root is the zero hash or the sha3 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 the database or node pool 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(onleaf LeafCallback) (common.Hash, int, error)
Commit writes all nodes and the secure hash pre-images to the trie's database. Nodes are stored with their sha3 hash as the key.
Committing flushes nodes from memory. Subsequent Get calls will load nodes from the database.
func (*SecureTrie) Copy ¶
func (t *SecureTrie) Copy() *SecureTrie
Copy returns a copy of 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() common.Hash
Hash returns the root hash of SecureTrie. It does not write to the database and can be used even if the trie doesn't have one.
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) Prove ¶
func (t *SecureTrie) Prove(key []byte, fromLevel uint, proofDb ethdb.KeyValueWriter) 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 (*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) TryGetNode ¶
func (t *SecureTrie) TryGetNode(path []byte) ([]byte, int, error)
TryGetNode attempts to retrieve a trie node by compact-encoded path. It is not possible to use keybyte-encoding as the path might contain odd nibbles.
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) TryUpdateAccount ¶
func (t *SecureTrie) TryUpdateAccount(key []byte, acc *types.StateAccount) error
TryUpdateAccount account will abstract the write of an account to the secure trie.
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 StackTrie ¶
type StackTrie struct {
// contains filtered or unexported fields
}
StackTrie is a trie implementation that expects keys to be inserted in order. Once it determines that a subtree will no longer be inserted into, it will hash it and free up the memory it uses.
func NewFromBinary ¶
func NewFromBinary(data []byte, db ethdb.KeyValueWriter) (*StackTrie, error)
NewFromBinary initialises a serialized stacktrie with the given db.
func NewStackTrie ¶
func NewStackTrie(db ethdb.KeyValueWriter) *StackTrie
NewStackTrie allocates and initializes an empty trie.
func NewStackTrieWithOwner ¶ added in v0.8.15
func NewStackTrieWithOwner(db ethdb.KeyValueWriter, owner common.Hash) *StackTrie
NewStackTrieWithOwner allocates and initializes an empty trie, but with the additional owner field.
func (*StackTrie) Commit ¶
Commit will firstly hash the entrie trie if it's still not hashed and then commit all nodes to the associated database. Actually most of the trie nodes MAY have been committed already. The main purpose here is to commit the root node.
The associated database is expected, otherwise the whole commit functionality should be disabled.
func (*StackTrie) MarshalBinary ¶
MarshalBinary implements encoding.BinaryMarshaler
func (*StackTrie) UnmarshalBinary ¶
UnmarshalBinary implements encoding.BinaryUnmarshaler
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 ¶
New creates a trie with an existing root node from db and an assigned owner for storage proximity.
If root is the zero hash or the sha3 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 NewEmpty ¶ added in v0.8.15
NewEmpty is a shortcut to create empty tree. It's mostly used in tests.
func (*Trie) Commit ¶
Commit writes all nodes to the trie's memory database, tracking the internal and external (for account tries) references.
func (*Trie) Get ¶
Get returns the value for key stored in the trie. The value bytes must not be modified by the caller.
func (*Trie) Hash ¶
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 ¶
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) Reset ¶
func (t *Trie) Reset()
Reset drops the referenced root node and cleans all internal state.
func (*Trie) TryDelete ¶
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 ¶
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) TryGetNode ¶
TryGetNode attempts to retrieve a trie node by compact-encoded path. It is not possible to use keybyte-encoding as the path might contain odd nibbles.
func (*Trie) TryUpdate ¶
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) TryUpdateAccount ¶
func (t *Trie) TryUpdateAccount(key []byte, acc *types.StateAccount) error
func (*Trie) Update ¶
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.