Improve payout reliability (iteration 11) #1185

Activity

1. drips-wave

   added

   Stellar WaveIssues in the Stellar wave programIssues in the Stellar wave program

   on Oct 17, 2026
2. Obaara293 commented on Oct 17, 2026

   

   Obaara293

   on Oct 17, 2026 – with Drips Wave

   More actions

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

   Hi maintainer, I've reviewed the issue and I've recognized the solution, kindly assign this to me to get the best result.

   ℹ️ Repo Maintainers: To accept this application, review their application or assign @Obaara293 to this issue.
3. SagaciousBoss commented on Oct 17, 2026

   

   SagaciousBoss

   on Oct 17, 2026 – with Drips Wave

   Contributor

   More actions

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

   I would love to apply for this issues , I can handle it .

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

   assigned

   SagaciousBoss

   on Oct 17, 2026
5. drips-wave commented on Oct 17, 2026

   

   drips-waveBot

   on Oct 17, 2026 – with Drips Wave

   More actions

   Congratulations, @SagaciousBoss! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on October 22, 2026.

   🧑‍💻 @SagaciousBoss: 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 🌊
6. github-actions

   added a commit that references this issue on Oct 17, 2026

   feat: payout execution, money correctness and payout API security (#1183

   ...

   8119f72
7. SagaciousBoss commented on Oct 17, 2026

   

   SagaciousBoss

   on Oct 17, 2026

   Contributor

   More actions

   Delivered in #1290 (merged).

   Payout reliability work in that PR:

   PayoutEngine had no execution path. Auto-approved and manually approved batches were stamped completed without anything being sent, executing was unreachable dead state, and there was no failure or retry path.

   • Added a guarded pending -> executing -> completed | failed transition table. A batch is only marked completed when the rail returns a transaction hash, and a rail that resolves without one is treated as a failed attempt.
   • Added an injected executor that actually settles the batch and receives a stable idempotencyKey on every attempt, so a rail can deduplicate a replay.
   • Added exponential backoff with jitter, capped by maxAttempts. payout.delayed events carry the scheduled retry time.
   • daily / weekly / monthly now respect their period, and calendar batches are keyed by period bucket so a replayed evaluation pass cannot pay the same period twice. Previously all three cadences fired on every pass whenever a balance was pending.
   • thresholdAmount of 0 or undefined is now rejected instead of falling through to the "pay anything" branch.
   • Emit payout.created, payout.pending_review, payout.executing, payout.completed, payout.failed and payout.delayed through a pluggable sink. A subscriber that throws is ignored, so a webhook outage cannot abort a payout decision.
   • Exhausted batches keep their reservation rather than auto-releasing it. Returning the funds would immediately mint a fresh batch and spin against a rail that is already down; an approver calls releaseReservedFunds instead. The held amount is visible in stats().reservedAmount.
   • The retry worker never pushes a batch that owed human review past that review — it returns to the approval queue.
   • One merchant's misconfiguration is isolated so it cannot block every other merchant in the same pass.
   • Added the /api/v1/payouts REST surface, mounted in backend/src/index.ts. This also implements payout.completed, which the webhook subscriptions UI already advertised but nothing emitted server-side.

   Tests: services/payouts/__tests__/payout-engine.test.ts covers execution, stable idempotency keys across attempts, backoff growth (30s -> 60s -> 120s), attempt exhaustion, reservation release, calendar cadence, period-bucket cycle keys, event emission, per-merchant isolation and concurrent-pass collapse. New routes/__tests__/payouts.test.ts covers the HTTP lifecycle.

   Docs: docs/PAYOUT_RELIABILITY.md.
8. github-actions

   closed this as completedin bbdef79on Oct 17, 2026
9. drips-wave commented on Oct 17, 2026

   

   drips-waveBot

   on Oct 17, 2026 – with Drips Wave

   More actions

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

   😎 @SagaciousBoss: You earned 200 Points for completing this issue! Once the Wave's rewards are finalized, 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.
10. Georgechisom

    added a commit that references this issue on Oct 17, 2026

    fix: correct the type errors introduced in Smartdevs17#1290 (Smartdev…

    ...

    This issue will close once commit bbdef79 is merged into the 'main' branch.

    bbdef79