MultiversX Lending Protocol

https://github.com/xoxno/rs-lending
Admin
An enterprise-grade decentralized lending protocol built on the MultiversX blockchain, featuring...
Tokens:22,690
Snippets:104
Trust Score:7.7
License:AGPL-3.0
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Project Dependencies

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Installs necessary tools and libraries for the rs-lending project. Includes a JSON processor (jq), MultiversX SDK for CLI operations, and makes shell scripts executable.

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

--------------------------------

### Rust Project Setup and Build Commands

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Provides commands to clone the Rust lending smart contract repository, navigate to the directory, build the project, and run tests. This is the initial setup process for contributing to or running the project.

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

--------------------------------

### Rust Lending Configuration Examples

Source: https://github.com/xoxno/rs-lending/blob/master/controller/ORACLE.md

Provides example configuration settings for different types of tokens, including stablecoins, standard volatile tokens, and high-volatility experimental tokens. These configurations define tolerance levels and maximum staleness for price feeds.

```rust
// Conservative stablecoin settings
first_tolerance: 100 BPS (1.0%)
last_tolerance: 300 BPS (3.0%)
max_staleness: 300 seconds (5 minutes)

// Standard volatile token settings  
first_tolerance: 500 BPS (5.0%)
last_tolerance: 1000 BPS (10.0%)
max_staleness: 600 seconds (10 minutes)

// High-volatility experimental tokens
first_tolerance: 1000 BPS (10.0%)
last_tolerance: 2000 BPS (20.0%)
max_staleness: 900 seconds (15 minutes)
```

--------------------------------

### CLI: Example Liquidation Command

Source: https://context7.com/xoxno/rs-lending/llms.txt

This snippet shows an example command-line interface (CLI) command to execute a liquidation. It specifies the contract address, the function to call ('liquidate'), the account nonce to liquidate, and the ESDT transfers (token and amount) for the debt repayment. It also includes gas limit and chain parameters.

```bash
mxpy contract call erd1qqqqqqqqqqqqqpgq... \
  --function="liquidate" \
  --arguments 456 \
  --esdt-transfers=USDC-123456:1000000000 \  # 1000 USDC payment
  --gas-limit=20000000 \
  --chain=D

```

--------------------------------

### Shell: Example Contract Call for Borrowing

Source: https://context7.com/xoxno/rs-lending/llms.txt

This is an example shell command demonstrating how to call the 'borrow' function on the smart contract. It specifies the borrowed token, amount, and associated collateral (Account NFT). This command is useful for testing and understanding the contract's interaction from an external perspective.

```shell
// Example: Borrow 100 USDC against EGLD collateral
mxpy contract call erd1qqqqqqqqqqqqqpgq... \
  --function="borrow" \
  --arguments str:USDC-123456 100000000 \  # 100 USDC (6 decimals)
  --esdt-transfers=ACCOUNT-NFT:123:1 \  # Account NFT nonce 123
  --gas-limit=15000000 \
  --chain=D
```

--------------------------------

### Flash Loan Execution Example - CLI

Source: https://context7.com/xoxno/rs-lending/llms.txt

This command-line interface example demonstrates how to execute a flash loan of 1000 EGLD using the `flashLoan` function. It specifies the borrowed asset, amount, target contract address, and the callback endpoint. It also includes gas limit and chain parameters. Ensure the target contract has an `executeArbitrage` endpoint implemented.

```bash
# Example: Flash loan 1000 EGLD for arbitrage
mxpy contract call erd1qqqqqqqqqqqqqpgq... \
  --function="flashLoan" \
  --arguments str:EGLD 1000000000000000000000 erd1qqqqqqqqqqqqqpgq... str:executeArbitrage \
  --gas-limit=20000000 \
  --chain=D
```

--------------------------------

### Deploy and Manage Lending Markets (Make Commands)

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Core deployment and management operations for lending markets using make commands. Covers contract deployment, market creation, asset configuration, E-Mode setup, and oracle management. These commands are intended for a 'devnet' environment.

```bash
# 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
```

--------------------------------

### CLI: Example Repay Borrowed Debt Command

Source: https://context7.com/xoxno/rs-lending/llms.txt

This example demonstrates how to call the `repay` smart contract function using the `mxpy` command-line interface. It specifies the account nonce, the ESDT token to repay, the amount, and gas parameters. Note the format for `--esdt-transfers` which includes the token identifier and amount, adjusted for its decimals.

```bash
# Example: Repay 50 USDC debt for account 123
mxpy contract call erd1qqqqqqqqqqqqqpgq... \
  --function="repay" \
  --arguments 123 \
  --esdt-transfers=USDC-123456:50000000 \  # 50 USDC (6 decimals)
  --gas-limit=12000000 \
  --chain=D
```

--------------------------------

### Example Contract Call (CLI)

Source: https://context7.com/xoxno/rs-lending/llms.txt

This example demonstrates how to call the 'withdraw' function on the lending contract using the MultiversX CLI. It specifies the function to call, the arguments (in this case, 0.5 EGLD), and other necessary parameters like gas limit and chain. This is a practical illustration for interacting with the contract.

```bash
// Example: Withdraw 0.5 EGLD
mxpy contract call erd1qqqqqqqqqqqqqpgq... \
  --function="withdraw" \
  --arguments str:EGLD 500000000000000000 \  # 0.5 EGLD
  --esdt-transfers=ACCOUNT-NFT:123:1 \
  --gas-limit=12000000 \
  --chain=D
```

--------------------------------

### Elrond CLI: Query Asset Price

Source: https://context7.com/xoxno/rs-lending/llms.txt

An example command to query the asset price using the Elrond CLI. This demonstrates how to interact with a smart contract to retrieve price information for a specified asset, such as EGLD.

```shell
mxpy contract query erd1qqqqqqqqqqqqqpgq... \
  --function="getAssetPrice" \
  --arguments str:EGLD
```

--------------------------------

### Common Development Tasks for MultiversX Lending Protocol

Source: https://github.com/xoxno/rs-lending/blob/master/CLAUDE.md

Lists common development tasks for managing the lending protocol, including deploying contracts, market operations, oracle management, E-Mode setup, and contract verification.

```bash
# Deploy contracts
deployController
deployPriceAggregator
deployTemplateMarket

# Market operations
createMarket
upgradeMarket
listMarkets

# Oracle management
createOracle
addOracles
editOracleTolerance

# E-Mode setup
addEModeCategory
addAssetToEMode
listEModeCategories

# Verification
verifyController
verifyMarket
verifyPriceAggregator
```

--------------------------------

### Rust Storage Mapper Example

Source: https://github.com/xoxno/rs-lending/blob/master/CLAUDE.md

Demonstrates the use of the `#[storage_mapper]` attribute in Rust for defining storage mappers within a MultiversX smart contract module, specifically for a collection name.

```rust
#[multiversx_sc::module]
pub trait StorageModule {
    #[storage_mapper("collection_name")]
    fn collection_name(&self) -> SingleValueMapper<Type>;
}
```

--------------------------------

### Rust Input Validation Examples

Source: https://github.com/xoxno/rs-lending/blob/master/CLAUDE.md

Presents Rust code snippets for essential input validation in MultiversX smart contracts, focusing on checking for zero addresses and positive amounts.

```rust
require!(!address.is_zero(), Errors::ZERO_ADDRESS);
require!(amount > 0, Errors::INVALID_AMOUNT);
```

--------------------------------

### Rust Cache Pattern for Gas Optimization

Source: https://github.com/xoxno/rs-lending/blob/master/CLAUDE.md

Shows an example of implementing a cache pattern in Rust for gas optimization within MultiversX smart contracts, involving retrieving, modifying, and setting cache data.

```rust
let mut cache = self.get_cache();
// Perform operations on cache
self.set_cache(&cache);
```

--------------------------------

### Query User Account Data (Shell)

Source: https://context7.com/xoxno/rs-lending/llms.txt

Provides an example command to query user account data from a deployed contract using the `mxpy` CLI tool. It specifies the contract address, function to call, and the required argument (account NFT nonce). This is useful for interacting with the contract on a live network.

```shell
# Example: Query account positions
mxpy contract query erd1qqqqqqqqqqqqqpgq... \
  --function="getUserAccountData" \
  --arguments 123  # Account NFT nonce

```

--------------------------------

### Borrow Against Collateral (Bash)

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Bash command to borrow assets against existing collateral. This example shows borrowing USDC against EGLD collateral.

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

--------------------------------

### CLI: Query Deposit Rate for EGLD Market

Source: https://context7.com/xoxno/rs-lending/llms.txt

Example command to query the current deposit rate for the EGLD market using the mxpy contract query tool. This command specifies the contract address, the function to call ('deposit_rate'), and the relevant argument ('EGLD').

```bash
mxpy contract query erd1qqqqqqqqqqqqqpgq... \
  --function="deposit_rate" \
  --arguments str:EGLD
```

--------------------------------

### CLI: Query Borrow Rate for EGLD Market

Source: https://context7.com/xoxno/rs-lending/llms.txt

Example command to query the current borrow rate for the EGLD market using the mxpy contract query tool. This command specifies the contract address, the function to call ('borrow_rate'), and the relevant argument ('EGLD').

```bash
mxpy contract query erd1qqqqqqqqqqqqqpgq... \
  --function="borrow_rate" \
  --arguments str:EGLD
```

--------------------------------

### Automate Contract Deployment (Makefile)

Source: https://context7.com/xoxno/rs-lending/llms.txt

Demonstrates how to use a Makefile to automate the build and deployment process for smart contracts, specifically within a Docker environment for reproducibility. It lists commands for building the project and sequentially deploying core contracts like the price aggregator, template market, controller, and for registering account NFTs on a devnet.

```bash
# Build reproducibly using Docker
make build

# Deploy core contracts to devnet
make devnet deployPriceAggregator    # Step 1: Deploy oracle hub
make devnet deployTemplateMarket     # Step 2: Deploy EGLD pool template
make devnet deployController         # Step 3: Deploy main controller
make devnet registerToken            # Step 4: Register account NFT

```

--------------------------------

### Deploy to Devnet and Mainnet

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Commands to deploy the lending protocol's controller and other components to devnet and mainnet environments. Includes market creation for EGLD.

```bash
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
```

--------------------------------

### Core Build and Network Commands

Source: https://github.com/xoxno/rs-lending/blob/master/CLAUDE.md

Provides essential commands for building the project, running tests, and executing operations on different network environments (devnet, mainnet) using Makefiles.

```bash
make build
cargo build
cargo test

make devnet <command>
make mainnet <command>
```

--------------------------------

### Bash Build and Test Commands

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Provides shell commands for building all smart contracts and running comprehensive or specific test suites for the rs-lending project. Requires Rust and cargo tooling.

```bash
# 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
```

--------------------------------

### Bash Deployment Script Preparation

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Shell command to make deployment scripts executable. This is a prerequisite step before deploying the contracts to a network using the provided scripts.

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

--------------------------------

### Network Settings Configuration (JSON)

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Describes the network settings for the project, including endpoints, chain IDs, contract addresses, and oracle configurations. This section is a placeholder and details are expected within the `configs/networks.json` file.

```json
{
  "network_endpoints": "...",
  "chain_id": "...",
  "contract_addresses": {
    "controller": "...",
    "price_aggregator": "..."
  },
  "oracle_config": {},
  "account_and_token_details": {}
}
```

--------------------------------

### Unit Test Execution Commands

Source: https://github.com/xoxno/rs-lending/blob/master/CLAUDE.md

Details how to run unit tests in a Rust project, including commands to execute all tests, tests for a specific package, or tests with a particular name.

```bash
cargo test                           # All tests
cargo test --package controller     # Specific package
cargo test test_name               # Specific test
```

--------------------------------

### Market Parameters Configuration (JSON)

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Defines the risk parameters and configuration for a specific lending market, such as EGLD. Includes loan-to-value (ltv), liquidation thresholds, borrow/supply caps, interest rates, and reserve factors. This is a JSON configuration file.

```json
{
  "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
  }
}
```

--------------------------------

### Scaled Token System Calculations (Rust)

Source: https://github.com/xoxno/rs-lending/blob/master/liquidity_layer/README.md

Demonstrates the core formulas for calculating scaled and actual token amounts using a current index, crucial for managing assets with compound interest in the lending protocol.

```rust
scaled_amount = actual_amount / current_index
actual_amount = scaled_amount * current_index
```

--------------------------------

### Rust Staking Contract Exchange Rate Interface

Source: https://github.com/xoxno/rs-lending/blob/master/controller/ORACLE.md

Defines the interface for a Staking contract, specifically for retrieving LSD token exchange rates. It provides methods to get the current exchange rate, total staked amount, total supply, and the timestamp of the last exchange rate update. This is used for LSD token pricing.

```rust
trait StakingProvider {
    fn get_exchange_rate(&self) -> BigUint;
    fn get_total_staked(&self) -> BigUint;
    fn get_total_supply(&self) -> BigUint;
    fn get_last_exchange_rate_update(&self) -> u64;
}
```

--------------------------------

### Rust Price Monitoring Metrics

Source: https://github.com/xoxno/rs-lending/blob/master/controller/ORACLE.md

Defines key metrics for real-time price monitoring in the lending project. These metrics cover price deviation, source reliability, and position safety, which are crucial for production operations.

```rust
// Price deviation monitoring
deviation_first_tolerance: percentage // Current vs first threshold
deviation_last_tolerance: percentage  // Current vs last threshold
within_tolerance_count: counter       // Successful validations
tolerance_violation_count: counter    // Failed validations

// Source reliability metrics
aggregator_success_rate: percentage   // Aggregator uptime
safe_price_success_rate: percentage   // TWAP availability
average_response_time: milliseconds   // Oracle query latency
stale_price_count: counter            // Staleness violations

// Position safety metrics
unsafe_price_blocked_count: counter   // Operations blocked for borrowers
supplier_only_operations: counter     // Allowed unsafe price operations
position_safety_bypasses: counter     // Emergency overrides (if any)
```

--------------------------------

### Rust Oracle System Configuration Constants

Source: https://github.com/xoxno/rs-lending/blob/master/controller/ORACLE.md

Defines key constants for the oracle system's configuration, located in `common/constants`. These include tolerances for price fluctuations (minimum and maximum for first and last tolerance), a constant for seconds per minute used in freshness checks, and precision constants for various mathematical calculations (WAD, RAY, BPS). These values are critical for system calibration and operation.

```rust
/// Minimum first tolerance for oracle price fluctuation (0.50%)
pub const MIN_FIRST_TOLERANCE: usize = 50;

/// Maximum first tolerance for oracle price fluctuation (50%)
pub const MAX_FIRST_TOLERANCE: usize = 5_000;

/// Minimum last tolerance for oracle price fluctuation (1.5%)
pub const MIN_LAST_TOLERANCE: usize = 150;

/// Maximum last tolerance for oracle price fluctuation (100%)
pub const MAX_LAST_TOLERANCE: usize = 10_000;

/// TWAP freshness requirement (15 minutes)
pub const SECONDS_PER_MINUTE: u64 = 60;
// Freshness check: current_timestamp - last_update <= 15 * SECONDS_PER_MINUTE

/// Precision constants for mathematical calculations
pub const WAD_PRECISION: usize = 18;        // Standard 18-decimal precision
pub const WAD_HALF_PRECISION: usize = 9;     // For sqrt operations
pub const RAY_PRECISION: usize = 27;         // Interest rate calculations
pub const BPS_PRECISION: usize = 4;          // Basis points (0.01%)
```

--------------------------------

### Rust Error Handling Strategy

Source: https://github.com/xoxno/rs-lending/blob/master/controller/ORACLE.md

Outlines the error handling strategy for the oracle system, detailing a hierarchy of fallback mechanisms from aggregator price to safe price and finally panicking only when all sources fail. It also includes checks for position safety.

```rust
// Graceful degradation hierarchy:
1. Try aggregator price (with staleness check)
2. Fallback to safe price (TWAP)
3. Check allow_unsafe_price for position safety
4. Panic only if all sources fail
```

--------------------------------

### Market Configuration Parameters (JSON)

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

JSON object detailing the configuration parameters for an asset market, such as EGLD. Includes risk parameters like LTV and liquidation threshold, as well as interest rate settings and caps.

```json
{
  "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
  }
}
```

--------------------------------

### Piecewise Linear Interest Rate Model (Pseudocode)

Source: https://github.com/xoxno/rs-lending/blob/master/liquidity_layer/README.md

Illustrates the three-tier piecewise linear model used to calculate interest rates based on the utilization ratio of the lending pool. This model adjusts rates dynamically to encourage borrowing or supplying.

```pseudocode
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 / ...)
```

--------------------------------

### Rust Project Security and Edge Case Tests

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Runs security and edge case tests for the Rust lending project via Cargo. These tests focus on protecting against precision manipulation, validating mathematical rounding, and investigating interest rate calculations.

```bash
# 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
```

--------------------------------

### E-Mode Categories Configuration (JSON)

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Configures E-Mode categories, which allow for more efficient borrowing against correlated assets. This JSON file specifies parameters like name, loan-to-value (ltv), liquidation threshold, and liquidation bonus for each category.

```json
{
  "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
    }
  }
}
```

--------------------------------

### Core User Functions API

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

API endpoints for users to interact with the lending protocol, including supplying assets, borrowing, repaying loans, and liquidating positions.

```APIDOC
## Core User Functions

### `supply`

**Description**: Deposit assets to earn yield and create a position NFT.

**Method**: `POST` (via `mxpy contract call` or `make devnet supply`)

**Endpoint**: `/contract/call` (or specific `make` command)

**Parameters**:

#### Query Parameters
- **`optional_account_nonce`** (u64) - Optional - The nonce of the account making the transaction.
- **`e_mode_category`** (u8) - Optional - The efficiency mode category for supplying assets.

#### Request Body
- **`payment`** (TokenPayment) - The amount and token to supply.

### `withdraw`

**Description**: Withdraw supplied assets from your position.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`collaterals`** (Vec<TokenPayment>) - A list of token payments representing the assets to withdraw.
- **`nft_payment`** (NFT Payment) - Payment for the position NFT, used to track the position.

### `borrow`

**Description**: Borrow assets against your collateral.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`borrowed_tokens`** (Vec<TokenPayment>) - A list of token payments representing the assets to borrow.
- **`nft_payment`** (NFT Payment) - Payment for the position NFT, used to track the position.

### `repay`

**Description**: Repay borrowed assets.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Path Parameters
- **`account_nonce`** (u64) - The nonce of the account associated with the position.

#### Request Body
- **`payment`** (TokenPayment) - The amount and token to repay.

### `liquidate`

**Description**: Liquidate unhealthy positions to recover collateral.

**Method**: `POST` (via `make devnet liquidate` or `mxpy contract call`)

**Endpoint**: `/contract/call` (or specific `make` command)

**Parameters**:

#### Path Parameters
- **`account_nonce`** (u64) - The nonce of the account whose position is being liquidated.

#### Request Body
- **`payment`** (TokenPayment) - The payment used for liquidation, potentially receiving bonus.

### `flashLoan`

**Description**: Execute uncollateralized flash loans for arbitrage or liquidation purposes.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`token`** (string) - The token to borrow.
- **`amount`** (u256) - The amount to borrow.
- **`target_contract`** (Address) - The address of the contract to execute the loan with.
- **`endpoint`** (string) - The function name on the target contract to call.
- **`args`** (bytes) - Encoded arguments for the target contract function.

```

--------------------------------

### Rust Project Simulation Tests

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Executes simulation tests for the Rust lending project using Cargo. These tests cover complex scenario modeling and the validation of strategy operations within the lending protocol.

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

--------------------------------

### Rust Project Core Functionality Tests

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Executes core functionality tests for the Rust lending project using Cargo. This includes tests for basic lending operations, liquidation mechanisms, E-Mode functionality, and isolated market behavior.

```bash
# 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
```

--------------------------------

### Arda LP Pricing Model Calculation

Source: https://github.com/xoxno/rs-lending/blob/master/controller/ORACLE.md

This Rust code implements the Arda LP pricing model. It calculates the LP token price based on the constant product invariant (K), current prices from oracle feeds, and applies geometric mean formulas with precision handling. The output is the final LP token price.

```rust
// STEP 1: Get current reserves and prices
K = Reserve_A × Reserve_B  // Constant product invariant
Price_A = EGLD_price_of_token_A  // From oracle feeds  
Price_B = EGLD_price_of_token_B  // From oracle feeds

// STEP 2: Calculate price ratios for geometric mean
Price_Ratio_X = Price_B / Price_A
Price_Ratio_Y = Price_A / Price_B

// STEP 3: Apply geometric mean formula (Arda core)
X_Prime = sqrt(K × Price_Ratio_X)  // Modified reserve A
Y_Prime = sqrt(K × Price_Ratio_Y)  // Modified reserve B

// STEP 4: Calculate total LP value
Value_A = X_Prime × Price_A
Value_B = Y_Prime × Price_B
Total_LP_Value = Value_A + Value_B

// STEP 5: Final LP token price
LP_Price = Total_LP_Value / Total_Supply
```

--------------------------------

### Manage Account NFT and Attributes (Rust)

Source: https://context7.com/xoxno/rs-lending/llms.txt

Handles the creation and retrieval of account NFTs, which are central to position management. It supports creating new NFTs with specified attributes or using existing ones, validating attributes against operation requirements. Dependencies include various types from `TopEncode`, `TopDecode`, `NestedEncode`, `NestedDecode`, `TypeAbi`, and `ManagedTypeApi`.

```rust
// Account NFT attributes structure
#[derive(TopEncode, TopDecode, NestedEncode, NestedDecode, TypeAbi, Clone)]
pub struct AccountAttributes<M: ManagedTypeApi> {
    pub emode_id: u8,                          // E-Mode category (0 = disabled)
    pub is_isolated: bool,                     // Isolated asset mode
    pub isolated_token: Option<TokenId>,       // Isolated collateral asset
    pub position_mode: PositionMode,           // Normal/Multiply/Long/Short
}

// Create or retrieve account position NFT
fn get_or_create_account(
    &self,
    caller: &ManagedAddress,
    is_isolated: bool,
    position_mode: PositionMode,
    e_mode_category: OptionalValue<u8>,
    optional_account: Option<EgldOrEsdtTokenPayment>,
    optional_attributes: Option<AccountAttributes<Self::Api>>,
    optional_isolated_token: Option<EgldOrEsdtTokenIdentifier>,
) -> (u64, AccountAttributes<Self::Api>) {
    match optional_account {
        Some(account_nft) => {
            // Use existing account NFT
            let nonce = account_nft.token_nonce;
            let attributes = optional_attributes.unwrap();

            // Validate attributes match operation
            if is_isolated {
                require!(attributes.is_isolated(), ERROR_ACCOUNT_ATTRIBUTES_MISMATCH);
            }

            (nonce, attributes)
        },
        None => {
            // Create new account NFT
            let emode_id = e_mode_category.into_option().unwrap_or(0u8);
            let attributes = AccountAttributes {
                emode_id,
                is_isolated,
                isolated_token: optional_isolated_token,
                position_mode,
            };

            // Mint NFT with attributes
            let collection = self.account().get_token_id();
            let nonce = self.send().esdt_nft_create(
                &collection,
                &BigUint::from(1u64),
                &ManagedBuffer::new(),
                &BigUint::zero(),
                &ManagedBuffer::new(),
                &attributes,
                &ManagedVec::new(),
            );

            // Transfer NFT to user
            self.send().direct_esdt(
                caller,
                &collection,
                nonce,
                &BigUint::from(1u64),
            );

            (nonce, attributes)
        }
    }
}

```

--------------------------------

### Rust Error Handling Patterns

Source: https://github.com/xoxno/rs-lending/blob/master/CLAUDE.md

Illustrates common error handling techniques in Rust for MultiversX smart contracts, including conditional requirements and panicking with specific error types.

```rust
require!(condition, Errors::ERROR_NAME);
sc_panic!(Errors::CRITICAL_ERROR);
```

--------------------------------

### Key View Functions API

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

API endpoints for querying the current state and data of the lending protocol.

```APIDOC
## Key View Functions

### `health_factor`

**Description**: Calculate the health factor of a user's position, indicating its liquidation eligibility.

**Method**: `GET` (via `mxpy contract query`)

**Endpoint**: `/contract/query`

**Parameters**:

#### Query Parameters
- **`function`**: `health_factor`
- **`account_nonce`** (u64) - The nonce of the user's account.

**Returns**: `ManagedDecimal` - The calculated health factor.

### `user_account_data`

**Description**: Retrieve comprehensive data for a user's account, including supplied and borrowed assets.

**Method**: `GET` (via `mxpy contract query`)

**Endpoint**: `/contract/query`

**Parameters**:

#### Query Parameters
- **`function`**: `user_account_data`
- **`account_nonce`** (u64) - The nonce of the user's account.

**Returns**: `UserAccountData` - An object containing detailed account information.

### `all_markets`

**Description**: List all active asset markets within the protocol, including their configurations.

**Method**: `GET` (via `mxpy contract query`)

**Endpoint**: `/contract/query`

**Parameters**:

#### Query Parameters
- **`function`**: `all_markets`

**Returns**: `Vec<AssetMarket>` - A list of asset market data structures.

### `all_market_indexes`

**Description**: Retrieve the current interest rate indexes for all active markets.

**Method**: `GET` (via `mxpy contract query`)

**Endpoint**: `/contract/query`

**Parameters**:

#### Query Parameters
- **`function`**: `all_market_indexes`

**Returns**: `Vec<MarketIndex>` - A list of current interest rate indexes.

### `capital_utilisation`

**Description**: Get the current capital utilization ratio for a given market, used for interest rate modeling.

**Method**: `GET` (via `mxpy contract query`)

**Endpoint**: `/contract/query`

**Parameters**:

#### Query Parameters
- **`function`**: `capital_utilisation`
- **`market_token`** (string) - The token identifier of the market.

**Returns**: `ManagedDecimal` - The capital utilization ratio.

### `borrow_rate` / `deposit_rate`

**Description**: Query the current borrow or deposit Annual Percentage Rate (APR) / Annual Percentage Yield (APY) for a specific market.

**Method**: `GET` (via `mxpy contract query`)

**Endpoint**: `/contract/query`

**Parameters**:

#### Query Parameters
- **`function`**: `borrow_rate` or `deposit_rate`
- **`market_token`** (string) - The token identifier of the market.

**Returns**: `ManagedDecimal` - The current APR/APY.

```

--------------------------------

### Continuous Compound Interest Approximation (Pseudocode)

Source: https://github.com/xoxno/rs-lending/blob/master/liquidity_layer/README.md

Shows the Taylor series approximation used for calculating the compound interest factor, enabling continuous compounding of interest over time based on the interest rate and time delta.

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

--------------------------------

### Administrative Functions API

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

API endpoints for administrators to manage the lending protocol's configuration and parameters.

```APIDOC
## Administrative Functions

### `editAssetConfig`

**Description**: Update risk and interest rate parameters for a specific asset.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`asset`** (string) - The identifier of the asset to configure.
- **`ltv`** (string) - The new loan-to-value ratio (e.g., "7500" for 75.00%).
- **`liquidation_threshold`** (string) - The new liquidation threshold (e.g., "8000" for 80.00%).
- **`liquidation_bonus`** (string) - The new liquidation bonus percentage (e.g., "550" for 5.50%).

**Access Control**: `only_owner`

### `addEModeCategory`

**Description**: Create a new efficiency mode category with associated risk parameters.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`category_id`** (u8) - The unique identifier for the new e-mode category.
- **`ltv`** (string) - The loan-to-value ratio for this category.
- **`liquidation_threshold`** (string) - The liquidation threshold for this category.
- **`liquidation_bonus`** (string) - The liquidation bonus for this category.

**Access Control**: `only_owner`

### `setPositionLimits`

**Description**: Configure gas-safe limits for the number of supply and borrow positions per user.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`max_borrow_positions`** (u32) - The maximum number of borrow positions allowed.
- **`max_supply_positions`** (u32) - The maximum number of supply positions allowed.

**Access Control**: `only_owner`

### `setAggregator`

**Description**: Set the address of the price aggregator contract.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`aggregator_address`** (Address) - The address of the new price aggregator.

**Access Control**: `only_owner`

### `setSafePriceView`

**Description**: Set the address of the TWAP (Time-Weighted Average Price) price oracle.

**Method**: `POST` (via `mxpy contract call`)

**Endpoint**: `/contract/call`

**Parameters**:

#### Request Body
- **`safe_price_view_address`** (Address) - The address of the TWAP price oracle.

**Access Control**: `only_owner`

```

--------------------------------

### Supply Assets to Earn Yield (Bash)

Source: https://github.com/xoxno/rs-lending/blob/master/README.md

Bash commands to supply EGLD to the lending protocol, either for general yield or with E-Mode for higher efficiency. This action creates a position NFT.

```bash
# 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
```

--------------------------------

### Liquidity Pool Flash Loan Implementation - Rust (rs-lending)

Source: https://context7.com/xoxno/rs-lending/llms.txt

This Rust code implements the flash loan functionality within a liquidity pool. It calculates the flash loan fee, converts amounts, transfers funds to the target contract, executes a callback, and validates the repayment. It requires token identifiers, amounts in WAD precision, target contract address, endpoint name, arguments, fee in basis points, and price in WAD.

```rust
// Liquidity pool flash loan implementation
fn flash_loan(
    &self,
    token: EgldOrEsdtTokenIdentifier,
    amount_wad: ManagedDecimal<Self::Api, NumDecimals>,
    target_contract: &ManagedAddress,
    endpoint: ManagedBuffer<Self::Api>,
    args: ManagedArgBuffer<Self::Api>,
    fee_bps: ManagedDecimal<Self::Api, NumDecimals>,
    price_wad: ManagedDecimal<Self::Api, NumDecimals>,
) {
    // Calculate flash fee: fee = amount * fee_bps / 10000
    let flash_fee = self.mul_half_up(&amount_wad, &fee_bps, WAD_PRECISION);
    let flash_fee = self.div_half_up(&flash_fee, &self.bps(), WAD_PRECISION);
    let amount_plus_fee = amount_wad.clone() + flash_fee;

    // Convert to raw amount
    let amount_raw = self.from_decimal(amount_wad, params.asset_decimals);
    let expected_repayment = self.from_decimal(amount_plus_fee, params.asset_decimals);

    // Transfer funds to target contract and execute callback
    self.tx()
        .to(target_contract)
        .raw_call(&endpoint)
        .arguments_raw(args.into())
        .esdt_or_egld(&token, 0, &amount_raw)
        .transfer_execute();

    // Validate repayment
    let received_payment = self.call_value().single_esdt();
    require!(
        received_payment.amount >= expected_repayment,
        ERROR_INVALID_FLASHLOAN_REPAYMENT
    );
}
```

--------------------------------

### Recursive Price Resolution: Multi-Hop Pricing Algorithm Overview

Source: https://github.com/xoxno/rs-lending/blob/master/controller/ORACLE.md

Details the advanced pathfinding algorithm for discovering token prices through multi-hop routes when direct EGLD pairs are unavailable. It involves graph construction, path discovery using Dijkstra-like algorithms, cost evaluation, liquidity validation, and result caching.

```plaintext
1. Graph Construction: Build liquidity graph from all available DEX pairs
2. Path Discovery: Identify optimal routes using Dijkstra-like algorithm
3. Cost Evaluation: Balance gas costs vs. price accuracy
4. Liquidity Validation: Ensure adequate depth at each hop
5. Result Caching: Store successful paths for future queries
```

--------------------------------

### Bad Debt Socialization Calculation (Pseudocode)

Source: https://github.com/xoxno/rs-lending/blob/master/liquidity_layer/README.md

Explains the mechanism for distributing immediate losses due to bad debt by reducing the supply index. This ensures fair loss distribution among suppliers.

```pseudocode
reduction_factor = (total_supplied - bad_debt) / total_supplied
new_supply_index = old_supply_index * reduction_factor
```

--------------------------------

### Execute Flash Loan - Rust (rs-lending)

Source: https://context7.com/xoxno/rs-lending/llms.txt

This Rust code defines the controller endpoint for executing flash loans. It handles validation, reentrancy protection, and forwards the loan request to the liquidity pool. It requires the `EgldOrEsdtTokenIdentifier`, `BigUint` for amount, `ManagedAddress` for the target contract, `ManagedBuffer` for the endpoint, and `ManagedArgBuffer` for arguments. It returns a result indicating success or failure.

```rust
// Controller endpoint: execute flash loan with callback
#[endpoint(flashLoan)]
fn flash_loan(
    &self,
    borrowed_asset_id: &EgldOrEsdtTokenIdentifier,
    amount_raw: BigUint,
    contract_address: &ManagedAddress,  // Target contract for callback
    endpoint: ManagedBuffer<Self::Api>,  // Callback function name
    mut arguments: ManagedArgBuffer<Self::Api>,  // Callback arguments
) {
    let mut cache = Cache::new(self);
    let caller = self.blockchain().get_caller();

    // Reentrancy protection
    self.reentrancy_guard(cache.flash_loan_ongoing);
    let asset_config = cache.cached_asset_info(borrowed_asset_id);
    require!(asset_config.can_flashloan(), ERROR_FLASHLOAN_NOT_ENABLED);

    // Validate shard and endpoint security
    self.validate_flash_loan_shard(contract_address);
    self.validate_flash_loan_endpoint(&endpoint);

    // Set global flash loan flag
    self.flash_loan_ongoing().set(true);

    // Append original caller to arguments
    arguments.push_arg(caller);

    // Forward to liquidity pool
    let pool_address = cache.cached_pool_address(borrowed_asset_id);
    self.tx()
        .to(pool_address)
        .typed(proxy_pool::LiquidityPoolProxy)
        .flash_loan(
            borrowed_asset_id,
            amount_wad,
            contract_address,
            endpoint,
            arguments,
            asset_config.flashloan_fee_bps,  // Typically 50 BPS (0.5%)
            feed.price_wad,
        )
        .returns(ReturnsResult)
        .sync_call();

    // Clear flash loan flag
    self.flash_loan_ongoing().set(false);
}
```

--------------------------------

### Flash Loan Receiver - Execute Arbitrage - Rust (rs-lending)

Source: https://context7.com/xoxno/rs-lending/llms.txt

This Rust code defines the `executeArbitrage` endpoint for a flash loan receiver contract. It demonstrates receiving the flash loan funds, performing an arbitrage strategy, and repaying the loan along with the fee. It requires the `flash_loan_amount` and `original_caller` as arguments. The contract needs to implement logic to `perform_arbitrage` and correctly calculate the repayment.

```rust
// Flash loan receiver contract must implement callback
#[endpoint(executeArbitrage)]
fn execute_arbitrage(
    &self,
    flash_loan_amount: BigUint,
    original_caller: ManagedAddress,
) {
    // 1. Receive flash loan funds
    let payment = self.call_value().egld_or_single_esdt();

    // 2. Execute arbitrage strategy
    let profit = self.perform_arbitrage(&payment);

    // 3. Repay flash loan + fee (0.5%)
    let fee = payment.amount.clone() * 50u64 / 10000u64;
    let repayment = payment.amount + fee;

    self.tx()
        .to(&self.blockchain().get_caller())  // Controller contract
        .payment(&EgldOrEsdtTokenPayment::new(payment.token_identifier, 0, repayment))
        .transfer();
}
```

--------------------------------

### Rust: Safe Price Feed Validation with TWAP

Source: https://context7.com/xoxno/rs-lending/llms.txt

Implements a three-tier price validation system comparing an aggregator price feed with a 15-minute TWAP from a DEX. It uses configurable tolerance bounds to determine price reliability. Supports allowing unsafe prices for specific operations like supply/repay under strict conditions.

```rust
// Primary validation: ±2% tolerance (TWAP vs Aggregator)
fn safe_price_feed(
    &self,
    token_id: &EgldOrEsdtTokenIdentifier,
    cache: &mut Cache<Self>,
    pricing_method: PricingMethod,
) -> PriceFeedShort<Self::Api> {
    let tolerances = oracle.tolerance.clone();

    // Get aggregator price (median of multiple oracles)
    let aggregator_price = self.aggregator_price_feed(
        &oracle.base_token_id,
        &price_aggregator_addr,
        oracle.max_price_stale_seconds,
        cache.allow_unsafe_price,
    );

    // Get Safe Price View (15-minute TWAP from DEX)
    let safe_price = self.tx()
        .to(&safe_price_view_addr)
        .typed(proxy_safe_price::SafePriceViewProxy)
        .update_and_get_safe_price(
            &oracle.exchange_source,
            &oracle.base_token_id,
            &oracle.quote_token_id,
        )
        .returns(ReturnsResult)
        .sync_call();

    // Three-tier validation
    if self.is_within_anchor(
        &aggregator_price,
        &safe_price,
        &tolerances.first_upper_ratio_bps,  // +2%
        &tolerances.first_lower_ratio_bps,  // -2%
    ) {
        // Primary check passed: use TWAP price
        safe_price
    } else if self.is_within_anchor(
        &aggregator_price,
        &safe_price,
        &tolerances.second_upper_ratio_bps,  // +5%
        &tolerances.second_lower_ratio_bps,  // -5%
    ) {
        // Secondary check: average both prices
        (aggregator_price + safe_price) / 2u64
    } else {
        // Deviation > 5%: block risky operations
        require!(cache.allow_unsafe_price, ERROR_UN_SAFE_PRICE_NOT_ALLOWED);
        safe_price  // Only allow supply/repay
    }
}
```
Tokens:
Raw