@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
>