github.com/ava-labs/subnet-evm@v0.6.4/trie/trie.go (about) 1 // (c) 2020-2021, Ava Labs, Inc. 2 // 3 // This file is a derived work, based on the go-ethereum library whose original 4 // notices appear below. 5 // 6 // It is distributed under a license compatible with the licensing terms of the 7 // original code from which it is derived. 8 // 9 // Much love to the original authors for their work. 10 // ********** 11 // Copyright 2014 The go-ethereum Authors 12 // This file is part of the go-ethereum library. 13 // 14 // The go-ethereum library is free software: you can redistribute it and/or modify 15 // it under the terms of the GNU Lesser General Public License as published by 16 // the Free Software Foundation, either version 3 of the License, or 17 // (at your option) any later version. 18 // 19 // The go-ethereum library is distributed in the hope that it will be useful, 20 // but WITHOUT ANY WARRANTY; without even the implied warranty of 21 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 // GNU Lesser General Public License for more details. 23 // 24 // You should have received a copy of the GNU Lesser General Public License 25 // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>. 26 27 // Package trie implements Merkle Patricia Tries. 28 package trie 29 30 import ( 31 "bytes" 32 "errors" 33 "fmt" 34 35 "github.com/ava-labs/subnet-evm/core/types" 36 "github.com/ava-labs/subnet-evm/trie/trienode" 37 "github.com/ethereum/go-ethereum/common" 38 "github.com/ethereum/go-ethereum/log" 39 ) 40 41 // Trie is a Merkle Patricia Trie. Use New to create a trie that sits on 42 // top of a database. Whenever trie performs a commit operation, the generated 43 // nodes will be gathered and returned in a set. Once the trie is committed, 44 // it's not usable anymore. Callers have to re-create the trie with new root 45 // based on the updated trie database. 46 // 47 // Trie is not safe for concurrent use. 48 type Trie struct { 49 root node 50 owner common.Hash 51 52 // Flag whether the commit operation is already performed. If so the 53 // trie is not usable(latest states is invisible). 54 committed bool 55 56 // Keep track of the number leaves which have been inserted since the last 57 // hashing operation. This number will not directly map to the number of 58 // actually unhashed nodes. 59 unhashed int 60 61 // reader is the handler trie can retrieve nodes from. 62 reader *trieReader 63 64 // tracer is the tool to track the trie changes. 65 // It will be reset after each commit operation. 66 tracer *tracer 67 } 68 69 // newFlag returns the cache flag value for a newly created node. 70 func (t *Trie) newFlag() nodeFlag { 71 return nodeFlag{dirty: true} 72 } 73 74 // Copy returns a copy of Trie. 75 func (t *Trie) Copy() *Trie { 76 return &Trie{ 77 root: t.root, 78 owner: t.owner, 79 committed: t.committed, 80 unhashed: t.unhashed, 81 reader: t.reader, 82 tracer: t.tracer.copy(), 83 } 84 } 85 86 // New creates the trie instance with provided trie id and the read-only 87 // database. The state specified by trie id must be available, otherwise 88 // an error will be returned. The trie root specified by trie id can be 89 // zero hash or the sha3 hash of an empty string, then trie is initially 90 // empty, otherwise, the root node must be present in database or returns 91 // a MissingNodeError if not. 92 func New(id *ID, db *Database) (*Trie, error) { 93 reader, err := newTrieReader(id.StateRoot, id.Owner, db) 94 if err != nil { 95 return nil, err 96 } 97 trie := &Trie{ 98 owner: id.Owner, 99 reader: reader, 100 tracer: newTracer(), 101 } 102 if id.Root != (common.Hash{}) && id.Root != types.EmptyRootHash { 103 rootnode, err := trie.resolveAndTrack(id.Root[:], nil) 104 if err != nil { 105 return nil, err 106 } 107 trie.root = rootnode 108 } 109 return trie, nil 110 } 111 112 // NewEmpty is a shortcut to create empty tree. It's mostly used in tests. 113 func NewEmpty(db *Database) *Trie { 114 tr, _ := New(TrieID(types.EmptyRootHash), db) 115 return tr 116 } 117 118 // MustNodeIterator is a wrapper of NodeIterator and will omit any encountered 119 // error but just print out an error message. 120 func (t *Trie) MustNodeIterator(start []byte) NodeIterator { 121 it, err := t.NodeIterator(start) 122 if err != nil { 123 log.Error("Unhandled trie error in Trie.NodeIterator", "err", err) 124 } 125 return it 126 } 127 128 // NodeIterator returns an iterator that returns nodes of the trie. Iteration starts at 129 // the key after the given start key. 130 func (t *Trie) NodeIterator(start []byte) (NodeIterator, error) { 131 // Short circuit if the trie is already committed and not usable. 132 if t.committed { 133 return nil, ErrCommitted 134 } 135 return newNodeIterator(t, start), nil 136 } 137 138 // MustGet is a wrapper of Get and will omit any encountered error but just 139 // print out an error message. 140 func (t *Trie) MustGet(key []byte) []byte { 141 res, err := t.Get(key) 142 if err != nil { 143 log.Error("Unhandled trie error in Trie.Get", "err", err) 144 } 145 return res 146 } 147 148 // Get returns the value for key stored in the trie. 149 // The value bytes must not be modified by the caller. 150 // 151 // If the requested node is not present in trie, no error will be returned. 152 // If the trie is corrupted, a MissingNodeError is returned. 153 func (t *Trie) Get(key []byte) ([]byte, error) { 154 // Short circuit if the trie is already committed and not usable. 155 if t.committed { 156 return nil, ErrCommitted 157 } 158 value, newroot, didResolve, err := t.get(t.root, keybytesToHex(key), 0) 159 if err == nil && didResolve { 160 t.root = newroot 161 } 162 return value, err 163 } 164 165 func (t *Trie) get(origNode node, key []byte, pos int) (value []byte, newnode node, didResolve bool, err error) { 166 switch n := (origNode).(type) { 167 case nil: 168 return nil, nil, false, nil 169 case valueNode: 170 return n, n, false, nil 171 case *shortNode: 172 if len(key)-pos < len(n.Key) || !bytes.Equal(n.Key, key[pos:pos+len(n.Key)]) { 173 // key not found in trie 174 return nil, n, false, nil 175 } 176 value, newnode, didResolve, err = t.get(n.Val, key, pos+len(n.Key)) 177 if err == nil && didResolve { 178 n = n.copy() 179 n.Val = newnode 180 } 181 return value, n, didResolve, err 182 case *fullNode: 183 value, newnode, didResolve, err = t.get(n.Children[key[pos]], key, pos+1) 184 if err == nil && didResolve { 185 n = n.copy() 186 n.Children[key[pos]] = newnode 187 } 188 return value, n, didResolve, err 189 case hashNode: 190 child, err := t.resolveAndTrack(n, key[:pos]) 191 if err != nil { 192 return nil, n, true, err 193 } 194 value, newnode, _, err := t.get(child, key, pos) 195 return value, newnode, true, err 196 default: 197 panic(fmt.Sprintf("%T: invalid node: %v", origNode, origNode)) 198 } 199 } 200 201 // MustGetNode is a wrapper of GetNode and will omit any encountered error but 202 // just print out an error message. 203 func (t *Trie) MustGetNode(path []byte) ([]byte, int) { 204 item, resolved, err := t.GetNode(path) 205 if err != nil { 206 log.Error("Unhandled trie error in Trie.GetNode", "err", err) 207 } 208 return item, resolved 209 } 210 211 // GetNode retrieves a trie node by compact-encoded path. It is not possible 212 // to use keybyte-encoding as the path might contain odd nibbles. 213 // 214 // If the requested node is not present in trie, no error will be returned. 215 // If the trie is corrupted, a MissingNodeError is returned. 216 func (t *Trie) GetNode(path []byte) ([]byte, int, error) { 217 // Short circuit if the trie is already committed and not usable. 218 if t.committed { 219 return nil, 0, ErrCommitted 220 } 221 item, newroot, resolved, err := t.getNode(t.root, compactToHex(path), 0) 222 if err != nil { 223 return nil, resolved, err 224 } 225 if resolved > 0 { 226 t.root = newroot 227 } 228 if item == nil { 229 return nil, resolved, nil 230 } 231 return item, resolved, nil 232 } 233 234 func (t *Trie) getNode(origNode node, path []byte, pos int) (item []byte, newnode node, resolved int, err error) { 235 // If non-existent path requested, abort 236 if origNode == nil { 237 return nil, nil, 0, nil 238 } 239 // If we reached the requested path, return the current node 240 if pos >= len(path) { 241 // Although we most probably have the original node expanded, encoding 242 // that into consensus form can be nasty (needs to cascade down) and 243 // time consuming. Instead, just pull the hash up from disk directly. 244 var hash hashNode 245 if node, ok := origNode.(hashNode); ok { 246 hash = node 247 } else { 248 hash, _ = origNode.cache() 249 } 250 if hash == nil { 251 return nil, origNode, 0, errors.New("non-consensus node") 252 } 253 blob, err := t.reader.node(path, common.BytesToHash(hash)) 254 return blob, origNode, 1, err 255 } 256 // Path still needs to be traversed, descend into children 257 switch n := (origNode).(type) { 258 case valueNode: 259 // Path prematurely ended, abort 260 return nil, nil, 0, nil 261 262 case *shortNode: 263 if len(path)-pos < len(n.Key) || !bytes.Equal(n.Key, path[pos:pos+len(n.Key)]) { 264 // Path branches off from short node 265 return nil, n, 0, nil 266 } 267 item, newnode, resolved, err = t.getNode(n.Val, path, pos+len(n.Key)) 268 if err == nil && resolved > 0 { 269 n = n.copy() 270 n.Val = newnode 271 } 272 return item, n, resolved, err 273 274 case *fullNode: 275 item, newnode, resolved, err = t.getNode(n.Children[path[pos]], path, pos+1) 276 if err == nil && resolved > 0 { 277 n = n.copy() 278 n.Children[path[pos]] = newnode 279 } 280 return item, n, resolved, err 281 282 case hashNode: 283 child, err := t.resolveAndTrack(n, path[:pos]) 284 if err != nil { 285 return nil, n, 1, err 286 } 287 item, newnode, resolved, err := t.getNode(child, path, pos) 288 return item, newnode, resolved + 1, err 289 290 default: 291 panic(fmt.Sprintf("%T: invalid node: %v", origNode, origNode)) 292 } 293 } 294 295 // MustUpdate is a wrapper of Update and will omit any encountered error but 296 // just print out an error message. 297 func (t *Trie) MustUpdate(key, value []byte) { 298 if err := t.Update(key, value); err != nil { 299 log.Error("Unhandled trie error in Trie.Update", "err", err) 300 } 301 } 302 303 // Update associates key with value in the trie. Subsequent calls to 304 // Get will return value. If value has length zero, any existing value 305 // is deleted from the trie and calls to Get will return nil. 306 // 307 // The value bytes must not be modified by the caller while they are 308 // stored in the trie. 309 // 310 // If the requested node is not present in trie, no error will be returned. 311 // If the trie is corrupted, a MissingNodeError is returned. 312 func (t *Trie) Update(key, value []byte) error { 313 // Short circuit if the trie is already committed and not usable. 314 if t.committed { 315 return ErrCommitted 316 } 317 return t.update(key, value) 318 } 319 320 func (t *Trie) update(key, value []byte) error { 321 t.unhashed++ 322 k := keybytesToHex(key) 323 if len(value) != 0 { 324 _, n, err := t.insert(t.root, nil, k, valueNode(value)) 325 if err != nil { 326 return err 327 } 328 t.root = n 329 } else { 330 _, n, err := t.delete(t.root, nil, k) 331 if err != nil { 332 return err 333 } 334 t.root = n 335 } 336 return nil 337 } 338 339 func (t *Trie) insert(n node, prefix, key []byte, value node) (bool, node, error) { 340 if len(key) == 0 { 341 if v, ok := n.(valueNode); ok { 342 return !bytes.Equal(v, value.(valueNode)), value, nil 343 } 344 return true, value, nil 345 } 346 switch n := n.(type) { 347 case *shortNode: 348 matchlen := prefixLen(key, n.Key) 349 // If the whole key matches, keep this short node as is 350 // and only update the value. 351 if matchlen == len(n.Key) { 352 dirty, nn, err := t.insert(n.Val, append(prefix, key[:matchlen]...), key[matchlen:], value) 353 if !dirty || err != nil { 354 return false, n, err 355 } 356 return true, &shortNode{n.Key, nn, t.newFlag()}, nil 357 } 358 // Otherwise branch out at the index where they differ. 359 branch := &fullNode{flags: t.newFlag()} 360 var err error 361 _, branch.Children[n.Key[matchlen]], err = t.insert(nil, append(prefix, n.Key[:matchlen+1]...), n.Key[matchlen+1:], n.Val) 362 if err != nil { 363 return false, nil, err 364 } 365 _, branch.Children[key[matchlen]], err = t.insert(nil, append(prefix, key[:matchlen+1]...), key[matchlen+1:], value) 366 if err != nil { 367 return false, nil, err 368 } 369 // Replace this shortNode with the branch if it occurs at index 0. 370 if matchlen == 0 { 371 return true, branch, nil 372 } 373 // New branch node is created as a child of the original short node. 374 // Track the newly inserted node in the tracer. The node identifier 375 // passed is the path from the root node. 376 t.tracer.onInsert(append(prefix, key[:matchlen]...)) 377 378 // Replace it with a short node leading up to the branch. 379 return true, &shortNode{key[:matchlen], branch, t.newFlag()}, nil 380 381 case *fullNode: 382 dirty, nn, err := t.insert(n.Children[key[0]], append(prefix, key[0]), key[1:], value) 383 if !dirty || err != nil { 384 return false, n, err 385 } 386 n = n.copy() 387 n.flags = t.newFlag() 388 n.Children[key[0]] = nn 389 return true, n, nil 390 391 case nil: 392 // New short node is created and track it in the tracer. The node identifier 393 // passed is the path from the root node. Note the valueNode won't be tracked 394 // since it's always embedded in its parent. 395 t.tracer.onInsert(prefix) 396 397 return true, &shortNode{key, value, t.newFlag()}, nil 398 399 case hashNode: 400 // We've hit a part of the trie that isn't loaded yet. Load 401 // the node and insert into it. This leaves all child nodes on 402 // the path to the value in the trie. 403 rn, err := t.resolveAndTrack(n, prefix) 404 if err != nil { 405 return false, nil, err 406 } 407 dirty, nn, err := t.insert(rn, prefix, key, value) 408 if !dirty || err != nil { 409 return false, rn, err 410 } 411 return true, nn, nil 412 413 default: 414 panic(fmt.Sprintf("%T: invalid node: %v", n, n)) 415 } 416 } 417 418 // MustDelete is a wrapper of Delete and will omit any encountered error but 419 // just print out an error message. 420 func (t *Trie) MustDelete(key []byte) { 421 if err := t.Delete(key); err != nil { 422 log.Error("Unhandled trie error in Trie.Delete", "err", err) 423 } 424 } 425 426 // Delete removes any existing value for key from the trie. 427 // 428 // If the requested node is not present in trie, no error will be returned. 429 // If the trie is corrupted, a MissingNodeError is returned. 430 func (t *Trie) Delete(key []byte) error { 431 // Short circuit if the trie is already committed and not usable. 432 if t.committed { 433 return ErrCommitted 434 } 435 t.unhashed++ 436 k := keybytesToHex(key) 437 _, n, err := t.delete(t.root, nil, k) 438 if err != nil { 439 return err 440 } 441 t.root = n 442 return nil 443 } 444 445 // delete returns the new root of the trie with key deleted. 446 // It reduces the trie to minimal form by simplifying 447 // nodes on the way up after deleting recursively. 448 func (t *Trie) delete(n node, prefix, key []byte) (bool, node, error) { 449 switch n := n.(type) { 450 case *shortNode: 451 matchlen := prefixLen(key, n.Key) 452 if matchlen < len(n.Key) { 453 return false, n, nil // don't replace n on mismatch 454 } 455 if matchlen == len(key) { 456 // The matched short node is deleted entirely and track 457 // it in the deletion set. The same the valueNode doesn't 458 // need to be tracked at all since it's always embedded. 459 t.tracer.onDelete(prefix) 460 461 return true, nil, nil // remove n entirely for whole matches 462 } 463 // The key is longer than n.Key. Remove the remaining suffix 464 // from the subtrie. Child can never be nil here since the 465 // subtrie must contain at least two other values with keys 466 // longer than n.Key. 467 dirty, child, err := t.delete(n.Val, append(prefix, key[:len(n.Key)]...), key[len(n.Key):]) 468 if !dirty || err != nil { 469 return false, n, err 470 } 471 switch child := child.(type) { 472 case *shortNode: 473 // The child shortNode is merged into its parent, track 474 // is deleted as well. 475 t.tracer.onDelete(append(prefix, n.Key...)) 476 477 // Deleting from the subtrie reduced it to another 478 // short node. Merge the nodes to avoid creating a 479 // shortNode{..., shortNode{...}}. Use concat (which 480 // always creates a new slice) instead of append to 481 // avoid modifying n.Key since it might be shared with 482 // other nodes. 483 return true, &shortNode{concat(n.Key, child.Key...), child.Val, t.newFlag()}, nil 484 default: 485 return true, &shortNode{n.Key, child, t.newFlag()}, nil 486 } 487 488 case *fullNode: 489 dirty, nn, err := t.delete(n.Children[key[0]], append(prefix, key[0]), key[1:]) 490 if !dirty || err != nil { 491 return false, n, err 492 } 493 n = n.copy() 494 n.flags = t.newFlag() 495 n.Children[key[0]] = nn 496 497 // Because n is a full node, it must've contained at least two children 498 // before the delete operation. If the new child value is non-nil, n still 499 // has at least two children after the deletion, and cannot be reduced to 500 // a short node. 501 if nn != nil { 502 return true, n, nil 503 } 504 // Reduction: 505 // Check how many non-nil entries are left after deleting and 506 // reduce the full node to a short node if only one entry is 507 // left. Since n must've contained at least two children 508 // before deletion (otherwise it would not be a full node) n 509 // can never be reduced to nil. 510 // 511 // When the loop is done, pos contains the index of the single 512 // value that is left in n or -2 if n contains at least two 513 // values. 514 pos := -1 515 for i, cld := range &n.Children { 516 if cld != nil { 517 if pos == -1 { 518 pos = i 519 } else { 520 pos = -2 521 break 522 } 523 } 524 } 525 if pos >= 0 { 526 if pos != 16 { 527 // If the remaining entry is a short node, it replaces 528 // n and its key gets the missing nibble tacked to the 529 // front. This avoids creating an invalid 530 // shortNode{..., shortNode{...}}. Since the entry 531 // might not be loaded yet, resolve it just for this 532 // check. 533 cnode, err := t.resolve(n.Children[pos], append(prefix, byte(pos))) 534 if err != nil { 535 return false, nil, err 536 } 537 if cnode, ok := cnode.(*shortNode); ok { 538 // Replace the entire full node with the short node. 539 // Mark the original short node as deleted since the 540 // value is embedded into the parent now. 541 t.tracer.onDelete(append(prefix, byte(pos))) 542 543 k := append([]byte{byte(pos)}, cnode.Key...) 544 return true, &shortNode{k, cnode.Val, t.newFlag()}, nil 545 } 546 } 547 // Otherwise, n is replaced by a one-nibble short node 548 // containing the child. 549 return true, &shortNode{[]byte{byte(pos)}, n.Children[pos], t.newFlag()}, nil 550 } 551 // n still contains at least two values and cannot be reduced. 552 return true, n, nil 553 554 case valueNode: 555 return true, nil, nil 556 557 case nil: 558 return false, nil, nil 559 560 case hashNode: 561 // We've hit a part of the trie that isn't loaded yet. Load 562 // the node and delete from it. This leaves all child nodes on 563 // the path to the value in the trie. 564 rn, err := t.resolveAndTrack(n, prefix) 565 if err != nil { 566 return false, nil, err 567 } 568 dirty, nn, err := t.delete(rn, prefix, key) 569 if !dirty || err != nil { 570 return false, rn, err 571 } 572 return true, nn, nil 573 574 default: 575 panic(fmt.Sprintf("%T: invalid node: %v (%v)", n, n, key)) 576 } 577 } 578 579 func concat(s1 []byte, s2 ...byte) []byte { 580 r := make([]byte, len(s1)+len(s2)) 581 copy(r, s1) 582 copy(r[len(s1):], s2) 583 return r 584 } 585 586 func (t *Trie) resolve(n node, prefix []byte) (node, error) { 587 if n, ok := n.(hashNode); ok { 588 return t.resolveAndTrack(n, prefix) 589 } 590 return n, nil 591 } 592 593 // resolveAndTrack loads node from the underlying store with the given node hash 594 // and path prefix and also tracks the loaded node blob in tracer treated as the 595 // node's original value. The rlp-encoded blob is preferred to be loaded from 596 // database because it's easy to decode node while complex to encode node to blob. 597 func (t *Trie) resolveAndTrack(n hashNode, prefix []byte) (node, error) { 598 blob, err := t.reader.node(prefix, common.BytesToHash(n)) 599 if err != nil { 600 return nil, err 601 } 602 t.tracer.onRead(prefix, blob) 603 return mustDecodeNode(n, blob), nil 604 } 605 606 // Hash returns the root hash of the trie. It does not write to the 607 // database and can be used even if the trie doesn't have one. 608 func (t *Trie) Hash() common.Hash { 609 hash, cached := t.hashRoot() 610 t.root = cached 611 return common.BytesToHash(hash.(hashNode)) 612 } 613 614 // Commit collects all dirty nodes in the trie and replaces them with the 615 // corresponding node hash. All collected nodes (including dirty leaves if 616 // collectLeaf is true) will be encapsulated into a nodeset for return. 617 // The returned nodeset can be nil if the trie is clean (nothing to commit). 618 // Once the trie is committed, it's not usable anymore. A new trie must 619 // be created with new root and updated trie database for following usage 620 func (t *Trie) Commit(collectLeaf bool) (common.Hash, *trienode.NodeSet, error) { 621 defer t.tracer.reset() 622 defer func() { 623 t.committed = true 624 }() 625 // Trie is empty and can be classified into two types of situations: 626 // (a) The trie was empty and no update happens => return nil 627 // (b) The trie was non-empty and all nodes are dropped => return 628 // the node set includes all deleted nodes 629 if t.root == nil { 630 paths := t.tracer.deletedNodes() 631 if len(paths) == 0 { 632 return types.EmptyRootHash, nil, nil // case (a) 633 } 634 nodes := trienode.NewNodeSet(t.owner) 635 for _, path := range paths { 636 nodes.AddNode([]byte(path), trienode.NewDeleted()) 637 } 638 return types.EmptyRootHash, nodes, nil // case (b) 639 } 640 // Derive the hash for all dirty nodes first. We hold the assumption 641 // in the following procedure that all nodes are hashed. 642 rootHash := t.Hash() 643 644 // Do a quick check if we really need to commit. This can happen e.g. 645 // if we load a trie for reading storage values, but don't write to it. 646 if hashedNode, dirty := t.root.cache(); !dirty { 647 // Replace the root node with the origin hash in order to 648 // ensure all resolved nodes are dropped after the commit. 649 t.root = hashedNode 650 return rootHash, nil, nil 651 } 652 nodes := trienode.NewNodeSet(t.owner) 653 for _, path := range t.tracer.deletedNodes() { 654 nodes.AddNode([]byte(path), trienode.NewDeleted()) 655 } 656 t.root = newCommitter(nodes, t.tracer, collectLeaf).Commit(t.root) 657 return rootHash, nodes, nil 658 } 659 660 // hashRoot calculates the root hash of the given trie 661 func (t *Trie) hashRoot() (node, node) { 662 if t.root == nil { 663 return hashNode(types.EmptyRootHash.Bytes()), nil 664 } 665 // If the number of changes is below 100, we let one thread handle it 666 h := newHasher(t.unhashed >= 100) 667 defer func() { 668 returnHasherToPool(h) 669 t.unhashed = 0 670 }() 671 hashed, cached := h.hash(t.root, true) 672 return hashed, cached 673 } 674 675 // Reset drops the referenced root node and cleans all internal state. 676 func (t *Trie) Reset() { 677 t.root = nil 678 t.owner = common.Hash{} 679 t.unhashed = 0 680 t.tracer.reset() 681 t.committed = false 682 }