diff --git a/README.md b/README.md index cc7ee37..6c12926 100644 --- a/README.md +++ b/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. diff --git a/contracts/deploy_escrow_testnet.sh b/contracts/deploy_escrow_testnet.sh new file mode 100644 index 0000000..5b47707 --- /dev/null +++ b/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." diff --git a/docs/soroban-escrow-deployment.md b/docs/soroban-escrow-deployment.md new file mode 100644 index 0000000..22261fd --- /dev/null +++ b/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 --fn fund --source + +# example: release payment (either client or freelancer can call; pass the caller address as an argument if required) +soroban contract invoke --id --fn release --args --source + +# example: refund (freelancer invokes) +soroban contract invoke --id --fn refund --args --source +``` + +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