feat(escrow): add Soroban escrow deploy script and docs\n\nCloses #126

README.md

@@ -159,6 +159,11 @@ Future work may introduce an alternative CI/CD pipeline (e.g., a different provi
 
 ---
 
+## Soroban Escrow Deployment
+
+See the Soroban escrow deployment guide for build and deploy steps, example CLI calls, and integration notes: [docs/soroban-escrow-deployment.md](docs/soroban-escrow-deployment.md)
+
+
 ## 📄 License
 
 This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

contracts/deploy_escrow_testnet.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Simple helper to build the escrow contract WASM and show how to deploy it
+# to the Soroban / Stellar Testnet using the `soroban` CLI.
+#
+# Prerequisites:
+#  - Rust + cargo (with wasm32 target installed)
+#  - `soroban` CLI available in PATH
+#  - SOROBAN_RPC_URL set (defaults to https://rpc.testnet.soroban.stellar.org)
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONTRACT_DIR="$ROOT_DIR/contracts/escrow"
+
+echo "[escrow deploy] Building escrow contract..."
+cd "$CONTRACT_DIR"
+
+# Prefer standard cargo build for wasm target; the project Makefile also
+# provides `stellar contract build` which may be available in some setups.
+echo "[escrow deploy] Running cargo build (wasm32-unknown-unknown, release)"
+cargo build --release --target wasm32-unknown-unknown || {
+  echo "cargo build failed — you may need to run 'stellar contract build' or ensure wasm target is installed"
+  exit 1
+}
+
+WASM_PATH="$CONTRACT_DIR/target/wasm32-unknown-unknown/release/escrow.wasm"
+if [ ! -f "$WASM_PATH" ]; then
+  echo "WASM not found at $WASM_PATH"
+  exit 1
+fi
+
+SOROBAN_RPC_URL="${SOROBAN_RPC_URL:-https://rpc.testnet.soroban.stellar.org}"
+export SOROBAN_RPC_URL
+echo "[escrow deploy] Using SOROBAN_RPC_URL=$SOROBAN_RPC_URL"
+
+if ! command -v soroban >/dev/null 2>&1; then
+  echo "soroban CLI not found in PATH. Install from: https://github.com/stellar/soroban-tools"
+  exit 1
+fi
+
+echo "\nBuilt WASM: $WASM_PATH"
+echo "\nTo deploy the contract to the configured Soroban RPC, run:" 
+echo "\n  soroban contract deploy --wasm $WASM_PATH\n"
+
+echo "The `soroban contract deploy` command will submit a transaction and print the resulting contract ID and tx hash."
+echo "After deployment, you can call the contract methods (fund, release, refund, etc.) using `soroban contract invoke`."
+
+echo "If you want this script to run the deploy step automatically, set AUTO_DEPLOY=1 in the environment." 
+if [ "${AUTO_DEPLOY:-0}" = "1" ]; then
+  echo "[escrow deploy] AUTO_DEPLOY=1 detected — running deployment now..."
+  soroban contract deploy --wasm "$WASM_PATH"
+fi
+
+echo "\nDone. See docs/soroban-escrow-deployment.md for full instructions and examples."

docs/soroban-escrow-deployment.md

@@ -0,0 +1,61 @@
+# Soroban Escrow Contract — Deployment Guide
+
+This guide explains how to build and deploy the `escrow` Soroban contract included under `contracts/contracts/escrow` to the Stellar Testnet (Soroban).
+
+Prerequisites
+- Rust + cargo and the `wasm32-unknown-unknown` target installed:
+  - `rustup target add wasm32-unknown-unknown`
+- `soroban` CLI installed and available in your PATH (see https://github.com/stellar/soroban-tools)
+- Network RPC for Soroban testnet (the script defaults to `https://rpc.testnet.soroban.stellar.org`)
+
+Quick build & deploy
+
+1. Build the WASM artifact:
+
+```bash
+cd contracts
+./deploy_escrow_testnet.sh
+```
+
+The script builds the contract and prints the command you can run to deploy using the `soroban` CLI. If you set `AUTO_DEPLOY=1` it will attempt to run the deploy command automatically.
+
+Environment variables
+- `SOROBAN_RPC_URL` — optional. If unset the script uses `https://rpc.testnet.soroban.stellar.org`.
+- `AUTO_DEPLOY=1` — run the deploy command automatically after building.
+
+Example: manual deploy (after building)
+
+```bash
+# deploy the compiled wasm (prints tx hash and contract id)
+soroban contract deploy --wasm contracts/contracts/escrow/target/wasm32-unknown-unknown/release/escrow.wasm
+
+# example: call `fund` as the client (requires the client key available to soroban CLI)
+soroban contract invoke --id <CONTRACT_ID> --fn fund --source <CLIENT_SECRET>
+
+# example: release payment (either client or freelancer can call; pass the caller address as an argument if required)
+soroban contract invoke --id <CONTRACT_ID> --fn release --args <MILESTONE_ID> <CALLER_ADDRESS> --source <CALLER_SECRET>
+
+# example: refund (freelancer invokes)
+soroban contract invoke --id <CONTRACT_ID> --fn refund --args <MILESTONE_ID> <CALLER_ADDRESS> --source <FREELANCER_SECRET>
+```
+
+Notes on contract functions and mapping
+- `initialize(...)` — creates an escrow (maps to requested `create_escrow`).
+- `fund()` — lock funds into the contract (maps to `fund_escrow`).
+- `submit_milestone(milestone_id)` — freelancer submits completed milestone.
+- `approve(milestone_id)` — client approves submitted milestone.
+- `freelancer_confirm(milestone_id)` — freelancer confirms approval.
+- `release(milestone_id, caller)` — releases funds to freelancer (maps to `release_payment`).
+- `refund(milestone_id, caller)` — refunds client (maps to `refund_payment`).
+- `dispute(...)` / `resolve_dispute(...)` — dispute and arbiter resolution.
+
+Integration notes
+- The contract expects an SPL-like token address (`token`) passed at initialization. The contract uses the standard `token::Client` interface for transfers.
+- Constructing the initialization `milestones` vector via CLI can be complex; for integration we recommend using the `@stellar/stellar-sdk` / Soroban client in an application script to upload WASM and call `initialize` with typed arguments.
+
+Replacing the JS stub
+- The repository contains a JS stub at `lib/soroban/deploy.ts`. Replace that stub with an implementation that uploads the compiled WASM, sends the install/create contract transaction, and returns the deployed contract ID and tx hash. See notes in that file for steps.
+
+Further reading
+- Soroban RPC & CLI docs: https://soroban.stellar.org
+- Soroban developer docs: https://soroban.stellar.org/docs