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

# Contract Map & Inheritance

Elara's on-chain system is composed of ten contracts split across four layers. Every contract that holds protocol state inherits from `ElaraBase`, which provides UUPS upgradeability, reentrancy protection, pausability, and unified access control via OpenZeppelin's `AccessManagerUpgradeable`.

## Contract inventory

| Contract          | Source path                              | Purpose                                                                        |
| ----------------- | ---------------------------------------- | ------------------------------------------------------------------------------ |
| `ElaraBase`       | `contracts/base/ElaraBase.sol`           | Shared base: UUPS, pause, reentrancy, access control                           |
| `ElUSD`           | `contracts/token/ElUSD.sol`              | ERC-20 stablecoin; mintable/burnable; permit; account blocking                 |
| `sElUSD`          | `contracts/token/sElUSD.sol`             | ERC-20 staking share token; only `ElUSDStake` can mint/burn                    |
| `Vault`           | `contracts/vault/Vault.sol`              | Accepts collateral, mints/burns ELUSD, manages redemption queue                |
| `ElUSDStake`      | `contracts/staking/ElUSDStake.sol`       | Converts ELUSD ↔ sELUSD; runs `syncNAV()` to accrue yield                      |
| `PriceOracle`     | `contracts/oracle/PriceOracle.sol`       | Chainlink price feeds normalized to 18 decimals                                |
| `TreasuryAdapter` | `contracts/treasury/TreasuryAdapter.sol` | Bridge between Vault and the treasury multisig                                 |
| `TokenRegistry`   | `contracts/vault/TokenRegistry.sol`      | Stores per-token configuration (decimals, mint/redeem enabled)                 |
| `NAVAggregator`   | `contracts/nav/NAVAggregator.sol`        | Aggregates on-chain NAV from strategy adapters; read by `ElUSDStake.syncNAV()` |

## Inheritance hierarchy

Every core and infrastructure contract inherits from `ElaraBase`:

```
ElaraBase (UUPSUpgradeable + ReentrancyGuardUpgradeable + PausableUpgradeable + AccessManagedUpgradeable)
├── ElUSD
├── sElUSD
├── Vault
├── ElUSDStake
├── PriceOracle
├── TreasuryAdapter
└── TokenRegistry
```

`NAVAggregator` is an infrastructure contract that aggregates NAV adapter readings; it does not hold user funds.

## Cross-contract dependencies

```mermaid
graph TB
    User([User])

    subgraph Core
        Vault[Vault]
        ElUSD[ElUSD]
        ElUSDStake[ElUSDStake]
        sElUSD[sElUSD]
        TA[TreasuryAdapter]
    end

    subgraph Registry
        TR[TokenRegistry]
    end

    subgraph Infrastructure
        Oracle[PriceOracle]
        NAVAgg[NAVAggregator]
        AM[AccessManagerUpgradeable]
    end

    User -->|mint / redeem| Vault
    User -->|stake / unstake| ElUSDStake

    Vault -->|mint / burn| ElUSD
    Vault -->|getPrice| Oracle
    Vault -->|getTokenConfig| TR
    Vault -->|transferIn / transferOut| TA

    ElUSDStake -->|mint / burn| sElUSD
    ElUSDStake -->|hold / transfer| ElUSD
    ElUSDStake -->|getNAV| NAVAgg

    Oracle -->|latestRoundData| ChainlinkFeeds[Chainlink Feeds]

    AM -.->|access control| Vault
    AM -.->|access control| ElUSD
    AM -.->|access control| sElUSD
    AM -.->|access control| ElUSDStake
    AM -.->|access control| Oracle
    AM -.->|access control| TR
```

## Upgradeability

All contracts use the **UUPS** (ERC-1967) proxy pattern. Logic lives in implementation contracts; proxies delegate every call to the current implementation. Upgrades require the `UPGRADE_OPERATOR` role and are executed through `AccessManagerUpgradeable`, which supports mandatory time delays for high-privilege operations.

Each contract reserves a storage gap so future implementation versions can add state variables without collision:

| Contract        | Storage gap (slots) |
| --------------- | ------------------- |
| ElUSD           | 50                  |
| sElUSD          | 50                  |
| Vault           | 49                  |
| ElUSDStake      | 50                  |
| TreasuryAdapter | 49                  |
| TokenRegistry   | 50                  |
| PriceOracle     | N/A (minimal state) |

## Role system

Permissions are managed centrally by a single `AccessManagerUpgradeable` instance. All restricted functions on every contract use the `restricted` modifier, which defers to the manager.

| Role ID | Name                    | Typical holder      | Responsibilities                         |
| ------- | ----------------------- | ------------------- | ---------------------------------------- |
| 10      | `UPGRADE_OPERATOR`      | Multisig            | Deploy new contract implementations      |
| 20      | `PAUSE_OPERATOR`        | Guardian hot wallet | Emergency pause / unpause                |
| 30      | `CONTRACT_ADMIN`        | Multisig            | Configure fees, oracle, token list       |
| 50      | `MINT_OPERATOR`         | Vault contract      | Call `ElUSD.mint()`                      |
| 60      | `BURN_OPERATOR`         | Vault contract      | Call `ElUSD.burn()`                      |
| 70      | `YIELD_OPERATOR`        | Backend service     | Call `ElUSDStake.syncNAV()` daily        |
| 80      | `FEE_OPERATOR`          | Multisig            | Update fee schedule                      |
| 90      | `VAULT_ROLE`            | Vault, ElUSDStake   | Mint/burn ELUSD; call yield entry points |
| 95      | `STAKING_CONTRACT_ROLE` | Vault, ElUSDStake   | Mint/burn sELUSD                         |

Critical operations (upgrades, major configuration changes) carry a **4-day execution delay** enforced by the access manager. Day-to-day operations (pausing, `syncNAV`) execute with no delay.
