From ef0b1233556800c782b2b29c820ecb240d46a863 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 27 Oct 2026 11:19:39 +0800 Subject: [PATCH 1/5] =?UTF-8?q?core:=20the=20chain=20pin=20and=20the=20sit?= =?UTF-8?q?e-sync=20classifier=20=E2=80=94=20ChainPin=20(default=20chain?= =?UTF-8?q?=2021=20/=20ca76c276=E2=80=A6,=20RANDSCAN=5FEXPECTED=5FCHAIN=5F?= =?UTF-8?q?ID=20/=20RANDSCAN=5FEXPECTED=5FGENESIS),=20ChainView,=20classif?= =?UTF-8?q?y()=20into=20unreachable=20/=20wrong=5Fchain=20/=20stalled=20/?= =?UTF-8?q?=20behind=20/=20live=20with=20STALL=5FMS=2060=20000=20and=20MAX?= =?UTF-8?q?=5FLAG=2010,=20unit=20tests=20on=20every=20boundary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- crates/randscan-core/src/types/chain.rs | 379 ++++++++++++++++++++++++ crates/randscan-core/src/types/mod.rs | 2 + 2 files changed, 381 insertions(+) create mode 100644 crates/randscan-core/src/types/chain.rs diff --git a/crates/randscan-core/src/types/chain.rs b/crates/randscan-core/src/types/chain.rs new file mode 100644 index 0000000..aefe544 --- /dev/null +++ b/crates/randscan-core/src/types/chain.rs @@ -0,0 +1,379 @@ +//! Chain identity and the "is this site on the live chain and up to date" check +//! (`docs/superpowers/specs/2026-10-27-site-sync-design.md` in the monorepo, §1–§3). +//! +//! A chain is identified by its id *and* its genesis hash: this project cuts chains often enough +//! that an id alone has been reused by a misconfigured node. Every site pins the chain it expects +//! ([`ChainPin`]), derives a [`ChainView`] of what it is showing, and classifies the pair with the +//! same rules ([`classify`]), so randscan.org, zusd.money, randbridge.org and randprotocol.org +//! agree on what "live", "behind", "stalled" and "wrong chain" mean. + +use serde::{Deserialize, Serialize}; + +/// A head older than this is stalled: 24 blocks at the chain's 2.5 s block time. +pub const STALL_MS: i64 = 60_000; + +/// An indexer more than this many blocks behind its node is behind. +pub const MAX_LAG: i64 = 10; + +/// The chain a deployment expects when nothing configures another: chain 21, cut 2026-10-12. +/// Every pin moves at a chain cut; the monorepo's site-sync cron fails while one is left behind. +pub const DEFAULT_EXPECTED_CHAIN_ID: i64 = 21; +pub const DEFAULT_EXPECTED_GENESIS: &str = + "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a"; + +/// Lowercase hex without a `0x` prefix, so two spellings of one hash compare equal. +pub fn normalize_hash(h: &str) -> String { + let h = h.trim(); + h.strip_prefix("0x") + .or_else(|| h.strip_prefix("0X")) + .unwrap_or(h) + .to_ascii_lowercase() +} + +/// Whether two hex hashes are the same hash, ignoring case and a `0x` prefix. +pub fn same_hash(a: &str, b: &str) -> bool { + normalize_hash(a) == normalize_hash(b) +} + +/// The chain a deployment expects to be showing. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ChainPin { + pub chain_id: i64, + pub genesis_hash: String, +} + +impl Default for ChainPin { + fn default() -> Self { + Self { + chain_id: DEFAULT_EXPECTED_CHAIN_ID, + genesis_hash: DEFAULT_EXPECTED_GENESIS.to_string(), + } + } +} + +impl ChainPin { + pub fn new(chain_id: i64, genesis_hash: &str) -> Self { + Self { + chain_id, + genesis_hash: normalize_hash(genesis_hash), + } + } + + /// `RANDSCAN_EXPECTED_CHAIN_ID` and `RANDSCAN_EXPECTED_GENESIS`, each falling back to the + /// default pin when unset, empty or unparsable. + pub fn from_env() -> Self { + let d = Self::default(); + let chain_id = std::env::var("RANDSCAN_EXPECTED_CHAIN_ID") + .ok() + .and_then(|v| v.trim().parse().ok()) + .unwrap_or(d.chain_id); + let genesis_hash = std::env::var("RANDSCAN_EXPECTED_GENESIS") + .ok() + .map(|v| normalize_hash(&v)) + .filter(|v| !v.is_empty()) + .unwrap_or(d.genesis_hash); + Self { + chain_id, + genesis_hash, + } + } + + /// Whether `(chain_id, genesis_hash)` is the pinned chain. + pub fn matches(&self, chain_id: i64, genesis_hash: &str) -> bool { + self.chain_id == chain_id && same_hash(&self.genesis_hash, genesis_hash) + } +} + +/// What a site is showing (§2). `genesis_hash` and `head_*` describe the data the site serves; +/// `node_*` and `lag` describe the node it reads through, when there is one in between (here the +/// indexer). The node's own chain id and genesis are randscan's addition: they differ from the +/// stored ones exactly when the indexer has stopped writing because the node changed chains. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ChainView { + pub chain_id: i64, + pub genesis_hash: Option, + pub head_height: i64, + pub head_timestamp_ms: Option, + #[serde(default)] + pub node_height: Option, + #[serde(default)] + pub lag: Option, + #[serde(default)] + pub node_chain_id: Option, + #[serde(default)] + pub node_genesis_hash: Option, +} + +/// The classifier's verdict, worst first. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ChainState { + Unreachable, + WrongChain, + Stalled, + Behind, + Live, +} + +impl ChainState { + pub fn as_str(&self) -> &'static str { + match self { + ChainState::Unreachable => "unreachable", + ChainState::WrongChain => "wrong_chain", + ChainState::Stalled => "stalled", + ChainState::Behind => "behind", + ChainState::Live => "live", + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Classification { + pub state: ChainState, + /// One English sentence naming what is wrong (or that nothing is). + pub detail: String, +} + +/// Whether the view is not the pinned chain: a different chain id, a missing or different +/// genesis, or a node (behind an indexer) that reports a different chain than the pin. +pub fn is_wrong_chain(view: &ChainView, expected: &ChainPin) -> bool { + let stored = view.chain_id == expected.chain_id + && view + .genesis_hash + .as_deref() + .is_some_and(|g| same_hash(g, &expected.genesis_hash)); + let node_ok = view.node_chain_id.is_none_or(|c| c == expected.chain_id) + && view + .node_genesis_hash + .as_deref() + .is_none_or(|g| same_hash(g, &expected.genesis_hash)); + !(stored && node_ok) +} + +/// Whether the head is older than [`STALL_MS`] at `now_ms`, or has no timestamp at all. +pub fn is_stalled(view: &ChainView, now_ms: i64) -> bool { + match view.head_timestamp_ms { + Some(ts) => now_ms - ts > STALL_MS, + None => true, + } +} + +fn short(h: &str) -> String { + let h = normalize_hash(h); + if h.len() > 8 { + format!("{}…", &h[..8]) + } else { + h + } +} + +/// §3: `None` is a source that could not be read (fetch failed, timed out, did not parse). +/// Checked in order: unreachable, wrong chain, stalled, behind, live. +pub fn classify(view: Option<&ChainView>, expected: &ChainPin, now_ms: i64) -> Classification { + let Some(v) = view else { + return Classification { + state: ChainState::Unreachable, + detail: "The chain source could not be reached.".into(), + }; + }; + if is_wrong_chain(v, expected) { + let shown = match &v.genesis_hash { + Some(g) => format!("chain {} (genesis {})", v.chain_id, short(g)), + None => format!("chain {} (no genesis hash)", v.chain_id), + }; + let mut detail = format!( + "Showing {shown}; expected chain {} (genesis {}).", + expected.chain_id, + short(&expected.genesis_hash) + ); + if let (Some(c), Some(g)) = (v.node_chain_id, v.node_genesis_hash.as_deref()) { + let differs = + c != v.chain_id || v.genesis_hash.as_deref().is_none_or(|s| !same_hash(s, g)); + if differs { + detail = format!( + "{} The node now serves chain {c} (genesis {}); indexing stopped.", + detail, + short(g) + ); + } + } + return Classification { + state: ChainState::WrongChain, + detail, + }; + } + if is_stalled(v, now_ms) { + let detail = match v.head_timestamp_ms { + Some(ts) => format!( + "No new block for {} s since #{}.", + (now_ms - ts) / 1000, + v.head_height + ), + None => "No block has been indexed yet.".into(), + }; + return Classification { + state: ChainState::Stalled, + detail, + }; + } + if let Some(lag) = v.lag.filter(|l| *l > MAX_LAG) { + return Classification { + state: ChainState::Behind, + detail: format!("{lag} blocks behind the node, at #{}.", v.head_height), + }; + } + Classification { + state: ChainState::Live, + detail: format!("Live at #{}.", v.head_height), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const G: &str = DEFAULT_EXPECTED_GENESIS; + const NOW: i64 = 1_800_000_000_000; + + fn pin() -> ChainPin { + ChainPin::default() + } + + fn live_view() -> ChainView { + ChainView { + chain_id: 21, + genesis_hash: Some(G.into()), + head_height: 495_700, + head_timestamp_ms: Some(NOW - 2_500), + node_height: Some(495_700), + lag: Some(0), + node_chain_id: Some(21), + node_genesis_hash: Some(G.into()), + } + } + + fn state(v: Option<&ChainView>) -> ChainState { + classify(v, &pin(), NOW).state + } + + #[test] + fn a_fetch_error_is_unreachable() { + assert_eq!(state(None), ChainState::Unreachable); + } + + #[test] + fn a_fresh_head_on_the_pinned_chain_is_live() { + let c = classify(Some(&live_view()), &pin(), NOW); + assert_eq!(c.state, ChainState::Live); + assert_eq!(c.detail, "Live at #495700."); + } + + #[test] + fn the_stall_boundary_is_sixty_seconds_inclusive() { + let mut v = live_view(); + v.head_timestamp_ms = Some(NOW - 60_000); + assert_eq!( + state(Some(&v)), + ChainState::Live, + "exactly 60 000 ms is fresh" + ); + v.head_timestamp_ms = Some(NOW - 60_001); + assert_eq!(state(Some(&v)), ChainState::Stalled, "60 001 ms is stalled"); + } + + #[test] + fn a_missing_head_timestamp_is_stalled() { + let mut v = live_view(); + v.head_timestamp_ms = None; + let c = classify(Some(&v), &pin(), NOW); + assert_eq!(c.state, ChainState::Stalled); + assert_eq!(c.detail, "No block has been indexed yet."); + } + + #[test] + fn the_lag_boundary_is_ten_blocks_inclusive() { + let mut v = live_view(); + v.lag = Some(10); + assert_eq!(state(Some(&v)), ChainState::Live); + v.lag = Some(11); + assert_eq!(state(Some(&v)), ChainState::Behind); + v.lag = None; + assert_eq!(state(Some(&v)), ChainState::Live, "no indexer, no lag"); + } + + #[test] + fn a_missing_genesis_is_the_wrong_chain() { + let mut v = live_view(); + v.genesis_hash = None; + assert_eq!(state(Some(&v)), ChainState::WrongChain); + } + + #[test] + fn a_different_genesis_is_the_wrong_chain() { + let mut v = live_view(); + v.genesis_hash = Some("ab".repeat(32)); + assert_eq!(state(Some(&v)), ChainState::WrongChain); + } + + #[test] + fn a_chain_id_mismatch_with_a_matching_genesis_is_the_wrong_chain() { + let mut v = live_view(); + v.chain_id = 20; + assert_eq!(state(Some(&v)), ChainState::WrongChain); + } + + #[test] + fn a_node_that_changed_chains_under_the_indexer_is_the_wrong_chain() { + let mut v = live_view(); + v.node_genesis_hash = Some("cd".repeat(32)); + let c = classify(Some(&v), &pin(), NOW); + assert_eq!(c.state, ChainState::WrongChain); + assert!(c.detail.contains("indexing stopped"), "{}", c.detail); + let mut v = live_view(); + v.node_chain_id = Some(22); + assert_eq!(state(Some(&v)), ChainState::WrongChain); + } + + #[test] + fn hashes_compare_without_case_or_prefix() { + let mut v = live_view(); + v.genesis_hash = Some(format!("0x{}", G.to_ascii_uppercase())); + assert_eq!(state(Some(&v)), ChainState::Live); + assert!(ChainPin::new(21, &format!("0X{G}")).matches(21, G)); + } + + #[test] + fn the_order_is_wrong_chain_then_stalled_then_behind() { + let mut v = live_view(); + v.lag = Some(50); + v.head_timestamp_ms = Some(NOW - 600_000); + assert_eq!(state(Some(&v)), ChainState::Stalled, "stalled beats behind"); + v.chain_id = 20; + assert_eq!( + state(Some(&v)), + ChainState::WrongChain, + "wrong chain beats stalled" + ); + } + + #[test] + fn the_states_serialize_as_the_spec_spells_them() { + for (s, name) in [ + (ChainState::Unreachable, "unreachable"), + (ChainState::WrongChain, "wrong_chain"), + (ChainState::Stalled, "stalled"), + (ChainState::Behind, "behind"), + (ChainState::Live, "live"), + ] { + assert_eq!(serde_json::to_value(s).unwrap(), name); + assert_eq!(s.as_str(), name); + } + } + + #[test] + fn the_default_pin_is_chain_21() { + let p = ChainPin::default(); + assert_eq!(p.chain_id, 21); + assert_eq!(p.genesis_hash, G); + } +} diff --git a/crates/randscan-core/src/types/mod.rs b/crates/randscan-core/src/types/mod.rs index 21ce797..4b9f58f 100644 --- a/crates/randscan-core/src/types/mod.rs +++ b/crates/randscan-core/src/types/mod.rs @@ -5,6 +5,7 @@ mod auth; mod block; mod bridge; mod bridge_tokens; +mod chain; mod node; mod note; mod program; @@ -20,6 +21,7 @@ pub use auth::*; pub use block::*; pub use bridge::*; pub use bridge_tokens::*; +pub use chain::*; pub use node::*; pub use note::*; pub use program::*; From 5a4c7d4a5366c653b435eee52bb0cba65e9244c6 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 27 Oct 2026 11:19:39 +0800 Subject: [PATCH 2/5] =?UTF-8?q?indexer,=20api:=20the=20database=20belongs?= =?UTF-8?q?=20to=20one=20chain=20=E2=80=94=20migration=20015=20chain=5Fmet?= =?UTF-8?q?a=20(adopts=20the=20indexed=20chain's=20id=20and=20block-0=20ha?= =?UTF-8?q?sh,=20so=20the=20live=20chain-21=20database=20carries=20on),=20?= =?UTF-8?q?the=20indexer=20checks=20rand=5FchainId=20+=20rand=5FgetGenesis?= =?UTF-8?q?Hash=20every=20pass=20and=20stops=20writing=20while=20the=20nod?= =?UTF-8?q?e=20reports=20another=20chain=20(re-indexing=20only=20when=20th?= =?UTF-8?q?e=20node=20moves=20to=20the=20pinned=20chain),=20GET=20/api/v1/?= =?UTF-8?q?chain,=20and=20/health=20gains=20genesis=5Fhash,=20head=5Ftimes?= =?UTF-8?q?tamp=5Fms,=20stalled,=20wrong=5Fchain?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old behaviour — wipe and re-index whenever the node's chain id or genesis changed — is kept only for a database with no recorded chain. The mock hard-fork test now covers the three paths (cut to the pinned chain, an unpinned genesis that halts the indexer, a restart pinned to it), and tests/chain_sync.rs covers /chain live, behind, unreachable, stalled and a genesis switch that halts and then resumes. Co-Authored-By: Claude Opus 5.5 --- crates/randscan-api/src/handlers/chain.rs | 76 ++++++ crates/randscan-api/src/handlers/health.rs | 18 +- crates/randscan-api/src/handlers/mod.rs | 2 + crates/randscan-api/src/routes.rs | 2 + crates/randscan-api/tests/chain_sync.rs | 207 ++++++++++++++++ crates/randscan-api/tests/common/mock_node.rs | 37 ++- crates/randscan-api/tests/common/mod.rs | 49 +++- crates/randscan-api/tests/mock_node.rs | 89 ++++++- crates/randscan-core/src/types/api.rs | 27 +++ crates/randscan-db/src/lib.rs | 1 + crates/randscan-db/src/queries/blocks.rs | 9 + crates/randscan-db/src/queries/indexer.rs | 46 +++- crates/randscan-db/tests/accounts.rs | 88 ++++++- crates/randscan-db/tests/chain_reset.rs | 16 ++ crates/randscan-indexer/src/lib.rs | 7 + crates/randscan-indexer/src/service.rs | 220 +++++++++++------- migrations/015_chain_meta.sql | 24 ++ 17 files changed, 814 insertions(+), 104 deletions(-) create mode 100644 crates/randscan-api/src/handlers/chain.rs create mode 100644 crates/randscan-api/tests/chain_sync.rs create mode 100644 migrations/015_chain_meta.sql diff --git a/crates/randscan-api/src/handlers/chain.rs b/crates/randscan-api/src/handlers/chain.rs new file mode 100644 index 0000000..0bd875c --- /dev/null +++ b/crates/randscan-api/src/handlers/chain.rs @@ -0,0 +1,76 @@ +use crate::{state::AppState, ApiResult}; +use axum::{extract::State, Json}; +use randscan_core::{classify, ChainResponse, ChainState, ChainView}; +use randscan_db as db; + +/// Wall-clock milliseconds, the clock block timestamps are measured against. +pub(crate) fn now_ms() -> i64 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_millis() as i64) + .unwrap_or(0) +} + +/// The indexed data as a [`ChainView`], plus whether the indexer is halted and whether its last +/// request to the node succeeded. The stored chain is `chain_meta` (falling back to the chain id +/// `indexer_state` recorded, with no genesis, before the first pass); the head is the latest +/// indexed block. While halted, the node's height belongs to another chain, so `node_height` +/// and `lag` are left out rather than compared across chains. +pub(crate) async fn chain_view(state: &AppState) -> db::Result<(ChainView, bool, bool)> { + let pool = state.db.inner(); + let meta = db::get_chain_meta(pool).await?; + let (chain_id, genesis_hash) = match meta { + Some(m) => (m.chain_id, Some(m.genesis_hash)), + None => ( + db::get_indexer_state(pool).await?.chain_id.unwrap_or(0), + None, + ), + }; + let head = db::latest_block_head(pool).await?; + let s = state.indexer.get_state().await; + let head_height = head.map(|(h, _)| h).unwrap_or(0); + let (node_height, lag) = if s.halted || s.node_chain_id.is_none() { + (None, None) + } else { + let indexed = head.map(|(h, _)| h).unwrap_or(-1); + (Some(s.node_height), Some((s.node_height - indexed).max(0))) + }; + let view = ChainView { + chain_id, + genesis_hash, + head_height, + head_timestamp_ms: head.map(|(_, ts)| ts), + node_height, + lag, + node_chain_id: s.node_chain_id, + node_genesis_hash: s.node_genesis_hash, + }; + Ok((view, s.halted, s.is_connected)) +} + +/// GET /api/v1/chain — the explorer's [`ChainView`] and its state against the configured pin +/// (site-sync design §2–§3). The view classifies as the spec's table says. A node the indexer +/// cannot reach turns a `live` or `behind` view into `unreachable`: the data was current a moment +/// ago but nothing confirms it now. Once the head ages past `STALL_MS` the state is `stalled`, +/// which says more about what the reader is looking at. +pub async fn get_chain(State(state): State) -> ApiResult> { + let (view, halted, connected) = chain_view(&state).await?; + let expected = state.indexer.expected(); + let mut c = classify(Some(&view), expected, now_ms()); + if !connected && matches!(c.state, ChainState::Live | ChainState::Behind) { + c.state = ChainState::Unreachable; + c.detail = format!( + "The explorer cannot reach its node; last indexed block #{}.", + view.head_height + ); + } + Ok(Json(ChainResponse { + view, + state: c.state, + detail: c.detail, + expected_chain_id: expected.chain_id, + expected_genesis_hash: expected.genesis_hash.clone(), + halted, + node_connected: connected, + })) +} diff --git a/crates/randscan-api/src/handlers/health.rs b/crates/randscan-api/src/handlers/health.rs index 4b5cff6..4875dcb 100644 --- a/crates/randscan-api/src/handlers/health.rs +++ b/crates/randscan-api/src/handlers/health.rs @@ -1,9 +1,14 @@ +use super::chain::{chain_view, now_ms}; use crate::{state::AppState, ApiResult}; use axum::{extract::State, Json}; -use randscan_core::{HealthResponse, IndexerHealth}; +use randscan_core::{is_stalled, is_wrong_chain, HealthResponse, IndexerHealth}; use randscan_db as db; /// GET /api/v1/health +/// +/// `status` is `healthy` when the database answers and the indexer is connected, synced, fresh +/// and on the pinned chain; `degraded` when the database answers but any of that fails (a stalled +/// head or the wrong chain included); `unhealthy` without the database. pub async fn health(State(state): State) -> ApiResult> { let db_ok = db::get_network_stats(state.db.inner()).await.is_ok(); let s = state.indexer.get_state().await; @@ -15,7 +20,12 @@ pub async fn health(State(state): State) -> ApiResult) -> ApiResult Router { let api = Router::new() .route("/health", get(handlers::health)) + // Read cross-origin by zusd.money (the CORS layer below covers every /api/v1 route). + .route("/chain", get(handlers::get_chain)) .route("/stats", get(handlers::get_stats)) .route("/blocks", get(handlers::list_blocks)) .route("/blocks/latest", get(handlers::latest_blocks)) diff --git a/crates/randscan-api/tests/chain_sync.rs b/crates/randscan-api/tests/chain_sync.rs new file mode 100644 index 0000000..286e2bb --- /dev/null +++ b/crates/randscan-api/tests/chain_sync.rs @@ -0,0 +1,207 @@ +//! `GET /api/v1/chain` and the chain fields of `/api/v1/health` against a scripted node (site-sync +//! design, 2026-10-27): live on the pinned chain, behind by more than `MAX_LAG`, unreachable, +//! stalled, and a node that switches genesis under a running indexer, which stops writing until +//! the node comes back. Live indexer, needs `DATABASE_URL`. One lock: each test resets the shared +//! database to its own chain. + +mod common; + +use common::mock_node::*; +use common::*; +use randscan_core::ChainPin; +use serde_json::{json, Value}; +use std::time::Duration; + +const WAIT: Duration = Duration::from_secs(40); + +static LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(()); + +/// A previous run may have left this exact chain (same genesis) behind, which the first pass +/// would adopt as is; start from nothing. +async fn fresh(live: &LiveApp) { + let mut conn = live.pool.acquire().await.unwrap(); + randscan_db::reset_chain_data(&mut conn, 0).await.unwrap(); +} + +async fn get(live: &LiveApp, path: &str) -> Value { + call(&live.app, json_req("GET", path, None, None)).await.2 +} + +#[tokio::test] +async fn chain_view_tracks_live_behind_unreachable_and_stalled() { + let _g = LOCK.lock().await; + let mut chain = MockChain::new(40, "sync-a"); + for i in 0..3 { + chain.push_block(vec![tx( + 40, + &format!("s{i}"), + Some(bundle(&format!("sa{i}"))), + json!({ "kind": "none" }), + )]); + } + chain.go_live(); + let genesis = h("block-40-sync-a-0"); + let node = start_mock_node(chain).await; + let pin = ChainPin::new(40, &genesis); + let Some(live) = live_app_pinned(test_config(), &node.url, "127.0.0.1", pin).await else { + eprintln!("skipping: DATABASE_URL unset"); + return; + }; + fresh(&live).await; + live.start(); + + // Live: the stored genesis is the node's and the pin, the head is the node's head. + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| { + c["head_height"] == 3 && c["state"] == "live" + }) + .await; + assert_eq!(ch["chain_id"], 40); + assert_eq!(ch["genesis_hash"], genesis); + assert_eq!(ch["node_genesis_hash"], genesis); + assert_eq!(ch["node_chain_id"], 40); + assert_eq!(ch["node_height"], 3); + assert_eq!(ch["lag"], 0); + assert_eq!(ch["halted"], false); + assert_eq!(ch["node_connected"], true); + assert_eq!(ch["expected_chain_id"], 40); + assert_eq!(ch["expected_genesis_hash"], genesis); + let head_ts = node.with_chain(|c| c.blocks[3]["timestamp_ms"].clone()); + assert_eq!(ch["head_timestamp_ms"], head_ts); + + let health = live + .wait_for("/api/v1/health", WAIT, |b| b["status"] == "healthy") + .await; + assert_eq!(health["genesis_hash"], genesis); + assert_eq!(health["head_timestamp_ms"], head_ts); + assert_eq!(health["stalled"], false); + assert_eq!(health["wrong_chain"], false); + // The pre-existing fields are unchanged. + assert_eq!(health["database"], true); + assert_eq!(health["indexer"]["current_height"], 3); + assert!(health["version"].is_string()); + + // zusd.money reads /chain from the browser: it must be readable cross-origin. + let req = axum::http::Request::builder() + .uri("/api/v1/chain") + .header("origin", "https://zusd.money") + .body(axum::body::Body::empty()) + .unwrap(); + let (status, headers, _) = call(&live.app, req).await; + assert_eq!(status, 200); + assert_eq!( + headers + .get("access-control-allow-origin") + .and_then(|v| v.to_str().ok()), + Some("*") + ); + + // Behind: the node announces 12 blocks it does not serve yet. + node.with_chain(|c| { + c.serve_up_to = Some(3); + for _ in 0..12 { + c.push_block(vec![]); + } + }); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| c["state"] == "behind") + .await; + assert_eq!(ch["lag"], 12, "{ch}"); + assert_eq!(ch["node_height"], 15); + assert_eq!(ch["head_height"], 3); + + // Caught up again. + node.with_chain(|c| c.serve_up_to = None); + live.wait_for("/api/v1/chain", WAIT, |c| { + c["state"] == "live" && c["head_height"] == 15 + }) + .await; + + // Unreachable: the node stops answering while the indexed head is still fresh. + node.with_chain(|c| c.fail.push(("rand_getHead".into(), None))); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| c["state"] == "unreachable") + .await; + assert_eq!(ch["node_connected"], false); + assert_eq!(ch["head_height"], 15, "the last good height stays: {ch}"); + + // Stalled: the same view once the head is older than STALL_MS (aged in the database rather + // than by waiting a minute). + sqlx::query("UPDATE blocks SET timestamp_ms = timestamp_ms - 120000") + .execute(&live.pool) + .await + .unwrap(); + let ch = get(&live, "/api/v1/chain").await; + assert_eq!(ch["state"], "stalled", "{ch}"); + let health = get(&live, "/api/v1/health").await; + assert_eq!(health["stalled"], true); + assert_eq!(health["status"], "degraded"); +} + +#[tokio::test] +async fn a_genesis_switch_stops_the_indexer_until_the_node_comes_back() { + let _g = LOCK.lock().await; + let mut chain = MockChain::new(41, "switch-a"); + chain.push_block(vec![tx( + 41, + "w0", + Some(bundle("wa0")), + json!({ "kind": "none" }), + )]); + chain.go_live(); + let genesis_a = h("block-41-switch-a-0"); + let node = start_mock_node(chain).await; + let pin = ChainPin::new(41, &genesis_a); + let Some(live) = live_app_pinned(test_config(), &node.url, "127.0.0.1", pin).await else { + eprintln!("skipping: DATABASE_URL unset"); + return; + }; + fresh(&live).await; + live.start(); + live.wait_for("/api/v1/chain", WAIT, |c| { + c["head_height"] == 1 && c["state"] == "live" + }) + .await; + + // The node is re-pointed at another genesis with the same chain id and a longer chain. + let original = node.with_chain(|c| { + let mut other = MockChain::new(41, "switch-b"); + for _ in 0..5 { + other.push_block(vec![]); + } + other.go_live(); + std::mem::replace(c, other) + }); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| c["halted"] == true) + .await; + assert_eq!(ch["state"], "wrong_chain"); + assert_eq!(ch["genesis_hash"], genesis_a); + assert_eq!(ch["node_genesis_hash"], h("block-41-switch-b-0")); + let health = get(&live, "/api/v1/health").await; + assert_eq!(health["wrong_chain"], true); + assert_eq!(health["status"], "degraded"); + + tokio::time::sleep(Duration::from_secs(1)).await; + let (count, max): (i64, Option) = + sqlx::query_as("SELECT COUNT(*), MAX(height) FROM blocks") + .fetch_one(&live.pool) + .await + .unwrap(); + assert_eq!((count, max), (2, Some(1)), "no block of the other genesis"); + let b0 = get(&live, "/api/v1/blocks/0").await; + assert_eq!(b0["hash"], genesis_a); + + // Back on the stored chain, with a new block: indexing resumes where it stopped. + node.with_chain(|c| { + *c = original; + c.push_block(vec![]); + }); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| { + c["halted"] == false && c["head_height"] == 2 + }) + .await; + assert_eq!(ch["state"], "live", "{ch}"); + assert_eq!(ch["genesis_hash"], genesis_a); +} diff --git a/crates/randscan-api/tests/common/mock_node.rs b/crates/randscan-api/tests/common/mock_node.rs index 337aefa..d96de95 100644 --- a/crates/randscan-api/tests/common/mock_node.rs +++ b/crates/randscan-api/tests/common/mock_node.rs @@ -39,6 +39,14 @@ pub fn public_digest(program: &str) -> String { /// The treasury account a chain-21 mock (`v080: Some(true)`) holds. pub const MOCK_TREASURY: &str = "9b2e000000000000000000000000000000000000000000000000000000000001"; +/// Wall-clock milliseconds. +pub fn now_ms() -> u64 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_millis() as u64 +} + pub fn h(seed: &str) -> String { hex::encode(Sha256::digest(seed.as_bytes())) } @@ -114,6 +122,13 @@ pub struct MockChain { pub fail: Vec<(String, Option)>, /// Methods that answer `null`, the same way: a node that does not know the thing asked for. pub null: Vec<(String, Option)>, + /// Stamp new blocks with the wall clock instead of the fixed 2026-09 epoch, so the head is + /// fresh for the site-sync classifier (see [`MockChain::go_live`]). + pub live_clock: bool, + /// `rand_getBlockByHeight` answers `null` above this height while `rand_getHead` reports the + /// real head: a node that announced blocks it cannot serve yet, which leaves the indexer + /// behind by a chosen number of blocks. + pub serve_up_to: Option, } impl MockChain { @@ -140,11 +155,24 @@ impl MockChain { peers: Vec::new(), fail: Vec::new(), null: Vec::new(), + live_clock: false, + serve_up_to: None, }; c.push_block(vec![]); c } + /// Re-stamp every block so the head is now (one second apart going back) and stamp later + /// blocks with the wall clock. + pub fn go_live(&mut self) { + self.live_clock = true; + let now = now_ms(); + let n = self.blocks.len() as u64; + for (i, b) in self.blocks.iter_mut().enumerate() { + b["timestamp_ms"] = json!(now - (n - 1 - i as u64) * 1000); + } + } + pub fn head(&self) -> &Value { self.blocks.last().expect("genesis") } @@ -236,7 +264,7 @@ impl MockChain { "view": self.view, "parent": parent, "proposer": VALIDATOR, - "timestamp_ms": 1_789_000_000_000u64 + height * 1000, + "timestamp_ms": if self.live_clock { now_ms() } else { 1_789_000_000_000u64 + height * 1000 }, "tx_root": h(&format!("txroot-{height}")), "state_root": h(&format!("state-{}-{}-{height}", self.chain_id, self.salt)), "justify_view": self.view.saturating_sub(1), @@ -311,8 +339,11 @@ impl MockChain { }) } "rand_getBlockByHeight" => { - let height = p(0).as_u64().ok_or((-32602, "height".to_string()))? as usize; - self.blocks.get(height).cloned().unwrap_or(Value::Null) + let height = p(0).as_u64().ok_or((-32602, "height".to_string()))?; + if self.serve_up_to.is_some_and(|max| height > max) { + return Ok(Value::Null); + } + self.blocks.get(height as usize).cloned().unwrap_or(Value::Null) } "rand_getBlockByHash" => { let hash = p(0).as_str().unwrap_or("").to_ascii_lowercase(); diff --git a/crates/randscan-api/tests/common/mod.rs b/crates/randscan-api/tests/common/mod.rs index d465c99..db06eba 100644 --- a/crates/randscan-api/tests/common/mod.rs +++ b/crates/randscan-api/tests/common/mod.rs @@ -11,6 +11,7 @@ use axum::{ }; use http_body_util::BodyExt; use randscan_api::{create_router, mail::MailSender, ratelimit::RateLimiter, ApiConfig, AppState}; +use randscan_core::ChainPin; use randscan_db::{run_migrations, DbPool}; use randscan_indexer::{Broadcaster, IndexerConfig, IndexerService}; use randscan_ws::WsManager; @@ -130,16 +131,32 @@ pub struct LiveApp { pub pool: PgPool, pub indexer: Arc, pub broadcaster: Broadcaster, + pub rpc_url: String, + cfg: ApiConfig, + task: std::sync::Mutex>>, } impl LiveApp { pub fn start(&self) { let indexer = self.indexer.clone(); - tokio::spawn(async move { + let handle = tokio::spawn(async move { if let Err(e) = indexer.run().await { eprintln!("indexer stopped: {e:#}"); } }); + *self.task.lock().unwrap() = Some(handle); + } + + /// Stop this indexer and start another over the same database with `pin` (and `rpc_url`): + /// an operator restarting the explorer with a new `RANDSCAN_EXPECTED_*`, or pointing it at + /// another node. The new app is started. + pub fn restart(&self, rpc_url: &str, pin: ChainPin) -> LiveApp { + if let Some(h) = self.task.lock().unwrap().take() { + h.abort(); + } + let next = build_live(self.cfg.clone(), self.pool.clone(), rpc_url, pin); + next.start(); + next } /// Poll `GET path` until `pred(body)` holds; panics with the last body after `timeout`. @@ -171,6 +188,18 @@ pub async fn live_app(cfg: ApiConfig, rpc_url: &str) -> Option { /// tracker does not ask the network for it. A public one needs a fresh `node_geo` row to avoid /// a lookup. pub async fn live_app_with_ip(cfg: ApiConfig, rpc_url: &str, public_ip: &str) -> Option { + live_app_pinned(cfg, rpc_url, public_ip, ChainPin::default()).await +} + +/// [`live_app_with_ip`] with the indexer (and `/api/v1/chain`) pinned to `pin`. The database's +/// `chain_meta` row is cleared first, so the indexer's first pass takes the node's chain (and +/// drops whatever chain an earlier test left), as it does on a fresh database. +pub async fn live_app_pinned( + cfg: ApiConfig, + rpc_url: &str, + public_ip: &str, + pin: ChainPin, +) -> Option { let url = std::env::var("DATABASE_URL").ok()?; // Keep the peer tracker off the network (it would geolocate the host otherwise). std::env::set_var("NODE_PUBLIC_IP", public_ip); @@ -180,6 +209,14 @@ pub async fn live_app_with_ip(cfg: ApiConfig, rpc_url: &str, public_ip: &str) -> .await .expect("connect to DATABASE_URL"); run_migrations(&pool).await.expect("migrations"); + sqlx::query("DELETE FROM chain_meta") + .execute(&pool) + .await + .expect("clear chain_meta"); + Some(build_live(cfg, pool, rpc_url, pin)) +} + +fn build_live(cfg: ApiConfig, pool: PgPool, rpc_url: &str, pin: ChainPin) -> LiveApp { let db = DbPool::new(pool.clone()); let broadcaster = Broadcaster::new(); let indexer = Arc::new(IndexerService::new( @@ -189,6 +226,7 @@ pub async fn live_app_with_ip(cfg: ApiConfig, rpc_url: &str, public_ip: &str) -> batch_size: 50, stats_interval: Duration::from_millis(200), nodes_interval: Duration::from_secs(3600), + expected: pin, }, db.clone(), broadcaster.clone(), @@ -197,14 +235,17 @@ pub async fn live_app_with_ip(cfg: ApiConfig, rpc_url: &str, public_ip: &str) -> db, indexer: indexer.clone(), ws_manager: Arc::new(WsManager::new()), - config: Arc::new(cfg), + config: Arc::new(cfg.clone()), limiter: Arc::new(RateLimiter::new()), mailer: None, }; - Some(LiveApp { + LiveApp { app: create_router(state), pool, indexer, broadcaster, - }) + rpc_url: rpc_url.to_string(), + cfg, + task: std::sync::Mutex::new(None), + } } diff --git a/crates/randscan-api/tests/mock_node.rs b/crates/randscan-api/tests/mock_node.rs index fb98cdb..bc1a687 100644 --- a/crates/randscan-api/tests/mock_node.rs +++ b/crates/randscan-api/tests/mock_node.rs @@ -1,14 +1,16 @@ //! Indexer, database, API and broadcast fan-out working together against a scripted shielded //! node: every action kind of phases S1–S3, an unknown future kind, a block at the consensus //! transaction limit, the commitment tree and nullifier set, the S2 register/epoch/supply and -//! the S3-only register shape, and two hard forks under a running indexer (new chain id; same -//! chain id with a new genesis). Needs `DATABASE_URL`. +//! the S3-only register shape, and three chain changes under a running indexer: a cut to the +//! pinned chain (re-indexed from height 0), a re-created genesis nobody pinned (the indexer stops +//! writing and reports `wrong_chain`), and a restart pinned to that genesis (re-indexed). Needs +//! `DATABASE_URL`. mod common; use common::mock_node::*; use common::*; -use randscan_core::{BroadcastEvent, TxKind}; +use randscan_core::{BroadcastEvent, ChainPin, TxKind}; use serde_json::{json, Value}; use std::sync::{Arc, Mutex}; use std::time::Duration; @@ -252,7 +254,10 @@ async fn indexes_every_shielded_kind_and_survives_hard_forks() { chain.validators[0].rewards = "3000000".into(); let node = start_mock_node(chain).await; - let Some(live) = live_app(test_config(), &node.url).await else { + // Pinned to phase 2's chain from the start: an operator moving the pin ahead of a cut. The + // first pass still adopts chain 7, the node's chain, and `/chain` calls it the wrong chain. + let pin_b = ChainPin::new(8, &h("block-8-genesis-b-0")); + let Some(live) = live_app_pinned(test_config(), &node.url, "127.0.0.1", pin_b).await else { eprintln!("skipping: DATABASE_URL unset"); return; }; @@ -1233,8 +1238,19 @@ async fn indexes_every_shielded_kind_and_survives_hard_forks() { assert!(got.contains(&k), "broadcast kinds miss {k}: {got:?}"); } - // ----- phase 2: a user and an API key exist; the fleet hard-forks to chain 8 (an S3-only - // node: register without pending/active, no epoch, no supply) ---------------------------- + let (status, _, ch) = call_api(&live.app, "/api/v1/chain").await; + assert_eq!(status, 200, "{ch}"); + assert_eq!(ch["chain_id"], 7); + assert_eq!(ch["genesis_hash"], h("block-7-genesis-a-0")); + assert_eq!(ch["head_height"], 4); + assert_eq!( + ch["state"], "wrong_chain", + "chain 7 is not the pinned chain 8: {ch}" + ); + assert_eq!(ch["halted"], false, "the node and the database agree"); + + // ----- phase 2: a user and an API key exist; the fleet hard-forks to chain 8, the pinned + // chain (an S3-only node: register without pending/active, no epoch, no supply) ---------- let body = json!({ "email": unique_email(), "password": "correct horse battery" }); let (status, headers, _) = call( &live.app, @@ -1340,7 +1356,12 @@ async fn indexes_every_shielded_kind_and_survives_hard_forks() { let (status, _, _) = call(&live.app, req).await; assert_eq!(status, 200); - // ----- phase 3: same chain id, re-created genesis, node head below the indexed height --- + let (_, _, ch) = call_api(&live.app, "/api/v1/chain").await; + assert_eq!(ch["genesis_hash"], h("block-8-genesis-b-0")); + assert_eq!(ch["chain_id"], 8); + + // ----- phase 3: same chain id, a re-created genesis nobody pinned: the indexer stops + // writing, keeps what it has, and says so ------------------------------------------------- node.with_chain(|c| { c.push_block(vec![]); c.push_block(vec![]); @@ -1349,8 +1370,54 @@ async fn indexes_every_shielded_kind_and_survives_hard_forks() { b["indexer"]["current_height"] == 3 }) .await; + node.with_chain(|c| { + *c = MockChain::new(8, "genesis-c"); + for _ in 0..6 { + c.push_block(vec![]); + } + }); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| c["halted"] == true) + .await; + assert_eq!(ch["state"], "wrong_chain", "{ch}"); + assert_eq!( + ch["genesis_hash"], + h("block-8-genesis-b-0"), + "the stored chain" + ); + assert_eq!(ch["node_genesis_hash"], h("block-8-genesis-c-0")); + assert_eq!(ch["node_chain_id"], 8); + assert!(ch["node_height"].is_null() && ch["lag"].is_null(), "{ch}"); + assert!( + ch["detail"].as_str().unwrap().contains("indexing stopped"), + "{ch}" + ); + let (_, _, health) = call_api(&live.app, "/api/v1/health").await; + assert_eq!(health["status"], "degraded", "{health}"); + assert_eq!(health["wrong_chain"], true); + assert_eq!(health["genesis_hash"], h("block-8-genesis-b-0")); + // Nothing of the new genesis is written, however long the node keeps it up. + tokio::time::sleep(Duration::from_secs(2)).await; + let (_, _, b0) = call_api(&live.app, "/api/v1/blocks/0").await; + assert_eq!(b0["hash"], h("block-8-genesis-b-0")); + let (status, _, b3) = call_api(&live.app, "/api/v1/blocks/3").await; + assert_eq!(status, 200, "the old chain's blocks stay: {b3}"); + let (status, _, _) = call_api(&live.app, "/api/v1/blocks/4").await; + assert_eq!(status, 404, "the new genesis' blocks 4.. are never written"); + let (stored_chain, stored_genesis): (i64, String) = + sqlx::query_as("SELECT chain_id, genesis_hash FROM chain_meta WHERE id = 1") + .fetch_one(&live.pool) + .await + .unwrap(); + assert_eq!( + (stored_chain, stored_genesis), + (8, h("block-8-genesis-b-0")) + ); + + // ----- phase 4: the operator pins the re-created genesis and restarts; the node's head is + // below the old indexed height, and everything is re-read from height 0 and leaf 0 --------- node.with_chain(|c| *c = MockChain::new(8, "genesis-c")); - // The forced re-check is rate limited (10 s), so allow for that. + let live = live.restart(&node.url, ChainPin::new(8, &h("block-8-genesis-c-0"))); let b0 = live .wait_for("/api/v1/blocks/0", WAIT, |b| { b["hash"] == h("block-8-genesis-c-0") @@ -1359,8 +1426,12 @@ async fn indexes_every_shielded_kind_and_survives_hard_forks() { assert_eq!(b0["height"], 0); let (status, _, _) = call_api(&live.app, "/api/v1/blocks/3").await; assert_eq!(status, 404); + // The handler lists, then counts: wait on both, or a count taken just after the leaf's + // commit can pair with the empty page read just before it. let notes = live - .wait_for("/api/v1/notes", WAIT, |n| n["pagination"]["total"] == 1) + .wait_for("/api/v1/notes", WAIT, |n| { + n["pagination"]["total"] == 1 && n["data"].as_array().is_some_and(|d| d.len() == 1) + }) .await; assert_eq!( notes["data"][0]["cm"], diff --git a/crates/randscan-core/src/types/api.rs b/crates/randscan-core/src/types/api.rs index 3170c54..569ef5e 100644 --- a/crates/randscan-core/src/types/api.rs +++ b/crates/randscan-core/src/types/api.rs @@ -1,3 +1,4 @@ +use super::{ChainState, ChainView}; use serde::{Deserialize, Serialize}; /// Pagination query parameters (`page`, `limit`). @@ -206,6 +207,32 @@ pub struct HealthResponse { pub version: String, pub database: bool, pub indexer: IndexerHealth, + /// The genesis the indexed data belongs to (`None` before the indexer first reached a node). + pub genesis_hash: Option, + /// The latest indexed block's timestamp (`None` with nothing indexed). + pub head_timestamp_ms: Option, + /// No indexed block for more than `STALL_MS`, or none at all. + pub stalled: bool, + /// The indexed chain is not the configured pin, or the node has moved to another chain and + /// the indexer stopped writing. + pub wrong_chain: bool, +} + +/// `GET /api/v1/chain`: the [`ChainView`] of the indexed data, classified server-side against +/// the configured pin. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ChainResponse { + #[serde(flatten)] + pub view: ChainView, + pub state: ChainState, + pub detail: String, + pub expected_chain_id: i64, + pub expected_genesis_hash: String, + /// The indexer has stopped writing because the node reports a different chain than the one + /// stored. + pub halted: bool, + /// Whether the indexer's last request to the node succeeded. + pub node_connected: bool, } #[derive(Debug, Clone, Serialize, Deserialize)] diff --git a/crates/randscan-db/src/lib.rs b/crates/randscan-db/src/lib.rs index 5eacce4..797bed5 100644 --- a/crates/randscan-db/src/lib.rs +++ b/crates/randscan-db/src/lib.rs @@ -105,6 +105,7 @@ const MIGRATIONS: &[(i32, &str)] = &[ 14, include_str!("../../../migrations/014_perps_multisig_aggregate.sql"), ), + (15, include_str!("../../../migrations/015_chain_meta.sql")), ]; /// Advisory lock key used to serialize migration runs across concurrent callers. The diff --git a/crates/randscan-db/src/queries/blocks.rs b/crates/randscan-db/src/queries/blocks.rs index a5db832..df4bdda 100644 --- a/crates/randscan-db/src/queries/blocks.rs +++ b/crates/randscan-db/src/queries/blocks.rs @@ -101,6 +101,15 @@ pub async fn max_block_height(pool: &PgPool) -> Result> { .await?) } +/// The latest indexed block's height and timestamp, `None` with nothing indexed. +pub async fn latest_block_head(pool: &PgPool) -> Result> { + Ok( + sqlx::query_as("SELECT height, timestamp_ms FROM blocks ORDER BY height DESC LIMIT 1") + .fetch_optional(pool) + .await?, + ) +} + /// Average block interval over the last `n` blocks, in milliseconds. pub async fn avg_block_time_ms(pool: &PgPool, n: i64) -> Result { // MIN and MAX are NULL over an empty table, so they decode as `Option`. diff --git a/crates/randscan-db/src/queries/indexer.rs b/crates/randscan-db/src/queries/indexer.rs index d11784e..a5e2473 100644 --- a/crates/randscan-db/src/queries/indexer.rs +++ b/crates/randscan-db/src/queries/indexer.rs @@ -50,6 +50,42 @@ pub async fn set_chain_id(conn: &mut PgConnection, chain_id: i64) -> Result<()> Ok(()) } +/// The chain the indexed data belongs to (`chain_meta`, migration 015). +#[derive(Debug, Clone, PartialEq, Eq, sqlx::FromRow)] +pub struct ChainMeta { + pub chain_id: i64, + pub genesis_hash: String, +} + +/// `None` before the indexer first reached a node, and right after a chain reset. +pub async fn get_chain_meta(pool: &PgPool) -> Result> { + Ok( + sqlx::query_as::<_, ChainMeta>( + "SELECT chain_id, genesis_hash FROM chain_meta WHERE id = 1", + ) + .fetch_optional(pool) + .await?, + ) +} + +/// Record (or replace) the chain the indexed data belongs to; the hash is stored lowercase. +pub async fn set_chain_meta( + conn: &mut PgConnection, + chain_id: i64, + genesis_hash: &str, +) -> Result<()> { + sqlx::query( + "INSERT INTO chain_meta (id, chain_id, genesis_hash) VALUES (1, $1, LOWER($2)) + ON CONFLICT (id) DO UPDATE SET chain_id = EXCLUDED.chain_id, + genesis_hash = EXCLUDED.genesis_hash, adopted_at = NOW(), updated_at = NOW()", + ) + .bind(chain_id) + .bind(genesis_hash) + .execute(conn) + .await?; + Ok(()) +} + /// Tables derived from the chain, in dependency order. Everything else (users, sessions, /// API keys, password resets, the `node_geo` IP cache) is independent of the chain and kept. pub const CHAIN_TABLES: &[&str] = &[ @@ -63,8 +99,9 @@ pub const CHAIN_TABLES: &[&str] = &[ ]; /// Forget every block, transaction, note, nullifier, program and validator and start over at -/// height 0 (and leaf 0) for `chain_id`. Used when the node's chain id (or genesis block) no -/// longer matches the indexed data, e.g. after a testnet hard fork. Runs in one transaction. +/// height 0 (and leaf 0) for `chain_id`, and forget the recorded `chain_meta`. Used when the +/// indexer moves to the pinned chain, or on its first pass over data from another chain. Runs in +/// one transaction. pub async fn reset_chain_data(conn: &mut PgConnection, chain_id: i64) -> Result<()> { let tables = CHAIN_TABLES.join(", "); sqlx::query("BEGIN").execute(&mut *conn).await?; @@ -72,6 +109,11 @@ pub async fn reset_chain_data(conn: &mut PgConnection, chain_id: i64) -> Result< sqlx::query(&format!("TRUNCATE {tables} RESTART IDENTITY CASCADE")) .execute(&mut *conn) .await?; + // The wiped database belongs to no chain until the caller records the new one; if that + // never happens the indexer's next first pass takes the node's identity. + sqlx::query("DELETE FROM chain_meta") + .execute(&mut *conn) + .await?; sqlx::query( "UPDATE network_stats SET chain_id = $1, height = 0, view = 0, total_transactions = 0, notes = 0, nullifiers = 0, validator_count = 0, active_validator_count = 0, diff --git a/crates/randscan-db/tests/accounts.rs b/crates/randscan-db/tests/accounts.rs index 1579a91..4e1312c 100644 --- a/crates/randscan-db/tests/accounts.rs +++ b/crates/randscan-db/tests/accounts.rs @@ -32,7 +32,10 @@ async fn migrations_are_versioned_and_idempotent() { // A long-lived database (this shared one, and the live one) may also record the burned // version 8, the reverted chain-11 receivers migration; a fresh database never does. let versions: Vec = versions.into_iter().filter(|v| *v != 8).collect(); - assert_eq!(versions, vec![1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14]); + assert_eq!( + versions, + vec![1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15] + ); for table in ["users", "sessions", "api_keys"] { let exists: bool = sqlx::query_scalar( @@ -230,6 +233,84 @@ fn maintenance_and_scratch_urls(scratch_db: &str) -> (String, String) { ) } +/// Migration 015 on a database that already indexes a chain (the live explorer on chain 21) +/// adopts that chain: the recorded chain id and block 0's hash, lowercased. A database with no +/// block 0 gets no row, and the indexer's first pass records the node's chain. +#[tokio::test] +async fn migration_15_adopts_the_indexed_chain() { + if std::env::var("DATABASE_URL").is_err() { + eprintln!("skipping: DATABASE_URL unset"); + return; + } + let nanos = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos(); + let scratch_db = format!("randscan_mig15_{nanos}"); + let (maintenance_url, scratch_url) = maintenance_and_scratch_urls(&scratch_db); + let admin_pool = PgPoolOptions::new() + .max_connections(1) + .connect(&maintenance_url) + .await + .expect("connect to maintenance database"); + sqlx::query(&format!("CREATE DATABASE {scratch_db}")) + .execute(&admin_pool) + .await + .expect("create scratch database"); + let pool = PgPoolOptions::new() + .max_connections(2) + .connect(&scratch_url) + .await + .expect("connect to scratch database"); + + // A fresh database: no block 0, no row. + run_migrations(&pool).await.unwrap(); + let rows: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM chain_meta") + .fetch_one(&pool) + .await + .unwrap(); + assert_eq!(rows, 0); + + // Wind back to a version-14 database holding chain 21, then migrate it. + sqlx::query("DROP TABLE chain_meta") + .execute(&pool) + .await + .unwrap(); + sqlx::query("DELETE FROM schema_migrations WHERE version = 15") + .execute(&pool) + .await + .unwrap(); + let genesis = "CA76C2766ED6090AC6BA5DAD86B724DD5D2B80C0EDFAED287CD8B129E663CA9A"; + sqlx::query( + "INSERT INTO blocks (hash, height, view, parent, proposer, timestamp_ms, tx_root, state_root, justify_view, tx_count) + VALUES ($1, 0, 0, $2, 'p', 1, 'r', 's', 0, 0)", + ) + .bind(genesis) + .bind("00".repeat(32)) + .execute(&pool) + .await + .unwrap(); + sqlx::query("UPDATE indexer_state SET chain_id = 21 WHERE id = 1") + .execute(&pool) + .await + .unwrap(); + run_migrations(&pool).await.unwrap(); + let meta = db::get_chain_meta(&pool).await.unwrap(); + assert_eq!( + meta, + Some(db::ChainMeta { + chain_id: 21, + genesis_hash: genesis.to_ascii_lowercase(), + }) + ); + + pool.close().await; + sqlx::query(&format!("DROP DATABASE IF EXISTS {scratch_db}")) + .execute(&admin_pool) + .await + .expect("drop scratch database"); +} + #[tokio::test] async fn concurrent_migrations_do_not_race() { if std::env::var("DATABASE_URL").is_err() { @@ -275,7 +356,10 @@ async fn concurrent_migrations_do_not_race() { .await .unwrap(); // A fresh database: every migration in the tree once, and never the burned version 8. - assert_eq!(versions, vec![1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14]); + assert_eq!( + versions, + vec![1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15] + ); pool.close().await; sqlx::query(&format!("DROP DATABASE IF EXISTS {scratch_db}")) diff --git a/crates/randscan-db/tests/chain_reset.rs b/crates/randscan-db/tests/chain_reset.rs index 12439cf..2026d32 100644 --- a/crates/randscan-db/tests/chain_reset.rs +++ b/crates/randscan-db/tests/chain_reset.rs @@ -156,7 +156,23 @@ async fn reset_chain_data_truncates_chain_tables_and_keeps_users() { "a leaf is linked to the tx that carried its commitment" ); + randscan_db::set_chain_meta(&mut conn, 4, &"AB".repeat(32)) + .await + .unwrap(); + assert_eq!( + randscan_db::get_chain_meta(&pool).await.unwrap(), + Some(randscan_db::ChainMeta { + chain_id: 4, + genesis_hash: "ab".repeat(32) + }), + "stored lowercase" + ); reset_chain_data(&mut conn, 5).await.unwrap(); + assert_eq!( + randscan_db::get_chain_meta(&pool).await.unwrap(), + None, + "a reset forgets the recorded chain until the caller records the new one" + ); for t in CHAIN_TABLES { let n: i64 = sqlx::query_scalar(&format!("SELECT count(*) FROM {t}")) diff --git a/crates/randscan-indexer/src/lib.rs b/crates/randscan-indexer/src/lib.rs index 3b84600..f2c6840 100644 --- a/crates/randscan-indexer/src/lib.rs +++ b/crates/randscan-indexer/src/lib.rs @@ -12,6 +12,7 @@ pub use processor::*; pub use rpc::*; pub use service::*; +use randscan_core::ChainPin; use std::time::Duration; #[derive(Debug, Clone)] @@ -26,6 +27,10 @@ pub struct IndexerConfig { pub stats_interval: Duration, /// Interval between peer/geolocation refreshes. pub nodes_interval: Duration, + /// The chain this deployment expects (`RANDSCAN_EXPECTED_CHAIN_ID`, + /// `RANDSCAN_EXPECTED_GENESIS`). The API classifies against it; the indexer re-indexes from + /// height 0 only when the node moves *to* it (see `IndexerService::check_chain`). + pub expected: ChainPin, } impl Default for IndexerConfig { @@ -36,6 +41,7 @@ impl Default for IndexerConfig { batch_size: 200, stats_interval: Duration::from_secs(5), nodes_interval: Duration::from_secs(60), + expected: ChainPin::default(), } } } @@ -64,6 +70,7 @@ impl IndexerConfig { "NODES_INTERVAL_SECS", d.nodes_interval.as_secs(), )), + expected: ChainPin::from_env(), } } } diff --git a/crates/randscan-indexer/src/service.rs b/crates/randscan-indexer/src/service.rs index 192291a..26778e9 100644 --- a/crates/randscan-indexer/src/service.rs +++ b/crates/randscan-indexer/src/service.rs @@ -2,19 +2,18 @@ //! register, the bridge state, the supply audit and the stats. use crate::{BlockProcessor, Broadcaster, IndexerConfig, NodeTracker, RpcClient}; -use anyhow::Result; -use randscan_core::{BridgeState, NetworkStats, NodeInfo, PerpsInfo, RandPrice, Supply, TokenList}; +use anyhow::{anyhow, Result}; +use randscan_core::{ + normalize_hash, same_hash, BridgeState, ChainPin, NetworkStats, NodeInfo, PerpsInfo, RandPrice, + Supply, TokenList, +}; use randscan_db::{self as db, DbPool, NewValidator, StatsUpdate}; -use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; use std::time::Instant; use tokio::sync::RwLock; use tokio::time::{sleep, Duration}; use tracing::{error, info, warn}; -/// Minimum interval between forced chain re-checks (each costs two RPC calls). -const CHAIN_RECHECK_SECS: u64 = 10; - #[derive(Debug, Clone, Default)] pub struct IndexerState { /// Highest indexed height (-1 if nothing indexed). @@ -22,6 +21,23 @@ pub struct IndexerState { pub node_height: i64, pub is_syncing: bool, pub is_connected: bool, + /// The chain id and genesis hash the node reported on the last pass (`None` before the first). + pub node_chain_id: Option, + pub node_genesis_hash: Option, + /// The node reports a different chain than the database holds, so the indexer has stopped + /// writing until the node comes back to the stored chain or moves to the pinned one. + pub halted: bool, +} + +/// What a pass's chain check decided. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum ChainCheck { + /// The node serves the chain the database holds; index on. + Same, + /// The chain data was dropped and the node's chain recorded; start a fresh pass. + Reset, + /// The node serves another chain; write nothing. + Halted, } pub struct IndexerService { @@ -32,10 +48,6 @@ pub struct IndexerService { broadcaster: Broadcaster, state: Arc>, chain: RwLock>, - /// Set once the indexed data has been checked against the node's chain id. - chain_checked: AtomicBool, - /// Last forced re-check (the node's head fell below the indexed height, or a fork). - last_chain_check: RwLock>, last_stats: RwLock>, /// The node's public bridge state and supply audit, refreshed with the stats. bridge: RwLock>, @@ -73,8 +85,6 @@ impl IndexerService { ..Default::default() })), chain: RwLock::new(None), - chain_checked: AtomicBool::new(false), - last_chain_check: RwLock::new(None), last_stats: RwLock::new(None), bridge: RwLock::new(None), supply: RwLock::new(None), @@ -89,6 +99,11 @@ impl IndexerService { &self.rpc } + /// The chain this deployment expects (the configured pin). + pub fn expected(&self) -> &ChainPin { + &self.config.expected + } + /// The RPL token registry as last read from the node (`None` before the first refresh, or on /// a node without the method). pub async fn tokens(&self) -> Option { @@ -158,62 +173,117 @@ impl IndexerService { } } - /// Make sure the indexed data belongs to the chain the node serves. Returns true when the - /// chain data was reset (the caller should start a fresh pass). + /// The node's chain id and genesis hash. The genesis comes from `rand_getGenesisHash`, or + /// from block 0's hash on a node predating that method (v0.3) or failing it; the two are the + /// same hash. + async fn node_identity(&self) -> Result<(i64, String)> { + let chain_id = self.rpc.chain_id().await? as i64; + let genesis = match self.rpc.genesis_hash().await.ok().flatten() { + Some(g) if !g.trim().is_empty() => g, + _ => self + .rpc + .block_by_height(0) + .await? + .map(|b| b.hash) + .ok_or_else(|| anyhow!("the node serves no genesis hash and no block 0"))?, + }; + Ok((chain_id, normalize_hash(&genesis))) + } + + /// Make sure the database and the node are on one chain before anything is written. Runs on + /// every pass (two cheap RPC calls), so a node re-pointed at another chain is caught before + /// its first block lands. /// - /// A different chain id (testnet hard fork, or the node was re-pointed) or a different - /// genesis block throws away the chain-derived tables and starts over at height 0; user - /// accounts and API keys are kept. A database indexed before the chain id was recorded is - /// stamped with the node's id. The check runs once at startup and again, at most every - /// `CHAIN_RECHECK_SECS`, whenever the node looks like a different chain (`force`). - async fn ensure_chain(&self, force: bool) -> Result { - if self.chain_checked.load(Ordering::Relaxed) { - if !force { - return Ok(false); + /// * No `chain_meta` row (a fresh database, or a reset that was cut short): the node's chain + /// is recorded. Data already in the database from a different chain id or genesis block is + /// dropped first, as the indexer always did when it met a new chain; that data never had a + /// recorded identity to defend. (Migration 015 records the identity of a database that + /// already holds blocks, so the live explorer arrives here only when it is empty.) + /// * The node serves the recorded chain: index on. + /// * The node serves the pinned chain and the database holds another: the operator moved the + /// pin for a chain cut, so the chain data is dropped (users, sessions and keys stay) and the + /// new chain indexed from height 0. + /// * Anything else: the node is on a chain nobody asked for. Nothing is written until it comes + /// back; `/api/v1/chain` reports `wrong_chain` and `/api/v1/health` `degraded`. + async fn check_chain(&self) -> Result { + let (node_chain, node_genesis) = self.node_identity().await?; + { + let mut s = self.state.write().await; + s.node_chain_id = Some(node_chain); + s.node_genesis_hash = Some(node_genesis.clone()); + } + let pool = self.pool.inner(); + let check = match db::get_chain_meta(pool).await? { + Some(m) if m.chain_id == node_chain && same_hash(&m.genesis_hash, &node_genesis) => { + ChainCheck::Same } - let recently = self - .last_chain_check - .read() - .await - .map(|t| t.elapsed() < Duration::from_secs(CHAIN_RECHECK_SECS)) - .unwrap_or(false); - if recently { - return Ok(false); + Some(m) if self.config.expected.matches(node_chain, &node_genesis) => { + warn!( + "the node moved from chain {} (genesis {}) to the pinned chain {} (genesis {}); \ + resetting chain data and re-indexing from height 0", + m.chain_id, m.genesis_hash, node_chain, node_genesis + ); + self.reset_to(node_chain, &node_genesis).await?; + ChainCheck::Reset } - } - *self.last_chain_check.write().await = Some(Instant::now()); - - // Ask the node, not the cache: the node may have been restarted on another chain. - let node_chain = self.rpc.chain_id().await? as i64; - let st = db::get_indexer_state(self.pool.inner()).await?; - let mut reason = None; - match st.chain_id { - Some(stored) if stored == node_chain => {} - Some(stored) => { - reason = Some(format!( - "node serves chain {} but the database holds chain {} ({} blocks)", - node_chain, stored, st.next_height - )); + Some(m) => { + if !self.state.read().await.halted { + error!( + "the node serves chain {} (genesis {}) but the database holds chain {} \ + (genesis {}) and the pin is chain {} (genesis {}); indexing stopped", + node_chain, + node_genesis, + m.chain_id, + m.genesis_hash, + self.config.expected.chain_id, + self.config.expected.genesis_hash + ); + } + ChainCheck::Halted } None => { - let mut conn = self.pool.inner().acquire().await?; - db::set_chain_id(&mut conn, node_chain).await?; - info!("indexing chain {}", node_chain); + let st = db::get_indexer_state(pool).await?; + let stored_genesis = db::get_block_hash_at(pool, 0).await?; + let other_id = st.chain_id.filter(|c| *c != node_chain); + let other_genesis = stored_genesis.filter(|g| !same_hash(g, &node_genesis)); + if other_id.is_some() || other_genesis.is_some() { + warn!( + "the database holds chain {:?} (genesis {:?}) but the node serves chain {} \ + (genesis {}); resetting chain data and re-indexing from height 0", + st.chain_id, other_genesis, node_chain, node_genesis + ); + self.reset_to(node_chain, &node_genesis).await?; + ChainCheck::Reset + } else { + let mut conn = pool.acquire().await?; + if st.chain_id.is_none() { + db::set_chain_id(&mut conn, node_chain).await?; + } + db::set_chain_meta(&mut conn, node_chain, &node_genesis).await?; + info!("indexing chain {} (genesis {})", node_chain, node_genesis); + ChainCheck::Same + } } + }; + let halted = check == ChainCheck::Halted; + { + let mut s = self.state.write().await; + if s.halted && !halted { + info!("the node is back on the indexed chain; indexing resumed"); + } + s.halted = halted; } - if reason.is_none() && self.genesis_changed().await? { - reason = Some("the node's genesis block differs from the indexed one".to_string()); - } + Ok(check) + } - self.chain_checked.store(true, Ordering::Relaxed); - let Some(reason) = reason else { - return Ok(false); - }; - warn!( - "{}; resetting chain data and re-indexing from height 0", - reason - ); - self.processor.reset_chain(node_chain).await?; + /// Drop the chain data, record `(chain_id, genesis)` as the indexed chain and forget every + /// cached read of the old chain. + async fn reset_to(&self, chain_id: i64, genesis: &str) -> Result<()> { + self.processor.reset_chain(chain_id).await?; + { + let mut conn = self.pool.inner().acquire().await?; + db::set_chain_meta(&mut conn, chain_id, genesis).await?; + } *self.chain.write().await = None; // symbol/decimals may differ too *self.bridge.write().await = None; *self.supply.write().await = None; @@ -221,19 +291,7 @@ impl IndexerService { *self.perps.write().await = None; *self.rand_price.write().await = None; self.state.write().await.current_height = -1; - Ok(true) - } - - /// True when the node's genesis block differs from the one indexed, i.e. the chain was - /// re-created (possibly under the same id) and rewinding block by block would never converge. - async fn genesis_changed(&self) -> Result { - let Some(stored) = db::get_block_hash_at(self.pool.inner(), 0).await? else { - return Ok(false); - }; - let Some(node) = self.rpc.block_by_height(0).await? else { - return Ok(false); - }; - Ok(!stored.eq_ignore_ascii_case(&node.hash)) + Ok(()) } /// One pass. Returns true when caught up (caller sleeps). @@ -245,15 +303,15 @@ impl IndexerService { s.is_connected = true; s.node_height = node_height; } - if self.ensure_chain(false).await? { - return Ok(false); + match self.check_chain().await? { + ChainCheck::Same => {} + ChainCheck::Reset => return Ok(false), + ChainCheck::Halted => return Ok(true), } + // A head below what we indexed, on the same chain, is a node that lost blocks or is + // still catching up after a restart: wait for it (the check above rules out a new chain). let next = db::get_indexer_state(self.pool.inner()).await?.next_height; - // A head below what we indexed means the node lost blocks or is another chain. - if next > node_height + 1 && self.ensure_chain(true).await? { - return Ok(false); - } let behind = node_height - next + 1; let catching_up = behind > 5; { @@ -295,9 +353,7 @@ impl IndexerService { "parent mismatch at {}: stored {} vs node {}", h, parent, block.parent ); - if !self.ensure_chain(true).await? { - self.processor.rewind_to(h - 1).await?; - } + self.processor.rewind_to(h - 1).await?; return Ok(false); } None => { diff --git a/migrations/015_chain_meta.sql b/migrations/015_chain_meta.sql new file mode 100644 index 0000000..743d2a5 --- /dev/null +++ b/migrations/015_chain_meta.sql @@ -0,0 +1,24 @@ +-- The chain the indexed data belongs to, by id *and* genesis hash (site-sync design, 2026-10-27). +-- One row, written by the indexer when it first reaches a node and on a reset to the pinned chain. +-- While the node reports a different chain id or genesis than this row, the indexer stops writing +-- and /api/v1/chain and /api/v1/health say so: two chains never share one database. +-- +-- A database that already holds blocks adopts what it holds: the chain id the indexer recorded +-- and the hash of block 0, which is the node's genesis hash (`rand_getGenesisHash` answers exactly +-- that). On the live explorer that is chain 21's genesis, so the first deploy carries on indexing +-- rather than refusing. A database without a block 0 or a recorded chain id starts with no row and +-- takes the node's identity on the indexer's first pass. + +CREATE TABLE chain_meta ( + id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1), + chain_id BIGINT NOT NULL, + genesis_hash VARCHAR(64) NOT NULL, + adopted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() +); + +INSERT INTO chain_meta (id, chain_id, genesis_hash) +SELECT 1, s.chain_id, LOWER(b.hash) +FROM indexer_state s +JOIN blocks b ON b.height = 0 +WHERE s.id = 1 AND s.chain_id IS NOT NULL; From f4badab8aa909c605758a7c2f11b98dc70d440b1 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 27 Oct 2026 11:34:59 +0800 Subject: [PATCH 3/5] =?UTF-8?q?tests:=20/api/v1/chain=20against=20a=20real?= =?UTF-8?q?=20rand-node=20=E2=80=94=20equal=20to=20the=20node's=20genesis?= =?UTF-8?q?=20and=20head,=20unreachable=20then=20stalled=20once=20the=20no?= =?UTF-8?q?de=20is=20killed,=20wrong=5Fchain=20with=20nothing=20written=20?= =?UTF-8?q?when=20pointed=20at=20a=20second=20dev=20chain;=20the=20CI=20re?= =?UTF-8?q?al-node=20job=20runs=20it=20beside=20the=20contract=20test?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two real-node tests share the database, so they now take turns behind one lock, and the binary/env gate both use is one function. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 7 +- crates/randscan-api/tests/real_node.rs | 206 +++++++++++++++++++++---- 2 files changed, 185 insertions(+), 28 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c3bc4ec..2292517 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -71,7 +71,10 @@ jobs: # transfer, a deploy and a confidential call (and an RPL-2 invoke where the build has it), and # compares the explorer's every public number with the node's — including the REST contract # zusd.money and randprotocol.org read (/bridge, /bridge/assets, /tokens/:index, /envelopes, - # /stats, /supply). It gates: the test skips a sub-check the released binary has no flag for + # /stats, /supply). The same step runs the site-sync case (`chain_view_follows_a_real_node`): + # GET /api/v1/chain equals the node's genesis and head, turns `unreachable` then `stalled` once + # the node is killed (a minute of waiting), and `wrong_chain` with nothing written when the + # explorer is pointed at a second dev chain. It gates: the test skips a sub-check the released binary has no flag for # (with a printed reason), never the whole run. The wallet proves under the chain's `test` FRI # profile in its own release binary, so the test itself builds in the default profile. real-node: @@ -129,7 +132,7 @@ jobs: echo "RAND_NODE_BIN=$RUNNER_TEMP/fullnode/rand-node" >> "$GITHUB_ENV" echo "RAND_CLI=$RUNNER_TEMP/fullnode/rand" >> "$GITHUB_ENV" - - name: Explorer against the real node + - name: Explorer against the real node (contract + site-sync /chain) run: cargo test -p randscan-api --test real_node -- --nocapture env: DATABASE_URL: postgres://randscan:randscan@localhost:5432/randscan diff --git a/crates/randscan-api/tests/real_node.rs b/crates/randscan-api/tests/real_node.rs index 1801484..f67ea30 100644 --- a/crates/randscan-api/tests/real_node.rs +++ b/crates/randscan-api/tests/real_node.rs @@ -10,10 +10,16 @@ //! the explorer's receipt (tier, outputs, `h_in`) against the node's — the proof is made under //! whatever zkVM constraint set the node was built with, so this is what notices a zkVM //! re-sync changing the receipt shape. +//! +//! A second, lighter test follows the site-sync view (`GET /api/v1/chain`): it equals the node's +//! genesis and head, turns `unreachable` and then `stalled` once the node is killed, and turns +//! `wrong_chain`, with the indexer writing nothing, when pointed at a second dev chain with a +//! different genesis. The two tests share the database, so they take turns. mod common; use common::*; +use randscan_core::ChainPin; use serde_json::{json, Value}; use std::path::PathBuf; use std::process::{Child, Command, Stdio}; @@ -24,6 +30,43 @@ const CHAIN_ID: u64 = 7701; /// The genesis treasury's balance, 100 RAND in units. const MULTISIG_TREASURY_BALANCE: &str = "100000000000"; +/// The two tests below share `DATABASE_URL`; each indexes its own chain from height 0. +static LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(()); + +/// The node and wallet binaries, or `None` (a skip) when `RAND_NODE_BIN` or `DATABASE_URL` is +/// unset; with `RANDSCAN_REQUIRE_REAL_NODE` (CI) a missing variable is a failure instead. +fn binaries() -> Option<(PathBuf, PathBuf)> { + // CI's `real-node` job sets RANDSCAN_REQUIRE_REAL_NODE so a lost variable fails the job + // instead of passing it as a skip. + let required = std::env::var_os("RANDSCAN_REQUIRE_REAL_NODE").is_some(); + let Ok(bin) = std::env::var("RAND_NODE_BIN") else { + assert!( + !required, + "RANDSCAN_REQUIRE_REAL_NODE is set but RAND_NODE_BIN is not" + ); + eprintln!("skipping: RAND_NODE_BIN unset"); + return None; + }; + if std::env::var("DATABASE_URL").is_err() { + assert!( + !required, + "RANDSCAN_REQUIRE_REAL_NODE is set but DATABASE_URL is not" + ); + eprintln!("skipping: DATABASE_URL unset"); + return None; + } + let bin = PathBuf::from(bin); + let cli = std::env::var("RAND_CLI") + .map(PathBuf::from) + .unwrap_or_else(|_| bin.with_file_name("rand")); + assert!( + cli.is_file(), + "no wallet CLI at {}: set RAND_CLI", + cli.display() + ); + Some((bin, cli)) +} + struct Node { child: Child, url: String, @@ -327,34 +370,10 @@ async fn start_node(bin: &PathBuf, cli: &PathBuf) -> (Node, String, String) { #[tokio::test] async fn explorer_agrees_with_a_real_shielded_node() { - // CI's `real-node` job sets RANDSCAN_REQUIRE_REAL_NODE so a lost variable fails the job - // instead of passing it as a skip. - let required = std::env::var_os("RANDSCAN_REQUIRE_REAL_NODE").is_some(); - let Ok(bin) = std::env::var("RAND_NODE_BIN") else { - assert!( - !required, - "RANDSCAN_REQUIRE_REAL_NODE is set but RAND_NODE_BIN is not" - ); - eprintln!("skipping: RAND_NODE_BIN unset"); + let Some((bin, cli)) = binaries() else { return; }; - if std::env::var("DATABASE_URL").is_err() { - assert!( - !required, - "RANDSCAN_REQUIRE_REAL_NODE is set but DATABASE_URL is not" - ); - eprintln!("skipping: DATABASE_URL unset"); - return; - } - let bin = PathBuf::from(bin); - let cli = std::env::var("RAND_CLI") - .map(PathBuf::from) - .unwrap_or_else(|_| bin.with_file_name("rand")); - assert!( - cli.is_file(), - "no wallet CLI at {}: set RAND_CLI", - cli.display() - ); + let _g = LOCK.lock().await; let client = reqwest::Client::new(); let (node, validator_addr, _wallet_addr) = start_node(&bin, &cli).await; let wallet = node.dir.path().join("wallet.key.json"); @@ -770,6 +789,141 @@ async fn explorer_agrees_with_a_real_shielded_node() { drop(node); } +/// `GET /api/v1/chain` against real nodes (site-sync design §6). No transactions: a node that +/// commits empty blocks is all the view needs. +#[tokio::test] +async fn chain_view_follows_a_real_node() { + let Some((bin, cli)) = binaries() else { + return; + }; + let _g = LOCK.lock().await; + let client = reqwest::Client::new(); + let (node, _, _) = start_node(&bin, &cli).await; + let genesis = rpc(&client, &node.url, "rand_getGenesisHash", json!([])).await; + let genesis = genesis.as_str().unwrap().to_ascii_lowercase(); + let block0 = rpc(&client, &node.url, "rand_getBlockByHeight", json!([0])).await; + assert_eq!( + block0["hash"].as_str().unwrap().to_ascii_lowercase(), + genesis, + "rand_getGenesisHash is block 0's hash (migration 015 adopts block 0's hash on that basis)" + ); + let pin = ChainPin::new(CHAIN_ID as i64, &genesis); + let Some(live) = live_app_pinned(test_config(), &node.url, "127.0.0.1", pin.clone()).await + else { + return; + }; + { + let mut conn = live.pool.acquire().await.unwrap(); + randscan_db::reset_chain_data(&mut conn, 0).await.unwrap(); + } + live.start(); + + // Live: the stored chain is the node's, and the head is a block the node serves. + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| { + c["state"] == "live" && c["head_height"].as_i64().unwrap_or(0) >= 3 + }) + .await; + assert_eq!(ch["chain_id"], CHAIN_ID); + assert_eq!(ch["genesis_hash"], genesis); + assert_eq!(ch["node_genesis_hash"], genesis); + assert_eq!(ch["node_chain_id"], CHAIN_ID); + assert_eq!(ch["halted"], false); + let head_height = ch["head_height"].as_u64().unwrap(); + let node_block = rpc( + &client, + &node.url, + "rand_getBlockByHeight", + json!([head_height]), + ) + .await; + assert_eq!(ch["head_timestamp_ms"], node_block["timestamp_ms"], "{ch}"); + let node_head = rpc(&client, &node.url, "rand_getHead", json!([])).await["height"] + .as_i64() + .unwrap(); + let node_height = ch["node_height"].as_i64().unwrap(); + assert!( + node_height <= node_head && node_head - node_height <= 10, + "/chain's node_height {node_height} tracks the node's head {node_head}" + ); + assert!(ch["lag"].as_i64().unwrap() <= 10, "{ch}"); + let (_, _, b) = call( + &live.app, + json_req("GET", &format!("/api/v1/blocks/{head_height}"), None, None), + ) + .await; + assert_eq!(b["hash"], node_block["hash"]); + let health = live + .wait_for("/api/v1/health", WAIT, |h| h["status"] == "healthy") + .await; + assert_eq!(health["genesis_hash"], genesis); + assert_eq!(health["stalled"], false); + assert_eq!(health["wrong_chain"], false); + + // The node is killed: unreachable while the last head is fresh, stalled once it is older + // than STALL_MS (60 s). + drop(node); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| c["state"] == "unreachable") + .await; + assert_eq!(ch["node_connected"], false); + let last = ch["head_height"].clone(); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| c["state"] == "stalled") + .await; + assert_eq!(ch["head_height"], last, "the last good height stays: {ch}"); + let (_, _, health) = call(&live.app, json_req("GET", "/api/v1/health", None, None)).await; + assert_eq!(health["stalled"], true); + assert_eq!(health["status"], "degraded"); + + // A second dev chain (same id, its own validator, so another genesis): the explorer, still + // pinned to the first, is restarted against it. It writes nothing and reports wrong_chain. + let (node2, _, _) = start_node(&bin, &cli).await; + let genesis2 = rpc(&client, &node2.url, "rand_getGenesisHash", json!([])).await; + let genesis2 = genesis2.as_str().unwrap().to_ascii_lowercase(); + assert_ne!(genesis2, genesis); + let (blocks_before, max_before): (i64, Option) = + sqlx::query_as("SELECT COUNT(*), MAX(height) FROM blocks") + .fetch_one(&live.pool) + .await + .unwrap(); + let live = live.restart(&node2.url, pin); + let ch = live + .wait_for("/api/v1/chain", WAIT, |c| c["halted"] == true) + .await; + assert_eq!(ch["state"], "wrong_chain", "{ch}"); + assert_eq!(ch["genesis_hash"], genesis); + assert_eq!(ch["node_genesis_hash"], genesis2); + // Let the second chain grow past the first's head; still nothing is written. + let start = std::time::Instant::now(); + while rpc(&client, &node2.url, "rand_getHead", json!([])).await["height"] + .as_i64() + .unwrap() + <= max_before.unwrap_or(0) + 2 + { + assert!(start.elapsed() < WAIT * 2, "the second chain did not grow"); + tokio::time::sleep(Duration::from_millis(250)).await; + } + let (blocks_after, max_after): (i64, Option) = + sqlx::query_as("SELECT COUNT(*), MAX(height) FROM blocks") + .fetch_one(&live.pool) + .await + .unwrap(); + assert_eq!( + (blocks_after, max_after), + (blocks_before, max_before), + "no block of the second chain was written" + ); + let (_, _, b0) = call(&live.app, json_req("GET", "/api/v1/blocks/0", None, None)).await; + assert_eq!( + b0["hash"].as_str().map(str::to_ascii_lowercase), + Some(genesis) + ); + let (_, _, health) = call(&live.app, json_req("GET", "/api/v1/health", None, None)).await; + assert_eq!(health["wrong_chain"], true); + assert_eq!(health["status"], "degraded"); +} + /// Fullnode v0.8.0 multisig on a chain whose genesis seeds a 1-of-1 treasury: a payment out of it /// (`rand-node multisig pay prepare|sign|submit`, bundle-less) and a new account (`rand multisig /// create`, one bundle proof). Then the explorer's view against the node's: both kinds with their From 982abeebbee8f1394f46f2c53e5e0f3d22f5a78b Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 27 Oct 2026 11:35:00 +0800 Subject: [PATCH 4/5] frontend: the chain pill under the header and a red role="alert" banner on every page, from /api/v1/chain every 15 s, classified against the build's pin (src/lib/chainPin.ts) by a pure classifier with node:test coverage; the pin printed as / in every page's HTML; Health typed with the new fields; 20 languages The pill has its own line under the top bar: the bar is already full at every width, and the pill in it widened a phone page to 436 px. The banner keeps the page's numbers visible and names the last good block and its age. Co-Authored-By: Claude Opus 5.5 --- frontend/src/app/[lang]/layout.tsx | 4 + frontend/src/app/globals.css | 10 + frontend/src/components/ChainMeta.ts | 14 ++ frontend/src/components/ChainStatus.tsx | 93 +++++++++ frontend/src/components/Header.tsx | 7 + frontend/src/hooks/useApi.ts | 13 ++ frontend/src/i18n/messages/.source/ar.json | 17 ++ frontend/src/i18n/messages/.source/de.json | 17 ++ frontend/src/i18n/messages/.source/es.json | 17 ++ frontend/src/i18n/messages/.source/fa.json | 17 ++ frontend/src/i18n/messages/.source/fr.json | 17 ++ frontend/src/i18n/messages/.source/hi.json | 17 ++ frontend/src/i18n/messages/.source/id.json | 17 ++ frontend/src/i18n/messages/.source/it.json | 17 ++ frontend/src/i18n/messages/.source/ja.json | 17 ++ frontend/src/i18n/messages/.source/ko.json | 17 ++ frontend/src/i18n/messages/.source/ms.json | 17 ++ frontend/src/i18n/messages/.source/pl.json | 17 ++ frontend/src/i18n/messages/.source/ps.json | 17 ++ frontend/src/i18n/messages/.source/pt.json | 17 ++ frontend/src/i18n/messages/.source/ru.json | 17 ++ frontend/src/i18n/messages/.source/ta.json | 17 ++ frontend/src/i18n/messages/.source/ur.json | 17 ++ frontend/src/i18n/messages/.source/zh-hk.json | 17 ++ frontend/src/i18n/messages/.source/zh.json | 17 ++ frontend/src/i18n/messages/ar.json | 23 +++ frontend/src/i18n/messages/de.json | 23 +++ frontend/src/i18n/messages/en.json | 23 +++ frontend/src/i18n/messages/es.json | 23 +++ frontend/src/i18n/messages/fa.json | 23 +++ frontend/src/i18n/messages/fr.json | 23 +++ frontend/src/i18n/messages/hi.json | 23 +++ frontend/src/i18n/messages/id.json | 23 +++ frontend/src/i18n/messages/it.json | 23 +++ frontend/src/i18n/messages/ja.json | 23 +++ frontend/src/i18n/messages/ko.json | 23 +++ frontend/src/i18n/messages/ms.json | 23 +++ frontend/src/i18n/messages/pl.json | 23 +++ frontend/src/i18n/messages/ps.json | 23 +++ frontend/src/i18n/messages/pt.json | 23 +++ frontend/src/i18n/messages/ru.json | 23 +++ frontend/src/i18n/messages/ta.json | 23 +++ frontend/src/i18n/messages/ur.json | 23 +++ frontend/src/i18n/messages/zh-hk.json | 23 +++ frontend/src/i18n/messages/zh.json | 23 +++ frontend/src/lib/api.ts | 6 + frontend/src/lib/chainPin.ts | 24 +++ frontend/src/lib/chainStatus.ts | 139 ++++++++++++++ frontend/src/types/index.ts | 12 +- frontend/tests/chain-status.test.mjs | 176 ++++++++++++++++++ 50 files changed, 1280 insertions(+), 1 deletion(-) create mode 100644 frontend/src/components/ChainMeta.ts create mode 100644 frontend/src/components/ChainStatus.tsx create mode 100644 frontend/src/lib/chainPin.ts create mode 100644 frontend/src/lib/chainStatus.ts create mode 100644 frontend/tests/chain-status.test.mjs diff --git a/frontend/src/app/[lang]/layout.tsx b/frontend/src/app/[lang]/layout.tsx index 98883ed..8c78170 100644 --- a/frontend/src/app/[lang]/layout.tsx +++ b/frontend/src/app/[lang]/layout.tsx @@ -3,6 +3,8 @@ import localFont from 'next/font/local'; import { notFound } from 'next/navigation'; import { Header } from '@/components/Header'; import { Footer } from '@/components/Footer'; +import { ChainBanner } from '@/components/ChainStatus'; +import { ChainMeta } from '@/components/ChainMeta'; import { I18nProvider } from '@/i18n/client'; import { getMessages } from '@/i18n/messages'; import { LOCALE_CODES, isLocale, localeInfo, localizePath } from '@/i18n/locales'; @@ -85,6 +87,7 @@ export default async function RootLayout({ +