Enterprise-grade decentralized lending protocol built on MultiversX blockchain. Features NFT-based position management, multi-source oracle protection, sophisticated liquidation mechanisms, and institutional-level security architecture.

Decentralized Money Markets: The protocol creates isolated lending pools for digital assets where users can supply assets to earn yield or borrow against collateral. Each asset has its own liquidity pool with dynamic interest rates based on supply and demand.

Why: Traditional DeFi lending suffers from oracle manipulation vulnerabilities, liquidation cascades, and poor capital efficiency. Our protocol solves these through:

• Multi-source oracle validation with TWAP protection (±2% tolerance primary, ±5% secondary)
• NFT-based position isolation preventing cross-contamination between strategies
• Immediate bad debt socialization eliminating bank run scenarios
• Sophisticated liquidation bonuses targeting optimal health factors (1.01-1.02)

How: Users interact with a Controller contract that manages positions as NFTs, while individual Liquidity Layer contracts handle the core financial mechanics. Price feeds come through a multi-source aggregator with built-in manipulation resistance.

• Deposit assets into lending pools to earn compound interest
• Interest accrues through scaled token appreciation (no need to claim)
• Multiple supply positions per NFT with automatic yield optimization
• Revenue from borrower interest payments and protocol fees

• Take loans against supplied collateral with dynamic interest rates
• Support for over-collateralized positions with configurable LTV ratios
• Multiple borrow positions per NFT for portfolio diversification
• Automatic interest compounding using Taylor series calculations

• Uncollateralized loans repaid within the same transaction
• 0.50% fee structure for arbitrage and liquidation strategies
• Reentrancy protection through state management and validation
• Cross-shard execution support for complex DeFi strategies

• NFT-Based Positions: Each position is an NFT enabling isolated risk management
• E-Mode Categories: Higher efficiency for correlated assets (up to 92.5% LTV)
• Isolated Markets: Single-collateral positions for risk containment
• Position Limits: Maximum 10 supply + 10 borrow positions per NFT (gas optimization)

• Health factor-based liquidations when collateral value falls below debt
• Dynamic liquidation bonuses (1.5%-15%) targeting health factors of 1.01-1.02
• Bad debt cleanup for positions under $5 USD value
• Immediate loss socialization across all suppliers to prevent bank runs

                    ┌─────────────────────────────────────┐
                    │           Controller                │
                    │     (Main Protocol Logic)          │
                    │   • Position Management (NFTs)     │
                    │   • Risk Calculations              │
                    │   • User Interface                 │
                    └──────────────┬──────────────────────┘
                                   │
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
            ▼                      ▼                      ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Liquidity Layer │    │ Price Aggregator│    │   Position NFT  │
│ (EGLD Pool)     │    │  (Oracle Hub)   │    │   Collection    │
│ • Supply/Borrow │    │ • Multi-source  │    │ • Account Mgmt  │
│ • Interest Calc │    │ • TWAP Validation│    │ • Risk Isolation│
│ • Flash Loans   │    │ • Price Feeds   │    │ • Bulk Operations│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Other Asset     │    │ External Oracles│    │ Account         │
│ Pools (USDC,    │    │ • DEX Prices    │    │ Attributes      │
│ USDT, etc.)     │    │ • Fed Prices    │    │ • E-Mode        │
└─────────────────┘    │ • LP Tokens     │    │ • Isolation     │
                       └─────────────────┘    └─────────────────┘

Triple-Precision System:

• RAY (1e27): Interest indexes, internal calculations, scaled amounts
• WAD (1e18): Asset amounts, price calculations, user-facing values
• BPS (1e4): Percentages, fees, risk parameters

Interest Rate Model (3-tier piecewise linear):

if utilization < mid_utilization:
    rate = base_rate + (utilization * slope1 / mid_utilization)
else if utilization < optimal_utilization:  
    rate = base_rate + slope1 + ((utilization - mid_utilization) * slope2 / ...)
else:
    rate = base_rate + slope1 + slope2 + ((utilization - optimal_utilization) * slope3 / ...)

Compound Interest (Taylor Series, 5-term precision):

compound_factor = 1 + x + x²/2! + x³/3! + x⁴/4! + x⁵/5!
where x = interest_rate * time_delta_ms

Health Factor:

health_factor = Σ(collateral_value_i * ltv_i) / Σ(debt_value_j)
// Liquidatable when health_factor < 1.0

Primary Validation (±2% Tolerance):

• Uses TWAP price from Safe Price View for stability
• Validates against Aggregator price for manipulation detection
• Falls back to averaged price if deviation is within ±5%

Secondary Protection:

• 15-minute TWAP freshness requirement prevents stale price attacks
• Configurable tolerance bounds (0.5%-50% primary, 1.5%-100% secondary)
• LP token pricing using Arda formula with reserve validation

Code Evidence:

// Lines 800-831 in controller/src/oracle/mod.rs
if self.is_within_anchor(&aggregator_price, &safe_price, 
    &tolerances.first_upper_ratio_bps, &tolerances.first_lower_ratio_bps) {
    safe_price // Use TWAP price (±2% tolerance)
} else if self.is_within_anchor(/* ±5% tolerance */) {
    (aggregator_price + safe_price) / 2 // Average both sources
} else {
    require!(cache.allow_unsafe_price, ERROR_UN_SAFE_PRICE_NOT_ALLOWED);
    safe_price // Block dangerous operations during high deviation
}

Flash Loan State Guards:

• Global flash loan flag prevents concurrent execution
• All user functions check !flash_loan_ongoing before proceeding
• Cache-based state management with atomic commits

Controller-Only Functions:

• Liquidity layer functions restricted to only_owner (controller)
• Administrative functions require owner permissions
• Position limits enforced at protocol level

Code Evidence:

// Lines 277-279 in controller/src/validation.rs  
fn reentrancy_guard(&self, flash_loan_ongoing: bool) {
    require!(!flash_loan_ongoing, ERROR_FLASH_LOAN_ALREADY_ONGOING);
}

Health Factor Targeting:

• Dynamic liquidation bonuses target health factors of 1.01-1.02
• Linear scaling from 1.5% to 15% based on position health
• Bad debt cleanup for positions under $5 USD to prevent dust attacks

Bad Debt Socialization:

• Immediate supply index reduction distributes losses proportionally
• Prevents bank run scenarios where informed users exit early
• Minimum index floor prevents total pool collapse

Position Limits (Gas Safety):

• Maximum 10 supply + 10 borrow positions per NFT
• Prevents liquidation DoS through gas exhaustion
• Governance-adjustable based on network conditions

Triple-Precision System:

• RAY (27 decimals) for internal calculations prevents rounding errors
• Half-up rounding ensures consistent behavior
• Overflow protection through BigUint arithmetic

Interest Rate Security:

• Taylor series compound interest (5-term precision) prevents manipulation
• Per-millisecond rate conversion eliminates timing attacks
• Rate caps prevent infinite interest rate scenarios

E-Mode Categories:

• Correlated asset groupings with higher efficiency (up to 92.5% LTV)
• Asset correlation assumptions built into risk parameters
• Category-specific liquidation thresholds and bonuses

Market Isolation:

• Standard Markets: Cross-collateral borrowing with standard parameters
• Isolated Markets: Single collateral type per position
• Siloed Markets: Restricted borrowing to specific asset types

NFT-Based Position Management:

• Each position is an NFT enabling risk isolation between strategies
• Account attributes track E-Mode, isolation status, and position type
• Bulk operations with validation across multiple positions

• Rust 1.75+ with MultiversX SC framework
• MultiversX CLI (mxpy) for deployment
• jq for JSON configuration processing

# Build all contracts
make build

# Run comprehensive test suite  
cargo test

# Run specific test categories
cargo test liquidations
cargo test interest_rate_investigation
cargo test rounding_attack_test

# Make deployment scripts executable
chmod +x configs/script.sh

# Deploy to devnet
make devnet deployController       # Deploy main controller
make devnet deployPriceAggregator # Deploy oracle aggregator
make devnet createMarket EGLD     # Create EGLD lending market

# Deploy to mainnet
make mainnet deployController
make mainnet createMarket EGLD

# Supply EGLD to earn yield (creates position NFT)
make devnet supply EGLD 1.0

# Supply with E-Mode for higher efficiency  
mxpy contract call [controller_address] \
  --function="supply" \
  --arguments 0 1 \  # optional_account_nonce, e_mode_category
  --value=1000000000000000000 \  # 1 EGLD
  --gas-limit=10000000

# Borrow USDC against EGLD collateral
mxpy contract call [controller_address] \
  --function="borrow" \
  --arguments [encoded_borrowed_tokens] \
  --gas-limit=15000000

# Execute flash loan for arbitrage/liquidation
mxpy contract call [controller_address] \
  --function="flashLoan" \
  --arguments [target_contract] [endpoint] [loan_amounts] [params] \
  --gas-limit=20000000

# Liquidate unhealthy position
make devnet liquidate [account_nonce] 

# Check liquidation eligibility
make devnet calculateHealthFactor [account_nonce]

Each asset market is configured with risk and interest rate parameters:

{
  "EGLD": {
    "ltv": "7500",                      // 75.00% max loan-to-value
    "liquidation_threshold": "8000",    // 80.00% liquidation trigger  
    "liquidation_bonus": "550",         // 5.50% liquidator reward
    "borrow_cap": "20000",             // 20K EGLD max total borrows
    "supply_cap": "20000",             // 20K EGLD max total supply
    "base_rate": "1",                  // 1% base interest rate
    "max_rate": "69",                  // 69% maximum interest rate  
    "slope1": "5",                     // 5% slope until mid utilization
    "slope2": "15",                    // 15% slope until optimal utilization
    "slope3": "50",                    // 50% slope above optimal utilization
    "mid_utilization": "65",           // 65% first kink point
    "optimal_utilization": "90",       // 90% second kink point
    "reserve_factor": "2500",          // 25.00% protocol fee
    "flash_loan_fee": "50"             // 0.50% flash loan fee
  }
}

Efficiency mode for correlated assets with higher LTV ratios:

{
  "1": {
    "name": "EGLD Derivatives",
    "ltv": "9250",                     // 92.50% higher efficiency
    "liquidation_threshold": "9550",   // 95.50% tighter liquidation
    "liquidation_bonus": "150",        // 1.50% reduced bonus
    "assets": {
      "EGLD": {
        "can_be_collateral": "0x01",   // Can be used as collateral
        "can_be_borrowed": "0x01"      // Can be borrowed in E-Mode
      }
    }
  }
}

Gas-optimized position limits to ensure liquidatable positions:

{
  "max_borrow_positions": 10,   // Max debt positions per NFT
  "max_supply_positions": 10    // Max collateral positions per NFT  
}

# Core functionality tests
cargo test tests                        # Basic lending operations
cargo test liquidations                 # Liquidation mechanisms  
cargo test emode                       # E-Mode functionality
cargo test isolated                    # Isolated market behavior

# Security & edge case tests  
cargo test rounding_attack_test        # Precision manipulation protection
cargo test simple_rounding_test        # Mathematical rounding validation
cargo test interest_rate_investigation # Interest calculation accuracy

# Simulation tests
cargo test simulation                  # Complex scenario modeling
cargo test strategy                   # Strategy operation validation

• Mathematical Precision: RAY/WAD/BPS arithmetic, rounding behavior
• Oracle Security: TWAP validation, tolerance bounds, manipulation resistance
• Liquidation Logic: Health factor calculations, bonus scaling, bad debt handling
• Flash Loan Security: Reentrancy protection, fee enforcement, cross-shard validation
• Position Management: NFT-based isolation, E-Mode categories, position limits
• Interest Rates: Taylor series calculations, utilization-based rate models

• controller/tests/liquidations.rs - Liquidation scenarios and edge cases
• controller/tests/rounding_attack_test.rs - Precision manipulation defenses
• controller/tests/interest_rate_investigation.rs - Interest calculation validation
• controller/tests/simulation.rs - End-to-end protocol behavior

• Oracle Manipulation Resistance: Multi-source validation with ±2%/±5% tolerance bounds
• Reentrancy Protection: Flash loan state guards across all user functions
• Mathematical Precision: 27-decimal RAY precision with half-up rounding
• Liquidation Security: Dynamic bonuses targeting 1.01-1.02 health factors
• Bad Debt Mitigation: Immediate socialization preventing bank run scenarios
• Position Isolation: NFT-based risk separation with configurable limits

• Oracle Dependency: External price feed reliability during market stress
• Gas Limit Constraints: Position limits ensure liquidatable positions
• E-Mode Correlations: Asset correlation assumptions require monitoring
• Flash Loan Complexity: Multi-contract interactions increase attack surface

• Price feed freshness and deviation tracking
• Liquidation efficiency and gas usage monitoring
• Bad debt accumulation and socialization effectiveness
• Interest rate model performance under various utilization levels

git clone https://github.com/multiversx/mx-lending-sc
cd mx-lending-sc
make build
cargo test

• Security First: All changes require security analysis
• Mathematical Precision: Maintain RAY/WAD/BPS precision standards
• Gas Efficiency: Consider liquidation gas costs in design decisions
• Test Coverage: Comprehensive tests for all functionality

1. Security analysis for proposed changes
2. Implementation with comprehensive tests
3. Mathematical precision verification
4. Gas usage analysis and optimization
5. Code review and audit consideration

License: MIT License - see LICENSE

Security Disclaimer: This is experimental financial software. Users should:

• Understand smart contract risks and potential for loss of funds
• Start with small amounts and test thoroughly
• Monitor positions actively, especially during market volatility
• Understand liquidation mechanics and health factor requirements

Audit Status: Internal security review completed. External audit recommended before mainnet deployment with significant TVL.

# Install dependencies
sudo apt install jq          # JSON processor
pip install multiversx-sdk   # MultiversX CLI tools
chmod +x configs/script.sh   # Make deployment scripts executable

# Core deployment sequence
make devnet deployController        # Deploy main controller contract
make devnet deployPriceAggregator  # Deploy oracle aggregator
make devnet createMarket EGLD      # Create EGLD lending market

# Market management
make devnet createMarket USDC      # Add USDC market
make devnet editAssetConfig EGLD   # Update EGLD risk parameters
make devnet listMarkets            # View all deployed markets

# E-Mode configuration
make devnet addEModeCategory 1     # Add correlated asset category
make devnet addAssetToEMode 1 EGLD # Add EGLD to E-Mode category
make devnet listEModeCategories    # View E-Mode configurations

# Oracle management
make devnet createOracle EGLD      # Deploy EGLD price oracle
make devnet editOracleTolerance EGLD  # Update tolerance bounds
make devnet addOracles <oracle_addresses> # Add price feed sources

# Administrative operations
make devnet registerAccountToken   # Register position NFT collection
make devnet claimRevenue          # Claim accumulated protocol fees
make devnet pauseAggregator       # Emergency pause price feeds

{
  "EGLD": {
    "ltv": "7500",                    // 75% loan-to-value ratio
    "liquidation_threshold": "8000",  // 80% liquidation trigger
    "liquidation_bonus": "550",       // 5.5% liquidator reward
    "borrow_cap": "20000",           // 20K EGLD max borrows
    "supply_cap": "20000",           // 20K EGLD max supply
    "base_rate": "1",                // 1% base interest rate
    "reserve_factor": "2500"         // 25% protocol fee
  }
}

{
  "devnet": {
    "1": {
      "name": "EGLD Derivatives",
      "ltv": "9250",                  // 92.5% higher efficiency
      "liquidation_threshold": "9550", // 95.5% liquidation threshold
      "liquidation_bonus": "150"      // 1.5% reduced liquidator bonus
    }
  }
}

• Network endpoints and chain IDs
• Contract deployment addresses
• Oracle configuration
• Account and token details