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>, IStore, IStateStore, Block<T>, IEnumerable<IRenderer<T>>) constructor.

Inheritance

Object

BlockChain<T>

Namespace: Libplanet.Blockchain

Assembly: Libplanet.dll

Syntax

public class BlockChain<T> : object 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>, IStore, IStateStore, Block<T>, IEnumerable<IRenderer<T>>)

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

Declaration

public BlockChain(IBlockPolicy<T> policy, 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>.
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.

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<HashDigest<SHA256>> BlockHashes { get; }

Property Value

Type	Description
IEnumerable<HashDigest<SHA256>>

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[HashDigest<SHA256>]

Gets the block corresponding to the blockHash.

Declaration

public Block<T> this[HashDigest<SHA256> blockHash] { get; }

Parameters

Type	Name	Description
HashDigest<SHA256>	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

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>, IStore, IStateStore, Block<T>, IEnumerable<IRenderer<T>>) constructor instead.

Tip

The topmost Block<T> of the current blockchain. Can be null if the blockchain is empty.

Declaration

public Block<T> Tip { get; }

Property Value

Type	Description
Block<T>

Methods

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

Adds a block to the end of this chain.

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, DateTimeOffset currentTime, StateCompleterSet<T>? stateCompleters = null)

Parameters

Type	Name	Description
Block<T>	block	A next Block<T>, which is mined, to add.
DateTimeOffset	currentTime	The current time.
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
InvalidBlockBytesLengthException	Thrown when the block to mine is too long (according to GetMaxBlockBytes(Int64)) in bytes.
InvalidBlockException	Thrown when the given block is invalid (e.g., too many transactions), in itself or according to the Policy.
InvalidTxNonceException	Thrown when the Nonce is different from GetNextTxNonce(Address) result of the Signer.

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

Adds a block to the end of this chain.

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
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(HashDigest<SHA256>)

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

Declaration

public 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 BlockChain<T>.

Returns

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

Finalize()

Declaration

protected void Finalize()

GetBalance(Address, Currency, Nullable<HashDigest<SHA256>>, FungibleAssetStateCompleter<T>)

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

Declaration

public FungibleAssetValue GetBalance(Address address, Currency currency, HashDigest<SHA256>? 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<HashDigest<SHA256>>	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.

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.

GetState(Address, Nullable<HashDigest<SHA256>>, StateCompleter<T>)

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

Declaration

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

Parameters

Type	Name	Description
Address	address	An Address to get the states of.
Nullable<HashDigest<SHA256>>	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.

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.

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

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)

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 in 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.

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.

See Also

Create(Int64, PrivateKey, Nullable<HashDigest<SHA256>>, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>)

MineBlock(Address, DateTimeOffset, Boolean, Nullable<Int32>, CancellationToken)

Mines a next Block<T> using staged Transaction<T>s, and then Append(Block<T>, Nullable<StateCompleterSet<T>>) it to the chain (unless the append option is turned off).

Declaration

public Task<Block<T>> MineBlock(Address miner, DateTimeOffset currentTime, bool append = true, int? maxTransactions = null, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
Address	miner	The Address of miner that mined the block.
DateTimeOffset	currentTime	The when mining started.
Boolean	append	Whether to Append(Block<T>, Nullable<StateCompleterSet<T>>) the mined block. Turned on by default.
Nullable<Int32>	maxTransactions	The maximum number of transactions that a block can accept. This value must be greater than 0, and less than or equal to Policy.MaxTransactionsPerBlock. Zero and negative values are treated as 1. If it is omitted or more than Policy.MaxTransactionsPerBlock, it will be treated as Policy.MaxTransactionsPerBlock.
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(Address, Boolean, Nullable<Int32>, CancellationToken)

Mines a next Block<T> using staged Transaction<T>s, and then Append(Block<T>, Nullable<StateCompleterSet<T>>) it to the chain (unless the append option is turned off).

Declaration

public Task<Block<T>> MineBlock(Address miner, bool append = true, int? maxTransactions = null, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
Address	miner	The Address of miner that mined the block.
Boolean	append	Whether to Append(Block<T>, Nullable<StateCompleterSet<T>>) the mined block. Turned on by default.
Nullable<Int32>	maxTransactions	The maximum number of transactions that a block can accept. This value must be greater than 0, and less than or equal to Policy.MaxTransactionsPerBlock. Zero and negative values are treated as 1. If it is omitted or more than Policy.MaxTransactionsPerBlock, it will be treated as Policy.MaxTransactionsPerBlock.
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.

StageTransaction(Transaction<T>)

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

Declaration

public void StageTransaction(Transaction<T> transaction)

Parameters

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

Exceptions

Type	Condition
InvalidTxException	Thrown when the given transaction is invalid.

UnstageTransaction(Transaction<T>)

Removes a transaction from the pending list.

Declaration

public void UnstageTransaction(Transaction<T> transaction)

Parameters

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

See Also

StageTransaction(Transaction<T>)