Wrapped cCOP (wcCOP) - Cross-Chain Bridge

A decentralized and secure system for wrapping cCOP tokens from the Celo network to Base and Arbitrum, using Hyperlane for cross-chain messaging, Foundry for smart contract development, and a Next.js frontend for seamless user interaction.

Mission

To empower users with a secure, transparent, and easy-to-use platform for cross-chain cCOP token transfers, promoting interoperability and accessibility in the blockchain ecosystem.

Problem

Transferring tokens between different blockchains is often a complex and risky process that requires users to trust centralized bridges. Existing solutions may lack transparency, security, or ease of use, making cross-chain interoperability a significant challenge.

Solution

Our dApp provides a secure, decentralized, and intuitive way to bridge cCOP tokens between Celo, Base, and Arbitrum using Hyperlane's trust-minimized cross-chain infrastructure. The smart contracts, developed with Foundry, ensure that token transfers are secure and verifiable. The frontend offers a seamless user experience for connecting wallets, managing tokens, and viewing transaction history, all without relying on centralized custodians.

Key Features

Cross-Chain Infrastructure

• Hyperlane Integration: Leverages Hyperlane's permissionless interoperability protocol
• Multi-Chain Support: Celo (source), Base, and Arbitrum (destinations)
• Trust-Minimized: No centralized custodians or trusted relayers required

Smart Contract Features

• Lock & Mint: Lock cCOP on Celo, mint wcCOP on destination chains
• Burn & Unlock: Burn wcCOP to unlock original cCOP tokens
• Treasury Management: Secure fund management with admin controls
• Gas Optimization: Efficient cross-chain message encoding

Frontend Features

• Multi-Wallet Support: Connect with various wallets via AppKit/WalletConnect
• Real-Time Updates: Live transaction status and balance tracking
• Responsive Design: Modern UI compatible across devices
• Network Switching: Seamless switching between supported networks
• Libraries:
  • OpenZeppelin Contracts (ERC20, security)
  • Hyperlane Core (cross-chain messaging)
  • Forge-Std (testing utilities)
• Supported Networks:
  • Celo (Mainnet: 42220, Alfajores Testnet: 44787)
  • Base (Mainnet: 8453, Sepolia Testnet: 84532)
  • Arbitrum (Mainnet: 42161, Sepolia Testnet: 421614)
• Key Contracts:
  • Treasury.sol: Manages cCOP locking/unlocking and cross-chain message initiation on Celo
  • WrappedCCOP.sol: ERC20 wrapper contract handling wcCOP minting/burning on destination chains
  • CCOPMock.sol: Test ERC20 token simulating cCOP for development/testing

dApp (Frontend)

• Framework: Next.js 15.3.0 (React 19.0.0)
• Language: TypeScript
• UI Components: Custom React components with CSS modules
• Wallet Integration:
  • @reown/appkit v1.7.10 (based on Wagmi and WalletConnect)
  • Multi-chain wallet connection and network switching
• Blockchain Interaction:
  • wagmi v2.12.31 (React hooks for Ethereum)
  • viem v2.21.44 (TypeScript Ethereum library)
  • @tanstack/react-query v5.59.20 (data fetching and caching)
• Additional Features:
  • react-hot-toast for user notifications
  • react-spinner-toolkit for loading states
  • @divvi/referral-sdk for referral system integration

Deployed Contracts

Mainnet Addresses

• Celo Mainnet (42220)

  • cCOP Token: 0x8A567e2aE79CA692Bd748aB832081C45de4041eA
  • Treasury: 0x5Cc112D9634a2D0cB3A0BA8dDC5dC05a010A3D22

• Base Mainnet (8453)

  • wcCOP Token: 0x5Cc112D9634a2D0cB3A0BA8dDC5dC05a010A3D22

• Arbitrum Mainnet (42161)

  • wcCOP Token: 0x5Cc112D9634a2D0cB3A0BA8dDC5dC05a010A3D22

Testnet Addresses

• Celo Alfajores (44787)

  • cCOP Mock: 0xeF760Ba3281205ec8baB0E63Be0c74a734D11825
  • Treasury: 0xAF4387cC9105C9B716B9B84F673996dCa7ac5150

• Base Sepolia (84532)

  • wcCOP Token: 0x7B9AeD47626Fb43a4EFbFa11c21143158F5C3094

• Arbitrum Sepolia (421614)

  • wcCOP Token: To be deployed

Project Structure

/
├── contracts/          # Smart contracts and Foundry workspace
│   ├── src/           # Contract source code
│   │   ├── Treasury.sol       # Main treasury contract (Celo)
│   │   ├── WrappedCCOP.sol   # Wrapped token contract (Base/Arbitrum)
│   │   └── CCOPMock.sol      # Mock cCOP for testing
│   ├── script/        # Deployment and interaction scripts
│   │   ├── Treasury.s.sol         # Treasury deployment script
│   │   ├── WrappedCCOP_BASE.s.sol # Base deployment script  
│   │   ├── WrappedCCOP_ARB.s.sol  # Arbitrum deployment script
│   │   └── CCOPMock.s.sol         # Mock token deployment
│   ├── test/          # Comprehensive test suite
│   │   ├── unit/      # Unit tests (correct/revert scenarios)
│   │   └── fuzz/      # Fuzz testing for property validation
│   ├── lib/           # External dependencies (OpenZeppelin, Hyperlane)
│   ├── foundry.toml   # Foundry configuration
│   ├── makefile       # Deployment automation scripts
│   └── package.json   # Node.js dependencies (Hyperlane)
│
├── dapp/              # Next.js web application
│   ├── src/
│   │   ├── app/       # Next.js app router pages
│   │   ├── components/ # React UI components
│   │   │   ├── ConnectButton.tsx      # Wallet connection
│   │   │   ├── WrapperComponent.tsx   # Token wrapping interface
│   │   │   ├── UnwrapperComponent.tsx # Token unwrapping interface
│   │   │   └── TokenMenu.tsx          # Token selection menu
│   │   ├── config/    # AppKit and network configuration
│   │   ├── constants/ # Contract addresses and chain IDs
│   │   │   ├── address.tsx   # Deployed contract addresses
│   │   │   ├── chainID.tsx   # Supported chain configurations
│   │   │   └── abis/         # Contract ABI definitions
│   │   ├── context/   # React context providers
│   │   ├── hooks/     # Custom React hooks
│   │   └── utils/     # Utility functions
│   ├── public/        # Static assets (logos, icons)
│   ├── package.json   # Frontend dependencies
│   └── next.config.ts # Next.js configuration
│
├── docs/              # Documentation
│   ├── contracts.md   # Smart contracts documentation
│   ├── dapp.md        # Frontend/dApp documentation
│   ├── farcaster.md   # Farcaster miniapp integration guide
│   └── divvi-integration.md # Divvi referral system integration
│
└── README.md          # This file

Local Development

Follow these steps to set up the development environment on your local machine.

Prerequisites

• Foundry - Ethereum development toolkit
• Node.js (version 18 or higher)
• pnpm (recommended package manager)

1. Setting up the Contracts

1. Navigate to the contracts directory:

   cd contracts

2. Install Solidity dependencies:

   forge install

3. Install Node.js dependencies (for Hyperlane):

   npm install

4. Create environment file:

   cp .env.example .env
   # Edit .env with your private keys and RPC URLs

5. Compile the contracts:

   forge build

6. Run the test suite:

   forge test
   
   # Run specific test types
   make unitTest contract=Treasury type=correct
   make fuzzTest contract=WrappedCCOP

2. Setting up the dApp

1. Navigate to the dApp directory:

   cd dapp

2. Install frontend dependencies:

   pnpm install

3. Start the development server:

   pnpm dev

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

Deployment

Environment Setup

Create a .env file in the contracts directory with:

# Private Keys (use test keys for testnet)
PRIVATE_KEY=your_private_key_here

# RPC URLs
RPC_URL_CELO_MAINNET=https://forno.celo.org
RPC_URL_CELO_ALFAJORES=https://alfajores-forno.celo-testnet.org
RPC_URL_BASE_MAINNET=https://mainnet.base.org
RPC_URL_BASE_SEPOLIA=https://sepolia.base.org
RPC_URL_ARB_MAINNET=https://arb1.arbitrum.io/rpc
RPC_URL_ARB_TESTNET=https://sepolia-rollup.arbitrum.io/rpc

# API Keys for verification
ETHERSCAN_API=your_etherscan_api_key

Deployment Commands

Use the provided Makefile for streamlined deployment:

Testnet Deployment

# Deploy mock cCOP token (Celo Alfajores)
make deployCCOPMock

# Deploy Treasury contract (Celo Alfajores) 
make deployTreasury_TEST

# Deploy wcCOP on Base Sepolia
make deployWrappedCCOP_BaseTest

# Deploy wcCOP on Arbitrum Sepolia
make deployWrappedCCOP_ArbTest

Mainnet Deployment

# Deploy Treasury (Celo Mainnet)
make deployTreasury

# Deploy wcCOP on Base Mainnet
make deployWrappedCCOP_Base

# Deploy wcCOP on Arbitrum Mainnet  
make deployWrappedCCOP_Arb

Manual Deployment

For custom deployment parameters:

# Example: Deploy to Base Mainnet
forge script script/WrappedCCOP_BASE.s.sol:WrappedCCOP_Base_Script \
    --rpc-url $RPC_URL_BASE_MAINNET \
    --account defaultKey \
    --broadcast \
    --verify \
    --etherscan-api-key $ETHERSCAN_API

How It Works

Cross-Chain Flow

1. Wrapping Process (Celo → Base/Arbitrum):

   • User approves cCOP spending on Treasury contract
   • User calls wrapTo() on Treasury with destination chain and amount
   • Treasury locks cCOP tokens and sends cross-chain message via Hyperlane
   • Destination chain receives message and mints equivalent wcCOP to user

2. Unwrapping Process (Base/Arbitrum → Celo):

   • User calls unwrapTo() on wcCOP contract with Celo address and amount
   • wcCOP contract burns user's tokens and sends cross-chain message
   • Treasury receives message and releases locked cCOP to specified address

Security Features

• Multi-signature Admin: Treasury and wcCOP contracts have admin controls for emergency situations
• Chain Validation: Only authorized chains can send/receive cross-chain messages
• Amount Validation: Prevents zero-amount and overflow attacks
• Hyperlane Security: Leverages Hyperlane's validator network for message verification

Testing

The project includes comprehensive testing:

Contract Tests

# Run all tests
forge test

# Unit tests with specific scenarios
make unitTest contract=Treasury type=correct
make unitTest contract=Treasury type=revert

# Fuzz testing for edge cases
make fuzzTest contract=WrappedCCOP
make fuzzTest contract=Treasury

# Gas analysis
forge snapshot

Frontend Testing

cd dapp
pnpm lint      # ESLint checks
pnpm build     # Production build test

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Run tests: forge test and pnpm lint
4. Commit changes: git commit -m 'Add amazing feature'
5. Push to branch: git push origin feature/amazing-feature
6. Open a Pull Request

Security Considerations

• All contracts are upgradeable through admin functions for emergency situations
• Cross-chain messages are validated through Hyperlane's security model
• Treasury contract implements secure token locking mechanisms
• Regular security audits recommended before mainnet deployment

License

This project is licensed under the MIT License. See the license file for more details.

Additional Documentation

• Smart Contracts - Contract architecture and testing
• Frontend/dApp - Frontend setup and development guide
• Farcaster Miniapp Integration - Setup and deployment guide
• Divvi Referral Integration - Referral tracking implementation

Links

• Hyperlane Documentation
• Foundry Documentation
• Next.js Documentation
• Celo Documentation