Interface IStore

Namespace: Libplanet.Store

Assembly: Libplanet.dll

Syntax

public interface IStore

Methods

AppendIndex(Guid, HashDigest<SHA256>)

Declaration

long AppendIndex(Guid chainId, HashDigest<SHA256> hash)

Parameters

Type	Name	Description
Guid	chainId
HashDigest<SHA256>	hash

Returns

Type	Description
Int64

ContainsBlock(HashDigest<SHA256>)

Determines whether the IStore contains Block<T> the specified blockHash.

Declaration

bool ContainsBlock(HashDigest<SHA256> blockHash)

Parameters

Type	Name	Description
HashDigest<SHA256>	blockHash	The HashDigest<T> of the Block<T> to check if it is in the IStore.

Returns

Type	Description
Boolean	true if the IStore contains Block<T> with the specified blockHash; otherwise, false.

ContainsTransaction(TxId)

Determines whether the IStore contains Transaction<T> the specified txId.

Declaration

bool ContainsTransaction(TxId txId)

Parameters

Type	Name	Description
TxId	txId	The TxId of the Transaction<T> to check if it is in the IStore.

Returns

Type	Description
Boolean	true if the IStore contains Transaction<T> with the specified txId; otherwise, false.

CountBlocks()

Declaration

long CountBlocks()

Returns

Type	Description
Int64

CountIndex(Guid)

Declaration

long CountIndex(Guid chainId)

Parameters

Type	Name	Description
Guid	chainId

Returns

Type	Description
Int64

CountTransactions()

Declaration

long CountTransactions()

Returns

Type	Description
Int64

DeleteBlock(HashDigest<SHA256>)

Declaration

bool DeleteBlock(HashDigest<SHA256> blockHash)

Parameters

Type	Name	Description
HashDigest<SHA256>	blockHash

Returns

Type	Description
Boolean

DeleteChainId(Guid)

Deletes an index, tx nonces, and state references in the given chainId. It also deletes chain itself. If there is no such chainId it does nothing.

Declaration

void DeleteChainId(Guid chainId)

Parameters

Type	Name	Description
Guid	chainId	The ID of chain to delete.

Remarks

This does not delete blocks or transactions that belong to the index of the chainId, but only the index, tx nonces, and state references.

DeleteTransaction(TxId)

Declaration

bool DeleteTransaction(TxId txid)

Parameters

Type	Name	Description
TxId	txid

Returns

Type	Description
Boolean

ForkBlockIndexes(Guid, Guid, HashDigest<SHA256>)

Forks block indexes from sourceChainId to destinationChainId.

Declaration

void ForkBlockIndexes(Guid sourceChainId, Guid destinationChainId, HashDigest<SHA256> branchPoint)

Parameters

Type	Name	Description
Guid	sourceChainId	The chain ID of block indexes to fork.
Guid	destinationChainId	The chain ID of destination block indexes.
HashDigest<SHA256>	branchPoint	The branch point Block<T> to fork.

Exceptions

Type	Condition
ChainIdNotFoundException	Thrown when the given sourceChainId does not exist.

See Also

IterateIndexes(Guid, Int32, Nullable<Int32>)

AppendIndex(Guid, HashDigest<SHA256>)

ForkStateReferences<T>(Guid, Guid, Block<T>)

Forks state references, which are Hashes that have the state of the Addresses, from sourceChainId to destinationChainId.

This method copies state references from sourceChainId to destinationChainId and strips state references after branchPoint.

Declaration

void ForkStateReferences<T>(Guid sourceChainId, Guid destinationChainId, Block<T> branchPoint)
    where T : IAction, new()

Parameters

Type	Name	Description
Guid	sourceChainId	The chain ID of state references to fork.
Guid	destinationChainId	The new chain ID to have state references.
Block<T>	branchPoint	The branch point Block<T> to fork.

Type Parameters

Name	Description
T	An IAction class used with branchPoint.

Exceptions

Type	Condition
ChainIdNotFoundException	Thrown when the given sourceChainId does not exist.

See Also

IterateStateReferences(Guid, String, Nullable<Int64>, Nullable<Int64>, Nullable<Int32>)

StoreStateReference(Guid, IImmutableSet<String>, HashDigest<SHA256>, Int64)

GetBlock<T>(HashDigest<SHA256>)

Gets the corresponding stored Block<T> to the given blockHash.

Declaration

Block<T> GetBlock<T>(HashDigest<SHA256> blockHash)
    where T : IAction, new()

Parameters

Type	Name	Description
HashDigest<SHA256>	blockHash	Hash to find.

Returns

Type	Description
Block<T>	A found block, or null if no block having such blockHash is stored.

Type Parameters

Name	Description
T	An IAction type. It should match to Block<T>'s type parameter.

GetBlockDigest(HashDigest<SHA256>)

Gets the corresponding stored BlockDigest to the given blockHash.

Declaration

BlockDigest? GetBlockDigest(HashDigest<SHA256> blockHash)

Parameters

Type	Name	Description
HashDigest<SHA256>	blockHash	Hash to find.

Returns

Type	Description
Nullable<BlockDigest>	A found BlockDigest, or null if no block having such blockHash is stored.

GetBlockIndex(HashDigest<SHA256>)

Gets a stored block's Index by its Hash.

Declaration

long? GetBlockIndex(HashDigest<SHA256> blockHash)

Parameters

Type	Name	Description
HashDigest<SHA256>	blockHash	Hash to find.

Returns

Type	Description
Nullable<Int64>	A found block's Index, or null if no block having such blockHash is stored.

Remarks

It provides only limited information, but can be called without any type parameter unlike GetBlock<T>(HashDigest<SHA256>).

GetBlockStates(HashDigest<SHA256>)

Gets the states updated by actions in the inquired block.

Declaration

IImmutableDictionary<string, IValue> GetBlockStates(HashDigest<SHA256> blockHash)

Parameters

Type	Name	Description
HashDigest<SHA256>	blockHash	Hash to query.

Returns

Type	Description
IImmutableDictionary<String, IValue>	The states updated by actions in the inquired block. If actions definitely do not update any addresses it returns an empty map. If there is no record for the inquired block (because actions in it have never been evaluated yet) it returns null instead.

Remarks

It does not return all states built up from the genesis block nor delta, but only dirty states by actions the inquired block.

For example, if actions in the genesis block do a++; b++, /// and actions in the second block do b++; c++, this method /// for the second block returns b = 2; c = 1 (dirty), not a = 1; b = 2; c = 1 (all states) nor b = 1; c = 1 (delta).

See Also

SetBlockStates(HashDigest<SHA256>, IImmutableDictionary<String, IValue>)

GetCanonicalChainId()

Gets the ID of the current canonical chain.

Declaration

Guid? GetCanonicalChainId()

Returns

Type	Description
Nullable<Guid>	The ID of the current canonical chain. Maybe null.

See Also

SetCanonicalChainId(Guid)

GetTransaction<T>(TxId)

Declaration

Transaction<T> GetTransaction<T>(TxId txid)
    where T : IAction, new()

Parameters

Type	Name	Description
TxId	txid

Returns

Type	Description
Transaction<T>

Type Parameters

Name	Description
T

GetTxNonce(Guid, Address)

Gets Transaction<T> nonce of the address.

Declaration

long GetTxNonce(Guid chainId, Address address)

Parameters

Type	Name	Description
Guid	chainId	The ID of the chain to get Transaction<T> nonce.
Address	address	The Address to get Transaction<T> nonce.

Returns

Type	Description
Int64	A Transaction<T> nonce. If there is no previous Transaction<T>, return 0.

See Also

IncreaseTxNonce(Guid, Address, Int64)

IncreaseTxNonce(Guid, Address, Int64)

Increases (or decreases if a negative delta is given) the tx nonce counter for signer.

Declaration

void IncreaseTxNonce(Guid chainId, Address signer, long delta = null)

Parameters

Type	Name	Description
Guid	chainId	The ID of the chain to increase Transaction<T> nonce.
Address	signer	The address of the account to increase tx nonce.
Int64	delta	How many to increase the counter. A negative number decreases the counter. 1 by default.

See Also

GetTxNonce(Guid, Address)

IndexBlockHash(Guid, Int64)

Declaration

HashDigest<SHA256>? IndexBlockHash(Guid chainId, long index)

Parameters

Type	Name	Description
Guid	chainId
Int64	index

Returns

Type	Description
Nullable<HashDigest<SHA256>>

IterateBlockHashes()

Declaration

IEnumerable<HashDigest<SHA256>> IterateBlockHashes()

Returns

Type	Description
IEnumerable<HashDigest<SHA256>>

IterateIndexes(Guid, Int32, Nullable<Int32>)

Lists all block hashes in the .

Declaration

IEnumerable<HashDigest<SHA256>> IterateIndexes(Guid chainId, int offset = 0, int? limit = null)

Parameters

Type	Name	Description
Guid	chainId	The chain ID of the index that contains block hashes to iterate.
Int32	offset	The starting point to return block hashes.
Nullable<Int32>	limit	The maximum number of block hashes to get.

Returns

Type	Description
IEnumerable<HashDigest<SHA256>>	Block hashes in the index of the chainId, in ascending order; the genesis block goes first, and the tip block goes last.

IterateStagedTransactionIds()

Iterates staged TxIds.

Declaration

IEnumerable<TxId> IterateStagedTransactionIds()

Returns

Type	Description
IEnumerable<TxId>	Staged TxIds.

IterateStateReferences(Guid, String, Nullable<Int64>, Nullable<Int64>, Nullable<Int32>)

Gets pairs of a state reference and a corresponding Index of the requested key in the specified chainId.

Declaration

IEnumerable<Tuple<HashDigest<SHA256>, long>> IterateStateReferences(Guid chainId, string key, long? highestIndex = null, long? lowestIndex = null, int? limit = null)

Parameters

Type	Name	Description
Guid	chainId	The chain ID.
String	key	The key to get state references.
Nullable<Int64>	highestIndex	The highest index of state references to get. If it is null, it will be the highest index possible.
Nullable<Int64>	lowestIndex	The lowest index of state references to get. If it is null, it will be the lowest index possible.
Nullable<Int32>	limit	The maximum number of state references to get. If it is null, it does not limit the number of state references.

Returns

Type	Description
IEnumerable<Tuple<HashDigest<SHA256>, Int64>>	Ordered pairs of a state reference and a corresponding Index. The highest index (i.e., the closest to the tip) goes first and the lowest index (i.e., the closest to the genesis) goes last.

See Also

StoreStateReference(Guid, IImmutableSet<String>, HashDigest<SHA256>, Int64)

IterateTransactionIds()

Declaration

IEnumerable<TxId> IterateTransactionIds()

Returns

Type	Description
IEnumerable<TxId>

ListAllStateReferences(Guid, Int64, Int64)

Lists all accounts, that have any states, in the given chainId and their state references.

Declaration

IImmutableDictionary<string, IImmutableList<HashDigest<SHA256>>> ListAllStateReferences(Guid chainId, long lowestIndex = null, long highestIndex = null)

Parameters

Type	Name	Description
Guid	chainId	The chain ID to look up state references.
Int64	lowestIndex	Includes state references only made after the block this argument refers to.
Int64	highestIndex	Excludes state references made after the block this argument refers to.

Returns

Type	Description
IImmutableDictionary<String, IImmutableList<HashDigest<SHA256>>>	A dictionary of account addresses to lists of their corresponding state references. Each list of state references is in ascending order, i.e., the block closest to the genesis goes first and the block closest to the tip goes last.

ListChainIds()

Lists existing chain IDs.

Declaration

IEnumerable<Guid> ListChainIds()

Returns

Type	Description
IEnumerable<Guid>	Existing chain IDs.

ListStateKeys(Guid)

Lists all keys that have ever had states.

Declaration

IEnumerable<string> ListStateKeys(Guid chainId)

Parameters

Type	Name	Description
Guid	chainId	The ID of the chain to list state keys.

Returns

Type	Description
IEnumerable<String>	All state keys in an arbitrary order. The order might be vary for each call.

ListTxNonces(Guid)

Lists all Addresses that have ever signed Transaction<T>, and their corresponding Transaction<T> nonces.

Declaration

IEnumerable<KeyValuePair<Address, long>> ListTxNonces(Guid chainId)

Parameters

Type	Name	Description
Guid	chainId	The ID of the chain to list Addresses and their Transaction<T> nonces.

Returns

Type	Description
IEnumerable<KeyValuePair<Address, Int64>>	Pairs of an Address and its tx nonce. All nonces are greater than 0. (If there are underlying entries having zero nonces these must be hidden.)

See Also

GetTxNonce(Guid, Address)

LookupStateReference<T>(Guid, String, Block<T>)

Looks up a state reference, which is a block's Hash that contains an action mutating the key's tate.

Declaration

Tuple<HashDigest<SHA256>, long> LookupStateReference<T>(Guid chainId, string key, Block<T> lookupUntil)
    where T : IAction, new()

Parameters

Type	Name	Description
Guid	chainId	The chain ID to look up a state reference.
String	key	The state key to look up.
Block<T>	lookupUntil	The upper bound (i.e., the latest block) of the search range. Block<T>s after lookupUntil are ignored.

Returns

Type	Description
Tuple<HashDigest<SHA256>, Int64>	Returns a nullable tuple consisting of Hash and Index of the Block<T> with the state of the address.

Type Parameters

Name	Description
T	An IAction class used with lookupUntil.

See Also

StoreStateReference(Guid, IImmutableSet<String>, HashDigest<SHA256>, Int64)

IterateStateReferences(Guid, String, Nullable<Int64>, Nullable<Int64>, Nullable<Int32>)

PruneBlockStates<T>(Guid, Block<T>)

Prunes states in blockchain chainId with until specified block until.

Declaration

void PruneBlockStates<T>(Guid chainId, Block<T> until)
    where T : IAction, new()

Parameters

Type	Name	Description
Guid	chainId	The chain ID to prune block states.
Block<T>	until	The upper bound block to prune states.

Type Parameters

Name	Description
T	An IAction class used with until.

PutBlock<T>(Block<T>)

Puts the given block in to the store. If the same block already exists in the store it does nothing.

Declaration

void PutBlock<T>(Block<T> block)
    where T : IAction, new()

Parameters

Type	Name	Description
Block<T>	block	A Block<T> to put into the store.

Type Parameters

Name	Description
T	An IAction class used with block.

PutTransaction<T>(Transaction<T>)

Puts a given Transaction<T> to the store. If the same transaction already exists in the store it does nothing.

Declaration

void PutTransaction<T>(Transaction<T> tx)
    where T : IAction, new()

Parameters

Type	Name	Description
Transaction<T>	tx	A transaction to put into the store.

Type Parameters

Name	Description
T	An IAction type. It should match to Transaction<T>'s type parameter.

SetBlockStates(HashDigest<SHA256>, IImmutableDictionary<String, IValue>)

Sets the states updated by actions in the specified block (i.e., blockHash).

Declaration

void SetBlockStates(HashDigest<SHA256> blockHash, IImmutableDictionary<string, IValue> states)

Parameters

Type	Name	Description
HashDigest<SHA256>	blockHash	Hash to update states.
IImmutableDictionary<String, IValue>	states	The states updated by actions in the specified block (i.e., blockHash).

See Also

GetBlockStates(HashDigest<SHA256>)

SetCanonicalChainId(Guid)

Sets the canonical chain.

Declaration

void SetCanonicalChainId(Guid chainId)

Parameters

Type	Name	Description
Guid	chainId	The ID of a new canonical chain.

See Also

GetCanonicalChainId()

StageTransactionIds(IImmutableSet<TxId>)

Adds TxIds to the pending list so that a next Block<T> to be mined contains the corresponding Transaction<T>s.

Declaration

void StageTransactionIds(IImmutableSet<TxId> txids)

Parameters

Type	Name	Description
IImmutableSet<TxId>	txids	TxIds to add to pending list.

StoreStateReference(Guid, IImmutableSet<String>, HashDigest<SHA256>, Int64)

Marks the specified keys updated by any action in the specified block (i.e., blockHash).

Declaration

void StoreStateReference(Guid chainId, IImmutableSet<string> keys, HashDigest<SHA256> blockHash, long blockIndex)

Parameters

Type	Name	Description
Guid	chainId	The ID of the chain to store a state reference.
IImmutableSet<String>	keys	The keys updated by the block.
HashDigest<SHA256>	blockHash	The Hash of the block which changes the keys' states.
Int64	blockIndex	The block index.

See Also

IterateStateReferences(Guid, String, Nullable<Int64>, Nullable<Int64>, Nullable<Int32>)

UnstageTransactionIds(ISet<TxId>)

Declaration

void UnstageTransactionIds(ISet<TxId> txids)

Parameters

Type	Name	Description
ISet<TxId>	txids

Extension Methods

StoreExtensions.Copy(IStore, IStore)