Last Updated: 2026-05-29
A shared reference for technical and product terminology used across the YieldVault-RWA codebase, specifications, and documentation. Terms are grouped by domain — covering core vault concepts (shares, APY, strategies) as well as supporting systems (rate limiting, logging, accessibility, CI/CD). Individual specs may define additional context-specific terms in their own ## Glossary sections.
Identifier convention: Terms that map directly to a code symbol or config key include a parenthesised identifier, e.g. (Share_Price). General domain terms do not.
- Vault & Shares
- APY & Yield
- Strategies
- Real-World Assets (RWA)
- Smart Contracts & On-Chain
- Frontend & UI
- API & Backend
- Rate Limiting
- CI/CD & Infrastructure
- Logging & Observability
- Accessibility
Vault The core smart contract that accepts user deposits, issues shares, and allocates capital to yield-generating strategies. Deployed as a Soroban contract on the Stellar network.
Share
A tokenized unit of ownership in the Vault. Shares are issued to depositors proportional to their contribution relative to total vault assets at the time of deposit. Also referred to as yvUSDC shares.
Share Price (Share_Price)
The current redemption value of one yvUSDC share expressed in USDC. Computed on-chain as (total_assets × 10¹⁸) / total_shares and returned by the get_share_price contract function as an i128 scaled by 10¹⁸. See also: Fixed_Point_Divisor.
Total Assets The sum of all USDC held directly by the Vault plus the value of all assets currently deployed into active strategies.
Total Shares The total supply of yvUSDC shares currently in circulation across all depositors.
TVL (Total Value Locked) The aggregate dollar value of all assets deposited in the Vault, including capital deployed to strategies. A standard DeFi metric used on the dashboard and in analytics.
Fixed Point Divisor (Fixed_Point_Divisor)
The constant 1_000_000_000_000_000_000 (10¹⁸) used to convert the raw i128 contract return value for Share Price into a human-readable decimal number.
Deposit The action of a user transferring USDC into the Vault in exchange for newly minted yvUSDC shares at the current Share Price.
Withdrawal / Redemption The action of a user burning yvUSDC shares in exchange for the equivalent USDC value at the current Share Price.
Slippage The difference between the expected Share Price at the time a deposit or withdrawal is initiated and the actual price at execution. May occur due to concurrent transactions or strategy rebalancing.
Stale Price (Stale_Price)
A Share Price value fetched during a previous polling cycle that has not yet been replaced by a newer value. Displayed to the user when a live fetch is in progress or has failed.
APY (Annual Percentage Yield) The annualised rate of return on assets deposited into the Vault, accounting for compounding. Expressed as a percentage. Calculated from the rate of change in Share Price over time.
APR (Annual Percentage Rate) The annualised rate of return without accounting for compounding. APR represents the simple interest rate, while APY includes the effect of reinvested yield. APY ≥ APR when compounding occurs.
Net APY The effective APY returned to depositors after deducting all protocol fees (Management Fee, Performance Fee) and strategy costs from gross yield.
Gross Yield The total yield generated by all active strategies before any fee deductions.
Yield Source The underlying mechanism or asset class through which a strategy generates returns (e.g. lending interest, tokenised T-Bill coupons, RWA income streams).
Management Fee A recurring fee (expressed as an annualised percentage of Total Assets) charged by the protocol for operating the Vault infrastructure. Deducted before computing Net APY.
Performance Fee A fee charged as a percentage of the yield generated (not of principal). Applied only to positive returns before computing Net APY.
Strategy A smart contract or off-chain allocation module that deploys Vault capital into a specific yield source. The Vault may run multiple strategies simultaneously with configurable allocation weights.
Strategy Allocation The proportion of total Vault assets assigned to a given Strategy. Expressed as a percentage of Total Assets.
Active Strategy A Strategy currently receiving capital from the Vault and generating yield.
Harvest The process of collecting accrued yield from a Strategy and returning it to the Vault, increasing Total Assets and therefore Share Price.
Rebalancing The process of adjusting Strategy Allocations — moving capital between strategies to match target weights, respond to market conditions, or decommission underperforming strategies. Triggered by the Strategy Manager.
Strategy Manager The privileged role or contract responsible for adding, removing, and rebalancing Strategies within the Vault.
RWA (Real-World Asset) A financial asset that exists off-chain (e.g. treasury bills, bonds, real estate receivables) whose economic exposure is brought on-chain through tokenisation.
Tokenised T-Bill A blockchain representation of a short-term US government treasury bill used as a yield source within RWA strategies.
Underlying Asset The real-world financial instrument backing an on-chain RWA token.
Custodian A regulated entity responsible for holding the off-chain underlying assets that back RWA tokens issued on-chain.
Soroban The smart contract platform on the Stellar network. YieldVault contracts are compiled to WASM and execute in the Soroban runtime.
Contract ID (Contract_ID)
The unique Soroban contract address returned after deployment via stellar contract deploy. Configured via networkConfig.contractId in the frontend.
Soroban RPC (Soroban_RPC)
The Stellar Soroban RPC endpoint used to invoke contract functions. Configured via VITE_SOROBAN_RPC_URL in frontend/src/config/network.ts.
WASM WebAssembly binary format to which Soroban smart contracts are compiled before deployment.
Stellar CLI (Stellar_CLI)
The stellar command-line tool (formerly soroban) used to build, deploy, and invoke contracts on Stellar networks.
Token Contract (Token_Contract)
A Stellar testnet token contract (e.g. a deployed SAC or test token) used as the deposit asset during testing.
Deployer Account (Deployer_Account)
A Stellar account whose secret key is stored as the TESTNET_SECRET_KEY GitHub Actions secret, used to sign testnet deployments.
VaultContext
The React context (frontend/src/context/VaultContext.tsx) that provides vault state — including Share Price and balances — to dashboard components.
useSharePrice
A React hook that encapsulates Share Price fetching, 30-second polling logic, and error handling. Exposes sharePrice, isLoading, isRefetching, error, lastUpdated, and forceRefresh.
Share Price Display (Share_Price_Display)
The UI widget on the dashboard that shows the current Share Price and its live-update status.
Polling Cycle (Polling_Cycle)
A single scheduled invocation of the Share Price fetcher triggered by the 30-second interval timer.
Last Updated Timestamp (Last_Updated_Timestamp)
The wall-clock time at which the most recent successful Share Price fetch completed.
Loading Indicator (Loading_Indicator)
A visual element (spinner or animated icon) shown inside the Share Price Display while a Polling Cycle is in progress.
Error State (Error_State)
The UI condition in which the most recent Polling Cycle failed and no valid Share Price is currently available.
Tooltip
A short, non-interactive floating label that appears on hover or keyboard focus to surface contextual definitions of financial terms. Implemented with role="tooltip" and aria-describedby.
Popover
An interactive floating panel triggered by a button click. Remains open until explicitly dismissed. Used for rich help content including formatted text and links. Implemented with role="dialog" or role="region".
Trigger The interactive element (button or focusable element) that opens a Tooltip or Popover.
Floating Panel (Floating_Panel)
The positioned overlay element containing Tooltip or Popover content.
Help Hint (Help_Hint)
Any UI element that uses a Tooltip or Popover to surface contextual financial guidance to the user.
Inline Definition (Inline_Definition)
A Tooltip applied to a financial term or label to provide a short contextual definition without navigating away from the page.
Wallet Address (Wallet_Address)
A Stellar public key (G… address) supplied by the client. Used as the primary key for rate limiting and user identification.
Horizon API The Stellar Horizon REST API used for querying account balances, transaction history, and network state.
Rate Limiter (Rate_Limiter)
The middleware component responsible for counting requests per key and enforcing per-endpoint limits.
Redis Store (Redis_Store)
The Redis-backed persistence layer used by the Rate Limiter to store request counters and window expiry times across server restarts and multiple backend instances.
Window The fixed time interval (in milliseconds) over which requests are counted before the counter resets.
Limit
The maximum number of requests allowed per Wallet_Address (or fallback key) within a Window.
Retry After (Retry_After)
The number of seconds the client must wait before making another request, returned in the HTTP Retry-After response header when a limit is exceeded.
Endpoint Config (Endpoint_Config)
A per-route configuration object specifying the Limit and Window for a given API path.
Fallback Key (Fallback_Key)
The value used as the rate-limit key when no Wallet_Address is present in the request — either the client IP address or the string "unknown".
CI Pipeline (CI_Pipeline)
The GitHub Actions workflow triggered on push to main that builds, tests, and deploys the vault contract.
WASM Build Job (WASM_Build_Job)
The existing wasm-build job in .github/workflows/rust-wasm.yml that compiles Soroban contracts and produces the wasm-artifacts artifact.
Testnet Deploy Job (Testnet_Deploy_Job)
The GitHub Actions job that deploys the compiled vault contract to Stellar testnet and runs smoke tests.
Smoke Test (Smoke_Test)
A minimal end-to-end test that calls deposit and then balance on the deployed contract to verify basic liveness after a testnet deployment.
Deployment Artifact (Deployment_Artifact)
A JSON file containing the Contract_ID and the Git SHA of the deployment, uploaded as a GitHub Actions artifact for traceability.
Logger The off-chain logging utility responsible for emitting structured JSON log entries from the frontend and deployment scripts.
Log Entry (Log_Entry)
A single structured JSON object emitted by the Logger. Every entry includes timestamp (ISO 8601), level, correlation_id, message, and module.
Correlation ID (Correlation_ID)
A unique UUID v4 identifier attached to a request at its origin and propagated through all log entries related to that request, enabling end-to-end tracing.
Log Level (Log_Level)
A severity classification for a Log Entry — one of debug, info, warn, or error.
Log Field (Log_Field)
A named key-value pair included in a Log Entry.
Context The set of Log Fields associated with a specific request scope.
Request Any outbound call from the frontend or scripts to an external service (Soroban RPC, Horizon API, or deployment endpoints).
ARIA Accessible Rich Internet Applications — a set of HTML attributes that make web content more accessible to assistive technologies.
Focus Trap (Focus_Trap)
A keyboard navigation constraint that keeps focus within an open Popover, preventing users from accidentally leaving the panel without explicitly dismissing it.
Escape Dismissal (Escape_Dismissal)
The behaviour of closing a Tooltip or Popover when the user presses the Escape key.
Placement
The preferred side and alignment of a Floating Panel relative to its Trigger (e.g. top, bottom, left, right, with optional start/end alignment).
Flip Automatic repositioning of a Floating Panel to an alternative Placement when the preferred Placement would cause the panel to overflow the viewport.
This glossary is the authoritative cross-cutting reference. Per-spec glossaries in .kiro/specs/*/requirements.md define additional terms scoped to their feature context.