The previous articles traced six extensions of PayoutBase. This article covers the final two: CommodityPayout  and FixedPricePayout.

They belong together because they are the fixed and floating legs of a commodity swap — the same compositional pattern as an IRS, but for physical goods rather than interest rates. One leg pays a fixed price per unit. The other pays the observed market price. The product is the composition.

A WTI crude oil swap will serve as the running example: Party A pays Party B a fixed price of USD 80 per barrel on 50,000 barrels monthly. Party B pays Party A the monthly average of WTI spot prices on the same volume. Net, Party A locks in USD 80 and Party B takes the floating price.

FixedPricePayout — The Simplest Type

type FixedPricePayout extends PayoutBase:
    paymentDates PaymentDates (1..1)
    fixedPrice FixedPrice (1..1)
    schedule CalculationSchedule (0..1)

Three specific attributes. The smallest type surface of all eight payout types. No underlier. No rate. No strike. No observation. No contingency. Just a fixed price and a payment schedule.

fixedPrice (1..1) carries the price per unit — USD 80 per barrel. It is a FixedPrice type containing a PriceSchedule, which can be a single value or a step schedule. A swap where the fixed price steps up from USD 80 to USD 85 after six months uses the same type with a two-step schedule.

paymentDates (1..1) defines when payments occur — monthly for our crude swap. Unlike InterestRatePayout, where payment dates are optional (choice with paymentDate), FixedPricePayout makes them mandatory. Fixed-price payments always follow a schedule.

schedule (0..1) provides a non-parametric alternative for defining the payment periods when the simple frequency and roll convention are not enough.

The key design decision: no underlier. FixedPricePayout is the only payout type besides InterestRatePayout that has no underlier at all. The price is the price. There is nothing to observe, nothing to reference, nothing to deliver. This is what makes it the simplest type — the only economics are quantity × fixed price × payment frequency.

CommodityPayout — The Floating Leg

type CommodityPayout extends PayoutBase:
    averagingFeature AveragingCalculation (0..1)
    commodityPriceReturnTerms CommodityPriceReturnTerms (0..1)
    pricingDates PricingDates (1..1)
    schedule CalculationSchedule (0..1)
    calculationPeriodDates CalculationPeriodDates (0..1)
    paymentDates PaymentDates (1..1)
    underlier Underlier (1..1)
    fxFeature FxFeature (0..1)
    delivery AssetDeliveryInformation (0..1)

Nine specific attributes. The complexity is in the pricing structure — how the commodity price is observed and averaged — and the delivery logistics.

underlier is mandatory (1..1) and must be a commodity. The CDM enforces this through the CommodityUnderlier condition: the observable must resolve to a commodity asset. You cannot use CommodityPayout for equity or FX pricing — those are handled by PerformancePayout and SettlementPayout respectively.

pricingDates is mandatory (1..1). It defines when the commodity price is observed — every business day for a monthly average, or on a single fixing date for a bullet swap. It is a choice between specifiedDates (explicit list) and parametricDates (rule-based, e.g., every NYMEX business day in the period).

For our crude swap, pricingDates specifies every business day in each calendar month. The daily WTI settlement prices are averaged to produce the monthly floating price:

Floating Price = Average(Daily WTI Spot) over the month

averagingFeature specifies how the average is computed — unweighted (each day counts equally) or weighted (e.g., by volume). For our crude swap, it is unweighted.

commodityPriceReturnTerms carries commodity-specific parameters:

type CommodityPriceReturnTerms:
    rounding Rounding (0..1)
    spread SpreadSchedule (0..1)
    rollFeature RollFeature (0..1)
    conversionFactor number (0..1)

rollFeature is specific to exchange-traded contracts. When pricing references a futures contract (not spot), the contract expires monthly. The pricing must roll from the expiring contract to the next one on a defined schedule. rollFeature captures how: which calendar to use, how many days before expiry to roll.

spread allows a basis adjustment — WTI at Cushing plus USD 2 for transport to a different delivery point. conversionFactor handles unit mismatches — the contract is in barrels but the pricing source is in gallons.

delivery carries the physical delivery details — location, capacity, delivery periods. For a financially-settled swap, this is empty. For a physically-settled swap where barrels actually move, it specifies Cushing, Oklahoma as the delivery point.

calculationPeriodDates defines the accrual or pricing periods parametrically. For our crude swap, these are monthly periods. The alternative is schedule for non-parametric period definition — they are mutually exclusive, enforced by a condition.

The Two Together — Same Pattern as IRS

A commodity swap and an interest rate swap are structurally identical. Both are compositions of two payouts with opposite directions:

The difference is in the type, not the pattern. FixedPricePayout replaces the fixed InterestRatePayout. CommodityPayout replaces the floating InterestRatePayout. The composition stays the same.

Product Examples

Commodity swap (fixed-for-floating). Party A pays fixed USD 80/barrel on 50,000 barrels monthly. Party B pays the monthly average WTI spot price. One FixedPricePayout, one CommodityPayout. Same composition as IRS.

Commodity swap (float-for-float, basis swap). Party A pays WTI at Cushing. Party B pays Brent at Rotterdam. Two CommodityPayouts with different underliers and potentially different pricing dates. Same composition as a basis swap (two floating IRPs).

Commodity swap with averaging. A refiner buys WTI at the monthly average of daily prices rather than a single fixing. pricingDates = every business day. averagingFeature = unweighted. Protects against price manipulation on a single day.

Commodity forward. One SettlementPayout — no FixedPricePayout needed. Party A agrees to buy 50,000 barrels at USD 80 in six months. Settlement is a single exchange, not a recurring schedule. The forward is a single-payout product; the swap is a two-payout product.

Fixed-price supply agreement. A power plant agrees to buy natural gas at USD 3.50/MMBtu for 12 months, fixed quantity each month. One FixedPricePayout. No floating leg. The contract is a simple fixed-price schedule with no market observation.

Summary: The Complete Payout Taxonomy

Across eight articles, we have traced all eight extensions of PayoutBase. Here is the complete view.

The Eight Natures

Each payout type represents a different kind of economic obligation:

What They All Share

Every payout inherits from PayoutBase: payerReceiver (direction), priceQuantity (notional and price), settlementTerms (how settled), and principalPayment (principal exchange). This shared infrastructure is what makes composition possible — any payout can be paired with any other.

How They Compose

Products are compositions of payouts. The label is not the structure:

The Design Principles

The CDM’s payout taxonomy embodies four design principles that run through every article in this series:

Normalisation. Each economic concept lives in exactly one place. A floating rate is always modelled through FloatingRateSpecification, whether it appears in an IRS, a CDS premium leg, or an equity swap financing leg. The model does not have separate floating-rate structures for each product.

Composability. Complex products are built from simple building blocks. A CDS is not a monolithic type. It is an InterestRatePayout plus a CreditDefaultPayout. A swaption is an OptionPayout whose underlier contains a product with two InterestRatePayouts. The building blocks stay the same. The compositions vary.

The type is broad; the instance is narrow. SettlementTerms handles cash settlement for a vanilla IRS coupon, physical delivery for a CDS, and DVP for a repo. Each product populates only the attributes it needs. The type carries the union. The instance is lean.

Inheritance with purpose. The four-level floating-rate chain (FloatingRateBase → FloatingRate → FloatingRateSpecification → InflationRateSpecification) is not academic taxonomy. Each level is a contract: code written against FloatingRateBase works for every floating-rate payout in the model. Code written against FloatingRateSpecification sees trade-level detail. Code written against InflationRateSpecification adds inflation-specific attributes. Each consumer works at the level it needs.

• *AI-Native Financial Data Foundation
• Uncategorized