# Trader Integration

***

## Overview

The RFY Vault is an epoch-based ERC-4626 vault that enables offchain strategy execution by a whitelisted multisig **trader address**, while maintaining collateral fully onchain.

Deposited assets are pooled into a vault and locked for a fixed epoch duration. During the active epoch, a whitelisted trader (market maker) is authorized to borrow capital, execute strategies offchain, and return funds at settlement with realized profit or loss.

The vault acts as:

* Collateral custody layer
* Accounting and NAV calculation layer
* Settlement enforcement mechanism

{% hint style="info" %}
The system allows **traders** to access liquidity for executing strategies, with final PnL enforced onchain at settlement via a multisig.
{% endhint %}

***

### Roles

#### Trader (Market Maker)

Authorized via `TRADER_ROLE`.

**Permissions:**

* Borrow capital during an active epoch
* Settle final PnL at expiry

***

#### Admin (RFY)

Authorized via `DEFAULT_ADMIN_ROLE`.

**Responsibilities:**

* Start and manage epochs
* Configure vault parameters
* Control deposit and withdrawal states

***

### Vault Lifecycle

#### 1. Deposit Phase

Users deposit assets into the vault and receive ERC-4626 shares.

* Deposits increase `totalAssets`
* Shares represent proportional ownership of the vault

{% hint style="info" %}
Deposits remain open until an epoch is started.
{% endhint %}

***

#### 2. Epoch Initialization

```
startNewEpoch(uint256 minimumDeposits)
```

When an epoch starts:

* Deposits are paused
* Withdrawals are paused
* Vault capital is locked
* Initial assets are recorded

**Capital Allocation:**

* Portion may be deployed to an external vault (yield layer)
* Remaining assets stay as idle liquidity

***

#### 3. Trading Phase

During the active epoch, the trader can borrow funds.

**Borrowing**

```
borrow(uint256 amount)
```

**Behavior:**

* Funds are sourced in order:
  1. Idle vault liquidity
  2. External vault withdrawals
* Borrowed amount is tracked internally
* Liquidity can be requested **at any time during the epoch** via the trader multisig.

***

**Available Liquidity**

```
maxBorrow()
```

Returns:

* Idle liquidity
* Redeemable external vault assets

{% hint style="info" %}
Borrowing is **pull-based,** the vault does not push capital, the trader requests it.
{% endhint %}

{% hint style="danger" %}
All borrowed funds are accounted for and must be settled at the end of the epoch.
{% endhint %}

***

#### 4. Settlement Phase

Settlement occurs after the epoch duration has elapsed.

```
settle(int256 pnl)
```

{% hint style="danger" %}
Settlement is the only point where PnL is enforced and vault NAV is updated.
{% endhint %}

***

### Settlement Mechanics

```
settle(int256 pnl)
```

#### Requirements

* Epoch must be finished
* Trader must approve token transfer

***

#### Core Logic

The trader must return funds based on borrowed capital and realized PnL:

```
If pnl > 0:
    return = borrowed + pnl

If pnl < 0:
    return = borrowed - |pnl|
```

Execution:

```
IERC20(asset).safeTransferFrom(trader, vault, returnAmount);
```

***

#### Constraints

Losses cannot exceed borrowed capital.

```
|pnl| <= borrowed
```

{% hint style="warning" %}
The trader must approve the vault contract before calling `settle()`.
{% endhint %}

***

#### Final Accounting

At settlement, the vault computes:

```
totalPnl =
    tradingPnl
  + externalVaultPnl
  + adminPnl
```

Final vault assets:

```
finalVaultAssets = initialVaultAssets + totalPnl
```

This updates the vault’s NAV (`totalAssets`).

***

#### Post-Settlement

* Epoch is closed
* Withdrawals are enabled
* Deposits remain paused until reopened

Users can redeem shares based on updated NAV.


---

# 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.rfy.finance/resources/trader-integration.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.