[Backend] Wire top-up stream endpoint to Soroban contract

[ogazboiz]

https://t.me/+DOylgFv1jyJlNzM0

Description

The smart contract has a top_up_stream function allowing the sender to add more tokens to a running stream, but the backend has no corresponding POST /streams/:streamId/top-up route in v1. Adding this endpoint unlocks a key use-case: streams that are close to being depleted can be refuelled without cancellation. The handler should validate the caller, accept an amount in the body, call sorobanService.topUpStream(), and return the txHash.

Acceptance Criteria

• POST /api/v1/streams/:streamId/top-up route exists and is registered
• Request body contains amount (positive integer, XLM stroops); validation returns 400 on invalid input
• Endpoint verifies JWT/SIWX; only the stream sender may top up
• sorobanService.topUpStream(streamId, amount, callerAddress) called; txHash returned
• DB deposit_amount / remaining_balance fields updated on success
• Covered by at least one integration test

Files to Touch

• app/api/routes/v1/streams/ — add top-up.ts handler
• app/services/soroban.service.ts — expose topUpStream method
• app/api/routes/v1/streams/index.ts — register route
• app/repositories/stream.repository.ts — updateBalance helper
• tests/integration/streams/top-up.test.ts

[cybermax4200]

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

I can deliver an excellent work on this, please assign

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

[levibliz]

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

This issue looks like a good opportunity for me to practice and gain more experience, especially in areas I’m currently learning.

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

[BarryArinze]

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

I’d love to take this on because stream top-ups are a critical lifecycle feature—without it, users are forced into cancellation instead of extending active streams smoothly.

I’ll implement a POST /api/v1/streams/:streamId/top-up endpoint in the v1 streams route that validates the request body (ensuring a positive integer amount in stroops), enforces authentication via JWT/SIWX, and strictly checks that only the stream sender is allowed to top up the stream.

The handler will call sorobanService.topUpStream(streamId, amount, callerAddress) and return the resulting txHash to confirm the on-chain action.

On the persistence side, I’ll update the stream repository to correctly adjust deposit_amount and remaining_balance after a successful top-up so backend state stays in sync with the contract.

Finally, I’ll add an integration test covering authentication, validation, successful execution, and state updates to ensure the full flow is reliable and production-safe.

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

[drips-wave]

Congratulations, @cybermax4200! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on April 29, 2026.

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