Developer Documentation
Technical guide for DeCleanup Rewards
Quick Start
Get DeCleanup Rewards running locally in minutes.
Prerequisites
- Node.js 18+
- Base-compatible wallet (MetaMask, Coinbase Wallet, etc.)
- Git
Installation
git clone https://github.com/DeCleanup-Network/decleanup-mini-app.git
cd decleanup-mini-app
npm install
cp .env.example .env.local
# Edit .env.local with your configuration
npm run devFor detailed local testing instructions, see the Local Testing Guide on GitHub.
Tech Stack
| Category | Technologies |
|---|---|
| Frontend | Next.js 14, TypeScript, Tailwind CSS |
| Blockchain | Wagmi v2, Viem, Base (L2) |
| Wallet | Farcaster SDK, WalletConnect, MetaMask, Coinbase Wallet |
| Storage | IPFS (Pinata) |
| Smart Contracts | Solidity 0.8.20, Hardhat |
Architecture Overview
Key Flows
- Cleanup Submission: Photo → IPFS → On-chain
- Verification: Verifier dashboard → Review → Approve/Reject
- Rewards: Automatic $bDCU distribution
- Impact Products: Dynamic NFT minting and level progression
For detailed system architecture, see the System Architecture documentation on GitHub.
Environment Setup
Configure your environment variables for local development. Copy .env.example to .env.local and fill in your values.
Network Configuration
- Chain ID
- RPC URLs
Contract Addresses
- Impact Product NFT
- Verification Contract
- Reward Distributor
- $bDCU Token
IPFS/Pinata
Important: Pinata keys must be server-side only. Use PINATA_API_KEY, NOT NEXT_PUBLIC_PINATA_API_KEY
- Server-side API keys
Farcaster
- Neynar API key
- Base App ID
WalletConnect
- Project ID
See the .env.example file on GitHub for the complete list of required variables.
Development Commands
| Command | Description |
|---|---|
npm install | Install dependencies |
npm run dev | Start dev server |
npm run build | Build for production |
npm run test | Run tests |
npm run lint | Lint code |
npm run generate:metadata | Generate NFT metadata |
Smart Contracts
Core Contracts
| Contract | Description |
|---|---|
| ImpactProductNFT | Dynamic NFT (10 levels) |
| VerificationContract | Cleanup submissions |
| bDCURewardDistributor | Auto token distribution |
| $bDCU Token | ERC20 reward token |
Reward Structure
| Action | Reward |
|---|---|
| Level Claim | 10 $bDCU |
| Weekly Streak | 2 $bDCU |
| Referral | 3 $bDCU (both parties) |
| Impact Form | 5 $bDCU |
| Verification | 1 $bDCU |
Project Structure
- app/ - Next.js routes
- components/ - Reusable UI components
- lib/ - Business logic (contracts, IPFS, verification)
- contracts/ - Solidity smart contracts
- scripts/ - Utility scripts
Testing
For local development testing, follow the setup steps in Quick Start. Ensure your wallet is connected to Base Sepolia testnet.
Mobile Testing
For mobile testing instructions, see the Local Testing Guide.
Testing Checklist
- Wallet connection and network switching
- Photo upload and IPFS storage
- Cleanup submission and verification flow
- Reward distribution and Impact Product minting
Deployment
Frontend (Vercel)
- Push code to GitHub repository
- Connect repository to Vercel
- Configure environment variables in Vercel dashboard
- Deploy
Smart Contracts (Hardhat)
npx hardhat run scripts/deploy.js --network baseRemember: Set all required environment variables in your deployment platform before deploying.
API Routes
| Route | Method | Description |
|---|---|---|
/api/ipfs/upload | POST | Proxy IPFS uploads |
/api/health | GET | Health check |
Security Notes
- Pinata API keys are server-side only: Never expose API keys in client-side code. Use server-side API routes for IPFS uploads.
- IPFS uploads proxied through API route: All IPFS operations go through
/api/ipfs/uploadto protect credentials. - Wallet connection requires user approval: All wallet operations require explicit user consent.
- Network switching enforced: The app enforces Base network only to prevent transactions on wrong chains.
Troubleshooting
Wallet Connection Issues
Ensure your wallet extension is installed and unlocked. Try refreshing the page or switching networks manually.
IPFS Upload Failures
Verify your Pinata API keys are correctly set in .env.local. Check that keys are server-side only (no NEXT_PUBLIC_ prefix).
Contract Interaction Errors
Confirm you're on the correct network (Base Sepolia for testing). Verify contract addresses in your environment variables match the deployed contracts.