Package com.privatechain.examples.spring

Class BlockchainRestController

java.lang.Object
com.privatechain.examples.spring.BlockchainRestController
@RestController @RequestMapping("/api") public class BlockchainRestController extends Object
REST controller exposing the blockchain node as a set of HTTP endpoints.

Demonstrates the blockchain-spring autoconfiguration pattern (AC-10): the BlockchainNode is injected as a Spring bean with no boilerplate — it is created and started by BlockchainAutoConfiguration purely from application.yml properties.

Endpoints

Available REST endpoints
MethodPathDescriptionStatus
GET /api/status Node status snapshot 200
GET /api/chain All blocks as a JSON array 200
GET /api/chain/{index} Single block by index 200 / 404
POST/api/transactions Submit and sign a payment 202 / 422
POST/api/mine Mine a block from the mempool 200 / 204

Thread safety

All fields are final and injected via constructor. BlockchainNode is thread-safe internally (design.md §7.4). Spring MVC's default servlet thread pool may invoke these endpoints concurrently without additional synchronization.

Since:
1.0.0
See Also:

  • Constructor Details

    • BlockchainRestController

      public BlockchainRestController(BlockchainNode node, Wallet demoWallet)
      Constructs the controller via Spring constructor injection.
      Parameters:
      node - the autoconfigured blockchain node (non-null)
      demoWallet - the demo signing wallet (non-null)
      Throws:
      NullPointerException - if either argument is null

  • Method Details

    • getStatus

      @GetMapping("/status") public org.springframework.http.ResponseEntity<BlockchainNode.NodeStatus> getStatus()
      Returns a live snapshot of the node's operational status.

      Sample response:

      
 {
   "chainHeight": 3,
   "mempoolSize": 0,
   "peerCount": 0,
   "lastBlockTime": "2026-06-06T10:00:00Z",
   "consensusEngine": "NoOp"
 }
      Returns:
      HTTP 200 with the BlockchainNode.NodeStatus record as JSON

    • getChain

      @GetMapping("/chain") public org.springframework.http.ResponseEntity<List<Block>> getChain()
      Returns the full blockchain as an ordered JSON array.

      Each element is a Block serialized with its complete header, transaction list, and hash fields. For large chains, consider adding pagination via getBlock(int) instead.

      Returns:
      HTTP 200 with a JSON array of all blocks in ascending index order

    • getBlock

      @GetMapping("/chain/{index}") public org.springframework.http.ResponseEntity<Block> getBlock(@PathVariable int index)
      Returns a single block by its zero-based index.
      Parameters:
      index - the block index (≥ 0)
      Returns:
      HTTP 200 with the block, or HTTP 404 if no block exists at that index

    • submitTransaction

      @PostMapping("/transactions") public org.springframework.http.ResponseEntity<Map<String,Object>> submitTransaction(@RequestBody BlockchainRestController.TransactionRequest request)
      Accepts a payment transaction request, signs it with the demo wallet, and submits it to the mempool.

      Request body:

      
 {
   "senderAddress": "1AbcDef...",
   "receiverAddress": "1XyzWvu...",
   "amount": 42.00,
   "currency": "USD"
 }

      Response (202 ACCEPTED):

      
 {
   "txId": "3f4a6b2c-...",
   "status": "PENDING",
   "mempoolSize": 1
 }
      Parameters:
      request - the payment request body (non-null)
      Returns:
      HTTP 202 ACCEPTED with the transaction ID on success, HTTP 422 UNPROCESSABLE_CONTENT if validation fails

    • mineBlock

      @PostMapping("/mine") public org.springframework.http.ResponseEntity<Map<String,Object>> mineBlock()
      Triggers a manual block mining cycle, selecting up to 100 transactions from the mempool and appending the resulting block to the chain.

      Returns HTTP 204 NO_CONTENT if the mempool is empty (no block produced). Returns HTTP 200 with block metadata on success.

      This endpoint exists for demo convenience — in a real node, mining runs in a background thread or is triggered by a dedicated mining service.

      Returns:
      HTTP 200 with block index, hash, and tx count on success; HTTP 204 if the mempool is empty; HTTP 500 if consensus or validation fails