CLO Waterfall Model
Implementation Plan

Overview

We are building a Quarto document that models the full lifecycle cashflow waterfall of a realistic US broadly syndicated CLO — from loan pool collections through to tranche-by-tranche distributions and equity residual. The model runs a single base case scenario and produces Polars DataFrames for each tranche's cashflows, the OC/IC test timeline, and standard analytics (WAL, IRR, discount margin). All assumptions are cleanly separated so that stress scenarios can be added later by simply providing a second assumption dict to api.runDeal().

The computation engine is Hastructure, a high-performance structured finance cashflow engine written in Haskell. It runs as a local Docker container and exposes a REST API. The absbox Python library is the thin client that serialises deal definitions to JSON, POSTs them to Hastructure, and deserialises the cashflow results back into Python. All result DataFrames are converted from pandas to Polars immediately for downstream processing.

abbr[title] {
  text-decoration: underline dotted;
  text-underline-offset: 3px;
  cursor: help;
}

The pool's <abbr title="Weighted Average Spread">WAS</abbr> is 411bps over
<abbr title="Secured Overnight Financing Rate, 3-month term">SOFR3M</abbr>.
The annual <abbr title="Constant Default Rate">CDR</abbr> assumption is 2%.

Deal Architecture — Blackstone BSL CLO 2024-1

We model a representative US broadly syndicated CLO based on standard 2024 market conventions. The fictional deal — "Blackstone BSL CLO 2024-1" — is sized at $600m with seven tranches: six rated debt classes (A through F) and an unrated equity tranche. All rated tranches are SOFR3M-based floaters resetting quarterly.

The capital structure is calibrated to typical 2024 US CLO arbitrage parameters: Class A at 62% of the stack (consistent with Moody's AAA sizing methodology), a debt-to-equity ratio of 19:1, and an equity tranche sized at 5% — the minimum risk retention required under US CLO 2.0 / Dodd-Frank Credit Risk Retention rules (79 FR 77601, December 2014).

Loan Pool Construction

The loan pool is the engine of the CLO — all cash flowing through the waterfall originates here. We will construct a statistically representative synthetic tape of ~250 US broadly syndicated leveraged loans, calibrated to publicly available 2024 Leveraged Commentary & Data (LCD) market statistics. No Bloomberg or CUSIP licence is required.

Loans are diversified across 12 GICS industries, with technology, healthcare, and industrials making up the largest concentrations — consistent with the current US leveraged loan index composition. Each loan is represented by 7 fields that absbox needs to project its cashflows.

absbox API Primer

absbox has three main building blocks: the Pool (the loan assets), the Bond (an individual CLO tranche), and the Deal (the full CLO structure combining pool, bonds, accounts, fees, and waterfall). The API object connects to the Docker engine and exposes runPool() and runDeal().

from absbox import API, EnginePath
import polars as pl

# EnginePath.LOCAL resolves to "http://localhost:8081"
# Hastructure must be running: docker run -p 8081:8081 yellowbean/hastructure
api = API(EnginePath.LOCAL)

# Sanity-check — prints the engine version
print(api.version())

from absbox.local.component import Bond, Floater

# Class A: $372m, SOFR3M + 150bps, quarterly payments
class_a = Bond(
    balance       = 372_000_000,
    rate          = Floater("SOFR3M", 0.0150),
    originDate    = "2024-03-31",
    startDate     = "2024-03-31",
    rateResetDates = ["2024-06-30", "2024-09-30", "..."],
    paymentDates   = ["2024-06-30", "2024-09-30", "..."]
)

result = api.runDeal(deal, base_assumptions)

# result is a dict keyed by bond/account name → pandas DataFrames
# Convert everything to Polars in one pass
pool_cf = pl.from_pandas(result["pool"])

bonds = {
    k: pl.from_pandas(v)
    for k, v in result.items()
    if k.startswith("Class") or k == "Equity"
}

# bonds["ClassA"], bonds["ClassB"], ..., bonds["Equity"]

Waterfall Logic — Priority of Payments

The CLO waterfall defines the strict order in which quarterly cash collected from the loan pool is distributed. Cash flows top-down — senior creditors are paid first. OC and IC tests are evaluated at designated steps; a failure diverts remaining cash upward to sequentially pay down senior principal until the ratio recovers.

In absbox, the waterfall is encoded as a Python list of action tuples. Each action is a two-element list: an action type string (e.g. "payFee", "payInt", "runOCTest") and the name of the target account or bond. absbox handles the conditional OC/IC diversion logic automatically.

Interest Deferral — PIK vs Non-PIK by Tranche

When OC tests fail and the waterfall diverts cash upward, not every tranche is affected in the same way. The critical distinction is whether unpaid interest is non-deferrable — meaning it must be paid in full in cash every quarter — or PIK-eligible (PIK = Payment In Kind) — meaning unpaid interest capitalises onto the outstanding note balance and accrues at the stated coupon until the waterfall recovers.

Base Case Assumptions

All modelling assumptions are defined in a single dictionary before being passed to api.runDeal(). Keeping them in one place makes the model easy to audit and extend — adding a stress scenario later is as simple as creating a second dict that overrides the specific values you want to change.

The base case reflects typical 2024 US leveraged loan market conditions: a 2% annual CDR (broadly in line with the trailing 12-month US leveraged loan default rate), 15% CPR (driven by refinancing and repricing activity), 65% recovery rate (consistent with Moody's LGD database for US senior secured loans), and SOFR3M held flat at 5.25%.

# ── Pool cashflow assumptions ─────────────────────────────────────────────
# All scenario inputs live here. To add a stress case, create a new dict
# overriding only the keys that differ:
#   mild_assump = {**BASE_ASSUMPTIONS, "default": ("CDR", 0.05), ...}
# ─────────────────────────────────────────────────────────────────────────

BASE_ASSUMPTIONS = {
    # Annual Constant Default Rate — 2% reflects 2024 US BSL market conditions
    "default"     : ("CDR", 0.02),

    # Annual Constant Prepayment Rate — 15% reflects active refi/reprice market
    "prepay"      : ("CPR", 0.15),

    # Recovery rate on defaulted par — 65% is the Moody's US senior secured avg
    "recovery"    : 0.65,

    # Months from default event to cash recovery (typical US workout timeline)
    "recoveryLag" : 12,

    # Forward curve: hold SOFR3M flat at 5.25% for the full projection horizon
    "rates"       : {"SOFR3M": 0.0525},
}

Outputs & Analytics

api.runDeal() returns a dict of pandas DataFrames keyed by the names given to bonds and accounts in the Deal definition. We convert all of them to Polars immediately. The key tables are described below — these are the DataFrames we will work with throughout Steps 6–8.

Pool Cashflow Table — pool_cf

Bond Cashflow Table — bonds["ClassA"] etc.

date         interest   principal   equity_dist
2024-06-30   0.0        0.0         2_258_000
2024-09-30   0.0        0.0         2_258_000
2024-12-31   0.0        0.0         2_258_000
2025-03-31   0.0        0.0         2_258_000
2025-06-30   0.0        0.0         2_190_000   ← minor CDR erosion begins
2025-09-30   0.0        0.0         2_127_000
2026-03-31   0.0        0.0         1_940_000
2026-06-30   0.0        0.0         1_880_000   ← recoveries arriving, par stabilising

Analytics We Compute in Step 7

Implementation Roadmap — 8 Coding Steps

The document is organised into 8 Quarto code sections, each building on the previous one. Every section is self-contained: a short prose block explains the absbox concept being introduced, followed by a code cell that implements it and a great_tables display of the key outputs. You can inspect what absbox is consuming and producing at each stage before moving on.