Skip to content
TotalFinance

Fixed income · @insiderfinance/totalfinance

@insiderfinance/totalfinance/fixed-income/lattice

import { … } from '@insiderfinance/totalfinance/fixed-income/lattice'
stable-by-law (pre-1.0; not a 1.0 stability guarantee)iface 7fn 3JSON ↗
iface

BermudanSwaptionResult

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { BermudanSwaptionResult } from '@insiderfinance/totalfinance/fixed-income/lattice';

export interface BermudanSwaptionResult {
    /** Option value, scaled by `notional`. */
    price: number;
    /** The exercise schedule actually used, sorted ascending from the valuation date. */
    exerciseDates: string[];
    /** Applied conventions and model knobs, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        model: 'hull-white';
        dayCount: 'ACT/365F';
        settlementDate: string;
        stepsPerYear: number;
        meanReversion: number;
        sigma: number;
        fixedFrequency: Frequency;
        fixedDayCount: FixedIncomeDayCount;
        notional: number;
    };
    /** Honest computation report: the lattice method behind the price (Law 2 report grammar). */
    diagnostics: Diagnostics;
}
Fields, parameters and returned members (31)

Loading 31 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

BermudanSwaptionSpecification

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { BermudanSwaptionSpecification } from '@insiderfinance/totalfinance/fixed-income/lattice';

// ───────────────────────── Bermudan swaptions ─────────────────────────
export interface BermudanSwaptionSpecification {
    /** Discount/forecast curve (single-curve); its reference date is the valuation date. */
    curve: YieldCurve;
    /** Underlying swap maturity. */
    maturityDate: string;
    /** Fixed rate of the underlying swap. */
    fixedRate: number;
    /** `payer` = option to pay fixed; `receiver` = option to receive fixed. */
    optionType: 'payer' | 'receiver';
    /** Dates on which the holder may exercise into the swap (each is a swap start). */
    exerciseDates: string[];
    /** Fixed-leg frequency (default semiannual). */
    fixedFrequency?: Frequency;
    /** Fixed-leg day count (default `30/360`). */
    fixedDayCount?: FixedIncomeDayCount;
    /** Mean reversion and short-rate vol. */
    meanReversion: number;
    sigma: number;
    notional?: number;
    /** Tree steps per year (default 24, hard outer maximum 1,000,000; total-tree cap may be lower). */
    stepsPerYear?: number;
}
Fields, parameters and returned members (38)

Loading 38 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

BondOption

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { BondOption } from '@insiderfinance/totalfinance/fixed-income/lattice';

// ───────────────────────── callable / putable bonds ─────────────────────────
export interface BondOption {
    /** Option date (issuer call / holder put opportunity). */
    date: string;
    /** Strike (clean redemption price per the bond's face value, e.g. 102). */
    price: number;
}
Fields, parameters and returned members (2)
Name · typeMeaning · unitRequired · default
datestring

Option date (issuer call / holder put opportunity).

unitless by name
RequiredNo @default declared
pricenumber

Strike (clean redemption price per the bond's face value, e.g. 102).

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

CallableBondResult

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { CallableBondResult } from '@insiderfinance/totalfinance/fixed-income/lattice';

export interface CallableBondResult {
    /** Model dirty price including the embedded option(s). */
    price: number;
    /** Model dirty price of the otherwise-identical straight bond (no embedded options). */
    straightPrice: number;
    /** Value of the embedded option(s): `straightPrice − price` (positive for a callable). */
    optionValue: number;
    /** Effective duration from a ±1bp parallel curve shock (re-trees each side). */
    effectiveDuration: number;
    /** Option-adjusted spread (parallel curve shift repricing the model to `marketPrice`); present only when `marketPrice` is supplied. */
    oas?: number;
    /** Applied conventions and model knobs, echoed (R2). */
    assumptions: {
        conventionsVersion: string;
        dayCount: 'ACT/365F';
        settlementDate: string;
        model: TreeModel;
        stepsPerYear: number;
        meanReversion: number;
        sigma: number;
    };
    /** Honest computation report: the lattice method, and the OAS root-find when one ran (R2). */
    diagnostics: Diagnostics;
}
Fields, parameters and returned members (31)

Loading 31 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

CallableBondSpecification

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { CallableBondSpecification } from '@insiderfinance/totalfinance/fixed-income/lattice';

export interface CallableBondSpecification {
    bond: Bond;
    /** Calibration/discount curve (its reference date is the valuation date). */
    curve: YieldCurve;
    /** Mean reversion and short-rate volatility for the tree model. */
    meanReversion: number;
    sigma: number;
    /** Tree model (default `hull-white`). */
    model?: TreeModel;
    /** Issuer call schedule (caps the bond's value at each strike). */
    calls?: BondOption[];
    /** Holder put schedule (floors the bond's value at each strike). */
    puts?: BondOption[];
    /** Tree steps per year (default 24, hard outer maximum 1,000,000; total-tree cap may be lower). */
    stepsPerYear?: number;
    /** Market dirty price; when given, the result includes the option-adjusted spread. */
    marketPrice?: number;
}
Fields, parameters and returned members (62)

Loading 62 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

OasAnalyticsResult

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { OasAnalyticsResult } from '@insiderfinance/totalfinance/fixed-income/lattice';

export interface OasAnalyticsResult {
    /** Parallel curve shift repricing the callable model to `marketPrice` (decimal; ×1e4 = bps). */
    oas: number;
    /** Zero-volatility spread on the same lattice's straight leg (decimal). */
    zSpread: number;
    /** `zSpread − oas` (decimal) — the embedded-option cost. Positive callable / negative putable. */
    optionCost: number;
    /** OAS-consistent effective duration (curve shocked ±`durationShock` at constant OAS). */
    effectiveDuration: number;
    /** OAS-consistent effective convexity. */
    effectiveConvexity: number;
    /** The no-spread lattice model price (the gap `marketPrice − modelPrice` is what the OAS explains). */
    modelPrice: number;
    marketPrice: number;
    assumptions: CallableBondResult['assumptions'];
    diagnostics: Diagnostics;
}
Fields, parameters and returned members (33)

Loading 33 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

OasAnalyticsSpecification

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { OasAnalyticsSpecification } from '@insiderfinance/totalfinance/fixed-income/lattice';

// ───────────────────────── OAS analytics ─────────────────────────
export interface OasAnalyticsSpecification extends Omit<CallableBondSpecification, 'marketPrice'> {
    /** Market dirty price the OAS and Z-spread are solved to. */
    marketPrice: number;
    /** Curve shock for the effective duration/convexity, in decimal. Default 1e-4 (1 bp). */
    durationShock?: number;
    /**
     * Optional term-structure spread curve added to `curve` before the spreads are solved. The effective
     * benchmark becomes `curve` + `spreadCurve` (continuous zeros add ⇔ discount factors multiply), so the
     * reported OAS and Z-spread are measured OVER a NON-FLAT benchmark — e.g. an OIS discount curve plus a
     * sector/rating spread curve — rather than the plain `curve`. Its zero rates ARE the spreads (build one
     * with `curves.fromZeroRates(spreadPillars)`); it must share `curve`'s reference date.
     */
    spreadCurve?: YieldCurve;
}
Fields, parameters and returned members (91)

Loading 91 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

bermudanSwaption

#

Price a Bermudan swaption on the Hull-White tree. At each exercise date the holder takes max(continuation, swapValue), where the node-level forward swap value uses the Hull-White analytic bond reconstruction P(tᵢ, T; r_node). (Hull-White only — the lognormal Black-Karasinski tree has no analytic node bond.)

Signature
import { bermudanSwaption } from '@insiderfinance/totalfinance/fixed-income/lattice';

export declare function bermudanSwaption(specification: BermudanSwaptionSpecification): BermudanSwaptionResult;
Fields, parameters and returned members (26)

Loading 26 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

callableBond

#

Price a callable and/or putable bond on a short-rate tree, with option value, effective duration, and OAS.

Signature
import { callableBond } from '@insiderfinance/totalfinance/fixed-income/lattice';

export declare function callableBond(specification: CallableBondSpecification): CallableBondResult;
Fields, parameters and returned members (24)

Loading 24 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

oasAnalytics

#

Market-calibrated option-adjusted-spread analytics for a callable/putable bond: the OAS, the Z-spread, their difference (the embedded-**option cost**), and the **OAS-consistent** effective duration and convexity (the curve shocked with the spread held fixed). Composes the same short-rate lattice as callableBond. See docs/specs/oas-analytics.md.

Signature
import { oasAnalytics } from '@insiderfinance/totalfinance/fixed-income/lattice';

export declare function oasAnalytics(specification: OasAnalyticsSpecification): OasAnalyticsResult;
Fields, parameters and returned members (28)

Loading 28 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.