Class PreEvaluationBlockHeader

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

Inheritance

Object

PreEvaluationBlockHeader

Implements

IPreEvaluationBlockHeader

IBlockMetadata

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

System.Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

System.Object.ToString()

Namespace: Libplanet.Types.Blocks

Assembly: Libplanet.Types.dll

Syntax

public class PreEvaluationBlockHeader : IPreEvaluationBlockHeader, IBlockMetadata

Constructors

PreEvaluationBlockHeader(BlockMetadata, HashDigest<SHA256>)

Creates a PreEvaluationBlockHeader instance with its metadata and a valid preEvaluationHash. All other public constructors should be redirected to this one.

Declaration

public PreEvaluationBlockHeader(BlockMetadata metadata, HashDigest<SHA256> preEvaluationHash)

Parameters

Type	Name	Description
BlockMetadata	metadata	Block's metadata.
HashDigest<SHA256>	preEvaluationHash	A valid hash derived from metadata.

Exceptions

Type	Condition
InvalidBlockPreEvaluationHashException	Thrown when preEvaluationHash is invalid.

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	The pre-evaluation block header to copy.

Remarks

As header needn't be an actual PreEvaluationBlockHeader instance, but simply any object implementing IPreEvaluationBlockHeader interface, it can't be trusted to satisfy all the constraints for a valid PreEvaluationBlockHeader instance. As such, conditions are checked again whilst creating a copy. This is a relatively heavy operation, so must be used sparingly.

In particular, this creates a new instance of BlockMetadata with data extracted from header. Thus any Exceptions that can be thrown from a BlockMetadata's constructors may also be thrown in addition to the ones explicitly listed below.

Exceptions

Type	Condition
InvalidBlockPreEvaluationHashException	Thrown when the given pre-evaluation header's PreEvaluationHash is invalid.

See Also

BlockMetadata

Fields

Codec

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

Declaration

protected static readonly Codec Codec

Field Value

Type	Description
Bencodex.Codec

Properties

Index

The height of the block.

Declaration

public long Index { get; }

Property Value

Type	Description
System.Int64

Remarks

Zero means it is a genesis block. Not allowed to be negative.

LastCommit

The BlockCommit about previous block's vote information.

Declaration

public BlockCommit LastCommit { get; }

Property Value

Type	Description
BlockCommit

Metadata

Internal BlockMetadata.

Declaration

public BlockMetadata Metadata { get; }

Property Value

Type	Description
BlockMetadata

Miner

The address of the miner.

Declaration

public Address Miner { get; }

Property Value

Type	Description
Address

PreEvaluationHash

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

Declaration

public HashDigest<SHA256> PreEvaluationHash { get; }

Property Value

Type	Description
HashDigest<SHA256>

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. For the latest protocol version, see CurrentProtocolVersion. We have the following version info:

• 0: The initial block protocol version number. This is not actually recorded in storage. That is, the lack of block protocol version in a stored block means it is of version 0.
• 1: Introduced to be stored with the block data. Validation for PreEvaluationHash was added.
• 2: Updated to include Signature to blocks. As a result, the miner's identity is provided as a PublicKey instead of a Address. Additionally, total difficulty was added.
• 3: Updated to fix an issue with the internal execution ordering of Transactions in blocks.
• 4: Updated to introduce a PBFT scheme. LastCommit was added and total difficulty was removed.
• 5: Updated to introduce a world model. No structural changes were made to blocks. This is used as a marker indicating when the data model should be migrated.

Declaration

public int ProtocolVersion { get; }

Property Value

Type	Description
Int32

See Also

CurrentProtocolVersion

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.

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>, in Nullable<ImmutableArray<Byte>>)

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

Declaration

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

Parameters

Type	Name	Description
HashDigest<SHA256>	stateRootHash	The state root hash.
Nullable<System.Collections.Immutable.ImmutableArray<System.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 Dictionary MakeCandidateData(HashDigest<SHA256> stateRootHash, ImmutableArray<byte>? signature = null)

Parameters

Type	Name	Description
HashDigest<SHA256>	stateRootHash	The of the resulting states after evaluating transactions and a (if exists).
Nullable<System.Collections.Immutable.ImmutableArray<System.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
System.Collections.Immutable.ImmutableArray<System.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.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the block's ProtocolVersion is less than 2.
ArgumentException	Thrown when the given privateKey does not match to the block miner's PublicKey.

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<System.Collections.Immutable.ImmutableArray<System.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
System.Boolean	true if the signature is valid. false otherwise.

Implements

IPreEvaluationBlockHeader

IBlockMetadata

Extension Methods

IBlockMetadataExtensions.ValidateTimestamp(IBlockMetadata)

IBlockMetadataExtensions.ValidateTimestamp(IBlockMetadata, DateTimeOffset)