> For the complete documentation index, see [llms.txt](https://docs.rfy.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rfy.finance/resources/trader-integration.md).

# Trader Integration

Technical guide for strategists integrating with RFY vault execution, settlement, and workflow requirements.

## Overview

The RFY vault is an epoch-based ERC-4626 vault that enables offchain strategy execution by a whitelisted multisig **strategist address** while maintaining vault accounting onchain.

Deposited assets are pooled into a vault for a defined epoch. During the active epoch, a whitelisted strategist can borrow capital, execute the strategy directly offchain, and return funds at settlement with the realized profit or loss.

Blackbox uses this same core vault architecture; it does not require a separate Blackbox-specific contract system.

The vault acts as:

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

{% hint style="info" %}
In the contracts, the strategist is authorized through `TRADER_ROLE`. This role name is a contract-level identifier and does not imply a separate execution partner.
{% endhint %}

***

### Roles

#### Strategist

Authorized through `TRADER_ROLE`.

**Permissions**

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

#### Admin (RFY)

Authorized through `DEFAULT_ADMIN_ROLE`.

**Responsibilities**

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

***

### Vault lifecycle

#### 1. Deposit phase

Users deposit assets and receive ERC-4626 shares.

* Deposits increase `totalAssets`.
* Shares represent proportional ownership.
* Deposits remain open until an epoch is started, subject to vault-specific rules.

#### 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**

* A portion may be deployed to an external vault or onchain yield layer.
* Remaining assets stay as idle liquidity.

#### 3. Strategy phase

During the active epoch, the strategist can borrow funds.

**Borrowing**

```
borrow(uint256 amount)
```

Funds are sourced in order:

1. Idle vault liquidity
2. Redeemable external-vault assets

The borrowed amount is tracked internally. Liquidity is pull-based: the strategist requests capital through the authorized multisig.

**Available liquidity**

```
maxBorrow()
```

Returns the sum of idle liquidity and redeemable external-vault assets.

{% 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)
```

Settlement is the point where PnL is enforced and vault NAV is updated.

***

### Settlement mechanics

The strategist returns funds based on borrowed capital and realized PnL:

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

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

Execution:

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

**Requirements**

* The epoch must be finished.
* The strategist must approve the token transfer.
* Losses cannot exceed borrowed capital: `|pnl| <= borrowed`.

#### Final accounting

```
totalPnl =
    tradingPnl
  + externalVaultPnl
  + adminPnl

finalVaultAssets = initialVaultAssets + totalPnl
```

This updates the vault's NAV through `totalAssets`.

#### Post-settlement

* The epoch closes.
* Withdrawals are enabled according to the vault rules.
* Deposits remain paused until reopened.
* Users redeem shares based on the updated NAV.

See the Settlement Reference for worked examples.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.rfy.finance/resources/trader-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.