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 and the Deposit & Withdrawal Troubleshooting Guide for diagnosing failed operations.

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, startup order, and troubleshooting, see:

• Local Development Quickstart - Backend, contracts, and frontend bootstrap
• Service Dependency Matrix - Service relationships and operational notes

Quick Start

1. Start the backend:

   cd backend
   cp .env.example .env
   npm install
   npx prisma migrate dev
   npm run dev

2. Start the frontend in a second terminal:

   cd frontend
   cp .env.example .env
   npm install
   npm run dev

3. Optional: run contract tests from the repo root:

   rustup target add wasm32-unknown-unknown
   cargo test

4. Open the app at http://localhost:5173

The default local workflow uses Prisma's SQLite database and in-memory fallbacks for Redis-backed features unless you explicitly configure additional infrastructure.

For detailed setup instructions, prerequisites, validation steps, 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 & Incident Response

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.

Incident Response

See the Incident Runbook for the complete incident triage guide, including:

• Severity classification (Sev0–Sev3) with definitions, example scenarios, and response SLAs
• First responder triage flow with step-by-step instructions for the first 15 minutes
• Escalation paths with triggers and contact information
• Communication templates for status updates and stakeholder notifications
• Symptom-to-playbook quick reference for rapid diagnosis

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

Quarterly Milestones

• Q1: Finalize product scope, harden core vault flows, and complete baseline integration testing.
• Q2: Ship testnet-ready contract and frontend integration, then close critical polish gaps.
• Q3: Expand security review, run load and failure-mode validation, and prepare launch readiness.
• Q4: Complete mainnet launch checklist, monitor production stability, and gather retrospective improvements.

Deployment

For step-by-step deployment checklists covering both Testnet and Mainnet environments (smart contracts, backend, frontend, and infrastructure), see:

• Deployment Checklist — Comprehensive deployment checklist with pre-deployment, deployment, post-deployment verification, and rollback procedures
• Deployment & Operations Runbook — Smart contract deployment and upgrade procedures
• Release Readiness Checklist — Release readiness gate checklist
• Release Verification Checklist — Release verification for backend, frontend, and contracts

# Validate branch naming, PR description format, and contribution standards
npm run validate:contribution-standards

# Validate the testing strategy document for unit, integration, and E2E coverage guidance
npm run validate:testing-strategy

# Validate sprint label formats and issue triage taxonomy
npm run validate:sprint-and-triage

# Validate release notes template and cliff config
npm run validate:release-notes

# Validate NFR baselines (SLO, RTO, RPO)
npm run validate:nfr-baselines

🤝 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