Class BlockMetadata

A block metadata without transactions or any proofs like nonce or hash. This represents metadata of a block that is not yet mined nor proven.

To represent a block content including its metadata and transactions, use BlockContent<T>, which is its subclass.

Inheritance

Object

BlockMetadata

BlockContent<T>

Implements

IBlockMetadata

Namespace: Libplanet.Blocks

Assembly: Libplanet.dll

Syntax

public class BlockMetadata : object, IBlockMetadata

Remarks

Unlike other model types like Block<T> or PreEvaluationBlock<T>, this type is mutable. To get a distinct instance with partly changed fields, use BlockMetadata(IBlockMetadata) constructor and property setters on a copy instead.

Constructors

BlockMetadata()

Creates an empty BlockMetadata instance. Its properties can be easily filled with C# object initializers.

Declaration

public BlockMetadata()

BlockMetadata(IBlockMetadata)

Creates a BlockMetadata by copying the fields of another block metadata.

Declaration

public BlockMetadata(IBlockMetadata metadata)

Parameters

Type	Name	Description
IBlockMetadata	metadata	This source of the block metadata to copy. This hasn't be a actual BlockMetadata instance, but can be any object which implements IBlockMetadata instance.

Exceptions

Type	Condition
InvalidBlockProtocolVersionException	Thrown when the metadata's ProtocolVersion is less than 0, or greater than CurrentProtocolVersion, the latest known protocol version.
InvalidBlockIndexException	Thrown when the metadata has a negative Index.
InvalidBlockDifficultyException	Thrown when the metadata's Difficulty is negative.
InvalidBlockTotalDifficultyException	Thrown when the metadata's TotalDifficulty is less than its Difficulty.

Fields

CurrentProtocolVersion

The latest protocol version.

Declaration

public const int CurrentProtocolVersion = null

Field Value

Type	Description
Int32

Properties

Difficulty

The mining difficulty that the block's Nonce has to satisfy.

Declaration

public long Difficulty { get; set; }

Property Value

Type	Description
Int64

Remarks

This cannot not be negative.

When Difficulty is updated, TotalDifficulty is also updated together. For example, when Difficulty = 10 and TotalDifficulty = 50, if Difficulty is updated to 20 (= 10 + 10) TotalDifficulty is also updated to 60 (= 50 + 10).

Exceptions

Type	Condition
InvalidBlockDifficultyException	Thrown when the value to set is negative.

Index

The height of the block.

Declaration

public long Index { get; set; }

Property Value

Type	Description
Int64

Remarks

Zero means it is a genesis block. Disallowed to be negative.

Exceptions

Type	Condition
InvalidBlockIndexException	Thrown when the value to set is negative.

Miner

The address of the miner.

Declaration

public Address Miner { get; set; }

Property Value

Type	Description
Address

PreviousHash

The previous block's hash. If it's a genesis block (i.e., its Index is 0) this should be null.

Declaration

public BlockHash? PreviousHash { get; set; }

Property Value

Type	Description
Nullable<BlockHash>

ProtocolVersion

The protocol version number.

Declaration

public int ProtocolVersion { get; set; }

Property Value

Type	Description
Int32

Exceptions

Type	Condition
InvalidBlockProtocolVersionException	Thrown when the value to set is less than 0, or greater than CurrentProtocolVersion, the latest known protocol version.

PublicKey

The public key of the Miner. This is used for verifying the signature.

Although this is nullable type-wise, it is mandatory where ProtocolVersion is 2 or later. As blocks had not been signed in the previous protocol versions, the type of this is nullable.

Declaration

public PublicKey PublicKey { get; set; }

Property Value

Type	Description
PublicKey

Remarks

Its setter also updates the Miner property too.

Timestamp

The time the block is created.

Declaration

public DateTimeOffset Timestamp { get; set; }

Property Value

Type	Description
DateTimeOffset

Remarks

This is always UTC.

TotalDifficulty

The total mining difficulty since the genesis including the block's Difficulty.

Declaration

public BigInteger TotalDifficulty { get; set; }

Property Value

Type	Description
BigInteger

Remarks

This must be greater than or equal to Difficulty at least, and must not be negative.

Exceptions

Type	Condition
InvalidBlockTotalDifficultyException	Thrown when the value to set is less than Difficulty.

TxHash

The hash of all transactions in the block. This is null if the block has no transactions.

Declaration

public virtual HashDigest<SHA256>? TxHash { get; set; }

Property Value

Type	Description
Nullable<HashDigest<SHA256>>

Methods

DerivePreEvaluationHash(HashAlgorithmType, Nonce)

Derives a hash digest of hashAlgorithm from the block metadata and nonce.

Declaration

public ImmutableArray<byte> DerivePreEvaluationHash(HashAlgorithmType hashAlgorithm, Nonce nonce)

Parameters

Type	Name	Description
HashAlgorithmType	hashAlgorithm	The hash algorithm to use.
Nonce	nonce	The proof-of-work nonce.

Returns

Type	Description
ImmutableArray<Byte>	A pre-evaluation block hash.

MakeCandidateData(Nonce)

Serializes data of a possible candidate shifted from it into a Bencodex dictionary. This data is used for PoW (proof-of-work) to find the satisfying nonce, rather than transmitting the block over the network.

Declaration

public Bencodex.Types.Dictionary MakeCandidateData(Nonce nonce)

Parameters

Type	Name	Description
Nonce	nonce	The nonce of the block.

Returns

Type	Description
Bencodex.Types.Dictionary	The serialized block content in a Bencodex dictionary.

MineNonce(HashAlgorithmType, CancellationToken)

Mines the PoW (proof-of-work) nonce satisfying the block Difficulty.

Declaration

public (Nonce Nonce, ImmutableArray<byte> PreEvaluationHash) MineNonce(HashAlgorithmType hashAlgorithm, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
HashAlgorithmType	hashAlgorithm	The hash algorithm to use for calculating pre-evaluation hash.
CancellationToken	cancellationToken	An optional cancellation token used to propagate signal that this operation should be cancelled.

Returns

Type	Description
(, )<Nonce, ImmutableArray<Byte>>	A pair of the mined nonce and the pre-evaluation hash that satisfy the block Difficulty.

MineNonce(HashAlgorithmType, Int32, CancellationToken)

Mines the PoW (proof-of-work) nonce satisfying the block Difficulty.

Declaration

public (Nonce Nonce, ImmutableArray<byte> PreEvaluationHash) MineNonce(HashAlgorithmType hashAlgorithm, int workers, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
HashAlgorithmType	hashAlgorithm	The hash algorithm to use for calculating pre-evaluation hash.
Int32	workers	The number of workers to run in parallel. Must be greater than zero.
CancellationToken	cancellationToken	An optional cancellation token used to propagate signal that this operation should be cancelled.

Returns

Type	Description
(, )<Nonce, ImmutableArray<Byte>>	A pair of the mined nonce and the pre-evaluation hash that satisfy the block Difficulty.

Implements

IBlockMetadata

See Also

BlockContent<T>