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

```bash
# From project root
pnpm install
```

## Step 2: Configure Environment Variables

### Frontend (.env.local)

Create `frontend/.env.local`:

```env
# 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`:

```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`:

```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

```bash
# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE solace_treasury;

# Exit psql
\q
```

### 3.2 Run Migrations

```bash
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

```bash
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`:
   ```env
   NEXT_PUBLIC_TREASURY_WALLET_ADDRESS=<deployed_address>
   NEXT_PUBLIC_SUB_ACCOUNT_FACTORY_ADDRESS=<deployed_address>
   ```

2. **Backend** `.env`:
   ```env
   CONTRACT_ADDRESS=<deployed_treasury_wallet_address>
   ```

### 4.3 Verify Contracts (Optional)

```bash
cd contracts
pnpm run verify:sepolia
```

## Step 5: Start Development Servers

### Option A: Run All Services from Root

```bash
# From project root
pnpm run dev
```

### Option B: Run Services Individually

**Terminal 1 - Frontend:**
```bash
cd frontend
pnpm run dev
```
Frontend will be available at http://localhost:3000

**Terminal 2 - Backend API (if implementing REST/tRPC):**
```bash
cd backend
pnpm run dev
```

**Terminal 3 - Event Indexer:**
```bash
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:

```bash
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