Skip to main content

Core Concepts

Purpose: Build a mental model of how Octant vaults and yield-routing work across three conceptual tiers. Audience: Developers who are new to Octant v2 but comfortable with ERC-4626 and Solidity. Level: Beginner | Intermediate Source of truth: Octant v2 core protocol architecture and strategy patterns. Use this page when: You want to understand how vaults, strategies, and allocation mechanisms fit together, or you're deciding which primitives to use for your implementation. Do not use this page for: Implementation step-by-step guides, smart contract API reference, or specific deployment instructions (see the building sections for those).

Before you read this page

Octant v2 is infrastructure for routing DeFi yield to on-chain funding. Users deposit assets, the system generates yield through configurable strategies, and 100 % of that yield is directed to a beneficiary address instead of being retained by depositors. This page builds the mental model in three layers: start with the deployable primitives, then add the distribution layer, then the advanced mechanisms.

New here?

Read the three tiers in order. If you want to start building immediately, jump to the Developer Orientation for a guided learning track.

Tier 1 — The essentials​

These three ideas form the foundation. Everything else builds on them.

Deployable primitives​

The first thing to get straight is what you actually deploy.

Strategy vaults​

A strategy vault is a single-asset ERC-4626 contract built on Octant’s strategy framework. It is a direct deposit surface: users can deposit into it, receive shares, and withdraw through the standard ERC-4626 interface.

In Octant v2, a strategy vault is usually a contract derived from BaseStrategy. The strategist implements the strategy-specific hook surface, and the shared TokenizedStrategy implementation provides the standardized ERC-4626 mechanics, accounting, access control, and donation-share settlement.

There are two main strategy-vault families:

  • Yield Donating Strategy vault (YDS) — for standard tokens such as DAI or USDC. The vault deploys assets into an external yield source and, on report(), mints profit as strategy shares to the donation address.
  • Yield Skimming Strategy vault (YSS) — for appreciating assets such as wstETH or rETH. The vault holds the appreciating asset directly and, on report(), captures exchange-rate appreciation for the donation address.

→ Deep dives: Yield Donating Strategy section, Yield Skimming Strategy section → Smart contract references: BaseStrategy, TokenizedStrategy

Multistrategy vaults​

A multistrategy vault is a separate ERC-4626 vault layer that allocates one underlying asset across several attached strategy vaults. It manages debt allocation, withdrawal queues, reporting intake, and rebalancing. This is the deployable primitive you use when you want one vault to sit above several strategies.

Use a multistrategy vault when capital allocation across several strategies is part of the product. Use a strategy vault directly when you only need one strategy and one deposit surface.

→ Smart contract references: MultistrategyVault, MultistrategyLockedVault

Funding vaults (umbrella term)​

What is a funding vault?

Funding vault is not a class you can import. It is a conceptual umbrella term for Octant's vault-based funding setups. In practice, you deploy either a strategy vault (single yield source) or a multistrategy vault (multiple yield sources under one deposit surface).

Funding vault is a conceptual umbrella term in Octant docs, not the name of one concrete contract class. It refers to vault-based funding setups that route yield or appreciation to a donation address.

In practice, a funding-vault setup is implemented in one of two ways:

  • a standalone strategy vault used as the direct ERC-4626 deposit surface, or
  • a multistrategy vault that sits above one or more strategy vaults.

When you are coding, prefer the concrete contract names, such as BaseStrategy, MultistrategyVault, or MultistrategyLockedVault. Use “funding vault” only when you mean the broader product pattern.

The report() loop​

The donation model works through a periodic report cycle:

  1. A keeper or management calls report() on the strategy vault.
  2. The strategy calls its reporting hook to measure the current position value.
  3. The framework compares the current value to the previous report snapshot.
  4. If value increased, new strategy shares are minted to the donation address.
  5. If value decreased, and burning is enabled, shares are burned from the donation address first up to the available balance. Any residual loss still reduces price per share for holders.

This mint-on-profit and burn-on-loss pattern is how Octant routes yield on-chain without moving a separate profit token between contracts.

The following diagram illustrates the report() cycle:

→ Lifecycle details: YDS Mental Model & Lifecycle

What do I actually deploy?​

Use this rule of thumb:

  • One asset, one strategy, one deposit surface → deploy a strategy vault.
  • One asset, several strategies, operator-managed allocation → deploy a MultistrategyVault or MultistrategyLockedVault.
  • One donated yield stream, several downstream recipients → route the donation address to a PaymentSplitter.

Tier 2 — The distribution layer​

Once yield reaches the donation address, it still needs to be routed to its final recipients. These contracts handle that.

Payment Splitter​

The Payment Splitter is the most common donation-address configuration. It receives strategy shares and distributes them proportionally to multiple predefined recipients — allocation mechanism contracts, community staking contracts, operational cost addresses, and any other on-chain recipients.

Distribution uses a pull payment model: payees must actively claim their allocated share. This gives Octant a simple routing layer between yield generation and the final recipients, and lets recipients claim on their own schedule.

→ Practical guide: Payment Splitter Patterns → Smart contract reference: PaymentSplitter

Allocation Mechanisms (TAM)​

Tokenized Allocation Mechanisms (TAM) are contracts that receive yield shares and distribute them according to community decisions — token-weighted voting, quadratic funding, or custom governance logic.

A TAM is built on the same delegatecall proxy pattern as strategies. You implement a set of hooks, and the shared TokenizedAllocationMechanism implementation handles proposal submission, voting, and round lifecycle.

→ Deep dive: Tokenized Allocation Mechanisms section → Smart contract references: BaseAllocationMechanism, TokenizedAllocationMechanism

Contribution models​

There are two ways a capital provider can fund initiatives through Octant:

  • Vault-based funding (Regenerative Funding Contribution) — assets are deposited into a strategy vault or a multistrategy vault. Yield flows on-chain automatically when strategies report.
  • Allowance-based funding (Direct Funding Contribution) — funds stay in the user's Safe wallet. A Safe Linear Allowance module authorizes Octant to withdraw pre-set amounts on a schedule. No DeFi exposure is required.

Tier 3 — Advanced mechanisms​

Skip for now?

If you're focused on building your first strategy, you can skip Tier 3 and come back later. Everything you need is in Tiers 1 and 2.

These mechanisms add governance, safety, and institutional features on top of the core model. You do not need to understand them to build a strategy, but they become relevant when integrating with existing Octant deployments or building vault-operator tooling.

Community Staking (RegenStaker)​

Capital providers can stream a portion of generated yield into a Community Staking contract. Community members stake an ecosystem token and, in return, participate in allocation decisions and earn rewards, which they can donate to projects or withdraw.

→ Smart contract references: RegenStaker, RegenStakerBase, RegenEarningPowerCalculator

Safe-integrated vaults​

Legacy term

Older documentation and some contract-level names call these "Dragon" Vaults. Prefer the contract names (MultistrategyVault, MultistrategyLockedVault) in current developer docs.

Safe-integrated vaults add treasury-oriented control and exit mechanics on top of the standard multistrategy vault model. In practice, the main distinction is between the plain vault and the locked variant:

  • MultistrategyVault is the standard multi-strategy ERC-4626 vault. It handles deposits, withdrawals, debt allocation, and strategy queues, but it does not add a custody-based exit flow.
  • MultistrategyLockedVault adds a custody-based rage quit flow. A user explicitly locks a chosen number of shares by calling initiateRageQuit(shares). Those shares become non-transferable during the cooldown. After the cooldown expires, the user can withdraw or redeem up to the remaining custodied amount, including through partial withdrawals, until that custody entry is exhausted.
  • The vault-level two-step governance protection applies to the rage-quit cooldown period, not to donation-address or strategy-queue snapshots. If governance proposes a new rageQuitCooldownPeriod, users who initiate rage quit before finalization keep the old cooldown for that custody entry. Users who initiate after finalization use the new cooldown.
  • Donation address changes live at the strategy layer. TokenizedStrategy uses a separate two-step flow, setDragonRouter followed by finalizeDragonRouterChange, to change the donation address (dragonRouter) after a cooldown.

→ Smart contract references: MultistrategyVault, MultistrategyLockedVault, TokenizedStrategy

Burning mechanism​

When the enableBurning flag is set to true during strategy deployment, the strategy will burn donation shares as the first line of defense against losses. This reduces total supply instead of leaving shares with the donation address. The choice between burning and holding depends on the downstream accounting and tax treatment required by the capital provider.

Health checks​

Both BaseHealthCheck (for YDS) and BaseYieldSkimmingHealthCheck (for YSS) let you configure profit and loss bounds that cause report() to revert if the measured delta is out of range. This prevents faulty oracle data or unexpected protocol behavior from being recorded as valid profit or loss.