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

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.

---

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.

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 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.