PATINA docs

Sync and reindex

Three modes: initial sync, steady state, and rebuild. The third is always available, which is what makes the first two safe.

What you will know after this page
  • Which height to start from, and why /ready has to keep failing until the first sync finishes.
  • How to spot a reorg from your stored block hashes, and the six steps back to steady state.
  • The five situations that force a full reindex, and the two that look like they should and do not.
  • How to rebuild alongside a live index and compare state roots at a shared height before you swap.
  • Why a rebuild never loses anything, and why hand editing the store is never the answer.

Initial sync

Four things to get right on the first pass. The fourth is the one people skip, and it is the one that makes a reorg detectable later.

  1. Start at the deployment start height. Earlier blocks contain nothing.
  2. Process blocks in order, applying the rules and recording invalid events.
  3. Keep /ready failing throughout. An indexer that answers during initial sync gives correct answers for a height nobody asked about.
  4. Record block hashes per height as you go. Without them you cannot detect a reorg later.
watch -n 10 "curl -s http://localhost:PORT/patina/status \
  | grep -o '\"indexed_height\":[0-9]*'"

Steady state

  • Follow the node's tip. Apply each new block as it arrives.
  • Compare the incoming block's previous hash with your stored hash for that height. A mismatch is a reorg.
  • Keep the gap between indexed_height and tip_height small, and alert when it is not.
  • Nothing needs to happen per block per artifact. Depth is computed at query time, so a block with no PATINA activity costs almost nothing.

Reorg handling

  1. Detect a mismatch between your stored hash and the node's block at that height.
  2. Walk back to the last height where hashes agree. That is the fork point.
  3. Roll state back to the fork point.
  4. Fail /ready while rolling back and replaying.
  5. Replay forward, applying the same rules.
  6. Return to steady state.

Rules and requirements on Reorg behavior. The critical property is that rolling back to height H and replaying to H reproduces the same state root. Test it deliberately, not only when it happens.

When to reindex from scratch

Rebuild when the rules that produced the state changed, or when you cannot say what produced it. Slowness is not on that list, and the last two rows are there because they are the ones people most often get wrong.

Reindex triggers.
SituationReindexWhy
Upgrading to a build with a parser changeYesOld state was produced by different rules
spec_sha256 changedYesThe specification is different, so the state may be too
A state root mismatch against another implementationYes, after the bug is understoodRebuilding on a fixed parser is the only way to trust the result
Storage corruption, or an unclean shutdown you cannot reason aboutYesRebuild is cheap compared with serving wrong state
A reorg deeper than your rollback historyYesYou cannot reach the fork point
A performance problemNoFix the query path. Reindexing does not make wrong data fast or fast data right.
Bug fix in serving code onlyNoThe state is unaffected

Reindex procedure

  1. Announce it if you serve others

    Say what you are rebuilding and why. A silent rebuild looks like an outage.

  2. Build into a new store

    Do not destroy the old index first. Rebuild alongside it, so you can compare the two and so a failed rebuild is not an outage.

  3. Run the golden vectors on the new build

    Before it touches a real chain.

  4. Index to a height the old store also reached

    Then compare state roots at that exact height. Identical roots mean the rebuild changed nothing, which is the expected result unless you were fixing a bug.

  5. Swap and keep the old store

    Keep it until the new one has been correct for long enough that you would not want to go back.

Nothing is lost by rebuilding

The entire index is derived from the blockchain. There is no user data in it, no state that exists only in your database, and nothing that cannot be recomputed. That is why reindex is always a safe answer, and why an operator should never be tempted to hand edit the store.

Upgrades

  1. Read the release notes for parser changes. Any parser change means a reindex.
  2. Run the vectors on the new build.
  3. If the parser is unchanged, a rolling restart is enough. Confirm indexed_height resumes from where it stopped.
  4. If the parser changed, follow the reindex procedure and compare roots before serving.
  5. Publish the new spec_sha256 and parser_version through status.

What never happens during any of this

  • No artifact is created, moved, or destroyed by anything an operator does. Only the chain does that.
  • No depth is affected by downtime. Depth is measured from block heights, not from uptime, which the public site shows moving block by block on the depth page.
  • No holder needs to act because an indexer restarted.