[kyoto-hardening] resolve chain checkpoint from start_height

Kyoto seeds its header / compact-filter sync from a HeaderCheckpoint.
We had two hard-coded mainnet activation checkpoints and a genesis
fallback for everything else, so signet / testnet pods re-walked ~300k
headers on every rebuild. Combined with the supervisor restart loop,
that meant each Kyoto bounce cost several minutes of catch-up before
deposits could be confirmed again.

Resolve the checkpoint once at monitor startup: keep the mainnet
activation fast-path, otherwise call bitcoind getblockhash(start_height)
and use that as the checkpoint. Store the result on the Monitor so the
supervision loop reuses it across rebuilds without re-RPC.

Author: 0xsiddharthks

crates/hashi/src/btc_monitor/monitor.rs

@@ -5,6 +5,7 @@ use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;
 
+use anyhow::Context;
 use anyhow::Result;
 use kyoto::FeeRate;
 use kyoto::HeaderCheckpoint;
@@ -92,6 +93,10 @@ pub struct Monitor {
     bitcoind_rpc: Arc<corepc_client::client_sync::v29::Client>,
     client_tx: tokio::sync::mpsc::Sender<MonitorMessage>,
     requester: kyoto::Requester,
+    /// Starting point for Kyoto's header / compact-filter sync. Resolved
+    /// once at startup and reused on every rebuild so Kyoto resumes from
+    /// `start_height` rather than re-walking from genesis after a restart.
+    chain_checkpoint: HeaderCheckpoint,
     tip: Option<HeaderCheckpoint>,
     block_height_tx: tokio::sync::watch::Sender<u32>,
     pending_deposits: Vec<PendingDeposit>,
@@ -113,17 +118,10 @@ where
 }
 
 impl Monitor {
-    fn build_kyoto_node(config: &MonitorConfig) -> (kyoto::Node, kyoto::Client) {
-        let checkpoint = match config.network {
-            bitcoin::Network::Bitcoin if config.start_height > 709_631 => {
-                kyoto::HeaderCheckpoint::taproot_activation()
-            }
-            bitcoin::Network::Bitcoin if config.start_height > 481_823 => {
-                kyoto::HeaderCheckpoint::segwit_activation()
-            }
-            network => kyoto::HeaderCheckpoint::from_genesis(network),
-        };
-
+    fn build_kyoto_node(
+        config: &MonitorConfig,
+        checkpoint: HeaderCheckpoint,
+    ) -> (kyoto::Node, kyoto::Client) {
         let mut builder = kyoto::Builder::new(config.network)
             .add_peers(config.trusted_peers.iter().cloned())
             // Only connect to the configured trusted peers. Prevents Kyoto from
@@ -140,6 +138,61 @@ impl Monitor {
         builder.build()
     }
 
+    /// Pick a chain-state checkpoint without contacting bitcoind. Returns
+    /// `None` when the caller needs to resolve a hash via RPC (i.e.
+    /// non-mainnet with a non-zero `start_height`).
+    fn builtin_checkpoint(
+        network: bitcoin::Network,
+        start_height: u32,
+    ) -> Option<HeaderCheckpoint> {
+        // Mainnet ships with two well-known activation checkpoints baked into
+        // Kyoto. Prefer them when applicable — they avoid an RPC roundtrip
+        // and match the network's deployment schedule.
+        if network == bitcoin::Network::Bitcoin {
+            if start_height > 709_631 {
+                return Some(HeaderCheckpoint::taproot_activation());
+            }
+            if start_height > 481_823 {
+                return Some(HeaderCheckpoint::segwit_activation());
+            }
+        }
+        if start_height == 0 {
+            return Some(HeaderCheckpoint::from_genesis(network));
+        }
+        None
+    }
+
+    /// Resolve the Kyoto chain-state checkpoint for this configuration.
+    ///
+    /// On mainnet, prefers the built-in activation checkpoints. On other
+    /// networks, falls through to a bitcoind `getblockhash(start_height)`
+    /// RPC so Kyoto can resume from `start_height` instead of re-walking
+    /// every header from genesis on each rebuild.
+    async fn resolve_chain_checkpoint(
+        bitcoind_rpc: &Arc<corepc_client::client_sync::v29::Client>,
+        network: bitcoin::Network,
+        start_height: u32,
+    ) -> Result<HeaderCheckpoint> {
+        if let Some(checkpoint) = Self::builtin_checkpoint(network, start_height) {
+            return Ok(checkpoint);
+        }
+
+        let block_hash = btc_rpc_call(bitcoind_rpc, move |rpc| {
+            rpc.get_block_hash(start_height as u64)
+        })
+        .await
+        .with_context(|| format!("bitcoind getblockhash({start_height}) failed"))?
+        .block_hash()
+        .with_context(|| format!("parsing block hash at height {start_height}"))?;
+
+        info!(
+            height = start_height,
+            hash = %block_hash,
+            "Resolved Kyoto chain-state checkpoint from bitcoind",
+        );
+        Ok(HeaderCheckpoint::new(start_height, block_hash))
+    }
+
     /// Run a BTC monitor with the given configuration.
     /// Returns the client for interacting with the monitor and a Service for lifecycle management.
     pub fn run(config: MonitorConfig, metrics: Arc<Metrics>) -> Result<(MonitorClient, Service)> {
@@ -156,14 +209,24 @@ impl Monitor {
             async move {
                 let bitcoind_rpc = Arc::new(bitcoind_rpc);
 
-                // Build initial Kyoto node.
-                let (kyoto_node, kyoto_client) = Self::build_kyoto_node(&config);
+                // Resolve the chain-state checkpoint once. The supervision
+                // loop reuses it on every Kyoto rebuild, so the RPC roundtrip
+                // is amortized across the lifetime of the monitor.
+                let chain_checkpoint = Self::resolve_chain_checkpoint(
+                    &bitcoind_rpc,
+                    config.network,
+                    config.start_height,
+                )
+                .await?;
+
+                let (kyoto_node, kyoto_client) = Self::build_kyoto_node(&config, chain_checkpoint);
 
                 let mut monitor = Monitor {
                     config,
                     metrics,
                     bitcoind_rpc,
                     requester: kyoto_client.requester.clone(),
+                    chain_checkpoint,
                     client_tx,
                     tip: None,
                     block_height_tx,
@@ -251,7 +314,8 @@ impl Monitor {
             debug!("Sleeping {delay:?} before rebuilding Kyoto");
             tokio::time::sleep(delay).await;
 
-            let (new_node, new_client) = Self::build_kyoto_node(&self.config);
+            let (new_node, new_client) =
+                Self::build_kyoto_node(&self.config, self.chain_checkpoint);
             current_node = new_node;
             current_client = new_client;
             self.requester = current_client.requester.clone();
@@ -1264,4 +1328,58 @@ mod tests {
             assert!(d <= max, "{d:?} > base + jitter");
         }
     }
+
+    #[test]
+    fn mainnet_above_taproot_uses_taproot_activation() {
+        let cp = Monitor::builtin_checkpoint(bitcoin::Network::Bitcoin, 800_000).unwrap();
+        assert_eq!(cp, HeaderCheckpoint::taproot_activation());
+    }
+
+    #[test]
+    fn mainnet_above_segwit_below_taproot_uses_segwit_activation() {
+        let cp = Monitor::builtin_checkpoint(bitcoin::Network::Bitcoin, 600_000).unwrap();
+        assert_eq!(cp, HeaderCheckpoint::segwit_activation());
+    }
+
+    #[test]
+    fn zero_height_uses_genesis_for_any_network() {
+        for net in [
+            bitcoin::Network::Bitcoin,
+            bitcoin::Network::Signet,
+            bitcoin::Network::Testnet4,
+            bitcoin::Network::Regtest,
+        ] {
+            let cp = Monitor::builtin_checkpoint(net, 0).unwrap();
+            assert_eq!(cp, HeaderCheckpoint::from_genesis(net));
+        }
+    }
+
+    #[test]
+    fn non_mainnet_nonzero_height_requires_rpc() {
+        // For signet / testnet / regtest with a real start_height, the
+        // caller must resolve the hash via bitcoind RPC — no built-in
+        // checkpoint applies.
+        for net in [
+            bitcoin::Network::Signet,
+            bitcoin::Network::Testnet4,
+            bitcoin::Network::Regtest,
+        ] {
+            assert_eq!(Monitor::builtin_checkpoint(net, 297_756), None);
+        }
+    }
+
+    #[test]
+    fn mainnet_below_segwit_uses_genesis_when_zero_otherwise_rpc() {
+        // Pre-segwit mainnet with start_height == 0 → genesis.
+        let cp = Monitor::builtin_checkpoint(bitcoin::Network::Bitcoin, 0).unwrap();
+        assert_eq!(
+            cp,
+            HeaderCheckpoint::from_genesis(bitcoin::Network::Bitcoin)
+        );
+        // Pre-segwit mainnet with a non-zero start_height → no built-in.
+        assert_eq!(
+            Monitor::builtin_checkpoint(bitcoin::Network::Bitcoin, 400_000),
+            None
+        );
+    }
 }