Class PreEvaluationBlockHeader

A block candidate without evaluating actions (in its transactions and a possible BlockAction) and state root hash.

Inheritance

Object

PreEvaluationBlockHeader

PreEvaluationBlock<T>

Implements

IPreEvaluationBlockHeader

IBlockMetadata

Namespace: Libplanet.Blocks

Assembly: Libplanet.dll

Syntax

public class PreEvaluationBlockHeader : object, IPreEvaluationBlockHeader, IBlockMetadata

Remarks

It guarantees that every instance of this type has a valid proof-of-work Nonce which satisfies its Difficulty.

Constructors

PreEvaluationBlockHeader(BlockMetadata, Nonce)

Declaration

protected PreEvaluationBlockHeader(BlockMetadata metadata, Nonce nonce)

Parameters

Type	Name	Description
BlockMetadata	metadata
Nonce	nonce

PreEvaluationBlockHeader(BlockMetadata, Nonce, ImmutableArray<Byte>)

Declaration

protected PreEvaluationBlockHeader(BlockMetadata metadata, Nonce nonce, ImmutableArray<byte> preEvaluationHash)

Parameters

Type	Name	Description
BlockMetadata	metadata
Nonce	nonce
ImmutableArray<Byte>	preEvaluationHash

PreEvaluationBlockHeader(IBlockMetadata, Nonce)

Creates a PreEvaluationBlockHeader instance with its metadata and a valid proof-of-work nonce which satisfies the required Difficulty.

Declaration

public PreEvaluationBlockHeader(IBlockMetadata metadata, Nonce nonce)

Parameters

Type	Name	Description
IBlockMetadata	metadata	Block's metadata.
Nonce	nonce	A valid proof-of-work nonce which satisfies the required Difficulty.

Remarks

PreEvaluationHash is automatically derived from the given arguments.

Exceptions

Type	Condition
InvalidBlockProtocolVersionException	Thrown when the metadata's to set is 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.
InvalidBlockNonceException	Thrown when the given proof-of-work nonce does not satisfy the required Difficulty.

PreEvaluationBlockHeader(IBlockMetadata, Nonce, ImmutableArray<Byte>)

Creates a PreEvaluationBlockHeader instance with its metadata, a valid proof-of-work nonce which satisfies the required Difficulty, and a preEvaluationHash digest derived from them.

Declaration

public PreEvaluationBlockHeader(IBlockMetadata metadata, Nonce nonce, ImmutableArray<byte> preEvaluationHash)

Parameters

Type	Name	Description
IBlockMetadata	metadata	Block's metadata.
Nonce	nonce	A valid proof-of-work nonce which satisfies the required Difficulty.
ImmutableArray<Byte>	preEvaluationHash	The hash digest derived from the given arguments.

Exceptions

Type	Condition
InvalidBlockProtocolVersionException	Thrown when the metadata's to set is 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.
InvalidBlockPreEvaluationHashException	Thrown when the given preEvaluationHash is invalid.
InvalidBlockNonceException	Thrown when the given proof-of-work nonce does not satisfy the required Difficulty.

PreEvaluationBlockHeader(IPreEvaluationBlockHeader)

Creates a PreEvaluationBlockHeader by copying the fields of another pre-evaluation block header.

Declaration

public PreEvaluationBlockHeader(IPreEvaluationBlockHeader header)

Parameters

Type	Name	Description
IPreEvaluationBlockHeader	header	A pre-evaluation block header to copy.

Exceptions

Type	Condition
InvalidBlockProtocolVersionException	Thrown when the header's to set is ProtocolVersion is less than 0, or greater than CurrentProtocolVersion, the latest known protocol version.
InvalidBlockIndexException	Thrown when the header has a negative Index.
InvalidBlockDifficultyException	Thrown when the header's Difficulty is negative.
InvalidBlockTotalDifficultyException	Thrown when the header's TotalDifficulty is less than its Difficulty.
InvalidBlockPreEvaluationHashException	Thrown when the given pre-evaluation header's PreEvaluationHash is invalid.
InvalidBlockNonceException	Thrown when the given pre-evaluation header's Nonce does not satisfy the required Difficulty.

Fields

Codec

Declaration

protected static readonly Codec Codec

Field Value

Type	Description
Codec

Properties

Difficulty

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

Declaration

public long Difficulty { get; }

Property Value

Type	Description
Int64

Index

The height of the block.

Declaration

public long Index { get; }

Property Value

Type	Description
Int64

Remarks

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

Metadata

The internal block metadata.

Declaration

protected BlockMetadata Metadata { get; }

Property Value

Type	Description
BlockMetadata

Miner

The address of the miner.

Declaration

public Address Miner { get; }

Property Value

Type	Description
Address

Nonce

The proof-of-work nonce which satisfies the required Difficulty.

Declaration

public Nonce Nonce { get; }

Property Value

Type	Description
Nonce

PreEvaluationHash

The hash derived from the block except of its state root hash (i.e., without action evaluation). Used for validating Nonce.

Declaration

public ImmutableArray<byte> PreEvaluationHash { get; }

Property Value

Type	Description
ImmutableArray<Byte>

See Also

Nonce

PreviousHash

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

Declaration

public BlockHash? PreviousHash { get; }

Property Value

Type	Description
Nullable<BlockHash>

ProtocolVersion

The protocol version number.

Declaration

public int ProtocolVersion { get; }

Property Value

Type	Description
Int32

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

Property Value

Type	Description
PublicKey

Timestamp

The time the block is created.

Declaration

public DateTimeOffset Timestamp { get; }

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

Property Value

Type	Description
BigInteger

Remarks

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

TxHash

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

Declaration

public HashDigest<SHA256>? TxHash { get; }

Property Value

Type	Description
Nullable<HashDigest<SHA256>>

Methods

DeriveBlockHash(in HashDigest<SHA256>, Nullable<ImmutableArray<Byte>>)

Derives a hash digest from the given pre-evaluation block header and stateRootHash.

Declaration

public BlockHash DeriveBlockHash(in HashDigest<SHA256> stateRootHash, ImmutableArray<byte>? signature)

Parameters

Type	Name	Description
HashDigest<SHA256>	stateRootHash	The state root hash.
Nullable<ImmutableArray<Byte>>	signature	The block signature created using MakeSignature(PrivateKey, HashDigest<SHA256>) method with the stateRootHash. This must be null for blocks with earlier ProtocolVersions than 2.

Returns

Type	Description
BlockHash	A block hash.

MakeCandidateData(HashDigest<SHA256>, Nullable<ImmutableArray<Byte>>)

Serializes data of a possible candidate shifted from it into a Bencodex dictionary. This data is used as the input to calculate the block Hash, rather than transmitting the block over the network.

Declaration

public Bencodex.Types.Dictionary MakeCandidateData(HashDigest<SHA256> stateRootHash, ImmutableArray<byte>? signature = null)

Parameters

Type	Name	Description
HashDigest<SHA256>	stateRootHash	The Hash of the resulting states after evaluating transactions and a BlockAction (if exists).
Nullable<ImmutableArray<Byte>>	signature	The block signature created using MakeSignature(PrivateKey, HashDigest<SHA256>) method with the stateRootHash. This must be null for blocks with earlier ProtocolVersions than 2.

Returns

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

MakeSignature(PrivateKey, HashDigest<SHA256>)

Makes a signature of the block content with a stateRootHash using the given privateKey.

Declaration

public ImmutableArray<byte> MakeSignature(PrivateKey privateKey, HashDigest<SHA256> stateRootHash)

Parameters

Type	Name	Description
PrivateKey	privateKey	The miner's private key. This must match to the block's Miner and PublicKey.
HashDigest<SHA256>	stateRootHash	The state root hash to include to the input message to sign.

Returns

Type	Description
ImmutableArray<Byte>	The signature of the block content with a stateRootHash using the given privateKey.

Remarks

As blocks have their signatures since the ProtocolVersion 2, it is not usable with blocks of the earlier ProtocolVersions than 2.

VerifySignature(Nullable<ImmutableArray<Byte>>, HashDigest<SHA256>)

Verifies if the given block signature is valid with the block content and the specified stateRootHash.

Declaration

public bool VerifySignature(ImmutableArray<byte>? signature, HashDigest<SHA256> stateRootHash)

Parameters

Type	Name	Description
Nullable<ImmutableArray<Byte>>	signature	The block signature created using MakeSignature(PrivateKey, HashDigest<SHA256>) method with the stateRootHash. This must be null for blocks with earlier ProtocolVersions than 2.
HashDigest<SHA256>	stateRootHash	The state root hash included in the original message of the signature.

Returns

Type	Description
Boolean	true if the signature is valid. false otherwise.

Implements

IPreEvaluationBlockHeader

IBlockMetadata