> For the complete documentation index, see [llms.txt](https://docs.unison.gg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unison.gg/implementation/architecture.md).

# Architecture

Architecture

Unison is built around five layers: the vault, strategies, cross-chain adapters, an off-chain rebalancing engine, and the DAO vault factory.

```mermaid
graph TD
    subgraph Users
        U1[User on Chain A]
        U2[User on Chain B]
        U3[DAO / Treasury]
    end

    subgraph Hub Chain
        V[UnisonVault<br/>ERC-4626]
        F[DAOVaultFactory]
    end

    subgraph Off-Chain
        RE[Rebalancing Engine<br/>monitors yields, triggers keeper]
    end

    subgraph Cross-Chain Layer
        BA[Bridge Adapter<br/>currently CCIP]
        MA[Messaging Adapter<br/>currently CCIP]
    end

    subgraph Strategies
        S1[Strategy<br/>Chain A]
        S2[Strategy<br/>Chain B]
        S3[Strategy<br/>Chain C]
        S4[RWA Strategy<br/>any chain]
    end

    U1 -->|deposit / withdraw| V
    U2 -->|cross-chain deposit| BA
    BA -->|route to vault| V
    U3 -->|create custom vault| F
    F -->|deploys| V

    RE -->|deploy / rebalance / harvest| V
    RE -.->|monitor yields & positions| S1
    RE -.->|monitor yields & positions| S2
    RE -.->|monitor yields & positions| S3
    RE -.->|monitor yields & positions| S4

    V -->|deploy capital| BA
    BA -->|bridge tokens| S1
    BA -->|bridge tokens| S2
    BA -->|bridge tokens| S3
    V -->|same-chain transfer| S4

    S1 -->|report profit| MA
    S2 -->|report profit| MA
    S3 -->|report profit| MA
    MA -->|update NAV| V
    S4 -->|update NAV directly| V

    style V fill:#1a1a2e,stroke:#e94560,color:#fff
    style BA fill:#16213e,stroke:#0f3460,color:#fff
    style MA fill:#16213e,stroke:#0f3460,color:#fff
    style F fill:#1a1a2e,stroke:#e94560,color:#fff
    style RE fill:#0a3d62,stroke:#3c6382,color:#fff
```

***

### Vault

The vault is the central hub. It follows the ERC-4626 tokenized vault standard and lives on a single hub chain.

It accepts deposits and mints vault shares (uTokens) proportional to current NAV, tracks how much capital is deployed to every strategy on every chain, reserves funds for pending cross-chain withdrawals, and maintains a priority-ordered queue of registered strategies.

**NAV** equals the idle vault balance plus the total capital deployed to strategies. When strategies report profit, the deployed balance goes up, NAV goes up, and so does the share price.

#### Deposit

Users deposit on the vault's home chain or cross-chain via the bridge adapter. The vault mints uTokens based on NAV per share. Capital sits idle until the keeper deploys it to strategies.

#### Capital deployment

The keeper moves idle vault capital into strategies. Same-chain strategies get a direct transfer. Cross-chain strategies go through the bridge adapter. The vault tracks exactly how much is deployed to each strategy on each chain.

#### Withdrawal

Withdrawals follow a priority-ordered cascade:

```mermaid
flowchart LR
    W[User withdraws] --> A{Idle balance<br/>sufficient?}
    A -->|Yes| D[Instant transfer]
    A -->|No| B[Withdraw from<br/>local strategies]
    B --> C{Fully filled?}
    C -->|Yes| D
    C -->|No| E[Request from<br/>remote strategies]
    E --> F[Pending withdrawal<br/>with GUID]
    F -->|Bridge settles| G[Funds arrive<br/>at vault]
    G --> D
```

The vault tries idle balance first. If that's not enough it pulls from same-chain strategies in priority order. If there's still a shortfall it sends withdrawal requests to cross-chain strategies and creates a pending withdrawal with a unique GUID.

Each user can have one active cross-chain withdrawal at a time. Shares stay locked until settlement completes.

#### Profit reporting

Strategies harvest yield periodically and report profit back to the vault. Same-chain strategies report directly. Cross-chain strategies send it through the messaging adapter. Reported profit increases total assets which pushes up the share price for all holders.

***

### Strategies

Strategies are modular isolated contracts that deploy vault capital into yield sources. Each one lives on a specific chain and interacts with a specific protocol or set of protocols.

They are pluggable (new ones can be added without touching existing ones), isolated (a failure in one doesn't affect others or drain the vault), and self-contained (each manages its own allowances, reward claims, and compounding).

#### Harvest cycle

```mermaid
flowchart TD
    H[Keeper triggers harvest] --> R[Claim rewards from<br/>underlying protocol]
    R --> S[Swap rewards to<br/>deposit asset]
    S --> P{Profit?}
    P -->|Yes| FE[Take performance fee<br/>to treasury]
    FE --> RE[Reinvest remaining]
    RE --> RP[Report profit<br/>to vault]
    P -->|No| DONE[No action]
```

The keeper triggers a harvest. The strategy claims accrued rewards, swaps them to the deposit asset, takes the performance fee, reinvests the rest, and reports profit to the vault.

#### Fee structure

| Fee             | Rate          | When                            |
| --------------- | ------------- | ------------------------------- |
| Performance fee | 20% of profit | At each harvest                 |
| Withdrawal fee  | 0.2%          | Only on cross-chain withdrawals |

***

### Cross-chain adapters

Cross-chain communication is abstracted behind two interfaces: one for messaging (withdraw requests, profit reports) and one for bridging (token transfers). This means the underlying provider can be swapped without changing any vault or strategy code.

The current implementation uses Chainlink CCIP for both messaging and bridging through a single adapter contract. It handles outbound token transfers and messages as well as inbound messages that execute function calls on the target contract.

The adapter is fully swappable. A new one implementing the same interfaces can replace CCIP with any bridge provider while the vault and strategy contracts stay untouched.

***

### Off-chain rebalancing engine

The on-chain contracts handle execution. The decisions about where and when to deploy capital are made off-chain by the rebalancing engine.

***

### Access control

All vault and strategy contracts share three roles:

| Role        | Responsibilities                                                         |
| ----------- | ------------------------------------------------------------------------ |
| **Owner**   | Protocol multisig. Sets keeper and manager. Two-step ownership transfer. |
| **Manager** | Operations. Adds/deactivates strategies, updates fees, pause/unpause.    |
| **Keeper**  | Automated. Deploys capital, triggers harvests, rebalances.               |

***

### Emergency safeguards

| Action                    | Triggered by | What it does                                                                       |
| ------------------------- | ------------ | ---------------------------------------------------------------------------------- |
| **Strategy kill**         | Manager      | Liquidates entire position, bridges funds back, revokes all allowances             |
| **Vault pause**           | Manager      | Blocks new deposits and withdrawals. Pending withdrawals keep settling.            |
| **Strategy pause**        | Manager      | Blocks deposits and harvests. Revokes external protocol allowances.                |
| **Strategy deactivation** | Manager      | Removes strategy from withdrawal queue. Can't deactivate with pending withdrawals. |
| **Pending reset**         | Manager      | Manually clears stuck pending state after permanent bridge failure.                |