Document and handle chain-reorg behavior for the indexer in INDEXER_INTEGRATION.md and src/starknet/agreement-index.ts

[Jagadeeshftw]

📌 Description

INDEXER_INTEGRATION.md documents how src/starknet/agreement-index.ts builds its index from chain events, but doesn't appear to describe what happens if a previously-indexed block is later reorged out — a real scenario on most chains, distinct from the ordinary cache-eviction concerns already tracked elsewhere.

🧩 Requirements and context

• Document the current (or intended) reorg-handling behavior: does the indexer re-scan from a safe depth, or is there a known gap?
• If there is a real gap, add a minimal safeguard (e.g. only treat blocks past a confirmation depth as final) in src/starknet/agreement-index.ts.
• Add a test simulating a reorg (a block's events superseded by a competing block) and assert the index converges to the canonical state.

🛠️ Suggested execution

1. Investigate current reorg behavior in src/starknet/agreement-index.ts and write up findings in INDEXER_INTEGRATION.md.
2. If needed, add a confirmation-depth threshold before treating indexed data as final.
3. Add a reorg-simulation test.

✅ Acceptance criteria

• INDEXER_INTEGRATION.md accurately describes reorg behavior/limitations.
• A simulated reorg test passes against the documented/implemented behavior.

🔒 Security notes

An unhandled reorg could let stale/superseded event data drive incorrect agreement state — treat this as a data-integrity issue, not just documentation.

📋 Guidelines

• Minimum 95% test coverage
• Clear documentation
• Timeframe: 96 hours

[Devadakene]

@Devadakene has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I am skilled enough to implement this issue having worked on similar issues in the past

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Devadakene to this issue.

[drips-wave]

Congratulations, @Devadakene! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Devadakene: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[Jagadeeshftw]

Thanks for applying here. Please also join our Telegram group here: https://t.me/+vTbe0hOUKrFhNTJl. It helps us keep communication clear while we review contributions.

[drips-wave]

This issue has been completed by @Devadakene as part of the Stellar Wave Program's 7th Wave 🥳

😎 @Devadakene: You earned 100 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.