{"record":{"id":"c19a690859f8e465","repo":"nautechsystems/nautilus_trader","slug":"finality-transaction-hash-was-not-found","errorCode":null,"errorMessage":"Finality transaction hash was not found","messagePattern":"Finality transaction hash was not found","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":7131,"sourceCode":"            UPDATE execution_transaction_hash\n            SET status = $3, block_number = $4, block_hash = $5,\n                receipt_success = $6, gas_used = $7, effective_gas_price = $8,\n                updated_at = NOW()\n            WHERE intent_id = $1 AND transaction_hash = $2\n            \",\n        )\n        .bind(finality.intent_id)\n        .bind(finality.transaction_hash)\n        .bind(finality.status.as_str())\n        .bind(block_number)\n        .bind(finality.block_hash)\n        .bind(finality.receipt_success)\n        .bind(gas_used)\n        .bind(finality.effective_gas_price)\n        .execute(&mut *transaction)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to record verified finality receipt: {e}\"))?;\n        anyhow::ensure!(\n            hash_result.rows_affected() == 1,\n            \"Finality transaction hash was not found\"\n        );\n\n        let active = !fill_emitted && !terminal_emitted;\n        sqlx::query(\n            \"UPDATE execution_intent SET status = $2, active = $3, updated_at = NOW() WHERE id = $1\",\n        )\n        .bind(finality.intent_id)\n        .bind(finality.status.as_str())\n        .bind(active)\n        .execute(&mut *transaction)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to record verified finality intent: {e}\"))?;\n\n        let transition_key = format!(\n            \"{}:{}:{}:{}\",\n            finality.status.as_str(),","sourceCodeStart":7113,"sourceCodeEnd":7149,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/cache/database.rs#L7113-L7149","documentation":"An assertion that the UPDATE of `execution_transaction_hash` (status, block_number, block_hash) affected exactly one row. Zero affected rows means no transaction-hash record exists for this finality's transaction hash, so the receipt cannot be attached to a known transaction and the finality commit aborts. It is a referential-integrity check against the transaction-hash ledger.","triggerScenarios":"Finality arriving for a transaction hash never recorded in `execution_transaction_hash`; the row was scoped to a different chain_id/wallet in the UPDATE's WHERE clause; a truncated or differently-encoded transaction hash (case/0x-prefix) than stored; the row was deleted by cleanup before finality was processed.","commonSituations":"Out-of-order processing where finality is applied before the transaction-hash row is written; environment/DB mismatch between the submitter and finality verifier; hash normalization differences (checksummed hex vs lowercase, 0x prefix) after a refactor; retention jobs pruning rows too aggressively.","solutions":["Query `execution_transaction_hash` by the finality transaction hash to confirm the row exists and with which chain_id/wallet values","Ensure ordering: the transaction-hash row must be committed before finality is applied","Normalize the transaction hash (lowercase hex, consistent 0x handling) on both write and lookup paths","Check retention/cleanup jobs are not deleting rows pending finality","Verify the UPDATE's WHERE clause scoping matches how the row was originally written"],"exampleFix":"// before\nanyhow::ensure!(\n    hash_result.rows_affected() == 1,\n    \"Finality transaction hash was not found\"\n);\n// after\nanyhow::ensure!(\n    hash_result.rows_affected() == 1,\n    \"Finality transaction hash was not found: hash={} chain={} intent={}\",\n    finality.transaction_hash, chain_id, finality.intent_id\n);","handlingStrategy":"validation","validationCode":"// Confirm the transaction hash row exists before applying finality\nlet exists = sqlx::query_scalar::<_, i64>(\n    \"SELECT COUNT(*) FROM execution_transaction_hash \\\n     WHERE transaction_hash = $1 AND chain_id = $2 AND wallet_address = $3\"\n)\n.bind(normalize_hash(&finality.transaction_hash))\n.bind(chain_id)\n.bind(finality.wallet_address)\n.fetch_one(&mut *conn).await?;\nif exists == 0 { /* defer finality until the hash row is committed */ }","typeGuard":"fn tx_hash_is_known(finality: &VerifiedFinality, known: &HashSet<String>) -> bool {\n    known.contains(&normalize_hash(&finality.transaction_hash))\n}","tryCatchPattern":"match apply_verified_finality(...).await {\n    Err(e) if e.to_string().contains(\"transaction hash was not found\") => {\n        warn!(\"unknown tx hash {} for finality — deferring\", finality.transaction_hash);\n        requeue(finality);\n    }\n    other => other,\n}","preventionTips":["Normalize transaction hashes (lowercase hex, 0x policy) on both write and lookup","Guarantee the tx-hash row is committed before finality events are consumed","Exclude rows pending finality from retention/cleanup jobs","Scope hash rows with the same chain_id/wallet used by finality lookups"],"tags":["database","not-found","integrity","finality"],"backgroundTag":"record-not-found","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}