Ledger and invariants

Every instruction keeps one identity per side, live reserve equals cash plus debt plus hedged-vault depth, and custody checks keep each vault's real balance above everything the ledger owes from it.

Updated Nov 15, 2026

V1 kept a market's books with three rules: the virtual reserve equals cash plus debt, cash never goes negative, and every operation changes both sides of that equation by the same amount. V2 keeps all three, adds terms for leverage debt and the hedged vaults, and checks the books against the tokens each vault holds.

The identity

For each side ii of a market, base or quote:

Ri=Ci+Dif+Diℓ+Φi+HiR_i = C_i + D_i^{f} + D_i^{\ell} + \Phi_i + H_i
TermStored asWhat it is
RiR_ilive_reserveThe side's live reserve
CiC_icash_reserveAccounted cash, the only term a swap, withdrawal, loan or interest claim can pay out
DifD_i^{f}fixed_*_shares times the borrow indexPublic lending debt, accrued interest included
DiℓD_i^{\ell}isolated_*_shares times the borrow indexIsolated leverage debt
Φi\Phi_iflash_receivableCollateral committed to an open hLP flash recovery; it must equal the vault's flash_collateral_debit
HiH_ibase_hlp_live_reserve, quote_hlp_live_reserveDepth the hedged vaults own on this side: the principal of the funding they borrowed in this token

Debt is held as shares of a per-side borrow index IiI_i, a nine-decimal fixed-point number that starts at 1.0 and grows as interest accrues. A book of NN shares owes ⌊NIi⌋\lfloor N I_i \rfloor, so one accrual raises every loan on the side. The public and leverage books share the index and floor their totals separately. Together they are the side's cash-backed debt, Dicb=Dif+DiℓD_i^{\mathrm{cb}} = D_i^{f} + D_i^{\ell}. The hedged vaults' funding debt is not part of it: it counts toward utilization and the vaults' value, and the identity carries the vaults through HiH_i.

Φ\Phi is nonzero only inside one transaction. An hLP flash recovery's begin instruction moves cash into it and checks that its settle instruction comes later in the same transaction; settle requires the same slot and clears it.

Borrow neutrality

A cash-backed borrow of aa on side ii exchanges cash for a loan claim of the same size:

Ci′=Ci−aDicb ′=Dicb+aRi′=Ci′+Dicb ′+Φi+Hi=Ri\begin{aligned} C_i' &= C_i - a \\ D_i^{\mathrm{cb}\,\prime} &= D_i^{\mathrm{cb}} + a \\ R_i' &= C_i' + D_i^{\mathrm{cb}\,\prime} + \Phi_i + H_i = R_i \end{aligned}

This is borrow neutrality, which the whitepaper calls credit neutrality. RiR_i stays where it was, so lending does not move the price. The loan still uses up cash, which raises utilization, an input to the borrow rate. A swap changes inventory on both sides: its net input raises CC and RR on one side, and its output lowers them on the other.

Shares make the debt step slightly larger than aa. borrow mints n=⌈a/Ii⌉n = \lceil a / I_i \rceil shares on top of the side's NN, and its debt grows by

ΔDicb=⌊(N+n) Ii⌋−⌊N Ii⌋ ≥ a\Delta D_i^{\mathrm{cb}} = \lfloor (N+n)\,I_i \rfloor - \lfloor N\,I_i \rfloor \ \ge\ a

The program debits exactly aa of cash and adds the residue ΔDicb−a\Delta D_i^{\mathrm{cb}} - a to RiR_i. Principal grows by exactly aa, so the residue also lands in the unpaid interest JiJ_i below, and the executable reserve does not move by a single atom.

borrow commits the books before any token leaves:

  1. Accrue interest on both sides and refresh the curve and risk observations.
  2. Run the admission checks in Dynamic collateral factor.
  3. Debit CiC_i, add the shares and principal, credit the residue to RiR_i and store the position's factor.
  4. Transfer aa from the reserve vault, then check custody and that the borrower received at least min_debt_amount_out.
  5. Rebuild the curve from the new reserves and refresh risk.

The executable reserve

Interest accrues into DD, so it raises RR before any borrower pays. It is credited to holders at the same moment, so the curve trades only on what those claims leave:

Xi=max⁡ ⁣(0, Ri+Ui+Δi−Qi−Πi)X_i = \max\!\left(0,\ R_i + U_i + \Delta_i - Q_i - \Pi_i\right)

QiQ_i is credited interest not yet claimed, owed to LP holders, the junior seed and the operator. Πi\Pi_i is the protocol's share of the interest borrowers still owe; the protocol is paid only when they pay. UiU_i is the funding interest the hedged vaults owe in this token: it accrues outside RR but is credited like public interest, so it is added back. Δi\Delta_i is the token's recorded interest deficit, zero unless a loss has exceeded all LP capital.

An accrual of ii raises RR, or UU for funding, and Q+ΠQ + \Pi by the same ii, so it never moves the curve. A repayment of interest xx adds xx less the protocol's share xp=⌊x Πi/Ji⌋x_p = \lfloor x\,\Pi_i/J_i \rfloor to CC, where JiJ_i is all interest outstanding, public and funding, and lowers Π\Pi by xpx_p. A claim of yy lowers CC and QQ by yy. Neither moves XX: repayments and claims change depth through cash, never the price.

srLP mints and burns against XX. Burning ss of SS shares pays ⌊sXi/S⌋\lfloor s X_i / S \rfloor from each side, and a deposit pays in at a rate rounded up.

Worked example

One quote side of a six-decimal token, with no hedged vaults and no operator share. At index 1.023456789, existing borrowers owe 204,691.3578 against 200,000 of principal, all of it accrued under the default 20% protocol markup, so the protocol's unpaid share is a sixth of the 4,691.3578 of interest. The rate holds at 6%.

StepCCDcbD^{\mathrm{cb}}QQΠ\PiRRXX
Start800,000204,691.3578003,909.464834781.8929661,004,691.3578001,000,000
Borrow 100,000700,000304,691.3578003,909.464834781.8929661,004,691.3578001,000,000
30 days of interest700,000306,494.4625245,412.0521041,082.4104201,006,494.4625241,000,000
New loan repaid in full800,493.150604205,902.6818005,412.052104983.7803001,006,395.8324041,000,000

The borrow mints 97,708,082,134 raw shares, worth exactly 100,000 at this index. A borrow of 100,000.000034 would mint debt worth one atom more; RR and Q+ΠQ + \Pi would both rise by that atom and XX would stay put. Thirty days at 6% with the markup grow the index by 0.06×30365×1.2=0.59178%0.06 \times \tfrac{30}{365} \times 1.2 = 0.59178\%, and the 1,803.104724 of new interest is credited at once: a sixth to Π\Pi, the rest to QQ. The repayment burns the new loan's shares for 100,591.780724. The 100,000 of principal and the 591.780724 of interest enter CC, less the protocol's 98.630120, which moves to its revenue liabilities. Holders' QQ does not change until they claim.

Solvency

Every debit of CC is checked. A swap's output or an srLP payout larger than the side's cash fails with InsufficientLiquidity, a borrow larger than it with InsufficientBorrowHeadroom, and any other debit that would take cash below zero with CashReserveUnderflow. So Ci≥0C_i \ge 0, and with Φ\Phi and HH never negative, the identity gives V1's solvency invariant:

Ri ≥ Dif+DiℓR_i \ \ge\ D_i^{f} + D_i^{\ell}

The books are then checked against the tokens held. After its last transfer, every swap, liquidity change, loan, leverage action, liquidation, hedged-vault action and harvest requires each reserve vault it touched to hold at least:

Vireserve ≥ Ci+Fi+Ei+Bi+ZiV_i^{\text{reserve}} \ \ge\ C_i + F_i + E_i + B_i + Z_i

FiF_i is swap-fee yield held for claimants, EiE_i protocol revenue in escrow or pending release, BiB_i inventory backing the hedged vaults and ZiZ_i surcharge kept for the curve's next recentering. The check reads the vault balance after the instruction's final transfer; the swap path uses the exact projected balance instead. Tokens sent to a vault outside an instruction only raise the left side, so a donation never becomes executable liquidity. Credited interest has no vault of its own: it is part of CC, and a claim draws on the same cash as a withdrawal.

How each instruction moves it

Every path keeps the transition rule

ΔRi=ΔCi+ΔDif+ΔDiℓ+ΔΦi+ΔHi\Delta R_i = \Delta C_i + \Delta D_i^{f} + \Delta D_i^{\ell} + \Delta \Phi_i + \Delta H_i
InstructionΔC\Delta CΔDf\Delta D^{f}ΔDℓ\Delta D^{\ell}ΔR\Delta RΔX\Delta X
SwapPlus the net input on one side, minus the output on the other00=ΔC= \Delta C on each side=ΔC= \Delta C on each side
Add srLPPlus a proportional deposit00=ΔC= \Delta C=ΔC= \Delta C
Remove srLPMinus a proportional payout00=ΔC= \Delta C=ΔC= \Delta C
Borrow aa−a-a+a+a, rounded up0Rounding only0
Interest accrual0Plus interestPlus interestPlus interest0
Repay principal pp and interest ii, protocol share ipi_p+(p+i−ip)+(p + i - i_p)−(p+i)-(p + i)0−ip-i_p0
Interest claim yy−y-y00−y-y0

Of these rows, only trades and liquidity changes move XX, and with it the price. The other paths follow the same rule:

PathWhat moves
Swap feesThe protocol's share goes to its revenue lanes and the rest is LP income. Part of it compounds into CC and RR, part waits in fee custody FF, and the junior tranche's split is taken first.
Interest paymentsPaid interest stays in CC except the protocol's pro-rata share, which moves to its revenue liabilities. Holders' credited interest does not change until they claim.
LeverageOpening or increasing a position borrows from the debt side's cash into DℓD^{\ell} and swaps it on the curve into collateral, which moves to the leverage collateral vault. The trader never receives cash. Decreasing or closing swaps back and repays.
Flash liquidationThe repaid principal returns to CC and the repaid debt leaves DD. Recovery pays principal first; interest it cannot pay is written off as a pool loss. The junior part of the liquidation charge stays in CC, credited to Junior LP.
Emergency liquidationThe collateral enters its side's cash, the internal swap repays debt on the other side, principal first, and any principal or interest left unpaid is written off. The write-off lowers RR on the debt side, and the program burns junior reserve shares so that the loss lands on junior holders. Senior shares lose value only once no junior shares remain.
Junior conversion and exitThese move ownership between srLP and jrLP and never move an asset.
Hedged vaultsDeposits, withdrawals and every swap that reaches an active vault rebuild both vaults' srLP shares, funding debt and HH from the trade's endpoint. RR moves by the change in HH. A funding payment lowers the vault's debt, and only its protocol share leaves CC.
Harvests and revenue claimsSwap fees come from fee custody FF and referral and protocol revenue from EE. LP and operator interest is paid from CC, as far as it goes, and lowers QQ by the same amount, so XX does not move.

Checks the program runs

There is no single check after every instruction. Each path runs the checks its own state changes need.

CheckConditionErrorRuns on
Reserve identityThe identity above, on both sidesBrokenInvariantSwaps and every leverage action or liquidation that settles through the swap engine, junior conversion and seeding, hedged-vault changes
Market invariantsEqual srLP supply on both sides, junior shares no more than total shares, no live reserve without srLP, fee liabilities backed, no hLP backing without hLP supply, recorded interest equal to the debt it measures, Π\Pi no more than that interest and any gap recorded as a deficitBrokenInvariantThe same swap-engine paths, junior conversion and seeding, hLP flash recovery
CustodyThe vault inequality aboveUnbackedFeeLiabilityThe instructions listed under Solvency
CashDebits, payouts and loans within cash, and X≥0X \ge 0InsufficientLiquidity, InsufficientBorrowHeadroom, CashReserveUnderflow; BrokenInvariant if XX would go negativeEvery debit
Market health floorAggregate health at or above the floor, set at creation and at least 100%InsufficientMarketHealthBorrows, srLP removal, hLP deposits and withdrawals, settings execution, operator-share increases
Utilization guardBoth sides below 80%UtilizationGuardExceededSettings execution, operator-share increases

A curve ramp step that would break the health floor or the utilization guard is skipped, and the swap that attempted it goes through.

Borrows, repayments and srLP changes do not re-run the identity check. They move matching terms and check custody.

A few rules have no runtime check and hold by construction:

  • Reserve principal excludes reserve-custodied swap-fee liabilities, credited interest and the protocol's unpaid share.
  • Outside the hedged vaults' own transitions, HH changes only when a vault is initialized, rolled back or replaced, and the vaults never borrow srLP.
  • Isolated leverage debt counts toward utilization but never enters a public borrower's health check.
  • A referral binding never changes principal, debt, interest, health or liquidation terms.

Empty states

  • A side with no srLP must hold no live reserve; BrokenInvariant rejects anything else.
  • An hLP vault with no supply must have no backing inventory on either side.
  • When a side has no public, leverage or funding debt shares, the next accrual resets its borrow index to exactly 1.0. While only funding debt remains, each accrual checks that Ri=Ci+Φi+HiR_i = C_i + \Phi_i + H_i.
  • The first srLP deposit mints db dq\sqrt{d_b\, d_q} shares for deposits dbd_b and dqd_q and burns 1,000 of them permanently. Those locked shares make inflating the share price of an empty market expensive.

Rounding

Every conversion rounds in the market's favour:

  • Debt shares round up and debt values round down: n=⌈a/I⌉n = \lceil a / I \rceil and D=⌊NI⌋D = \lfloor N I \rfloor.
  • A repayment is charged on the side's whole share bucket, ⌊NI⌋−⌊(N−n)I⌋\lfloor N I \rfloor - \lfloor (N - n) I \rfloor for nn burned shares, so a repayment split into pieces costs the same in total. Charging each payer's own rounded amount could erase up to one share of debt per split.
  • srLP mints round down, and the deposits behind them round up: deposits did_i mint min⁡i⌊diS/Xi⌋\min_i \lfloor d_i S / X_i \rfloor shares, and each side is charged ⌈sXi/S⌉\lceil s X_i / S \rceil.
  • Payouts round down, and so does the protocol's share of a fee.
  • Auction payments round up, and so does a junior loss burn.

The one exception is the junior exit fee, which rounds down.

Accounts

AccountOne perHolds
MarketMarketConfig, curve state, both sides' reserves and fees, debt indexes, the two hLP vaults, risk observations, oracle policy, tranche capital and policy, the active jrLP mint, each side's interest ledger, operator and optional manager, parameter revisions, reduce-only flag
MarketSide (inside Market)AssetMint, vault addresses, reserve components, srLP supply, fee liabilities, the interest ledger and growth indexes, the daily borrow bucket
BorrowPositionPosition, per marketCollateral, debt shares and principal per side, stored liquidation factors, referral binding, and the active liquidation session
LeveragePositionPosition, per marketDebt asset, collateral, margin, notional, debt shares, multiplier, timestamps
LeverageDelegationLeverage positionThe delegate program allowed to act and which actions it may take
YieldAccountOwner × market × LP mint × asset × kindCheckpoints against the swap-fee and interest growth indexes, accrued amounts, any jrLP held in an exit request, recipient and harvest authority
JuniorExitAccountOwner × jrLP mintOne exit request: its jrLP, ready slot and the end of its exercise window
JuniorCohortjrLP mintOne junior generation; its growth indexes, frozen once it is retired
OperatorProposal, OperatorRevenueAccountMarket × nonce; market × revenue epochPending atomic bundle and the credited operator interest sealed at a recipient change; see Market operators
ReferralPartner, ReferralAccrualPartner, partner × market × assetSee Governance
FutarchyAuthorityProtocolRevenue shares, recipients, auction config, referral cap, global reduce-only

Each side has three vaults: a reserve vault for cash, custody and every interest payout, a collateral vault for lending collateral and a leverage collateral vault. The accounts reference lists every field and the seeds that derive each address.

Where it lives

LayerPathOwns
Instruction adaptersinstructions/Accounts, validation, token transfers, custody checks and events
Transitionstransitions/Checked state changes; the identity and market invariants are in transitions/ledger.rs
Account methodsstate/One on-chain account per file, with its local invariants
Pure mathmath/Fixed-point curve, risk and interest math

The paths are under programs/dusk/src in the program repository. Persistent state, the few things that wait across transactions, has its own page: Lifecycles.