Package com.privatechain.core.model

Record Class BlockHeader

java.lang.Object
java.lang.Record
com.privatechain.core.model.BlockHeader
Record Components:
version - protocol version (must be ≥ 1)
bits - compact difficulty target used by PoW consensus; 0 for non-PoW engines
nonce - proof-of-work nonce discovered during mining
merkleRoot - hex-encoded SHA-256 Merkle root of the block's transactions
timestamp - instant at which the block was produced (UTC, non-null)
public record BlockHeader(int version, int bits, long nonce, String merkleRoot, Instant timestamp) extends Record
Lightweight, immutable record representing the header of a Block.

The header contains all metadata needed for chain validation without loading the full transaction list, satisfying FR-CORE-05. It is a Java record to guarantee immutability and provide auto-generated equals/hashCode/toString.

Fields follow Bitcoin-style naming conventions where applicable:

  • version — protocol version for future-compatibility
  • bits — compact difficulty target (PoW specific; ignored by other engines)
  • nonce — mutable-during-mining counter; fixed after block is sealed
  • merkleRoot — SHA-256 root of the transaction Merkle tree
  • timestamp — wall-clock time at block creation (UTC)
Since:
1.0.0
See Also:

  • Field Details

    • EMPTY_MERKLE_ROOT

      public static final String EMPTY_MERKLE_ROOT
      Sentinel Merkle root used when a block contains no transactions.
      See Also:

  • Constructor Details

    • BlockHeader

      public BlockHeader(int version, int bits, long nonce, String merkleRoot, Instant timestamp)
      Canonical constructor with validation.
      Parameters:
      version - protocol version (must be ≥ 1)
      bits - compact difficulty target (≥ 0)
      nonce - mining nonce
      merkleRoot - Merkle root hex string (non-null, non-blank)
      timestamp - block timestamp (non-null)
      Throws:
      IllegalArgumentException - if version < 1, bits < 0, or strings are blank
      NullPointerException - if merkleRoot or timestamp is null

  • Method Details

    • of

      public static BlockHeader of(int bits, long nonce, String merkleRoot)
      Creates a BlockHeader with the current UTC timestamp and version 1.

      Convenience factory for common use cases where the caller does not need to control the timestamp (e.g., tests, quick demos).

      Parameters:
      bits - compact difficulty target
      nonce - mining nonce
      merkleRoot - Merkle root hex string
      Returns:
      a new BlockHeader timestamped Instant.now()

    • genesis

      public static BlockHeader genesis()
      Creates a genesis-block header with a zero nonce and the empty Merkle root.
      Returns:
      a header suitable for use as the genesis block header

    • builder

      public static BlockHeader.Builder builder()
      Returns a new BlockHeader.Builder pre-populated with sensible defaults.
      Returns:
      a mutable builder for constructing a BlockHeader

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • version

      public int version()
      Returns the value of the version record component.
      Returns:
      the value of the version record component

    • bits

      public int bits()
      Returns the value of the bits record component.
      Returns:
      the value of the bits record component

    • nonce

      public long nonce()
      Returns the value of the nonce record component.
      Returns:
      the value of the nonce record component

    • merkleRoot

      public String merkleRoot()
      Returns the value of the merkleRoot record component.
      Returns:
      the value of the merkleRoot record component

    • timestamp

      public Instant timestamp()
      Returns the value of the timestamp record component.
      Returns:
      the value of the timestamp record component