Trader Integration

Technical guide for traders 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 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

The system allows traders to access liquidity for executing strategies, with final PnL enforced onchain at settlement via a multisig.

---

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

Deposits remain open until an epoch is started.

---

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

Borrowing is pull-based, the vault does not push capital, the trader requests it.

All borrowed funds are accounted for and must be settled at the end of the epoch.

---

4. Settlement Phase

Settlement occurs after the epoch duration has elapsed.

settle(int256 pnl)

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

---

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

The trader must approve the vault contract before calling settle().

---

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.