Interface ITrie

An interface for Merkle Tree.

Namespace: Libplanet.Store.Trie

Assembly: Libplanet.Store.dll

Syntax

public interface ITrie

Properties

Hash

The state root hash of the trie.

Declaration

HashDigest<SHA256> Hash { get; }

Property Value

Type	Description
HashDigest<SHA256>

Remarks

If Root is null, this still gives a unique HashDigest<T> value corresponding to null that is never recorded.

See Also

Root

Recorded

Whether Root is recorded in the store.

Declaration

bool Recorded { get; }

Property Value

Type	Description
System.Boolean

Remarks

A Root that is null is always considered as recorded.

See Also

MerkleTrie

Root

The root of the ITrie. This is null if and only if the ITrie is empty. That is, this is never a "hashed node" of a null root.

Declaration

INode Root { get; }

Property Value

Type	Description
INode

See Also

Hash

Methods

Diff(ITrie)

Lists every non-null that is different from the one stored in other given any KeyBytes path.

Declaration

IEnumerable<(KeyBytes Path, IValue? TargetValue, IValue SourceValue)> Diff(ITrie other)

Parameters

Type	Name	Description
ITrie	other	The other MerkleTrie to compare to.

Returns

Type	Description
IEnumerable<System.ValueTuple<KeyBytes, System.Nullable<IValue>, IValue>>	A list of tuples where each tuple consists of the path where the difference occurred, the "old" value from other and the current "new" value.

Remarks

This operation has the following properties:

• This operation is non-symmetric. That is, in general, trieA.Diff(trieB) and trieB.Diff(trieA) are not the same.
• Values existing in other but not in the source instance, considered as null in the source, are not included in the result.

Exceptions

Type	Condition
InvalidTrieNodeException	Thrown when the method fails to traverse the ITrie.

See Also

MerkleTrie

Get(IReadOnlyList<KeyBytes>)

Gets the values stored with keys in Set(in KeyBytes, IValue).

Declaration

IReadOnlyList<IValue?> Get(IReadOnlyList<KeyBytes> keys)

Parameters

Type	Name	Description
IReadOnlyList<KeyBytes>	keys	The keys used in Set(in KeyBytes, IValue) to store a value.

Returns

Type	Description
IReadOnlyList<System.Nullable<IValue>>	The values associated to the specified keys. The associated values are ordered in the same way to the corresponding keys. Absent values are represented as null.

See Also

MerkleTrie

Get(KeyBytes)

Gets the values stored with key in Set(in KeyBytes, IValue).

Declaration

IValue? Get(KeyBytes key)

Parameters

Type	Name	Description
KeyBytes	key	The key used in Set(in KeyBytes, IValue) to store a value.

Returns

Type	Description
System.Nullable<IValue>	The value associated to the specified key. Absent value is represented as null.

See Also

MerkleTrie

GetNode(Nibbles)

Gets the first node encountered at nibbles when traversing down from Root.

Declaration

INode GetNode(Nibbles nibbles)

Parameters

Type	Name	Description
Nibbles	nibbles	The path to check.

Returns

Type	Description
INode	A node at nibbles, if any. Otherwise null.

Remarks

There may be more than one INode at nibbles. For instance, a FullNode, a ValueNode as the value of the aforementioned FullNode, and up to two additional HashNodes is possible.

As such, for two equivalent ITries, Libplanet.Store.Tries that would have the same committed Hashes, this may return different types of INode depending on the actual underlying "structure". However, returned INodes for such ITries are equivalent as sub-ITries.

Exceptions

Type	Condition
InvalidTrieNodeException	Thrown when an unknown type of INode is encountered while traversing to the given path.

See Also

MerkleTrie

IterateNodes()

Iterates and every stored INode along with its respective path in Nibbles.

Declaration

IEnumerable<(Nibbles Path, INode Node)> IterateNodes()

Returns

Type	Description
IEnumerable<System.ValueTuple<Nibbles, INode>>	An of all INodes in no particular order.

Remarks

This is a very heavy operation.

See Also

MerkleTrie

IterateValues()

Iterates and every stored along with its respective path in KeyBytes.

Declaration

IEnumerable<(KeyBytes Path, IValue Value)> IterateValues()

Returns

Type	Description
IEnumerable<System.ValueTuple<KeyBytes, IValue>>	An of all s in no particular order.

Remarks

This is a very heavy operation.

See Also

MerkleTrie

Remove(in KeyBytes)

Removes the value at the path corresponding to given key in memory. If there is no at key, this does nothing.

Declaration

ITrie Remove(in KeyBytes key)

Parameters

Type	Name	Description
KeyBytes	key	The unique key to associate with the value.

Returns

Type	Description
ITrie	Returns new updated ITrie.

Remarks

This should not actually remove anything from storage. The removal of the value at the marked path given by key is actually recorded to storage when Commit(ITrie) is called. Regardless, there is actually no removal of any value from storage even when Commit(ITrie) is called.

See Also

Commit(ITrie)

Set(in KeyBytes, IValue)

Stores the value at the path corresponding to given key in memory.

Declaration

ITrie Set(in KeyBytes key, IValue value)

Parameters

Type	Name	Description
KeyBytes	key	The unique key to associate with the value.
IValue	value	The value to store.

Returns

Type	Description
ITrie	Returns new updated ITrie.

Remarks

This should not actually write anything to storage. Stored value is actually written to storage when Commit(ITrie) is called.

See Also

Commit(ITrie)

Extension Methods

TrieExtensions.GetMetadata(ITrie)

TrieExtensions.SetMetadata(ITrie, IValue)

TrieExtensions.SetMetadata(ITrie, TrieMetadata)

See Also

MerkleTrie