🍪 Cookie Jar Protocol

February 11, 2026 · View on GitHub

Decentralized funding pools with smart access control. Create shared ETH/ERC20 pools with allowlist, NFT, POAP, Unlock Protocol, Hypercerts, and Hats Protocol gating plus configurable withdrawal rules.

📋 Prerequisites

Manual Install: Node.js 18+, Git
Auto-Install: bun, Foundry (installed automatically)
System: 4GB+ RAM, 2GB storage
Editor: VS Code or Cursor (recommended for inline linting)

⚠️ Note on Submodules: This repository uses git submodules for Foundry dependencies. If you encounter SSH errors during bun install, see the Submodule/Foundry Setup Issues section for quick HTTPS workaround or SSH setup instructions.

🚀 Quick Start

Choose your installation method:

Option 1: Auto-install (npm)

git clone https://github.com/greenpill-dev-guild/cookie-jar.git
cd cookie-jar
npm install  # Auto-installs bun + Foundry (via preinstall hook)
bun install  # Install project dependencies
bun dev      # Start development

Option 2: Direct install (bun)

git clone https://github.com/greenpill-dev-guild/cookie-jar.git
cd cookie-jar
bun install  # Auto-installs Foundry + all dependencies
bun dev      # Start development

Open http://localhost:3000 and explore 4 pre-seeded demo jars with Cookie Monster NFTs! 🍪

✨ Auto-setup: Shell script checks system, installs missing tools (bun/Foundry), then sets up complete dev environment.

💡 Note: If you don't have bun installed, Option 1 installs it for you. If you already have bun, use Option 2.

For the best development experience with inline linting errors and auto-fix on save:

  1. Open workspace in VS Code or Cursor
  2. Install recommended extensions when prompted (ESLint, Prettier, Solidity)
  3. Reload window to activate linting
  4. Errors now appear inline as you code!

See docs/DEVELOPMENT.md for details.

💻 Development

bun dev                     # Local development (fastest)
bun dev:ethereum            # Fork Ethereum mainnet  
bun dev:celo                # Fork Celo network
bun dev:base                # Fork Base network
bun dev:base-sepolia        # Fork Base Sepolia testnet

Auto-included: Anvil blockchain, contract deployment, demo seeding, hot reload, type generation.

🔧 Configuration

Local: Zero config needed
Production: cp .example.env .env.local and edit with your API keys

See .example.env for WalletConnect, Alchemy, RPC endpoints, and factory settings.

🔐 Production Wallet (Foundry Keystore)

cast wallet import deployer --interactive  # Enter private key + password
cast wallet list  # Verify keystore created

Benefits: Encrypted keys, no env secrets, industry standard

🎭 Pre-Seeded Demo Jars

4 ready-to-test jars with different patterns:

  1. 🏛️ Community Stipend: Allowlist + ETH + Fixed amounts + Periodic intervals
  2. 💰 Grants Program: Allowlist + ERC20 + Variable amounts + Purpose required
  3. 🍪 Cookie Monster Benefits: NFT-gated + ETH + Variable amounts + NFT rewards
  4. 🎁 Cookie Monster Airdrop: NFT-gated + ERC20 + One-time claims + Token distribution

💡 Use the pre-funded test accounts below to try different access patterns!

📦 Project Structure

cookie-jar/
├── client/             # Next.js frontend 
├── contracts/          # Smart contracts (Foundry/Solidity)
├── docs/               # Documentation
├── e2e/                # Playwright tests
└── scripts/            # Development utilities

Key docs: Access Control • Development • Deployment • Architecture • Testing

Component READMEs: contracts • client • e2e

✨ Core Features

Access Control: Allowlist, NFT-gated, POAP, Unlock Protocol, Hypercerts, Hats Protocol
Distribution: ETH/ERC20 support, fixed/variable amounts, time controls, purpose tracking
Security: Smart contract governed, transparent, emergency controls, Foundry deployment

📚 Detailed Guide: docs/PROTOCOL_GUIDE.md

📋 Development Workflow

Contracts: Edit in contracts/src/ → Auto-recompile → Auto-redeploy → Regen types
Client: localhost:3000 with hot reload on Chain ID 31337
Testing: bun run test (both contracts + client)

bun run test:contracts  # Smart contract tests
bun run test:client     # Frontend tests
bun deploy:local        # Manual deployment
bun seed:demo           # Refresh demo data

🔧 Network Configuration

Local blockchain: http://127.0.0.1:8545 (Chain ID: 31337)
Accounts: 10 pre-funded (1000 ETH each)
Addresses: Deterministic CREATE2 (consistent across restarts)
Fork modes: Ethereum, Celo, Base, Base Sepolia available

🔑 Pre-funded Test Accounts

AccountAddressPrivate KeyBalance
#0 (Deployer)0xf39Fd6e51aad88F6F4ce6aB8827279cffFb922660xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff801000 ETH
#1 (Cookie Monster)0x70997970C51812dc3A010C7d01b50e0d17dc79C80x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d1000 ETH
#2 (Cookie Fan)0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a1000 ETH
#3 (Test User)0x90F79bf6EB2c4f870365E785982E1f101E93b9060x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a61000 ETH
...(6 more accounts)...1000 ETH each

⚠️ Security Note: These are well-known test keys. Never use them on mainnet or testnets!

🛠️ Available Commands

All commands use bun:

# Essential
bun dev                    # Start local development
bun run test               # Run all tests
bun build                  # Build contracts + client

# Development variants  
bun dev:ethereum           # Fork Ethereum mainnet
bun dev:celo               # Fork Celo network
bun dev:base               # Fork Base network
bun dev:base-sepolia       # Fork Base Sepolia testnet

# Deployment
bun deploy:local           # Deploy to Anvil
bun deploy:ethereum        # Deploy to mainnet
bun deploy:celo            # Deploy to celo
bun deploy:base            # Deploy to base
bun deploy:base-sepolia    # Deploy to Base Sepolia testnet

bun seed:demo              # Refresh demo data
bun generate               # Regenerate types

# Utilities
bun lint                   # Lint all code
bun format                 # Format all code
bun clean                  # Clean build artifacts
bun dev:stop               # Stop all services

🚀 Production Deployment Guide

Cookie Jar uses Foundry for secure, efficient deployments to any EVM chain with automatic client configuration updates.

📋 Prerequisites

  1. Foundry installed (curl -L https://foundry.paradigm.xyz | bash && foundryup)
  2. Deployment wallet with funds for the target chain
  3. Environment variables configured (see .example.env)
  4. Etherscan API key (for contract verification)

🔧 Environment Setup

  1. Copy and configure environment variables:

    cp .example.env .env
# Edit .env with your actual values - see .example.env for all options

  2. Key configuration sections (see .example.env for complete list):

    • API Keys: Etherscan verification keys
    • RPC URLs: Network endpoints (Base, Ethereum, Celo, etc.)
    • Factory Configuration: Fee settings, minimum deposits, admin addresses

🔐 Secure Deployment Wallet

✅ Recommended: Foundry Keystore

Already covered in the Secure Wallet Setup section above. This approach:

  • Encrypts private keys with password
  • Keeps secrets out of environment files
  • Works seamlessly with all deployment commands

🌐 Deploy to Any Chain

Universal deployment using secure keystore:

# Export environment variables  
export $(cat .env | xargs)

# Deploy to your target chain (examples):
cd contracts

# Deploy to Base Sepolia
forge script script/Deploy.s.sol:Deploy \
  --rpc-url base-sepolia \
  --account deployer \
  --broadcast \
  --verify

# Deploy to Ethereum Mainnet (requires --verify flag)
forge script script/Deploy.s.sol:Deploy \
  --rpc-url mainnet \
  --account deployer \
  --broadcast \
  --verify

# Deploy to any chain using custom RPC
forge script script/Deploy.s.sol:Deploy \
  --rpc-url $YOUR_CHAIN_RPC_URL \
  --account deployer \
  --broadcast \
  --verify

💡 Security Tip: The --account deployer flag uses your secure keystore. You'll be prompted for your password during deployment.

✅ Post-Deployment

After successful deployment:

  1. Automatic Client Updates: The client configuration automatically updates when contracts are deployed
  2. Contract Verification: Contracts are verified on Etherscan/block explorer automatically
  3. V2 Detection: New deployments are automatically detected as V2 contracts
  4. Factory Address: Copy the deployed factory address to your frontend configuration if needed

🔍 Deployment Verification

Verify your deployment was successful:

# Check contract size is under limit
forge build --sizes | grep CookieJarFactory

# Verify on block explorer
cast call $FACTORY_ADDRESS "owner()" --rpc-url $RPC_URL

# Test factory functionality
cast call $FACTORY_ADDRESS "getCookieJars()" --rpc-url $RPC_URL

🐛 Troubleshooting Deployments

Contract size too large:

# Check sizes
forge build --sizes

# Solution: Contract has been optimized to fit under 24KB limit
# If still too large, increase optimizer runs in foundry.toml

Environment variables not found:

# Export variables explicitly
export $(cat .env | xargs)

# Or source the file
source .env

Keystore password issues:

# List available keystores
cast wallet list

# Re-import if needed (uses secure keystore approach)
cast wallet import deployer --interactive

📁 Generated Files

client/public/contracts/
├── local-deployment.json    # Contract addresses (auto-generated)
└── seed-data.json          # Demo environment data

contracts/
├── anvil.log               # Blockchain logs  
└── out/                    # Compiled contracts

🔍 Troubleshooting

Common Issues

Port Conflicts

  • Client: Port 3000
  • Anvil: Port 8545
  • Solution: Kill conflicting processes with bun dev:stop

Contract Changes Not Reflecting

  1. Check contracts/anvil.log for blockchain errors
  2. Manually redeploy: bun deploy:local
  3. Regenerate types: bun generate
  4. Check deployment sync: bun sync:check

Client Not Connecting to Local Contracts

  1. Ensure NODE_ENV=development
  2. Check client/public/contracts/local-deployment.json exists
  3. Verify Anvil is running on port 8545
  4. Try restarting: bun seed:reset

Environment Issues

  1. Check Node.js version: node --version (should be ≥18.0.0)
  2. Check bun version: bun --version (should be ≥1.0.0)
  3. Check Foundry installation: forge --version
  4. Reinstall dependencies: rm -rf node_modules */node_modules && bun install

Enhanced Features Dependencies

For full functionality of performance monitoring and advanced UX features:

# Install optional enhancement dependencies
bun add web-vitals lodash date-fns
bun add -D @types/lodash

Submodule/Foundry Setup Issues

SSH Authentication Errors (Permission denied (publickey) during install):

This happens because Foundry dependencies use SSH URLs but you don't have SSH keys configured with GitHub.

🚀 Quick Fix (HTTPS Workaround) - Get running immediately:

# Configure git to use HTTPS instead of SSH globally
git config --global url."https://github.com/".insteadOf git@github.com:
git config --global url."https://".insteadOf git://

# Clean and reinstall
cd cookie-jar
rm -rf lib contracts/lib
bun install

✅ Proper Solution (Recommended) - Better long-term:

# 1. Generate SSH key (if you don't have one)
ssh-keygen -t ed25519 -C "your-email@example.com"

# 2. Start ssh-agent and add key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# 3. Add public key to GitHub
cat ~/.ssh/id_ed25519.pub
# Copy output and add to: GitHub Settings > SSH and GPG keys > New SSH key

# 4. Test connection
ssh -T git@github.com
# Should see: "Hi username! You've successfully authenticated..."

# 5. Clean and reinstall
cd cookie-jar
rm -rf lib contracts/lib
bun install

📚 Full SSH Setup Guide: GitHub SSH Documentation

Other Common Issues:

  • Missing forge-std or openzeppelin-contracts: Run git submodule update --init --recursive && cd contracts && forge install
  • Forge command not found: Install Foundry: curl -L https://foundry.paradigm.xyz | bash && foundryup
  • Submodule conflicts: If you have old submodules in contracts/lib/, remove them with rm -rf contracts/lib before running install
  • Still having issues?: Ensure git is properly installed: git --version

Wallet Connection Issues

  1. Add local network to your Web3 wallet (MetaMask, Rabby, or Coinbase Wallet):
    • Network Name: Anvil Local
    • RPC URL: http://127.0.0.1:8545
    • Chain ID: 31337
    • Currency Symbol: ETH
  2. Import test account using private key from table above
  3. Ensure you're on the correct network in your wallet
  4. Try switching between wallets if connection issues persist

Performance Issues

  • Slow builds: Increase Node.js memory: export NODE_OPTIONS="--max_old_space_size=4096"
  • Anvil crashes: Ensure sufficient system memory (8GB+ recommended)
  • Client slow loading: Disable browser extensions or use incognito mode

📊 Logs & Monitoring

Monitor development services:

# View logs in real-time
tail -f contracts/anvil.log          # Blockchain logs
tail -f contracts/client-dev.log     # Client development logs  
tail -f contracts/watch-deploy.log   # Contract watcher logs

# All log files are in contracts/ directory for easy access

🔧 Latest Enhancements

Performance & UX Improvements:

  • Error Boundaries: Global and protocol-specific error handling
  • Transaction Retry: Automatic retry logic with exponential backoff
  • NFT Caching: Intelligent LRU cache with block-based invalidation
  • Mobile UX: Enhanced forms and touch-optimized interactions
  • Performance Monitoring: Core Web Vitals tracking and dashboard
  • Bundle Optimization: Code-splitting and lazy loading

Smart Contract Refactoring:

  • Modular Libraries: Extracted complex logic into reusable libraries
  • Gas Optimization: Circular buffers and storage packing
  • Enhanced Security: Multi-strategy NFT validation and DoS protection
  • Streaming Support: Modular streaming functionality architecture

🎯 Getting Started Guide

For Local Development (Fastest Path)

  1. Install Prerequisites: Node.js (18+), Git
  2. Clone & Setup: 
    git clone https://github.com/greenpill-dev-guild/cookie-jar.git
cd cookie-jar

# If you don't have bun:
npm install && bun install

# If you have bun:
bun install

# Start development:
bun dev
  3. Open Client: Navigate to http://localhost:3000
  4. Connect Wallet: Add local network (Chain ID: 31337) to your Web3 wallet
  5. Import Test Account: Use any account from the pre-funded test accounts table
  6. Explore Demo Jars: 4 pre-seeded jars with different access patterns ready to test

For Production Deployment

  1. Environment Setup: Copy .example.env to .env and configure
  2. Secure Wallet: Set up Foundry keystore with cast wallet import deployer --interactive
  3. Deploy: Use the deployment commands in the Production Deployment Guide

🎉 Minimal Configuration for Development

Almost no setup needed for local development! The monorepo approach makes it seamless:

  • Auto-installs: bun and Foundry are installed automatically if missing
  • Auto-deploys: Contracts deploy automatically on first run
  • Auto-configures: Client configuration updates automatically

Just clone, install, and develop!

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and test: bun run test
  4. Commit with conventional commits: git commit -m "feat: add amazing feature"
  5. Push and create a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Additional Resources

📖 Documentation

All documentation is in docs/ directory:

Component documentation:

🛠️ Developer Tools

🌐 Community & Support