solace-bg-dubai/SETUP_GUIDE.md

Complete Setup Guide

This guide walks you through setting up the Solace Treasury DApp from scratch.

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0 (npm install -g pnpm)
• PostgreSQL database (local or remote)
• Ethereum RPC endpoint (Alchemy, Infura, or similar)
• WalletConnect Project ID (from https://cloud.walletconnect.com)

Step 1: Install Dependencies

# From project root
pnpm install

Step 2: Configure Environment Variables

Frontend (.env.local)

Create frontend/.env.local:

# WalletConnect Project ID (get from https://cloud.walletconnect.com)
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id

# RPC URLs (use Alchemy, Infura, or public RPCs)
NEXT_PUBLIC_SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
NEXT_PUBLIC_MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY

# Contract Addresses (set after deployment in Step 4)
NEXT_PUBLIC_TREASURY_WALLET_ADDRESS=
NEXT_PUBLIC_SUB_ACCOUNT_FACTORY_ADDRESS=

Backend (.env)

Create backend/.env:

# PostgreSQL connection string
DATABASE_URL=postgresql://user:password@localhost:5432/solace_treasury

# Ethereum RPC Configuration
RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
CHAIN_ID=11155111

# Contract Address (set after deployment)
CONTRACT_ADDRESS=

Contracts (.env)

Create contracts/.env:

# Network RPC URLs
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY

# Deployer private key (NEVER commit this file)
PRIVATE_KEY=your_private_key_here

# Etherscan API Key for contract verification
ETHERSCAN_API_KEY=your_etherscan_api_key

Step 3: Set Up Database

3.1 Create PostgreSQL Database

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE solace_treasury;

# Exit psql
\q

3.2 Run Migrations

cd backend

# Ensure DATABASE_URL is set in .env
pnpm run db:migrate

This will create all necessary tables:

• organizations
• users
• memberships
• treasuries
• sub_accounts
• transaction_proposals
• approvals
• audit_logs

Step 4: Deploy Smart Contracts

4.1 Deploy to Sepolia Testnet

cd contracts

# Ensure SEPOLIA_RPC_URL and PRIVATE_KEY are set in .env
pnpm run deploy:sepolia

This will output contract addresses. Save these addresses!

4.2 Update Environment Variables

After deployment, update:

1. Frontend .env.local:

   NEXT_PUBLIC_TREASURY_WALLET_ADDRESS=<deployed_address>
   NEXT_PUBLIC_SUB_ACCOUNT_FACTORY_ADDRESS=<deployed_address>
   

2. Backend .env:

   CONTRACT_ADDRESS=<deployed_treasury_wallet_address>
   

4.3 Verify Contracts (Optional)

cd contracts
pnpm run verify:sepolia

Step 5: Start Development Servers

Option A: Run All Services from Root

# From project root
pnpm run dev

Option B: Run Services Individually

Terminal 1 - Frontend:

cd frontend
pnpm run dev

Frontend will be available at http://localhost:3000

Terminal 2 - Backend API (if implementing REST/tRPC):

cd backend
pnpm run dev

Terminal 3 - Event Indexer:

cd backend
pnpm run indexer:start

Step 6: Test the Application

1. Connect Wallet: Open http://localhost:3000 and connect your Web3 wallet (MetaMask, WalletConnect, etc.)

2. Create Treasury: Use the UI to create a new treasury wallet

3. Configure Multisig: Add signers and set threshold in Settings

4. Test Transactions:

   • Send a payment
   • Approve transactions
   • Create sub-accounts

Troubleshooting

Database Connection Issues

• Verify PostgreSQL is running: pg_isready
• Check DATABASE_URL format: postgresql://user:password@host:port/database
• Ensure database exists

Contract Deployment Issues

• Verify RPC URL is correct and accessible
• Ensure account has enough ETH for gas
• Check network ID matches (Sepolia = 11155111)

Frontend Build Issues

• Clear Next.js cache: rm -rf frontend/.next
• Reinstall dependencies: pnpm install
• Check environment variables are prefixed with NEXT_PUBLIC_ for client-side access

Type Errors

• Regenerate TypeScript types: cd contracts && pnpm run compile
• Restart TypeScript server in IDE

Production Deployment

Frontend (Vercel Recommended)

1. Push code to GitHub
2. Connect repository to Vercel
3. Set environment variables in Vercel dashboard
4. Deploy

Backend

Deploy to your preferred hosting (Railway, Render, AWS, etc.):

1. Set environment variables
2. Run migrations: pnpm run db:migrate
3. Start services: pnpm run dev and pnpm run indexer:start

Contracts

Deploy to mainnet after thorough testing and security audits:

cd contracts
pnpm run deploy:mainnet

Security Checklist

• Never commit .env files
• Use environment-specific RPC endpoints
• Keep private keys secure (use hardware wallets for mainnet)
• Verify contracts on Etherscan
• Enable database connection encryption
• Set up rate limiting for API endpoints
• Implement proper CORS policies
• Use HTTPS in production

Next Steps

• Review and customize smart contract parameters
• Set up monitoring and alerting
• Configure backup strategies for database
• Plan for mainnet deployment
• Schedule security audit