Skip to content

README.md

Latest commit

 

History

History
97 lines (84 loc) · 5.4 KB

README.md

File metadata and controls

97 lines (84 loc) · 5.4 KB

StellarLend Protocol Documentation

This repository contains the Soroban smart contracts and related resources for the StellarLend protocol.

Contents:

  • Overview
  • Modules and Features
  • Admin Operations
  • Monitoring & Analytics
  • Upgrade & Configuration
  • Event Indexing
  • Cross-Chain Bridge
  • Social Recovery & Multisig

Overview

StellarLend is a lending and borrowing protocol built on Soroban. It features cross-asset accounting, risk management, governance, AMM integration, flash loans, and more.

Test Documentation

  • Borrow Function Tests - Comprehensive test suite documentation for the borrow functionality, covering all validation paths, edge cases, interest accrual, pause functionality, events, and security scenarios.
  • Event Indexing Guide - Catalog of contract events, indexing options for RPC, Mercury, and SubQuery, and the current status of stellar-lend/indexing_system/.
  • Upgrade Mechanism - Runbook for planned and emergency upgrades, rollback handling, and storage compatibility guidance.

Modules and Features

  • Interest rate model with smoothing
  • Risk config and scoring
  • Cross-asset positions and oracle support
  • Flash loans with configurable fees
  • AMM integration hooks (swap, add/remove liquidity)
  • Cross-chain bridge interface with fees and events
  • Analytics: global and per-user metrics, daily snapshots
  • Monitoring: health, performance, and security alerts
  • Social recovery: guardians, timelock approvals, execution
  • Multisig for admin min-collateral changes
  • Upgrade tracking and approval manager in contracts/lending; see upgrade-mechanism.md for current scope and limitations
  • Data management: generic data store, backup/restore, migration
  • Configuration: versioned param store with backup/restore

Admin Operations

Key admin entrypoints (see contract for full list):

  • initialize(admin)
  • set_min_collateral_ratio(caller, ratio)
  • set_risk_params(...), set_pause_switches(...)
  • set_price_cache_ttl(caller, ttl)
  • register_bridge(caller, network_id, bridge, fee_bps)
  • set_bridge_fee(caller, network_id, fee_bps)
  • upgrade_propose/approve/execute/rollback in the separate lending workspace upgrade manager
  • config_set/config_backup/config_restore
  • ms_set_admins, ms_propose_set_min_cr, ms_approve, ms_execute

Monitoring & Analytics

  • record_user_action(user, action) updates risk and emits events
  • Analytics auto-update on deposit/borrow/repay/withdraw
  • Monitoring entrypoints: monitor_report_health/performance/security, monitor_get
  • Event indexing details, topic layouts, and decoding examples are documented in event-indexing.md

Analytics Read APIs

  • get_protocol_report() & get_user_report(address) surface typed structs (ProtocolReport, UserReport) containing current metrics, active-user counts, and the latest activity feed snapshot time.
  • get_asset_report(asset) returns AssetReport with per-asset analytics and historical bucketed data.
  • get_recent_activity(limit) supplies an ActivityFeed with newest-first entries, a total_available counter (capped at 1,000 retained records), and the generated_at ledger timestamp for indexers.
  • Activity entries include user, activity_type, amount, optional asset, and a metadata map for extended tags.
  • Example payloads: protocol_report.json and user_report.json demonstrate the serialized shape returned by the contract. Monetary totals are raw integers in the protocol’s smallest units, and percentage-style fields (e.g., utilization, success rate, health score) are exported as fixed-point integers scaled by 1e6 (333333 ≈ 33.3333%).
  • Field hints:
    • total_value_locked, total_deposits, total_borrows, etc. are cumulative atomic units across all assets.
    • Percentage-like values (e.g., avg_utilization_rate, protocol_risk_score, uptime_percentage, collateralization_ratio) use the same 1e6 scaling; divide by 1_000_000 to obtain human-readable percentages.
    • User analytics expose running totals plus derived scores (activity_score, loyalty_tier) that map to reward tiers.
  • Example Soroban call: 
    soroban contract invoke \
  --id <contract-id> \
  --fn get_recent_activity \
  --arg limit=50
    Returns a feed where entries[0] is the most recent action; set limit to 0 for metadata-only responses.

Upgrade & Configuration

  • The separate lending workspace ships an UpgradeManager with proposal, approval, execute, and rollback metadata tracking
  • upgrade_status returns tracked version state for that manager
  • See upgrade-mechanism.md for the exact process and the current limitation that code swaps are not automated by the manager itself
  • Config supports version bumps, validation, and easy backup/restore

Event Indexing

  • event-indexing.md covers the current hello-world event surface, additional workspace contracts, testnet/mainnet indexing choices, and why stellar-lend/indexing_system/ should currently be treated as deprecated prototype code

Cross-Chain Bridge

  • Register networks and fees, and use bridge_deposit/bridge_withdraw to move balances with transparent fees

Social Recovery & Multisig

  • Set guardians per-user and execute timelocked recoveries
  • Multisig supports proposing and executing admin changes with threshold