Plether Protocol

Plether is a DeFi protocol for synthetic dollar-denominated tokens with inverse and direct exposure to the US Dollar Index (USDX). Users deposit USDC to mint paired tokens that track USD strength, enabling speculation and hedging on dollar movements.

How It Works

The protocol creates two synthetic tokens from USDC collateral:

• plDXY-BEAR - Appreciates when USD weakens (USDX falls)
• plDXY-BULL - Appreciates when USD strengthens (USDX rises)

These tokens are always minted and burned in pairs, maintaining a zero-sum relationship. When you deposit 100 USDC, you receive equal amounts of both tokens. The combined value of a BEAR + BULL pair always equals the original USDC deposit.

Architecture

Core Contracts

Staking Layer

Oracle Layer

BasketOracle Design

The BasketOracle computes a USDX-like index using normalized arithmetic weighting rather than the geometric weighting of the official ICE USDX index:

Price = Σ(Weight_i × Price_i / BasePrice_i)

Each currency’s contribution is normalized by its base price, ensuring the intended USDX weights are preserved regardless of absolute FX rate scales. Without normalization, low-priced currencies like JPY (~$0.007) would be nearly ignored compared to EUR (~$1.08), causing severe weight distortion.

This design enables gas-efficient on-chain computation and eliminates rebalancing requirements, which guarantees protocol solvency.

Inverse Relationship: Because the oracle measures the USD value of a foreign currency basket, it moves inversely to the real USDX index. When the dollar strengthens, USDX rises but our basket value falls (foreign currencies are worth less in USD terms). This is why plDXY-BEAR appreciates when the basket value rises (dollar weakens).

Fixed Base Prices and Weights (immutable, set at deployment based on January 1, 2026 prices):

Both weights and base prices are permanently fixed and cannot be changed after deployment.

Routing Layer

Yield Adapters (ERC-4626)

InvarCoin (INVAR)

InvarCoin is a passive savings token that maintains exposure to a basket of global currencies. Users deposit USDC, which the vault pairs with plDXY-BEAR through Curve to create a balanced position that hedges against USD weakness.

Deposit flow: USDC in → mint INVAR shares (priced against optimistic NAV to prevent dilution).

Withdraw flow: Burn INVAR → receive USDC from local buffer + JIT Curve LP unwinding. An EMA-based slippage floor prevents MEV sandwich amplification on the Curve leg.

LP deposit: Advanced path for depositing USDC + BEAR directly into Curve LP.

LP withdraw: Balanced exit returning pro-rata USDC + BEAR. lpWithdraw intentionally works when paused, serving as the emergency exit.

Yield: Curve LP trading fees accrue as virtual price growth. Keepers call harvest() to mint INVAR proportional to the fee yield and donate it to sINVAR (StakedToken) stakers via a 1-hour streaming window. Only fee yield is captured — price appreciation of the underlying assets is excluded via VP-based cost tracking.

Operational setup sequence:

• Deploy InvarCoin and StakedToken, then call proposeStakedInvarCoin(sINVAR)
• Wait STAKED_INVAR_TIMELOCK (7 days), then call finalizeStakedInvarCoin() before relying on harvest/donation flows
• Propose the reward sink with proposeGaugeRewardsReceiver(receiver)
• Wait GAUGE_REWARDS_TIMELOCK (7 days), then call finalizeGaugeRewardsReceiver()
• Mark CRV and any other gauge incentives with protectRewardToken(token) so they cannot be swept with rescueToken()
• After claiming rewards, route protected balances only through sweepGaugeRewards(token)

Keeper operations:

• deployToCurve() — pushes excess USDC buffer (>2% target) into single-sided Curve LP
• replenishBuffer() — burns Curve LP to restore the 2% USDC buffer
• harvest() — captures LP fee yield and streams to sINVAR stakers

Safety:

• Dual LP pricing: pessimistic (min of EMA, oracle) for withdrawals, optimistic (max) for deposits
• Spot-vs-EMA deviation guard (0.5%) blocks deposits/deployments during pool manipulation
• Virtual shares (1e18/1e6) prevent first-depositor inflation attacks
• totalAssets() is a best-effort NAV view for UX/monitoring; use totalAssetsValidated() for strict oracle-validated accounting reads
• _harvestSafe() gracefully skips when Curve VP reads fail; if yield is pending, strict oracle validation is still enforced
• setEmergencyMode() pauses deposits and single-sided withdrawals without discarding LP accounting; emergencyWithdrawFromCurve() only zeroes LP tracking after assets are actually recovered
• stakedInvarCoin and gaugeRewardsReceiver both use 7-day timelocked propose/finalize flows
• Protected reward tokens cannot be rescued arbitrarily and must be swept to the configured reward receiver
• L2 sequencer uptime validation is enforced on state-changing oracle-critical flows (deposit/lpDeposit/harvest/deploy/replenish)

Ecosystem Integrations

Token Flow

• Chainlink - Price feeds for EUR/USD, JPY/USD, GBP/USD, CAD/USD, CHF/USD
• Pyth Network - Price feed for SEK/USD (via PythAdapter)
• Curve Finance - AMM pools for USDC/plDXY-BEAR swaps
• Morpho Vault - Yield generation on idle USDC reserves via VaultAdapter

Bear Leverage

Flash loan USDC from Morpho → swap to plDXY-BEAR on Curve → stake → deposit splDXY-BEAR as Morpho collateral.

Bull Leverage

Flash loan USDC from Morpho → mint BEAR+BULL pairs → sell BEAR on Curve → stake BULL → deposit splDXY-BULL as Morpho collateral.

Both routers use fee-free Morpho flash loans and a fixed debt model: debt = principal × (leverage - 1).

Staking & Rewards

• StakedToken - ERC-4626 vaults (splDXY-BEAR, splDXY-BULL) that receive streaming USDC rewards
• RewardDistributor - Permissionless distributeRewards() allocates yield from SyntheticSplitter, favoring the underperforming token’s stakers to incentivize price convergence

Protocol Mechanics

Liquidity Management

The SyntheticSplitter maintains a 10% local buffer of USDC for redemptions. Anyone can call deployToAdapter() to push excess USDC to yield adapters, targeting 90% deployment. This generates yield while ensuring liquidity for normal operations.

If adapter liquidity is constrained (e.g., high Morpho utilization), the owner can pause the protocol and use withdrawFromAdapter() for gradual extraction as liquidity becomes available.

Leverage

Users can open leveraged positions through the routers:

1. LeverageRouter (Bear): Morpho flash loan USDC → Swap to plDXY-BEAR → Stake → Deposit to Morpho as collateral → Borrow USDC to repay flash loan
2. BullLeverageRouter (Bull): Morpho flash loan USDC → Mint pairs → Sell plDXY-BEAR → Stake plDXY-BULL → Deposit to Morpho → Borrow to repay

Both routers use a fixed debt model: debt = principal × (leverage - 1). For 2x leverage with $100 principal, Morpho debt is always $100.

Morpho Blue provides fee-free flash loans, making leveraged positions more capital-efficient.

After opening, users can adjust positions with addCollateral() and removeCollateral() without closing.

Both routers include MEV protection via user-defined slippage caps (max 1%). All USDC entry points support EIP-2612 permits for gasless approvals.

Reward Distribution

The RewardDistributor receives yield from SyntheticSplitter and allocates it to StakedToken vaults based on the price discrepancy between the oracle and Curve EMA:

• ≥2% discrepancy: 100% to underperforming token stakers
• <2% discrepancy: Quadratic interpolation from 50/50 toward 100/0
• 0% discrepancy: 50/50 split

This mechanism incentivizes arbitrageurs to correct price deviations by rewarding stakers of the underpriced token. A 0.1% caller reward incentivizes permissionless distribution.

Lifecycle States

The protocol operates in three states:

1. ACTIVE - Normal operations (mint, burn, swap). If Chainlink and Curve EMA prices diverge >2%, BasketOracle reverts, blocking minting, leverage, and reward distribution until prices converge. Burns and swaps remain available—the 10% liquid buffer ensures users can always exit.
2. PAUSED - Emergency pause (minting and reward distribution blocked, burning allowed so users can exit, gradual adapter withdrawal enabled)
3. SETTLED - End-of-life when plDXY hits CAP price (only redemptions allowed)

Development

Prerequisites

• Foundry

Build

forge build

Test

forge test              # Run all tests
forge test -vvv         # Verbose output
forge coverage          # Generate coverage report

Fork Tests

Fork tests run against mainnet state using real Chainlink oracles, Curve pools, and Morpho Blue. They require an RPC URL:

# Set RPC URL (or add to .env file)
export MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY

# Run all fork tests
forge test --match-path "test/fork/*.sol" --fork-url $MAINNET_RPC_URL -vvv

# Or source from .env
source .env && forge test --match-path "test/fork/*.sol" --fork-url $MAINNET_RPC_URL -vvv

Fork test files:

Run a specific fork test file:

source .env && forge test --match-path test/fork/LeverageRouterFork.t.sol --fork-url $MAINNET_RPC_URL -vvv

Testnet Deployment

Sepolia

Deploy to Sepolia testnet with a custom Morpho Blue instance (the public Morpho on Sepolia has no enabled IRMs/LLTVs):

# Required environment variables in .env:
# TEST_PRIVATE_KEY=0x...  (your deployer private key)
# SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY

# Deploy (43 transactions - may take a few minutes)
source .env && forge script script/DeployToSepolia.s.sol --tc DeployToSepolia \
  --rpc-url $SEPOLIA_RPC_URL \
  --broadcast

# Verify contracts on Etherscan (optional)
# ETHERSCAN_API_KEY=... in .env
source .env && forge verify-contract <ADDRESS> <CONTRACT> \
  --chain sepolia --etherscan-api-key $ETHERSCAN_API_KEY

The Sepolia deployment script:

• Deploys its own Morpho Blue instance with a ZeroRateIrm (0% interest for testnet)
• Creates all protocol contracts, oracles, and routers
• Seeds Curve pool and Morpho markets with liquidity
• Mints 100k MockUSDC to the deployer

Anvil (Local)

For frontend development and testing without spending real ETH:

# 1. Start local Anvil node forking Ethereum mainnet
anvil --fork-url $MAINNET_RPC_URL --chain-id 31337

# 2. Deploy all contracts with real Chainlink/Pyth oracles (mints 100k USDC to deployer)
TEST_PRIVATE_KEY=0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d \
forge script script/DeployToAnvilFork.s.sol --tc DeployToAnvilFork \
  --rpc-url http://127.0.0.1:8545 \
  --broadcast

# 3. (Optional) Simulate yield accrual (1% of adapter assets)
cast send <MOCK_YIELD_ADAPTER> "generateYield()" \
  --rpc-url http://127.0.0.1:8545 \
  --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d

# 4. (Optional) Seed Morpho markets for leverage testing
#    Morpho seeding is built into DeployToTest.s.sol for testnet deploys.
#    For Anvil fork, create markets manually using cast commands.

The Anvil fork deployment uses real mainnet oracles (Chainlink for EUR/JPY/GBP/CAD/CHF, Pyth for SEK) with prices frozen at the fork block. MockUSDC and MockYieldAdapter are still used for flexible testing.

Anvil Test Accounts (pre-funded with 10,000 ETH each):

MetaMask Setup:

1. Import a test private key (Settings → Import Account)
2. Add network: RPC http://127.0.0.1:8545, Chain ID 31337

Format

forge fmt               # Format code
forge fmt --check       # Check formatting

Documentation

View Reference Documentation

Generate HTML documentation locally from NatSpec comments:

forge doc               # Generate docs to ./docs
forge doc --serve       # Serve docs locally at http://localhost:3000
forge doc --build       # Build static site to ./docs/book

Security

• All contracts use OpenZeppelin’s battle-tested implementations
• Reentrancy protection on state-changing functions
• 7-day timelock for critical governance changes
• Oracle staleness checks (8–24 hour timeouts depending on context)
• Oracle bound validation against Curve EMA to prevent price manipulation
• Flash loan callback validation (initiator + lender checks)
• Yield adapter uses Morpho Vault vault accounting for yield generation

For detailed security assumptions, trust model, and emergency procedures, see SECURITY.md.

License

AGPL-3.0

Disclaimer

This software is provided “as is” without warranty of any kind. Use at your own risk. This protocol has not been audited. Do not use in production without a professional security audit.

Contents

• FlashLoanBase
• LeverageRouterBase

FlashLoanBase

Git Source

Inherits: IERC3156FlashBorrower, IMorphoFlashLoanCallback

Title: FlashLoanBase

Abstract base for flash loan borrowers with validation logic.

Supports both Morpho flash loans and ERC-3156 flash mints.

Constants

CALLBACK_SUCCESS

ERC-3156 callback success return value.

bytes32 internal constant CALLBACK_SUCCESS = keccak256("ERC3156FlashBorrower.onFlashLoan")

Functions

_validateFlashLoan

Validates ERC-3156 flash loan callback parameters.

function _validateFlashLoan(
    address lender,
    address expectedLender,
    address initiator
) internal view;

Parameters

_validateLender

Validates that msg.sender is the expected lender.

function _validateLender(
    address lender,
    address expectedLender
) internal pure;

Parameters

Errors

FlashLoan__InvalidLender

Thrown when flash loan callback called by wrong lender.

error FlashLoan__InvalidLender();

FlashLoan__InvalidInitiator

Thrown when flash loan initiator is not this contract.

error FlashLoan__InvalidInitiator();

FlashLoan__InvalidOperation

Thrown when callback receives unknown operation type.

error FlashLoan__InvalidOperation();

LeverageRouterBase

Git Source

Inherits: FlashLoanBase, Ownable2Step, Pausable, ReentrancyGuard

Title: LeverageRouterBase

Abstract base for leverage routers with shared validation and admin logic.

Common infrastructure for LeverageRouter (plDXY-BEAR) and BullLeverageRouter (plDXY-BULL).

Note: security-contact: contact@plether.com

Constants

MAX_SLIPPAGE_BPS

Maximum slippage in basis points (1% = 100 bps).

uint256 public constant MAX_SLIPPAGE_BPS = 100

EXCHANGE_RATE_BUFFER_BPS

Buffer for exchange rate drift protection (1% = 100 bps).

uint256 public constant EXCHANGE_RATE_BUFFER_BPS = 100

USDC_INDEX

USDC index in Curve USDC/plDXY-BEAR pool.

uint256 public constant USDC_INDEX = 0

PLDXY_BEAR_INDEX

plDXY-BEAR index in Curve USDC/plDXY-BEAR pool.

uint256 public constant PLDXY_BEAR_INDEX = 1

OP_OPEN

Operation type: open leverage position.

uint8 internal constant OP_OPEN = 1

OP_CLOSE

Operation type: close leverage position.

uint8 internal constant OP_CLOSE = 2

MORPHO

Morpho Blue lending protocol.

IMorpho public immutable MORPHO

CURVE_POOL

Curve pool for USDC/plDXY-BEAR swaps.

ICurvePool public immutable CURVE_POOL

USDC

USDC stablecoin.

IERC20 public immutable USDC

PLDXY_BEAR

plDXY-BEAR token.

IERC20 public immutable PLDXY_BEAR

State Variables

marketParams

Morpho market configuration.

MarketParams public marketParams

Functions

constructor

Initializes base router with core dependencies.

constructor(
    address _morpho,
    address _curvePool,
    address _usdc,
    address _plDxyBear
) Ownable(msg.sender);

Parameters

pause

Pause the router. Blocks openLeverage and closeLeverage.

function pause() external onlyOwner;

unpause

Unpause the router.

function unpause() external onlyOwner;

getActualDebt

Returns the user’s current debt in this market (includes accrued interest).

function getActualDebt(
    address user
) external view returns (uint256 debt);

Parameters

Returns

getCollateral

Returns the user’s collateral in this market.

function getCollateral(
    address user
) external view returns (uint256 collateral);

Parameters

Returns

_marketId

Computes market ID from marketParams.

function _marketId() internal view returns (bytes32);

_getActualDebt

Computes actual debt from Morpho position, rounded up to ensure full repayment.

function _getActualDebt(
    address user
) internal view returns (uint256);

_getBorrowShares

Returns user’s borrow shares from Morpho position.

function _getBorrowShares(
    address user
) internal view returns (uint256);

_getCollateral

Returns user’s collateral from Morpho position.

function _getCollateral(
    address user
) internal view returns (uint256);

Errors

LeverageRouterBase__ZeroAddress

Thrown when zero address provided.

error LeverageRouterBase__ZeroAddress();

LeverageRouterBase__ZeroPrincipal

Thrown when principal is zero.

error LeverageRouterBase__ZeroPrincipal();

LeverageRouterBase__ZeroCollateral

Thrown when collateral is zero.

error LeverageRouterBase__ZeroCollateral();

LeverageRouterBase__Expired

Thrown when deadline has passed.

error LeverageRouterBase__Expired();

LeverageRouterBase__LeverageTooLow

Thrown when leverage multiplier <= 1x.

error LeverageRouterBase__LeverageTooLow();

LeverageRouterBase__SlippageExceedsMax

Thrown when slippage exceeds MAX_SLIPPAGE_BPS.

error LeverageRouterBase__SlippageExceedsMax();

LeverageRouterBase__NotAuthorized

Thrown when user hasn’t authorized router in Morpho.

error LeverageRouterBase__NotAuthorized();

LeverageRouterBase__InsufficientOutput

Thrown when swap output is insufficient.

error LeverageRouterBase__InsufficientOutput();

LeverageRouterBase__InvalidCurvePrice

Thrown when Curve price query returns zero.

error LeverageRouterBase__InvalidCurvePrice();

LeverageRouterBase__SplitterNotActive

Thrown when Splitter is not active.

error LeverageRouterBase__SplitterNotActive();

LeverageRouterBase__ZeroAmount

Thrown when amount is zero.

error LeverageRouterBase__ZeroAmount();

LeverageRouterBase__NoPosition

Thrown when user has no position in Morpho.

error LeverageRouterBase__NoPosition();

LeverageRouterBase__Unhealthy

Thrown when withdrawal would make position unhealthy.

error LeverageRouterBase__Unhealthy();

LeverageRouterBase__AmountTooSmall

Thrown when amount is too small after conversion.

error LeverageRouterBase__AmountTooSmall();

LeverageRouterBase__PermitFailed

error LeverageRouterBase__PermitFailed();

LeverageRouterBase__BelowMinAmountOut

Thrown when output is below user-specified minimum (MEV protection).

error LeverageRouterBase__BelowMinAmountOut();

Contents

• AggregatorV3Interface
• ICurveGauge
• ICurveMinter
• ICurvePool
• ICurveTwocrypto
• IInvarCoin
• MarketParams
• IMorpho
• IMorphoFlashLoanCallback
• PythStructs
• IPyth
• IRewardDistributor
• ISyntheticSplitter
• IYieldAdapter

AggregatorV3Interface

Git Source

Title: AggregatorV3Interface

Chainlink price feed interface.

Standard interface for Chainlink oracles. See https://docs.chain.link/data-feeds.

Functions

decimals

Returns the number of decimals in the price.

function decimals() external view returns (uint8);

description

Returns a human-readable description of the feed.

function description() external view returns (string memory);

version

Returns the feed version number.

function version() external view returns (uint256);

getRoundData

Returns historical round data.

function getRoundData(
    uint80 _roundId
)
    external
    view
    returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound);

Parameters

Returns

latestRoundData

Returns the latest round data.

function latestRoundData()
    external
    view
    returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound);

Returns

ICurveGauge

Git Source

Functions

lp_token

function lp_token() external view returns (address);

deposit

function deposit(
    uint256 amount
) external;

withdraw

function withdraw(
    uint256 amount
) external;

claim_rewards

function claim_rewards() external;

balanceOf

function balanceOf(
    address
) external view returns (uint256);

ICurveMinter

Git Source

Functions

mint

function mint(
    address gauge
) external;

ICurvePool

Git Source

Title: ICurvePool

Interface for Curve StableSwap pools.

Used for USDC/plDXY-BEAR swaps. Indices: USDC=0, plDXY-BEAR=1.

Functions

get_dy

Calculates expected output for a swap.

function get_dy(
    uint256 i,
    uint256 j,
    uint256 dx
) external view returns (uint256);

Parameters

Returns

exchange

Executes a token swap.

function exchange(
    uint256 i,
    uint256 j,
    uint256 dx,
    uint256 min_dy
) external payable returns (uint256);

Parameters

Returns

price_oracle

Returns EMA oracle price (18 decimals).

function price_oracle() external view returns (uint256);

Returns

ICurveTwocrypto

Git Source

Functions

add_liquidity

function add_liquidity(
    uint256[2] calldata amounts,
    uint256 min_mint_amount
) external returns (uint256);

remove_liquidity_one_coin

function remove_liquidity_one_coin(
    uint256 token_amount,
    uint256 i,
    uint256 min_amount
) external returns (uint256);

remove_liquidity

function remove_liquidity(
    uint256 amount,
    uint256[2] calldata min_amounts
) external returns (uint256[2] memory);

get_virtual_price

function get_virtual_price() external view returns (uint256);

lp_price

function lp_price() external view returns (uint256);

calc_token_amount

function calc_token_amount(
    uint256[2] calldata amounts,
    bool deposit
) external view returns (uint256);

calc_withdraw_one_coin

function calc_withdraw_one_coin(
    uint256 token_amount,
    uint256 i
) external view returns (uint256);

IInvarCoin

Git Source

Functions

donateUsdc

function donateUsdc(
    uint256 usdcAmount
) external;

totalAssets

function totalAssets() external view returns (uint256);

MarketParams

Git Source

Morpho Blue market configuration.

struct MarketParams {
address loanToken;
address collateralToken;
address oracle;
address irm;
uint256 lltv;
}

Properties

IMorpho

Git Source

Title: IMorpho

Minimal interface for Morpho Blue lending protocol.

See https://docs.morpho.org for full documentation.

Functions

setAuthorization

Set authorization for an address to act on behalf of the caller

function setAuthorization(
    address authorized,
    bool newIsAuthorized
) external;

isAuthorized

Check if an address is authorized to act on behalf of another

function isAuthorized(
    address authorizer,
    address authorized
) external view returns (bool);

createMarket

Create a new market

function createMarket(
    MarketParams memory marketParams
) external;

idToMarketParams

Get market ID from params

function idToMarketParams(
    bytes32 id
) external view returns (MarketParams memory);

supply

Supply loan assets to a Morpho market as a lender

function supply(
    MarketParams memory marketParams,
    uint256 assets,
    uint256 shares,
    address onBehalfOf,
    bytes calldata data
) external returns (uint256 assetsSupplied, uint256 sharesSupplied);

withdraw

Withdraw loan assets from a Morpho market as a lender

function withdraw(
    MarketParams memory marketParams,
    uint256 assets,
    uint256 shares,
    address onBehalfOf,
    address receiver
) external returns (uint256 assetsWithdrawn, uint256 sharesWithdrawn);

supplyCollateral

Supply collateral to a Morpho market as a borrower

function supplyCollateral(
    MarketParams memory marketParams,
    uint256 assets,
    address onBehalfOf,
    bytes calldata data
) external;

withdrawCollateral

Withdraw collateral from a Morpho market as a borrower

function withdrawCollateral(
    MarketParams memory marketParams,
    uint256 assets,
    address onBehalfOf,
    address receiver
) external;

borrow

Borrow assets from a Morpho market

function borrow(
    MarketParams memory marketParams,
    uint256 assets,
    uint256 shares,
    address onBehalfOf,
    address receiver
) external returns (uint256 assetsBorrowed, uint256 sharesIssued);

repay

Repay borrowed assets to a Morpho market

function repay(
    MarketParams memory marketParams,
    uint256 assets,
    uint256 shares,
    address onBehalfOf,
    bytes calldata data
) external returns (uint256 assetsRepaid, uint256 sharesRepaid);

accrueInterest

Accrue interest for a market

function accrueInterest(
    MarketParams memory marketParams
) external;

liquidate

Liquidate an unhealthy position

function liquidate(
    MarketParams memory marketParams,
    address borrower,
    uint256 seizedAssets,
    uint256 repaidShares,
    bytes calldata data
) external returns (uint256 assetsSeized, uint256 assetsRepaid);

Parameters

flashLoan

Execute a flash loan

Morpho flash loans are fee-free. Callback must repay exact amount.

function flashLoan(
    address token,
    uint256 assets,
    bytes calldata data
) external;

Parameters

position

Get position data for a user in a market

function position(
    bytes32 id,
    address user
) external view returns (uint256 supplyShares, uint128 borrowShares, uint128 collateral);

market

Get market data

function market(
    bytes32 id
)
    external
    view
    returns (
        uint128 totalSupplyAssets,
        uint128 totalSupplyShares,
        uint128 totalBorrowAssets,
        uint128 totalBorrowShares,
        uint128 lastUpdate,
        uint128 fee
    );

Structs

MarketState

Market state for IRM calculations.

struct MarketState {
    uint128 totalSupplyAssets;
    uint128 totalSupplyShares;
    uint128 totalBorrowAssets;
    uint128 totalBorrowShares;
    uint128 lastUpdate;
    uint128 fee;
}

IMorphoFlashLoanCallback

Git Source

Title: IMorphoFlashLoanCallback

Callback interface for Morpho flash loan receivers.

Functions

onMorphoFlashLoan

Called by Morpho during flash loan execution.

function onMorphoFlashLoan(
    uint256 assets,
    bytes calldata data
) external;

Parameters

PythStructs

Git Source

Title: Pyth Price Structs

Structs

Price

struct Price {
    int64 price;
    uint64 conf;
    int32 expo;
    uint256 publishTime;
}

IPyth

Git Source

Title: Pyth Network Interface (minimal)

Minimal interface for reading Pyth price feeds.

Functions

getPriceUnsafe

Returns the price without staleness checks.

function getPriceUnsafe(
    bytes32 id
) external view returns (PythStructs.Price memory price);

Parameters

Returns

getPriceNoOlderThan

Returns the price if it’s no older than age seconds.

function getPriceNoOlderThan(
    bytes32 id,
    uint256 age
) external view returns (PythStructs.Price memory price);

Parameters

Returns

updatePriceFeeds

Updates price feeds with signed data from Pyth.

function updatePriceFeeds(
    bytes[] calldata updateData
) external payable;

Parameters

getUpdateFee

Returns the fee required to update price feeds.

function getUpdateFee(
    bytes[] calldata updateData
) external view returns (uint256 feeAmount);

Parameters

Returns

IRewardDistributor

Git Source

Title: IRewardDistributor

Interface for the RewardDistributor contract that allocates staking rewards based on price discrepancy between oracle and Curve pool.

Functions

distributeRewards

Permissionless function to distribute accumulated USDC rewards.

Calculates price discrepancy, acquires tokens, and donates to vaults.

function distributeRewards() external returns (uint256 callerReward);

Returns

distributeRewardsWithPriceUpdate

Distributes rewards after updating the Pyth oracle price.

Bundles Pyth price update with reward distribution. Pass empty array if no update needed.

function distributeRewardsWithPriceUpdate(
    bytes[] calldata pythUpdateData
) external payable returns (uint256 callerReward);

Parameters

Returns

previewDistribution

Preview the distribution without executing.

function previewDistribution()
    external
    view
    returns (uint256 bearPct, uint256 bullPct, uint256 usdcBalance, uint256 callerReward);

Returns

Events

RewardsDistributed

Emitted when rewards are distributed to staking vaults.

event RewardsDistributed(
    uint256 bearAmount, uint256 bullAmount, uint256 invarUsdcAmount, uint256 bearPct, uint256 bullPct
);

Parameters

Errors

RewardDistributor__DistributionTooSoon

Thrown when distribution is attempted before cooldown expires.

error RewardDistributor__DistributionTooSoon();

RewardDistributor__NoRewards

Thrown when there are no rewards to distribute.

error RewardDistributor__NoRewards();

RewardDistributor__SplitterNotActive

Thrown when the SyntheticSplitter is not in ACTIVE status.

error RewardDistributor__SplitterNotActive();

RewardDistributor__ZeroAddress

Thrown when a constructor parameter is zero address.

error RewardDistributor__ZeroAddress();

RewardDistributor__RefundFailed

Thrown when ETH refund to caller fails.

error RewardDistributor__RefundFailed();

RewardDistributor__InvalidPrice

Thrown when oracle returns zero or negative price.

error RewardDistributor__InvalidPrice();

ISyntheticSplitter

Git Source

Title: ISyntheticSplitter

Minimal interface for external contracts to interact with SyntheticSplitter.

Used by ZapRouter and other integrations.

Functions

mint

Deposits collateral to mint equal amounts of plDXY-BEAR and plDXY-BULL tokens.

Requires approval on USDC. Amount is in 18-decimal token units.

function mint(
    uint256 amount
) external;

Parameters

mintWithPermit

Deposits collateral to mint tokens with a USDC permit signature (gasless approval).

function mintWithPermit(
    uint256 amount,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) external;

Parameters

burn

Burns equal amounts of plDXY-BEAR and plDXY-BULL tokens to retrieve collateral.

Works when not liquidated. May be restricted when paused and insolvent.

function burn(
    uint256 amount
) external;

Parameters

emergencyRedeem

Emergency exit after liquidation. Burns plDXY-BEAR for its full CAP value.

Only works when protocol is liquidated (price >= CAP).

function emergencyRedeem(
    uint256 amount
) external;

Parameters

currentStatus

Returns the current protocol lifecycle status.

function currentStatus() external view returns (Status);

Returns

CAP

Returns the protocol CAP price (8 decimals, oracle format).

function CAP() external view returns (uint256);

Returns

liquidationTimestamp

Returns the timestamp when the protocol was liquidated.

function liquidationTimestamp() external view returns (uint256);

Returns

treasury

Returns the treasury address.

function treasury() external view returns (address);

Returns

Enums

Status

Defines the current lifecycle state of the protocol.

enum Status {
    ACTIVE,
    PAUSED,
    SETTLED
}

Variants

IYieldAdapter

Git Source

Title: IYieldAdapter

Extended interface for yield adapters that support interest accrual.

Optional extension to IERC4626 for adapters with pending interest.

Functions

accrueInterest

Forces the underlying protocol to accrue pending interest.

Call before reading totalAssets() if exact values are needed for calculations.

function accrueInterest() external;

Contents

• DecimalConstants
• IIrm
• MorphoBalancesLib
• OracleLib

DecimalConstants

Git Source

Title: DecimalConstants

Shared decimal scaling constants for the Plether protocol.

Centralizes decimal conversions to prevent scaling bugs.

Constants

ONE_WAD

One unit with 18 decimals (standard ERC20/leverage scale).

uint256 internal constant ONE_WAD = 1e18

ONE_USDC

One USDC (6 decimals).

uint256 internal constant ONE_USDC = 1e6

USDC_TO_TOKEN_SCALE

USDC (6 dec) + Chainlink (8 dec) -> Token (18 dec): 10^20.

uint256 internal constant USDC_TO_TOKEN_SCALE = 1e20

CHAINLINK_TO_MORPHO_SCALE

Chainlink (8 dec) -> Morpho (36 + loanDec - collateralDec = 24 dec): 10^16.

uint256 internal constant CHAINLINK_TO_MORPHO_SCALE = 1e16

CHAINLINK_TO_TOKEN_SCALE

Chainlink (8 dec) -> Token (18 dec): 10^10.

uint256 internal constant CHAINLINK_TO_TOKEN_SCALE = 1e10

IIrm

Git Source

Title: IIrm

Minimal interface for Morpho Blue Interest Rate Models.

Functions

borrowRateView

Returns the borrow rate per second (scaled by 1e18).

function borrowRateView(
    MarketParams memory marketParams,
    IMorpho.MarketState memory market
) external view returns (uint256);

MorphoBalancesLib

Git Source

Title: MorphoBalancesLib

Library to compute expected Morpho balances including pending interest.

Mirrors Morpho Blue’s internal interest accrual logic for accurate view functions.

Constants

WAD

uint256 internal constant WAD = 1e18

Functions

expectedTotalSupplyAssets

Computes expected total supply assets including pending interest.

function expectedTotalSupplyAssets(
    IMorpho morpho,
    MarketParams memory marketParams
) internal view returns (uint256 expectedSupplyAssets);

Parameters

Returns

expectedSupplyAssets

Converts supply shares to expected assets including pending interest.

function expectedSupplyAssets(
    IMorpho morpho,
    MarketParams memory marketParams,
    uint256 shares
) internal view returns (uint256 assets);

Parameters

Returns

OracleLib

Git Source

Title: OracleLib

Library for common oracle validation patterns.

Provides reusable functions for sequencer checks, staleness validation, and price validation.

Functions

checkSequencer

Check if the L2 sequencer is up and grace period has passed.

Skips check if sequencerFeed is address(0) (e.g., on L1 or testnets).

function checkSequencer(
    AggregatorV3Interface sequencerFeed,
    uint256 gracePeriod
) internal view;

Parameters

checkStaleness

Check if the oracle price is stale.

function checkStaleness(
    uint256 updatedAt,
    uint256 timeout
) internal view;

Parameters

checkStalenessAt

Check staleness relative to a specific reference timestamp instead of block.timestamp.

function checkStalenessAt(
    uint256 updatedAt,
    uint256 timeout,
    uint256 referenceTime
) internal pure;

Parameters

verifyHistoricalPrice

Verifies a caller-provided hint round is the correct price at a target timestamp.

Avoids backward traversal that breaks on Chainlink phase boundaries.

function verifyHistoricalPrice(
    AggregatorV3Interface feed,
    uint256 targetTimestamp,
    uint80 hintRoundId
) internal view returns (int256 price, uint256 updatedAt);

Parameters

Returns

getValidatedPrice

Get a validated price from an oracle with staleness and sequencer checks.

Reverts on zero or negative prices to prevent operations during oracle failures.

function getValidatedPrice(
    AggregatorV3Interface oracle,
    AggregatorV3Interface sequencerFeed,
    uint256 gracePeriod,
    uint256 timeout
) internal view returns (uint256 price);

Parameters

Returns

tryGetValidatedPrice

Non-reverting variant of getValidatedPrice for best-effort oracle reads.

function tryGetValidatedPrice(
    AggregatorV3Interface oracle,
    AggregatorV3Interface sequencerFeed,
    uint256 gracePeriod,
    uint256 timeout
) internal view returns (bool success, uint256 price);

Returns

Errors

OracleLib__SequencerDown

error OracleLib__SequencerDown();

OracleLib__SequencerGracePeriod

error OracleLib__SequencerGracePeriod();

OracleLib__StalePrice

error OracleLib__StalePrice();

OracleLib__InvalidPrice

error OracleLib__InvalidPrice();

OracleLib__NoPriceAtExpiry

error OracleLib__NoPriceAtExpiry();

OracleLib__InsufficientGas

error OracleLib__InsufficientGas();

Contents

• DOVZapRouter
• ISettlementOracle
• IOptionToken
• MarginEngine
• OptionToken
• IMarginEngine
• PletherDOV

DOVZapRouter

Git Source

Inherits: FlashLoanBase, ReentrancyGuard, Ownable2Step

Title: DOVZapRouter

Coordinates USDC→splDXY zaps across BEAR and BULL DOVs.

Mints pairs for the overlapping USDC amount (zero slippage), routes excess through Curve or flash mint.

Note: security-contact: contact@plether.com

Constants

USDC_INDEX

uint256 public constant USDC_INDEX = 0

PLDXY_BEAR_INDEX

uint256 public constant PLDXY_BEAR_INDEX = 1

SAFETY_BUFFER_BPS

uint256 public constant SAFETY_BUFFER_BPS = 50

SPLITTER

ISyntheticSplitter public immutable SPLITTER

CURVE_POOL

ICurvePool public immutable CURVE_POOL

USDC

IERC20 public immutable USDC

PLDXY_BEAR

IERC20 public immutable PLDXY_BEAR

PLDXY_BULL

IERC20 public immutable PLDXY_BULL

STAKED_BEAR

IERC4626 public immutable STAKED_BEAR

STAKED_BULL

IERC4626 public immutable STAKED_BULL

BEAR_DOV

PletherDOV public immutable BEAR_DOV

BULL_DOV

PletherDOV public immutable BULL_DOV

CAP

uint256 public immutable CAP

CAP_PRICE

uint256 public immutable CAP_PRICE

Functions

constructor

constructor(
    address _splitter,
    address _curvePool,
    address _usdc,
    address _plDxyBear,
    address _plDxyBull,
    address _stakedBear,
    address _stakedBull,
    address _bearDov,
    address _bullDov
) Ownable(msg.sender);

coordinatedZapAndStartEpochs

Pulls USDC from both DOVs, mints matched pairs, routes excess, starts epoch auctions.

function coordinatedZapAndStartEpochs(
    EpochParams calldata bearParams,
    EpochParams calldata bullParams,
    uint256 minBearSwapOut,
    uint256 minBullSwapOut
) external onlyOwner nonReentrant;

_flashZapBull

function _flashZapBull(
    uint256 usdcAmount,
    uint256 minSwapOut
) internal;

onFlashLoan

function onFlashLoan(
    address initiator,
    address,
    uint256 amount,
    uint256 fee,
    bytes calldata data
) external override returns (bytes32);

onMorphoFlashLoan

function onMorphoFlashLoan(
    uint256,
    bytes calldata
) external pure override;

Events

CoordinatedZap

event CoordinatedZap(uint256 bearUsdc, uint256 bullUsdc, uint256 matchedAmount);

Errors

DOVZapRouter__SolvencyBreach

error DOVZapRouter__SolvencyBreach();

DOVZapRouter__BearPriceAboveCap

error DOVZapRouter__BearPriceAboveCap();

Structs

EpochParams

struct EpochParams {
    uint256 strike;
    uint256 expiry;
    uint256 maxPremium;
    uint256 minPremium;
    uint256 duration;
}

ISettlementOracle

Git Source

Functions

getSettlementPrices

function getSettlementPrices(
    uint256 expiry,
    uint80[] calldata roundHints
) external view returns (uint256 bearPrice, uint256 bullPrice);

IOptionToken

Git Source

Functions

initialize

function initialize(
    string memory name,
    string memory symbol,
    address marginEngine
) external;

mint

function mint(
    address to,
    uint256 amount
) external;

burn

function burn(
    address from,
    uint256 amount
) external;

totalSupply

function totalSupply() external view returns (uint256);

MarginEngine

Git Source

Inherits: ReentrancyGuard, AccessControl

Title: MarginEngine

Core options clearinghouse for Plether DOVs.

Enforces 100% margin requirements and Fractional In-Kind Settlement via StakedTokens.

Note: security-contact: contact@plether.com

Constants

SERIES_CREATOR_ROLE

bytes32 public constant SERIES_CREATOR_ROLE = keccak256("SERIES_CREATOR_ROLE")

SPLITTER

ISyntheticSplitter public immutable SPLITTER

ORACLE

ISettlementOracle public immutable ORACLE

STAKED_BEAR

IERC4626 public immutable STAKED_BEAR

STAKED_BULL

IERC4626 public immutable STAKED_BULL

OPTION_IMPLEMENTATION

address public immutable OPTION_IMPLEMENTATION

CAP

uint256 public immutable CAP

State Variables

nextSeriesId

uint256 public nextSeriesId = 1

series

mapping(uint256 => Series) public series

seriesCreator

mapping(uint256 => address) public seriesCreator

writerLockedShares

mapping(uint256 => mapping(address => uint256)) public writerLockedShares

writerOptions

mapping(uint256 => mapping(address => uint256)) public writerOptions

totalSeriesShares

mapping(uint256 => uint256) public totalSeriesShares

totalSeriesMinted

mapping(uint256 => uint256) public totalSeriesMinted

totalSeriesExercisedShares

mapping(uint256 => uint256) public totalSeriesExercisedShares

settlementTimestamp

mapping(uint256 => uint256) public settlementTimestamp

Functions

constructor

constructor(
    address _splitter,
    address _oracle,
    address _stakedBear,
    address _stakedBull,
    address _optionImplementation
) ;

createSeries

Admin function to deploy a new Option Token Series via EIP-1167.

function createSeries(
    bool isBull,
    uint256 strike,
    uint256 expiry,
    string memory name,
    string memory symbol
) external onlyRole(SERIES_CREATOR_ROLE) returns (uint256 seriesId);

mintOptions

Writers (DOVs) call this to lock splDXY yield-bearing shares and mint options.

Ensures exact 1:1 backing of the underlying asset capacity.

function mintOptions(
    uint256 seriesId,
    uint256 optionsAmount
) external nonReentrant;

settle

Locks the settlement price and exchange rate at expiration.

Callable by anyone. Triggers “Early Acceleration” if protocol liquidates mid-cycle.

function settle(
    uint256 seriesId,
    uint80[] calldata roundHints
) external;

Parameters

adminSettle

Admin fallback for oracle failures — settles with a manually provided price.

2-day grace period after expiry gives the oracle time to recover first.

function adminSettle(
    uint256 seriesId,
    uint256 settlementPrice
) external onlyRole(DEFAULT_ADMIN_ROLE);

exercise

Buyers burn ITM Options to extract their fractional payout of the collateral pool.

Share conversion uses the settlement-time rate for economically correct payouts.

function exercise(
    uint256 seriesId,
    uint256 optionsAmount
) external nonReentrant;

unlockCollateral

Writers unlock their remaining splDXY shares post-settlement.

Uses global debt pro-rata to stay consistent with the exercise cap. globalDebtShares represents the theoretical max debt assuming 100% exercise. If some option holders don’t exercise, their unclaimed share of globalDebtShares remains locked until sweepUnclaimedShares is called after 90 days.

function unlockCollateral(
    uint256 seriesId
) external nonReentrant;

sweepUnclaimedShares

Sweeps unclaimed exercise shares 90 days after settlement.

Returns shares reserved for unexercised ITM options to the admin for distribution.

function sweepUnclaimedShares(
    uint256 seriesId
) external onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

_getGlobalDebtShares

function _getGlobalDebtShares(
    Series storage s,
    uint256 totalMinted,
    uint256 totalShares
) private view returns (uint256 globalDebtShares);

_snapshotShareRate

function _snapshotShareRate(
    Series storage s
) private view returns (uint256);

_transferVaultShares

function _transferVaultShares(
    bool isBull,
    address to,
    uint256 amount
) private;

Events

SeriesCreated

event SeriesCreated(uint256 indexed seriesId, address optionToken, bool isBull, uint256 strike, uint256 expiry);

OptionsMinted

event OptionsMinted(uint256 indexed seriesId, address indexed writer, uint256 optionsAmount, uint256 sharesLocked);

SeriesSettled

event SeriesSettled(uint256 indexed seriesId, uint256 settlementPrice, uint256 settlementShareRate);

OptionsExercised

event OptionsExercised(
    uint256 indexed seriesId, address indexed buyer, uint256 optionsAmount, uint256 sharesReceived
);

CollateralUnlocked

event CollateralUnlocked(
    uint256 indexed seriesId, address indexed writer, uint256 optionsAmount, uint256 sharesReturned
);

UnclaimedSharesSwept

event UnclaimedSharesSwept(uint256 indexed seriesId, uint256 sharesSwept);

Errors

MarginEngine__InvalidParams

error MarginEngine__InvalidParams();

MarginEngine__Expired

error MarginEngine__Expired();

MarginEngine__NotExpired

error MarginEngine__NotExpired();

MarginEngine__AlreadySettled

error MarginEngine__AlreadySettled();

MarginEngine__NotSettled

error MarginEngine__NotSettled();

MarginEngine__OptionIsOTM

error MarginEngine__OptionIsOTM();

MarginEngine__ZeroAmount

error MarginEngine__ZeroAmount();

MarginEngine__SplitterNotActive

error MarginEngine__SplitterNotActive();

MarginEngine__AdminSettleTooEarly

error MarginEngine__AdminSettleTooEarly();

MarginEngine__SweepTooEarly

error MarginEngine__SweepTooEarly();

MarginEngine__Unauthorized

error MarginEngine__Unauthorized();

Structs

Series

struct Series {
    bool isBull;
    uint256 strike;
    uint256 expiry;
    address optionToken;
    uint256 settlementPrice;
    uint256 settlementShareRate;
    bool isSettled;
}

OptionToken

Git Source

Title: OptionToken

EIP-1167 Minimal Proxy Implementation for Option Series.

Constants

decimals

uint8 public constant decimals = 18

State Variables

name

string public name

symbol

string public symbol

totalSupply

uint256 public totalSupply

balanceOf

mapping(address => uint256) public balanceOf

allowance

mapping(address => mapping(address => uint256)) public allowance

marginEngine

address public marginEngine

_initialized

bool private _initialized

Functions

constructor

constructor() ;

onlyEngine

modifier onlyEngine() ;

initialize

Initialize the proxy (called once by MarginEngine).

function initialize(
    string memory _name,
    string memory _symbol,
    address _marginEngine
) external;

mint

function mint(
    address to,
    uint256 amount
) external onlyEngine;

burn

function burn(
    address from,
    uint256 amount
) external onlyEngine;

approve

function approve(
    address spender,
    uint256 amount
) external returns (bool);

transfer

function transfer(
    address to,
    uint256 amount
) external returns (bool);

transferFrom

function transferFrom(
    address from,
    address to,
    uint256 amount
) external returns (bool);

Events

Transfer

event Transfer(address indexed from, address indexed to, uint256 value);

Approval

event Approval(address indexed owner, address indexed spender, uint256 value);

Initialized

event Initialized(string name, string symbol, address marginEngine);

Errors

OptionToken__AlreadyInitialized

error OptionToken__AlreadyInitialized();

OptionToken__Unauthorized

error OptionToken__Unauthorized();

OptionToken__InsufficientBalance

error OptionToken__InsufficientBalance();

OptionToken__InsufficientAllowance

error OptionToken__InsufficientAllowance();

OptionToken__ZeroAddress

error OptionToken__ZeroAddress();

IMarginEngine

Git Source

Functions

createSeries

function createSeries(
    bool isBull,
    uint256 strike,
    uint256 expiry,
    string memory name,
    string memory sym
) external returns (uint256);

mintOptions

function mintOptions(
    uint256 seriesId,
    uint256 optionsAmount
) external;

settle

function settle(
    uint256 seriesId,
    uint80[] calldata roundHints
) external;

unlockCollateral

function unlockCollateral(
    uint256 seriesId
) external;

exercise

function exercise(
    uint256 seriesId,
    uint256 optionsAmount
) external;

series

function series(
    uint256 seriesId
) external view returns (bool, uint256, uint256, address, uint256, uint256, bool);

SPLITTER

function SPLITTER() external view returns (address);

Errors

MarginEngine__ZeroAmount

error MarginEngine__ZeroAmount();

PletherDOV

Git Source

Inherits: ERC20, ReentrancyGuard, Ownable2Step

Title: PletherDOV

Automated Covered Call Vault for Plether synthetic assets.

Natively holds splDXY to prevent weekly AMM slippage. Implements on-chain Dutch Auctions.

Note: security-contact: contact@plether.com

Constants

MARGIN_ENGINE

IMarginEngine public immutable MARGIN_ENGINE

STAKED_TOKEN

IERC4626 public immutable STAKED_TOKEN

USDC

IERC20 public immutable USDC

IS_BULL

bool public immutable IS_BULL

State Variables

currentState

State public currentState = State.UNLOCKED

currentEpochId

uint256 public currentEpochId = 0

zapKeeper

address public zapKeeper

epochs

mapping(uint256 => Epoch) public epochs

pendingUsdcDeposits

uint256 public pendingUsdcDeposits

userUsdcDeposits

mapping(address => uint256) public userUsdcDeposits

userDepositEpoch

mapping(address => uint256) public userDepositEpoch

epochDeposits

mapping(uint256 => EpochDeposits) public epochDeposits

_preZapSplDXYBalance

uint256 internal _preZapSplDXYBalance

_preZapDepositUsdc

uint256 internal _preZapDepositUsdc

_preZapPremiumUsdc

uint256 internal _preZapPremiumUsdc

_zapSnapshotTaken

bool internal _zapSnapshotTaken

Functions

constructor

constructor(
    string memory _name,
    string memory _symbol,
    address _marginEngine,
    address _stakedToken,
    address _usdc,
    bool _isBull
) ERC20(_name, _symbol) Ownable(msg.sender);

initializeShares

Mints initial shares to the owner for seed capital already held by the vault.

Must be called before the first epoch if the vault holds pre-seeded splDXY.

function initializeShares() external onlyOwner;

deposit

Queue USDC to be deposited into the DOV at the start of the next epoch.

Auto-claims shares from any previous epoch deposit before recording the new one.

function deposit(
    uint256 amount
) external nonReentrant;

withdrawDeposit

Withdraw queued USDC that has not yet been processed into an epoch.

function withdrawDeposit(
    uint256 amount
) external nonReentrant;

claimShares

Claims DOV shares earned from a previous epoch’s processed deposit.

function claimShares() external nonReentrant;

withdraw

Redeems vault shares for proportional splDXY (and any premium USDC).

Only callable during UNLOCKED. Auto-claims pending deposit shares first.

function withdraw(
    uint256 shares
) external nonReentrant;

setZapKeeper

function setZapKeeper(
    address _keeper
) external onlyOwner;

releaseUsdcForZap

Releases all USDC held by this DOV to the caller (zapKeeper only).

Snapshots pre-zap state for share calculation in startEpochAuction.

function releaseUsdcForZap() external returns (uint256 amount);

startEpochAuction

Step 1: Rolls the vault into a new epoch, mints options, starts Dutch Auction.

If deposits are pending, releaseUsdcForZap must have been called first to snapshot pre-zap state. Deposit shares are minted proportionally based on the zap conversion.

function startEpochAuction(
    uint256 strike,
    uint256 expiry,
    uint256 maxPremium,
    uint256 minPremium,
    uint256 duration
) external nonReentrant;

getCurrentOptionPrice

Calculates the current linearly decaying price per option.

function getCurrentOptionPrice() public view returns (uint256);

fillAuction

Step 2: Market Makers call this to buy the entire batch of options.

Premium calculation: optionsMinted (18 decimals) * currentPremium (6 decimals) / 1e18 = totalPremiumUsdc (6 decimals). Relies on OptionToken.decimals() == 18.

function fillAuction() external nonReentrant;

cancelAuction

Cancels an expired auction that received no fill, returning the vault to UNLOCKED.

Also allows immediate cancellation when the Splitter has liquidated.

function cancelAuction() external nonReentrant;

exerciseUnsoldOptions

Exercises unsold option tokens held by the DOV after a cancelled auction.

Skips exercise for OTM options so keeper batch transactions don’t revert.

function exerciseUnsoldOptions(
    uint256 epochId
) external nonReentrant;

reclaimCollateral

Reclaims collateral from an unsold series after it has been settled.

function reclaimCollateral(
    uint256 epochId
) external nonReentrant;

settleEpoch

Step 3: At expiration, settles the series and unlocks remaining collateral.

function settleEpoch(
    uint80[] calldata roundHints
) external nonReentrant;

Parameters

emergencyWithdraw

Recovers stranded funds after Splitter liquidation (protocol end-of-life).

Only callable by owner when the Splitter has permanently settled.

function emergencyWithdraw(
    IERC20 token
) external onlyOwner;

pendingSharesOf

Returns the number of shares a user can claim from a processed deposit.

function pendingSharesOf(
    address user
) external view returns (uint256);

totalVaultAssets

Returns the vault’s total assets excluding pending deposits.

function totalVaultAssets() external view returns (uint256 splDXYShares, uint256 usdcBalance);

_claimShares

Claims DOV shares for a user whose deposit was processed in a previous epoch.

function _claimShares(
    address user
) internal;

_calculatePendingShares

function _calculatePendingShares(
    address user
) private view returns (uint256);

_mintDepositShares

Computes and mints aggregate shares for all depositors whose USDC was zapped. Uses the pre-zap snapshot from releaseUsdcForZap to attribute splDXY proportionally between existing shareholders (premium) and new depositors (deposit USDC).

function _mintDepositShares() internal;

Events

DepositQueued

event DepositQueued(address indexed user, uint256 amount);

DepositWithdrawn

event DepositWithdrawn(address indexed user, uint256 amount);

EpochRolled

event EpochRolled(uint256 indexed epochId, uint256 seriesId, uint256 optionsMinted);

AuctionFilled

event AuctionFilled(uint256 indexed epochId, address indexed buyer, uint256 premiumPaid);

AuctionCancelled

event AuctionCancelled(uint256 indexed epochId);

EpochSettled

event EpochSettled(uint256 indexed epochId, uint256 collateralReturned);

EmergencyWithdraw

event EmergencyWithdraw(address indexed token, uint256 amount);

ZapKeeperSet

event ZapKeeperSet(address indexed keeper);

SharesInitialized

event SharesInitialized(address indexed owner, uint256 shares);

DepositSharesMinted

event DepositSharesMinted(uint256 indexed epochId, uint256 totalShares, uint256 totalDepositsUsdc);

SharesClaimed

event SharesClaimed(address indexed user, uint256 shares);

Withdrawn

event Withdrawn(address indexed user, uint256 shares, uint256 splDXYAmount, uint256 usdcAmount);

Errors

PletherDOV__WrongState

error PletherDOV__WrongState();

PletherDOV__ZeroAmount

error PletherDOV__ZeroAmount();

PletherDOV__AuctionEnded

error PletherDOV__AuctionEnded();

PletherDOV__AuctionNotExpired

error PletherDOV__AuctionNotExpired();

PletherDOV__SplitterNotSettled

error PletherDOV__SplitterNotSettled();

PletherDOV__InvalidParams

error PletherDOV__InvalidParams();

PletherDOV__InsufficientDeposit

error PletherDOV__InsufficientDeposit();

PletherDOV__DepositProcessed

error PletherDOV__DepositProcessed();

PletherDOV__Unauthorized

error PletherDOV__Unauthorized();

PletherDOV__AlreadyInitialized

error PletherDOV__AlreadyInitialized();

PletherDOV__NotInitialized

error PletherDOV__NotInitialized();

PletherDOV__DepositsNotZapped

error PletherDOV__DepositsNotZapped();

PletherDOV__NothingToClaim

error PletherDOV__NothingToClaim();

Structs

Epoch

struct Epoch {
    uint256 seriesId;
    uint256 optionsMinted;
    uint256 auctionStartTime;
    uint256 maxPremium; // Max USDC price per option (6 decimals)
    uint256 minPremium; // Min USDC price per option (6 decimals)
    uint256 auctionDuration;
    address winningMaker;
}

EpochDeposits

struct EpochDeposits {
    uint256 totalUsdc;
    uint256 sharesMinted;
}

Enums

State

enum State {
    UNLOCKED,
    AUCTIONING,
    LOCKED
}

Contents

• BasketOracle
• IMorphoOracle
• MorphoOracle
• PythAdapter
• SettlementOracle
• IOracle
• StakedOracle

BasketOracle

Git Source

Inherits: AggregatorV3Interface, Ownable2Step

Title: BasketOracle

Aggregates multiple Chainlink feeds into a normalized weighted plDXY basket price.

Price = Sum(Weight_i * Price_i / BasePrice_i). Normalization preserves intended currency weights.

Note: security-contact: contact@plether.com

Constants

DECIMALS

Chainlink standard decimals for fiat/USD pairs.

uint8 public constant DECIMALS = 8

DESCRIPTION

Oracle description string.

string public constant DESCRIPTION = "plDXY Fixed Basket (Bounded)"

TIMELOCK_DELAY

Timelock delay for Curve pool updates (7 days).

uint256 public constant TIMELOCK_DELAY = 7 days

MAX_DEVIATION_BPS

Maximum allowed deviation from Curve spot (basis points).

uint256 public immutable MAX_DEVIATION_BPS

CAP

Protocol CAP price (8 decimals). Theoretical price is clamped to this before deviation check.

uint256 public immutable CAP

State Variables

components

Array of currency components (EUR, JPY, GBP, CAD, SEK, CHF).

Component[] public components

curvePool

Curve pool for deviation validation.

ICurvePool public curvePool

pendingCurvePool

Pending Curve pool for timelock-protected updates.

address public pendingCurvePool

hasPendingProposal

Whether a proposal is active (needed because address(0) is a valid proposal).

bool public hasPendingProposal

curvePoolActivationTime

Timestamp when pending Curve pool can be finalized.

uint256 public curvePoolActivationTime

Functions

constructor

Creates basket oracle with currency components.

constructor(
    address[] memory _feeds,
    uint256[] memory _quantities,
    uint256[] memory _basePrices,
    uint256 _maxDeviationBps,
    uint256 _cap,
    address _owner
) Ownable(_owner);

Parameters

setCurvePool

Sets the Curve pool for deviation validation (initial setup only).

function setCurvePool(
    address _curvePool
) external onlyOwner;

Parameters

proposeCurvePool

Proposes a new Curve pool (requires 7-day timelock).

function proposeCurvePool(
    address _newPool
) external onlyOwner;

Parameters

finalizeCurvePool

Finalizes the Curve pool update after timelock expires.

function finalizeCurvePool() external onlyOwner;

latestRoundData

Returns the aggregated basket price from all component feeds.

function latestRoundData() public view returns (uint80, int256, uint256, uint256, uint80);

Returns

_checkDeviation

Validates basket price against Curve spot. Reverts on excessive deviation. Intentionally acts as a global circuit breaker: if Chainlink and Curve EMA diverge beyond MAX_DEVIATION_BPS, all consumers (SyntheticSplitter, MorphoOracle, StakedOracle) are frozen — including Morpho liquidations. This is the desired behavior: large divergence signals either a compromised feed or a manipulated pool, and freezing is safer than acting on potentially bad price data.

function _checkDeviation(
    uint256 theoreticalDxy8Dec
) internal view;

Parameters

decimals

Returns oracle decimals (8).

function decimals() external pure returns (uint8);

description

Returns oracle description.

function description() external pure returns (string memory);

version

Returns oracle version (1).

function version() external pure returns (uint256);

getRoundData

Returns data for a specific round ID.

Only round ID 1 is supported (synthetic basket has no historical rounds).

function getRoundData(
    uint80 _roundId
) external view returns (uint80, int256, uint256, uint256, uint80);

Events

CurvePoolProposed

Emitted when a new Curve pool is proposed.

event CurvePoolProposed(address indexed newPool, uint256 activationTime);

CurvePoolUpdated

Emitted when Curve pool is updated.

event CurvePoolUpdated(address indexed oldPool, address indexed newPool);

Errors

BasketOracle__InvalidPrice

Thrown when a component feed returns invalid price.

error BasketOracle__InvalidPrice(address feed);

BasketOracle__LengthMismatch

Thrown when feeds and quantities arrays have different lengths.

error BasketOracle__LengthMismatch();

BasketOracle__PriceDeviation

Thrown when basket price deviates too far from Curve spot.

error BasketOracle__PriceDeviation(uint256 theoretical, uint256 spot);

BasketOracle__AlreadySet

Thrown when Curve pool is already configured.

error BasketOracle__AlreadySet();

BasketOracle__TimelockActive

Thrown when timelock period has not elapsed.

error BasketOracle__TimelockActive();

BasketOracle__InvalidProposal

Thrown when no pending proposal exists.

error BasketOracle__InvalidProposal();

BasketOracle__InvalidDeviation

Thrown when max deviation is zero.

error BasketOracle__InvalidDeviation();

BasketOracle__InvalidBasePrice

Thrown when a base price is zero.

error BasketOracle__InvalidBasePrice();

BasketOracle__InvalidWeights

Thrown when quantities don’t sum to 1e18.

error BasketOracle__InvalidWeights();

BasketOracle__InvalidRoundId

error BasketOracle__InvalidRoundId();

Structs

Component

Component feed with its basket weight and base price for normalization.

struct Component {
    AggregatorV3Interface feed;
    uint256 quantity;
    uint256 basePrice;
}

IMorphoOracle

Git Source

Interface for Morpho-compatible price oracles.

Functions

price

Returns price of 1 collateral unit in loan asset terms (Morpho scale: 36 + loanDec - colDec = 24 decimals).

function price() external view returns (uint256);

MorphoOracle

Git Source

Inherits: IMorphoOracle

Title: MorphoOracle

Adapts BasketOracle price to Morpho Blue’s oracle scale (24 decimals for USDC/plDXY).

Supports both plDXY-BEAR (direct) and plDXY-BULL (inverse) pricing.

Note: security-contact: contact@plether.com

Constants

BASKET_ORACLE

Source price feed (BasketOracle).

AggregatorV3Interface public immutable BASKET_ORACLE

CAP

Protocol CAP price (8 decimals).

uint256 public immutable CAP

IS_INVERSE

If true, returns CAP - Price (for plDXY-BULL).

bool public immutable IS_INVERSE

STALENESS_TIMEOUT

Maximum age for valid oracle price.

uint256 public constant STALENESS_TIMEOUT = 24 hours

Functions

constructor

Creates Morpho-compatible oracle wrapper.

constructor(
    address _basketOracle,
    uint256 _cap,
    bool _isInverse
) ;

Parameters

price

Returns collateral price in Morpho scale (24 decimals for USDC(6)/plDXY(18)).

Morpho expects: 36 + loanDecimals - collateralDecimals = 36 + 6 - 18 = 24. BEAR (IS_INVERSE=false): min(basketPrice, CAP) * CHAINLINK_TO_MORPHO_SCALE. BULL (IS_INVERSE=true): (CAP - basketPrice) * CHAINLINK_TO_MORPHO_SCALE. Returns 1 (not 0) when BULL price would be zero to avoid Morpho division errors.

function price() external view override returns (uint256);

Returns

Errors

MorphoOracle__InvalidPrice

Thrown when source oracle returns zero or negative price.

error MorphoOracle__InvalidPrice();

MorphoOracle__StalePrice

Thrown when source oracle data is stale.

error MorphoOracle__StalePrice();

MorphoOracle__ZeroAddress

Thrown when zero address provided to constructor.

error MorphoOracle__ZeroAddress();

PythAdapter

Git Source

Inherits: AggregatorV3Interface

Title: PythAdapter

Adapts Pyth Network price feeds to Chainlink’s AggregatorV3Interface.

Pyth is pull-based: prices must be pushed on-chain before reading. This adapter reads the latest price and converts it to 8 decimals. Supports price inversion for feeds like USD/SEK → SEK/USD.

Note: security-contact: contact@plether.com

Constants

PYTH

IPyth public immutable PYTH

PRICE_ID

bytes32 public immutable PRICE_ID

MAX_STALENESS

uint256 public immutable MAX_STALENESS

MAX_CONFIDENCE_BPS

uint256 public immutable MAX_CONFIDENCE_BPS

INVERSE

bool public immutable INVERSE

DECIMALS

uint8 public constant DECIMALS = 8

State Variables

DESCRIPTION

string public DESCRIPTION

Functions

constructor

constructor(
    address pyth_,
    bytes32 priceId_,
    uint256 maxStaleness_,
    string memory description_,
    bool inverse_,
    uint256 maxConfidenceBps_
) ;

Parameters

latestRoundData

Returns the latest price data in Chainlink-compatible format.

Converts Pyth’s variable exponent to fixed 8 decimals. Reports block.timestamp as updatedAt (self-attestation): this adapter validates freshness internally against publishTime using MAX_STALENESS, then attests “price valid as of now.” Downstream consumers (BasketOracle, SyntheticSplitter) see a fresh timestamp and skip their own staleness check, avoiding double-timeout rejection during weekend forex market closures.

function latestRoundData() external view returns (uint80, int256, uint256, uint256, uint80);

Returns

getRoundData

Returns data for a specific round ID.

Only round ID 1 is supported (Pyth doesn’t use rounds).

function getRoundData(
    uint80 _roundId
) external view returns (uint80, int256, uint256, uint256, uint80);

decimals

Returns the number of decimals (always 8 for compatibility).

function decimals() external pure returns (uint8);

description

Returns the price feed description.

function description() external view returns (string memory);

version

Returns the adapter version.

function version() external pure returns (uint256);

updatePrice

Updates the Pyth price feed with new data.

Anyone can call this to push fresh prices on-chain.

function updatePrice(
    bytes[] calldata updateData
) external payable;

Parameters

getUpdateFee

Returns the fee required to update the price.

function getUpdateFee(
    bytes[] calldata updateData
) external view returns (uint256 fee);

Parameters

Returns

_convertTo8Decimals

Converts Pyth price to 8 decimals.

Pyth uses variable exponents (e.g., -8, -6). This normalizes to -8.

function _convertTo8Decimals(
    int64 price,
    int32 expo
) internal pure returns (int256);

Parameters

Returns

_invertTo8Decimals

Inverts Pyth price and converts to 8 decimals.

For converting USD/SEK to SEK/USD: 1 / (price * 10^expo) * 10^8

function _invertTo8Decimals(
    int64 price,
    int32 expo
) internal pure returns (int256);

Parameters

Returns

Errors

PythAdapter__StalePrice

error PythAdapter__StalePrice(uint256 publishTime, uint256 maxAge);

PythAdapter__InvalidPrice

error PythAdapter__InvalidPrice();

PythAdapter__ConfidenceTooWide

error PythAdapter__ConfidenceTooWide(uint64 conf, int64 price);

PythAdapter__InvalidRoundId

error PythAdapter__InvalidRoundId();

PythAdapter__RefundFailed

error PythAdapter__RefundFailed();

SettlementOracle

Git Source

Title: SettlementOracle

Pure theoretical oracle for option settlement.

Uses historical Chainlink round data to look up prices at expiry, eliminating the settlement window and preventing lookback MEV.

Note: security-contact: contact@plether.com

Constants

CAP

uint256 public immutable CAP

SEQUENCER_UPTIME_FEED

AggregatorV3Interface public immutable SEQUENCER_UPTIME_FEED

SEQUENCER_GRACE_PERIOD

uint256 public constant SEQUENCER_GRACE_PERIOD = 1 hours

ORACLE_TIMEOUT

uint256 public constant ORACLE_TIMEOUT = 24 hours

State Variables

components

Component[] public components

Functions

constructor

constructor(
    address[] memory _feeds,
    uint256[] memory _quantities,
    uint256[] memory _basePrices,
    uint256 _cap,
    address _sequencerUptimeFeed
) ;

getSettlementPrices

Returns the pure theoretical settlement prices at a given expiry timestamp.

function getSettlementPrices(
    uint256 expiry,
    uint80[] calldata roundHints
) external view returns (uint256 bearPrice, uint256 bullPrice);

Parameters

Returns

Errors

SettlementOracle__InvalidPrice

error SettlementOracle__InvalidPrice(address feed);

SettlementOracle__LengthMismatch

error SettlementOracle__LengthMismatch();

SettlementOracle__WrongHintCount

error SettlementOracle__WrongHintCount();

SettlementOracle__InvalidBasePrice

error SettlementOracle__InvalidBasePrice();

SettlementOracle__InvalidWeights

error SettlementOracle__InvalidWeights();

Structs

Component

struct Component {
    AggregatorV3Interface feed;
    uint256 quantity;
    uint256 basePrice;
}

IOracle

Git Source

Interface for price oracles.

Functions

price

Returns price of 1 collateral unit in loan asset terms.

function price() external view returns (uint256);

StakedOracle

Git Source

Inherits: IOracle

Title: StakedOracle

Prices ERC4626 vault shares by combining underlying price with exchange rate.

Price = UnderlyingPrice * ExchangeRate. Used for splDXY-BEAR/splDXY-BULL in Morpho.

Note: security-contact: contact@plether.com

Constants

VAULT

The staking vault (splDXY-BEAR or splDXY-BULL).

IERC4626 public immutable VAULT

UNDERLYING_ORACLE

Oracle for the underlying plDXY token.

IOracle public immutable UNDERLYING_ORACLE

SHARE_DECIMALS

Decimal multiplier for vault shares (accounts for ERC4626 decimal offset).

uint256 public immutable SHARE_DECIMALS

Functions

constructor

Creates staked oracle for a vault.

constructor(
    address _vault,
    address _underlyingOracle
) ;

Parameters

price

Returns price of 1 vault share including accrued yield.

function price() external view override returns (uint256);

Returns

Errors

StakedOracle__InvalidPrice

Thrown when underlying oracle returns zero price.

error StakedOracle__InvalidPrice();

StakedOracle__ZeroAddress

Thrown when zero address provided to constructor.

error StakedOracle__ZeroAddress();

Contents

• interfaces
• libraries
• modules
• CfdEngine
• CfdEnginePlanTypes
• CfdMath
• CfdTypes
• HousePool
• MarginClearinghouse
• OrderRouter
• TrancheVault

Contents

• ICfdEngine
• ICfdVault
• IHousePool
• IMarginClearinghouse
• IOrderRouterAccounting
• ITrancheVaultBootstrap
• IWithdrawGuard

ICfdEngine

Git Source

Stateful CFD trading engine: processes orders, settles funding, and liquidates positions.

Functions

clearinghouse

Margin clearinghouse address used for account margin locking/unlocking

function clearinghouse() external view returns (address);

orderRouter

Current order router allowed to execute orders through the engine.

function orderRouter() external view returns (address);

USDC

Settlement token used for fees, margin, and payouts

function USDC() external view returns (IERC20);

lastMarkPrice

Last mark price observed by the engine (8 decimals)

function lastMarkPrice() external view returns (uint256);

processOrder

Settles funding and processes an open/close order at the given oracle price

function processOrder(
    CfdTypes.Order memory order,
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc,
    uint64 publishTime
) external;

Parameters

processOrderTyped

Router-facing order execution entrypoint with typed business-rule failures.

Reverts with CfdEngine__TypedOrderFailure for expected order invalidations so the router can apply deterministic failed-order bounty policy without selector matching.

function processOrderTyped(
    CfdTypes.Order memory order,
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc,
    uint64 publishTime
) external;

previewOpenRevertCode

Returns the current open-path revert code using canonical vault depth and a caller-supplied oracle snapshot.

function previewOpenRevertCode(
    bytes32 accountId,
    CfdTypes.Side side,
    uint256 sizeDelta,
    uint256 marginDelta,
    uint256 oraclePrice,
    uint64 publishTime
) external view returns (uint8 code);

previewOpenFailurePolicyCategory

Returns the semantic commit-time policy category for the current open-path invalidation, if any.

function previewOpenFailurePolicyCategory(
    bytes32 accountId,
    CfdTypes.Side side,
    uint256 sizeDelta,
    uint256 marginDelta,
    uint256 oraclePrice,
    uint64 publishTime
) external view returns (CfdEnginePlanTypes.OpenFailurePolicyCategory category);

recordDeferredClearerBounty

Records a deferred clearer bounty when immediate vault payment is unavailable.

Deferred keeper bounties are later claimed as clearinghouse credit, not direct wallet transfer.

function recordDeferredClearerBounty(
    address keeper,
    uint256 amountUsdc
) external;

getDeferredClaimHead

function getDeferredClaimHead() external view returns (DeferredClaim memory claim);

getDeferredTraderStatus

function getDeferredTraderStatus(
    bytes32 accountId
) external view returns (DeferredTraderStatus memory status);

getDeferredClearerStatus

function getDeferredClearerStatus(
    address keeper
) external view returns (DeferredClearerStatus memory status);

reserveCloseOrderExecutionBounty

Reserves close-order execution bounty from free settlement first, then active position margin.

function reserveCloseOrderExecutionBounty(
    bytes32 accountId,
    uint256 amountUsdc,
    address recipient
) external;

absorbRouterCancellationFee

Pulls router-custodied cancellation fees into protocol revenue.

function absorbRouterCancellationFee(
    uint256 amountUsdc
) external;

recordRouterProtocolFee

Books router-delivered protocol-owned inflow as accumulated fees after the router has already paid the vault.

function recordRouterProtocolFee(
    uint256 amountUsdc
) external;

liquidatePosition

Liquidates an undercollateralized position, returns keeper bounty in USDC

function liquidatePosition(
    bytes32 accountId,
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc,
    uint64 publishTime
) external returns (uint256 keeperBountyUsdc);

Parameters

Returns

previewLiquidation

Canonical liquidation preview using the vault’s current accounted depth.

function previewLiquidation(
    bytes32 accountId,
    uint256 oraclePrice
) external view returns (LiquidationPreview memory preview);

simulateLiquidation

Hypothetical liquidation simulation at a caller-supplied vault depth.

function simulateLiquidation(
    bytes32 accountId,
    uint256 oraclePrice,
    uint256 vaultDepthUsdc
) external view returns (LiquidationPreview memory preview);

getSideState

Returns the accounting state for a given side.

function getSideState(
    CfdTypes.Side side
) external view returns (SideState memory);

getMaxLiability

Worst-case directional liability after taking the max of bull/bear payout bounds.

function getMaxLiability() external view returns (uint256);

getAccountLedgerView

Compact per-account ledger view spanning clearinghouse, router escrow, and deferred trader payout state.

function getAccountLedgerView(
    bytes32 accountId
) external view returns (AccountLedgerView memory viewData);

getAccountLedgerSnapshot

Expanded per-account ledger snapshot for debugging account health and settlement reachability across protocol components.

function getAccountLedgerSnapshot(
    bytes32 accountId
) external view returns (AccountLedgerSnapshot memory snapshot);

getProtocolAccountingSnapshot

Canonical protocol-wide accounting snapshot across physical assets, liabilities, fees, bad debt, and deferred obligations.

function getProtocolAccountingSnapshot() external view returns (ProtocolAccountingSnapshot memory snapshot);

accumulatedFeesUsdc

Accumulated execution fees awaiting withdrawal (6 decimals)

function accumulatedFeesUsdc() external view returns (uint256);

getWithdrawalReservedUsdc

Total withdrawal reserve required by current protocol liabilities.

function getWithdrawalReservedUsdc() external view returns (uint256);

getHousePoolInputSnapshot

Canonical accounting snapshot consumed by HousePool.

function getHousePoolInputSnapshot(
    uint256 markStalenessLimit
) external view returns (HousePoolInputSnapshot memory snapshot);

Parameters

getHousePoolStatusSnapshot

Canonical non-accounting market/status snapshot consumed by HousePool.

function getHousePoolStatusSnapshot() external view returns (HousePoolStatusSnapshot memory snapshot);

totalDeferredPayoutUsdc

Deferred profitable-close payouts still owed to traders.

function totalDeferredPayoutUsdc() external view returns (uint256);

totalDeferredClearerBountyUsdc

Deferred liquidation bounties still owed after failed immediate payout.

function totalDeferredClearerBountyUsdc() external view returns (uint256);

deferredClaimHeadId

function deferredClaimHeadId() external view returns (uint64);

getUnrealizedTraderPnl

Aggregate unrealized PnL of all open positions at lastMarkPrice. Positive = traders winning (house liability). Negative = traders losing (house asset).

function getUnrealizedTraderPnl() external view returns (int256);

getUnrealizedFundingPnl

Aggregate unrealized funding PnL across all open positions. Positive = traders are net funding receivers (vault liability).

function getUnrealizedFundingPnl() external view returns (int256);

getCappedFundingPnl

Aggregate unrealized funding PnL with negative per-side funding capped by backing margin. Positive = traders are net funding receivers after clipping uncollectible debts.

function getCappedFundingPnl() external view returns (int256);

getLiabilityOnlyFundingPnl

Aggregate funding liabilities only, excluding any trader debts owed to the vault. Used by withdrawal firewalls that must assume funding receivables are uncollectible until physically seized.

function getLiabilityOnlyFundingPnl() external view returns (uint256);

getVaultMtmAdjustment

Combined MtM liability: per-side (PnL + funding), clamped at zero. Positive = vault owes traders (unrealized liability). Zero = traders losing or neutral. Unrealized trader losses are not counted as vault assets.

function getVaultMtmAdjustment() external view returns (uint256);

lastMarkTime

Timestamp of the last mark price update

function lastMarkTime() external view returns (uint64);

hasLiveLiability

Returns true when the engine currently has open bounded liability that depends on mark freshness.

function hasLiveLiability() external view returns (bool);

syncFunding

Materializes accrued funding into storage so subsequent reads reflect current state.

function syncFunding() external;

updateMarkPrice

Push a fresh mark price without processing an order

function updateMarkPrice(
    uint256 price,
    uint64 publishTime
) external;

Parameters

CAP_PRICE

Protocol cap price (8 decimals). Oracle prices are clamped to this.

function CAP_PRICE() external view returns (uint256);

isFadWindow

True during weekend FX closure or admin-configured FAD days

function isFadWindow() external view returns (bool);

fadMaxStaleness

Maximum oracle staleness allowed during FAD windows

function fadMaxStaleness() external view returns (uint256);

isOracleFrozen

True only when FX markets are actually closed and oracle freshness can be relaxed.

function isOracleFrozen() external view returns (bool);

hasOpenPosition

Returns true when the account currently has an open position.

function hasOpenPosition(
    bytes32 accountId
) external view returns (bool);

getPositionSize

Returns the current position size for an account (18 decimals).

function getPositionSize(
    bytes32 accountId
) external view returns (uint256);

getPositionSide

Returns the stored side for an open position.

function getPositionSide(
    bytes32 accountId
) external view returns (CfdTypes.Side);

degradedMode

True when the engine has latched degraded mode after a close revealed insolvency.

function degradedMode() external view returns (bool);

fadDayOverrides

Whether a given day number is an admin-configured FAD override

function fadDayOverrides(
    uint256 dayNumber
) external view returns (bool);

getProtocolPhase

function getProtocolPhase() external view returns (ProtocolPhase);

getProtocolStatus

function getProtocolStatus() external view returns (ProtocolStatus memory);

Errors

CfdEngine__TypedOrderFailure

error CfdEngine__TypedOrderFailure(
    CfdEnginePlanTypes.ExecutionFailurePolicyCategory failureCategory, uint8 failureCode, bool isClose
);

CfdEngine__MarkPriceOutOfOrder

error CfdEngine__MarkPriceOutOfOrder();

Structs

AccountLedgerView

Compact per-account ledger view spanning trader-owned settlement buckets and router-reserved order state.

settlementBalanceUsdc, freeSettlementUsdc, activePositionMarginUsdc, otherLockedMarginUsdc, and deferredPayoutUsdc are trader-owned value or obligations recorded by the protocol. activePositionMarginUsdc is the canonical clearinghouse custody bucket for live position backing, while engine economic position margin is exposed separately on AccountLedgerSnapshot.margin. executionEscrowUsdc is router-custodied order bounty escrow attributed to the account. committedMarginUsdc remains trader-owned settlement reserved for queued orders inside the clearinghouse.

struct AccountLedgerView {
    uint256 settlementBalanceUsdc;
    uint256 freeSettlementUsdc;
    uint256 activePositionMarginUsdc;
    uint256 otherLockedMarginUsdc;
    uint256 executionEscrowUsdc;
    uint256 committedMarginUsdc;
    uint256 deferredPayoutUsdc;
    uint256 pendingOrderCount;
}

AccountLedgerSnapshot

Expanded per-account ledger snapshot for debugging account health, reachability, and queued-order state.

Extends AccountLedgerView with typed clearinghouse locked-margin buckets, terminal settlement reachability, equity, buying power, and live position risk. margin is the engine’s economic position margin, while positionMarginBucketUsdc is the clearinghouse custody bucket that should back it.

struct AccountLedgerSnapshot {
    uint256 settlementBalanceUsdc;
    uint256 freeSettlementUsdc;
    uint256 activePositionMarginUsdc;
    uint256 otherLockedMarginUsdc;
    uint256 positionMarginBucketUsdc;
    uint256 committedOrderMarginBucketUsdc;
    uint256 reservedSettlementBucketUsdc;
    uint256 executionEscrowUsdc;
    uint256 committedMarginUsdc;
    uint256 deferredPayoutUsdc;
    uint256 pendingOrderCount;
    uint256 closeReachableUsdc;
    uint256 terminalReachableUsdc;
    uint256 accountEquityUsdc;
    uint256 freeBuyingPowerUsdc;
    bool hasPosition;
    CfdTypes.Side side;
    uint256 size;
    uint256 margin;
    uint256 entryPrice;
    int256 unrealizedPnlUsdc;
    int256 pendingFundingUsdc;
    int256 netEquityUsdc;
    bool liquidatable;
}

ProtocolAccountingSnapshot

struct ProtocolAccountingSnapshot {
    uint256 vaultAssetsUsdc;
    uint256 netPhysicalAssetsUsdc;
    uint256 maxLiabilityUsdc;
    uint256 effectiveSolvencyAssetsUsdc;
    uint256 withdrawalReservedUsdc;
    uint256 freeUsdc;
    uint256 accumulatedFeesUsdc;
    uint256 accumulatedBadDebtUsdc;
    int256 cappedFundingPnlUsdc;
    uint256 liabilityOnlyFundingPnlUsdc;
    uint256 totalDeferredPayoutUsdc;
    uint256 totalDeferredClearerBountyUsdc;
    bool degradedMode;
    bool hasLiveLiability;
}

HousePoolInputSnapshot

struct HousePoolInputSnapshot {
    uint256 physicalAssetsUsdc;
    uint256 netPhysicalAssetsUsdc;
    uint256 maxLiabilityUsdc;
    uint256 withdrawalFundingLiabilityUsdc;
    uint256 unrealizedMtmLiabilityUsdc;
    uint256 deferredTraderPayoutUsdc;
    uint256 deferredClearerBountyUsdc;
    uint256 protocolFeesUsdc;
    bool markFreshnessRequired;
    uint256 maxMarkStaleness;
}

HousePoolStatusSnapshot

struct HousePoolStatusSnapshot {
    uint64 lastMarkTime;
    bool oracleFrozen;
    bool degradedMode;
}

SideState

struct SideState {
    uint256 maxProfitUsdc;
    uint256 openInterest;
    uint256 entryNotional;
    uint256 totalMargin;
    int256 fundingIndex;
    int256 entryFunding;
}

LiquidationPreview

struct LiquidationPreview {
    bool liquidatable;
    uint256 oraclePrice;
    int256 equityUsdc;
    int256 pnlUsdc;
    int256 fundingUsdc;
    uint256 reachableCollateralUsdc;
    uint256 keeperBountyUsdc;
    uint256 seizedCollateralUsdc;
    uint256 settlementRetainedUsdc;
    uint256 freshTraderPayoutUsdc;
    uint256 existingDeferredConsumedUsdc;
    uint256 existingDeferredRemainingUsdc;
    uint256 immediatePayoutUsdc;
    uint256 deferredPayoutUsdc;
    uint256 badDebtUsdc;
    bool triggersDegradedMode;
    bool postOpDegradedMode;
    uint256 effectiveAssetsAfterUsdc;
    uint256 maxLiabilityAfterUsdc;
    int256 solvencyFundingPnlUsdc;
}

DeferredClaim

struct DeferredClaim {
    DeferredClaimType claimType;
    bytes32 accountId;
    address keeper;
    uint256 remainingUsdc;
    uint64 prevClaimId;
    uint64 nextClaimId;
}

DeferredTraderStatus

struct DeferredTraderStatus {
    uint64 claimId;
    uint256 deferredPayoutUsdc;
    bool isHead;
    bool claimableNow;
}

DeferredClearerStatus

struct DeferredClearerStatus {
    uint64 claimId;
    uint256 deferredBountyUsdc;
    bool isHead;
    bool claimableNow;
}

ProtocolStatus

struct ProtocolStatus {
    ProtocolPhase phase;
    uint64 lastMarkTime;
    uint256 lastMarkPrice;
    bool oracleFrozen;
    bool fadWindow;
    uint256 fadMaxStaleness;
}

Enums

DeferredClaimType

enum DeferredClaimType {
    TraderPayout,
    ClearerBounty
}

ProtocolPhase

High-level protocol lifecycle used by external status consumers. Active means the engine is wired and the vault has enabled live risk-taking.

enum ProtocolPhase {
    Configuring,
    Active,
    Degraded
}

ICfdVault

Git Source

Vault that custodies USDC backing the CFD trading system.

Functions

totalAssets

Canonical economic USDC backing recognized by the vault (6 decimals). Ignores unsolicited positive token transfers until explicitly accounted, but still reflects raw-balance shortfalls if assets leave the vault unexpectedly.

function totalAssets() external view returns (uint256);

payOut

Transfers USDC from the vault to a recipient

function payOut(
    address recipient,
    uint256 amount
) external;

Parameters

recordProtocolInflow

Increases canonical vault assets to recognize a legitimate protocol-owned inflow.

This is the controlled accounting path for endogenous protocol gains that should increase economic vault depth. It does not require raw excess to be present and may also be used to restore canonical accounting after a raw-balance shortfall has already reduced totalAssets() via the min(rawBalance, accountedAssets) boundary. Reverts if the caller is unauthorized.

function recordProtocolInflow(
    uint256 amount
) external;

recordRecapitalizationInflow

Records an explicit recapitalization inflow intended to restore senior first.

function recordRecapitalizationInflow(
    uint256 amount
) external;

recordTradingRevenueInflow

Records LP-owned trading revenue and directly attaches it to seeded claimants when both tranches are otherwise at zero principal.

function recordTradingRevenueInflow(
    uint256 amount
) external;

markStalenessLimit

Maximum age for mark price freshness checks outside FAD mode (seconds)

function markStalenessLimit() external view returns (uint256);

isSeedLifecycleComplete

Returns true once both tranche seed positions exist.

function isSeedLifecycleComplete() external view returns (bool);

hasSeedLifecycleStarted

Returns true if bootstrap seeding has started for either tranche.

function hasSeedLifecycleStarted() external view returns (bool);

canAcceptOrdinaryDeposits

Returns true once ordinary LP deposits are allowed.

function canAcceptOrdinaryDeposits() external view returns (bool);

canIncreaseRisk

Returns true once risk-increasing trader actions are allowed.

function canIncreaseRisk() external view returns (bool);

isTradingActive

Returns true if owner has activated trading after seed completion.

function isTradingActive() external view returns (bool);

IHousePool

Git Source

Two-tranche USDC pool that acts as counterparty to CFD traders. Senior tranche earns fixed yield; junior absorbs first-loss and excess profit.

Functions

seniorPrincipal

Total USDC attributed to the senior tranche (6 decimals)

function seniorPrincipal() external view returns (uint256);

juniorPrincipal

Total USDC attributed to the junior tranche (6 decimals)

function juniorPrincipal() external view returns (uint256);

seniorHighWaterMark

Senior high-water mark used to block dilutive recapitalizing deposits.

function seniorHighWaterMark() external view returns (uint256);

unassignedAssets

Accounted LP assets currently quarantined pending explicit bootstrap / assignment (6 decimals)

function unassignedAssets() external view returns (uint256);

depositSenior

function depositSenior(
    uint256 amount
) external;

withdrawSenior

function withdrawSenior(
    uint256 amount,
    address receiver
) external;

depositJunior

function depositJunior(
    uint256 amount
) external;

withdrawJunior

function withdrawJunior(
    uint256 amount,
    address receiver
) external;

assignUnassignedAssets

Explicitly bootstraps quarantined LP assets into a tranche and mints matching shares.

function assignUnassignedAssets(
    bool toSenior,
    address receiver
) external;

initializeSeedPosition

Seeds a tranche with permanent share-backed minimum ownership using real USDC.

Canonical deployment should initialize both tranche seeds before enabling ordinary LP lifecycle.

function initializeSeedPosition(
    bool toSenior,
    uint256 amount,
    address receiver
) external;

getMaxSeniorWithdraw

Max withdrawable by senior, capped by free USDC

function getMaxSeniorWithdraw() external view returns (uint256);

getMaxJuniorWithdraw

Max withdrawable by junior, subordinated behind senior

function getMaxJuniorWithdraw() external view returns (uint256);

getPendingTrancheState

Read-only tranche state as if reconcile() ran immediately with current inputs.

function getPendingTrancheState()
    external
    view
    returns (
        uint256 seniorPrincipalUsdc,
        uint256 juniorPrincipalUsdc,
        uint256 maxSeniorWithdrawUsdc,
        uint256 maxJuniorWithdrawUsdc
    );

Returns

reconcile

Settles revenue/loss waterfall between tranches

function reconcile() external;

isWithdrawalLive

Whether withdrawals are currently possible (not degraded, mark is fresh)

function isWithdrawalLive() external view returns (bool);

hasSeedLifecycleStarted

function hasSeedLifecycleStarted() external view returns (bool);

canAcceptOrdinaryDeposits

function canAcceptOrdinaryDeposits() external view returns (bool);

canAcceptTrancheDeposits

function canAcceptTrancheDeposits(
    bool isSenior
) external view returns (bool);

canIncreaseRisk

function canIncreaseRisk() external view returns (bool);

isTradingActive

function isTradingActive() external view returns (bool);

IMarginClearinghouse

Git Source

USDC-only cross-margin account system that holds settlement balances and settles PnL for CFD positions.

Functions

balanceUsdc

Returns the settlement USDC balance for an account.

function balanceUsdc(
    bytes32 accountId
) external view returns (uint256);

lockedMarginUsdc

Returns the locked USDC margin for an account

function lockedMarginUsdc(
    bytes32 accountId
) external view returns (uint256);

getLockedMarginBuckets

Returns the typed locked-margin buckets for an account.

function getLockedMarginBuckets(
    bytes32 accountId
) external view returns (LockedMarginBuckets memory buckets);

getOrderReservation

Returns the reservation record for a specific order id.

function getOrderReservation(
    uint64 orderId
) external view returns (OrderReservation memory reservation);

getAccountReservationSummary

Returns the aggregate active reservation summary for an account.

function getAccountReservationSummary(
    bytes32 accountId
) external view returns (AccountReservationSummary memory summary);

lockPositionMargin

Locks trader-owned settlement into the active position margin bucket.

function lockPositionMargin(
    bytes32 accountId,
    uint256 amountUsdc
) external;

unlockPositionMargin

Unlocks active position margin back into free settlement.

function unlockPositionMargin(
    bytes32 accountId,
    uint256 amountUsdc
) external;

lockCommittedOrderMargin

Locks trader-owned settlement into the committed-order bucket reserved for queued open orders.

function lockCommittedOrderMargin(
    bytes32 accountId,
    uint256 amountUsdc
) external;

reserveCommittedOrderMargin

Reserves committed-order margin for a specific order id inside the clearinghouse reservation ledger.

function reserveCommittedOrderMargin(
    bytes32 accountId,
    uint64 orderId,
    uint256 amountUsdc
) external;

unlockCommittedOrderMargin

Unlocks committed-order margin back into free settlement when a queued open order is released.

function unlockCommittedOrderMargin(
    bytes32 accountId,
    uint256 amountUsdc
) external;

releaseOrderReservation

Releases any remaining reservation balance for an order back into free settlement.

function releaseOrderReservation(
    uint64 orderId
) external returns (uint256 releasedUsdc);

releaseOrderReservationIfActive

Releases any remaining reservation balance for an order if it is still active.

function releaseOrderReservationIfActive(
    uint64 orderId
) external returns (uint256 releasedUsdc);

consumeOrderReservation

Consumes a specific amount from an order reservation, capped by its remaining balance.

function consumeOrderReservation(
    uint64 orderId,
    uint256 amountUsdc
) external returns (uint256 consumedUsdc);

consumeAccountOrderReservations

Consumes active order reservations for an account in FIFO reservation order.

function consumeAccountOrderReservations(
    bytes32 accountId,
    uint256 amountUsdc
) external returns (uint256 consumedUsdc);

consumeOrderReservationsById

Consumes the supplied active order reservations in FIFO order until the requested amount is exhausted.

function consumeOrderReservationsById(
    uint64[] calldata orderIds,
    uint256 amountUsdc
) external returns (uint256 consumedUsdc);

lockReservedSettlement

Locks settlement into a reserved bucket excluded from generic order/position margin release paths.

function lockReservedSettlement(
    bytes32 accountId,
    uint256 amountUsdc
) external;

unlockReservedSettlement

Unlocks settlement from the reserved bucket back into free settlement.

function unlockReservedSettlement(
    bytes32 accountId,
    uint256 amountUsdc
) external;

settleUsdc

Adjusts USDC balance for funding, PnL, or rebates (+credit, -debit)

function settleUsdc(
    bytes32 accountId,
    int256 amount
) external;

creditSettlementAndLockMargin

Credits settlement USDC and locks the same amount as active margin.

function creditSettlementAndLockMargin(
    bytes32 accountId,
    uint256 amountUsdc
) external;

applyOpenCost

Applies an open/increase trade cost by debiting or crediting settlement and updating locked margin.

function applyOpenCost(
    bytes32 accountId,
    uint256 marginDeltaUsdc,
    int256 tradeCostUsdc,
    address recipient
) external returns (int256 netMarginChangeUsdc);

consumeFundingLoss

Consumes funding loss from free settlement plus the active position margin bucket.

function consumeFundingLoss(
    bytes32 accountId,
    uint256 lockedPositionMarginUsdc,
    uint256 lossUsdc,
    address recipient
) external returns (uint256 marginConsumedUsdc, uint256 freeSettlementConsumedUsdc, uint256 uncoveredUsdc);

consumeCloseLoss

Consumes close-path losses from settlement buckets while preserving the remaining live position margin and reserved escrow.

function consumeCloseLoss(
    bytes32 accountId,
    uint64[] calldata reservationOrderIds,
    uint256 lossUsdc,
    uint256 protectedLockedMarginUsdc,
    bool includeOtherLockedMargin,
    address recipient
) external returns (uint256 seizedUsdc, uint256 shortfallUsdc);

applyLiquidationSettlementPlan

Applies a pre-planned liquidation settlement mutation while preserving reserved escrow.

function applyLiquidationSettlementPlan(
    bytes32 accountId,
    uint64[] calldata reservationOrderIds,
    LiquidationSettlementPlan calldata plan,
    address recipient
) external returns (uint256 seizedUsdc);

seizeUsdc

Transfers settlement USDC from an account to a recipient (losses, fees, or bad debt)

function seizeUsdc(
    bytes32 accountId,
    uint256 amount,
    address recipient
) external;

seizePositionMarginUsdc

Transfers settlement USDC from active position margin to a recipient and unlocks the same amount.

function seizePositionMarginUsdc(
    bytes32 accountId,
    uint256 amount,
    address recipient
) external;

getAccountUsdcBuckets

function getAccountUsdcBuckets(
    bytes32 accountId
) external view returns (AccountUsdcBuckets memory buckets);

getAccountEquityUsdc

Returns total account equity in settlement USDC (6 decimals)

function getAccountEquityUsdc(
    bytes32 accountId
) external view returns (uint256);

getFreeBuyingPowerUsdc

Returns strictly free buying power after subtracting locked margin (6 decimals)

function getFreeBuyingPowerUsdc(
    bytes32 accountId
) external view returns (uint256);

getFreeSettlementBalanceUsdc

Returns free settlement-asset balance after subtracting locked margin (6 decimals)

function getFreeSettlementBalanceUsdc(
    bytes32 accountId
) external view returns (uint256);

getTerminalReachableUsdc

Returns settlement-asset balance reachable during a terminal settlement path.

function getTerminalReachableUsdc(
    bytes32 accountId
) external view returns (uint256);

getSettlementReachableUsdc

Returns settlement-asset balance reachable for a terminal or partial settlement path.

Protects only the explicitly supplied remaining locked margin bucket and treats all other settlement-asset balance as reachable for loss collection.

function getSettlementReachableUsdc(
    bytes32 accountId,
    uint256 protectedLockedMarginUsdc
) external view returns (uint256);

Structs

LockedMarginBuckets

struct LockedMarginBuckets {
    // Canonical custody bucket backing currently live positions.
    uint256 positionMarginUsdc;
    uint256 committedOrderMarginUsdc;
    uint256 reservedSettlementUsdc;
    uint256 totalLockedMarginUsdc;
}

OrderReservation

struct OrderReservation {
    bytes32 accountId;
    ReservationBucket bucket;
    ReservationStatus status;
    uint96 originalAmountUsdc;
    uint96 remainingAmountUsdc;
}

AccountReservationSummary

struct AccountReservationSummary {
    uint256 activeCommittedOrderMarginUsdc;
    uint256 activeReservedSettlementUsdc;
    uint256 activeReservationCount;
}

AccountUsdcBuckets

struct AccountUsdcBuckets {
    uint256 settlementBalanceUsdc;
    uint256 totalLockedMarginUsdc;
    uint256 activePositionMarginUsdc;
    uint256 otherLockedMarginUsdc;
    uint256 freeSettlementUsdc;
}

LiquidationSettlementPlan

struct LiquidationSettlementPlan {
    uint256 settlementRetainedUsdc;
    uint256 settlementSeizedUsdc;
    uint256 freshTraderPayoutUsdc;
    uint256 badDebtUsdc;
    uint256 positionMarginUnlockedUsdc;
    uint256 otherLockedMarginUnlockedUsdc;
}

Enums

MarginBucket

enum MarginBucket {
    Position,
    CommittedOrder,
    ReservedSettlement
}

ReservationBucket

enum ReservationBucket {
    CommittedOrder,
    ReservedSettlement
}

ReservationStatus

enum ReservationStatus {
    None,
    Active,
    Consumed,
    Released
}

IOrderRouterAccounting

Git Source

Shared accounting-facing subset of OrderRouter used by engine views and margin bookkeeping.

Functions

syncMarginQueue

Prunes any zero-remaining committed-order reservations out of the router’s margin queue for an account.

function syncMarginQueue(
    bytes32 accountId
) external;

getAccountEscrow

Returns aggregate queued escrow attributed to an account across all pending orders.

function getAccountEscrow(
    bytes32 accountId
) external view returns (AccountEscrowView memory escrow);

getAccountOrderSummary

Returns aggregate queued order state attributed to an account.

Committed margin value is derived from the clearinghouse reservation summary; the router only owns queue structure.

function getAccountOrderSummary(
    bytes32 accountId
) external view returns (AccountOrderSummary memory summary);

getPendingOrdersForAccount

Returns pending orders for an account with escrow-aware queue details.

function getPendingOrdersForAccount(
    bytes32 accountId
) external view returns (PendingOrderView[] memory pending);

pendingOrderCounts

Returns the number of pending orders currently attributed to an account.

function pendingOrderCounts(
    bytes32 accountId
) external view returns (uint256);

getMarginReservationIds

Returns the current router-maintained margin-queue order ids for an account in FIFO order.

This is a structural traversal helper; committed-margin value remains owned by the clearinghouse reservation ledger.

function getMarginReservationIds(
    bytes32 accountId
) external view returns (uint64[] memory orderIds);

Structs

AccountEscrowView

Router/accounting view of queued order escrow attributed to an account.

committedMarginUsdc is derived from canonical MarginClearinghouse reservation state. executionBountyUsdc is router-custodied bounty escrow reserved for queued orders.

struct AccountEscrowView {
    uint256 committedMarginUsdc;
    uint256 executionBountyUsdc;
    uint256 pendingOrderCount;
}

AccountOrderSummary

struct AccountOrderSummary {
    uint256 pendingOrderCount;
    uint256 pendingCloseSize;
    uint256 committedMarginUsdc;
    uint256 executionBountyUsdc;
    bool hasTerminalCloseQueued;
}

PendingOrderView

struct PendingOrderView {
    uint64 orderId;
    bool isClose;
    CfdTypes.Side side;
    uint256 sizeDelta;
    uint256 marginDelta;
    uint256 targetPrice;
    uint64 commitTime;
    uint64 commitBlock;
    uint64 retryAfterTimestamp;
    uint256 committedMarginUsdc;
    uint256 executionBountyUsdc;
}

Enums

OrderStatus

enum OrderStatus {
    None,
    Pending,
    Executed,
    Failed
}

ITrancheVaultBootstrap

Git Source

Functions

previewDeposit

function previewDeposit(
    uint256 assets
) external view returns (uint256 shares);

bootstrapMint

function bootstrapMint(
    uint256 shares,
    address receiver
) external;

configureSeedPosition

function configureSeedPosition(
    address receiver,
    uint256 floorShares
) external;

IWithdrawGuard

Git Source

Pre-withdrawal hook that prevents clearinghouse withdrawals while positions are open.

Functions

checkWithdraw

Reverts if the account is not allowed to withdraw from the clearinghouse. Implementations may inspect current clearinghouse balances after tentative debit.

function checkWithdraw(
    bytes32 accountId
) external view;

Parameters

Contents

• CashPriorityLib
• CfdEnginePlanLib
• CfdEnginePlanLib constants
• CfdEngineSettlementLib
• CfdEngineSnapshotsLib
• CloseAccountingLib
• HousePoolAccountingLib
• HousePoolFreshnessLib
• HousePoolPendingLivePlanLib
• HousePoolPendingPreviewLib
• HousePoolReconcilePlanLib
• HousePoolSeedLifecycleLib
• HousePoolTrancheGateLib
• HousePoolWaterfallAccountingLib
• HousePoolWithdrawalPreviewLib
• LiquidationAccountingLib
• MarginClearinghouseAccountingLib
• MarketCalendarLib
• OpenAccountingLib
• OrderFailurePolicyLib
• OrderOraclePolicyLib
• PositionRiskAccountingLib
• SolvencyAccountingLib
• WithdrawalAccountingLib

CashPriorityLib

Git Source

Functions

reserveFreshPayouts

function reserveFreshPayouts(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc
) internal pure returns (SeniorCashReservation memory reservation);

reserveDeferredHeadClaim

function reserveDeferredHeadClaim(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc,
    uint256 headClaimAmountUsdc
) internal pure returns (SeniorCashReservation memory reservation);

reservedSeniorCashUsdc

function reservedSeniorCashUsdc(
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc
) internal pure returns (uint256);

availableCashForFreshPayouts

function availableCashForFreshPayouts(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc
) internal pure returns (uint256);

availableCashForDeferredClaim

function availableCashForDeferredClaim(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc,
    uint256 claimAmountUsdc
) internal pure returns (uint256);

availableCashForProtocolFeeWithdrawal

function availableCashForProtocolFeeWithdrawal(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc
) internal pure returns (uint256);

canPayFreshPayout

function canPayFreshPayout(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc,
    uint256 amountUsdc
) internal pure returns (bool);

canPayDeferredClaim

function canPayDeferredClaim(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc,
    uint256 claimAmountUsdc
) internal pure returns (bool);

canWithdrawProtocolFees

function canWithdrawProtocolFees(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc,
    uint256 amountUsdc
) internal pure returns (bool);

_saturatingSub

function _saturatingSub(
    uint256 lhs,
    uint256 rhs
) private pure returns (uint256);

_buildSeniorCashReservation

function _buildSeniorCashReservation(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc
) private pure returns (SeniorCashReservation memory reservation);

Structs

SeniorCashReservation

struct SeniorCashReservation {
    uint256 physicalAssetsUsdc;
    uint256 protocolFeesUsdc;
    uint256 deferredTraderPayoutUsdc;
    uint256 deferredClearerBountyUsdc;
    uint256 totalSeniorClaimsUsdc;
    uint256 reservedSeniorCashUsdc;
    uint256 protocolFeeWithdrawalUsdc;
    uint256 freeCashUsdc;
    uint256 headClaimServiceableUsdc;
}

CfdEnginePlanLib

Git Source

Title: CfdEnginePlanLib

Pure plan functions for the CfdEngine plan→apply architecture. Each function takes a RawSnapshot and returns a typed delta describing all effects. No storage reads, no external calls — purely deterministic over memory inputs.

Functions

computeOpenMarginAfter

function computeOpenMarginAfter(
    uint256 marginAfterFunding,
    int256 netMarginChange
) internal pure returns (bool drained, uint256 marginAfter);

computeSideTotalMarginAfterOpen

function computeSideTotalMarginAfterOpen(
    uint256 sideTotalMarginAfterFunding,
    uint256 effectivePositionMarginAfterFunding,
    uint256 positionMarginAfterOpen
) internal pure returns (uint256 sideTotalMarginAfterOpen);

getOpenFailurePolicyCategory

function getOpenFailurePolicyCategory(
    CfdEnginePlanTypes.OpenRevertCode code
) internal pure returns (CfdEnginePlanTypes.OpenFailurePolicyCategory);

getExecutionFailurePolicyCategory

function getExecutionFailurePolicyCategory(
    CfdEnginePlanTypes.OpenRevertCode code
) internal pure returns (CfdEnginePlanTypes.ExecutionFailurePolicyCategory);

getExecutionFailurePolicyCategory

function getExecutionFailurePolicyCategory(
    CfdEnginePlanTypes.CloseRevertCode code
) internal pure returns (CfdEnginePlanTypes.ExecutionFailurePolicyCategory);

_selectedAndOpposite

function _selectedAndOpposite(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    CfdTypes.Side side
)
    private
    pure
    returns (CfdEnginePlanTypes.SideSnapshot memory selected, CfdEnginePlanTypes.SideSnapshot memory opposite);

_absSkewUsdc

function _absSkewUsdc(
    CfdEnginePlanTypes.SideSnapshot memory bull,
    CfdEnginePlanTypes.SideSnapshot memory bear,
    uint256 price
) private pure returns (uint256);

_postOpenSkewUsdc

function _postOpenSkewUsdc(
    CfdEnginePlanTypes.SideSnapshot memory bull,
    CfdEnginePlanTypes.SideSnapshot memory bear,
    CfdTypes.Side side,
    uint256 sizeDelta,
    uint256 price
) private pure returns (uint256);

_computeGlobalFundingPnl

function _computeGlobalFundingPnl(
    CfdEnginePlanTypes.SideSnapshot memory bull,
    CfdEnginePlanTypes.SideSnapshot memory bear
) private pure returns (int256 bullFunding, int256 bearFunding);

_isCollectedFundingLoss

function _isCollectedFundingLoss(
    CfdEnginePlanTypes.FundingPayoutType payoutType
) private pure returns (bool);

_solvencyCappedFundingPnl

function _solvencyCappedFundingPnl(
    CfdEnginePlanTypes.SideSnapshot memory bull,
    CfdEnginePlanTypes.SideSnapshot memory bear
) private pure returns (int256);

_planDeferredPayoutConsumption

function _planDeferredPayoutConsumption(
    uint256 deferredPayoutUsdc,
    uint256 shortfallUsdc,
    bool shortfallAlreadyIncludesDeferred
) private pure returns (uint256 consumedUsdc, uint256 remainingUsdc, uint256 badDebtUsdc);

_planCloseDeferredPayoutConsumption

function _planCloseDeferredPayoutConsumption(
    uint256 deferredPayoutUsdc,
    CfdEngineSettlementLib.CloseSettlementResult memory lossResult
)
    private
    pure
    returns (uint256 consumedUsdc, uint256 remainingUsdc, uint256 feeRecoveredUsdc, uint256 badDebtUsdc);

planGlobalFunding

function planGlobalFunding(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    uint256 executionPrice,
    uint64 publishTime
) internal pure returns (CfdEnginePlanTypes.GlobalFundingDelta memory gfd);

planFunding

function planFunding(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    uint256 executionPrice,
    uint64 publishTime,
    bool isClose,
    bool isFullClose
) internal pure returns (CfdEnginePlanTypes.FundingDelta memory fd);

planOpen

function planOpen(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    CfdTypes.Order memory order,
    uint256 executionPrice,
    uint64 publishTime
) internal pure returns (CfdEnginePlanTypes.OpenDelta memory delta);

_buildPostOpenRiskState

function _buildPostOpenRiskState(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    CfdEnginePlanTypes.OpenDelta memory delta
) private pure returns (PositionRiskAccountingLib.PositionRiskState memory riskState);

_isOpenInsolventAfterPlan

function _isOpenInsolventAfterPlan(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    CfdTypes.Side side,
    CfdEnginePlanTypes.OpenDelta memory delta,
    CfdEnginePlanTypes.SideSnapshot memory bull,
    CfdEnginePlanTypes.SideSnapshot memory bear
) private pure returns (bool);

planClose

function planClose(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    CfdTypes.Order memory order,
    uint256 executionPrice,
    uint64 publishTime
) internal pure returns (CfdEnginePlanTypes.CloseDelta memory delta);

_computeCloseSolvency

function _computeCloseSolvency(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    CfdEnginePlanTypes.CloseDelta memory delta,
    CfdEnginePlanTypes.SideSnapshot memory bull,
    CfdEnginePlanTypes.SideSnapshot memory bear
) private pure returns (CfdEnginePlanTypes.SolvencyPreview memory sp);

_buildCloseSettlementBuckets

function _buildCloseSettlementBuckets(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    uint256 marginToFreeUsdc,
    CfdEnginePlanTypes.FundingDelta memory fd,
    bool includeOtherLockedMargin
) private pure returns (IMarginClearinghouse.AccountUsdcBuckets memory);

planLiquidation

function planLiquidation(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    uint256 executionPrice,
    uint64 publishTime
) internal pure returns (CfdEnginePlanTypes.LiquidationDelta memory delta);

Constants

Git Source

EXECUTION_FEE_BPS

uint256 constant EXECUTION_FEE_BPS = 4

CfdEngineSettlementLib

Git Source

Functions

collectSettlementDeficit

function collectSettlementDeficit(
    uint256 availableUsdc,
    uint256 owedUsdc
) internal pure returns (DebtCollectionResult memory result);

closeSettlementResult

function closeSettlementResult(
    uint256 availableUsdc,
    uint256 owedUsdc,
    uint256 execFeeUsdc
) internal pure returns (CloseSettlementResult memory result);

closeSettlementResultForTerminalBuckets

function closeSettlementResultForTerminalBuckets(
    IMarginClearinghouse.AccountUsdcBuckets memory buckets,
    uint256 protectedLockedMarginUsdc,
    uint256 owedUsdc,
    uint256 execFeeUsdc
) internal pure returns (CloseSettlementResult memory result);

liquidationSettlementResult

function liquidationSettlementResult(
    uint256 accountBalanceUsdc,
    int256 residualUsdc
) internal pure returns (LiquidationSettlementResult memory result);

Structs

DebtCollectionResult

struct DebtCollectionResult {
    uint256 seizedUsdc;
    uint256 shortfallUsdc;
}

CloseSettlementResult

struct CloseSettlementResult {
    uint256 seizedUsdc;
    uint256 shortfallUsdc;
    uint256 collectedExecFeeUsdc;
    uint256 badDebtUsdc;
}

LiquidationSettlementResult

struct LiquidationSettlementResult {
    uint256 targetBalanceUsdc;
    uint256 seizedUsdc;
    uint256 payoutUsdc;
    uint256 badDebtUsdc;
}

CfdEngineSnapshotsLib

Git Source

Functions

buildFundingSnapshot

function buildFundingSnapshot(
    int256 bullFunding,
    int256 bearFunding,
    uint256 totalBullMargin,
    uint256 totalBearMargin
) internal pure returns (FundingSnapshot memory snapshot);

getWithdrawalReservedUsdc

function getWithdrawalReservedUsdc(
    uint256 maxLiability,
    uint256 protocolFees,
    uint256 fundingLiability
) internal pure returns (uint256 reservedUsdc);

Structs

FundingSnapshot

struct FundingSnapshot {
    int256 bullFunding;
    int256 bearFunding;
    int256 solvencyFunding;
    uint256 withdrawalFundingLiability;
}

SolvencySnapshot

struct SolvencySnapshot {
    uint256 physicalAssets;
    uint256 protocolFees;
    uint256 netPhysicalAssets;
    uint256 maxLiability;
    int256 solvencyFunding;
    uint256 effectiveSolvencyAssets;
}

CloseAccountingLib

Git Source

Functions

buildCloseState

function buildCloseState(
    uint256 positionSize,
    uint256 positionMarginUsdc,
    uint256 entryPrice,
    uint256 maxProfitUsdc,
    int256 vpiAccrued,
    CfdTypes.Side side,
    uint256 sizeDelta,
    uint256 oraclePrice,
    uint256 capPrice,
    uint256 preSkewUsdc,
    uint256 postSkewUsdc,
    uint256 vaultDepthUsdc,
    uint256 vpiFactor,
    uint256 executionFeeBps,
    int256 fundingSettlementUsdc
) internal pure returns (CloseState memory state);

Structs

CloseState

struct CloseState {
    int256 realizedPnlUsdc;
    uint256 marginToFreeUsdc;
    uint256 remainingMarginUsdc;
    uint256 remainingSize;
    uint256 maxProfitReductionUsdc;
    int256 proportionalAccrualUsdc;
    int256 vpiDeltaUsdc;
    uint256 executionFeeUsdc;
    int256 netSettlementUsdc;
}

HousePoolAccountingLib

Git Source

Functions

buildWithdrawalSnapshot

function buildWithdrawalSnapshot(
    ICfdEngine.HousePoolInputSnapshot memory engineSnapshot
) internal pure returns (WithdrawalSnapshot memory snapshot);

buildReconcileSnapshot

function buildReconcileSnapshot(
    ICfdEngine.HousePoolInputSnapshot memory engineSnapshot
) internal pure returns (ReconcileSnapshot memory snapshot);

getMarkFreshnessPolicy

function getMarkFreshnessPolicy(
    ICfdEngine.HousePoolInputSnapshot memory accountingSnapshot
) internal pure returns (MarkFreshnessPolicy memory policy);

isMarkFresh

function isMarkFresh(
    uint64 lastMarkTime,
    uint256 limit,
    uint256 currentTimestamp
) internal pure returns (bool);

Structs

WithdrawalSnapshot

struct WithdrawalSnapshot {
    uint256 physicalAssets;
    uint256 maxLiability;
    uint256 protocolFees;
    uint256 reserved;
    uint256 freeUsdc;
}

ReconcileSnapshot

struct ReconcileSnapshot {
    uint256 physicalAssets;
    uint256 protocolFees;
    uint256 deferredLiabilities;
    uint256 cashMinusFees;
    uint256 mtm;
    uint256 distributable;
}

MarkFreshnessPolicy

struct MarkFreshnessPolicy {
    bool required;
    uint256 maxStaleness;
}

HousePoolFreshnessLib

Git Source

Functions

markIsFreshForReconcile

function markIsFreshForReconcile(
    ICfdEngine.HousePoolInputSnapshot memory accountingSnapshot,
    ICfdEngine.HousePoolStatusSnapshot memory statusSnapshot,
    uint256 currentTimestamp
) internal pure returns (bool);

withdrawalsLive

function withdrawalsLive(
    ICfdEngine.HousePoolInputSnapshot memory accountingSnapshot,
    ICfdEngine.HousePoolStatusSnapshot memory statusSnapshot,
    uint256 currentTimestamp
) internal pure returns (bool);

markFresh

function markFresh(
    ICfdEngine.HousePoolInputSnapshot memory accountingSnapshot,
    ICfdEngine.HousePoolStatusSnapshot memory statusSnapshot,
    uint256 currentTimestamp
) internal pure returns (bool);

HousePoolPendingLivePlanLib

Git Source

Functions

planApplyPendingBuckets

function planApplyPendingBuckets(
    HousePoolPendingPreviewLib.PendingAccountingState memory state,
    uint256 currentSeniorPrincipal,
    uint256 pendingRecapitalizationUsdc,
    uint256 pendingTradingRevenueUsdc
) internal pure returns (PendingLivePlan memory plan);

Structs

PendingLivePlan

struct PendingLivePlan {
    HousePoolPendingPreviewLib.PendingAccountingState state;
    bool seniorPrincipalChanged;
}

HousePoolPendingPreviewLib

Git Source

Functions

applyPendingBucketsPreview

function applyPendingBucketsPreview(
    PendingAccountingState memory state,
    uint256 pendingRecapitalizationUsdc,
    uint256 pendingTradingRevenueUsdc
) internal pure;

applyRecapitalizationIntent

function applyRecapitalizationIntent(
    PendingAccountingState memory state,
    uint256 amount
) internal pure;

routeSeededRevenue

function routeSeededRevenue(
    PendingAccountingState memory state,
    uint256 amount
) internal pure;

Structs

PendingAccountingState

struct PendingAccountingState {
    HousePoolWaterfallAccountingLib.WaterfallState waterfall;
    uint256 unassignedAssets;
    uint256 seniorSupply;
    uint256 juniorSupply;
}

HousePoolReconcilePlanLib

Git Source

Functions

planReconcile

function planReconcile(
    HousePoolPendingPreviewLib.PendingAccountingState memory state,
    HousePoolAccountingLib.ReconcileSnapshot memory snapshot,
    uint256 pendingBucketAssets,
    uint256 seniorRateBps,
    uint256 yieldElapsed,
    bool markFresh
) internal pure returns (ReconcilePlan memory plan);

juniorRevenueWithoutOwners

function juniorRevenueWithoutOwners(
    ReconcilePlan memory plan
) internal pure returns (uint256);

Structs

ReconcilePlan

struct ReconcilePlan {
    HousePoolPendingPreviewLib.PendingAccountingState state;
    uint256 yieldAccrued;
    bool markFresh;
    bool juniorSupplyZero;
    bool claimedEquityZero;
    bool revenue;
    uint256 deltaUsdc;
    uint256 juniorPrincipalBeforeRevenue;
}

HousePoolSeedLifecycleLib

Git Source

Functions

isSeedLifecycleComplete

function isSeedLifecycleComplete(
    bool seniorSeedInitialized,
    bool juniorSeedInitialized
) internal pure returns (bool);

hasSeedLifecycleStarted

function hasSeedLifecycleStarted(
    bool seniorSeedInitialized,
    bool juniorSeedInitialized
) internal pure returns (bool);

canAcceptOrdinaryDeposits

function canAcceptOrdinaryDeposits(
    bool seniorSeedInitialized,
    bool juniorSeedInitialized,
    bool isTradingActive
) internal pure returns (bool);

canIncreaseRisk

function canIncreaseRisk(
    bool seniorSeedInitialized,
    bool juniorSeedInitialized,
    bool isTradingActive
) internal pure returns (bool);

tradingActivationReady

function tradingActivationReady(
    bool seniorSeedInitialized,
    bool juniorSeedInitialized
) internal pure returns (bool);

hasPendingBootstrap

function hasPendingBootstrap(
    uint256 unassignedAssets
) internal pure returns (bool);

HousePoolTrancheGateLib

Git Source

Functions

trancheDepositsAllowed

function trancheDepositsAllowed(
    bool ordinaryDepositsAllowed,
    bool paused,
    uint256 unassignedAssets,
    bool markFreshForReconcile,
    uint256 projectedUnassignedAssets,
    bool isSenior,
    uint256 projectedSeniorPrincipal,
    uint256 projectedSeniorHighWaterMark
) internal pure returns (bool);

HousePoolWaterfallAccountingLib

Git Source

Constants

BPS

uint256 internal constant BPS = 10_000

SECONDS_PER_YEAR

uint256 internal constant SECONDS_PER_YEAR = 31_536_000

Functions

accrueSeniorYield

function accrueSeniorYield(
    uint256 seniorPrincipal,
    uint256 seniorRateBps,
    uint256 elapsed
) internal pure returns (uint256);

planReconcile

function planReconcile(
    uint256 seniorPrincipal,
    uint256 juniorPrincipal,
    uint256 distributableUsdc,
    uint256 seniorRateBps,
    uint256 elapsed
) internal pure returns (ReconcilePlan memory plan);

scaleSeniorOnWithdraw

function scaleSeniorOnWithdraw(
    WaterfallState memory state,
    uint256 withdrawAmountUsdc
) internal pure returns (WaterfallState memory nextState);

distributeRevenue

function distributeRevenue(
    WaterfallState memory state,
    uint256 revenueUsdc
) internal pure returns (WaterfallState memory nextState);

absorbLoss

function absorbLoss(
    WaterfallState memory state,
    uint256 lossUsdc
) internal pure returns (WaterfallState memory nextState);

Structs

WaterfallState

struct WaterfallState {
    uint256 seniorPrincipal;
    uint256 juniorPrincipal;
    uint256 unpaidSeniorYield;
    uint256 seniorHighWaterMark;
}

ReconcilePlan

struct ReconcilePlan {
    uint256 yieldAccrued;
    bool isRevenue;
    uint256 deltaUsdc;
}

HousePoolWithdrawalPreviewLib

Git Source

Functions

reserveAssets

function reserveAssets(
    HousePoolAccountingLib.WithdrawalSnapshot memory snapshot,
    uint256 reservedAssets
) internal pure returns (HousePoolAccountingLib.WithdrawalSnapshot memory nextSnapshot);

seniorWithdrawCap

function seniorWithdrawCap(
    uint256 freeUsdc,
    uint256 seniorPrincipal
) internal pure returns (uint256);

juniorWithdrawCap

function juniorWithdrawCap(
    uint256 freeUsdc,
    uint256 seniorPrincipal,
    uint256 juniorPrincipal
) internal pure returns (uint256);

LiquidationAccountingLib

Git Source

Functions

buildLiquidationState

function buildLiquidationState(
    uint256 size,
    uint256 oraclePrice,
    uint256 reachableCollateralUsdc,
    int256 fundingUsdc,
    int256 pnlUsdc,
    uint256 maintMarginBps,
    uint256 minBountyUsdc,
    uint256 bountyBps,
    uint256 tokenScale
) internal pure returns (LiquidationState memory state);

settlementForState

function settlementForState(
    LiquidationState memory state
) internal pure returns (CfdEngineSettlementLib.LiquidationSettlementResult memory result);

Structs

LiquidationState

struct LiquidationState {
    int256 equityUsdc;
    uint256 reachableCollateralUsdc;
    uint256 maintenanceMarginUsdc;
    uint256 keeperBountyUsdc;
}

MarginClearinghouseAccountingLib

Git Source

Functions

buildAccountUsdcBuckets

function buildAccountUsdcBuckets(
    uint256 settlementBalanceUsdc,
    uint256 positionMarginUsdc,
    uint256 committedOrderMarginUsdc,
    uint256 reservedSettlementUsdc
) internal pure returns (IMarginClearinghouse.AccountUsdcBuckets memory buckets);

buildPartialCloseUsdcBuckets

function buildPartialCloseUsdcBuckets(
    uint256 settlementBalanceUsdc,
    uint256 positionMarginUsdc,
    uint256 committedOrderMarginUsdc,
    uint256 reservedSettlementUsdc
) internal pure returns (IMarginClearinghouse.AccountUsdcBuckets memory buckets);

planFundingLossConsumption

function planFundingLossConsumption(
    IMarginClearinghouse.AccountUsdcBuckets memory buckets,
    uint256 lossUsdc
) internal pure returns (SettlementConsumption memory consumption);

getTerminalReachableUsdc

function getTerminalReachableUsdc(
    IMarginClearinghouse.AccountUsdcBuckets memory buckets
) internal pure returns (uint256 reachableUsdc);

getSettlementReachableUsdc

function getSettlementReachableUsdc(
    IMarginClearinghouse.AccountUsdcBuckets memory buckets,
    uint256 protectedLockedMarginUsdc
) internal pure returns (uint256 reachableUsdc);

planTerminalLossConsumption

function planTerminalLossConsumption(
    IMarginClearinghouse.AccountUsdcBuckets memory buckets,
    uint256 protectedLockedMarginUsdc,
    uint256 lossUsdc
) internal pure returns (SettlementConsumption memory consumption);

applyFundingLossMutation

function applyFundingLossMutation(
    IMarginClearinghouse.AccountUsdcBuckets memory,
    SettlementConsumption memory consumption
) internal pure returns (BucketMutation memory mutation);

applyTerminalLossMutation

function applyTerminalLossMutation(
    IMarginClearinghouse.AccountUsdcBuckets memory,
    uint256,
    SettlementConsumption memory consumption
) internal pure returns (BucketMutation memory mutation);

planLiquidationResidual

function planLiquidationResidual(
    IMarginClearinghouse.AccountUsdcBuckets memory buckets,
    int256 residualUsdc
) internal pure returns (LiquidationResidualPlan memory plan);

Structs

SettlementConsumption

struct SettlementConsumption {
    uint256 freeSettlementConsumedUsdc;
    uint256 activeMarginConsumedUsdc;
    uint256 otherLockedMarginConsumedUsdc;
    uint256 totalConsumedUsdc;
    uint256 uncoveredUsdc;
}

BucketMutation

struct BucketMutation {
    uint256 settlementDebitUsdc;
    uint256 positionMarginUnlockedUsdc;
    uint256 otherLockedMarginUnlockedUsdc;
}

LiquidationResidualPlan

struct LiquidationResidualPlan {
    uint256 settlementRetainedUsdc;
    uint256 settlementSeizedUsdc;
    uint256 freshTraderPayoutUsdc;
    uint256 badDebtUsdc;
    BucketMutation mutation;
}

MarketCalendarLib

Git Source

Constants

SECONDS_PER_DAY

uint256 internal constant SECONDS_PER_DAY = 86_400

SECONDS_PER_HOUR

uint256 internal constant SECONDS_PER_HOUR = 3600

Functions

isFadWindow

function isFadWindow(
    uint256 timestamp,
    bool todayOverride,
    bool tomorrowOverride,
    uint256 fadRunwaySeconds
) internal pure returns (bool);

isOracleFrozen

function isOracleFrozen(
    uint256 timestamp,
    bool todayOverride
) internal pure returns (bool);

_dayAndHour

function _dayAndHour(
    uint256 timestamp
) private pure returns (uint256 dayOfWeek, uint256 hourOfDay);

OpenAccountingLib

Git Source

Functions

buildOpenState

function buildOpenState(
    OpenInputs memory inputs
) internal pure returns (OpenState memory state);

effectiveMarginAfterTradeCost

function effectiveMarginAfterTradeCost(
    uint256 marginUsdc,
    int256 tradeCostUsdc
) internal pure returns (uint256 effectiveMarginUsdc);

Structs

OpenInputs

struct OpenInputs {
    uint256 currentSize;
    uint256 currentEntryPrice;
    CfdTypes.Side side;
    uint256 sizeDelta;
    uint256 price;
    uint256 capPrice;
    uint256 preSkewUsdc;
    uint256 postSkewUsdc;
    uint256 vaultDepthUsdc;
    uint256 executionFeeBps;
    int256 currentFundingIndex;
    CfdTypes.RiskParams riskParams;
}

OpenState

struct OpenState {
    uint256 addedMaxProfitUsdc;
    uint256 oldEntryNotional;
    uint256 newEntryPrice;
    uint256 newSize;
    uint256 newEntryNotional;
    uint256 postSkewUsdc;
    int256 positionFundingContribution;
    int256 vpiUsdc;
    uint256 notionalUsdc;
    uint256 executionFeeUsdc;
    int256 tradeCostUsdc;
    uint256 maintenanceMarginUsdc;
    uint256 initialMarginRequirementUsdc;
}

OrderFailurePolicyLib

Git Source

Functions

isPredictablyInvalidOpen

function isPredictablyInvalidOpen(
    CfdEnginePlanTypes.OpenFailurePolicyCategory category
) internal pure returns (bool);

failureDomainForExecutionCategory

function failureDomainForExecutionCategory(
    CfdEnginePlanTypes.ExecutionFailurePolicyCategory category
) internal pure returns (FailureDomain);

bountyPolicyForFailure

function bountyPolicyForFailure(
    FailureContext memory context
) internal pure returns (FailedOrderBountyPolicy);

Structs

RoutedFailure

struct RoutedFailure {
    FailureDomain domain;
    uint8 code;
    bool isClose;
}

FailureContext

struct FailureContext {
    RoutedFailure failure;
    FailureSource source;
    bool closeOnly;
    bool oracleFrozen;
    bool isFad;
    bool degradedMode;
}

Enums

FailedOrderBountyPolicy

enum FailedOrderBountyPolicy {
    None,
    ClearerFull,
    RefundUser
}

FailureSource

enum FailureSource {
    RouterPolicy,
    EngineTyped,
    UntypedRevert,
    Expired
}

FailureDomain

enum FailureDomain {
    UserInvalid,
    ProtocolStateInvalidated,
    Retryable,
    Expired
}

RouterFailureCode

enum RouterFailureCode {
    None,
    CloseOnlyOracleFrozen,
    CloseOnlyFad
}

OrderOraclePolicyLib

Git Source

Functions

getOracleExecutionPolicy

function getOracleExecutionPolicy(
    OracleAction action,
    bool oracleFrozen,
    bool isFad,
    uint256 liveExecutionStaleness,
    uint256 liveLiquidationStaleness,
    uint256 fadMaxStaleness
) internal pure returns (OracleExecutionPolicy memory policy);

isStale

function isStale(
    uint64 oraclePublishTime,
    uint256 maxStaleness,
    uint256 currentTimestamp
) internal pure returns (bool);

Structs

OracleExecutionPolicy

struct OracleExecutionPolicy {
    bool oracleFrozen;
    bool isFad;
    bool closeOnly;
    bool mevChecks;
    uint256 maxStaleness;
}

Enums

OracleAction

enum OracleAction {
    OrderExecution,
    MarkRefresh,
    Liquidation
}

PositionRiskAccountingLib

Git Source

Functions

getPendingFunding

function getPendingFunding(
    CfdTypes.Position memory pos,
    int256 currentIndex
) internal pure returns (int256 fundingUsdc);

previewPendingFunding

function previewPendingFunding(
    CfdTypes.Position memory pos,
    int256 bullFundingIndex,
    int256 bearFundingIndex,
    uint256 lastMarkPrice,
    uint256 bullOi,
    uint256 bearOi,
    uint64 lastFundingTime,
    uint256 currentTimestamp,
    uint256 vaultDepthUsdc,
    CfdTypes.RiskParams memory riskParams
) internal pure returns (int256 fundingUsdc);

computeFundingStep

function computeFundingStep(
    FundingStepInputs memory inputs
) internal pure returns (FundingStepResult memory result);

buildPositionRiskState

function buildPositionRiskState(
    CfdTypes.Position memory pos,
    uint256 price,
    uint256 capPrice,
    int256 pendingFundingUsdc,
    uint256 reachableCollateralUsdc,
    uint256 requiredBps
) internal pure returns (PositionRiskState memory state);

Structs

FundingStepInputs

struct FundingStepInputs {
    uint256 price;
    uint256 bullOi;
    uint256 bearOi;
    uint256 timeDelta;
    uint256 vaultDepthUsdc;
    CfdTypes.RiskParams riskParams;
}

FundingStepResult

struct FundingStepResult {
    uint256 absSkewUsdc;
    int256 bullFundingIndexDelta;
    int256 bearFundingIndexDelta;
}

PositionRiskState

struct PositionRiskState {
    int256 pendingFundingUsdc;
    int256 unrealizedPnlUsdc;
    int256 equityUsdc;
    uint256 currentNotionalUsdc;
    uint256 maintenanceMarginUsdc;
    bool liquidatable;
}

SolvencyAccountingLib

Git Source

Functions

getMaxLiability

function getMaxLiability(
    uint256 bullMaxProfitUsdc,
    uint256 bearMaxProfitUsdc
) internal pure returns (uint256);

getMaxLiabilityAfterClose

function getMaxLiabilityAfterClose(
    uint256 bullMaxProfitUsdc,
    uint256 bearMaxProfitUsdc,
    CfdTypes.Side side,
    uint256 maxProfitReductionUsdc
) internal pure returns (uint256);

buildSolvencyState

function buildSolvencyState(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 maxLiabilityUsdc,
    int256 solvencyFundingPnlUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc
) internal pure returns (SolvencyState memory state);

effectiveAssetsAfterPendingPayout

function effectiveAssetsAfterPendingPayout(
    SolvencyState memory state,
    uint256 pendingVaultPayoutUsdc
) internal pure returns (uint256);

isInsolvent

function isInsolvent(
    SolvencyState memory state
) internal pure returns (bool);

previewPostOpSolvency

function previewPostOpSolvency(
    SolvencyState memory currentState,
    PreviewDelta memory delta,
    bool alreadyDegraded
) internal pure returns (PreviewResult memory result);

_applySignedDelta

function _applySignedDelta(
    uint256 value,
    int256 delta
) private pure returns (uint256 updatedValue);

Structs

PreviewDelta

struct PreviewDelta {
    int256 physicalAssetsDeltaUsdc;
    uint256 protocolFeesDeltaUsdc;
    uint256 maxLiabilityAfterUsdc;
    int256 deferredTraderPayoutDeltaUsdc;
    int256 deferredLiquidationBountyDeltaUsdc;
    uint256 pendingVaultPayoutUsdc;
}

PreviewResult

struct PreviewResult {
    uint256 effectiveAssetsAfterUsdc;
    uint256 maxLiabilityAfterUsdc;
    bool triggersDegradedMode;
    bool postOpDegradedMode;
}

SolvencyState

struct SolvencyState {
    uint256 physicalAssetsUsdc;
    uint256 protocolFeesUsdc;
    uint256 netPhysicalAssetsUsdc;
    uint256 maxLiabilityUsdc;
    int256 solvencyFundingPnlUsdc;
    uint256 deferredTraderPayoutUsdc;
    uint256 deferredClearerBountyUsdc;
    uint256 effectiveAssetsUsdc;
}

WithdrawalAccountingLib

Git Source

Functions

buildWithdrawalState

function buildWithdrawalState(
    uint256 physicalAssetsUsdc,
    uint256 maxLiabilityUsdc,
    uint256 protocolFeesUsdc,
    uint256 fundingLiabilityUsdc,
    uint256 deferredTraderPayoutUsdc,
    uint256 deferredClearerBountyUsdc
) internal pure returns (WithdrawalState memory state);

Structs

WithdrawalState

struct WithdrawalState {
    uint256 physicalAssetsUsdc;
    uint256 maxLiabilityUsdc;
    uint256 protocolFeesUsdc;
    uint256 fundingLiabilityUsdc;
    uint256 deferredTraderPayoutUsdc;
    uint256 deferredClearerBountyUsdc;
    uint256 reservedUsdc;
    uint256 freeUsdc;
}

Contents

• OrderEscrowAccounting

OrderEscrowAccounting

Git Source

Inherits: IOrderRouterAccounting

Constants

engine

ICfdEngine public immutable engine

clearinghouse

IMarginClearinghouse internal immutable clearinghouse

USDC

IERC20 internal immutable USDC

State Variables

orderRecords

mapping(uint64 => OrderRecord) internal orderRecords

pendingOrderCounts

mapping(bytes32 => uint256) public pendingOrderCounts

pendingCloseSize

mapping(bytes32 => uint256) public pendingCloseSize

marginHeadOrderId

mapping(bytes32 => uint64) public marginHeadOrderId

marginTailOrderId

mapping(bytes32 => uint64) public marginTailOrderId

claimableUsdc

mapping(address => uint256) public claimableUsdc

Functions

constructor

constructor(
    address _engine
) ;

getAccountEscrow

function getAccountEscrow(
    bytes32 accountId
) public view override returns (IOrderRouterAccounting.AccountEscrowView memory escrow);

getAccountOrderSummary

function getAccountOrderSummary(
    bytes32 accountId
) public view returns (IOrderRouterAccounting.AccountOrderSummary memory summary);

_summarizePendingOrders

function _summarizePendingOrders(
    bytes32 accountId
)
    internal
    view
    returns (
        uint256 pendingOrderCount,
        uint256 executionBountyUsdc,
        uint256 pendingCloseSize_,
        bool hasTerminalCloseQueued
    );

getMarginReservationIds

function getMarginReservationIds(
    bytes32 accountId
) public view override returns (uint64[] memory orderIds);

_reserveExecutionBounty

function _reserveExecutionBounty(
    bytes32 accountId,
    uint64 orderId,
    uint256 executionBountyUsdc,
    bool isClose
) internal;

_reserveCommittedMargin

function _reserveCommittedMargin(
    bytes32 accountId,
    uint64 orderId,
    bool isClose,
    uint256 marginDelta
) internal;

_consumeOrderEscrow

function _consumeOrderEscrow(
    uint64 orderId,
    bool success,
    uint8 failedPolicy
) internal returns (uint256 executionBountyUsdc);

_collectExecutionBounty

function _collectExecutionBounty(
    uint64 orderId
) internal returns (uint256 executionBountyUsdc);

_refundExecutionBounty

function _refundExecutionBounty(
    uint64 orderId
) internal;

_tryTransferUsdc

function _tryTransferUsdc(
    address to,
    uint256 amount
) internal returns (bool success);

_releaseCommittedMargin

function _releaseCommittedMargin(
    uint64 orderId
) internal;

_linkMarginOrder

function _linkMarginOrder(
    bytes32 accountId,
    uint64 orderId
) internal;

_unlinkMarginOrder

function _unlinkMarginOrder(
    bytes32 accountId,
    uint64 orderId
) internal;

_pruneMarginQueue

function _pruneMarginQueue(
    bytes32 accountId
) internal;

_orderRecord

function _orderRecord(
    uint64 orderId
) internal view virtual returns (OrderRecord storage record);

_pendingHeadOrderId

function _pendingHeadOrderId(
    bytes32 accountId
) internal view virtual returns (uint64);

_reserveCloseExecutionBounty

function _reserveCloseExecutionBounty(
    bytes32 accountId,
    uint256 executionBountyUsdc
) internal virtual;

_revertInsufficientFreeEquity

function _revertInsufficientFreeEquity() internal pure virtual;

_revertMarginOrderLinkCorrupted

function _revertMarginOrderLinkCorrupted() internal pure virtual;

Structs

OrderRecord

struct OrderRecord {
    CfdTypes.Order core;
    IOrderRouterAccounting.OrderStatus status;
    uint256 executionBountyUsdc;
    uint64 retryAfterTimestamp;
    uint64 nextPendingOrderId;
    uint64 prevPendingOrderId;
    uint64 nextGlobalOrderId;
    uint64 prevGlobalOrderId;
    uint64 nextMarginOrderId;
    uint64 prevMarginOrderId;
    bool inMarginQueue;
}

CfdEngine

Git Source

Inherits: IWithdrawGuard, Ownable2Step, ReentrancyGuardTransient

Title: CfdEngine

The core mathematical ledger for Plether CFDs.

Settles all funds through the MarginClearinghouse and CfdVault.

Note: security-contact: contact@plether.com

Constants

CAP_PRICE

uint256 public immutable CAP_PRICE

USDC

IERC20 public immutable USDC

clearinghouse

IMarginClearinghouse public immutable clearinghouse

EXECUTION_FEE_BPS

uint256 public constant EXECUTION_FEE_BPS = 4

TIMELOCK_DELAY

uint256 public constant TIMELOCK_DELAY = 48 hours

State Variables

vault

ICfdVault public vault

sides

SideState[2] public sides

lastMarkPrice

uint256 public lastMarkPrice

lastMarkTime

uint64 public lastMarkTime

accumulatedFeesUsdc

uint256 public accumulatedFeesUsdc

accumulatedBadDebtUsdc

uint256 public accumulatedBadDebtUsdc

degradedMode

bool public degradedMode

lastFundingTime

uint64 public lastFundingTime

riskParams

CfdTypes.RiskParams public riskParams

_positions

mapping(bytes32 => StoredPosition) internal _positions

deferredPayoutUsdc

mapping(bytes32 => uint256) public deferredPayoutUsdc

totalDeferredPayoutUsdc

uint256 public totalDeferredPayoutUsdc

deferredClearerBountyUsdc

mapping(address => uint256) public deferredClearerBountyUsdc

totalDeferredClearerBountyUsdc

uint256 public totalDeferredClearerBountyUsdc

deferredClaims

mapping(uint64 => ICfdEngine.DeferredClaim) public deferredClaims

nextDeferredClaimId

uint64 public nextDeferredClaimId = 1

deferredClaimHeadId

uint64 public deferredClaimHeadId

deferredClaimTailId

uint64 public deferredClaimTailId

traderDeferredClaimIdByAccount

mapping(bytes32 => uint64) public traderDeferredClaimIdByAccount

clearerDeferredClaimIdByKeeper

mapping(address => uint64) public clearerDeferredClaimIdByKeeper

orderRouter

address public orderRouter

fadDayOverrides

mapping(uint256 => bool) public fadDayOverrides

fadMaxStaleness

uint256 public fadMaxStaleness = 3 days

fadRunwaySeconds

uint256 public fadRunwaySeconds = 3 hours

engineMarkStalenessLimit

uint256 public engineMarkStalenessLimit = 60

pendingRiskParams

CfdTypes.RiskParams public pendingRiskParams

riskParamsActivationTime

uint256 public riskParamsActivationTime

_pendingAddFadDays

uint256[] private _pendingAddFadDays

addFadDaysActivationTime

uint256 public addFadDaysActivationTime

_pendingRemoveFadDays

uint256[] private _pendingRemoveFadDays

removeFadDaysActivationTime

uint256 public removeFadDaysActivationTime

pendingFadMaxStaleness

uint256 public pendingFadMaxStaleness

fadMaxStalenessActivationTime

uint256 public fadMaxStalenessActivationTime

pendingFadRunway

uint256 public pendingFadRunway

fadRunwayActivationTime

uint256 public fadRunwayActivationTime

pendingEngineMarkStalenessLimit

uint256 public pendingEngineMarkStalenessLimit

engineMarkStalenessActivationTime

uint256 public engineMarkStalenessActivationTime

Functions

_sideIndex

function _sideIndex(
    CfdTypes.Side side
) internal pure returns (uint256);

_sideState

function _sideState(
    CfdTypes.Side side
) internal view returns (SideState storage state);

_oppositeSide

function _oppositeSide(
    CfdTypes.Side side
) internal pure returns (CfdTypes.Side);

_sideAndOppositeStates

function _sideAndOppositeStates(
    CfdTypes.Side side
) internal view returns (SideState storage selected, SideState storage opposite);

_bullAndBearStates

function _bullAndBearStates() internal view returns (SideState storage bullState, SideState storage bearState);

getSideState

function getSideState(
    CfdTypes.Side side
) public view returns (ICfdEngine.SideState memory state);

_requireTimelockReady

function _requireTimelockReady(
    uint256 activationTime
) internal view;

onlyRouter

modifier onlyRouter() ;

constructor

constructor(
    address _usdc,
    address _clearinghouse,
    uint256 _capPrice,
    CfdTypes.RiskParams memory _riskParams
) Ownable(msg.sender);

Parameters

setVault

One-time setter for the HousePool vault backing all positions

function setVault(
    address _vault
) external onlyOwner;

setOrderRouter

One-time setter for the authorized OrderRouter

function setOrderRouter(
    address _router
) external onlyOwner;

proposeRiskParams

Proposes new risk parameters (margin BPS, funding curve, bounty config) subject to timelock

function proposeRiskParams(
    CfdTypes.RiskParams memory _riskParams
) external onlyOwner;

finalizeRiskParams

Applies proposed risk parameters after timelock expires; settles funding first

function finalizeRiskParams() external onlyOwner;

cancelRiskParamsProposal

Cancels a pending risk parameters proposal

function cancelRiskParamsProposal() external onlyOwner;

proposeAddFadDays

Proposes adding FAD (Friday Afternoon Deleverage) override days — elevated margin on those dates

function proposeAddFadDays(
    uint256[] calldata timestamps
) external onlyOwner;

finalizeAddFadDays

Applies proposed FAD day additions after timelock expires

function finalizeAddFadDays() external onlyOwner;

cancelAddFadDaysProposal

Cancels a pending add-FAD-days proposal

function cancelAddFadDaysProposal() external onlyOwner;

proposeRemoveFadDays

Proposes removing FAD override days (restores normal margin on those dates)

function proposeRemoveFadDays(
    uint256[] calldata timestamps
) external onlyOwner;

finalizeRemoveFadDays

Applies proposed FAD day removals after timelock expires

function finalizeRemoveFadDays() external onlyOwner;

cancelRemoveFadDaysProposal

Cancels a pending remove-FAD-days proposal

function cancelRemoveFadDaysProposal() external onlyOwner;

proposeFadMaxStaleness

Proposes a new fadMaxStaleness — max age of the last mark price before FAD kicks in

function proposeFadMaxStaleness(
    uint256 _seconds
) external onlyOwner;

finalizeFadMaxStaleness

Applies proposed fadMaxStaleness after timelock expires

function finalizeFadMaxStaleness() external onlyOwner;

cancelFadMaxStalenessProposal

Cancels a pending fadMaxStaleness proposal

function cancelFadMaxStalenessProposal() external onlyOwner;

proposeFadRunway

Proposes a new fadRunway — how many seconds before an FAD day the elevated margin activates

function proposeFadRunway(
    uint256 _seconds
) external onlyOwner;

finalizeFadRunway

Applies proposed fadRunway after timelock expires

function finalizeFadRunway() external onlyOwner;

cancelFadRunwayProposal

Cancels a pending fadRunway proposal

function cancelFadRunwayProposal() external onlyOwner;

proposeEngineMarkStalenessLimit

function proposeEngineMarkStalenessLimit(
    uint256 newStaleness
) external onlyOwner;

finalizeEngineMarkStalenessLimit

function finalizeEngineMarkStalenessLimit() external onlyOwner;

cancelEngineMarkStalenessLimitProposal

function cancelEngineMarkStalenessLimitProposal() external onlyOwner;

withdrawFees

Withdraws accumulated execution fees from the vault to a recipient

function withdrawFees(
    address recipient
) external onlyOwner;

absorbRouterCancellationFee

Pulls router-custodied cancellation fees into the vault and books them as protocol revenue.

function absorbRouterCancellationFee(
    uint256 amountUsdc
) external onlyRouter;

recordRouterProtocolFee

Books router-delivered protocol-owned inflow as protocol fees after the router has already synced funding and funded the vault.

function recordRouterProtocolFee(
    uint256 amountUsdc
) external onlyRouter;

addMargin

Adds isolated margin to an existing open position without changing size.

function addMargin(
    bytes32 accountId,
    uint256 amount
) external nonReentrant;

claimDeferredPayout

Claims a previously deferred profitable close payout into the clearinghouse.

The payout remains subject to current vault cash availability. Funds are credited to the clearinghouse first, so traders access them through the normal account-balance path.

function claimDeferredPayout(
    bytes32 accountId
) external nonReentrant;

claimDeferredClearerBounty

Claims a previously deferred clearer bounty when the vault has replenished cash.

Deferred keeper bounties settle to clearinghouse credit for the recorded keeper address-derived account, rather than attempting a direct USDC wallet transfer.

function claimDeferredClearerBounty() external nonReentrant;

recordDeferredClearerBounty

Records a liquidation bounty that could not be paid immediately because vault cash was unavailable.

function recordDeferredClearerBounty(
    address keeper,
    uint256 amountUsdc
) external onlyRouter;

reserveCloseOrderExecutionBounty

function reserveCloseOrderExecutionBounty(
    bytes32 accountId,
    uint256 amountUsdc,
    address recipient
) external onlyRouter;

clearBadDebt

Reduces accumulated bad debt after governance-confirmed recapitalization

function clearBadDebt(
    uint256 amount
) external onlyOwner;

Parameters

clearDegradedMode

function clearDegradedMode() external onlyOwner;

checkWithdraw

Reverts if the account has an open position that would be undercollateralized after withdrawal

function checkWithdraw(
    bytes32 accountId
) external view override;

Parameters

syncFunding

Materializes accrued funding into storage so subsequent reads reflect current state. O(1) gas, idempotent (no-op if called twice in the same block).

function syncFunding() external;

_syncFunding

Canonical internal funding sync. Every function that changes vault cash or reads funding-dependent state must call this first. Using a dedicated helper instead of inline _updateFunding(lastMarkPrice, vault.totalAssets()) ensures new call sites cannot silently skip the sync.

function _syncFunding() internal;

_syncFundingForMarkUpdate

function _syncFundingForMarkUpdate() internal;

_updateFunding

function _updateFunding(
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc
) internal;

getPendingFunding

Returns unsettled funding owed to (+) or by (-) a position in USDC (6 decimals)

function getPendingFunding(
    CfdTypes.Position memory pos
) public view returns (int256 fundingUsdc);

Parameters

Returns

processOrder

Executes an order: settles funding, then increases or decreases the position. Called exclusively by OrderRouter after MEV and slippage checks pass.

function processOrder(
    CfdTypes.Order memory order,
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc,
    uint64 publishTime
) external onlyRouter nonReentrant;

Parameters

processOrderTyped

Router-facing order execution entrypoint with typed business-rule failures.

function processOrderTyped(
    CfdTypes.Order memory order,
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc,
    uint64 publishTime
) external onlyRouter nonReentrant;

_processOrder

function _processOrder(
    CfdTypes.Order memory order,
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc,
    uint64 publishTime,
    bool typedFailures
) internal;

_syncTotalSideMargin

function _syncTotalSideMargin(
    CfdTypes.Side side,
    uint256 marginBefore,
    uint256 marginAfter
) internal;

_syncMarginQueue

function _syncMarginQueue(
    bytes32 accountId,
    uint256 consumedCommittedReservationUsdc
) internal;

_payOrRecordDeferredTraderPayout

function _payOrRecordDeferredTraderPayout(
    bytes32 accountId,
    uint256 amountUsdc
) internal;

_enqueueOrAccrueDeferredTraderPayout

function _enqueueOrAccrueDeferredTraderPayout(
    bytes32 accountId,
    uint256 amountUsdc
) internal;

_enqueueOrAccrueDeferredClearerBounty

function _enqueueOrAccrueDeferredClearerBounty(
    address keeper,
    uint256 amountUsdc
) internal;

_accountVaultCashInflow

function _accountVaultCashInflow(
    VaultCashInflow memory inflow
) internal;

_canPayFreshVaultPayout

function _canPayFreshVaultPayout(
    uint256 amountUsdc
) internal view returns (bool);

_canWithdrawProtocolFees

function _canWithdrawProtocolFees(
    uint256 amountUsdc
) internal view returns (bool);

_availableCashForFreshVaultPayouts

function _availableCashForFreshVaultPayouts() internal view returns (uint256);

_claimableHeadAmountUsdc

function _claimableHeadAmountUsdc() internal view returns (uint256);

_freshVaultReservation

function _freshVaultReservation() internal view returns (CashPriorityLib.SeniorCashReservation memory reservation);

_headDeferredClaimReservation

function _headDeferredClaimReservation(
    uint256 headClaimAmountUsdc
) internal view returns (CashPriorityLib.SeniorCashReservation memory reservation);

_enqueueDeferredClaim

function _enqueueDeferredClaim(
    ICfdEngine.DeferredClaimType claimType,
    bytes32 accountId,
    address keeper,
    uint256 amountUsdc
) internal returns (uint64 claimId);

_popDeferredClaimHead

function _popDeferredClaimHead() internal;

_unlinkDeferredClaim

function _unlinkDeferredClaim(
    uint64 claimId
) internal;

isFadWindow

Returns true during the Friday Afternoon Deleverage (FAD) window (Friday 19:00 UTC → Sunday 22:00 UTC), on admin-configured FAD days, or within fadRunwaySeconds before an admin FAD day (deleverage runway).

function isFadWindow() public view returns (bool);

isOracleFrozen

Returns true only when FX markets are closed and oracle freshness can be relaxed. Distinct from FAD, which starts earlier for deleveraging risk controls.

function isOracleFrozen() public view returns (bool);

hasOpenPosition

function hasOpenPosition(
    bytes32 accountId
) external view returns (bool);

positions

function positions(
    bytes32 accountId
)
    external
    view
    returns (
        uint256 size,
        uint256 margin,
        uint256 entryPrice,
        uint256 maxProfitUsdc,
        int256 entryFundingIndex,
        CfdTypes.Side side,
        uint64 lastUpdateTime,
        int256 vpiAccrued
    );

getPositionSize

function getPositionSize(
    bytes32 accountId
) external view returns (uint256);

getAccountCollateralView

function getAccountCollateralView(
    bytes32 accountId
) external view returns (AccountCollateralView memory viewData);

getAccountLedgerView

function getAccountLedgerView(
    bytes32 accountId
) external view returns (ICfdEngine.AccountLedgerView memory viewData);

getAccountLedgerSnapshot

function getAccountLedgerSnapshot(
    bytes32 accountId
) external view returns (ICfdEngine.AccountLedgerSnapshot memory snapshot);

_buildAccountLedgerSnapshot

function _buildAccountLedgerSnapshot(
    bytes32 accountId
) internal view returns (ICfdEngine.AccountLedgerSnapshot memory snapshot);

getPositionView

function getPositionView(
    bytes32 accountId
) external view returns (PositionView memory viewData);

getProtocolAccountingView

function getProtocolAccountingView() external view returns (ProtocolAccountingView memory viewData);

getProtocolAccountingSnapshot

function getProtocolAccountingSnapshot()
    external
    view
    returns (ICfdEngine.ProtocolAccountingSnapshot memory snapshot);

_buildProtocolAccountingSnapshot

function _buildProtocolAccountingSnapshot()
    internal
    view
    returns (ICfdEngine.ProtocolAccountingSnapshot memory snapshot);

previewOpenRevertCode

function previewOpenRevertCode(
    bytes32 accountId,
    CfdTypes.Side side,
    uint256 sizeDelta,
    uint256 marginDelta,
    uint256 oraclePrice,
    uint64 publishTime
) external view returns (uint8 code);

previewOpenFailurePolicyCategory

function previewOpenFailurePolicyCategory(
    bytes32 accountId,
    CfdTypes.Side side,
    uint256 sizeDelta,
    uint256 marginDelta,
    uint256 oraclePrice,
    uint64 publishTime
) external view returns (CfdEnginePlanTypes.OpenFailurePolicyCategory category);

getDeferredPayoutStatus

function getDeferredPayoutStatus(
    bytes32 accountId,
    address keeper
) external view returns (DeferredPayoutStatus memory status);

getDeferredClaimHead

function getDeferredClaimHead() external view returns (ICfdEngine.DeferredClaim memory claim);

getDeferredTraderStatus

function getDeferredTraderStatus(
    bytes32 accountId
) public view returns (ICfdEngine.DeferredTraderStatus memory status);

getDeferredClearerStatus

function getDeferredClearerStatus(
    address keeper
) public view returns (ICfdEngine.DeferredClearerStatus memory status);

previewClose

Canonical close preview using the vault’s current accounted depth.

function previewClose(
    bytes32 accountId,
    uint256 sizeDelta,
    uint256 oraclePrice
) external view returns (ClosePreview memory preview);

simulateClose

Hypothetical close simulation at a caller-supplied vault depth.

function simulateClose(
    bytes32 accountId,
    uint256 sizeDelta,
    uint256 oraclePrice,
    uint256 vaultDepthUsdc
) external view returns (ClosePreview memory preview);

_previewClose

function _previewClose(
    bytes32 accountId,
    uint256 sizeDelta,
    uint256 oraclePrice,
    uint256 vaultDepthUsdc
) internal view returns (ClosePreview memory preview);

previewLiquidation

Canonical liquidation preview using the vault’s current accounted depth.

function previewLiquidation(
    bytes32 accountId,
    uint256 oraclePrice
) external view returns (LiquidationPreview memory preview);

simulateLiquidation

Hypothetical liquidation simulation at a caller-supplied vault depth.

function simulateLiquidation(
    bytes32 accountId,
    uint256 oraclePrice,
    uint256 vaultDepthUsdc
) external view returns (LiquidationPreview memory preview);

_previewLiquidation

function _previewLiquidation(
    bytes32 accountId,
    uint256 oraclePrice,
    uint256 vaultDepthUsdc
) internal view returns (LiquidationPreview memory preview);

_applyLiquidationPreviewForfeiture

function _applyLiquidationPreviewForfeiture(
    bytes32 accountId,
    CfdEnginePlanTypes.RawSnapshot memory snap
) internal view;

getPositionSide

function getPositionSide(
    bytes32 accountId
) external view returns (CfdTypes.Side);

getMaintenanceMarginUsdc

Returns the maintenance margin requirement in USDC (6 decimals). Uses fadMarginBps during the FAD window, maintMarginBps otherwise.

function getMaintenanceMarginUsdc(
    uint256 size,
    uint256 currentOraclePrice
) public view returns (uint256);

Parameters

liquidatePosition

Liquidates an undercollateralized position. Surplus equity (after bounty) is returned to the user. In bad-debt cases (equity < bounty), all remaining margin is seized by the vault.

function liquidatePosition(
    bytes32 accountId,
    uint256 currentOraclePrice,
    uint256 vaultDepthUsdc,
    uint64 publishTime
) external onlyRouter nonReentrant returns (uint256 keeperBountyUsdc);

Parameters

Returns

_assertPostSolvency

function _assertPostSolvency() internal view;

_maxLiability

function _maxLiability() internal view returns (uint256);

_getWithdrawalReservedUsdc

function _getWithdrawalReservedUsdc() internal view returns (uint256 reservedUsdc);

_buildHousePoolInputSnapshot

function _buildHousePoolInputSnapshot(
    uint256 markStalenessLimit
) internal view returns (ICfdEngine.HousePoolInputSnapshot memory snapshot);

_buildHousePoolStatusSnapshot

function _buildHousePoolStatusSnapshot()
    internal
    view
    returns (ICfdEngine.HousePoolStatusSnapshot memory snapshot);

_buildAdjustedSolvencyState

function _buildAdjustedSolvencyState() internal view returns (SolvencyAccountingLib.SolvencyState memory);

_buildAdjustedSolvencySnapshot

function _buildAdjustedSolvencySnapshot()
    internal
    view
    returns (CfdEngineSnapshotsLib.SolvencySnapshot memory snapshot);

_buildRawSnapshot

function _buildRawSnapshot(
    bytes32 accountId,
    uint256,
    uint256 vaultDepthUsdc,
    uint64
) internal view returns (CfdEnginePlanTypes.RawSnapshot memory snap);

_copySideSnapshot

function _copySideSnapshot(
    SideState storage state
) internal view returns (CfdEnginePlanTypes.SideSnapshot memory snap);

_getProjectedPendingFunding

function _getProjectedPendingFunding(
    bytes32 accountId,
    CfdTypes.Position memory pos
) internal view returns (int256 fundingUsdc);

_buildProjectedPositionRiskState

function _buildProjectedPositionRiskState(
    bytes32 accountId,
    CfdTypes.Position memory pos,
    uint256 price,
    uint256 reachableUsdc,
    uint256 riskBps
) internal view returns (PositionRiskAccountingLib.PositionRiskState memory riskState);

_tryGetFreshLiveMarkPrice

function _tryGetFreshLiveMarkPrice() internal view returns (bool fresh, uint256 price);

_revertIfOpenInvalid

function _revertIfOpenInvalid(
    CfdEnginePlanTypes.OpenRevertCode code
) internal pure;

_revertIfOpenInvalidTyped

function _revertIfOpenInvalidTyped(
    CfdEnginePlanTypes.OpenRevertCode code
) internal pure;

_revertIfCloseInvalid

function _revertIfCloseInvalid(
    CfdEnginePlanTypes.CloseRevertCode code
) internal pure;

_revertIfCloseInvalidTyped

function _revertIfCloseInvalidTyped(
    CfdEnginePlanTypes.CloseRevertCode code
) internal pure;

_applyFundingAndMark

function _applyFundingAndMark(
    int256 bullDelta,
    int256 bearDelta,
    uint256 absSkew,
    uint64 newFundingTime,
    uint256 newMarkPrice,
    uint64 newMarkTime
) internal;

_applyFundingSettlement

function _applyFundingSettlement(
    CfdEnginePlanTypes.FundingDelta memory fd,
    bytes32 accountId,
    StoredPosition storage pos,
    CfdTypes.Side marginSide
) internal returns (uint256 marginAfterFunding);

_applyOpen

function _applyOpen(
    CfdEnginePlanTypes.OpenDelta memory delta
) internal;

_applyClose

function _applyClose(
    CfdEnginePlanTypes.CloseDelta memory delta
) internal;

_applyLiquidation

function _applyLiquidation(
    CfdEnginePlanTypes.LiquidationDelta memory delta
) internal returns (uint256 keeperBountyUsdc);

_enterDegradedModeIfInsolvent

function _enterDegradedModeIfInsolvent(
    bytes32 accountId,
    uint256 pendingVaultPayoutUsdc
) internal;

_physicalReachableCollateralUsdc

function _physicalReachableCollateralUsdc(
    bytes32 accountId
) internal view returns (uint256);

_positionMarginBucketUsdc

function _positionMarginBucketUsdc(
    bytes32 accountId
) internal view returns (uint256);

_loadPosition

function _loadPosition(
    bytes32 accountId
) internal view returns (CfdTypes.Position memory pos);

_liveMarkStalenessLimit

function _liveMarkStalenessLimit() internal view returns (uint256);

_consumeDeferredTraderPayout

function _consumeDeferredTraderPayout(
    bytes32 accountId,
    uint256 amountUsdc
) internal;

_computeGlobalFundingPnl

function _computeGlobalFundingPnl() internal view returns (int256 bullFunding, int256 bearFunding);

_getProjectedFundingIndices

function _getProjectedFundingIndices() internal view returns (int256 bullFundingIndex, int256 bearFundingIndex);

_buildFundingSnapshot

function _buildFundingSnapshot() internal view returns (CfdEngineSnapshotsLib.FundingSnapshot memory snapshot);

_getSolvencyCappedFundingPnl

function _getSolvencyCappedFundingPnl() internal view returns (int256);

_canProjectFundingStep

function _canProjectFundingStep() internal view returns (bool);

_buildFundingStep

function _buildFundingStep(
    uint256 price,
    uint256 vaultDepthUsdc
) internal view returns (PositionRiskAccountingLib.FundingStepResult memory step);

_getLiabilityOnlyFundingPnl

function _getLiabilityOnlyFundingPnl() internal view returns (uint256);

_validateRiskParams

function _validateRiskParams(
    CfdTypes.RiskParams memory _riskParams
) internal pure;

_getUnrealizedFundingPnl

function _getUnrealizedFundingPnl() internal view returns (int256);

getUnrealizedFundingPnl

Aggregate unsettled funding across all positions (uncapped, for reporting only)

function getUnrealizedFundingPnl() external view returns (int256);

Returns

getCappedFundingPnl

Aggregate unsettled funding across all positions with uncollectible debts capped by margin.

function getCappedFundingPnl() external view returns (int256);

Returns

getLiabilityOnlyFundingPnl

Aggregate unsettled funding liabilities only, ignoring trader debts owed to the vault.

function getLiabilityOnlyFundingPnl() external view returns (uint256);

Returns

getMaxLiability

Returns the protocol’s worst-case directional liability.

function getMaxLiability() external view returns (uint256);

getWithdrawalReservedUsdc

Returns the total USDC reserve required for withdrawals.

function getWithdrawalReservedUsdc() external view returns (uint256);

getHousePoolInputSnapshot

function getHousePoolInputSnapshot(
    uint256 markStalenessLimit
) external view returns (ICfdEngine.HousePoolInputSnapshot memory snapshot);

getHousePoolStatusSnapshot

function getHousePoolStatusSnapshot() external view returns (ICfdEngine.HousePoolStatusSnapshot memory snapshot);

updateMarkPrice

Updates the cached mark price without settling funding or processing trades

function updateMarkPrice(
    uint256 price,
    uint64 publishTime
) external onlyRouter;

Parameters

hasLiveLiability

Returns true when the protocol still has live bounded directional liability.

function hasLiveLiability() external view returns (bool);

getUnrealizedTraderPnl

Aggregate unrealized PnL of all open positions at lastMarkPrice. Positive = traders winning (house liability). Negative = traders losing (house asset).

function getUnrealizedTraderPnl() external view returns (int256);

Returns

getVaultMtmAdjustment

Combined MtM: per-side (PnL + funding), clamped at zero per side then summed. Positive = vault owes traders (unrealized liability). Zero = traders losing or neutral.

function getVaultMtmAdjustment() external view returns (uint256);

Returns

_getVaultMtmLiability

function _getVaultMtmLiability() internal view returns (uint256);

_getProtocolPhase

function _getProtocolPhase() internal view returns (ICfdEngine.ProtocolPhase);

getProtocolPhase

function getProtocolPhase() external view returns (ICfdEngine.ProtocolPhase);

getProtocolStatus

function getProtocolStatus() external view returns (ICfdEngine.ProtocolStatus memory status);

Events

FundingUpdated

event FundingUpdated(int256 bullIndex, int256 bearIndex, uint256 absSkewUsdc);

PositionOpened

event PositionOpened(
    bytes32 indexed accountId, CfdTypes.Side side, uint256 sizeDelta, uint256 price, uint256 marginDelta
);

PositionClosed

event PositionClosed(bytes32 indexed accountId, CfdTypes.Side side, uint256 sizeDelta, uint256 price, int256 pnl);

PositionLiquidated

event PositionLiquidated(
    bytes32 indexed accountId, CfdTypes.Side side, uint256 size, uint256 price, uint256 keeperBounty
);

MarginAdded

event MarginAdded(bytes32 indexed accountId, uint256 amount);

FadDaysAdded

event FadDaysAdded(uint256[] timestamps);

FadDaysRemoved

event FadDaysRemoved(uint256[] timestamps);

FadMaxStalenessUpdated

event FadMaxStalenessUpdated(uint256 newStaleness);

FadRunwayUpdated

event FadRunwayUpdated(uint256 newRunway);

EngineMarkStalenessLimitProposed

event EngineMarkStalenessLimitProposed(uint256 newStaleness, uint256 activationTime);

EngineMarkStalenessLimitUpdated

event EngineMarkStalenessLimitUpdated(uint256 newStaleness);

RiskParamsProposed

event RiskParamsProposed(uint256 activationTime);

RiskParamsFinalized

event RiskParamsFinalized();

AddFadDaysProposed

event AddFadDaysProposed(uint256[] timestamps, uint256 activationTime);

AddFadDaysFinalized

event AddFadDaysFinalized();

RemoveFadDaysProposed

event RemoveFadDaysProposed(uint256[] timestamps, uint256 activationTime);

RemoveFadDaysFinalized

event RemoveFadDaysFinalized();

FadMaxStalenessProposed

event FadMaxStalenessProposed(uint256 newStaleness, uint256 activationTime);

FadMaxStalenessFinalized

event FadMaxStalenessFinalized();

FadRunwayProposed

event FadRunwayProposed(uint256 newRunway, uint256 activationTime);

FadRunwayFinalized

event FadRunwayFinalized();

BadDebtCleared

event BadDebtCleared(uint256 amount, uint256 remaining);

DegradedModeEntered

event DegradedModeEntered(uint256 effectiveAssets, uint256 maxLiability, bytes32 indexed triggeringAccount);

DegradedModeCleared

event DegradedModeCleared();

DeferredPayoutRecorded

event DeferredPayoutRecorded(bytes32 indexed accountId, uint256 amountUsdc);

DeferredPayoutClaimed

event DeferredPayoutClaimed(bytes32 indexed accountId, uint256 amountUsdc);

DeferredClearerBountyRecorded

event DeferredClearerBountyRecorded(address indexed keeper, uint256 amountUsdc);

DeferredClearerBountyClaimed

event DeferredClearerBountyClaimed(address indexed keeper, uint256 amountUsdc);

Errors

CfdEngine__Unauthorized

error CfdEngine__Unauthorized();

CfdEngine__VaultAlreadySet

error CfdEngine__VaultAlreadySet();

CfdEngine__RouterAlreadySet

error CfdEngine__RouterAlreadySet();

CfdEngine__NoFeesToWithdraw

error CfdEngine__NoFeesToWithdraw();

CfdEngine__NoDeferredPayout

error CfdEngine__NoDeferredPayout();

CfdEngine__InsufficientVaultLiquidity

error CfdEngine__InsufficientVaultLiquidity();

CfdEngine__NoDeferredClearerBounty

error CfdEngine__NoDeferredClearerBounty();

CfdEngine__DeferredClaimNotAtHead

error CfdEngine__DeferredClaimNotAtHead();

CfdEngine__MustCloseOpposingPosition

error CfdEngine__MustCloseOpposingPosition();

CfdEngine__FundingExceedsMargin

error CfdEngine__FundingExceedsMargin();

CfdEngine__VaultSolvencyExceeded

error CfdEngine__VaultSolvencyExceeded();

CfdEngine__MarginDrainedByFees

error CfdEngine__MarginDrainedByFees();

CfdEngine__CloseSizeExceedsPosition

error CfdEngine__CloseSizeExceedsPosition();

CfdEngine__NoPositionToLiquidate

error CfdEngine__NoPositionToLiquidate();

CfdEngine__PositionIsSolvent

error CfdEngine__PositionIsSolvent();

CfdEngine__PostOpSolvencyBreach

error CfdEngine__PostOpSolvencyBreach();

CfdEngine__InsufficientInitialMargin

error CfdEngine__InsufficientInitialMargin();

CfdEngine__PositionTooSmall

error CfdEngine__PositionTooSmall();

CfdEngine__WithdrawBlockedByOpenPosition

error CfdEngine__WithdrawBlockedByOpenPosition();

CfdEngine__EmptyDays

error CfdEngine__EmptyDays();

CfdEngine__ZeroStaleness

error CfdEngine__ZeroStaleness();

CfdEngine__RunwayTooLong

error CfdEngine__RunwayTooLong();

CfdEngine__PartialCloseUnderwaterFunding

error CfdEngine__PartialCloseUnderwaterFunding();

CfdEngine__DustPosition

error CfdEngine__DustPosition();

CfdEngine__MarkPriceStale

error CfdEngine__MarkPriceStale();

CfdEngine__MarkPriceOutOfOrder

error CfdEngine__MarkPriceOutOfOrder();

CfdEngine__NotAccountOwner

error CfdEngine__NotAccountOwner();

CfdEngine__NoOpenPosition

error CfdEngine__NoOpenPosition();

CfdEngine__TimelockNotReady

error CfdEngine__TimelockNotReady();

CfdEngine__NoProposal

error CfdEngine__NoProposal();

CfdEngine__BadDebtTooLarge

error CfdEngine__BadDebtTooLarge();

CfdEngine__InvalidRiskParams

error CfdEngine__InvalidRiskParams();

CfdEngine__SkewTooHigh

error CfdEngine__SkewTooHigh();

CfdEngine__DegradedMode

error CfdEngine__DegradedMode();

CfdEngine__NotDegraded

error CfdEngine__NotDegraded();

CfdEngine__StillInsolvent

error CfdEngine__StillInsolvent();

CfdEngine__ZeroAddress

error CfdEngine__ZeroAddress();

CfdEngine__InsufficientCloseOrderBountyBacking

error CfdEngine__InsufficientCloseOrderBountyBacking();

CfdEngine__InvalidVaultCashInflow

error CfdEngine__InvalidVaultCashInflow();

Structs

AccountCollateralView

struct AccountCollateralView {
    uint256 settlementBalanceUsdc;
    uint256 lockedMarginUsdc;
    // Clearinghouse custody bucket for currently locked live position backing.
    uint256 activePositionMarginUsdc;
    uint256 otherLockedMarginUsdc;
    uint256 freeSettlementUsdc;
    // Current UI helper only; this does not include terminally reachable queued committed margin.
    uint256 closeReachableUsdc;
    uint256 terminalReachableUsdc;
    uint256 accountEquityUsdc;
    uint256 freeBuyingPowerUsdc;
    uint256 deferredPayoutUsdc;
}

PositionView

struct PositionView {
    bool exists;
    CfdTypes.Side side;
    uint256 size;
    uint256 margin;
    uint256 entryPrice;
    uint256 entryNotionalUsdc;
    uint256 physicalReachableCollateralUsdc;
    uint256 nettableDeferredPayoutUsdc;
    int256 unrealizedPnlUsdc;
    int256 pendingFundingUsdc;
    int256 netEquityUsdc;
    uint256 maxProfitUsdc;
    bool liquidatable;
}

ProtocolAccountingView

struct ProtocolAccountingView {
    uint256 vaultAssetsUsdc;
    uint256 maxLiabilityUsdc;
    uint256 withdrawalReservedUsdc;
    uint256 freeUsdc;
    uint256 accumulatedFeesUsdc;
    int256 cappedFundingPnlUsdc;
    uint256 liabilityOnlyFundingPnlUsdc;
    uint256 totalDeferredPayoutUsdc;
    uint256 totalDeferredClearerBountyUsdc;
    bool degradedMode;
    bool hasLiveLiability;
}

ClosePreview

struct ClosePreview {
    bool valid;
    CfdTypes.CloseInvalidReason invalidReason;
    uint256 executionPrice;
    uint256 sizeDelta;
    int256 realizedPnlUsdc;
    int256 fundingUsdc;
    int256 vpiDeltaUsdc;
    uint256 vpiUsdc;
    uint256 executionFeeUsdc;
    uint256 freshTraderPayoutUsdc;
    uint256 existingDeferredConsumedUsdc;
    uint256 existingDeferredRemainingUsdc;
    uint256 immediatePayoutUsdc;
    uint256 deferredPayoutUsdc;
    uint256 seizedCollateralUsdc;
    uint256 badDebtUsdc;
    uint256 remainingSize;
    uint256 remainingMargin;
    bool triggersDegradedMode;
    bool postOpDegradedMode;
    uint256 effectiveAssetsAfterUsdc;
    uint256 maxLiabilityAfterUsdc;
    int256 solvencyFundingPnlUsdc;
}

LiquidationPreview

struct LiquidationPreview {
    bool liquidatable;
    uint256 oraclePrice;
    int256 equityUsdc;
    int256 pnlUsdc;
    int256 fundingUsdc;
    uint256 reachableCollateralUsdc;
    uint256 keeperBountyUsdc;
    uint256 seizedCollateralUsdc;
    uint256 settlementRetainedUsdc;
    uint256 freshTraderPayoutUsdc;
    uint256 existingDeferredConsumedUsdc;
    uint256 existingDeferredRemainingUsdc;
    uint256 immediatePayoutUsdc;
    uint256 deferredPayoutUsdc;
    uint256 badDebtUsdc;
    bool triggersDegradedMode;
    bool postOpDegradedMode;
    uint256 effectiveAssetsAfterUsdc;
    uint256 maxLiabilityAfterUsdc;
    int256 solvencyFundingPnlUsdc;
}

DeferredPayoutStatus

struct DeferredPayoutStatus {
    uint256 deferredTraderPayoutUsdc;
    bool traderPayoutClaimableNow;
    uint256 deferredClearerBountyUsdc;
    bool liquidationBountyClaimableNow;
}

SideState

struct SideState {
    uint256 maxProfitUsdc;
    uint256 openInterest;
    uint256 entryNotional;
    // Cached aggregate of engine economic position margins for this side; not a custody bucket.
    uint256 totalMargin;
    int256 fundingIndex;
    int256 entryFunding;
}

VaultCashInflow

struct VaultCashInflow {
    uint256 physicalCashReceivedUsdc;
    uint256 protocolOwnedUsdc;
    uint256 lpOwnedUsdc;
}

StoredPosition

struct StoredPosition {
    uint256 size;
    uint256 entryPrice;
    uint256 maxProfitUsdc;
    int256 entryFundingIndex;
    CfdTypes.Side side;
    uint64 lastUpdateTime;
    int256 vpiAccrued;
}

CfdEnginePlanTypes

Git Source

Title: CfdEnginePlanTypes

Snapshot and delta structs for the plan→apply architecture. Plan functions are pure over a RawSnapshot and return typed deltas. Apply functions consume deltas to perform state mutations and external calls.

Structs

SideSnapshot

struct SideSnapshot {
    uint256 maxProfitUsdc;
    uint256 openInterest;
    uint256 entryNotional;
    uint256 totalMargin;
    int256 fundingIndex;
    int256 entryFunding;
}

RawSnapshot

struct RawSnapshot {
    CfdTypes.Position position;
    bytes32 accountId;

    uint256 currentTimestamp;
    uint64 lastFundingTime;
    uint256 lastMarkPrice;
    uint64 lastMarkTime;

    SideSnapshot bullSide;
    SideSnapshot bearSide;

    uint256 fundingVaultDepthUsdc;
    uint256 vaultAssetsUsdc;
    uint256 vaultCashUsdc;

    IMarginClearinghouse.AccountUsdcBuckets accountBuckets;
    IMarginClearinghouse.LockedMarginBuckets lockedBuckets;

    uint64[] marginReservationIds;

    uint256 accumulatedFeesUsdc;
    uint256 accumulatedBadDebtUsdc;
    uint256 totalDeferredPayoutUsdc;
    uint256 totalDeferredClearerBountyUsdc;
    uint256 deferredPayoutForAccount;
    bool degradedMode;

    uint256 capPrice;
    CfdTypes.RiskParams riskParams;
    bool isFadWindow;
    bool liveMarkFreshForFunding;
}

GlobalFundingDelta

struct GlobalFundingDelta {
    int256 bullFundingIndexDelta;
    int256 bearFundingIndexDelta;
    uint256 fundingAbsSkewUsdc;
    uint64 newLastFundingTime;
    uint256 newLastMarkPrice;
    uint64 newLastMarkTime;
}

FundingDelta

struct FundingDelta {
    int256 bullFundingIndexDelta;
    int256 bearFundingIndexDelta;
    uint256 fundingAbsSkewUsdc;
    uint64 newLastFundingTime;

    uint256 newLastMarkPrice;
    uint64 newLastMarkTime;

    int256 pendingFundingUsdc;
    int256 closeFundingSettlementUsdc;
    FundingPayoutType payoutType;

    uint256 fundingVaultPayoutUsdc;
    uint256 fundingClearinghouseCreditUsdc;

    uint256 fundingLossConsumedFromMargin;
    uint256 fundingLossConsumedFromFree;
    uint256 fundingLossUncovered;

    uint256 posMarginIncrease;
    uint256 posMarginDecrease;

    int256 sideEntryFundingDelta;
    int256 newPosEntryFundingIndex;
}

SolvencyPreview

struct SolvencyPreview {
    uint256 effectiveAssetsAfterUsdc;
    uint256 maxLiabilityAfterUsdc;
    int256 solvencyFundingPnlUsdc;
    bool triggersDegradedMode;
    bool postOpDegradedMode;
}

OpenDelta

struct OpenDelta {
    bool valid;
    OpenRevertCode revertCode;

    FundingDelta funding;
    OpenAccountingLib.OpenState openState;

    CfdTypes.Side posSide;
    uint256 newPosSize;
    uint256 newPosEntryPrice;
    int256 posVpiAccruedDelta;
    uint256 posMaxProfitIncrease;
    uint256 positionMarginAfterOpen;

    uint256 sideOiIncrease;
    int256 sideEntryNotionalDelta;
    int256 sideEntryFundingContribution;
    uint256 sideMaxProfitIncrease;

    int256 tradeCostUsdc;
    uint256 marginDeltaUsdc;
    int256 netMarginChange;
    uint256 vaultRebatePayoutUsdc;

    uint256 executionFeeUsdc;

    uint256 sideTotalMarginBefore;
    uint256 sideTotalMarginAfterFunding;
    uint256 sideTotalMarginAfterOpen;

    bytes32 accountId;
    uint256 sizeDelta;
    uint256 price;
    uint256 effectivePositionMarginAfterFunding;
}

CloseDelta

struct CloseDelta {
    bool valid;
    CloseRevertCode revertCode;

    FundingDelta funding;
    CloseAccountingLib.CloseState closeState;
    uint256 postBullOi;
    uint256 postBearOi;

    uint256 posMarginAfter;
    uint256 posSizeDelta;
    uint256 posMaxProfitReduction;
    int256 posVpiAccruedReduction;
    bool deletePosition;

    CfdTypes.Side side;
    uint256 sideOiDecrease;
    uint256 sideEntryNotionalReduction;
    int256 sideEntryFundingReduction;
    uint256 sideMaxProfitReduction;

    uint256 unlockMarginUsdc;

    SettlementType settlementType;

    uint256 freshTraderPayoutUsdc;
    bool freshPayoutIsImmediate;
    bool freshPayoutIsDeferred;
    uint256 existingDeferredConsumedUsdc;
    uint256 existingDeferredRemainingUsdc;
    uint256 deferredFeeRecoveryUsdc;

    CfdEngineSettlementLib.CloseSettlementResult lossResult;
    MarginClearinghouseAccountingLib.SettlementConsumption lossConsumption;
    uint256 syncMarginQueueAmount;

    uint256 executionFeeUsdc;
    uint256 badDebtUsdc;

    uint256 totalMarginBefore;
    uint256 totalMarginAfterFunding;
    uint256 totalMarginAfterClose;

    SolvencyPreview solvency;

    bytes32 accountId;
    uint256 sizeDelta;
    uint256 price;
    int256 realizedPnlUsdc;
}

LiquidationDelta

struct LiquidationDelta {
    bool liquidatable;

    GlobalFundingDelta funding;

    PositionRiskAccountingLib.PositionRiskState riskState;
    LiquidationAccountingLib.LiquidationState liquidationState;

    CfdTypes.Side side;
    uint256 posSize;
    uint256 posMargin;
    uint256 posMaxProfit;
    uint256 posEntryPrice;
    int256 posEntryFundingIndex;

    uint256 sideOiDecrease;
    uint256 sideMaxProfitDecrease;
    uint256 sideEntryNotionalReduction;
    int256 sideEntryFundingReduction;
    uint256 sideTotalMarginReduction;

    uint256 keeperBountyUsdc;
    uint256 liquidationReachableCollateralUsdc;

    int256 residualUsdc;
    MarginClearinghouseAccountingLib.LiquidationResidualPlan residualPlan;

    uint256 settlementRetainedUsdc;
    uint256 freshTraderPayoutUsdc;
    bool freshPayoutIsImmediate;
    bool freshPayoutIsDeferred;
    uint256 existingDeferredConsumedUsdc;
    uint256 existingDeferredRemainingUsdc;

    uint256 syncMarginQueueAmount;

    uint256 badDebtUsdc;

    SolvencyPreview solvency;

    bytes32 accountId;
    uint256 price;
}

Enums

OpenFailurePolicyCategory

enum OpenFailurePolicyCategory {
    None,
    CommitTimeRejectable,
    ExecutionTimeUserInvalid,
    ExecutionTimeProtocolStateInvalidated
}

ExecutionFailurePolicyCategory

enum ExecutionFailurePolicyCategory {
    None,
    UserInvalid,
    ProtocolStateInvalidated
}

FundingPayoutType

enum FundingPayoutType {
    NONE,
    MARGIN_CREDIT,
    CLOSE_SETTLEMENT,
    DEFERRED_PAYOUT,
    LOSS_CONSUMED,
    LOSS_UNCOVERED_REVERT,
    LOSS_UNCOVERED_CLOSE
}

OpenRevertCode

enum OpenRevertCode {
    OK,
    MUST_CLOSE_OPPOSING,
    DEGRADED_MODE,
    POSITION_TOO_SMALL,
    SKEW_TOO_HIGH,
    MARGIN_DRAINED_BY_FEES,
    INSUFFICIENT_INITIAL_MARGIN,
    SOLVENCY_EXCEEDED,
    FUNDING_EXCEEDS_MARGIN
}