Skip to content

feat: add Soroban escrow client wrapper#21

Closed
Belzabeem wants to merge 1 commit intoStellarState:mainfrom
Belzabeem:feature/soroban-escrow-client
Closed

feat: add Soroban escrow client wrapper#21
Belzabeem wants to merge 1 commit intoStellarState:mainfrom
Belzabeem:feature/soroban-escrow-client

Conversation

@Belzabeem
Copy link
Copy Markdown

@Belzabeem Belzabeem commented Mar 25, 2026 •
edited
Loading

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:

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

@drips-wave
Copy link
Copy Markdown

drips-wave bot commented Mar 25, 2026

@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
Copy link
Copy Markdown
Contributor

Jayrodri088 commented Mar 25, 2026

@Belzabeem Please fix workflow warnings

@Jayrodri088
Copy link
Copy Markdown
Contributor

Jayrodri088 commented Mar 27, 2026

@Belzabeem Fix workflows or be unassigned

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Soroban escrow client wrapper and env-driven configuration

3 participants

@Belzabeem @Jayrodri088 @Kilwizzy