@ethereumjs/mpt / MerklePatriciaTrie
Defined in: mpt.ts:61
The basic trie interface, use with import { MerklePatriciaTrie } from '@ethereumjs/mpt'.
Preferred entry point: createMPT. For proof-backed sparse tries: createMPTFromProof.
Merkle Patricia Trie — a space-optimized trie where single-child nodes merge with their parent. Node types: branch (16-way + optional value), extension (shared path), leaf (terminal value).
new MerklePatriciaTrie(
opts?):MerklePatriciaTrie
Defined in: mpt.ts:92
Creates a new trie.
MerklePatriciaTrie
Use createMPT instead; it applies the same options with sensible defaults.
EMPTY_TRIE_ROOT:
Uint8Array
Defined in: mpt.ts:74
The root for an empty trie
walkTrieIterable: (…
args) =>AsyncIterable
Defined in: mpt.ts:422
…[Uint8Array<ArrayBufferLike>, number[], OnFound, NodeFilter, Set<string>]
AsyncIterable
_formatNode(
node,topLevel,opStack,remove?):Uint8Array<ArrayBufferLike> |NodeReferenceOrRawMPTNode|BranchMPTNodeBranchValue[]
Defined in: mpt.ts:810
Serializes a node and either stores it (put) or schedules removal (del). Nodes ≥32 bytes (or top-level) are hashed and stored; smaller nodes are inlined as raw.
the node to persist
boolean
if true, always store (root must be in DB)
BatchDBOp[]
accumulates put/del operations for batch commit
boolean = false
if true, schedule del (used when pruning)
Uint8Array<ArrayBufferLike> | NodeReferenceOrRawMPTNode | BranchMPTNodeBranchValue[]
hash (for references) or raw encoding (for inline)
batch(
ops,skipKeyTransform?):Promise<void>
Defined in: mpt.ts:849
The given hash of operations (key additions or deletions) are executed on the trie
(delete operations are only executed on DB with deleteFromDB set to true)
BatchDBOp[]
Put/delete operations applied in order
boolean
Promise<void>
const ops = [
{ type: 'del', key: Uint8Array.from('father') }
, { type: 'put', key: Uint8Array.from('name'), value: Uint8Array.from('Yuri Irsenovich Kim') } // cspell:disable-line
, { type: 'put', key: Uint8Array.from('dob'), value: Uint8Array.from('16 February 1941') }
, { type: 'put', key: Uint8Array.from('spouse'), value: Uint8Array.from('Kim Young-sook') } // cspell:disable-line
, { type: 'put', key: Uint8Array.from('occupation'), value: Uint8Array.from('Clown') }
]
await trie.batch(ops)
checkpoint():
void
Defined in: mpt.ts:1025
Creates a checkpoint that can later be reverted to or committed.
After this is called, all changes can be reverted until commit is called.
void
checkRoot(
root):Promise<boolean>
Defined in: mpt.ts:169
Checks if a given root exists.
Uint8Array
Promise<boolean>
commit():
Promise<void>
Defined in: mpt.ts:1035
Commits a checkpoint to disk, if current checkpoint is not nested. If nested, only sets the parent checkpoint as current checkpoint.
Promise<void>
If not during a checkpoint phase
database(
db?,valueEncoding?):CheckpointDB
Defined in: mpt.ts:134
DB<string, string | Uint8Array<ArrayBufferLike>>
ValueEncoding
del(
key,skipKeyTransform?):Promise<void>
Defined in: mpt.ts:253
Deletes the value at key.
Physical DB deletes occur only when node pruning is enabled.
Uint8Array
boolean = false
Promise<void>
findPath(
key,throwIfMissing?,partialPath?):Promise<Path>
Defined in: mpt.ts:288
Finds the path from root to the node for the given key. Walks the trie, matching nibbles at each level. Returns the target node (if found) and the stack of nodes along the path (needed for updates/deletes).
Uint8Array
the search key (bytes)
boolean = false
if true, throws when nodes are missing (e.g. proof verification)
optional pre-loaded stack for resuming from a mid-path node
MPTNode[]
Promise<Path>
flushCheckpoints():
void
Defined in: mpt.ts:1067
Flushes all checkpoints, restoring the initial checkpoint state.
void
get(
key,throwIfMissing?):Promise<Uint8Array<ArrayBufferLike> |null>
Defined in: mpt.ts:188
Gets a value given a key
Uint8Array
the key to search for
boolean = false
if true, throws if any nodes are missing. Used for verifying proofs. (default: false)
Promise<Uint8Array<ArrayBufferLike> | null>
A Promise that resolves to Uint8Array if a value was found or null if no value was found.
getValueMap(
startKey?,limit?):Promise<{nextKey:string|null;values: {[key:string]:string; }; }>
Defined in: mpt.ts:1079
Returns a list of values stored in the trie
bigint = BIGINT_0
first unhashed key in the range to be returned (defaults to 0). Note, all keys must be of the same length or undefined behavior will result
number
the number of keys to be returned (undefined means all keys)
Promise<{ nextKey: string | null; values: {[key: string]: string; }; }>
an object with two properties (a map of all key/value pairs in the trie - or in the specified range) and then a nextKey reference if a range is specified
hasCheckpoints():
boolean
Defined in: mpt.ts:1017
Is the trie during a checkpoint phase?
boolean
lookupNode(
node):Promise<MPTNode>
Defined in: mpt.ts:473
Retrieves a node from db by hash.
Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike>[]
Promise<MPTNode>
persistRoot():
Promise<void>
Defined in: mpt.ts:951
Persists the root hash in the underlying database
Promise<void>
put(
key,value,skipKeyTransform?):Promise<void>
Defined in: mpt.ts:204
Stores value at key, or deletes the key when value is empty.
Deletes only reach the backing DB when node pruning is enabled.
Uint8Array
Uint8Array<ArrayBufferLike> | null
boolean = false
Promise<void>
revert():
Promise<void>
Defined in: mpt.ts:1051
Reverts the trie to the state it was at when checkpoint was first called.
If during a nested checkpoint, sets root to most recent checkpoint, and sets
parent checkpoint as current.
Promise<void>
root(
value?):Uint8Array
Defined in: mpt.ts:149
Gets and/or Sets the current root of the trie
Uint8Array<ArrayBufferLike> | null
Uint8Array
saveStack(
pathNibbles,stack,opStack):Promise<void>
Defined in: mpt.ts:772
Persists the modified node stack to the DB. Processes nodes from leaf toward root, wiring each node’s references (extension value, branch slot) to its child’s hash.
nibble path that corresponds to the stack
MPTNode[]
nodes from findPath/update, bottom (leaf) to top (root)
BatchDBOp[]
put/del operations accumulated by _formatNode
Promise<void>
shallowCopy(
includeCheckpoints?,opts?):MerklePatriciaTrie
Defined in: mpt.ts:934
Returns a copy of the underlying trie.
Note on db: the copy will create a reference to the same underlying database.
Note on cache: for memory reasons a copy will by default
not recreate a new LRU cache but initialize with cache
being deactivated. This behavior can be overwritten by
explicitly setting cacheSize as an option on the method.
boolean = true
If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db.
MerklePatriciaTrie
verifyPrunedIntegrity():
Promise<boolean>
Defined in: mpt.ts:867
Verifies that every key in the DB is reachable from the root. Used to ensure pruning is correct – unreachable keys indicate a bug or corrupt state.
Promise<boolean>
walkAllNodes(
onFound):Promise<void>
Defined in: mpt.ts:429
Executes a callback for each node in the trie.
OnFound
callback to call when a node is found.
Promise<void>
Resolves when finished walking trie.
walkAllValueNodes(
onFound):Promise<void>
Defined in: mpt.ts:440
Executes a callback for each value node in the trie.
OnFound
callback to call when a node is found.
Promise<void>
Resolves when finished walking trie.
walkTrie(
root,onFound):Promise<void>
Defined in: mpt.ts:418
Walk the trie from root, invoking onFound for each visited node.
Uint8Array
Root hash to start from
Callback that may schedule further child visits via the walk controller
Promise<void>