Skip to content

SETUP.md

Latest commit

 

History

History
389 lines (280 loc) · 7.3 KB

SETUP.md

File metadata and controls

389 lines (280 loc) · 7.3 KB
Raw

Zenith Protocol - Setup & Deployment Guide

✅ Pre-Flight Checklist

Before launching Zenith Protocol, verify:

Development Environment

  • Rust 1.84.0+ installed (rustup --version)
  • Stellar CLI v26+ installed (stellar --version)
  • Node.js 20+ installed (node --version)
  • Git configured (git config --list)
  • WebAssembly target added (rustup target list | grep wasm32)

Repository Setup

  • Clone complete: all files present
  • Dependencies installable: cargo build succeeds
  • Tests pass: make test runs without errors
  • Frontend builds: cd frontend && npm install && npm run build
  • Git initialized: .git directory exists

🚀 Quick Start

1. Clone Repository

git clone https://github.com/zenith-protocol/zenith-stellar.git
cd zenith-stellar

2. Add WebAssembly Target

rustup target add wasm32-unknown-unknown

3. Build & Test

# Build the smart contract
make build

# Run all tests
make test

# Format verification
make fmt

4. Setup Frontend

cd frontend

# Install dependencies
npm install

# Create environment config
cat > .env.local << EOF
NEXT_PUBLIC_ZENITH_CONTRACT_ID=to-be-deployed
NEXT_PUBLIC_API_URL=http://localhost:3000
EOF

# Start development server
npm run dev

Visit http://localhost:3000 to see the dashboard.

🌐 Testnet Deployment

Prerequisites

# Install Stellar CLI (macOS/Linux/WSL)
curl https://apt.stellar.org/StellarSecureServer.asc | gpg --import
sudo apt-get install stellar-cli

# Or use Homebrew (macOS)
brew install stellar-cli

# Verify installation
stellar --version

Step-by-Step Deployment

1. Create Stellar Identity

# Generate a keypair for deployment
stellar keys generate zenith_admin --network testnet

2. Fund Your Account

Visit the Stellar Testnet Faucet:

# Visit: https://friendbot.stellar.org/?addr=<YOUR_PUBLIC_KEY>

Verify funding:

stellar account info --account zenith_admin --network testnet

3. Deploy Contract

# From repository root
make deploy

This will:

  • Build the contract
  • Optimize WASM
  • Deploy to testnet
  • Initialize the contract
  • Output: CONTRACT_ID: CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

4. Configure Environment

Update frontend/.env.local:

NEXT_PUBLIC_ZENITH_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
NEXT_PUBLIC_API_URL=http://localhost:3000

5. Test Deployment

# Connect wallet via Freighter browser extension
# Visit http://localhost:3000
# Click "Connect Wallet"
# (Note: won't have points yet - requires admin allocation)

💰 Initialize Protocol (Admin Operations)

After contract deployment, the admin must initialize:

1. Deposit Funds (Sponsor)

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source-account zenith_admin \
  --network testnet \
  -- \
  deposit \
  --from <SPONSOR_ACCOUNT> \
  --amount 50000000000  # 5,000 USDC (in Stroops)

2. Award Points (Admin)

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source-account zenith_admin \
  --network testnet \
  -- \
  award_points \
  --contributor <DEVELOPER_ACCOUNT> \
  --points 100

3. Close Wave

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source-account zenith_admin \
  --network testnet \
  -- \
  close_wave

After closing, developers can claim!

🌍 Mainnet Deployment

⚠️ Pre-Mainnet Checklist

  • Contract security audit completed
  • Testnet stress testing passed
  • All team members trained
  • Legal review done (if applicable)
  • Mainnet keypairs securely backed up
  • Incident response plan documented

Deployment Steps

Same as testnet but replace --network testnet with --network public.

1. Create Production Identity

stellar keys generate zenith_admin_mainnet --network public

2. Fund Account

Contact Stellar Development Foundation or use production exchange.

3. Deploy

# Modify deploy.sh temporarily:
# NETWORK="public"
# SOURCE_ACCOUNT="zenith_admin_mainnet"

./scripts/deploy.sh

4. Verify Deployment

stellar contract info \
  --id <MAINNET_CONTRACT_ID> \
  --network public \
  --rpc-url https://soroban-mainnet.stellar.org

🔐 Security Best Practices

Key Management

# Never commit private keys
echo "*.key" >> .gitignore
echo ".env.production" >> .gitignore

# Backup keys securely (encrypted storage)
# Consider hardware wallets for mainnet

Contract Safety

# Review code before deployment
code contracts/zenith_core/src/lib.rs

# Run comprehensive tests
make test

# Check for vulnerabilities
cargo audit

Frontend Security

# Update dependencies regularly
cd frontend
npm audit
npm update

# Review environment variables
cat .env.local  # Never commit secrets!

📊 Monitoring & Operations

Check Contract State

# Get admin address
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source-account <ANY_ACCOUNT> \
  --network testnet \
  -- \
  get_admin

# Monitor events
curl -X POST https://soroban-testnet.stellar.org \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSorobanEvents",
    "params": [{
      "filters": [{
        "contractIds": ["<CONTRACT_ID>"]
      }]
    }]
  }'

Transaction Monitoring

# View recent transactions
stellar tx fetch <TRANSACTION_HASH> --network testnet

🐛 Troubleshooting

Build Failures

# Clean rebuild
make clean
make build

# Verbose output
RUST_BACKTRACE=1 cargo build

Test Failures

# Run specific test
cargo test test_successful_flow -- --nocapture

# View full output
RUST_LOG=debug cargo test

Deployment Issues

# Verify CLI configuration
stellar network list

# Check account status
stellar account info --account zenith_admin --network testnet

# Ensure sufficient fees
# Current: ~100 stroops per operation

Frontend Issues

# Clear Next.js cache
cd frontend
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Debug TypeScript
npm run build

📚 Documentation

🤝 Getting Help

Resources

Reporting Issues

  1. Search existing GitHub Issues
  2. Create detailed issue with:
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment (OS, versions)
    • Logs/error messages

Security Reports

Do NOT open public issues for security vulnerabilities.

Email: security@zenith-protocol.dev

Status: Ready for Development
Last Updated: July 2026
Maintainers: Zenith Protocol Team