StellarVault 🏦

A DeFi protocol library for Stellar — token vaults, AMM pools, staking, collateralised lending, yield vaults, price oracles, and governance, all built as composable Rust primitives ready for Soroban deployment.

Features

• 🪙 VaultToken — mintable/burnable SEP-41-style token with allowances
• 💧 AmmPool — constant-product AMM (x·y=k) with configurable fees and slippage guards
• 🌾 StakingVault — reward-per-token staking with accurate multi-user reward splitting
• 🏦 LendingMarket — collateralised lending with utilisation-based interest rates and liquidations
• 📈 YieldVault — ERC-4626-style share-based yield vault
• 🔮 PriceOracle — asset price store with staleness checks
• 🏛️ GovernanceContract — proposal/vote/execute on-chain governance

Quick Start

git clone https://github.com/Pilot39/StellarVault.git
cd StellarVault
cargo test

Project Structure

StellarVault/
├── src/
│   ├── lib.rs                  # Crate root and re-exports
│   ├── contracts/
│   │   ├── token.rs            # VaultToken
│   │   ├── amm.rs              # AmmPool
│   │   ├── staking.rs          # StakingVault
│   │   ├── lending.rs          # LendingMarket
│   │   ├── vault.rs            # YieldVault
│   │   ├── oracle.rs           # PriceOracle
│   │   └── governance.rs       # GovernanceContract
│   ├── math/
│   │   └── fixed_point.rs      # mul_div, bps_of, simple_interest, isqrt
│   └── types/                  # Shared data types
├── tests/
│   └── integration_tests.rs    # Cross-contract integration tests
├── examples/
│   ├── amm_demo.rs
│   ├── staking_demo.rs
│   └── lending_demo.rs
└── Cargo.toml

Usage

Add to your Cargo.toml:

[dependencies]
stellar-vault = { git = "https://github.com/Pilot39/StellarVault" }

Token

use stellar_vault::VaultToken;

let mut token = VaultToken::new("My Token", "MTK", 7);
token.mint("alice", 1_000_000)?;
token.transfer("alice", "bob", 250_000)?;

AMM Pool

use stellar_vault::AmmPool;

let mut pool = AmmPool::new("XLM", "USDC");
pool.add_liquidity("alice", 10_000, 40_000, 0)?;
let out = pool.swap("XLM", 500, 0)?; // swap 500 XLM for USDC

Staking

use stellar_vault::StakingVault;

let mut vault = StakingVault::new("SVT", "REWARD", 100); // 100 tokens/sec
vault.stake("alice", 5_000, now)?;
let rewards = vault.claim("alice", now + 3600)?; // claim after 1 hour

Lending

use stellar_vault::LendingMarket;

let mut market = LendingMarket::new("USDC");
market.supply("alice", 100_000)?;
market.borrow("bob", 20_000, 14_000, now)?; // 70% LTV
let owed = market.repay("bob", now + 86400)?;

Governance

use stellar_vault::GovernanceContract;

let mut gov = GovernanceContract::new(86_400, 1_000); // 1 day, 1_000 quorum
let id = gov.propose("alice", "Increase fee", "Raise swap fee to 0.5%", now);
gov.vote("alice", id, true, 2_000, now)?;
gov.finalise(id, now + 86_401)?;
gov.execute(id)?;

Running Examples

cargo run --example amm_demo
cargo run --example staking_demo
cargo run --example lending_demo

Testing

cargo test                    # all tests
cargo test --lib              # unit tests only
cargo test --test integration # integration tests only

Math Utilities

All financial calculations use integer fixed-point arithmetic to avoid floating-point non-determinism:

Function	Description
mul_div(a, b, denom)	a * b / denom with overflow check
bps_of(amount, rate_bps)	Apply a basis-point rate
simple_interest(principal, rate_bps, secs)	Simple annual interest
prec_mul / prec_div	PRECISION-scaled multiply/divide
isqrt(n)	Integer square root

License

MIT OR Apache-2.0