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 of a market, base or quote:
| Term | Stored as | What it is |
|---|---|---|
live_reserve | The side's live reserve | |
cash_reserve | Accounted cash, the only term a swap, withdrawal, loan or interest claim can pay out | |
fixed_*_shares times the borrow index | Public lending debt, accrued interest included | |
isolated_*_shares times the borrow index | Isolated leverage debt | |
flash_receivable | Collateral committed to an open hLP flash recovery; it must equal the vault's flash_collateral_debit | |
base_hlp_live_reserve, quote_hlp_live_reserve | Depth 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 , a nine-decimal fixed-point number that starts at 1.0 and grows as interest accrues. A book of shares owes , 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, . 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 .
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 on side exchanges cash for a loan claim of the same size:
This is borrow neutrality, which the whitepaper calls credit neutrality. 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 and on one side, and its output lowers them on the other.
Shares make the debt step slightly larger than . borrow mints shares on top of the side's , and its debt grows by
The program debits exactly of cash and adds the residue to . Principal grows by exactly , so the residue also lands in the unpaid interest below, and the executable reserve does not move by a single atom.
borrow commits the books before any token leaves:
- Accrue interest on both sides and refresh the curve and risk observations.
- Run the admission checks in Dynamic collateral factor.
- Debit , add the shares and principal, credit the residue to and store the position's factor.
- Transfer from the reserve vault, then check custody and that the borrower received at least
min_debt_amount_out. - Rebuild the curve from the new reserves and refresh risk.
The executable reserve
Interest accrues into , so it raises before any borrower pays. It is credited to holders at the same moment, so the curve trades only on what those claims leave:
is credited interest not yet claimed, owed to LP holders, the junior seed and the operator. is the protocol's share of the interest borrowers still owe; the protocol is paid only when they pay. is the funding interest the hedged vaults owe in this token: it accrues outside but is credited like public interest, so it is added back. is the token's recorded interest deficit, zero unless a loss has exceeded all LP capital.
An accrual of raises , or for funding, and by the same , so it never moves the curve. A repayment of interest adds less the protocol's share to , where is all interest outstanding, public and funding, and lowers by . A claim of lowers and by . Neither moves : repayments and claims change depth through cash, never the price.
srLP mints and burns against . Burning of shares pays 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%.
| Step | ||||||
|---|---|---|---|---|---|---|
| Start | 800,000 | 204,691.357800 | 3,909.464834 | 781.892966 | 1,004,691.357800 | 1,000,000 |
| Borrow 100,000 | 700,000 | 304,691.357800 | 3,909.464834 | 781.892966 | 1,004,691.357800 | 1,000,000 |
| 30 days of interest | 700,000 | 306,494.462524 | 5,412.052104 | 1,082.410420 | 1,006,494.462524 | 1,000,000 |
| New loan repaid in full | 800,493.150604 | 205,902.681800 | 5,412.052104 | 983.780300 | 1,006,395.832404 | 1,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; and would both rise by that atom and would stay put. Thirty days at 6% with the markup grow the index by , and the 1,803.104724 of new interest is credited at once: a sixth to , the rest to . The repayment burns the new loan's shares for 100,591.780724. The 100,000 of principal and the 591.780724 of interest enter , less the protocol's 98.630120, which moves to its revenue liabilities. Holders' does not change until they claim.
Solvency
Every debit of 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 , and with and never negative, the identity gives V1's solvency invariant:
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:
is swap-fee yield held for claimants, protocol revenue in escrow or pending release, inventory backing the hedged vaults and 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 , and a claim draws on the same cash as a withdrawal.
How each instruction moves it
Every path keeps the transition rule
| Instruction | |||||
|---|---|---|---|---|---|
| Swap | Plus the net input on one side, minus the output on the other | 0 | 0 | on each side | on each side |
| Add srLP | Plus a proportional deposit | 0 | 0 | ||
| Remove srLP | Minus a proportional payout | 0 | 0 | ||
| Borrow | , rounded up | 0 | Rounding only | 0 | |
| Interest accrual | 0 | Plus interest | Plus interest | Plus interest | 0 |
| Repay principal and interest , protocol share | 0 | 0 | |||
| Interest claim | 0 | 0 | 0 |
Of these rows, only trades and liquidity changes move , and with it the price. The other paths follow the same rule:
| Path | What moves |
|---|---|
| Swap fees | The protocol's share goes to its revenue lanes and the rest is LP income. Part of it compounds into and , part waits in fee custody , and the junior tranche's split is taken first. |
| Interest payments | Paid interest stays in except the protocol's pro-rata share, which moves to its revenue liabilities. Holders' credited interest does not change until they claim. |
| Leverage | Opening or increasing a position borrows from the debt side's cash into 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 liquidation | The repaid principal returns to and the repaid debt leaves . Recovery pays principal first; interest it cannot pay is written off as a pool loss. The junior part of the liquidation charge stays in , credited to Junior LP. |
| Emergency liquidation | The 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 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 exit | These move ownership between srLP and jrLP and never move an asset. |
| Hedged vaults | Deposits, withdrawals and every swap that reaches an active vault rebuild both vaults' srLP shares, funding debt and from the trade's endpoint. moves by the change in . A funding payment lowers the vault's debt, and only its protocol share leaves . |
| Harvests and revenue claims | Swap fees come from fee custody and referral and protocol revenue from . LP and operator interest is paid from , as far as it goes, and lowers by the same amount, so 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.
| Check | Condition | Error | Runs on |
|---|---|---|---|
| Reserve identity | The identity above, on both sides | BrokenInvariant | Swaps and every leverage action or liquidation that settles through the swap engine, junior conversion and seeding, hedged-vault changes |
| Market invariants | Equal 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, no more than that interest and any gap recorded as a deficit | BrokenInvariant | The same swap-engine paths, junior conversion and seeding, hLP flash recovery |
| Custody | The vault inequality above | UnbackedFeeLiability | The instructions listed under Solvency |
| Cash | Debits, payouts and loans within cash, and | InsufficientLiquidity, InsufficientBorrowHeadroom, CashReserveUnderflow; BrokenInvariant if would go negative | Every debit |
| Market health floor | Aggregate health at or above the floor, set at creation and at least 100% | InsufficientMarketHealth | Borrows, srLP removal, hLP deposits and withdrawals, settings execution, operator-share increases |
| Utilization guard | Both sides below 80% | UtilizationGuardExceeded | Settings 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, 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;
BrokenInvariantrejects 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 .
- The first srLP deposit mints shares for deposits and 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: and .
- A repayment is charged on the side's whole share bucket, for 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 mint shares, and each side is charged .
- 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
| Account | One per | Holds |
|---|---|---|
Market | Market | Config, 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) | Asset | Mint, vault addresses, reserve components, srLP supply, fee liabilities, the interest ledger and growth indexes, the daily borrow bucket |
BorrowPosition | Position, per market | Collateral, debt shares and principal per side, stored liquidation factors, referral binding, and the active liquidation session |
LeveragePosition | Position, per market | Debt asset, collateral, margin, notional, debt shares, multiplier, timestamps |
LeverageDelegation | Leverage position | The delegate program allowed to act and which actions it may take |
YieldAccount | Owner × market × LP mint × asset × kind | Checkpoints against the swap-fee and interest growth indexes, accrued amounts, any jrLP held in an exit request, recipient and harvest authority |
JuniorExitAccount | Owner × jrLP mint | One exit request: its jrLP, ready slot and the end of its exercise window |
JuniorCohort | jrLP mint | One junior generation; its growth indexes, frozen once it is retired |
OperatorProposal, OperatorRevenueAccount | Market × nonce; market × revenue epoch | Pending atomic bundle and the credited operator interest sealed at a recipient change; see Market operators |
ReferralPartner, ReferralAccrual | Partner, partner × market × asset | See Governance |
FutarchyAuthority | Protocol | Revenue 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
| Layer | Path | Owns |
|---|---|---|
| Instruction adapters | instructions/ | Accounts, validation, token transfers, custody checks and events |
| Transitions | transitions/ | Checked state changes; the identity and market invariants are in transitions/ledger.rs |
| Account methods | state/ | One on-chain account per file, with its local invariants |
| Pure math | math/ | 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.