feat(rpc): add invalidateblock and submitheader RPCs

Add two new JSON-RPC methods:

- invalidateblock: marks a block and all descendants as invalid,
  rolling back the chain tip to the parent block.
- submitheader: decodes a hex-encoded 80-byte block header and
  submits it as a candidate chain tip via accept_header.

Also:
* Added RPC helpers in the Python test framework (floresta.py)
* Functional tests for both RPCs (invalidateblock.py, submitheader.py)

Author: jaoleal

crates/floresta-node/src/json_rpc/blockchain.rs

@@ -2,6 +2,7 @@ use bitcoin::block::Header;
 use bitcoin::consensus::encode::serialize_hex;
 use bitcoin::consensus::Encodable;
 use bitcoin::constants::genesis_block;
+use bitcoin::hashes::hex::FromHex;
 use bitcoin::hashes::Hash;
 use bitcoin::Address;
 use bitcoin::Block;
@@ -310,6 +311,26 @@ impl<Blockchain: RpcChain> RpcImpl<Blockchain> {
     // getchainstates
     // getchaintips
     // getchaintxstats
+
+    // invalidateblock
+    pub(super) fn invalidate_block(&self, hash: BlockHash) -> Result<(), JsonRpcError> {
+        self.chain
+            .invalidate_block(hash)
+            .map_err(|_| JsonRpcError::BlockNotFound)
+    }
+
+    // submitheader
+    pub(super) fn submit_header(&self, hex: String) -> Result<(), JsonRpcError> {
+        let bytes = Vec::from_hex(&hex).map_err(|_| JsonRpcError::InvalidHex)?;
+
+        let header: Header = bitcoin::consensus::deserialize(&bytes)
+            .map_err(|e| JsonRpcError::Decode(e.to_string()))?;
+
+        self.chain
+            .accept_header(header)
+            .map_err(|_| JsonRpcError::Chain)
+    }
+
     // getdeploymentinfo
     // getdifficulty
     // getmempoolancestors

crates/floresta-node/src/json_rpc/server.rs

@@ -313,6 +313,18 @@ async fn handle_json_rpc_request(
 
         "getroots" => state.get_roots().map(|v| serde_json::to_value(v).unwrap()),
 
+        "invalidateblock" => {
+            let hash = get_hash(&params, 0, "blockhash")?;
+            state.invalidate_block(hash)?;
+            Ok(Value::Null)
+        }
+
+        "submitheader" => {
+            let hex = get_string(&params, 0, "hexdata")?;
+            state.submit_header(hex)?;
+            Ok(Value::Null)
+        }
+
         "findtxout" => {
             let txid = get_hash(&params, 0, "txid")?;
             let vout = get_numeric(&params, 1, "vout")?;

tests/floresta-cli/invalidateblock.py

@@ -0,0 +1,68 @@
+"""
+invalidateblock.py
+
+Test the `invalidateblock` RPC on florestad.
+
+We mine blocks via utreexod, sync them to florestad, then call `invalidateblock`
+on florestad to mark a block as invalid. We verify that florestad's tip rolls back
+to the parent of the invalidated block.
+"""
+
+import time
+
+from test_framework import FlorestaTestFramework
+from test_framework.node import NodeType
+
+
+class InvalidateBlockTest(FlorestaTestFramework):
+    """Test that invalidateblock marks a block invalid and rolls back the tip."""
+
+    def set_test_params(self):
+        self.florestad = self.add_node_default_args(variant=NodeType.FLORESTAD)
+        self.utreexod = self.add_node_extra_args(
+            variant=NodeType.UTREEXOD,
+            extra_args=[
+                "--miningaddr=bcrt1q4gfcga7jfjmm02zpvrh4ttc5k7lmnq2re52z2y",
+                "--utreexoproofindex",
+                "--prune=0",
+            ],
+        )
+
+    def run_test(self):
+        self.run_node(self.florestad)
+        self.run_node(self.utreexod)
+
+        # Mine 10 blocks on utreexod and sync to florestad
+        self.log("=== Mining 10 blocks with utreexod")
+        self.utreexod.rpc.generate(10)
+
+        self.log("=== Connecting florestad to utreexod")
+        self.connect_nodes(self.florestad, self.utreexod)
+
+        self.log("=== Waiting for sync")
+        time.sleep(20)
+
+        # Verify both nodes are synced
+        floresta_info = self.florestad.rpc.get_blockchain_info()
+        utreexo_info = self.utreexod.rpc.get_blockchain_info()
+        self.assertEqual(floresta_info["height"], utreexo_info["blocks"])
+        self.assertEqual(floresta_info["best_block"], utreexo_info["bestblockhash"])
+
+        # Get the hash of block 5 and its parent (block 4)
+        hash_at_5 = self.florestad.rpc.get_blockhash(5)
+        hash_at_4 = self.florestad.rpc.get_blockhash(4)
+
+        # Invalidate block 5 on florestad
+        self.log(f"=== Invalidating block at height 5: {hash_at_5}")
+        self.florestad.rpc.invalidate_block(hash_at_5)
+
+        # Verify florestad's tip rolled back to block 4
+        new_info = self.florestad.rpc.get_blockchain_info()
+        self.assertEqual(new_info["height"], 4)
+        self.assertEqual(new_info["best_block"], hash_at_4)
+
+        self.log("=== invalidateblock test passed")
+
+
+if __name__ == "__main__":
+    InvalidateBlockTest().main()

tests/floresta-cli/submitheader.py

@@ -0,0 +1,62 @@
+"""
+submitheader.py
+
+Test the `submitheader` RPC on florestad.
+
+We mine a block on utreexod to obtain a valid header, then shut it down.
+We start florestad in isolation and submit the header via `submitheader`.
+Florestad should accept the header and advance its tip to height 1.
+"""
+
+from test_framework import FlorestaTestFramework
+from test_framework.node import NodeType
+
+
+class SubmitHeaderTest(FlorestaTestFramework):
+    """Test that submitheader accepts a valid block header."""
+
+    def set_test_params(self):
+        self.florestad = self.add_node_default_args(variant=NodeType.FLORESTAD)
+        self.utreexod = self.add_node_extra_args(
+            variant=NodeType.UTREEXOD,
+            extra_args=[
+                "--miningaddr=bcrt1q4gfcga7jfjmm02zpvrh4ttc5k7lmnq2re52z2y",
+                "--prune=0",
+            ],
+        )
+
+    def run_test(self):
+        # Start utreexod, mine 1 block, grab its header
+        self.run_node(self.utreexod)
+
+        self.log("=== Mining 1 block with utreexod")
+        self.utreexod.rpc.generate(1)
+
+        block_hash = self.utreexod.rpc.get_blockhash(1)
+        raw_block_hex = self.utreexod.rpc.get_block(block_hash, 0)
+
+        # First 160 hex chars = 80-byte block header
+        header_hex = raw_block_hex[:160]
+
+        self.log("=== Stopping utreexod")
+        self.utreexod.stop()
+
+        # Start florestad in isolation and submit the header
+        self.run_node(self.florestad)
+
+        info_before = self.florestad.rpc.get_blockchain_info()
+        self.assertEqual(info_before["height"], 0)
+
+        self.log(f"=== Submitting header for block {block_hash}")
+        self.florestad.rpc.submit_header(header_hex)
+
+        # Verify florestad accepted the header and advanced to height 1
+        info_after = self.florestad.rpc.get_blockchain_info()
+        self.assertEqual(info_after["height"], 1)
+        self.assertEqual(info_after["best_block"], block_hash)
+
+        self.log("=== submitheader test passed")
+
+
+if __name__ == "__main__":
+    SubmitHeaderTest().main()

tests/test_framework/rpc/floresta.py

@@ -24,6 +24,14 @@ def get_roots(self):
         """
         return self.perform_request("getroots")
 
+    def invalidate_block(self, blockhash: str):
+        """Marks a block as invalid"""
+        return self.perform_request("invalidateblock", params=[blockhash])
+
+    def submit_header(self, hexdata: str):
+        """Submits a raw block header as a candidate chain tip"""
+        return self.perform_request("submitheader", params=[hexdata])
+
     def get_memoryinfo(self, mode: str):
         """
         Returns stats about our memory usage performing

tests/test_runner.py

@@ -22,8 +22,8 @@
 import os
 import subprocess
 from collections import defaultdict
-from threading import Thread
 from queue import Queue
+from threading import Thread
 from time import time
 
 from test_framework.util import Utility
@@ -71,6 +71,8 @@
     ("example", "bitcoin"),
     ("example", "utreexod"),
     ("florestad", "node-info"),
+    ("floresta-cli", "invalidateblock"),
+    ("floresta-cli", "submitheader"),
 ]
 
 # Before running the tests, we check if the number of tests
@@ -206,7 +208,6 @@ def run_test_worker(task_queue: Queue, results_queue: Queue, args: argparse.Name
         with open(
             test_log_name, "wt", encoding="utf-8", buffering=args.log_buffer
         ) as log_file:
-
             # Avoid using 'with' for `subprocess.Popen` here, as we need the
             # process to start and stream output immediately for port detection
             # to work correctly. Using 'with' might delay output flushing,