YieldVault - Stellar RWA

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.

Project Structure

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-api for 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.

Architecture

For a comprehensive overview of the smart contract architecture, module responsibilities, and interaction boundaries, see Contracts Architecture.

Contract Modules

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

Technology Stack

• Network: Stellar (Testnet/Mainnet)
• Smart Contracts: Soroban (Rust, WebAssembly)
• Frontend: Vite, React, TypeScript, Vanilla CSS
• Wallet Connection: Freighter

Getting Started

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

Quick Start (5 minutes)

1. Start infrastructure (PostgreSQL + Redis):

   docker-compose up -d postgres redis

2. Start backend API (in one terminal):

   cd backend && npm install && npx prisma migrate dev && npm run dev

3. Start frontend (in another terminal):

   cd frontend && npm install && npm run dev

4. Open browser: http://localhost:5173

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.

API Documentation

Generate contract and frontend API docs:

cargo doc -p vault --no-deps
cd frontend
npm install
npm run docs:api

See docs/api/README.md for output locations. Integrators should also read docs/api/ERROR_CODE_CATALOG.md for error codes and remediation guidance.

Webhook Integration

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.

Quick Start

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 shares
• pndwdraw — Large withdrawal initiated (24-hour timelock)
• withdraw — Withdrawal completes
• feechg — Protocol fee updated
• mindepchg — Minimum deposit threshold updated

Complete examples:

• TypeScript Consumer
• Python Consumer

Disaster Recovery

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

See Disaster Recovery Runbooks for detailed procedures.

Roadmap (Phases)

• 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

🤝 Contributing

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