Soroban escrow client wrapper and env-driven configuration

[Jayrodri088]

Context

The product vision replaces centralized factors with programmable escrow on Stellar (Soroban). The REST API will orchestrate contracts; this issue adds a server-side client wrapper and configuration so contract calls are isolated, testable, and environment-driven.

Complexity & points

High — 200 points

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

• Add a module under e.g. src/services/stellar/soroban/ that:
  • Reads ESCROW_CONTRACT_ID and RPC settings from env.
  • Exposes typed functions for the minimal contract surface you need for wave 1 (e.g. fundEscrow, releaseEscrow, or read-only getEscrowState—align to your actual contract).
  • Returns structured errors when misconfigured (missing contract id, wrong network).
• Keep Soroban logic out of Express route handlers; routes call a thin service.

Out of scope

• Deploying the contract (document link to contract repo if external).
• Full end-to-end investment → escrow in one PR unless already small—prefer wrapper + one integration call site behind a feature flag.

Dependencies / versions

• If soroban-client or additional Stellar packages are required, justify compatibility with existing stellar-sdk and Node 22 in the PR.

Acceptance criteria

• Unit tests mock RPC / contract responses; CI does not hit public RPC unless explicitly allowed.
• Clear README or PR notes: env vars, testnet vs mainnet.
• 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 #11.
• PR links to contract source or interface spec (Wasm ID, ABI, or generated bindings).
• Call out any security assumptions (trusted admin, oracle, etc.).

[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

[Belzabeem]

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

I'd like to take this on. I have scanned the SS-backend repository and see the objective - make Soroban logic out of route handlers into a clean and testable service layer.

What I will create in the path of src/services/stellar/soroban/

• Retrieves env settings of ESCROW CONTRACT ID and RPC settings on startup.
• misconfig- Returns structure errors: absent contract ID, incorrect network, unreachable RPC.
• Wave 1 contract surface typed functions: - fundEscrow, releaseEscrow, getEscrowState
• Typed functions of the wave 2 surface: - fundEscrow, releaseEscrow, getEscrowState
• Routes refer to the slender service - zero Soroban logic leakage into Express handlers.

Testing:

• Unit tests simulation of RPC and contract responses - CI will never go into public RPC.
• type-check Before PR type-check passes, all tests green.

PR will include:

• Closes #11
• Env var testnet vs mainnet
• Env var testnet vs mainnet
• Connection to the source of contract / interface spec.
  Soroban-client is not compatible with existing stellar-sdk + Node 22.
• Security assumptions made out explicitly.

**ETA:Write PR in 24 hours of assignment.

Please assign this to me!

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

[drips-wave]

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

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

[johnsmccain]

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

Hi maintainer, I would like to work on this issue

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