🚀 SOVEREIGN Protocol
Deployment Guide
Complete deployment instructions from local testing to mainnet launch
🚀 Quick Deployment Overview
This guide covers deploying the SOVEREIGN protocol from local testing through mainnet deployment. The protocol has been fully tested and verified on local blockchain with all 23 tests passing.
✅ Current Status: Ready for Deployment
- 23/23 tests passing locally
- All smart contracts deployed and verified
- AI agents operational and tested
- Frontend dashboard functional
- Multi-chain architecture ready
🛠️ Prerequisites
Required Software
- Node.js: 18.0.0 or higher
- npm: 8.0.0 or higher
- Git: Latest version
- MetaMask: Browser wallet
Required Accounts
- Ethereum wallet with private key
- OpenAI API key for AI agents
- Farcaster account (optional)
- RPC provider (Alchemy, Infura)
ETH Requirements
- Local testing: 0 ETH
- Testnet: ~0.5 ETH for gas
- Mainnet: ~2-5 ETH for deployment
🔧 Environment Setup
1. Clone and Install
# Clone the repository
git clone https://github.com/your-org/sovereign-protocol.git
cd sovereign-protocol
# Install dependencies
npm install
# Copy environment template
cp .env.example .env
2. Configure Environment Variables
# Deployment Configuration
PRIVATE_KEY=your_deployment_private_key_here
DEPLOYER_ADDRESS=your_deployer_address_here
# Network RPC URLs
MAINNET_RPC_URL=https://eth-mainnet.alchemyapi.io/v2/your-api-key
GOERLI_RPC_URL=https://eth-goerli.alchemyapi.io/v2/your-api-key
ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/your-api-key
BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/your-api-key
# AI Configuration
OPENAI_API_KEY=your_openai_api_key_here
CONFIDENCE_THRESHOLD=80
# Treasury Settings
AGENT_DECISION_INTERVAL=3600000 # 1 hour
MAX_TRANSACTION_SIZE=0.01 # Starting ETH limit
COOLDOWN_PERIOD=1800 # 30 minutes
# Security Settings
EMERGENCY_PAUSE_ENABLED=true
INITIAL_SOVEREIGNTY_LEVEL=1
3. Verify Configuration
# Test environment setup
npm run test:config
# Verify network connectivity
npm run test:networks
# Check account balances
npm run check:balances
📍 Local Development Deployment
Quick Start (Recommended)
# Windows
./quick-start.ps1
# Linux/Mac
./quick-start.sh
# Follow the menu options:
# 1. Full Setup (recommended for first time)
# 2. Test Everything
# 3. Start Development Environment
Manual Local Deployment
# Terminal 1: Start local blockchain
npx hardhat node
# Terminal 2: Deploy contracts
npm run deploy:local
# Terminal 3: Start AI agents
npm run start:agents
# Terminal 4: Start frontend
cd frontend && npx http-server -p 3000
Verify Local Deployment
# Run all tests
npm test
# Check deployment addresses
cat deployments/localhost-deployment.json
# Verify agent status
curl http://localhost:3001/agents/status
Expected Output:
{
"network": "localhost",
"chainId": "31337",
"contracts": {
"SOVToken": "0x610178dA211FEF7D417bC0e6FeD39F05609AD788",
"AgentController": "0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e",
"SovereignTreasury": "0xA51c1fc2f0D1a1b8494Ed1FE312d7C3a78Ed91C0",
"SovereignStaking": "0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82"
}
}
🌐 Testnet Deployment
Goerli Testnet Deployment
# 1. Get Goerli ETH from faucet
# Visit: https://goerlifaucet.com
# 2. Deploy to Goerli
npm run deploy:goerli
# 3. Verify contracts on Etherscan
npm run verify:goerli
# 4. Start agents on testnet
NETWORK=goerli npm run start:agents
Multi-Testnet Deployment
# Deploy to all testnets
npm run deploy:all-testnets
# This runs:
# - Goerli deployment
# - Arbitrum Goerli deployment
# - Base Goerli deployment
# - Cross-chain verification
Testnet Verification Checklist
- ☐ All contracts deployed successfully
- ☐ Contract verification on block explorers
- ☐ AI agents connecting and operational
- ☐ Frontend connecting to testnet contracts
- ☐ Staking functionality working
- ☐ Treasury operations executing
- ☐ Social media integration active
- ☐ Cross-chain bridges operational
🏗️ Mainnet Deployment
⚠️ Pre-Deployment Security Checklist
- ☐ Smart Contract Audit: Professional audit completed
- ☐ Security Review: Internal security assessment passed
- ☐ Agent Testing: AI agents tested extensively on testnet
- ☐ Economic Model: Tokenomics validated under stress
- ☐ Emergency Procedures: Incident response plan prepared
- ☐ Insurance: Smart contract insurance in place
Phase 1: Core Contracts
# 1. Deploy core contracts to Ethereum mainnet
npm run deploy:mainnet:core
# 2. Verify contracts on Etherscan
npm run verify:mainnet
# 3. Initialize with conservative settings
npm run initialize:mainnet:conservative
Phase 2: Agent Activation
# 1. Start agents in monitoring mode
NETWORK=mainnet MODE=monitoring npm run start:agents
# 2. Monitor for 24 hours, then activate
npm run agents:activate:mainnet
# 3. Gradually increase autonomy
npm run agents:increase-autonomy --level=1
Phase 3: Multi-Chain Expansion
# Deploy to Layer 2s
npm run deploy:arbitrum
npm run deploy:base
# Set up cross-chain bridges
npm run setup:bridges
# Verify multi-chain functionality
npm run test:cross-chain
Post-Deployment Configuration
# 1. Fund treasury with initial ETH
npm run treasury:fund --amount=10 --network=mainnet
# 2. Set up initial liquidity
npm run liquidity:setup --pair=SOV/ETH --amount=1000000
# 3. Configure agent parameters
npm run agents:configure --network=mainnet
# 4. Announce launch
npm run launch:announce
🔍 Deployment Verification
Smart Contract Verification
# Verify all contracts on Etherscan
npx hardhat verify --network mainnet
# Bulk verification
npm run verify:all --network=mainnet
Agent Functionality Testing
# Test agent decision making
curl -X POST http://localhost:3001/test/agent-decision \
-H "Content-Type: application/json" \
-d '{"type": "market_analysis", "test_mode": true}'
# Monitor agent performance
tail -f logs/agents.log
Frontend Integration Testing
# Test wallet connection
npm run test:wallet-connection
# Test contract interactions
npm run test:contract-integration
# Load test dashboard
npm run test:frontend-load
📊 Monitoring & Maintenance
Essential Monitoring
# Set up monitoring stack
docker-compose up -d monitoring
# This starts:
# - Prometheus metrics collection
# - Grafana dashboard
# - AlertManager notifications
# - Log aggregation
Key Metrics to Monitor
| Metric | Threshold | Alert |
|---|---|---|
| Agent Success Rate | < 80% | Critical |
| Treasury Balance | < 10 ETH | Warning |
| Gas Price | > 100 gwei | Warning |
| Contract Errors | > 5/hour | Critical |
Daily Maintenance Tasks
# Check agent health
npm run agents:health-check
# Verify treasury performance
npm run treasury:performance-report
# Update market data
npm run data:market-update
# Backup agent logs
npm run logs:backup
🚨 Emergency Procedures
Emergency Pause
# Pause all protocol operations
npm run emergency:pause --network=mainnet
# Pause specific contract
npm run emergency:pause:contract --contract=treasury --network=mainnet
# Resume operations
npm run emergency:resume --network=mainnet
Agent Suspension
# Suspend problematic agent
npm run agents:suspend --agent=treasurer --reason="abnormal_behavior"
# Emergency agent shutdown
npm run agents:emergency-stop
Recovery Procedures
# Restart from safe state
npm run recovery:restart --from-checkpoint=
# Emergency treasury withdrawal
npm run treasury:emergency-withdraw --to=
🎯 Success Criteria
Deployment Success Indicators
- ✅ All contracts deployed and verified
- ✅ Agent success rate >95%
- ✅ Treasury operations executing smoothly
- ✅ Frontend fully functional
- ✅ Community engagement active
- ✅ No critical security issues
- ✅ Economic model performing as expected
Long-term Success Metrics
- TVL Growth: Target $100M+ within 6 months
- User Adoption: 10,000+ active addresses
- Agent Performance: Consistent >95% success rate
- Protocol Autonomy: Level 5 sovereignty achieved
- Multi-chain Presence: Successful L2 deployments
- Ecosystem Growth: 20+ protocol integrations
🚀 Complete Deployment Guide
From development to mainnet - maintaining security and operational excellence