SnellCoin 🍃

SnellCoin is an open-source experimental prototype and architectural case study exploring how verified human deeds can be transformed into digital proofs (ERC-721 NFTs on Base Sepolia L2) using a Scandinavian botanical aesthetic.

---

⚠️ Prototype & Educational Disclaimer

Important

This repository is an educational prototype and architectural proof-of-concept (PoC). It was built to explore rapid Web2 (Supabase) + Web3 (Base Sepolia L2 & IPFS) prototyping and gasless UX patterns.

• Not Production Hardened: The current code contains simplified trust boundaries, prototype RLS policies, and simulated merchant/payment flows.
• Testnet Only: All blockchain integrations run exclusively on Base Sepolia (L2 Testnet). Never fund server wallets with mainnet assets or use this code for real financial transactions without implementing server-side authentication and transactional state machines.
• For a complete architectural assessment and future hardening roadmap, see PROJECT_REVIEW.md and BACKLOG.md.

---

🚀 Key Features

• Plant a Seed (/create): Document a positive deed by uploading a photo and description directly from your device.
• Nourish & Verify (/approve): Community consensus mechanism where members review and "water" pending deeds.
• On-chain Proof of Action (NFTs): Approved actions are pinned to IPFS via Pinata and minted as ERC-721 tokens on Base Sepolia (L2).
• Peer-to-Peer Payments (/spend): Prototype QR code generation for local exchanges.
• Merchant Terminal (/merchant): Mobile camera scanner demo for local stores.
• Botanical UX & Tone: Modern interface designed around human growth and natural metaphors without cold financial jargon.

---

🛠 Tech Stack

• Frontend: Next.js 16 (App Router), React 19, Tailwind CSS v4, TypeScript
• Backend / Database: Supabase (PostgreSQL with Row Level Security & Storage)
• Web3 & Blockchain: Base Sepolia L2 via viem and Pinata (IPFS)
• Icons & Tooling: Lucide React, qrcode.react, @yudiel/react-qr-scanner, react-hot-toast

For a complete breakdown of all packages and integrations, see DEPENDENCIES.md.

---

📂 Project Structure

snellCoin/
├── web/                  # Next.js Frontend & API routes
│   ├── src/app/          # App router pages & API endpoints
│   ├── src/components/   # Reusable UI components
│   ├── src/lib/          # Hooks, context, and domain logic
│   └── src/utils/        # Supabase and Web3 client configs
├── database/             # Supabase PostgreSQL schema & triggers
│   └── 01_current_schema.sql
├── docs/                 # GitHub Pages documentation & case study hub
│   ├── index.html
│   ├── learnings-supabase.html
│   ├── learnings-nft-web3.html
│   ├── architecture.html
│   └── smart-contract.html
├── PROJECT_REVIEW.md     # Full architectural and security audit
├── BACKLOG.md            # Completed tasks & future production roadmap
├── CONTRIBUTING.md       # Contribution guidelines
├── SECURITY.md           # Responsible security disclosure
└── README.md             # This file

---

💻 Getting Started Locally

Follow these steps to run SnellCoin on your local machine:

1. Clone the repository and install dependencies

git clone https://github.com/MokanGit/snellCoin.git
cd snellCoin/web
npm install

2. Configure Environment Variables

Copy the template .env.example to .env.local:

cp .env.example .env.local

Fill in your Supabase project credentials:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-public-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-confidential-service-role-key

Note: If Web3 keys (ADMIN_PRIVATE_KEY / PINATA_JWT) are left blank, the app automatically runs in Mock Stub Mode, returning simulated transaction receipts so UI development is 100% functional without blockchain gas.

3. Set Up the Database

Execute the script in database/01_current_schema.sql inside the Supabase SQL Editor.

4. Start the Development Server

npm run dev

Open http://localhost:3000 in your browser.

---

🛣️ Future Work & Production Hardening Roadmap

For contributors looking to evolve this prototype toward a hardened production release:

1. Server-Side Authentication: Enforce session and identity verification inside all service-role API routes (/api/web3/mint, /api/transactions/send).
2. Granular RLS Policies: Restrict user updates using auth.uid() and key profiles to unique user IDs instead of plain email strings.
3. Idempotent Minting State Machine: Implement a robust outbox pattern (pending -> minting -> confirmed/failed) ensuring partial failures do not produce duplicate NFTs.
4. Complete IPFS Image Pinning: Pin raw image bytes directly to IPFS alongside metadata JSON.
5. Full Ledger Migration: Add persistent ledger migrations and atomic transfer RPCs for peer-to-peer payments.

See PROJECT_REVIEW.md and BACKLOG.md for detailed implementation plans.

---

🤝 Contributing

Contributions and learning experiments are welcome! Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting pull requests.

---

📄 License

This project is open-source and licensed under the MIT License.