Sync & Follow
One command takes you from the first block you care about to the live chain head, and keeps you there.
Lifecycle of a run
Sieve starts at the lowest start_block across your contracts, factories, and transfers (or --start-block) and fetches history from peers in parallel batches. A bloom filter check skips the body and receipt fetch for blocks that cannot contain a matching log.
As it nears the tip, Sieve keeps tracking the head that peers report, so the target moves with the chain instead of stopping at the height it saw at startup.
Once caught up, Sieve indexes each new block as it arrives. On OP-Stack chains it follows the sequencer's unsafe head, typically within a block or two.
Pass --end-block to stop at a fixed height instead of following. On Base, a backfill can also start from snapshot archives; see Base Archive Bootstrap.
sieve # backfill, then follow sieve --start-block 21000000 --end-block 21100000 # fixed range, then exit
Restarts
Blocks are committed in strict order, and the checkpoint always equals the highest committed block. A restart resumes at the next block, with no holes and no half-written ranges. On startup Sieve re-verifies its last committed block against a peer quorum before the API serves anything, which also catches a reorg that happened while it was stopped. See Integrity.
Only one Sieve process can write to a database at a time. A second one pointed at the same database is refused.
Reorgs
In follow mode Sieve compares stored block hashes with what peers report. When a peer quorum agrees on a different canonical tip, Sieve rolls back indexed rows, transfers, calls, and factory children above the fork point and re-indexes the new branch. Rollback covers up to 64 blocks. A single peer can never trigger one.
Peers
Peer heads are refreshed continuously while following, and after every successful fetch. In follow mode, a peer that has not answered successfully for two minutes is evicted and disconnected, and discovery replaces it. If you run your own node, pin it with trusted_peers so it is always in the set.
Graceful shutdown
Ctrl+C or SIGTERM (including docker stop) stops new work, drains what is in flight, and saves progress. This works at any stage, including while Sieve is still waiting for peers. A second signal forces an immediate exit.
Under Docker, give the container enough stop time for the drain to finish. See Docker.
Health and readiness
With the API enabled ([api] port or --api-port), these endpoints sit next to GraphQL:
Liveness. Returns 200 while the process is up.
Readiness. Returns 503 during backfill and 200 once Sieve has caught up and is following the head, or has finished a fixed --end-block range. Use it to keep traffic away from a half-synced instance.
Prometheus metrics in OpenMetrics text format.
Metrics
| Metric | Meaning |
|---|---|
| sieve_blocks_indexed_total | Blocks processed |
| sieve_events_matched_total | Events matched by filters |
| sieve_events_stored_total | Events written to the database |
| sieve_transfers_stored_total | Native transfers written |
| sieve_calls_stored_total | Function calls written |
| sieve_chain_head | Latest observed chain head |
| sieve_indexed_block | Latest indexed block |
| sieve_connected_peers | Connected peers |
| sieve_active_fetches | Fetch tasks in flight |
| sieve_pending_blocks | Blocks left in the scheduler queue |
sieve_chain_head minus sieve_indexed_block is your lag behind the chain.