DiffusalSettlementReadinessCalculator

View functions for settlement readiness calculations, extracted from SettlementReadinessLiquidator

The DiffusalSettlementReadinessCalculator contract provides all read-only view functions for settlement readiness calculations. It was extracted from DiffusalSettlementReadinessLiquidator to reduce contract size while maintaining the same functionality.

Overview

The settlement readiness calculator handles:

Function	Description
Settlement Readiness Info	Returns comprehensive settlement readiness status per user
Liquidatable Status	Checks if user/portfolio can be liquidated for settlement
Penalty Rate Calculation	Computes IV-based penalty rate for liquidations
Liquidatable Portfolios	Returns array of portfolios that are settlement-liquidatable

Architecture

┌─────────────────────────────────────────────────────────────────┐
│             DiffusalSettlementReadinessCalculator                │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │       All settlement readiness view functions              │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │           Portfolio-aware calculations                     │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │            Read-only (no state changes)                    │  │
│  └───────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               │ reads from
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Dependencies                              │
│                                                                  │
│  ┌──────────────────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │SettlementReadiness       │  │ Collateral  │  │  Position   │ │
│  │Liquidator                │  │   Vault     │  │  Manager    │ │
│  │(liquidation execution)   │  │ (deposits)  │  │ (positions) │ │
│  └──────────────────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Key Concepts

Settlement Readiness

Settlement readiness liquidation triggers when a user has positions expiring soon but lacks sufficient cash to cover worst-case settlement obligations. This calculator provides the view functions to determine if this condition exists.

Contract Size Reduction

This contract was extracted from DiffusalSettlementReadinessLiquidator to reduce bytecode size. The main liquidator contract handles execution, while this calculator provides all read-only queries.

View Functions

External Reference Getters

`settlementReadinessLiquidator`

Returns the settlement readiness liquidator contract address.

function settlementReadinessLiquidator() external view returns (address)

`collateralVault`

Returns the collateral vault address.

function collateralVault() external view returns (address)

`positionManager`

Returns the position manager address.

function positionManager() external view returns (address)

`seriesRegistry`

Returns the series registry address.

function seriesRegistry() external view returns (address)

`quoter`

Returns the quoter address.

function quoter() external view returns (address)

`oracle`

Returns the oracle address.

function oracle() external view returns (address)

Settlement Readiness Info

`getSettlementReadinessInfo`

Returns settlement readiness information for a user's default portfolio (portfolio 0).

function getSettlementReadinessInfo(address user) external view returns (SettlementReadinessInfo memory info)

Returns: SettlementReadinessInfo struct from IDiffusalSettlementReadinessLiquidator.

Field	Type	Description
`isLiquidatable`	`bool`	Can be liquidated for settlement readiness
`cashRequired`	`uint256`	Total cash needed for expiring obligations (USDC)
`cashAvailable`	`uint256`	Deposited collateral (USDC)
`cashShortfall`	`uint256`	Amount obligations can't cover (USDC)
`positionValueAvailable`	`uint256`	Value of liquidatable longs (USDC)
`expiringShortsCount`	`uint256`	Number of short positions expiring within window
`expiringLongsCount`	`uint256`	Number of long positions expiring within window
`liquidatablePositionsCount`	`uint256`	Number of non-expiring long positions available
`totalPremiumReceivable`	`int256`	Total premium receivable available (WAD)
`premiumReceivableValueAfterDiscount`	`uint256`	Value after discount rate (USDC)

`getPortfolioSettlementReadinessInfo`

Returns settlement readiness information for a specific portfolio.

function getPortfolioSettlementReadinessInfo(address user, uint256 portfolioId) external view returns (SettlementReadinessInfo memory info)

Parameter	Type	Description
`user`	`address`	User address
`portfolioId`	`uint256`	Portfolio ID

Returns: Same SettlementReadinessInfo struct, scoped to the specific portfolio.

Liquidatable Status

`isSettlementReadinessLiquidatable`

Checks if user's default portfolio (portfolio 0) can be liquidated for settlement readiness.

function isSettlementReadinessLiquidatable(address user) external view returns (bool)

Returns true if:

User is not an MMM
User has positions expiring within 1 day with net obligations
User's cash shortfall > 0
User has liquidatable assets (premium receivables OR non-expiring long positions)

`isPortfolioSettlementReadinessLiquidatable`

Checks if a specific portfolio can be liquidated for settlement readiness.

function isPortfolioSettlementReadinessLiquidatable(address user, uint256 portfolioId) external view returns (bool)

Parameter	Type	Description
`user`	`address`	User address
`portfolioId`	`uint256`	Portfolio ID

Returns: Same logic as isSettlementReadinessLiquidatable, scoped to the specific portfolio.

Penalty Rate

`calculatePenaltyRate`

Calculates the penalty rate for a trading pair based on current implied volatility.

function calculatePenaltyRate(bytes32 pairId) external view returns (uint256 penaltyRate)

Formula:

\text{Penalty Rate} = \text{Base (1\%)} + \frac{\text{Current IV} - 50\%}{100}

The penalty rate is capped at MAX_LIQUIDATION_PENALTY to prevent excessive penalties.

Returns: Penalty rate in WAD (e.g., 0.01e18 = 1%).

Liquidatable Portfolios

`getSettlementReadinessLiquidatablePortfolios`

Returns an array of portfolio IDs that can be liquidated for settlement readiness.

function getSettlementReadinessLiquidatablePortfolios(address user) external view returns (uint256[] memory portfolioIds)

Returns: Array of portfolio IDs where isPortfolioSettlementReadinessLiquidatable returns true.

Integration Points

Depends On

Contract	Purpose
DiffusalSettlementReadinessLiquidator	Liquidation execution
DiffusalCollateralVault	User deposit queries
DiffusalOptionsPositionManager	Position data
DiffusalOptionsSeriesRegistry	Series parameters
DiffusalOptionsQuoter	Mark prices
DiffusalOracle	Volatility for penalty calc

Used By

Component	Purpose
Keeper bots	Monitor for settlement readiness liquidations
Frontend	Display settlement readiness status to users
Analytics	Track settlement readiness metrics

Example Usage

import {IDiffusalSettlementReadinessCalculator} from "@diffusal/interfaces/IDiffusalSettlementReadinessCalculator.sol";
import {IDiffusalSettlementReadinessLiquidator} from "@diffusal/interfaces/IDiffusalSettlementReadinessLiquidator.sol";

// Get settlement readiness info for a user
IDiffusalSettlementReadinessLiquidator.SettlementReadinessInfo memory info =
    settlementReadinessCalculator.getSettlementReadinessInfo(user);

// Check if user can be liquidated
if (info.isLiquidatable) {
    // User has expiring obligations with insufficient cash
    uint256 shortfall = info.cashShortfall;
    uint256 availableAssets = info.positionValueAvailable;
}

// Get all liquidatable portfolios
uint256[] memory portfolios = settlementReadinessCalculator.getSettlementReadinessLiquidatablePortfolios(user);
for (uint256 i = 0; i < portfolios.length; i++) {
    // Each portfolio can be liquidated separately
}

Code Reference

Interface: packages/contracts/src/interfaces/IDiffusalSettlementReadinessCalculator.sol

Contract Documentation

DiffusalSettlementReadinessLiquidator — Liquidation execution
DiffusalMarginCalculator — Similar pattern for margin calculations
DiffusalLiquidationCalculator — Similar pattern for regular liquidation

Protocol Documentation

Liquidation (Protocol) — High-level liquidation mechanics
Options Settlement (Protocol) — Why cash is needed at expiry

DiffusalSettlementReadinessCalculator

On this page