> 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/protocol-reference/overview/architecture.md).

# Architecture

Technical architecture reference for the Elara protocol.

## System Overview

Elara is a KYC-gated, compliant token issuance protocol. Users deposit supported collateral tokens to receive elUSD, stake elUSD to earn yield through sElUSD shares, and redeem collateral at any time. The protocol is composed of nine independently upgradeable contracts governed by a shared `AccessManager`.

## Contract Map

| Contract          | Role                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `Vault`           | Core: minting, redeeming, yield routing                                                     |
| `ElUSD`           | Protocol-issued token (18 dec) — mintable/burnable by Vault                                 |
| `sElUSD`          | ERC20 share token representing staked elUSD                                                 |
| `ElUSDStake`      | Share-based staking pool; issues and redeems sElUSD                                         |
| `TreasuryAdapter` | Coordinates fund routing without holding funds                                              |
| `PriceOracle`     | Pluggable price-feed wrapper (18-decimal normalized); depeg guard for stablecoin collateral |
| `KYCRegistry`     | On-chain KYC status per address                                                             |
| `TokenRegistry`   | Supported collateral configs and per-token fee rates                                        |
| `ElaraBase`       | Abstract base: UUPS + access control + pause + reentrancy                                   |

## Inheritance

Every protocol contract inherits `ElaraBase`, which composes four OpenZeppelin upgradeable bases:

```
ElaraBase
├── AccessManagedUpgradeable   — role-based function restrictions
├── UUPSUpgradeable            — proxy-safe upgrade pattern
├── ReentrancyGuardUpgradeable — reentrancy protection
└── PausableUpgradeable        — emergency pause
```

## Cross-Contract Dependencies

{% tabs %}
{% tab title="Mint" %}

```
Vault.mint(token, recipient, tokenAmount)
  ├── KYCRegistry.isKycApproved(minter)
  ├── KYCRegistry.isKycApproved(recipient)
  ├── TokenRegistry.getTokenConfig(token)
  ├── PriceOracle.getPrice(token)
  ├── TreasuryAdapter.transferIn(token, minter, amount)  ← balance validation
  └── ElUSD.mint(recipient, elUSDAmount)
```

{% endtab %}

{% tab title="Redeem" %}

```
Vault.redeem(token, elUSDAmount, recipient)
  ├── KYCRegistry.isKycApproved(redeemer)
  ├── KYCRegistry.isKycApproved(recipient)
  ├── TokenRegistry.getTokenConfig(token)
  ├── PriceOracle.getPrice(token)
  ├── TreasuryAdapter.canTransferOut(token, total)
  │     ├── [sufficient]   → ElUSD.burn() + TreasuryAdapter.transferOut()
  │     └── [insufficient] → queue Redemption{} struct
  └── ElUSD.burn(vault, elUSDAmount)   ← only on instant or deferred settle
```

{% endtab %}

{% tab title="Yield" %}

```
TreasuryAdapter.distributeYield(amount)
  └── Vault.mintYieldToStaking(amount)
        ├── ElUSD.mint(stakingContract, amount)
        └── ElUSDStake.receiveYield(amount)   ← accounting notification
```

{% endtab %}
{% endtabs %}

## Treasury Architecture

`TreasuryAdapter` is a **coordination layer only** — it holds no funds itself:

* **depositWallet** — receives collateral tokens from mint operations
* **withdrawWallet** — provides collateral for redemptions; must pre-approve the Vault

This separation allows the treasury to deploy deposited collateral to yield strategies independently of maintaining redemption liquidity in the withdrawal pool.

## Access Control Roles

Roles are managed by OpenZeppelin `AccessManager` and enforced via the `restricted` modifier.

| Role               | Capabilities                                        |
| ------------------ | --------------------------------------------------- |
| `CONTRACT_ADMIN`   | Configure fees, oracle settings, contract addresses |
| `KYC_OPERATOR`     | Grant / revoke KYC status in bulk                   |
| `PAUSE_OPERATOR`   | Pause / unpause any contract                        |
| `UPGRADE_OPERATOR` | Authorize UUPS upgrades                             |
| `MINT_OPERATOR`    | Mint elUSD and sElUSD (granted to Vault)            |
| `BURN_OPERATOR`    | Burn elUSD and sElUSD (granted to Vault)            |
| `PUBLIC_ROLE`      | `settleRedemption` — callable by anyone             |

## Storage Layout

All contracts reserve a 50-slot `__gap` for future upgrades (EIP-1967).

| Contract          | Key State                                                                                          |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `Vault`           | `queuedRedemptions mapping(uint256 → Redemption)`, `redemptionIdCounter`                           |
| `ElUSD`           | `isBlocked mapping(address → bool)`                                                                |
| `ElUSDStake`      | `_elUSD`, `_sElUSD`, `_vault`                                                                      |
| `KYCRegistry`     | `isKycApproved mapping(address → bool)`                                                            |
| `TokenRegistry`   | `tokenConfigs mapping(address → TokenConfig)`, `supportedTokens address[]`                         |
| `PriceOracle`     | `oracleTypes mapping(address → OracleType)`, `chainlinkConfigs mapping(address → ChainlinkConfig)` |
| `TreasuryAdapter` | `depositWallet`, `withdrawWallet`, `vault`                                                         |