ChainSync Cursor Persistence
ChainSync Cursor Persistence
Section titled “ChainSync Cursor Persistence”Overview
Section titled “Overview”This guide describes optional ChainSync cursor persistence for Adder operators and Go integrators. A persisted cursor lets ChainSync resume from the most recently emitted block after a restart while keeping rollback handling aligned with emitted events.
Configure a SQLite path when ChainSync should resume from saved progress after a restart.
Operator configuration
Section titled “Operator configuration”Enable cursor persistence with the CLI
Section titled “Enable cursor persistence with the CLI”Set --input-chainsync-state-path to a SQLite database file:
adder \ --input chainsync \ --input-chainsync-state-path /var/lib/adder/chainsync-state.sqliteAdder creates the SQLite file when the path does not exist and reopens it when the path already exists. The parent directory must exist, and the Adder process must have permission to create, read, write, and close the file.
Enable cursor persistence with YAML
Section titled “Enable cursor persistence with YAML”Set state-path under the chainsync input plugin:
plugins: input: chainsync: state-path: /var/lib/adder/chainsync-state.sqliteThe default value is an empty path. Leave the CLI option and YAML setting empty or unset to disable cursor persistence and preserve the normal ChainSync startup behavior.
When a setting has multiple sources, Adder applies the general configuration precedence order: CLI flags override environment variables, environment variables override YAML configuration, and YAML configuration overrides defaults. See the ChainSync options in the command reference for the complete option list.
Warning: After Adder saves a cursor, ChainSync uses that cursor as the startup intersection. The persisted cursor takes precedence over the configured
intersect-tipandintersect-pointvalues. The configured intersection applies only until the state store contains a cursor.
Persistence and rollback behavior
Section titled “Persistence and rollback behavior”ChainSync persists a cursor that represents the most recently emitted block. It does not persist a block merely because the node supplied it or because ChainSync placed it in a confirmation buffer.
- ChainSync updates the pending cursor after it emits every event for a block successfully.
- Adder flushes the pending cursor to SQLite every five seconds.
- Adder flushes the pending cursor again during shutdown.
- A failed flush leaves the pending cursor available for a later flush attempt.
- A rollback rewinds the pending cursor to the last emitted block that survives the rollback. ChainSync does not persist a block that the rollback removed.
- If a rollback removes every emitted block in the tracked history, ChainSync resets the pending cursor to the genesis point.
- On restart, ChainSync loads the saved cursor before it connects and resumes from that point.
The saved cursor records ChainSync progress, not the output event itself. Cursor persistence does not provide exactly-once processing and does not make event delivery durable. Consumers must apply their own delivery and deduplication strategy when those guarantees are required.
When state-path remains unset, ChainSync does not create a state store, does not flush a cursor, and continues to use the configured intersection on each start.
Go API
Section titled “Go API”Go integrations can provide a state store directly or select a different key for the cursor.
Provide a state store
Section titled “Provide a state store”Use WithStateStore with a state.Store implementation. The SQLite store provides a file-backed implementation:
package main
import ( "log"
"github.com/blinklabs-io/adder/input/chainsync" "github.com/blinklabs-io/adder/state")
func newChainSync() *chainsync.ChainSync { store, err := state.NewSqliteStore("/var/lib/adder/chainsync-state.sqlite") if err != nil { log.Fatal(err) }
return chainsync.New( chainsync.WithStateStore(store), chainsync.WithStateKey("consumer-a"), )}WithStateStore changes startup behavior only when the store already contains a cursor. ChainSync uses that cursor instead of the configured intersection and otherwise retains the configured intersection until the first cursor flush.
Select the cursor key
Section titled “Select the cursor key”ChainSync uses chainsync-cursor as the default state key. Use WithStateKey to select a distinct key when multiple ChainSync instances share one SQLite file:
chainsync.New( chainsync.WithStateStore(sharedStore), chainsync.WithStateKey("orders-consumer"),)Each shared instance requires a distinct key to prevent one cursor from replacing another.
Manage store ownership
Section titled “Manage store ownership”ChainSync distinguishes stores that it creates from stores that a caller provides:
- The
state-pathconfiguration creates an owned SQLite store. ChainSync closes the owned store during shutdown and reopens it for the next run. WithStateStoresupplies a caller-owned store. ChainSync leaves that store open acrossStopandStartRunso shared integrations can continue using it. The caller closes the store when all users finish.
This lifecycle applies to the store connection. The SQLite file remains available for later runs when the process closes the store.
Related reference
Section titled “Related reference”Docs authored by Doc Holiday