Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
311 lines (222 loc) · 8.65 KB

DEPLOYMENT.md

File metadata and controls

311 lines (222 loc) · 8.65 KB
Raw

Deployment Guide

How to deploy the Stellar Tipz contract and frontend to Testnet and Mainnet.

Prerequisites

  • Soroban CLI installed (soroban --version → 21.0+)
  • Rust + wasm32-unknown-unknown target
  • A funded Stellar account (Testnet: use Friendbot; Mainnet: real XLM)
  • Node.js 18+ (for frontend)
  • Vercel CLI (optional, for frontend deployment)

Pre-Deployment Checklist

Complete before any deployment (and re-verify before mainnet):

Security

  • cargo test passes for the contract (contracts/tipz)
  • cargo fmt --check and cargo clippy -- -D warnings are clean
  • For mainnet: third-party security audit completed and findings resolved
  • Admin key custody decided (hardware wallet or multisig for mainnet)
  • Fee basis points reviewed and within the contract cap (≤ 1000 bps / 10%)

Testing

  • Full happy path exercised on testnet (register → tip → withdraw)
  • Edge cases verified (dust withdrawal fee, overflow, unregistered profile)
  • Frontend smoke-tested against the deployed testnet contract

Resource / cost estimates

  • Wasm built in --release and (for mainnet) soroban contract optimize run
  • Deploy + initialize resource fees estimated with --sim / dry-run
  • Deployer account funded with enough XLM for deploy and storage rent
  • Storage TTL strategy understood (see docs/adr/ADR-004-storage-strategy.md)

Environment Configuration per Network

Setting Testnet Mainnet
VITE_NETWORK / REACT_APP_NETWORK TESTNET PUBLIC
Network passphrase Test SDF Network ; September 2015 Public Global Stellar Network ; September 2015
Soroban RPC URL https://soroban-testnet.stellar.org a mainnet RPC provider
Native XLM SAC (--native_token) CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC resolve via soroban contract id asset --asset native --network mainnet
Deployer funding Friendbot real XLM
Admin key dev keypair hardware wallet / multisig

1. Contract Deployment

Build the Wasm Binary

cd contracts

# Run tests first
cargo test

# Build optimized release binary
cargo build --target wasm32-unknown-unknown --release

# The Wasm file will be at:
# target/wasm32-unknown-unknown/release/tipz.wasm

Deploy to Testnet

# Generate a deploy key (one time)
soroban keys generate tipz-deployer --network testnet

# Fund it via Friendbot
curl "https://friendbot.stellar.org?addr=$(soroban keys address tipz-deployer)"

# Deploy
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/tipz.wasm \
  --source tipz-deployer \
  --network testnet

# Save the contract ID! Example output:
# CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

Initialize the Contract

CONTRACT_ID="<your-contract-id>"
DEPLOYER_ADDR="$(soroban keys address tipz-deployer)"

# Resolve the native XLM SAC address for testnet:
NATIVE_TOKEN=$(stellar contract id asset --asset native --network testnet)
# Testnet default: CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

soroban contract invoke \
  --id $CONTRACT_ID \
  --source tipz-deployer \
  --network testnet \
  -- \
  initialize \
  --admin $DEPLOYER_ADDR \
  --fee_collector $DEPLOYER_ADDR \
  --fee_bps 200 \
  --native_token $NATIVE_TOKEN

Verify Deployment

# Check contract stats
soroban contract invoke \
  --id $CONTRACT_ID \
  --source tipz-deployer \
  --network testnet \
  -- \
  get_stats

2. Frontend Deployment

Environment Setup

Create frontend-scaffold/.env:

CONTRACT_ID=<deployed-contract-id>
REACT_APP_NETWORK=TESTNET

Build

cd frontend-scaffold
npm install --legacy-peer-deps
npm run build

The production build will be in frontend-scaffold/build/.

Deploy to Vercel

The repo includes a vercel.json at the root:

# Install Vercel CLI
npm i -g vercel

# Deploy (from repo root)
vercel

# Or deploy to production
vercel --prod

Vercel configuration in vercel.json handles:

  • Build command: cd frontend-scaffold && npm install --legacy-peer-deps && npm run build
  • Output directory: frontend-scaffold/build
  • SPA rewrites: all routes → index.html

Deploy via Docker (Alternative)

cd frontend-scaffold

# Build image
docker build -t stellar-tipz-frontend .

# Run locally
docker run -p 8080:80 stellar-tipz-frontend

3. Mainnet Deployment (Future)

⚠️ Mainnet deployment requires a security audit first.

Additional Steps for Mainnet

  1. Security audit — Third-party audit of the Soroban contract
  2. Config changes:
    • Update REACT_APP_NETWORK=PUBLIC
    • Update RPC URL to mainnet
    • Update network passphrase to Public Global Stellar Network ; September 2015
  3. Real XLM — Deployer account needs real XLM for deployment
  4. Admin key security — Use a hardware wallet or multisig for the admin key
  5. Monitoring — Set up event monitoring and alerting

4. Helper Scripts

Located in scripts/:

deploy-testnet.sh

Fully automated testnet deployment — builds, deploys, and initializes the contract in one step.

# Deploy with the pre-built wasm (default):
./scripts/deploy-testnet.sh

# Build the contract first, then deploy:
./scripts/deploy-testnet.sh --build

# Use an optimized wasm (run `soroban contract optimize` first):
./scripts/deploy-testnet.sh --optimized

# Validate inputs and wasm path without actually deploying:
./scripts/deploy-testnet.sh --dry-run

# Use a custom key name (defaults to "tipz-deployer"):
./scripts/deploy-testnet.sh my-key-name

# Override the native XLM SAC address via env var:
NATIVE_TOKEN_ID=<SAC_ADDRESS> ./scripts/deploy-testnet.sh

The script automatically funds the deployer account via Friendbot and calls initialize with --native_token set to the testnet XLM SAC address (CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC by default, overrideable via the NATIVE_TOKEN_ID environment variable).

fund-account.sh

Fund a testnet account:

./scripts/fund-account.sh <PUBLIC_KEY>

generate-bindings.sh

Generate TypeScript bindings from the deployed contract:

./scripts/generate-bindings.sh <CONTRACT_ID>

5. Post-Deployment Checklist

  • Contract deployed and initialized
  • get_stats() returns expected initial values
  • Test register_profile() with a test account
  • Test send_tip() between two test accounts
  • Test withdraw_tips() and verify fee deduction
  • Frontend .env updated with contract ID
  • Frontend builds successfully
  • Frontend deployed and accessible
  • Freighter wallet connects on deployed frontend
  • End-to-end happy path works (register → tip → withdraw)

6. Emergency Procedures and Rollback

Contract pause (first response)

The contract supports an admin pause that blocks state-changing entry points (tips, withdrawals) while reads stay available. On a suspected exploit or critical bug:

  1. As admin, call the contract's pause (see admin.rs) to halt mutations.
  2. Communicate status to users (status page / social) — the frontend should surface a maintenance banner.
  3. Investigate with on-chain events and logs before resuming.
  4. Call unpause only once the issue is understood and mitigated.

Frontend rollback

The frontend is immutable per deployment, so rollback is instant:

# List recent deployments and promote a known-good one
vercel ls
vercel promote <previous-deployment-url>
# or, in the Vercel dashboard: Deployments → previous → "Promote to Production"

If the issue is purely a bad VITE_CONTRACT_ID/network value, fix the env var and redeploy rather than rolling back code.

Contract upgrade vs. redeploy

  • Upgrade (preferred): the contract is upgradeable (ContractVersion is bumped on upgrade). Ship a fixed Wasm via soroban contract install + the admin-gated upgrade path; storage and the contract ID are preserved.
  • Redeploy (last resort): if state is corrupt or the ID must change, deploy a fresh contract, migrate/re-initialize required state, then point the frontend at the new contract ID. There is no automatic state migration — plan it explicitly.

Key compromise

If the admin key is compromised: pause immediately, transfer admin to a new secure key (hardware wallet / multisig) via the admin-transfer path, rotate any related operational secrets, and post-mortem before unpausing.

Post-incident

  • Root cause documented (consider a new docs/adr/ entry if architectural)
  • Regression test added under contracts/tipz/src/test
  • Fix deployed and verified against the post-deployment checklist above