> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saffron.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Contracts

> Technical overview of the Saffron Vaults smart contract system

```mermaid theme={null}
flowchart LR

%% ================= Node Definitions & Shapes =================
    RVF["RestrictedVaultFactory"]
    VF["VaultFactory"]

    V(["UniV3Vault"])
    VA[["Vault (abstract)"]]

    LRA["UniV3LimitedRangeAdapter"]
    FRA["UniV3FullRangeAdapter"]
    ABase["AdapterBase"]

%% ================= Factories =================
    RVF -.-> |"extends"| VF

%% ================= Vault =================
    VF -- "createVault" --> V
    V -.-> VA

%% ================= Adapter System =================
    VF -- "creates" --> LRA
    VF -- "creates" --> FRA
    FRA -.-> |"extends"| LRA

    V -- "manages" --> ABase
    V --> LRA
    V --> FRA

%% ================= Assets & External =================
    subgraph Tokens ["Token Layer"]
        direction TB
        CT["ClaimToken"]
        FBT["FixedBearerToken"]
        VBT["VariableBearerToken"]
    end

    V --> Tokens

    subgraph External ["External Protocols"]
        direction TB
        UPool[("Uniswap V3 Pool")]
        UPosMgr["PositionManager"]
        VarAsset["variableAsset (ERC20)"]
    end

    LRA & FRA --> External

%% ================= Styling (CSS Classes) =================
    classDef factory fill:#f5f3ff,stroke:#7c3aed,stroke-width:2px,color:#2e1065
    classDef vault fill:#eff6ff,stroke:#2563eb,stroke-width:2px,color:#1e3a8a
    classDef adapter fill:#fff7ed,stroke:#ea580c,stroke-width:2px,color:#7c2d12
    classDef tokens fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef external fill:#fafafa,stroke:#525252,stroke-width:1px,stroke-dasharray: 5 5,color:#171717

    class RVF,VF factory
    class V,VA vault
    class LRA,FRA,ABase adapter
    class CT,FBT,VBT tokens
    class UPool,UPosMgr,VarAsset external
```

## Contract Architecture

Saffron Vaults consist of four contract types: factories, vaults, adapters, and bearer tokens.

### VaultFactory / RestrictedVaultFactory

* Deploys new vaults and adapters from stored bytecode implementations
* Maintains protocol-level settings such as:
  * `feeBps` (protocol fee in basis points)
  * `feeReceiver` (address receiving protocol fees)
* Registers and tracks all deployed instances with associated metadata
* `RestrictedVaultFactory` extends `VaultFactory` and:
  * Restricts all vault and adapter creation to `onlyOwner`
  * Restricts initialization and configuration flows to `onlyOwner`

### UniV3Vault

* Core vault contract that coordinates fixed side and variable side deposits
* Starts automatically when both fixed and variable sides reach capacity
* Once started, funds are locked until maturity
* Enables fixed side positions to convert from `claimToken` to `fixedBearerToken` via `claim()` after vault start
* Settles Uniswap V3 fee earnings at maturity and:
  * Distributes variable side yield via `variableBearerToken`
  * Mints protocol fees in `variableBearerToken` (held by vault for `feeReceiver` to claim)
* Allows early withdrawals only before the vault has started; no withdrawals after start until maturity

### UniV3LimitedRangeAdapter

* Connects a vault to a specific Uniswap V3 pool over a defined tick range
* Mints, manages, and burns the Uniswap V3 position NFT on behalf of the vault
* Provides functions to:
  * Add/remove liquidity
  * Collect and return underlying liquidity and accumulated trading fees
* Enforces:
  * Liquidity tolerance bounds (to protect against misconfiguration)
  * Pool authenticity checks (ensuring the correct Uniswap V3 pool is used)
* Handles early capital return for fixed side withdrawals before the vault starts

### UniV3FullRangeAdapter

* Extends `UniV3LimitedRangeAdapter` with full-range tick configuration
* Automatically sets tick range to `MIN_TICK` and `MAX_TICK` during initialization
* Provides the same functionality as `UniV3LimitedRangeAdapter` but covers the entire price range

### VaultBearerToken

* ERC-20 token contract used for all vault position tokens
* Three instances created per vault:
  * `claimToken` — represents the initial fixed side deposit
  * `fixedBearerToken` — represents the fixed side position after claiming
  * `variableBearerToken` — represents variable side deposits and share of trading fees
* Minting and burning restricted to the owning vault contract