@ethereumjs/trie / Trie
The basic trie interface, use with import { Trie } from '@ethereumjs/trie'.
• new Trie(opts?)
Creates a new trie.
| Name | Type | Description |
|---|---|---|
opts? |
TrieOpts |
Options for instantiating the trie Note: in most cases, the static create constructor should be used. It uses the same API but provides sensible defaults |
• EMPTY_TRIE_ROOT: Uint8Array
The root for an empty trie
• walkTrieIterable: (…args: [nodeHash: Uint8Array, currentKey: number[], onFound: OnFound, filter: NodeFilter, visited: Set<string>]) => AsyncIterable<{ currentKey: number[] ; node: TrieNode }>
▸ (…args): AsyncIterable<{ currentKey: number[] ; node: TrieNode }>
| Name | Type |
|---|---|
...args |
[nodeHash: Uint8Array, currentKey: number[], onFound: OnFound, filter: NodeFilter, visited: Set<string>] |
AsyncIterable<{ currentKey: number[] ; node: TrieNode }>
▸ batch(ops, skipKeyTransform?): Promise<void>
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)
Example
const ops = [
{ type: 'del', key: Uint8Array.from('father') }
, { type: 'put', key: Uint8Array.from('name'), value: Uint8Array.from('Yuri Irsenovich Kim') }
, { type: 'put', key: Uint8Array.from('dob'), value: Uint8Array.from('16 February 1941') }
, { type: 'put', key: Uint8Array.from('spouse'), value: Uint8Array.from('Kim Young-sook') }
, { type: 'put', key: Uint8Array.from('occupation'), value: Uint8Array.from('Clown') }
]
await trie.batch(ops)
| Name | Type |
|---|---|
ops |
BatchDBOp<Uint8Array, Uint8Array>[] |
skipKeyTransform? |
boolean |
Promise<void>
packages/trie/src/trie.ts:1139
▸ checkRoot(root): Promise<boolean>
Checks if a given root exists.
| Name | Type |
|---|---|
root |
Uint8Array |
Promise<boolean>
▸ checkpoint(): void
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
packages/trie/src/trie.ts:1306
▸ commit(): Promise<void>
Commits a checkpoint to disk, if current checkpoint is not nested. If nested, only sets the parent checkpoint as current checkpoint.
Throws
If not during a checkpoint phase
Promise<void>
packages/trie/src/trie.ts:1316
▸ createProof(key): Promise<Proof>
Creates a proof from a trie and key that can be verified using verifyProof. An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data. The returned proof will be in the format of an array that contains Uint8Arrays of serialized branch, extension, and/or leaf nodes.
| Name | Type | Description |
|---|---|---|
key |
Uint8Array |
key to create a proof for |
Promise<Proof>
▸ createReadStream(): TrieReadStream
The data event is given an Object that has two properties; the key and the value. Both should be Uint8Arrays.
Returns a stream of the contents of the trie
packages/trie/src/trie.ts:1211
▸ database(db?, valueEncoding?): CheckpointDB
| Name | Type |
|---|---|
db? |
DB<string, string | Uint8Array> |
valueEncoding? |
ValueEncoding |
▸ del(key, skipKeyTransform?): Promise<void>
Deletes a value given a key from the trie
(delete operations are only executed on DB with deleteFromDB set to true)
| Name | Type | Default value |
|---|---|---|
key |
Uint8Array |
undefined |
skipKeyTransform |
boolean |
false |
Promise<void>
A Promise that resolves once value is deleted.
▸ findPath(key, throwIfMissing?, partialPath?): Promise<Path>
Tries to find a path to the node for the given key.
It returns a stack of nodes to the closest node.
| Name | Type | Default value | Description |
|---|---|---|---|
key |
Uint8Array |
undefined |
the search key |
throwIfMissing |
boolean |
false |
if true, throws if any nodes are missing. Used for verifying proofs. (default: false) |
partialPath |
Object |
undefined |
- |
partialPath.stack |
TrieNode[] |
undefined |
- |
Promise<Path>
▸ flushCheckpoints(): void
Flushes all checkpoints, restoring the initial checkpoint state.
void
packages/trie/src/trie.ts:1348
▸ fromProof(proof): Promise<void>
Create a trie from a given (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof. An EIP-1186 proof contains the encoded trie nodes from the root node to the leaf node storing state data. This function does not check if the proof has the same expected root. A static version of this function exists with the same name.
Deprecated
Use updateFromProof
| Name | Type | Description |
|---|---|---|
proof |
Proof |
an EIP-1186 proof to update the trie from |
Promise<void>
▸ get(key, throwIfMissing?): Promise<null | Uint8Array>
Gets a value given a key
| Name | Type | Default value | Description |
|---|---|---|---|
key |
Uint8Array |
undefined |
the key to search for |
throwIfMissing |
boolean |
false |
if true, throws if any nodes are missing. Used for verifying proofs. (default: false) |
Promise<null | Uint8Array>
A Promise that resolves to Uint8Array if a value was found or null if no value was found.
▸ hasCheckpoints(): boolean
Is the trie during a checkpoint phase?
boolean
packages/trie/src/trie.ts:1298
▸ lookupNode(node): Promise<TrieNode>
Retrieves a node from db by hash.
| Name | Type |
|---|---|
node |
Uint8Array | Uint8Array[] |
Promise<TrieNode>
▸ persistRoot(): Promise<void>
Persists the root hash in the underlying database
Promise<void>
packages/trie/src/trie.ts:1245
▸ put(key, value, skipKeyTransform?): Promise<void>
Stores a given value at the given key or do a delete if value is empty
(delete operations are only executed on DB with deleteFromDB set to true)
| Name | Type | Default value |
|---|---|---|
key |
Uint8Array |
undefined |
value |
null | Uint8Array |
undefined |
skipKeyTransform |
boolean |
false |
Promise<void>
A Promise that resolves once value is stored.
▸ revert(): Promise<void>
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>
packages/trie/src/trie.ts:1332
▸ root(value?): Uint8Array
Gets and/or Sets the current root of the trie
| Name | Type |
|---|---|
value? |
null | Uint8Array |
Uint8Array
▸ saveStack(key, stack, opStack): Promise<void>
Saves a stack of nodes to the database.
| Name | Type | Description |
|---|---|---|
key |
Nibbles |
the key. Should follow the stack |
stack |
TrieNode[] |
a stack of nodes to the value given by the key |
opStack |
BatchDBOp<Uint8Array, Uint8Array>[] |
a stack of levelup operations to commit at the end of this function |
Promise<void>
packages/trie/src/trie.ts:1053
▸ shallowCopy(includeCheckpoints?, opts?): Trie
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.
| Name | Type | Default value | Description |
|---|---|---|---|
includeCheckpoints |
boolean |
true |
If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db. |
opts? |
TrieShallowCopyOpts |
undefined |
- |
packages/trie/src/trie.ts:1228
▸ updateFromProof(proof, shouldVerifyRoot?): Promise<undefined | Uint8Array>
Updates a trie from a proof by putting all the nodes in the proof into the trie. If a trie is being updated with multiple proofs, {@param shouldVerifyRoot} can be passed as false in order to not immediately throw on an unexpected root, so that root verification can happen after all proofs and their nodes have been added. An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data.
| Name | Type | Default value | Description |
|---|---|---|---|
proof |
Proof |
undefined |
An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof to update the trie from. |
shouldVerifyRoot |
boolean |
false |
If true, verifies that the root key of the proof matches the trie root. Throws if this is not the case. |
Promise<undefined | Uint8Array>
The root of the proof
▸ verifyProof(rootHash, key, proof): Promise<null | Uint8Array>
Verifies a proof by putting all of its nodes into a trie and attempting to get the proven key. An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data. A static version of this function exists with the same name.
Throws
If proof is found to be invalid.
| Name | Type | Description |
|---|---|---|
rootHash |
Uint8Array |
Root hash of the trie that this proof was created from and is being verified for |
key |
Uint8Array |
Key that is being verified and that the proof is created for |
proof |
Proof |
an EIP-1186 proof to verify the key against |
Promise<null | Uint8Array>
The value from the key, or null if valid proof of non-existence.
▸ verifyPrunedIntegrity(): Promise<boolean>
Promise<boolean>
packages/trie/src/trie.ts:1157
▸ verifyRangeProof(rootHash, firstKey, lastKey, keys, values, proof): Promise<boolean>
A range proof is a proof that includes the encoded trie nodes from the root node to leaf node for one or more branches of a trie, allowing an entire range of leaf nodes to be validated. This is useful in applications such as snap sync where contiguous ranges of state trie data is received and validated for constructing world state, locally. Also see verifyRangeProof. A static version of this function also exists.
| Name | Type | Description |
|---|---|---|
rootHash |
Uint8Array |
root hash of state trie this proof is being verified against. |
firstKey |
null | Uint8Array |
first key of range being proven. |
lastKey |
null | Uint8Array |
last key of range being proven. |
keys |
Uint8Array[] |
key list of leaf data being proven. |
values |
Uint8Array[] |
value list of leaf data being proven, one-to-one correspondence with keys. |
proof |
null | Uint8Array[] |
proof node list, if all-elements-proof where no proof is needed, proof should be null, and both firstKey and lastKey must be null as well |
Promise<boolean>
a flag to indicate whether there exists more trie node in the trie
▸ walkAllNodes(onFound): Promise<void>
Executes a callback for each node in the trie.
| Name | Type | Description |
|---|---|---|
onFound |
OnFound |
callback to call when a node is found. |
Promise<void>
Resolves when finished walking trie.
▸ walkAllValueNodes(onFound): Promise<void>
Executes a callback for each value node in the trie.
| Name | Type | Description |
|---|---|---|
onFound |
OnFound |
callback to call when a node is found. |
Promise<void>
Resolves when finished walking trie.
▸ walkTrie(root, onFound): Promise<void>
Walks a trie until finished.
| Name | Type | Description |
|---|---|---|
root |
Uint8Array |
|
onFound |
FoundNodeFunction |
callback to call when a node is found. This schedules new tasks. If no tasks are available, the Promise resolves. |
Promise<void>
Resolves when finished walking trie.
▸ Static create(opts?): Promise<Trie>
| Name | Type |
|---|---|
opts? |
TrieOpts |
Promise<Trie>
▸ Static createFromProof(proof, trieOpts?, shouldVerifyRoot?): Promise<Trie>
Create a trie from a given (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof. A proof contains the encoded trie nodes from the root node to the leaf node storing state data.
| Name | Type | Default value | Description |
|---|---|---|---|
proof |
Proof |
undefined |
an EIP-1186 proof to create trie from |
trieOpts? |
TrieOpts |
undefined |
trie opts to be applied to returned trie |
shouldVerifyRoot |
boolean |
false |
If true, verifies that the root key of the proof matches the trie root. Throws if this is not the case. |
Promise<Trie>
new trie created from given proof
▸ Static fromProof(proof, opts?): Promise<Trie>
Static version of fromProof function. If a root is provided in the opts param, the proof will be checked to have the same expected root. An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data.
Deprecated
Use createFromProof
| Name | Type | Description |
|---|---|---|
proof |
Proof |
An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data. |
opts? |
TrieOpts |
- |
Promise<Trie>
▸ Static verifyProof(key, proof, opts?): Promise<null | Uint8Array>
Static version of verifyProof function with the same behavior. An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data.
Throws
If proof is found to be invalid.
| Name | Type | Description |
|---|---|---|
key |
Uint8Array |
Key that is being verified and that the proof is created for |
proof |
Proof |
An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data. |
opts? |
TrieOpts |
optional, the opts may include a custom hashing function to use with the trie for proof verification |
Promise<null | Uint8Array>
The value from the key, or null if valid proof of non-existence.
▸ Static verifyRangeProof(rootHash, firstKey, lastKey, keys, values, proof, opts?): Promise<boolean>
A range proof is a proof that includes the encoded trie nodes from the root node to leaf node for one or more branches of a trie, allowing an entire range of leaf nodes to be validated. This is useful in applications such as snap sync where contiguous ranges of state trie data is received and validated for constructing world state, locally. Also see verifyRangeProof. A static version of this function also exists.
| Name | Type | Description |
|---|---|---|
rootHash |
Uint8Array |
root hash of state trie this proof is being verified against. |
firstKey |
null | Uint8Array |
first key of range being proven. |
lastKey |
null | Uint8Array |
last key of range being proven. |
keys |
Uint8Array[] |
key list of leaf data being proven. |
values |
Uint8Array[] |
value list of leaf data being proven, one-to-one correspondence with keys. |
proof |
null | Uint8Array[] |
proof node list, if all-elements-proof where no proof is needed, proof should be null, and both firstKey and lastKey must be null as well |
opts? |
TrieOpts |
optional, the opts may include a custom hashing function to use with the trie for proof verification |
Promise<boolean>
a flag to indicate whether there exists more trie node in the trie