Technical Audit Documentation

Introduction

CLVEX provides no-loss strategy vaults that use rebasing token yields to create options positions. Users deposit rebasing tokens (e.g., aBasUSDC), and only the accrued yield is used for options strategies - original deposits are always preserved.

Available Strategies

Scope & Reading Order

This HTML is meant to orient auditors to the Solidity code under thetanuts_v4/src/. It focuses on the CLVEX/Klyra strategy vault stack, plus the RFQ/options infrastructure that the vaults rely on.

High-Level Components in thetanuts_v4/src/

Recommended Audit Reading Order

1. src/vaults/utils/VaultStorage.sol (storage layout shared with EventHandler)
2. src/vaults/BaseVault.sol (queues, RFQs, withdrawals, option splitting, callbacks)
3. src/vaults/utils/EventHandler.sol (delegatecall event routing and tracking mutation)
4. src/vaults/YieldStrategyVault.sol (principal protection, earnings accounting, recovery mode)
5. src/vaults/DirectionalStrategyVault.sol + src/vaults/MeanRevertingCondorStrategyVault.sol (strategy-specific sizing/strikes)
6. src/options/BaseOption.sol + src/options/CashSettledOption.sol (roles, events, splitting, payout path)
7. src/options/OptionFactory.sol (RFQ lifecycle, fees, settlement, limit-mode)
8. src/oracles/ and src/adapters/ (external dependency surfaces)

Quick Start Integration

Depositing (ClvexWrapper: USDC entry)

// 1) Approve USDC to the wrapper
await usdc.approve(clvexWrapperAddress, amount);

// 2) Deposit (wrapper supplies to Aave → deposits aBasUSDC on your behalf)
await clvexWrapper.depositUSDC(vaultAddress, amount);

// Note: after the first vault deposit, shares are typically minted on RFQ settlement.
// See "Pending Deposits" for lifecycle details.

Depositing (StrategyVaultWrapperABasUSDC: aBasUSDC entry)

// 1) Approve aBasUSDC to the wrapper
await aBasUSDC.approve(strategyWrapperAddress, amount);

// 2) Deposit into a directional vault (isCall=true for call vault, false for put vault)
await strategyWrapper.depositDirectional(amount, true);

// Or deposit into the condor vault
await strategyWrapper.depositCondor(amount);

Depositing (StrategyVaultWrapper: sUSDS entry + rsUSDS adapter)

// 1) Approve sUSDS to the wrapper
await sUSDS.approve(strategyWrapperAddress, amount);

// 2) Deposit directional (wrapper converts sUSDS → rsUSDS internally)
await strategyWrapper.depositDirectional(amount, true);

Claiming Earnings (Non-Compounding Vaults)

// Check claimable
const claimable = await vault.calculateClaimableEarnings(userAddress);

// Claim (transfers aBasUSDC to user)
await vault.claimEarnings();

Withdrawing

// Direct (receive aBasUSDC; withdrawals are payable for potential option split fees)
await vault.withdraw(shares, { value: ethers.parseEther("0.01") });

// ClvexWrapper: withdraw to USDC (Aave withdraw)
await clvexWrapper.withdrawToUSDC(vaultAddress, shares, { value: ethers.parseEther("0.01") });

// StrategyVaultWrapper*: withdraw via wrapper
// 1) Approve vault shares to the wrapper
await vault.approve(strategyWrapperAddress, shares);

// 2) Withdraw from a directional vault (isCall=true/false) or condor
await strategyWrapper.withdrawDirectional(shares, true, { value: ethers.parseEther("0.01") });
await strategyWrapper.withdrawCondor(shares, { value: ethers.parseEther("0.01") });

Note on assetIndex Parameter

Architecture Overview

Contract Hierarchy

BaseVault (abstract)
    └── CashSettledVault (abstract)
           └── YieldStrategyVault (abstract)
                  ├── DirectionalStrategyVault (isLongOptionStrategy=true, isCompounding=false)
                  └── MeanRevertingCondorStrategyVault (isLongOptionStrategy=false, isCompounding=true)

EventHandler (delegatecall)
    └── Mutates BaseVault state via VaultStorage layout

ClvexWrapper / StrategyVaultWrapper*
    └── UX wrappers for deposits/withdrawals + option forwarding

Key State Variables (YieldStrategyVault)

// YieldStrategyVault.sol lines 72-78
uint256 public totalEarnings;           // Accumulated earnings from options
uint256 public baseDeposit;             // Total original deposits (pool-level, not per-user)
uint256 public recoveryRatio = 0;       // Set during recovery mode
uint256 public accEarningsPerShare;     // Earnings accumulator (1e18 precision)
mapping(address => uint256) public userEarningsDebt;  // Per-user debt for earnings calc
bool public immutable isCompounding;    // Set at deployment, cannot change

Codebase Map

This section is a quick index of the major Solidity components in thetanuts_v4/src/ and how they relate.

BaseVault (Queues, RFQs, Withdrawals)

BaseVault is the operational core: it queues deposits, opens RFQs via OptionFactory, tracks active options, and handles withdrawals that may split option positions.

Deposit Queueing (First vs Subsequent Deposits)

RFQ Lifecycle (Vault Side)

Withdrawal + Option Splitting

Withdrawals are payable because users may need to supply ETH for option split fees. When options are active, BaseVault can transfer or split option roles proportionally via _handleOptionWithdrawal() (L957).

Critical Functions (BaseVault.sol)

EventHandler (Delegatecall Option Event Router)

EventHandler is a separate contract created during BaseVault construction and invoked via delegatecall to mutate vault state in response to option events.

Event Routing

OptionFactory (RFQ System)

OptionFactory implements a commit-reveal RFQ mechanism and deploys options as EIP-1167 clones. Vaults use it to source pricing and counterparties for each option cycle.

RFQ Flow (Factory Side)

Key Entry Points (OptionFactory.sol)

BaseOption & CashSettledOption (Option Primitives)

Options are role-based contracts (buyer/seller). They notify both parties (vaults or wrappers) using IOptionEventReceiver callbacks; these callbacks are explicitly non-blocking.

Lifecycle Events

Key Entry Points

Oracles

Strike selection and settlement rely on Chainlink AggregatorProxy price feeds and a TWAP computation that iterates historical rounds.

Rebasing Adapters

Vaults are designed to hold rebasing/yield-bearing ERC20s. Adapters present yield accrual as increasing balances and expand the external dependency surface.

DirectionalStrategyVault

Overview

A LONG option buyer vault that uses rebased yield to purchase directional options. Can be configured for calls (bullish) or puts (bearish) via constructor parameters.

Configuration Parameters

// DirectionalStrategyVault.sol lines 67-69
int256 public immutable STRIKE_PERCENTAGE_DIFFERENCE;  // Can be negative for puts
uint256 public immutable STRIKE_ROUNDING;              // Strike price increment
uint256 public immutable CALL_SPREAD_RATIO_BPS;        // Optional spread ratio (0 = vanilla)

Strike Calculation (Actual Implementation)

// DirectionalStrategyVault.sol lines 153-166
function calculateStrikes() public view override returns (uint256[] memory strikes) {
    uint256 currentPrice = getCurrentPrice(0);
    strikes = new uint256[]((CALL_SPREAD_RATIO_BPS > 0) ? 2 : 1);

    uint256 mainStrike = currentPrice * uint256(100 + STRIKE_PERCENTAGE_DIFFERENCE) / 100;

    // Directional rounding: Ceiling for calls (rounds up), Floor for puts (rounds down)
    strikes[0] = ((mainStrike + ((STRIKE_PERCENTAGE_DIFFERENCE >= 0) ? (STRIKE_ROUNDING - 1) : 0))
            / STRIKE_ROUNDING) * STRIKE_ROUNDING;

    if (CALL_SPREAD_RATIO_BPS > 0) {
        strikes[1] = strikes[0] * CALL_SPREAD_RATIO_BPS / 10_000;
    }
}

Strategy Direction

Non-Compounding Behavior

isCompounding = false means option returns are tracked separately in totalEarnings and distributed via the earnings system, not reinvested into new positions.

MeanRevertingCondorStrategyVault

Overview

A SHORT iron condor seller vault that profits when price stays within a range. Sells OTM put spreads and call spreads centered around current price.

Configuration Parameters

// MeanRevertingCondorStrategyVault.sol lines 49-51
uint256 public immutable STRIKE_GAP;        // Distance from spot to inner strikes
uint256 public immutable STRIKE_INCREMENT;  // Width of each spread wing
uint256 public immutable STRIKE_ROUNDING;   // Strike price rounding increment

Strike Calculation (4 strikes)

// MeanRevertingCondorStrategyVault.sol lines 105-116
function calculateStrikes() public view override returns (uint256[] memory strikes) {
    uint256 currentPrice = getCurrentPrice(0);
    strikes = new uint256[](4);

    // Round current price to nearest STRIKE_ROUNDING
    uint256 roundedPrice = ((currentPrice + STRIKE_ROUNDING / 2) / STRIKE_ROUNDING) * STRIKE_ROUNDING;

    strikes[0] = roundedPrice - STRIKE_GAP - STRIKE_INCREMENT;  // Long put (lower)
    strikes[1] = roundedPrice - STRIKE_GAP;                      // Short put
    strikes[2] = roundedPrice + STRIKE_GAP;                      // Short call
    strikes[3] = roundedPrice + STRIKE_GAP + STRIKE_INCREMENT;  // Long call (upper)
}

Compounding Behavior

isCompounding = true means premium collected is automatically reinvested into new condor positions. No separate earnings tracking.

Compounding Design Rationale

The different compounding modes between Directional and Condor vaults are not arbitrary—they reflect the fundamental economic asymmetry between buying options and selling options.

Why Condor = Compounding

Iron condor sellers receive premium (USDC) when positions are opened. This premium is the same asset used to collateralize new positions. Automatic reinvestment creates a yield-compounding effect typical of premium-selling strategies. The expected return profile (many small wins) aligns well with snowball accumulation.

Why Directional = Non-Compounding

Option buyers pay premium upfront and receive binary payouts—either the option expires worthless (0 return) or pays out significantly if ITM. These returns are irregular and speculative. Distributing earnings via totalEarnings gives users control over realized gains rather than automatically reinvesting into more directional bets. Users may want to take profits, rebalance, or wait for better entry points.

YieldStrategyVault (Base)

Core Formula

The fundamental no-loss calculation that determines how much yield is available for options:

// YieldStrategyVault.sol lines 508-521
function calculateRfqAmount() public view override returns (uint256) {
    if (isInRecoveryMode) revert CannotInitiateRFQInRecoveryMode();
    uint256 totalBalance = _getAssetBalance(0);
    uint256 pendingDepositsTotal = _calculatePendingDepositsTotal();
    uint256 requiredBalance = pendingDepositsTotal + totalEarnings + baseDeposit;

    if (totalBalance <= requiredBalance) {
        return 0;  // No yield available
    }

    uint256 rfqAmount = totalBalance - requiredBalance;
    return rfqAmount;  // Only the rebased yield
}

Earnings System (Non-Compounding Vaults)

How Earnings Accrue

For non-compounding vaults (DirectionalStrategyVault), option payouts are tracked via an accumulator pattern:

// YieldStrategyVault.sol lines 266-294
function _handleExpiredOptions() internal override {
    // Early return guard: only proceed if options have actually expired
    if ((block.timestamp < activeExpiryTimestamp) || (activeExpiryTimestamp == 0)) {
        return;
    }

    if (!isCompounding) {
        uint256 newEarnings = 0;

        // Optimization: Cache TWAP to avoid redundant oracle calls (L274-278)
        // Only cache if options exist, otherwise skip the oracle call
        if (activeOptions[0].length > 0) {
            CashSettledOption firstOption = CashSettledOption(activeOptions[0][0].optionContract);
            uint256 cachedTWAP = firstOption.getTWAP();

            for (uint256 i = 0; i < activeOptions[0].length; i++) {
                CashSettledOption option = CashSettledOption(activeOptions[0][i].optionContract);
                newEarnings += option.calculatePayout(cachedTWAP);
            }
        }

        super._handleExpiredOptions();

        if (newEarnings > 0 && totalSupply() > 0) {
            accEarningsPerShare += (newEarnings * 1e18) / totalSupply();
            totalEarnings += newEarnings;
        }
    } else {
        // Compounding vaults also call super to handle option cleanup
        super._handleExpiredOptions();
    }
}

Earnings Debt System

Prevents new depositors from claiming historical earnings:

// On deposit - YieldStrategyVault.sol lines 171-188
function _mint(address account, uint256 shareAmount, uint256 assetAmount, uint256 assetIndex) internal override {
    uint256 newSharesDebt = 0;
    if (!isCompounding) {
        newSharesDebt = (shareAmount * accEarningsPerShare) / 1e18;
    }

    baseDeposit += assetAmount;
    super._mint(account, shareAmount, assetAmount, assetIndex);

    if (!isCompounding) {
        userEarningsDebt[account] += newSharesDebt;  // Prevents claiming old earnings
    }
}

Claiming Earnings

// YieldStrategyVault.sol lines 314-324
function calculateClaimableEarnings(address user) public view returns (uint256) {
    if (isCompounding) return 0;
    if (isInRecoveryMode && recoveryRatio == 0) revert RecoveryRatioNotSet();

    uint256 accrued = (balanceOf(user) * accEarningsPerShare) / 1e18;
    uint256 pending = accrued > userEarningsDebt[user] ? accrued - userEarningsDebt[user] : 0;
    if (recoveryRatio > 0) {
        pending = (pending * recoveryRatio) / 1e18;  // Scale down in recovery
    }
    return pending;
}

No-Loss Guarantee

Pool-Level Tracking

The no-loss guarantee is implemented at the pool level, not per-user:

// State variable - YieldStrategyVault.sol line 73
uint256 public baseDeposit;  // Total original deposits (pool-level)

// Updated on mint - YieldStrategyVault.sol line 179
baseDeposit += assetAmount;

// Updated on withdrawal - YieldStrategyVault.sol lines 410-416
if (shares == totalSupply()) {
    baseDeposit = 0;
} else if (baseDeposit > 0) {
    // Proportional reduction
    baseDeposit -= (amounts[0] * baseDeposit) / (baseDeposit + excessBalance);
}

How It Works

1. User deposits 1000 aBasUSDC → baseDeposit += 1000
2. Rebasing yields 10 aBasUSDC → totalBalance = 1010
3. Available for options = 1010 - 0 - 0 - 1000 = 10 aBasUSDC
4. Original 1000 is protected, only the 10 yield is at risk

Recovery Mode

Trigger Condition

Recovery mode activates when any asset shortfall occurs (negative rebase, withdrawal, transfer, or other cause) that causes the invariant to fail:

// YieldStrategyVault.sol lines 570-577
function initiateRecoveryMode() external override {
    if (isInRecoveryMode) revert AlreadyInRecoveryMode();
    if (_getAssetBalance(0) < baseDeposit + _calculatePendingDepositsTotal() + totalEarnings) {
        isInRecoveryMode = true;
        emit RecoveryModeInitiated();
    }
}

Recovery Ratio Calculation

// YieldStrategyVault.sol lines 462-487
function determineRecoveryRatio() public {
    if (!isInRecoveryMode) revert NotInRecoveryMode();
    // Must have no active options
    for (uint256 i = 0; i < activeOptionsStrategies; i++) {
        if (activeOptions[i].length != 0) revert ActiveOptionsExist();
    }

    uint256 totalBalance = _getAssetBalance(0);
    uint256 pendingDepositsTotal = _calculatePendingDepositsTotal();

    // Calculate ratio for fair distribution
    recoveryRatio = (totalBalance * 1e18) / (pendingDepositsTotal + baseDeposit + totalEarnings);

    // Scale down all claims proportionally
    for (uint256 i = 0; i < pendingDeposits.length; i++) {
        pendingDeposits[i].amount = (pendingDeposits[i].amount * recoveryRatio) / 1e18;
    }
    baseDeposit = (baseDeposit * recoveryRatio) / 1e18;
    totalEarnings = (totalEarnings * recoveryRatio) / 1e18;
}

Effects of Recovery Mode

Security Warnings

Transfer Hooks Security (Auditor Deep-Dive Required)

The _beforeTokenTransfer and _afterTokenTransfer hooks in YieldStrategyVault.sol implement earnings claim and debt management during share transfers. This is a complex attack surface that has required multiple fixes.

Security Properties That Must Hold

Current Implementation (Post-Fix)

// _claimEarnings: Defense-in-depth early return (L335-338)
function _claimEarnings(address user) internal {
    if (isCompounding) return;
    // Fresh addresses have nothing to claim - prevents griefing via dust transfers
    if (balanceOf(user) == 0 && userEarningsDebt[user] == 0) return;
    // ... proceed with earnings calculation and transfer
}

// _beforeTokenTransfer: Claims for BOTH parties at PRE-TRANSFER balances
if (from != address(0) && to != address(0) && !isCompounding) {
    _claimEarnings(from);  // Sender claims at current balance
    _claimEarnings(to);    // Receiver claims at current balance
                           // Fresh address: balance=0, debt=0 → early return, claims 0
}

// _afterTokenTransfer: Only debt updates (NO claiming)
if (from != address(0) && to != address(0) && !isCompounding) {
    userEarningsDebt[to] = (balanceOf(to) * accEarningsPerShare) / 1e18;
    userEarningsDebt[from] = (balanceOf(from) * accEarningsPerShare) / 1e18;
}

// Reentrancy protection on public ERC20 functions (L362, L383, L392)
// Required because _claimEarnings does external safeTransfer
function transfer(address to, uint256 amount) public override nonReentrant returns (bool);
function transferFrom(address from, address to, uint256 amount) public override nonReentrant returns (bool);
function claimEarnings() external nonReentrant;

Earnings Calculation Formula (Full Logic)

The simplified formula pending = (balance * accEarningsPerShare / 1e18) - debt has additional protective mechanisms in the actual implementation:

// calculateClaimableEarnings() - L314-323
uint256 accrued = (balanceOf(user) * accEarningsPerShare) / 1e18;
uint256 pending = accrued > userEarningsDebt[user]
    ? accrued - userEarningsDebt[user]
    : 0;  // ← Clamped to prevent negative (underflow protection)

if (recoveryRatio > 0) {
    pending = (pending * recoveryRatio) / 1e18;  // ← Scaled during recovery mode
}

// _claimEarnings() - L332-356
// Defense-in-depth: Fresh addresses exit early (L335-338)
if (balanceOf(user) == 0 && userEarningsDebt[user] == 0) return;
// ...
if (pending > totalEarnings) {
    pending = totalEarnings;  // ← Capped to prevent over-distribution
}

Historical Vulnerabilities Fixed

Known Limitations

ClvexWrapper

Purpose

Converts between USDC and aBasUSDC, providing a simpler UX where users interact with USDC but vaults use yield-bearing aBasUSDC.

Actual Function Signatures

// ClvexWrapper.sol - Deposit functions
function depositUSDC(IStrategyVault vault, uint256 usdcAmount) external;
function depositABasUSDC(IStrategyVault vault, uint256 aBasUSDCAmount) external;

// ClvexWrapper.sol - Withdraw functions
function withdrawToABasUSDC(IStrategyVault vault, uint256 shares) external;
function withdrawToUSDC(IStrategyVault vault, uint256 shares) external;

Deposit Flow

Pending Deposits

When you deposit into a CLVEX vault (except the very first deposit), your tokens are not immediately converted to shares. Instead, they enter a pending queue and are processed when the next option cycle settles.

Deposit Lifecycle

Checking Queue Status

// Check how many deposits are pending
const queueLength = await vault.getPendingDepositsLength();

// Check individual pending deposit
const [user, amount, assetIndex] = await vault.pendingDeposits(index);

Cancelling a Pending Deposit

You can cancel your pending deposit at any time before shares are minted by calling withdrawPendingDeposits():

// Cancel all your pending deposits and get tokens back
await vault.withdrawPendingDeposits();

Exit Option Tracking

When users withdraw from vaults with active option positions, the vault splits the option and sends the user's proportional share. The wrapper tracks these "exit options" to distinguish them from options the user bought directly.

Problem Solved

After migration/withdrawal, exit options (split from vault) are indistinguishable from options acquired directly elsewhere (e.g., created via OptionFactory). The tracking system provides on-chain differentiation.

Data Structure

struct ExitOptionRecord {
    address option;        // Option contract address
    bool isBuyerRole;      // Whether user received buyer (true) or seller (false) role
    uint256 timestamp;     // Block timestamp when forwarded
    address fromVault;     // Source vault the option came from
}

mapping(address => ExitOptionRecord[]) public userExitOptions;
mapping(address => mapping(address => uint256)) public exitOptionIndex;

View Functions

// Get all exit options for a user
function getUserExitOptions(address user) external view returns (ExitOptionRecord[] memory);

// Check if an option is an exit option
function isExitOption(address user, address option) external view returns (bool);

// Get full details
function getExitOptionDetails(address user, address option) external view returns (
    bool exists,
    bool isBuyerRole,
    uint256 timestamp,
    address fromVault
);

Events

event ExitOptionTracked(
    address indexed user,
    address indexed option,
    address indexed fromVault,
    bool isBuyerRole,
    uint256 timestamp
);

Frontend Usage

StrategyVaultWrapperABasUSDC

A strategy wrapper in src/wrappers/StrategyVaultWrapperABasUSDC.sol that accepts aBasUSDC directly and routes deposits/withdrawals to the strategy vaults. It also forwards any option positions received during withdrawals to the end user.

Key Functions (as implemented)

// StrategyVaultWrapperABasUSDC.sol
function depositDirectional(uint256 amount, bool isCall) external;
function depositCondor(uint256 amount) external;
function processQueuedDeposits(bool isDirectional, uint256 batchSize) external returns (uint256 processed);

function withdrawDirectional(uint256 shareAmount, bool isCall) external payable returns (uint256 returnedAssets);
function withdrawCondor(uint256 shareAmount) external payable returns (uint256 returnedAssets);

Withdrawal Option Forwarding

StrategyVaultWrapper (sUSDS ↔ rsUSDS)

A strategy wrapper in src/wrappers/StrategyVaultWrapper.sol that accepts a “stableToken” (e.g., sUSDS) and converts to a rebasing token (rsUSDS) via SkyRebasingAdapter before depositing to vaults.

Key Functions (as implemented)

// StrategyVaultWrapper.sol
function depositDirectional(uint256 amount, bool isCall) external;
function depositCondor(uint256 amount) external;
function processQueuedDeposits(bool isDirectional, uint256 batchSize) external returns (uint256 processed);

function withdrawDirectional(uint256 shareAmount, bool isCall) external payable returns (uint256 returnedAssets);
function withdrawCondor(uint256 shareAmount) external payable returns (uint256 returnedAssets);

Key Invariants

Intentional Design Patterns (Not Bugs)

Gas Cost Reference

Measured gas costs from test suite (includes vault interactions):

ClvexWrapper Operations

Error Reference

Critical Code Paths for Auditors