{"record":{"id":"7f7749fab12e24fb","repo":"nautechsystems/nautilus_trader","slug":"verified-finalized-header-ledger-mismatch-for-heig","errorCode":null,"errorMessage":"Verified finalized header ledger mismatch for height {number}","messagePattern":"Verified finalized header ledger mismatch for height (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"critical","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":7028,"sourceCode":"            .bind(&base_fee)\n            .bind(finality.manifest_digest)\n            .execute(&mut *transaction)\n            .await\n            .map_err(|e| anyhow::anyhow!(\"Failed to extend finalized header ledger: {e}\"))?;\n            let stored = sqlx::query_as::<_, (String, String, i64, Option<String>, String)>(\n                \"\n                SELECT hash, parent_hash, timestamp, base_fee_per_gas, manifest_digest\n                FROM execution_verified_finalized_header\n                WHERE chain_id = $1 AND wallet_address = $2 AND number = $3\n                \",\n            )\n            .bind(chain_id)\n            .bind(finality.wallet_address)\n            .bind(number)\n            .fetch_one(&mut *transaction)\n            .await\n            .map_err(|e| anyhow::anyhow!(\"Failed to validate finalized header ledger: {e}\"))?;\n            anyhow::ensure!(\n                stored\n                    == (\n                        header.hash.clone(),\n                        header.parent_hash.clone(),\n                        timestamp,\n                        base_fee,\n                        finality.manifest_digest.to_string(),\n                    ),\n                \"Finalized header ledger conflicts at height {}\",\n                header.number\n            );\n        }\n\n        let (current_status, intent_nonce, fill_emitted, terminal_emitted) =\n            sqlx::query_as::<_, (String, Option<i64>, bool, bool)>(\n                \"\n                SELECT status, nonce, fill_emitted, terminal_emitted\n                FROM execution_intent","sourceCodeStart":7010,"sourceCodeEnd":7046,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/cache/database.rs#L7010-L7046","documentation":"This is a data-integrity assertion: after inserting and reading back the finalized header ledger row, the code ensure()s the stored tuple (hash, parent_hash, timestamp, base_fee_per_gas, manifest_digest) equals what was intended to write. A mismatch means the ledger row at this height differs from the header being verified — i.e. the append-only invariant of the verified header ledger was violated. It indicates either a conflicting header for the same height or corrupted/stale ledger data.","triggerScenarios":"Re-verifying a height whose ledger row already exists with a different hash/parent_hash (chain reorg or fork); a prior partial/corrupt write; recomputing timestamp/base_fee/manifest_digest differently than when the row was first stored; a wrong wallet_address or chain_id scoping pulling in a foreign row.","commonSituations":"Replaying finality events after a node switched to a different chain branch (reorg); backfilling historical headers over rows recorded from another source; mixing testnet/mainnet data under the same chain_id; a code change altering manifest_digest computation between the original write and re-verification.","solutions":["Compare the stored tuple in the error context with the incoming header values to identify which field diverged","If a legitimate reorg occurred, clear/rebuild the ledger rows for the affected heights from the authoritative source before reprocessing","Confirm chain_id and wallet_address scoping are correct — the mismatch may be a foreign row","Ensure manifest_digest and base_fee computation is deterministic and unchanged since the original write","Treat as a integrity alarm: do not overwrite the ledger row silently; investigate which writer produced the divergent header"],"exampleFix":"// before\nanyhow::ensure!(\n    stored == (header.hash.clone(), header.parent_hash.clone(), timestamp, base_fee, finality.manifest_digest),\n    \"Verified finalized header ledger mismatch for height {number}\"\n);\n// after\nlet expected = (header.hash.clone(), header.parent_hash.clone(), timestamp, base_fee, finality.manifest_digest);\nanyhow::ensure!(\n    stored == expected,\n    \"Verified finalized header ledger mismatch for height {number}: stored={stored:?} expected={expected:?}\"\n);","handlingStrategy":"validation","validationCode":"// Before writing, check for a conflicting ledger row\nlet existing = sqlx::query_as::<_, (String, String)>(\n    \"SELECT hash, parent_hash FROM execution_verified_finalized_header \\\n     WHERE chain_id = $1 AND wallet_address = $2 AND number = $3\"\n)\n.bind(chain_id).bind(finality.wallet_address).bind(number)\n.fetch_optional(&mut *conn).await?;\nif let Some((hash, parent)) = &existing {\n    if *hash != header.hash || *parent != header.parent_hash {\n        return Err(anyhow!(\"reorg/conflict detected at height {number}\"));\n    }\n}","typeGuard":"fn ledger_matches(stored: &(String, String, i64, Option<String>, String),\n                   expected: &(String, String, i64, Option<String>, String)) -> bool {\n    stored == expected\n}","tryCatchPattern":"match apply_verified_finality(...).await {\n    Err(e) if e.to_string().contains(\"ledger mismatch\") => {\n        // halt processing for this chain and alert — possible reorg or corrupt ledger\n        alert_ops(\"verified header ledger integrity violation\");\n        Err(e)\n    }\n    other => other,\n}","preventionTips":["Never overwrite ledger rows; treat mismatches as reorg/corruption alarms","Track chain reorgs and rebuild the ledger segment for re-parented heights","Keep manifest_digest computation versioned and deterministic","Ensure single writer per (chain_id, wallet) to avoid divergent headers"],"tags":["integrity","consensus","database","invariant"],"backgroundTag":"checksum-mismatch","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}