Skip to main content

Introduction to Yield Donating Strategies

Purpose: Teach the core mental model and key concepts of YDS, including the donation flow, loss buffering, and how YDS differs from standard yield vaults.

Audience: Solidity developers with basic DeFi knowledge who are new to YDS and want to understand the conceptual foundation before diving into architecture or implementation.

Level: Beginner

Source of truth: Yearn V3 strategy framework and Octant YDS specification.

Use this page when: You're learning YDS for the first time; you need to explain YDS to colleagues; you want to understand the economic model before reading architecture; you need to review key concepts and lifecycle overview.

Do not use this page for: Implementation details of specific hooks; architecture and delegatecall patterns (see Architecture page); detailed lifecycle step-by-step (see Mental Model & Lifecycle); writing production-ready code.

Before you read this page
TL;DR

A Yield Donating Strategy (YDS) is a single-strategy ERC-4626 vault that routes realized profit to a configured donation address instead of to depositors. In the common direct-deposit pattern, you implement three core hooks, _deployFunds, _freeFunds, and _harvestAndReport, and the shared implementation handles donation-share minting on profit and donation-share burning on loss during report(). Users retain access to principal, but they do not receive the strategy's yield.

Yield Donating Strategies (YDS) are smart-contract vaults that accept a single ERC-20 asset and donate realized profits to a configured onchain address.

Users can deposit directly into a YDS through the standard ERC-4626 interface. That is the first architectural point to internalize: a standalone YDS is itself a deposit surface, not just an internal component hidden behind another vault.

In the most common pattern, the strategy vault deploys funds into one external yield source such as a lending market, staking system, or savings vault. When a report realizes profit, the system mints new shares to the donation address. When a report realizes a loss, the system burns donation shares first. As long as the available donation-share buffer is large enough to absorb that loss, user price per share stays unchanged. If the loss exceeds the available buffer, the residual loss is socialized across share holders and user PPS falls.

Who this is for​

This section is for Solidity developers with basic DeFi knowledge who want to build strategies that fund a beneficiary address by design. It assumes:

  • Ethereum-mainnet context
  • ERC-20 and ERC-4626 familiarity
  • Foundry workflow for development and testing

The model in one paragraph​

A YDS strategy vault is an ERC-4626 vault where realized profit becomes donation exposure instead of depositor yield. The donation address holds strategy shares that are minted on profit and, when loss buffering is enabled, burned on loss before any residual loss reaches user PPS. In 1.2.0-develop.15, the first successful deposit into an empty YDS also seeds 1_000 permanently locked shares at address(0xdead), so first-deposit tests should account for assets - 1000 user shares rather than assuming exact 1:1 minting.

That buffering is limited, not absolute. Donation shares protect users only up to the size of the currently available buffer. Once that buffer is exhausted, additional loss lowers PPS for everyone.

If your integration needs several strategies under one deposit surface, that is a separate vault-layer concern handled by MultistrategyVault or MultistrategyLockedVault, not by the standalone YDS contract itself.

Why YDS​

  • Codify philanthropic yield. Ship strategy vaults whose profits are guaranteed to fund a beneficiary address onchain.
  • Clear depositor promise. Users retain principal access while knowingly foregoing yield. Donation mechanics are visible in balances and events.
  • Simple user surface. Depositors interact through standard ERC-4626 entry points.
  • Single settlement point. Profit and loss accounting are finalized at report(), which can be automated.

How is this different from just donating money?​

When you donate money, it's gone. When you deposit into a YDS vault, your principal stays — you can withdraw it anytime. Only the yield your principal generates goes to the beneficiary. This means you can support causes continuously and indefinitely, without reducing your savings.

Key concepts​

  • Strategy vault: a single-strategy ERC-4626 contract that accepts one underlying asset and routes realized profit into a donation flow.
  • Donation address: the beneficiary account that receives donation shares on profit. In the contract layer this is often routed through the configured dragon router.
  • Donation buffer: the currently available balance of donation shares that can be burned first when a loss is reported.
  • Minimum liquidity: the 1_000 first shares permanently locked at address(0xdead) on the first successful empty-strategy deposit or mint.
  • Price per share (PPS): user share value. In YDS, profit does not increase PPS. Loss only reduces PPS when the donation buffer is insufficient.
  • Report: a trusted keeper or management action that values the position, finalizes accounting, and settles profit or loss.
  • Roles:
    • Management — trusted configuration and operational control.
    • Keeper — automation for report() calls.
    • Emergency admin — shutdown and emergency response authority.

Lifecycles at a glance​

Strategy vault lifecycle (direct deposits)​

  1. Deposit → shares. A user deposits through the ERC-4626 interface and receives strategy shares.
  2. Deploy. The strategy moves idle funds into its external yield position.
  3. Accrue. Rewards, interest, or exchange-rate gains build up in the external position. User PPS does not rise from that profit.
  4. Report → settle profit or loss. A trusted call values the position and finalizes accounting.
    • Profit: donation shares are minted to the donation address.
    • Loss: donation shares are burned first, then any residual loss reduces PPS.
  5. Withdraw. Users redeem at current PPS. After a socialized loss, they receive less underlying than before that loss.

Vault layer (optional aggregator)​

A multistrategy vault can hold several strategies and manage allocations across them. That is a vault-operator concern and is not required to author a direct-deposit YDS. See the YDS lifecycle material and the multi-strategy vault docs if your integration sits behind a vault rather than being used directly.

Responsibilities for strategy authors​

  • Accurate reporting. Your reported total assets must reflect the true value of idle and deployed assets.
  • Boring public paths. Keep deposit, mint, withdraw, and redeem flows simple and deterministic.
  • Operational readiness. No report means no donation settlement and no loss-buffer settlement. Plan keeper automation or an explicit runbook.
  • Safe burn-disable operations. If burn protection is enabled and pending dragon shares exist, management should use reportAndDisableBurning() instead of calling setEnableBurning(false) directly.
  • Clear event surfaces. Downstream analytics and UIs rely on donation mint, burn, and routing events.

Three core hooks, plus important optional overrides​

At the BaseStrategy layer, the core strategy hooks are:

  • _deployFunds
  • _freeFunds
  • _harvestAndReport

Those three hooks define the heart of a YDS integration. Depending on your external protocol, you may also need optional overrides such as deposit limits, withdraw limits, emergency withdrawal behavior, or tending logic. The strategy model is simple, but not every integration is identical.

What users should expect​

  • No depositor APY from strategy profit. YDS shares are principal-tracking by design.
  • Transparent loss handling. Donation shares absorb loss first only up to the size of the available buffer.
  • Withdrawals at current PPS. Users can exit through the standard ERC-4626 interface, subject to the latest settled accounting.