LiquiFlow

Cross-chain liquidity rewards protocol powered by Uniswap V4 hooks, Arc Testnet treasury, and Circle CCTP.

Overview

LiquidFlow incentivizes liquidity provision across multiple chains through a unified rewards system. Users provide liquidity on Ethereum Sepolia or Base Sepolia via Uniswap V4 pools, and earn USDC rewards distributed from an Arc Testnet treasury. Rewards can be claimed to any supported chain using Circle's Cross-Chain Transfer Protocol (CCTP).

Demo

Live Application: https://liquiflow.vercel.app

Backend Agent: https://liquiflow-3.onrender.com

Note: The backend runs on Render's free tier, which may experience cold starts (10-15 second delay on first request after inactivity). For production deployments, a paid tier is recommended.

Demo video screenshots

Adding Liquidity and claiming through Bridge Kit

Reward sent to destination chain successfully

Technical Implementation

Smart Contracts

Custom Uniswap V4 hooks track liquidity events across chains:

function afterAddLiquidity(
    address sender,
    PoolKey calldata key,
    IPoolManager.ModifyLiquidityParams calldata params,
    BalanceDelta delta,
    BalanceDelta feesAccrued,
    bytes calldata hookData
) external override returns (bytes4, BalanceDelta) {
    emit LiquidityAdded(
        sender, 
        key.toId(), 
        params.liquidityDelta, 
        block.timestamp, 
        block.chainid
    );
    return (this.afterAddLiquidity.selector, delta);
}

Backend Agent

Node.js service listens to hook events and calculates time-weighted rewards:

// Time-weighted reward calculation
liquidityTime = liquidity × timeHeld
userReward = (userLiquidityTime / totalLiquidityTime) × treasuryBalance

Cross-Chain Claims

Circle's Bridge Kit handles USDC transfers from Arc treasury to destination chains:

const result = await kit.bridge({
  from: { adapter, chain: 'Arc_Testnet' },
  to: { adapter, chain: 'Ethereum_Sepolia', recipientAddress: userAddress },
  amount: claimAmount
});

Technology Stack

Smart Contracts: Solidity, Foundry, Uniswap V4
Treasury Chain: Arc Testnet
Cross-Chain Bridge: Circle CCTP + Bridge Kit
Backend: Node.js, Express, ethers.js
Frontend: Next.js 14, TypeScript, Tailwind CSS
Deployment: Vercel (frontend), Render (backend)

Installation

Prerequisites

• Node.js 18+
• Foundry
• MetaMask wallet with testnet ETH

Setup

# Clone repository
git clone https://github.com/yourusername/liquiflow.git
cd liquiflow

# Install dependencies
cd frontend && npm install
cd ../agent && npm install
cd ../hook && forge install

Environment Variables

Backend (.env)

ETHEREUM_RPC=your_ethereum_sepolia_rpc
BASE_RPC=your_base_sepolia_rpc
ARC_RPC=your_arc_testnet_rpc

HOOK_ETHEREUM=0xABa7EC5298eb6D179926B5bf605FEC3f2e1Cc500
HOOK_BASE=0x4d85A01C422Db1362FEcF9DF112dE42ea5a14500

TREASURY_PRIVATE_KEY=your_treasury_private_key
USDC_ARC=0x3600000000000000000000000000000000000000

PORT=3000

Smart Contracts (.env)

PRIVATE_KEY=your_deployer_private_key
ETHEREUM_RPC=your_ethereum_sepolia_rpc
BASE_RPC=your_base_sepolia_rpc

Running Locally

Backend Agent:

cd agent
npm start

Frontend:

cd frontend
npm run dev

Deployment Addresses

Ethereum Sepolia

• Hook: 0xABa7EC5298eb6D179926B5bf605FEC3f2e1Cc500
• Pool ID: 0xd0efb6e7b0c5cf16a2c4428ede00ba10454dcb62ed15888b225d0394355fa832
• USDC: 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
• WETH: 0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14

Base Sepolia

• Hook: 0x4d85A01C422Db1362FEcF9DF112dE42ea5a14500
• Pool ID: 0x2dd0e0ad16888ae5666b27ef91dabf4aebad0c3cff2910a9b8ed9af2e098172d
• USDC: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
• WETH: 0x4200000000000000000000000000000000000006

Arc Testnet (Treasury)

• USDC: 0x3600000000000000000000000000000000000000
• CCTP Domain: 26
• Treasury Address: 0xfE6887759cF0cC3B447CD20F510E6b03448EDD93

Uniswap V4 Core Contracts

Ethereum Sepolia:

• PoolManager: 0xE03A1074c86CFeDd5C142C4F04F1a1536e203543
• PositionManager: 0x429ba70129df741B2Ca2a85BC3A2a3328e5c09b4

Base Sepolia:

• PoolManager: 0x05E73354cFDd6745C338b50BcFDfA3Aa6fA03408
• PositionManager: 0x4B2C77d209D3405F41a037Ec6c77F7F5b8e2ca80

Usage

Adding Liquidity

1. Connect MetaMask to Ethereum Sepolia or Base Sepolia
2. Navigate to the "Add Liquidity" page
3. Enter USDC and WETH amounts (e.g., 0.1 USDC + 0.001 WETH)
4. Approve tokens via Permit2
5. Submit transaction to add liquidity
6. Hook emits event, backend agent tracks position

Claiming Rewards

1. Navigate to "Claim Rewards" page
2. View pending USDC rewards based on time-weighted liquidity
3. Select destination chain (Ethereum Sepolia or Base Sepolia)
4. Enter claim amount
5. Confirm transaction
6. Circle CCTP bridges USDC from Arc treasury (10-15 minutes)

Testing

# Test smart contracts
cd hook
forge test -vv

# Deploy to testnet
forge script script/01_InitializePool.s.sol --rpc-url $ETHEREUM_RPC --broadcast
forge script script/02_AddLiquidity.s.sol --rpc-url $ETHEREUM_RPC --broadcast

Key Features

Cross-Chain Compatibility: Unified rewards across Ethereum and Base
Time-Weighted Distribution: Fair reward allocation based on liquidity amount and duration
Arc Treasury Hub: Cost-efficient settlement layer for reward distribution
Native USDC Bridging: Circle CCTP enables seamless cross-chain claims
Event-Driven Architecture: Real-time position tracking via Uniswap V4 hooks

Project Structure

liquiflow/
├── frontend/          # Next.js application
├── agent/            # Node.js backend service
├── hook/             # Uniswap V4 hook contracts
└── README.md

License

MIT License