trie

Documentation

Overview

Package trie implements Merkle Patricia Tries.

Index

• Variables
• func VerifyProof(rootHash common.Hash, key []byte, proof []rlp.RawValue) (value []byte, err error)
• type Database
• type DatabaseWriter
• type Iterator
  • func NewIterator(trie *Trie) *Iterator
  • func (self *Iterator) Next() bool
• type SecureTrie
  • func NewSecure(root common.Hash, db Database) (*SecureTrie, error)
  • func (t *SecureTrie) Delete(key []byte)
  • func (t *SecureTrie) Get(key []byte) []byte
  • func (t *SecureTrie) GetKey(shaKey []byte) []byte
  • func (t *SecureTrie) Update(key, value []byte)
• type SyncResult
• type Trie
  • func New(root common.Hash, db Database) (*Trie, error)
  • 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) Update(key, value []byte)
• type TrieSync
  • func NewTrieSync(root common.Hash, database pbfdb.Database, callback TrieSyncLeafCallback) *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) (int, error)
• type TrieSyncLeafCallback

Variables

var ErrMissingRoot = errors.New("missing root node")

Functions

func VerifyProof

func VerifyProof(rootHash common.Hash, key []byte, proof []rlp.RawValue) (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.

Types

type Database

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

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
	Value []byte
	// contains filtered or unexported fields
}

func NewIterator

func NewIterator(trie *Trie) *Iterator

func (*Iterator) Next

func (self *Iterator) Next() bool

type SecureTrie

type SecureTrie struct {
	*Trie
	// 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

func NewSecure(root common.Hash, db Database) (*SecureTrie, error)

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 panics if db is nil and returns ErrMissingRoot if the root node cannpt be found. Accessing the trie loads nodes from db on demand.

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) 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 SyncResult

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

func New(root common.Hash, db Database) (*Trie, error)

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 panics if db is nil or root does not exist in the database. Accessing the trie loads nodes from db on demand.

func (*Trie) Commit

func (t *Trie) Commit() (root common.Hash, err error)

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

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) 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() common.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) Iterator

func (t *Trie) Iterator() *Iterator

Iterator returns an iterator over all mappings in the trie.

func (*Trie) Prove

func (t *Trie) Prove(key []byte) []rlp.RawValue

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.

The returned proof is nil if the trie does not contain a value for key. For existing keys, the proof will have at least one element.

func (*Trie) Root

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

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

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 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 common.Hash, database pbfdb.Database, callback TrieSyncLeafCallback) *TrieSync

NewTrieSync creates a new trie data download scheduler.

func (*TrieSync) AddRawEntry

func (s *TrieSync) AddRawEntry(hash common.Hash, depth int, parent common.Hash)

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 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

func (s *TrieSync) Missing(max int) []common.Hash

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) (int, error)

Process injects a batch of retrieved trie nodes data.

type TrieSyncLeafCallback

type TrieSyncLeafCallback func(leaf []byte, parent common.Hash) 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.