@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>
▸ 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:1277
▸ 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:1287
▸ createAsyncReadStream(): ReadableStream<any>
Use asynchronous iteration over the chunks in a web stream using the for await…of syntax.
ReadableStream<any>
Returns a web stream of the contents of the trie
packages/trie/src/trie.ts:1182
▸ createProof(key): Promise<Proof>
Creates a proof from a trie and key that can be verified using verifyProof.
| Name | Type |
|---|---|
key |
Uint8Array |
Promise<Proof>
packages/trie/src/trie.ts:1035
▸ createReadStream(): TrieReadStream
The data event is given an Object that has two properties; the key and the value. Both should be Uint8Arrays.
Deprecated
Use createAsyncReadStream
Returns a stream of the contents of the trie
packages/trie/src/trie.ts:1174
▸ 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?): 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) |
Promise<Path>
▸ flushCheckpoints(): void
Flushes all checkpoints, restoring the initial checkpoint state.
void
packages/trie/src/trie.ts:1319
▸ fromProof(proof): Promise<void>
Saves the nodes from a proof into the trie. A static version of this function exists with the same name.
Deprecated
Use updateFromProof
| Name | Type |
|---|---|
proof |
Proof |
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:1269
▸ 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:1216
▸ 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:1303
▸ 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>
▸ 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:1199
▸ updateFromProof(proof, shouldVerifyRoot?): Promise<undefined | Uint8Array>
Updates a trie from a proof
| Name | Type | Default value | Description |
|---|---|---|---|
proof |
Proof |
undefined |
The proof |
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
packages/trie/src/trie.ts:1005
▸ verifyProof(rootHash, key, proof): Promise<null | Uint8Array>
Verifies a proof. A static version of this function exists with the same name.
Throws
If proof is found to be invalid.
| Name | Type |
|---|---|
rootHash |
Uint8Array |
key |
Uint8Array |
proof |
Proof |
Promise<null | Uint8Array>
The value from the key, or null if valid proof of non-existence.
packages/trie/src/trie.ts:1053
▸ verifyPrunedIntegrity(): Promise<boolean>
Promise<boolean>
packages/trie/src/trie.ts:1119
▸ verifyRangeProof(rootHash, firstKey, lastKey, keys, values, proof): Promise<boolean>
| Name | Type |
|---|---|
rootHash |
Uint8Array |
firstKey |
null | Uint8Array |
lastKey |
null | Uint8Array |
keys |
Uint8Array[] |
values |
Uint8Array[] |
proof |
null | Uint8Array[] |
Promise<boolean>
packages/trie/src/trie.ts:1096
▸ 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?): Promise<Trie>
Create a trie from a given proof
| Name | Type | Description |
|---|---|---|
proof |
Proof |
proof to create trie from |
trieOpts? |
TrieOpts |
trie opts to be applied to returned trie |
Promise<Trie>
new trie created from given proof
▸ Static fromProof(proof, opts?): Promise<Trie>
Static version of fromProof function with the same behavior.
Deprecated
Use updateFromProof
| Name | Type |
|---|---|
proof |
Proof |
opts? |
TrieOpts |
Promise<Trie>
▸ Static verifyProof(key, proof, opts?): Promise<null | Uint8Array>
Static version of verifyProof function with the same behavior.
Throws
If proof is found to be invalid.
| Name | Type | Description |
|---|---|---|
key |
Uint8Array |
|
proof |
Proof |
|
opts? |
TrieOpts |
Trie options |
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>
Static version of verifyRangeProof function with the same behavior
| Name | Type |
|---|---|
rootHash |
Uint8Array |
firstKey |
null | Uint8Array |
lastKey |
null | Uint8Array |
keys |
Uint8Array[] |
values |
Uint8Array[] |
proof |
null | Uint8Array[] |
opts? |
TrieOpts |
Promise<boolean>