TipForge ⚡

Retro-pixel crypto tipping for creators on Farcaster

TipForge is a decentralized tipping platform that allows users to send cryptocurrency tips to their favorite creators using a retro-pixel aesthetic. Built on Base with Farcaster integration.

Features

• 🎮 Retro-Pixel Design - Nostalgic 8-bit aesthetic with modern UX
• ⚡ Instant Tips - Send USDC tips with one click
• 🔗 Farcaster Native - Deep integration with Farcaster frames
• 🛡️ Base Network - Fast and cheap transactions on Base
• 💰 Revenue Splitting - Automatic revenue distribution
• 🔄 Upgradeable - UUPS proxy pattern for future improvements

Quick Start

Prerequisites

• Node.js 18+
• pnpm
• Git

Installation

# Clone the repository
git clone https://github.com/your-username/tipforge.git
cd tipforge

# Install dependencies
pnpm install

# Copy environment files
cp .env.example .env.local
cp packages/contracts/.env.example packages/contracts/.env

# Fill in your environment variables
# See .env.example for required values

Development

# Start development server
pnpm dev

# Open http://localhost:3000

Smart Contract Development

# Navigate to contracts
cd packages/contracts

# Install Foundry dependencies
forge install

# Run tests
forge test

# Deploy to Base Sepolia
pnpm deploy:sepolia

Project Structure

tipforge/
├── apps/
│   └── web/                 # Next.js web application
├── packages/
│   ├── contracts/           # Smart contracts (Foundry)
│   └── ui/                  # Shared UI components
├── docs/                    # Documentation
└── scripts/                 # Build and deployment scripts

Architecture

Smart Contracts

• TipJar.sol - Main tipping contract with UUPS upgradeability
• Revenue Splitting - Automatic distribution to multiple recipients
• Platform Fees - Configurable platform fee system
• EIP-2612 Support - Gasless approvals with permits

Frontend

• Next.js 14 - React framework with App Router
• OnchainKit - Coinbase's Web3 UI components
• Wagmi + Viem - Ethereum interaction library
• Tailwind CSS - Utility-first CSS framework

Farcaster Integration

• Frames API - Interactive tipping frames
• Mini-App - Native Farcaster application
• Dynamic Images - Generated frame images

Demo

Try the live demo:

1. Visit tipforge.xyz/demo
2. Connect your wallet (MetaMask, Coinbase Wallet, WalletConnect)
3. Get test USDC from Base Sepolia faucet
4. Tip a demo creator!

Environment Variables

Web Application (.env.local)

NEXT_PUBLIC_ONCHAINKIT_API_KEY=your_onchainkit_api_key
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id
NEXT_PUBLIC_ALCHEMY_API_KEY=your_alchemy_api_key

Smart Contracts (.env)

PRIVATE_KEY=your_private_key_without_0x
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
BASESCAN_API_KEY=your_basescan_api_key

Scripts

# Development
pnpm dev              # Start development server
pnpm build            # Build all packages
pnpm lint             # Run linting
pnpm type-check       # TypeScript type checking

# Smart Contracts
pnpm contracts:test           # Run contract tests
pnpm contracts:deploy:sepolia # Deploy to Base Sepolia
pnpm contracts:verify:sepolia # Verify contracts
pnpm contracts:coverage       # Test coverage

# Utilities
pnpm clean            # Clean build artifacts
pnpm format           # Format code

Testing

Smart Contract Tests

cd packages/contracts

# Run all tests
forge test

# Run with gas reporting
forge test --gas-report

# Run coverage
forge coverage

# Run specific test
forge test --match-test testTip

Web Application Tests

# Linting
pnpm lint

# Type checking
pnpm type-check

# Unit tests (when implemented)
pnpm test

Deployment

Base Sepolia (Testnet)

# Deploy contracts
pnpm contracts:deploy:sepolia

# Verify contracts
pnpm contracts:verify:sepolia

# Deploy web app
pnpm build
# Deploy to your preferred hosting platform

Base Mainnet (Production)

# Deploy contracts
pnpm contracts:deploy:mainnet

# Verify contracts
pnpm contracts:verify:mainnet

Gas Costs

Operation	Gas Used	Cost (ETH)	Cost (USD)
First tip	~65,000	0.0013	~$3.25
Subsequent tips	~45,000	0.0009	~$2.25
Set revenue split	~55,000	0.0011	~$2.75

Estimates based on 20 gwei gas price and $2500 ETH

Security

• ✅ Reentrancy protection
• ✅ Access control
• ✅ Input validation
• ✅ Pause mechanism
• ✅ Upgrade safety
• 🔄 Security audit (planned)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE for details.

Links

• Documentation
• Base Documentation
• OnchainKit
• Farcaster
• Foundry

Support

For questions and support:

• Create an issue
• Join our Discord
• Follow us on Twitter

---

Built with ⚡ on Base • Retro-Pixel Vibes • Open Source