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
• CfdEngineAccountLens
• CfdEngineAdmin
• CfdEngineLens
• CfdEnginePlanTypes
• CfdEnginePlanner
• CfdEngineProtocolLens
• CfdEngineSettlementModule
• CfdMath
• CfdTypes
• HousePool
• MarginClearinghouse
• OrderRouter
• OrderRouterAdmin
• PerpsPublicLens
• TrancheVault

Contents

• AccountLensViewTypes
• CfdEngineSettlementTypes
• DeferredEngineViewTypes
• EngineStatusViewTypes
• HousePoolEngineViewTypes
• ICfdEngine
• ICfdEngineAccountLens
• ICfdEngineAdminHost
• ICfdEngineCore
• ICfdEngineLens
• ICfdEnginePlanner
• ICfdEngineProtocolLens
• ICfdEngineSettlementHost
• ICfdEngineSettlementModule
• ICfdVault
• IHousePool
• IMarginAccount
• IMarginClearinghouse
• IOrderRouterAccounting
• IOrderRouterAdminHost
• IPerpsAdmin
• IPerpsKeeper
• IPerpsLP
• IPerpsLPActions
• IPerpsLPViews
• IPerpsTrader
• IPerpsTraderActions
• IPerpsTraderViews
• IProtocolViews
• ITrancheVaultBootstrap
• IWithdrawGuard
• PerpsViewTypes
• ProtocolLensViewTypes

AccountLensViewTypes

Git Source

Structs

AccountLedgerView

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

AccountLedgerSnapshot

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

CfdEngineSettlementTypes

Git Source

Structs

PositionState

struct PositionState {
    bool deletePosition;
    uint256 size;
    uint256 entryPrice;
    uint256 maxProfitUsdc;
    uint64 lastUpdateTime;
    uint64 lastCarryTimestamp;
    int256 vpiAccrued;
    CfdTypes.Side side;
}

DeferredEngineViewTypes

Git Source

Structs

DeferredCreditStatus

Aggregate deferred-credit status under the current beneficiary-balance model.

struct DeferredCreditStatus {
    uint256 deferredTraderCreditUsdc;
    bool traderPayoutClaimableNow;
    uint256 deferredKeeperCreditUsdc;
    bool keeperCreditClaimableNow;
}

EngineStatusViewTypes

Git Source

Structs

ProtocolStatus

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

HousePoolEngineViewTypes

Git Source

Structs

HousePoolInputSnapshot

struct HousePoolInputSnapshot {
    uint256 physicalAssetsUsdc;
    uint256 netPhysicalAssetsUsdc;
    uint256 maxLiabilityUsdc;
    uint256 supplementalReservedUsdc;
    uint256 unrealizedMtmLiabilityUsdc;
    uint256 deferredTraderCreditUsdc;
    uint256 deferredKeeperCreditUsdc;
    uint256 protocolFeesUsdc;
    bool markFreshnessRequired;
    uint256 maxMarkStaleness;
}

HousePoolStatusSnapshot

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

ICfdEngine

Git Source

Stateful CFD trading engine: processes orders and liquidates positions.

This remains a rich internal/admin integration interface. Product-facing consumers should prefer the slim public surfaces in IPerpsTraderActions, IPerpsTraderViews, IPerpsLPActions, IPerpsLPViews, IPerpsKeeper, IProtocolViews, and IMarginAccount. Live protocol contracts should prefer smaller role-specific interfaces like ICfdEngineCore.

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);

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;

recordDeferredKeeperCredit

Records deferred keeper credit when immediate clearinghouse settlement is unavailable.

Deferred keeper value is always later claimed as clearinghouse credit.

function recordDeferredKeeperCredit(
    address keeper,
    uint256 amountUsdc
) external;

reserveCloseOrderExecutionBounty

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

function reserveCloseOrderExecutionBounty(
    bytes32 accountId,
    uint256 sizeDelta,
    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;

creditKeeperExecutionBounty

Credits a keeper execution bounty into the beneficiary’s clearinghouse account.

Realizes carry first when the beneficiary account currently has an open position so the settlement-balance credit cannot retroactively dilute carry owed over the elapsed interval.

function creditKeeperExecutionBounty(
    address beneficiary,
    uint256 amountUsdc,
    uint256 price,
    uint64 publishTime
) 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

realizeCarryBeforeMarginChange

Realizes accrued carry against the current reachable collateral before a user-level settlement balance mutation changes the carry basis.

function realizeCarryBeforeMarginChange(
    bytes32 accountId,
    uint256 reachableCollateralBasisUsdc
) external;

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);

accumulatedFeesUsdc

Accumulated execution fees awaiting withdrawal (6 decimals)

function accumulatedFeesUsdc() external view returns (uint256);

totalDeferredTraderCreditUsdc

Deferred trader credit still owed to beneficiaries.

function totalDeferredTraderCreditUsdc() external view returns (uint256);

totalDeferredKeeperCreditUsdc

Deferred keeper credit still owed after failed immediate settlement.

function totalDeferredKeeperCreditUsdc() external view returns (uint256);

lastMarkTime

Timestamp of the last mark price update

function lastMarkTime() external view returns (uint64);

updateMarkPrice

Pushes a fresh mark price without processing an order.

This updates the cached mark only; carry is realized on execution and margin-mutating paths.

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);

positions

Returns the current position tuple for an account.

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

getPositionLastCarryTimestamp

Returns the timestamp through which carry has been realized for the position.

function getPositionLastCarryTimestamp(
    bytes32 accountId
) external view returns (uint64);

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);

getProtocolStatus

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

Errors

CfdEngine__TypedOrderFailure

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

CfdEngine__MarkPriceOutOfOrder

error CfdEngine__MarkPriceOutOfOrder();

Structs

SideState

struct SideState {
    uint256 maxProfitUsdc;
    uint256 openInterest;
    uint256 entryNotional;
    uint256 totalMargin;
}

LiquidationPreview

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

Enums

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
}

ICfdEngineAccountLens

Git Source

Functions

getAccountCollateralView

Legacy detailed account lens kept for internal tooling, tests, and migration. Product-facing consumers should prefer IPerpsTraderViews via PerpsPublicLens.

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

getWithdrawableUsdc

function getWithdrawableUsdc(
    bytes32 accountId
) external view returns (uint256 withdrawableUsdc);

getAccountLedgerView

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

getAccountLedgerSnapshot

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

ICfdEngineAdminHost

Git Source

Functions

applyRiskConfig

function applyRiskConfig(
    EngineRiskConfig calldata config
) external;

applyCalendarConfig

function applyCalendarConfig(
    EngineCalendarConfig calldata config
) external;

applyFreshnessConfig

function applyFreshnessConfig(
    EngineFreshnessConfig calldata config
) external;

Structs

EngineRiskConfig

struct EngineRiskConfig {
    CfdTypes.RiskParams riskParams;
    uint256 executionFeeBps;
}

EngineCalendarConfig

struct EngineCalendarConfig {
    uint256[] fadDayTimestamps;
    uint256 fadRunwaySeconds;
}

EngineFreshnessConfig

struct EngineFreshnessConfig {
    uint256 fadMaxStaleness;
    uint256 engineMarkStalenessLimit;
}

ICfdEngineCore

Git Source

Core/operator-facing engine surface used by live perps contracts.

Functions

clearinghouse

function clearinghouse() external view returns (address);

orderRouter

function orderRouter() external view returns (address);

settlementModule

function settlementModule() external view returns (address);

USDC

function USDC() external view returns (IERC20);

lastMarkPrice

function lastMarkPrice() external view returns (uint256);

riskParams

function riskParams()
    external
    view
    returns (
        uint256 vpiFactor,
        uint256 maxSkewRatio,
        uint256 maintMarginBps,
        uint256 initMarginBps,
        uint256 fadMarginBps,
        uint256 baseCarryBps,
        uint256 minBountyUsdc,
        uint256 bountyBps
    );

processOrderTyped

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

recordDeferredKeeperCredit

function recordDeferredKeeperCredit(
    address keeper,
    uint256 amountUsdc
) external;

reserveCloseOrderExecutionBounty

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

absorbRouterCancellationFee

function absorbRouterCancellationFee(
    uint256 amountUsdc
) external;

recordRouterProtocolFee

function recordRouterProtocolFee(
    uint256 amountUsdc
) external;

creditKeeperExecutionBounty

function creditKeeperExecutionBounty(
    address beneficiary,
    uint256 amountUsdc,
    uint256 price,
    uint64 publishTime
) external;

accumulatedFeesUsdc

function accumulatedFeesUsdc() external view returns (uint256);

totalDeferredTraderCreditUsdc

function totalDeferredTraderCreditUsdc() external view returns (uint256);

totalDeferredKeeperCreditUsdc

function totalDeferredKeeperCreditUsdc() external view returns (uint256);

liquidatePosition

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

lastMarkTime

function lastMarkTime() external view returns (uint64);

updateMarkPrice

function updateMarkPrice(
    uint256 price,
    uint64 publishTime
) external;

CAP_PRICE

function CAP_PRICE() external view returns (uint256);

realizeCarryBeforeMarginChange

function realizeCarryBeforeMarginChange(
    bytes32 accountId,
    uint256 reachableCollateralBasisUsdc
) external;

checkpointCarryUsingStoredMark

function checkpointCarryUsingStoredMark(
    bytes32 accountId,
    uint256 reachableCollateralBasisUsdc
) external;

isFadWindow

function isFadWindow() external view returns (bool);

fadMaxStaleness

function fadMaxStaleness() external view returns (uint256);

engineMarkStalenessLimit

function engineMarkStalenessLimit() external view returns (uint256);

fadDayOverrides

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

isOracleFrozen

function isOracleFrozen() external view returns (bool);

positions

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

degradedMode

function degradedMode() external view returns (bool);

getProtocolStatus

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

Errors

CfdEngine__TypedOrderFailure

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

CfdEngine__MarkPriceOutOfOrder

error CfdEngine__MarkPriceOutOfOrder();

ICfdEngineLens

Git Source

Functions

engine

function engine() external view returns (address);

previewClose

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

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);

simulateClose

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

previewLiquidation

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

simulateLiquidation

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

ICfdEnginePlanner

Git Source

Functions

computeOpenMarginAfter

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

planOpen

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

planClose

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

planLiquidation

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

getOpenFailurePolicyCategory

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

getExecutionFailurePolicyCategory

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

getCloseExecutionFailurePolicyCategory

function getCloseExecutionFailurePolicyCategory(
    CfdEnginePlanTypes.CloseRevertCode code
) external pure returns (CfdEnginePlanTypes.ExecutionFailurePolicyCategory);

ICfdEngineProtocolLens

Git Source

Functions

getProtocolAccountingSnapshot

Legacy detailed protocol lens kept for internal tooling, tests, and migration. Product-facing consumers should prefer IPerpsTraderViews, IPerpsLPViews, and IProtocolViews via PerpsPublicLens.

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

getHousePoolInputSnapshot

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

getHousePoolStatusSnapshot

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

ICfdEngineSettlementHost

Git Source

Functions

clearinghouse

function clearinghouse() external view returns (address);

vault

function vault() external view returns (address);

orderRouter

function orderRouter() external view returns (address);

settlementApplyFundingAndMark

function settlementApplyFundingAndMark(
    uint256 newMarkPrice,
    uint64 newMarkTime
) external;

settlementSyncTotalSideMargin

function settlementSyncTotalSideMargin(
    CfdTypes.Side side,
    uint256 marginBefore,
    uint256 marginAfter
) external;

settlementApplySideDelta

function settlementApplySideDelta(
    CfdTypes.Side side,
    int256 maxProfitDelta,
    int256 openInterestDelta,
    int256 entryNotionalDelta
) external;

settlementConsumeDeferredTraderPayout

function settlementConsumeDeferredTraderPayout(
    bytes32 accountId,
    uint256 amountUsdc
) external;

settlementRecordDeferredTraderPayout

function settlementRecordDeferredTraderPayout(
    bytes32 accountId,
    uint256 amountUsdc
) external;

settlementAccumulateFees

function settlementAccumulateFees(
    uint256 amountUsdc
) external;

settlementAccumulateBadDebt

function settlementAccumulateBadDebt(
    uint256 amountUsdc
) external;

settlementWritePosition

function settlementWritePosition(
    bytes32 accountId,
    CfdEngineSettlementTypes.PositionState calldata position
) external;

settlementDeletePosition

function settlementDeletePosition(
    bytes32 accountId
) external;

ICfdEngineSettlementModule

Git Source

Functions

executeOpen

function executeOpen(
    ICfdEngineSettlementHost host,
    CfdEnginePlanTypes.OpenDelta calldata delta,
    CfdTypes.Position calldata currentPosition,
    uint64 publishTime
) external;

executeClose

function executeClose(
    ICfdEngineSettlementHost host,
    CfdEnginePlanTypes.CloseDelta calldata delta,
    CfdTypes.Position calldata currentPosition,
    uint64 publishTime
) external;

executeLiquidation

function executeLiquidation(
    ICfdEngineSettlementHost host,
    CfdEnginePlanTypes.LiquidationDelta calldata delta,
    uint64 publishTime
) external returns (uint256 keeperBountyUsdc);

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;

recordClaimantInflow

Records claimant-owned value that should ultimately flow through the tranche waterfall.

CashArrived increments canonical accounted assets because raw USDC arrived in this flow. AlreadyRetained only routes ownership for value already retained physically by the vault.

function recordClaimantInflow(
    uint256 amount,
    ClaimantInflowKind kind,
    ClaimantInflowCashMode cashMode
) 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);

Enums

ClaimantInflowKind

enum ClaimantInflowKind {
    Revenue,
    Recapitalization
}

ClaimantInflowCashMode

enum ClaimantInflowCashMode {
    CashArrived,
    AlreadyRetained
}

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);

isOracleFrozen

function isOracleFrozen() external view returns (bool);

frozenLpFeeBps

function frozenLpFeeBps(
    bool isSenior
) external view returns (uint256);

IMarginAccount

Git Source

Public trader-facing margin account surface stripped of internal reservation and bucket plumbing.

Functions

depositMargin

function depositMargin(
    uint256 amount
) external;

withdrawMargin

function withdrawMargin(
    uint256 amount
) external;

getAccountEquityUsdc

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

getFreeBuyingPowerUsdc

Returns settlement equity that is not currently locked into margin buckets.

This is a clearinghouse-local view and does not account for engine withdrawal guards.

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

IMarginClearinghouse

Git Source

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

This is the full operator/integration surface. Product-facing consumers should prefer IMarginAccount and avoid depending on reservation buckets, internal custody buckets, or settlement-path helpers.

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 settlement USDC for realized PnL, deferred-claim servicing, 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);

consumeSettlementLoss

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

function consumeSettlementLoss(
    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;

reserveCloseExecutionBountyFromSettlement

Reserves free-settlement USDC for a close-order execution bounty with carry checkpointing.

Restricted to the engine’s atomic fresh close-bounty path.

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

reserveStaleCloseExecutionBountyFromSettlement

Reserves free-settlement USDC for a stale close-order execution bounty without checkpointing carry.

Restricted to the engine’s atomic stale close-bounty path.

function reserveStaleCloseExecutionBountyFromSettlement(
    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;

reserveStaleCloseExecutionBountyFromPositionMargin

Reserves active position margin for a stale close-order execution bounty without checkpointing carry.

Restricted to the engine’s bounded stale close-bounty path.

function reserveStaleCloseExecutionBountyFromPositionMargin(
    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);

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

ReservationStatus

enum ReservationStatus {
    None,
    Active,
    Consumed,
    Released
}

IOrderRouterAccounting

Git Source

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

This remains an internal/admin integration surface. Product-facing consumers should prefer IPerpsTraderViews via PerpsPublicLens and avoid depending on queue-accounting internals directly.

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);

accountHeadOrderId

Returns the current account-queue head id for pending-order traversal.

function accountHeadOrderId(
    bytes32 accountId
) external view returns (uint64 headOrderId);

getPendingOrderView

Returns the pending-order view for a specific order plus the next account-queue order id.

function getPendingOrderView(
    uint64 orderId
) external view returns (PendingOrderView memory pending, uint64 nextAccountOrderId);

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;
}

PendingOrderView

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

Enums

OrderStatus

enum OrderStatus {
    None,
    Pending,
    Executed,
    Failed
}

IOrderRouterAdminHost

Git Source

Functions

applyRouterConfig

function applyRouterConfig(
    RouterConfig calldata config
) external;

applyOracleConfig

function applyOracleConfig(
    OracleConfig calldata config
) external;

Structs

RouterConfig

struct RouterConfig {
    uint256 maxOrderAge;
    uint256 orderExecutionStalenessLimit;
    uint256 liquidationStalenessLimit;
    uint256 pythMaxConfidenceRatioBps;
    uint256 minOpenNotionalUsdc;
    uint256 openOrderExecutionBountyBps;
    uint256 minOpenOrderExecutionBountyUsdc;
    uint256 maxOpenOrderExecutionBountyUsdc;
    uint256 closeOrderExecutionBountyUsdc;
    uint256 maxPendingOrders;
    uint256 minEngineGas;
    uint256 maxPruneOrdersPerCall;
}

OracleConfig

struct OracleConfig {
    address pyth;
    bytes32[] feedIds;
    uint256[] quantities;
    uint256[] basePrices;
    bool[] inversions;
}

IPerpsAdmin

Git Source

Administrative surface for perps configuration, emergency controls, and one-time setup.

Functions

setPauser

function setPauser(
    address newPauser
) external;

pause

function pause() external;

unpause

function unpause() external;

IPerpsKeeper

Git Source

Keeper-facing execution and liquidation surface for the simplified product API.

Functions

executeOrder

Executes the next eligible delayed order using fresh oracle data.

function executeOrder(
    uint64 orderId,
    bytes[] calldata pythUpdateData
) external payable;

executeOrderBatch

Executes a bounded batch of eligible delayed orders using a shared oracle update.

function executeOrderBatch(
    uint64 maxOrderId,
    bytes[] calldata pythUpdateData
) external payable;

executeLiquidation

Liquidates an unsafe account using fresh oracle data.

function executeLiquidation(
    bytes32 accountId,
    bytes[] calldata pythUpdateData
) external payable;

IPerpsLP

Git Source

Inherits: IPerpsLPActions, IPerpsLPViews

Combined LP-facing surface for the simplified perps product API.

IPerpsLPActions

Git Source

LP-facing senior/junior tranche action surface.

Functions

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;

IPerpsLPViews

Git Source

Compact LP-facing read surface for senior and junior tranches.

Functions

getSeniorTranche

function getSeniorTranche() external view returns (PerpsViewTypes.TrancheView memory viewData);

getJuniorTranche

function getJuniorTranche() external view returns (PerpsViewTypes.TrancheView memory viewData);

getLpStatus

function getLpStatus() external view returns (PerpsViewTypes.LpStatusView memory viewData);

IPerpsTrader

Git Source

Inherits: IPerpsTraderActions, IPerpsTraderViews

Combined trader-facing surface for the simplified perps product API.

IPerpsTraderActions

Git Source

Trader-facing action surface aligned with the current delayed-order router model.

Functions

commitOrder

function commitOrder(
    CfdTypes.Side side,
    uint256 sizeDelta,
    uint256 marginDelta,
    uint256 targetPrice,
    bool isClose
) external;

IPerpsTraderViews

Git Source

Compact trader-facing read surface for the simplified perps product API.

Functions

getTraderAccount

function getTraderAccount(
    bytes32 accountId
) external view returns (PerpsViewTypes.TraderAccountView memory viewData);

getPosition

function getPosition(
    bytes32 accountId
) external view returns (PerpsViewTypes.PositionView memory viewData);

getPendingOrders

function getPendingOrders(
    bytes32 accountId
) external view returns (PerpsViewTypes.PendingOrderView[] memory pending);

isLiquidatable

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

IProtocolViews

Git Source

Compact protocol-wide read surface for product consumers.

Functions

getProtocolStatus

function getProtocolStatus() external view returns (PerpsViewTypes.ProtocolStatusView memory viewData);

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;

Parameters

PerpsViewTypes

Git Source

Canonical public-facing view structs for the simplified perps product surface.

Structs

TraderAccountView

struct TraderAccountView {
    uint256 equityUsdc;
    uint256 withdrawableUsdc;
    uint256 pendingOrderMarginUsdc;
    uint256 pendingExecutionBountyUsdc;
    bool hasOpenPosition;
    bool liquidatable;
}

PositionView

struct PositionView {
    bool exists;
    CfdTypes.Side side;
    uint256 size;
    uint256 entryPrice;
    uint256 marginUsdc;
    int256 unrealizedPnlUsdc;
    uint256 maintenanceMarginUsdc;
    bool liquidatable;
}

PendingOrderView

struct PendingOrderView {
    uint64 orderId;
    CfdTypes.Side side;
    uint256 sizeDelta;
    int256 marginDeltaUsdc;
    uint256 acceptablePrice;
    bool isReduceOnly;
    OrderStatus status;
}

TrancheView

struct TrancheView {
    uint256 totalAssetsUsdc;
    uint256 totalShares;
    uint256 sharePrice;
    uint256 maxWithdrawUsdc;
    uint256 frozenLpFeeBps;
    bool depositEnabled;
    bool withdrawEnabled;
    bool oracleFrozen;
}

LpStatusView

struct LpStatusView {
    bool tradingActive;
    bool withdrawalLive;
    uint64 lastMarkTime;
    bool oracleFresh;
    bool oracleFrozen;
}

ProtocolStatusView

struct ProtocolStatusView {
    uint8 phase;
    uint256 lastMarkPrice;
    uint64 lastMarkTime;
    bool oracleFrozen;
    bool fadWindow;
    bool tradingActive;
    bool withdrawalLive;
}

Enums

OrderStatus

enum OrderStatus {
    None,
    Pending,
    Executed,
    Failed
}

ProtocolLensViewTypes

Git Source

Structs

ProtocolAccountingSnapshot

struct ProtocolAccountingSnapshot {
    uint256 vaultAssetsUsdc;
    uint256 netPhysicalAssetsUsdc;
    uint256 maxLiabilityUsdc;
    uint256 effectiveSolvencyAssetsUsdc;
    uint256 withdrawalReservedUsdc;
    uint256 freeUsdc;
    uint256 accumulatedFeesUsdc;
    uint256 accumulatedBadDebtUsdc;
    uint256 totalDeferredTraderCreditUsdc;
    uint256 totalDeferredKeeperCreditUsdc;
    bool degradedMode;
    bool hasLiveLiability;
}

Contents

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

CashPriorityLib

Git Source

Functions

reserveFreshPayouts

function reserveFreshPayouts(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc
) internal pure returns (SeniorCashReservation memory reservation);

reserveDeferredClaim

function reserveDeferredClaim(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc,
    uint256 deferredClaimAmountUsdc
) internal pure returns (SeniorCashReservation memory reservation);

reservedSeniorCashUsdc

function reservedSeniorCashUsdc(
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc
) internal pure returns (uint256);

availableCashForFreshPayouts

function availableCashForFreshPayouts(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc
) internal pure returns (uint256);

availableCashForDeferredBeneficiaryClaim

function availableCashForDeferredBeneficiaryClaim(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc,
    uint256 claimAmountUsdc
) internal pure returns (uint256);

availableCashForProtocolFeeWithdrawal

function availableCashForProtocolFeeWithdrawal(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc
) internal pure returns (uint256);

canPayFreshPayout

function canPayFreshPayout(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc,
    uint256 amountUsdc
) internal pure returns (bool);

canPayDeferredBeneficiaryClaim

function canPayDeferredBeneficiaryClaim(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc,
    uint256 claimAmountUsdc
) internal pure returns (bool);

canWithdrawProtocolFees

function canWithdrawProtocolFees(
    uint256 physicalAssetsUsdc,
    uint256 protocolFeesUsdc,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc,
    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 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc
) private pure returns (SeniorCashReservation memory reservation);

Structs

SeniorCashReservation

struct SeniorCashReservation {
    uint256 physicalAssetsUsdc;
    uint256 protocolFeesUsdc;
    uint256 deferredTraderCreditUsdc;
    uint256 deferredKeeperCreditUsdc;
    uint256 totalSeniorClaimsUsdc;
    uint256 reservedSeniorCashUsdc;
    uint256 protocolFeeWithdrawalUsdc;
    uint256 freeCashUsdc;
    uint256 deferredClaimServiceableUsdc;
}

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

_liquidationVpiClawbackUsdc

function _liquidationVpiClawbackUsdc(
    int256 vpiAccrued
) private pure returns (uint256);

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);

_planDeferredTraderCreditConsumption

function _planDeferredTraderCreditConsumption(
    uint256 deferredTraderCreditUsdc,
    uint256 shortfallUsdc,
    bool shortfallAlreadyIncludesDeferred
) private pure returns (uint256 consumedUsdc, uint256 remainingUsdc, uint256 badDebtUsdc);

_planCloseDeferredTraderCreditConsumption

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

planOpen

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

_applyPendingCarryRealizationToOpenSnapshot

function _applyPendingCarryRealizationToOpenSnapshot(
    CfdEnginePlanTypes.RawSnapshot memory snap,
    uint256 pendingCarryUsdc
) private pure returns (bool hasShortfall);

_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,
    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);

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

Structs

SolvencySnapshot

struct SolvencySnapshot {
    uint256 physicalAssets;
    uint256 protocolFees;
    uint256 netPhysicalAssets;
    uint256 maxLiability;
    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
) 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(
    HousePoolEngineViewTypes.HousePoolInputSnapshot memory engineSnapshot
) internal pure returns (WithdrawalSnapshot memory snapshot);

buildReconcileSnapshot

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

getMarkFreshnessPolicy

function getMarkFreshnessPolicy(
    HousePoolEngineViewTypes.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(
    HousePoolEngineViewTypes.HousePoolInputSnapshot memory accountingSnapshot,
    HousePoolEngineViewTypes.HousePoolStatusSnapshot memory statusSnapshot,
    uint256 currentTimestamp
) internal pure returns (bool);

withdrawalsLive

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

markFresh

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

HousePoolPendingLivePlanLib

Git Source

Functions

planApplyPendingClaimantBuckets

function planApplyPendingClaimantBuckets(
    HousePoolPendingPreviewLib.PendingAccountingState memory state,
    uint256 currentSeniorPrincipal,
    HousePoolPendingPreviewLib.ClaimantPendingBuckets memory claimantBuckets
) internal pure returns (PendingLivePlan memory plan);

Structs

PendingLivePlan

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

HousePoolPendingPreviewLib

Git Source

Functions

applyPendingClaimantBucketsPreview

function applyPendingClaimantBucketsPreview(
    PendingAccountingState memory state,
    ClaimantPendingBuckets memory claimantBuckets
) internal pure;

applyClaimantRecapitalizationIntent

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

applyRevenueIntent

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

Structs

ClaimantPendingBuckets

struct ClaimantPendingBuckets {
    uint256 recapitalizationUsdc;
    uint256 revenueUsdc;
}

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 equityUsdc,
    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);

getSettlementBalanceUsdc

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

getFreeSettlementUsdc

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

getPositionMarginUsdc

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

getQueuedReservedUsdc

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

getGenericReachableUsdc

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

planFundingLossConsumption

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

planOpenCostApplication

function planOpenCostApplication(
    IMarginClearinghouse.AccountUsdcBuckets memory buckets,
    uint256 marginDeltaUsdc,
    int256 tradeCostUsdc
) internal pure returns (OpenCostPlan memory plan);

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;
}

OpenCostPlan

struct OpenCostPlan {
    int256 netMarginChangeUsdc;
    uint256 settlementCreditUsdc;
    uint256 settlementDebitUsdc;
    uint256 positionMarginUnlockedUsdc;
    uint256 positionMarginLockedUsdc;
    uint256 resultingSettlementBalanceUsdc;
    uint256 resultingPositionMarginUsdc;
    uint256 resultingFreeSettlementUsdc;
    bool insufficientFreeEquity;
    bool insufficientPositionMargin;
}

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;
    CfdTypes.RiskParams riskParams;
}

OpenState

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

OracleFreshnessPolicyLib

Git Source

Functions

getPolicy

function getPolicy(
    Mode mode,
    bool oracleFrozen,
    bool isFad,
    uint256 engineMarkStalenessLimit,
    uint256 poolMarkStalenessLimit,
    uint256 routerOrderExecutionStalenessLimit,
    uint256 routerLiquidationStalenessLimit,
    uint256 fadMaxStaleness
) internal pure returns (Policy memory policy);

isStale

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

_effectiveLiveMarkLimit

function _effectiveLiveMarkLimit(
    uint256 engineMarkStalenessLimit,
    uint256 poolMarkStalenessLimit
) private pure returns (uint256);

Structs

Policy

struct Policy {
    bool closeOnly;
    bool requireStoredMark;
    bool allowAnyStoredMark;
    uint256 maxStaleness;
}

Enums

Mode

enum Mode {
    OpenExecution,
    CloseExecution,
    Liquidation,
    PoolReconcile,
    CloseCommitFallback,
    MarkRefresh
}

OrderFailurePolicyLib

Git Source

Functions

isPredictablyInvalidOpen

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

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(
    uint256 oraclePublishTime,
    uint256 maxStaleness,
    uint256 currentTimestamp
) internal pure returns (bool);

Structs

OracleExecutionPolicy

struct OracleExecutionPolicy {
    bool closeOnly;
    uint256 maxStaleness;
}

Enums

OracleAction

enum OracleAction {
    OrderExecution,
    MarkRefresh,
    Liquidation
}

PositionRiskAccountingLib

Git Source

Functions

_vpiClawbackUsdc

function _vpiClawbackUsdc(
    int256 vpiAccrued
) private pure returns (uint256);

computeLpBackedNotionalUsdc

function computeLpBackedNotionalUsdc(
    uint256 size,
    uint256 price,
    uint256 reachableCollateralUsdc
) internal pure returns (uint256 lpBackedNotionalUsdc);

computePendingCarryUsdc

function computePendingCarryUsdc(
    uint256 lpBackedNotionalUsdc,
    uint256 baseCarryBps,
    uint256 timeDelta
) internal pure returns (uint256 carryUsdc);

buildPositionRiskState

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

buildPositionRiskStateWithCarry

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

Structs

PositionRiskState

struct PositionRiskState {
    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,
    uint256 deferredTraderCreditUsdc,
    uint256 deferredKeeperCreditUsdc
) 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 deferredKeeperCreditDeltaUsdc;
    uint256 pendingVaultPayoutUsdc;
}

PreviewResult

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

SolvencyState

struct SolvencyState {
    uint256 physicalAssetsUsdc;
    uint256 protocolFeesUsdc;
    uint256 netPhysicalAssetsUsdc;
    uint256 maxLiabilityUsdc;
    uint256 deferredTraderCreditUsdc;
    uint256 deferredKeeperCreditUsdc;
    uint256 withdrawalReservedUsdc;
    uint256 freeWithdrawableUsdc;
    uint256 effectiveAssetsUsdc;
}

Contents

• OrderEscrowAccounting
• OrderExecutionOrchestrator
• OrderOracleExecution
• OrderQueueBook

OrderEscrowAccounting

Git Source

Inherits: IOrderRouterAccounting

Constants

engine

ICfdEngineCore 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;

accountHeadOrderId

mapping(bytes32 => uint64) public accountHeadOrderId;

accountTailOrderId

mapping(bytes32 => uint64) internal accountTailOrderId;

marginHeadOrderId

mapping(bytes32 => uint64) public marginHeadOrderId;

marginTailOrderId

mapping(bytes32 => uint64) public marginTailOrderId;

Functions

constructor

constructor(
    address _engine
);

getAccountEscrow

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

_summarizePendingOrders

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

_nextCommitId

function _nextCommitId() internal view virtual returns (uint64);

getMarginReservationIds

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

_reserveExecutionBounty

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

_reserveCommittedMargin

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

_consumeOrderEscrow

function _consumeOrderEscrow(
    uint64 orderId,
    bool success,
    uint256 executionPrice,
    uint64 oraclePublishTime
) internal returns (uint256 executionBountyUsdc);

_collectExecutionBounty

function _collectExecutionBounty(
    uint64 orderId,
    uint256 executionPrice,
    uint64 oraclePublishTime
) internal returns (uint256 executionBountyUsdc);

_releaseCommittedMargin

function _releaseCommittedMargin(
    uint64 orderId
) internal;

_linkMarginOrder

function _linkMarginOrder(
    bytes32 accountId,
    uint64 orderId
) internal;

_linkAccountOrder

function _linkAccountOrder(
    bytes32 accountId,
    uint64 orderId
) internal;

_unlinkAccountOrder

function _unlinkAccountOrder(
    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);

_reserveCloseExecutionBounty

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

_revertInsufficientFreeEquity

function _revertInsufficientFreeEquity() internal pure virtual;

_revertMarginOrderLinkCorrupted

function _revertMarginOrderLinkCorrupted() internal pure virtual;

_revertPendingOrderLinkCorrupted

function _revertPendingOrderLinkCorrupted() internal pure virtual;

Structs

OrderRecord

struct OrderRecord {
    CfdTypes.Order core;
    IOrderRouterAccounting.OrderStatus status;
    uint256 executionBountyUsdc;
    uint64 nextGlobalOrderId;
    uint64 prevGlobalOrderId;
    uint64 nextAccountOrderId;
    uint64 prevAccountOrderId;
    uint64 nextMarginOrderId;
    uint64 prevMarginOrderId;
    bool inAccountQueue;
    bool inMarginQueue;
}

OrderExecutionOrchestrator

Git Source

Inherits: OrderOracleExecution, OrderQueueBook

Constants

PANIC_SELECTOR

bytes4 internal constant PANIC_SELECTOR = 0x4e487b71;

TYPED_ORDER_FAILURE_SELECTOR

bytes4 internal constant TYPED_ORDER_FAILURE_SELECTOR = ICfdEngineCore.CfdEngine__TypedOrderFailure.selector;

MARK_PRICE_OUT_OF_ORDER_SELECTOR

bytes4 internal constant MARK_PRICE_OUT_OF_ORDER_SELECTOR = ICfdEngineCore.CfdEngine__MarkPriceOutOfOrder.selector;

State Variables

minEngineGas

uint256 public minEngineGas;

maxPruneOrdersPerCall

uint256 public maxPruneOrdersPerCall;

Functions

_maxOrderAge

function _maxOrderAge() internal view virtual returns (uint256);

_queueHeadOrderId

function _queueHeadOrderId() internal view virtual override returns (uint64);

_setQueueHeadOrderId

function _setQueueHeadOrderId(
    uint64 orderId
) internal virtual override;

_revertNoOrdersToExecute

function _revertNoOrdersToExecute() internal pure virtual;

_revertInsufficientGas

function _revertInsufficientGas() internal pure virtual;

_revertMevDetected

function _revertMevDetected() internal pure virtual;

_revertCloseOnlyMode

function _revertCloseOnlyMode() internal pure virtual;

_releaseCommittedMarginForExecution

function _releaseCommittedMarginForExecution(
    uint64 orderId
) internal virtual;

_deleteOrder

function _deleteOrder(
    uint64 orderId,
    IOrderRouterAccounting.OrderStatus terminalStatus
) internal virtual;

_skipStaleOrders

function _skipStaleOrders(
    uint64 upToId,
    uint256 executionPrice,
    uint64 oraclePublishTime
) internal returns (uint256 skipped);

_pruneExpiredHeadOrders

function _pruneExpiredHeadOrders(
    uint64 upToId,
    uint256 maxPrunes,
    uint256 executionPrice,
    uint64 oraclePublishTime
) internal returns (uint256 pruned);

_processTypedOrderExecution

function _processTypedOrderExecution(
    CfdTypes.Order memory order,
    uint256 executionPrice,
    uint256 vaultDepth,
    uint64 oraclePublishTime
) internal returns (bool success, OrderFailReason failureReason, FailedOrderOutcome failureOutcome);

_executePendingOrder

function _executePendingOrder(
    uint64 orderId,
    CfdTypes.Order memory order,
    uint256 executionPrice,
    uint64 oraclePublishTime,
    RouterExecutionContext memory executionContext,
    bool revertOnBlockedExecution,
    uint256 pythFee
) internal returns (OrderExecutionStepResult result);

_finalizeOrCleanupOrder

function _finalizeOrCleanupOrder(
    uint64 orderId,
    uint256 pythFee,
    bool success,
    FailedOrderOutcome failedOutcome,
    bool refundEthNow,
    uint256 executionPrice,
    uint64 oraclePublishTime
) internal;

_decodeTypedOrderFailure

function _decodeTypedOrderFailure(
    bytes memory revertData
)
    internal
    pure
    returns (CfdEnginePlanTypes.ExecutionFailurePolicyCategory failureCategory, uint8 failureCode, bool isClose);

_failedOutcomeFromEngineRevert

function _failedOutcomeFromEngineRevert(
    CfdTypes.Order memory order,
    bytes memory revertData
) internal pure returns (FailedOrderOutcome outcome);

_failedOutcomeForTerminalFailure

function _failedOutcomeForTerminalFailure(
    CfdTypes.Order memory order
) internal pure returns (FailedOrderOutcome outcome);

_failedOutcomeForSlippageFailure

function _failedOutcomeForSlippageFailure(
    CfdTypes.Order memory order
) internal pure returns (FailedOrderOutcome outcome);

_cleanupOrder

function _cleanupOrder(
    uint64 orderId,
    FailedOrderOutcome,
    uint256 executionPrice,
    uint64 oraclePublishTime
) internal returns (uint256 executionBountyUsdc);

_finalizeExecution

function _finalizeExecution(
    uint64 orderId,
    uint256 executionPrice,
    uint64 oraclePublishTime
) internal;

_sendEth

function _sendEth(
    address to,
    uint256 amount
) internal virtual;

Events

OrderExecuted

event OrderExecuted(uint64 indexed orderId, uint256 executionPrice);

OrderFailed

event OrderFailed(uint64 indexed orderId, OrderFailReason reason);

Enums

OrderExecutionStepResult

enum OrderExecutionStepResult {
    Continue,
    Break,
    Return
}

FailedOrderOutcome

enum FailedOrderOutcome {
    ClearerFull
}

OrderFailReason

enum OrderFailReason {
    Expired,
    CloseOnly,
    SlippageExceeded,
    EnginePanic,
    AccountLiquidated,
    EngineRevert
}

OrderOracleExecution

Git Source

Inherits: OrderEscrowAccounting

Constants

vault

ICfdVault internal immutable vault;

engineLens

ICfdEngineLens internal immutable engineLens;

State Variables

pyth

IPyth public pyth;

pythFeedIds

bytes32[] public pythFeedIds;

quantities

uint256[] public quantities;

basePrices

uint256[] public basePrices;

inversions

bool[] public inversions;

orderExecutionStalenessLimit

uint256 public orderExecutionStalenessLimit = 60;

liquidationStalenessLimit

uint256 public liquidationStalenessLimit = 15;

pythMaxConfidenceRatioBps

uint256 public pythMaxConfidenceRatioBps = 10_000;

Functions

_revertZeroAddress

function _revertZeroAddress() internal pure virtual;

_revertEmptyFeeds

function _revertEmptyFeeds() internal pure virtual;

_revertLengthMismatch

function _revertLengthMismatch() internal pure virtual;

_revertInvalidBasePrice

function _revertInvalidBasePrice() internal pure virtual;

_revertInvalidWeights

function _revertInvalidWeights() internal pure virtual;

_revertMissingPythUpdateData

function _revertMissingPythUpdateData() internal pure virtual;

_revertInsufficientPythFee

function _revertInsufficientPythFee() internal pure virtual;

_revertMockModeDisabled

function _revertMockModeDisabled() internal pure virtual;

_revertOraclePriceTooStale

function _revertOraclePriceTooStale() internal pure virtual;

_revertOracleConfidenceTooWide

function _revertOracleConfidenceTooWide() internal pure virtual;

_revertOraclePublishTimeOutOfOrder

function _revertOraclePublishTimeOutOfOrder() internal pure virtual;

_revertMevOraclePriceTooStale

function _revertMevOraclePriceTooStale() internal pure virtual;

_revertOraclePriceNegative

function _revertOraclePriceNegative() internal pure virtual;

constructor

constructor(
    address _engine,
    address _engineLens,
    address _vault,
    address _pyth,
    bytes32[] memory _feedIds,
    uint256[] memory _quantities,
    uint256[] memory _basePrices,
    bool[] memory _inversions
) OrderEscrowAccounting(_engine);

_currentRouterExecutionContext

function _currentRouterExecutionContext() internal view returns (RouterExecutionContext memory context);

_prepareOrderExecutionOracle

function _prepareOrderExecutionOracle(
    bytes[] calldata pythUpdateData,
    uint256 mockFallbackPrice
) internal returns (OracleUpdateResult memory update, RouterExecutionContext memory executionContext);

_prepareMarkRefreshOracle

function _prepareMarkRefreshOracle(
    bytes[] calldata pythUpdateData
) internal returns (OracleUpdateResult memory update);

_prepareLiquidationOracle

function _prepareLiquidationOracle(
    bytes[] calldata pythUpdateData
) internal returns (OracleUpdateResult memory update);

_executionPolicyForOrder

function _executionPolicyForOrder(
    bool isClose,
    bool oracleFrozen,
    bool isFadWindow
) internal view returns (OracleFreshnessPolicyLib.Policy memory);

_resolveOraclePrice

function _resolveOraclePrice(
    bytes[] calldata pythUpdateData,
    uint256 mockFallbackPrice,
    uint256 maxStaleness,
    uint256 maxPublishTimeDivergence
) internal returns (uint256 price, uint64 publishTime, uint256 pythFee);

_setOracleConfig

function _setOracleConfig(
    address newPyth,
    bytes32[] memory newFeedIds,
    uint256[] memory newQuantities,
    uint256[] memory newBasePrices,
    bool[] memory newInversions
) internal;

_validateOracleConfig

function _validateOracleConfig(
    address newPyth,
    bytes32[] memory newFeedIds,
    uint256[] memory newQuantities,
    uint256[] memory newBasePrices,
    bool[] memory newInversions
) internal pure;

_computeBasketPrice

function _computeBasketPrice(
    uint256 maxStaleness,
    uint256 maxPublishTimeDivergence
) internal view returns (uint256 basketPrice, uint256 minPublishTime);

_checkSlippage

function _checkSlippage(
    CfdTypes.Order memory order,
    uint256 executionPrice
) internal pure returns (bool);

_commitReferencePrice

function _commitReferencePrice() internal view returns (uint256 price);

_canUseCommitMarkForOpenPrefilter

function _canUseCommitMarkForOpenPrefilter() internal view returns (bool);

_isOracleFrozen

function _isOracleFrozen() internal view returns (bool);

_isCloseOnlyWindow

function _isCloseOnlyWindow() internal view returns (bool);

_invertPythPrice

function _invertPythPrice(
    int64 price,
    int32 expo
) internal pure returns (uint256);

_normalizePythPrice

function _normalizePythPrice(
    int64 price,
    int32 expo
) internal pure returns (uint256);

Structs

RouterExecutionContext

struct RouterExecutionContext {
    bool oracleFrozen;
    bool isFadWindow;
    OracleFreshnessPolicyLib.Policy policy;
}

OracleUpdateResult

struct OracleUpdateResult {
    uint256 executionPrice;
    uint64 oraclePublishTime;
    uint256 pythFee;
}

OrderQueueBook

Git Source

Inherits: OrderEscrowAccounting

Functions

_queueHeadOrderId

function _queueHeadOrderId() internal view virtual returns (uint64);

_setQueueHeadOrderId

function _setQueueHeadOrderId(
    uint64 orderId
) internal virtual;

_queueTailOrderId

function _queueTailOrderId() internal view virtual returns (uint64);

_setQueueTailOrderId

function _setQueueTailOrderId(
    uint64 orderId
) internal virtual;

_revertOrderNotPending

function _revertOrderNotPending() internal pure virtual;

_linkGlobalOrder

function _linkGlobalOrder(
    uint64 orderId
) internal;

_unlinkGlobalOrder

function _unlinkGlobalOrder(
    uint64 orderId
) internal;

_pendingOrder

function _pendingOrder(
    uint64 orderId
) internal view returns (OrderRecord storage record, CfdTypes.Order memory order);

_getQueuedPositionView

function _getQueuedPositionView(
    bytes32 accountId
) internal view returns (QueuedPositionView memory queuedPosition);

Structs

QueuedPositionView

struct QueuedPositionView {
    bool exists;
    CfdTypes.Side side;
    uint256 size;
}

CfdEngine

Git Source

Inherits: IWithdrawGuard, ICfdEngineAdminHost, 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;

State Variables

vault

ICfdVault public vault;

planner

ICfdEnginePlanner public planner;

settlementModule

ICfdEngineSettlementModule public settlementModule;

admin

address public admin;

sides

SideState[2] public sides;

lastMarkPrice

uint256 public lastMarkPrice;

lastMarkTime

uint64 public lastMarkTime;

accumulatedFeesUsdc

uint256 public accumulatedFeesUsdc;

accumulatedBadDebtUsdc

uint256 public accumulatedBadDebtUsdc;

unsettledCarryUsdc

mapping(bytes32 => uint256) public unsettledCarryUsdc;

degradedMode

bool public degradedMode;

riskParams

CfdTypes.RiskParams public riskParams;

_positions

mapping(bytes32 => StoredPosition) internal _positions;

deferredTraderCreditUsdc

mapping(bytes32 => uint256) public deferredTraderCreditUsdc;

totalDeferredTraderCreditUsdc

uint256 public totalDeferredTraderCreditUsdc;

deferredKeeperCreditUsdc

mapping(address => uint256) public deferredKeeperCreditUsdc;

totalDeferredKeeperCreditUsdc

uint256 public totalDeferredKeeperCreditUsdc;

orderRouter

address public orderRouter;

fadDayOverrides

mapping(uint256 => bool) public fadDayOverrides;

_fadOverrideDays

uint256[] private _fadOverrideDays;

fadMaxStaleness

uint256 public fadMaxStaleness = 3 days;

fadRunwaySeconds

uint256 public fadRunwaySeconds = 3 hours;

engineMarkStalenessLimit

uint256 public engineMarkStalenessLimit = 60;

executionFeeBps

uint256 public executionFeeBps = 4;

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);

_checkpointDeferredClaimCarryIfPossible

function _checkpointDeferredClaimCarryIfPossible(
    bytes32 accountId,
    StoredPosition storage pos
) internal;

_claimDeferredBalance

function _claimDeferredBalance(
    uint256 amount,
    bytes32 accountId
) internal returns (uint256 claimAmountUsdc);

_increaseDeferredLiability

function _increaseDeferredLiability(
    uint256 currentAmountUsdc,
    uint256 currentTotalUsdc,
    uint256 amountUsdc
) internal pure returns (uint256 updatedAmountUsdc, uint256 updatedTotalUsdc);

_decreaseDeferredLiability

function _decreaseDeferredLiability(
    uint256 currentAmountUsdc,
    uint256 currentTotalUsdc,
    uint256 amountUsdc
) internal pure returns (uint256 updatedAmountUsdc, uint256 updatedTotalUsdc);

onlyRouter

modifier onlyRouter();

onlySettlementModule

modifier onlySettlementModule();

onlyAdmin

modifier onlyAdmin();

constructor

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

Parameters

setDependencies

One-time setter for planner, settlement module, and admin sidecars.

function setDependencies(
    address planner_,
    address settlementModule_,
    address admin_
) external onlyOwner;

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;

withdrawFees

Withdraws accumulated execution fees from the vault to a recipient.

function withdrawFees(
    address recipient
) external onlyOwner;

withdrawFees

Withdraws up to amountUsdc of accumulated execution fees from the vault to a recipient.

function withdrawFees(
    address recipient,
    uint256 amountUsdc
) public 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 funded the vault.

function recordRouterProtocolFee(
    uint256 amountUsdc
) external onlyRouter;

creditKeeperExecutionBounty

Credits a router-collected execution bounty into the beneficiary’s clearinghouse account.

Realizes carry first when the beneficiary currently has an open position because the clearinghouse settlement credit changes the carry basis. Router execution already validates the oracle publish time, so this helper only enforces monotonic publish ordering before checkpointing against the validated cached mark.

function creditKeeperExecutionBounty(
    address beneficiary,
    uint256 amountUsdc,
    uint256 price,
    uint64 publishTime
) external onlyRouter nonReentrant;

addMargin

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

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

realizeCarryBeforeMarginChange

Realizes accrued carry before a user-level clearinghouse balance mutation changes the carry basis.

Called only by the clearinghouse before user deposits and withdrawals.

function realizeCarryBeforeMarginChange(
    bytes32 accountId,
    uint256 reachableCollateralBasisUsdc
) external nonReentrant;

checkpointCarryUsingStoredMark

Checkpoints carry against the cached stored mark when fresh-mark liveness is unavailable.

Restricted to the clearinghouse stale-deposit path so deposits preserve pre-mutation carry basis.

function checkpointCarryUsingStoredMark(
    bytes32 accountId,
    uint256 reachableCollateralBasisUsdc
) external nonReentrant;

claimDeferredTraderCredit

Claims deferred trader credit balance into the clearinghouse.

The claim can be partial if current vault cash is insufficient. Funds are credited to the clearinghouse first, so beneficiaries access them through the normal account-balance path. Carry is checkpointed before the settlement-basis change using a fresh mark when available, otherwise the cached stored mark is used.

function claimDeferredTraderCredit(
    bytes32 accountId
) external nonReentrant;

claimDeferredKeeperCredit

Claims previously deferred keeper credit when the vault has replenished cash.

Deferred keeper value always settles to clearinghouse credit for the recorded keeper address-derived account.

function claimDeferredKeeperCredit() external nonReentrant;

recordDeferredKeeperCredit

Records keeper credit that could not be serviced immediately because vault cash was unavailable.

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

reserveCloseOrderExecutionBounty

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

clearBadDebt

Reduces accumulated bad debt after governance-confirmed recapitalization

function clearBadDebt(
    uint256 amount
) external onlyOwner;

Parameters

sweepToken

function sweepToken(
    address token,
    address to,
    uint256 amount
) external onlyOwner;

clearDegradedMode

function clearDegradedMode() external onlyOwner;

applyRiskConfig

function applyRiskConfig(
    ICfdEngineAdminHost.EngineRiskConfig calldata config
) external onlyAdmin;

applyCalendarConfig

function applyCalendarConfig(
    ICfdEngineAdminHost.EngineCalendarConfig calldata config
) external onlyAdmin;

applyFreshnessConfig

function applyFreshnessConfig(
    ICfdEngineAdminHost.EngineFreshnessConfig calldata config
) external onlyAdmin;

checkWithdraw

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

function checkWithdraw(
    bytes32 accountId
) external override 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
) 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;

_enqueueOrAccrueDeferredKeeperCredit

function _enqueueOrAccrueDeferredKeeperCredit(
    address keeper,
    uint256 amountUsdc
) 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);

_freshVaultReservation

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

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);

positions

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

getPositionLastCarryTimestamp

function getPositionLastCarryTimestamp(
    bytes32 accountId
) external view returns (uint64);

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);

_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);

_tryGetFreshLiveMarkPrice

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

_revertIfOpenInvalidTyped

function _revertIfOpenInvalidTyped(
    CfdEnginePlanTypes.OpenRevertCode code
) internal view;

_revertIfCloseInvalidTyped

function _revertIfCloseInvalidTyped(
    CfdEnginePlanTypes.CloseRevertCode code
) internal view;

_applyFundingAndMark

function _applyFundingAndMark(
    uint256 newMarkPrice,
    uint64 newMarkTime
) internal;

settlementApplyFundingAndMark

function settlementApplyFundingAndMark(
    uint256 newMarkPrice,
    uint64 newMarkTime
) external onlySettlementModule;

settlementSyncTotalSideMargin

function settlementSyncTotalSideMargin(
    CfdTypes.Side side,
    uint256 marginBefore,
    uint256 marginAfter
) external onlySettlementModule;

settlementApplySideDelta

function settlementApplySideDelta(
    CfdTypes.Side side,
    int256 maxProfitDelta,
    int256 openInterestDelta,
    int256 entryNotionalDelta
) external onlySettlementModule;

settlementConsumeDeferredTraderPayout

function settlementConsumeDeferredTraderPayout(
    bytes32 accountId,
    uint256 amountUsdc
) external onlySettlementModule;

settlementRecordDeferredTraderPayout

function settlementRecordDeferredTraderPayout(
    bytes32 accountId,
    uint256 amountUsdc
) external onlySettlementModule;

settlementAccumulateFees

function settlementAccumulateFees(
    uint256 amountUsdc
) external onlySettlementModule;

settlementAccumulateBadDebt

function settlementAccumulateBadDebt(
    uint256 amountUsdc
) external onlySettlementModule;

settlementWritePosition

function settlementWritePosition(
    bytes32 accountId,
    CfdEngineSettlementTypes.PositionState calldata position
) external onlySettlementModule;

settlementDeletePosition

function settlementDeletePosition(
    bytes32 accountId
) external onlySettlementModule;

_applyOpen

function _applyOpen(
    CfdEnginePlanTypes.OpenDelta memory delta,
    uint64 publishTime
) internal;

_applyClose

function _applyClose(
    CfdEnginePlanTypes.CloseDelta memory delta,
    uint64 publishTime
) internal;