Stellar Liquidity and Yield Optimization Engine

A comprehensive DeFi yield optimization platform built on Stellar's Soroban smart contracts, featuring auto-compounding vaults, intelligent rebalancing, and advanced risk management tools.

🚀 Features

Core Functionality

• Auto-compounding Yield Vaults: Automatically harvest and reinvest rewards for maximum yield
• Smart Rebalancing Engine: Move liquidity between pools based on APY and impermanent loss metrics
• Multi-token Reward Distribution: Support for XLM, USDC, and native reward tokens
• Plug-in Strategy System: Customizable yield farming strategies with risk levels
• Emergency Controls: Pause functionality and admin controls for security

Advanced Features

• Impermanent Loss Calculation: Real-time IL tracking and historical analysis
• Risk Assessment: Comprehensive risk scoring and scenario analysis
• Performance Analytics: Detailed metrics, Sharpe ratios, and drawdown analysis
• Automated Bots: Harvest and rebalancing bots with configurable parameters
• React UI Components: Modern interface for vault management and monitoring

📋 Architecture

stellar-liquidity-yield-engine/
├── src/                          # Soroban Contracts (Rust)
│   ├── lib.rs                   # Main contract exports
│   ├── yield_vault.rs           # Auto-compounding vault logic
│   ├── rebalance_engine.rs      # Smart liquidity rebalancing
│   ├── reward_distributor.rs    # Multi-token reward distribution
│   └── strategy_registry.rs     # Strategy management system
├── sdk/src/                     # TypeScript SDK
│   ├── vaultClient.ts           # Vault interaction client
│   ├── rebalancer.ts            # Rebalancing execution client
│   ├── yieldCalculator.ts       # Risk and yield calculations
│   ├── types.ts                 # TypeScript interfaces
│   └── index.ts                 # SDK exports
├── ui/src/components/           # React Components
│   ├── YieldVaultCard.tsx       # Vault display and controls
│   ├── RebalancePanel.tsx       # Rebalancing visualization
│   ├── ImpermanentLossChart.tsx # IL analysis charts
│   ├── StrategySelector.tsx     # Strategy selection interface
│   └── hooks/useYieldVault.ts   # React hooks for vault data
└── examples/                    # Example Scripts
    ├── auto-compound-setup.ts   # Auto-compounding configuration
    ├── cross-pool-rebalance.ts  # Cross-pool rebalancing
    ├── yield-harvest-bot.ts     # Automated harvesting bot
    └── risk-analysis.ts         # Risk analysis tools

🛠️ Installation

Prerequisites

• Rust 1.70+ with Soroban CLI
• Node.js 18+
• TypeScript 5+
• Stellar SDK

Build Contracts

# Install Rust and Soroban
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install soroban-cli

# Build contracts (run from the repository root — Cargo.toml lives there)
cargo build --target wasm32-unknown-unknown --release

Install SDK

cd sdk/
npm install
npm run build

Setup UI

cd ui/
npm install
npm run dev

🔧 Quick Start

1. Deploy Contracts

See the full Contract Deployment section below for the actual build/deploy/initialize commands and current build caveats.

2. Create a Yield Vault

import { VaultClient, TESTNET_CONFIG } from 'stellar-liquidity-yield-engine-sdk';

const vaultClient = new VaultClient('VAULT_ADDRESS', TESTNET_CONFIG);

// Initialize vault
await vaultClient.initialize(
  adminKeyPair,
  'USDC-XLM Vault',
  USDC_ADDRESS,
  XLM_ADDRESS,
  POOL_ADDRESS,
  STRATEGY_ID,
  100,  // 1% fee rate
  50,   // 0.5% harvest fee
  100   // 1% withdrawal fee
);

3. Deposit Liquidity

// Deposit tokens
const result = await vaultClient.deposit(userKeyPair, {
  amountA: BigInt(1000000),  // 1 USDC
  amountB: BigInt(5000000),  // 5 XLM
  minShares: BigInt(950000)
});

4. Enable Auto-compounding

// Configure auto-compounding
const autoCompoundManager = new AutoCompoundManager(vaultAddress, TESTNET_CONFIG);

// Start monitoring (every hour)
autoCompoundManager.startMonitoring(userKeyPair, 60);

📊 Vault Strategies

Conservative Strategy

• Risk Level: Low (1/3)
• Target APY: 8-12%
• Max IL Risk: 10%
• Suitable For: Risk-averse users, stable assets

Balanced Strategy

• Risk Level: Medium (2/3)
• Target APY: 12-20%
• Max IL Risk: 20%
• Suitable For: Balanced risk-return profile

Aggressive Strategy

• Risk Level: High (3/3)
• Target APY: 20-35%
• Max IL Risk: 30%
• Suitable For: High risk tolerance, volatile assets

🔄 Rebalancing System

The rebalancing engine automatically optimizes liquidity allocation:

Features

• Multi-pool Analysis: Monitor performance across all vault pools
• APY Thresholds: Rebalance when APY gaps exceed thresholds
• IL Risk Assessment: Consider impermanent loss in decisions
• Gas Optimization: Batch transactions for cost efficiency
• Slippage Protection: Maximum slippage tolerance settings

Arbitrage profitability and round-trip costs

The SDK compares one year of expected APY-difference returns against a round-trip estimate for the configured investment amount. The estimate must cover both entering the destination pool and exiting it, and must report network, execution, and protocol costs in the same asset and base units as the investment. The scanner exposes gross_profit before these fees, round_trip_cost for their sum, and net_profit after fees. Opportunities with zero or negative net profit are excluded; remaining opportunities are ranked by net return with the existing impermanent-loss risk adjustment. IL risk remains a separate routing check and is deducted by the profitability simulation.

Provide an ArbitrageScanner roundTripCostEstimator (and pass the investment amount, asset, and source pool to findOpportunities) to enable cost-aware recommendations. AutoRebalancer accepts the same estimator and an investmentAsset for its maxPositionSize. The estimator must convert fees such as XLM-denominated network charges into the investment asset using a trustworthy quote source, return all three cost components, and return null if a component or conversion is unavailable. Missing, negative, malformed, or wrong-asset estimates are logged and excluded; the SDK never treats unknown fees as zero. The same round-trip estimate is reused by ranking, profitability calculation, and simulation rather than charged again at each step.

There is currently no built-in network-fee, execution-fee, or protocol-fee oracle/converter for this arbitrage path. Until an estimator is configured, arbitrage opportunities are intentionally not recommended. APY differences are annualized, so the comparison assumes a one-year holding period; shorter holding periods and unmodeled costs must be handled by the configured estimator or a separate strategy constraint.

Configuration

const rebalancerClient = new RebalancerClient(TESTNET_CONFIG);

// Create rebalancing strategy
const strategyId = await rebalancerClient.createStrategy(
  adminKeyPair,
  'Dynamic Yield Optimization',
  2, // Balanced risk
  1000, // 10% minimum APY
  1500, // 15% max IL risk
  86400, // Rebalance every 24 hours
  allocations
);

💰 Reward Distribution

Multi-token reward system supporting:

• XLM: Native Stellar token
• USDC: Stablecoin rewards
• Native Tokens: Project-specific reward tokens
• Merkle Distribution: Efficient off-chain calculation
• Claim Deadlines: Time-limited reward claims — each stream carries a claim_deadline (Unix seconds) set in add_reward_stream and adjustable with set_claim_deadline; claim_rewards rejects a stream once the ledger passes it. A deadline of 0 means the stream never expires.
• Fee Structure: Performance and management fees

Claiming Rewards

const rewardClient = new RewardDistributorClient(TESTNET_CONFIG);

// Claim rewards
const claimed = await rewardClient.claimRewards(
  userKeyPair,
  userAddress,
  vaultAddress,
  rewards,
  merkleProof
);

📈 Risk Management

Impermanent Loss Analysis

import { YieldCalculator } from 'stellar-liquidity-yield-engine-sdk';

// Calculate current IL
const il = YieldCalculator.calculateImpermanentLoss(
  1.0,    // Initial price ratio
  1.5,    // Current price ratio
  30      // Days elapsed
);

console.log(`Current IL: ${il.ilPercent.toFixed(2)}%`);

Risk Metrics

• Value at Risk (VaR): 95% confidence level
• Conditional VaR (CVaR): Expected loss beyond VaR
• Maximum Drawdown: Historical peak-to-trough loss
• Sharpe Ratio: Risk-adjusted return measure
• Volatility Analysis: Asset and portfolio volatility

Scenario Analysis

// Run Monte Carlo simulation
const simulation = YieldCalculator.simulateImpermanentLoss(
  1.0,    // Initial price ratio
  0.25,   // 25% volatility
  30,     // 30 days
  1000    // 1000 simulations
);

console.log(`Average IL: ${simulation.averageIl.toFixed(2)}%`);
console.log(`Worst case IL: ${simulation.worstCaseIl.toFixed(2)}%`);

🤖 Automated Bots

Harvest Bot

Automated reward harvesting with intelligent timing:

import { YieldHarvestBot } from './examples/yield-harvest-bot';

const bot = new YieldHarvestBot(BOT_CONFIG, BOT_KEYPAIR, TESTNET_CONFIG);

// Start bot
await bot.start();

// Force harvest specific vault
await bot.forceHarvest('VAULT_ADDRESS');

Bot Configuration

• Check Interval: Monitoring frequency (15-60 minutes)
• Reward Thresholds: Minimum rewards for harvesting
• Gas Price Limits: Maximum acceptable gas costs
• Cooldown Periods: Minimum time between harvests
• Performance Tracking: Detailed harvest statistics

🎛️ React Components

YieldVaultCard

Complete vault interface with deposit/withdraw functionality:

import { YieldVaultCard } from '@/components/YieldVaultCard';

<YieldVaultCard
  vaultAddress="VAULT_ADDRESS"
  userAddress="USER_ADDRESS"
  network="testnet"
/>

RebalancePanel

Visual rebalancing interface with strategy management:

import { RebalancePanel } from '@/components/RebalancePanel';

<RebalancePanel network="testnet" />

ImpermanentLossChart

Interactive IL analysis and visualization:

import { ImpermanentLossChart } from '@/components/ImpermanentLossChart';

<ImpermanentLossChart
  initialPriceRatio={1.0}
  currentPriceRatio={1.5}
  timeElapsed={30}
/>

🔒 Security Features

Contract Security

• In-place Upgrades: Every contract exposes admin-only upgrade(admin, new_wasm_hash), migrate(admin) and get_storage_version() so deployed state can be fixed without changing the contract address — see docs/UPGRADING.md
• Emergency Pause: Admin can pause all operations
• Access Control: Role-based permissions
• Input Validation: Comprehensive parameter checks
• Reentrancy Protection: Prevent recursive calls
• Overflow Protection: Safe arithmetic operations

Risk Mitigation

• Slippage Protection: Maximum acceptable price impact
• Position Limits: Maximum exposure per vault
• Time Locks: Delays for sensitive operations
• Multi-signature: Enhanced admin security
• Audit Trail: Complete operation logging

Swap-router slippage tolerance

max_slippage_bps and the router's default_slippage are integer basis points (100 = 1%). They accept values from 0 through 100 inclusive. Values above 100 are rejected with InvalidSlippage; an invalid admin update does not replace the previously configured value. Supplying no per-quote value uses the validated configured default.

📊 Performance Metrics

Key Performance Indicators

• APY: Annual percentage yield after fees
• TVL: Total value locked across all vaults
• Harvest Efficiency: Rewards harvested per gas spent
• IL Impact: Average impermanent loss experienced
• User Retention: User engagement and retention rates

Analytics Dashboard

Real-time monitoring of:

• Vault performance and rankings
• Strategy effectiveness
• Risk metrics and alerts
• Gas usage and optimization
• User activity patterns

🌐 Network Support

Testnet

• RPC: https://soroban-testnet.stellar.org
• Horizon: https://horizon-testnet.stellar.org
• Network Passphrase: Test SDF Network ; September 2015

Mainnet

• RPC: https://soroban.stellar.org
• Horizon: https://horizon.stellar.org
• Network Passphrase: Public Global Stellar Network ; September 2015

🔧 Configuration

Environment Variables

Copy .env.example to .env and fill in real values:

cp .env.example .env

# Network configuration
STELLAR_NETWORK=testnet
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
HORIZON_URL=https://horizon-testnet.stellar.org

# Contract addresses
YIELD_ENGINE_ADDRESS=...
REWARD_DISTRIBUTOR_ADDRESS=...
REBALANCE_ENGINE_ADDRESS=...
STRATEGY_REGISTRY_ADDRESS=...

# Bot configuration
BOT_PRIVATE_KEY=...
HARVEST_THRESHOLD=1000
CHECK_INTERVAL=300000

.env.example also lists governance-related addresses (GOVERNANCE_CONTRACT, VOTING_ESCROW_CONTRACT, etc.) read by sdk/src/governance.ts. There is no working contract to deploy for those yet — see GOVERNANCE_STATUS.md.

Contract Deployment

There is no scripts/ directory in this repo — deploy with the soroban CLI directly. All commands below run from the repository root (that's where Cargo.toml lives; the crate is not under src/).

One contract per wasm. Soroban exports a contract's entrypoints under their plain function names, so two contracts cannot live in the same wasm binary — they collide on shared names such as initialize or pause. Each contract is behind a Cargo feature; build the one you are deploying with --no-default-features --features <contract>. A default cargo build (every feature) is for host builds and tests only. src/governance.rs is not part of the crate and is still incomplete — see GOVERNANCE_STATUS.md.

Deployable contracts: engine (the umbrella StellarLiquidityYieldEngine), yield-vault, rebalance-engine, reward-distributor, strategy-registry, il-insurance, actuary.

# 0. One-time setup: install the wasm target and create/fund a testnet identity
rustup target add wasm32-unknown-unknown
soroban keys generate deployer --network testnet
soroban keys fund deployer --network testnet

# 1. Build one contract's wasm
cargo build --target wasm32-unknown-unknown --release \
  --no-default-features --features yield-vault
# -> target/wasm32-unknown-unknown/release/stellar_liquidity_yield_engine.wasm
# Repeat with a different --features value for each contract you deploy.

# 2. (Optional) Optimize the wasm binary size
soroban contract optimize \
  --wasm target/wasm32-unknown-unknown/release/stellar_liquidity_yield_engine.wasm

# 3. Deploy — prints the deployed CONTRACT_ID
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/stellar_liquidity_yield_engine.wasm \
  --source deployer \
  --network testnet

# 4. Initialize the deployed contract (use the CONTRACT_ID from step 3)
soroban contract invoke \
  --id CONTRACT_ID \
  --source deployer \
  --network testnet \
  -- \
  initialize \
  --admin $(soroban keys address deployer) \
  --strategy_registry STRATEGY_REGISTRY_ADDRESS \
  --reward_distributor REWARD_DISTRIBUTOR_ADDRESS

# 5. Verify it deployed correctly by reading back a value
soroban contract invoke \
  --id CONTRACT_ID \
  --source deployer \
  --network testnet \
  -- \
  get_admin

Save the resulting CONTRACT_ID into your .env file as YIELD_ENGINE_ADDRESS (and repeat steps 3–4 for any other addresses you need, such as STRATEGY_REGISTRY_ADDRESS and REWARD_DISTRIBUTOR_ADDRESS, before running step 4 above).

🧪 Testing

Unit Tests

# Run contract tests (run from the repository root)
cargo test

# Run SDK tests
cd sdk/
npm test

# Run component tests
cd ui/
npm test

Integration Tests

# Run full integration suite
npm run test:integration

# Run performance benchmarks
npm run test:performance

📚 API Reference

VaultClient

class VaultClient {
  // Core operations
  deposit(keypair: any, params: DepositParams): Promise<TransactionResult>
  withdraw(keypair: any, params: WithdrawParams): Promise<TransactionResult>
  harvest(keypair: any): Promise<TransactionResult>
  
  // Queries
  getVaultInfo(): Promise<VaultInfo>
  getMetrics(): Promise<VaultMetrics>
  getUserPosition(address: Address): Promise<UserPosition>
  getAPY(): Promise<number>
  getTVL(): Promise<bigint>
  
  // Admin functions
  pause(keypair: any): Promise<TransactionResult>
  unpause(keypair: any): Promise<TransactionResult>
}

RebalancerClient

class RebalancerClient {
  // Strategy management
  createStrategy(keypair: any, ...params): Promise<number>
  updateStrategy(keypair: any, ...params): Promise<void>
  getStrategies(): Promise<RebalanceStrategy[]>
  
  // Rebalancing
  analyzeRebalanceOpportunities(strategyId: number): Promise<RebalanceProposal[]>
  executeRebalance(keypair: any, proposal: RebalanceProposal): Promise<boolean>
  
  // Analytics
  getHistory(limit: number): Promise<RebalanceHistory[]>
  calculateImpermanentLoss(poolId: Address, ...): Promise<number>
}

YieldCalculator

class YieldCalculator {
  // Impermanent loss
  static calculateImpermanentLoss(initialRatio: number, currentRatio: number, timeElapsed: number): ImpermanentLossData
  static simulateImpermanentLoss(initialRatio: number, volatility: number, timePeriod: number, simulations: number): SimulationResult
  
  // Yield calculations
  static projectApy(historicalApy: number[], marketConditions: MarketConditions, timeHorizon: number): ApyProjection
  static estimateFeeRevenue(tvl: bigint, ...): FeeRevenue
  
  // Risk metrics
  static calculateSharpeRatio(returns: number[], riskFreeRate: number): number
  static calculateMaxDrawdown(values: number[]): MaxDrawdownData
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Code Standards

• Rust: cargo fmt and cargo clippy
• TypeScript: ESLint and Prettier
• React: Component testing with Jest
• Documentation: Updated README and API docs

📄 License

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

🆘 Support

• Documentation: GitHub Repository
• Discord: Stellar Yield Community
• Issues: GitHub Issues
• Email: support@stellar-yield.com

🗺️ Roadmap

Q1 2024

• Core vault functionality
• Auto-compounding system
• Basic rebalancing engine
• React UI components

Q2 2024

• Advanced strategy system
• Cross-chain support
• Mobile app
• Governance features (in-progress scaffolding exists in src/governance.rs but does not compile or work yet — see GOVERNANCE_STATUS.md)

Q3 2024

• DeFi integrations
• Advanced analytics
• Insurance products
• Layer 2 optimization

Q4 2024

• AI-powered optimization
• Social trading
• Enterprise features
• Regulatory compliance

📊 Performance Benchmarks

Vault Operations

• Deposit: ~50,000 gas
• Withdraw: ~60,000 gas
• Harvest: ~45,000 gas
• Rebalance: ~80,000 gas

SDK Performance

• Vault Query: <100ms
• Strategy Analysis: <500ms
• Risk Calculation: <200ms
• Batch Operations: <1s

UI Metrics

• Initial Load: <2s
• Transaction Response: <500ms
• Chart Rendering: <300ms
• Real-time Updates: <100ms

🔍 Audits

Security Audits

This project has not yet undergone a third-party security audit. Do not use in production or with real funds until an audit has been completed. This section will be updated with audit firm names, dates, and report links once an audit is performed.

Reporting a Vulnerability

There is no bug bounty program at this time. If you discover a security issue, please open a GitHub issue or contact the maintainers directly rather than disclosing it publicly.

---

Built with ❤️ for the Stellar ecosystem