From 71b76fe3dcaa47573b9c482b6cd22490bb874c6b Mon Sep 17 00:00:00 2001
From: snowrugar-beep <snowrugar@gmail.com>
Date: Wed, 27 May 2026 15:10:24 +0000
Subject: [PATCH] feat: configure soroban-cli for local development (#159)

- Add Makefile targets: setup, deploy-testnet, deploy-sandbox, sandbox-start
- Add scripts/deploy.sh supporting testnet/sandbox/mainnet networks
- Add deployments/ directory (tracked via .gitkeep)
- Update .gitignore to exclude deployment JSON files and .stellaraid_contract_id

Acceptance criteria met:
- soroban-cli installed via 'make setup'
- Local sandbox configured via 'make sandbox-start'
- 'make build' compiles all contracts (wasm32-unknown-unknown)
- 'make deploy-sandbox' deploys to local sandbox
- 'make deploy-testnet' deploys to Stellar testnet

Closes #159
---
 .gitignore           |   4 ++
 Makefile             |  53 ++++++++++++++++++----
 deployments/.gitkeep |   0
 scripts/deploy.sh    | 103 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 151 insertions(+), 9 deletions(-)
 create mode 100644 deployments/.gitkeep
 create mode 100755 scripts/deploy.sh

diff --git a/.gitignore b/.gitignore
index e4a1730..deb732b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,3 +26,7 @@ Thumbs.db
 # Soroban
 .stellar/
 soroban.toml
+
+# Deployment records (contain network-specific contract IDs; committed per-env as needed)
+deployments/*.json
+.stellaraid_contract_id
diff --git a/Makefile b/Makefile
index 56a6c2c..79c6bc3 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,5 @@
-.PHONY: build build-wasm build-tools test fmt lint clean help
+.PHONY: build build-wasm build-tools test fmt lint clean help \
+        setup deploy-testnet deploy-sandbox sandbox-start
 
 # Default target
 build: build-wasm build-tools
@@ -40,14 +41,48 @@ clean:
 	cargo clean
 	@echo "✅ Clean complete"
 
+# Install soroban-cli and required Rust targets
+setup:
+	@echo "🔧 Installing soroban-cli..."
+	cargo install --locked stellar-cli --features opt
+	@echo "🔧 Adding wasm32-unknown-unknown target..."
+	rustup target add wasm32-unknown-unknown
+	@echo "✅ Setup complete. Run 'make build' to compile contracts."
+
+# Start local sandbox (requires Docker)
+sandbox-start:
+	@echo "🐳 Starting local Stellar sandbox..."
+	docker run --rm -d \
+		--name stellar-sandbox \
+		-p 8000:8000 \
+		stellar/quickstart:testing \
+		--standalone \
+		--enable-soroban-rpc
+	@echo "✅ Sandbox running at http://localhost:8000"
+	@echo "   RPC endpoint: http://localhost:8000/soroban/rpc"
+
+# Deploy to local sandbox
+deploy-sandbox: build-wasm
+	@echo "🚀 Deploying to local sandbox..."
+	bash scripts/deploy.sh sandbox
+
+# Deploy to Stellar testnet
+deploy-testnet: build-wasm
+	@echo "🚀 Deploying to testnet..."
+	bash scripts/deploy.sh testnet
+
 # Show help
 help:
 	@echo "Available commands:"
-	@echo "  make build       - Build WASM contract and CLI tools"
-	@echo "  make build-wasm  - Build Soroban WASM contract only"
-	@echo "  make build-tools - Build CLI tools only"
-	@echo "  make test        - Run all tests"
-	@echo "  make fmt         - Format code"
-	@echo "  make lint        - Run linter"
-	@echo "  make clean       - Clean build artifacts"
-	@echo "  make help        - Show this help message"
+	@echo "  make setup          - Install soroban-cli and required Rust targets"
+	@echo "  make build          - Build WASM contract and CLI tools"
+	@echo "  make build-wasm     - Build Soroban WASM contract only"
+	@echo "  make build-tools    - Build CLI tools only"
+	@echo "  make test           - Run all tests"
+	@echo "  make fmt            - Format code"
+	@echo "  make lint           - Run linter"
+	@echo "  make clean          - Clean build artifacts"
+	@echo "  make sandbox-start  - Start local Stellar sandbox (requires Docker)"
+	@echo "  make deploy-sandbox - Deploy contract to local sandbox"
+	@echo "  make deploy-testnet - Deploy contract to Stellar testnet"
+	@echo "  make help           - Show this help message"
diff --git a/deployments/.gitkeep b/deployments/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/deploy.sh b/scripts/deploy.sh
new file mode 100755
index 0000000..b4d0218
--- /dev/null
+++ b/scripts/deploy.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# scripts/deploy.sh — Deploy StellarAid core contract to a Soroban network.
+#
+# Usage:
+#   bash scripts/deploy.sh [testnet|sandbox|mainnet]
+#
+# Environment variables (loaded from .env if present):
+#   SOROBAN_ADMIN_SECRET_KEY  — funded account secret key
+#   SOROBAN_NETWORK           — fallback network name (default: testnet)
+#
+# Closes #159, #160
+
+set -euo pipefail
+
+# ── Load .env if present ──────────────────────────────────────────────────────
+if [ -f ".env" ]; then
+  # shellcheck disable=SC1091
+  set -o allexport
+  source .env
+  set +o allexport
+fi
+
+# ── Resolve network ───────────────────────────────────────────────────────────
+NETWORK="${1:-${SOROBAN_NETWORK:-testnet}}"
+
+# ── Network-specific RPC / passphrase ────────────────────────────────────────
+case "$NETWORK" in
+  testnet)
+    RPC_URL="${SOROBAN_TESTNET_RPC_URL:-https://soroban-testnet.stellar.org:443}"
+    PASSPHRASE="${SOROBAN_TESTNET_PASSPHRASE:-Test SDF Network ; September 2015}"
+    ;;
+  mainnet)
+    RPC_URL="${SOROBAN_MAINNET_RPC_URL:-https://soroban-rpc.mainnet.stellar.gateway.fm}"
+    PASSPHRASE="${SOROBAN_MAINNET_PASSPHRASE:-Public Global Stellar Network ; September 2015}"
+    ;;
+  sandbox)
+    RPC_URL="${SOROBAN_SANDBOX_RPC_URL:-http://localhost:8000/soroban/rpc}"
+    PASSPHRASE="${SOROBAN_SANDBOX_PASSPHRASE:-Standalone Network ; February 2017}"
+    ;;
+  *)
+    echo "❌ Unknown network: $NETWORK (use testnet | sandbox | mainnet)"
+    exit 1
+    ;;
+esac
+
+# ── Paths ─────────────────────────────────────────────────────────────────────
+WASM_PATH="target/wasm32-unknown-unknown/release/stellaraid_core.wasm"
+DEPLOYMENTS_DIR="deployments"
+DEPLOYMENT_FILE="${DEPLOYMENTS_DIR}/${NETWORK}.json"
+
+# ── Validate prerequisites ────────────────────────────────────────────────────
+if [ ! -f "$WASM_PATH" ]; then
+  echo "❌ WASM not found at $WASM_PATH — run 'make build-wasm' first"
+  exit 1
+fi
+
+if [ -z "${SOROBAN_ADMIN_SECRET_KEY:-}" ]; then
+  echo "❌ SOROBAN_ADMIN_SECRET_KEY is not set. Add it to .env or export it."
+  exit 1
+fi
+
+# ── Idempotency check ─────────────────────────────────────────────────────────
+if [ -f "$DEPLOYMENT_FILE" ]; then
+  EXISTING_ID=$(python3 -c "import json,sys; d=json.load(open('$DEPLOYMENT_FILE')); print(d.get('contract_id',''))" 2>/dev/null || true)
+  if [ -n "$EXISTING_ID" ]; then
+    echo "ℹ️  Contract already deployed on $NETWORK: $EXISTING_ID"
+    echo "   Delete $DEPLOYMENT_FILE to force a re-deploy."
+    exit 0
+  fi
+fi
+
+# ── Deploy ────────────────────────────────────────────────────────────────────
+echo "🚀 Deploying to $NETWORK..."
+echo "   RPC: $RPC_URL"
+echo "   WASM: $WASM_PATH"
+
+CONTRACT_ID=$(stellar contract deploy \
+  --wasm "$WASM_PATH" \
+  --source "$SOROBAN_ADMIN_SECRET_KEY" \
+  --rpc-url "$RPC_URL" \
+  --network-passphrase "$PASSPHRASE")
+
+echo "✅ Contract deployed!"
+echo "📝 Contract ID: $CONTRACT_ID"
+
+# ── Persist deployment record ─────────────────────────────────────────────────
+mkdir -p "$DEPLOYMENTS_DIR"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+cat > "$DEPLOYMENT_FILE" <<EOF
+{
+  "network": "$NETWORK",
+  "contract_id": "$CONTRACT_ID",
+  "rpc_url": "$RPC_URL",
+  "deployed_at": "$TIMESTAMP",
+  "wasm": "$WASM_PATH"
+}
+EOF
+
+echo "💾 Deployment record saved to $DEPLOYMENT_FILE"
+
+# Also write the plain contract-ID file for backward compatibility
+echo "$CONTRACT_ID" > .stellaraid_contract_id
+echo "✅ Contract ID stored in .stellaraid_contract_id"