github.com/klaytn/klaytn@v1.12.1/storage/statedb/trie.go

// Modifications Copyright 2018 The klaytn Authors
// Copyright 2015 The go-ethereum Authors
// This file is part of the go-ethereum library.
//
// The go-ethereum library is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// The go-ethereum library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
//
// This file is derived from trie/trie.go (2018/06/04).
// Modified and improved for the klaytn development.

package statedb

import (
	"bytes"
	"errors"
	"fmt"

	"github.com/klaytn/klaytn/common"
	"github.com/klaytn/klaytn/crypto"
)

var (
	// emptyRoot is the known root hash of an empty trie.
	emptyRoot = common.HexToHash("56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421")

	// emptyState is the known hash of an empty state trie entry.
	emptyState = crypto.Keccak256Hash(nil)
)

// TrieOpts consists of trie operation options
type TrieOpts struct {
	Prefetching bool // If true, certain metric is enabled

	// If PruningBlockNumber is nonzero, trie update and delete operations
	// will schedule obsolete nodes to be pruned when the given block number becomes obsolete.
	// This option is only viable when the pruning is enabled on database.
	PruningBlockNumber uint64
}

// 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 LeafCallback func(paths [][]byte, hexpath []byte, leaf []byte, parent common.ExtHash, parentDepth int) error

// Trie is a Merkle Patricia Trie.
// The zero value is an empty trie with no database.
// Use NewTrie to create a trie that sits on top of a database.
//
// Trie is not safe for concurrent use.
type Trie struct {
	TrieOpts
	db           *Database
	root         node
	originalRoot common.ExtHash

	pruning           bool // True if the underlying database has pruning enabled.
	storage           bool // If storage and Pruning are both true, root hash is attached a fresh nonce.
	pruningMarksCache map[common.ExtHash]uint64
}

// newFlag returns the cache flag value for a newly created node.
func (t *Trie) newFlag() nodeFlag {
	return nodeFlag{dirty: true}
}

// NewTrie 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,
// NewTrie 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 NewTrie(root common.Hash, db *Database, opts *TrieOpts) (*Trie, error) {
	return newTrie(root.ExtendZero(), db, opts, false)
}

// NewStorageTrie creates a storage 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,
// NewTrie 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.
//
// A storage trie is identified with an ExtHash root node. With Live Pruning enabled,
// its root hash will be extended with a nonzero nonce.
func NewStorageTrie(root common.ExtHash, db *Database, opts *TrieOpts) (*Trie, error) {
	return newTrie(root, db, opts, true)
}

func newTrie(root common.ExtHash, db *Database, opts *TrieOpts, storage bool) (*Trie, error) {
	if db == nil {
		panic("statedb.NewTrie called without a database")
	}
	if opts == nil {
		opts = &TrieOpts{}
	}

	trie := &Trie{
		TrieOpts:          *opts,
		db:                db,
		originalRoot:      root,
		pruning:           db.diskDB.ReadPruningEnabled(),
		storage:           storage,
		pruningMarksCache: make(map[common.ExtHash]uint64),
	}
	if !trie.pruning && trie.PruningBlockNumber != 0 {
		return nil, ErrPruningDisabled
	}
	if !common.EmptyExtHash(root) && root.Unextend() != emptyRoot {
		rootnode, err := trie.resolveHash(root[:], nil)
		if err != nil {
			return nil, err
		}
		trie.root = rootnode
	}
	return trie, nil
}

// NodeIterator returns an iterator that returns nodes of the trie. Iteration starts at
// the key after the given start key.
func (t *Trie) NodeIterator(start []byte) NodeIterator {
	return newNodeIterator(t, start)
}

// Get returns the value for key stored in the trie.
// The value bytes must not be modified by the caller.
func (t *Trie) Get(key []byte) []byte {
	res, err := t.TryGet(key)
	if err != nil {
		logger.Error("Unhandled trie error in Trie.Get", "err", err)
	}
	return res
}

// 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 (t *Trie) TryGet(key []byte) ([]byte, error) {
	key = keybytesToHex(key)
	value, newroot, didResolve, err := t.tryGet(t.root, key, 0)
	if err == nil && didResolve {
		t.root = newroot
	}
	return value, err
}

func (t *Trie) tryGet(origNode node, key []byte, pos int) (value []byte, newnode node, didResolve bool, err error) {
	switch n := (origNode).(type) {
	case nil:
		return nil, nil, false, nil
	case valueNode:
		return n, n, false, nil
	case *shortNode:
		if len(key)-pos < len(n.Key) || !bytes.Equal(n.Key, key[pos:pos+len(n.Key)]) {
			// key not found in trie
			return nil, n, false, nil
		}
		value, newnode, didResolve, err = t.tryGet(n.Val, key, pos+len(n.Key))
		if err == nil && didResolve {
			n = n.copy()
			n.Val = newnode
		}
		return value, n, didResolve, err
	case *fullNode:
		value, newnode, didResolve, err = t.tryGet(n.Children[key[pos]], key, pos+1)
		if err == nil && didResolve {
			n = n.copy()
			n.Children[key[pos]] = newnode
		}
		return value, n, didResolve, err
	case hashNode:
		child, err := t.resolveHash(n, key[:pos])
		if err != nil {
			return nil, n, true, err
		}
		value, newnode, _, err := t.tryGet(child, key, pos)
		return value, newnode, true, err
	default:
		panic(fmt.Sprintf("%T: invalid node: %v", origNode, origNode))
	}
}

// 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 (t *Trie) TryGetNode(path []byte) ([]byte, int, error) {
	item, newroot, resolved, err := t.tryGetNode(t.root, compactToHex(path), 0)
	if err != nil {
		return nil, resolved, err
	}
	if resolved > 0 {
		t.root = newroot
	}
	if item == nil {
		return nil, resolved, nil
	}
	return item, resolved, err
}

func (t *Trie) tryGetNode(origNode node, path []byte, pos int) (item []byte, newnode node, resolved int, err error) {
	// If non-existent path requested, abort
	if origNode == nil {
		return nil, nil, 0, nil
	}
	// If we reached the requested path, return the current node
	if pos >= len(path) {
		// Although we most probably have the original node expanded, encoding
		// that into consensus form can be nasty (needs to cascade down) and
		// time consuming. Instead, just pull the hash up from disk directly.
		var hash hashNode
		if node, ok := origNode.(hashNode); ok {
			hash = node
		} else {
			hash, _ = origNode.cache()
		}
		if hash == nil {
			return nil, origNode, 0, errors.New("non-consensus node")
		}
		blob, err := t.db.Node(common.BytesToExtHash(hash))
		return blob, origNode, 1, err
	}
	// Path still needs to be traversed, descend into children
	switch n := (origNode).(type) {
	case valueNode:
		// Path prematurely ended, abort
		return nil, nil, 0, nil

	case *shortNode:
		if len(path)-pos < len(n.Key) || !bytes.Equal(n.Key, path[pos:pos+len(n.Key)]) {
			// Path branches off from short node
			return nil, n, 0, nil
		}
		item, newnode, resolved, err = t.tryGetNode(n.Val, path, pos+len(n.Key))
		if err == nil && resolved > 0 {
			n = n.copy()
			n.Val = newnode
		}
		return item, n, resolved, err

	case *fullNode:
		item, newnode, resolved, err = t.tryGetNode(n.Children[path[pos]], path, pos+1)
		if err == nil && resolved > 0 {
			n = n.copy()
			n.Children[path[pos]] = newnode
		}
		return item, n, resolved, err

	case hashNode:
		child, err := t.resolveHash(n, path[:pos])
		if err != nil {
			return nil, n, 1, err
		}
		item, newnode, resolved, err := t.tryGetNode(child, path, pos)
		return item, newnode, resolved + 1, err

	default:
		panic(fmt.Sprintf("%T: invalid node: %v", origNode, origNode))
	}
}

// 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.
func (t *Trie) Update(key, value []byte) {
	if err := t.TryUpdate(key, value); err != nil {
		logger.Error("Unhandled trie error in Trie.Update", "err", err)
	}
}

// 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 (t *Trie) TryUpdate(key, value []byte) error {
	hexKey := keybytesToHex(key)
	return t.TryUpdateWithHexKey(hexKey, value)
}

// TryUpdateWithHexKey uses pre-generated hexKey.
// It is both called from TryUpdate and SecureTrie.TryUpdateWithKeys.
func (t *Trie) TryUpdateWithHexKey(hexKey, value []byte) error {
	if len(value) != 0 {
		_, n, err := t.insert(t.root, nil, hexKey, valueNode(value))
		if err != nil {
			return err
		}
		t.root = n
	} else {
		_, n, err := t.delete(t.root, nil, hexKey)
		if err != nil {
			return err
		}
		t.root = n
	}
	return nil
}

func (t *Trie) insert(n node, prefix, key []byte, value node) (bool, node, error) {
	if len(key) == 0 {
		if v, ok := n.(valueNode); ok {
			return !bytes.Equal(v, value.(valueNode)), value, nil
		}
		return true, value, nil
	}
	switch n := n.(type) {
	case *shortNode:
		matchlen := prefixLen(key, n.Key)
		// If the whole key matches, keep this short node as is
		// and only update the value.
		if matchlen == len(n.Key) {
			dirty, nn, err := t.insert(n.Val, append(prefix, key[:matchlen]...), key[matchlen:], value)
			if !dirty || err != nil {
				return false, n, err
			}
			t.markPrunableNode(n) // dirty; something's changed in the child
			return true, &shortNode{n.Key, nn, t.newFlag()}, nil
		}
		// Otherwise branch out at the index where they differ.
		branch := &fullNode{flags: t.newFlag()}
		var err error
		_, branch.Children[n.Key[matchlen]], err = t.insert(nil, append(prefix, n.Key[:matchlen+1]...), n.Key[matchlen+1:], n.Val)
		if err != nil {
			return false, nil, err
		}
		_, branch.Children[key[matchlen]], err = t.insert(nil, append(prefix, key[:matchlen+1]...), key[matchlen+1:], value)
		if err != nil {
			return false, nil, err
		}
		t.markPrunableNode(n) // this node has changed
		// Replace this shortNode with the branch if it occurs at index 0.
		if matchlen == 0 {
			return true, branch, nil
		}
		// Otherwise, replace it with a short node leading up to the branch.
		return true, &shortNode{key[:matchlen], branch, t.newFlag()}, nil

	case *fullNode:
		dirty, nn, err := t.insert(n.Children[key[0]], append(prefix, key[0]), key[1:], value)
		if !dirty || err != nil {
			return false, n, err
		}
		t.markPrunableNode(n) // dirty; something's changed in the child
		n = n.copy()
		n.flags = t.newFlag()
		n.Children[key[0]] = nn
		return true, n, nil

	case nil:
		return true, &shortNode{key, value, t.newFlag()}, nil

	case hashNode:
		// We've hit a part of the trie that isn't loaded yet. Load
		// the node and insert into it. This leaves all child nodes on
		// the path to the value in the trie.
		rn, err := t.resolveHash(n, prefix)
		if err != nil {
			return false, nil, err
		}
		dirty, nn, err := t.insert(rn, prefix, key, value)
		if !dirty || err != nil {
			return false, rn, err
		}
		return true, nn, nil

	default:
		panic(fmt.Sprintf("%T: invalid node: %v", n, n))
	}
}

// Delete removes any existing value for key from the trie.
func (t *Trie) Delete(key []byte) {
	if err := t.TryDelete(key); err != nil {
		logger.Error("Unhandled trie error in Trie.Delete", "err", err)
	}
}

// TryDelete removes any existing value for key from the trie.
// If a node was not found in the database, a MissingNodeError is returned.
func (t *Trie) TryDelete(key []byte) error {
	k := keybytesToHex(key)
	_, n, err := t.delete(t.root, nil, k)
	if err != nil {
		return err
	}
	t.root = n
	return nil
}

// delete returns the new root of the trie with key deleted.
// It reduces the trie to minimal form by simplifying
// nodes on the way up after deleting recursively.
func (t *Trie) delete(n node, prefix, key []byte) (bool, node, error) {
	switch n := n.(type) {
	case *shortNode:
		matchlen := prefixLen(key, n.Key)
		if matchlen < len(n.Key) {
			return false, n, nil // don't replace n on mismatch
		}
		if matchlen == len(key) {
			t.markPrunableNode(n) // it's the target leaf
			return true, nil, nil // remove n entirely for whole matches
		}
		// The key is longer than n.Key. Remove the remaining suffix
		// from the subtrie. Child can never be nil here since the
		// subtrie must contain at least two other values with keys
		// longer than n.Key.
		dirty, child, err := t.delete(n.Val, append(prefix, key[:len(n.Key)]...), key[len(n.Key):])
		if !dirty || err != nil {
			return false, n, err
		}
		t.markPrunableNode(n) // dirty; something's changed in the child
		switch child := child.(type) {
		case *shortNode:
			// Deleting from the subtrie reduced it to another
			// short node. Merge the nodes to avoid creating a
			// shortNode{..., shortNode{...}}. Use concat (which
			// always creates a new slice) instead of append to
			// avoid modifying n.Key since it might be shared with
			// other nodes.
			return true, &shortNode{concat(n.Key, child.Key...), child.Val, t.newFlag()}, nil
		default:
			return true, &shortNode{n.Key, child, t.newFlag()}, nil
		}

	case *fullNode:
		dirty, nn, err := t.delete(n.Children[key[0]], append(prefix, key[0]), key[1:])
		if !dirty || err != nil {
			return false, n, err
		}
		t.markPrunableNode(n) // dirty; something's changed in the child
		n = n.copy()
		n.flags = t.newFlag()
		n.Children[key[0]] = nn

		// Check how many non-nil entries are left after deleting and
		// reduce the full node to a short node if only one entry is
		// left. Since n must've contained at least two children
		// before deletion (otherwise it would not be a full node) n
		// can never be reduced to nil.
		//
		// When the loop is done, pos contains the index of the single
		// value that is left in n or -2 if n contains at least two
		// values.
		pos := -1
		for i, cld := range &n.Children {
			if cld != nil {
				if pos == -1 {
					pos = i
				} else {
					pos = -2
					break
				}
			}
		}
		if pos >= 0 {
			if pos != 16 {
				// If the remaining entry is a short node, it replaces
				// n and its key gets the missing nibble tacked to the
				// front. This avoids creating an invalid
				// shortNode{..., shortNode{...}}.  Since the entry
				// might not be loaded yet, resolve it just for this
				// check.
				cnode, err := t.resolve(n.Children[pos], prefix)
				if err != nil {
					return false, nil, err
				}
				if cnode, ok := cnode.(*shortNode); ok {
					k := append([]byte{byte(pos)}, cnode.Key...)
					return true, &shortNode{k, cnode.Val, t.newFlag()}, nil
				}
			}
			// Otherwise, n is replaced by a one-nibble short node
			// containing the child.
			return true, &shortNode{[]byte{byte(pos)}, n.Children[pos], t.newFlag()}, nil
		}
		// n still contains at least two values and cannot be reduced.
		return true, n, nil

	case valueNode:
		return true, nil, nil

	case nil:
		return false, nil, nil

	case hashNode:
		// We've hit a part of the trie that isn't loaded yet. Load
		// the node and delete from it. This leaves all child nodes on
		// the path to the value in the trie.
		rn, err := t.resolveHash(n, prefix)
		if err != nil {
			return false, nil, err
		}
		dirty, nn, err := t.delete(rn, prefix, key)
		if !dirty || err != nil {
			return false, rn, err
		}
		return true, nn, nil

	default:
		panic(fmt.Sprintf("%T: invalid node: %v (%v)", n, n, key))
	}
}

func concat(s1 []byte, s2 ...byte) []byte {
	r := make([]byte, len(s1)+len(s2))
	copy(r, s1)
	copy(r[len(s1):], s2)
	return r
}

func (t *Trie) resolve(n node, prefix []byte) (node, error) {
	if n, ok := n.(hashNode); ok {
		return t.resolveHash(n, prefix)
	}
	return n, nil
}

func (t *Trie) resolveHash(n hashNode, prefix []byte) (node, error) {
	hash := common.BytesToExtHash(n)
	node, fromDB := t.db.node(hash)
	if t.Prefetching && fromDB {
		memcacheCleanPrefetchMissMeter.Mark(1)
	}
	if node != nil {
		return node, nil
	}
	return nil, &MissingNodeError{NodeHash: hash.Unextend(), Path: prefix}
}

// 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 (t *Trie) Hash() common.Hash {
	return t.HashExt().Unextend()
}

// HashExt returns the root hash of the trie in ExtHash type. It does not write to the
// database and can be used even if the trie doesn't have one.
func (t *Trie) HashExt() common.ExtHash {
	hash, cached := t.hashRoot(nil, nil)
	t.root = cached
	return hash
}

// Commit writes all nodes to the trie's memory database, tracking the internal
// and external (for account tries) references. Returns the root hash.
func (t *Trie) Commit(onleaf LeafCallback) (root common.Hash, err error) {
	extroot, err := t.CommitExt(onleaf)
	return extroot.Unextend(), err
}

// CommitExt writes all nodes to the trie's memory database, tracking the internal
// and external (for account tries) references. Returns the root hash in ExtHash type.
func (t *Trie) CommitExt(onleaf LeafCallback) (root common.ExtHash, err error) {
	if t.db == nil {
		panic("commit called on trie with nil database")
	}
	t.commitPruningMarks()
	hash, cached := t.hashRoot(t.db, onleaf)
	t.root = cached
	return hash, nil
}

func (t *Trie) hashRoot(db *Database, onleaf LeafCallback) (common.ExtHash, node) {
	if t.root == nil {
		return emptyRoot.ExtendZero(), nil
	}
	h := newHasher(&hasherOpts{
		onleaf:      onleaf,
		pruning:     t.pruning,
		storageRoot: t.storage,
	})

	defer returnHasherToPool(h)
	hashed, cached := h.hashRoot(t.root, db, true)
	hash := common.BytesToExtHash(hashed.(hashNode))
	return hash, cached
}

// Mark the node for later pruning by writing PruningMark to database.
func (t *Trie) markPrunableNode(n node) {
	// Mark nodes only if both conditions are met:
	// - t.pruning: database has pruning enabled, i.e. nodes are stored with ExtHash
	// - t.PruningBlockNumber: requested pruning through state.New -> OpenTrie -> NewTrie.
	if !t.pruning || t.PruningBlockNumber == 0 {
		return
	}

	if hn, ok := n.(hashNode); ok {
		// If a node exists as a hashNode, it means the node is either:
		// (1) lives in database but yet to be resolved - subject to pruning,
		// (2) collapsed by Hash or Commit - may or may not be in database, add the mark anyway.
		t.pruningMarksCache[common.BytesToExtHash(hn)] = t.PruningBlockNumber
	} else if hn, _ := n.cache(); hn != nil {
		// If node.flags.hash is nonempty, it means the node is either:
		// (1) loaded from databas - subject to pruning,
		// (2) went through hasher by Hash or Commit - may or may not be in database, add the mark anyway.
		t.pruningMarksCache[common.BytesToExtHash(hn)] = t.PruningBlockNumber
	}
}

// commitPruningMarks writes all the pruning marks
func (t *Trie) commitPruningMarks() {
	if len(t.pruningMarksCache) > 0 {
		t.db.lock.Lock()
		for hash, blockNum := range t.pruningMarksCache {
			t.db.insertPruningMark(hash, blockNum)
		}
		t.db.lock.Unlock()

		t.pruningMarksCache = make(map[common.ExtHash]uint64)
	}
}

func GetHashAndHexKey(key []byte) ([]byte, []byte) {
	var hashKeyBuf [common.HashLength]byte
	h := newHasher(nil)
	h.sha.Reset()
	h.sha.Write(key)
	hashKey := h.sha.Sum(hashKeyBuf[:0])
	returnHasherToPool(h)
	hexKey := keybytesToHex(hashKey)
	return hashKey, hexKey
}