Liquidation Waterfall

Install and import

bash

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

Name	Type	Notes
`data`	`PositionInput`	Position state — balances, prices, and the protocol parameters the calculation depends on.
`config`	`ProtocolConfig`	Protocol-specific thresholds and factors. These differ per protocol and per asset, so a figure computed under the wrong config is confidently wrong.

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

data

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

config

{
  "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

Liquidation Waterfall — diagnostic deep dive

Liquidation Waterfall — parameter sensitivity

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