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

Clone the repository:

git clone <repo-url>
cd stellarlend-contracts

Navigate to the contract directory:
```
cd stellar-lend/contracts/hello-world
```

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/hello-world/
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/hello_world.wasm

Testing

Run the test suite:

# From stellar-lend/contracts/hello-world/
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/hello_world.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/hello_world.wasm

# Deploy (use optimized WASM)
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/hello_world-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/         # Main StellarLend contract (Single Canonical Tree)
        │   ├── Cargo.toml
        │   ├── Makefile     # Build/test shortcuts
        │   ├── README.md    # Contract-specific docs
        │   └── src/
        │       ├── lib.rs   # Main contract entry point
        │       ├── rounding_strategy.rs # Mathematical utilities
        │       └── interest_drift_regression_test.rs # Regression tests
        └── hello-world/     # Minimal placeholder contract
            ├── Cargo.toml
            ├── Makefile
            ├── README.md
            └── src/
                └── lib.rs

Contract Modules

The StellarLend contract is organized into the following modules:

Core Lending (deposit.rs, borrow.rs, repay.rs, withdraw.rs): Deposit collateral, borrow assets, repay debt, and withdraw collateral
Liquidation (liquidate.rs): Partial liquidation with close factor and liquidation incentives
Oracle (oracle.rs): Price feed integration with validation, fallback, and caching
Governance (governance.rs): Admin controls, multisig, and parameter management
AMM Integration (amm.rs): Automated market maker hooks for swaps and liquidity
Flash Loans (flash_loan.rs): Configurable flash loan functionality
Analytics (analytics.rs): Protocol and user metrics, activity feeds, and reporting

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

Fork the repository and clone your fork

Create a branch for your feature or fix:

git checkout -b feature/your-feature-name

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
Run local CI checks:
```
./local-ci.sh
```
Commit your changes with clear, descriptive commit messages
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.

Name		Name	Last commit message	Last commit date
Latest commit History 1,755 Commits
.claude		.claude
.github		.github
.vscode		.vscode
api		api
contracts/lending/scr		contracts/lending/scr
docs		docs
oracle		oracle
scripts		scripts
stellar-lend		stellar-lend
stellarlend-contracts		stellarlend-contracts
.gitignore		.gitignore
CONTRIBUTORS.md		CONTRIBUTORS.md
README.md		README.md
UPGRADE_MIGRATION_IMPLEMENTATION.md		UPGRADE_MIGRATION_IMPLEMENTATION.md
local-ci.sh		local-ci.sh
package-lock.json		package-lock.json

Folders and files

Latest commit

History

Repository files navigation

StellarLend Smart Contracts

Overview

Features

Getting Started

Prerequisites

Installing Rust Components

Installing Soroban CLI

Installation

Environment Setup

Building

Testing

Running Local CI Checks

Network Deployment

Deploy to Testnet

Deploy to Mainnet

Repository Structure

Contract Modules

Key Entrypoints

Core Operations

Oracle, Admin, and Emergency Controls

Flash Loans

Query Functions

Documentation

Contributing

Development Workflow

Code Style

Pull Request Guidelines

Reporting Issues

Security

License

Links & Resources

Official Documentation

Development Tools

Community

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages