Initial commit: add .gitignore and README

2026-02-09 21:51:53 -08:00
commit c94eb595f8
120 changed files with 22079 additions and 0 deletions
--- a/SETUP_GUIDE.md
+++ b/SETUP_GUIDE.md
@@ -0,0 +1,252 @@
+# 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
+