🤝 soroban-escrow-sdk

A programmable Soroban escrow smart contract and TypeScript SDK — add trustless, condition-based fund locking and release to any Stellar dApp with a three-line integration.

---

Overview

Escrow is a fundamental Web3 primitive — yet every team rebuilds it from scratch. soroban-escrow-sdk gives you a battle-tested, auditable escrow contract and a developer-friendly TypeScript SDK so you can focus on your product, not the plumbing.

Supported release conditions:

• ⏱ Time-lock — funds release after a specified ledger sequence number
• ✅ Arbiter approval — a neutral third party approves or disputes
• 🔑 Milestone hash — release triggered by submitting a pre-agreed SHA-256 deliverable hash

---

Technical Architecture

Stack Overview

Layer	Technology
Smart Contracts	Rust + Soroban SDK (v21)
Contract Testing	Soroban testutils + Cargo test
TypeScript SDK	Node.js 20 + TypeScript
Stellar Client	@stellar/stellar-sdk
Build	tsup (ESM + CJS dual output)
Testing	Vitest
Examples	ts-node runnable scripts

Contract State Machine

CREATED  →  FUNDED  →  RELEASED
                  ↘  DISPUTED  →  RESOLVED (release or refund)
                  ↘  REFUNDED

SDK Quick Start

import { EscrowClient } from 'soroban-escrow-sdk';

const client = new EscrowClient({
  network: 'testnet',
  contractId: 'CXXX...',
  signer: freighterSigner,
});

// Create an escrow with a 1000 XLM time-lock
const escrowId = await client.create({
  depositor: 'G...',
  beneficiary: 'G...',
  amount: '1000',
  asset: 'native',
  releaseCondition: { type: 'timeLock', ledger: 5000000 },
});

// Release when condition is met
await client.release({ escrowId });

---

🌊 Drips Wave Program

This repository participates in the Drips Wave Program — solve scoped GitHub issues and earn crypto rewards streamed directly to your wallet.

How to Contribute & Earn Rewards

Step 1 — Connect to Drips Head to drips.network and connect your Ethereum wallet. All reward payouts go to this address.

Step 2 — Find This Project Search for soroban-escrow-sdk on Drips, or use the link in the GitHub About panel of this repository.

Step 3 — Pick a Funded Issue Issues are labeled by complexity:

Label	Complexity	Typical Reward Range
drips:trivial	Trivial	$10 – $50
drips:medium	Medium	$51 – $200
drips:high	High	$201 – $500+

Examples in this repo:

• Trivial: Add JSDoc comments to all SDK public methods
• Medium: Implement the dispute() method in EscrowClient
• High: Build the full DisputeContract with arbiter resolution logic

Step 4 — Claim Comment /claim on the issue. Do not open a PR for unclaimed issues.

Step 5 — PR & Review Submit a PR with Closes #XX. Contract changes need test coverage. SDK changes need Vitest tests and updated TypeDoc.

Step 6 — Get Paid Drips streams your reward on merge. Trustless, automatic, no forms.

---

Project Structure

soroban-escrow-sdk/
├── contracts/
│   ├── escrow/             # Core EscrowContract (Rust/Soroban)
│   ├── dispute/            # DisputeContract for arbiter flows
│   └── tests/              # Soroban testutils integration tests
├── sdk/
│   ├── src/
│   │   ├── client/         # EscrowClient class
│   │   ├── types/          # TypeScript interfaces & enums
│   │   └── utils/          # Condition builders, XDR helpers
│   └── tests/              # Vitest SDK unit tests
├── examples/
│   ├── basic-escrow/       # Time-lock example script
│   └── milestone-escrow/   # Hash-verified release example
├── scripts/                # Contract deploy & seed scripts
├── .github/
│   └── workflows/          # CI: cargo test, SDK build, Vitest
├── Cargo.toml
├── package.json
└── README.md

---

Getting Started

# Clone
git clone https://github.com/YOUR_ORG/soroban-escrow-sdk.git
cd soroban-escrow-sdk

# Build contracts
cargo build --target wasm32-unknown-unknown --release

# Test contracts
cargo test

# Install SDK dependencies
cd sdk && npm install

# Build SDK
npm run build

# Run the basic escrow example
cd ../examples/basic-escrow
npx ts-node index.ts

---

License

MIT © soroban-escrow-sdk contributors