Package com.privatechain.core.model

Class Block

java.lang.Object
com.privatechain.core.model.Block
public final class Block extends Object
Immutable unit of the blockchain containing a list of transactions and a cryptographic link to the previous block (FR-CORE-01).

Every Block is self-contained: its hash is computed from the block's own fields (including previousHash and the Merkle root of its transactions) during construction and stored immutably. Tampering with any field of a block — or any transaction inside it — invalidates the hash, which in turn invalidates every subsequent block's previousHash link, making fraud detectable by Blockchain.isChainValid().

minerAddress is an optional field populated by consensus engines that need to identify which node produced a block (e.g. PoA, RoundRobin, PBFT). PoW blocks leave this field null since the producer is identified by hash effort alone.

Usage


 // PoW block (no miner address needed)
 Block block = Block.builder()
     .index(1)
     .previousHash(genesisBlock.getHash())
     .transactions(txList)
     .header(BlockHeader.builder().nonce(42L).build())
     .build();

 // PoA / RoundRobin / PBFT block (miner address required)
 Block block = Block.builder()
     .index(1)
     .previousHash(genesisBlock.getHash())
     .transactions(txList)
     .header(BlockHeader.builder().build())
     .minerAddress("0xABC...")
     .build();
Since:
1.0.0
See Also:

  • Field Details

    • GENESIS_PREVIOUS_HASH

      public static final String GENESIS_PREVIOUS_HASH
      The previousHash value of the genesis block (index 0). Defined as 64 hex-encoded zero bytes per FR-CORE-07.
      See Also:

  • Constructor Details

    • Block

      public Block(int index, BlockHeader header, String previousHash, String hash, List<Transaction> transactions, String minerAddress)
      Constructs a fully formed, immutable block.

      The hash parameter is stored as-is (not recomputed). New blocks should be created via Block.Builder.build() which computes the hash automatically.

      Parameters:
      index - block index (≥ 0)
      header - block header (non-null)
      previousHash - SHA-256 hex of the preceding block (non-null)
      hash - SHA-256 hex of this block (non-null)
      transactions - transactions in this block (non-null; may be empty)
      minerAddress - address of the producing node, or null for PoW blocks
      Throws:
      NullPointerException - if indexed, header, previousHash, hash, or transactions is null
      IllegalArgumentException - if index is negative

  • Method Details

    • computeHash

      public static String computeHash(int index, String previousHash, BlockHeader header, String minerAddress)
      Computes the SHA-256 hash of a block from its constituent fields.

      The hash input is a deterministic canonical string formed by concatenating: index, previousHash, merkleRoot, timestamp, version, bits, nonce, and minerAddress. Including minerAddress in the hash ensures a block cannot claim a different producer without invalidating its hash.

      Parameters:
      index - block index
      previousHash - hex hash of the previous block
      header - block header (supplies nonce, Merkle root, etc.)
      minerAddress - producing node address; use "" when absent
      Returns:
      hex-encoded SHA-256 digest of the canonical input
      Throws:
      IllegalStateException - if SHA-256 is not available (unreachable on JDK 17+)

    • computeHash

      public static String computeHash(int index, String previousHash, BlockHeader header)
      Backwards-compatible overload that omits minerAddress.

      Delegates to computeHash(int, String, BlockHeader, String) with minerAddress = null. Preserved so existing callers in blockchain-core that do not supply a miner address compile without changes.

      Parameters:
      index - block index
      previousHash - hex hash of the previous block
      header - block header
      Returns:
      hex-encoded SHA-256 digest

    • builder

      public static Block.Builder builder()
      Returns a new, empty Block.Builder.

    • getIndex

      public int getIndex()
      Returns the zero-based index of this block in the chain.

    • getHeader

      public BlockHeader getHeader()
      Returns the block header (version, nonce, Merkle root, timestamp).

    • getPreviousHash

      public String getPreviousHash()
      Returns the SHA-256 hash of the preceding block.

    • getHash

      public String getHash()
      Returns the pre-computed SHA-256 hash of this block.

    • getTransactions

      public List<Transaction> getTransactions()
      Returns the ordered, immutable list of transactions in this block.

    • getMerkleRoot

      public String getMerkleRoot()
      Convenience accessor for the Merkle root stored in the header.

    • getMinerAddress

      public String getMinerAddress()
      Returns the address of the node that produced this block, or null for PoW blocks where no identity claim is embedded.

      Used by identity-based consensus engines (ProofOfAuthorityEngine, RoundRobinEngine, PBFTEngine — all in blockchain-consensus) to validate that the block was produced by an authorized node.

      Returns:
      miner address string, or null

    • isHashValid

      public boolean isHashValid()
      Verifies that the stored hash matches a fresh computation.

      Used by Blockchain.isChainValid() and storage implementations after deserialization to detect corruption (NFR-SEC-03).

      Returns:
      true if the stored hash equals a freshly computed hash

    • equals

      public boolean equals(Object obj)
      Two blocks are equal if and only if their hashes are equal.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare
      Returns:
      true if obj is a Block with the same hash

    • hashCode

      public int hashCode()
      Hash code based on the block's SHA-256 hash string.
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Human-readable summary safe for logging (hash truncated, no tx data).
      Overrides:
      toString in class Object