Class BlockChain<T>

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

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, Block<T>)

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

Declaration

public BlockChain(IBlockPolicy<T> policy, IStore store, Block<T> genesisBlock)

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

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

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>

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

Adds a block to the end of this chain.

Note that Render(IActionContext, IAccountStateDelta) methods of all IAction objects that belong to the block are called right after the block is confirmed (and thus all states reflect changes in the block).

Declaration

public void Append(Block<T> block)

Parameters

Type	Name	Description
Block<T>	block	A next Block<T>, which is mined, to add.

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.

Append(Block<T>, DateTimeOffset)

Adds a block to the end of this chain.

Note that Render(IActionContext, IAccountStateDelta) methods of all IAction objects that belong to the block are called right after the block is confirmed (and thus all states reflect changes in the block).

Declaration

public void Append(Block<T> block, DateTimeOffset currentTime)

Parameters

Type	Name	Description
Block<T>	block	A next Block<T>, which is mined, to add.
DateTimeOffset	currentTime	The current time.

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

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>>, Boolean)

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

Declaration

public IValue GetState(Address address, HashDigest<SHA256>? offset = null, bool completeStates = false)

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.
Boolean	completeStates	When the BlockChain<T> instance does not contain states dirty of the block which lastly updated states of a requested address, this option makes the incomplete states calculated and filled on the fly. If this option is turned off (which is default) this method throws IncompleteBlockStatesException instead for the same situation. Just-in-time calculation of states could take a long time so that the overall latency of an application may rise.

Returns

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

Exceptions

Type	Condition
IncompleteBlockStatesException	Thrown when the BlockChain<T> instance does not contain states dirty of the block which lastly updated states of a requested address, because actions in the block have never been executed. If completeStates option is turned on this exception is not thrown and incomplete states are calculated and filled on the fly instead.

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

Mine the genesis block of the blockchain.

Declaration

public static Block<T> MakeGenesisBlock(IEnumerable<T> actions = null, PrivateKey privateKey = null, DateTimeOffset? timestamp = 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.

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.

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, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>)

MineBlock(Address)

Declaration

public Task<Block<T>> MineBlock(Address miner)

Parameters

Type	Name	Description
Address	miner

Returns

Type	Description
Task<Block<T>>

MineBlock(Address, DateTimeOffset, CancellationToken)

Mine a Block<T> using staged Transaction<T>s.

Declaration

public Task<Block<T>> MineBlock(Address miner, DateTimeOffset currentTime, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
Address	miner	The Address of miner that mined the block.
DateTimeOffset	currentTime	The when mining started.
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>)

Events

TipChanged

An event which is invoked when Tip is changed.

Declaration

public event EventHandler<BlockChain<T>.TipChangedEventArgs> TipChanged

Event Type

Type	Description
EventHandler<BlockChain.TipChangedEventArgs<>>

See Also

IAction

Block<T>

Transaction<T>