A comprehensive liquidation system for the Cambi Protocol, featuring both off-chain monitoring bots and on-chain Uniswap V4 hooks for capital-efficient liquidations.

The Cambi Protocol enables users to mint yield-bearing synthetic assets (cmBTC, cmUSD, cmBRL) backed by Bitcoin and stablecoin collateral. When positions become under-collateralized (below 130% ratio), they need to be liquidated to maintain protocol stability.

This repository provides two complementary liquidation solutions:

Off-chain monitoring and execution system that:

• Continuously scans for under-collateralized positions
• Calculates liquidation profitability in real-time
• Executes liquidations via direct protocol interaction
• Supports batch processing and automated scheduling
• Deployable on Vercel for serverless operation

On-chain Uniswap V4 hook enabling capital-efficient liquidations:

• Flash liquidations without upfront capital requirements
• Atomic execution: flash loan → liquidate → swap → profit
• Gas-optimized using V4's singleton architecture
• Integrated slippage protection and profit validation

graph TB
    subgraph "Cambi Protocol"
        PM[Position Manager]
        SA[Synthetic Assets<br/>cmBTC/cmUSD/cmBRL]
        LC[Lens Contract]
        CCYOE[Cross-Collateral Yield<br/>Optimization Engine]
    end
    
    subgraph "Liquidation Infrastructure"
        LB[Liquidation Bot<br/>TypeScript/Viem]
        LH[Liquidation Hook<br/>Solidity/Uniswap V4]
        LO[Liquidation Orchestrator<br/>Batch Management]
    end
    
    subgraph "Uniswap V4"
        PM4[Pool Manager]
        HOOKS[Hook System]
        FA[Flash Accounting]
    end
    
    LB --> LC
    LB --> PM
    LH --> PM4
    LH --> HOOKS
    LH --> FA
    LO --> LH
    PM --> SA
    LC --> PM

• Node.js v18+
• Foundry
• Private key with ETH for gas
• Access to Cambi Protocol contracts

git clone https://github.com/cambi-protocol/cambi-liquidatoor.git
cd cambi-liquidatoor

cd liquidation-bot
npm install
cp .env.example .env
# Edit .env with your configuration
npm run build
npm start

cd liquidation-hook
forge install
forge build --via-ir
# Edit deployment script with contract addresses
forge script script/Deploy.s.sol --rpc-url <your_rpc> --broadcast

• 🔍 Automated Scanning: Continuous monitoring via Lens contract
• 💰 Profitability Assessment: Real-time profit/gas calculations
• ⚡ Fast Execution: Optimized transaction handling
• 📊 Comprehensive Logging: Detailed operation tracking
• 🛡️ Error Handling: Robust failure recovery
• 🔄 Batch Processing: Concurrent liquidation execution
• 📱 Vercel Compatible: Serverless deployment ready
• 🌐 REST API: Integration endpoints

• 💎 Capital Efficiency: No upfront token requirements
• ⚛️ Atomic Execution: Single-transaction liquidations
• 🔒 Risk Reduction: Failed liquidations auto-revert
• ⛽ Gas Optimized: V4 singleton pattern benefits
• 🎯 Slippage Protection: Configurable minimum outputs
• 🔧 Flexible Configuration: Multi-pool and fee tier support

• cmBTC: Bitcoin-backed synthetic (5-8% APY)
• cmUSD: USD-backed by LatAm receivables (14-18% APY)
• cmBRL: Brazilian Real backed by local bonds (20-25% APY)

• Liquidation Threshold: 130% collateralization ratio
• Over-collateralization: 150% minimum at position creation
• Liquidation Discount: Variable based on asset type
• Cross-Collateral Benefits: CCYOE yield optimization

# Vercel deployment
npm run deploy

# Traditional server
npm run build
npm start

# Deploy to mainnet/testnet
forge script script/Deploy.s.sol:DeployScript \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify

# Network
RPC_URL=https://base-mainnet.alchemyapi.io/v2/your-key
CHAIN_ID=8453

# Contracts
LENS_CONTRACT_ADDRESS=0x...
POSITION_MANAGER_ADDRESS=0x...
FACTORY_ADDRESS=0x...

# Bot Settings
SCAN_INTERVAL_SECONDS=60
MIN_PROFIT_USD=5
MAX_GAS_PRICE_GWEI=300
BATCH_SIZE=10

# Security
LIQUIDATOR_PRIVATE_KEY=0x...
API_KEY=your-secret-key

• Pool creation with hook integration
• Fee tier and tick spacing configuration
• Liquidation protocol interface implementation
• Orchestrator deployment for batch operations

• Private Key Management: Never commit keys to version control
• Gas Management: Configure appropriate limits and monitoring
• Slippage Protection: Set reasonable minimum output amounts
• Reentrancy Protection: Built-in hook state management
• Emergency Controls: Orchestrator emergency liquidation capabilities

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Liquidation Bot Documentation
• Liquidation Hook Documentation
• Cambi Protocol Whitepaper
• API Reference

• Discord
• Twitter
• Documentation

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

• Uniswap V4 - Hook system and flash accounting
• Foundry - Development framework
• Viem - TypeScript Ethereum library
• MakerDAO - CDP architecture inspiration

Built with ❤️ for the Cambi Protocol ecosystem