Package com.privatechain.core.spi

Interface ConsensusEngine

All Known Implementing Classes:
PBFTEngine, ProofOfAuthorityEngine, ProofOfWorkEngine, RoundRobinEngine
public interface ConsensusEngine
Service Provider Interface (SPI) for pluggable consensus algorithms.

Implement this interface to define how new blocks are produced and how existing blocks are validated. The library ships four built-in implementations in the blockchain-consensus module:

  • ProofOfWorkEngine — SHA-256 mining with configurable difficulty
  • ProofOfAuthorityEngine — authorized-signer allowlist
  • PBFTEngine — practical Byzantine fault-tolerance (3-phase commit)
  • RoundRobinEngine — deterministic slot-based rotation (dev/test)

Inject your implementation via BlockchainConfig:


 BlockchainNode node = BlockchainConfig.builder()
     .consensusEngine(new MyCustomEngine())
     .build();

Thread safety: Implementations must be safe for concurrent calls to validateBlock(com.privatechain.core.model.Block, com.privatechain.core.builder.Blockchain) (e.g., during sync) but mineBlock(java.util.List<com.privatechain.core.model.Transaction>, com.privatechain.core.model.Block) is called from a single producer thread per node.

Since:
1.0.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    engineName()
    Returns a human-readable name identifying this consensus engine.
    Block
    mineBlock(List<Transaction> transactions, Block previousBlock)
    Produces a new candidate block from the given transactions and the current chain tip.
    boolean
    validateBlock(Block block, Blockchain chain)
    Validates whether the given block satisfies the consensus rules of this engine.

  • Method Details

    • validateBlock

      boolean validateBlock(Block block, Blockchain chain)
      Validates whether the given block satisfies the consensus rules of this engine.

      Implementations should verify engine-specific invariants such as:

      • PoW: block.getHash() meets the required difficulty target
      • PoA: block.getHeader() is signed by an authorized node
      • PBFT: block carries the required quorum of pre-commit signatures

      This method is called by Blockchain.addBlock(com.privatechain.core.model.Block) before the block is appended to the chain. Returning false causes addBlock to throw a BlockValidationException.

      Parameters:
      block - the candidate block to validate (non-null)
      chain - the current blockchain state at the time of validation (non-null)
      Returns:
      true if the block is valid according to this engine's rules
      Throws:
      ConsensusException - if an unrecoverable error occurs during validation (e.g., network quorum unreachable in PBFT)

    • mineBlock

      Block mineBlock(List<Transaction> transactions, Block previousBlock)
      Produces a new candidate block from the given transactions and the current chain tip.

      For mining-based engines (PoW) this method blocks until a valid nonce is found. For authority-based engines (PoA, Round-Robin) it returns almost immediately after signing. For PBFT, it initiates the multiphase protocol and returns once a quorum has been reached.

      The returned block must pass validateBlock(com.privatechain.core.model.Block, com.privatechain.core.builder.Blockchain) when called on the same engine instance.

      Parameters:
      transactions - ordered list of transactions to include (non-null; may be empty)
      previousBlock - the current chain tip that the new block will extend (non-null)
      Returns:
      a fully formed, consensus-ready block ready to be passed to Blockchain.addBlock(com.privatechain.core.model.Block)
      Throws:
      ConsensusException - if block production fails (e.g., not enough peers for PBFT quorum)

    • engineName

      String engineName()
      Returns a human-readable name identifying this consensus engine.

      Used in log messages, metrics labels, and the node status response. Must be stable across restarts (i.e., don't include a random UUID).

      Returns:
      non-null, non-blank engine name (e.g., "ProofOfWork", "PBFT")