Skip to content

Expand rollback guard documentation with reorg detection guide#802

Draft
JasoonS wants to merge 1 commit intomainfrom
claude/add-rollback-guard-9KGmu
Draft

Expand rollback guard documentation with reorg detection guide#802
JasoonS wants to merge 1 commit intomainfrom
claude/add-rollback-guard-9KGmu

Conversation

@JasoonS
Copy link
Contributor

@JasoonS JasoonS commented Feb 13, 2026

Summary

Significantly expanded documentation for the rollback_guard feature across HyperSync and HyperIndex docs to provide comprehensive guidance on detecting and handling chain reorganizations (reorgs).

Key Changes

  • Enhanced RollbackGuard struct documentation with clearer field descriptions in both HyperSync query and LLM docs
  • Added detailed reorg handling section explaining:
    • How HyperSync internally validates block parent hashes and stays on canonical chain
    • Data consistency guarantees within a single query response
    • Step-by-step reorg detection logic using hash comparison between successive queries
    • Concrete example showing hash matching/mismatching scenarios
  • Provided reorg recovery procedure with pseudocode example demonstrating:
    • Storing rollback guard history
    • Walking backwards to find reorg depth
    • Rolling back state and re-querying from the correct point
    • Trimming history based on chain reorg threshold
  • Added HyperIndex recommendation as an alternative for users who want automatic reorg handling without manual implementation
  • Cross-linked documentation between HyperSync and HyperIndex reorg support pages to guide users to appropriate solutions

Notable Details

  • The pseudocode example uses Python-like syntax for clarity and includes practical considerations like reorg threshold management
  • Emphasizes the important guarantee that data within a single query response is always consistent
  • Clarifies that the rollback guard detects that a reorg occurred but not which specific block, requiring historical comparison
  • Provides clear guidance on when to use HyperSync's manual approach vs. HyperIndex's automated handling

https://claude.ai/code/session_01FubCA6TsvCKBgVFYFA1gvx

@claude
docs: Add detailed rollback guard documentation for HyperSync reorg d…
0d3568c 
…etection

Expand the Rollback Guard section in the HyperSync query docs to explain
how HyperSync handles chain reorgs internally, the data consistency
guarantee within a single query, how to detect reorgs using
first_parent_hash comparison, and a step-by-step guide with pseudocode
for handling detected reorgs. Also adds cross-reference from the
HyperIndex reorgs-support page and updates the LLM documentation.

https://claude.ai/code/session_01FubCA6TsvCKBgVFYFA1gvx
@vercel
Copy link

vercel bot commented Feb 13, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
envio-docs Ready Ready Preview, Comment Feb 13, 2026 11:07am

Request Review

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Feb 13, 2026

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch claude/add-rollback-guard-9KGmu

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

JasoonS
JasoonS commented Feb 13, 2026
View reviewed changes
docs/HyperSync/hypersync-query.md
# Store rollback guards from recent queries
rollback_history = [] # list of (block_number, hash) tuples

while True:
Copy link
Contributor Author

@JasoonS JasoonS Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to check this code 🍇 All AI

JasoonS
JasoonS commented Feb 13, 2026
View reviewed changes
Copy link
Contributor Author

@JasoonS JasoonS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This update needs some love, but also need to get going soon.

docs/HyperSync-LLM/hypersync-complete.mdx
When a reorg is detected, the rollback guard tells you *that* a reorg happened, but not *which specific block* was reorganized. To handle this:

1. **Store the rollback guard from every recent query** — keep enough history to cover the reorg threshold for your chain (e.g., up to 200 blocks for Polygon).
2. **Walk backwards through stored rollback guards** to find the first query whose block hash no longer matches the chain.
Copy link
Contributor Author

@JasoonS JasoonS Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to refine this step, it'll always only be the latest rollback guard that doesn't match, but a query to hypersync needs to check all the recent blockhashes to find out exactly where the reorg happend (while looking at the previous reorg guards, or stored hashes).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@JasoonS @claude

Comments