Implement Idempotent Sync Logic

[dDevAhmed]

📚 Overview

Blockchain data ingestion must be idempotent by design.

This issue focuses on ensuring that re-running the indexer — intentionally or accidentally — never corrupts backend state.

---

🎯 Objectives

Guarantee that:

• Events are processed once
• Duplicate executions are harmless
• Backend state remains deterministic

---

🧠 Problem Context

Indexers can restart due to:

• Deployments
• Crashes
• Network issues

Without idempotency:

• Balances drift
• Rewards double-count
• Trust is broken

---

🧩 Technical Scope

1️⃣ Event Uniqueness

Define uniqueness constraints using:

• txHash
• logIndex
• blockNumber

Enforce at DB level.

---

2️⃣ Processing Guards

• Check existence before writes
• Use transactional writes where needed
• Fail safely on conflicts

---

3️⃣ Restart Safety

• Indexer can resume from last processed block
• Reprocessing same range produces same DB state

---

✅ Acceptance Criteria

• Re-running indexer produces identical state
• Duplicate events are ignored safely
• DB constraints enforce uniqueness
• Tests cover replay scenarios

---

⏳ Complexity & Effort

Complexity: Medium
Estimated Effort: ~0.5 day

---

🏷️ Labels

• backend
• blockchain-sync
• idempotency
• medium-complexity
• drips-wave

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 150 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[gregemax]

@gregemax has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi maintainer, I’d like to work on this issue.

I have strong backend experience with Node.js/NestJS, MongoDB, and blockchain indexers, including handling replays, RPC inconsistencies, and ensuring deterministic state updates. I understand how critical idempotency is for reliable data ingestion.

My approach will be to:

Enforce DB-level uniqueness with compound indexes on txHash, logIndex, and blockNumber

Add processing guards and prefer upserts or existence checks before writes

Use transactions for any multi-step state updates (balances, rewards, aggregates)

Persist and resume from the last processed block safely

Ensure reprocessing of the same block ranges produces identical DB state

Add tests that replay events and assert deterministic outcomes

I can start immediately and should complete within the estimated effort. Please assign this issue to me if this approach works. Thanks!

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

[drips-wave]

Congratulations, @gregemax! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on January 31, 2026.

🧑‍💻 @gregemax: 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.

⚠️ Important: When opening a PR, please link it to this issue to ensure it gets tracked accurately.

🤠 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 🌊

[gregemax]

@dDevAhmed can you please close the issue so the point can reflect

[drips-wave]

This issue has been marked as completed by a Drips Wave moderator for @gregemax as part of the Stellar Wave Program's 1st Wave 🥳

Moderator's reason: The issue was resolved by the contributor and merged by the maintainer in PR:
#30

😎 @gregemax: You earned 150 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.

🧑‍💻 Repo maintainers: How'd the contributor do? If you like, you can reward them with additional points by making a compliment within seven days after the Wave Program's current wave ends.

ℹ️ Note: This issue was marked complete via moderation. Points were issued even though the GitHub issue remains open.

[dDevAhmed]

@gregemax can you make a PR for this so I can close the issue?