Debt Buffer

Debt Buffer is a three-decimal percentage that caps how much debt can sit above the market’s initial level. When outstanding debt crosses this threshold, deposits pause—acting as a circuit-breaker during demand surges (e.g., a stable-coin de-peg). The buffer must be at least the larger of 10 % or initial maxPayout ÷ capacity. Too low and the market shuts early; too high and the circuit-breaker may never trip. Values can exceed 100 % if needed.

A good heuristic to calculate a debtBuffer with is to determine the amount of capacity that you think is reasonable to be expended in a short duration as a percent, e.g. 25%. Then a reasonable debtBuffer would be: 0.25 * 1e3 * decayInterval / marketDuration where decayInterval = max(3 days, 5 * depositInterval) and marketDuration = conclusion - creation time.

"Debt" explained

Debt is the running liability of the market — the total amount of payout tokens that have already been sold to buyers but have not yet vested or been claimed.

• When a user deposits, the contract mints new debt equal to the payout amount they will eventually receive.

• As time passes and purchasers redeem vested tokens, that debt decays (is burned), reducing the outstanding total.

• Debt is recorded in payout-token decimals and reported on-chain as:

  • totalDebt – aggregate outstanding debt for the market

  • currentDebt(id) – helper that returns totalDebt after accounting for the latest decay

Debt is the figure that both maxDebt (an absolute ceiling) and the debt buffer (a dynamic circuit-breaker) compare against.

If outstanding debt grows too quickly relative to capacity—because many users buy in before earlier bonds vest—the debt buffer halts new deposits until enough of that debt has decayed.

How it works

1. Circuit-breaker for demand spikes

   If external events (e.g., a stable-coin de-peg) trigger rapid buying, the buffer stops deposits once debt grows beyond the set percentage, preventing runaway issuance.

2. Interaction with depositInterval

   A short deposit interval (frequent small buys) generally pairs with a smaller buffer.

   A long interval (large, infrequent buys) benefits from a larger buffer to accommodate bigger single transactions.

3. Dynamic debt reduction

   As vesting claims are redeemed, outstanding debt falls; deposits reopen automatically when debt again sits below the cap—no owner intervention needed.

Recommended Debt Buffer Settings

You may choose any value ≥ 10 %, but high-demand / low-liquidity tokens often settle in the 30-50 % range so the auction can shut itself off quickly if buying spikes.

Low (Conservative) → 15% For very controlled markets with low expected demand. Minimizes risk of over-issuance but may close market early if demand unexpectedly spikes.

Medium (Recommended) → 25% The default for most markets. Provides a balance of safety and market flexibility.

High (Active / Volatile) → 35% Use if you expect strong demand or external risks (e.g. stablecoin depegs, whales).

Very High (Extreme Demand) → 50% For large or mature markets expecting very high short-term buying pressure.