feat: add Soroban escrow client wrapper

[Belzabeem]

Closes #11
This PR adds a server-side client wrapper and configuration so contract calls are isolated, testable, and environment-driven.

Changes

New Module: src/services/stellar/soroban/

File	Description
client.ts	SorobanClient wrapper class with typed methods
config.ts	Environment configuration and validation
errors.ts	Structured error classes
types.ts	TypeScript interfaces
index.ts	Module exports
README.md	Documentation
__tests__/client.test.ts	Unit tests

Modified Files

File	Changes
.env.example	Added SOROBAN_RPC_URL, SOROBAN_RPC_TIMEOUT
jest.config.js	Updated roots to include src directory

Features

• ✅ Reads ESCROW_CONTRACT_ID and RPC settings from env
• ✅ Typed functions for contract surface (fundEscrow, releaseEscrow, getEscrowState)
• ✅ Structured errors when misconfigured (missing contract ID, wrong network)
• ✅ Soroban logic isolated in service layer, away from Express routes
• ✅ Unit tests mock RPC/contract responses - CI does not hit public RPC

Environment Variables

Required

• ESCROW_CONTRACT_ID - Contract ID of the escrow contract

Optional

• SOROBAN_RPC_URL - Soroban RPC endpoint (defaults to testnet)
• SOROBAN_RPC_TIMEOUT - RPC timeout in milliseconds (default: 30000)
• TOKEN_CONTRACT_ID - Token contract ID

Contract Interface

Method	Description	Auth
init	Initialize new escrow	Yes
fund	Fund escrow with XLM	Yes
release	Release funds to recipient	Yes (admin)
cancel	Cancel and refund investor	Yes (admin)
get_state	Read escrow state	No
get_balance	Get escrow balance	No

Security Assumptions

• Admin operations (fundEscrow, releaseEscrow, cancelEscrow) require a trusted platform keypair
• Oracle/price data is trusted and validated by contract logic
• Contract itself enforces release conditions

Testing

# Run type-check
npm run type-check

# Run tests
npm test

Checklist

• Unit tests mock RPC/contract responses
• CI does not hit public RPC
• README/notes include env vars
• npm run type-check passes
• Tests pass

Related Issues

Closes #11

Contract Source

The escrow contract interface should be documented in the contract repository:

• Repository: StellarState/SS-contracts
• ABI: See contract deployment documentation

---

ETA: PR submitted within 24 hours of assignment as promised.

[drips-wave]

@Belzabeem Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Jayrodri088]

@Belzabeem Please fix workflow warnings

[Jayrodri088]

@Belzabeem Fix workflows or be unassigned