> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# OAV v4 — Meta Vaults
> Multi-strategy Optimized Allocator Vaults with dynamic rebalancing and offchain optimization
## Overview
**Meta Vaults** are non-custodial, **ERC-4626 compliant allocator vaults** that let users deposit a single asset (e.g., USDC) and receive a share token representing a proportional claim on a **diversified portfolio of underlying yield strategies** spanning multiple DeFi protocols.
On-chain, the vault holds **"meta-assets"** (strategy vault shares) and values the portfolio by converting each strategy position back into underlying assets to produce a single share price.
***
## What Meta Vaults Can Do
Allocate deposits across multiple strategies inside a single vault
Update target weights across whitelisted strategies — manually or via an optimization engine
Compound incentive rewards by claiming, swapping, and reinvesting into the deposit asset
Deposit, management, and performance fees enforced on-chain via share minting
### Core Capabilities
* Allocate deposits across multiple strategies inside a single vault (multi-protocol portfolio)
* Update the strategy set over time (add, remove, replace strategies as the opportunity set changes)
* Update target weights across whitelisted strategies, either manually or via an optimization engine
### Automation (optional)
* Monitor strategy signals (APY, TVL, and optional capacity/cap constraints) and compute new target weights using a pluggable optimizer
* Optionally execute weight updates and rebalances on-chain under guardrails
### Compounding & Fees
* Compound incentive rewards by claiming reward tokens, swapping them into the deposit asset, and reinvesting (via the reinvestment pipeline)
* Apply vault-level fees (deposit, management, performance) enforced on-chain via vault share minting
***
## Two-Layer System Design
Meta Vaults are explicitly designed as a two-layer system:
| Layer | Responsibility |
| ------------- | ------------------------------------------------------------------------------------------------------- |
| **On-chain** | Custody, accounting, and permissions enforcement |
| **Off-chain** | Strategy monitoring, weight computation, and optional transaction execution for allocation optimization |
This split keeps smart contracts minimal and auditable while allowing optimization logic to evolve quickly without contract upgrades.
***
## Key Security Considerations
Standard ERC-4626 share-based accounting with a single `totalAssets()` view over all strategies — user balances are always defined by one consistent price-per-share
Vault can be paused, and allocations can be shifted toward "idle" (unallocated) assets to de-risk if needed
Reinvestment flows use slippage tolerances — adverse price moves or thin liquidity are bounded at the transaction level
Admin, pauser, configurator, strategist, harvester, and rebalancer roles are split, so no single operator needs broad powers
***
## Architecture
A Meta Vault deployment consists of:
* **Meta Vault Core contract** (ERC-4626 vault)
* **Reinvester** (compounding module)
* **Swapper** (swap execution adapter)
* **Off-chain optimization cron + database audit trail**
### High-Level Flow
1. Users interact only with the **Meta Vault Core** via ERC-4626 methods
2. The vault allocates capital into **whitelisted strategy vaults (metaAssets)** according to **weights + idleWeight**
3. The off-chain layer continuously:
* Ingests strategy metrics + reads on-chain allocations
* Runs an optimizer
* Writes an auditable decision snapshot
* (Optionally) executes `setWeights()` + `rebalance()`
4. Compounding is performed by `compoundRewards()`, which triggers the **Reinvester + Swapper** pipeline
***
## On-Chain Components
### Meta Vault Core Contract
The Meta Vault Core contract is the single user entrypoint and accounting layer. It:
* Exposes ERC-4626 interface: `deposit`, `mint`, `withdraw`, `redeem`
* Holds a portfolio of whitelisted strategies: `metaAssets[]`
* Maintains portfolio targets:
* `weights[]` (per-strategy target weights)
* `idleWeight` (target portion of assets held idle in the vault)
**Privileged functions for vault operations:**
| Function | Purpose |
| ------------------------------- | ---------------------------- |
| `setMetaAssets` | Change strategy set |
| `setWeights` | Update target weights |
| `rebalance` | Move funds to targets |
| `manualAllocate` / `manualExit` | Manual portfolio actions |
| `harvest` | Fee realization |
| `compoundRewards` | Trigger compounding pipeline |
The Meta Vault can interact with yield opportunities that follow ERC-4626. To support non-ERC-4626 opportunities, Yield.xyz deploys wrappers/adapters so the Meta Vault still interacts through a uniform ERC-4626 surface.
### Portfolio Valuation & Share Price
The vault's share price is driven by `totalAssets()`, which aggregates:
* **Idle funds** held directly by the vault (e.g., USDC)
* **Redeemable underlying value** of each strategy position (valued using strategy share-to-asset conversion, via `previewRedeem()` / `convertToAssets()` patterns)
This is the core mechanism that makes a single ERC-4626 share represent an aggregate multi-strategy portfolio.
**What makes share price move:**
* **Strategy yield**: interest, fees, and emissions accrued in the underlying strategy positions
* **Incentives compounding**: rewards claimed, swapped back into the underlying asset, and returned to the vault
Compounding increases the vault's idle underlying immediately. Allocation does not automatically change — the new idle assets are deployed after `rebalance()` is executed.
### Rebalancing Logic
`rebalance()` is a portfolio-level action gated by `REBALANCER_ROLE` used to bring allocations in line with weights. For each strategy *i*, it computes:
```text theme={null}
targetAssets = totalAssets * weight[i] / 10_000
```
Compares target vs current value and processes reallocations:
* **Over-allocated**: withdraw excess
* **Under-allocated**: deposit from idle and/or from funds withdrawn from other strategies
**Idle allocation** serves as:
* A risk-off buffer
* A holding zone when caps are hit
* A transition buffer during strategy changes
* A response path when an underlying strategy is paused or unavailable
### Fee Model (on-chain)
Fees are configured via a `FeeConfig`:
| Parameter | Description |
| ---------------- | ----------------------------------- |
| `depositFee` | One-time fee at entry |
| `managementFee` | Annualized fee on AUM |
| `performanceFee` | Fee on realized profits |
| `feeRecipient` | Address receiving minted fee shares |
Fees are applied by **minting new Meta Vault shares**:
* **Deposit fee**: on user deposit, fee shares are minted to `feeRecipient`, and net shares to the user
* **Management + performance fees**: realized through `harvest()`, based on elapsed time since last checkpoint and growth in share value since last checkpoint
### Reinvester
The Reinvester keeps the Meta Vault Core minimal while enabling flexible compounding. Deployed for a specific Meta Vault and Swapper, it performs:
* Execute allowlisted reward claims
* Swap reward tokens → deposit asset
* Transfer deposit asset back to the Meta Vault
Only the specific Meta Vault can call `reinvest()`.
### Swapper
A lightweight swap execution adapter used by the Reinvester. In the current iteration it executes swaps through Uniswap Universal Router (Base) and can be extended to other DEX/aggregation methods.
* Output tokens end up with the caller (e.g., Reinvester)
* Swapper measures `tokenOut` balance before/after, transfers `tokenIn` to the router, and returns the delta as `amountOut`
***
## Off-Chain Components
The off-chain layer turns the vault into an actively managed allocator by:
* Continuously observing strategy performance and current allocation
* Producing target weights using a pluggable algorithm
* Optionally executing changes on-chain under guardrails
### Automation Cron Responsibilities
Fetches and stores time-series metrics such as APY, TVL, and capacity/cap constraints where available.
Reads the current strategy list, strategy share balances, and underlying value of allocations.
Computes new target weights using a selected algorithm.
Records an auditable snapshot and, when enabled, submits on-chain transactions to update weights and call `rebalance()`.
### Execution Modes (configurable per client)
| Mode | Behavior |
| ------------------ | -------------------------- |
| **Metrics-only** | Collect data |
| **Decide-only** | Compute + record decisions |
| **Live execution** | Also submit transactions |
Execution is optional — clients can hardcode weights and manually update without any algorithm.
### Cron Phases
Each run has 3 phases:
1. **Collect data** — strategy metrics + on-chain state
2. **Compute decision** — target weights + whether to rebalance
3. **Store output + optionally execute** — write snapshot; send txs if enabled
### Optimizer Interface
Each algorithm implements:
**Inputs:**
* Meta Vault config (network, input token, whitelisted strategies / yieldIds)
* Current allocations (addresses, current weights, current value)
* Strategy metrics (APY, TVL, etc.)
**Outputs:**
* `shouldRebalance` (boolean)
* `reason` (human-readable)
* `newAllocations[]` (target weights)
* `algorithmVersion` (e.g., `tvl-adjusted-apy-chaser`)
* `algorithmParams` (snapshot of parameters)
### Supported Algorithms
**Goal**: Maximize APY while penalizing concentration into low-TVL strategies (proxy for capacity, slippage, diminishing returns).
**Steps:**
1. Build inputs: APY per strategy (missing → 0), TVL per strategy (missing/0 → heavy penalty), current allocation values
2. Apply TVL-based penalty coefficient
3. Solve for weights via gradient search (starts from equal weights; runs gradient ascent loop optimizing APY objective with TVL penalty)
4. Convert final weights into bps
Allocates 100% to the strategy with the highest valid APY and 0% to others. Useful for sanity checks, early testing, or explicitly all-in policy.
### Guardrails
**Drift threshold (primary enforced guardrail):** The system rebalances only when drift exceeds a configured threshold — to avoid churn and unnecessary gas spend.
**Additional guardrails (designed for future expansion):**
* Max move size
* Allocation caps from strategy metrics
* Manual approval thresholds
* Risk score changes
**On-chain constraints:** If automated execution is enabled, the wallet with `REBALANCER_ROLE` can only change weights and trigger `rebalance()` — funds can move only between already whitelisted strategies.
***
## Vault Mechanics
Meta Vaults behave like a single ERC-4626 vault externally, while internally managing a portfolio of strategy vault positions. Users deposit one underlying token (e.g., USDC) and receive a single share token; the vault deploys and manages capital across strategies according to target allocation settings.
### What a Meta Vault Maintains
| Component | Description |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **Idle funds** | Underlying deposit asset held directly by the vault, governed by `idleWeight` |
| **Deployed funds** | Assets deposited into whitelisted strategy vaults (`metaAssets[]`), held as strategy shares |
| **Targets** | `weights[]` per strategy + `idleWeight` define the desired portfolio shape |
### User Entrypoints
Users interact via standard ERC-4626 methods:
* `deposit`, `mint`, `withdraw`, `redeem`
From the user's perspective:
* There is one deposit asset (e.g., USDC)
* There is one share token
* Share price increases as the portfolio earns yield and rewards are compounded
### Operator Entrypoints
Update the set of strategies (add, remove, replace).
Update target weights and idleWeight — takes effect on next rebalance.
Move capital between idle and strategies to match targets, or perform explicit manual movements during strategy changes.
Realize management/performance fees (shares minted to feeRecipient) and trigger incentive reward compounding via the reinvest pipeline.
**Compounding does not auto-allocate.** When `compoundRewards()` executes, underlying assets increase inside the vault but remain idle until `rebalance()` is triggered to redeploy them according to target weights. This is intentional — it keeps compounding modular and makes allocation movement an explicit portfolio action.
***
## Allocation, Weights & Rebalancing
Meta Vaults separate **portfolio intent** (target allocations) from **portfolio enforcement** (moving capital). Targets are defined by weights; enforcement happens through `rebalance()`.
### The Target Allocation Model
* `metaAssets[]`: whitelisted strategy vaults
* `weights[]`: target weights per strategy (bps)
* `idleWeight`: target underlying held idle (bps)
**Example:** If `idleWeight` = 500 (5%), the vault targets \~5% idle and \~95% deployed across strategies according to `weights[]`.
### Updating Targets: `setWeights()`
`setWeights()` updates the vault's target state. **It does not move funds by itself.** Weights may be set:
* Manually by an operator
* Automatically from the optimizer's output (off-chain)
### Enforcing Targets: `rebalance()`
`rebalance()` is the canonical on-chain mechanism to align real allocations with targets:
1. Computes the vault's current `totalAssets()`
2. Converts each strategy position into underlying value
3. Compares current vs target per strategy and idle
4. Withdraws from over-allocated strategies into idle
5. Deposits from idle into under-allocated strategies
This is the step that actually shifts capital after:
* A weight update
* A strategy add/remove/replace
* A compounding event that increases idle
* A manual exit to idle
***
## Strategy Lifecycle
Meta Vaults are designed to evolve: strategies can be introduced, removed, or replaced as market conditions change. The lifecycle is safe because it separates composition changes from capital movement.
**Roles involved:**
* `STRATEGIST_ROLE` controls the allowed strategy set via `setMetaAssets()`
* `REBALANCER_ROLE` controls capital movement and targets via `manualExit()`, `setWeights()`, and `rebalance()`
### Add a Strategy
Add strategy to `metaAssets[]` via `setMetaAssets()`
Set target weight via `setWeights()` (adjust other weights/idle as needed)
Call `rebalance()` to deploy capital into the new strategy
A strategy can exist in the allowed set with a zero allocation — that's expected and often useful during rollout.
### Remove a Strategy
Pull capital back to idle via `manualExit(strategy)`
Remove strategy from `metaAssets[]` via `setMetaAssets()`
Update targets and redeploy using `setWeights()` + `rebalance()`
The contracts include checks that prevent removing strategies that still have meaningful (non-dust) balances.
### Replace a Strategy
The recommended pattern:
1. `manualExit(oldStrategy)` → pull capital to idle
2. `setMetaAssets` (remove old, add new)
3. `setWeights` (new targets including replacement)
4. `rebalance()` → deploy into the replacement and realign the portfolio
This sequence is easy to review in a signer workflow and produces a clean audit trail.
***
## Roles & Signing Models
Meta Vaults gate privileged functionality with roles:
| Role | Capabilities |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **DEFAULT\_ADMIN\_ROLE** | Manages AccessControl itself (grant/revoke roles). Typically client multisig/governance |
| **PAUSER\_ROLE** | Toggle global `paused` flag via `setPaused` — gates deposits/withdrawals for emergencies |
| **CONFIGURATOR\_ROLE** | Set economic parameters via `configureVault` (fees + fee recipient), wire reinvestment pipeline via `setReinvester` |
| **STRATEGIST\_ROLE** | Manage whitelisted strategies (`setMetaAssets`), with checks preventing removal of funded strategies |
| **REBALANCER\_ROLE** | Allocation operations: `setWeights`, `rebalance`, `manualExit`, `manualAllocate` |
| **HARVESTER\_ROLE** | Fee realization via `harvest` and incentive compounding via `compoundRewards` |
End users never need a role — they interact only with standard ERC-4626 functions (`deposit`, `mint`, `withdraw`, `redeem`).
### Signing & Execution Models
Execution automated via a dedicated operator EOA wallet holding only the required operating role(s) — commonly `REBALANCER_ROLE` (and optionally `HARVESTER_ROLE`).
**Security boundary:**
* Operator wallet does **not** hold admin authority — cannot grant/revoke roles or take over governance
* Actions are bound by on-chain rules: rebalancing only moves within the vault (idle ↔ whitelisted strategies), strategy removal blocked if balance remains, and compounding constrained by allowlists + slippage checks
For enterprise deployments, operational control transfers to a client multisig (e.g., Safe) with a **propose → sign → execute** flow:
System generates transactions (e.g., `setWeights`, `rebalance`) and submits them as multisig proposals
Client reviews "what changes / why / expected effect" and signs
Once threshold met, transaction executes on-chain
Supports co-signing or client-only signing depending on client requirements.
***
## v3 vs v4 Comparison
| Feature | OAV v3 | OAV v4 (Meta Vaults) |
| ---------------------- | --------------- | --------------------------------- |
| Strategies | Single | **Multiple** |
| Rebalancing | Not applicable | **Dynamic allocation** |
| Role system | Basic | **Granular (6 roles)** |
| Off-chain optimization | Not applicable | **Pluggable algorithms** |
| Compounding | Auto-offramping | **Reinvester + Swapper pipeline** |
| Status | Production | **Production** |
***
## Audit Status
0 critical, high, or medium issues found
Smart contract security assessment completed
[View Report →](https://github.com/Zellic/publications/blob/master/StakeKit%20-%20Zellic%20Audit%20Report.pdf)
***
## Next Steps
Introduction, off-the-shelf OAVs, and API endpoints
Single-strategy vault details
Fee configuration details
Full DeFi integration guide