StellarLend Smart Contracts

Overview

StellarLend is a decentralized finance (DeFi) lending protocol built on the Stellar blockchain using Soroban smart contracts. The protocol enables users to deposit collateral, borrow assets, accrue interest, and participate in a secure, transparent, and risk-managed lending market. Designed for DeFi developers, protocol integrators, and users seeking a robust lending solution on Stellar, StellarLend provides comprehensive features including cross-asset support, flash loans, AMM integration, governance mechanisms, and advanced risk management tools.

The protocol is built with production-grade security in mind, featuring social recovery, multisig governance, upgrade mechanisms, and comprehensive monitoring and analytics. Whether you're building a DeFi application, integrating lending capabilities, or contributing to the protocol's development, StellarLend offers a complete, auditable, and extensible foundation for decentralized lending on Stellar.

---

Features

• Collateralized Lending: Users can deposit collateral and borrow against it with support for multiple asset types
• Dynamic Interest Rate Model: Interest rates adjust based on protocol utilization with configurable parameters
• Oracle Integration: Real-time price feeds with validation, fallback mechanisms, and caching
• Risk Management: Admin-configurable risk parameters, pause switches, and advanced liquidation logic
• Partial Liquidation: Supports close factor and liquidation incentive for liquidators
• Cross-Asset Operations: Multi-asset collateral and borrowing with unified position tracking
• Flash Loans: Configurable flash loan functionality with fee management
• AMM Integration: Built-in hooks for automated market maker (AMM) swaps and liquidity operations
• Cross-Chain Bridge: Interface for cross-chain asset transfers with fee management
• Governance: Multisig support for critical parameter changes
• Social Recovery: Guardian-based recovery mechanisms for enhanced security
• Upgrade System: Propose, approve, execute, and rollback contract upgrades
• Analytics & Monitoring: Comprehensive protocol and user analytics with activity feeds
• Comprehensive Event Logging: Emits events for all major protocol actions

---

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Rust (latest stable version) - Install Rust
• Cargo (comes with Rust) - Cargo Documentation
• Soroban CLI - Install Soroban CLI
• Stellar CLI (optional, for advanced operations) - Stellar Developer Tools

Installing Rust Components

After installing Rust, add the required components:

# Add Rust formatting and linting tools
rustup component add rustfmt clippy

# Add WebAssembly target for Soroban contracts
rustup target add wasm32-unknown-unknown

Installing Soroban CLI

# macOS (using Homebrew)
brew install stellar-cli

# Or using cargo
cargo install --locked soroban-cli

Installation

1. Clone the repository:

   git clone <repo-url>
   cd stellarlend-contracts

2. Navigate to the contract directory:

   cd stellar-lend/contracts/lending

3. Verify your setup:

   # Check Rust version
   rustc --version
   
   # Check Cargo version
   cargo --version
   
   # Check Soroban CLI
   stellar --version

Environment Setup

No environment variables are required for local development and testing. The contract uses Soroban's built-in test utilities for development.

For deployment to networks, you may need:

• Network RPC endpoint (for testnet/mainnet)
• Admin account keypair
• Oracle contract addresses (if using external oracles)

Building

Build the contract using the Soroban CLI:

# From stellar-lend/contracts/lending/
stellar contract build

# Or using Cargo directly
cargo build --target wasm32-unknown-unknown --release

# Or using the Makefile
make build

The compiled WASM file will be located at:

target/wasm32-unknown-unknown/release/stellarlend_lending.wasm

Testing

Run the test suite:

# From stellar-lend/contracts/lending/
cargo test

# Run with verbose output
cargo test -- --nocapture

# Run specific test
cargo test test_function_name

# Or using the Makefile
make test

Running Local CI Checks

To reproduce CI checks locally before pushing:

# From project root
chmod +x local-ci.sh
./local-ci.sh

This script runs:

• Format checking (cargo fmt)
• Linting (cargo clippy)
• Contract building and optimization
• Unit tests
• Security audit (cargo audit)
• Documentation generation

Network Deployment

Deploy to Testnet

# Build the contract
stellar contract build

# Deploy to testnet (requires testnet account)
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/stellarlend_lending.wasm \
  --network testnet \
  --source <your-testnet-keypair>

# Initialize the contract
stellar contract invoke \
  --id <contract-id> \
  --network testnet \
  --source <admin-keypair> \
  -- initialize \
  --admin <admin-address>

Deploy to Mainnet

# Build and optimize
stellar contract build
stellar contract optimize \
  --wasm target/wasm32-unknown-unknown/release/stellarlend_lending.wasm

# Deploy (use optimized WASM)
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/stellarlend_lending-optimized.wasm \
  --network mainnet \
  --source <your-mainnet-keypair>

⚠️ Security Note: Always audit and test thoroughly before deploying to mainnet. Use multisig for admin operations in production.

---

Repository Structure

stellarlend-contracts/
├── README.md                 # This file
├── local-ci.sh               # Local CI reproduction script
├── docs/                     # Protocol documentation
│   ├── README.md            # Detailed protocol documentation
│   └── examples/            # Example JSON reports
│       ├── protocol_report.json
│       └── user_report.json
└── stellar-lend/            # Main contract workspace
    ├── Cargo.toml           # Workspace configuration
    └── contracts/
        └── lending/         # Canonical StellarLend contract (79 .rs files)
            ├── Cargo.toml
            ├── Makefile     # Build/test shortcuts
            ├── README.md    # Contract-specific docs
            └── src/
                ├── lib.rs, debt.rs, cross_asset.rs, rate_model.rs,
                ├── math.rs, events.rs, upgrade.rs,
                ├── rounding_strategy.rs,
                └── 71 test/*_test.rs files

---

Contract Modules

The canonical contract lives at stellar-lend/contracts/lending/. Its module layout:

lending (stellar-lend/contracts/lending/src/) — the canonical contract

Core lending logic (deposit, withdraw, borrow, repay, liquidation, pausing, oracle price handling, cross-asset positions, etc.) lives directly in lib.rs as #[contractimpl] functions on LendingContract — there are no separate deposit.rs/borrow.rs/repay.rs/ withdraw.rs/liquidate.rs/oracle.rs/governance.rs/amm.rs/flash_loan.rs/analytics.rs files in this crate. The supporting modules that do exist are:

• debt.rs: Debt position accounting and interest accrual (global borrow-index model plus legacy elapsed-time accrual).
• cross_asset.rs: Multi-asset collateral/debt storage helpers and cross-asset health-factor computation.
• rate_model.rs: Kink-model interest rate curve, plus rate smoothing/hysteresis.
• rounding_strategy.rs: Configurable-rounding interest calculator used by debt.rs.
• math.rs: Shared checked-arithmetic helpers.
• events.rs: Versioned event structs/emitters for deposit/withdraw/borrow/repay/liquidate.
• upgrade.rs: Self-contained timelocked multisig upgrade governance (propose/approve/execute).

See the contract's own README for the full, accurate interface.

---

Key Entrypoints

Core Operations

Function	Description
initialize	Initialize contract and set admin
deposit	Deposit collateral to the protocol
borrow	Borrow assets against collateral
repay	Repay borrowed assets
withdraw	Withdraw collateral
liquidate	Liquidate undercollateralized positions

Oracle, Admin, and Emergency Controls

Function	Description
get_admin	Read current admin
propose_admin	Propose admin handoff
accept_admin	Accept pending admin role
set_guardian	Configure shutdown guardian
get_guardian	Read shutdown guardian
set_emergency_state	Set protocol emergency state
set_min_borrow	Configure minimum borrow amount
get_min_borrow	Read minimum borrow amount
set_debt_ceiling	Configure debt ceiling
set_flash_fee	Configure flash loan fee
set_oracle_pubkey	Configure signed price oracle public key
get_oracle_pubkey	Read oracle public key
set_price	Store a signed oracle price update
get_price_record	Read stored oracle price

Flash Loans

Function	Description
flash_loan	Issue a callback-based flash loan
repay_flash_loan	Repay flash-loan funds to treasury storage

Query Functions

Function	Description
get_position	Query user position (collateral, debt, ratio)
get_debt_position	Query raw debt principal and last update time
get_health_factor	Query current health factor
get_protocol_metrics	Query aggregate debt, supply, utilization, ledger

For exact signatures and planned-but-not-shipping names, see docs/interface_quick_reference.md.

---

Documentation

• Developer Glossary: Key protocol terms, numeric scales (BPS, Health Factor), and common pitfalls for integrators
• Protocol Documentation: Comprehensive protocol documentation including modules, admin operations, monitoring, analytics, and upgrade procedures
• Release Checklist: Required tests, invariant coverage, upgrade safety, security notes template, and CI gates for every contract PR
• Upgrade Authorization: Strict upgrade authorization boundaries, key rotation workflow, and security assumptions
• Storage Layout and Migration: Detailed documentation of the contract's persistent storage structure, keys, types, and upgrade/migration strategies
• Cross-Asset Rules: Borrowing/repay rules, view guarantees (G-1..G-10), and invariants for multi-asset positions
• Repay Semantics: Both repay paths (single-asset vs cross-asset), overpay behaviour, interest ordering, and dust prevention
• Contract README: Contract-specific documentation and entrypoint reference
• CI/CD Overview: Continuous integration setup and local reproduction guide
• Example Reports: Example JSON outputs for protocol and user analytics

---

Contributing

We welcome contributions! Here's how to get started:

Development Workflow

1. Fork the repository and clone your fork
2. Create a branch for your feature or fix:

   git checkout -b feature/your-feature-name

3. Make your changes following the code style:
   • Run cargo fmt to format your code
   • Run cargo clippy to check for linting issues
   • Write tests for new functionality
4. Run local CI checks:

   ./local-ci.sh

5. Commit your changes with clear, descriptive commit messages
6. Push to your fork and open a pull request

Code Style

• Follow Rust standard formatting (cargo fmt)
• Address all Clippy warnings (cargo clippy)
• Write unit tests for new functionality
• Add documentation comments for public functions
• Keep functions focused and modular

Pull Request Guidelines

• For bug fixes: Include a description of the bug and how your fix addresses it
• For new features: Describe the feature, its use case, and any breaking changes
• For major changes: Discuss in an issue first before implementing
• Testing: Ensure all tests pass and add tests for new functionality
• Documentation: Update relevant documentation files

Reporting Issues

When reporting issues, please include:

• Description of the issue
• Steps to reproduce
• Expected vs. actual behavior
• Environment details (Rust version, Soroban CLI version, etc.)
• Relevant logs or error messages

Security

If you discover a security vulnerability, please do not open a public issue. Instead, contact the maintainers directly through a secure channel.

---

License

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

---

Links & Resources

Official Documentation

• Stellar Soroban Documentation
• Stellar Developers Portal
• Soroban Examples

Development Tools

• Rust Programming Language
• Cargo Documentation
• Soroban CLI Reference

Community

• Stellar Discord
• Stellar Stack Exchange
• Stellar GitHub

---

Support

For questions, issues, or contributions:

• Open an issue on GitHub for bug reports or feature requests
• Check the documentation for detailed protocol information
• Review CI documentation for build and test issues