[Backend] handleTokensWithdrawn increments withdrawnAmount before the dedup guard - replay/reset double-counts and corrupts claimable

[grantfox-oss]

Telegram (ask questions / claim the issue here first): https://t.me/+DOylgFv1jyJlNzM0

Labels: bug, backend, Stellar Wave, database, critical

The withdrawn-amount update runs before the dedup check, so replaying events under-pays recipients.

soroban-event-worker.ts:631-641 computes newWithdrawnAmount = BigInt(stream.withdrawnAmount) + BigInt(amount) and calls tx.stream.update unconditionally. The dedup check at line 643 only guards inserting the StreamEvent row, not the financial field. So when the admin POST /v1/admin/indexer/replay resets the cursor and re-polls the same ledgers, every replay adds amount again even though the StreamEvent row is skipped. withdrawnAmount inflates, claimable shrinks, and the recipient is short-changed. The replay endpoint's Swagger doc even claims it's idempotent.

What the fix has to hold to

• The stream's withdrawnAmount only changes when the StreamEvent row is newly created, in the same transaction
• Replay/reset is genuinely idempotent

Done when

• withdrawnAmount update is idempotent (mutate only on a new StreamEvent insert, same tx)
• Test processes the same tokens_withdrawn event twice and asserts withdrawnAmount changes once
• handleStreamCancelled/handleStreamCompleted audited to confirm they stay idempotent
• Tests + lint pass, CI green

Where to start
backend/src/workers/soroban-event-worker.ts for the ordering fix; indexerService.ts and admin.routes.ts are listed for the replay path and audit. On-chain event schema is out of scope. Medium.

[Godfrey-Delight]

@Godfrey-Delight has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi maintainer! I’d love to work on this issue if it’s still available. I have a good understanding of the requirements and would be happy to implement the solution. Thanks for considering my request!

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

[elcabasa]

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

Hi team,

I would love to take on this issue! Ensuring that the financial mutations are strictly idempotent during indexer replays is incredibly important, as an unconditional increment to withdrawnAmount before the deduplication guard corrupts the calculated claimable amounts and impacts recipient payouts.

I am ready to align the event worker tracking to ensure strict database consistency and meet the acceptance criteria:

• Idempotent Mutations: Refactor handleTokensWithdrawn in soroban-event-worker.ts so that the withdrawnAmount field is only updated if the StreamEvent row is newly created, encapsulating both actions safely within the same atomic database transaction.
• Worker Auditing: Audit handleStreamCancelled and handleStreamCompleted within the worker file to guarantee that their state transition handlers are completely idempotent and immune to indexer replays.
• Replay Testing: Add an integration test that processes the exact same tokens_withdrawn event payload twice, asserting that the underlying withdrawnAmount updates exactly once.

I will keep the scope localized to these backend indexing workflows without touching the on-chain event schemas. Could you please assign this issue to me? I will jump into the Telegram chat to sync up as well. Thanks!

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

[Olamidepy]

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

Hi Maintainer,

I would love to be assigned to this issue.

I’m a Full-Stack Developer and I also actively explore blockchain development and smart contracts, which has strengthened my problem-solving skills and attention to code quality.

After reviewing the issue, I believe I can contribute effectively and deliver a well-tested solution within the expected standards of the project.

ETA: 6 hours

Thank you for your consideration.

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

[Banx17]

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

Please assign me this issue thanks.

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

[jadonamite]

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

Please maintainer can i work on this issue
I have read your requirements and i am ready to jump on this and submit before 9:00AM tomorrow

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

[EbukaMoses]

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

Hello Maintainer,

I’d like to apply to work on this issue.

I’m Ebuka Moses, a full-stack and blockchain developer with experience building, testing, and maintaining smart contracts, particularly using Rust and blockchain-based architectures. I’m comfortable working with contract logic, validation, access control, persistent storage, and event handling, and I always pay close attention to correctness, security, and edge cases.

I take time to fully understand the issue requirements before implementing a solution, and I ensure my work follows the project’s coding standards. I also write clear, well-tested code and submit clean pull requests with meaningful commits.

I’m confident I can deliver a solid solution that meets the acceptance criteria and adds value to the project.

Thank you for your consideration, and I look forward to contributing.

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

[drips-wave]

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

🧑‍💻 @jadonamite: 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 🌊

[grantfox-oss]

🦊 GrantFox — @jadonamite has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #802)
2. Your PR will be reviewed by the LabsCrypt maintainers

Good luck! Track your progress on GrantFox.