Show / Hide Table of Contents

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

| Improve this Doc View Source

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

| Improve this Doc View Source

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>>
| Improve this Doc View Source

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>
| Improve this Doc View Source

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

| Improve this Doc View Source

Genesis

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

Declaration
public Block<T> Genesis { get; }
Property Value
Type Description
Block<T>
| Improve this Doc View Source

Id

Declaration
public Guid Id { get; }
Property Value
Type Description
Guid
| Improve this Doc View Source

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>
| Improve this Doc View Source

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>
| Improve this Doc View Source

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>
| Improve this Doc View Source

Policy

The block and blockchain policy.

Declaration
public IBlockPolicy<T> Policy { get; }
Property Value
Type Description
IBlockPolicy<T>
| Improve this Doc View Source

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.

| Improve this Doc View Source

StagePolicy

The staging policy.

Declaration
public IStagePolicy<T> StagePolicy { get; set; }
Property Value
Type Description
IStagePolicy<T>
| Improve this Doc View Source

Tip

The topmost Block<T> of the current blockchain.

Declaration
public Block<T> Tip { get; }
Property Value
Type Description
Block<T>

Methods

| Improve this Doc View Source

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
InvalidBlockBytesLengthException

Thrown when the given block is too long in bytes (according to GetMaxBlockBytes(Int64)).

BlockExceedingTransactionsException

Thrown when the given block has too many transactions (according to GetMaxTransactionsPerBlock(Int64)).

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.

| Improve this Doc View Source

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.

| Improve this Doc View Source

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.

| Improve this Doc View Source

Finalize()

Declaration
protected void Finalize()
| Improve this Doc View Source

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.

| Improve this Doc View Source

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.

| Improve this Doc View Source

GetStagedTransactionIds()

Lists all staged TxIds.

Declaration
public IImmutableSet<TxId> GetStagedTransactionIds()
Returns
Type Description
IImmutableSet<TxId>

of staged transactions.

| Improve this Doc View Source

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.

| Improve this Doc View Source

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.

| Improve this Doc View Source

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.

| Improve this Doc View Source

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

Mine the genesis block of the blockchain.

Declaration
public static Block<T> MakeGenesisBlock(HashAlgorithmType hashAlgorithm, IEnumerable<T> actions = null, PrivateKey privateKey = null, DateTimeOffset? timestamp = null, IAction blockAction = null)
Parameters
Type Name Description
HashAlgorithmType hashAlgorithm

The hash algorithm for proof-of-work on the genesis block.

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.

Returns
Type Description
Block<T>

The genesis block mined with parameters.

| Improve this Doc View Source

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<BlockHash>, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>)
| Improve this Doc View Source

MineBlock(PrivateKey, DateTimeOffset, Boolean, 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, 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.

Int32 maxTransactions

The maximum number of transactions that a block can accept. See also GetMaxTransactionsPerBlock(Int64) method.

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.

| Improve this Doc View Source

MineBlock(PrivateKey, Nullable<DateTimeOffset>, Nullable<Boolean>, 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, 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<Int32> maxTransactions

The maximum number of transactions that a block can accept. See also GetMaxTransactionsPerBlock(Int64) method.

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.

| Improve this Doc View Source

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.

| Improve this Doc View Source

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.

| Improve this Doc View Source

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>)
  • Improve this Doc
  • View Source
In This Article
Back to top Copyright © 2018–2021 Planetarium