Documentation
¶
Overview ¶
Package trie implements Merkle Patricia Tries.
Index ¶
- Variables
- func CacheMisses() int64
- func CacheUnloads() int64
- func VerifyProof(rootHash common.Hash, key []byte, proof []rlp.RawValue) (value []byte, err error)
- type Database
- type DatabaseWriter
- type Iterator
- type MissingNodeError
- type NodeIterator
- type SecureTrie
- func (t *SecureTrie) Commit() (root common.Hash, err error)
- func (t *SecureTrie) CommitTo(db DatabaseWriter) (root common.Hash, err error)
- 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) Iterator() *Iterator
- func (t *SecureTrie) NodeIterator() *NodeIterator
- func (t *SecureTrie) Root() []byte
- func (t *SecureTrie) TryDelete(key []byte) error
- func (t *SecureTrie) TryGet(key []byte) ([]byte, error)
- func (t *SecureTrie) TryUpdate(key, value []byte) error
- func (t *SecureTrie) Update(key, value []byte)
- type SyncResult
- type Trie
- func (t *Trie) Commit() (root common.Hash, err error)
- func (t *Trie) CommitTo(db DatabaseWriter) (root common.Hash, err error)
- func (t *Trie) Delete(key []byte)
- func (t *Trie) Get(key []byte) []byte
- func (t *Trie) Hash() common.Hash
- func (t *Trie) Iterator() *Iterator
- func (t *Trie) Prove(key []byte) []rlp.RawValue
- func (t *Trie) Root() []byte
- func (t *Trie) SetCacheLimit(l uint16)
- func (t *Trie) TryDelete(key []byte) error
- func (t *Trie) TryGet(key []byte) ([]byte, error)
- func (t *Trie) TryUpdate(key, value []byte) error
- func (t *Trie) Update(key, value []byte)
- type TrieSync
- func (s *TrieSync) AddRawEntry(hash common.Hash, depth int, parent common.Hash)
- func (s *TrieSync) AddSubTrie(root common.Hash, depth int, parent common.Hash, callback TrieSyncLeafCallback)
- func (s *TrieSync) Missing(max int) []common.Hash
- func (s *TrieSync) Pending() int
- func (s *TrieSync) Process(results []SyncResult) (bool, int, error)
- type TrieSyncLeafCallback
Constants ¶
This section is empty.
Variables ¶
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 ¶ added in v1.5.0
func CacheMisses() int64
CacheMisses retrieves a global counter measuring the number of cache misses the trie did since process startup. This isn't useful for anything apart from trie debugging purposes.
func CacheUnloads ¶ added in v1.5.0
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 VerifyProof ¶ added in v1.3.1
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 Database ¶ added in v1.3.1
type Database interface { DatabaseWriter // Get returns the value for key from the database. Get(key []byte) (value []byte, err error) }
Database must be implemented by backing stores for the trie.
type DatabaseWriter ¶ added in v1.3.1
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 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 // contains filtered or unexported fields }
Iterator is a key-value trie iterator that traverses a Trie.
func NewIterator ¶
NewIterator creates a new key-value iterator.
type MissingNodeError ¶ added in v1.4.0
MissingNodeError is returned by the trie functions (TryGet, TryUpdate, TryDelete) in the case where a trie node is not present in the local database. Contains information necessary for retrieving the missing node through an ODR service.
NodeHash is the hash of the missing node ¶
RootHash is the original root of the trie that contains the node ¶
Key is a binary-encoded key that contains the prefix that leads to the first missing node and optionally a suffix that hints on which further nodes should also be retrieved
PrefixLen is the nibble length of the key prefix that leads from the root to the missing node
SuffixLen is the nibble length of the remaining part of the key that hints on which further nodes should also be retrieved (can be zero when there are no such hints in the error message)
func (*MissingNodeError) Error ¶ added in v1.4.0
func (err *MissingNodeError) Error() string
type NodeIterator ¶ added in v1.4.0
type NodeIterator struct { Hash common.Hash // Hash of the current node being iterated (nil if not standalone) Node node // Current node being iterated (internal representation) Parent common.Hash // Hash of the first full ancestor node (nil if current is the root) Leaf bool // Flag whether the current node is a value (data) node LeafBlob []byte // Data blob contained within a leaf (otherwise nil) Error error // Failure set in case of an internal error in the iterator // contains filtered or unexported fields }
NodeIterator is an iterator to traverse the trie post-order.
func NewNodeIterator ¶ added in v1.4.0
func NewNodeIterator(trie *Trie) *NodeIterator
NewNodeIterator creates an post-order trie iterator.
func (*NodeIterator) Next ¶ added in v1.4.0
func (it *NodeIterator) Next() bool
Next moves the iterator to the next node, returning whether there are any further nodes. In case of an internal error this method returns false and sets the Error field to the encountered failure.
type SecureTrie ¶ added in v0.9.17
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 ¶ added in v0.9.17
NewSecure creates a trie with an existing root node from db.
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 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 ¶ added in v1.4.0
func (t *SecureTrie) Commit() (root common.Hash, err 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) CommitTo ¶ added in v1.4.0
func (t *SecureTrie) CommitTo(db DatabaseWriter) (root common.Hash, err error)
CommitTo writes all nodes and the secure hash pre-images to the given database. Nodes are stored with their sha3 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) Delete ¶ added in v0.9.17
func (t *SecureTrie) Delete(key []byte)
Delete removes any existing value for key from the trie.
func (*SecureTrie) Get ¶ added in v0.9.17
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 ¶ added in v0.9.17
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 ¶ added in v1.4.14
func (t *SecureTrie) Hash() common.Hash
func (*SecureTrie) Iterator ¶ added in v1.4.14
func (t *SecureTrie) Iterator() *Iterator
func (*SecureTrie) NodeIterator ¶ added in v1.4.14
func (t *SecureTrie) NodeIterator() *NodeIterator
func (*SecureTrie) Root ¶ added in v1.4.14
func (t *SecureTrie) Root() []byte
func (*SecureTrie) TryDelete ¶ added in v1.4.0
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 ¶ added in v1.4.0
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 ¶ added in v1.4.0
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 ¶ added in v0.9.17
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 SyncResult ¶ added in v1.3.1
type SyncResult struct { Hash common.Hash // 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 ¶
New creates a trie with an existing root node from db.
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 (*Trie) Commit ¶ added in v0.8.5
Commit writes all nodes 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 (*Trie) CommitTo ¶ added in v1.3.1
func (t *Trie) CommitTo(db DatabaseWriter) (root common.Hash, err error)
CommitTo writes all nodes to the given database. Nodes are stored with their sha3 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) Get ¶
Get returns the value for key stored in the trie. The value bytes must not be modified by the caller.
func (*Trie) Hash ¶ added in v0.8.5
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) Prove ¶ added in v1.3.1
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) SetCacheLimit ¶ added in v1.4.18
SetCacheLimit sets the number of 'cache generations' to keep. A cache generations is created by a call to Commit.
func (*Trie) TryDelete ¶ added in v1.4.0
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 ¶ added in v1.4.0
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 ¶ added in v1.4.0
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 ¶
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 TrieSync ¶ added in v1.3.1
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 ¶ added in v1.3.1
func NewTrieSync(root common.Hash, database ethdb.Database, callback TrieSyncLeafCallback) *TrieSync
NewTrieSync creates a new trie data download scheduler.
func (*TrieSync) AddRawEntry ¶ added in v1.3.1
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 ¶ added in v1.3.1
func (s *TrieSync) AddSubTrie(root common.Hash, depth int, parent common.Hash, callback TrieSyncLeafCallback)
AddSubTrie registers a new trie to the sync code, rooted at the designated parent.
func (*TrieSync) Missing ¶ added in v1.3.1
Missing retrieves the known missing nodes from the trie for retrieval.