Understand the model. Know what moves it.

What ForwardFlow models

A Buyer pays for one Bitcoin under an Agreement. BTC Now is Holder 0 and sells the receiving side to a Holder. ForwardFlow models the Holder’s purchases, collections, fees and stop-sale proceeds month by month under a chosen price path and Buyer behavior.

The workspace supports scenario research, risk analysis, historical replay, hedge comparison and monthly cash and P&L analysis. The REST API and MCP interface use the same server-side engine. A result answers a question about the assumptions submitted with that run.

Choose how you measure success

Choose Dollar workspace to grow USD capital, or Coin workspace to grow BTC holdings compared with holding Bitcoin. Each keeps its own draft, strategy choices and completed research. Open the workspace chooser or read the workspace guide.

Both Research homes keep the price-path view, Agreement cash and exits, scenario questions and Monte Carlo close to your assumptions. Dollar simulations measure USD outcomes; Coin simulations measure BTC outcomes against holding matching contributions. Research links directly to stress maps, the purchase-price solver and Agreement detail, whose supporting measures remain labelled USD.

Advanced analysis provides the full assumptions editor, custom strategy builder, monthly exhibits and historical vintages. The original research desk and its existing shared links remain available. Specialist results stay attached to their completed run. If you change assumptions, run again before interpreting them as results for the new scenario. Dollar and Coin drafts are separate; copying a scenario between them is explicit.

Read a result in four steps

1. Identify the construction. One scenario is one path. Monte Carlo summarizes many seeds. Historical vintages summarize different historical start months. A bridge fixes the terminal price; its spread measures uncertainty along the way.
2. Inspect the assumptions. Check the price model, purchase price, Buyer behavior, pacing and stop-sale terms. For a hedge, also check its surface, coverage, tenor, trading costs and lifecycle.
3. Read loss measures beside IRR. Cash-loss frequency, cash multiple and shortfall answer different questions. An unavailable IRR is not zero. An ambiguous IRR needs its flag, and IRR percentiles may exclude seeds without a defined rate.
4. Keep the evidence. Save the completed run package or MCP replay together with the engine build and historical-data identity. Reproduce against that same build and data. A chart image alone does not contain the full run.

Results and return measures defines the metrics. Verification and reproduction explains the evidence to retain.

The vocabulary

Buyer is the paying side. Holder is the receiving side. Completion delivers the coin after the schedule is paid. Early completion pays the remaining schedule in cash and delivers the coin. A stop sells the coin for dollars and distributes the proceeds through the stop waterfall. A stopped Buyer receives dollars, never coin.

The glossary gives definitions and formula references. Technical identifiers can retain historical names—for example, Owner means Holder and Obligor means Buyer.

Get access

Use the workspace in your browser, or connect your AI assistant to ask questions in your own words. For AI access, email info@btcnow.com. BTC Now provides an access token privately; no ForwardFlow account is needed.

# Engine, from backend/
cargo run --release

# Web app, from web/
npm ci
npm run dev

The Agreement, explained

This chapter describes the Bitcoin Purchase Agreement the way the engine models it. It is not the Agreement itself and it is not a summary of the legal text. Where the code and the program differ, the difference is stated here and the code is what the numbers come from. Every rule carries the date of the ruling that made it, so a reader can trace a number in a Model Card back to a decision.

The vocabulary is the locked one (Marc, 2026-09-02). The paying side of an Agreement is the Buyer; Buyer 0 opened it. The receiving side is the Holder; Holder 0 is always BTC Now. The paying side changes hands by Transfer, the receiving side by Sale. A Partner is anyone paid a cut of BTC Now’s fees. Engine identifiers keep older names (Owner for the Holder, Obligor for the Buyer, non_performance for a stop); they are quoted in code font when the code is being explained and nowhere else.

The parties

Three entities move money in the engine, and every cent between them goes through the ledger (ledger.rs).

A fourth entity, EntityId::Market, is the counterparty to the stop sale. It buys the coin for dollars and the dollars flow out from it. It has no economics of its own.

What the Buyer buys and pays

The Buyer buys one coin at a price fixed on the day the Agreement opens. That price is the strike \(K\), the coin’s dollar cost at origination. The Buyer agrees to pay a Purchase Price equal to the strike times the program multiple, \(m = 1.475\):

\[ P = K \cdot m \]

contract.rs::ContractTerms::terminal computes \(P\) and quantizes it to cents. At the base terms, a $60,000 coin carries a Purchase Price of $88,500.

The Purchase Price is paid in equal monthly payments over the term \(n\), 60 months in the current program. The payment is straight division, not an annuity:

\[ \text{PMT} = \frac{P}{n} = \frac{88{,}500}{60} = 1{,}475 \]

contract.rs::ContractTerms::schedule builds the schedule. Each payment is rounded down to the cent and the final payment absorbs the residual, so the sixty payments sum to the Purchase Price exactly. The remaining schedule after \(t\) payments is what the Buyer still owes in nominal dollars:

\[ R_t = P - \text{PMT} \cdot t \]

The term is a property of today’s offer, not of the Agreement (Marc, 2026-07-29). Nothing in the engine hard-codes 60 months (spec v1.1). The multiple implies a financing rate, the rate at which an ordinary amortizing schedule of $1,475 would repay $60,000: 16.50% nominal per year at the base terms, solved by bisection in contract.rs::ContractTerms::implied_monthly_rate. The engine calls this the implied financing rate and uses it only for display and for the moneyness boundary; no ledger amount depends on it.

The Buyer may pay early or pay extra at any time without a fee. The Buyer never owes anything after a stop. There are no late fees, no returned-payment fees, no termination fees on the Buyer’s side.

The first payment goes to BTC Now

Every Agreement opens with BTC Now as Holder 0, and the first payment flows to BTC Now whole (Marc, 2026-08-31: “BTC Now always first owner”). In the engine this is input #3, origination_payments, default 1: the first \(N\) payments post from the Buyer to BTC Now as TxKind::OriginationFee and never enter the Holder’s stream (engine.rs::run, step 1). They carry no servicing fee because nothing was delivered to a Holder.

At the base terms the first payment is $1,475, which is 1.67% of the Purchase Price (one sixtieth) and 2.46% of the Holder’s capital. The Holder should read it as a day-one cost of the paper.

The Sale of the paper to a Holder

The Holder buys the paper from BTC Now at a purchase price. The default is par: 1.00 times the strike, $60,000 on the base coin (Marc, 2026-07-12; spec v1.4). Input #6b, purchase_pct_of_strike, expresses it as a fraction of the strike so that a paced book of many cohorts scales correctly. The engine posts the purchase from the Holder to BTC Now at the origination month as TxKind::PurchasePrice.

In the engine the Holder pays at origination and payment 1 arrives a month later. In the program BTC Now is Holder 0 first and a Primary Sale follows; the Holder’s economics start at its purchase date. The engine collapses this to one date, which is the conservative reading for the Holder: it pays before the first payment that it does not receive.

After the Sale, payments 2 to 60 are delivered to the Holder. The Holder never receives the coin.

The servicing fee

BTC Now keeps 5% of every dollar delivered to the Holder, deducted at each send (Marc, 2026-08-31: “we retain 5% of each send”). It is uniform and has no exemptions: scheduled payments, early-completion payoffs and stop-sale deliveries all carry it, and the termination send does too (“we get our 5% of that as well”). The Holder receives 95% of each send.

Input #4, servicing_fee_rate, is the flat rate (spec v1.5). It is not derived from the term; the earlier form, a rate per year times the term in years, died with the September program. A 60-month term at the old 1% per year happened to give the same 5%, so the base case did not move; every other term now pays the same flat rate.

fees.rs::FeeState::split takes a delivery and returns the Holder’s net and the fee, summing exactly to the delivery. The fee posting on each delivery is the difference between the rounded cumulative fee before and after (convention C2), so any single posting may differ from 5% of that delivery by a cent, but the lifetime fee on an Agreement is exact to the cent. At the base terms nothing rounds: 5% of $1,475 is $73.75 and the Holder’s net payment is $1,401.25.

On a completed Agreement the lifetime fee is \(0.05 \cdot (P - N \cdot \text{PMT})\), which is $4,351.25 at the base terms, because the first payment is never delivered and carries no fee. The invariant suite tests this identity at terms of 36, 48, 60, 84 and 120 months (invariants.rs::fee_identity_exact_to_the_cent).

The fee is the only thing BTC Now takes from the paper after the first payment. There is no dial that gives BTC Now a share of a stop sale, and the invariant suite asserts that BTC Now’s total take equals its origination fees plus its flow fees.

The stop

A stop is the Buyer ceasing to pay. It is the Buyer’s only exit other than completing, and it is the exit a Holder prices.

The Stop Date

A payment up to 15 days late carries nothing: no fee, no penalty, no consequence. Day 16 after the missed due date is the Stop Date (Marc, 2026-08-22: “stop is 15 days later and we stop on day 16 as always”; atom R-1035). A returned payment counts as no payment. The Buyer may also elect to stop in the app on any day, and that day is the Stop Date.

On the Stop Date the Agreement ends. The Buyer owes nothing further and can pay nothing further.

The engine works at monthly resolution and does not model the 15 days as a separate event. It records the missed payment date \(D\) and treats day 16 after it as the Stop Date. \(D\) is \(t+1\) for a stop drawn at payment age \(t\) (payments run first, so payment \(t\) was made) and \(t\) for a conviction walk or a rational-boundary walk, where the walk is the missed payment. The Agreement’s exit month is \(D\).

The sale for dollars

Within two business days of the Stop Date the coin is sold for dollars at market through the normal venue, in a recorded sale, costs on the Company, with the record kept (Marc, 2026-08-22, approving the drafted mechanics; atom R-1037). The sale exists to fix one number, the proceeds \(V\), against which the refund is computed. It is a recorded sale rather than an index read because Marc chose it: “official sale, to record the proceeds” (2026-08-22).

The engine sells the coin stop_sale_lag_days after the missed date (input #24, default 18 calendar days: day 16 plus two business days). The sale price is the path’s price at that point, interpolated log-linearly between the monthly marks on either side. The proceeds are

\[ V = S(D + 18/30.4375) \cdot e^{-h} \cdot (1 - c) \]

where \(h\) is the static haircut (input #15, default 0, Marc 2026-07-12: a one-coin sale has no market impact) and \(c\) is the market-sale cost (input #16, default 25 basis points, Marc 2026-07-11). All of this is engine.rs::stop_sale. The cash posts at the first monthly date at or after the sale, ceil(D + stop_sale_lag_days/30.4375). At the default 18-day lag this is the month after the missed date; at zero lag it is the missed month.

One difference to note. The ruling puts the sale’s costs on the Company; the engine takes the 25 basis points out of the proceeds, which lowers \(V\) by $150 on a $60,000 coin. The waterfall determines how that reduction is allocated between the refund and the delivery; each does not necessarily fall by $150. The sale standard itself, the venue, the deadline and the price against the index, is not yet written into the Agreement, and the model assumes a market sale at the path price less 25 basis points.

The waterfall

Let \(A\) be every payment the Buyer made, payment 1 included (engine.rs::Agreement::paid_in), \(P\) the Purchase Price and \(R = P - A\) the remaining schedule. The proceeds pay out by the R-1033 formula (Marc, 2026-08-22, reporting legal’s approval):

\[ \text{refund} = \min\big(A,\ \max(0,\ V + A - P)\big) \]

\[ \text{delivered} = V - \text{refund} \]

The refund goes to the Buyer in dollars. The delivery goes to the Holder, less the 5% fee. Read as a waterfall, the proceeds pay the Holder the remaining schedule first, then refund the Buyer up to what he paid in, and any surplus above the Purchase Price stays with the Holder (Marc, 2026-09-03: after the refund “the rest goes to” the Holder; the ruling of 2026-08-22 had left the upside with the Company, and 2026-09-03 moved it to the Holder). Three regimes follow from the formula:

The Buyer never gets back more than he paid. The Holder never receives less than the proceeds allow and never more than the remaining schedule plus the surplus above the Purchase Price. Nobody owes anybody anything after a stop. engine.rs::stop_sale records shortfall_usd = max(0, R − V), stop_surplus_usd = max(0, V − P), buyer_refund_usd and stop_proceeds_usd on the Agreement, and the invariant suite checks the three regimes against these identities on every stop of a rising path.

Whether payment 1, the one BTC Now kept, sits in the Buyer’s refund base is a term-sheet item that is flagged, not decided. The engine models it as included, reading Marc’s “the maximum he paid” (2026-09-03).

Dollars, never coin

A stopped Buyer receives dollars, never coin. The refund is paid from the proceeds within ten business days with a statement (Marc, 2026-08-22). The Holder’s delivery is also in dollars; there is no in-kind residual term. A Holder who wants the coin buys it with the proceeds on its own account (Marc, 2026-09-03: “they get in dollars but of course they can just back to back it into coin anyways”). The engine posts TxKind::StopSaleDelivery from the market to the Holder and TxKind::StopRefund from the market to the Buyer; a zero refund posts nothing. Any view that reinvests stop proceeds into coin models the Holder’s own behavior, not a term of the Agreement.

This replaced two earlier designs. The July engine sized the sale to the remaining schedule and returned the residual coin to the Buyer (spec v1.2, Marc 2026-07-11). The 2026-08-21 election of dollars or coin at the agreed price was dropped the next day because a payoff available only by quitting reads like a bet on the price. Under the September program the only way to profit from Bitcoin through the Agreement is to complete it.

Early completion

The Buyer may pay the remaining schedule \(R_t\) in cash at any time and take the coin. This is early completion. It is cash only: the coin is never sold to pay for it (spec v1.5, change 3). The Holder receives \(R_t\) less the 5% fee and the Agreement closes.

engine.rs::settle posts the payoff from the Buyer to the Holder as TxKind::MakeWholeDelivery (the identifier is historical) and the fee to BTC Now. It records the Buyer’s coin equity at exit, the spot value of the coin less the payoff, as coin_returned_usd. That figure is the Buyer’s property, not a cash flow, and it appears in the outputs only as a transparency counter.

Relative to full scheduled completion at the base terms, early completion delivers the same total net scheduled cash sooner. It also closes the Agreement, removing any later stop exposure and possible surplus. Its effect on portfolio cash and IRR therefore depends on the alternative path and exit behavior. Run the early-completion propensity (input #12) at zero as a separate sensitivity. In the engine the decision is a monthly draw with probability proportional to how far the coin is above the remaining schedule, \(u_t = \text{propensity} \cdot \max(0, (S_t - R_t)/S_t)\), optionally gated by a take-profit threshold on the Buyer’s all-in cost (input #22). Those are model choices, not terms; see the behavior chapter.

Completion

When the sixtieth payment is made, the Agreement completes and the coin is delivered to the Buyer. The engine marks the Agreement Completed at the payment date that brings payments_made to the term and posts nothing further. Delivery of the coin is outside the ledger: the Holder never held it and the engine never values it. No new hazard draw occurs after payment 60 completes the Agreement. A hazard draw after payment 59 can miss payment 60 and follows the same stop waterfall and sale timing as an earlier stop. A lost-conviction walk armed at payment 59, or a rational-boundary decision at payment 60 itself, can still consume payment 60 unpaid (engine.rs::run, steps 1 and 2a); those are deterministic rules, not draws.

The two lockouts

Two lockouts were reinstated on 2026-09-03 (Marc), after the ruling of 2026-08-10 that struck the July lockout ladder.

1. A person who has not yet signed gets a 60-minute window to accept a price. Letting two such windows lapse locks the person out of the program for seven days. This stops the free look at the price from being farmed.
2. A Buyer who stops, for any reason, is locked out for six months. This makes re-entering at a lower strike a six-month bet with the deposits at stake.

Neither is modelled. The engine has no notion of a person across Agreements and no re-entry; each Agreement is one Buyer, once. The July rescission ladder, escalating lockouts and Application Fee are not part of the modelled program.

No qualification and no sizing

There is no qualification of Buyers and no sizing of an Agreement to the Buyer’s cash flow (Marc, 2026-08-22: “we will NOT check eligibility, we do NOT size”; atoms R-1034 and R-1036). Four checks run before a Sale or a Transfer: identity verification, sanctions screening, a bankruptcy screen on the consumer report, and the one-Bitcoin active cap, under which a Buyer’s active coin across Agreements in force may not exceed one Bitcoin. The cap is the only sizing rule. A credit-score floor was considered on 2026-08-21 and foreclosed the next day.

The engine models none of these. It has no Buyer attributes: no score, no income, no identity, no cap. Every Agreement is one coin, which is why the engine’s book of one-coin Agreements is also a book that respects the cap. The consequence for the Holder is that the stop hazard is a prior on an unscreened population, and the behavior chapter says so.

What the engine does not model

The engine models money. It leaves out the parts of the program that move the coin or move the parties.

• The Dedicated Wallet and custody. Each Agreement’s coin sits in a per-Agreement wallet under a trust structure until completion, and on a stop the trust releases it to the Company for sale. The engine has no wallet; it prices the coin on the path and sells it at a number.
• The Transfer of the paying side. A Buyer may hand the Agreement to another Buyer (Transferor to Transferee) for a $250 transfer fee. The engine has one Buyer per Agreement for its whole life.
• The Sale of the receiving side after the Primary Sale. Secondary Sales between Holders, and the 1% facilitation fee on the value moved (Marc, 2026-08-31), are outside the engine. It models one Holder that buys at origination and holds to the end.
• Referral cuts. A Partner’s cut of the first payment (X1, ruled 50% on 2026-08-31) and of the servicing fee (X2, ruled 0 for now) are splits inside BTC Now’s take. The engine reports BTC Now’s take whole.
• The stop-sale mechanics. Venue, deadline, the record, the refund’s ten-day clock and the refund rail (dollars to the account paid from) are procedure. The engine posts the refund and the delivery at one date.
• The lockouts, above.
• Payment rails and timing inside a month. ACH, the 15 days of grace, returned payments and the reminder ladder collapse into one monthly mark.

One Agreement, three endings

Everything below is at the base terms and was run through the engine at POST /api/forwardflow/simulate with one cohort of one Agreement, zero hazard, and a constructed path (PathMode::Custom). The early completion was forced with the propensity (input #12) at 1.0 and the take-profit gate (input #22) at 0, and the stop with the lost-conviction rule (input #11) at X = 0%, Y = 1, so that each exit lands on the stated month; the dollar figures do not depend on how the exit was forced. A $60,000 coin, 1.475×, 60 payments of $1,475, Purchase Price $88,500, payment 1 to BTC Now, 5% on every delivered dollar, the Holder buys at par ($60,000), the stop sale 18 days after the missed payment, 25 basis points of sale cost, no haircut. The rates of return quoted are irr_nominal_pa from outputs.rs::analyze for that single Agreement on that path; they are not the Model Card’s book figures.

Completion

The Buyer pays $1,475 a month for 60 months and takes the coin.

The Holder’s undiscounted multiple is 1.378×. The engine prints a nominal rate of 13.1% per year (14.0% effective), a weighted average life of 31 months and payback in month 44. That is the paper’s rate with nobody stopping and nobody completing early.

Early completion at month 24

The Buyer makes 24 payments, then, with the coin at $90,000, pays the remaining schedule in cash and takes the coin.

The Holder’s total is the same $82,673.75 as at completion and its multiple is the same 1.378×; only the timing differs, and the engine prints 20.1% nominal (22.0% effective) because the money came back in two years instead of five. The Buyer’s $36,900 never enters the ledger.

A stop after twelve payments, at three prices

The Buyer makes 12 payments and misses the thirteenth. \(A = 17{,}700\), \(R = 70{,}800\), \(P = 88{,}500\). Day 16 is the Stop Date. The coin is sold 18 days after the missed date. Three prices at the sale show the three regimes. The Holder has already received 11 net payments, $15,413.75, and BTC Now has $1,475 plus 11 fees of $73.75.

Three things to read off the table.

At $40,000 the sale does not cover the remaining schedule. The Buyer gets nothing back, the Holder takes the whole $39,900 and still loses $6,681.25 on its $60,000. This is the loss the paper carries, and it is a loss on any stop where the proceeds fall below the capital line described in the risk-desk chapter.

At $75,000 the proceeds clear the remaining schedule by $4,012.50, and exactly that amount goes back to the Buyer. The Holder receives precisely the remaining schedule, $70,800 gross, and its total is the same $82,673.75 it would have received at completion. In regime 2 a stop is a completion that arrived early.

At $100,000 the proceeds exceed the Purchase Price. The Buyer gets back everything he paid, $17,700, and not a dollar more; the Holder receives the remaining schedule plus the $11,250 surplus. This is the ruling of 2026-09-03 in one row: the upside on a stop belongs to the Holder. On Bitcoin’s own history it is the row that moves the replay figures, and the Model Card says to read them with the in-the-money stop rate attached.

In every column BTC Now’s take is its fees only: the first payment, 5% of the delivered payments and 5% of the delivered proceeds. In every column the sale cash posts at month 14, the Agreement’s exit month is 13, and the Buyer receives dollars.

Where each rule comes from

The full sequence of versions, with what each one changed in the numbers, is in Versions and rulings. The formulas above are derived and tested in Contract math and the fee and The stop waterfall.

Reading BTC performance

BTC cash-flow IRR tells you the annual return implied by the investment’s dated BTC-equivalent flows. The amounts tell you how much went in, how much came back and how much remains a model value. Use both.

Start with the amounts

The cash and economic views reconcile:

economic recovery − economic contribution = cash recovery − cash contribution + signed horizon value.

For 24 cohorts of ten par Agreements, contractual BTC and gross BTC deployment are both 240 BTC. Earlier receipts can offset later purchases, so net additional contributions may be below 240 BTC. The cohort table shows unhedged purchase funding, fee-net receipts, gain and dated IRR. Cohort gross amounts and gains add to the book; cohort IRRs and monthly-net contribution ratios do not. Shared hedge costs are reported at book level unless an allocation rule is explicitly supplied.

Engine 0.6.0 introduced this entry-funding convention; 0.6.1 retains it while correcting monthly Coin-delta sizing. Earlier versions translated purchase dollars at the monthly reporting price; entry dispersion could therefore show 241.9214 BTC equivalents for the default 240-Agreement case. Old saved results keep that earlier definition and need a fresh run before comparison with current results.

Show both contribution and recovery sides. A horizon mark can flip a month’s sign, so adding it to recovery alone does not always reconcile. Sum cash flows over time; use the final observation for a stock such as an open position’s value.

A total return is not always an annual rate

With one contribution of 100 BTC and one recovery of 110 BTC, the recovery ratio is 1.10× and total return is 10%. If the flows are exactly one year apart, annualized IRR is also 10%. Five years apart gives about 1.92% a year. Other dated contributions and receipts change the rate again. Costs must already be included in the flow amounts being compared.

BTC cash-flow IRR remains useful when Agreements pay over time: it accounts for the dates and amounts. It uses the original modeled BTC-equivalent flows and reports unavailable or multiple-root diagnostics where needed. At constant spot, equivalent USD and BTC flow vectors have the same IRR within numerical tolerance. Changing Bitcoin prices can make their returns very different.

The net recovery ratio is recovery divided by contribution, with economic and realized-cash versions named separately. Zero contribution or a non-finite ratio makes it unavailable. The legacy net outcome per BTC of Agreement purchases uses gross purchase BTC equivalents as its denominator and signed hedge flows in its numerator. That is a different ratio. For a flat-price example with a purchase of 1, receipt of 1.5 and hedge cost of 0.2, the legacy Coin ratio is 1.30× while the USD combined multiple is 1.25×. The difference is convention, not currency performance.

What holding BTC means here

Current Research compares each strategy with retaining its same dated net BTC-equivalent contributions. Show that contribution amount beside the surplus. Each strategy can need a different amount; a larger absolute surplus alone does not establish a better use of the same starting capital.

Legacy shelf alternatives use a contractual one-coin-per-Agreement reference and their own cost, timing and collateral assumptions. Sharing market paths does not make them equal-budget investments. A sampled hedge result does not guarantee a floor, even if no path in that sample loses BTC.

A complete wallet comparison would start each strategy with the same BTC budget and track idle BTC, USD cash, conversion costs, reserves, collateral, liabilities and additional transfers. It would also say what happens when the wallet cannot meet a call. That model is not implemented. Do not interpret BTC cash-flow IRR as complete-wallet CAGR.

Reporting currency, cash and value

ForwardFlow funds Agreement purchases at their actual entry prices. It converts subsequent USD receipts, hedge cash and remaining values at the stated monthly USD/BTC price. These are explicit timing assumptions; the model does not execute a currency trade or prove an actual venue settlement. Instruments can use different quote units, settlement assets and collateral rules. Deribit’s inverse option specification, for example, describes actual BTC premiums and settlement; it does not certify that this model implements that venue’s complete rules.

Purchase-yield Agreement marks explain monthly P&L under a cost-calibrated flat-continuation convention. They are not certified reporting fair values. IFRS 13’s fair-value concept concerns a current market-participant exit value, which cost calibration alone cannot establish.

CFA Institute’s GIPS handbook distinguishes money-weighted returns sensitive to external-flow timing from time-weighted returns that neutralize those flows. A complete account return must define the account boundary and include its assets and cash. This is useful measurement context; ForwardFlow does not claim GIPS compliance.

See the workspace guide, hedging formulas, MCP capabilities and release model card.

Glossary

Find the terms used in the Agreement, the workspace and the API. Each entry includes a short definition, further explanation and a reference to the relevant method. Use the alphabet or search the guide.

A

Abuse caps

Also: caps, heavy permit, HEAVY, semaphore, 400.

Bounds on the work a request can ask for, each answering 400 with the input named: 1,200 cohorts, 50,000 Agreements, 480 months, 100,000 runs, 24 million Agreement-runs, 900 heatmap cells. Three heavy requests run at once; the rest queue.

Hosting hardening of 2026-07-13 (spec v1.4 change 13). The engine’s validate panics with a message naming the input and catch_engine unwinds it into the 400, which is why the build must never set panic = "abort".

→ Where it is derived

Agreement

Also: Agreements, BPA, Bitcoin Purchase Agreement.

A Bitcoin Purchase Agreement: one coin bought at a price fixed on the day it opens, paid for on a fixed monthly schedule. The Buyer pays, the Holder receives; the coin passes at completion.

An Agreement is a conditional sale of one Bitcoin. The Buyer pays the Purchase Price, entry strike times the multiple, on the contractual monthly schedule; title passes at completion. The Agreement can complete, complete early or stop. A cohort is an origination group of these one-BTC Agreements. The Holder’s purchase price is a separate amount: from engine 0.6.0, the Coin model funds it at that Agreement’s own entry strike, so a par purchase uses exactly one BTC even with dispersed entry prices; a non-par purchase uses purchase price divided by entry strike. The engine does not track Buyer identity across Agreements.

→ Where it is derived

Amortized obligation

Also: remaining obligation, B_t, remaining amortized obligation, obligation.

The Buyer’s remaining obligation in present-value terms: the amortization balance at the implied financing rate. $51,580.88 after payment 12 at the base terms, against a nominal $70,800. The rational modes measure underwater against it.

contract.rs::ContractTerms::remaining_obligation; \(B_0 = \text{strike}\), \(B_n = 0\). A Buyer compares the coin to what the remaining payments are worth, not their undiscounted sum; against \(R_t\) every Buyer on a flat path would be “underwater” for nineteen months and the rational mode would empty the book. So: nominal for the waterfall and the ledger, amortized for the boundary.

[ B_t = \text{strike},(1+i)^t - \text{PMT},\frac{(1+i)^t - 1}{i} ]

→ Where it is derived

API key

Also: X-API-Key, key name, desk key.

A desk’s credential in keyed mode: the header X-API-Key: <key> on every /api/forwardflow/* call. Issued by BTC Now, one per counterparty, compared in constant time; only its name ever reaches a log or the X-Key-Name header.

Configured on the engine as FF_API_KEYS (name:key,…, every key at least 24 characters). Never shared between institutions, never placed in a browser page; rotated or revoked by asking BTC Now. The cockpit holds its own key server-side.

→ Where it is derived

As-of month

Also: as_of_month, as of, as_of_spot.

The month at which the book is valued for the Greeks: the ladder month, 23 by default on the base path. Bumps start the month after; the existing book is frozen by stopping origination there.

from = as_of + 1; apply_bump leaves earlier months untouched. The as-of spot ($33,375.25 on the base path at month 23) is what delta in coins divides by.

→ Where it is derived

ATM vol

Also: at-the-money vol, surface ATM, ATM 12m, ATM 24m, atm_vol_used.

The surface’s vol at moneyness 1.00 (strike equal to spot) for a tenor. The placement exhibit shows the 12-month ATM beside the paper’s implied vol; the fair value’s paths run at the 24-month ATM.

VolSurface::atm(tenor_months). The stylised preset’s ATM is 41.4% from 1 to 12 months rising to 48% at 24; the flat preset is 43% everywhere. The fair value uses one vol because its paths are plain GBM — the skew enters the placement exhibit and the hedge legs, not those paths.

→ Where it is derived

B

backtest

Also: POST /api/forwardflow/backtest, ff_backtest.

One engine run per seasoned historical vintage: the configuration with the path, cohorts and origination window overridden per vintage, everything else held. Returns the vintage rows, the blended figures and a count of failed vintages.

Heavy route. Replay is rebased so month 0 equals the start price; agreements_per_cohort sets the units per vintage. 113 vintages and no holes at the base cockpit configuration.

→ Where it is derived

Base configuration

Also: BASE_CONFIG, base cockpit configuration, program base case, Reset to program base case, ≈ memo config.

What the cockpit loads first: a 43% bridge from $60,000 to $60,000, 40% lifetime stop prior, multipliers off, 2.5% early completion, 24 cohorts of 10 with dispersed strikes, par, 5%, 18-day lag, seed 42. Not the Model Card’s construction.

Defined by lib.ts::BASE_CONFIG. It sets intramonth strike dispersion on and a fixed 84-month market horizon; the engine default has dispersion off and derives its horizon. A saved draft can replace the initial workspace configuration. Read the full submitted configuration and completed run metadata rather than treating a historical base-case figure or short hash as current.

→ Where it is derived

Baseline hump

Also: program hump, Program hump, the hump, BaselineCurve, timing shape, actuarial curve.

The program’s hazard shape as a step function of term fraction: ×1.0 for the first 5%, ×2.0 up to 25% (the hump), ×1.2 to 40%, ×0.7 to 60%, ×0.25 after. At 60 months the hump is payments 4 to 15.

defaults.rs::shape_weights, normalized to term fraction so the shape travels with the term (spec v1.1). At 60 months it reproduces the program’s actuarial buckets exactly. The unconditional mass by year at the 40% prior: 18.7% in year one, 12.4%, 5.5%, 1.8%, 1.6%. The cockpit’s timing chips are the hump, flat, and late-loaded.

→ Where it is derived

Basis lock

Also: locked basis, basis schedule.

A modeled annual basis rate for an initial number of months, followed by the configured rate after that period. It describes the price of futures exposure under the selected schedule.

BasisSchedule specifies locked_months, locked_rate and after_rate. Availability, execution and future roll rates are assumptions, not verified listed-market quotes. Long and short positions apply the stated sign convention; the duration and cost must stay with the result.

→ Where it is derived

Basis rate

Also: basis, basis_rate, cash-and-carry rate, hurdle.

The crypto risk-free rate to a market-neutral desk (default 6%/yr): what cash-and-carry earns. The hurdle the hedged median IRR is read against; hedged excess over basis is the median minus this.

Request field basis_rate on the hedge endpoint, annual effective, ±100%. It does not enter any hedge flow — it is a reference line on the percentile strips and the subtraction behind hedged_excess_over_basis_pp. A desk that can earn the basis with no directional risk needs the hedged paper to beat it.

→ Where it is derived

Basis received

Also: basis paid, a short receives the basis, basis leg.

Dated-futures basis, annualised, charged monthly on the hedge notional as h·S_m·b/12 at m + 1: a long pays it, a short receives it. The coin book’s long pays 4% then 10%; the dollar book’s short is paid 4% a year.

BasisSchedule { locked_months, locked_rate, after_rate } sets b: the locked rate for the first months of each Agreement’s life (a dated contract held to expiry), the after rate on the rolls. The engine posts the basis on its own leg beside the mark-to-market, so a desk sees where the money went.

→ Where it is derived

Behavior Engine

Also: parked Behavior Engine, bbe/v0, BBE.

The thirty-seven-parameter behavior model parked on its own branch on 2026-09-03 (Marc). Its rational boundary was lifted into the main engine as input #25; its four-channel decomposition goes to the memo as prose.

It stays the validation instrument for the day live vintages exist and an actual-versus-model report can be run.

→ Where it is derived

Believed drift

Also: mu_annual, μ, Boundary believed drift %/yr, Believed drift, belief.

The Buyer’s own expected annual appreciation of the coin, the one lattice parameter that is a belief. Default 25%; zero is the pessimist who should never have signed and walks at or above par from the first dates.

Accepted within ±200% a year, and \(|\mu|\sqrt{\Delta}\) must not exceed sigma. The risk endpoint reports the frontier for a family of drifts, by default 0, 10%, 25% and 50%. At payment 1 the frontier reads 1.162, 1.011, 0.521 and 0.152 of entry respectively.

→ Where it is derived

Below the Agreement-purchase reference

Also: share below one coin, pct_negative (coin).

The all-seed share whose legacy net outcome per BTC of Agreement purchases is below 1×. This is a BTC-outcome event, independent of whether a path has an IRR.

Legacy Coin Dist.pct_negative uses this purchase-normalized loss event; USD pct_negative instead concerns negative valid IRRs. The Coin Research matched-contribution comparison names its own capital basis. Neither label means a custody account literally contains fewer than one BTC. Zero observed losses in a finite sample is not zero loss probability.

→ Where it is derived

Below the line

Also: below_schedule, below_capital, below the schedule line, below the capital line.

An active Agreement whose stop sale at this month’s mark would not cover the line: below the schedule line a stop leaves a shortfall; below the capital line it loses the Holder’s capital.

On the base path the count below the capital line peaks at 127 in month 22 and is zero from month 30; the count below the schedule line is still 62 at month 30 and first reaches zero at month 40. The loss story lives in the first two years of each vintage.

→ Where it is derived

Benchmarks

Also: paper vs spot vs covered call, Benchmarks, include_benchmarks, the directional desk’s comparison.

The directional desk’s comparison on the same seeds: the paper as the config runs it, spot (buy the same coins at the same months, sell at the horizon), and spot with a covered-call overwrite. Three distributions, one set of paths.

hedge::benchmarks(config, surface, seeds), returned when the hedge request sets include_benchmarks. The paper row equals the unhedged distribution. The headline is the paper’s median IRR over spot’s, in points: whether the paper beats owning the coin outright on the config’s own price model, and whether the paper’s short put is paid better than an overwrite pays.

→ Where it is derived

Black-Scholes

Also: BS put, BS call, bs_put, bs_call, European put.

The option formula the desk uses as written: a European put on one coin is K·e^{−rT}·N(−d₂) − S·N(−d₁), the call S·N(d₁) − K·e^{−rT}·N(d₂), with d₁ = (ln(S/K) + (r + σ²/2)T)/(σ√T) and d₂ = d₁ − σ√T.

surface::bs_put, bs_call, bs_delta_put (N(d₁) − 1) and bs_vega (S·√T·φ(d₁), dollars per vol point). The normal CDF is written out (Hart 1968 via West 2005) so the numbers a desk sees never depend on a platform’s erf. Zero tenor or zero vol degenerates to discounted intrinsic. The placement prices at the funding rate; the hedge overlay and the benchmarks price at zero rate, the surface’s own quoting convention.

[ P = K e^{-rT} N(-d_2) - S, N(-d_1), \qquad d_1 = \frac{\ln(S/K) + (r + \sigma^2/2),T}{\sigma\sqrt{T}}, \quad d_2 = d_1 - \sigma\sqrt{T} ]

→ Where it is derived

Blended

Also: blended MOIC, blended_moic, blended row, buy-every-month.

The realized flow of buying every vintage at equal size: blended MOIC = (Σ deployed + Σ net gain) ÷ Σ deployed. 3.081× at the base cockpit configuration, $138.2m of net gain on $66.4m deployed.

Dominated by the early vintages, which rode the whole rally from single-digit dollars. A one-asset history has survivorship in it; the rows are the information.

[ \text{blended MOIC} = \frac{\sum_v \text{deployed}_v + \sum_v \text{net gain}_v}{\sum_v \text{deployed}_v} ]

→ Where it is derived

Block length

Also: block_len, Block length (months), blocks.

How many consecutive de-meaned monthly returns the bootstrap glues together at a time: 6 by default, so half a year of the actual sequence, its drawdown streaks and recoveries, survives inside each block.

Each block start is drawn uniformly from the regime’s returns; the last block is truncated at the horizon. The regime must supply at least block_len + 1 bars or the run fails with RegimeTooShort.

→ Where it is derived

Break-even frontier

Also: IRR = 0 frontier, the cliff, Where’s the cliff, bold line = break-even.

The IRR = 0 contour on a heatmap, drawn by the cockpit as a bold segment on every edge between adjacent cells of opposite sign. At the base configuration only the volatility × conviction grid crosses it.

charts.tsx::Heatmap; holes take part in no edge. It is the break-even line an investment committee argues about.

→ Where it is derived

Brownian bridge

Also: bridge, Bridge (pinned), pinned bridge, end price, End price.

An endpoint-pinned price path: volatility changes the route between the chosen start and end prices. It answers a conditional question about a specified terminal price.

paths.rs::bridge. Zero volatility gives a deterministic log-linear ramp; equal endpoints then give a flat path. Bridge Monte Carlo samples intermediate prices, not terminal-price uncertainty. Legacy API defaults use a bridge; new Dollar and Coin workspaces start with illustrative GBM assumptions. A saved scenario retains its own path mode.

[ x_{k+1} = x_k + \frac{T - x_k}{n} + \sigma_m \sqrt{\tfrac{n-1}{n}}; Z_k, \qquad \sigma_m = \sigma/\sqrt{12} ]

→ Where it is derived

BTC cash-flow IRR

Also: IRR in coin, Coin IRR, BTC cash-flow IRR.

Annualized IRR of the Holder’s dated monthly BTC-equivalent investment flows after included costs. Signed horizon derivative value is included once where applicable. Useful for comparing cash-flow timing; not annual growth of an entire BTC wallet.

coin.rs::coin_seat_metrics solves the original BTC flows through outputs.rs::irr_analysis_f64, preserving unavailable reasons and multiple-root diagnostics. Purchases use their Agreement entry price; receipts and hedge cash use monthly spot, with signed horizon value included once where applicable. Equal USD and BTC vectors up to constant scale have equal IRRs, but constant monthly spot alone does not ensure this if entry prices differ. One contribution of 100 BTC and recovery of 110 BTC gives 10% total return; annualized IRR is 10% only when those are the only flows and one year apart. Unused reserves and total wallet growth are outside this measure.

→ Where it is derived

BTC net asset value

All modeled assets less liabilities expressed in BTC at the valuation date, including cash and open positions once. A complete funded-wallet NAV is not currently simulated; cumulative BTC-equivalent cash surplus is a different measure.

See the workspace measurement contract for cash, economic value, denominator and funding boundaries.

→ Where it is derived

BTC Now

Also: the Company, originator, servicer, BtcNow.

Originator and servicer of every Agreement, and always Holder 0. It takes the first payment whole and 5% of every dollar delivered to a Holder, never a share of a stop sale. Ledger entity BtcNow.

BTC Now pays nothing into the engine; it receives the purchase price of the paper at the Sale, the first N payments and the flow fees. The invariant suite asserts its total take equals origination fees plus flow fees. The engine assumes BTC Now is always there to service; servicer failure is a Phase 4 dial.

→ Where it is derived

BTC Now take

Also: total_take, Program take, BTC Now’s take, BTC Now take, btcnow, take.

Origination fees plus flow fees, and nothing else: $5,826.25 on a completed base Agreement ($1,475 + $4,351.25), $892,043.38 on the historical early-September reference book. No dial gives BTC Now a share of a stop sale.

outputs.rs::BtcNowTake, built from ledger totals by posting kind. The purchase prices Holders paid are acquisition proceeds, reported separately, and the paper spread is reported separately too so the M0 identities keep holding. A Partner’s cuts are splits inside this figure.

→ Where it is derived

BTC Now’s own posture

Also: 70% floor, 75% density, BTC Now posture, the ruling of 2026-08-16.

The preset encoding the ruling of 2026-08-16: puts at 70% of entry, 24-month tenor, 0.75 coins per Agreement, put on at each origination. BTC Now’s own posture as Holder 0, labelled as such — one preset among several, not a recommendation.

HedgeSpec::PutLadder { strike_pct_of_entry: 0.70, tenor_months: 24, coverage: 0.75, inception: AtOrigination }. The 70% floor is the strike; the 75% density is the coverage. It is on the shelf so a Holder can see what BTC Now does with its own book and compare, not so it is adopted.

→ Where it is derived

BTC recovery ratio

Net BTC recovery divided by net BTC contribution on the same cash or economic basis. A dimensionless multiple, reported as ×; ratio minus one is total return. A zero denominator is unavailable. Timing is measured separately by BTC cash-flow IRR.

See the workspace measurement contract for cash, economic value, denominator and funding boundaries.

→ Where it is derived

Bump

Also: bump overlay, PathBump, price bump, vol bump, what-if bump, Bumps.

The second overlay (v1.6): from a month on, every price times a factor and the log returns’ deviations from their mean times a vol factor, drift kept. It exists for the Greeks and can be set directly as a what-if.

paths.rs::apply_bump; month 0 is never bumped. hold_strikes true keeps the existing book’s strikes on the unbumped path. The risk endpoint refuses a configuration that already carries a bump, because the Greeks own it. Price factor accepted in (0.1, 10), vol factor in [0, 5).

[ r’m = \bar r + v,(r_m - \bar r), \qquad P’m = P{a-1} \exp\Big(\sum{j=a}^{m} r’_j\Big) ]

→ Where it is derived

Bump-and-revalue

Also: finite difference, revalue.

The method behind the Greeks: apply a bump to every future price (or to realized volatility), re-run the same seeded book, and take the difference in net gain. Valid only because every Agreement draws from its own stream.

A finite difference is a sensitivity only if the two runs differ by the bump alone. greeks_are_sensitivities_not_draw_noise bumps a 240-Agreement book by one basis point and requires at most two exits to flip. The risk endpoint refuses a configuration that already carries a what-if bump.

→ Where it is derived

Buyer

Also: Buyers, paying side, Obligor, obligor.

The paying side of an Agreement: the person paying the schedule for one coin. Buyer 0 opened it; the paying side changes hands by Transfer. The engine’s ledger calls the Buyer Obligor.

Locked by Marc on 2026-09-02. The Buyer pays the schedule, receives a dollar refund on a stop, and takes the coin at completion or early completion. The Buyer never owes anything after a stop and pays no late, returned-payment or termination fees. The engine identifier Obligor(id) predates the lock and was kept so stored results keep deserializing; the exit tag non_performance likewise means a stop.

→ Where it is derived

Buyer 0

Also: Buyer zero, original Buyer.

The Buyer who opened the Agreement. Buyers are numbered from 0; a Transfer hands the paying side to Buyer 1, then Buyer 2, and so on. The engine has one Buyer per Agreement for its whole life.

The chain is numbered rather than named: “Original Buyer” is not a word (Marc, 2026-09-02). The engine models no Transfer, so every Agreement is Buyer 0 from origination to exit.

→ Where it is derived

Buyer discount rate

Also: r_c_annual, r_c, Buyer discount rate %/yr, personal discount rate.

The rate at which the rational Buyer discounts the continuation value of paying: 15% a year by default, e^(−r_c/12) per month. Accepted from 0 to below 100%.

Applied at each of the four lattice steps a month, \(e^{-r_c\Delta} = 0.99688\) per step. A coin one does not expect to appreciate is not worth financing at 1.475× and a 15% discount rate, whatever the volatility.

→ Where it is derived

Byte ceiling

Also: FF_MAX_ESTIMATED_BYTES, estimated ledger memory, estimate_bytes, POSTING_BYTES, work estimate.

A per-request admission ceiling on estimated peak memory, FF_MAX_ESTIMATED_BYTES (1.5 GB by default). It includes the route’s retained state and response allowance where applicable; the raw posting estimate alone is not a detailed-output bound.

The raw forwardflow::estimate_bytes posting expectation and work_estimate.rs::peak_bytes serve different purposes. Admission validates the configuration first and uses a conservative peak bound for the route. In 0.6.1, estimate_simulate_request includes selected Agreement/cohort detail, typed postings and bounded JSON capacity, and simulation responses retain their process-memory reservation through serialization, compression and outgoing byte ownership. Coin routes also budget retained monthly surfaces. The process budget is separate from the per-request ceiling: requests that cannot fit alongside current work receive 503 with Retry-After. These estimates are neither measured RSS nor a precise CPU-time guarantee.

→ Where it is derived

C

Call spread

Also: call spreads, 1.475× / 2.5× spread, 2× / 4× spread.

A bought call and a written call with a higher strike, at the selected size and tenor. The written leg helps pay the premium but gives up protection above its strike.

Read each strike, side, premium, settlement and horizon mark. Short-option collateral and execution constraints are not established by the model; a lower net premium alone does not prove a cheaper fully funded hedge.

→ Where it is derived

Cancellation

Also: Cancel, cooperative cancellation, cancel token, PathError::Cancelled, 499.

A token every seed, cell, structure and vintage loop reads before each unit of work; a dropped HTTP request or a closed websocket — mid-chunk included — sets it, the units not started are reclaimed and the permit and the memory reservation return. A running month finishes; the loop is never interrupted.

forwardflow::Cancel (cancel.rs; model audit 2026-09-06, M08): run_monte_carlo_with_cancel, hedge_overlay_with_cancel, hedge_series_with_cancel, drift_sweep_with_cancel, unhedged_dists_with_cancel and greeks_with_cancel return PathError::Cancelled instead of the next unit; the API’s run_work hands a token to every heavy request and CancelOnDrop sets it when the caller goes away; the websocket selects both its permit wait and each chunk against the socket, so a close mid-chunk stops the chunk at its next seed (model audit 2026-09-07, R10). A token can carry a budget of units, which is how the tests stop a run after exactly one seed.

→ Where it is derived

Capability table

Also: what each instrument supports, instrument capabilities, per-instrument capability table.

The one table, per hedge structure, of what the desk computes from the contract, what stands in as a proxy, and what it does not compute and says so — cash flows, maturity, monthly mark, execution cost, margin, close-out, whole wealth.

Model audit 2026-09-06, M10’s acceptance. Read it before comparing structures on the run page: a “no (stated)” cell — the collar’s free coin, the coin-delta branch’s trading cost, any option’s margin — is a figure a Holder supplies from outside, and the label “total P&L” on that row is the contract’s cash and mark as modelled and nothing more.

→ Where it is derived

Capital at risk

Also: capital_at_risk_usd, dollars that can be lost, peak capital at risk.

The sum of unrecovered capital over active Agreements: the dollars a par Holder can actually lose, month by month. Peaks at $5.94m at month 23 on the base path, the default ladder month.

It is the figure the exposure ladder colours, and the month of its peak is the default as-of month for the Greeks. It is the capital line’s numerator summed across the book.

→ Where it is derived

Capital line

Also: capital_line, the capital line, loss line.

The sale proceeds that return the Holder’s unrecovered capital, counting what it has already been paid, over the strike. 1.053 at months 0 and 1 (payment 1 went to BTC Now, every dollar carries 5%), 0.487 at month 24, zero from 44.

exposure.rs::capital_proceeds_needed solves \(\text{delivered}(V)(1-f) = U_t\) piecewise on the waterfall: \(U_t/(1-f)\) while that is at most \(R_t\), else \(A_t + U_t/(1-f)\), flagged capital_above_purchase_price. At par the first branch holds throughout. A stop below this line loses the Holder money; after month 44 no stop at any price can.

[ V^{\text{cap}}_t = \begin{cases} U_t/(1-f) & U_t/(1-f) \le R_t \ A_t + U_t/(1-f) & \text{otherwise} \end{cases}, \qquad \ell^{C}_t = V^{\text{cap}}_t / \text{strike} ]

→ Where it is derived

Capital loss

Also: capital_loss_usd, Capital loss, realized capital loss.

Σ max(0, −capital P&L) over a vintage’s stops: the par Holder’s realized loss, against its outlay net of what it had already been paid. $231k on the historical early-September reference book against an EL of $990k.

Most of the shortfall lands on Agreements that had already returned most of the Holder’s capital, the dollar version of the gap between the two lines. Cohort 1 loses $57,708 of capital; cohort 23 none.

→ Where it is derived

Capital P&L

Also: capital_pnl, Capital P&L $, realized profit, capital loss on a row, Net cash gain.

Hard dollars: net received minus capital deployed on the Agreement, owner_net − purchase_price. Negative is money actually lost against deployed funds; a row can show a shortfall and still be positive here.

The reference Agreement’s is +$22,673.75. In the engine’s worked stop, Agreement 2 stops at age 22 with a $21,212 shortfall and a capital P&L of +$2,522, because 21 delivered payments came in first. The risk desk’s capital loss sums the negative ones over stops.

[ \text{capital P&L} = \text{owner net} - \text{purchase price} ]

→ Where it is derived

Carry bucket

Also: carry, carry at the purchase yield.

The mark rolling forward one month at the purchase yield: y × V(t−1, S at m−1) per Agreement on last month’s book, stops in transit included — the accrual of the month’s expected flows. On a riskless flat path, the only nonzero bucket.

Over the life of a riskless flat path the carry sums to the flat-path markup exactly — $90,695 on the test’s four Agreements.

[ \text{carry} = y,V(t-1, S_{m-1}) ]

→ Where it is derived

Cash fan

Also: cash_fan, When is the money back, cumulative cash band, p5 cash band.

Per month, the p5, p25, p50, p75 and p95 of cumulative net cash across the runs: when the money is actually back, under uncertainty. Chip S5 points here.

At the base cockpit configuration the month-12 band runs from −$9.87M to −$4.51M because the 24 cohorts are still being bought; by month 84 it runs from +$2.29M to +$8.95M, median +$4.53M. The dark band is the middle half, the light band 90% of futures.

→ Where it is derived

Cash loss

Also: pct_cash_loss, cash-loss-share, cash-loss share, share losing cash.

The share of ALL seeds (or runs) whose undiscounted multiple is below one — coins per coin below one on the coin seat. Never conditional on an IRR: a path the solver cannot rate is still a loss if less came back than went out.

Dist::pct_cash_loss and MonteCarloSummary::pct_cash_loss (audit 2026-09-05, finding 1). The share negative counts only the seeds with an IRR; a written option assigned deep in the money, or a book whose every payment BTC Now retains, can leave every seed without one. The negative-IRR share is then unavailable, not 0%. The cash-loss share is the figure to read first when seeds_without_irr is not zero.

→ Where it is derived

Cash recovery

Also: cash_recovery, recovery at 12, 24, 36, cash back by month 12.

Cumulative gross cash received through month 12, 24 and 36, divided by the whole run’s gross outflow. Of everything committed to this program, how much is back by then: 25.69% / 53.71% / 81.74% on the reference Agreement.

The denominator is the run’s total outflow, not the capital deployed by the marker, so on a paced book the markers read low early: 10.04% / 40.01% / 74.41% on the historical early-September reference book. Markers past the horizon are omitted.

[ \text{recovery}M = \frac{\sum{m \le M} \text{in}_m}{\sum_m \text{out}_m} ]

→ Where it is derived

Cash-and-carry basis

Also: basis trade, cash and carry, carry trade.

A shelf row and a dollar asset: the dollars deployed earn the basis (4% a year by default). The dollar seat is the rate on every path; the coin seat is that multiple over where the coin ends — 1.24 flat, 0.29 at the 5th.

The paper’s convention for a dollar asset: coins per coin = (1 + r)^years ÷ (S_T / S_0). Table 19: 3.38 / 1.24 / 0.46 / 0.17 coins from −18% to +49% a year at 4.0% throughout; 41% of flat paths lose coins.

→ Where it is derived

Circular bootstrap

Also: circular block bootstrap, wrapping blocks, sampler weights.

The bootstrap’s draw since the model audit (M03): a block starts on any of the n returns and wraps past the window’s end, so every observation weighs 1/n and the expected log return is zero at every horizon — the sampler’s own zero drift.

paths.rs::bootstrap. The non-circular draw from 0..=n − L weighed the interior more than the edges, and after an equally weighted de-meaning the sampler carried +1.24% / −1.73% / −3.67% a year of log drift on the 2012 / 2017 / 2024 windows. Zero drift means zero expected LOG return under the sampler’s weights, nothing more: the price factor’s median and mean are the empirical block distribution’s (median log step −0.46% a month on the pricing window, log(mean(exp(step))) +0.69%), not a lognormal’s (model audit 2026-09-07). Every bootstrap path changed at the same seed; the Model Card’s zero-drift rows moved by about half a point, the replay rows not at all.

→ Where it is derived

Close on exit

Also: close_on_exit, futures_retained_agreement_months, retained exposure.

A calendar futures leg’s flag: close the position the month its Agreement leaves the book instead of holding it to the next reset. Default off; the result names the Agreement-months held past the exit as retained exposure.

TradingRule::close_on_exit (model audit 2026-09-07, “a calendar futures hedge can outlive the underlying Agreement”: a 12-month Agreement under a five-month reset kept a $60,000 short at month 12 and booked $30,000 of futures profit on a month-13 halving against paper that had completed). Off, the calendar rule holds through the interval — what a k-monthly roll literally does, and what every stored structure was priced on — and HedgeResult::futures_retained_agreement_months counts the Agreement-months a position was held past the paper’s exit, with a warning in the notes when positive. On, the position is closed at the exit, the close-out in the turnover and charged the trading cost.

→ Where it is derived

Cohort

Also: cohorts, monthly cohort, vintage cohort, Monthly cohorts, Agreements per cohort.

A group of Agreements that originate in the same month at that month’s price. The base book is 24 monthly cohorts of 10 Agreements, 240 in all; cohorts and Agreements per cohort are input #13.

Cohorts originate month 0 first, one per month, until the origination window closes. Everyone in a cohort shares the month’s entry price unless intramonth strike dispersion is on. The caps: at most 1,200 cohorts and 50,000 Agreements in a book.

→ Where it is derived

Coin

Also: Bitcoin, BTC, the coin.

The asset underlying each Agreement is one Bitcoin. The contractual ledger records USD payments and stop-sale cash. The Coin workspace adds a BTC unit-of-account view with an explicit purchase-funding and receipt-conversion rule.

The program describes a per-Agreement Dedicated Wallet under a trust structure until completion; the simulator does not implement custody. From engine 0.6.0, a par Agreement purchase is funded with exactly one BTC at its own entry price. Holder receipts and hedge flows are converted analytically at monthly simulated spot. One BTC of contract notional does not mean one BTC of receipts or one BTC of price sensitivity, and modeled equivalents do not establish actual BTC settlement.

→ Where it is derived

Coin book

Also: the coin book.

The Agreement book and modeled hedge evaluated in BTC. Each par Agreement uses one BTC at its own entry price; Holder receipts and hedge cash use monthly simulated spot.

The Coin objective evaluates BTC amounts and dated investment returns against the stated holding reference. Gross Agreement funding is distinct from monthly net contributions, which may reuse receipts. Market moves, Buyer outcomes, costs, model assumptions and funding needs can create losses. The analytical convention does not implement wallet balances, reserves or forced closure.

→ Where it is derived

Coin delta

Also: dC/dlnS, coin delta surface, ex-ante coin delta.

dC/dlnS: expected remaining BTC-receipt sensitivity per unit log spot move. The shared reader uses each Agreement’s actual lifecycle; one BTC of contract notional is not one BTC of delta.

coin.rs::agreement_coin_delta uses CoinDeltaSurface for performing Agreements and an analytic sale/refund/receipt conversion value for known stops awaiting sale. Both use the stated median-flat lognormal continuation volatility (zero log drift); the performing surface also uses its recorded valuation seed. From 0.6.1 it has a node at every monthly payment age, so the final receipt and other monthly transitions are represented directly. Known stops retain their actual paid count, remaining schedule and residual sale lag, including after contractual maturity. After receipt booking and conversion, remaining receipt delta is zero. Delta may be negative, zero or positive. Monthly per-Agreement figures divide by the same performing-plus-stopped-unsold population that was summed.

[ \delta_{\mathrm{performing}}=\frac{\overline C(1.01S)-\overline C(0.99S)}{\ln1.01-\ln0.99},\qquad \delta_{\mathrm{stop}}=\frac{d}{d\ln S}\mathbb E[\mathrm{Holder\ receipt}/S_{\mathrm{booking}}] ]

→ Where it is derived

Coin hedge-ratio sensitivity

Also: coin hedge-ratio sensitivity.

An experiment comparing coin-delta hedge sizes under explicit market and cost assumptions. The historical name of this glossary key does not describe a guarantee.

A finite simulation cannot establish a return floor in every future path. Report the observed downside percentile, sample count, uncertainty and omitted funding constraints. Historical private-paper ratios are not universal optima, and annualizing a purchase-denominator multiple does not produce wallet CAGR.

→ Where it is derived

Coin lending

Also: coin lent, 2% a year in coin.

An illustrative shelf alternative that assumes a fixed annual BTC growth rate over the holding period, then values the proceeds at horizon spot. The fixed growth is an input, not a guaranteed external product return.

The shelf omits counterparty failure, trading and custody frictions unless stated in its convention. Its contractual one-coin starting basis can differ from an Agreement’s purchase amount and from Research’s matched net contributions. Use it as a labeled reference, not an equal-budget or risk-free ranking.

→ Where it is derived

Coin seat

Also: the coin seat, coin mandate.

The Agreement and hedge book read in BTC equivalents: purchases funded at each Agreement’s own entry price, and receipts and hedge cash converted at monthly simulated spot. At par, each originated Agreement uses exactly one BTC.

Engine 0.6.0 separates actual-entry purchase funding from monthly receipt conversion. Fixed future USD receipts buy fewer BTC when spot rises and more when it falls. Read gross BTC purchases, receipts, net contributions, recovery, gain and cash-flow IRR together. The Coin view is an analytical accounting convention, not actual custody or proof that a finite wallet can meet cash calls.

→ Where it is derived

Coin to Buyer

Also: coin_returned_usd, coin_returned_to_obligors, coin equity, Buyer’s coin equity, coin returned.

The spot value of the coin a Buyer took at early completion, net of the payoff: the Buyer’s property, never the Holder’s cash, reported as a transparency counter. Zero on every other exit; a stopped Buyer receives dollars, never coin.

engine.rs::settle records it; $36,900 in the program chapter’s month-24 early completion at $90,000, $2,123,267.67 across the historical early-September reference book. The report view’s July fallback counted the old sale’s residual coin under this name; the live engine counts only early-completion equity.

→ Where it is derived

Commitment delta

Also: delta_commitment_usd_per_pct, Commitment delta, forward-flow commitment.

Delta with the full pacing, so cohorts after the as-of month strike at the bumped prices: the purchase commitment’s exposure rather than the existing book’s. Coincides with delta when no cohort originates after the as-of month.

On a book with no stops the existing book’s delta is zero and the commitment delta is positive as of month 0 (greeks_vanish_on_a_riskless_book). On the base configuration as of month 23, the last origination month, both read +$24,885.

→ Where it is derived

Completion

Also: completed, Completed, completes.

All payments delivered; the coin passes to the Buyer and the Agreement closes. At the base terms the Holder has received 59 net payments of $1,401.25, $82,673.75, on $60,000 paid.

The engine marks the Agreement Completed at the payment date that brings payments_made to the term and posts nothing further. Delivery of the coin is outside the ledger. No new hazard is drawn after the final payment completes the Agreement. A hazard draw after the penultimate payment, or a walk decided before payment, can still cause the final payment to be missed.

→ Where it is derived

Configuration hash

Also: config hash, sha8, hash.

The first eight hex characters of SHA-256 over JSON.stringify(config) in the cockpit’s field order: a fingerprint of the deal, printed on every export. BASE_CONFIG hashes to 4e8fd718.

export.ts::sha8. Key order matters: the same values with shock moved to the end hash to a0ac777b. It is a fingerprint, not an encoding; the configuration must travel with the figure. The seed is printed separately because two configurations differing only in seed are the same deal on a different path.

→ Where it is derived

Conservation

Also: Σ ≡ $0.00, honesty check, conservation_ok, balances to the cent.

The engine’s honesty check: the sum of every entity’s balance is exactly zero, so money only moves and is never created. The header must read Σ ≡ $0.00 ✓; anything else is an engine bug, not a market outcome.

ledger.rs::Ledger::conservation_sum; asserted at the end of every run in debug builds, reported as conservation_ok on every simulate response, and checked across scenario families by conservation_to_the_cent_across_scenarios. On a stop the three postings sum to the proceeds, which is what the Market gives up.

[ \sum_{e \in \text{entities}} \text{balance}(e) \equiv 0 ]

→ Where it is derived

Content integrity

Also: content-integrity check, digest check, unkeyed hash, not a signature.

What a package’s digest proves: the content is unaltered since it was sealed. It does not prove which engine produced it — an unkeyed hash is not a signature; provenance needs an engine signature or a trusted run record.

Model audit 2026-09-07 (“content hashes are not authentication”): changing a result and recomputing the digest verifies, as expected of an unkeyed SHA-256, so the wording “the run it says it is” overstated the check. The package’s identity is its content; its provenance is the engine identity it carries (build, data digest), which the desk package now keeps per answer and refuses to mix.

→ Where it is derived

Convention C1

Also: C1, floor to the cent, residual.

The payment is floored to the cent and the final payment absorbs the residual, so the schedule sums to the Purchase Price exactly. At 36 months payments 1–35 are $2,458.33 and the last is $2,458.45.

Decided at milestone M1 and amended after adversarial review on 2026-07-11: half-even rounding could push the accumulated schedule past \(P\) at a micro-strike and make the final payment negative. tiny_strike_schedule_never_goes_negative runs a $10 coin over 84 months.

[ \text{PMT} = \Big\lfloor \frac{P}{n} \Big\rfloor_{0.01}, \qquad p_n = P - (n - 1),\text{PMT} ]

→ Where it is derived

Convention C2

Also: C2, cumulative rounding, cumulative fee rounding.

The fee is rounded cumulatively: each posting is round(f × cumulative delivered) minus the previous rounded cumulative. Any single posting may wobble a cent; the lifetime fee per Agreement is exactly round(f × total delivered).

fees.rs::FeeState::split. The sum telescopes, so no intermediate rounding survives. At 36 months the postings alternate 122.92, 122.91, … and sum to $4,302.08, where naive per-posting rounding would give $4,302.20. fee_identity_exact_to_the_cent asserts the identity as an equality on Decimal.

[ \text{fee}_k = \text{round}(f \cdot \text{cum}k) - \text{round}(f \cdot \text{cum}{k-1}) ]

→ Where it is derived

Convention C3

Also: C3, IRR on quantized flows.

IRR is computed on the quantized flows: the Holder’s monthly net flow is built from cent-exact postings, converted to f64, and solved by a grid scan and 200 bisections. The engine matches the M0 fixtures within 0.01 points.

The fixtures were generated in exact rational arithmetic on unquantized flows, which is why the tolerance exists. Nominal is 12 times the monthly rate; effective is \((1+r)^{12} - 1\).

→ Where it is derived

Conviction walk

Also: conviction walks, conviction_walk, conviction_walks, walk, walks, the walk.

A stop produced by the lost-conviction rule (or the rational boundary): a walk is decided at or before a payment date and consumes it unpaid, so the walk is the missed payment. Settled like any stop.

Exit tag ConvictionWalk. Walks differ from hazard draws in timing: a draw at age \(t\) happens after payment \(t\) and misses \(t+1\); a walk at age \(t\) has payments_made \(= t - 1\) and misses \(t\) itself. A walk at the final payment date and a hazard draw after the penultimate payment can each cause the final payment to be missed.

→ Where it is derived

Cost in bps of deployed

Also: cost, bps of deployed, cost_bps_of_deployed, cost of carry.

Mean net premium and carry paid over mean capital deployed (the sum of purchase prices), in basis points: the hedge’s cost as a share of the money the Holder put into the paper.

HedgeResult::cost_bps_of_deployed. A running-cost figure a desk compares with the basis and with the paper’s spread: 300 bps of deployed on a book that spreads 800 bps to par leaves 500. Undiscounted on both sides.

→ Where it is derived

Cost in IRR points

Also: cost_irr_points, cost of the hedge in yield.

Unhedged median IRR minus hedged median IRR, in percentage points. Positive: the hedge cost yield; negative: it paid more than it cost on these seeds.

HedgeResult::cost_irr_points. The directional desk’s price of the floor: how many points of median yield the structure gives up to buy the p5 it achieves. Read with the floor achieved to see what each point bought.

[ \text{cost}{pp} = 100 \times \big(\text{median IRR}{unhedged} - \text{median IRR}_{hedged}\big) ]

→ Where it is derived

Coverage

Also: CoveragePoint, Coverage on the simulated path, coverage_by_cohort.

The two lines applied to the run’s path month by month: how many price-exposed Agreements sit below each line, and the dollars those positions carry. A stopped Agreement stays on the panel until the month its sale is booked.

exposure.rs::exposure, from tracks reconstructed off the ledger; which Agreements count at a month is engine.rs::price_exposed_at, the one lifecycle the hedge desk and the monthly mark read too (M04). Proceeds are priced at the month’s mark with haircut and sale cost, without the 18-day interpolation: coverage asks what a sale at this mark would do. At month 12 on the base path: 123 active, 123 below the schedule line, 117 below the capital line, capital at risk $4.54m, intrinsic shortfall $3.18m. Per cohort it reports mean months and share of Agreement-months below each line.

→ Where it is derived

Covered call

Also: covered-call overwrite, Benchmarks::covered_call, overwrite.

The legacy spot reference with 12-month calls written at 130% of spot at each roll. Calls start at each coin’s origination and roll annually while held. Premium uses the supplied surface and pricing rate, with no execution cost.

Cash settlement occurs at expiry; an option still open at the horizon retains its signed remaining-life model value. The reference buys one coin per Agreement and has its own capital and cost conventions. It is not the Research matched-contribution holding benchmark or an equal-budget ranking of the Agreement and market alternatives.

→ Where it is derived

Crash library

Also: crash presets, named crash.

One-click price paths shaped like named Bitcoin crashes — 2018, 2022, March 2020, May 2021, the FTX week, a fast crash at the vintage peak — as stylised anchors, not replays.

Each preset is a custom path through a few (month, price ratio) anchors that reproduce the episode’s depth and speed, then holds flat. They are stylisations for a stress conversation; the historical replay mode carries the actual monthly closes.

→ Where it is derived

Cross-book collar

Also: collar, holder of free coin.

A legacy partial Agreement-sleeve illustration: calls on separately held coin provide premium for puts on the Agreements. It does not report the complete combined coin book.

Call premium enters the Agreement-sleeve distribution; the external coin value and written-call liability do not. Call assignment is reported separately and is not charged to that distribution. Paired Research and explicit Coin sweep/monthly requests refuse this incomplete performance boundary; the Coin workspace does not offer it as a complete strategy. The Buyer’s promised coin cannot cover the Holder’s written call.

→ Where it is derived

Cumulative net cash

Also: cumulative_net_cash, net cash position, Cumulative, when is the money back.

The running sum of the Holder’s monthly net flow, one value per month. Its last entry is the run’s total net gain, $22,673.75 on the reference Agreement; it feeds the cash-recovery curve and the Monte Carlo cash fan.

On the base paced book it runs deeply negative while the 24 cohorts are being bought (median −$6.48M at month 12 across 1,000 runs) and ends at a median +$4.53M at month 84.

→ Where it is derived

Custom path

Also: Custom, anchor path, anchors, points.

A deterministic path through (month, ratio) anchors, log-linear between them and flat after the last. API only; no cockpit picker. It is how the worked stops and the exact-cents test state a price shape as data.

paths.rs::custom; the origin (0, 1.0) is implicit. Halfway between anchors at 0.40 and 0.80 the price is the geometric mean, $33,941 on a $60,000 start, not $36,000. Validation: at least one anchor, strictly increasing months after 0, positive finite ratios.

→ Where it is derived

Custom per-year shares

Also: CustomYearly, per-year view, custom timing curve, your per-year view, per-year bars, Late-loaded, Flat.

A timing view stated as the share of the original book that stops in each year of the term. Each year’s mass is spread over its stoppable ages and divided by the survival so far, so a flat path realizes the shares exactly.

DefaultScenario::CustomYearly { shares }, spec v1.4. One share per year, finite and non-negative, summing below 100% with a \(10^{-9}\) headroom; a year with no stoppable age (at 37 months, year four holds only the final date) must carry 0%. The cockpit seeds it with three unbranded chips: the program hump, flat through time, late-loaded stress.

[ h_t = \frac{m_t}{1 - \sum_{k<t} m_k} ]

→ Where it is derived

Customer

Also: Customers, funnel.

A person in the funnel before signing. Once an Agreement opens the person is Buyer 0. Not an engine word; listed because the vocabulary ruling names it.

Marc, 2026-09-02. A Customer gets a 60-minute window to accept a price; letting two such windows lapse locks the person out for seven days.

→ Where it is derived

D

Data digest

Also: X-Engine-Data, data_sha256, ENGINE_DATA_SHA256, series digest.

The SHA-256 of the price series compiled into the engine (data/btc_historical_monthly.csv, 174 months, February 2012 – July 2026), stamped by build.rs and sent as X-Engine-Data on every response and data_sha256 on health.

8846a81b803001d885b0cc3b830f26bfeba35405b91d1843c6376eeca5d8a1bf on the current tree — the audit’s own measurement. A data refresh changes the digest without a version bump, which is why it travels beside the build identity (model audit 2026-09-06, M07). It attests the bytes, not their provenance: vendor reconciliation, fixing and licence are the Model Card’s data section.

→ Where it is derived

Dealer call

Also: five-year call, 5-year call.

A modeled long call per Agreement for the chosen long tenor and strike. It is an illustrative dealer-style reference, not an executable dealer quote.

HedgeSpec::DealerCall prices the supplied terms on the model surface. Premium, execution, expiry settlement and open horizon value are separate. The model does not verify availability, credit terms, collateral or liquidity of a matching instrument.

→ Where it is derived

Decimal and f64

Also: Decimal, f64, cents, money.

Money is rust_decimal Decimal quantized to cents, half-to-even; boundaries and statistics (prices, rates, moneyness, hazards, IRR) are f64. A float becomes money in exactly one place, and never goes back on the ledger side.

money.rs::cents and cents_from_f64; the latter is called when a strike is fixed, a sale is recorded, coin equity at early completion is noted, and for the frontier’s reference strike. The repository rule: Decimal for money, f64 for boundaries and display, never f64 in a ledger posting.

→ Where it is derived

Delivered gross

Also: delivered_gross, Delivered, gross deliveries, Holder collections.

Every dollar that entered the Holder’s stream from an Agreement before the fee: scheduled payments after the first N, the early-completion payoff, the stop-sale delivery (proceeds minus refund). $87,025 on a completed base Agreement.

Per row on the drill-down; a regime-2 stop shows the same $87,025 as a completed row, because the waterfall delivered exactly the remaining schedule. Auditor check C5 re-derives it by outcome and re-sums it from the row’s own postings.

→ Where it is derived

Delta

Also: delta_usd_per_pct, Δ, existing-book delta.

Change in the Holder’s net gain per +1% in every price after the as-of month, existing book only. +$24,885 per 1% on the base configuration as of month 23: the Holder is long the coin where its Buyers are underwater.

The central difference of net gain under price factors \(1 \pm 0.05\), averaged over the seed ensemble, in dollars per 1%. Flat above the schedule line, where a stop delivers the schedule in full; zero on a book with no stops. As of month 48 it falls to +$1,509.

[ \Delta = \frac{1}{k}\sum_s \frac{G_s(1+b) - G_s(1-b)}{2 \cdot 100,b} ]

→ Where it is derived

Delta band

Also: DeltaBand, band_coins_per_agreement, band.

Rebalance::DeltaBand { band_coins_per_agreement }: reset the futures position only when the target has drifted from it by more than the band, in coins per Agreement. A band no drift can cross trades once, at signing, and never again.

Test, one cohort on a moving path: the monthly reset 53 trades and 3.39 coins of turnover, a huge band one trade and 3.32 coins; the hedged medians differ (16.02% against 16.84%) because a held position is not the melting one — the band’s cost is the path it holds.

→ Where it is derived

Delta in coins

Also: delta_coins, coins, delta hedge.

USD-value sensitivity expressed as the BTC position whose 1% spot move produces the same dollar change. It is distinct from Coin delta, dC/dlnS, which measures expected BTC-receipt sensitivity.

The risk desk’s USD bump-and-revalue delta is divided by 1% of the as-of BTC/USD mark. The resulting unit is a BTC position equivalent, not BTC held, deployed or returned. Read its valuation method and as-of month; do not substitute it for the Coin lifecycle delta.

[ \Delta_{\text{coins}} = \frac{\Delta}{0.01 \times S_{\text{as of}}} ]

→ Where it is derived

Delta series

Also: DeltaSeries, three deltas, proxy_delta_coins, greeks_delta_coins_quarterly.

Delta readings for the complete selected path: the embedded-ladder proxy, the Coin value sensitivity and optional quarterly Greeks from bump-and-revalue. The report names its path-selection rule and seed.

DollarDelta sizes from the USD ladder proxy; CoinDelta sizes from the shared lifecycle-aware BTC-receipt sensitivity used by the hedge. Coin delta includes performing and stopped-unsold Agreements, and price_exposed_agreements supplies that same population for per-Agreement display. A known stop may retain sensitivity after the term; cash already booked and converted has no remaining receipt sensitivity. Preserve both the realized-path seed and valuation seed. Optional quarterly Greeks use additional USD simulated valuations and remain a distinct measure.

→ Where it is derived

Deployed

Also: deployed_usd, Capital deployed, capital outstanding, Peak capital outstanding.

Gross outflow: the capital the Holder put into a vintage or a book, the sum of purchase prices. $9,619,863.62 on the historical early-September reference book with dispersed strikes; $14,400,000 on a flat path (240 × $60,000).

The denominator of the EL rate, the undiscounted multiple and cash recovery. Peak capital outstanding on the report view is the most negative point of cumulative net cash.

→ Where it is derived

Desk seeds

Also: seeds per structure, seeds, MAX_DESK_SEEDS.

How many seeded engine runs the fair value and the hedge overlay average (default 32, ceiling 256). Every seed is one full run of the book, once per structure; seed k is the config’s seed plus k, so the figure is reproducible.

Request field seeds on the fair-value and hedge endpoints; the cap is named in the 400 when exceeded. The unhedged distribution is identical across structures in one request because they share the seeds; the benchmarks share them too. More seeds narrow the estimate of the median, p5 and mean; the worst path is only the worst of the seeds run.

→ Where it is derived

Dollar book

Also: dollar seat, the dollar book.

The Agreement book evaluated in USD, including fixed receipts and price-sensitive stop outcomes. The relevant hedge follows its modeled dollar exposure.

A dollar-delta hedge and a coin-delta hedge answer different questions on the same underlying cash flows. Their cost and residual risks depend on the configuration; no fixed cost advantage, universal hedge direction or complete market neutrality is promised.

→ Where it is derived

Dollars lent against coin

Also: dollar lending, 7.65% on dollars, dollars lent.

A shelf row and a dollar asset: dollars earning 7.65% a year (the paper’s rate), read on the coin seat as the dollar multiple over where the coin ends — 1.48 coins on a flat median, 0.34 at the 5th, 33% of paths losing coins.

Table 19: 4.02 / 1.48 / 0.54 / 0.20 coins from −18% to +49% a year, 7.6% in dollars throughout. The engine holds the dollar row at its rate within half a point and asserts its coin median above the 4% basis row’s.

→ Where it is derived

Draw

Also: hazard draw, stop draw, draws, uniform draw.

A random stop: each month, after payments, every active Agreement at a reachable age draws a uniform from its own stream and stops if it falls below the hazard. A draw at age t misses payment t+1.

Step 4 of the monthly order. The draw is taken unconditionally before any price test, so a bumped price changes whether the draw matters and never the draw. Early completion is the same mechanism in step 3 against the propensity.

→ Where it is derived

Drawdown-scaled hazard

Also: drawdown multipliers, drawdown_hazard_multipliers, state multipliers, Drawdown-scaled hazard (tiered), ×0.5 in the money.

Each month the hazard is multiplied by a state read off the coin against the Buyer’s entry: above entry ×0.5, drawdown up to 30% ×1.0, 30–50% ×1.5, 50–70% ×2.0, deeper ×3.0, capped at 1. Off in the cockpit, on in the Model Card.

Input #23, engine.rs::drawdown_multiplier, from the drawdown memo’s mortgage double-trigger evidence: price pain coincident with a liquidity shock, never a cliff. A coin exactly at entry sits in the ×1.0 bucket, so a flat path reproduces the toggle-off run draw for draw. The ×0.5 in the money is what sets how often a winning Buyer stops, the least-evidenced number in the model.

[ h_t^{\text{eff}} = \min\bigl(1, h_t \cdot m(S_t / \text{strike})\bigr) ]

→ Where it is derived

Drift

Also: μ, mu_annual, drift μ %/yr, expected growth.

The continuous annual price-drift parameter μ. Under GBM, expected one-year price growth is exp(μ) − 1; median growth is exp(μ − volatility² / 2) − 1. At 0% drift and 43% volatility, expected price stays flat while median price declines about 8.83% annually.

A chosen market assumption, not a forecast. Setting both drift and volatility to zero produces constant GBM prices before shocks or bumps. Jump-diffusion includes its jump compensation; the simple GBM median formula does not describe a jump or regime-switching path. Under the risk-neutral measure the drift is replaced by the funding rate. The Buyer’s believed drift for the walk-away boundary is a separate input.

→ Where it is derived

Drift sweep

Also: Table 7b, coin seat sweep.

Re-run the Agreement book and selected hedges on matching seeds for several GBM price-growth assumptions, at the configured volatility and costs. Compare BTC cash-flow IRR, amounts and loss statistics.

coin.rs::drift_sweep accepts median annual price growth r and uses continuous drift mu = ln(1+r) + volatility²/2. The Coin Research sensitivity labels continuous drift separately from median price growth. Keep the captured seed, valuation seed, surface, shock/bump and costs fixed for a matched comparison. Outcomes are conditional; no fixed growth threshold applies to every configuration.

[ \mu = \ln(1 + r) + \tfrac{1}{2}\sigma^2 ]

→ Where it is derived

E

EAD

Also: exposure at default, exposure at the stop, Mean remaining schedule at the stop, ead_usd.

The mean remaining schedule at the stop across a vintage’s stops: the put’s strike at exercise. $43,563 on the historical early-September reference book; $75,325 for cohort 1, whose Buyers stopped early in the schedule.

EAD times the stop count is the vintage’s \(\sum R_t\), the denominator of LGD.

→ Where it is derived

Early completion

Also: early completions, completed early, settled, settlement, make-whole, MakeWholeDelivery, Settled.

The Buyer pays the remaining schedule in cash at once and takes the coin. Cash only; the coin is never sold to pay for it. The Holder receives the remaining schedule less the 5% fee, years early and undiscounted.

Available without a separate early-completion fee; the servicing fee still applies to the delivery. The Holder’s lifetime cash is the same as at completion ($82,673.75 at the base terms); scheduled cash arrives sooner. It also removes exposure to later stops and possible surplus proceeds, so its effect on portfolio returns depends on the scenario. In the engine it is a monthly draw with probability \(u_t = p \cdot \max(0, (S_t - R_t)/S_t)\), optionally gated by the take-profit threshold. The ledger kind MakeWholeDelivery and the exit tag settled are the engine’s older names for it.

→ Where it is derived

Early completion propensity

Also: settlement_propensity, Early completion %/mo, Early settlement %/mo, propensity, prepays.

Monthly chance that an in-the-money Buyer pays off the remaining schedule in cash and takes the coin, scaled by his equity in the coin: u_t = p × max(0, (S_t − R_t)/S_t). Default 2.5% a month; a Holder isolating it sets 0.

Input #12, spec §4.4, accepted 0 to 100%. After twelve payments with the coin at $100,000, \(u = 0.025 \times 0.292 = 0.73\)% a month. Nobody pays $70,800 in cash for a coin worth $60,000, so the propensity is zero there. A prior (Model Card §7). Compare zero propensity with the selected rate: early completion accelerates scheduled receipts but removes later stop exposure and possible surplus. The high early-completion scenario uses 5%.

[ u_t = p \cdot \max!\Bigl(0, \frac{S_t - R_t}{S_t}\Bigr) ]

→ Where it is derived

Economic hedge payoff

Also: payoff_mean_usd, hedge payoff.

Mean signed realized hedge settlements plus the signed value of derivatives still open at the horizon. Premium, basis and modeled costs are reported separately.

HedgeResult.payoff_mean_usd equals realized_settlement_mean_usd plus horizon_mark_mean_usd. A bought option can have no realized settlement and a positive horizon value; a written option can have a negative value that has not yet been paid. Those marks enter economic performance once and are excluded from realized-only cash measures. Economic payoff alone is not net profit.

→ Where it is derived

Effective IRR

Also: effective, effective annual rate, irr_effective_pa, eff..

The monthly IRR compounded into a true annual rate, (1 + r)^12 − 1: 13.965% on the reference Agreement. The figure the Monte Carlo, the heatmap, the backtest, the tornado and the solver all use.

The gap between the paper’s 17.80% effective implied financing rate and the Holder’s 13.97% on the same flat Agreement is BTC Now’s take: the first payment and the 5%.

[ \text{effective} = (1+r)^{12} - 1 ]

→ Where it is derived

EL

Also: expected loss, el_usd, EL $, Σ shortfall.

Σ shortfall in dollars over the vintage’s stops: $990,282 on the historical early-September reference book, equal to the simulate response’s total shortfall at the same seed. EL = PD × LGD × EAD × n holds by construction.

Realized against the schedule on one seeded path, so it is the put’s realized intrinsic value, not a market value; no surface enters it. 0.4208 × 0.2251 × 43,562.82 × 240 = 990,282.

[ \text{EL} = \text{PD} \times \text{LGD} \times \text{EAD} \times n ]

→ Where it is derived

EL rate

Also: el_rate, EL % of deployed, EL ÷ deployed.

EL divided by capital deployed, the sum of purchase prices: 10.3% on the historical early-September reference book ($990,282 on $9.62m).

The vintage rows divide by that vintage’s deployed capital; the book row by the whole book’s.

→ Where it is derived

Embedded call

Also: long call, the call, call at the Purchase Price, surplus leg.

The Holder’s long call struck at the Purchase Price, about 147% of entry, exercised only by a Buyer who stops with the coin worth more than that. It exists only since the ruled waterfall and is why the base-config vega is positive.

Its realized value is the surplus column of the credit table, $149k on the base book, all in vintages originated from month 10 on. Rare by construction under the ×0.5 in-the-money multiplier, but worth the whole gap between the coin and the Purchase Price when it fires.

→ Where it is derived

Embedded put

Also: short put, the put, put at the schedule.

The Holder’s short put on the coin struck at the remaining schedule, exercised only when the Buyer stops: the schedule line is its strike, the ladder’s notional its size, EL its realized intrinsic value, delta and gamma its sensitivities.

One of the plan’s four legs; its exercise is behavioral, which is why the frontier family sits beside the line. It sits at 50 to 85% moneyness and 6 to 24 months, the corner of the Bitcoin surface with the heaviest skew; the engine prints its expected loss, not its market value.

→ Where it is derived

Embedded put ladder

Also: put ladder, the ladder, embedded_put_ladder.

The paper’s short put as a strip of European puts, one per payment age: struck at the remaining schedule R_t, expiring at the missed payment date t + 1, each weighted by the unconditional probability that the Buyer stops there.

surface::embedded_put_ladder(config, surface, r), at cohort-1 terms. The Holder is short a put on every stop date: if the coin is worth less than the remaining schedule when the Buyer stops, the stop sale falls short by the difference, which is exactly a put’s payoff. Legs run from age 1 to term − 1; each is priced on the surface at its own strike and tenor, and its weight is survival × hazard from the config’s default scenario, price-blind. The ladder’s value is Σ weight × put; the placement exhibit draws it on the surface. The perpetual delta hedge shorts the delta of this ladder, conditional on survival to date, as its proxy for the book’s delta.

[ L(\sigma) = \sum_{t=1}^{T-1} w_t ; P\big(S_0,, R_t,, \tfrac{t+1}{12},, \sigma_t,, r\big), \qquad w_t = S(t-1), h_t ]

→ Where it is derived

Endpoint

Also: endpoints, route, routes, the API.

One of the server’s nine routes: GET /health, six POSTs under /api/forwardflow (simulate, montecarlo, solve_price, heatmap, backtest, risk), GET history, and a WebSocket for chunked Monte Carlo. Stateless: a configuration in, results out.

An Axum server on port 8080 over the Rust crate. Money travels as strings, ratios as numbers. A well-formed request the engine refuses is a 400 naming the input; a malformed body is a 422; a missing content type 415. Heavy routes share three permits.

→ Where it is derived

Engine version headers

Also: X-Engine-Spec, X-Engine-Version, X-Engine-Build, X-Engine-Data, version headers, build identity, data digest.

Every response, open or keyed, success or error, carries X-Engine-Spec: v1.14 (the spec implemented), X-Engine-Version: <crate version> (from backend/Cargo.toml), X-Engine-Build: <crate version>+<spec>+<sha> (0.5.0+v1.14+1a2b3c4d5e6f, the build identity) and X-Engine-Data: <sha256> (the compiled-in price series’ digest). A run record takes them from the answer that carried its result.

Two engines at the same spec can differ by a fix, which is why the crate version travels separately from the spec — and two builds at the same version can differ by a commit or a data refresh, which is why the source revision and the series’ SHA-256 travel too (model audit 2026-09-06, M07). backend/build.rs stamps both at build time: the revision from GIT_SHA (the deploy workflow passes the commit), else git rev-parse on the build host, else unknown; the digest from the CSV the engine embeds, so a data refresh changes the header without a version bump.

→ Where it is derived

Entry close

Also: entry_close, Entry close, actual close.

The real Bitcoin close of the vintage’s origination month, a context label. The replay itself is rebased so month 0 equals the configured start price, which keeps dollar figures comparable across vintages.

$4.90 for February 2012, $35,026.90 for June 2021. The backtest chart draws it as a dashed line on a log scale, the cycle context behind each vintage’s IRR.

→ Where it is derived

Execution cost

Also: execution cost, bps of premium, exec_cost_bps, slippage.

Basis points of option premium charged on every option leg at execution (default 50 bps), bought or written, in both directions. For the variance swap it is bps of the vega notional; perpetuals carry none, and a futures leg carries none either — its trades are charged by its own futures_cost_bps (bps of the notional of every trade, the turnover’s terms at the month’s spot, default 0; model audit 2026-09-06, M10), reported as futures_trading_cost_mean_usd beside the turnover.

Request field exec_cost_bps, 0–1000. It is the bid-ask and slippage of dealing, paid on the gross premium: a put spread pays it on both legs, so the spread is not free of it because the premiums net. The benchmarks’ covered-call write charges none, so the covered call is the frictionless comparison.

→ Where it is derived

Exit month

Also: exit_month, the month the Agreement left.

The month an Agreement left the book. For a stop it is the missed payment date, not the sale or posting date; for completion or early completion, the payment date of the payoff.

outputs.rs::agreement_table reports it as exit_month, null while open. The stop’s cash posts one month later at the default lag; reconciling a row against the postings needs both dates.

→ Where it is derived

Exit split

Also: exit_split, Exit split, outcomes, Agreement outcomes, Outcome.

How every Agreement ended: completed, completed early, stop, stop under rational mode, conviction walk, rational boundary, open. The four stop buckets are identical in cash and counted apart to separate the prior from the rules.

ExitSplit, one bucket per engine.rs::ExitTag plus open. The historical early-September reference book at seed 42 reports 84 completed, 55 completed early and 101 stops. The backtest sums the stop buckets into one non_performance column. Two counters travel with it: suppressed defaults and coin taken at early completion.

→ Where it is derived

Expected net

Also: expected_net, Expected net $, full performance.

What a fully performing Agreement would deliver net of fee: (Purchase Price − first N payments) × (1 − fee), cent-rounded. $82,673.75 at the base terms. The benchmark each drill-down row is judged against.

Auditor check C2. A completed row lands within two cents of it (convention C2’s wobble); a stopped row’s gap to it is the schedule the Holder did not collect.

[ \text{expected net} = \text{cents}\big((P - \textstyle\sum_{k \le N} p_k),(1 - f)\big) ]

→ Where it is derived

Expected shortfall

Also: ES3, ES5, es3, es5, CVaR, tail mean.

The mean of the worst tail, not where the tail starts: ES3 averages the worst ⌈0.03 n⌉ runs, ES5 the worst ⌈0.05 n⌉. A fat left tail drags ES well below p3. At the base cockpit configuration ES3 is 9.03% and ES5 9.46%.

forwardflow_api.rs::summarize; with 1,000 runs ES3 averages the worst 30. It is Basel’s post-VaR measure; the outcome strip draws it as a red diamond inside the p3 zone. The risk desk’s word “shortfall” is a different quantity, the stop’s schedule gap.

[ \mathrm{ES}q = \frac{1}{k}\sum{i<k} \text{sorted}[i], \qquad k = \max\big(1, \lceil q, n \rceil\big) ]

→ Where it is derived

Exposure ladder

Also: ladder, Ladder, put ladder, Ladder month, ladder_month.

The book at one calendar month binned by the embedded put’s moneyness (sale proceeds ÷ remaining schedule) and tenor (months remaining), each cell with Agreement count, notional and capital at risk. What a desk maps onto listed strikes.

ladder_month left unset is the month of peak capital at risk, 23 on the base path, where 84 of 203 active Agreements sit in the 0.50–0.70 × > 36 months cell. That corner of the surface carries the heaviest put skew and the thinnest listed liquidity; the ladder makes the mapping possible and does not price it.

→ Where it is derived

F

Fee timeline

Also: btcnow_fee_monthly, revenue by year, How the money arrives, revenue timeline.

BTC Now’s take month by month: the ledger’s fee postings per month plus each Agreement’s paper spread at its origination month. Sums to total take plus spread. When paper stops paying, the fee stream on it stops too.

ledger.rs::Ledger::btcnow_monthly_fees; the cockpit’s “How the money arrives” exhibit charts it by year. Auditor check A7 re-derives it within a cent per month.

→ Where it is derived

FICO preset

Also: FICO presets, 700+, 600, 500, 400, band.

One-click loads of the baseline curve at a band’s lifetime target: 700 and above 15%, 600 to 699 35%, 500 to 599 55%, below 500 70%. They change nothing but the target.

defaults.rs::DefaultScenario::fico_preset, lib.ts::FICO_PRESETS, input #8. The program’s 40% stance sits between the 600 and 500 bands. There is no credit-score floor in the program (foreclosed 2026-08-22); the presets are a Holder’s way of stating a view.

→ Where it is derived

First payment to BTC Now

Also: origination payment, origination payments, first N payments, origination_payments, First N payments → BTC Now, N.

The first N scheduled payments (N = 1 in the program) go whole to BTC Now and never enter the Holder’s stream, so they carry no servicing fee. At the base terms $1,475, 2.46% of the Holder’s capital.

Input #3, posted as OriginationFee. Marc, 2026-08-31: BTC Now is always Holder 0 and the first payment flows to it. The Holder’s stream begins at payment N+1; the payments are still in the Buyer’s paid-in total. Setting N to 0 recovers the pre-program case the M0 fixtures and the memo-config badge use. The identity n_payments_identity says Holder cash at N differs from N = 0 by \(\sum_{k \le N} p_k (1-f)\).

→ Where it is derived

Flat annual

Also: FlatAnnual, Annualized default %/yr, Flat %/yr, constant annual stop rate.

A constant annual stop rate converted to the monthly hazard 1 − (1 − r)^(1/12), the same at every reachable age. Rate semantics, not a lifetime target: 10% a year gives 0.8742% a month and 40.4% over a 60-month term.

DefaultScenario::FlatAnnual { annual_rate }, API and the backtest page only. The backtest calls it “the framework”.

[ h = 1 - (1 - r_{\text{annual}})^{1/12} ]

→ Where it is derived

Flat surface

Also: Flat 43%, flat preset, flat vol.

The preset surface with one vol at every tenor and strike: 43%/yr, the cockpit’s base bridge volatility, no skew. Under it every option is plain Black-Scholes at 43%.

VolSurface::flat(0.43) on tenors 1, 3, 6, 12, 24 months and moneyness 0.50 to 1.30. It is the control: run the placement on the flat surface and on the stylised skew and the difference is what the skew alone does to the ladder.

→ Where it is derived

Flat-path markup

Also: markup, flat_path_markup, markup per Agreement.

The completing Agreement’s net gain to the Holder on a flat price path, per Agreement at cohort-1 terms: (the schedule’s total − the first N payments) × (1 − fee) − the purchase price, cents-exact.

surface::flat_path_markup(config). It is what the Holder earns if nobody stops and the price never moves — the paper’s gross margin before behavior. The paper’s implied vol is the flat vol at which this markup exactly pays for the weighted ladder.

→ Where it is derived

FlowFee posting

Also: flow_fees, Servicing fee → BTC Now, servicing take.

Buyer or Market → BTC Now with every delivery: the flat 5% on the delivered dollar, whether a scheduled payment, an early-completion payoff or a stop-sale delivery. $655,556.23 on the historical early-September reference book.

Computed as the difference of two rounded cumulatives (convention C2), so any single posting may wobble a cent while the lifetime fee per Agreement is exact. Summed as flow_fees.

→ Where it is derived

Free coin

Also: free coins, free_coins, the Holder’s other book, cross-book collar.

BTC held separately from the Agreement book. The legacy cross-book collar uses call premium on those external coins to support puts on the Agreements; it does not report complete combined-book performance.

The legacy CrossBookCollar Agreement-sleeve distribution includes call premium and Agreement put flows, but excludes the external coins’ value and written-call liability. Call assignment is shown separately on a leg and is not charged to that sleeve’s distribution. Paired Research and explicit Coin sweep/monthly requests reject this incomplete combined-book strategy. The Buyer’s promised BTC cannot cover a Holder’s written call.

→ Where it is derived

Frontier family

Also: frontier_mus, frontiers, Walk-away frontier family, FrontierFamily, Believed drift 1 … k.

The frontier drawn for several believed drifts on the same axes as the two lines: by default μ = 0, 10%, 25% and 50% a year, 1 to 8 allowed. The family brackets the book; each curve is the walk-away price of one belief.

The distance between a curve and the capital line at a month is the price fall that has to happen before that Buyer’s stop becomes the Holder’s loss. The zero-drift Buyer walks above the capital line from the first month; the 25% Buyer sits below it through payment 26 and above it after; the 50% Buyer walks almost nowhere. The other lattice parameters come from frontier_params, else the config’s rational_boundary, else the defaults.

→ Where it is derived

Funding rate

Also: funding_rate, funding rate %/yr, risk-free rate.

The desk’s dollar rate, annual, continuously compounded (default 4.5%/yr): the rate the placement’s puts discount at, and the rate the risk-neutral paths drift at and their flows discount at.

Request field funding_rate on the placement and fair-value endpoints. It is not the perpetual’s funding rate — that lives in the perp delta hedge spec — and it does not enter the hedge overlay’s option prices, which are at zero rate by the surface’s quoting convention. Under the risk-neutral measure the coin’s expected growth is this rate, whatever the config’s drift says.

→ Where it is derived

G

Gamma

Also: gamma_usd_per_pct2, Γ, curvature.

The second difference of net gain per (1%)²: the change in delta per 1% move. −$175.6 on the base configuration: the loss accelerates into a drawdown, the convexity of a short put.

Computed from the same three runs as delta, averaged over the ensemble. As of month 48 it falls to −59.

[ \Gamma = \frac{1}{k}\sum_s \frac{G_s(1+b) - 2,G_s(1) + G_s(1-b)}{(100,b)^2} ]

→ Where it is derived

GBM

Also: geometric Brownian motion, Gbm, Brownian motion.

Geometric Brownian motion at monthly steps: the price model a desk brings with its own drift and vol. Log return per month = (μ − σ²/2)/12 + σ√(1/12)·z, so E[S_t] = S₀·e^{μt}. Free at the far end, unlike the bridge.

PathMode::Gbm { mu_annual, vol_annual } (Phase 2). The −σ²/2 is the Itô correction that makes μ the expected growth rate of the price, not of its log. vol_annual = 0 is the deterministic exponential ramp at μ. The diffusion draws are taken from the run’s stream first, one per month, so a jump-diffusion at λ = 0 or a regime switch at equal vols is this path exactly on the same seed. The fair value runs the engine under GBM at the funding rate.

[ \ln \frac{S_{t+1}}{S_t} = \frac{\mu - \sigma^2/2}{12} + \sigma\sqrt{\tfrac{1}{12}}, z_t, \qquad z_t \sim N(0,1) ]

→ Where it is derived

Greeks

Also: the Greeks, Greeks by bump-and-revalue, sensitivities.

Sensitivities of the Holder’s net cash gain to a bump in the future path: delta, gamma, vega, theta, and delta and vega of the IRR. The engine is re-run bumped and finite differences are taken over a seed ensemble.

exposure.rs::greeks. Seven runs per seed: base, price up and down, commitment up and down, vol up and down, for 16 seeds by default. Signs to expect on a stopping book: positive delta, negative gamma, positive theta; vega negative where the stops are underwater and positive where the surplus dominates. The base IRR in the Greeks (15.86%) is an ensemble mean, not the seed-42 run’s 14.21%.

→ Where it is derived

H

Haircut

Also: static haircut, liquidation haircut, Haircut % (sale below spot), sale below spot.

An extra discount on the stop sale below the path price, stored in log units: the sale executes at spot × e^(−h). Default 0 (Marc, 2026-07-12): a one-coin sale has no market impact. A skeptic’s dial.

Input #15. The cockpit shows a percent and stores \(h = -\ln(1 - \text{pct})\); the tornado’s “Stop-sale haircut 50%” is \(h = 0.693\). Until Phase 4 adds a market-impact model, the haircut is how a Holder prices synchronized stops in a crash.

→ Where it is derived

Hazard

Also: monthly hazard, h_t, hazard_monthly, stop hazard, default hazard.

The probability that an Agreement which has just made payment t stops before payment t+1. A vector by payment age, zero at the final payment date, built once per run from the stop scenario and drawn against each month.

defaults.rs::DefaultScenario::monthly_hazard; the simulate response carries it as hazard_monthly. At the base terms and the 40% prior: 0.977% a month at ages 1–3, 1.953% at 4–15, 1.172% at 16–24, 0.684% at 25–36, 0.244% at 37–59. The drawdown multipliers scale it by state; rational mode moves where its stops land.

[ h_t = \min(1, K, w_t), \qquad t = 1, \dots, n-1, \qquad h_n = 0 ]

→ Where it is derived

health

Also: GET /health, OK, liveness.

Liveness: GET /health answers the plain text OK with status 200. The launcher polls it once a second for up to thirty seconds after starting the engine; the cockpit does not call it.

A deploy check should. The engine listens on port 8080 and the web app on 3000.

→ Where it is derived

Health route

Also: /api/forwardflow/health, health, liveness.

GET /api/forwardflow/health, open in both modes: {"status":"ok","engine_spec":"v1.10","version":"<crate version>","mode":"open"|"keyed"}. The plain GET /health answers OK for a deploy check.

The one route that tells a caller which mode the engine is in before any credential is sent.

→ Where it is derived

heatmap

Also: POST /api/forwardflow/heatmap, break-even heatmap, Where it breaks, GridSpec, PriceDefault, VolConviction.

A sensitivity grid, every cell a full run of the current book at the configuration’s seed with two assumptions swapped, up to 900 cells: price × lifetime stop share, or volatility × conviction depth. A failed cell is a hole, never a 400.

forwardflow_api.rs::ff_heatmap, cells in parallel. The cockpit’s price axis runs 0.25 to 2.0 times the start price against priors from 80% to 0%; the vol axis 10% to 100% against depths 10% to 80%. Blue cells are positive, red negative; the bold frontier is IRR = 0. Click a cell to load that scenario. Chip S11.

→ Where it is derived

Hedge coverage

Also: coverage, coins per Agreement, density, share of the proxy delta.

The option notional per one-BTC Agreement, or a stated share of a modeled USD or Coin delta. Coverage sizes a trade; it does not guarantee a return or complete capital protection.

Fixed coverage scales option premium, payoff and execution cost linearly. A coverage of 1 means one underlying BTC of option notional per Agreement, subject to its strike, tenor and roll rules. Delta-based coverage uses the chosen sensitivity at inception or rebalance. Generic sizing supports values up to 2 where permitted by the selected field. Contract notional, funded BTC capital and price sensitivity are different quantities; a non-par purchase changes capital without changing the Agreement’s one-BTC notional.

→ Where it is derived

Hedge desk

Also: /forwardflow/hedge, the Hedge desk, derivatives desk.

The derivatives desk’s page at /forwardflow/hedge (FUND_DESK_PLAN Phases 2–3): the embedded put ladder on a vol surface, the risk-neutral fair value, the hedge overlay on the paper’s own seeded paths, and the benchmarks.

Manual Run. It reads the same engine the workbench runs (forwardflow::surface and forwardflow::hedge) and adds nothing to the ledger: the surface, the fair value and every hedge are the Holder’s own view laid over the paper. Its headline is the paper’s implied vol beside the market’s and the hedged excess over basis. Exports are stamped with the config hash, the seed and the engine spec version.

→ Where it is derived

Hedge leg

Also: leg, HedgeLeg, paid, received, both sides of every leg.

One component of a hedge, averaged across the sample. Its debit and credit fields include premium, costs, settlements and signed open derivative values; a marked value is not cash paid or received.

HedgeLeg reports paid_mean_usd and received_mean_usd as legacy economic debit/credit fields. A leg labelled ‘(open at the horizon, marked)’ is an unrealized asset or liability. Read gross leg amounts to understand a spread or collar, and use the explicit realized-settlement and horizon-mark totals to distinguish cash from terminal valuation.

→ Where it is derived

Hedge overlay

Also: overlay, hedge_overlay, /api/forwardflow/hedge, the overlay.

Hedge cash flows laid over the SAME seeded paths the paper runs on: per seed the paper runs, the structure’s monthly dollar flows are built on that run’s path and book, added to the Holder’s flows, and the IRR of the combined flow is taken.

hedge::hedge_overlay(config, surface, spec, exec_cost_bps, seeds, pricing) behind POST /api/forwardflow/hedge (up to 8 structures per request). Nothing touches the ledger: the hedge is the Holder’s own act, in f64 dollars, quantized to cents only where it joins the paper’s flows. Every option is priced off the surface at its inception spot, strike and CONTRACTUAL tenor, at the option pricing’s rate; an option still open at the run’s last month is marked there at its remaining-life model value on the surface at that month’s spot, on a leg labelled “(open at the horizon, marked)” — never settled at intrinsic on a shortened life. The result is the unhedged and hedged distributions, the cost and floor figures, both sides of every leg, and the conventions in notes.

→ Where it is derived

Hedge preset

Also: presets, preset shelf, HedgePreset, presets from the engine.

The shelf of fifteen named structures the engine ships with every hedge response — the risk paper’s menu, seat-prefixed: four for the dollar seat, seven for the coin seat, the pair for both, and three other instruments.

hedge::presets(). A preset is a starting point, not a recommendation — every parameter is editable once chosen, and since v1.9 each is a list of legs. BTC Now’s own posture is labelled as such on the shelf and is one preset among several.

→ Where it is derived

Hedge ratio

Also: ratio, share of the coin delta.

The fraction of modeled coin delta covered by CoinDeltaFutures, from 0 to 2; 1 means the full modeled delta. This is a sizing assumption, not a universally preferred setting.

Increasing coverage changes exposure, basis, execution and margin requirements. The ratio that improves one sampled downside measure can worsen another, and depends on the market process, Buyer behavior and funding assumptions. Evaluate matching paths and distinct evaluation seeds; a sampled minimum or p5 is not a guaranteed floor.

→ Where it is derived

Hedge spec

Also: structure, HedgeSpec, hedge structure, instrument.

One hedge structure and its parameters, externally tagged on the wire: PutLadder, PutSpread, RollingPuts, PerpDeltaHedge, VarianceSwap or CrossBookCollar. Each is validated by named input before it runs.

hedge::HedgeSpec. Static puts on the paper (one put per Agreement × coverage, struck at a share of entry, held to expiry); a put spread (long the higher strike, short the lower); rolling short-dated puts struck at a share of the spot at each roll; short perpetuals reset to coverage × the proxy delta at every rebalance, with funding and margin carry; long variance at the surface’s ATM vol, rolled through the horizon; and the cross-book collar, calls on free coin paying for puts on the paper.

→ Where it is derived

Hedge strike

Also: strike, % of entry, strike_pct_of_entry, strike_pct_of_spot, long_strike_pct, short_strike_pct, call_strike_pct_of_spot, put_strike_pct_of_entry.

An option leg’s strike as a fraction of a reference price: of each Agreement’s entry price for the static puts (0.70 = the 70% floor), of the spot at each roll for rolling puts and written calls (0.85, 1.30). 0.01–3.00; calls to 5.00.

The entry price is the price the Agreement struck at, so a put at 70% of entry protects the Holder below the point where the stop sale starts to fall short of the schedule’s early ages. The put spread’s long strike must exceed its short. The surface is read at the leg’s own K/S, so a lower strike reads the skew’s put wing.

→ Where it is derived

Hedge tenor

Also: tenor (months), tenor_months, tenor of each swap, tenor of each put.

An instrument’s time to expiry in months, 1–120, always priced whole. Static structures hold to expiry — one still open at the horizon is marked there at its remaining life; rolling puts, the variance swap and the collar’s calls are re-struck every tenor while the position is live.

The surface is read at this tenor, so a 3-month rolling put pays the short-dated vol twelve times in three years while a 12-month ladder pays the 12-month vol once. On the ladder table, the tenor column is the leg’s expiry: the missed payment date t + 1.

→ Where it is derived

Hedge-mark bucket

Also: hedge mark, futures_mark, hedge settlement bucket, basis bucket.

Monthly realized futures/perpetual P&L: the held position times the spot move. Futures settle monthly, so this is cash. Open option/swap value is reported separately.

The attribution’s hedge-settlement bucket carries premium and execution cost. Option-value attribution combines the change in signed option/swap value with the realized settlements replacing that value. Basis carries futures basis, funding and margin carry. These attribution buckets differ from the raw cash component named hedge_settlement; use the native BTC ledger when reconciling realized cash. The horizon derivative mark belongs to economic outcome once and is not cash received.

→ Where it is derived

Hedged distribution

Also: hedged, Hedged — paper plus the structure, Dist, distribution.

The Holder’s outcome over the seeds with the structure’s flows added to the paper’s: median, mean, p5 and p95 effective annual IRR and the share below zero over the seeds with an IRR; the median and p5 multiple and the cash-loss share over every seed; and the seeds with, and without, an IRR.

hedge::Dist on the hedged side of a HedgeResult. Compare currency, sample count, unavailable/root diagnostics and the unhedged distribution on the same seeds. A p5 is a sampled percentile. USD multiples put negative hedge flows in gross outflows; legacy Coin multiples use a paper-purchase denominator and signed hedge numerator. Neither is a complete wallet return.

→ Where it is derived

Hedged excess over basis

Also: excess over basis, hedged_excess_over_basis_pp, the market-neutral desk’s number.

Hedged median USD IRR minus the requested annual cash-and-carry basis rate, in percentage points. It is a USD reference comparison, not BTC return above holding.

HedgeResult.hedged_excess_over_basis_pp is populated for structures classified as market-neutral. The comparison basis_rate is separate from the futures leg’s modeled locked/after cost schedule. A negative value means the modeled USD return did not beat this reference on the sampled paths. The reference does not establish equal capital, equal funding needs or absence of counterparty and execution risk.

[ \text{excess}{pp} = 100 \times \big(\text{median IRR}{hedged} - r_{basis}\big) ]

→ Where it is derived

Hedged p5

Also: floor, floor_p5_irr, p5 floor, the floor.

The selected reporting unit’s fifth-percentile annual cash-flow IRR, conditional on paths with a valid IRR. It is a sampled downside statistic, not a guaranteed minimum.

The legacy HedgeResult.floor_p5_irr field is always USD. A Coin view uses hedged_coin.p5_irr and must select adverse paths using a Coin metric. Report how many sample paths have valid IRRs; a path can lie below p5 and further samples can move it. A put strike does not guarantee the combined Agreement-and-hedge return.

→ Where it is derived

Histogram

Also: irr_histogram, IRR histogram, bins.

The distribution of effective IRR over the runs in 50 equal-width bins from the worst to the best, reported as (left edge, count) pairs. Counts sum to the runs that had an IRR.

The bin width is floored at \(10^{-12}\) so a degenerate distribution does not divide by zero. The cockpit’s outcome panel draws it above the percentile strip.

→ Where it is derived

Historical replay

Also: replay, HistoricalReplay, Start month, start_index.

Bitcoin’s actual monthly closes from a chosen start month, rescaled so month 0 equals the start price: history’s shape at your level. Seed-free; it carries whatever drift history had, so replay figures are descriptive, not probabilistic.

paths.rs::replay, \(P_k = P_0 \cdot C_{s+k}/C_s\). The run needs \(H + 1\) bars from the start index; otherwise the API returns 400 InsufficientHistory. With 174 bars a single 60-month vintage has 113 feasible starts and the paced book 90. The cockpit’s mode switch lands on index 21, November 2013; chip S9 replays the 2013 top.

→ Where it is derived

history

Also: GET /api/forwardflow/history, embedded series, 174 bars, historical closes.

The embedded monthly Bitcoin bars compiled into the engine: 174 months and closes from February 2012 ($4.90) to July 2026 ($62,875.50). The cockpit uses it to label replay start months and grey out those without enough history.

paths.rs::historical_closes and historical_months, parsed once from backend/data/btc_historical_monthly.csv via include_str!; no data files at runtime. Index 59 is January 2017, index 149 July 2024.

→ Where it is derived

Hold strikes

Also: hold_strikes, strikes held, strikes floating.

A bump option: true strikes every cohort off the path as it stood before the bump, so only the coin moves; false lets cohorts in bumped months strike at the bumped prices. The Greeks get ‘held’ by stopping origination instead.

The intramonth dispersion spread is derived from the strike path when strikes are held, so a bump does not change the spread either. exposure.rs::greeks runs every bump with hold_strikes: false and freezes the existing book with origination_stop_month; the commitment delta is the same bump on the full pacing.

→ Where it is derived

Holder

Also: Holders, receiving side, Owner, owner, Purchaser, forward-flow buyer.

The receiving side of an Agreement: the party that bought the paper and collects the schedule. Holder 0 is always BTC Now; the receiving side changes hands by Sale. The ledger calls the Holder Owner.

The Holder pays the purchase price of the paper (par, $60,000 on the base coin) and receives 95% of every dollar delivered after the first payment. It never receives the coin: a stop delivers dollars, and completion delivers the coin to the Buyer. Every output the engine reports is the Holder’s. Older documents say “Purchaser”, “the fund” or “forward-flow buyer”; all three now mean the Holder.

→ Where it is derived

Holder 0

Also: Holder zero, BTC Now as Holder 0.

BTC Now, always. Every Agreement opens with BTC Now on the receiving side; the first payment flows to it whole, and it sells the receiving side to a Holder by a Primary Sale.

Marc, 2026-08-31: “BTC Now always first owner”. In the engine the Holder pays BTC Now at origination and payment 1 arrives a month later, which collapses the Primary Sale onto the origination date; that is the conservative reading for the Holder, who pays before the first payment it does not receive. Whether BTC Now sits in the ledger as Holder 0 with the first payment as its own is an open term-sheet question (limits, item 3).

→ Where it is derived

Horizon

Also: H, simulated window, 84 months.

The last simulated month: (cohorts that originate − 1) + term + the settlement tail, ⌊lag/30.4375⌋ + 1 months (one at the program’s 18 days) — or the market horizon when the configuration sets one. One vintage at 60 months runs to month 61; the base paced book of 24 cohorts to month 84, so the path has 85 marks.

engine.rs::SimConfig::horizon. The tail (engine.rs::settlement_tail_months; spec v1.5 change 4 for the first month, widened 2026-09-05 for lags past a month) lets a stop at the last stoppable payment date price and settle inside the ledger rather than be clamped; it also costs the backtest a vintage per tail month, since a vintage is seasoned only when term + tail months of history follow it. market_horizon_months, when set, pins the path’s last month so a pacing change cannot move the bridge’s endpoint date.

[ H = \max\big(H_{\text{market}},\ (\text{cohorts} - 1) + \text{term} + \lfloor \text{lag}/30.4375 \rfloor + 1\big) ]

→ Where it is derived

I

Implied financing rate

Also: paper rate, implied rate, financing rate, implied monthly rate.

The monthly rate at which a level payment of PMT over the term has present value equal to the strike: 1.375% a month at the base terms, 16.50% nominal, 17.80% effective. Display and boundary only; no ledger amount depends on it.

contract.rs::ContractTerms::implied_monthly_rate solves the ordinary annuity identity by bisection on \(i \in [-0.5, 1.0]\), with the unquantized PMT. A multiple of 1.0 gives zero and a multiple below 1.0 a negative rate (0.90× at 60 months: about −4.07% nominal). It is not the Holder’s return: the Holder pays par, misses the first payment and gives up 5%, so the flat run prints 13.97% effective against the paper’s 17.80%.

[ \text{PMT} = \text{strike} \cdot \frac{i,(1+i)^n}{(1+i)^n - 1} ]

→ Where it is derived

Implied vol

Also: implied volatility, IV, vol.

The annual volatility that, put into Black-Scholes, reproduces an option’s market price — the number a surface stores at each tenor and strike, as an annual fraction (0.43 = 43%/yr).

Implied vol is the market’s price of an option restated in volatility units, so options across strikes and tenors compare on one scale. The surface stores it; the ladder, the hedge legs and the benchmarks’ calls each read the vol at their own strike and tenor. It is distinct from realized vol, which is measured from a path after the fact, and from the paper’s implied vol, which is the flat vol the paper’s markup pays for.

→ Where it is derived

In-the-money stop

Also: stop in the money, winning Buyer stops.

A stop while the coin is worth more than the Purchase Price: the Holder is paid the schedule, the Buyer refunded in full, and the surplus stays with the Holder. How often this happens is the least-evidenced number in the model.

The engine produces such stops at half the baseline hazard with the multipliers on and at the full hazard with them off; neither rate has been observed. The rational robot never stops with a surplus. On Bitcoin’s history a handful per vintage moved the single-vintage replay median from 38.2% to 47.9% between two runs of the same morning. Model Card §6 asks that this sentence be attached to every replay figure.

→ Where it is derived

Inception

Also: Inception, AtOrigination, AtMonth, inception month, when the hedge is put on.

When a static hedge is put on: at each origination (every cohort hedges at its own month and spot, off each Agreement’s entry price), or the book at a month (everything on the books then hedges at once; later Agreements stay unhedged).

hedge::Inception. The put ladder, the put spread and the collar’s puts take an inception; the rolling puts, the perp hedge and the variance swap are rolled through the horizon and have none. An AtMonth past the horizon is rejected by name.

→ Where it is derived

include_postings

Also: include_agreements, raw postings flag.

Simulate request flags. include_postings (default false) attaches the raw double-entry ledger, which the audit needs; include_agreements (default true) attaches the per-Agreement table, about 106 KB of the base book’s 112 KB body.

Side-runs that only read scalars pass include_agreements: false and read agreement_count instead; the tornado, the heatmap and the solver do. A reproduction posts the stamped configuration with postings on and runs the tie-out.

→ Where it is derived

Initial margin

Also: initial margin, % of notional, initial_margin_pct, margin carry.

The margin the short perpetual posts as a fraction of its notional, 0–1. Its cost is the carry of that capital at the perp’s funding rate, charged monthly and reported as the leg margin carry.

Margin is not lost — it is capital tied up. The overlay charges only its carry, not the margin itself, so the hedged flows show the cost of holding the capital idle rather than the capital moving in and out. No forced close is modelled: the position is held whatever the mark.

→ Where it is derived

Intramonth proxy

Also: intramonth_call, intramonth call, 18-day sigma, 18-day convention.

The call met inside the month, on the paper’s 18-day convention: the month’s mark re-read on its log move scaled by √(18/30.4375) ≈ 0.769, plus the basis, floored at zero. A proxy for a typical 18-day move, not the path’s own worst point.

The engine is monthly and cannot see the month’s path; the month-end mark is the call actually settled. On the base configuration’s median seed the peak call is $349,793 against a proxy of $261,053 (test).

[ \text{intramonth}_m = \max\Big(0,, -\Big(\text{mark}_m,\frac{e^{kr}-1}{e^{r}-1} + \text{basis}_m\Big)\Big), \qquad k = \sqrt{18/30.4375} ]

→ Where it is derived

Intramonth strike dispersion

Also: dispersion, strike dispersion, intramonth_strike_dispersion, dispersed strikes.

Each Agreement draws its own entry price log-normally around its month’s mark, mean-preserving, with a spread of the monthly volatility of the twelve months before its cohort month over √2 — the path mode’s stated volatility with fewer than three returns behind it; zero on a flat path. On in the cockpit since 2026-07-13, off in the engine default.

Input #20 (engine.rs::entry_sigma_monthly). An entry executed at a uniformly random time inside the month sees half the month’s variance on average. On a 43% bridge the first three cohorts disperse at 8.8%, later ones at the trailing year’s realized figure. The spread reads only what is known at entry (2026-09-05, the audit’s finding 2): before, the whole generated path’s volatility fed it, so a crash placed at month 24 moved the strikes struck at month 0. The draw comes from the Agreement’s own stream. The purpose is behavioral: thresholds fire across a cohort over a range of prices instead of all at once for ten identical twins. Dispersion changes Agreement terms and behavioral thresholds, so it can change realized receipts and returns. Mean preservation before cent rounding does not preserve every book’s outcome; par Coin funding remains one BTC per Agreement at its own entry price.

[ \text{strike} = \text{cents}\Big(S_m \exp\big(\sigma_{\text{intra}} z - \tfrac{1}{2}\sigma_{\text{intra}}^2\big)\Big), \qquad \sigma_{\text{intra}} = \sigma_m/\sqrt{2} ]

→ Where it is derived

Intrinsic shortfall

Also: intrinsic_shortfall_usd, intrinsic loss.

Over Agreements below the schedule line at a month, Σ (R_t − V_m): the book’s intrinsic loss if every one of them stopped at this month’s price. $3.18m at month 12, a peak of $3.73m at month 21 on the base path.

The intrinsic value of the embedded put ladder, marked at the path. It is a what-if, not a realized figure; the realized book shortfall is the credit table’s EL.

[ \text{intrinsic shortfall}m = \sum{\text{below schedule}} (R_t - V_m) ]

→ Where it is derived

IRR ambiguity

Also: irr_ambiguous, irr_root_count, seeds_irr_ambiguous, multiple roots, several roots.

A flow with several sign changes can have several IRRs; the engine reports the flag and the count, the cockpit shows them beside the figure and keeps them in exports, and the hedged root nearest the unhedged rate is the stated convention.

outputs.rs::irr_analysis (model audit 2026-09-06, M02) classifies the flow and searches a finite rate grid with extremum checks; it does not certify that every mathematical root was found. Roots outside the supported monthly range or three tightly clustered roots inside one grid cell can be missed. The flags count the located roots; RunOutputs.irr_ambiguous / irr_root_count and Dist.seeds_irr_ambiguous carry it. Model audit 2026-09-07 (R09): the cockpit declared the fields and readIrr still returned an ambiguous 10.00% unqualified, so a root chosen under a convention read as an unambiguous outcome; the qualification now travels with the figure on every page and in exports, the cash multiple and net cash beside it.

→ Where it is derived

J

Jump rate

Also: λ, jump_rate_annual, jumps per year.

λ, the expected number of jumps per year in a jump-diffusion (2.0 = two a year on average). Each month’s jump count is Poisson(λ/12). At λ = 0 no extra draw is taken and the path is GBM’s.

Named-input validated: finite and non-negative. The compensator the drift absorbs scales with λ, so a higher jump rate under a negative mean jump does not lower the expected price — it widens the distribution around the same μ.

→ Where it is derived

Jump-diffusion

Also: JumpDiffusion, jump diffusion, diffusion σ.

GBM plus a Poisson stream of jumps: each month’s count is Poisson(λ/12), each jump adds one log-size draw from the jump law (Merton or Kou). The drift is compensated so E[S_t] = S₀·e^{μt} holds with the jumps in; λ = 0 is GBM exactly.

PathMode::JumpDiffusion { mu_annual, vol_annual, jump_rate_annual, jump }. The diffusion σ is the volatility of the continuous part only; the jumps add their own variance on top. The compensator λ·(E[e^J] − 1)/12 is subtracted from each month’s log step. The Poisson count uses Knuth’s product method on the run’s uniforms so the draw sequence is fixed by the engine, not by a library.

[ \ln \frac{S_{t+1}}{S_t} = \frac{\mu - \sigma^2/2 - \lambda,(E[e^J]-1)}{12} + \sigma\sqrt{\tfrac{1}{12}}, z_t + \sum_{i=1}^{N_t} J_i, \qquad N_t \sim \text{Poisson}(\lambda/12) ]

→ Where it is derived

K

Keyed mode

Also: keyed, FF_API_KEYS set.

The engine with keys in FF_API_KEYS: every /api/forwardflow/* route needs X-API-Key (on the websocket, a token will do) except health and openapi.json. Bad or missing credentials get 401 JSON naming what is missing, never a value.

The hosted engine at btcnow-forwardflow.fly.dev runs keyed; health reports "mode":"keyed". Limits are counted per key and a success carries X-Key-Name.

→ Where it is derived

Kou jumps

Also: Kou, JumpKind::Kou, double exponential jumps.

Kou (2002) double exponential: a jump is up with probability p_up, size Exponential(η₊); else down, size Exponential(η₋). Mean up-jump 1/η₊, mean down-jump 1/η₋ in log terms. Needs η₊ > 1 for the compensator to exist.

JumpKind::Kou { p_up, eta_up, eta_down } — η₊ = 10 is a mean +10% log up-jump, η₋ = 4 a mean −25% log down-jump. E[e^J] = p·η₊/(η₊ − 1) + (1 − p)·η₋/(η₋ + 1). The asymmetry lets down-jumps be fat and up-jumps thin, the shape a crypto desk usually wants.

→ Where it is derived

L

Ladder leg

Also: leg, LadderLeg, age, payment age.

One put of the embedded ladder: the stop at payment age t (t payments made, the next missed), struck at R_t, expiring at month t + 1, with its weight, its S₀/K and K/S, the surface’s vol there and the put’s dollar value.

surface::LadderLeg — month, strike_usd, tenor_months, weight, moneyness (S₀/K, the engine’s convention), implied_vol and put_value_usd. The ladder table on the Hedge desk is one row per leg; the last column, W × put, is the leg’s contribution to the ladder value.

→ Where it is derived

Ladder value

Also: W × put, ladder_value_usd_per_agreement, weighted ladder.

What the surface says the Holder’s short puts are worth per Agreement: Σ weight × put over the ladder’s legs, each leg counted with the probability the Buyer stops there.

Read beside the flat-path markup: where the markup exceeds the ladder value, the paper’s price more than pays for the puts the Holder is short at the surface’s vols; where the ladder is worth more, the market values those puts above what the paper pays. Their crossing in flat vol is the paper’s implied vol.

→ Where it is derived

Lattice

Also: the lattice, Lattice sigma %/yr, sigma_annual, CRR, backward induction, optimal stopping.

The optimal-stopping grid behind the walk-away frontier: Cox-Ross-Rubinstein steps in log-spot, four a month, on a full-width grid, decisions at payment dates only, under the Buyer’s drift, volatility and discount rate.

boundary.rs::rational_frontier. Lattice volatility defaults to 41.4%, the trailing-24-month realized; \(\Delta = 1/48\) year, \(u = e^{\sigma\sqrt\Delta} = 1.0616\), \(q = (e^{\mu\Delta} - d)/(u - d)\). The grid is full width rather than a tree from a single root so a coin that halved at payment 1 is visible; the Phase 1 review found that a rooted tree kept such a Buyer paying until payment 4. At each date the Buyer picks the best of pay, settle and walk.

[ u = e^{\sigma\sqrt{\Delta}}, \quad d = 1/u, \quad q = \frac{e^{\mu\Delta} - d}{u - d}, \quad \Delta = \tfrac{1}{48} ]

→ Where it is derived

Ledger

Also: the ledger, double-entry ledger, double-entry.

An append-only list of postings in exact cents. Every dollar in a run is one transfer between two of four entities: the Holder, BTC Now, a Buyer, and the Market. Both sides are written at once, so conservation holds by construction.

ledger.rs::Ledger. An amount must be cent-quantized and non-negative or the call panics; a zero amount is dropped. verify_balances recomputes every balance from the raw postings, which is what the in-browser auditor does in TypeScript. The coin is never on the ledger; only dollars are.

→ Where it is derived

Leg

Also: legs, Leg::Futures, Leg::Option.

One position in a generic structure: listed futures per on-book Agreement (side, sizing, basis, margin) or a European option per Agreement (kind, side, strike, tenor, roll, coverage). Each posts into the one set of flows as leg N: ….

hedge.rs::Leg has two variants, externally tagged on the wire. A futures leg’s sizing is DollarDelta, CoinDelta or Coins, resolved at each rebalance; an option leg’s strike and coverage are resolved at each inception. A one-leg structure reproduces the fixed shape it copies bit for bit.

→ Where it is derived

Legs structure

Also: HedgeSpec::Legs, generic structure, Legs.

HedgeSpec::Legs { legs }: a hedge built as a list of legs rather than a fixed shape. The paper’s whole menu — loss-line ladders, the market-neutral short, coin-delta futures, spreads, the split and the pair — is written this way.

Three predicates read the list: is_coin_seat (a coin-delta futures leg or a coin-delta coverage), revalues_the_ladder_monthly (anything sized at the dollar delta) and is_market_neutral (a short futures leg at the dollar delta). Eleven of the fifteen presets are Legs structures.

→ Where it is derived

LGD

Also: loss given default, loss given stop, Shortfall ÷ remaining schedule.

Σ shortfall over Σ remaining schedule at the stop, across the vintage’s stops: the share of the put’s strike that was lost. 0.225 on the historical early-September reference book; 0.531 for cohort 1, 0.043 for cohort 23.

Measured against the schedule, the put’s strike, not against the Holder’s capital; the capital-loss column is the par Holder’s version.

[ \text{LGD} = \frac{\sum \text{shortfall}}{\sum R_t} ]

→ Where it is derived

Lifecycle

Also: state_at, Performing, StoppedAwaitingSale, SoldAwaitingCash, Closed, price_exposed_at, stop_sale_timing, one lifecycle.

The one state of an Agreement at a month that every consumer reads: performing; stopped awaiting sale (the coin still held — price exposure); sold awaiting cash (the month the sale’s cash lands — a receivable, no price exposure); closed.

engine.rs::state_at, with price_exposed_at and price_exposure_end read off it. The timing is engine.rs::stop_sale_timing, the stop’s own: pos = D + lag/30.4375; the sale executes inside ⌊pos⌋ and is booked at ⌈pos⌉, the first payment date at or after the sale point — never before the last mark that priced it (model audit 2026-09-07, R02) — where the delivery, the fee and the refund post. Coverage, capital at risk, the ladder, the hedge desk’s on-book test and the monthly mark all read it, so a stopped Agreement leaves the three panels together (model audit 2026-09-06, M04 — before, risk and hedges dropped it at missed + 1 regardless of the lag while the mark carried it to the sale).

→ Where it is derived

Lifetime stop prior

Also: lifetime, Lifetime default %, Lifetime stop %, lifetime target, stop prior, 40%.

The share of the original book that ever stops over the term on a flat path: 40% in the program’s pricing stance, 70% in the Model Card’s Panel B. The baseline curve is scaled by bisection so a flat path lands it exactly.

Input #7, BaselineCurve { lifetime }, accepted in [0%, 100%). No BTC Now vintage has been observed, so it is a prior on an unscreened population, not a measurement. With drawdown multipliers on the realized share becomes path-dependent by design. With a custom timing curve it is the sum of the per-year bars.

[ 1 - \prod_{t=1}^{n-1}\bigl(1 - \min(1, K,w_t)\bigr) = \text{lifetime} ]

→ Where it is derived

Lockout

Also: lockouts, six-month lockout, seven-day lockout.

Two program lockouts reinstated 2026-09-03: seven days after letting two 60-minute price windows lapse, six months after a stop. Neither is modelled; the six-month one enters only through the rational boundary’s walk cost.

The engine has no notion of a person across Agreements and no re-entry, so a Buyer who stops is simply gone. The walk cost of input #25 (2.5% of the coin’s cost, about one payment) lumps the lockout, the re-strike at market and the lost access into one number on the Buyer’s side of the decision. The July lockout ladder and the rescission ladder remain dead.

→ Where it is derived

Loss-line strike

Also: LossLineAtExpiry, loss line at expiry, the Holder’s loss line.

A put strike set from the Holder’s modeled unrecovered cost at the option’s expiry age. It changes with the terms, fees, purchase price and elapsed payments.

Strike::LossLineAtExpiry reads the configured capital line. A contractual strike does not guarantee the combined investment’s return: premium, coverage, stops, tenor gaps and execution still matter. A zero resolved strike means no put is bought under this rule.

→ Where it is derived

Lost-conviction rule

Also: conviction rule, conviction, X% below entry price, Y consecutive months, capitulation, Conviction exits, Conviction walks.

Deterministic capitulation: a Buyer whose coin has sat X% below the entry price for Y consecutive payment dates walks at the next one. Off by default; X = 50%, Y = 6 when on. Measured against the strike, never the obligation.

Input #11, spec §4.3. A breaching month extends the streak, a non-breaching month resets it; when the streak reaches Y a walk is armed for the next payment date and executes there as the missed payment. Nobody starts underwater: at signing the coin is the entry price. BTC moves about 12% in an ordinary month, so X below about 25% reads normal volatility as capitulation. Chip S4 sets X = 0, Y = 1; the tornado’s behavioral floor X = 0, Y = 2.

[ S_t < (1 - X),\text{strike} ]

→ Where it is derived

M

M0 fixtures

Also: fixtures, M0_FIXTURES.md, closed-form fixtures.

Closed-form contract-math figures computed on 10 July 2026 in exact rational arithmetic before the engine existed, sharing no code with it: a flat path, no exits, $60,000, 1.475×, a 105% purchase price and the July fee basis.

The engine must reproduce them within two cents. They keep their historical fee by pinning the flat rate per term (3.75% at 60 months); regenerating them at 5% would cost their independence. Their 60-month N = 0 effective IRR of 13.3226% matched the Python engine exactly.

→ Where it is derived

MakeWholeDelivery posting

Also: payoff, early-completion payoff.

Buyer → Holder at early completion: the remaining schedule R_t, paid in cash, net of the fee. The identifier predates the vocabulary; it means early completion, cash only since spec v1.5.

engine.rs::settle posts it and the fee to BTC Now, and records the Buyer’s coin equity at exit, spot less the payoff, as coin_returned_usd. settlements_deliver_remaining_schedule_on_upside checks every such posting comes from the Buyer’s account.

→ Where it is derived

Margin buffer

Also: MarginBuffer, buffer, p95_worst_call_of_par, p99_worst_call_of_par.

The buffer the treasury sizes, over the seeds as shares of each seed’s par: the worst single call at p95 and p99, the deepest point of the cumulative futures cash at p95, and the month of the worst call at the median. Zero without futures.

Base configuration, the futures preset, 8 seeds (test): on GBM p95 worst call 3.83% of par, p99 3.88%, p95 worst cumulative 4.92%, the worst month 20.5; on the bridge 4.16%, 4.20% and 5.08%. The p99 interpolates between the top seeds — run more seeds for a tail that means more.

→ Where it is derived

Margin path

Also: margin_balance, initial margin path, futures_notional.

The month-by-month futures cash the treasury must post: the variation call, the intramonth proxy, the initial margin held (margin_balance, margin share × gross notional) and the notional, banded over the seeds. Zero without futures.

The initial margin is capital, reported and — only when a leg’s margin_funding_rate is set — charged at rate/12 on the basis channel (default zero; at 6% the test charges $2,806 over the life on a $44,521 peak). Summarised by the margin buffer.

→ Where it is derived

Margin peak

Also: margin_peak_of_par, initial margin peak, margin pocket.

The peak modeled futures collateral requirement: the configured initial margin share times gross notional, summed across futures legs. It is reserved capital, not an expense.

margin_peak_of_par divides this amount by the stated purchase/par reference. A zero value only means no futures margin is modeled by that structure; it does not establish zero short-option, swap or venue collateral. Funding cost and collateral deposits are separate.

→ Where it is derived

Market

Also: the market, EntityId::Market.

The ledger’s fourth entity: the external counterparty of the stop sale. It buys the coin for dollars, and the three stop postings flow out from it, so its balance goes negative by exactly the sale amount.

The Market entity is what makes a stop balance without the coin ever being on the ledger. Everything the three parties end up with was paid by a Buyer, paid by the Holder or sold to the market.

→ Where it is derived

Market-neutral seat

Also: market neutral, delta hedged in listed futures, Table 20.

A dollar-delta hedge intended to reduce modeled first-order USD price exposure. Rebalancing and basis settings are explicit inputs.

Residual stop, timing, nonlinear, basis and model risks remain. The predicate identifying a dollar-delta short is a trading-rule label, not proof of zero market risk, deployability or a stable return across all paths.

→ Where it is derived

Matched BTC holding reference

BTC retained from the same dated contribution schedule as the selected strategy. Current Research uses strategy-specific net economic contributions; this is not a common starting-budget comparison.

See the workspace measurement contract for cash, economic value, denominator and funding boundaries.

→ Where it is derived

Memory budget

Also: FF_MEMORY_BUDGET_BYTES, process budget, MemoryBudget, memory 503.

One counter for the process: every route reserves its peak bound before it runs and releases it when the work ends; a request that does not fit beside the runs in progress is 503 with Retry-After: 5, computing nothing.

forwardflow_api.rs::MemoryBudget (model audit 2026-09-07, R04: the byte ceiling was per request, so several individually admissible requests could exceed the machine together). The limit is FF_MEMORY_BUDGET_BYTES, default the per-request ceiling (1.5 GB) so one maximal request fits; fly.toml sets 1,200,000,000 for the 2 GB machine. The reservation is taken after the heavy permit (a queued request holds none) and moves into the blocking task with the permit, so it is released when the work ends, not when the request future drops.

→ Where it is derived

Merton jumps

Also: Merton, JumpKind::Merton, normal jumps.

Merton (1976): the log jump size is Normal(mean_log, vol_log²). A mean of −0.20 is a typical jump of about −18%; the size’s standard deviation is the second parameter.

JumpKind::Merton { mean_log, vol_log }. E[e^J] = exp(mean_log + vol_log²/2), the term the compensator uses. Symmetric around its mean, so a crash-biased calibration sets the mean negative.

→ Where it is derived

Missed date

Also: missed payment date, D, the missed payment.

The payment date the Buyer did not pay: t+1 for a hazard draw at age t (payments run first), t for a walk. Day 16 after it is the Stop Date; the sale is priced 18 days after it; it is the Agreement’s exit month.

stop_sale is called with missed = m + 1 for every draw and missed = m for every walk. From the missed date the Agreement is stopped awaiting its sale (engine.rs::state_at): still price-exposed, on the coverage panel and the hedge desk’s book, until the month the sale is booked — ⌈D + lag/30.4375⌉, the first payment date at or after the sale point (R02) — the month after at the program’s 18 days.

→ Where it is derived

Model Card

Also: Model Cards, the card, v2.0 draft, v1.1.

The document that stamps one configuration and one set of Holder-return figures for a data room, citing the spec version it was run on. v1.1 (6 August 2026) is stamped; v2.0 (3 September 2026) is a draft pending Marc’s stamp.

Three cards exist. v2.0 describes the September program on spec v1.6: paced zero-drift median 13.1%, single vintage 14.9%, single-vintage replay median 47.9%. Until Marc stamps it, the figures a Holder may be shown are v1.1’s, which describe a product that no longer exists. cargo run --release --example w0108_refresh reproduces the table.

→ Where it is derived

Moneyness

Also: underwater, in the money, out of the money, M_t.

Spot over the amortized obligation, S_t / B_t. Below 1 the coin is worth less than the discounted value of what the Buyer still owes: underwater. The exposure ladder uses a different ratio, spot over the remaining schedule.

contract.rs::ContractTerms::moneyness; engine.rs::Agreement::underwater tests \(S_t < B_t\). The rational-default redirect and the frontier’s walk_below_moneyness use this ratio. The risk desk’s ladder buckets Agreements by \(V_m / R_t\), the ratio a hedging desk maps onto listed strikes, and calls that moneyness as well; the two differ by the \(R_t / B_t\) column, 1.373 after payment 12.

[ M_t = S_t / B_t ]

→ Where it is derived

Moneyness bucket

Also: MONEYNESS_BUCKETS, < 0.50, 0.50–0.70, 0.70–0.85, 0.85–1.00, 1.00–1.20, ≥ 1.20.

The ladder’s rows: sale proceeds at the month’s mark over the remaining schedule, in six buckets from < 0.50 to ≥ 1.20, lower bound inclusive. The put’s moneyness, not the amortized-obligation moneyness of the rational modes.

A cohort-0 Agreement at month 23 on the base path has \(V/R_{23} = 33{,}292/54{,}575 = 0.610\); an Agreement originated that month sits at \(0.9975/1.475 = 0.676\), the same bucket.

[ \text{moneyness} = \frac{V_m}{R_t} ]

→ Where it is derived

Monte Carlo

Also: MC, Outcome distribution, simulated futures, the fan, montecarlo.

The same book run across many price futures at consecutive seeds, same assumptions, different market luck. On a bridge it is the uncertainty between the pinned endpoints, not a view on where the price ends.

outputs.rs::run_monte_carlo runs seeds base, base + 1, … in parallel and summarizes IRR and WAL percentiles, expected shortfall, a histogram and the cash fan. Serious readers judge the tail, not the median. At the base cockpit configuration, 1,000 runs from seed 42: median 14.93%, p5 10.29%, p95 21.90%, none negative. The Model Card’s figures use the zero-drift bootstrap instead.

→ Where it is derived

Monte Carlo cache

Also: MC_CACHE, memoized, memoization, LRU.

An in-memory LRU of 64 Monte Carlo summaries keyed by run count and the configuration’s serialization. A hit skips the engine. Sound only because the engine is seeded: the same request always gives the same summary.

Built server-side from the struct, so a client’s JSON key order does not matter. Empty after a restart. A change that broke determinism would break the cache silently, which is one reason the invariant suite diffs golden outputs. A single simulate is not cached.

→ Where it is derived

montecarlo

Also: POST /api/forwardflow/montecarlo, montecarlo/ws, ff_monte_carlo.

N seeded runs summarized: IRR and WAL percentiles, expected shortfall, the share negative, a 50-bin histogram, the cash fan and the base seed. Identical requests are memoized; a WebSocket variant streams progress per 1,000-run chunk.

Request: config and runs. The base book at 1,000 runs took 0.30 s cold and 0.006 s memoized. The WebSocket sends Progress, Complete and Error frames and takes the heavy permit per chunk.

→ Where it is derived

Monthly report

Also: hedge series, hedge_series, the months, HedgeSeries.

Monthly cash, values, P&L attribution, margin and deltas for a hedged sleeve, with pointwise bands across the sample and one complete selected path. BTC flow components and open-value stocks are separate.

POST /api/forwardflow/hedge_series records selection.metric and selection.seed. Coin selects the lower-median economic BTC gain; Dollar selects the lower-median finite USD IRR, falling back to USD multiple if no IRR exists. An explicit in-sample selected_seed replays that path. Pointwise p5, median and p95 bands are not individual paths. Preserve costs, surface, market seeds and the fixed valuation seed for comparison.

→ Where it is derived

N

Naked write

Also: naked, written option on the paper, (naked).

The rule: a written option on the paper is naked. The coin inside an Agreement is promised to the Buyer, who owns its upside, so nothing covers a written call and a written put is a second short. Every written leg’s label ends (naked).

The engine does not forbid the write — a call spread needs one — it labels it. The covered write stays the cross-book collar’s business, where the free coin sits on the other book. The risk paper’s rule: never write a call on a coin inside an Agreement.

→ Where it is derived

Negative paths

Also: pct_negative_irr, share negative, runs below zero, futures that lose money.

The share of runs whose effective IRR is below zero, over the runs that had one — conditional. Read the cash-loss share beside it: a run with no IRR can still be a loss. Unavailable when no run has an IRR.

On the histogram the 0% line is marked: futures left of it lose money outright. The heatmap’s break-even frontier is the same threshold drawn across two assumptions. pct_negative_irr is over the runs with an IRR; pct_cash_loss is the share of ALL runs whose undiscounted multiple is below one, and runs_without_irr says how many had no IRR and why.

→ Where it is derived

Net BTC contribution

The BTC equivalent of negative net monthly flows. State whether economic contributions include a terminal liability mark or realized-cash contributions exclude it. This differs from gross Agreement purchases and opening wallet capital.

See the workspace measurement contract for cash, economic value, denominator and funding boundaries.

→ Where it is derived

Net BTC recovery

The BTC equivalent of positive net monthly flows. Economic recovery can include unpaid horizon value; realized-cash recovery excludes it. A recovery retained inside a strategy is not an external distribution.

See the workspace measurement contract for cash, economic value, denominator and funding boundaries.

→ Where it is derived

Net gain

Also: net_gain_usd, Net gain, base_net_gain_usd, collections minus capital.

Receipts less purchases plus the included signed hedge flows, in the stated currency. Unhedged cash gain and hedged economic gain differ when the latter includes unpaid horizon derivative value.

net_gain_usd and net_gain_coins require their cash/economic convention. BTC equivalents use each month’s modeled price. Economic surplus equals realized net recovery minus realized net contribution plus the signed horizon mark; this is not a custody balance or an annual return.

→ Where it is derived

Net IRR

Also: IRR, Net IRR (effective), Net IRR (eff.), irr_effective_pa, irr_monthly, annualized return.

USD cash-flow IRR: the monthly rate that balances the Holder’s dated net dollar flows, annualized as (1 + monthly rate)^12 − 1. Net means after the deductions included in those flows; it does not imply all investor expenses are modeled.

outputs.rs::irr_analysis solves the supplied monthly flow vector and retains unavailable reasons and multiple-root diagnostics. A conventional flow has one outflow phase followed by receipts; non-conventional flows can have more than one root. Read the selected-root convention, cash amounts and timing beside the rate. A hedged economic IRR can include signed derivative value at the horizon; an unhedged scalar describes the Agreement flows. BTC cash-flow IRR is a separate currency measure.

[ \mathrm{NPV}(r) = \sum_{m=0}^{H} \frac{f_m}{(1+r)^m} = 0 ]

→ Where it is derived

Net outcome per BTC of Agreement purchases

Also: coin multiple.

Legacy ratio: gross Holder receipt BTC equivalents plus signed hedge economic BTC flows, divided by gross Agreement purchase BTC equivalents. Display as ×, not BTC. Hedge costs reduce the numerator.

coin.rs::coin_seat_metrics reports this legacy purchase-denominator ratio as median_multiple and p5_multiple. Its denominator sums each Agreement’s USD purchase divided by its own entry strike: at par exactly one BTC per originated Agreement, even with intramonth dispersion. Non-par purchase amounts change that capital. Receipts and hedge cash use monthly simulated spot. The ratio differs from net-contribution recovery and a starting-wallet budget. Negative values represent net liabilities, not a negative physical coin count. USD and Coin multiples coincide only where their price and flow-side conventions align.

[ \text{coins per coin} = \frac{\sum_m c^{\text{in}}_m + \sum_m h_m}{\sum_m c^{\text{out}}_m} ]

→ Where it is derived

Nominal IRR

Also: nominal, irr_nominal_pa, nominal annual rate.

The monthly IRR times 12: 13.144% on the reference Agreement. Quoted in the program chapter’s three-endings tables; everywhere else the effective figure is used.

The same convention names the implied financing rate: 16.50% nominal is \(12 i\), 17.80% effective is \((1+i)^{12} - 1\).

[ \text{nominal} = 12,r ]

→ Where it is derived

Notional

Also: notional_usd, put ladder notional, total_notional_usd, Σ remaining schedule.

The sum of the remaining schedule over active Agreements: the size of the puts the Holder is short, the embedded put ladder’s notional. $4.58m in the ladder’s largest cell at month 23 on the base path.

Reported per coverage month and per ladder cell; ladder_and_coverage_tie_to_each_other holds the totals equal.

→ Where it is derived

O

One-Bitcoin cap

Also: one-Bitcoin active cap, the cap.

A Buyer’s active coin across Agreements in force may not exceed one Bitcoin. The only sizing rule in a program with no qualification and no sizing (Marc, 2026-08-22, R-1036). Not modelled.

The program requires identity verification, sanctions screening, a bankruptcy screen and the active-BTC cap before a Sale or Transfer. The engine does not represent Buyer identity or those checks. One BTC per Agreement fixes contract notional; it does not prove that two active Agreements belong to different Buyers or enforce a per-Buyer aggregate cap. The stop hazard remains an assumed population prior.

→ Where it is derived

Open

Also: open, still active, Open.

An Agreement still active at the end of the simulated window. The horizon gives the last cohort its full term plus a month, so a finished run reports zero here; the engine calls the bucket ‘only possible mid-experiment’.

exit_month is null while open; the drill-down’s delivered figure for an open row is the scheduled deliveries so far.

→ Where it is derived

Open mode

Also: open, FF_API_KEYS unset.

The engine with FF_API_KEYS unset or empty: every /api/forwardflow/* route answers without a credential and one warning is logged at start, FF_API_KEYS unset — the API is open. A local cargo run is open; limits apply per client IP.

GET /api/forwardflow/health reports "mode":"open". The cockpit’s proxy forwards as-is with no FF_API_KEY, so local development is unchanged.

→ Where it is derived

OpenAPI document

Also: openapi.json, Swagger, OpenAPI.

The engine’s own OpenAPI 3 description of every route, served open in both modes at GET /api/forwardflow/openapi.json and compiled in from backend/openapi/openapi.json. The book’s Try-it page loads it into a Swagger UI.

Hosted copy: https://btcnow-forwardflow.fly.dev/api/forwardflow/openapi.json. Its security schemes describe the X-API-Key header and the websocket token.

→ Where it is derived

Option mark

Also: option_mark, open options’ value, marked options.

Signed model value of open options at month end, using remaining tenor, spot and the stated volatility surface and pricing rate. A written option is a liability; no open option means zero.

A surviving option’s horizon mark enters economic return once, but is not settled cash or available funding. The realized-cash series excludes that terminal value and reports it separately. Paying premium exchanges cash for an option asset; the marked P&L view includes changes in that asset alongside cash. This is a model mark, not a verified exit quote.

→ Where it is derived

Option rate

Also: rate_annual, OptionPricing, option pricing rate.

OptionPricing::rate_annual: the Black-Scholes rate every option is priced at. Default zero, the surface’s own quoting convention; the risk paper prices at 4.5% (OptionPricing::paper()).

The option-pricing rate is an explicit assumption used with the supplied volatility surface and tenor; it is not necessarily zero. USD discounting, futures funding and BTC cash-flow conversion are separate conventions. A supplied surface is not a claim of executable quotes.

→ Where it is derived

Option value bucket

Also: option_value, option value.

The ninth attribution bucket: the change in the option mark plus the settlement cash of the positions closed this month, a payoff booked against the mark it replaces, never twice. At inception it offsets the premium to the execution cost.

Each month after inception it is the option’s decay and re-pricing; at the run’s last month it carries the horizon mark of a position still open. On the audit’s bought 24-month call (flat $60,000, 43% vol, zero rate and cost) month 0 is +$6,834.90 against the premium’s −$6,834.90, so total_pnl[0] is 0.00 where it read −$6,834.90 before, and month 1 is the −$288.76 of decay on the flat path. Attribution::option_value; the identity reads total = cash + Δmark + Δoption mark + hedge cash = the nine buckets.

→ Where it is derived

Origination window

Also: origination stop, origination_stop_month, runoff, Origination stops at month, book runs off.

The months in which cohorts originate. Input #18 stops new purchases from a given month on (0 = never); existing Agreements run to completion. Stopping origination caps the size of the position, never the rate on what is owned.

engine.rs::SimConfig::effective_cohorts caps the cohort count with it and the horizon shortens. runoff_caps_size_never_rate checks that stopping at month 6 leaves the IRR identical to \(10^{-9}\). The Greeks use it to freeze the existing book at the as-of month.

→ Where it is derived

OriginationFee posting

Also: OriginationFee, origination_fees, Origination (first N) → BTC Now, origination take.

Buyer → BTC Now for payments 1 to N: one of the first N payments routed whole to BTC Now. Never delivered to the Holder, so it carries no servicing fee. $1,475 per base Agreement.

Summed as origination_fees, $236,487.15 on the historical early-September reference book. Per row, origination_to_btcnow counts as many of the first N as were made.

→ Where it is derived

Owner net

Also: owner_net, Holder (net), Holder net, net delivered, owner_total_inflow.

Delivered gross less the 5% servicing fee: what the Holder actually received from an Agreement. $82,673.75 on a completed base Agreement. Book-wide, owner_total_inflow.

The identifier keeps the ledger’s Owner for the Holder. Capital P&L is this figure minus the purchase price.

→ Where it is derived

P

P&L attribution

Also: attribution, the identity, total_pnl, buckets.

The month’s P&L split into nine buckets that sum to it exactly: carry, price, stops, early completion, hedge mark, hedge settlement, basis, option value and residual. Total = cash in − cash out + the change in the paper’s mark + the change in the options’ mark + the hedge’s cash — total P&L on marks, not a cash report.

Every bucket is the sum over Agreements of a per-Agreement formula on the flat-continuation mark (V(t,S)) at the purchase yield. The identity holds every month on every seed and on the mean band (the mean is linear); the test measures the gap at (2\times10^{-15}) of par on the bridge and on GBM, futures and put ladder alike.

[ \text{total}_m = (\text{in}_m - \text{out}_m) + \text{mark}m - \text{mark}{m-1} + \text{option mark}m - \text{option mark}{m-1} + \text{hedge cash}_m ]

→ Where it is derived

p1

Also: 1st percentile.

The 1st percentile, the stress floor beside the worst observed run. It wants at least 1,000 runs to be stable, and the cockpit says so. 9.18% at the base cockpit configuration.

With fewer than 100 runs p1 is the worst run itself, since \(\mathrm{round}(0.01 (n-1))\) is zero.

→ Where it is derived

p3

Also: 3rd percentile, the p3 line, institutional worst case.

The 3rd percentile of the distribution: the line a credit desk provisions to, the institutional worst case (spec v1.4). 9.70% effective IRR at the base cockpit configuration over 1,000 runs.

The outcome-distribution strip draws the bad 3% as a red zone from the worst observed run to p3, with the tail mean (ES3) as a red diamond inside it.

→ Where it is derived

p5

Also: 5th percentile, bad-luck case.

The empirical fifth percentile of the named measure over the stated sample. About 5% of the sampled values lie at or below this part of the distribution; it is not a guaranteed minimum.

Read the variable, currency and sample count. IRR percentiles use paths with a supported IRR and retain missing/ambiguous counts. Cash or BTC-loss statistics do not disappear when IRR is unavailable. A pointwise percentile band is not one realizable individual path. Historical worked examples are not the current scenario’s result.

→ Where it is derived

Pacing

Also: paced book, deployment pacing, book and pacing.

How the book is built over time: one cohort a month for as many months as the window allows. Paced entry ladders the strikes, the built-in dollar-cost averaging that decides how a crash lands.

A paced book’s outputs are book-level: IRR and payback on net flows, WAL and the multiple on gross flows, so purchases in one month are never netted against deliveries in the same month. The Model Card’s paced book is 24 cohorts of 20 over an 84-month horizon.

→ Where it is derived

Paid in

Also: A, paid-in total, payments made, what he paid.

Every payment the Buyer made, payment 1 included: 1,475 × k after k payments at the base terms. It is the refund base of the stop waterfall and the complement of the remaining schedule.

engine.rs::Agreement::paid_in. Whether payment 1, which BTC Now kept, belongs in the refund base is a term-sheet question flagged rather than ruled; the engine models it as included, reading Marc’s “the maximum he paid” (2026-09-03). At the base terms the difference is $1,475 per stop that pays any refund.

→ Where it is derived

Paper spread

Also: spread, paper_spread, origination margin.

What BTC Now earns or gives up on the sale of the paper itself: Σ (purchase price − strike) over the book. Zero at par; $3,000 per base Agreement and $720,000 on the 240-Agreement book at 1.05×, −$720,000 at 0.95×.

outputs.rs::BtcNowTake::paper_spread, pinned by paper_spread_identity. It enters the revenue timeline at each Agreement’s origination month and is kept out of total_take.

[ \text{spread} = \sum_{\text{Agreements}} (\text{purchase} - \text{strike}) ]

→ Where it is derived

Paper’s implied vol

Also: paper implied vol, paper_implied_vol, the paper’s own implied vol.

The flat vol σ at which the behavior-weighted put ladder equals the flat-path markup: the vol at which the paper’s price exactly pays for the puts the Holder is short. Below it on the surface, the markup more than covers the ladder.

surface::paper_implied_vol(config, r), bisection on σ in (1%, 300%); the ladder value is increasing in σ so the root is unique when it exists. None when no root sits in range — usually because the markup exceeds the ladder even at 300%, which says the markup covers more than the total loss of every stopped coin; the cockpit then prints none and says why. Where the surface’s vols at the ladder’s strikes sit below this number, the paper is cheap in the market’s terms; above it, the market values the puts at more than the paper pays.

[ \sigma^\ast : ; \sum_t w_t, P\big(S_0, R_t, \tfrac{t+1}{12}, \sigma^\ast, r\big) = \text{markup} ]

→ Where it is derived

Partner

Also: Partners, referrer.

Anyone paid a cut of BTC Now’s fees. The referral cuts (50% of the first payment, 0% of the servicing fee, ruled 2026-08-31) are splits inside BTC Now’s take and are not modelled.

The one word for the party formerly called a referrer (Marc, 2026-09-02). A Partner’s cut of the first payment (X1, ruled 50%) and of the servicing fee (X2, ruled 0 for now) are divisions of BTC Now’s own take; the engine reports BTC Now’s take whole.

→ Where it is derived

Path mode

Also: path, price path, PathMode, Mode, the path.

The generator of the monthly Bitcoin price the whole book lives on: a Brownian bridge (the cockpit default), a historical replay, a zero-drift bootstrap, or a custom anchor path. The shock and the bump overlay any of them.

paths.rs::generate, input #2c. Prices are f64 and become cents only when a strike is fixed or a sale is recorded. The path decides who is underwater, what a stop sale fetches and whether early completion is worth taking; everything downstream is a consequence of it.

→ Where it is derived

Payback month

Also: payback, Payback, payback_month, money back.

The first month after 0 at which cumulative net cash is non-negative: month 44 on the reference Agreement (the 43rd delivery of $1,401.25 covers $60,000), month 48 on the base book at seed 42. None if never reached inside the horizon.

Defined on net flows. The \(m > 0\) guard stops a book with no purchase at month 0 from reporting payback at 0. Chip S5 and the cash fan answer the same question under uncertainty.

[ \text{payback} = \min{, m > 0 : \textstyle\sum_{k \le m} f_k \ge 0 ,} ]

→ Where it is derived

Payment

Also: payments, PMT, monthly payment, scheduled payment.

One of the equal monthly amounts the Buyer pays: the Purchase Price divided by the term, floored to the cent, the last payment absorbing the residual. $1,475.00 at the base terms.

Straight division, not an annuity (\(\text{PMT} = P/n\)). Payment \(t\) is schedule()[t-1]. Payments 1 to N go whole to BTC Now; each later payment splits 95% to the Holder and 5% to BTC Now, $1,401.25 and $73.75 at the base terms. At 36 months the payment is $2,458.33 and the last one $2,458.45 (convention C1).

[ \text{PMT}^* = \lfloor P / n \rfloor_{0.01}, \qquad p_n = P - (n-1),\text{PMT}^* ]

→ Where it is derived

PaymentDelivery posting

Also: PaymentDelivery, delivery, deliveries, delivered, send.

Buyer → Holder for payments N+1 to the term: a scheduled payment net of the servicing fee, $1,401.25 at the base terms, posted alongside a FlowFee of $73.75.

A “delivery” or “send” is any dollar that enters the Holder’s stream: a scheduled payment after the first N, an early-completion payoff or a stop-sale delivery. All three pass through fees.rs::FeeState::split.

→ Where it is derived

Payout over premium

Also: payout ÷ premium, payout_over_premium, payout ratio.

Mean economic payoff divided by mean net premium and carry paid, when that denominator is positive. The numerator includes open horizon value; the ratio is not a cash-recovery ratio.

HedgeResult.payout_over_premium has a legacy wire value of zero when the denominator is nonpositive; the interface should show unavailable in that case. Above 1 means economic payoff exceeds the reported net premium/carry on this sample. It does not establish fair pricing, identify the cause of a model difference or guarantee protection. Read realized settlements, open value and all costs separately.

→ Where it is derived

PD

Also: probability of default, stop rate, Stops ÷ Agreements, stop frequency.

Stops divided by Agreements in the vintage: 0.421 on the historical early-September reference book (101 of 240). A stop is any outcome other than completed, completed early or open; all four stop tags count.

exposure.rs::exposure, per origination month and once for the book. The identity \(\text{EL} = \text{PD} \times \text{LGD} \times \text{EAD} \times n\) holds by construction. Cohort 1 on the base path has 4 stops of 10, cohort 23 has 7 of 10 but almost no loss.

[ \text{PD} = \frac{\text{stops}}{\text{Agreements}} ]

→ Where it is derived

Peak bound

Also: peak_bytes, peak_postings, 2·term − N + 4, peak_postings_per_agreement.

The most postings a run can write, from the engine’s own rules: 2·term − N + 4 an Agreement, the ledger’s vector sized to exactly it; with the Agreement state and the path, the bytes admission reserves — a bound, not an expectation.

work_estimate.rs::peak_bytes, SimConfig::peak_postings_per_agreement (model audit 2026-09-07, R04: the expected ledger size was not a ceiling — the auditor’s 480-month Agreement on a path to 1% of entry with early completion at 100% was expected at 355.7 postings and wrote 956; the bound is 963, and the vector’s capacity is exactly 963). The 50,000-Agreement version was admitted light at an expected 782,557,368 bytes; its peak is 2,917,431,256 and it is refused. A light route whose peak is over 128 MB (HEAVY_BYTES_THRESHOLD) takes the heavy guard whatever its Agreement-run count. The expectation remains what a user is shown.

→ Where it is derived

Per-Agreement stream

Also: agreement_rng, own stream, per-Agreement draw stream, unconditional draws.

Since spec v1.6 every Agreement draws its strike, stop and early-completion decisions from its own ChaCha20 stream keyed on (seed, id), and the draws are taken before any price test. A bump changes decisions, never the random numbers.

The key is built by splitmix64 from the seed and the Agreement id. Under the earlier single shared stream, one Agreement leaving a month earlier shifted every later draw in the book and the Greeks were unreadable. greeks_are_sensitivities_not_draw_noise bumps a 240-Agreement book by one basis point and requires at most two exits to flip.

→ Where it is derived

Per-Agreement table

Also: drill-down, AgreementRow, agreement_table, Per-Agreement drill-down, the rows.

One row per Agreement: entry, outcome, exit month, payments made, delivered gross, fee, owner net, shortfall, proceeds, refund, surplus, coin equity, purchase price, expected net, capital P&L. Every cent traceable.

outputs.rs::agreement_table, about 106 KB of the base book’s simulate body; pass include_agreements: false on runs that only read scalars. The cockpit’s drill-down sorts on any column and exports the rows as a stamped CSV.

→ Where it is derived

Percentile

Also: percentiles, p25, p50, p75, p95, median, Net IRR percentiles.

A quantile of the sorted outcomes. The calculation convention depends on the result: the legacy Monte Carlo route selects an order statistic; paired Research and hedge distributions interpolate between adjacent observations.

forwardflow_api.rs::percentiles uses sorted[round(q (n−1))], without interpolation, for the legacy Dollar Monte Carlo and cash fan. Research and hedge::Dist use linear interpolation. IRR quantiles exclude paths with unavailable IRRs; count those paths separately and read cash-loss measures across all paths. A sample percentile is not a guaranteed outcome floor.

→ Where it is derived

Percentile strip

Also: percentile strips, strip chart, p5–p95 bar.

The Hedge desk’s chart of a distribution over the seeds: the bar runs p5 to p95, the tick is the median, the ring the mean. The basis rate and zero are the reference lines; the hedged, unhedged and benchmark strips share the seeds.

One strip per distribution, on one axis of effective annual IRR, so the eye reads the floor (left end), the cost (the medians’ gap) and the upside given up (right end) in one glance. A strip whose left end sits right of the basis line is a structure that beats the basis in its 5th percentile.

→ Where it is derived

Perp funding

Also: perp funding %/yr, funding_rate_annual (perp), perpetual funding.

The annual funding rate the short perpetual pays on its notional (0.10 = 10%/yr; negative means the short is paid), ±100%, charged monthly. Perpetuals carry funding and margin cost, never an execution cost.

Reported as the leg perpetual funding, paid side. On a perpetual swap, funding flows between longs and shorts to hold the perp at spot; in a contango market shorts are paid, so a negative rate is a real case. It is a different number from the desk’s funding rate on the fair-value endpoint.

→ Where it is derived

Perpetual delta hedge

Also: perp hedge, delta hedge, perpetual short.

A short in perpetual futures sized to the book’s proxy delta, reset at each rebalance and marked monthly, carrying funding and margin — the market-neutral desk’s hedge.

The proxy delta is the embedded put ladder’s delta, weighted by the stop probabilities still ahead of each Agreement; the surplus above the Purchase Price is left unhedged. Funding and the carry on initial margin are paid monthly on the short notional. This is the one structure for which the hedged excess over basis is reported.

→ Where it is derived

Posting

Also: postings, transfer, raw postings.

One ledger transfer: month, from, to, amount, kind, Agreement id. A completed base Agreement produces 120 postings; the historical early-September reference book 17,728. Ask for them with include_postings on the simulate endpoint.

Entities serialize as "Owner", "BtcNow", "Market" and {"Obligor": id}; kinds are the seven TxKind variants. Every reported total can be rebuilt from the postings by hand, which is the drill-down audit.

→ Where it is derived

Posting month

Also: cash lands at, posts at.

The first payment date at or after the stop sale point, ⌈D + lag/30.4375⌉, clamped to the horizon — never before the last mark that priced the sale: with the default 18-day lag the month after the missed date, at 45 days two months after. The three stop postings carry it; the price is not rounded, only the date.

Only a lag of zero (or a whole number of months) posts at the sale point itself; any fraction of a month posts at the next payment date, whose mark is the later of the two the sale interpolates (model audit 2026-09-07, R02: the nearest date put a 10- or 45-day sale’s cash a month before the mark that priced it, so a later mark revised realised cash). The refund’s ten-business-day deadline is inside the same month at this resolution, so the refund posts with the delivery.

→ Where it is derived

Premium and carry paid

Also: premium paid, premium_paid_mean_usd, net premium.

Mean over the seeds of the net premium and carry a structure costs per run: option premium bought less premium received, plus execution cost, funding and margin carry. Negative when the structure is net premium-positive.

HedgeResult::premium_paid_mean_usd. It is the cost side of the hedge before any settlement; the payoff is the other side. A collar or a put spread can be net negative here, meaning the written legs paid for the bought ones, at the price of the assignments those legs carry in the payoff.

→ Where it is derived

Price bucket

Also: price line, coin price, coin-price line.

The coin-price line: last month’s book rolled one month at y, re-priced at this month’s spot minus at last month’s, same ages. Small — about 0.24 coins per Agreement at signing, the dollar seat’s delta — a dollar schedule being price-blind.

Price enters only through the stop and early-completion masses and the sale proceeds; the September stop’s surplus above the Purchase Price makes every expected stop a long call, and a stop in transit is re-marked here at the month’s spot — a whole coin for its ~1.6 months, hedged the same months — so at +10% a month the line peaks at 9.6% of par (test, month 50). At origination it carries (V(0,S_m) - V(0,K)) when the strike is not the spot. The book rolls first, then is re-priced: the factor is that order.

[ \text{price} = (1+y)\big(V(t-1, S_m) - V(t-1, S_{m-1})\big) ]

→ Where it is derived

Price multiple

Also: multiple, 1.475×, markup.

The Purchase Price as a multiple of the coin’s cost: 1.475 in the program, so a $60,000 coin is sold for $88,500. It implies the paper’s financing rate; a multiple below 1.0 implies a negative one.

Input #5, accepted in \(0 < m < 100\). The report view’s configuration line prints \((\text{multiple} - 1)/\text{term-years}\), 9.5% at the base terms, a simple markup per year that is not the implied financing rate. The inverse input, a nominal rate to a multiple, exists in contract.rs::pmt_from_nominal_rate but is not wired to the cockpit.

→ Where it is derived

Proceeds

Also: V, sale proceeds, stop proceeds, stop_proceeds_usd, recorded proceeds.

The recorded dollars from the stop sale: the interpolated path price 18 days after the missed payment, less the haircut and the 25 bp sale cost. The one number the Holder, the Buyer’s statement and the auditor share.

Stored on the Agreement as stop_proceeds_usd. At the base terms with the coin at $60,000, \(V = 59{,}850\). Everything in the waterfall is computed from \(V\), \(A\) and \(P\); the three postings of a stop sum to \(V\), which is what the Market entity gives up.

[ V = \operatorname{cents}\big(S \cdot e^{-\text{haircut}} \cdot (1 - \text{sale cost})\big) ]

→ Where it is derived

Purchase Price

Also: Agreement price, terminal value, terminal, P, all-in cost.

What the Buyer pays for the coin in total: strike times the price multiple, quantized to cents. At the base terms $60,000 × 1.475 = $88,500, paid as 60 payments of $1,475.

contract.rs::ContractTerms::terminal computes \(P\). It is the letter the stop waterfall uses too: the Buyer’s refund is capped where \(V + A\) exceeds \(P\), and any proceeds above \(P\) are the Holder’s surplus. Not to be confused with the purchase price of the paper, which is what the Holder pays BTC Now.

[ P = \text{cents}(\text{strike} \times \text{multiple}) ]

→ Where it is derived

Purchase price of the paper

Also: purchase % of coin cost, purchase_pct_of_strike, par, Holder’s purchase price, capital deployed.

What the Holder pays BTC Now per Agreement, as a fraction of that Agreement’s strike. Par (1.00×, $60,000 on the base coin) since spec v1.4; the premium is the negotiable.

Input #6b. Posted at origination as PurchasePrice from the Holder to BTC Now; the fraction form keeps a paced book of many cohorts sane when each cohort strikes at a different price. Before v1.4 the default was 1.05×, $63,000, which is what the M0 fixtures and any July document use. The difference between purchase price and strike, summed over the book, is the paper spread.

[ \text{purchase} = \text{cents}(\text{strike} \times \text{pct}) ]

→ Where it is derived

Purchase-yield mark

Also: purchase yield, mark_paper, reporting mark, purchase_yield_annual.

Purchase-yield attribution mark: expected remaining Agreement flows along a flat continuation of current spot, discounted at the yield that calibrates a fresh Agreement to its purchase cost.

series.rs::purchase_yields and mark_paper define a model convention for explaining monthly P&L. Stops in transit use expected proceeds at current spot discounted to their modeled receipt date. Cost calibration does not establish market-participant fair value or auditor acceptance. Monthly-settled futures have no separate surviving mark; open options and swaps can retain signed model value. Read the stated method and limitations.

→ Where it is derived

PurchasePrice posting

Also: PurchasePrice, purchase_prices.

Holder → BTC Now at the origination month: the Holder buys the paper, strike times input #6b ($60,000 at par). Paper acquisition, not BTC Now’s take; the identifier names the Holder’s purchase, not the Buyer’s Purchase Price.

The only outflow kind from the Holder (auditor check A2b). Summed as purchase_prices in the BTC Now block and reported separately from total_take.

→ Where it is derived

Put ladder

Also: static put ladder, puts on the paper.

A put bought on each Agreement at its origination, struck at a share of its entry price, for a fixed tenor — the simplest floor under the coin the Holder is short.

Coverage is coins per Agreement (one Agreement is one coin). The premium leaves the Holder’s flows at inception; the intrinsic value at expiry comes back. BTC Now’s own posture is a put ladder at 70% of entry with 75% coverage over a 24-month window.

→ Where it is derived

Put skew

Also: put_skew_points, skew points, five points of skew.

OptionPricing::put_skew_points: vol points added to the surface’s vol whenever a put is priced (5: a 40% surface prices puts at 45%); calls read the surface as it is. Default zero — the surface’s smile already carries its skew.

The risk paper’s Appendix D prices every put five points over its implied vol at a 4.5% rate. On the engine the year-end loss-line put goes from 5.77% of spot the default way to 6.00% the paper’s way (the_papers_pricing_moves_a_put_the_way_black_scholes_says).

→ Where it is derived

Put spread

Also: spread.

A put bought at a higher strike and one sold at a lower strike on the same Agreement and tenor: cheaper than the ladder, protection that stops below the lower strike.

The written put’s premium offsets the bought put’s; below the short strike the Holder is unprotected again, which is the trade the spread makes for its lower cost.

→ Where it is derived

R

Rate limit

Also: 429, Retry-After, concurrency cap, per-key limit.

Per key in keyed mode, per client IP in open mode: 120 requests per rolling minute and at most 4 concurrent heavy runs. A breach is HTTP 429 with a JSON error and Retry-After in seconds; a refused request is not itself counted.

State is in memory on the one machine. Heavy means a route taking the server’s HEAVY permit — Monte Carlo and its websocket, heatmap, backtest, risk, fair value, hedge, coin seat. Behind these sit the server-wide three permits and the engine’s own work caps, which answer 400.

→ Where it is derived

Rational boundary

Also: rational_boundary, boundary, Rational boundary, input #25, fifth behavior mode, pessimist robot.

The fifth behavior mode (v1.6): a Buyer whose coin sits below the computed walk-away frontier for the payment date does not pay; the walk is the missed payment. The one behavior number that carries no prior.

Input #25, Option<BoundaryParams>; exit tag RationalBoundary. The frontier is computed once per run by boundary.rs::rational_frontier from cohort-1 terms and, being scale-invariant in the strike, serves every Agreement. At step 1, before payment \(t\), the Buyer compares spot with frontier[t − 1] times the strike. Lifted from the parked Behavior Engine and re-derived for the September stop (Marc, 2026-09-03).

[ S_m < f_t \cdot \text{strike} ;\Rightarrow; \text{do not pay; arm the walk} ]

→ Where it is derived

Rational default

Also: rational mode, rational_default, Rational redirection, redirect, the ruthless robot, Stop (rational).

Keeps the hazard, moves the stops: a drawn stop sticks only on a Buyer whose coin is below the amortized obligation; an in-the-money draw is redirected to a random underwater Agreement, or suppressed and counted if there is none.

Input #9, spec §4.2; the exit tag is non_performance_rational. Underwater means \(S_t < B_t\) against the amortized obligation, not the entry price and not the nominal schedule. The same lifetime curve concentrates into drawdowns; on a strong rally draws are suppressed and the realized share bends below the target. With the multipliers also on, the drawing Agreement’s hazard is scaled first, then the redirect looks for someone underwater.

→ Where it is derived

Realized hedge settlements

Also: realized_settlement_mean_usd, hedge settlements, settlements.

Signed option, swap and futures cash settlements already modeled as received or paid. Open horizon derivative values, premiums, basis and costs are separate.

HedgeResult.realized_settlement_mean_usd is the mean economic payoff less horizon_mark_mean_usd. A long-dated option still open at the horizon can therefore report zero realized settlement alongside a nonzero economic payoff. Read the final open value before treating economic recovery as cash available.

→ Where it is derived

Realized volatility

Also: realized vol, Realized vol, base_vol_annual, σ_real.

The engine’s own definition: the population standard deviation of a path’s monthly log returns, annualized by √12; zero for fewer than three prices. The base seed-42 bridge realizes 39.4% against its 43% input.

exposure.rs::realized_vol. It sets the intramonth dispersion spread and translates a vega bump into a vol factor. The examples that print the Model Card’s regime figures divide by \(n - 1\) instead: 40.6% versus 41.4% on the trailing 24 months. A bridge realizes a little below its input because pinning removes variance.

[ \sigma_{\text{real}} = \sqrt{12};\sqrt{\frac{1}{n}\sum_{i=1}^{n}(r_i - \bar r)^2} ]

→ Where it is derived

Rebalance

Also: rebalance every, rebalance_months, rebalance date.

Months between resets of the perpetual delta hedge, 1–120. At each rebalance date the short position is reset to coverage × the proxy delta of the book, in coins; between dates it is held and marked monthly.

The proxy delta is the delta of the embedded put ladder’s legs still ahead of each Agreement on the book, conditional on survival to date, at the surface’s vol for each strike and tenor — not exposure::greeks, which is an ensemble figure costing seven engine runs per date. The surplus call above the Purchase Price is left out: the desk shorts the put’s delta. A shorter rebalance tracks the delta closer and pays no more funding, since funding is on the notional, not the trade.

→ Where it is derived

Rebalancing rule

Also: TradingRule, trading rule, rebalance policy, Calendar, PriceMove, min_trade_coins, lot_coins.

A futures leg’s TradingRule: when to reset the position — Calendar { months }, DeltaBand, PriceMove { pct } — with a minimum trade, a lot (CME is 5) and a margin funding rate. A parameter with a measured cost, not an assumption.

series.rs::rebalance_policy_comparison (POST /api/forwardflow/rebalance_policies) runs one structure under each policy on the same seeds at the desk’s own execution cost (the request’s exec_cost_bps applies to option premium; futures turnover has its separate futures_cost_bps) and reports turnover and trade count beside each hedged distribution, every row saying the cost it was priced at; the page subtracts each median from the monthly reset’s. A reset smaller than the minimum is skipped and the net position is rounded to the lot. A calendar position can remain past the Agreement’s exit until its next reset unless close_on_exit is enabled. On the wire a plain calendar rule still reads and writes rebalance_months.

→ Where it is derived

Redline

Also: the Redline, legal review.

The legal review that rules on drafting questions the engine cannot: whether a credit-flavoured identifier such as Obligor may live in code, and the sale standard’s venue, deadline and index once written into the Agreement.

The vocabulary ruling maps Obligor to “the Buyer of record” and leaves the identifier for Redline to rule on. Term-sheet questions the engine has taken a position on pending an answer are listed in the limits chapter.

→ Where it is derived

Refund

Also: refunds, Buyer refund, buyer_refund_usd, Refunds to Buyers, StopRefund, Refund $.

The dollars a stopped Buyer gets back out of the sale proceeds: min(paid in, max(0, proceeds + paid in − Purchase Price)). Zero when the sale does not clear the remaining schedule; never more than he paid.

The R-1033 rule (Marc, 2026-08-22, reporting counsel’s approval). Since \(R = P - A\), the middle term is \(V - R\): the refund is the proceeds above the remaining schedule, floored at zero and capped at the paid-in total. It is paid in dollars from the proceeds within ten business days; a zero refund posts nothing. At the base terms after 12 payments, a $75,000 coin refunds $4,012.50 and a $100,000 coin refunds the full $17,700.

[ \text{refund} = \min\big(A,\ \max(0,\ V + A - P)\big) ]

→ Where it is derived

Regime

Also: regimes, the three regimes, regime 1, regime 2, regime 3.

One of the three cases of the stop waterfall, ordered by where the proceeds fall: below the remaining schedule (shortfall), between the schedule and the Purchase Price (refund), or above it (surplus).

Regime 1: \(V \le R\), refund 0, the Holder takes everything and books a shortfall. Regime 2: \(R < V \le P\), the Holder receives exactly \(R\), everything above refunds the Buyer, a completion that arrived early. Regime 3: \(V > P\), the refund cap binds at \(A\) and the Holder keeps the surplus. Shortfall and surplus cannot both be positive. The same word also names a bootstrap window (regime start).

→ Where it is derived

Regime start

Also: Regime from, regime_start_index, modern regime, trailing 24 months, full history.

The month from which the bootstrap samples returns. January 2017 (index 59) is the cockpit’s modern-regime default; July 2024 (index 149) starts the trailing-24-month pricing window; February 2012 (index 0) is the full-history stress.

Bar \(i\) is the month \(12(y - 2012) + (m - 2)\). The modern regime drops the early hundred-fold years without dropping institutional-era volatility. Marc ruled on 2026-08-05 that the pricing stance is current volatility, the trailing 24 months, with full history as the printed stress.

→ Where it is derived

Regime switching

Also: RegimeSwitching, calm σ, stressed σ, two-state vol, Markov vol.

A two-state monthly Markov chain on the volatility: calm or stressed, one drift. Each month’s log return uses the state’s σ, then the state may switch for the next month. Equal vols reduce to GBM exactly.

PathMode::RegimeSwitching { mu_annual, calm_vol, stressed_vol, p_calm_to_stressed, p_stressed_to_calm, start_stressed }. Month k’s return uses the state entering month k; the switch draw for the next month follows. A chain that can never move still takes its draws, so the path depends on the seed alone, never on the parameters’ zeros. The long-run share of months in the stressed state is p_cs / (p_cs + p_sc).

→ Where it is derived

Remaining schedule

Also: R, R_t, remaining nominal schedule, what remains, schedule still owed.

What the Buyer still owes in nominal dollars after t payments: the tail of the schedule. At the base terms $88,500 − $1,475 t: $70,800 after payment 12, $60,475 after payment 19.

engine.rs::Agreement::remaining_schedule, read from a suffix-sum table. It is what the Buyer pays at early completion, what the stop waterfall pays the Holder first, the numerator of the schedule line, the embedded put’s strike and the risk desk’s EAD. The paid-in total is its complement, \(A_t = P - R_t\).

[ R_t = \sum_{k=t+1}^{n} p_k ]

→ Where it is derived

Research workspace

Also: the workbench, /forwardflow, cockpit, Forward-Flow Simulator, Workbench.

The workspace at /forwardflow for testing a theory. Its main scenario reruns after accepted assumption changes, with a 300 ms debounce.

Choose a question or a scenario, inspect the assumptions, then review returns, cash flows, stress and the ledger. Single-run exhibits describe one seeded path; Monte Carlo exhibits describe a distribution. Save a baseline to compare completed runs.

→ Where it is derived

Residual bucket

Also: residual.

What no bucket’s formula claims: the fee’s cent rounding, the conviction rule’s memory (the model restarts each month with no streak), a completion’s last payment against its discounted mark, the cent between (V(0,K)) and the purchase price.

Measured, never assumed away: at most (9\times10^{-8}) of par across the identity test. A residual that grows is a formula that is wrong.

→ Where it is derived

risk

Also: POST /api/forwardflow/risk, ff_risk, RiskRequest, risk endpoint.

The exposure layer (v1.6): the two lines, coverage by month and cohort, the ladder at a month, PD·LGD·EAD per vintage, the Greeks and the frontier family. Options: ladder month, bumps, believed drifts, lattice parameters, Greek seeds.

Heavy route; 0.05 s on the base configuration. config.bump must be null because the Greeks own the bump. The response carries no stamp; the Risk desk page stamps its exports with the spec version from a constant in the page.

→ Where it is derived

Risk desk

Also: /forwardflow/risk, the Risk desk, exposure layer, Risk desk page.

The exposure layer’s page at /forwardflow/risk (spec v1.6): the two lines with the frontier family, coverage on the simulated path, the exposure ladder, the Greeks and PD·LGD·EAD by vintage, on the engine’s own seeded paths.

Manual Run. Its headline is the book-wide share of Agreement-months below the capital line. Exports are stamped config ‹hash› · seed ‹seed› · engine spec v1.6.

→ Where it is derived

Risk-neutral fair value

Also: fair value, FairValue, PV per Agreement, PV of the book, risk-neutral value.

The paper priced the way a desk prices any claim on the coin: the engine run under GBM at the funding rate with the surface’s ATM vol, the Holder’s monthly cash discounted at the funding rate to month 0, averaged over seeds.

surface::fair_value(config, surface, funding_rate, seeds). The measure is the desk’s — drift at its funding rate, vol off its surface — while behavior (hazards, multipliers, propensity, the conviction rule, the rational modes) stays the config’s: our priors for the Buyer, their measure for the price. Every seed is one full engine run (PathMode::Gbm); the Holder’s receipts and purchases (Ledger::owner_monthly_gross) are discounted continuously and averaged. The shock and bump overlays are cleared — a fair value is not a stress. pv_per_agreement_usd is the book’s PV over the number of Agreements.

[ PV = \frac{1}{N}\sum_{s=1}^{N} \sum_{m=0}^{H} e^{-r,m/12}, C_{s,m} ]

→ Where it is derived

Rolled calls

Also: rolled listed calls, 12-month calls at the fixed strike.

Calls bought at the configured strike reference and tenor, renewed at expiry while the Agreement remains eligible. Coverage and any years limit determine the size and stopping rule.

HedgeSpec::RolledCalls prices each premium on the supplied surface and records premium, execution, settlement and any remaining horizon value separately. A fixed entry strike may become expensive after a rally. BTC amounts are reporting equivalents of modeled USD flows, not a claim that a venue executes or settles this strategy in BTC.

→ Where it is derived

Rolling puts

Also: rolling short-dated puts.

Short-dated puts struck at a share of the current spot, bought again at every expiry while the Agreement is on the book — protection that follows the price, at a premium paid every roll.

Rolling keeps the strike near the money, which is why it is the most expensive structure on the shelf over a five-year Agreement: the premium is paid many times and, on a path that never crashes, never comes back.

→ Where it is derived

Ruling

Also: rulings, Marc, 2026-08-22, R-1033, R-1035, R-1037, decider.

A decision by Marc on a program term or a modelling choice, cited by date. R-1033 is the refund formula, R-1035 the Stop Date, R-1037 the sale within two business days (all 2026-08-22); 2026-09-03 moved the surplus to the Holder.

Each rule in the program chapter carries the date of the ruling that made it, so a number in a Model Card can be traced to a decision. Two items are flagged rather than ruled: payment 1 in the refund base, and the sale standard.

→ Where it is derived

Run package

Also: completed-run package, research package, ff-run-package/1, export this run, verify a package.

The durable bundle of a completed run — the request as sent, engine and cockpit identity, timestamps, the result and its warnings — sealed with a SHA-256 over canonical JSON, a content-integrity check (unaltered since sealing — not proof of which engine produced it); “export this run” writes it, “verify a package” reads it.

package.ts (model audit 2026-09-06, M07): schema ff-run-package/1; the engine block carries spec, version, build and data digest, the cockpit its spec and commit; verifyPackage recomputes the digest before a file’s numbers are read and configDiff sets the packaged request beside the live inputs. The stamp’s eight characters are a display reference; the package’s digest is the run’s content identity — a matching digest proves the file unaltered since it was sealed, not that the engine produced it (an unkeyed hash is not a signature; model audit 2026-09-07). The nested shapes (engine, cockpit, timestamps, warnings) are validated before anything is rendered, and a desk package keeps the identity of every answer and refuses a mixed one (R06, R07). The Scenario export remains an input export.

→ Where it is derived

Runs

Also: paths, Monte Carlo runs, input #14, number of runs.

How many seeded simulations a Monte Carlo summarizes: 1 to 100,000, and runs × book size at most 24,000,000 Agreement-runs. Run i is the single run at seed + i.

Spec input #14, forwardflow_api.rs::validate_mc. The 24 million cap is the 100,000-run ceiling at the 240-Agreement base book. p1 wants at least 1,000 runs to be stable. The workbench defaults to 2,000, the report view to 1,000.

→ Where it is derived

S

Sale

Also: Primary Sale, Secondary Sale, Selling Holder, Buying Holder, holder swap.

The receiving side of an Agreement changing hands. A Primary Sale is Holder 0 (BTC Now) selling the paper; a Secondary Sale is any later one, carrying a 1% facilitation fee. The engine models one Holder buying at origination.

The word is capitalised to separate it from the stop sale, which is the sale of the coin for dollars. The engine collapses the Primary Sale onto the origination date and models no Secondary Sale; the 1% facilitation fee on the value moved (Marc, 2026-08-31) is outside the engine.

→ Where it is derived

Sale cost

Also: market-sale cost, sale_cost_bps, 25 bp, execution cost, Market-sale cost (bps).

Execution cost of the stop sale in basis points: proceeds × (1 − b/10,000). 25 bp in the program (Marc, 2026-07-11), so V = 0.9975 × S at the base terms; $150 on a $60,000 coin.

Input #16, accepted from 0 to below 10,000 bps. The same fraction goes to the rational frontier’s walk payoff. The ruling puts the sale’s costs on the Company; the engine takes them out of the proceeds, which lowers the refund and the delivery.

→ Where it is derived

Scenario report

Also: /forwardflow/v2, Holder Analytics, diligence report, Report view.

The manual-run report at /forwardflow/v2, with overview, terms, cash flows, credit, stress, methodology and assumptions.

Shows completed server responses and reports failed analyses explicitly. Changes to the scenario draft require a new run. The former frozen July first-paint and offline fallback has been removed.

→ Where it is derived

Scenario shelf

Also: SHELF, chips, S1, S4, S5, S12, one-click chips.

Thirteen one-click chips, S1 to S13, each a named fear that rewrites the configuration and scrolls to the panel that answers it: a 50% crash the day after wiring, the bleed, doubled stops, the ruthless robot, the kitchen sink.

lib.ts::SHELF, spec §8.1. S5 targets the cash fan, S9 replays the 2013 top, S10 the solver, S11 the heatmap, S13 the tornado. S4 is rational mode plus the conviction rule at X = 0, Y = 1.

→ Where it is derived

Schedule

Also: the schedule, payment schedule, contracted schedule, nominal schedule.

The fixed list of monthly payments that adds up to the Purchase Price exactly. Built once per Agreement at origination and never recomputed; nothing in it depends on the price of the coin.

contract.rs::ContractTerms::schedule builds it under convention C1. The schedule is a contract amount in exact cents: the early-completion payoff, the stop waterfall’s first claim and the risk desk’s schedule line all read its tail. The test schedule_sums_to_terminal_any_term checks the sum at terms 1 to 120.

→ Where it is derived

Schedule line

Also: schedule_line, the schedule line, put strike line.

The remaining nominal schedule over the strike, R_t / strike. Above it a stop sale delivers the whole remaining schedule and the Holder loses only future yield. 1.45 after payment 1, through 1.00 between payments 19 and 20.

It is the strike of the embedded put: the Holder’s shortfall on a stop is \(\max(0, R_t - V)\). Coverage counts the Agreements whose sale at this month’s mark would land below it; the ladder’s notional is the sum of its numerators. The cockpit reports the first row at or below 1.0, month 20.

[ \ell^{S}_t = \frac{R_t}{\text{strike}} ]

→ Where it is derived

Seasoned

Also: fully seasoned, seasoning.

A vintage whose whole window, term + 1 months, fits inside recorded history. With 174 bars through July 2026 and a 60-month term the last seasoned start is June 2021, index 112; there are 113.

The extra month lets a stop at the final stoppable age settle inside the ledger; it costs one vintage against the July program’s 114. Months too close to the present are greyed out in the cockpit’s replay picker for the same reason.

→ Where it is derived

Seed

Also: seeds, seeded, ChaCha20, random-number seed.

The random-number key of a run, default 42. Same configuration and seed, byte-identical output. It drives the price path and, through a per-Agreement key, every Agreement’s own draws.

engine.rs::run seeds a ChaCha20 generator from config.seed for the path alone; engine.rs::agreement_rng(seed, id) derives one stream per Agreement through splitmix64. Monte Carlo run \(i\) uses seed + i, so any run of a distribution is reproducible alone. A change of seed changes the path and every Agreement’s draws together, “another world”; a change of anything else on the same seed holds the world fixed. Determinism is a property of one engine version: v1.6’s per-Agreement streams draw differently from v1.5 at the same seed.

→ Where it is derived

Seed ensemble

Also: greek_seeds, ensemble, 16 seeds, ensemble mean.

The Greeks average over consecutive seeds starting at the configuration’s seed, 16 by default and at most 256, so a bump is not the property of one path. The ensemble also gives the Greeks’ base net gain and base IRR.

Seven runs per seed, so 112 runs at the default. Per-Agreement streams remove draw noise from each difference; the ensemble averages the remaining threshold noise.

→ Where it is derived

Seeds with IRR

Also: seeds_with_irr, seeds with an IRR.

The count of seeds whose combined flow has an IRR at all: a flow with a single sign (all out, or all in) has none, and a flow can change sign with no root in the solver’s range. The IRR statistics are over these seeds only; the multiples and the cash-loss share are over every seed.

Dist::seeds_with_irr, beside seeds_total, seeds_without_irr and without_irr_reasons (single-signed, no root in range, non-finite). A hedge that pays more than the paper returns on a path can leave the combined flow single-signed or rootless; such seeds have no IRR and are out of the IRR statistics, but they are still paths: pct_cash_loss, median_multiple and p5_multiple count them (audit 2026-09-05, finding 1). When this number is below the seeds run, read the cash-loss share and the multiples beside the IRR.

→ Where it is derived

Servicing fee

Also: fee, flow fee, FlowFee, 5%, servicing_fee_rate, program fee, Servicing fee % of each delivery.

BTC Now keeps a flat 5% of every dollar delivered to the Holder, deducted at each send: scheduled payments after the first N, early-completion payoffs and stop-sale deliveries alike. The Holder receives 95%.

Input #4, a flat share not derived from the term (Marc, 2026-08-31; spec v1.5). At the base terms one delivery of $1,475 splits into $73.75 of fee and $1,401.25 to the Holder; the lifetime fee on a completed Agreement is $4,351.25. The fee is rounded cumulatively (convention C2), so a single posting may differ from 5% of that delivery by a cent while the lifetime fee is exact. It is the only thing BTC Now takes after the first payment; no dial gives it a share of a stop sale.

[ \text{fee}k = \text{round}(f,C_k) - \text{round}(f,C{k-1}), \qquad \text{net}_k = d_k - \text{fee}_k ]

→ Where it is derived

Shock designer

Also: shock, Shock, crash overlay, Drop %, Over months, Recover to %.

A crash overlaid on any path: from month X the price is multiplied by a log-linear ramp reaching 1 − Z at month X + W − 1, then held, or recovered log-linearly to R times the unshocked level at the horizon.

Input #17, paths.rs::apply_shock, applied after generation and before the bump. A cleaner crash instrument than moving the bridge’s endpoints, which changes every month. Chip S1 is −50% from month 1 over 3 months; the tornado’s crash row is −70% over 3 months, whose ramp reads 0.669, 0.448, 0.300.

→ Where it is derived

Shortfall

Also: shortfalls, schedule shortfall, shortfall_usd, total_shortfall_usd, Schedule lost to stops, Stop-sale shortfall, Shortfall $.

On a stop, the remaining schedule minus the sale proceeds where the sale fell short: max(0, R − V). The Holder’s loss against the schedule in dollars, before the fee. Zero once the sale covers the schedule.

Regime 1 of the waterfall. The shortfall is not the Holder’s capital loss: the Holder has already received net payments, and the row’s capital_pnl is the number for realized loss. Book shortfall equals the risk desk’s EL, $990,282.37 on the historical early-September reference book at seed 42.

[ \text{shortfall} = \max(0,\ R - V) ]

→ Where it is derived

SimConfig

Also: config, configuration, the inputs panel, Assumptions.

The whole inputs panel as one object, the config member of every POST body: inputs #1 to #25 by their engine field names. Decimal fields travel as strings; optional inputs are null when off; enums are externally tagged objects.

engine.rs::SimConfig, the SimConfig type in lib.ts. Two defaults matter: SimConfig::default in the engine and BASE_CONFIG in the cockpit, which differ only in intramonth strike dispersion. Validation panics name the input and become HTTP 400.

→ Where it is derived

simulate

Also: POST /api/forwardflow/simulate, ff_simulate, one run.

One seeded run: the Holder’s outputs, the per-Agreement table, the path, the hazard vector, the conservation flag and, on request, the postings. 0.010 s at the base book; not gated by the heavy semaphore.

Request: config, include_postings (default false), include_agreements (default true). The base book’s body is 111,692 bytes raw, 17,500 gzipped, 2,547 gzipped without the rows. The workbench fires it 300 ms after any edit.

→ Where it is derived

solve_price

Also: POST /api/forwardflow/solve_price, price solver, inverse price solver, What should I actually pay, hurdle, clearing price, input #19.

The inverse of the deal card: given a target effective IRR and the client’s own configuration, the purchase price at which the paper returns exactly that rate — solved directly as the present value of the Holder’s net receipts at the target over the present value of the strikes, from one prepared run, and verified by a second. At 12% the base book clears at 103.84%, $62,301.38.

outputs.rs::solve_purchase_price (2026-09-05, the audit’s finding 7): the Holder’s receipts do not depend on what the Holder paid, so no search is needed and both runs are at the configuration’s seed. Returns SolvedPrice { price, irr_check, attainable, note }: price is None only when the Holder receives nothing; a target beyond the desk’s 1%–500% bracket gets its price with attainable: false and the edge named. The target must lie in (−90%, +1,000%). Chip S10.

→ Where it is derived

Spec version

Also: spec, v1.5, v1.6, the specification, change block.

A number the specification carries, v1.0 through v1.8, changing when the engine’s definition changes. v1.5 (2026-09-03) applied the September program; v1.6 (the same day) the exposure layer; v1.7 (2026-09-04) the price models, the surface and the hedge desk; v1.8 (2026-09-05) the coin seat.

The spec is the intent, the crate is the truth: where they differ the crate wins until someone changes it. A ruling is applied by a spec version, sometimes weeks later; from 22 August to 3 September the engine still priced the July product.

→ Where it is derived

Spot benchmark

Also: spot, Benchmarks::spot, buy and hold.

Buy one coin per Agreement at its entry price in its origination month, sell every coin at the horizon’s mark. The same coins, the same months, the same seeded paths as the paper — with no schedule, no stops and no fees.

The directional Holder’s alternative: own the coin instead of the paper on it. On a rising path spot keeps the whole rise, where the paper caps the Holder at the schedule; on a falling path spot takes the whole fall, where the paper’s schedule and stop sale cushion it. The paper’s median over spot’s is the benchmarks’ headline.

→ Where it is derived

Spread to par

Also: spread, spread_bps, spread to purchase.

(PV − purchases) ÷ purchases in basis points, both discounted to month 0: positive means the paper is worth more under the surface’s measure than it costs. The gap is the spread the paper pays for behavior and illiquidity.

FairValue::spread_bps. Purchases are the sum of every purchase price the Holder paid, discounted the same way as the receipts — a paced book buys over many months, so the later purchases are worth less at month 0. Par is the purchase book; the spread is how far the risk-neutral PV sits above or below it.

[ \text{spread}{bps} = 10{,}000 \times \frac{PV{book} - PV_{purchases}}{PV_{purchases}} ]

→ Where it is derived

Stamp

Also: stamped, export stamp, config ‹hash› · seed ‹seed›.

A label on an exported exhibit identifying its configuration fingerprint and seed. Retain the full completed run package and engine identity to reproduce the analysis.

A short configuration hash is a fingerprint, not the configuration itself or a source-build identifier. Chart and CSV stamps vary by export; specialist results also require their endpoint options. Save the complete request, response warnings, engine build and historical-data digest. MCP replay metadata uses a separate canonical hash.

→ Where it is derived

Stop

Also: stops, stopped, stopping, Non-perf., non-performance, non_performance, default, defaults.

A Buyer ceasing payments. A payment up to 15 days late carries nothing; day 16 is the Stop Date, the Agreement ends, and the coin is sold for dollars within two business days. The proceeds are divided by a fixed waterfall.

The stop is the Buyer’s only exit other than completing, and the exit a Holder prices. On the Stop Date the Buyer owes nothing further. The coin is sold for dollars (modelled 18 days after the missed payment, priced on the path), the Holder is paid the remaining schedule first, the Buyer is refunded up to what he paid in, and any surplus above the Purchase Price stays with the Holder. A stopped Buyer receives dollars, never coin. The engine’s identifier for the outcome is non_performance, and a few cockpit labels still say “default”; both mean a stop.

[ \text{refund} = \min\big(A,\ \max(0,\ V + A - P)\big), \qquad \text{delivered} = V - \text{refund} ]

→ Where it is derived

Stop (rational)

Also: non_performance_rational, NonPerformanceRational, rational stop.

A stop drawn under rational mode: only a Buyer whose coin was worth less than the amortized obligation. Same sale, same waterfall, same postings as any stop; counted apart in the exit split.

Includes a draw redirected from an in-the-money Buyer onto an underwater one. The missed date is \(t + 1\) like any draw.

→ Where it is derived

Stop Date

Also: Stop Dates, day 16.

Day 16 after a missed payment due date (R-1035). A payment up to 15 days late carries nothing; on day 16 the Agreement ends and the sale for dollars begins. A returned payment counts as no payment.

Marc, 2026-08-22: “stop is 15 days later and we stop on day 16 as always”. The Buyer may also elect to stop in the app on any day, and that day is the Stop Date. The engine works at monthly resolution and does not model the 15 days as an event: it records the missed payment date \(D\) and sells the coin stop_sale_lag_days (default 18, day 16 plus two business days) after it.

→ Where it is derived

Stop mass

Also: weight, ladder weight, unconditional stop probability, stop_mass.

The unconditional probability of a stop at one payment age: survival to the previous age × the hazard at this age, from the config’s default scenario. Price-blind; the weights sum to the scenario’s lifetime stop rate.

The weight on each ladder leg. Drawdown multipliers, the conviction rule, the rational modes and early completion are all ignored, so the ladder is the paper’s short put under the Holder’s prior for behavior, not under any price path. The perpetual hedge’s proxy delta uses the same masses conditional on having reached the current age.

[ w_t = \Big(\prod_{k<t} (1 - h_k)\Big), h_t ]

→ Where it is derived

Stop sale

Also: sale for dollars, recorded sale, forced sale, liquidation.

The sale of the coin for dollars after a stop: within two business days of the Stop Date, at market through the normal venue, in a recorded sale. Modelled 18 days after the missed payment, priced on the path.

Marc, 2026-08-22 (R-1037), approving the drafted mechanics; costs on the Company, record kept. The engine takes the 25 bp out of the proceeds, which lowers the refund and delivery by $150 on a $60,000 coin. The venue, deadline and index are not yet written into the Agreement (the sale standard, a term-sheet question). “Liquidation” is the retired July word.

→ Where it is derived

Stop-sale lag

Also: sale lag, stop_sale_lag_days, 18 days, Sale lag (days after the missed payment), Stop-sale lag (days).

Calendar days from the missed payment date to the recorded sale: 18 by default, day 16 (the Stop Date) plus two business days. The sale is priced on the path between the monthly marks; cash lands at the first monthly date at or after the sale.

Input #24 accepts 0–90 calendar days. The sale price is log-linearly interpolated between monthly marks at pos = missed month + lag/30.4375. Receipt cash is booked at ceil(pos), the first modeled monthly date at or after sale. At the default 18-day lag this is the month after the missed payment; at zero lag it is the missed month. The realized path and the performing Coin valuation continuation both retain the full required sale and booking tail. A short supplied valuation path extends flat without moving the cash date.

[ S = \exp\big((1-f)\ln S_k + f \ln S_{k+1}\big), \qquad f = \text{pos} - \lfloor \text{pos} \rfloor,\ \text{pos} = D + \tfrac{\text{lag}}{30.4375} ]

→ Where it is derived

StopRefund posting

Also: refund posting.

Market → Buyer at the payment date after the sale: the Buyer’s dollar refund, min(A, max(0, V + A − P)). Dropped when zero, so a regime-1 stop writes no refund line at all.

Every refund in a run is a StopRefund to an Obligor; the book’s buyer_refunds_usd equals their sum (auditor check C13). The program pays it within ten business days with a statement, inside the same month at the engine’s resolution.

→ Where it is derived

Stops bucket

Also: stops realised against the prior, stop release, early-completion bucket.

Stops realised against the prior: a stopped Agreement books its cash (payment plus the proceeds expected at the month’s spot, discounted) less its rolled mark, and the recorded proceeds against that expectation the month they land; a survivor books the stop the model expected and released. Averages to zero under the config’s own hazard.

For the stopped Agreement the rolled mark is ((1+y),V(t-1, S_m)); for the survivor the release is (q,(V(t,S_m) - \text{stop value}\cdot d^k)), (q) the model’s stop mass at the age, (k) its posting lag, (d = 1/(1+y)); a walk the rational boundary expected releases the same way, and the early-completion bucket is the same pair with the payoff. A book that stops exactly as the hazard says shows zero here.

→ Where it is derived

StopSaleDelivery posting

Also: stop-sale delivery, delivery to the Holder.

Market → Holder at the payment date after the sale: the proceeds less the Buyer’s refund, net of the fee. It can exceed the remaining schedule, because the surplus above the Purchase Price is the Holder’s.

One of the three stop postings, together with the servicing fee and Buyer refund; their amounts sum to the net sale proceeds. Receipt cash posts at ceil(missed month + lag/30.4375), with the default 18-day lag landing in the next month. The Coin view converts that receipt at its booking month spot, which can differ from the interpolated sale price.

→ Where it is derived

Strike

Also: coin cost, entry price, entry, coin’s cost, K.

The coin’s dollar cost at origination, fixed on the day the Agreement opens: the month’s path price, or a dispersed draw around it. The Purchase Price is the strike times the multiple.

Quantized to cents at origination, the one place a path price becomes money before a stop. The conviction rule measures its drawdown against the strike, the two lines are drawn as fractions of it, and the frontier is scale-invariant in it. With intramonth strike dispersion on, each Agreement in a cohort draws its own strike around the month’s mark.

→ Where it is derived

Stylised surface

Also: Stylised skew, stylised preset, btc_stylised, illustrative skew.

An illustrative Bitcoin skew — a shape, not a snapshot: ATM 41.4% from 1 to 12 months rising to 48% at 24; the 0.70 put +9, +6, +4 vol points at 3, 12, 24 months; the 1.30 call −2, −1, 0. The default surface when none is sent.

VolSurface::btc_stylised(), on tenors 1, 3, 12, 24 and moneyness 0.70, 1.00, 1.30. Its source string says so: stylised illustration, not market data; import a real snapshot. Beyond 0.70 the wing convention continues the put skew in total variance, so the deep puts of the capital-loss zone carry more than the 0.70 vol (52.8% at 0.50× at 12 months against the 47.4% quote) — a convention, until a real snapshot replaces this.

→ Where it is derived

Suppressed defaults

Also: suppressed stops, suppressed_defaults, suppressed.

Hazard draws that rational mode set aside because nobody was underwater that month. Counted on the run rather than dumped on an in-the-money Buyer: Marc’s answer to spec open question 3 (suppress, with a visible counter).

SimResult::suppressed_defaults. rational_mode_suppresses_when_nobody_is_underwater requires a positive count and fewer stops than the naive mode on a zero-vol bridge to $240,000.

→ Where it is derived

Surface interpolation

Also: bilinear, bilinear interpolation, between knots.

How a vol is read between the grid’s knots and beyond them: linear in the vol between quoted strikes (ln moneyness), total variance linear in the tenor between quoted tenors, and beyond the quoted moneyness the wing convention — total variance σ²T linear in ln K/S at the edge’s own slope, Lee-bounded, so there is no kink at the edge.

VolSurface::vol_at(tenor_months, moneyness) reads each bracketing tenor row linearly in the vol between its quotes and, beyond the quoted moneyness, by the wing convention (surface.rs::row_vol): total variance \(w = \sigma^2 T\) continues linearly in \(k = \ln K/S\) at the edge cell’s own slope \(dw/dk = 2\sigma_e\sigma’ T\), clamped to Lee’s bound \(|dw/dk| \le 2\) and floored at zero, matching the edge slope when the Lee bound does not clamp it — a flat continuation put a concave kink at every sloped edge, which is a butterfly priced below zero (model audit 2026-09-07, R01). Between two quoted tenors the two rows’ readings blend in total variance, linearly in the tenor (with price-space checks applied separately); beyond the quoted tenors the surface is flat in tenor. A flat vol has zero slope, so a flat surface reads the same everywhere. Every price beyond the quoted range is the convention, not a quote: the surface reports quoted_moneyness and wing on the wire, and every desk response carries surface_note.

→ Where it is derived

Surface moneyness

Also: K/S, moneyness axis, strike over spot.

The surface’s column axis: strike over spot, K/S. Below 1 are puts struck under the market (the paper’s zone), above 1 are calls struck over it. Note the engine’s own moneyness is the reciprocal, S₀/K.

The ladder table shows both: S₀/K the way contract.rs and the exposure ladder read the coin, and K/S the way the surface is indexed. Interpolation between columns is linear in ln(K/S); beyond the quoted columns, the disclosed wing convention extrapolates total variance. Deep puts outside the stylised surface’s 0.70–1.30 quoted range use extrapolated volatility, not a flat edge quote.

→ Where it is derived

Surface tenor

Also: tenor axis, tenors_months.

The surface’s row axis: time to expiry in months. Between quoted tenors, total variance is interpolated linearly in tenor. Beyond the quoted tenors, volatility is flat in tenor.

Tenors must be ascending and positive. The ladder’s legs are looked up at their own expiry, the missed payment date t + 1 in months; the fair value’s paths run at the 24-month ATM vol, the paper’s weighted average life.

→ Where it is derived

Surplus

Also: stop surplus, stop_surplus_usd, Surplus to the Holder, Stop-sale surplus, Surplus $.

Sale proceeds above the whole Purchase Price on a stop, max(0, V − P). After the Buyer has been refunded everything he paid, this is the Holder’s (Marc, 2026-09-03). Never BTC Now’s.

Regime 3 of the waterfall: the Holder is delivered \(R + (V - P)\), the remaining schedule plus the surplus. It is the long call struck at the Purchase Price that the risk desk describes, exercised only by a Buyer who stops in the money, and the reason the replay figures moved so much under the September rule. On the historical early-September reference book it sums to $148,595.85.

[ \text{surplus} = \max(0,\ V - P) ]

→ Where it is derived

Switch probability

Also: P(calm → stressed), P(stressed → calm), p_calm_to_stressed, p_stressed_to_calm, transition probability.

The monthly probability of leaving one vol state for the other in regime switching: P(calm → stressed) and P(stressed → calm), each in [0, 1]. Their reciprocals are the expected months spent in each state.

Named-input validated to [0, 1]. A P(calm → stressed) of 0.05 means a stressed spell arrives about once every 20 months; a P(stressed → calm) of 0.30 means it lasts about three. Both zero freezes the chain in its starting state.

→ Where it is derived

T

Take-profit gate

Also: settlement_min_return, Profit ≥ % of all-in cost, gate, Take-profit gate.

When on, early completion needs the coin to beat the whole Purchase Price by the stated margin: S_t ≥ P(1 + x). At the cockpit’s 10% that is $97,350 on the base coin. Off by default; the Model Card runs ungated.

Input #22 (Marc, 2026-07-12), accepted 0 to 1000%. Ungated, the Buyer is coldly marginal and compares the coin to what remains; gated, he anchors on his all-in cost, sunk payments included. The draw still happens first (v1.6) so the stream never depends on the price. A 0% gate silences every early completion on a flat path, because the coin never beats $88,500.

[ S_t \ge P,(1 + x) ]

→ Where it is derived

Tenor bucket

Also: tenor, TENOR_BUCKETS, months remaining, ≤ 6 mo, 7–12 mo, 13–24 mo, 25–36 mo, > 36 mo.

The ladder’s columns: months remaining on the Agreement, n − t, in five buckets ≤ 6, 7–12, 13–24, 25–36 and > 36 months. At month 23 every cell is in the > 36 column; by month 48 the book has spread across 7–36.

The tenor axis is what a desk needs to place the put ladder on a listed expiry surface.

→ Where it is derived

Term

Also: term_months, Term (months), 60 months, n.

Number of monthly payments per Agreement: 60 in the current program, a property of today’s offer and not of the Agreement. Nothing in the engine hard-codes it; the payment, the hazard shape and the horizon re-derive from it.

Input #6, accepted 1 to 480 months (spec v1.1, Marc 2026-07-10). The baseline hazard is drawn after payment ages 1 through term−1; a draw after term−1 can miss the final payment. A positive baseline lifetime stop prior therefore needs a term of at least 2. The fee is no longer derived from the term: 5% flat at every term since spec v1.5.

→ Where it is derived

The bracket

Also: four readings, three readings, behavior bracket, model-risk band.

The four readings of the same paths a Holder should run instead of one house view: price-blind (#7 alone), drawdown-multiplied (#7 + #23), rational robot (#7 + #9), and the frontier (#25 at several drifts). The band is the answer.

No single mode is BTC Now’s house view because no vintage exists to make it one. The first three differ mostly in how often an in-the-money Buyer stops; the frontier answers a different question, the floor under a fully informed Buyer with a stated belief. Zero the early-completion propensity and run again.

→ Where it is derived

The in-browser auditor

Also: audit, The audit, tie-out, runAudit, audit.ts, re-derived.

An independent TypeScript check of USD ledger integrity, selected USD metrics and per-Agreement contract rows against Rust, using exact integer cents for money.

audit.ts::runAudit, behind the workbench’s “The audit” button, which fetches the run with postings. Checks A (ledger integrity), B (metrics from postings) and C (contract math per Agreement, the waterfall included). A defect in agreement_table that the ledger did not share fails C and passes A. This does not independently validate Coin valuation, hedge pricing, Monte Carlo statistics or the behavioral priors.

→ Where it is derived

The invariant suite

Also: invariants, tests/invariants.rs, tests/exposure.rs, cargo test, gates.

The Rust tests that assert identities which must hold for every run: 88 green on 3 September 2026 (42 unit, 32 invariants, 9 exposure, 5 API), 2 ignored directional checks. Red blocks a commit; memo numbers never gate.

cargo test --release --workspace. Conservation, the closed-form fixtures, the fee identity, the N-payments identity, term parametricity, determinism, gated orderings, the September stop, fail-fast inputs and the risk desk. Tolerances: two cents per Agreement lifetime, 0.01 pp of IRR, 0.01 months of WAL. It proves the arithmetic, not the priors.

→ Where it is derived

The memo

Also: memorandum, the memorandum, memo §09, drawdown memo.

The July 2026 memorandum: the pricing stance (the zero-drift bootstrap), the actuarial hazard buckets, the drawdown memo’s double-trigger multipliers, and the tables the custom per-year mode mirrors. Dated before the September rules.

Its figures were produced under v1.4’s economics and must be read with the history chapter’s translation table. The parked Behavior Engine’s four-channel decomposition goes to it as prose (Marc, 2026-09-03).

→ Where it is derived

The monthly order

Also: four steps, steps of a month, one month, in order, step 1, step 4.

Each simulated month runs in a fixed order: originate, scheduled payments (the boundary’s decision first), walks, early completions, hazard draws. The order is part of the model: it decides who has paid before who leaves.

engine.rs::run. A Buyer who leaves by early completion or a draw at age \(t\) has already made payment \(t\); a walk consumes the date unpaid. A successfully paid final date completes the Agreement before later exit draws. A pending walk, a boundary decision before payment, or a hazard draw after the penultimate payment can instead cause that final payment to be missed.

→ Where it is derived

The pair

Also: pair, ladder plus spread, both seats hedged.

A combined put ladder and call spread intended to address different downside and upside exposures. Read the configured legs and their total cost together.

The component flows sum into one structure. Its USD and BTC outcomes still use different measurement conventions; the combination does not guarantee either return or remove funding requirements.

→ Where it is derived

The plan

Also: FUND_DESK_PLAN.md, fund-desk plan, six phases, Phase 1, Phase 2.

The original six-phase implementation plan, FUND_DESK_PLAN.md. It records design intent and proposed work, not the current release status.

Paths, surfaces, hedge comparisons and monthly analysis are now implemented. Remaining limitations and open modelling questions are described in the guide. Plan estimates are not delivery commitments.

→ Where it is derived

The seven posting kinds

Also: TxKind, posting kind, kinds.

Every dollar in a run is one of seven kinds: PurchasePrice, OriginationFee, PaymentDelivery, FlowFee, MakeWholeDelivery, StopSaleDelivery, StopRefund. BTC Now’s take is OriginationFee plus FlowFee and nothing else.

ledger.rs::TxKind. There is no posting kind for a share of a stop sale, and the repository’s rules forbid adding one. Two identifiers predate the vocabulary: MakeWholeDelivery is an early-completion payoff and PurchasePrice names the Holder’s purchase of the paper, not the Buyer’s Purchase Price.

→ Where it is derived

The shelf

Also: shelf, Table 18, ShelfRow, ShelfParams.

Illustrative market references evaluated on the same market path and origination dates: spot holding, fixed-rate BTC growth, call overwrites, basis and other stated alternatives.

hedge.rs::benchmarks_with_shelf uses a contractual one-coin-per-Agreement basis and the supplied ShelfParams. Agreement purchase prices, recycled cash, strategy contributions, execution and collateral conventions can differ. Same seeds alone do not make these equal-capital comparisons. Research’s matched-contribution holding reference is a separate benchmark.

→ Where it is derived

The split

Also: split hedge, the other 20%, futures plus calls.

A combined structure assigning part of the modeled coin exposure to futures and part to calls. The selected sizing and strike rules define the proportions.

A split is one strategy with all component cash flows and costs counted. Read futures settlement, basis and option premiums, settlements and open value separately. Historical sample proportions are presets, not universal recommendations.

→ Where it is derived

The tie-out harness

Also: audit harness, audit-harness.ts, harness.

The same auditor run from Node against the engine on four adversarial configurations, exiting non-zero on any failure: the base bridge, everything on at an awkward 48-month term, a replay with no stops, and a $3.37 coin over two months.

cd web && npx tsx app/forwardflow/audit-harness.ts. On 3 September 2026 it printed 32/32, 32/32, 32/32 and 29/29 ties on 240, 70, 240 and 15 Agreements.

→ Where it is derived

The two lines

Also: lines, LineRow, two_lines.

The two curves every desk draws on BPA paper: the schedule line and the capital line, both sale proceeds as a fraction of the entry price by payments made, both falling every month. Scale-invariant in the strike.

exposure.rs::two_lines; pinned by two_lines_match_the_plan_table. Between the lines a stop leaves a shortfall against the schedule but returns the Holder’s capital; below the capital line it does not. The 25 bp sale cost is not in the lines; it enters through the proceeds when the lines meet a path.

→ Where it is derived

Theta

Also: theta_usd_per_month, Θ, markup accrual.

Not a bump: the markup accrual on a path with no price risk. The book is run on a flat bridge and the net gain divided by its weighted average life: +$127,160 per month on the base configuration ($4,571,951 over 35.95 months).

Positive by construction; the flat path’s own stops are already inside it. Unchanged by the as-of month.

[ \Theta = \frac{G_{\text{flat}}}{\text{WAL}_{\text{flat}}} ]

→ Where it is derived

Tornado

Also: assumption tornado, What actually kills this, TORNADO, stresses, S13.

Seven stresses, each a mutation of the current base configuration run at its seed; the bar is the stressed effective IRR minus the base in percentage points, sorted by damage. Clicking a bar loads the scenario.

lib.ts::TORNADO: origination stop at month 3, BTC −70%/3mo permanent with flow continuing, 90% lifetime stops, stop-sale haircut 50%, the behavioral floor (X = 0, Y = 2), crash plus origination stop, and all three. The early-September worked example in the results chapter is historical; current outcomes depend on the saved scenario. If the base or stressed run has no IRR, the change is unavailable, with its reason shown separately and no numerical bar.

→ Where it is derived

Transfer

Also: Transferor, Transferee, buyer swap.

The paying side of an Agreement changing hands: the Transferor hands over, the Transferee takes over, for a $250 transfer fee. Not modelled; the engine has one Buyer per Agreement.

Transferor and Transferee keep the legal direction of the Assignment and Transfer Agreement. The engine has no notion of a person across Agreements, so each Agreement is one Buyer, once.

→ Where it is derived

Turnover

Also: futures_turnover_coins_mean, futures_trades_mean, trades, trade count.

futures_turnover_coins_mean: coins the futures leg traded over the life, mean over seeds — the opening, every reset, the close-outs — and futures_trades_mean, the months a reset moved the position. What a rebalancing rule costs.

The minimum trade thins the count monotonically (test: 55 trades at zero, 49 at (10^{-6}) coins, 5 at 0.05); lots of five on a 40-Agreement book move the notional by at most 2.45 coins against the unrounded leg. A reset that moves nothing is not a trade.

→ Where it is derived

U

Undiscounted multiple

Also: multiple, MOIC, moic, Undiscounted multiple, cash multiple.

Gross cash received over gross cash invested, ignoring timing: 1.3779× on the reference Agreement ($82,673.75 on $60,000). It keeps the IRR honest; amortizing paper has modest multiples at healthy IRRs. The backtest calls it moic.

None when nothing was invested. Defined on gross flows, so a flat 24-cohort book reports the single-Agreement multiple. The M0 fixtures at 105% and the old fee print 1.3295× for the same Agreement.

[ \text{multiple} = \frac{\sum_m \text{in}_m}{\sum_m \text{out}_m} ]

→ Where it is derived

Unhedged distribution

Also: unhedged, Unhedged — the paper alone, the paper alone.

The paper alone on the same seeds: the Holder’s IRR and multiple distribution with no hedge flows. Identical for every structure in one request and to the benchmarks’ paper row, because they share the seeds.

HedgeResult::unhedged. It is the control every hedged number is read against — the same config, the same seeded paths, the same behavior — so any difference is the structure alone.

→ Where it is derived

Unrecovered capital

Also: U_t, unrecovered_capital_usd, Unrecovered capital $.

The Holder’s purchase price less the net payments it has received so far, floored at zero: $60,000 after payments 0 and 1, then $60,000 − $1,401.25 (t − 1), reaching zero at payment 44 at the base terms.

The numerator of the capital line and, summed over active Agreements, the risk desk’s capital at risk. It counts net payments after the first N, so the payment-1 refund-base question does not touch it.

[ U_t = \max!\Big(0,\ \text{purchase} - \sum_{k=N+1}^{t} p_k,(1-f)\Big) ]

→ Where it is derived

Uploaded path

Also: upload, path upload, uploaded prices.

A price path the desk supplies as a list of monthly prices; the engine rebases it to the start price and runs the book on it.

The upload must cover the whole horizon (cohorts plus term plus one month); extra points are ignored and a short list is refused with the named input. It lets a desk run its own generator’s paths through the engine without trusting ours.

→ Where it is derived

V

Variance swap

Also: var swap.

A contract paying the difference between realised and agreed variance, in vol points times a vega notional — the way a desk hedges the volatility in the paper rather than its price.

Struck at the surface’s at-the-money vol for the tenor and rolled through the horizon on its CONTRACTUAL tenor; realised variance is the annualised zero-mean sum of squared monthly log returns. Since the model audit of 6 September 2026 (M10) every swap is marked each month at its remaining-life value — (\tfrac{N_{\text{vega}}}{2K}\big(\sigma^2_{\text{exp}} - K^2\big)) with (\sigma^2_{\text{exp}} = (\sigma^2_t, t + K^2 (T - t))/T), the realised months as they were and the unrealised at the strike (hedge.rs::variance_swap_mark) — zero at inception, decaying to (-N_{\text{vega}} K/2) in vol points on a path with no moves; the settlement on the full contractual window is booked against the mark it replaces (option_value), and a swap whose window runs past the run’s last month is marked there on the (open at the horizon, marked) leg, never settled on a window cut to the horizon. Its settlements arrive late and can be large, which is why the hedged IRR is solved as the root nearest the unhedged rate.

→ Where it is derived

Variation call

Also: variation_call, the call, margin call.

The futures cash the month took, floored at zero: max(0, −(futures mark + futures basis)). The call the desk posts; a received basis is not a call, and a flat path with a zero basis posts nothing.

Non-negative on every seed every month; the worst single call across the seeds is the margin buffer’s headline figure.

[ \text{call}_m = \max\big(0,, -(\text{futures mark}_m + \text{futures basis}_m)\big) ]

→ Where it is derived

Vega

Also: vega_usd_per_vol_point, vega_method, Vol bump (points), vol_bump.

Change in net gain per one-point rise in volatility. On every path mode — the bridge included — the base path is kept through the as-of month and the deviations of the log returns after it are scaled around their mean, never a regeneration; +$8,631 per point on the base configuration (the earlier +$29,718 re-drew the bridge from inception, strikes included), zero on an existing book of fixed schedules, negative on a falling bridge.

Vega has two signs under the September waterfall: the Holder is short a put at the schedule and long the surplus above the Purchase Price, so a wider path feeds the call as much as the put. On the base bridge pinned at $60,000 at both ends the ensemble vega is positive; greeks_have_the_signs_of_a_short_put_on_a_stopping_book pins it negative on a bridge to $30,000. It is a realized-volatility sensitivity, not an implied-volatility vega; the spec’s −$24k figure predates per-Agreement streams and is stale.

→ Where it is derived

Vega notional

Also: vega notional $ per vol point, vega_notional_usd, variance notional.

The variance swap’s size in dollars per vol point, 0–1e12. The swap pays vega notional ÷ (2K) × (σ² − K²) in vol points, long variance, K the surface’s ATM vol for the tenor; no premium, the execution cost is bps of this notional.

HedgeSpec::VarianceSwap { tenor_months, vega_notional_usd }, the standard convention. Realized variance is the zero-mean annualized sum of squared monthly log returns over the swap’s months; the swap is rolled at the surface’s then-ATM through the horizon. It pays when the path is rougher than the surface said it would be, whatever the direction.

[ \text{settlement} = \frac{N_{vega}}{2K},\big(\sigma_{realized}^2 - K^2\big) \times 100 ]

→ Where it is derived

Vintage

Also: vintages, VintageRow, origination month, cohort by origination month.

Agreements grouped by origination month. In the backtest, one cohort originated at a historical month and replayed on the real path that followed; on the risk desk, a row of the credit table.

The backtest returns 113 vintages at a 60-month term, February 2012 to June 2021, each carrying entry close, IRR, MOIC, net gain, deployed, shortfall, the exit counts, refunds, surplus, coin taken and BTC Now’s take. No BTC Now vintage has yet been observed; the word here means simulated history.

→ Where it is derived

Vintage backtest

Also: backtest page, static-pool analysis, Every vintage, decomposed.

The static-pool exhibit: one cohort at every seasoned historical month, replayed on the actual Bitcoin path that followed by the same engine, exits decomposed and netted to the Holder after fees, with a blended buy-every-month row.

Replay constructions carry Bitcoin’s own history and its drift; they are descriptive, not probabilistic, and the early vintages dominate the blend: a 2012 entry at $4.90 rebased to $60,000 rides the whole rally. Read the rows, not the blend, and read every replay figure with the in-the-money-stop sentence attached.

→ Where it is derived

Vol surface

Also: volatility surface, VolSurface, surface, the surface, edited surface.

Implied volatility by tenor and moneyness K/S: rows are tenors in months, columns are strikes as a share of spot. Every option the desk prices is read off it; between quotes the vol is interpolated, beyond the quoted moneyness the wing convention prices, and every surface is checked for arbitrage in price space before it prices anything.

surface::VolSurface — tenors_months, moneyness, vols (one row per tenor) and a source string that says where the numbers came from. It can be built directly, from the two presets (flat, stylised) or from a delta-quoted grid (from_delta_quotes), the shape Deribit and the OTC desks quote in: each delta is converted to a strike at its own vol, K/S = exp(σ²T/2 − d₁σ√T). The cockpit’s grid is editable cell by cell; an edited surface is sent back to every desk endpoint as surface. Both presets are shapes for the exhibit, never market data — the desk imports its own snapshot.

→ Where it is derived

Vol-surface placement

Also: placement, placement exhibit, Placement, /api/forwardflow/placement.

The exhibit that draws the paper’s put ladder on the surface: each leg’s strike and tenor, the vol read there, the put’s value and its weighted contribution, with the paper’s own implied vol beside the market’s 12-month ATM.

surface::placement(config, surface, r) behind POST /api/forwardflow/placement. Returns the legs, paper_implied_vol, surface_atm_12m, ladder_value_usd_per_agreement and markup_usd_per_agreement. It is the exhibit a derivatives desk draws before it talks about price: where the paper’s puts sit on the skew, and whether the markup pays for them at the market’s vols.

→ Where it is derived

W

WAL

Also: weighted average life, Weighted Average Life, wal_months.

Weighted average life: the gross-inflow-weighted mean month of receipt, in months from simulation month 0. How long the average delivered dollar was out. 31.0 months on the reference Agreement; 34.9 on the base book at seed 42.

None when there is no inflow. Defined on gross inflows, so a paced book’s cohort offsets are inside it: a flat 24-cohort book reports 31 + 11.5 = 42.5. The paper pays back monthly from month two, so the average dollar is out far shorter than the term.

[ \mathrm{WAL} = \frac{\sum_m m \cdot \text{in}_m}{\sum_m \text{in}_m} ]

→ Where it is derived

Walk cost

Also: walk_cost_of_strike, Walk cost, % of coin cost, cost of walking.

What walking costs the Buyer as a lump, as a fraction of the coin’s cost: 2.5% by default, $1,500 on the base coin, about one payment. It lumps the six-month lockout, the re-strike at market and the lost access into one number.

Subtracted from the refund in the lattice’s walk payoff. A fraction of the strike so that the frontier is scale-invariant. A higher walk cost deepens the frontier (walk_cost_and_belief_deepen_the_frontier). It is the only place a lockout is priced, and on the Buyer’s side.

→ Where it is derived

Walk-away frontier

Also: frontier, walk_below_of_entry, walk_below_spot, walk_below_moneyness, FrontierRow, rational frontier.

The spot below which a rational Buyer with a given belief is better off walking, one number per payment date, by backward induction on the lattice. About half of entry through year one at 25% drift; 1.16 of entry at payment 1 at zero drift.

boundary.rs::rational_frontier. Walking beats settling only where the refund is zero, so the frontier lies at or below the schedule line and is a single threshold per date. It is the crossing between the highest node where walking wins and the next node up, interpolated in log-spot; None means no node walks. Reported in dollars, as a fraction of entry and as moneyness against \(B_{t-1}\). Every curve meets at 2.4% of entry at payment 59 and nobody walks at payment 60.

[ S^\ast_t = S_k \cdot \exp\Bigl(\sigma\sqrt{\Delta} \cdot \frac{g_k}{g_k - g_{k+1}}\Bigr) ]

→ Where it is derived

Waterfall

Also: stop waterfall, R-1033, the ruled waterfall.

How stop-sale proceeds are divided: the Holder is paid the remaining schedule first, the Buyer is refunded up to what he paid in, and any surplus above the Purchase Price stays with the Holder. Nobody owes anything after.

Ruled 2026-08-22 (the refund formula) and 2026-09-03 (the surplus to the Holder), applied in spec v1.5. Three regimes follow: \(V \le R\) (refund 0, shortfall \(R - V\)), \(R < V \le P\) (the Holder gets exactly \(R\), the rest refunds the Buyer), \(V > P\) (the Buyer refunded in full, the Holder keeps \(R + V - P\)). BTC Now takes its 5% of the delivered dollars and nothing else.

→ Where it is derived

WebSocket

Also: montecarlo/ws, Progress frame, chunked Monte Carlo.

GET /api/forwardflow/montecarlo/ws: the same Monte Carlo over a socket in chunks of 1,000 runs, a Progress frame per chunk, then Complete with the summary, so a heavy book neither times out nor looks dead.

The client’s first text frame is the request JSON. A cached request skips straight to Complete; a disconnect stops the server after the current chunk. Streamed and one-shot results are the same numbers. The URL is derived from the API URL by swapping the scheme, so a hosted backend must serve wss too.

→ Where it is derived

Websocket token

Also: token, ws token, ?token=.

The one credential the Monte Carlo websocket takes besides a key: ?token= = base64url(<key-name>|<expiry>) + . + base64url(HMAC-SHA256 over it), expiry at most 10 minutes ahead. Minted server-side; the browser never sees a key.

Signed with FF_TOKEN_SECRET (at least 32 characters; unset = tokens disabled). The token names a key, so the socket is counted against that key’s limits. A desk’s own code needs none — it sends X-API-Key on the upgrade.

→ Where it is derived

Wing convention

Also: wing, quoted_moneyness, Lee’s bound, beyond the quoted range, LEE_SLOPE_BOUND.

Beyond the quoted moneyness each tenor row continues linearly in total variance (σ²T against ln K/S) at its edge cell’s own slope, clamped to Lee’s bound |dw/dk| ≤ 2 and floored at zero — matching the edge slope when the bound does not clamp it. A convention, never a quote.

surface.rs::row_vol, WING_CONVENTION (model audit 2026-09-07, R01). The flat continuation it replaced put a concave kink in the vol at every sloped edge, and a kink in the vol is a butterfly priced below zero; a wing steeper than Lee’s bound is itself a static arbitrage, so the slope is clamped and the check names the clamp when it bites. Between quoted tenors total variance is linear in the tenor; beyond them the surface is flat in tenor. The surface reports quoted_moneyness and wing on the wire and every desk response carries surface_note. On the stylised preset the put wing moved the fee-gross embedded ladder $5,598.11 → $5,659.39 per Agreement; the flat preset is bit-identical.

→ Where it is derived

Worst

Also: worst run, worst observed run, floor.

The minimum of the distribution: the single worst run observed. 7.21% effective IRR at the base cockpit configuration over 1,000 runs. Reproducible alone by its seed.

Every run of a Monte Carlo is a full seeded run, so the worst one can be loaded into the cockpit at seed base + i and read path by path.

→ Where it is derived

Worst month of cash

Also: futures_worst_month_of_par_median, futures_worst_month_of_par_p95, worst month.

The largest modeled monthly futures cash outflow from settlements and basis, expressed against the stated reference amount. It is a monthly cash screen, not a daily margin limit.

Report the result’s sample and sign convention. Initial collateral, short-option/swap requirements, intramonth moves and forced closure can add funding needs outside this measure. A sample percentile is not a guaranteed maximum.

→ Where it is derived

Worst path

Also: worst_path_irr, worst_path_seed, worst seed.

The lowest hedged IRR across the seeds with one, and the seed that produced it; null when no seed has an IRR, when the worst multiple stands in. Run that seed on the workbench under the same config to see the path.

HedgeResult::worst_path_irr (None when no seed has an IRR) and worst_path_seed, beside worst_path_multiple and worst_path_multiple_seed, which are always present. Seed k of the desk’s seeds is the config’s seed plus k, so the worst path is reproducible anywhere the config is. It is the tail beyond the p5 and the first thing to inspect when the floor looks too good.

→ Where it is derived

Z

Zero-drift bootstrap

Also: bootstrap, Real returns, trend removed, ZeroDriftBootstrap, block bootstrap, de-meaned.

Real monthly log returns from a chosen regime, mean removed, glued together in blocks of six consecutive months. History’s volatility with no assumed appreciation: the memorandum’s pricing stance and the Model Card’s production mode.

paths.rs::bootstrap. Zero drift means zero EXPECTED LOG RETURN of a generated path: the blocks are drawn circularly (a start on any of the window’s n returns, wrapping past the end, the last block cut at the horizon), so every observation weighs exactly 1/n under the sampler’s own rule and the de-meaned mean, zero, is the expected log return of every month; the median and the mean of the price factor are the empirical block distribution’s, not a lognormal’s — on the pricing window the median monthly log step is −0.46% and log(mean(exp(step))) +0.69%, so the median price drifts slightly down and the mean up; no exact Gaussian mean/median relation is claimed (model audit 2026-09-07) (model audit 2026-09-06, M03 — the earlier non-circular draw carried +1.24% / −1.73% / −3.67% a year of log drift on the three windows). De-meaning asserts that the paper’s return is earned by the schedule, not by the coin: Bitcoin’s mean monthly log return is +5.5% over the full history and +3.7% from 2017. The endpoint is free. The three windows in use: full history from Feb 2012 (86.5% realized), the modern regime from Jan 2017 (69.1%, the cockpit’s default), and the trailing 24 months from Jul 2024 (40.6%, the pricing regime).

→ Where it is derived

Zero-rate convention

Also: zero rate, at zero rate.

Options on the hedge desk are priced with the interest rate set to zero: the surface’s volatility does all the work, and the funding rate only appears where dollars are discounted.

The hedge overlay prices every option leg with Black-Scholes at a zero rate, on the surface’s vol for that strike and tenor. Present values in the placement and fair-value exhibits use the funding rate instead. Keeping the two apart makes a hedge’s cost a pure volatility number and a fair value a pure discounting number.

→ Where it is derived

Limits and assumptions

ForwardFlow calculates the consequences of an explicit scenario. Its tests check arithmetic, accounting identities and selected model properties. They do not establish that Buyer behavior, market assumptions or execution conditions describe future outcomes.

This chapter distinguishes implemented features from remaining modelling gaps. The verification chapter describes the checks; the surfaces and hedging chapter describes the current hedge and monthly analysis capabilities.

Buyer behavior is not calibrated

The repository does not supply an observed BTC Now vintage dataset for calibrating stop rates or early completion. Treat the behavior settings as priors. Historical Bitcoin prices provide market paths, not observations of how Buyers would have behaved under these Agreements.

Sources: defaults.rs::DefaultScenario, engine.rs::SimConfig::default, engine.rs::drawdown_multiplier, boundary.rs::BoundaryParams.

Compare price-blind behavior, drawdown-scaled hazards and the rational boundary. Also run with early-completion propensity at zero. Early completion accelerates the remaining scheduled receipts relative to full scheduled completion, but it also removes exposure to a later stop and its possible surplus. Its effect on the whole portfolio is scenario-dependent.

In-the-money stops drive upside

A stop can benefit the Holder when sale proceeds exceed the Purchase Price: the Holder receives the remaining schedule plus the surplus, before its servicing fee. The frequency and timing of these stops are particularly important on rising historical paths.

With drawdown multipliers off, the baseline hazard is price-blind. With them on, the in-the-money multiplier is 0.5. Neither setting is an observed stop rate for the program. The rational-boundary mode offers a different behavior construction. Compare them rather than interpreting a high replay return as evidence that surplus stops will recur.

The waterfall is in engine.rs::stop_sale; the behavior rules are in Buyer behavior. Keep the stop prior and behavior mode beside any quoted historical return.

Vega can have either sign

The Holder is exposed both to shortfalls and to surplus proceeds. Wider price paths can affect both, so the sign of the paper’s volatility sensitivity depends on the scenario and Buyer behavior.

The risk analysis computes a continuation sensitivity: it keeps the path through the as-of month and scales log-return deviations after that month. This applies to every path mode, including the bridge. A flat path has no deviations to scale. This is a sensitivity to the modelled path amplitude, not an option surface’s implied-volatility vega (exposure.rs::greeks).

A volatility surface and hedge overlay are already implemented. Their separate pricing conventions are described in Surfaces and hedging. A sign in one risk-analysis run is not a universal hedge direction.

Monthly resolution

The engine uses one price mark and one payment step per month. A stop sale is priced between adjacent marks by log-linear interpolation. At the base lag of 18 calendar days after the missed payment, the sale sits about 0.5914 months after that date; cash posts at the first monthly date at or after the sale (engine.rs::stop_sale_timing, using the ceiling of the fractional month).

The 18-day lag approximates the program’s day-16 stop plus a sale within two business days. It does not model an actual business-day calendar, venue execution or intramonth price recovery. Monthly margin and intramonth stress proxies likewise do not reconstruct an observed daily collateral account.

One path, many seeds, or historical starts

A single scenario answers what happens on one seeded path. Monte Carlo summarizes the specified path family across seeds. A historical analysis compares start months from the embedded price series, with simulated Buyer exits. These are different constructions.

The workspaces can include a single-run exhibit and a distribution on the same page. Read each exhibit’s run count and construction. IRR statistics can be conditional on seeds with a defined IRR; keep missing and ambiguous IRR counts, cash-loss frequency and cash multiples alongside them. See Results and returns.

Historical starts can overlap substantially and share the same market episodes. They are not independent trials or a probability distribution for future performance. The embedded series is identified by the engine’s historical-data digest; it is not a live price feed.

A bridge fixes the terminal price

A Brownian bridge conditions every path on the selected end price at the market horizon. Its Monte Carlo spread measures variation along the path, while all paths share the same terminal price. Moving the horizon changes the question.

The engine also supports GBM, jump diffusion, regime switching, historical replay, a zero-drift bootstrap, custom anchors and uploaded monthly paths (paths.rs::PathMode). Choose a model that expresses the question; an unpinned stochastic model also brings its own drift, volatility and distribution assumptions.

Sale terms and execution

The model sells at the interpolated path price, applies a log haircut, and deducts a sale cost—25 basis points by default. It does not select a venue or establish that this execution price is attainable.

The documented program ruling allocates sale costs to the Company, while the engine deducts them from sale proceeds before the waterfall. This affects how the cost is allocated between the Holder and Buyer. The sale standard, cost allocation and authoritative Agreement wording need to be reconciled by the program owner; this guide records the implemented convention. See The Agreement.

Payment 1 in the refund base

The model includes the first payment in the Buyer’s paid-in amount, even though BTC Now retained it (engine.rs::Agreement::paid_in). The program specification flags confirmation of that treatment as a term-sheet question. At the base terms, the first payment is $1,475. The stop waterfall shows how paid-in cash limits the refund.

Lockouts and re-entry

The engine has no persistent Buyer identity, re-entry history or operational enforcement of lockouts. Each Agreement is simulated independently as an Agreement, not as a complete lifetime relationship with a person.

The rational boundary’s walk cost is an assumed economic penalty. It does not simulate a six-month lockout, its enforcement or a later Agreement. Custody, paying-side Transfers, secondary Sales between Holders and Buyer screening are also outside the cash-flow engine.

Synchronized stops and market impact

Shared price moves and behavior rules can cause many stops in the same period. The core stop-sale model still applies the same configured haircut and sale-cost rate regardless of the quantity sold. It does not derive execution from market depth or congestion.

A zero haircut is a modelling assumption, not proof that a portfolio has no impact. Stress sale costs and haircut alongside clustered exits, and state the assumed execution conditions. The hedge trading-cost settings are separate from an endogenous impact model for Agreement stop sales.

Surfaces, jumps and hedge limitations

Jump models, regime switching, surface import, option pricing, fair-value analysis, hedge comparisons and monthly marks are implemented. The earlier description of these as future features is superseded.

The remaining limits matter:

• Surface quality. The default surface is a stylised illustration, not a market snapshot. Importing quotes does not guarantee their freshness or liquidity. Prices outside the quoted moneyness use the disclosed wing convention; outside quoted tenors they use the stated tenor convention. Discrete arbitrage checks do not prove continuous arbitrage freedom everywhere.
• Fair-value assumptions. The calculation uses an assumed market process, volatility and discounting basis, while Buyer behavior remains a model input. Its output is a model value, not an executable dealer quote.
• Hedge lifecycle. Options can outlive an Agreement. Futures may remain after exit under a calendar policy unless configured to close. Written options can be naked against the Agreement. Retain the result’s coverage and lifecycle warnings.
• Funding and liquidity. Reported cash needs, initial margin and variation proxies do not form a constrained cash account that enforces collateral, solvency or forced deleveraging. Positive lifetime P&L does not demonstrate that an institution could meet every interim cash call.

Sources: surface.rs, hedge.rs, series.rs; see Surfaces and hedging.

Servicing and legal interpretation

The core Agreement simulation assumes servicing continues under the configured rules. It does not simulate a servicing interruption, transition to a backup servicer, or a legal change that impairs the Agreement’s cash flows. Operational custody, enforceability and the governing documents require review outside this model.

Saved results and historical references

The Scenario report now displays completed server responses. The frozen July first-paint and offline fallback has been removed. If an analysis fails, its error remains visible; a draft edit does not relabel an earlier result as a new calculation.

Some worked figures and test descriptions in the technical chapters record a dated configuration or earlier specification. They are examples and historical evidence. Re-run on the intended source build and historical dataset before using them as current figures.

The ignored July tornado reference remains a historical comparison, not a passing acceptance gate for the September waterfall. Verification records that distinction.

Capabilities and remaining gaps

FUND_DESK_PLAN.md records the original phased plan. It is not a current release manifest or a commitment to delivery dates.

Questions for the program owner

Confirm the authoritative treatment of payment 1 in the refund base, sale-cost allocation, the sale standard and the structure of the Holder’s ownership. Distinguish those contractual decisions from analysis choices such as the behavior base case, discounting basis and surface source.

A scenario can choose a convention to quantify its effect. It cannot settle an unresolved term. The dated versions and rulings chapter records the decisions cited by this guide; the latest governing documents must establish their current status.

Before sharing a result

Retain the full assumptions, seed sequence, response warnings, engine build and historical-data identity. State whether the result is a single path, Monte Carlo distribution, historical replay or model value. Show downside and cash needs beside return measures, and separate empirical evidence from chosen priors. Reproduction and interpretation are both necessary parts of a review.

Measurement and release status

BTC cash-flow IRR, total return, gross purchases and net contributions answer different questions. Read the measurement contract and release model card. A surviving derivative mark is economic value, not received cash; a purchase-yield attribution mark does not certify market-participant fair value. No finite Monte Carlo sample establishes a return floor in every future path.

Dollar and Coin workspaces

Choose the workspace that matches how you measure success. Dollar focuses on growing USD capital. Coin focuses on growing BTC holdings compared with holding Bitcoin.

Both use the same Agreement model. Your choice changes the questions, strategy selection and measures you see. It does not change the Agreement’s contractual dollar payments or the Buyer’s rights.

Choose your objective

Open the workspace chooser. Each workspace keeps its own assumptions, selected strategies and completed comparison in your browser. Use Use in another workspace to copy a scenario deliberately. The target’s previous draft is saved aside and can be restored. Existing scenario links and the original research desks remain available.

Four steps

1. Research: choose a question, edit assumptions and watch one simulated Bitcoin price path update. Review the Agreement’s cash flows and exits, then run Monte Carlo to see a range of outcomes in your workspace’s units. New starting cases use an illustrative GBM with zero drift and 43% annual volatility, so the terminal price can vary. Existing links retain their own market model. These settings are assumptions, not forecasts.
2. Compare strategies: inspect the selected variants on the same simulations used in Research, or change the selection and run again. Start with 256 for exploration; larger runs and separate-seed checks help assess sampling stability. Unhedged Agreements are always included.
3. Risk & cash: inspect the loss distribution, cash screen and an actual adverse seed. Dollar and BTC can rank the same path differently.
4. Evidence: challenge the completed run with separate seeds or a named stress, review the conventions and export the samples and exact requests.

The price path is one seeded example, not a median path or a forecast. Bitcoin market prices are shown in USD per BTC in both workspaces. The unhedged Agreement preview accumulates net cash in Dollar and monthly BTC conversion equivalents in Coin; the Coin chart is not a funded wallet balance. Monte Carlo reports the selected strategies across matching seeds, using dollar outcomes in Dollar and BTC outcomes in Coin.

Research also links directly to stress maps, the purchase-price solver and Agreement detail. These supporting exhibits retain their USD Agreement measures. The comparison shows trade-offs; it does not search every possible hedge or automatically choose the best strategy for you. Advanced analysis provides custom strategy construction, all assumptions, the full USD Agreement research desk and ledger, monthly exhibits, USD exposure and sensitivity, and historical Agreement vintages. Each exhibit keeps its stated units.

Reading the Coin result

Each Agreement represents one BTC. Purchase funding uses its own entry price, so 240 par Agreements deploy 240 BTC, including when entry prices vary within a month. A purchase premium or discount changes that funding amount. USD receipts and hedge flows convert at the month’s simulated BTC price; their net BTC flow determines additional contributions or recovery. The holding reference retains those same dated net contributions. BTC surplus is recovery minus that reference.

Gross BTC deployment counts all Agreement purchases. Same-month receipts can support later purchases, and hedges can need additional capital. These offsets and costs explain why net contributions differ from gross deployment. The selected-path cohort table reconciles unhedged purchase cost, receipts and gain to the book. Each strategy can require different additional contributions; the comparison does not assume an identical starting wallet.

Economic outcomes include any surviving derivative mark at the horizon. A positive mark is not already received cash; a negative mark can imply an additional terminal economic contribution. Realized-only contributions, recoveries and signed marks are available separately. The economic and realized bridges each retain both their contribution and recovery sides. No BTC discount rate is assumed.

This is an analytical conversion convention, not a funded BTC wallet. Actual conversion trading costs, cash reserves, borrowing and external free BTC are not represented by this benchmark. See hedging methods for the exact definitions.

BTC cash-flow IRR and wallet growth

BTC cash-flow IRR is an annualized return on dated investment cash flows. It is not the annual growth of an entire starting BTC wallet. Purchases are funded at each Agreement’s entry price; USD receipts and hedges convert at monthly spot. IRR accounts for the dates of these BTC contributions and receipts and excludes unused BTC reserves. Falling Bitcoin prices can make dollar receipts buy more BTC, so BTC IRR can be much higher than USD IRR on the same path.

A single contribution of 100 BTC and recovery of 110 BTC gives 10% total return, after any costs already included in those flows. It is also 10% annualized IRR only when those are the only flows and exactly one year apart; over two years the annualized rate is about 4.88%. Dated payments explain why both the rate and the amounts matter.

The Research headline labels this rate This path’s BTC cash-flow IRR. It always describes unhedged Agreements on one seed. Choosing a strategy does not apply that hedge to the preview. Use the strategy selector in completed Monte Carlo results to see the hedged distribution. A draft change does not recalculate an earlier completed comparison.

To check a particular return, use Export this path. The file preserves the completed assumptions, amounts and engine version. Read gross BTC deployed, net contributions and recoveries alongside the dated IRR. Starting-case results can change when assumptions or calculation methods change; figures from an earlier release should stay attached to that release’s saved result.

For a wallet comparison, define the starting BTC budget, reserves, conversion costs, future cash calls and any derivative collateral first. Use the same starting budget for every strategy and holding BTC, and check that the wallet can meet its obligations on every simulated path. The current contribution-matched benchmark does not establish that feasibility.

Understand the Bitcoin growth assumption

The GBM drift setting is a continuous annual parameter. Expected one-year price growth is exp(drift) − 1; median one-year price growth is exp(drift − volatility² / 2) − 1. At the starting 0% drift and 43% volatility, expected price stays constant while median price declines about 8.83% per year. Zero drift is therefore not a flat typical price path. These are properties of the assumed model, before any shock or bump, not market forecasts.

Coin Research shows these implications beside the completed price path. Its growth sensitivity check changes the drift on matching seeds, keeps the configured volatility and selected hedge, and reports BTC cash-flow IRRs separately for unhedged Agreements and that hedge. The check runs only when requested. Read its simulation count and unavailable or ambiguous rates; an exploratory sample does not establish tail stability. To test a truly flat price control, set both drift and volatility to zero and remove shocks and bumps: BTC and USD cash-flow IRRs should then agree.

Read dollar cash needs separately

In both workspaces, operational cash estimates are labelled USD. That screen assumes receipts remain available as dollars under monthly netting. The BTC outcome assumes monthly conversion equivalents. Converting receipts could remove dollars needed for a later margin call, so the two readings do not establish one jointly funded strategy.

A cash allowance checks whether the modeled monthly need exceeds an amount. It does not change trades or simulate forced closure. Daily margin calls and a reserve/conversion policy require further modelling. Read limits and assumptions before relying on a result.

Keep the evidence

Completed results retain their original inputs when the draft changes. A notice tells you when the displayed comparison uses earlier assumptions. Navigation reuses that completed experiment; leaving during a run cancels its unfinished batches.

Saved results from before engine 0.6.0 retain their earlier monthly-purchase conversion convention and carry a legacy-funding notice. Run a new baseline before replaying or comparing them with current results. New evidence packages specify the unit of every summary field; USD cash requirements stay USD inside a Coin package.

Browser storage is bounded. If a sample cannot be saved, export it before closing or reloading; the interface reports the problem. Browser-local drafts are not shared team accounts.

Export assumptions to transfer the draft, or export all samples from Evidence to retain the completed analysis. The run includes its objective, benchmark/conversion conventions, selected strategies, seeds, engine build and data identity. Replaying an adverse path checks that it reproduces its saved outcome.

Ask through MCP

Use the same MCP connection for either objective. For example:

I measure success in BTC. Compare these strategies against holding the matching contributed BTC. Show the downside and state the cash-conversion assumptions.

Or:

I measure success in USD. Compare the dollar gain, loss severity and cash needs of the unhedged Agreements and these hedges.

The hedge_risk_samples tool accepts objective: "coin" or objective: "dollar". An assistant should clarify an unspecified objective before ranking strategies. No second connection or access token is needed just to change objectives.

The measurement guide defines gross purchases, net contributions, recovery ratios, BTC cash-flow IRR and mark treatment. The release model card identifies the supported version and remaining validation limits.

Inputs and defaults

This chapter explains the core simulation inputs using the specification’s established input numbers. It gives the JSON field, default, validation bounds and effect. Workspace labels may be shorter than the historical labels in these tables. The API explorer supplies the deployed schema, and Surfaces and hedging covers additional price models and desk-specific parameters. The chapters that derive the math are linked from each group.

Where the inputs live

Every input is a field of engine.rs::SimConfig, the config member of every request body on the API (see The API) and the SimConfig type in lib.ts. Distinguish the engine defaults, the legacy desk configuration and a new workspace scenario.

• engine.rs::SimConfig::default is the program base case as the engine understands it, used by the tests and the examples.
• lib.ts::BASE_CONFIG supplies the legacy and advanced desk base configuration.
• New Dollar and Coin workspace scenarios (scenario.ts::defaultWorkspaceScenario) start from that configuration but use illustrative GBM with continuous annual drift 0 and volatility 43%. Saved scenarios keep their own path mode and assumptions.

Two differences matter: intramonth strike dispersion (#20) is off in the engine default and on in the workspace; market_horizon_months is null in the engine default and explicitly 84 in BASE_CONFIG. The default 24-cohort, 60-month book needs 84 months either way, but the explicit horizon keeps the market endpoint fixed when pacing is shortened. MCP fills omitted fields from the engine default, not the workspace draft. The archived Model Card run of 3 September 2026 is a historical configuration, not a current default: drawdown multipliers (#23) on, 24 cohorts of 20, the zero-drift bootstrap from the trailing 24 months. Its §2 states it in full.

Input validation is defined by engine.rs::SimConfig::check, called before API work estimation and by the engine’s validate wrapper. The engine wrapper panics on failure with a message naming the input; forwardflow_api.rs::catch_engine unwinds the panic into HTTP 400 with that message as the body. A few checks live in the module that owns the input: the custom per-year curve in defaults.rs::custom_yearly_hazard, the custom path in paths.rs::custom, the boundary’s parameters in boundary.rs::BoundaryParams::validate, the risk desk’s bumps in exposure.rs::greeks. Path generation failures (paths.rs::PathError) are ordinary errors and reach the client the same way. The error texts below were read back from the running engine on 2026-09-03. Where a message says “default”, that is the engine’s identifier for a stop.

Numbering. The spec table runs #1 to #25 with three gaps that are not fields of SimConfig. #10 is the state of #9 when it is off. #14 (Monte Carlo runs) and #19 (the inverse price solver, target_effective_irr, accepted in \( -0.9 < r < 10 \) by outputs.rs::solve_purchase_price) are request fields of their own endpoints; the solver, the heatmap grids and the vintage backtest are described in The API. #21, a pooled-vehicle view, was removed (Marc, 2026-07-12; spec v1.4 change 11): recycling multiplies wealth, never the rate. The bump overlay and the seed carry no spec number.

Types on the wire. Money-exact fields are Decimal in Rust and travel as JSON strings ("1.475"); prices, rates and probabilities are f64 numbers; counts are unsigned integers; optional inputs are null when off; the enums (path, scenario) are externally tagged objects such as {"Bridge": {"end_price": 60000, "vol_annual": 0.43}}.

Price path

The path is generated once per run by paths.rs::generate from the seed; the shock and the bump overlays are then applied to it, in that order. It has horizon + 1 monthly marks, month 0 to month \( H \), where engine.rs::SimConfig::horizon sets

\[ H_{\min} = (C_{\text{eff}} - 1) + n + \left\lfloor\frac{\text{lag days}}{30.4375}\right\rfloor + 1, \]

with \( C_{\text{eff}} \) the cohorts that actually originate (#13 capped by #18) and \( n \) the term. horizon() uses market_horizon_months when supplied, which must be at least this minimum; otherwise it uses the minimum. At the base case that is \( 23 + 60 + 1 = 84 \), so 85 marks; the extra month lets a stop at the last stoppable payment date settle inside the ledger (spec v1.5 change 4). Derivations: Price paths, shocks and bumps.

The eight modes of paths.rs::PathMode (the four additional stochastic/upload modes are derived in Surfaces and hedging):

The embedded series (paths.rs::historical_closes, compiled in from backend/data/btc_historical_monthly.csv) has 174 monthly bars, February 2012 to July 2026. Bar \( i \) is the month \( 12(y - 2012) + (m - 2) \), so January 2017 is 59 and July 2024, the start of the Model Card’s trailing-24-month pricing window, is 149. GET /api/forwardflow/history returns the month list.

Paper terms

The contract math is in contract.rs::ContractTerms; Contract math and the fee derives it. Every Agreement in a run shares these five inputs. Only the strike varies, by cohort month and, when #20 is on, within a cohort.

At the base terms a $60,000 coin at 1.475× is a Purchase Price of $88,500. contract.rs::ContractTerms::schedule divides it into 60 payments quantized to cents toward zero, the last absorbing any residual; here every payment is exactly $1,475.00. Payment 1 goes to BTC Now; each later payment splits $73.75 to BTC Now and $1,401.25 to the Holder, who paid $60,000 at par.

Behavior

Who stops, who completes early, and how the price bends both. The monthly order is fixed in engine.rs::run: (1) scheduled payments, with the rational boundary’s decision before each; (2) walks armed at an earlier date, then the conviction streaks; (3) early completions; (4) the hazard draws. Who stops paying derives the hazards and the modes. The bracket a Holder runs is #7 alone, then #23, #9 and #25 (spec §1, row 25).

The three variants of defaults.rs::DefaultScenario:

The validation messages above retain the phrase “the final payment date cannot default”. This refers to the absence of a new hazard draw after the final payment, not to immunity of that receipt: a draw after payment term−1 can miss the final payment, as can a walk decided before it.

Book and pacing

The base book is 24 × 10 = 240 Agreements.

The stop

After a missed payment, day 16 is the Stop Date, the coin is sold for dollars within two business days, and the proceeds pay by the ruled waterfall (Marc, 2026-08-22 and 2026-09-03; spec v1.5 change 1). Three inputs shape the sale; The stop waterfall derives the rest.

At the base lag the sale sits \( 18 / 30.4375 = 0.591 \) of the way from the missed date’s mark to the next, and the cash posts one month after the missed date. Worked at the base terms, with the coin at $60,000 when sold and 12 payments made: proceeds \( V = 60{,}000 \times (1 - 0.0025) = 59{,}850.00 \); paid in \( A = 12 \times 1{,}475 = 17{,}700 \); Purchase Price \( P = 88{,}500 \); refund \( \min(A, \max(0, V + A - P)) = \min(17{,}700, \max(0, -10{,}950)) = 0 \); the Holder is delivered $59,850.00 less 5% ($2,992.50), net $56,857.50; shortfall \( R - V = 70{,}800 - 59{,}850 = 10{,}950.00 \) (engine.rs::stop_sale).

The overlays

Multiplicative overlays applied to the generated path before the run starts, the shock first (engine.rs::run). Neither changes the seed’s draws.

The rational boundary

Input #25 (spec v1.6 change 6) is the fifth behavior mode: a Buyer whose coin sits below the computed walk-away frontier for the payment date does not pay; the walk is the missed payment, settled like any stop with the exit tag RationalBoundary. The frontier is computed once per run by boundary.rs::rational_frontier from cohort-1 terms and is scale-invariant in the strike, so it serves every Agreement, dispersed strikes included. engine.rs::run reads frontier[t − 1] before payment \( t \) as a fraction of the entry price and compares spot with that fraction times the Agreement’s strike. The risk desk derives the lattice.

One more check runs inside boundary.rs::rational_frontier: if \( \lvert \mu \rvert \sqrt{\Delta} \) exceeds \( \sigma \), with \( \Delta = 1/48 \) of a year (the lattice takes four price steps a month), the branch probability leaves \( [0, 1] \) and the run fails with rational boundary (input #25): |mu|·√Δ exceeds sigma — raise sigma or lower |mu|. The defaults are boundary.rs::BoundaryParams::default; the object is validated by boundary.rs::BoundaryParams::validate, called from engine.rs::validate and again by the frontier.

The seed

The Risk desk request

POST /api/forwardflow/risk takes a config plus six options of forwardflow_api.rs::RiskRequest, shaping exposure.rs::exposure_report (the two lines, coverage, the exposure ladder, PD·LGD·EAD per vintage, the Greeks) and a frontier family. A config error surfaces as above; the option errors are listed here.

forwardflow_api.rs::HEAVY admits three risk, Monte Carlo, heatmap or backtest requests at a time.

The Monte Carlo request

POST /api/forwardflow/montecarlo and the WebSocket GET /api/forwardflow/montecarlo/ws take forwardflow_api.rs::MonteCarloRequest: a config and runs (spec input #14, “Monte Carlo runs”). Run \( i \) is the config with seed \( + i \); on a bridge that is the same endpoints redrawn, endpoint-pinned by design (spec §9, question 4). Outputs covers the percentiles.

Identical requests, keyed on (runs, the config’s JSON), are memoized in a 64-entry LRU (forwardflow_api.rs::MC_CACHE), sound because the engine is seeded. The WebSocket variant runs chunks of 1,000 (forwardflow_api.rs::MC_CHUNK) with a Progress frame per chunk.

Connect an AI assistant

Ask questions in your own words. Your assistant uses ForwardFlow to run the model on BTC Now’s server and explain the results. No ForwardFlow account or model installation is needed.

1. Request your access token

Email info@btcnow.com with your name, organisation and the AI client you want to use.

BTC Now will arrange access and send your token privately. Keep it in your client’s connection settings, not in the chat. Each invited person or organisation receives its own token.

2. Connect your assistant

Choose your setup guide:

• ChatGPT desktop — fill in the connection fields in the app.
• Codex CLI or IDE — use the shared local MCP configuration.
• Claude Code — save the connection from your terminal.

ChatGPT web and other connection options.

3. Ask your first question

Use ForwardFlow to help me frame an analysis. I want to understand the Holder’s return from Agreements. Ask me only the missing questions, then explain the assumptions before calculating.

The assistant should establish whether you want USD growth or BTC growth compared with holding the same contributed BTC, and what you want to compare. It asks up to three short questions at a time and should keep answers you already gave. If you do not know a technical assumption, it can propose an explicit illustrative starting case and test how the answer changes when that assumption changes.

Before calculating, the assistant shows the objective, capital basis, horizon and main assumptions. ForwardFlow checks the prepared request and supplies the calculation inputs. The assistant then uses the engine’s results, including warnings and unavailable metrics, to explain the answer. A prepared request does not certify the assumptions or establish investment suitability.

Once the first case is clear, try:

Compare that with Bitcoin falling 40% in month six and staying lower. Keep the other assumptions the same. What changes for the Holder?

An Agreement represents one contractual BTC. A question about a fixed wallet with reserves, reinvestment or daily margin requires a different portfolio model; ForwardFlow cannot silently treat a 100 BTC wallet as 100 Agreements. The connection supplies tools, an analyst guide and an optional starter prompt. It does not install a skill in your assistant.

Need help?

Email info@btcnow.com. If the service is busy, wait and try again; invited users share the server’s computing capacity.

Explore the model’s assumptions · Technical reference

Compare hedge risk

Ask: “Compare my hedge variants with unhedged on matching simulations. Show dollar and coin losses, worst-5% loss, and the cash needed before protection pays. Explain the market-path assumptions and test another seed sample.”

The hedge_risk_samples tool supplies the observations. It returns at most 32 simulations per call, or 8 with monthly detail. Combine raw observations from non-overlapping seed batches only when the assumptions, valuation seed, engine build and historical-data identity match. Cash is a monthly screen; daily collateral calls and forced closure are not simulated. Read the comparison guide.

Choose Dollar or Coin

Tell your assistant which outcome matters: grow USD capital or grow BTC compared with holding the same contributed BTC. Both use the same MCP connection and access token. For example: “Use Coin. Compare the current hedge against unhedged Agreements and holding BTC. Show BTC surplus, the chance of ending below holding, and USD cash needs separately.” The assistant should confirm the objective before judging which strategy is better. How the holding comparison works.

Connect with ChatGPT desktop or Codex

Use the ChatGPT desktop app to ask ForwardFlow questions in plain English. The model runs on BTC Now’s server. Codex CLI and IDE users can use the configuration option below. ChatGPT in a browser has a separate setup.

You need a ForwardFlow access token. Request one from info@btcnow.com; BTC Now will send it privately. No ForwardFlow account is needed.

1. Add the connection

In ChatGPT desktop, open Settings → MCP servers → Add server. Fill in:

Replace YOUR_ACCESS_TOKEN with your token, keeping the space after Bearer. Paste it into the header value, not into a chat message.

Leave Bearer token env var and Headers from environment variables empty. Those fields are for a different setup.

Select Save. The connection and token stay saved on this computer; keep its configuration private.

2. Check that it connects

Select Restart when prompted. Open a chat and enter:

/mcp

Check that forwardflow is connected and enabled. Review any permission request to use its tools.

3. Ask your first question

Use ForwardFlow to run the base case. Explain the assumptions and the Holder’s return and cash flows in plain English. Include any warnings from the model.

ChatGPT should use the ForwardFlow tools to calculate the answer. Then try:

Compare that with Bitcoin falling 40% in month six and staying lower. Keep the other assumptions the same. What changes for the Holder?

Need help?

Email info@btcnow.com. Do not include your token in the message or a screenshot.

Codex CLI and IDE

Local ChatGPT desktop, Codex CLI and IDE clients share MCP configuration on the same Codex host. A connection saved there does not need to be added again for each client.

If configuring Codex directly, add this entry to your user configuration, normally ~/.codex/config.toml, replacing the placeholder privately:

[mcp_servers.forwardflow]
url = "https://btcnow-forwardflow.fly.dev/mcp"
http_headers = { Authorization = "Bearer YOUR_ACCESS_TOKEN" }

Restart the client. In Codex CLI, use /mcp to check the connection. This service uses the supplied token; codex mcp login is for OAuth servers and is not needed here. Environment-based credentials are also supported, but the variable must exist in the environment of the host running the client.

Setup checked against OpenAI’s MCP documentation on 14 September 2026. Back to AI connections.

Connect with Claude Code

You need Claude Code installed and a ForwardFlow access token. Request your token from info@btcnow.com; BTC Now will send it privately.

This guide is for Claude Code in your terminal.

1. Save the connection once

Copy the block for your terminal and run it. When asked, paste your token and press Enter. It stays hidden while you type.

macOS using zsh (the default shell):

{
  read -rs 'ffAccessToken?ForwardFlow access token: '
  echo
  claude mcp add --transport http \
    --header "Authorization: Bearer $ffAccessToken" \
    --scope user forwardflow https://btcnow-forwardflow.fly.dev/mcp
  unset ffAccessToken
}

{
  read -rsp 'ForwardFlow access token: ' ffAccessToken
  echo
  claude mcp add --transport http \
    --header "Authorization: Bearer $ffAccessToken" \
    --scope user forwardflow https://btcnow-forwardflow.fly.dev/mcp
  unset ffAccessToken
}

& {
  $ffAccessToken = Read-Host 'ForwardFlow access token' -AsSecureString
  $ffTokenValue = [System.Net.NetworkCredential]::new('', $ffAccessToken).Password
  claude mcp add --transport http --header "Authorization: Bearer $ffTokenValue" --scope user forwardflow https://btcnow-forwardflow.fly.dev/mcp
  Remove-Variable ffAccessToken, ffTokenValue
}

The options precede the server name, as required by Claude Code. --scope user saves this connection outside the project in your user configuration. The token is stored on this computer; keep that configuration private. You do not need to enter it each time you open Claude Code.

2. Open Claude Code

Start a new session:

claude

Enter /mcp, select forwardflow and check that it connects. Review any tool-permission request from Claude Code.

3. Ask a question

Use ForwardFlow to help me frame an analysis. I want to understand the Holder’s return from Agreements. Ask me only the missing questions, then explain the assumptions before calculating.

Claude should establish Dollar or Coin, the comparison and the capital basis, asking at most three missing questions at a time. If you do not know a technical assumption, ask for a labelled illustrative starting case and a sensitivity. Claude should show the prepared assumptions before calling the calculation tool. The calculations run on BTC Now’s server; check that Claude uses the ForwardFlow tools when reporting model numbers.

For an optional guided start, type / and choose /forwardflow:start_analysis (MCP), or enter:

/mcp__forwardflow__start_analysis

Then state your question in ordinary language. This server prompt takes no arguments. It supplies the same analyst guidance available through describe_model and the MCP resource forwardflow://guides/analyst-v1. These are server capabilities, not an automatically installed Claude skill. If the prompt is not listed, restart Claude Code and check /mcp; asking in ordinary language still works. How Claude Code discovers MCP prompts.

Need help?

Email info@btcnow.com. Never include your token in the message or a screenshot.

claude mcp remove --scope user forwardflow

Setup follows Anthropic’s MCP documentation, checked 14 September 2026. These commands configure Claude Code; they do not add a connection to Claude’s web app. Model tools and result details.

API reference

The engine is a Rust crate. Everything a desk sees of it goes through one small Axum server, backend/src/main.rs, and one module, backend/src/api/forwardflow_api.rs. The server has no saved-run database: requests supply assumptions and receive results. It retains bounded computation caches and access-limit state. The workspace calls these calculations and derives display summaries and independent checks from the responses. The MCP interface exposes a bounded subset for assistants.

This chapter documents each route: method, path, request body field by field, response body field by field, a curl that was actually run against http://localhost:8080 on 2026-09-03 with its response trimmed, and the error semantics. It closes with the WebSocket protocol, client snippets in Python and TypeScript, the hosting notes and the result identity needed for reproduction. Examples dated 3 September 2026 are historical worked responses; consult the deployed OpenAPI schema for current field shapes.

Two conventions apply everywhere.

• Money travels as strings. Every ledger amount is a cent-quantized Decimal and serializes as a JSON string ("1475.00", "0.05"). Ratios, moneyness, IRRs and statistics are f64 and serialize as JSON numbers. The split is deliberate: nothing that posts to the ledger is ever a float.
• Same numerical request, same build. The engine is seeded (ChaCha20, seed in the configuration). Repeat numerical requests against the same build, historical data and runtime environment for deterministic reproduction; headers, timing and progress metadata are not the calculation. The Monte Carlo memoization below depends on this.

The configuration object, SimConfig, is the same for every POST route. Its fields are documented one by one in Every input; this chapter names them only where a route treats them specially.

The server

main.rs calls lib.rs::build_router, sizes the rayon pool to max(1, cores − 1) so the async accept loop is never starved by a Monte Carlo, wraps the routes in gzip compression and a CORS layer configured by FF_CORS_ORIGINS, and listens on 0.0.0.0:8080.

The additional pricing and hedge requests are documented in Surfaces and hedging and the API explorer. MCP uses /mcp on the engine and is a separate protocol.

“Heavy” means the route takes a permit from forwardflow_api.rs::HEAVY, a three-permit semaphore. At most three heavy calculations run at once and eight may wait in the compute queue. Capacity refusals return 503 with Retry-After. Executed requests also reserve memory from the shared process budget.

simulate, solve_price and placement take this guard when their estimate exceeds 1,000,000 Agreement-runs or 128,000,000 bytes at peak. Their current book caps cannot reach the count threshold, but the byte threshold can apply, including to detailed simulation responses. Request flags therefore matter to admission; the raw engine book estimate is not the complete response estimate.

Choose the reporting objective

simulate can include the complete unhedged USD/BTC observation with include_research: true. Use hedge_research with an explicit objective: "coin" or "dollar" for paired simulations. Legacy Dollar-only routes, including solve_price and montecarlo, accept an omitted objective for compatibility or an explicit "dollar"; an explicit Coin, null or unrecognized objective is refused. A Dollar purchase-price solution is not a BTC target return. There is no BTC purchase-price solver.

Detailed simulation requests reserve memory for their selected postings, Agreement rows, research arrays and JSON output as well as the underlying engine book. Serialization is bounded, and the reservation stays with the response through compression and transmission. Large output requests can be refused before calculation; request fewer Agreements or omit detail you do not need. This is a resource limit, not a change to Agreement economics.

Errors and caps

The engine validates its inputs with named assertions in engine.rs::validate. A failed assertion panics with a message that names the input; forwardflow_api.rs::catch_engine catches the panic and returns it as HTTP 400 with the message as the body. This is why the build must never set panic = "abort": the 400 depends on unwinding.

$ curl -s -i -X POST localhost:8080/api/forwardflow/simulate \
    -H 'Content-Type: application/json' -d @bad.json   # term_months: 1700
HTTP/1.1 400 Bad Request
term (input #6) must be 1–480 months, got 1700

A PathError from paths.rs also maps to 400. Asking for a historical replay that runs off the end of the series:

HTTP/1.1 400 Bad Request
historical replay needs 85 months from index 170, have 4

A missing field or wrong JSON value type normally returns 422 before reaching the engine. Invalid JSON syntax returns 400; a missing Content-Type: application/json returns 415. An explicitly unsupported objective also returns 400. A bounded simulation response that cannot fit its declared serialization allowance returns 413; internal failures can return 500. Read the response message rather than treating every 400 as an economic-input error or every 500 as a blocking-task failure.

The caps, all of which answer 400 with the input named (hosting hardening, spec v1.4 item 13, 2026-07-13):

The 24 million Agreement-run ceiling is the 100,000-run Monte Carlo at the base 240-Agreement book, and since the audit of 2026-09-05 (finding 8) every route estimates its work in that unit before it takes a thread — simulate = book, montecarlo = book × runs, solve_price = book × 2, heatmap = book × cells, backtest = agreements_per_cohort × vintages, risk = book × (1 + 7 × greek_seeds), placement = book, fair_value = book × seeds, hedge = book × seeds × Σ structure units (+ 2 with the benchmarks), rebalance_policies = book × seeds × structure units × policies, coin_seat = book × seeds × (Σ structure units + 1) × drifts, hedge_series = book × (seeds × structure units + the Greeks’ runs when include_greeks) — to bound estimated work before execution. hedge_research uses the hedge estimate without the legacy shelf benchmarks, then adds 2 × book × seeds for paired cash and coverage, plus response-memory allowances. The estimate is not a runtime guarantee. A refusal names the estimate, the formula with the inputs’ values and the inputs to lower.

GET /health

Returns the text OK with status 200 for a liveness check. Deployment verification uses /api/forwardflow/health to check the running version, source build, data digest and access mode as well.

POST /api/forwardflow/simulate

One run of the engine on one seeded path. Handler: forwardflow_api.rs::ff_simulate.

Request

Response

The optional research observation uses research.rs::unhedged_observation on the existing simulated book; it does not run another path. It equals hedge_research.samples[0].unhedged for matching configuration, seed and zero USD discount rate. It always includes monthly spot, paper_cash, hedge_cash, margin, hedge_cash_required and total_cash_required; hedge and margin values are zero. npv_usd uses zero discounting and equals net_gain_usd. The BTC holding comparison retains matching dated net contributions; it is a monthly-conversion equivalent, not a funded wallet balance. USD cash assumes receipts remain in dollars. Agreement rows and raw postings can both be omitted independently. Invalid non-finite BTC conversions are refused with 400, using the same guards as paired research.

RunOutputs (outputs.rs::RunOutputs, computed by outputs.rs::analyze):

The exit vocabulary in the JSON is the engine’s: non_performance is a stop, settled is an early completion. Identifiers were kept when the words were locked (Marc, 2026-09-02, spec v1.5).

AgreementRow (outputs.rs::AgreementRow, built by outputs.rs::agreement_table):

A posting (ledger.rs::Posting) has month, from, to, amount, kind, agreement. Entities are "Owner" (the Holder), "BtcNow", "Market" and {"Obligor": id} (the Buyer). Kinds are PurchasePrice, OriginationFee, PaymentDelivery, FlowFee, MakeWholeDelivery, StopSaleDelivery, StopRefund.

Example. One Agreement at the base terms, run clean so the schedule can be read off: a $60,000 coin, 1.475×, 60 payments of $1,475, payment 1 to BTC Now, 5% on every delivered dollar, the Holder buys at par. The configuration is BASE_CONFIG from lib.ts with vol_annual: 0, lifetime: 0, settlement_propensity: 0, cohorts: 1, agreements_per_cohort: 1 and intramonth_strike_dispersion: false.

The response excerpt below requests both include_postings: true and include_agreements: true alongside that configuration.

$ curl -s -X POST http://localhost:8080/api/forwardflow/simulate \
    -H 'Content-Type: application/json' -d @one.json
{
  "outputs": {
    "irr_effective_pa": 0.139654410356713,
    "wal_months": 31.0,
    "payback_month": 44,
    "undiscounted_multiple": 1.3778958333333333,
    "owner_total_inflow": "82673.75",
    "owner_total_outflow": "60000.00",
    "exit_split": { "completed": 1, "settled": 0, "non_performance": 0, "…": 0 },
    "btcnow": { "origination_fees": "1475.00", "flow_fees": "4351.25",
                "total_take": "5826.25", "purchase_prices": "60000.00", "paper_spread": "0.00" },
    "…": "…"
  },
  "agreements": [ { "id": 0, "outcome": "completed", "exit_month": 60, "payments_made": 60,
                    "delivered_gross": "87025.00", "owner_net": "82673.75",
                    "fee_to_btcnow": "4351.25", "origination_to_btcnow": "1475.00",
                    "capital_pnl": "22673.75", "…": "…" } ],
  "agreement_count": 1,
  "conservation_ok": true,
  "postings": [
    { "month": 0, "from": "Owner", "to": "BtcNow", "amount": "60000.00", "kind": "PurchasePrice", "agreement": 0 },
    { "month": 1, "from": { "Obligor": 0 }, "to": "BtcNow", "amount": "1475.00", "kind": "OriginationFee", "agreement": 0 },
    { "month": 2, "from": { "Obligor": 0 }, "to": "Owner", "amount": "1401.25", "kind": "PaymentDelivery", "agreement": 0 },
    { "month": 2, "from": { "Obligor": 0 }, "to": "BtcNow", "amount": "73.75", "kind": "FlowFee", "agreement": 0 },
    "… 116 more"
  ]
}

Payments 2 to 60 deliver $1,401.25 to the Holder and $73.75 to BTC Now each; 59 × $1,401.25 = $82,673.75, and 59 × $73.75 + $1,475 = $5,826.25. The full base book (24 cohorts × 10 Agreements, 43% bridge, 40% lifetime stop share, seed 42) returns irr_effective_pa 0.1421, exits 84 completed / 55 early / 101 stopped, total_shortfall_usd 990,282.37, buyer_refunds_usd 603,951.54 and stop_surplus_usd 148,595.85. That body is 111,692 bytes raw, 17,500 gzipped, 2,547 gzipped with include_agreements: false.

POST /api/forwardflow/montecarlo

runs seeded runs with seeds seed, seed + 1, …, seed + runs − 1 (outputs.rs::run_monte_carlo, in parallel), summarized. Handler: forwardflow_api.rs::ff_monte_carlo.

Request: config (SimConfig) and runs (int, 1 – 100,000, subject to the Agreement-run cap).

Response (MonteCarloSummary):

Percentiles carries worst, p1, p3, p5, p25, p50, p75, p95, mean, es3, es5. In forwardflow_api.rs::percentiles, over the sorted sample of size \( n \), a percentile is the nearest-rank value

\[ x_{(i)},\quad i = \operatorname{round}\big(p,(n-1)\big), \]

and the expected shortfall is the mean of the worst \( \lceil p,n \rceil \) runs (at least one):

\[ \mathrm{ES}p = \frac{1}{k}\sum{j=1}^{k} x_{(j)},\quad k = \lceil p,n \rceil . \]

p3 is the empirical third percentile, not a worst-case guarantee; es3 and es5 are what you average if you land in the tail, not where the tail starts.

Memoization. Results are cached in forwardflow_api.rs::MC_CACHE, an LRU of 64 summaries keyed by runs plus the serde serialization of the configuration. The key is built server-side from the struct, so a client’s JSON key order does not matter. The base book at 1,000 runs took 0.30 s cold and 0.006 s memoized.

$ curl -s -X POST http://localhost:8080/api/forwardflow/montecarlo \
    -H 'Content-Type: application/json' -d '{"config": <BASE_CONFIG>, "runs": 1000}'
{
  "runs": 1000,
  "irr_effective": { "worst": 0.0721, "p1": 0.0918, "p3": 0.0970, "p5": 0.1029, "p25": 0.1291,
                     "p50": 0.1493, "p75": 0.1722, "p95": 0.2190, "mean": 0.1538,
                     "es3": 0.0903, "es5": 0.0946 },
  "wal_months": { "p5": 34.48, "p50": 35.91, "p95": 37.34, "…": "…" },
  "pct_negative_irr": 0.0,
  "irr_histogram": [ [0.0721, 3], [0.0777, 2], "… 48 more" ],
  "cash_fan": [ "…", { "month": 84, "p5": 2288927.49, "p50": 4529348.68, "p95": 8948182.21, "…": "…" } ],
  "base_seed": 42
}

The bridge is endpoint-pinned, so this distribution is the uncertainty between $60,000 and $60,000, not a view on where the price ends. The archived Model Card’s pricing stance uses the zero-drift bootstrap instead; see Price paths.

Unavailable IRR statistics are null

A path whose flows never change sign (every payment retained by BTC Now, a written call assigned deep in the money) has no IRR, and since the follow-up audit of 6 September 2026 (finding 1; spec v1.12) no route prints a zero for one. Here irr_effective and pct_negative_irr are null when no run has an IRR; on the hedge routes (/hedge, /hedge_series, /rebalance_policies, /coin_seat) every Dist’s median_irr, mean_irr, p5_irr, p95_irr and pct_negative are null when no seed has one (the coin seat’s pct_negative is over all seeds and stays present), and the figures derived from a missing median or p5 — HedgeResult.cost_irr_points, floor_p5_irr, hedged_excess_over_basis_pp — are null with it. What is always present is the cash: pct_cash_loss, the multiples, seeds_with_irr / seeds_without_irr and without_irr_reasons. The audit’s zero-receipts probe (12 of 12 payments to BTC Now, eight seeds) reads median_irr null … pct_cash_loss 1.0, seeds_with_irr 0, single_signed 8; tests/openapi_shapes.rs holds every nullable field documented as such in openapi.json. A client should read the count before the statistic, and the cockpit does (reading.ts: “—”, with the reason).

The engine’s identity travels with every answer

Every response carries X-Engine-Spec, X-Engine-Version, X-Engine-Build (0.7.0+v1.14+<sha>: crate version + spec + the source revision build.rs stamps from GIT_SHA or git rev-parse, else unknown) and X-Engine-Data (the SHA-256 of the compiled-in price series; model audit 2026-09-06, M07); the browser WebSocket API does not expose handshake headers, so Monte Carlo also puts the identity on its Complete frame as engine; /api/forwardflow/health reports them as engine_spec, version, build, git_sha and data_sha256. A desk that records a completed run should take the identity off that answer, never off a global “last response” — the cockpit’s record builders do (record.ts, spec v1.12 item 4). See The version headers.

GET /api/forwardflow/montecarlo/ws

The same computation over a WebSocket, in chunks of 1,000 runs (forwardflow_api.rs::MC_CHUNK), so a heavy book neither times out nor looks dead. Handler: forwardflow_api.rs::handle_mc_socket.

Protocol. The client’s first text frame is the MonteCarloRequest JSON, exactly the REST body. The server then sends text frames, each a JSON object with an event field:

A request already in the memo cache skips straight to Complete. If the client disconnects, the server stops after the current chunk. The heavy permit is taken per chunk, not per request, so a long Monte Carlo yields to other work between chunks. A transcript from a Node client (WebSocket is global in Node 22+), base book, seed 4242 to miss the cache, 3,000 runs:

{"done":1000,"event":"Progress","pct":33,"total":3000}
{"done":2000,"event":"Progress","pct":66,"total":3000}
{"done":3000,"event":"Progress","pct":100,"total":3000}
{"event":"Complete","summary":{"runs":3000,"base_seed":4242,
  "irr_effective":{"p5":0.1024,"p50":0.1494,"es5":0.0933,"…":"…"},"pct_negative_irr":0,"…":"…"}}

and the two error shapes:

{"event":"Error","message":"runs must be 1–100000 (input #14)"}
{"event":"Error","message":"expected ident at line 1 column 2"}

POST /api/forwardflow/solve_price

The inverse of the deal card (input #19): given a target effective annual IRR and the client’s own configuration, the purchase price at which the paper returns exactly that rate. outputs.rs::solve_purchase_price solves it directly — the Holder’s receipts do not depend on the price paid, so the price is the present value of the net receipts at the target rate over the present value of the strikes at their origination months, from one prepared run on the configuration’s seed — and verifies it with a second run (see The inverse price solver).

Request: config and target_effective_irr (number, e.g. 0.12; must lie in (−0.9, 10)).

Response: pct_of_strike (string, eight decimals; null only when the Holder receives nothing), usd_at_start_price (number, the fraction × start_price, or null), target_effective_irr echoed, irr_check (the verifying run’s effective IRR at that price), attainable (true when the price lies inside the desk’s 1%–500% bracket and the check agrees within a basis point) and note (the method, or why the target is not attained — the bracket edge it lies beyond, or nothing received).

$ curl -s -X POST http://localhost:8080/api/forwardflow/solve_price \
    -H 'Content-Type: application/json' -d '{"config": <BASE_CONFIG>, "target_effective_irr": 0.12}'
{"pct_of_strike":"1.03835638","usd_at_start_price":62301.3828,"target_effective_irr":0.12,"irr_check":0.12000000467405858,"attainable":true,"note":"the present value of the Holder's net receipts at the target rate (monthly compounding of the effective annual target) over the present value of the strikes at their origination months, from one prepared run; verified by a run at that price"}

At a 12% hurdle the base book clears at 103.7% of the coin’s cost, $62,220.60 on a $60,000 coin. The clean single Agreement of the simulate example clears at 104.15%, $62,491.80.

POST /api/forwardflow/heatmap

A sensitivity grid: every cell is a full deterministic run on the configuration’s seed, cells computed in parallel (M4, spec v1.3). Handler: forwardflow_api.rs::ff_heatmap. The request carries config plus a flattened GridSpec selected by grid:

Response: cells[row][col], the effective annual IRR, or null where the run is undefined or the cell fails validation. A bad cell is a hole, never a 400, because the rest of the map is still information. Grids are capped at 900 cells.

$ curl -s -X POST http://localhost:8080/api/forwardflow/heatmap -H 'Content-Type: application/json' \
    -d '{"config": <BASE_CONFIG>, "grid": "PriceDefault", "end_prices": [30000,60000,90000], "lifetimes": [0.2,0.4,0.6]}'
{"cells":[[0.1360,0.1459,0.1547],[0.1224,0.1421,0.1578],[0.0999,0.1298,0.1525]]}

The centre cell, 40% and $60,000, is the base run’s 0.1421 exactly. Read across for the price, down for the stops; the break-even frontier is the IRR = 0 contour on a wider grid.

POST /api/forwardflow/backtest

The static-pool vintage exhibit: one cohort originated at every fully seasoned historical month, each replayed against the actual price path that followed, all by the same engine. Handler: forwardflow_api.rs::ff_backtest.

Request: config only. path, cohorts and origination_stop_month are overridden per vintage (HistoricalReplay { start_index }, 1, none); everything else, including agreements_per_cohort as the units per vintage, is the sensitivity set. The replay is rebased so month 0 equals start_price, which keeps dollar figures comparable across vintages.

A vintage is seasoned when term + 1 months of history follow it (the extra month lets a stop at the last age settle, spec v1.5 item 4). With 174 monthly bars, February 2012 to July 2026, and a 60-month term, that is 113 vintages, February 2012 to June 2021.

Response: vintages (VintageRow[]), blended_net_gain_usd, blended_deployed_usd, blended_moic (every vintage bought at equal size), failed (vintages the engine rejected; holes, not a 400).

VintageRow:

$ curl -s -X POST http://localhost:8080/api/forwardflow/backtest -H 'Content-Type: application/json' \
    -d '{"config": <BASE_CONFIG>}'
{ "vintages": [ "…", { "month": [2021, 6], "start_index": 112, "entry_close": 35026.9,
    "irr_effective_pa": 0.1729, "moic": 1.3697, "net_gain_usd": 219143.32, "deployed_usd": 592714.83,
    "shortfall_usd": 28602.45, "completed": 6, "settled": 0, "non_performance": 4,
    "buyer_refund_usd": 46994.76, "stop_surplus_usd": 23506.44, "btcnow_take_usd": 57300.22, "…": "…" } ],
  "blended_net_gain_usd": 138206160.2, "blended_deployed_usd": 66412793.69, "blended_moic": 3.081, "failed": 0 }

The early vintages dominate the blend: a 2012 entry at $4.90 rebased to $60,000 rides the whole rally. Read the rows, not the blend, and see Limits on survivorship in a one-asset history.

GET /api/forwardflow/history

The embedded monthly bars (paths.rs::historical_months, paths.rs::historical_closes, compiled in with include_str!; no data files at runtime). Response: months ([year, month][]) and closes (number[]), 174 each, [2012, 2] to [2026, 7]; the first close is 4.9, the last 62,875.5, the highest 115,765. The cockpit uses it to label replay start months and to grey out the ones without enough remaining history.

POST /api/forwardflow/risk

The exposure layer (spec v1.6, Marc’s “start”, 2026-09-03): the two lines, coverage by month and by cohort, the exposure ladder at a month, PD·LGD·EAD per vintage, the Greeks by bump-and-revalue, and the rational frontier for a family of believed drifts. Handler: forwardflow_api.rs::ff_risk; the report is exposure.rs::exposure_report, the frontier boundary.rs::rational_frontier. The derivations are in The risk desk; this section is the wire format.

Request

Response. The ExposureReport fields are flattened to the top level, then frontiers and frontier_params.

lines (LineRow[], one per payments made, t = 0 to term, from exposure.rs::two_lines, scale-invariant in the coin’s cost so one table serves the book):

With \( U_t = \max(0,\ \text{purchase} - \text{net received}) \), \( R_t \) the remaining schedule, \( A_t \) the payments made and \( f \) the fee, exposure.rs::capital_proceeds_needed gives

\[ V^{\text{cap}}_t = \begin{cases} U_t/(1-f) & \text{if } U_t/(1-f) \le R_t \\ A_t + U_t/(1-f) & \text{otherwise,} \end{cases} \]

because between \( R_t \) and the Purchase Price the Holder is delivered exactly \( R_t(1-f) \) and the rest refunds the Buyer. At the base terms the lines read 1.475 / 1.0526 at \( t = 0 \), 1.4504 / 1.0526 at \( t = 1 \), 0.885 / 0.4872 at \( t = 24 \), and the capital line is zero from \( t = 44 \).

coverage (CoveragePoint[], one per calendar month): month, spot, active, below_schedule, below_capital (active Agreements whose sale at this month’s price, haircut and sale cost applied, would not cover the line), notional_usd (Σ remaining schedule), capital_at_risk_usd (Σ unrecovered capital), intrinsic_shortfall_usd. active counts the price-exposed Agreements (engine.rs::price_exposed_at, the one lifecycle the hedge desk and the monthly mark read too): a stopped Agreement stays on the panel until the month its sale is booked, round(D + lag/30.4375) — the month after the missed date at the program’s 18 days, three months on at 90.

coverage_by_cohort (CohortCoverage[]): origination_month, agreements, months_below_schedule and months_below_capital (mean per Agreement), share_below_schedule and share_below_capital (share of active Agreement-months).

ladder (Ladder): month, spot, active, total_notional_usd, total_capital_at_risk_usd, and 30 cells, one per moneyness bucket (< 0.50, 0.50–0.70, 0.70–0.85, 0.85–1.00, 1.00–1.20, ≥ 1.20, sale proceeds ÷ remaining schedule) × tenor bucket (≤ 6 mo, 7–12 mo, 13–24 mo, 25–36 mo, > 36 mo), each with agreements, notional_usd, capital_at_risk_usd. The bucket labels are the moneyness and tenor strings above, verbatim.

credit (CreditRow[], one per vintage and a book row last with origination_month: null): agreements, stops, completed, completed_early, pd (stops ÷ Agreements), ead_usd (mean remaining schedule at the stop), lgd (Σ shortfall ÷ Σ remaining schedule at the stop), el_usd (Σ shortfall), el_rate (÷ capital deployed), capital_loss_usd (Σ negative capital P&L on stops), deployed_usd, refunds_usd, surplus_usd. The book row’s el_usd equals the simulate response’s total_shortfall_usd.

greeks (Greeks, from exposure.rs::greeks):

Delta is the central difference over the seed ensemble,

\[ \Delta = \frac{1}{n_s}\sum_{s} \frac{G_s(1+b) - G_s(1-b)}{2 \cdot 100,b}, \]

with \( b \) the price bump; every Agreement draws from its own seeded stream, so the difference is the bump’s alone.

frontiers (FrontierFamily[]): for each mu_annual, rows (FrontierRow[], one per payment): m (row index, payment − 1), payment, walk_below_spot, walk_below_of_entry, walk_below_moneyness (the boundary below which walking is optimal, in dollars, as a fraction of entry, and as spot ÷ amortized obligation; null when no lattice node walks), remaining_obligation, remaining_schedule. frontier_params echoes the lattice parameters used.

$ curl -s -X POST http://localhost:8080/api/forwardflow/risk -H 'Content-Type: application/json' \
    -d '{"config": <BASE_CONFIG>}'
{
  "lines": [ { "t": 0, "schedule_line": 1.475, "capital_line": 1.0526, "capital_above_purchase_price": false,
               "remaining_schedule_usd": 88500.0, "unrecovered_capital_usd": 60000.0 }, "… 60 more" ],
  "coverage": [ "…", { "month": 12, "spot": 30126.08, "active": 123, "below_schedule": 123, "below_capital": 117,
                       "notional_usd": 6876400.20, "capital_at_risk_usd": 4542958.33, "intrinsic_shortfall_usd": 3180156.59 }, "…" ],
  "coverage_by_cohort": [ "… 24 rows" ],
  "ladder": { "month": 23, "spot": 33375.25, "active": 203, "cells": [ "… 30 cells" ], "…": "…" },
  "credit": [ "…", { "origination_month": null, "agreements": 240, "stops": 101, "completed": 84, "completed_early": 55,
                     "pd": 0.4208, "ead_usd": 43562.82, "lgd": 0.2251, "el_usd": 990282.37, "el_rate": 0.1029,
                     "capital_loss_usd": 230645.54, "deployed_usd": 9619863.62, "refunds_usd": 603951.54, "surplus_usd": 148595.85 } ],
  "greeks": { "as_of_month": 23, "as_of_spot": 33375.25, "seeds": 16, "base_net_gain_usd": 5072824.14, "base_irr": 0.1586,
              "delta_usd_per_pct": 23259.16, "delta_commitment_usd_per_pct": 24884.96, "delta_coins": 69.69,
              "gamma_usd_per_pct2": -175.64, "vega_usd_per_vol_point": 8631.36, "theta_usd_per_month": 127160.35,
              "delta_irr_pp_per_pct": 0.0910, "vega_irr_pp_per_vol_point": 0.0415, "base_vol_annual": 0.3941, "…": "…" },
  "frontiers": [ "…", { "mu_annual": 0.25, "rows": [ { "m": 0, "payment": 1, "walk_below_spot": 31270.64,
                   "walk_below_of_entry": 0.5212, "walk_below_moneyness": 0.5212, "remaining_obligation": 60000.0,
                   "remaining_schedule": 88500.0 }, "… 59 more" ] }, "…" ],
  "frontier_params": { "sigma_annual": 0.414, "mu_annual": 0.25, "r_c_annual": 0.15, "walk_cost_of_strike": 0.025 }
}

Two things to notice. The ladder month, left unset, came back as 23, the month of peak capital at risk, which on this path is also the last origination month; the existing-book delta and the commitment delta therefore coincide, since no cohort originates after the as-of month either way. And the base IRR in the Greeks (0.1586) is a 16-seed mean, not the seed-42 run’s 0.1421. The whole call took 0.05 s.

Connecting from your own code

The API is plain JSON over HTTP; no client library is needed. Python, standard library only:

import json, urllib.request

API = "http://localhost:8080"

def post(path, body):
    req = urllib.request.Request(
        f"{API}{path}", data=json.dumps(body).encode(),
        headers={"Content-Type": "application/json"}, method="POST")
    try:
        with urllib.request.urlopen(req) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"{e.code}: {e.read().decode()}") from None  # 400 carries the named input

config = json.load(open("base_config.json"))          # a SimConfig; Decimals as strings
run = post("/api/forwardflow/simulate", {"config": config, "include_agreements": False})
print(run["outputs"]["irr_effective_pa"], run["agreement_count"])

mc = post("/api/forwardflow/montecarlo", {"config": config, "runs": 1000})
print(mc["irr_effective"]["p5"], mc["irr_effective"]["es5"])

Parse the string fields with decimal.Decimal, not float, if you intend to re-add them; the ledger is exact to the cent and a float sum will not be.

TypeScript, the cockpit’s own client. web/app/forwardflow/lib.ts exports the types in this chapter (SimConfig, RunOutputs, AgreementRow, MonteCarloSummary, RiskResponse, and the rest) and an api object built on one helper:

const API = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8080";

async function post<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {
  const r = await fetch(`${API}${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal,
  });
  if (!r.ok) throw new Error(await r.text());   // the 400 body is the engine's message
  return r.json();
}

export const api = {
  simulate: (config, includePostings = false, opts?) =>
    post<SimulateResponse>("/api/forwardflow/simulate",
      { config, include_postings: includePostings, include_agreements: opts?.includeAgreements ?? true },
      opts?.signal),
  monteCarlo: (config, runs, signal?) =>
    post<MonteCarloSummary>("/api/forwardflow/montecarlo", { config, runs }, signal),
  monteCarloWs: (config, runs, onProgress) =>
    new Promise<MonteCarloSummary>((resolve, reject) => {
      const ws = new WebSocket(`${API.replace(/^http/, "ws")}/api/forwardflow/montecarlo/ws`);
      ws.onopen = () => ws.send(JSON.stringify({ config, runs }));
      ws.onmessage = (ev) => {
        const msg = JSON.parse(ev.data as string);
        if (msg.event === "Progress") onProgress(msg.pct as number);
        else if (msg.event === "Complete") { resolve(msg.summary); ws.close(); }
        else if (msg.event === "Error") { reject(new Error(msg.message)); ws.close(); }
      };
      ws.onclose = () => reject(new Error("closed before finishing"));  // a no-op once settled
    }),
  // solvePrice, heatmap, backtest, risk, history follow the same shape
};

Two habits the cockpit keeps and a client should copy: abort superseded requests through the AbortSignal, and pass include_agreements: false on any run that only reads scalars. The real monteCarloWs also guards against settling the promise twice; the excerpt drops that for length.

Hosting notes

• Where the client points. The workspace normally calls its same-origin /api/forwardflow/ proxy, which forwards to FF_API_URL and adds the server-held FF_API_KEY. NEXT_PUBLIC_API_URL explicitly bypasses that proxy for an open engine. The token route supplies the normal WebSocket URL and short-lived token; see Access.
• CORS. A 24-hour max-age, so the browser pays one preflight per route per day, not one per POST. With FF_CORS_ORIGINS unset any origin is allowed; the hosted engine lists https://ff.btcnow.com (see Access).
• Compression. CompressionLayer gzips every response the client accepts compressed; tiny bodies are skipped. Measured on the base book: 111,692 bytes raw, 17,500 gzipped, 2,547 gzipped and slim.
• Memoization. Identical Monte Carlo requests, REST or WebSocket, are served from the 64-entry LRU. This is sound only because the engine is seeded; a change that breaks determinism breaks the cache silently, which is one reason the invariant suite diffs golden outputs.
• Memory. The server uses jemalloc so freed pages return to the operating system after a Monte Carlo peak; the system allocator holds them.
• Concurrency. Three heavy permits, rayon on cores − 1 threads, the async runtime on the rest. A deploy that puts the server behind a proxy should allow WebSocket upgrades on /api/forwardflow/montecarlo/ws and a request timeout long enough for a 100,000-run Monte Carlo, or use the WebSocket for anything large.

Result identity and configuration fingerprints

The completed run package records the arguments and engine identity associated with the response. Preserve that package for reproduction, including endpoint-specific settings. A scenario edited later is not the completed request.

Some chart and CSV exports use export.ts::sha8: the first eight hex characters of SHA-256 over JSON.stringify(config). That fingerprint depends on property order and numeric/string representation; it does not encode the assumptions and cannot identify an engine build by itself. Keep the full request with any standalone exhibit.

MCP uses a separate canonical replay hash with recursively sorted keys. Its run_id is not interchangeable with sha8. See Verification and reproduction and MCP result metadata.

Access — keys, tokens, limits

The engine runs in one of two modes, decided once at start by the environment it reads (backend/src/access.rs::AccessConfig::from_env).

• Open mode — FF_API_KEYS unset or empty. Every /api/forwardflow/* route answers without a credential and the engine logs one warning at start, FF_API_KEYS unset — the API is open. A local cargo run --release is open when no keys are supplied.
• Keyed mode — FF_API_KEYS holds name:key,name:key, every key at least 24 characters. Every /api/forwardflow/* route requires a credential except three that stay open in both modes: GET /health, GET /api/forwardflow/health and GET /api/forwardflow/openapi.json. The hosted engine at https://btcnow-forwardflow.fly.dev runs keyed.

Two more variables complete the contract: FF_TOKEN_SECRET, an HMAC-SHA256 secret of at least 32 characters that enables the websocket token below (unset = tokens disabled), and FF_CORS_ORIGINS, comma-separated exact origins (unset = permissive).

The header

A desk authenticates with one header on every request:

X-API-Key: <key>

The same key can instead be sent as Authorization: Bearer <key>. Both REST and MCP accept these headers; sending both together is refused with HTTP 400. Invited parties need no ForwardFlow account or login. See the connection guide to request a token and choose a supported client.

The engine compares the presented key against every configured key in constant time (access.rs::name_for_key). Only the key’s name ever leaves the engine: it appears in the tracing log and is attached to authenticated responses as X-Key-Name. The key is never logged, never echoed and never part of an error.

Getting, keeping and revoking a key

Email info@btcnow.com to request access. BTC Now issues one named token per invited person or organisation and delivers it privately. No ForwardFlow account is needed. Keep the token in your client’s credential settings or a private server configuration.

To replace or revoke a token, contact BTC Now. The operator updates FF_API_KEYS and restarts or rolls every engine instance; removal takes effect for new requests on each restarted instance. There is no guaranteed one-minute revocation window. Already running work is not retroactively cancelled. The short-lived websocket token has its own expiry. See operator steps.

The limits

Keyed callers share REST and MCP allowances under the key’s name. Anonymous callers are counted by IP; explicit MCP open mode has a separate anonymous rate state. These counters and the compute/memory budgets live in each server process, so multiple machines do not form a distributed quota.

A dropped request or disconnected websocket requests cooperative cancellation at the next engine checkpoint. A single simulation may finish its current unit before its compute resources are released. Simulation response memory remains reserved while its serialized or compressed response bytes are still owned by the transport. The websocket also watches for disconnects while a chunk is running; a socket that sends no request within ten seconds of upgrading is closed.

Every estimate checks the configuration before computation. Requests must fit both their per-request peak ceiling (FF_MAX_ESTIMATED_BYTES, default 1.5 GB) and the free part of the shared process budget (FF_MEMORY_BUDGET_BYTES, 1.2 GB in fly.toml). A request that does not fit beside current work returns 503 with Retry-After: 5 and does not calculate. Detailed simulation flags add Agreement rows, postings and bounded response buffers to the estimate.

The per-key concurrency classification includes /mcp, montecarlo and its websocket, heatmap, backtest, risk, fair_value, hedge, hedge_research, hedge_series, rebalance_policies and coin_seat. It also includes simulate, solve_price and placement when their complete estimate exceeds 1,000,000 Agreement-runs or 128,000,000 bytes peak memory. MCP protocol calls consume a per-key slot without necessarily running a calculation.

The four per-key slots do not override the shared three-calculation compute limit, its eight waiting places, or the memory budget. Each route checks its own work formula against the 24,000,000 Agreement-run ceiling; MCP adds the tighter tool limits. A refusal names the route and inputs to reduce. See Errors and caps for the underlying configuration limits.

401 and 429

Both are JSON, both name what went wrong, and neither repeats a value it was sent.

HTTP/1.1 401 Unauthorized
{"error":"missing X-API-Key header"}

HTTP/1.1 401 Unauthorized
{"error":"invalid X-API-Key"}

HTTP/1.1 429 Too Many Requests
Retry-After: 37
{"error":"rate limit exceeded: 120 requests per minute for this key"}

The websocket route’s 401s add missing X-API-Key header or token query parameter, token expired, token signature invalid, token expiry is more than 10 minutes ahead and websocket tokens are disabled on this engine (FF_TOKEN_SECRET unset).

The version headers

Every response, open or keyed, success or error, carries

X-Engine-Spec: v1.14
X-Engine-Version: 0.7.0
X-Engine-Build: 0.7.0+v1.14+<sha>
X-Engine-Data: <sha256>

X-Engine-Spec is the spec the engine implements (access.rs::ENGINE_SPEC); X-Engine-Version is the crate version from backend/Cargo.toml; X-Engine-Build is the three joined (access.rs::ENGINE_BUILD): crate version, spec and the source revision backend/build.rs stamps at build time — GIT_SHA from the environment (the deploy workflow passes the commit), else git rev-parse --short=12 HEAD on the build host, suffixed -dirty when that host’s backend/ tree had uncommitted changes, else unknown — identifying the deployed source revision. Local edits made under the same -dirty revision can share that marker; use an immutable committed build for reproducible shared results. X-Engine-Data is the SHA-256 of the compiled-in price series (data/btc_historical_monthly.csv), the data half of the identity: a data refresh changes the header without anyone bumping a version. The browser WebSocket API does not expose handshake headers, so Monte Carlo also puts the identity on its Complete frame as engine (spec, version, build, data_sha256), and /api/forwardflow/health reports them as engine_spec, version, build, git_sha and data_sha256. A desk that stamps its own exhibits should record the build and the data digest beside the configuration hash, off the answer that produced them.

The websocket token

A browser cannot send a header on a WebSocket upgrade, so GET /api/forwardflow/montecarlo/ws alone accepts a second credential, the query parameter ?token=<t> (access.rs::mint_token / verify_token):

t       = base64url(payload) + "." + base64url(HMAC-SHA256(FF_TOKEN_SECRET, payload))
payload = "<key-name>|<expiry unix seconds>"        expiry at most 10 minutes ahead

The token names a key rather than carrying one, so the socket is counted against that key’s limits and answered with its X-Key-Name. It is minted server-side by whoever holds a key and the secret — for the cockpit, by the web app’s own GET /api/forwardflow/token route — and the browser learns only the token and the socket URL. A desk’s own code needs no token: it sends X-API-Key on the upgrade request.

The health route and the OpenAPI document

GET /api/forwardflow/health is open in both modes. The following illustrates a 0.7.0 response; read the live response for the actual deployed version and build:

{"status":"ok","engine_spec":"v1.14","version":"0.7.0","build":"0.7.0+v1.14+1a2b3c4d5e6f","git_sha":"1a2b3c4d5e6f","data_sha256":"8846a81b803001d885b0cc3b830f26bfeba35405b91d1843c6376eeca5d8a1bf","mode":"keyed"}

GET /api/forwardflow/openapi.json is the OpenAPI 3 document for every route, compiled into the binary from backend/openapi/openapi.json and also open: https://btcnow-forwardflow.fly.dev/api/forwardflow/openapi.json. The next chapter, Try it, loads it into a Swagger UI.

A first call

Against the hosted engine, the base configuration, one run, scalars only:

$ curl -s -i -X POST https://btcnow-forwardflow.fly.dev/api/forwardflow/simulate \
    -H 'X-API-Key: REPLACE_ME_desk_alpha_key_0001' \
    -H 'Content-Type: application/json' \
    -d '{"config": <BASE_CONFIG>, "include_agreements": false}'
HTTP/2 200
content-type: application/json
x-key-name: desk-alpha
x-engine-spec: v1.14
x-engine-version: 0.6.0
{"outputs":{"irr_monthly":…},"agreements":[],"agreement_count":240,…}

REPLACE_ME_desk_alpha_key_0001 is a placeholder, never a key; <BASE_CONFIG> is the configuration object from Every input.

The cockpit at ff.btcnow.com holds its own key server-side: the browser calls same-origin /api/forwardflow/<path>, the cockpit’s server adds the key and forwards, and the websocket carries a token minted the same way. Nothing a desk can see in the page is a credential.

Paired hedge research

POST /api/forwardflow/hedge_research accepts config, 0–8 structures, 1–32 seeds, optional objective (dollar or coin, default dollar for legacy callers), optional surface, option_rate, put_skew_points, exec_cost_bps (default 50), discount_rate_annual (default 0), valuation_seed (default 42), and include_monthly (default false; at most 8 seeds when true). Surface warning acceptance follows the other hedge endpoints. Cross-book collars and wrapping seed ranges are refused.

The response includes surface_note and any warnings alongside the calculation fields. samples contains ordered per-seed unhedged and strategy outcomes, dollar and coin net gain, NPV, cash needs, horizon marks and paper exposure peaks. Optional monthly arrays support replay inspection. See the comparison guide for definitions. The served OpenAPI describes every field.

Keep valuation_seed fixed: it controls estimation noise in the coin-delta trading rule independently of realized paths. To scale a run, make sequential requests with disjoint consecutive seed ranges and identical assumptions. Check engine build/data identity and merge raw samples before calculating statistics. Do not average separate batches’ percentiles. The endpoint uses the shared heavy queue, per-key limits, cancellation and memory budget. Larger browser runs stop when the page closes.

MCP exposes the same bounded calculation as hedge_risk_samples, with replay inputs and engine identity. Small individual tool calls do not establish precise tail risk.

The additive workspace contract retains response schema: 1 and returns objective plus conventions version 2. The objective changes interpretation only: the same inputs return identical raw samples for Dollar and Coin. Present invalid objectives are refused. A price path that produces a non-finite BTC conversion is refused with HTTP 400 instead of returning a null numeric result. discount_rate_annual discounts USD only; no BTC NPV is implied.

Each outcome now carries coin_holding: contributed_coins, recovered_coins, holding_benchmark_coins, surplus_coins, realized_cash_contributed_coins, realized_cash_recovered_coins and signed horizon_mark_coins. Fund each Agreement purchase at its actual entry price, then combine that BTC outlay with the month’s USD receipts and hedge economic flows converted at monthly spot. Negative net BTC amounts are contributions; positive amounts are recoveries. Holding retains exactly the same dated contributed BTC, so the benchmark equals contributions and surplus equals existing net_gain_coins (up to floating-point tolerance when subtracting totals). These are strategy-specific net contributions, not a common initial budget. Gross acquisition at par is exactly one BTC per Agreement, before receipt offsets and hedge needs. Purchase prices different from strike and phased purchases follow their actual dated net flows. Reserves, borrowed capital, external free BTC and conversion trading costs are excluded.

Economic totals include surviving derivative marks at the horizon; realized-only fields exclude them. Negative marks may create a hypothetical terminal contribution. monthly.spot gives the spot used for each replay month. paper_cash + hedge_cash is realized net USD cash; add horizon_mark_usd in the final month to reconcile USD economic totals. For BTC, use monthly.btc_book.net_realized_cash_btc and add coin_holding.horizon_mark_coins once; purchases use their own entry prices, so dividing the total USD flow by monthly spot does not reconstruct the BTC result. The USD cash-requirement screen retains receipts in dollars and reserves futures margin. It is separate from monthly BTC conversion: the two readings do not establish one jointly funded portfolio or wallet. Full conventions.

Coin measurement fields in 0.6.0

simulate retains its legacy scalar fields and adds coin_irr_unavailable, coin_irr_ambiguous and coin_irr_root_count; USD diagnostics describe USD only. Set include_research: true for the complete unhedged observation and convention metadata.

hedge_research accepts structures: [] for unhedged-only sampling. Coin holding outcomes provide paper_purchase_coins, paper_receipt_coins, economic_recovery_multiple, economic_total_return, realized_cash_recovery_multiple and realized_cash_total_return. Nullable ratios are unavailable when their denominator is not positive and finite or the calculated ratio is non-finite. BTC cash-flow IRR is annualized; total return is a dimensionless recovery ratio minus one, not an annual rate.

Engine 0.6.0 and ResearchConventions.version: 2 fund each Agreement purchase at its actual entry price: one BTC at par. agreement_notional_coins records actual originated Agreements times one BTC; paper_receipt_offset_coins records same-month receipt offsets against Agreement purchases before hedge cash. The old monthly-purchase conversion method remains part of saved pre-0.6.0 evidence and must not be mixed with current results.

Detailed unhedged observations expose coin_cohorts, with count, contractual BTC, funded purchases, fee-net receipts, gain and dated Coin return per origination month. Monthly also returns these unhedged rows on median_seed. Shared hedge costs are not silently allocated. Gross cohort amounts and gains reconcile to the book; cohort IRRs and net-contribution ratios are not added.

When monthly observations are requested, monthly.btc_book contains the engine’s BTC-equivalent component ledger, with modeled USD originals and the conversion spot available beside it. Sum flow components; use end observations for value stocks. Realized cash excludes horizon marks and the economic bridge adds the signed mark once. Fees already netted from receipts must not be deducted twice. The measurement guide defines the denominators and reporting/settlement boundary.

Keep valuation_seed fixed when comparing hedges or replaying a path. Legacy hedge, coin-seat and monthly endpoints disclose their optional valuation-seed convention; research’s fixed valuation seed is independent of the realized config.seed. A matched market seed alone is insufficient if the estimated hedge rule changes.

hedge_series accepts objective (legacy default dollar) and optional selected_seed. Its response records objective, valuation_seed and selection: { metric, seed }. Coin selects the lower-median economic BTC gain; Dollar selects the lower-median finite USD IRR, or USD multiple if every IRR is unavailable. selected_seed must belong to the requested sample. A replay keeps both the market seed and the valuation seed. Explicit Coin monthly and Coin drift requests reject the incomplete legacy cross-book collar.

Monthly btc_book includes flow components and separate open derivative/Agreement value stocks for the selected path and bands. Research’s optional monthly ledger does not compute monthly valuation stocks: those two fields are null, not zero. Its signed horizon derivative value remains available separately in coin_holding.

The hedge response separates realized_settlement_mean_usd from horizon_mark_mean_usd; their sum is payoff_mean_usd. A remaining mark is economic value, not already received cash. Monthly delta_series.price_exposed_agreements gives the population matching total delta, including stopped collateral awaiting sale. Raw delta equivalents and actual strategy positions are different quantities.

API explorer

Read the request schema and try an engine operation from this page. For natural-language questions, use Connect an AI assistant.

The viewer does not persist authorization across reloads. Executing an operation uses the engine’s normal capacity and rate allowance. Read the access rules before running a large analysis.

To request your own access token, email info@btcnow.com. BTC Now delivers it privately. In the viewer’s Bearer authorization field, enter the token itself; the viewer adds Bearer to the request header. This differs from an MCP client’s generic header value, where you enter the full Bearer YOUR_ACCESS_TOKEN text. Choose only one authorization method.

The schema comes from the engine serving this workspace. If the explorer cannot load, open the workspace schema or the hosted engine’s schema. Each describes the build serving that address.

How the engine works

This chapter is the map of the machine. It says what the pieces are, in what order one simulated month runs, which conventions fix the timing and the cents, and why the same request always returns the same bytes. The math of each piece has its own chapter; this one shows where each piece sits and names the function that owns it.

Three layers

The simulator is three programs stacked on one another.

The source defines the implemented calculation. The specification records its intent. A disagreement requires investigation; it is not resolved merely by displaying a result. lib.rs lists the modules: contract (the schedule and the implied rate), defaults (hazards), paths (prices), ledger, fees, money, engine (the monthly loop), outputs (IRR, WAL, Monte Carlo), exposure and boundary (risk analysis), and surface, hedge, series and coin (pricing, hedge flows, monthly analysis and coin-denominated analysis). The server exposes the calculations through the REST API and the bounded MCP interface. The API reference lists the current route families.

There is no database. A request carries the whole configuration; the response carries the whole result. There is no saved-run database. The server does retain bounded computation caches and access-limit state; the browser can retain scenario drafts and completed run records locally.

Three entities and the Market boundary

Every dollar the engine moves belongs to one of three parties, or crosses the boundary to the market. They are the variants of ledger.rs::EntityId.

The identifiers Owner and Obligor are older than the vocabulary lock (Marc, 2026-09-02) and stay in the code so that stored results keep deserializing. The words in prose are Holder and Buyer.

The Market entity is what makes a stop balance. The coin is never on the ledger; only dollars are. When a stop sells the coin, the proceeds are posted from Market to the Holder, to BTC Now and to the Buyer, and the Market’s balance goes negative by exactly the sale amount. Everything the three parties end up with was either paid by a Buyer, paid by the Holder, or sold to the market.

The ledger

ledger.rs::Ledger is an append-only list of postings. A posting is one transfer: month, from, to, amount, kind, Agreement id. There are no debits without credits, because Ledger::transfer writes both sides of one amount at once. That is what “double-entry” means here, and it gives conservation for free.

\[ \sum_{e \in \text{entities}} \text{balance}(e) \equiv 0 \]

ledger.rs::Ledger::conservation_sum computes that sum; engine.rs::run asserts it is zero at the end of every run in debug builds, ff_simulate reports it as conservation_ok on every response, and the invariant test conservation_to_the_cent_across_scenarios checks it across scenario families. Ledger::verify_balances recomputes every balance from the raw postings and compares it with the running map, which is the drill-down audit: any reported total can be rebuilt from the postings by hand.

Three rules in Ledger::transfer keep the ledger honest. An amount must already be quantized to the cent, or the call panics. An amount must be non-negative; a refund is a transfer from the market to the Buyer, not a negative transfer the other way. An amount of exactly zero is dropped, so a stop whose refund is zero posts no StopRefund line at all. The invariant test stop_sale_regime_one_exact_cents asserts that last point.

Money: Decimal and f64

The engine keeps two kinds of numbers apart on purpose.

Money is rust_decimal::Decimal, quantized to cents by money.rs::cents, which rounds half-to-even. Every ledger amount, every schedule line, every fee posting is Decimal. Sums of Decimals are exact, so the schedule sums to the terminal value to the cent and the lifetime fee is exact to the cent.

Boundaries and statistics are f64. Prices on the path, the sale price of a stop, the implied financing rate, moneyness, hazards, IRR, WAL and the percentiles of a Monte Carlo are all floats. A float becomes money in exactly one place: money.rs::cents_from_f64, which is called when a strike is fixed at origination, when a sale price is turned into proceeds, when the value of the coin at early completion is recorded as the Buyer’s equity, and for the frontier’s reference strike. Once a number has become money it never goes back to a float on the ledger side.

The rule in the repository’s instructions is the short form: Decimal for money, f64 for boundaries and display, never f64 in a ledger posting.

One month, in order

engine.rs::run is a loop over calendar months \(m = 0, 1, \dots, H\). Before the loop it validates the configuration, seeds the path generator, draws the price path, applies the shock overlay and the bump overlay in that order, and (when input #25 is on) computes the rational walk-away frontier once. Then, each month, five steps run in a fixed order. The order is fixed for reproducibility, and because it is part of the model: which step runs first decides who has paid before who leaves.

Two consequences of the order matter to a risk desk. First, an early completion or a hazard draw in month \(m\) follows that month’s payment. The draw records the next payment date as missed. Second, a successfully paid final date completes the Agreement before any further draw, but a hazard draw after payment \(\text{term}-1\) can miss the final payment. A pending walk or the boundary’s decision before payment can also consume it unpaid. defaults.rs calibrates the baseline lifetime target over draw ages 1 through term−1 and sets the hazard at the term to zero.

The rational-boundary decision sits inside step 1 rather than in a step of its own, because it is a decision about this payment. The Buyer looks at the coin, looks at the frontier for payment \(t\), and either pays or does not. A Buyer who does not pay has a walk pending, and (2a) executes it in the same month. The exit carries the tag RationalBoundary and is counted separately in the exit split. This mode was lifted from the parked Behavior Engine into the main engine as spec change v1.6 #6 (Marc, 2026-09-03); the frontier itself is derived in The risk desk.

The behavior models behind steps 2 to 4 are in Who stops paying. The conviction rule and the boundary are “walks” and the hazard is a “draw”: walks are decided at or before a payment date and consume it unpaid, draws happen after the payment date has passed.

Timing conventions

Every exit is stamped with a month, and the stop has three dates. The conventions are deterministic and written into engine.rs; reconciling a per-Agreement row against the postings needs all of them.

A draw at age \(t\) misses payment \(t+1\). Step 4 runs after step 1, so the Buyer made payment \(t\) this month. The missed payment date \(D\) is the next one, \(m+1\), and stop_sale is called with missed = m + 1. The Agreement’s exit_month is \(D\), and payments_made is \(t\).

A walk is the missed payment. A conviction walk or a boundary walk pending at month \(m\) consumes that payment date unpaid. The missed date is \(m\) itself; stop_sale is called with missed = m. So a walk at age \(t\) has payments_made \(= t-1\) and exit_month \(= m\).

Day 16 is the Stop Date; the sale is 18 days after the missed payment. A payment up to 15 days late carries nothing (R-1035). The coin is sold for dollars within two business days of day 16 (R-1037), which the engine models as stop_sale_lag_days = 18 calendar days after \(D\) (input #24). The sale is priced on the path by log-linear interpolation between the monthly marks:

\[ \text{pos} = D + \frac{\text{lag}}{30.4375}, \qquad k = \lfloor \text{pos} \rfloor, \qquad f = \text{pos} - k, \qquad S_{\text{sale}} = \exp\big((1-f)\ln S_k + f \ln S_{k+1}\big) \]

At 18 days, \(f = 0.5914\). The proceeds are \(V = S_{\text{sale}} \cdot e^{-\text{haircut}} \cdot (1 - \text{sale cost})\), turned into cents by cents_from_f64. Lag 0 sells at the missed date’s mark, lag 30.4375 at the next one; the invariant test stop_sale_regime_one_exact_cents checks all three.

Cash lands at the first monthly date at or after the sale. The three stop postings (StopSaleDelivery, FlowFee, StopRefund) are dated \(\lceil\text{pos}\rceil\), clamped to the horizon. At 18 days that is always \(D + 1\). The exit month stays \(D\).

Horizon. engine.rs::SimConfig::horizon uses the automatic run-off horizon below unless a supplied market_horizon_months extends it. A supplied shorter horizon is rejected. The automatic horizon is

\[ H = (\text{effective cohorts} - 1) + \text{term} + \left\lfloor\frac{\text{stop sale lag days}}{30.4375}\right\rfloor + 1 \]

The effective cohort count includes the origination cut-off. The last cohort originates at month \(\text{effective cohorts} - 1\); its Buyers can miss payment \(\text{term}\) at the latest. The settlement tail keeps that final stop’s sale and receipt inside the ledger. At the default 18-day lag it adds one month: 24 cohorts and 60 payments give \(H = 23 + 60 + 1 = 84\), with 85 path marks.

The whole stop is worked, with its three regimes, in The stop waterfall.

Determinism

The engine is fully seeded. Same configuration and same seed produce the same postings, byte for byte. Three mechanisms make that true, and a fourth makes it useful.

The path has its own stream. engine.rs::run seeds a ChaCha20 generator from config.seed (ChaCha20Rng::seed_from_u64) and uses it only for the price path: the bridge’s increments or the bootstrap’s block picks. Historical replay and custom paths draw nothing. Shocks and bumps are deterministic overlays applied after the draw.

Every Agreement has its own stream. engine.rs::agreement_rng(seed, id) builds a 256-bit ChaCha20 key from the configuration seed and the Agreement’s id. The mixing is splitmix64: the id is multiplied by the golden-ratio constant \(\text{0x9E3779B97F4A7C15}\), the product is rotated left by 23 bits and XORed with the seed, and four rounds of splitmix64 (add the constant, apply the finalizer) fill the four 64-bit words of the key. Agreement 17 under seed 42 gets the same stream in every run of every configuration that uses seed 42, whatever the other 239 Agreements did. Its dispersed strike (input #20), its early-completion draw, its hazard draw and, in rational mode, the redirect pick all come from this stream.

Draws are unconditional. In steps 3 and 4 the uniform is drawn before the engine looks at the price, every month the Agreement is eligible, whether or not the price makes the draw matter. Spec v1.6 introduced both this and the per-Agreement streams for one reason: bump-and-revalue. When the risk desk bumps every future price by 5% and reruns, the random numbers behind every decision are identical; only the decisions change. The difference between the two runs is a sensitivity, not draw noise. Under the earlier single shared stream, one Agreement leaving a month earlier shifted every later draw in the book, and the Greeks were unreadable.

Monte Carlo seeds are consecutive. outputs.rs::run_monte_carlo runs \(n\) simulations with seeds \(\text{base}, \text{base}+1, \dots, \text{base}+n-1\) (wrapping_add), in parallel on the rayon pool, collected in order. Run \(i\) of a 10,000-run Monte Carlo is exactly the single run you get by asking for seed \(\text{base}+i\). The WebSocket variant runs the same seeds in chunks of 1,000 (forwardflow_api.rs::run_chunk passes the chunk offset), so streamed and one-shot results are the same numbers. The reported base_seed on the summary is what a reader needs to reproduce any run of the distribution.

One consequence when comparing across versions: changing how the streams are derived changes the draws. The Model Card notes that the v1.6 per-Agreement streams draw differently from v1.5 at the same seed, which moved the zero-drift medians by a tenth of a point and the single-vintage replay median by ten points. Determinism is a property of one engine version.

The posting kinds

ledger.rs::TxKind has seven variants. Every dollar in a run is one of them.

BTC Now’s take is OriginationFee plus FlowFee, and nothing else (outputs.rs::analyze computes total_take as exactly that sum). There is no posting kind for a share of a stop sale, and the repository’s rules forbid adding one.

The money conventions

Three conventions fix how rational numbers become cents. They were decided at milestone M1 (M0_FIXTURES.md, “Cent-quantization conventions”) and they are what makes every identity in Verification testable to the cent.

C1. The payment is floored to the cent; the final payment absorbs the residual. contract.rs::ContractTerms::schedule computes

\[ \text{PMT} = \Big\lfloor \frac{P}{\text{term}} \Big\rfloor_{0.01}, \qquad \text{payment}_{\text{term}} = P - (\text{term} - 1),\text{PMT} \]

where \(P = \text{strike} \times \text{multiple}\) is the Purchase Price of the coin to the Buyer (the terminal value), itself rounded half-even to the cent by ContractTerms::terminal before the division. Flooring rather than rounding was an amendment after adversarial review (2026-07-11): rounding half-even could push the accumulated schedule past \(P\) at a micro-strike and make the final payment negative. With the floor, the residual is always non-negative and the schedule sums to \(P\) exactly. At the base terms, \(88{,}500 / 60 = 1{,}475.00\) is a whole cent and all 60 payments are equal. At 36 months, \(88{,}500 / 36 = 2{,}458.3\overline{3}\): payments 1 to 35 are $2,458.33 and payment 36 is $2,458.45.

C2. The fee is rounded cumulatively. fees.rs::FeeState::split keeps, per Agreement, the cumulative dollars delivered and the cumulative fee posted, and computes each fee posting as a difference:

\[ \text{fee}_k = \text{round}(f \cdot \text{cum}k) - \text{round}(f \cdot \text{cum}{k-1}), \qquad \text{net}_k = \text{delivery}_k - \text{fee}_k \]

Each posting conserves by construction (net plus fee equals the delivery), and the lifetime fee is exactly \(\text{round}(f \times \text{total delivered})\) whatever the individual postings did. The price of that exactness is that a single posting may wobble by a cent against \(\text{round}(f \times \text{delivery})\). At the base terms there is no wobble: 5% of $1,475.00 is $73.75, and the Holder nets $1,401.25 on every delivered payment. At 36 months the wobble appears: 5% of $2,458.33 is $122.9165, so the first fee posting is $122.92, the second is $122.91 (because \(\text{round}(0.05 \times 4{,}916.66) = 245.83\)), and the cumulative total is exact at every step. The fee applies to every delivered dollar: scheduled payments after the first N, early-completion payoffs, and stop-sale deliveries (Marc, 2026-08-31, “we retain 5% of each send”). The first N payments are not deliveries and carry no fee.

C3. IRR is computed on the quantized flows. outputs.rs::analyze builds the Holder’s monthly net flow from the ledger (ledger.rs::Ledger::owner_monthly_gross, inflows and outflows kept separate and netted only for IRR and payback), converts each cent-exact Decimal to f64, and outputs.rs::irr solves for the monthly rate by a grid scan in steps of 0.01 for a sign change of NPV over \((-0.95, 5.0)\) followed by 200 bisection steps. Nominal is 12 times the monthly rate; effective is \((1+r)^{12} - 1\). The M0 fixtures were generated in exact rational arithmetic on unquantized flows, so the Rust engine is required to match them within 0.01 percentage points, not exactly. The metrics are derived in Outputs.

A worked example at the base terms

Take the engine’s own default configuration (engine.rs::SimConfig::default): a $60,000 coin, 1.475× so \(P = $88{,}500\), 60 payments of $1,475, the first to BTC Now, 5% servicing, the Holder buys at par, sale 18 days after a missed payment at 25 bp cost and no haircut, a bridge from $60,000 to $60,000 at 43% volatility, the baseline hazard curve at a 40% lifetime prior, 2.5% monthly early-completion propensity, 24 cohorts of 10, seed 42. Posting this as POST /api/forwardflow/simulate with include_postings: true gives 240 Agreements, an 85-mark path, 17,728 postings and conservation_ok: true.

Origination. In month 0, ten PurchasePrice postings of $60,000.00 move from the Holder to BTC Now.

A delivered payment. Agreement 2 (cohort 0) pays $1,475.00 at age 1, posted whole to BTC Now as OriginationFee. At age 2 the same $1,475.00 splits: PaymentDelivery $1,401.25 to the Holder, FlowFee $73.75 to BTC Now.

A stop. Agreement 2 draws below its hazard at age 22 (month 22). Payment 22 was made in step 1; the draw in step 4 misses payment 23, so exit_month is 23 and payments_made is 22. The sale sits at position \(23 + 18/30.4375 = 23.591\), between the month-23 mark of $33,375.25 and the month-24 mark of $36,038.10; log-linear interpolation gives $34,925.24, and after 25 bp the proceeds are \(V = $34{,}837.93\). The Buyer has paid \(A = 22 \times 1{,}475 = $32{,}450\); the remaining schedule is \(R = 88{,}500 - 32{,}450 = $56{,}050\). Then \(V + A - P = -21{,}212.07 < 0\), so the refund is zero and no StopRefund posts. The whole $34,837.93 is delivered. Under C2 the Agreement had delivered \(21 \times 1{,}475 = $30{,}975\) with a cumulative fee of $1,548.75; the new cumulative is $65,812.93 and \(\text{round}(0.05 \times 65{,}812.93) = 3{,}290.65\), so the fee posting is $1,741.90 and the Holder’s StopSaleDelivery is $33,096.03. Both post in month 24, the payment date after the sale. The row shows shortfall_usd \(= R - V = $21{,}212.07\), stop_surplus_usd 0, owner_net $62,522.28 and capital_pnl $2,522.28: the Holder got its $60,000 back and a little more, because 21 delivered payments came in before the stop.

The three regimes of the waterfall, by the same arithmetic, for a Buyer who stops after 12 payments (\(A = $17{,}700\), \(R = $70{,}800\)) with 11 prior deliveries:

Below the schedule line the Holder takes everything and books a shortfall. Between the schedule and the Purchase Price the Holder is made whole first and the Buyer gets the rest of what he paid. Above the Purchase Price the Buyer is refunded in full and the surplus stays with the Holder. The refund base \(A\) includes payment 1, which BTC Now kept; that is modelled as “the maximum he paid” and is flagged as a term-sheet question, not a ruling (spec v1.5 change 8).

Abuse caps and the memoized Monte Carlo

The API runs on a shared box, so the engine and the server both bound the work a request can ask for. The cohort, book-size and Monte Carlo-work caps and the semaphore were added in the hosting hardening of 2026-07-13 (spec v1.4 change 13). Every cap returns HTTP 400 naming the offending input; the semaphore queues rather than refuses.

The 24 million figure is the 100,000-run ceiling at the default 240-Agreement book; a bigger book gets fewer runs. The engine’s validate panics on a bad input with a message that names it; forwardflow_api.rs::catch_engine catches the unwind and turns it into the 400. That is why the build profiles must never set panic = "abort": the whole error path depends on unwinding.

Identical Monte Carlo requests are memoized. forwardflow_api.rs::MC_CACHE is an LRU of 64 summaries keyed by the run count and the configuration’s JSON. A hit returns the stored summary without touching the engine; the WebSocket variant sends its Complete frame at once. This is sound only because the engine is seeded: the same configuration and run count always produce the same summary, so a cached copy is the answer, not an approximation of it. The cache is in memory and is empty after a restart. A single simulate is not cached; it is fast enough not to need it.

The server also leaves one core free for the async runtime (main.rs sizes the rayon pool at cores minus one), gzips responses, and caches CORS preflights for a day. None of that changes a number.

What byte-identical means

The repository’s rule reads “same config ⇒ byte-identical output”. Here is the precise claim.

Given the same engine build, the same SimConfig (every field, including seed) and the same request flags, POST /api/forwardflow/simulate returns the same response body, byte for byte: the same postings in the same order with the same amounts, the same per-Agreement rows, the same path, the same outputs. Two consecutive requests at the base configuration above return bodies with the same SHA-256, and that is the check anyone can repeat with curl and shasum. The invariant test seeded_determinism in backend/forwardflow/tests/invariants.rs asserts the same thing one level down: two runs of one configuration serialize to identical postings, and a different seed serializes to different ones.

What is covered: every random draw (the path, dispersed strikes, early-completion draws, hazard draws, rational-mode redirects), every posting, every derived output, and every run of a Monte Carlo individually by its seed. Parallelism does not enter: each Monte Carlo run is independent and collected in order.

What is not covered: a different engine version, which may derive the streams differently (v1.5 to v1.6 did); a different configuration that looks the same but differs in a defaulted field; and floating-point results across different hardware or compilers, which the repository does not test. On one build on one machine, the claim is exact.

The risk desk depends on this. A bump-and-revalue Greek is the difference between two runs that share every draw and differ only in the prices. A Model Card figure carries its seed and its configuration, and is the deterministic function of them. If a reader reproduces a run and gets a different number, the build or the configuration changed, and the engine’s job is to make that the only possible explanation.

Contract and fees

Start with the scheduled cash flows of one Agreement: what the Buyer pays, what BTC Now retains, and what reaches the Holder. This chapter derives the payment schedule, implied financing rate, remaining balances and fee rounding.

Implementation: contract.rs, fees.rs, money.rs, and the origination and payment steps of engine.rs::run. The reference fixtures are M0_FIXTURES.md.

The worked numbers use the base terms throughout: a $60,000 coin, a 1.475× multiple, 60 monthly payments, the first payment to BTC Now, a flat 5% servicing fee on every dollar delivered to the Holder, and a Holder who buys at par. Every figure below is either printed by the engine, asserted by a test, or one line of arithmetic from a figure that is.

The terms in one line

An Agreement is a conditional sale of one coin. The Buyer pays a fixed dollar schedule; when the schedule is complete, title to the coin passes. The engine’s contract.rs::ContractTerms holds five fields:

Nothing in contract.rs may hard-code a term. “Sixty months” is a default, not an assumption (spec v1.1 change 1, Marc, 2026-07-10). Every quantity below is written for a general term \(n\) and then evaluated at \(n = 60\).

Money is rust_decimal::Decimal quantized to cents; rates and boundaries are f64. money.rs::cents rounds half-to-even. A ledger posting is never an f64 (project rule 5).

The terminal value

The terminal value is the Agreement’s full dollar price, the Purchase Price in the program’s contract language:

\[ P = \text{cents}(\text{strike} \times \text{multiple}) . \]

At the base terms \(P = 60{,}000 \times 1.475 = $88{,}500.00\). This is contract.rs::ContractTerms::terminal. The engine’s stop waterfall calls this quantity \(P\) as well; the letter is shared on purpose (see the stop waterfall).

The schedule and convention C1

The nominal payment is the terminal value divided by the term:

\[ \text{PMT} = \frac{P}{n} = \frac{\text{strike} \times \text{multiple}}{n} . \]

At the base terms \(\text{PMT} = 88{,}500 / 60 = $1{,}475.00\), a whole number of cents. At other terms it usually is not, and a schedule of sixty identical cent amounts would not sum to the terminal. Convention C1 fixes this (M0_FIXTURES.md, amended after adversarial review 2026-07-11):

1. Quantize PMT to cents rounding toward zero (a floor, for positive money).
2. Every payment but the last is that floored amount.
3. The final payment absorbs the residual, so the schedule sums to \(P\) exactly.

In contract.rs::ContractTerms::schedule:

\[ \text{PMT}^* = \lfloor \text{PMT} \rfloor_{0.01}, \qquad p_t = \text{PMT}^* ;(t < n), \qquad p_n = P - (n-1),\text{PMT}^* . \]

The floor, rather than half-even rounding, is what makes \(p_n \ge \text{PMT}^*\) at every strike. With half-even rounding an upward round on a tiny strike could push \((n-1),\text{PMT}^*\) past \(P\) and make the last payment negative; the invariant tiny_strike_schedule_never_goes_negative runs a $10 coin over 84 months to hold the line.

The 36-month example shows the residual:

At 36 months the last payment is twelve cents larger than the others; at 84 months, twelve cents as well. The unit test residual_absorbed_at_inexact_terms in contract.rs pins the 36-month case, and schedule_sums_to_terminal_any_term checks the sum at terms 1, 7, 24, 36, 48, 60, 84 and 120.

schedule()[t-1] is payment \(t\). The engine builds the vector once per Agreement at origination and never recomputes it.

The remaining nominal schedule

After \(t\) payments the Buyer still owes the tail of the schedule:

\[ R_t = \sum_{k=t+1}^{n} p_k . \]

This is contract.rs::ContractTerms::remaining_schedule, and inside the engine engine.rs::Agreement::remaining_schedule, which reads a suffix-sum table built at origination so the lookup is one index rather than a re-sum (spec v1.4 change 13; the values are identical). Because C1 makes all but the last payment equal, at the base terms \(R_t = 88{,}500 - 1{,}475,t\): $87,025 after payment 1, $70,800 after payment 12, $60,475 after payment 19, $35,400 after payment 36, zero after payment 60.

\(R_t\) is the dollar figure the program treats as “what remains.” It is what the Buyer pays at early completion (engine.rs::settle), what the stop waterfall pays the Holder first (engine.rs::stop_sale), and the numerator of the risk desk’s schedule line \(R_t / \text{strike}\).

The Buyer’s paid-in total is the complement, \(A_t = P - R_t\) (engine.rs::Agreement::paid_in, payment 1 included). The waterfall’s refund base is this \(A\).

The implied financing rate

The paper carries a rate even though the contract states none. It is the monthly rate \(i\) at which a level payment of PMT over \(n\) months has present value equal to the strike, the ordinary annuity identity:

\[ \text{PMT} = \text{strike} \cdot \frac{i,(1+i)^n}{(1+i)^n - 1} . \]

The engine calls \(12,i\) the nominal annual rate and \((1+i)^{12} - 1\) the effective annual rate, and the accepted name for either is the implied financing rate. contract.rs::ContractTerms::implied_monthly_rate solves the identity with the unquantized PMT (\(P/n\) as a float, so the rate does not jump with a cent of C1 residual) by bisection.

Two details of the solver matter for a desk that explores below-par pricing:

• The domain is signed. Bisection runs on \(i \in [-0.5, 1.0]\) for 200 halvings. The right-hand side is increasing in \(i\) on that interval, so the bracket always contains the root. A multiple of exactly 1.0 gives \(i = 0\), and a multiple below 1.0 gives a negative rate, which is the correct reading of paper priced below its coin: at 0.90× and 60 months the solver returns a nominal rate of about −4.07% per year (invariant below_par_multiple_gets_a_negative_implied_rate). An earlier solver clamped at zero and corrupted the moneyness boundary for below-par inputs; the signed domain is the fix.
• The zero point is guarded. When \(|i| < 10^{-12}\) the identity degenerates to \(\text{strike}/n\) rather than \(0/0\).

At the base terms: