> ## 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.

# Architecture

> How a Meta Vault deployment fits together: the vault contract, its compounding pipeline, and the off-chain allocation optimizer.

A Meta Vault deployment has three parts: the vault contract itself, a compounding pipeline for incentive rewards, and an off-chain service that can compute and apply target weight changes.

## The vault contract

The vault contract is the single user entrypoint. It exposes the standard ERC-4626 methods (`deposit`, `mint`, `withdraw`, `redeem`) and holds its own state for the strategy portfolio:

| State | What it holds |
| - | - |
| Strategy set | The whitelisted strategies the vault can hold, each itself an ERC-4626 vault |
| Weights | A target weight per strategy, in basis points |
| Idle weight | The target share of the portfolio held as idle underlying rather than deployed |

Privileged, role-gated functions change this state or move capital against it: changing the strategy set, updating weights, triggering a portfolio-wide rebalance, moving a specific amount into or out of one strategy, realizing fees, and compounding rewards. [Roles & signing models](/documentation/platform/vaults/meta-vaults/vault-mechanics/roles-signing-models) covers which role gates which function.

<Info>
  A strategy in the set can be a non-ERC-4626 yield source wrapped in a minimal ERC-4626 adapter, the same wrapper pattern OAVs use for protocols like Aave. The vault always sees a uniform ERC-4626 interface.
</Info>

## Valuation

The vault's `totalAssets()` aggregates idle underlying held directly by the vault plus the redeemable value of every strategy position, converting each strategy's shares back to underlying through that strategy's own ERC-4626 conversion functions. One share price then represents a claim on the whole portfolio. See [Accounting & share price](/documentation/platform/vaults/meta-vaults/vault-mechanics/accounting-share-price) for the fee and checkpoint model built on top of this.

## Compounding

Fee realization and incentive compounding are role-gated, harvester-triggered operations: one call realizes accrued management and performance fees as new shares, and a separate call claims allowlisted reward tokens, swaps them into the vault's deposit asset, and returns the proceeds to the vault. yield.xyz's OAV v3 family compounds rewards through a companion reinvestor and swapper contract pair with an allowlist and a slippage check on every swap; the Meta Vault contract exposes the equivalent hooks (a configurable reinvestor and a single compounding entrypoint), so a compounding event raises the vault's idle balance without minting new shares. Redeployment of that new idle balance into strategies is a separate step: see the rebalancing note below.

## Off-chain allocation service

yield.xyz runs a recurring job that can keep a Meta Vault's weights aligned with current strategy performance. Each run:

1. **Collects strategy metrics.** APY, TVL, and available deposit capacity for every strategy in the vault's set.
2. **Reads on-chain allocations.** The current strategy set and each strategy's held value, converted to a current weight in basis points.
3. **Computes a decision.** A pluggable algorithm proposes new target weights and whether the drift from current weights justifies acting.
4. **Records the decision.** Every run is written to an auditable log: the previous and proposed allocations, the algorithm and its version, the reason, and, if executed, the transaction hash and the resulting weight drift.
5. **Optionally executes.** If the deployment has automated execution enabled, the job calls `setWeights()` and then `rebalance()` on-chain.

Two algorithms exist today:

<Tabs>
  <Tab title="Default (max APY)">
    Allocates the full portfolio to the single strategy with the highest reported APY, and proposes a rebalance when that strategy's current weight has drifted far enough from 100%.
  </Tab>

  <Tab title="TVL-adjusted APY chaser">
    Maximizes expected yield across the strategy set while penalizing concentration into low-TVL strategies, using a gradient search that starts from an equal-weight split and converges on weights that sum to 100%.
  </Tab>
</Tabs>

<Note>
  Automated execution is optional per deployment. A Meta Vault's weights can also be set and updated manually by its operator without any algorithm running.
</Note>

Each deployment's rebalance transactions are signed by that vault's designated signer, which is either a dedicated wallet or a client-controlled multisig depending on the deployment; see [Roles & signing models](/documentation/platform/vaults/meta-vaults/vault-mechanics/roles-signing-models).

## Next steps

<Columns cols={2}>
  <Card title="Allocation and rebalancing" icon="scale-balanced" href="/documentation/platform/vaults/meta-vaults/vault-mechanics/allocation-weights-rebalancing">
    Target weights, setWeights(), and rebalance() in depth.
  </Card>

  <Card title="Accounting and share price" icon="calculator" href="/documentation/platform/vaults/meta-vaults/vault-mechanics/accounting-share-price">
    How totalAssets() and the fee checkpoint model work.
  </Card>

  <Card title="Roles and signing models" icon="user-lock" href="/documentation/platform/vaults/meta-vaults/vault-mechanics/roles-signing-models">
    Who can call which privileged function.
  </Card>

  <Card title="Smart contract addendum" icon="file-contract" href="/documentation/platform/vaults/meta-vaults/smart-contract-addendum">
    A conceptual walkthrough of components and invariants.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.