YieldVault is a decentralized vault platform built specifically for the Stellar network. It bridges the gap between complex Real-World Asset (RWA) infrastructure and retail adoption by allowing users to deposit USDC and earn yield generated by tokenized real-world assets (like tokenized Korean bonds or other sovereign debt instruments) via Stellar's Soroban smart contracts.
This project is structured as a monorepo containing both the Stellar Soroban smart contracts and the frontend web application.
/contracts/vault/: Contains the Rust Soroban smart contract for handling the vault logic, fractional share minting (yvUSDC), scaling withdrawals, and simulated yield accrual./contracts/mock-strategy/: Contains test mock contracts for the Korean sovereign debt strategy and price oracle./frontend/: Contains the React + Vite frontend application, integrating@stellar/freighter-apifor seamless user wallet connections and a premium UI to interact with the protocol./docs/: Contains the Product Requirements Document (PRD), Architecture Document, Domain Glossary, and tracked GitHub issues. See also the Deposit & Withdrawal Lifecycle for sequence diagrams and the Vault UX Pattern Library for approved frontend interaction rules.
For a comprehensive overview of the smart contract architecture, module responsibilities, and interaction boundaries, see Contracts Architecture.
| Module | Purpose |
|---|---|
| YieldVault | Main vault contract: deposit/withdraw, yield accrual, strategy management, DAO governance, RWA shipment tracking |
| StrategyTrait | Interface for pluggable strategy connectors |
| BenjiStrategy | Test connector for BENJI fund token strategy |
| MockKoreanSovereignStrategy | Test mock for Korean debt strategy with stepped yield curve |
| OracleValidator | Standalone oracle price validation library (heartbeat, deviation, decimals) |
| MockPriceOracle | Test mock oracle with configurable failure modes |
- Network: Stellar (Testnet/Mainnet)
- Smart Contracts: Soroban (Rust, WebAssembly)
- Frontend: Vite, React, TypeScript, Vanilla CSS
- Wallet Connection: Freighter
For complete local development setup with service dependencies, startup order, and troubleshooting, see:
- Local Development Quickstart – Complete setup guide with step-by-step instructions
- Service Dependency Matrix – Visual dependency graph and service specifications
- Stellar Testnet & Mainnet Deployment Runbook – Pinned toolchain alignment, optimizations, and upgrade guide
-
Start infrastructure (PostgreSQL + Redis):
docker-compose up -d postgres redis
-
Start backend API (in one terminal):
cd backend && npm install && npx prisma migrate dev && npm run dev
-
Start frontend (in another terminal):
cd frontend && npm install && npm run dev
-
Configure frontend contract env (required before on-chain features work):
cp frontend/.env.local.example frontend/.env.local # Set VITE_VAULT_CONTRACT_ID from deployment.json after a contract deploy npm run validate:frontend-env -- --env-file frontend/.env.local --strict --check-rpc -
Open browser: http://localhost:5173
After installing backend dependencies, fund a contributor wallet with Friendbot:
read -rsp "Testnet secret key: " TESTNET_SECRET_KEY && echo
export TESTNET_SECRET_KEY
node scripts/fund-testnet-account.js
unset TESTNET_SECRET_KEYTo create a classic test-USDC trustline, set TESTNET_USDC_ISSUER. For a
locally controlled test issuer, also set TESTNET_USDC_ISSUER_SECRET; the
script will send TESTNET_USDC_AMOUNT (default 1000) to the contributor
wallet. Secrets are read only from environment variables and are never
committed or printed.
For detailed setup instructions, prerequisites, and troubleshooting, see Local Development Quickstart.
For a complete environment variable reference with defaults, required flags, and production recommendations, see Environment Variable Matrix.
Generate contract and frontend API docs:
cargo doc -p vault --no-deps
cd frontend
npm install
npm run docs:apiSee docs/api/README.md for output locations. Integrators should also read
docs/api/ERROR_CODE_CATALOG.md for error codes
and remediation guidance, and docs/api/PAGINATION.md for
deterministic cursor paging examples.
Pagination consumer examples:
YieldVault emits cryptographically-signed events for all critical vault operations. Off-chain services can consume these events to track deposits, withdrawals, fee changes, and other protocol activity.
For a complete guide on consuming YieldVault events, see Webhook Integration Guide.
Listen for vault events (TypeScript):
import { Server } from "@stellar/stellar-sdk";
const server = new Server("https://soroban-testnet.stellar.org");
const contractId = "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4";
const response = await server.getEvents({
filters: [{ type: "contract", contractIds: [contractId] }],
startLedger: 0,
limit: 100,
});
for (const event of response.events) {
console.log(`Event: ${event.topic[1]}`, event.value);
}Events emitted:
deposit— User deposits USDC and receives sharespndwdraw— Large withdrawal initiated (24-hour timelock)withdraw— Withdrawal completesfeechg— Protocol fee updatedmindepchg— Minimum deposit threshold updated
Complete examples:
YieldVault has comprehensive disaster recovery procedures to ensure system resilience:
- RTO (Recovery Time Objective): 1 hour for critical systems
- RPO (Recovery Point Objective): 15 minutes maximum data loss
- Runbooks: Step-by-step recovery procedures for all failure scenarios. Key runbooks include:
- Phase 1: Planning, Documentation, and Frontend UI Baseline (Completed)
- Phase 2: Soroban Smart Contract Implementation in Rust (Completed)
- Phase 3: Stellar Testnet Deployment and Frontend Integration (Up next)
- Phase 4: Security Audit and Mainnet Launch
Fork the repository and clone it to your local machine Create a new branch for your changes Make and test your updates following the project guidelines Commit and push your changes to your fork Open a Pull Request with a clear description