feat(contracts): Complete smart contract infrastructure for pool creation with Safe multi-sig integration

.gitignore

@@ -11,11 +11,36 @@ firestore-debug.log
 # Env Variables
 .env
 .env.*
+!.env.template
 
 # Ngrok config (contains personal authtoken)
 ngrok.yml
 
 # Claude Code files
 CLAUDE.md
 **/CLAUDE.md
-.claude/
+.claude/
+
+# SuperDesign files
+.superdesign/
+
+# Hardhat contracts
+packages/contracts/artifacts/
+packages/contracts/cache/
+packages/contracts/coverage/
+packages/contracts/coverage.json
+packages/contracts/typechain-types/
+packages/contracts/.openzeppelin/
+packages/contracts/deployments/
+
+# Service account keys
+packages/backend/service-account-key.json
+
+# Wallet information (contains private keys)
+wallet-info.json
+
+# Coverage reports (keep merge script and config files)
+coverage/
+!coverage/.gitkeep
+packages/*/coverage/
+apps/*/coverage/

.nycrc.json

@@ -0,0 +1,29 @@
+{
+  "temp-dir": "./coverage/.nyc_output",
+  "report-dir": "./coverage/merged",
+  "reporter": [
+    "lcov",
+    "text-summary",
+    "html"
+  ],
+  "include": [
+    "packages/*/src/**/*.ts",
+    "apps/*/src/**/*.{ts,tsx}"
+  ],
+  "exclude": [
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/node_modules/**",
+    "**/coverage/**",
+    "**/*.d.ts"
+  ],
+  "extension": [
+    ".ts",
+    ".tsx"
+  ],
+  "cache": true,
+  "all": true,
+  "check-coverage": false
+}

README.md

@@ -25,7 +25,7 @@ This project serves as a comprehensive portfolio piece demonstrating expertise a
 
 - **Multi-Pool Architecture:** Supports the creation of multiple independent lending pools, each with its own members and potentially unique parameters.
 - **Permissioned Membership:** Pool administrators (initially controlled by a multi-sig Safe) approve members before they can contribute or borrow.
-- **Liquidity Contribution:** Pool members can contribute MATIC (or a custom ERC-20 token) to provide liquidity for loans.
+- **Liquidity Contribution:** Pool members can contribute POL (or a custom ERC-20 token) to provide liquidity for loans.
 - **Loan Request & Approval:** Members can request loans from their pool. Loan requests are initially reviewed by an off-chain AI agent (mocked/basic implementation) and then approved by the pool admin.
 - **Loan Repayment & Management:** Borrowers can repay loans. Admins can manage defaults.
 - **Multi-Sig Administration:** Core protocol contracts (like the Pool Factory) are controlled by a [e.g., 2-of-3] multi-signature Safe for enhanced security and progressive decentralization. Individual pools are managed by their respective admin.
@@ -85,6 +85,7 @@ superpool-dapp/
 3.  **Mobile App:** Provides the user interface for interacting with the platform. Features a comprehensive wallet connection system supporting multiple providers (MetaMask, WalletConnect, Coinbase, etc.), signature-based authentication, multi-chain support, and robust error handling with user-friendly feedback.
 
 **Authentication Flow:**
+
 1. User connects wallet via Reown AppKit (supports 100+ wallets)
 2. App requests authentication message from backend Cloud Function
 3. User signs message with their wallet (cryptographic proof of ownership)
@@ -100,9 +101,10 @@ Follow these steps to set up and run the SuperPool project locally.
 - Node.js (v18 or higher)
 - pnpm (install via `npm install -g pnpm`)
 - Git
-- A Polygon (Amoy Testnet recommended) wallet with some MATIC for gas.
+- A Polygon (Amoy Testnet recommended) wallet with some POL for gas.
 - A Firebase project set up with Firestore, Authentication, and Cloud Functions enabled.
 - A Reown Cloud account and project ID for wallet connections (sign up at [cloud.reown.com](https://cloud.reown.com)).
+- **Alchemy account and API key** (sign up at [alchemy.com](https://alchemy.com) for blockchain RPC access - required for contract deployment and forked network testing).
 - **ngrok account and authtoken** (sign up at [ngrok.com](https://ngrok.com) for local development with mobile devices).
 
 ### 1. Clone the Repository
@@ -134,7 +136,7 @@ PRIVATE_KEY=[YOUR_TESTNET_DEPLOYER_PRIVATE_KEY]
 
 # Polygon Amoy RPC URL (e.g., Alchemy, Infura)
 POLYGON_AMOY_RPC_URL=https://polygon-amoy.g.alchemy.com/v2/[YOUR_ALCHEMY_KEY]
-POLYGONSCAN_API_KEY=[YOUR_POLYGONSCAN_API_KEY] # For contract verification
+ETHERSCAN_API_KEY=[YOUR_ETHERSCAN_API_KEY] # For contract verification (works for all chains)
 ```
 
 - `packages/backend/.env`
@@ -176,20 +178,79 @@ EXPO_PUBLIC_CLOUD_FUNCTIONS_BASE_URL=https://[HOST]:[PORT]/[YOUR_PROJECT_ID]/[YO
 EXPO_PUBLIC_POOL_FACTORY_ADDRESS=[DEPLOYED_POOL_FACTORY_ADDRESS_ON_AMOY]
 ```
 
-### 4. Deploy Smart Contracts (Testnet)
+### 4. Smart Contract Development
+
+You have multiple options for smart contract development and testing:
+
+#### Option A: Local Development (Recommended for Development)
+
+**Fastest iteration for development and testing:**
+
+```bash
+# Terminal 1: Start local Hardhat node
+cd packages/contracts
+pnpm node:local
+
+# Terminal 2: Deploy contracts with test data
+pnpm deploy:local
+
+# Terminal 3: Interactive testing
+pnpm console:local
+```
+
+**What you get:**
 
-Navigate to the `contracts` package and deploy:
+- ✅ 3 pre-configured test pools with different parameters
+- ✅ 10 funded test accounts with clear roles (deployer, pool owners, borrowers, lenders)
+- ✅ 50 POL funding per pool for immediate testing
+- ✅ Complete deployment info for mobile app integration
+- ✅ Instant transactions, free gas, full control
+
+#### Option B: Forked Development (Most Realistic Testing)
+
+**Test against real network state:**
 
 ```bash
+# Terminal 1: Start forked node (requires POLYGON_AMOY_RPC_URL in .env)
 cd packages/contracts
-pnpm deploy:amoy # This command should be defined in your package.json scripts
+pnpm node:fork
+
+# Terminal 2: Deploy to forked network
+pnpm deploy:fork
+
+# Terminal 3: Test against real network state
+pnpm test:fork
+```
+
+#### Option C: Testnet Deployment (Pre-Production Testing)
+
+**Deploy to Polygon Amoy testnet:**
+
+```bash
+cd packages/contracts
+pnpm deploy:amoy
 ```
 
 - **Important:** Note the deployed `PoolFactory` address. You will need this for your `backend` and `mobile` `.env` files.
+- **Multi-sig Setup:** After `PoolFactory` is deployed, set up your multi-sig Safe (e.g., Gnosis Safe on Polygon Amoy) and transfer ownership of the `PoolFactory` to your Safe.
+
+### 5. Mobile App Integration
 
-- **Multi-sig Setup:** After `PoolFactory` is deployed, set up your multi-sig Safe (e.g., Gnosis Safe on Polygon Amoy) and transfer ownership of the `PoolFactory` to your Safe. All subsequent calls to `createPool` from your backend should be initiated via the Safe.
+The mobile app automatically supports localhost development:
 
-### 5. Deploy Backend Cloud Functions
+- **Localhost Network**: Automatically available in development mode (Chain ID 31337)
+- **Network Switching**: Appears in wallet connection UI when `__DEV__` is true
+- **Contract Integration**: Connect to `http://127.0.0.1:8545` to interact with local contracts
+
+**Quick Mobile Testing:**
+
+1. Start local contracts: `pnpm node:local` → `pnpm deploy:local`
+2. Note the Factory Address from deployment output
+3. Run mobile app: `pnpm start` (in apps/mobile/)
+4. Connect wallet and select "Localhost" network
+5. Interact with your local contracts instantly!
+
+### 6. Deploy Backend Cloud Functions
 
 ---
 
@@ -276,16 +337,19 @@ Here is the complete workflow to test your authentication functions:
 
 ---
 
-### 6. Set Up Wallet Connection (Reown Cloud)
+### 7. Set Up Wallet Connection (Reown Cloud)
 
 Before running the mobile app, you need to set up wallet connection capabilities:
 
 1. **Create a Reown Cloud Account:**
+
    - Visit [cloud.reown.com](https://cloud.reown.com) and create an account.
    - Create a new project and note your **Project ID**.
 
 2. **Update Environment Variables:**
+
    - Add your Reown Project ID to `apps/mobile/.env`:
+
    ```
    EXPO_PUBLIC_REOWN_PROJECT_ID=your_project_id_here
    ```
@@ -294,15 +358,16 @@ Before running the mobile app, you need to set up wallet connection capabilities
    - The app currently supports: Mainnet, Polygon, Arbitrum, Base, BSC, and Polygon Amoy.
    - Networks are configured in `apps/mobile/src/app/_layout.tsx`.
 
-### 7. Set Up Ngrok for Local Development (Mobile Device Testing)
+### 8. Set Up Ngrok for Local Development (Mobile Device Testing)
 
 For testing the mobile app on a physical device with local Firebase emulators, you'll need ngrok:
 
 1. **Configure Ngrok:**
+
    ```bash
    # Copy the template
    cp ngrok.yml.template ngrok.yml
-   
+
    # Edit ngrok.yml and add your authtoken
    # Get your authtoken from: https://dashboard.ngrok.com/get-started/your-authtoken
    ```
@@ -312,24 +377,45 @@ For testing the mobile app on a physical device with local Firebase emulators, y
    authtoken: your_ngrok_authtoken_here
    ```
 
-### 8. Run the Development Environment
+### 9. Complete Development Workflow
 
-Use the automated development script that handles all local setup:
+#### Quick Start (All-in-One)
 
 ```bash
 # Start everything with one command
 pnpm dev
 ```
 
 This command will:
+
 - ✅ Start Firebase emulators (auth, functions, firestore)
 - ✅ Launch ngrok tunnels for mobile device access
 - ✅ Automatically update mobile app environment variables with ngrok URLs
 - ✅ Start the Expo development server
 
-**Manual alternative (if needed):**
+#### Smart Contract Development Workflow
+
+```bash
+# Terminal 1: Start local blockchain
+cd packages/contracts
+pnpm node:local
+
+# Terminal 2: Deploy with test data
+pnpm deploy:local
+
+# Terminal 3: Interactive testing (optional)
+pnpm console:local
+
+# Terminal 4: Start mobile app
+cd apps/mobile
+pnpm start
+```
+
+#### Manual Backend Setup (if needed)
+
 ```bash
 # Start Firebase emulators
+cd packages/backend
 firebase emulators:start
 
 # In another terminal, start ngrok
@@ -340,11 +426,13 @@ cd apps/mobile
 pnpm start
 ```
 
-**Testing the App:**
-- **Mobile Device:** Scan the QR code with Expo Go app on your phone
-- **Simulator:** Use Android/iOS simulator from your development machine
-- **Testing Wallet Connection:** Try connecting with MetaMask Mobile, Coinbase Wallet, or other WalletConnect-compatible wallets
-- **Authentication Flow:** After connecting, you'll be prompted to sign an authentication message to access the dashboard
+**Testing Options:**
+
+- **Local Contracts:** Instant testing with localhost network
+- **Mobile Device:** Scan QR code with Expo Go app
+- **Simulator:** Use Android/iOS simulator
+- **Wallet Connection:** MetaMask Mobile, Coinbase Wallet, WalletConnect-compatible wallets
+- **Network Switching:** Test with localhost, Polygon Amoy, or mainnet
 
 ## 🤝 Multi-Sig Administration
 

SPRINT_PLAN.md

@@ -50,7 +50,7 @@ To build a functional micro-lending decentralized application on Polygon Amoy wh
   - **Backend (Cloud Functions):** Create an API endpoint for a pool admin to approve requests, triggering the `approveMember` call on-chain (via their respective Safe).
   - **Mobile App:** Develop admin UI to view pending join requests and approve/reject them.
 - **Contribute Liquidity to Pool**
-  - **Smart Contracts (`LendingPool.sol`):** Implement `deposit` function (for MATIC/ERC20 contribution into the pool).
+  - **Smart Contracts (`LendingPool.sol`):** Implement `deposit` function (for POL/ERC20 contribution into the pool).
   - **Backend (Cloud Functions):** Listen for `Deposit` events from the contract and update off-chain lender balances and pool liquidity data in Firestore.
   - **Mobile App:** Develop UI for approved members to contribute funds to the pool.
 

apps/mobile/.env.template

@@ -0,0 +1,27 @@
+# SuperPool Mobile App Environment Variables Template
+#
+# This template shows the required environment variables for the mobile app.
+# Copy this file to .env and fill in the actual values.
+#
+# The dev-start.js script will automatically update the ngrok URLs when you run `pnpm dev`
+
+# Firebase Client Configuration (public keys)
+EXPO_PUBLIC_FIREBASE_API_KEY="your-firebase-api-key"
+EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN="your-project.firebaseapp.com"
+EXPO_PUBLIC_FIREBASE_PROJECT_ID="your-project-id"
+EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET="your-project.firebasestorage.app"
+EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID="your-sender-id"
+EXPO_PUBLIC_FIREBASE_APP_ID="your-app-id"
+EXPO_PUBLIC_FIREBASE_MEASUREMENT_ID="your-measurement-id"
+
+# Ngrok URLs for Firebase Emulators (automatically updated by dev-start.js)
+EXPO_PUBLIC_NGROK_URL_AUTH="https://your-auth-tunnel.ngrok-free.app"
+EXPO_PUBLIC_NGROK_URL_FUNCTIONS="your-functions-tunnel.ngrok-free.app"
+EXPO_PUBLIC_NGROK_URL_FIRESTORE="your-firestore-tunnel.ngrok-free.app"
+
+# Cloud Functions Base URL (ngrok domain auto-updated, but keep your project zone)
+# Format: http://NGROK_DOMAIN/YOUR_PROJECT_ID/YOUR_ZONE/
+EXPO_PUBLIC_CLOUD_FUNCTIONS_BASE_URL="http://your-functions-tunnel.ngrok-free.app/your-project-id/us-central1/"
+
+# Reown Project Id for wallet connection
+EXPO_PUBLIC_REOWN_PROJECT_ID="your-reown-project-id"

apps/mobile/jest.config.js

@@ -35,8 +35,8 @@ module.exports = {
     '!src/firebase.config.ts', // Exclude Firebase config that imports Expo modules
     '!src/utils/appCheckProvider.ts', // Exclude App Check provider that imports Expo modules
   ],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov', 'html'],
+  coverageDirectory: '<rootDir>/../../coverage/mobile',
+  coverageReporters: ['lcov', 'text'],
 
   // Module mapping for mocks
   moduleNameMapper: {

apps/mobile/package.json

@@ -51,6 +51,7 @@
     "eslint-plugin-react-native": "^5.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "minimatch": "^10.0.3",
     "react-test-renderer": "19.0.0",
     "ts-jest": "^29.1.1",
     "typescript": "~5.8.3"

apps/mobile/src/app/_layout.tsx

@@ -15,6 +15,7 @@ import { Stack } from 'expo-router';
 import { useEffect } from 'react';
 import Toast from 'react-native-toast-message';
 import { WagmiProvider } from 'wagmi';
+import { localhost } from '../config/chains';
 import { useGlobalLogoutState } from '../hooks/useLogoutState';
 import { useWalletToasts } from '../hooks/useWalletToasts';
 import { SessionManager } from '../utils/sessionManager';
@@ -38,7 +39,7 @@ const metadata = {
   },
 };
 
-const chains = [mainnet, polygon, polygonAmoy, arbitrum, base, bsc] as const;
+const chains = [mainnet, polygon, polygonAmoy, arbitrum, base, bsc, ...(__DEV__ ? [localhost] : [])] as const;
 
 const wagmiConfig = defaultWagmiConfig({ chains, projectId, metadata });