feat(coprocessor): add --seed-start-block flag to host-listener poller (backport 0.13.x) (#3124)

feat(coprocessor): add --seed-start-block flag to host-listener poller

Without a persisted anchor the poller used to seed its cursor from
host_chain_blocks_valid, a table owned by the WS listener. That
cross-service read was a bootstrap aid from when the poller was first
introduced into already-running systems; on a fresh database it is a
startup race: if the poller initializes before the WS listener has
written anything, it anchors at 0 and walks the chain from genesis
(observed on Amoy pollers on devnet/testnet, ~2-3 months behind head).

Drop the cross-service read entirely. The poller's seed sources are now
its own: the persisted anchor row always wins; otherwise
--seed-start-block seeds deterministically (non-negative = absolute
height, 0 = genesis explicitly, negative = that many blocks behind
head); otherwise the poller exits with an explicit error, so a missing
flag on a new chain surfaces as a crash-loop at deploy time instead of
a silent weeks-long genesis walk.

The flag is deliberately initialization-only, not the listener's
--start-at-block semantics (where the flag beats persisted state on
every startup): once the anchor row exists the flag is inert, so a flag
left in Helm values can never rewind the poller on restart, skip blocks
past the anchor, or clobber a drift-revert anchor reset. Deliberate
rewinds remain a manual host_listener_poller_state update.

Adding a poller to an already-running listener-only deployment now
requires setting --seed-start-block explicitly (the removed fallback
previously covered that case). The e2e compose poller passes
--seed-start-block=0: fresh local chain, genesis is the honest value.

Author: Eikix

coprocessor/fhevm-engine/host-listener/src/bin/poller.rs

@@ -40,6 +40,14 @@ struct Args {
     #[arg(long, help = "PostgreSQL connection URL")]
     database_url: DatabaseURL,
 
+    #[arg(
+        long,
+        default_value = None,
+        help = "Initial sync block used only when no poller state exists yet; an existing anchor always wins (can be negative from last block)",
+        allow_hyphen_values = true
+    )]
+    seed_start_block: Option<i64>,
+
     #[arg(
         long,
         default_value_t = 15,
@@ -180,6 +188,7 @@ async fn main() -> anyhow::Result<()> {
         max_http_retries: args.max_http_retries,
         rpc_compute_units_per_second: args.rpc_compute_units_per_second,
         health_port: args.health_port,
+        seed_start_block: args.seed_start_block,
         dependence_cache_size: args.dependence_cache_size,
         dependence_by_connexity: args.dependence_by_connexity,
         dependence_cross_block: args.dependence_cross_block,

coprocessor/fhevm-engine/host-listener/src/poller/mod.rs

@@ -70,6 +70,58 @@ fn handle_rpc_failure<E: std::fmt::Display>(
     }
 }
 
+/// Seed for `host_listener_poller_state` when no anchor row exists yet; an
+/// existing row always wins in the caller, so restarts never rewind or skip.
+/// A non-negative value is an absolute height (0 = genesis, explicitly), a
+/// negative value means that many blocks behind the current head. Unset is an
+/// error: the first start for a chain must state where to begin.
+#[derive(Debug, PartialEq, Eq)]
+enum StartAnchor {
+    Block(i64),
+    BehindHead(u64),
+}
+
+fn resolve_start_anchor(seed_start_block: Option<i64>) -> Result<StartAnchor> {
+    match seed_start_block {
+        Some(block) if block >= 0 => Ok(StartAnchor::Block(block)),
+        Some(delta) => Ok(StartAnchor::BehindHead(delta.unsigned_abs())),
+        None => Err(anyhow!(
+            "no poller state for this chain and no --seed-start-block; \
+             set it explicitly (0 for genesis)"
+        )),
+    }
+}
+
+#[cfg(test)]
+mod start_anchor_tests {
+    use super::{resolve_start_anchor, StartAnchor};
+
+    #[test]
+    fn non_negative_flag_is_absolute() {
+        assert_eq!(
+            resolve_start_anchor(Some(7)).unwrap(),
+            StartAnchor::Block(7)
+        );
+        assert_eq!(
+            resolve_start_anchor(Some(0)).unwrap(),
+            StartAnchor::Block(0)
+        );
+    }
+
+    #[test]
+    fn negative_flag_is_behind_head() {
+        assert_eq!(
+            resolve_start_anchor(Some(-10_000)).unwrap(),
+            StartAnchor::BehindHead(10_000)
+        );
+    }
+
+    #[test]
+    fn no_flag_is_an_error() {
+        assert!(resolve_start_anchor(None).is_err());
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct PollerConfig {
     pub url: String,
@@ -88,6 +140,9 @@ pub struct PollerConfig {
     /// Higher values = less throttling.
     pub rpc_compute_units_per_second: u64,
     pub health_port: u16,
+    /// Initial sync anchor when no poller state exists yet
+    /// (initialization-only; >= 0 absolute, negative from head).
+    pub seed_start_block: Option<i64>,
     // Dependence chain settings
     pub dependence_cache_size: u16,
     pub dependence_by_connexity: bool,
@@ -195,7 +250,17 @@ pub async fn run_poller(config: PollerConfig) -> Result<()> {
         Some(block) => u64::try_from(block)
             .context("last_caught_up_block cannot be negative")?,
         None => {
-            let initial = db.read_last_valid_block().await.unwrap_or(0);
+            let initial = match resolve_start_anchor(config.seed_start_block)? {
+                StartAnchor::Block(block) => block,
+                StartAnchor::BehindHead(delta) => {
+                    let head = client.latest_block_number().await.context(
+                        "Failed to fetch head to resolve negative seed-start-block",
+                    )?;
+                    i64::try_from(head.saturating_sub(delta)).context(
+                        "start block computed from head is out of range",
+                    )?
+                }
+            };
             db.poller_set_last_caught_up_block(chain_id, initial)
                 .await?;
             db.tick.update();

coprocessor/fhevm-engine/host-listener/tests/poller_integration_tests.rs

@@ -182,6 +182,7 @@ async fn poller_catches_up_to_safe_tip(
         max_http_retries: 0,
         rpc_compute_units_per_second: 1000,
         health_port: 18081,
+        seed_start_block: Some(0),
         dependence_cache_size: 10_000,
         dependence_by_connexity: false,
         dependence_cross_block: false,

test-suite/fhevm/docker-compose/coprocessor-docker-compose.yml

@@ -55,6 +55,7 @@ services:
     command:
       - host_listener_poller
       - --database-url=${DATABASE_URL}
+      - --seed-start-block=0
       - --acl-contract-address=${ACL_CONTRACT_ADDRESS}
       - --tfhe-contract-address=${FHEVM_EXECUTOR_CONTRACT_ADDRESS}
       - --kms-generation-address=${KMS_GENERATION_ADDRESS}