> For the complete documentation index, see [llms.txt](https://docs.afiprotocol.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.afiprotocol.xyz/proof-of-reserve-vaults/afiusd-vault/technical-architecture.md).

# Technical Architecture

### Overview <a href="#overview" id="overview"></a>

The vault system is designed to abstract complex DeFi strategy execution into a simple and transparent interface for users. Through a layered architecture and clearly defined flows, users can deposit stablecoins, receive yield-bearing vault tokens, and withdraw assets, all while the system optimally manages funds across integrated protocols.

### System Architecture <a href="#system-architecture" id="system-architecture"></a>

<figure><img src="https://3912034821-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEPdvkoJHpBF3QkBeBWkM%2Fuploads%2FlLgvnggiKVdrXqO4cFES%2FScreenshot%202026-01-17%20at%2011.19.51%E2%80%AFAM.png?alt=media&amp;token=e5faaefb-036a-4561-a562-f43c1d5cec98" alt=""><figcaption></figcaption></figure>

The vault system consists of four primary layers:

#### 1. Non-Custodial **Wallet Layer** <a href="#id-1.-smart-wallet-layer" id="id-1.-smart-wallet-layer"></a>

* **User** connects his wallet that interacts with the `afiUSD Vault` to deposit and withdraw assets.
* Deposits are converted into vault shares at the current exchange rate.

#### 2. **Core Contracts** <a href="#id-2.-core-contracts" id="id-2.-core-contracts"></a>

* **afiUSD Vault**: Central vault contract handling deposits, withdrawals, and yield accrual.
* **Yield**: Receives strategy performance updates and facilitates yield distribution over time.
* **Manager**: Executes asset allocation into supported external DeFi protocols.

#### 3. **Admin Layer** <a href="#id-3.-admin-layer" id="id-3.-admin-layer"></a>

* **Admin / Operator / Rebalancer**: Authorized roles responsible for yield updates, vault operations, rebalancing, and governance proposals.
  * **ADMIN\_ROLE**: Multi-signature governance (3/4)
  * **OPERATOR\_ROLE**: Operational functions
  * **REBALANCER\_ROLE**: Yield distribution

#### 4. **External Protocols** <a href="#id-4.-external-protocols" id="id-4.-external-protocols"></a>

* Capital is deployed across multiple integrated protocols through the `Manager`, aiming for optimal yield based on strategy logic.

***

### Flow Summary <a href="#flow-summary" id="flow-summary"></a>

#### Deposit Flow - <a href="#deposit-flow" id="deposit-flow"></a>

<figure><img src="https://3912034821-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEPdvkoJHpBF3QkBeBWkM%2Fuploads%2FfwR3SemPvoCGbJrSEc3G%2FScreenshot%202026-01-17%20at%2011.20.22%E2%80%AFAM.png?alt=media&amp;token=dbfaffe7-ab0f-4484-a835-5bd9bd16f426" alt=""><figcaption></figcaption></figure>

**Sequence Diagram**

* Users approve the vault to spend their assets.
* Vault transfers the assets to the `Manager`.
* Vault mints shares to the user based on the current exchange rate.
* Fee shares (if applicable) are minted to the `Treasury`.
* The `Manager` deploys capital across selected DeFi protocols.

**Step-by-Step:**

1. When a user joins our platform, they connect their wallet to the application.
2. Once a user approves asset spending, our backend service automatically invokes the `deposit()` function from the user's wallet. This function includes the specified amount and the receiver's address, facilitating the direct transfer of funds to the Vault.
3. Vault transfers funds to the `Manager.`
4. Vault mints shares to the user.
5. Manager deploys funds across integrated protocols.

***

#### Withdrawal Flow - <a href="#withdrawal-flow" id="withdrawal-flow"></a>

<figure><img src="https://3912034821-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEPdvkoJHpBF3QkBeBWkM%2Fuploads%2FqydoYgrWWINZhwTAES9v%2FScreenshot%202026-01-17%20at%2011.20.13%E2%80%AFAM.png?alt=media&amp;token=de6e218f-c1d0-47ac-9e95-bfa4403541be" alt=""><figcaption></figcaption></figure>

**Sequence Diagram**

* Users initiate a withdrawal request with their vault share amount.
* A cooldown period (e.g., 72h) is triggered.
* Once complete, the withdrawal is executed and shares are burned.
* Funds are retrieved from protocols and sent to the user.

**Step-by-Step**

1. User calls `requestWithdrawal(shares)`.
2. 72-hour cooldown period begins.
3. `Manager` retrieves funds from protocols.
4. Once cooldown ends, user executes withdrawal.
5. Vault burns user shares.
6. Assets transferred back to user.

#### Yield Distribution Flow - <a href="#yield-distribution-flow" id="yield-distribution-flow"></a>

<figure><img src="https://3912034821-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEPdvkoJHpBF3QkBeBWkM%2Fuploads%2FYEIJj2r2Jeu22rAtX0hW%2FScreenshot%202026-01-17%20at%2011.20.04%E2%80%AFAM.png?alt=media&amp;token=92a18a0c-9063-4a98-9f03-32ce7754cead" alt=""><figcaption></figcaption></figure>

**Sequence Diagram**

* The off-chain engine calculates strategy profits and pushes them on-chain.
* The `Rebalancer` role calls `distributeYield()` on the `Yield` contract.
* Vault's virtual assets are updated.
* Treasury receives a portion of the yield as fee shares.
* Exchange rate increases for all vault holders.

**Step-by-Step**

1. Off-chain system computes yield from deployed strategies.
2. Rebalancer initiates on-chain yield distribution.
3. Yield is allocated to the vault and recorded.
4. Fee shares (if configured) are minted to Treasury.
5. Exchange rate increases gradually as yield vests.

***

### Vault Mechanics <a href="#vault-mechanics" id="vault-mechanics"></a>

#### Yield Vesting - <a href="#yield-vesting" id="yield-vesting"></a>

To protect against front-running and provide a fair yield experience:

* Yield accrues linearly over a vesting period (typically 24 hours).
* This smooths out exchange rate increases and reduces volatility.
* Prevents “sniping” behavior around profit distribution events.

#### Cooldown Period (Withdrawals) - <a href="#cooldown-period-withdrawals" id="cooldown-period-withdrawals"></a>

* Designed to ensure liquidity before honoring withdrawal requests.
* The `Manager` begins to unwind deployed positions during this period.
* Helps avoid slippage or capital inefficiency during high withdrawal demand.