Skip to main content

YSS: Architecture

Purpose: Explain the architecture of Yield Skimming Strategies, the authoring surface, and the layers that make YSS work.

Audience: Engineers building YSS implementations, those needing to understand the tokenized-strategy pattern, and developers integrating YSS with multistrategy vaults.

Level: Intermediate

Source of truth: [email protected] TokenizedStrategy and BaseYieldSkimmingStrategy implementations.

Use this page when: You are learning the YSS architecture, designing a strategy, or comparing YSS to other strategy patterns (like YDS).

Do not use this page for: Exact code implementation steps—refer to the "Writing a YSS Strategy" guide instead; or solidity-level contract interfaces—use the smart contract reference pages.

Before you read this page
TL;DR

YSS reuses Octant v2’s tokenized-strategy architecture for yield-bearing assets that appreciate in place. A YSS is a single-strategy ERC-4626 vault. Instead of deploying assets into an external source, a YSS strategy holds an appreciating asset directly, tracks its exchange rate, and captures appreciation by minting donation shares to the donation address at report() time. For the standard YSS authoring path, inherit BaseYieldSkimmingStrategy and implement _getCurrentExchangeRate() plus decimalsOfExchangeRate().

Overview​

This page gives DeFi-native engineers a concise mental model for Yield Skimming Strategies (YSS).

The first distinction to keep clear is this:

  • a YSS strategy vault is itself an ERC-4626 deposit surface,
  • a MultistrategyVault is a separate allocator vault that can sit above one or more strategy vaults.

If you are authoring a YSS, you are normally building the first of those two layers.

What YSS keeps from the shared strategy model​

YSS still uses the same broad Octant v2 pattern:

  • an ERC-4626 strategy-vault surface,
  • shared tokenized-strategy logic for accounting, roles, and lifecycle,
  • permissionless composition under multistrategy vaults,
  • a thin strategy-specific authoring layer.

That means the strategy author does not rebuild ERC-4626 accounting or role handling from scratch.

What YSS changes​

Standard strategy pattern​

In a standard direct-deposit strategy vault, assets are typically deployed into an external yield source and profit or loss is realized by comparing total assets over time.

YSS pattern​

In YSS, the strategy vault instead:

  • holds an appreciating asset directly, such as wstETH or rETH,
  • tracks its exchange rate,
  • measures user and donation claims in value debt terms,
  • captures appreciation at report() by minting donation shares.

The practical result is different from a compounding strategy:

  • appreciation is redirected to the donation address,
  • users keep exposure to the tracked value model rather than compounding appreciation,
  • depreciation can be absorbed by donation shares if loss protection is enabled and the donation buffer is sufficient.

The YSS authoring surface​

For the common YSS path in [email protected], inherit BaseYieldSkimmingStrategy.

That base already provides:

  • no-op _deployFunds() and _freeFunds(),
  • a ready-made _harvestAndReport() based on totalAssets(),
  • the shared rate-aware reporting flow.

As a strategist, you normally implement:

  • _getCurrentExchangeRate() — return the current exchange rate used for value accounting,
  • decimalsOfExchangeRate() — declare the precision of that rate so the base can normalize it.

This is the main architectural difference from YDS, where the strategy author typically implements the deploy, free, and report hooks directly.

In return, the framework exposes two rate view functions that are useful for monitoring and testing:

  • getCurrentRateRay() — reads _getCurrentExchangeRate(), normalizes it to RAY precision using decimalsOfExchangeRate(), and returns the result. Used by BaseYieldSkimmingHealthCheck to apply rate-delta bounds at report() time.
  • getLastRateRay() — returns the normalized rate that was recorded at the last successful report(). Useful in tests to assert that the rate snapshot was updated, and in off-chain monitoring to track the previous reporting baseline.
What is RAY precision?

RAY is a fixed-point number format where 1.0 is represented as 10^27 (1,000,000,000,000,000,000,000,000,000). It originated in the MakerDAO codebase and is used in several DeFi protocols for high-precision rate calculations. YSS uses RAY internally so that tiny exchange-rate changes aren't lost to rounding.

Why strategies stay small​

YSS strategies keep only the logic that is specific to the appreciating asset. Shared mechanics live in the common implementation layer.

That gives you:

  • small strategy contracts,
  • consistent ERC-4626 behavior,
  • reusable reporting and insolvency logic,
  • cheap deployment and easier auditing of the shared pattern.

Components and layers​

  • Strategy vault: a single-asset ERC-4626 vault that holds a yield-bearing token directly and tracks value through an exchange rate.
  • Shared implementation layer: the TokenizedStrategy-based machinery that handles ERC-4626 accounting, roles, and reporting flow.
  • Optional multistrategy vault layer: a separate allocator vault that can sit above several strategy vaults and manage allocation, queues, and debt.
  • Donation address: the onchain recipient that receives donation shares when appreciation is captured.
  • Donation buffer: the live balance of donation shares available to absorb depreciation when loss protection is enabled.
  • Exchange rate: the rate used to translate the appreciating asset into the tracked value model. Internally, YSS normalizes this for accounting.
  • Value debt: the accounting layer that tracks what users and the donation address are owed in value terms.
  • Solvent mode: the normal operating mode, where value debt is fully covered and rate-based conversions apply.
  • Insolvent mode: the degraded mode entered when uncovered depreciation exhausts the available protection and the strategy can no longer preserve the normal value model.
Burn-disable flow in 1.2.0-develop.15

If burn protection is enabled, direct setEnableBurning(false) can revert with report before disabling burning while a pending dragon burn should still be accounted for. Operators should use reportAndDisableBurning() when they want to synchronize the current rate and disable burn protection atomically.

Contract-level variable name

In Solidity, the donation destination is still stored as dragonRouter for historical reasons. In docs, “donation address” is the clearer term and should be treated as canonical.

Roles​

On the strategy side, the important roles are:

  • Management — configuration and trusted operational actions,
  • Keeper — routine report() calls,
  • Emergency admin — shutdown and emergency response actions.

These are enforced by the shared strategy layer rather than reimplemented in each concrete YSS strategy.

System data flow​

Standalone strategy vault​

User -> YSS strategy vault -> appreciating asset held directly -> report() -> donation shares minted to donation address

Multistrategy composition​

User -> MultistrategyVault -> allocates capital -> YSS strategy vault(s) -> report() -> donation shares minted at strategy layer

Design invariants to internalize​

  • Passive holding, not active deployment. Standard YSS strategies hold the appreciating asset directly instead of deploying it through custom _deployFunds() logic.
  • A YSS is itself a vault. The standalone strategy is already an ERC-4626 deposit surface.
  • Rate-based accounting. The core signal is the exchange rate, not harvested reward tokens.
  • Donation happens at report. Appreciation is captured only when report() finalizes accounting.
  • Loss protection is conditional. Burning donation shares applies only when configured and when enough donation shares exist.
  • Multistrategy composition is separate. Allocation across strategies belongs to MultistrategyVault, not to the standalone YSS contract.
  • Insolvency is a mode switch, not a cosmetic edge case. Once the strategy cannot honor the normal value model, behavior changes materially.

Vault integration context​

A YSS strategy can be used directly or attached to a MultistrategyVault.

In that setup:

  • the strategy still runs its own report lifecycle,
  • the vault separately books strategy-level P&L through its own accounting flow,
  • vault operators manage allocation, queues, and debt at the vault layer.

That vault context matters, but it is a separate concern from the core YSS architecture.

Key takeaway​

Think in layers.

When you build YSS, you are usually building a strategy vault. When you need one vault above several strategies, you add a multistrategy vault. “Funding vault” is a useful umbrella phrase for the product pattern, but the concrete deployable surfaces are the strategy vault and the multistrategy vault.