fix: validate complete watchdog state on idempotent init; add permissive CORS

Idempotent init now requires readable config.json and a non-empty checkpoint
snapshot before exit 0, so supervisors are not told success on unusable
state. Document LONG_BLOCK_RANGE_ERROR_CODES as init-only. Enable
CorsLayer::permissive for browser POST /tx.

Author: stephenctw

README.md

@@ -146,6 +146,7 @@ Notes:
 - payload size is bounded at ingress; oversized requests are rejected before entering the hot path.
 - overload is enforced at queue admission: if the inclusion-lane queue is full, `POST /tx` returns HTTP `429` with code `OVERLOADED` and message `queue full`.
 - queue capacity is an internal runtime constant tuned alongside inclusion-lane chunking to absorb short bursts; if this starts triggering persistently, it is a signal to revisit runtime sizing or throughput rather than add another admission layer.
+- CORS is currently **permissive** (`Access-Control-Allow-Origin: *`, all methods/headers) so browser wallets can call `POST /tx`. Tighten once the planned ingress/egress port split lands.
 
 ### `GET /ws/subscribe?from_offset=<u64>`
 

docs/watchdog/README.md

@@ -182,7 +182,7 @@ the chain id explicitly).
 The watchdog has two subcommands:
 
 ```bash
-sequencer-watchdog init   # setup: writes config.json + head.json (idempotent)
+sequencer-watchdog init   # setup: writes config.json + head.json (idempotent if complete)
 sequencer-watchdog tick   # one compare cycle; schedule this
 ```
 

docs/watchdog/operator-deployment.md

@@ -160,6 +160,7 @@ Today `WalletApp::default()` / `WalletConfig::sepolia()` align with Sepolia stag
 | `CARTESI_WATCHDOG_BLOCKCHAIN_ID` | Chain id label for `status.prom` metrics (prefer set at `init`; optional auto-detect via `eth_chainId` when L1 endpoint is present at `init`) |
 | `CARTESI_WATCHDOG_METRICS_FILE` | Override path for the Prometheus textfile written by each `tick` |
 | `CARTESI_WATCHDOG_LUA_DEPS` | `.deps/lua` |
+| `CARTESI_WATCHDOG_LONG_BLOCK_RANGE_ERROR_CODES` | Optional CSV of RPC error codes that trigger `eth_getLogs` partition retry. **Evaluated only at `init` and persisted in `config.json`** — not a tick-time override; re-running idempotent `init` does not refresh it. Wipe state and re-init (or edit `config.json`) to change. Default matches the sequencer: `-32005,-32012,-32600,-32602,-32616`. |
 
 The sequencer discovers and pins `input_box_address` at startup; use the same values as `CARTESI_SEQUENCER_BLOCKCHAIN_HTTP_ENDPOINT` / `CARTESI_SEQUENCER_APP_ADDRESS` configuration.
 
@@ -174,13 +175,15 @@ Pick one:
 3. **Replay from genesis** (only for new rollups / low block height — slow).
 
 Run `init` once to store the bootstrap CM snapshot into the watchdog state
-layout. Re-running `init` on an already-initialized state directory is a no-op
-success (exit `0`), matching `sequencer setup` — safe for process supervisors
-that always invoke init before tick. The L1 RPC URL is not persisted — each
-`tick` reads `CARTESI_WATCHDOG_BLOCKCHAIN_HTTP_ENDPOINT` so it can rotate
-without editing state. If `CARTESI_WATCHDOG_BLOCKCHAIN_ID` is unset at `init`,
-auto-detect also needs that endpoint present then (prefer setting the chain id
-explicitly):
+layout. Re-running `init` on a **complete** already-initialized state directory
+is a no-op success (exit `0`), matching `sequencer setup` — safe for process
+supervisors that always invoke init before tick. If `head.json` exists but
+`config.json` or the selected snapshot is missing/corrupt, `init` fails (exit
+`1`) and asks you to wipe `state_dir` and re-run — it will not certify an
+unusable state. The L1 RPC URL is not persisted — each `tick` reads
+`CARTESI_WATCHDOG_BLOCKCHAIN_HTTP_ENDPOINT` so it can rotate without editing
+state. If `CARTESI_WATCHDOG_BLOCKCHAIN_ID` is unset at `init`, auto-detect also
+needs that endpoint present then (prefer setting the chain id explicitly):
 
 ```bash
 sequencer-watchdog init

sequencer/Cargo.toml

@@ -18,7 +18,7 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 toml = "0.8"
 tracing = "0.1"
-tower-http = { version = "0.6.8", features = ["trace"] }
+tower-http = { version = "0.6.8", features = ["trace", "cors"] }
 rusqlite = { version = "0.38.0", features = ["bundled"] }
 rusqlite_migration = "2.3.0"
 alloy-primitives = { version = "1.4.1", features = ["serde", "k256"] }

sequencer/src/http.rs

@@ -21,6 +21,7 @@ use axum::response::{IntoResponse, Response};
 use serde::Serialize;
 use thiserror::Error;
 use tokio::sync::mpsc;
+use tower_http::cors::CorsLayer;
 use tower_http::trace::TraceLayer;
 
 pub use crate::egress::api::SnapshotState;
@@ -228,7 +229,10 @@ pub fn start_on_listener(
         ))
         // Enforces a raw request-body cap before JSON deserialization, including whitespace.
         .layer(DefaultBodyLimit::max(config.max_body_bytes))
-        .layer(TraceLayer::new_for_http());
+        .layer(TraceLayer::new_for_http())
+        // Permissive CORS so browser wallets can POST /tx (and preflight OPTIONS).
+        // Tighten when the ingress/egress port split lands and public exposure is narrower.
+        .layer(CorsLayer::permissive());
 
     tokio::spawn(async move {
         axum::serve(listener, app)

sequencer/tests/snapshot_endpoints.rs

@@ -522,3 +522,33 @@ async fn latest_snapshot_falls_back_to_finalized_when_no_pending() {
 
     assert!(wait_for_lease(db.path.as_str(), fin_id, 0).await);
 }
+
+#[tokio::test]
+async fn cors_permits_browser_preflight_on_tx() {
+    let db = temp_db("cors-preflight");
+    let Some(server) = start_server(db.path.as_str()).await else {
+        return;
+    };
+
+    let resp = reqwest::Client::new()
+        .request(reqwest::Method::OPTIONS, server.url("/tx"))
+        .header("Origin", "https://wallet.example")
+        .header("Access-Control-Request-Method", "POST")
+        .header("Access-Control-Request-Headers", "content-type")
+        .send()
+        .await
+        .expect("OPTIONS /tx");
+
+    assert!(
+        resp.status().is_success(),
+        "preflight status: {}",
+        resp.status()
+    );
+    let allow_origin = resp
+        .headers()
+        .get("access-control-allow-origin")
+        .expect("Access-Control-Allow-Origin")
+        .to_str()
+        .expect("header utf8");
+    assert_eq!(allow_origin, "*");
+}

watchdog/config.lua

@@ -125,6 +125,21 @@ function config.persisted(cfg)
     }
 end
 
+--- Validate a persisted config.json object (no tick-time env required).
+--- Raises on missing/invalid fields; used by idempotent init before exit 0.
+function config.validate_persisted(data)
+    if type(data) ~= "table" then
+        error("config.json is not an object")
+    end
+    if data.version ~= config.VERSION then
+        error("unsupported config.json version: " .. tostring(data.version))
+    end
+    required_field(data, "sequencer_url")
+    required_field(data, "input_box_address")
+    required_field(data, "app_address")
+    return true
+end
+
 function config.from_persisted(state_dir, data, env)
     env = normalize_env(env)
     if data.version ~= config.VERSION then

watchdog/main.lua

@@ -106,15 +106,56 @@ local function default_deps(cfg)
     return deps, json
 end
 
+local function shell_quote(value)
+    value = tostring(value)
+    return "'" .. value:gsub("'", "'\\''") .. "'"
+end
+
+--- True when `path` is a non-empty directory (CM snapshot must have content).
+local function directory_nonempty(path)
+    local quoted = shell_quote(path)
+    local ok = os.execute("test -d " .. quoted .. " && test -n \"$(ls -A " .. quoted .. " 2>/dev/null)\"")
+    return ok == true or ok == 0
+end
+
+--- Require a complete, tick-usable state before reporting idempotent init success.
+--- A valid head.json alone is not enough — config.json or the selected snapshot
+--- may be missing/corrupt after a partial wipe.
+local function validate_initialized_state(state_dir, existing, json)
+    local persisted, cfg_err = state.read_json(state_dir, "config.json", json)
+    if not persisted then
+        return nil,
+            "incomplete watchdog state: missing or unreadable config.json ("
+                .. tostring(cfg_err)
+                .. ")"
+    end
+    local ok, validate_err = pcall(config.validate_persisted, persisted)
+    if not ok then
+        return nil, "incomplete watchdog state: " .. tostring(validate_err)
+    end
+    if type(existing.snapshot_dir) ~= "string" or existing.snapshot_dir == "" then
+        return nil, "incomplete watchdog state: head has no snapshot_dir"
+    end
+    if not directory_nonempty(existing.snapshot_dir) then
+        return nil,
+            "incomplete watchdog state: missing or empty snapshot at "
+                .. tostring(existing.snapshot_dir)
+    end
+    return true
+end
+
 local function run_init(cfg, deps)
     deps = deps or default_machine_deps(cfg)
     local json = json_mod.new()
 
     local existing, load_err = checkpoint.load(cfg.state_dir)
     if existing then
-        -- Idempotent like `sequencer setup`: re-init on an already-set-up
-        -- state dir is a no-op success so process supervisors can run init
-        -- unconditionally without wrapping exit codes.
+        local usable, why = validate_initialized_state(cfg.state_dir, existing, json)
+        if not usable then
+            return nil, tostring(why) .. "; wipe state_dir and re-run init"
+        end
+        -- Idempotent like `sequencer setup`: complete state → no-op success so
+        -- process supervisors can run init unconditionally.
         return {
             ok = true,
             already_initialized = true,

watchdog/tests/run.lua

@@ -521,6 +521,13 @@ local function fake_machine(inspect_state)
     function machine:dump(_instance, snapshot_dir, reference_block)
         self.saved_snapshot_dir = snapshot_dir
         _instance.reference_block = reference_block
+        -- Real CM dumps create a non-empty snapshot dir; mirror that so
+        -- idempotent-init usability checks see a complete state.
+        os.execute("mkdir -p " .. "'" .. tostring(snapshot_dir):gsub("'", "'\\''") .. "'")
+        local marker = io.open(snapshot_dir .. "/.dump", "w")
+        assert(marker, "write snapshot marker")
+        marker:write("ok")
+        marker:close()
         return true
     end
     function machine:feed_inputs(instance, inputs)
@@ -976,6 +983,41 @@ test("init is a no-op success when state is already initialized", function()
     assert_eq(second.safe_block, first.safe_block)
 end)
 
+test("init fails when config.json is missing after head exists", function()
+    local dir = os.tmpname()
+    os.remove(dir)
+
+    local cfg = fake_cfg()
+    cfg.state_dir = dir
+    local first, first_err = main_mod.run_init(cfg, { machine = fake_machine("{}") })
+    assert(first, first_err)
+
+    assert(os.remove(dir .. "/config.json"))
+
+    local second, second_err = main_mod.run_init(cfg, { machine = fake_machine("{}") })
+    assert_eq(second, nil)
+    assert(tostring(second_err):find("config.json", 1, true), tostring(second_err))
+    assert(tostring(second_err):find("wipe state_dir", 1, true), tostring(second_err))
+end)
+
+test("init fails when checkpoint snapshot is missing after head exists", function()
+    local dir = os.tmpname()
+    os.remove(dir)
+
+    local cfg = fake_cfg()
+    cfg.state_dir = dir
+    local first, first_err = main_mod.run_init(cfg, { machine = fake_machine("{}") })
+    assert(first, first_err)
+
+    local loaded = assert(checkpoint.load(dir))
+    assert(os.execute("rm -rf '" .. loaded.snapshot_dir:gsub("'", "'\\''") .. "'"))
+
+    local second, second_err = main_mod.run_init(cfg, { machine = fake_machine("{}") })
+    assert_eq(second, nil)
+    assert(tostring(second_err):find("snapshot", 1, true), tostring(second_err))
+    assert(tostring(second_err):find("wipe state_dir", 1, true), tostring(second_err))
+end)
+
 test("runner happy path replays inputs and writes checkpoint", function()
     local checkpoint_writes = {}
     local checkpoint_mod = {