WRMB Protocol - Complete DeFi Ecosystem

📋 Overview

WRMB Protocol is a comprehensive DeFi ecosystem built on Ethereum, featuring wrapped RMB tokens, savings vaults, bond pools, and automated market operations. The protocol enables users to wrap sRMB tokens into interest-bearing sWRMB, participate in bond subscriptions, and benefit from automated liquidity management.

🏗️ Architecture

Core Components

1. WRMB Token (WRMB.sol)

   • ERC20 token with minting restrictions
   • Only designated minter can mint new tokens
   • Serves as the base currency for the ecosystem

2. WRMB Minter (WRMBMinter.sol)

   • Controls WRMB token minting across different scenarios
   • Supports minting for wrap operations, vault increases, and bond maturity
   • Implements role-based access control

3. Savings Vault (SavingsVault.sol)

   • ERC4626-compliant vault for WRMB tokens
   • Issues sWRMB shares representing vault positions
   • Integrates with AMO for dynamic asset management
   • Supports keeper-triggered NAV increases

4. Wrap Manager (WrapManager.sol)

   • Manages conversion from sRMB to sWRMB
   • Handles fee calculations and oracle price feeds
   • Integrates with savings vault for seamless wrapping

5. Active Liquidity AMO (ActiveLiquidityAMO.sol)

   • Automated Market Operations for arbitrage and rebalancing
   • Manages WRMB debt and liquidity positions
   • Keeper-operated for automated execution

6. WRMB Bond Pool (WRMBBondPool.sol)

   • Bond subscription system with compound interest
   • Users deposit USDT to earn WRMB rewards
   • Configurable bond terms and interest rates

7. Bond Liquidity AMO (BondLiquidityAMO.sol)

   • Single-sided USDT liquidity provider for bond pool
   • Automated rebalancing based on utilization rates
   • Position management and yield optimization

8. Oracle Stub (OracleStub.sol)

   • Mock oracle for testing and development
   • Provides price feeds and TWAP functionality
   • Supports batch price updates

🚀 Quick Start

Prerequisites

• Node.js >= 16.0.0
• npm or yarn
• Hardhat development environment

Installation

# Clone the repository
git clone https://github.com/CINALabs/WRMB-protocol-contracts.git
cd WRMB-protocol-contracts

# Install dependencies
npm install

# Compile contracts
npm run build

Deployment

# Deploy to local network
npm run node
# In another terminal
npm run deploy

# Deploy to specific network
npx hardhat run scripts/deploy.ts --network <network-name>

Testing

# Run all tests
npm test

# Run specific test file
npx hardhat test test/WRMB.test.ts

# Run tests with coverage
npm run coverage

📖 Usage Guide

1. Wrapping sRMB to sWRMB

// Approve sRMB to WrapManager
await srmb.approve(wrapManager.address, amount);

// Preview wrap operation
const [expectedSWRMB, expectedWRMB, fee] = await wrapManager.previewWrap(amount);

// Execute wrap
await wrapManager.wrap(amount);

2. Bond Subscription

// Preview bond subscription
const [wrmbAmount, maturityTime, expectedReward] = await bondPool.previewSubscription(usdtAmount);

// Approve USDT to BondPool
await usdt.approve(bondPool.address, usdtAmount);

// Subscribe to bond
await bondPool.subscribeBond(usdtAmount);

// Mature bond after duration
await bondPool.matureBond(bondId);

3. Savings Vault Operations

// Deposit WRMB to vault
await wrmb.approve(savingsVault.address, amount);
await savingsVault.deposit(amount, recipient);

// Redeem sWRMB for WRMB
await savingsVault.redeem(shares, recipient, owner);

// Check current NAV
const nav = await savingsVault.getNAV_sWRMB();

🧪 Testing

The project includes comprehensive test suites for all contracts:

• Unit Tests: Individual contract functionality
• Integration Tests: Cross-contract interactions
• Scenario Tests: Real-world usage scenarios

Test Coverage

• WRMB Token: Minting, transfers, access control
• Savings Vault: Deposits, withdrawals, NAV calculations
• Wrap Manager: sRMB wrapping, fee calculations
• Bond Pool: Subscriptions, maturity, compound interest
• AMO Contracts: Arbitrage, rebalancing, debt management

📊 Contract Interactions

Flow Diagram: sRMB → sWRMB → WRMB

User → WrapManager → SavingsVault → WRMBMinter → WRMB Token
  ↓        ↓            ↓             ↓           ↓
Approve   GetNAV    MintShares   MintWRMB   Transfer
sRMB      Price     (sWRMB)      Tokens     to Vault

Bond Subscription Flow

User → BondPool → Oracle → WRMBMinter → WRMB Token
  ↓        ↓        ↓         ↓           ↓
USDT    GetPrice  Price    MintRewards  Transfer
Deposit  Feed     Check    (Maturity)   to User

🔧 Configuration

Environment Variables

Create a .env file with the following variables:

# Network Configuration
INFURA_API_KEY=your_infura_key
PRIVATE_KEY=your_private_key

# Contract Addresses (after deployment)
WRMB_ADDRESS=0x...
MINTER_ADDRESS=0x...
VAULT_ADDRESS=0x...

# Oracle Configuration
ORACLE_UPDATE_INTERVAL=3600
PRICE_DEVIATION_THRESHOLD=500

Hardhat Configuration

The project uses Hardhat with TypeScript support:

• Solidity version: 0.8.20
• Optimizer enabled with 200 runs
• TypeChain integration for type-safe contract interactions
• Gas reporting and coverage analysis

🔒 Security Considerations

Access Control

• Owner-only functions: Critical configuration changes
• Role-based minting: Separate minters for different scenarios
• Keeper operations: Automated functions with designated operators
• Emergency controls: Pause functionality and emergency withdrawals

Risk Management

• Slippage protection: Maximum slippage limits for operations
• Debt tracking: Accurate AMO debt accounting
• Cooldown periods: Rate limiting for sensitive operations
• Validation checks: Comprehensive input validation

Audit Recommendations

1. Reentrancy Protection: All external calls use ReentrancyGuard
2. Integer Overflow: SafeMath equivalent checks in Solidity 0.8+
3. Access Control: Comprehensive role-based permissions
4. Oracle Security: Price staleness and manipulation checks
5. Emergency Procedures: Pause and emergency withdrawal mechanisms

📈 Monitoring and Analytics

Key Metrics

• TVL (Total Value Locked): Across all protocol components
• Utilization Rates: Vault and AMO utilization
• Bond Subscriptions: Active bonds and maturity schedule
• NAV Performance: sWRMB net asset value trends
• AMO Performance: Arbitrage profits and rebalancing efficiency

Events for Monitoring

// Core protocol events
event BondSubscribed(address user, uint256 bondId, uint256 amount);
event WrapExecuted(address user, uint256 srmb, uint256 swrmb);
event NAVUpdated(uint256 oldNAV, uint256 newNAV);
event RebalanceExecuted(uint256 amount, string operation);

🛠️ Development Tools

Recommended Tools

• TypeChain: Type-safe contract interactions
• Hardhat: Development environment and testing
• OpenZeppelin: Security-audited contract libraries
• Solhint: Solidity linting and best practices
• Prettier: Code formatting for Solidity

Scripts

# Development
npm run build          # Compile contracts
npm run test           # Run tests
npm run coverage       # Test coverage
npm run lint           # Lint Solidity code

# Deployment
npm run deploy         # Deploy to local network
npm run verify         # Verify contracts on Etherscan

# Utilities
npm run typechain      # Generate TypeScript types
npm run clean          # Clean build artifacts

📚 Additional Resources

Documentation

• ERC4626 Specification
• OpenZeppelin Contracts
• Hardhat Documentation

Community

• GitHub Issues: Bug reports and feature requests
• Discord: Community discussions and support
• Documentation: Comprehensive guides and tutorials

📄 License

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

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Development Guidelines

• Follow Solidity style guide
• Write comprehensive tests
• Document all public functions
• Use meaningful commit messages
• Ensure all tests pass before submitting

---

Note: This is a development version. Do not use in production without proper auditing and testing.