Settlement flow: funded to settled, pro-rata investor returns

[Jayrodri088]

Context

When the debtor pays, investors realize yield. Until automated Soroban/oracle settlement is fully wired, the backend still needs a correct, auditable settlement path that closes the invoice and investments and records returns.

Contributor workflow

• Apply on Drips before opening a PR: Claim this issue through the Drips platform before you open a pull request. Unsolicited PRs from unassigned contributors may be closed without review.
• ETA required: Your application must include an ETA for when you will open the first draft PR.
• Draft PR within 24 hours: If a draft PR is not linked on this issue within 24 hours of assignment, maintainers may unassign you so someone else can take the issue.

Goals

• Implement settlement that transitions:
  • Invoice: funded → settled (reject invalid states with stable error.code).
  • Investments: confirmed → settled with actual_return populated.
• Pro-rata returns: Distribute settlement proceeds across investors by their committed amounts (document formula; handle rounding to last investor or fixed precision—state choice).
• Create or update Transaction rows of type payment where it aids audit (link to users/invoices as your schema allows).
• Idempotency: Calling settlement twice must not double-pay in DB terms.

MVP input (choose and document)

• Either authenticated admin endpoint, or seller endpoint with strict checks, accepting e.g. paidAmount, stellarTxHash (optional), settledAt.
• Clearly label in code comments / PR that this is an MVP bridge until on-chain settlement drives status.

Acceptance criteria

• Illegal transitions return 400 with stable codes.
• Pro-rata math tests cover at least 2 investors + rounding edge case.
• Idempotent settlement verified by test.
• npm run type-check passes; tests pass.

PR submission requirements

• CI: All GitHub Actions workflow runs for this PR must pass (green) before merge; failing checks block merge.
• PR description must include: Closes #9.
• PR explains how this will be replaced or augmented by Soroban events later (short paragraph).
• List who is authorized to call settlement in this MVP (role / user type).

[drips-wave]

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

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

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 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

[lynaDev2]

@lynaDev2 has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

can i work on this my eta is 4 hours

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

[annacodervibe]

@annacodervibe has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

i am a backend developer my eta is 4 hours

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

[OsagieCynthia]

@OsagieCynthia has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I will love to work on this issue please assign

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

[drips-wave]

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

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