[Backend] Transaction Simulation & Pre-Flight Fee Estimation API for Client-Side Signing

[blurbeast]

Overview & Background

In accordance with Issue #1274 and the security audit in docs/audits/1274-keeper-key-blast-radius.md, FlowFi is deprecating centralized backend keeper key signing in favor of client-side signing (Freighter, Lobstr, xBull). However, building and signing Soroban transactions directly in browser extensions requires running a Soroban RPC transaction simulation (simulateTransaction) to obtain ledger footprint keys, resource limits (CPU/memory instructions), and the minimum base fee.

---

Detailed Problem Statement

1. Client Complexity & Duplicate RPC Calls:
   • Forcing every frontend client to implement low-level Soroban transaction simulation results in bloated bundle sizes and inconsistent fee calculations.
2. Frequent Simulation Failures:
   • Client-side simulation errors often lack human-readable error messages when contracts revert or balances are insufficient.
3. No Centralized Fee Buffer Policy:
   • Clients need an authoritative backend endpoint to compute simulation footprints with appropriate safety fee buffers.

---

Technical Specification & Architecture

1. Simulation API Endpoint

POST /api/v1/streams/simulate

Request Body:

{
  "action": "create" | "withdraw" | "cancel" | "top_up" | "batch_withdraw",
  "senderPublicKey": "G...",
  "params": {
    "streamId": "123",
    "recipient": "G...",
    "amount": "1000000000",
    "duration": 2592000
  }
}

Response Body:

{
  "success": true,
  "data": {
    "unsignedXdr": "AAAAAgAAA...",
    "minResourceFee": "15000",
    "recommendedFee": "20000",
    "cpuInstructions": 1420500,
    "memoryBytes": 524000,
    "expiresAtLedger": 482910,
    "simulatedReturn": "100000000"
  }
}

2. Implementation in sorobanService.ts

• Assembles the contract invocation XDR.
• Invokes server.simulateTransaction(tx) via the RPC pool.
• Validates simulation result: if failed, extracts the specific Soroban error code and translates to a typed ApiError with user-friendly remediation hints.
• Adds recommended 15% resource fee buffer to prevent out-of-gas errors.

---

Target Files

• backend/src/routes/v1/stream.routes.ts
• backend/src/controllers/stream.controller.ts
• backend/src/services/sorobanService.ts
• backend/tests/soroban.service.test.ts

---

Acceptance Criteria

• Endpoint correctly simulates create, withdraw, cancel, and top_up contract calls.
• Returns valid base64-encoded unsigned XDR consumable by Freighter wallet.
• Reverted simulations return appropriate HTTP 400 with decoded contract error messages.
• Unit tests mock both successful and failed Soroban RPC simulation responses.

[codefather2026]

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

Hi maintainer, i will like to solve this issue

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

[Mikey-222]

@Mikey-222 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

can i take this

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

[drips-wave]

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

🧑‍💻 @Mikey-222: 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 @Mikey-222 as part of the Stellar Wave Program's 9th Wave 🥳

😎 @Mikey-222: 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.