[CONTRACT-03] Soroban Deployment Scripts & Contract Address Registry

[mftee]

⚠️ Depends on: [CONTRACT-01] & [CONTRACT-02] — contracts must be tested before deployment automation is built.

Overview

All five Soroban contracts are written and tested, but there are no deployment scripts, no testnet deployment instructions, and no way to track which contract addresses are in use. This issue sets up the full deployment pipeline for Soroban testnet and documents the production deploy path. The backend will consume the deployed contract addresses from [BE-28] and [BE-29].

Technical Details

1. Deployment Shell Scripts (in contracts/scripts/)

Create the following scripts:

contracts/scripts/deploy-all.sh
Full deployment script for all 5 contracts:

#!/bin/bash
# Usage: ./deploy-all.sh --network testnet --identity alice
# Requires: Soroban CLI installed and a funded testnet account

set -e
NETWORK=${1:-testnet}
IDENTITY=${2:-default}

echo "=== Deploying FreightFlow Soroban Contracts to $NETWORK ==="

# Build all
cargo build --manifest-path contracts/Cargo.toml --target wasm32-unknown-unknown --release

# Deploy each contract and capture addresses
IDENTITY_ADDR=$(soroban contract deploy --wasm target/wasm32-unknown-unknown/release/identity.wasm --network $NETWORK --source $IDENTITY)
SHIPMENT_ADDR=$(soroban contract deploy --wasm target/wasm32-unknown-unknown/release/shipment.wasm --network $NETWORK --source $IDENTITY)
ESCROW_ADDR=$(soroban contract deploy --wasm target/wasm32-unknown-unknown/release/escrow.wasm --network $NETWORK --source $IDENTITY)
DOCUMENT_ADDR=$(soroban contract deploy --wasm target/wasm32-unknown-unknown/release/document.wasm --network $NETWORK --source $IDENTITY)
REPUTATION_ADDR=$(soroban contract deploy --wasm target/wasm32-unknown-unknown/release/reputation.wasm --network $NETWORK --source $IDENTITY)

# Write to .env file
cat > contracts/deployed-addresses.env << EOF
IDENTITY_CONTRACT_ADDRESS=$IDENTITY_ADDR
SHIPMENT_CONTRACT_ADDRESS=$SHIPMENT_ADDR
ESCROW_CONTRACT_ADDRESS=$ESCROW_ADDR
DOCUMENT_CONTRACT_ADDRESS=$DOCUMENT_ADDR
REPUTATION_CONTRACT_ADDRESS=$REPUTATION_ADDR
EOF

echo "✅ All contracts deployed. Addresses saved to contracts/deployed-addresses.env"

contracts/scripts/initialize-contracts.sh
Calls any required initialize(admin_address) or init() functions on the deployed contracts:

source contracts/deployed-addresses.env
soroban contract invoke --id $IDENTITY_CONTRACT_ADDRESS --network testnet -- initialize --admin $ADMIN_ADDRESS
# (repeat for each contract that requires initialization)

contracts/scripts/upgrade.sh (template only):
Documents the contract upgrade path using soroban contract install + upgrade to replace WASM bytecode.

2. Contract Address Registry (contracts/deployed-addresses.md)

Create a markdown file tracking deployed addresses across environments:

| Contract | Testnet | Mainnet |
|---|---|---|
| Identity | Cxxx... | — |
| Shipment | Cxxx... | — |
| Escrow | Cxxx... | — |
| Document | Cxxx... | — |
| Reputation | Cxxx... | — |

Update this file after each deployment.

3. Backend .env Template Update

Add to backend/.env.example:

IDENTITY_CONTRACT_ADDRESS=
SHIPMENT_CONTRACT_ADDRESS=
ESCROW_CONTRACT_ADDRESS=
DOCUMENT_CONTRACT_ADDRESS=
REPUTATION_CONTRACT_ADDRESS=

4. GitHub Actions CI for Contracts

Add .github/workflows/contracts-ci.yml:

name: Soroban Contracts CI
on:
  push:
    paths: ['contracts/**']
  pull_request:
    paths: ['contracts/**']
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown
      - name: Run contract tests
        run: cd contracts && cargo test
      - name: Build WASM binaries
        run: cd contracts && cargo build --target wasm32-unknown-unknown --release

Acceptance Criteria

• ./contracts/scripts/deploy-all.sh successfully deploys all 5 contracts to Stellar testnet
• Deployed addresses are written to contracts/deployed-addresses.env
• contracts/deployed-addresses.md is updated with testnet addresses
• backend/.env.example includes all 5 contract address variables
• .github/workflows/contracts-ci.yml exists and runs cargo test + WASM build on PRs touching contracts/
• All 5 contracts compile to WASM without errors (cargo build --target wasm32-unknown-unknown --release)
• Initialize script correctly calls each contract's admin setup function

[Chongai-Cli]

Hello maintainer, can i be assigned to this issue?