Durable Checkpoints for Incremental Blockchain Scans
Checkpoint accepted ranges only after durable processing, and use restart tests to prevent skipped pages or duplicate effects in incremental scans.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A checkpoint says which work is safely complete. Writing it too early can skip records after a crash; writing it too late requires replay-safe processing.
Define committed progress
Keep network, range boundary, block identity and relevant query version in the checkpoint. Commit processed records and progress together where the storage model allows it. If they cannot be atomic, choose a recovery protocol that tolerates replay. A last-seen timestamp alone is insufficient when many events share one timestamp.
Worked example: crash between fetch and write
The client fetches page P and immediately stores its next cursor, then crashes before writing P’s records. On restart it skips P. Reverse the durable boundary: process the page safely, then advance progress under a transactional or replay-safe contract. Repeated processing must not create duplicate business actions.
Verify on restart
Check that the stored block reference still belongs to the accepted chain where required. Test a crash before commit, after commit and during rollback repair. Keep query changes from silently reusing incompatible checkpoints. A new filter or decoder requirement may need a bounded rescan rather than continuing from an unrelated old cursor.
A practical acceptance test
Crash the scanner before record commit, after record commit and after progress commit. Each restart should either replay safely or resume after completed work. Add a changed query filter and ensure its old checkpoint is not reused blindly. A progress marker should identify the evidence boundary it actually certifies, not merely the last successful HTTP fetch.
Questions about the topic
Frequently asked questions
Is fetched equivalent to durably processed?
No. A crash can occur between those steps.
Can a checkpoint ignore query filters?
Not safely when those filters define what completed work means.
Standards & technical documentation
