StellarLend

Asset Onboarding Checklist

Use this checklist when onboarding a new asset to the protocol. Complete each item and record the reviewer and documentation updates before merging.

• Configuration: Add asset parameters (collateral factor, liquidation threshold, decimals, oracle feed) via set_asset_params
• Oracle: Register and validate the price feed; confirm fallback and staleness handling
• Risk Review: Confirm risk parameters against protocol limits and document rationale
• Testing: Add unit and integration tests covering deposit, borrow, repay, withdraw, and liquidation paths
• Liquidity: Verify pool whitelisting and minimum liquidity ratio requirements
• Monitoring: Add the asset to monitoring/alerting dashboards and rebalancing config
• Documentation: Update protocol docs, entrypoint references, and changelog
• Review: Obtain sign-off from a second reviewer

Onboarding Sign-off

Item	Owner	Status
Configuration
Oracle
Risk Review
Testing
Liquidity
Monitoring
Documentation
Review

Stablecoin Reserve Rebalancing Automation

The system automatically maintains stablecoin pegs across pools by:

1. Monitoring: Continuously checks pool prices against target peg
2. Detecting: Identifies significant deviations (>1% by default)
3. Arbitrage: Executes cross-pool transfers to normalize prices
4. Safety: Maintains minimum liquidity ratios and transfer limits

Configuration

Edit src/config/automation.ts:

const stablecoinConfig = {
  targetPegPrice: 1.0,          // Target price (e.g., 1.0 for USDT/USDC)
  thresholdPercentage: 0.01,    // % deviation before action
  maxTransferAmount: 1000000,   // USD value per transfer
  minLiquidityRatio: 0.95,      // Minimum liquidity ratio
  checkIntervalMinutes: 15,    // Monitoring frequency
  pools: ['USDT_POOL_1', 'USDC_POOL_2'] // Whitelisted pools
};

Troubleshooting

• No actions executed: Verify pool prices are outside threshold
• Failed transfers: Check liquidity ratios and transaction limits
• Monitoring gaps: Confirm scheduler is running (src/scheduler.ts)

Testing

Run comprehensive tests:

npm test automation/balancer.test.ts

<<<<<<< HEAD The unified contract suite runs the shared test-utils framework and the suites built on it. It records timing, gas benchmarks and coverage:

scripts/testing/run-contract-tests.sh            # all suites
scripts/testing/run-contract-tests.sh bench      # gas benchmark reports
scripts/testing/run-contract-tests.sh coverage   # lcov + summary (cargo-llvm-cov)

See stellar-lend/TESTING.md for fixtures, seeding, scenarios and CI.

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

Docker Quickstart

To run the project locally without manually installing Node.js dependencies, you can use Docker:

1. Ensure you have Docker and Docker Compose installed.
2. Create your local environment files at api/.env and oracle/.env (use .env.example as a template).
3. From the root directory, build and start the containers:

   docker-compose up --build
   

4. The API will be accessible at http://localhost:3000.

Local Soroban Devnet (Docker Compose)

For a full local Stellar/Soroban environment (local node, Horizon, Friendbot, deployed contracts, seeded accounts and test data):

cd docker/devnet
cp .env.example .env
docker compose up -d            # boots the Soroban node, API, oracle, postgres, redis
./healthcheck.sh --wait         # wait for init + services

• Soroban RPC: http://localhost:8000/soroban/rpc
• Horizon: http://localhost:8000
• Friendbot (free test XLM): http://localhost:8000/friendbot

Fund extra devnet accounts with XLM and devnet USDC using the faucet: npm run devnet:faucet -- <identity|address>.

See docker/devnet/README.md for full setup, seeded data, liquidation scenarios, and reset instructions. The same environment is used by the VS Code Dev Container.

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.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗