🍪 Cookie Jar Protocol

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: pnpm, 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 pnpm 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 pnpm + Foundry (via preinstall hook)
pnpm install # Install project dependencies
pnpm dev     # Start development

Option 2: Direct install (pnpm)

git clone https://github.com/greenpill-dev-guild/cookie-jar.git
cd cookie-jar
pnpm install # Auto-installs Foundry + all dependencies
pnpm 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 (pnpm/Foundry), then sets up complete dev environment.

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

🎨 Editor Setup (Recommended)

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

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

See docs/DEVELOPMENT.md for details.

💻 Development

pnpm dev                    # Local development (fastest)
pnpm dev:ethereum           # Fork Ethereum mainnet  
pnpm dev:celo               # Fork Celo network
pnpm dev:base               # Fork Base network
pnpm 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:

🏛️ Community Stipend: Allowlist + ETH + Fixed amounts + Periodic intervals
💰 Grants Program: Allowlist + ERC20 + Variable amounts + Purpose required
🍪 Cookie Monster Benefits: NFT-gated + ETH + Variable amounts + NFT rewards
🎁 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: pnpm test (both contracts + client)

pnpm test:contracts     # Smart contract tests
pnpm test:client        # Frontend tests  
pnpm deploy:local       # Manual deployment
pnpm 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

Account	Address	Private Key	Balance
#0 (Deployer)	`0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`	`0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`	1000 ETH
#1 (Cookie Monster)	`0x70997970C51812dc3A010C7d01b50e0d17dc79C8`	`0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d`	1000 ETH
#2 (Cookie Fan)	`0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC`	`0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a`	1000 ETH
#3 (Test User)	`0x90F79bf6EB2c4f870365E785982E1f101E93b906`	`0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6`	1000 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 pnpm:

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

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

# Deployment
pnpm deploy:local          # Deploy to Anvil
pnpm deploy:ethereum       # Deploy to mainnet
pnpm deploy:celo           # Deploy to celo
pnpm deploy:base           # Deploy to base
pnpm deploy:base-sepolia   # Deploy to mainnet

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

# Utilities
pnpm lint                  # Lint all code
pnpm format                # Format all code
pnpm clean                 # Clean build artifacts
pnpm 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

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

🔧 Environment Setup

Copy and configure environment variables:

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

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:

Automatic Client Updates: The client configuration automatically updates when contracts are deployed
Contract Verification: Contracts are verified on Etherscan/block explorer automatically
V2 Detection: New deployments are automatically detected as V2 contracts
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 pnpm dev:stop

Contract Changes Not Reflecting

Check contracts/anvil.log for blockchain errors
Manually redeploy: pnpm deploy:local
Regenerate types: pnpm generate
Check deployment sync: pnpm sync:check

Client Not Connecting to Local Contracts

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

Environment Issues

Check Node.js version: node --version (should be ≥18.0.0)
Check pnpm version: pnpm --version (should be ≥8.0.0)
Check Foundry installation: forge --version
Reinstall dependencies: rm -rf node_modules */node_modules && pnpm install

Enhanced Features Dependencies

For full functionality of performance monitoring and advanced UX features:

# Install optional enhancement dependencies
pnpm add web-vitals lodash date-fns
pnpm 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 [email protected]:
git config --global url."https://".insteadOf git://

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

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

# 1. Generate SSH key (if you don't have one)
ssh-keygen -t ed25519 -C "[email protected]"

# 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 [email protected]
# Should see: "Hi username! You've successfully authenticated..."

# 5. Clean and reinstall
cd cookie-jar
rm -rf lib contracts/lib
pnpm 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

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
Import test account using private key from table above
Ensure you're on the correct network in your wallet
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)

Install Prerequisites: Node.js (18+), Git

Clone & Setup:

git clone https://github.com/greenpill-dev-guild/cookie-jar.git
cd cookie-jar

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

# If you have pnpm:
pnpm install

# Start development:
pnpm dev

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

For Production Deployment

Environment Setup: Copy .example.env to .env and configure
Secure Wallet: Set up Foundry keystore with cast wallet import deployer --interactive
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: pnpm 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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test: pnpm test
Commit with conventional commits: git commit -m "feat: add amazing feature"
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:

ACCESS_CONTROL.md - 6 access control methods (Allowlist, NFT, POAP, Unlock, Hypercerts, Hats)
DEVELOPMENT.md - Development workflow, commands, and best practices
DEPLOYMENT.md - Production deployment guide with Foundry
TESTING.md - Testing strategies (unit, integration, E2E)
ARCHITECTURE.md - System design and technical architecture
CONTRACTS.md - Smart contract architecture details
FRONTEND.md - Next.js frontend architecture
INTEGRATIONS.md - Protocol integrations (Superfluid, Uniswap, etc.)
NFT_INTEGRATION.md - Comprehensive NFT functionality guide
AI_AGENTS.md - AI agent configuration for Cursor
RELEASES.md - Release history and changelog
MIGRATIONS.md - Migration guides between versions

Component documentation:

contracts/README.md - Smart contract details
client/README.md - Frontend architecture
e2e/README.md - E2E testing setup
.example.env - Environment configuration template

🛠️ Developer Tools

Foundry Documentation - Smart contract development framework
Next.js Documentation - React framework and App Router
RainbowKit Documentation - Wallet connection components

🌐 Community & Support

Discord: Greenpill Dev Guild
Twitter: @greenpilldevs
GitHub Issues: For bug reports and feature requests

Name		Name	Last commit message	Last commit date
Latest commit History 421 Commits
.cursor		.cursor
.github		.github
client		client
contracts		contracts
e2e		e2e
lib		lib
scripts		scripts
.biomeignore		.biomeignore
.cursorignore		.cursorignore
.editorconfig		.editorconfig
.gitignore		.gitignore
.gitmodules		.gitmodules
.oxlintrc.json		.oxlintrc.json
AGENTS.md		AGENTS.md
README.md		README.md
VERCEL_BUILD_FIX.md		VERCEL_BUILD_FIX.md
biome.json		biome.json
example.env		example.env
foundry.toml		foundry.toml
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Uh oh!

greenpill-dev-guild/cookie-jar

Folders and files

Latest commit

History

Repository files navigation

🍪 Cookie Jar Protocol

📋 Prerequisites

🚀 Quick Start

Option 1: Auto-install (npm)

Option 2: Direct install (pnpm)

🎨 Editor Setup (Recommended)

💻 Development

🔧 Configuration

🔐 Production Wallet (Foundry Keystore)

🎭 Pre-Seeded Demo Jars

📦 Project Structure

✨ Core Features

📋 Development Workflow

🔧 Network Configuration

🔑 Pre-funded Test Accounts

🛠️ Available Commands

🚀 Production Deployment Guide

📋 Prerequisites

🔧 Environment Setup

🔐 Secure Deployment Wallet

🌐 Deploy to Any Chain

✅ Post-Deployment

🔍 Deployment Verification

🐛 Troubleshooting Deployments

📁 Generated Files

🔍 Troubleshooting

Common Issues

Port Conflicts

Contract Changes Not Reflecting

Client Not Connecting to Local Contracts

Environment Issues

Enhanced Features Dependencies

Submodule/Foundry Setup Issues

Wallet Connection Issues

Performance Issues

📊 Logs & Monitoring

🔧 Latest Enhancements

🎯 Getting Started Guide

For Local Development (Fastest Path)

For Production Deployment

🎉 Minimal Configuration for Development

🤝 Contributing

📄 License

📚 Additional Resources

📖 Documentation

🛠️ Developer Tools

🌐 Community & Support

About

Topics

Resources

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Languages