DiffusalLiquidationSettlement

The DiffusalLiquidationSettlement contract handles all collateral flows during liquidation, including bounty payments and insurance coverage. It was extracted from DiffusalLiquidationEngine to reduce contract size.

Overview

The settlement contract handles:

Function	Description
Collateral Settlement	Bidirectional flows between liquidator and user
Bounty Payments	Ensures liquidators always receive their bounty
Insurance Coverage	Draws from insurance fund for shortfalls
Portfolio Cleanup	Deletes empty portfolios after full liquidation

Settlement Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                       settlePortfolioCollateral()                            │
│                                                                              │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │           1. Transfer longs cost (liquidator -> user)                  │  │
│  └─────────────────────────────────┬─────────────────────────────────────┘  │
│                                    ▼                                         │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │           2. Transfer shorts cost (user -> liquidator)                 │  │
│  └─────────────────────────────────┬─────────────────────────────────────┘  │
│                                    ▼                                         │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │      3. Pay bounty (user first, then insurance if needed)              │  │
│  └─────────────────────────────────┬─────────────────────────────────────┘  │
│                                    ▼                                         │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │        4. Cover negative equity shortfall from insurance               │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Key Concepts

Bidirectional Flows

During liquidation, collateral flows in both directions:

Flow	Direction	Description
Longs Cost	Liquidator → User	Liquidator pays for long positions at penalized price
Shorts Cost	User → Liquidator	User pays liquidator to take short obligations
Bounty	User → Liquidator	Reward for executing liquidation

Guaranteed Bounty

Liquidator bounty is ALWAYS paid to incentivize liquidations:

First, attempt to pay from user's remaining collateral
If insufficient, draw from insurance fund

This ensures liquidators remain incentivized even for underwater users.

Settlement Order

The settlement follows a strict order to maximize collateral recovery:

Longs Cost — Liquidator pays user for long positions
Shorts Cost — User pays liquidator for short positions
Bounty — Pay liquidator reward (insurance backup)
Shortfall — Cover remaining negative equity from insurance

Functions

Settlement

`settlePortfolioCollateral`

Main settlement function called by LiquidationEngine after closing positions.

function settlePortfolioCollateral(
    IDiffusalCollateralVault vault,
    SettlementParams calldata params
) external returns (uint256 insuranceUsed, uint256 actualBountyPaid)

Parameter	Type	Description
`vault`	`IDiffusalCollateralVault`	Collateral vault contract
`params`	`SettlementParams`	Settlement parameters

SettlementParams:

struct SettlementParams {
    address user;           // User being liquidated
    uint256 portfolioId;    // Portfolio being liquidated
    address liquidator;     // Liquidator executing
    uint256 longsCost;      // Amount liquidator pays for longs (USDC)
    uint256 shortsCost;     // Amount user pays for shorts (USDC)
    uint256 bounty;         // Bounty to pay liquidator (USDC)
}

Returns:

insuranceUsed — Amount drawn from insurance fund (USDC)
actualBountyPaid — Actual bounty paid to liquidator (USDC)

Requirements: Only authorized callers (LiquidationEngine).

`coverBountyFromInsurance`

Cover bounty shortfall when user cannot pay full bounty.

function coverBountyFromInsurance(
    IDiffusalCollateralVault vault,
    address liquidator,
    uint256 amount,
    address user
) external returns (uint256 covered)

Parameter	Type	Description
`vault`	`IDiffusalCollateralVault`	Collateral vault
`liquidator`	`address`	Liquidator to credit
`amount`	`uint256`	Amount to cover (USDC)
`user`	`address`	User for event indexing

Returns: Amount actually covered from insurance (may be less if fund depleted).

Emits: BountyCoveredFromInsurance

`coverShortfall`

Cover negative equity shortfall from insurance fund.

function coverShortfall(uint256 shortfall, address user) external returns (uint256 insuranceUsed)

Parameter	Type	Description
`shortfall`	`uint256`	Shortfall amount (USDC)
`user`	`address`	User for event indexing

Returns: Amount actually used from insurance.

Emits: ShortfallCovered

`cleanupEmptyPortfolio`

Delete empty portfolio after full liquidation.

function cleanupEmptyPortfolio(
    address user,
    uint256 portfolioId,
    IDiffusalOptionsPositionManager pm,
    IDiffusalCollateralVault vault
) external

Parameter	Type	Description
`user`	`address`	Portfolio owner
`portfolioId`	`uint256`	Portfolio to delete
`pm`	`IDiffusalOptionsPositionManager`	Position manager
`vault`	`IDiffusalCollateralVault`	Collateral vault

Requirements:

Portfolio has no positions
Portfolio has no collateral

Note: Any empty portfolio can be deleted, including portfolio 0.

Emits: EmptyPortfolioCleaned

View Functions

`insuranceFund`

Returns the insurance fund address.

function insuranceFund() external view returns (address)

`portfolioManager`

Returns the portfolio manager address.

function portfolioManager() external view returns (address)

`marginCalculator`

Returns the margin calculator address.

function marginCalculator() external view returns (address)

`isAuthorizedCaller`

Check if an address is authorized to call settlement functions.

function isAuthorizedCaller(address caller) external view returns (bool)

`marginCalculator`

Returns the margin calculator address.

function marginCalculator() external view returns (address)

Owner Functions

`setInsuranceFund`

Set the insurance fund address.

function setInsuranceFund(address insuranceFund_) external

Requirements: Owner only.

`setPortfolioManager`

Set the portfolio manager address.

function setPortfolioManager(address portfolioManager_) external

Requirements: Owner only.

`setAuthorizedCaller`

Authorize or revoke a caller (LiquidationEngine).

function setAuthorizedCaller(address caller, bool authorized) external

Requirements: Owner only.

Events

Event	Parameters	Description
`BountyCoveredFromInsurance`	`liquidator`, `amount`, `user`	Bounty shortfall covered by insurance
`ShortfallCovered`	`user`, `amount`	Negative equity covered by insurance
`EmptyPortfolioCleaned`	`user`, `portfolioId`	Empty portfolio deleted after liquidation

Integration Points

Depends On

Contract	Purpose
DiffusalCollateralVault	Collateral transfers
DiffusalInsuranceFund	Shortfall coverage
DiffusalPortfolioManager	Portfolio deletion
DiffusalMarginCalculator	Margin calculations

Used By

Contract	Purpose
DiffusalLiquidationEngine	Calls after position closure

Example Flow

Scenario

User with portfolio 1 is liquidated:

Longs value: $5,000 (liquidator pays)
Shorts obligation: $3,000 (user pays liquidator)
Debt: $2,500
Bounty: $125 (5% of debt)
User's remaining deposit: $50

Settlement Process

// 1. Liquidator pays for longs
vault.transferCollateral(liquidator, user, 5000e6);  // +$5,000 to user

// 2. User pays for shorts
vault.transferCollateral(user, liquidator, 3000e6);  // -$3,000 from user

// 3. Pay bounty
// User has: original_deposit + 5000 - 3000 = $2,050
// Bounty: $125, paid from user
vault.transferCollateral(user, liquidator, 125e6);

// 4. No shortfall (user has positive equity)
// If user had negative equity, insurance would cover

Result

Liquidator receives: positions worth $5,000 + $3,000 obligation taken + $125 bounty
User has: remaining collateral after all flows
Insurance used: $0 (in this case)

Code Reference

Source: packages/contracts/src/DiffusalLiquidationSettlement.sol

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

Liquidation — High-level liquidation mechanics
DiffusalLiquidationEngine — Main liquidation contract
DiffusalInsuranceFund — Shortfall coverage

DiffusalLiquidationSettlement

On this page