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, Vault Invariants, Protocol Risk Limits, Oracle Failure Handling, Performance Regression Thresholds, Root Scripts Reference, and tracked GitHub issues. See also the Deposit & Withdrawal Lifecycle for sequence diagrams, the Deposit & Withdrawal Troubleshooting Guide for diagnosing failed operations, and the Dependency Update Policy for upgrade cadence, testing gates, CVE SLAs, and high-risk library requirements.

Architecture

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

For a cross-layer view of ownership boundaries, API flow maps, event propagation, and interface assumptions between the frontend, backend, and contracts, see System Ownership & Data Flow.

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)
AccountingInvariants	Contract-level total-supply and share-price consistency checks
ProtocolRiskLimits	Protocol-wide TVL, concentration, and stress-mode exposure caps
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

Node ≥ 20 and pnpm ≥ 9.12 are required. The lockfile format changed between pnpm 8 and pnpm 9; using an older version produces ERR_PNPM_LOCKFILE_BREAKING_CHANGE. Use Corepack (bundled with Node ≥ 16) to pin the right version automatically:

corepack enable
corepack prepare pnpm@9.12.0 --activate

1. Start the backend:

   cd backend
   cp .env.example .env
   pnpm install
   npx prisma migrate dev
   pnpm dev

2. Start the frontend in a second terminal:

   cd frontend
   cp .env.example .env
   pnpm install
   pnpm 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.

Makefile Targets

The root Makefile wraps the existing pnpm scripts so common tasks have one entry point. Run make (or make help) to list them:

Command	What it runs
make help	Lists all targets (default goal)
make install	pnpm check:pnpm-version then pnpm install for the whole workspace
make test	pnpm test:all (backend Jest, frontend Vitest, root script tests)
make lint	ESLint for backend and frontend
make build	pnpm build (API schemas, backend, frontend)
make format	Prettier for backend, plus cargo fmt --all when cargo is installed
make validate	Contribution, testing-strategy, triage, release-notes, NFR, CODEOWNERS, PR template and Renovate validators

The targets use GNU make and POSIX shell, so they run on Linux, macOS and Git Bash on Windows. Git Bash does not ship make; install it with choco install make, scoop install make, or winget install ezwinports.make. Set PNPM to override the pnpm binary, for example make install PNPM="corepack pnpm".

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