Class BlockChain<T>

A class have Block<T>s, Transaction<T>s, and the chain information.

In order to watch its state changes, implement IRenderer<T> interface and pass it to the BlockChain(IBlockPolicy<T>, IStagePolicy<T>, IStore, IStateStore, Block<T>, IEnumerable<IRenderer<T>>) constructor.

Inheritance

Object

BlockChain<T>

Implements

IBlockChainStates<T>

Namespace: Libplanet.Blockchain

Assembly: Libplanet.dll

Syntax

public class BlockChain<T> : object, IBlockChainStates<T> where T : IAction, new()

Type Parameters

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

Remarks

This object is guaranteed that it has at least one block, since it takes a genesis block when it's instantiated.

Constructors

BlockChain(IBlockPolicy<T>, IStagePolicy<T>, IStore, IStateStore, Block<T>, IEnumerable<IRenderer<T>>)

Initializes a new instance of the BlockChain<T> class.

Declaration

public BlockChain(IBlockPolicy<T> policy, IStagePolicy<T> stagePolicy, IStore store, IStateStore stateStore, Block<T> genesisBlock, IEnumerable<IRenderer<T>> renderers = null)

Parameters

Type	Name	Description
IBlockPolicy<T>	policy	IBlockPolicy<T> to use in the BlockChain<T>.
IStagePolicy<T>	stagePolicy	The staging policy to follow.
IStore	store	IStore to store Block<T>s, Transaction<T>s, and BlockChain<T> information.
IStateStore	stateStore	IStateStore to store states.
Block<T>	genesisBlock	The genesis Block<T> of the BlockChain<T>, which is a part of the consensus. If the given store already contains the genesis block it checks if the existing genesis block and this argument is the same. If the store has no genesis block yet this argument will be used for that.
IEnumerable<IRenderer<T>>	renderers	Listens state changes on the created chain. Listens nothing by default or if it is null. Note that action renderers receive events made by unsuccessful transactions too; see also AtomicActionRenderer<T> for workaround.

Exceptions

Type	Condition
InvalidGenesisBlockException	Thrown when the store has a genesis block and it does not match to what the network expects (i.e., genesisBlock).

Properties

ActionRenderers

A filtered list, from Renderers, which contains only IActionRenderer<T> instances.

Declaration

public IImmutableList<IActionRenderer<T>> ActionRenderers { get; }

Property Value

Type	Description
IImmutableList<IActionRenderer<T>>

BlockHashes

All Hashes in the current index. The genesis block's hash goes first, and the tip goes last. Returns a integer that represents the number of elements in the BlockChain<T>.

Declaration

public IEnumerable<BlockHash> BlockHashes { get; }

Property Value

Type	Description
IEnumerable<BlockHash>

Count

Returns a integer that represents the number of elements in the BlockChain<T>.

Declaration

public long Count { get; }

Property Value

Type	Description
Int64	A number that represents how many elements in the BlockChain<T>.

Genesis

The first Block<T> in the BlockChain<T>.

Declaration

public Block<T> Genesis { get; }

Property Value

Type	Description
Block<T>

Id

Declaration

public Guid Id { get; }

Property Value

Type	Description
Guid

Item[in BlockHash]

Gets the block corresponding to the blockHash.

Declaration

public Block<T> this[in BlockHash blockHash] { get; }

Parameters

Type	Name	Description
BlockHash	blockHash	A Hash of the Block<T> to get.

Property Value

Type	Description
Block<T>

Item[Int32]

Gets the block corresponding to the index.

Declaration

public Block<T> this[int index] { get; }

Parameters

Type	Name	Description
Int32	index	A number of index of Block<T>.

Property Value

Type	Description
Block<T>

Item[Int64]

Gets the block corresponding to the index.

Declaration

public Block<T> this[long index] { get; }

Parameters

Type	Name	Description
Int64	index	A number of index of Block<T>.

Property Value

Type	Description
Block<T>

Policy

The block and blockchain policy.

Declaration

public IBlockPolicy<T> Policy { get; }

Property Value

Type	Description
IBlockPolicy<T>

Renderers

The list of registered renderers listening the state changes.

Declaration

public IImmutableList<IRenderer<T>> Renderers { get; }

Property Value

Type	Description
IImmutableList<IRenderer<T>>

Remarks

Since this value is immutable, renderers cannot be registered after once a BlockChain<T> object is instantiated; use renderers option of BlockChain(IBlockPolicy<T>, IStagePolicy<T>, IStore, IStateStore, Block<T>, IEnumerable<IRenderer<T>>) constructor instead.

StagePolicy

The staging policy.

Declaration

public IStagePolicy<T> StagePolicy { get; set; }

Property Value

Type	Description
IStagePolicy<T>

Tip

The topmost Block<T> of the current blockchain.

Declaration

public Block<T> Tip { get; }

Property Value

Type	Description
Block<T>

Methods

Append(Block<T>, Nullable<StateCompleterSet<T>>)

Adds a block to the end of this chain.

Transactions in the block updates states and balances in the blockchain, and TxExecutions for transactions are recorded.

Note that Renderers receive events right after the block is confirmed (and thus all states reflect changes in the block).

Declaration

public void Append(Block<T> block, StateCompleterSet<T>? stateCompleters = null)

Parameters

Type	Name	Description
Block<T>	block	A next Block<T>, which is mined, to add.
Nullable<StateCompleterSet<T>>	stateCompleters	The strategy to complement incomplete block states which are required for action execution and rendering. Recalculate by default.

Exceptions

Type	Condition
BlockPolicyViolationException	Thrown when given block does not satisfy any of the constraints validated by ValidateNextBlock(BlockChain<T>, Block<T>) of Policy.
InvalidBlockException	Thrown when the given block is invalid, in itself or according to the Policy.
InvalidTxNonceException	Thrown when the Nonce is different from GetNextTxNonce(Address) result of the Signer.

ContainsBlock(BlockHash)

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

Declaration

public bool ContainsBlock(BlockHash blockHash)

Parameters

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

Returns

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

ExecuteActions(Block<T>, Nullable<StateCompleterSet<T>>)

Evaluates actions in the given block and fills states with the results.

Declaration

public IReadOnlyList<ActionEvaluation> ExecuteActions(Block<T> block, StateCompleterSet<T>? stateCompleters = null)

Parameters

Type	Name	Description
Block<T>	block	A block to execute.
Nullable<StateCompleterSet<T>>	stateCompleters	The strategy to complement incomplete previous block states. Recalculate by default.

Returns

Type	Description
IReadOnlyList<ActionEvaluation>	The result of action evaluations of the given block.

Remarks

This method is idempotent (except for rendering). If the given block has executed before, it does not execute it nor mutate states. Exposed as public for benchmarking.

Finalize()

Declaration

protected void Finalize()

FindNextHashes(BlockLocator, Nullable<BlockHash>, Int32)

Find the branching point between this blockchain and locator, and the hashes of subsequent blocks from the point.

Declaration

public Tuple<long?, IReadOnlyList<BlockHash>> FindNextHashes(BlockLocator locator, BlockHash? stop = null, int count = 500)

Parameters

Type	Name	Description
BlockLocator	locator	The BlockLocator to find the branching point from.
Nullable<BlockHash>	stop	A block hash to stop looking for subsequent blocks once encountered.
Int32	count	Maximum number of block hashes to return.

Returns

Type	Description
Tuple<Nullable<Int64>, IReadOnlyList<BlockHash>>	A tuple of the index of the branching point and block hashes.

Fork(BlockHash, Boolean)

Forks the chain at point and returns the newly forked chain.

Declaration

public BlockChain<T> Fork(BlockHash point, bool inheritRenderers = true)

Parameters

Type	Name	Description
BlockHash	point	The hash in which to fork from.
Boolean	inheritRenderers	Whether to inherit the renderers from the existing chain.

Returns

Type	Description
BlockChain<T>	An instance of the newly forked chain.

GetBalance(Address, Currency, BlockHash, FungibleAssetStateCompleter<T>)

Queries address's balance of the currency in the BlockChain<T> from offset.

Declaration

public FungibleAssetValue GetBalance(Address address, Currency currency, BlockHash offset, FungibleAssetStateCompleter<T> stateCompleter)

Parameters

Type	Name	Description
Address	address	The owner Address to query.
Currency	currency	The currency type to query.
BlockHash	offset	The HashDigest<T> of the block to start finding the state.
FungibleAssetStateCompleter<T>	stateCompleter	When the BlockChain<T> instance does not contain states dirty of the block which lastly updated states of a requested address, this delegate is called and its return value is used instead. Recalculate makes the incomplete states recalculated and filled on the fly. Reject makes the incomplete states (if needed) to cause IncompleteBlockStatesException instead.

Returns

Type	Description
FungibleAssetValue	The address's current balance (or balance as of the given offset) of the currency.

GetBalance(Address, Currency, Nullable<BlockHash>, FungibleAssetStateCompleter<T>)

Queries address's balance of the currency in the BlockChain<T> from offset.

Declaration

public FungibleAssetValue GetBalance(Address address, Currency currency, BlockHash? offset = null, FungibleAssetStateCompleter<T> stateCompleter = null)

Parameters

Type	Name	Description
Address	address	The owner Address to query.
Currency	currency	The currency type to query.
Nullable<BlockHash>	offset	The HashDigest<T> of the block to start finding the state. It will be the tip of the BlockChain<T> if it is null.
FungibleAssetStateCompleter<T>	stateCompleter	When the BlockChain<T> instance does not contain states dirty of the block which lastly updated states of a requested address, this delegate is called and its return value is used instead. Recalculate makes the incomplete states recalculated and filled on the fly. Reject (which is default) makes the incomplete states (if needed) to cause IncompleteBlockStatesException instead.

Returns

Type	Description
FungibleAssetValue	The address's current balance (or balance as of the given offset) of the currency.

GetBlockLocator(Int32)

Returns a new BlockLocator from the tip of current chain.

Declaration

public BlockLocator GetBlockLocator(int threshold = 10)

Parameters

Type	Name	Description
Int32	threshold	The amount of consequent blocks to include before sampling.

Returns

Type	Description
BlockLocator	A instance of block locator.

GetNextTxNonce(Address)

Gets next Nonce of the address.

Declaration

public long GetNextTxNonce(Address address)

Parameters

Type	Name	Description
Address	address	The Address from which to obtain the Nonce value.

Returns

Type	Description
Int64	The next Nonce value of the address.

GetStagedTransactionIds()

Lists all staged TxIds.

Declaration

public IImmutableSet<TxId> GetStagedTransactionIds()

Returns

Type	Description
IImmutableSet<TxId>	of staged transactions.

GetState(Address, Nullable<BlockHash>, StateCompleter<T>)

Gets the state of the given address in the BlockChain<T> from offset.

Declaration

public IValue GetState(Address address, BlockHash? offset = null, StateCompleter<T> stateCompleter = null)

Parameters

Type	Name	Description
Address	address	An Address to get the states of.
Nullable<BlockHash>	offset	The HashDigest<T> of the block to start finding the state. It will be The tip of the BlockChain<T> if it is null.
StateCompleter<T>	stateCompleter	When the BlockChain<T> instance does not contain states dirty of the block which lastly updated states of a requested address, this delegate is called and its return value is used instead. Recalculate makes the incomplete states recalculated and filled on the fly. Reject (which is default) makes the incomplete states (if needed) to cause IncompleteBlockStatesException instead.

Returns

Type	Description
IValue	The current state of given address. This can be null if address has no value.

GetStates(IReadOnlyList<Address>, BlockHash, StateCompleter<T>)

Declaration

public IReadOnlyList<IValue> GetStates(IReadOnlyList<Address> addresses, BlockHash offset, StateCompleter<T> stateCompleter)

Parameters

Type	Name	Description
IReadOnlyList<Address>	addresses
BlockHash	offset
StateCompleter<T>	stateCompleter

Returns

Type	Description
IReadOnlyList<IValue>

GetStates(IReadOnlyList<Address>, Nullable<BlockHash>, StateCompleter<T>)

Gets multiple states associated to the specified addresses.

Declaration

public IReadOnlyList<IValue> GetStates(IReadOnlyList<Address> addresses, BlockHash? offset = null, StateCompleter<T> stateCompleter = null)

Parameters

Type	Name	Description
IReadOnlyList<Address>	addresses	Addresses of states to query.
Nullable<BlockHash>	offset	The HashDigest<T> of the block to start finding the states. Tip by default.
StateCompleter<T>	stateCompleter	When the BlockChain<T> instance does not contain states of the block, this delegate is called and its return values are used instead. Recalculate makes the incomplete states recalculated and filled on the fly. Reject (which is default) makes the incomplete states (if needed) to cause IncompleteBlockStatesException instead.

Returns

Type	Description
IReadOnlyList<IValue>	The states associated to the specified addresses. Associated values are ordered in the same way to the corresponding addresses. Absent states are represented as null.

GetTotalSupply(Currency, BlockHash, TotalSupplyStateCompleter<T>)

Gets the total supply of a currency in the BlockChain<T> from offset, and if not found, return 0.

Declaration

public FungibleAssetValue GetTotalSupply(Currency currency, BlockHash offset, TotalSupplyStateCompleter<T> stateCompleter)

Parameters

Type	Name	Description
Currency	currency	The currency type to query.
BlockHash	offset	The HashDigest<T> of the block to start finding the state.
TotalSupplyStateCompleter<T>	stateCompleter	When the BlockChain<T> instance does not contain states of the block, this delegate is called and its return values are used instead. Recalculate makes the incomplete states recalculated and filled on the fly. Reject makes the incomplete states (if needed) to cause IncompleteBlockStatesException instead.

Returns

Type	Description
FungibleAssetValue	The total supply value of currency at offset in FungibleAssetValue.

GetTotalSupply(Currency, Nullable<BlockHash>, TotalSupplyStateCompleter<T>)

Gets the total supply of a currency in the BlockChain<T> from offset, and if not found, derive from the sum of all balances.

Declaration

public FungibleAssetValue GetTotalSupply(Currency currency, BlockHash? offset = null, TotalSupplyStateCompleter<T> stateCompleter = null)

Parameters

Type	Name	Description
Currency	currency	The currency type to query.
Nullable<BlockHash>	offset	The HashDigest<T> of the block to start finding the state.
TotalSupplyStateCompleter<T>	stateCompleter	When the BlockChain<T> instance does not contain states of the block, this delegate is called and its return values are used instead. Recalculate makes the incomplete states recalculated and filled on the fly. Reject makes the incomplete states (if needed) to cause IncompleteBlockStatesException instead.

Returns

Type	Description
FungibleAssetValue	The total supply value of currency at offset in FungibleAssetValue.

GetTransaction(TxId)

Gets the transaction corresponding to the txId.

Declaration

public Transaction<T> GetTransaction(TxId txId)

Parameters

Type	Name	Description
TxId	txId	A TxId of the Transaction<T> to get.

Returns

Type	Description
Transaction<T>	Transaction<T> with txId.

GetTxExecution(BlockHash, TxId)

Queries the recorded TxExecution for a successful or failed Transaction<T> within a Block<T>.

Declaration

public TxExecution GetTxExecution(BlockHash blockHash, TxId txid)

Parameters

Type	Name	Description
BlockHash	blockHash	The Hash of the Block<T> that the Transaction<T> is executed within.
TxId	txid	The executed Transaction<T>'s Id.

Returns

Type	Description
TxExecution	The recorded TxExecution. If the transaction has never been executed within the block, it returns null instead.

MakeGenesisBlock(IEnumerable<T>, PrivateKey, Nullable<DateTimeOffset>, IAction, Predicate<Currency>)

Mine the genesis block of the blockchain.

Declaration

public static Block<T> MakeGenesisBlock(IEnumerable<T> actions = null, PrivateKey privateKey = null, DateTimeOffset? timestamp = null, IAction blockAction = null, Predicate<Currency> nativeTokenPredicate = null)

Parameters

Type	Name	Description
IEnumerable<T>	actions	List of actions will be included in the genesis block. If it's null, it will be replaced with as default.
PrivateKey	privateKey	A private key to sign the transaction and the genesis block. If it's null, it will use new private key as default.
Nullable<DateTimeOffset>	timestamp	The timestamp of the genesis block. If it's null, it will use as default.
IAction	blockAction	A block action to execute and be rendered for every block. It must match to BlockAction of Policy.
Predicate<Currency>	nativeTokenPredicate	A predicate function to determine whether the specified Currency is a native token defined by chain's NativeTokens or not. Treat no Currency as native token if the argument omitted.

Returns

Type	Description
Block<T>	The genesis block mined with parameters.

MakeTransaction(PrivateKey, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>)

Creates a new Transaction<T> and stage the transaction. Cannot create new transaction if the genesis block does not exist.

Declaration

public Transaction<T> MakeTransaction(PrivateKey privateKey, IEnumerable<T> actions, IImmutableSet<Address> updatedAddresses = null, DateTimeOffset? timestamp = null)

Parameters

Type	Name	Description
PrivateKey	privateKey	A PrivateKey of the account who creates and signs a new transaction.
IEnumerable<T>	actions	A list of IActions to include to a new transaction.
IImmutableSet<Address>	updatedAddresses	Addresses whose states affected by actions.
Nullable<DateTimeOffset>	timestamp	The time this Transaction<T> is created and signed.

Returns

Type	Description
Transaction<T>	A created new Transaction<T> signed by the given privateKey.

MineBlock(PrivateKey, DateTimeOffset, Boolean, Int64, Int32, Int32, IComparer<Transaction<T>>, CancellationToken)

Mines a next Block<T> using staged Transaction<T>s.

Declaration

public async Task<Block<T>> MineBlock(PrivateKey miner, DateTimeOffset timestamp, bool append, long maxBlockBytes, int maxTransactions, int maxTransactionsPerSigner, IComparer<Transaction<T>> txPriority = null, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
PrivateKey	miner	The miner's PublicKey that mines the block.
DateTimeOffset	timestamp	The when mining started.
Boolean	append	Whether to append the mined block immediately after mining.
Int64	maxBlockBytes	The maximum number of bytes a block can have. See also GetMaxBlockBytes(Int64).
Int32	maxTransactions	The maximum number of transactions that a block can accept. See also GetMaxTransactionsPerBlock(Int64).
Int32	maxTransactionsPerSigner	The maximum number of transactions that a block can accept per signer. See also GetMaxTransactionsPerSignerPerBlock(Int64).
IComparer<Transaction<T>>	txPriority	An optional comparer for give certain transactions to priority to belong to the block. No certain priority by default.
CancellationToken	cancellationToken	A cancellation token used to propagate notification that this operation should be canceled.

Returns

Type	Description
Task<Block<T>>	An awaitable task with a Block<T> that is mined.

MineBlock(PrivateKey, Nullable<DateTimeOffset>, Nullable<Boolean>, Nullable<Int64>, Nullable<Int32>, Nullable<Int32>, IComparer<Transaction<T>>, Nullable<CancellationToken>)

Mines a next Block<T> using staged Transaction<T>s.

All unprovided and/or null arguments are reassigned accordingly and redirected to a overloaded method with non-nullable parameters. By default, a policy adhering block is produced with current timestamp and appended immediately to the chain.

Declaration

public async Task<Block<T>> MineBlock(PrivateKey miner, DateTimeOffset? timestamp = null, bool? append = null, long? maxBlockBytes = null, int? maxTransactions = null, int? maxTransactionsPerSigner = null, IComparer<Transaction<T>> txPriority = null, CancellationToken? cancellationToken = null)

Parameters

Type	Name	Description
PrivateKey	miner	The miner's PublicKey that mines the block.
Nullable<DateTimeOffset>	timestamp	The when mining started.
Nullable<Boolean>	append	Whether to append the mined block immediately after mining.
Nullable<Int64>	maxBlockBytes	The maximum number of bytes a block can have. See also GetMaxBlockBytes(Int64).
Nullable<Int32>	maxTransactions	The maximum number of transactions that a block can accept. See also GetMaxTransactionsPerBlock(Int64).
Nullable<Int32>	maxTransactionsPerSigner	The maximum number of transactions that a block can accept per signer. See also GetMaxTransactionsPerSignerPerBlock(Int64).
IComparer<Transaction<T>>	txPriority	An optional comparer for give certain transactions to priority to belong to the block. No certain priority by default.
Nullable<CancellationToken>	cancellationToken	A cancellation token used to propagate notification that this operation should be canceled.

Returns

Type	Description
Task<Block<T>>	An awaitable task with a Block<T> that is mined.

PerceiveBlock(IBlockExcerpt, Nullable<DateTimeOffset>)

Records and queries the perceivedTime of the given blockExcerpt.

Although blocks have their own Timestamp, but these values are untrustworthy as they are arbitrarily determined by their miners.

On the other hand, this method returns the subjective time according to the local node's perception.

If the local node has never perceived the blockExcerpt yet, it is perceived at that moment and the current time is returned instead. (However, you can replace the current time with the perceivedTime option.) In other words, this method is idempotent.

Declaration

public BlockPerception PerceiveBlock(IBlockExcerpt blockExcerpt, DateTimeOffset? perceivedTime = null)

Parameters

Type	Name	Description
IBlockExcerpt	blockExcerpt	The perceived block.
Nullable<DateTimeOffset>	perceivedTime	The time the local node perceived the given blockExcerpt. The current time by default.

Returns

Type	Description
BlockPerception	A pair of a block and the time it was perceived.

StageTransaction(Transaction<T>)

Adds transaction to the pending list so that a next Block<T> to be mined may contain given transaction.

Declaration

public bool StageTransaction(Transaction<T> transaction)

Parameters

Type	Name	Description
Transaction<T>	transaction	Transaction<T> to add to the pending list.

Returns

Type	Description
Boolean	true if staging was successful, false otherwise.

Exceptions

Type	Condition
InvalidTxGenesisHashException	Thrown when given transaction has invalid GenesisHash.

UnstageTransaction(Transaction<T>)

Removes a transaction from the pending list.

Declaration

public bool UnstageTransaction(Transaction<T> transaction)

Parameters

Type	Name	Description
Transaction<T>	transaction	A Transaction<T> to remove from the pending list.

Returns

Type	Description
Boolean	true if unstaging was successful, false otherwise.

See Also

StageTransaction(Transaction<T>)

Implements

IBlockChainStates<T>