Technical Audit Documentation

Introduction

Kairos is a subdao of Thetanuts that provides physically settled vaults at fixed prices that automatically transition between calls and puts. The protocol enables users to earn yield on their assets while waiting for target prices, transforming traditional limit orders into yield-generating positions.

Design Philosophy

Architecture Overview

Contract Hierarchy

BaseVault (abstract)
    └── PhysicallySettledVault (dual-asset management, recovery mode)
           └── FixedStrikeVault (fixed strike strategy)

BaseOption (abstract)
    └── PhysicallySettledOption (abstract, exercise window logic)
           ├── PhysicallySettledCallOption
           └── PhysicallySettledPutOption

OptionFactory (RFQ system, option creation)

Key Design Decisions

Audit Scope

OptionFactory

Overview

The OptionFactory implements a Request for Quotation (RFQ) system using a commit-reveal scheme to prevent front-running and MEV attacks.

RFQ Lifecycle

Key Functions

Fee Structure

Security Properties

BaseOption

Overview

Abstract base contract providing common functionality for all option types including transfers, splits, and the event notification system.

State Variables

address public buyer;           // Option holder (right to exercise)
address public seller;          // Collateral provider (obligation)
address public collateralToken; // ERC20 used as collateral
uint256[] public strikes;       // Strike price(s)
uint256 public expiryTimestamp; // When option expires
uint256 public numContracts;    // Number of contracts
uint256 public collateralAmount;// Total collateral locked
uint256 public splitGeneration; // For exponential fee calculation
bytes32 public paramsHash;      // Hash of immutable parameters

Split Mechanism

Options can be split into two child options, preserving the total contract count.

Transfer System

Role transfers (buyer/seller) require explicit approval or caller authorization:

function transfer(bool isBuyer, address target) external {
    // Authorized if:
    // 1. msg.sender is current role holder
    // 2. msg.sender has allowance from current role holder
    // 3. msg.sender is the factory

    // Allowance auto-revokes after use
}

Event Notification System

Options notify buyer and seller contracts about lifecycle events:

PhysicallySettledOption

Overview

Abstract contract for options involving actual asset delivery. Manages exercise windows, oracle failure handling, and physical settlement flows.

Key Constants

uint256 public constant EXERCISE_WINDOW = 1 hours;
// Minimum time after expiry before anyone can force-settle ITM options

Settlement Flow

Exercise Functions

Oracle Failure Handling

function oracleUnhealthy() public view returns (bool unhealthy, uint8 reason) {
    // reason: 0=healthy, 1=TWAP failed, 2=Price feed stale, 3=Invalid data
    // Staleness threshold: max(2 * twapPeriod, 1 day)
}

Security Properties

// Simplified withdraw logic for ITM options:
function withdraw() external {
    // After 1-hour window for ITM...
    try this.exercise() {
        return; // Success - buyer got their payout
    } catch {
        // Buyer didn't have approvals - treat as forfeit
        // Return collateral to seller
    }
}

PhysicallySettledCallOption & PhysicallySettledPutOption

Call Option (Base Collateral)

Put Option (Quote Collateral)

Option Type Encoding

// Option type bit layout: 0xABCD
// A (bits 12-15): Structure (0=Single, 1=Spread, 2=Butterfly, 3=Condor)
// B (bits 8-11):  Collateral (0=Base, 1=Quote)
// C (bits 4-7):   Settlement (0=Cash, 1=Physical)
// D (bits 0-3):   Style (0=Call, 1=Put, 2=Iron Condor)

BaseVault

Overview

Abstract ERC20 vault managing deposits, withdrawals, option creation via RFQ, and share accounting.

Core State

// Immutables
OptionFactory public immutable factory;
bool public immutable isLongOptionStrategy;
uint256 public immutable activeOptionsStrategies;

// RFQ State
uint256 public activeRfqId = type(uint256).max;  // No active RFQ
uint256 public lastRFQTimestamp;
uint256 public activeExpiryTimestamp;

// Deposit Queue
PendingDeposit[] public pendingDeposits;
uint256 public lastProcessedDepositIndex;
uint256[] public lastRecordedValuePerShare;

Deposit Flow

Withdrawal Flow

Option Creation Flow

Share Minting for Pending Deposits

When an RFQ settles, pending deposits are minted shares based on:

// For SHORT strategies (selling options):
effectiveDeposit = deposit + premiumBonus - intrinsicDeduction - itmPenalty

// Where:
// - premiumBonus = deposit * premium / collateralAmount
// - intrinsicDeduction = deposit * intrinsicValue / collateralAmount
// - itmPenalty = 1% if option is ITM (prevents ITM deposit manipulation)

// For LONG strategies (buying options):
effectiveDeposit = deposit - (deposit * totalLongOptionValuation / totalAssetsUSD)

// Where:
// - priceOfOption = premium / collateralAmount (per-contract option price)
// - totalLongOptionValuation = priceOfOption * totalOptionStrategyCollateral
// Long deposits are haircut by the proportion of vault value locked in options

Reserve Ask Calculation

function calculateReserveAsk(...) public view returns (uint256) {
    uint256 timeToExpiry = getNextExpiryTimestamp() - block.timestamp;
    uint256 aprBasedReserve = collateralAmount * MIN_APR_BPS * timeToExpiry / (365 days * 10000);

    if (isLongOptionStrategy) {
        // Buying: APR-based maximum (prevent overpaying)
        return aprBasedReserve;
    } else {
        // Selling: max(APR-based, intrinsicValue) - prevent selling ITM at loss
        uint256 intrinsicValue = calculatePayout(currentPrice);
        return max(aprBasedReserve, intrinsicValue);
    }
}

PhysicallySettledVault

Overview

Extends BaseVault for dual-asset management (base + quote) and physical settlement. Includes comprehensive recovery mode for fault tolerance.

Dual Asset Management

The vault manages two assets:

• Asset Index 0: Base asset (e.g., WETH) - used for Call options
• Asset Index 1: Quote asset (e.g., USDC) - used for Put options

Value Calculation

function calculateValueInUSD(uint256 amount, uint256 assetIndex) {
    if (assetIndex == 1) {
        // Quote asset: adjust decimals only (assume ~$1)
        return amount * PRICE_DECIMALS / 10^quoteDecimals;
    } else {
        // Base asset: multiply by oracle price
        return amount * getCurrentPrice(0) / 10^baseDecimals;
    }
}

Invariant Check

function assertInvariant() internal view {
    if (totalSupply() == 0) return;
    if (isInRecoveryMode && block.timestamp >= recoveryInitiatedAt + RECOVERY_DELAY) return;

    uint256[] memory currentVPS = _calculateValuePerShare();
    bool baseDecreased = currentVPS[0] * 10000 < lastRecordedVPS[0] * (10000 - MAX_VALUE_DROP_BPS);
    bool quoteDecreased = currentVPS[1] * 10000 < lastRecordedVPS[1] * (10000 - MAX_VALUE_DROP_BPS);

    if (baseDecreased && quoteDecreased) revert InvariantViolation();
}

Recovery Mode

Recovery mode can be triggered by anyone when:

1. Invariant Violation: Value drops in both base AND quote terms beyond MAX_VALUE_DROP_BPS threshold
2. Oracle Failure: Invalid data (roundId=0, price<=0, updatedAt=0) or stale data exceeding 86400 seconds (24 hours) since last update

Recovery Mode Effects

Stuck RFQ Recovery

If an RFQ settles but the settlement callback fails (e.g., due to invariant violation), the owner must manually recover:

function recoverSettledRFQOption() external onlyOwner {
    require(isInRecoveryMode);
    require(activeRfqId != type(uint256).max);
    require(pendingDeposits.length > 0);

    // Verify RFQ is truly stuck
    try this.callHandleActiveRfq() {
        revert RFQNotStuck();
    } catch {
        // Transfer option to owner for manual distribution
        BaseOption(optionContract).transfer(isLongOptionStrategy, owner());
    }
}

FixedStrikeVault

Overview

Specialized vault creating options at a fixed strike price. The vault sells covered calls when holding ETH and cash-secured puts when holding USDC.

Key Properties

uint256 public immutable FIXED_STRIKE;

// Always a SHORT strategy (selling covered calls or secured puts)
isLongOptionStrategy = false;

// Both assets must share the SAME underlying price feed (e.g., ETH/USD)
require(assets[0].priceFeed == assets[1].priceFeed);

Automatic Asset Selection (Deposits)

The convenience deposit(uint256 amount) function selects asset based on price vs strike:

function deposit(uint256 amount) external {
    uint256 currentPrice = getCurrentPrice(0);
    uint256 assetIndex;

    if (currentPrice < FIXED_STRIKE) {
        // Below strike: deposit base asset (ETH) for covered calls
        assetIndex = 0;
    } else {
        // Above strike: deposit quote asset (USDC) for secured puts
        assetIndex = 1;
    }

    super.deposit(amount, assetIndex);
}

RFQ Asset Selection (Option Creation)

// PhysicallySettledVault.calculateRfqAmount()
function calculateRfqAmount() public view returns (uint256 collateralAmount, uint256 assetIndex) {
    (uint256[] memory assetValues,,,) = getTotalAssets();
    assetIndex = assetValues[0] > assetValues[1] ? 0 : 1;  // Larger holding wins
    collateralAmount = assets[assetIndex].token.balanceOf(address(this));
}

The position flip happens indirectly: settlement exchanges assets, changing which asset dominates holdings.

Contract Calculation

function calculateNumContracts(uint256 amount, uint256 assetIndex) {
    if (assetIndex == 0) {
        // Calls: 1:1 with base asset
        return amount;
    } else {
        // Puts: amount * PRICE_DECIMALS / FIXED_STRIKE
        return amount * PRICE_DECIMALS / FIXED_STRIKE;
    }
}

Example Workflow

Key Invariants

Protection Mechanisms

Split Attack Prevention

Vault Share Rounding Attacks

ITM Deposit Manipulation

Oracle Manipulation

MEV/Frontrunning

Reentrancy

Attack Vectors to Review

High Priority

1. Exercise Window Race: Can withdraw() and exercise() create race conditions where both succeed/fail unexpectedly?
2. Split Fee Bypass: Can an attacker avoid exponential split fees through creative contract interactions?
3. Recovery Mode Entry: Can an attacker force recovery mode via transient oracle issues to permanently DoS deposits?
4. RFQ Settlement Order: Can ordering of reveals be manipulated to extract value?
5. Pending Deposit Manipulation: Can pending deposits be weaponized during RFQ settlement?
6. First Depositor Donation Attack: After first deposit, can direct token transfer inflate share price to dilute later depositors? (MIN_VALUE provides partial mitigation)

Medium Priority

1. Price Oracle Dependency: What happens with extreme price movements during settlement?
2. Callback Griefing: Can malicious option holders grief vaults via callbacks?
3. Allowance Persistence: Are approvals properly cleaned up after transfers?
4. Dust Accumulation: Can dust amounts accumulate in ways that affect accounting?
5. Split Generation Overflow: After many splits, does 2^generation overflow or create DoS?
6. Share Minting Arithmetic: Edge cases when totalLongOptionValuation > totalAssetsUSD or division by zero scenarios

External Dependencies

• Chainlink Oracle: TWAP calculation depends on oracle availability and accuracy
• Swap Aggregators: swapAndExercise relies on authorized routers (Kyber, 1inch, 0x, Odos, Paraswap)
• ERC20 Tokens: Fee-on-transfer and rebasing tokens explicitly NOT supported

Additional Security Considerations

Known Limitations & Unsupported Scenarios

Emergency Procedures

Access Control Summary

Testing Recommendations

• Fuzz split operations with varying collateral amounts near boundaries
• Test exercise window race conditions with concurrent transactions
• Simulate oracle failures at various points in settlement lifecycle
• Test recovery mode transitions and stuck RFQ scenarios
• Verify share minting math with extreme premium/intrinsic values
• Test MAX_RFQ_VALUE capping with large deposits
• Test first depositor + donation attack scenarios
• Test split generation limits (what happens at generation 20+?)

Intentional Design Patterns (Not Bugs)

The following patterns may appear problematic but are intentional design decisions:

// BaseVault.sol:955-956
// Split the lowest generation option (cheapest fee)
BaseOption optionToSplit = BaseOption(options[lowestGenerationIndex].optionContract);

Critical Code Paths for Auditors

Line references for intensive review: