# Architecture

This page describes the contract architecture of MetaVaults, how the components interact, and the design decisions behind the system.

## Contract stack

{% @mermaid/diagram content="graph TB
%% Entities
User(\["<b>DEPOSITOR</b><br/>Deposit / Withdraw"])
Curator(\["<b>CURATOR</b><br/>Allocate Liquidity /<br/>Deploy Strategies"])
Guardian(\["<b>GUARDIAN</b><br/>Guard Curator Actions /<br/>Check Timelocked Actions"])
Accountant(\["<b>ACCOUNTANT</b><br/>Performance Tracking,<br/>Share Value Calculations,<br/>Epoch Management"])

```
%% Contracts
MW["MetaVault Wrapper<br/>ERC-7540"]
IV["Infrastructure Vault"]
AC{"Access Control<br/>(Zodiac)"}
GS["SAFE"]
SM[("Markets")]

%% User flow
User -.-> MW
MW --> IV
IV --> GS
GS --> SM

%% Roles through Zodiac
Curator -.-> AC
Guardian -.-> AC
Accountant -.-> AC
AC -.-> GS

%% Styling
classDef entity fill:#f5c542,stroke:#c9a227,stroke-width:2px,color:#000
classDef contract fill:#1b4332,stroke:#1b4332,stroke-width:2px,color:#fff
classDef zodiac fill:#2d6a4f,stroke:#2d6a4f,stroke-width:2px,color:#fff

class User,Curator,Guardian,Accountant entity
class MW,IV,GS,SM contract
class AC zodiac" %}
```

## MetaVaultWrapper

The [MetaVaultWrapper](https://dev.spectra.finance/metavaults/contract-functions/metavault-wrapper) is the user-facing entry point. It implements [ERC-7540](https://eips.ethereum.org/EIPS/eip-7540) (asynchronous vault) and issues ERC-20 wrapper shares. The wrapper layer exists to allow infrastructure vault migrations without disrupting depositors, and to standardise the interface and events under ERC-7540.

Key responsibilities:

* Accept `requestDeposit` / `requestRedeem` from depositors
* Track per-user balances per epoch in wrapper-level storage
* Delegate actual asset custody to the infrastructure vault
* Mint/burn wrapper shares on settlement (`deposit` / `redeem`)

## Infrastructure Vault

The infrastructure vault is the core accounting layer responsible for epoch management, share price calculations, and isolating incoming/outgoing funds. It handles the `settle()` call, which computes performance fees, processes pending deposits and redeems, and increments the epoch.

The current infrastructure vault implementation is the [Amphor AsyncVault](https://github.com/AmphorProtocol/asynchronous-vault/tree/main). The accountant role calls `settle()` to trigger epoch transitions.

### Epoch data

Each epoch stores a snapshot of `totalSupply` and `totalAssets` at settlement time. This allows share/asset conversions for any historical epoch, which is critical for correctly processing claims from different request epochs.

## MetavaultsRegistry

The [MetavaultsRegistry](https://dev.spectra.finance/metavaults/contract-functions/metavaults-registry) is a global on-chain registry that tracks:

* **Vaults** — registered MetaVault addresses
* **Markets** — whitelisted Curve pools (and their associated PT, YT, IBT, asset addresses)
* **Chains** — registered destination chains with remote vault addresses

The registry is access-managed (`AccessManagedUpgradeable`) — only authorized callers can modify it. On-chain validation contracts read from the registry at execution time to validate curator actions.

## Zodiac and Safe architecture

Each MetaVault is owned by a [Safe](https://safe.global/) multisig. The Safe uses the [Zodiac](https://www.gnosisguild.org/) [RolesModifier](https://github.com/gnosisguild/zodiac-modifier-roles) to delegate specific, scoped permissions to the curator role.

For more details on the Zodiac framework, see the [Gnosis Guild documentation](https://docs.roles.gnosisguild.org/).

### How scoping works

The curator is not a Safe signer — instead, the curator executes transactions against a RolesModifier, which acts as the gateway to the Safe. When the curator submits a transaction, the RolesModifier verifies that:

1. The sender belongs to the correct role (e.g. `CURATOR`).
2. The target contract and function selector are allowed for that role.
3. The parameters passed to the function match the restrictions configured for that scope.

Each permitted action is scoped with a combination of constraints. The available [scoping types](https://github.com/gnosisguild/zodiac-modifier-roles/blob/main/packages/evm/contracts/Types.sol) include target address restrictions, function-level allowlists, and parameter-level comparisons (equal, greater than, less than, one-of, etc.).

If any check fails, the transaction is reverted before reaching the Safe. This ensures that even a compromised curator key cannot interact with unauthorized contracts, functions, or parameter values.

### Delay module

A [Delay module](https://github.com/gnosisguild/zodiac-modifier-delay) can be configured between the curator role and execution, adding a time delay before sensitive actions take effect. This gives guardians time to veto malicious transactions.
