Skip to content

CLAUDE.md

Latest commit

 

History

History
178 lines (137 loc) · 5.77 KB

CLAUDE.md

File metadata and controls

178 lines (137 loc) · 5.77 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Reference

Task Type Reference Document
Architecture decisions, coding standards, security docs/spec/project-guidelines.md
Contract state, types, data flow, API schemas docs/spec/data-schema.md
UI components, styling, animations, OnchainKit docs/spec/frontend-guidelines.md

Always consult the relevant spec document before making changes.

Project Overview

Send $1 or NGMI is a viral Mini-App for Base App and Farcaster. It's a game-theoretic experiment where the last 100 people to send $1 (0.001 ETH) split the entire pot when a 42-minute countdown expires. Every transaction resets the timer.

Key constraints:

  • Mini-App runs in iframe (no localStorage, no <form> tags)
  • Gas-sponsored transactions via Base Paymaster
  • Platform detection for Base App vs Farcaster UX
  • Must call setFrameReady() on load

Common Commands

Frontend (Next.js)

npm run dev          # Start development server at localhost:3000
npm run build        # Production build
npm run lint         # Run ESLint
npm run test         # Run Vitest tests
npm run test:ui      # Run Vitest with UI

Smart Contract (Foundry)

forge build                              # Compile contracts
forge test                               # Run all tests
forge test -vvv                          # Run tests with verbose output
forge test --match-test test_SendOne     # Run specific test
forge test --gas-report                  # Run tests with gas reporting

Contract Deployment

# Load env vars first: source .env
forge script contracts/script/Deploy.s.sol:DeploySendOneOrNGMI \
  --rpc-url $BASE_SEPOLIA_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --verify

Architecture Overview

Smart Contract (contracts/SendOneOrNGMI.sol)

  • Solidity 0.8.20 with OpenZeppelin ReentrancyGuard and Ownable
  • Uses USDC (6 decimals) instead of ETH for payments
  • Constants: ENTRY_FEE (1 USDC), QUEUE_SIZE (100), COUNTDOWN_DURATION (42 min)
  • Circular buffer (winnerQueue[100]) stores last 100 entrants
  • sendOne() is the main entry point (requires USDC approval, resets timer)
  • endGame() callable by anyone after countdown expires
  • batchPayout() distributes pot to all winners in single tx
  • restartGame() any player can restart by paying 1 USDC (becomes first player)
  • ownerRestartGame() owner-only restart without fee (for emergencies)

See docs/spec/data-schema.md for full contract state and function signatures.

Frontend (src/)

  • Next.js 14 App Router with TypeScript
  • providers/MiniKitProvider.tsx: Wraps app with Wagmi, React Query, and OnchainKit MiniKit
  • lib/contract.ts: Contract ABI and constants
  • components/: UI components (CountdownTimer, PotStats, CTASection, LiveQueue, etc.)
  • app/api/paymaster/route.ts: Paymaster proxy endpoint
  • app/api/webhook/route.ts: Farcaster frame webhooks

See docs/spec/frontend-guidelines.md for component patterns and styling.

Key Integration Points

  • Uses OnchainKit's MiniKitProvider with setFrameReady() for Mini-App lifecycle
  • Smart Wallet only (no EOA) via preference: 'smartWalletOnly'
  • Gasless transactions via CDP Paymaster configured in MiniKitProvider
  • Contract data polling via useReadContract with refetchInterval

Platform Detection

const isBaseApp = context?.client?.clientFid === 309857;
const isFarcaster = context?.client?.clientFid === 1 || context?.client?.clientFid === 9152;

Environment Variables

Required variables (see .env.example):

  • NEXT_PUBLIC_ONCHAINKIT_API_KEY: CDP API key
  • NEXT_PUBLIC_CONTRACT_ADDRESS: Deployed contract address
  • CDP_PAYMASTER_URL: CDP Paymaster endpoint (server-side only!)

See docs/spec/data-schema.md for full environment variable schema.

Test Structure

  • Frontend tests: tests/ directory, run with Vitest
  • Contract tests: contracts/test/SendOneOrNGMI.t.sol, run with Forge

When to Consult Spec Documents

docs/spec/project-guidelines.md

Consult when:

  • Making architectural decisions
  • Adding new features or components
  • Understanding security requirements
  • Setting up deployment workflows
  • Reviewing coding standards

docs/spec/data-schema.md

Consult when:

  • Working with contract state or functions
  • Defining TypeScript types
  • Understanding data flow between contract and frontend
  • Implementing API routes
  • Validating data

docs/spec/frontend-guidelines.md

Consult when:

  • Creating or modifying UI components
  • Implementing styling or animations
  • Working with OnchainKit components
  • Adding accessibility features
  • Optimizing performance

Current Project Status

✅ Completed

  • Smart contract with 42-min countdown, batch payout
  • All UI components (7 major components)
  • MiniKit/OnchainKit provider setup
  • API routes (paymaster, webhook, manifest)
  • Contract tests (Foundry)

📋 Pending (Priority Order)

  1. Deploy contract to Base Sepolia testnet
  2. Configure CDP Paymaster
  3. Generate Farcaster manifest signatures
  4. Create app assets (icon, splash, og-image)
  5. Deploy to Vercel
  6. Add share-to-Farcaster functionality
  7. End-to-end testing

See project-tasks.md for detailed task tracking.

Key Files

Purpose File
Contract ABI/Address src/lib/contract.ts
Provider Setup src/providers/MiniKitProvider.tsx
Main Page Logic src/app/page.tsx
Paymaster Proxy src/app/api/paymaster/route.ts
Farcaster Manifest src/app/.well-known/farcaster.json/route.ts
Contract Source contracts/SendOneOrNGMI.sol
Contract Tests contracts/test/SendOneOrNGMI.t.sol
Deploy Script contracts/script/Deploy.s.sol