Skip to content
Testnet only: a reference implementation, not a production service.Tokens and bank transfers here are simulated and have no value.
Stablecoin ReferenceSign up on Testnet

Reserve rule and headroom

The reserve rule is one inequality that must hold for each asset at all times:

supply_expected + inflight_reserved ≤ available_reserves

The terms:

  • supply_expected is the supply the issuer believes is on chain. It changes only through confirmed mint and burn operations seen by the watcher.
  • inflight_reserved is the sum of reservations for signed transactions that have neither been confirmed nor expired yet.
  • available_reserves is the ledger's customer fiat balance plus the sum of every fresh reserve source value.

A reserve source is fresh while its value is younger than its maxAgeSeconds. An older value counts as zero, so stale data can only reduce headroom, never raise it.

Headroom is what's left: available_reserves − supply_expected − inflight_reserved. A mint may reserve only if its amount fits inside headroom.

How a mint reserves before it mints

requestMint(asset, amount) runs in one transaction:

  1. Lock the asset's reserve state row.
  2. Fail with mints_paused if minting is paused.
  3. Compute the available reserves.
  4. Check supply_expected + inflight_reserved + amount ≤ reserves; otherwise fail with insufficient_reserve_headroom.
  5. Record the reservation and add amount to inflight_reserved.

A reservation is tied to one signed envelope and its max_time. When the watcher confirms inclusion, the amount moves from inflight_reserved to supply_expected. When the envelope is confirmed expired, the reservation is released. Each happens exactly once, so a reservation can't be counted twice or lost.

When the rule breaks

Reconciliation runs every five minutes and on demand. It compares the ledger, the chain and the rails, and reacts:

CheckOn break
On-chain supply against supply_expectedStop the line: set mints_paused (Sev-1)
supply_expected + inflight_reserved against reservesStop the line: set mints_paused (Sev-1)
Ledger customer fiat against the rail's balanceWarn, and track the difference as in-transit with an age
Reserve source freshnessWarn

Resuming mints after a stop needs an operator, a written reason and an audit row.

Endpoints

Edit on GitHub