Liquidation Waterfall

Install and import#

npm install fintech-algorithms

import { liquidationWaterfall } from "fintech-algorithms/digital-assets-and-on-chain-finance/liquidity-and-liquidation/liquidation-waterfall";

Signature#

liquidationWaterfall(data, config)

The order in which collateral is seized and debt repaid, including liquidation bonus and any protocol fee. Determines what a borrower recovers, and it is rarely proportional.

Parameters#

Returns#

{ status, value, components, diagnostics }

The result with every component, so a position's state can be reconciled against the protocol's own interface.

Errors#

• When a required protocol parameter is missing — reported as a status rather than thrown

Complexity: time O(assets), space O(assets).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

{
  "debt_value": 10000,
  "collateral_sale_proceeds": 7000,
  "protocol_reserve": 1000,
  "insurance_fund": 2500,
  "backstop_capacity": 1000
}

{
  "collateral_recovery_rate": 1,
  "backstop_enabled": true
}

Call#

liquidationWaterfall(data, config)

Returns#

object with 9 fields: debt_value, effective_collateral_proceeds, total_buffer_capacity, covered_debt, uncovered_bad_debt, coverage_fraction, backstop_enabled, ledger, …

{
  "debt_value": 10000,
  "effective_collateral_proceeds": 7000,
  "total_buffer_capacity": 4500,
  "covered_debt": 10000,
  "uncovered_bad_debt": 0,
  "coverage_fraction": 1,
  "backstop_enabled": true,
  "ledger": [
    {
      "layer": "collateral-recovery",
      "available_capacity": 7000,
      "absorbed": 7000,
      "remaining_debt": 3000,
      "cumulative_absorbed": 7000
    },
    {
      "layer": "protocol-reserve",
      "available_capacity": 1000,
      "absorbed": 1000,
      "remaining_debt": 2000,
      "cumulative_absorbed": 8000
    },
    {
      "layer": "insurance-fund",
      "available_capacity": 2500,
      "absorbed": 2000,
      "remaining_debt": 0,
      "cumulative_absorbed": 10000
    }
  ],
  "trace": [
    {
      "collateral_proceeds_multiplier": 0,
      "covered_debt": 4500,
      "uncovered_bad_debt": 5500
    },
    {
      "collateral_proceeds_multiplier": 0.005,
      "covered_debt": 4535,
      "uncovered_bad_debt": 5465
    },
    {
      "collateral_proceeds_multiplier": 0.01,
      "covered_debt": 4570,
      "uncovered_bad_debt": 5430
    }
  ]
}

Other exports#

This module also exports impermanentLoss, feeApr, healthFactor, liquidationPrice, runTopic. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Calculation flow#

flowchart LR
    A["Identify protocol, version, chain, and valuation time"] --> B["Validate finite inputs and common units"]
    B --> C["Pass remaining debt through ordered capacities"]
    C --> D["Return value plus state/reason"]
    D --> E["Check equality, zero, and unsupported states"]
    E --> F["Compare sensitivity profiles"]
    F --> G{"Operational evidence complete?"}
    G -->|No| H["Keep as synthetic or descriptive calculation"]
    G -->|Yes| I["Add live source, oracle, execution, and finality controls"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Compound III Liquidation — Compound; Compound documentation team
• Liquidation 2.0 Module — MakerDAO; Maker Protocol documentation contributors
• Health Factor & Liquidations — Aave; Aave Labs documentation team
• Aave V3 LiquidationLogic.sol — Aave; Aave protocol contributors
• Evidence boundary

The rest of the Liquidity and Liquidation family#

• Impermanent-Loss CalculationValue lost by providing liquidity rather than simply holding the two assets.
• Liquidity-Provider Fee APRAnnualised fee return for a liquidity position.
• Collateral-Health FactorThe ratio of weighted collateral to debt in a lending position.
• Liquidation-Price CalculationThe collateral price at which a position becomes liquidatable.