A decentralized Bitcoin-backed yield protocol powered by tokenized Latin American bonds and receivables.
Cambi Protocol enables users to earn 7-25% APY on Bitcoin and stablecoins by minting yield-bearing synthetic assets (cmBTC, cmUSD, cmBRL) backed by real-world assets from Latin American markets. Through the innovative Cross-Collateral Yield Optimization Engine (CCYOE), the protocol redistributes excess yields to maximize returns across all users.
- Overview
- Core Components
- Key Features
- Synthetic Assets
- Prerequisites
- Installation
- Usage
- Contract Architecture
- Contributing
- License
Cambi Protocol represents a paradigm shift in how Bitcoin & Stablecoin holders access yield and how Latin Americans interact with their wealth. By creating the world's first permissionless Bitcoin-backed yield system powered by Latin American real-world assets, we're expanding El Salvador's Volcano Bonds concept into a more accessible and scalable solution.
- CambiFactory: Central registry managing synthetic assets, collateral types, and CCYOE configuration
- CambiPositionManager: Handles time-locked collateralized debt positions (CDPs) with enhanced features
- RebasingSyntheticAsset: Rebasing ERC20 tokens that automatically show growing balances (cmBTC, cmUSD, cmBRL)
- CCYOEVault: Cross-Collateral Yield Optimization Engine managing yield distribution per asset
- CambiLens: Comprehensive view contract providing formatted data for frontend applications
- WrappedRebasingSyntheticAsset: Non-rebasing wrappers for DeFi composability (wcmBTC, wcmUSD, wcmBRL)
- cmBTC: Bitcoin-backed synthetic with 5-8% base yield
- cmUSD: USD-backed synthetic with 14-18% yield from Brazilian receivables
- cmBRL: Brazilian Real synthetic with 20-25% yield from local bonds
- Daily rebasing shows users their balances growing automatically
- Redistributes excess yields from high-performing assets to boost others
- Network effects where success in one asset benefits all users
- Automated rebalancing based on performance thresholds
- Strategic yield allocation to drive protocol growth
- Minimum lock periods: 90 days for cmBTC/cmUSD/cmBRL, 30 days for others
- Early withdrawal penalties: 2-5% depending on asset type
- Extended lock periods for additional yield benefits
- Emergency withdrawal mechanisms for crisis situations
- Direct access to Brazilian receivables yielding 14-18% annually
- Integration with tokenization platforms like Liqi & DUX
- Ladder maturity management for continuous yield realization
- USD-denominated receivables eliminate FX exposure for cmUSD
- Emergency stop functionality for protocol-wide pauses
- Over-collateralization with isolated vault architecture
- Multi-signature controls on RWA purchases
- Circuit breakers for unusual yield patterns
- Wrapped versions (wcmBTC, wcmUSD, wcmBRL) for standard DeFi protocols
- Planned Uniswap V4 liquidation hooks for capital efficiency
- ERC20 compatibility while maintaining rebasing benefits
- Yield farming and lending protocol integration
- Yield: 5-8% base + CCYOE boosts
- Backing: Bitcoin collateral + institutional lending
- Use Case: Bitcoin hodlers wanting yield without selling
- Liquidity: Instant cmUSD minting for operational needs
- Yield: 14-18% from USD-denominated Brazilian receivables
- Backing: Bitcoin/stablecoin collateral + RWA exposure
- Use Case: Dollarization for LatAm users, superior DeFi collateral
- No FX Risk: Receivables denominated in USD or hedge-embedded
- Yield: 20-25% from Brazilian bonds and receivables
- Backing: Bitcoin collateral + local RWA exposure
- Use Case: Spend in BRL while collateral appreciates
- Inflation Hedge: Earn above Brazilian inflation rates
- Foundry - Ethereum development toolkit
- Node.js 16+ for frontend integration
- Understanding of CDP mechanics and rebasing tokens
- Clone the repository:
git clone https://github.com/your-org/cambi-contracts.git
cd cambi-contracts- Install dependencies:
forge install- Set up environment variables:
cp .env.example .env
# Edit .env with your configurationCompile the contracts:
forge buildRun the test suite:
forge testRun tests with gas reporting:
forge test --gas-reportDeploy to a network:
FEE_COLLECTOR_ADDRESS=<address> \
PROTOCOL_TREASURY_ADDRESS=<address> \
forge script script/CambiDeploy.s.sol:CambiDeployScript \
--rpc-url <your_rpc_url> \
--private-key <your_private_key> \
--broadcastTrigger daily rebase for an asset:
cast send <CAMBI_FACTORY> "triggerRebase(address)" <SYNTHETIC_ASSET> \
--rpc-url <rpc> --private-key <key>Rebalance CCYOE:
cast send <CAMBI_FACTORY> "rebalanceCCYOE()" \
--rpc-url <rpc> --private-key <key>Central registry managing all protocol parameters, synthetic assets, and the CCYOE system. Handles asset registration, collateral management, and yield optimization coordination.
Key Functions:
- Register rebasing synthetic assets with RWA backing
- Configure CCYOE parameters and rebalancing
- Manage emergency stops and protocol security
- Handle collateral and asset relationships
Enhanced CDP manager with time-locked staking and advanced liquidation mechanisms.
Key Functions:
- Create time-locked positions with custom lock periods
- Handle early withdrawal with penalties
- Execute liquidations with Uniswap V4 hooks (planned)
- Manage emergency withdrawals during crisis
Rebasing ERC20 implementation that automatically grows user balances through yield accumulation.
Key Functions:
- Daily rebasing based on vault yield rates
- Fractional balance tracking for accurate rebasing
- Yield distribution from CCYOE optimization
- Rebase history tracking for analytics
Individual vault managing yield generation and RWA integration for each synthetic asset.
Key Functions:
- Invest in Brazilian RWA opportunities
- Manage maturity ladder for continuous yield
- Optimize yield distribution strategies
- Handle emergency RWA withdrawals
Comprehensive view contract providing formatted data access for frontend applications.
Key Functions:
- Get enhanced position details with time locks
- Analyze CCYOE performance and optimization
- Track rebasing token metrics and history
- Calculate protocol-wide statistics
- Protocol Fee: 1.5% on withdrawals and position closures
- Performance Fee: 10% on yields above base rates
- Early Withdrawal Penalty: 1-5% based on asset type and lock period
- Emergency Withdrawal Penalty: Additional penalties during emergency mode
- 40% to under-supplied assets (asset shortfalls)
- 30% to strategic growth incentives
- 20% distributed proportionally to all holders
- 10% to protocol treasury for security and development
- cmBTC: Institutional Bitcoin lending (3-5%) + liquidity premium
- cmUSD: USD-denominated Brazilian receivables (14-18%)
- cmBRL: Brazilian fixed income & bonds (20-25%)
- CCYOE Boosts: Additional yield from cross-asset optimization
- 30-60 days: Base yield rates
- 90-180 days: +0.5% yield bonus
- 180-365 days: +1% yield bonus
- 365+ days: +2% yield bonus + governance voting weight
- cmBTC: 5% penalty if withdrawn before 90 days
- cmUSD: 3% penalty if withdrawn before 90 days
- cmBRL: 2% penalty if withdrawn before 90 days
- Emergency Mode: Reduced penalties (50% of normal rates)
- E-commerce receivables: 30-day maturity, 15% APR
- Agricultural exports: 60-day maturity, 18% APR
- Corporate bonds: 90-day maturity, 20% APR
- Infrastructure bonds: 1-year maturity, 25% APR
- Diversified portfolio: 50+ receivables across sectors
- Ladder maturities: Continuous liquidity through staggered maturities
- Credit analysis: Traditional + AI-powered risk assessment
- Insurance buffer: 2% of TVL reserved for defaults
// Get comprehensive protocol data
const protocolInfo = await cambiLens.getProtocolInfo();
// Create time-locked position
const tx = await positionManager.createPosition(
cmUSDAddress,
btcAddress,
collateralAmount,
mintAmount,
lockPeriod
);
// Check rebasing token metrics
const metrics = await cambiLens.getRebasingTokenMetrics(cmBTCAddress);
// Preview CCYOE rebalance
const rebalanceData = await cambiLens.previewCCYOERebalance();// Listen for rebase events
contract.on('Rebase', (epoch, multiplier, newSupply, yieldRate) => {
updateUserBalances();
});
// Monitor CCYOE rebalancing
factory.on('CCYOERebalanced', (totalYield, timestamp) => {
refreshYieldData();
});- Rebasing Mechanics: Token rebasing, yield distribution, balance calculations
- Time Lock System: Lock periods, early withdrawal penalties, emergency modes
- CCYOE Optimization: Yield redistribution, asset optimization, rebalancing
- RWA Integration: Mock provider interactions, yield claiming, emergency withdrawals
- Liquidation System: Under-collateralization detection, liquidation execution
- Emergency Procedures: Protocol pauses, emergency withdrawals, security measures
# Test rebasing functionality
forge test --match-path "test/RebasingTest.sol"
# Test CCYOE system
forge test --match-path "test/CCYOETest.sol"
# Test time locks
forge test --match-path "test/TimeLockTest.sol"
# Integration tests
forge test --match-path "test/IntegrationTest.sol"# Deploy factory with oracle and fee configuration
forge script script/01_DeployCore.s.sol --broadcast
# Deploy position manager
forge script script/02_DeployPositionManager.s.sol --broadcast
# Deploy lens for frontend integration
forge script script/03_DeployLens.s.sol --broadcast# Register synthetic assets
forge script script/04_RegisterAssets.s.sol --broadcast
# Set up collateral types with RWA integration
forge script script/05_SetupCollateral.s.sol --broadcast
# Configure CCYOE parameters
forge script script/06_ConfigureCCYOE.s.sol --broadcast# Deploy mock Brazilian RWA provider for testing
forge script script/07_DeployRWAProviders.s.sol --broadcast
# Connect RWA providers to collateral types
forge script script/08_ConnectRWA.s.sol --broadcast- CCYOE redistribution ratios and thresholds
- Time lock periods and early withdrawal penalties
- Fee structures and performance fee rates
- Emergency stop triggers and conditions
- RWA provider approvals and integrations
- Modular architecture allows individual contract upgrades
- Time-locked governance proposals for parameter changes
- Emergency procedures for critical security updates
- Community governance through $CMB token (future)
- Initial audit by top-tier security firm
- Economic model review by DeFi risk specialists
- RWA integration audit by TradFi experts
- Ongoing bug bounty program
- Over-collateralization requirements (150% minimum)
- Isolated vault architecture prevents contagion
- Circuit breakers for unusual market conditions
- Multi-signature controls on critical functions
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow Solidity best practices and style guide
- Write comprehensive tests for new features
- Update documentation for any interface changes
- Ensure gas optimization for user-facing functions
This project is licensed under the MIT License - see the LICENSE file for details.
Cambi Protocol is experimental software. Users should understand the risks involved in DeFi protocols, RWA integration, and yield-bearing assets. Past performance does not guarantee future results. Please consult with financial advisors before making investment decisions.
Built with ❤️ for the future of global finance
Bridging Bitcoin and Brazilian Real-World Assets