{"record":{"id":"cb1188863131ee0c","repo":"nautechsystems/nautilus_trader","slug":"persisted-terminal-transaction-tx-hash-is-not-st","errorCode":null,"errorMessage":"Persisted terminal transaction {tx_hash} is not stable at the finalized boundary","messagePattern":"Persisted terminal transaction (.+?) is not stable at the finalized boundary","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":994,"sourceCode":"        let executor = self.transaction_executor()?;\n        let prepared = PreparedTransaction {\n            intent_id: intent.id,\n            created_block: intent.created_block,\n            nonce,\n            tx_hash,\n            raw_tx: current.raw_transaction.clone().unwrap_or_default(),\n        };\n        let outcome = if matches!(intent.status.as_str(), \"finalized\" | \"reverted\") {\n            let receipt = executor\n                .http_rpc_client\n                .get_transaction_receipt(&tx_hash)\n                .await?\n                .ok_or_else(|| {\n                    anyhow::anyhow!(\n                        \"Finalized execution transaction {tx_hash} no longer has a receipt\"\n                    )\n                })?;\n            anyhow::ensure!(\n                executor.receipt_is_stably_finalized(&receipt).await?,\n                \"Persisted terminal transaction {tx_hash} is not stable at the finalized boundary\"\n            );\n\n            if intent.status == \"finalized\" {\n                InclusionOutcome::Finalized(IncludedTransaction {\n                    intent_id: intent.id,\n                    tx_hash,\n                    block_number: receipt.block_number,\n                    receipt,\n                })\n            } else {\n                InclusionOutcome::Reverted(tx_hash)\n            }\n        } else {\n            executor.await_finality(&prepared).await?\n        };\n","sourceCodeStart":976,"sourceCodeEnd":1012,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/2114cf6f761429e0adb5ca9596fcd7b895b16011/crates/adapters/blockchain/src/execution/client.rs#L976-L1012","documentation":"For a persisted terminal transaction, receipt_is_stably_finalized() re-derived finality and it failed: either the node's finalized block number is still below the receipt's block number, or re-fetching the receipt's block and the finalized block produced hashes different from the ones first observed. The ensure! converts that instability into a hard error instead of trusting the persisted 'finalized'/'reverted' status.","triggerScenarios":"Startup reconciliation of a 'finalized'/'reverted' intent while the RPC endpoint lags on finality, serves a non-canonical view, or the chain actually reorganized blocks that were previously reported finalized.","commonSituations":"Aggressively-load-balanced or self-hosted nodes with inconsistent fork state; reconnecting right after a network incident; querying nodes whose 'finalized' tag trails the actual finalized height.","solutions":["Retry connect()/reconciliation after the node catches up — finality lag is usually transient","Query the node directly: eth_getBlockByNumber('finalized') and compare its number/hash against the receipt's blockNumber/blockHash","If it persists, switch to a reputable, canonical RPC provider and reconcile again","Only if on-chain state is independently verified should you repair the intent row manually"],"exampleFix":"# before: fail-fast single attempt during a finality blip\nclient.connect()  # raises: not stable at the finalized boundary\n\n# after: retry with backoff until the node view stabilizes\nfor attempt in range(5):\n    try:\n        client.connect()\n        break\n    except Exception as e:\n        if \"finalized boundary\" not in str(e):\n            raise\n        time.sleep(10 * (attempt + 1))","handlingStrategy":"retry","validationCode":"from web3 import Web3\n\nw3 = Web3(Web3.HTTPProvider(rpc_url))\nfinalized = w3.eth.get_block('finalized')\nreceipt = w3.eth.get_transaction_receipt(tx_hash)\nstable = (finalized.number >= receipt.blockNumber)\nassert stable, 'node finality lags the receipt; retry connect later'","typeGuard":null,"tryCatchPattern":"for attempt in range(6):\n    try:\n        client.connect()\n        break\n    except Exception as e:\n        if 'finalized boundary' not in str(e):\n            raise\n        time.sleep(15 * (attempt + 1))  # let the node's finalized tag catch up\nelse:\n    raise RuntimeError('reconciliation never stabilized')","preventionTips":["Use RPC providers with fast, accurate finalized-tag tracking","Avoid reconnecting mid-network-incident; wait until finality indicators settle"],"tags":["blockchain","reconciliation","finality","chain-reorg","rpc"],"backgroundTag":"chain-reorg","analyzedSha":"2114cf6f761429e0adb5ca9596fcd7b895b16011","analyzedAt":"2026-08-21T11:28:30.864Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}