Package com.privatechain.core.builder

Class BlockchainNode

java.lang.Object
com.privatechain.core.builder.BlockchainNode
public final class BlockchainNode extends Object
Top-level entry point for the private-blockchain library.

BlockchainNode orchestrates all subsystems — chain management, mempool, event bus, P2P networking — through a well-defined lifecycle (start() / stop()).

Minimum example (FR-CFG-02)


 BlockchainNode node = BlockchainConfig.builder().build().start();
 System.out.println(node.status().chainHeight());
 node.stop();

Milestone 8 changes (T-066)

Since:
1.0.0
See Also:

  • Constructor Details

    • BlockchainNode

      public BlockchainNode(BlockchainConfig config)
      Constructs a BlockchainNode from the given configuration.

      Construction is lightweight — it does not start networking or mine blocks. Call start() to begin operations. The event bus is always non-null because BlockchainConfig.Builder initialises it unconditionally.

      Parameters:
      config - the fully built configuration (non-null)
      Throws:
      NullPointerException - if config is null

  • Method Details

    • setNodeServer

      public void setNodeServer(NodeServerLifecycle nodeServer)
      Wires the node server into this node.

      Called by blockchain-network during assembly. Applications should not call this directly.

      Parameters:
      nodeServer - the server to bind on start(); may be null for standalone mode

    • setPeerManager

      public void setPeerManager(PeerManagerLifecycle peerManager)
      Wires the peer manager into this node.

      Called by blockchain-network during assembly.

      Parameters:
      peerManager - the peer manager to start/stop with this node; may be null for standalone mode

    • setSyncManager

      public void setSyncManager(ChainSyncer syncManager)
      Wires the chain syncer into this node.

      Called by blockchain-network during assembly.

      Parameters:
      syncManager - the syncer to invoke on startup; may be null for standalone mode

    • start

      public BlockchainNode start()
      Starts the blockchain node.

      Steps in order:

      1. Genesis block if chain is empty (FR-CORE-07).
      2. Mempool TTL eviction scheduler (Milestone 8).
      3. PeerManagerLifecycle heartbeat (Milestone 7).
      4. NodeServerLifecycle TCP bind (Milestone 7).
      5. Initial chain sync via ChainSyncer (Milestone 7).
      Returns:
      this node (for fluent use)
      Throws:
      IllegalStateException - if already started

    • stop

      public void stop()
      Stops the blockchain node and cleanly releases all subsystems.

      Shutdown order (reverse of startup):

      1. Stop NodeServerLifecycle
      2. Stop PeerManagerLifecycle
      3. Stop mempool eviction scheduler (Milestone 8)
      4. Shutdown BlockchainEventBus
      Throws:
      IllegalStateException - if not yet started

    • submitTransaction

      public void submitTransaction(Transaction transaction)
      Validates and submits a transaction through the configured validator chain.

      Each registered TransactionValidator is applied in sequence. On success the transaction is added to the mempool which publishes a BlockchainEvent.TransactionSubmittedEvent (T-066).

      Parameters:
      transaction - the transaction to submit (non-null)
      Throws:
      NullPointerException - if transaction is null
      TransactionValidationException - if any validator rejects the transaction
      IllegalStateException - if the node has not been started

    • getChain

      public Blockchain getChain()
      Returns the underlying Blockchain for direct chain access.
      Returns:
      non-null Blockchain

    • getMempool

      public TransactionMempool getMempool()
      Returns the transaction mempool managed by this node.
      Returns:
      non-null TransactionMempool

    • status

      public BlockchainNode.NodeStatus status()
      Returns a snapshot of the current node status (NFR-UX-04).

      The mempoolSize field is populated from the live TransactionMempool (fixed in Milestone 8; was always 0 before).

      Returns:
      non-null BlockchainNode.NodeStatus
      Throws:
      IllegalStateException - if the node has not been started