Atomic Split Payment Rollback Coordinator

[Kingsman-99]

Description

Multi-recipient split payments consist of several payment operations grouped in one transaction, but when a partial failure occurs at the application layer (e.g. post-submission webhook failure, database write failure), the SDK provides no mechanism to track which portions of the split were acknowledged and coordinate a corrective resubmission or reversal. A rollback coordinator should record split state atomically and provide a reconciliation primitive.

Technical Context

Add src/splitRollbackCoordinator.ts. Integrates with src/snapshot.ts for state persistence. Reads SplitResult and SplitLeg from src/types.ts. Uses src/idempotency.ts to prevent double-reversal. Hooks into src/client.ts submitPayment() post-submission lifecycle. Emits splitRollbackInitiated and splitRollbackCompleted via src/events.ts.

Acceptance Criteria

• RollbackCoordinator.begin(splitId) creates a persistent rollback checkpoint recording all intended split legs
• RollbackCoordinator.markLegSuccess(splitId, legIndex) and markLegFailed(splitId, legIndex) update the checkpoint atomically
• RollbackCoordinator.getIncomplete(splitId) returns the set of legs that neither succeeded nor are confirmed failed
• RollbackCoordinator.initiateRollback(splitId) emits splitRollbackInitiated and stores a rollback record in src/snapshot.ts
• Integration test simulates a post-submission failure, calls initiateRollback, and asserts the checkpoint reflects the correct incomplete legs
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---

[Muneerat]

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

Please assign me this issue. I would like to work on it

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

[Abdulrasaq1515]

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

I want to implement an atomic split payment rollback coordinator because when a partial failure occurs (e.g., post-submission webhook failure, DB write failure), the SDK provides no mechanism to track which portions of the split were acknowledged and coordinate a corrective resubmission or reversal. The coordinator records split state atomically, provides reconciliation primitives, and integrates with snapshot persistence, idempotency, and events.

Relevant experience:

Rollback coordinators — built rollback coordinators for 2 split payment systems; state tracking, idempotency, reconciliation

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

[D-Ochuko]

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

I would like to work on this.
Please assign

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

[drips-wave]

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

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

[drips-wave]

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

😎 @D-Ochuko: You earned 200 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.