Building on Celo

# Building on Celo — Workshop Guide > A hands-on guide: build a production MiniPay app from scratch using Claude, Vercel, and the Celo stack. --- ## Module 00 — Celopedia: AI-native Celo ecosystem intelligence Install Celopedia first. It gives Claude verified contract addresses, live grant data, MiniPay submission requirements, DeFi protocol references, and Celo-specific security patterns — all queryable in natural language. ```bash npx skills add celo-org/celopedia-skills # Works with Claude Code, Cursor, Cline, Codex, and 10+ more agents ``` ### Why Celopedia changes how you build on Celo - **150+ verified contract addresses** — ask Claude instead of searching Celoscan. Wrong addresses = lost funds. - **Live grant matching** — fetches active programs from celopg.eco in real time. Proof of Ship, Prezenti, Builder Fund, Divvi, and 20+ more. - **MiniPay checklist built-in** — the full official submission requirements: copy rules, UI constraints, asset format (WebP/SVG only), PageSpeed targets, country-level targeting. - **DeFi protocol reference** — Aave V3, Uniswap V3/V4, Morpho Blue, Mento, x402, stCELO — correct ABIs, pool addresses, and Celo-specific gotchas. - **Ecosystem search** — query 6,300+ products via The Grid to validate your idea before building. - **Celo-specific security patterns** — aToken ratio drift, CIP-64 fee abstraction accounting, CELO token duality, L2 epoch effects. ### Example prompts (after installing Celopedia) ``` "What is the Aave V3 Pool address on Celo mainnet?" "What USDT adapter do I use for fee abstraction?" "What grants can I apply to right now for my MiniPay app?" "Review my app.js for MiniPay compliance issues." "Is there a no-loss lottery already live on Celo?" ``` > Learn more: celopedia.celo.org --- ## Module 01 — Setting up Claude with Celo Skills Claude Code is Anthropic's terminal-based AI agent. With the right MCP servers it can read your contracts, call RPC nodes, deploy to Vercel and push to GitHub — all in one session. ### Step 1 — Install Claude Code ```bash npm install -g @anthropic-ai/claude-code claude # opens interactive session ``` ### Step 2 — Add project-specific context to CLAUDE.md Create a `CLAUDE.md` at the root of your project. Claude reads this on every session. Keep it focused on YOUR contract addresses — protocol addresses (USDT, USDC, Aave, etc.) are handled automatically by Celopedia (Module 00). ```markdown # CLAUDE.md — project-specific context only ## Network - Chain: Celo Mainnet (chainId 42220) - RPC: https://forno.celo.org - Explorer: https://celoscan.io ## My Contracts - MyContract: 0xYOUR_CONTRACT_ADDRESS # Protocol addresses (USDT, USDC, Aave, etc.) → ask Celopedia ## Stack - Frontend: vanilla JS, deployed on Vercel (static) - Backend: Node.js serverless functions (api/*.js) - Wallet: MiniPay first, then WalletConnect fallback ``` ### Step 3 — Connect the Celo MCP server ```json // ~/.claude/mcp_servers.json { "mcpServers": { "celo": { "command": "npx", "args": ["-y", "@celo/mcp-server"], "env": { "CELO_RPC": "https://forno.celo.org" } } } } ``` > ⚠️ Never put private keys in mcp_servers.json. ### Step 4 — Starting prompt for every Claude session ``` You are helping me build a MiniPay mini-app on Celo. Stack: Solidity (contract already deployed), vanilla JS frontend, Node.js Vercel serverless functions, ethers.js v6. RPC: https://forno.celo.org | ChainId: 42220 Always use ethers.js v6 syntax (no .connect() on provider directly, use new ethers.JsonRpcProvider()). Ask before adding dependencies. ``` --- ## Module 02 — Smart contract security with Pashov Never deploy without an automated audit pass. ### Step 1 — Install Slither ```bash pip3 install slither-analyzer # Then ask Claude: # "Run slither on contracts/MyContract.sol and explain every HIGH and # MEDIUM finding. Suggest a fix for each one." ``` ### Step 2 — Pashov audit checklist prompt Paste into Claude Code: ``` Read contracts/MyContract.sol and audit it against the Pashov security checklist: 1. Reentrancy (CEI pattern, ReentrancyGuard) 2. Integer overflow / underflow (Solidity 0.8+ built-in, SafeMath) 3. Access control (onlyOwner, roles, constructor ownership) 4. Front-running / MEV exposure 5. Oracle manipulation 6. Unchecked external calls 7. Centralization risks 8. Event emissions for all state changes For each item: PASS / FAIL / N/A with explanation. ``` ### Step 3 — Generate a test suite ``` Based on the audit findings, write a full Hardhat test suite in TypeScript that covers: the happy path, reentrancy attack attempt, unauthorized access, and edge cases around deposit/withdrawal math. Use Celo fork (chainId 42220) via hardhat.config.ts. ``` --- ## Module 03 — GitHub + Vercel for automatic deployments ### Step 1 — Project structure ``` my-app/ ├── api/ │ ├── deposit.js # POST → interact with contract │ └── stats.js # GET → read on-chain data ├── frontend/ │ ├── index.html │ ├── app.js │ └── style.css └── vercel.json ``` ### Step 2 — vercel.json ```json { "builds": [ { "src": "api/*.js", "use": "@vercel/node" }, { "src": "frontend/**", "use": "@vercel/static" } ], "routes": [ { "src": "/api/(.*)", "dest": "api/$1.js" }, { "src": "/(.*)", "dest": "frontend/$1" } ], "crons": [ { "path": "/api/daily-job", "schedule": "0 2 * * *" } ], "functions": { "api/daily-job.js": { "maxDuration": 60 } } } ``` ### Step 3 — Env vars in serverless functions ```js const privateKey = process.env.MASTER_PRIVATE_KEY; const rpcUrl = process.env.CELO_RPC || "https://forno.celo.org"; const wallet = new ethers.Wallet(privateKey, new ethers.JsonRpcProvider(rpcUrl)); ``` ### Step 4 — Deploy loop with Claude ``` Deploy to production: npx vercel deploy --prod --yes If the build fails, read the error and fix it, then redeploy. ``` --- ## Module 04 — Integrating MiniPay hooks ### Step 1 — Detect MiniPay ```js function isMiniPay() { return !!(window.ethereum?.isMiniPay); } async function connectWallet() { if (isMiniPay()) { const accounts = await window.ethereum.request({ method: 'eth_requestAccounts' }); return accounts[0]; } return await connectViaWalletConnect(); } ``` ### Step 2 — Switch to Celo network ```js const CELO_CHAIN = { chainId: '0xA4EC', chainName: 'Celo', rpcUrls: ['https://forno.celo.org'], nativeCurrency: { name: 'CELO', symbol: 'CELO', decimals: 18 }, blockExplorerUrls: ['https://celoscan.io'], }; async function ensureCeloNetwork() { try { await window.ethereum.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: CELO_CHAIN.chainId }], }); } catch (err) { if (err.code === 4902) { await window.ethereum.request({ method: 'wallet_addEthereumChain', params: [CELO_CHAIN] }); } } } ``` ### Step 3 — Approve + deposit pattern ```js async function deposit(amountUSDT) { const amount = ethers.parseUnits(amountUSDT.toString(), 6); const allowance = await USDT.allowance(userAddress, CONTRACT_ADDRESS); if (allowance < amount) { const approveTx = await USDT.approve(CONTRACT_ADDRESS, amount); await approveTx.wait(); } const tx = await contract.deposit(amount); await tx.wait(); } ``` ### Step 4 — MiniPay UX rules - Show amounts in USD, not raw wei - Never show a seed phrase or private key UI - Fit the app in a single scrollable page (no nested modals) - Use font-size: 16px minimum - Test on a real Android device --- ## Module 05 — Agents with x402 + MCP + Vercel ### Step 1 — Agent wallet (one private key in Vercel env) ```js // api/agent.js const { ethers } = require("ethers"); const provider = new ethers.JsonRpcProvider(process.env.CELO_RPC || "https://forno.celo.org"); const agent = new ethers.Wallet(process.env.AGENT_PRIVATE_KEY, provider); module.exports = async (req, res) => { const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, agent); const tx = await contract.feed(agent.address); res.json({ ok: true, txHash: tx.hash }); }; ``` ### Step 2 — Schedule with Vercel cron ```json { "crons": [ { "path": "/api/agent", "schedule": "50 5 * * *" } ], "functions": { "api/agent.js": { "maxDuration": 60 } } } ``` > ⚠️ Schedule before your contract's daily deadline, not at midnight. ### Step 3 — MCP server so Claude can control the agent ```js // api/mcp.js const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js"); const { StreamableHTTPServerTransport } = require("@modelcontextprotocol/sdk/server/streamableHttp.js"); const server = new McpServer({ name: "my-app-agent", version: "1.0.0" }); server.tool("get_fox_status", "Read fox state for a wallet", { wallet: { type: "string" } }, async ({ wallet }) => { const status = await contract.getFoxStatus(wallet); return { content: [{ type: "text", text: JSON.stringify(status) }] }; }); server.tool("feed_fox", "Feed the fox (costs 1 USDT)", {}, async () => { const tx = await contract.feed(agent.address); await tx.wait(); return { content: [{ type: "text", text: `Fed! tx: ${tx.hash}` }] }; }); module.exports = async (req, res) => { const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined }); res.on("close", () => transport.close()); await server.connect(transport); await transport.handleRequest(req, res, req.body); }; ``` Connect to Claude Desktop: ```json { "mcpServers": { "my-app": { "url": "https://your-app.vercel.app/api/mcp" } } } ``` ### Step 4 — Fire-and-forget for cron efficiency ```js // ✅ fast — submit and return within the 60s cron window const tx = await contract.feed(agent.address); res.json({ ok: true, txHash: tx.hash, status: "submitted" }); // ❌ slow — awaiting confirmation blocks for ~5s and can timeout await tx.wait(); ``` ### Step 5 — x402 payment gate ```js const { withPaymentRequired } = require("x402-next"); module.exports = withPaymentRequired( async (req, res) => { res.json({ ok: true, data: await getPremiumData() }); }, { amount: "0.01", currency: "USDC", network: "celo", receiver: process.env.PAYMENT_ADDRESS, } ); ``` > x402 turns your endpoint into a monetized AI service — Claude agents pay USDC on Celo per call, no API keys needed. --- ## Module 06 — Building an on-chain dashboard + The Graph Start with direct RPC calls — fast to build and free to run. When you need historical data, time-series charts, or leaderboards at scale, add a subgraph on The Graph. ### Step 1 — Batch RPC calls ```js const [poolSize, totalUsers, myBalance] = await Promise.all([ contract.getTotalDeposited(), contract.getUniqueDepositors(), contract.getUserDeposit(userAddress), ]); ``` ### Step 2 — Read historical events ```js const toBlock = await provider.getBlockNumber(); const fromBlock = toBlock - 518400; // ~30 days on Celo const events = await contract.queryFilter( contract.filters.Deposited(), fromBlock, toBlock ); ``` ### Step 3 — Cache in serverless function ```js module.exports = async (req, res) => { res.setHeader("Cache-Control", "s-maxage=60, stale-while-revalidate=120"); res.setHeader("Access-Control-Allow-Origin", "*"); res.json({ ok: true, ...(await fetchOnChainData()) }); }; ``` ### Step 4 — Frontend auto-refresh ```js async function loadStats() { const data = await fetch("/api/stats?t=" + Date.now()).then(r => r.json()); document.getElementById("pool").textContent = "$" + Number(data.poolSize).toFixed(2); } loadStats(); setInterval(loadStats, 30_000); ``` ### Step 5 — Scale with The Graph subgraph Contract view functions only return current state. The Graph indexes every event into a GraphQL API — O(1) queries for lifetime totals, daily time-series, and leaderboards no matter how many transactions exist. Graph Studio is free. **① Define your schema** ```graphql # schema.graphql type GlobalStats @entity { id: ID! # always "global" totalTxCount: BigInt! totalDepositedUSDT: BigDecimal! # lifetime gross, not net balance totalDepositors: Int! activeDepositors: Int! } type DayStat @entity { id: ID! # "YYYY-MM-DD" date: String! txCount: Int! depositVolume: BigDecimal! uniqueUsers: Int! } ``` **② Map events in AssemblyScript** ```typescript // src/mappings.ts export function handleDeposited(event: Deposited): void { let global = getOrCreateGlobal(); let amount = normaliseUsdt(event.params.amount); // divide by 1_000_000 global.totalDepositedUSDT = global.totalDepositedUSDT.plus(amount); global.totalTxCount = global.totalTxCount + 1; global.save(); let day = getOrCreateDayStat(getDayId(event.block.timestamp)); day.depositVolume = day.depositVolume.plus(amount); day.txCount = day.txCount + 1; day.save(); } ``` **③ Deploy to Graph Studio, query from Vercel** ```js // api/graph-stats.js const ENDPOINT = "https://api.studio.thegraph.com/query/YOUR_ID/your-app/v0.0.1"; module.exports = async (req, res) => { res.setHeader("Cache-Control", "s-maxage=300, stale-while-revalidate=600"); const r = await fetch(ENDPOINT, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: `{ globalStats(id: "global") { totalTxCount totalDepositedUSDT totalDepositors activeDepositors } dayStats(first: 30, orderBy: date, orderDirection: desc) { date txCount depositVolume uniqueUsers } }` }), }); const { data } = await r.json(); res.json({ ok: true, source: "the-graph", ...data }); }; ``` > ⚠️ AssemblyScript gotchas: Use `.toI32()` not `as i32`. Use `BigDecimal.fromString("0")` not `BigDecimal.zero()`. Avoid `parseInt` — it doesn't exist. Renaming an entity changes the collection query name, so redeploy as a new version. --- ## Module 07 — Tracking off-chain data with PostHog ### Step 1 — Add PostHog snippet (use phc_ key, NOT phx_) ```html <script> posthog.init('phc_YOUR_PROJECT_KEY', { api_host: 'https://us.i.posthog.com', person_profiles: 'always', autocapture: true, }); </script> ``` ### Step 2 — Custom wallet events ```js posthog.identify(userAddress); posthog.capture('wallet_connected', { wallet_type: isMiniPay() ? 'minipay' : 'walletconnect' }); posthog.capture('deposit_completed', { amount_usdt: amount }); posthog.capture('withdraw_completed', { amount_usdt: amount }); ``` ### Step 3 — Server-side proxy for HogQL queries ```js // api/analytics.js module.exports = async (req, res) => { res.setHeader("Cache-Control", "s-maxage=300"); const r = await fetch( `https://us.i.posthog.com/api/projects/${process.env.PH_PROJECT_ID}/query/`, { method: "POST", headers: { "Authorization": `Bearer ${process.env.PH_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ query: { kind: "HogQLQuery", // ✅ Use countDistinctIf — CASE WHEN fails silently in HogQL query: `SELECT countDistinctIf(distinct_id, event = '$pageview') as visitors, countDistinctIf(distinct_id, event = 'wallet_connected') as connected FROM events WHERE timestamp >= now() - interval 30 day` } }) } ); res.json({ ok: true, results: (await r.json()).results }); }; ``` ### Step 4 — Zero-config setup wizard ```bash npx -y @posthog/wizard@latest ``` --- *Built with ❤️ on Celo · Powered by Claude*