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

Multi-strategy

Allocate deposits across multiple strategies inside a single vault

Dynamic rebalancing

Update target weights across whitelisted strategies — manually or via an optimization engine

Compounding

Compound incentive rewards by claiming, swapping, and reinvesting into the deposit asset

Vault-level fees

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

Consistent accounting

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

Emergency controls

Vault can be paused, and allocations can be shifted toward “idle” (unallocated) assets to de-risk if needed

Slippage bounds

Reinvestment flows use slippage tolerances — adverse price moves or thin liquidity are bounded at the transaction level

Role separation

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:

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

Strategy metrics collection

Fetches and stores time-series metrics such as APY, TVL, and capacity/cap constraints where available.

On-chain allocation fetching

Reads the current strategy list, strategy share balances, and underlying value of allocations.

Decision engine (optimizer)

Computes new target weights using a selected algorithm.

Execution (optional)

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

TVL-Adjusted APY Chaser

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

Default Max-APY (Baseline)

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

Composition: setMetaAssets

Update the set of strategies (add, remove, replace).

Targeting: setWeights

Update target weights and idleWeight — takes effect on next rebalance.

Execution: rebalance / manualAllocate / manualExit

Move capital between idle and strategies to match targets, or perform explicit manual movements during strategy changes.

Fees & compounding: harvest / compoundRewards

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

1. Whitelist

   Add strategy to metaAssets[] via setMetaAssets()

2. Assign weight

   Set target weight via setWeights() (adjust other weights/idle as needed)

3. Fund

   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

1. Exit funds

   Pull capital back to idle via manualExit(strategy)

2. Remove from set

   Remove strategy from metaAssets[] via setMetaAssets()

3. Redeploy

   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

Test Deployments (Operator Hot Wallet)

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

Enterprise (Client-Controlled Multisig)

For enterprise deployments, operational control transfers to a client multisig (e.g., Safe) with a propose → sign → execute flow:

1. Propose

   System generates transactions (e.g., setWeights, rebalance) and submits them as multisig proposals

2. Review & sign

   Client reviews “what changes / why / expected effect” and signs

3. Execute

   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

Cantina Audit

0 critical, high, or medium issues found

Zellic Audit

Smart contract security assessment completed

View Report →

---

Next Steps

OAV Overview

Introduction, off-the-shelf OAVs, and API endpoints

OAV v3 (Production)

Single-strategy vault details

Fees

Fee configuration details

DeFiKit

Full DeFi integration guide