{"record":{"id":"b4d8a3b4a9a4b4a7","repo":"nautechsystems/nautilus_trader","slug":"verified-finalized-headers-do-not-start-at-the-tru","errorCode":null,"errorMessage":"Verified finalized headers do not start at the trusted checkpoint","messagePattern":"Verified finalized headers do not start at the trusted checkpoint","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":4448,"sourceCode":"                .fetch_one(&mut *transaction)\n                .await\n                .map_err(|e| anyhow::anyhow!(\"Failed to lock finalized header tip: {e}\"))?;\n            anyhow::ensure!(\n                stored_tip\n                    == (\n                        i64::try_from(first_header.number)\n                            .context(\"Verified finalized height exceeds PostgreSQL BIGINT\")?,\n                        first_header.hash.clone(),\n                        first_header.parent_hash.clone(),\n                        i64::try_from(first_header.timestamp)\n                            .context(\"Verified finalized timestamp exceeds PostgreSQL BIGINT\")?,\n                        first_header.base_fee_per_gas.map(|value| value.to_string()),\n                        bootstrap.manifest_digest.to_string(),\n                    ),\n                \"Verified finalized header extension does not start at the durable tip\"\n            );\n        } else {\n            anyhow::ensure!(\n                first_header.number == bootstrap.checkpoint_number\n                    && first_header.hash == bootstrap.checkpoint_hash\n                    && first_header.parent_hash == bootstrap.checkpoint_parent_hash\n                    && first_header.timestamp == bootstrap.checkpoint_timestamp\n                    && first_header.base_fee_per_gas == bootstrap.checkpoint_base_fee_per_gas,\n                \"Verified finalized headers do not start at the trusted checkpoint\"\n            );\n        }\n\n        for header in bootstrap.finalized_headers.iter().skip(1) {\n            let number = i64::try_from(header.number)\n                .context(\"Verified finalized height exceeds PostgreSQL BIGINT\")?;\n            let timestamp = i64::try_from(header.timestamp)\n                .context(\"Verified finalized timestamp exceeds PostgreSQL BIGINT\")?;\n            let base_fee = header.base_fee_per_gas.map(|value| value.to_string());\n            sqlx::query(\n                \"\n                INSERT INTO execution_verified_finalized_header (","sourceCodeStart":4430,"sourceCodeEnd":4466,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/cache/database.rs#L4430-L4466","documentation":"This error is raised when the verified-finalized header ledger is being initialized for the first time (no existing rows, `initialized == false`). The first header of the incoming verified batch must exactly equal the trusted bootstrap checkpoint (number, hash, parent_hash, timestamp, base_fee_per_gas); otherwise the entire ledger would be anchored to a header that is not the trusted checkpoint. The code `anyhow::ensure!`s this equality inside the transaction and aborts on mismatch, preventing the ledger from ever being seeded from an untrusted starting point.","triggerScenarios":"Calling the verified-finalized bootstrap against an empty ledger while the first entry of `bootstrap.finalized_headers` differs from `bootstrap.checkpoint_*` fields: starting the batch at a height above the checkpoint, a different hash/parent_hash at the checkpoint height, differing timestamp or base_fee_per_gas, or supplying checkpoint metadata from a different chain/manifest than the header batch.","commonSituations":"Misconfigured checkpoint values (stale or hand-edited checkpoint hash/number in config); checkpoint taken from a different network (e.g. sepolia vs mainnet) than the data source; provider returning verified headers starting after the checkpoint; timestamp/base-fee fields normalized differently between the checkpoint source and the header source (e.g. zero vs None base fee).","solutions":["Verify `bootstrap.checkpoint_number/hash/parent_hash/timestamp/base_fee_per_gas` against the first header of the verified batch and make the batch start exactly at the checkpoint height.","Re-fetch checkpoint metadata from the trusted source (consensus checkpoint API or configured anchor) so it matches the headers the provider actually returns.","Confirm chain_id and network configuration match between the checkpoint definition and the RPC/data provider.","If the checkpoint itself is wrong/outdated, update the configured trusted checkpoint to one the verified header stream can begin from, then re-run initialization.","Normalize base_fee representation (None vs zero) so checkpoint and header values compare equal."],"exampleFix":"// before: checkpoint and batch start diverge\nlet checkpoint = Checkpoint { number: 1_000, hash: 0xa1.. };\nlet headers = fetch_verified_finalized(from: 1_050);\n\n// after: seed the batch from the trusted checkpoint itself\nlet checkpoint = load_trusted_checkpoint(chain_id)?;\nlet headers = fetch_verified_finalized(from: checkpoint.number);\nassert_eq!(headers[0].number, checkpoint.number);\nassert_eq!(headers[0].hash, checkpoint.hash);\npersist_finalized_headers(headers).await?;","handlingStrategy":"validation","validationCode":"fn matches_trusted_checkpoint(first: &VerifiedHeader, cp: &Checkpoint) -> bool {\n    first.number == cp.number\n        && first.hash == cp.hash\n        && first.parent_hash == cp.parent_hash\n        && first.timestamp == cp.timestamp\n        && first.base_fee_per_gas == cp.base_fee_per_gas\n}\n// call before bootstrapping an empty ledger\nassert!(matches_trusted_checkpoint(&headers[0], &checkpoint), \"batch must start at trusted checkpoint\");","typeGuard":"fn starts_at_checkpoint(headers: &[VerifiedHeader], cp: &Checkpoint) -> bool {\n    headers.first().map(|h| h.number == cp.number && h.hash == cp.hash).unwrap_or(false)\n}","tryCatchPattern":"match bootstrap_verified_finalized(&pool, &bootstrap).await {\n    Err(e) if e.to_string().contains(\"do not start at the trusted checkpoint\") => {\n        // reload checkpoint metadata or refetch headers from checkpoint height\n    }\n    Err(e) => return Err(e),\n    Ok(()) => {}\n}","preventionTips":["Derive the verified batch start from the configured checkpoint, never from an arbitrary snapshot height.","Validate checkpoint number/hash against the trusted source at startup.","Ensure chain_id and network match between checkpoint config and data provider.","Normalize base_fee (None vs zero) before comparing checkpoint and header values."],"tags":["database","blockchain","checkpoint","data-integrity"],"backgroundTag":"invalid-argument-value","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"}