Class PreEvaluationBlockHeader

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

Inheritance
Object
PreEvaluationBlockHeader
PreEvaluationBlock<T>
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

| Improve this Doc View Source

PreEvaluationBlockHeader(BlockMetadata, HashAlgorithmType, Nonce)

Declaration
protected PreEvaluationBlockHeader(BlockMetadata metadata, HashAlgorithmType hashAlgorithm, Nonce nonce)
Parameters
Type Name Description
BlockMetadata metadata
HashAlgorithmType hashAlgorithm
Nonce nonce
| Improve this Doc View Source

PreEvaluationBlockHeader(BlockMetadata, HashAlgorithmType, Nonce, ImmutableArray<Byte>)

Declaration
protected PreEvaluationBlockHeader(BlockMetadata metadata, HashAlgorithmType hashAlgorithm, Nonce nonce, ImmutableArray<byte> preEvaluationHash)
Parameters
Type Name Description
BlockMetadata metadata
HashAlgorithmType hashAlgorithm
Nonce nonce
ImmutableArray<Byte> preEvaluationHash
| Improve this Doc View Source

PreEvaluationBlockHeader(IBlockMetadata, HashAlgorithmType, 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, HashAlgorithmType hashAlgorithm, Nonce nonce)
Parameters
Type Name Description
IBlockMetadata metadata

Block's metadata.
HashAlgorithmType hashAlgorithm

The hash algorithm used for calculating PreEvaluationHash.
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.
| Improve this Doc View Source

PreEvaluationBlockHeader(IBlockMetadata, HashAlgorithmType, 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, HashAlgorithmType hashAlgorithm, Nonce nonce, ImmutableArray<byte> preEvaluationHash)
Parameters
Type Name Description
IBlockMetadata metadata

Block's metadata.
HashAlgorithmType hashAlgorithm

The hash algorithm used for calculating PreEvaluationHash.
Nonce nonce

A valid proof-of-work nonce which satisfies the required Difficulty.
ImmutableArray<Byte> preEvaluationHash

The hash digest of the hashAlgorithm 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.
| Improve this Doc View Source

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

| Improve this Doc View Source

Codec

Declaration
protected static readonly Codec Codec
Field Value
Type Description
Codec

Properties

| Improve this Doc View Source

Difficulty

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

Declaration
public long Difficulty { get; }
Property Value
Type Description
Int64
| Improve this Doc View Source

HashAlgorithm

The hash algorithm used for calculating PreEvaluationHash.

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

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.

| Improve this Doc View Source

Metadata

The internal block metadata.

Declaration
protected BlockMetadata Metadata { get; }
Property Value
Type Description
BlockMetadata
| Improve this Doc View Source

Miner

The address of the miner.

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

Nonce

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

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

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

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; }
Property Value
Type Description
Nullable<BlockHash>
| Improve this Doc View Source

ProtocolVersion

The protocol version number.

Declaration
public int ProtocolVersion { get; }
Property Value
Type Description
Int32
| Improve this Doc View Source

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

Timestamp

The time the block is created.

Declaration
public DateTimeOffset Timestamp { get; }
Property Value
Type Description
DateTimeOffset
Remarks

This is always UTC.

| Improve this Doc View Source

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.

| Improve this Doc View Source

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

| Improve this Doc View Source

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

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

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.

| Improve this Doc View Source

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