# 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="/files/YOkBZ9FJLsaynvFcK5as" 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="/files/58Zl5wjx8upzOCeOYE30" 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="/files/TVFuL4Vkqsiwj63AFOA5" 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="/files/AlKPdkcSVKzkZaBAQJMV" 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.afiprotocol.xyz/proof-of-reserve-vaults/afiusd-vault/technical-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.