Package com.privatechain.consensus

Class ConsensusSupport

java.lang.Object

com.privatechain.consensus.ConsensusSupport

public final class ConsensusSupport
extends Object

Shared helper methods for built-in consensus engines.

The consensus module follows the same explicit-wiring philosophy as the rest of the codebase: each engine is a concrete implementation of ConsensusEngine, and common block-construction logic lives in a single utility class so the individual engines stay focused on their own policy.

The helpers in this class are responsible for three recurring tasks:

• validating configured peer / validator collections,
• building blocks in a canonical, deterministic way, and
• checking shared integrity constraints such as Merkle-root and prefix rules.

All methods are stateless and thread-safe.

Since:

1.0.0

Method Summary

Modifier and Type	Method	Description
static Block	buildBlock(Block previousBlock, List<Transaction> transactions, int bits, long nonce, String minerAddress, Instant timestamp)	Builds a canonical block from consensus-specific inputs.
static List<String>	copyAndValidate(Collection<String> values, String label, boolean sort)	Returns a validated, defensive copy of the supplied string values.
static boolean	hasConsistentIntegrity(Block block)	Performs the baseline integrity checks shared by all consensus engines.
static boolean	hasLeadingZeroBits(String hexHash, int leadingZeroBits)	Verifies that a block hash satisfies a leading-zero-bit constraint.
static boolean	isGenesis(Block block)	Returns true if the supplied block is the genesis block.
static String	merkleRoot(List<Transaction> transactions)	Computes the canonical Merkle root for the supplied transactions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

copyAndValidate

public static List<String> copyAndValidate(Collection<String> values,
 String label,
 boolean sort)

Returns a validated, defensive copy of the supplied string values.

The returned list is immutable and can optionally be sorted into deterministic lexicographic order. This is useful for consensus policies that should produce stable output regardless of caller input ordering.

Parameters:

values - the values to validate and copy

label - human-readable label used in exception messages

sort - whether to sort the copy into deterministic lexicographic order

Returns:

an immutable list containing the validated values

Throws:

NullPointerException - if values or any element is null

IllegalArgumentException - if any element is blank

merkleRoot

public static String merkleRoot(List<Transaction> transactions)

Computes the canonical Merkle root for the supplied transactions.

The Merkle tree is built from transaction identifiers in the exact order supplied by the caller. That keeps the block hash deterministic and makes the resulting root suitable for inclusion in a block header.

Parameters:

transactions - the transactions to commit into the block

Returns:

the Merkle root derived from the ordered transaction IDs

Throws:

NullPointerException - if transactions or any transaction is null

buildBlock

public static Block buildBlock(Block previousBlock,
 List<Transaction> transactions,
 int bits,
 long nonce,
 String minerAddress,
 Instant timestamp)

Builds a canonical block from consensus-specific inputs.

The returned block uses the previous block hash, the supplied ordered transactions, and a header populated with the provided metadata. Each engine supplies the header values that make sense for its protocol (for example, proof-of-work uses the difficulty field as a mining target marker, while authority-based engines use the miner address).

Parameters:

previousBlock - the chain tip the block extends

transactions - ordered transactions to include

bits - engine-specific compact target or protocol marker

nonce - nonce value to embed in the block header

minerAddress - address of the producing node, or null

timestamp - block creation time

Returns:

a freshly constructed immutable block

Throws:

NullPointerException - if previousBlock, transactions, or timestamp is null

isGenesis

public static boolean isGenesis(Block block)

Returns true if the supplied block is the genesis block.

Parameters:

block - the block to inspect

Returns:

true if the block has index 0

Throws:

NullPointerException - if block is null

hasLeadingZeroBits

public static boolean hasLeadingZeroBits(String hexHash,
 int leadingZeroBits)

Verifies that a block hash satisfies a leading-zero-bit constraint.

The hash is supplied as lowercase hexadecimal, so the check is performed at bit precision instead of assuming a nibble-aligned prefix. This keeps the helper useful for both coarse and fine-grained difficulty settings.

Parameters:

hexHash - lowercase hex-encoded SHA-256 hash

leadingZeroBits - required number of leading zero bits

Returns:

true if the hash satisfies the requested prefix constraint

Throws:

NullPointerException - if hexHash is null

hasConsistentIntegrity

public static boolean hasConsistentIntegrity(Block block)

Performs the baseline integrity checks shared by all consensus engines.

The check verifies that the stored block hash still matches the block contents and that the Merkle root in the header matches the transactions carried by the block.

Parameters:

block - the candidate block

Returns:

true if the block hash and Merkle root both match the payload

Throws:

NullPointerException - if block is null