Theme: BuildAnything - Spark Hackathon MVP
Tagline: Every crypto payment deserves a receipt.
ProofPal AI is a production-ready application designed to solve a major personal crypto problem: transaction history tracking and tax compliance. It automatically generates AI-powered, cryptographically verifiable, and IPFS-stored professional payment receipts for transactions on the Monad Testnet, allowing users to search their payments using natural language, verify them onchain, and export beautiful, tax-ready PDF invoices.
- Frontend: Next.js 14 App Router, TypeScript, TailwindCSS v3, Framer Motion
- Wallet: Wagmi, RainbowKit, Viem
- Smart Contract: Solidity, Hardhat, Monad Testnet
- Storage & Database: Pinata IPFS Gateway, Supabase (with offline local failover)
- AI Service: Google Gemini (1.5 Flash Model)
graph TD
User[Web3 User] -->|1. Triggers Payment| FE[Next.js Frontend]
FE -->|2. Web3 TX| Monad[Monad Testnet EVM]
FE -->|3. TX Context| Gemini[Gemini AI Engine]
Gemini -->|4. AI Metadata| FE
FE -->|5. Pin Payload| Pinata[Pinata IPFS Gateway]
FE -->|6. Logs CID & Receipt ID| Contract[Solidity Contract]
FE -->|7. Indexes Receipt| Supabase[Supabase DB / Local Storage]
proofpal-ai/
├── app/ # Next.js App Router (Layout, Page, Global CSS)
│ ├── api/ # API Serverless Routes
│ │ ├── ai/ # Gemini AI Receipt Summary Generator
│ │ ├── ai-search/ # Gemini Natural Language Query Parser
│ │ └── ipfs/ # Pinata IPFS Pinning Gateway
│ ├── verify/[id]/ # Public receipt sharing and cryptographic verification route
│ │ └── page.tsx # Public onchain/IPFS verification view
│ ├── globals.css # Custom design system (glassmorphic theme)
│ ├── layout.tsx # HTML wrapper & Wallet provider
│ └── page.tsx # Router page coordinator
├── components/ # UI Component blocks
│ ├── Landing.tsx # Landing page (Hero, features, timelines)
│ ├── Sidebar.tsx # Navigation drawer & wrong-network warnings
│ ├── Overview.tsx # Metrics, Recharts volume area charts, category pie charts
│ ├── ReceiptsList.tsx # Natural language search input, sorting filters, history card grids
│ ├── CreatePayment.tsx # Send MON form, signatures, AI / IPFS / contract writer
│ ├── ReceiptDetail.tsx # Stripe-like white receipt card, vector PDF exporter, verification QR
│ └── Settings.tsx # Demo mode toggle, cache purging, RPC connection diagnostics
├── contracts/ # Smart contracts
│ └── ProofPalReceipts.sol # Solidity metadata registry
├── scripts/ # deployment automation scripts
│ └── deploy.ts # Hardhat compiler/deployer script
├── lib/ # Services and clients
│ ├── db.ts # Offline-first local storage client & Supabase sync engine
│ └── supabase.ts # Supabase client wrapper
├── docs/ # Documentation deliverables
│ └── demo_script.md # 3-minute video presentation talking points
├── hardhat.config.ts # Solidity hardhat settings
├── tailwind.config.js # Tailwind v3 configurations
└── package.json # Node modules build file
- Node.js version
18.xor20.x - npm or pnpm (if enabled)
cd proofpal-ai
npm installCopy the .env.example file to .env in the root directory:
cp .env.example .envGEMINI_API_KEY: Get a free key from Google AI Studio.PINATA_JWT: Get an IPFS pinning JWT from Pinata.NEXT_PUBLIC_SUPABASE_URL/NEXT_PUBLIC_SUPABASE_ANON_KEY: Setup a quick project on Supabase.PRIVATE_KEY: Your Monad Testnet deployer wallet private key (keep this secret!).
Note
If these variables are not configured, ProofPal AI's resilient fallback template system automatically boots up. This simulates high-fidelity AI summaries, IPFS pinning CIDs, and database updates to allow immediate reviewer/judge exploration without any configuration barriers.
npm run devOpen http://localhost:3000 in your browser.
To connect to Monad Testnet, add the network details manually in MetaMask:
- Network Name: Monad Testnet
- New RPC URL:
https://testnet-rpc.monad.xyz - Chain ID:
10143 - Currency Symbol:
MON - Block Explorer URL:
https://testnet.monadexplorer.com
Request test tokens from the official Monad faucet before deploying/submitting.
npx hardhat compilenpm run deploy:monadUpon successful deployment, copy the contract address printed on the console and paste it as the CONTRACT_ADDRESS constant inside CreatePayment.tsx and page.tsx.
Here is how ProofPal AI checks all boxes to maximize BuildAnything scoring:
- Practical Usefulness: Directly solves invoice management and tax logs for business owners, freelancers, and protocol teams transacting in crypto.
- Dynamic Public Sharing (
/verify/[id]): Anyone can share a receipt QR code or URL. The public page queries the Monad blockchain directly (using a public client RPC) and fetches metadata CIDs from IPFS to execute an authentic, decentralized audit check. - Resilient Offline Fallback: Features a Demo Mode Toggle in Settings. Judges can bypass MetaMask signatures and API keys to experience a fast, simulated receipt generation and verification flow in 30 seconds.
- Premium UI/UX: Custom responsive sidebar drawers for mobile, staggered Framer Motion slide transitions, responsive volume charts, and high-fidelity skeletons while waiting for Gemini AI outputs.
- Stripe-Style Export: Vector-based PDF generation builds high-fidelity invoices complete with verification badges, ledger hashes, and layout alignment.
- RPC Timeout Errors: If the Monad Testnet RPC is congested or down, toggle Demo Mode in the dashboard Settings to simulate successful transactions immediately.
- MetaMask Switch Issues: RainbowKit and Wagmi handles chain checks. If you are on an unsupported chain, the app will show a clear warning banner and switch buttons in both the sidebar and transaction forms to redirect you to Monad Testnet.
- ESLint/TypeScript Errors during Build: Run
npm run buildto verify typings, routing path checks, and React imports.