Chapter ΙΑʹ · appendix

Glossary and appendix

Terms of art, the Elements and Simplicity primitives the design leans on, and how to compile and verify the frozen covenants yourself.

1Glossary

OBOL
The USD-pegged debt token. A native Liquid issued asset with a fixed, non-reissuable supply of 100,000,000. Named for the coin paid to the ferryman.
POLICY / L-BTC
Liquid bitcoin, the network's policy asset. The collateral and the fee asset.
vault
A per-position covenant UTXO holding L-BTC, with (debt, owner, last_height) committed in its address.
pot
The single constant-address UTXO holding the entire OBOL supply. Outstanding OBOL is by definition 100,000,000 - pot balance.
issuer / identity token
The singleton covenant holding the unique one-unit token that authorizes every mint and every bad-debt attestation.
stability reserve
The single constant-address L-BTC UTXO that backstops bad debt, funded by protocol fees.
CR - collateral ratio
collateral value / debt value, computed in the k-encoding k = CR_percent * 2,000,000. Debt is denominated in cents.
tick
One oracle observation: (height, price, backing_k), BIP-340 signed by exactly three of the five oracle keys.
backing_k
The global backing ratio (aggregate collateral value over outstanding OBOL at par), co-signed inside every tick, read only by the REDEEM floor.
last_height
The per-vault freshness ratchet: the height of the newest tick the vault has acknowledged. Removal operations require a strictly newer tick.
last_mint_height
The global mint anchor in the issuer's data leaf. Mints require a tick at least this fresh (non-strict, so equal-height mints do not serialize).
ratchet
Any stored height that can only move forward, and only to a quorum-verified value. The protocol's substitute for reading a clock.
quorum
The exactly-3-of-5 signature check over a tick, returning the (MIN, MAX) of the three prices.
keeper
Any party running the permissionless operations: liquidations, bad-debt clears, POKE, REFRESH. No registration, no whitelist. A keeper run purely to watch for and perform the liveness duties (POKE, REFRESH) is a watchtower.
redeemer
Any OBOL holder swapping OBOL for collateral at the peg floor via REDEEM.
CMR - commitment Merkle root
The root hash identifying a Simplicity program; the covenant analog of a script hash. Taproot leaves commit to it, and witness data does not change it.
data leaf
An unspendable taproot leaf (version 0xc4, starting with OP_RETURN) carrying protocol state next to the covenant leaf in the same tree.
NUMS
The canonical BIP341 nothing-up-my-sleeve point used as every covenant's taproot internal key, making the key path unspendable.
dd
The debt delta repaid in a partial liquidation.
golden CMR
A frozen CMR value recorded in the test gate; any behavioral change to a covenant flips it.

2Elements and Simplicity primitives

The design leans on a small set of platform facts; several of them shaped the architecture directly.

  • Explicit values, fail-closed. Covenant reads use unwrap_right(amount): an explicit amount is the Right branch, a blinded one is Left and the unwrap fails. Protocol outputs are therefore unblinded by construction, and a blinded decoy cannot satisfy a covenant read. Privacy of protocol amounts is deliberately given up.
  • Non-reissuable issuance. Issuing with no token amount creates no reissuance token at all - fixed supply is a property of the asset, not a promise.
  • u64 ratio math. There is no 128-bit compare or split jet, so all ratio checks are reformulated as required-collateral comparisons via coll_at_cr(debt_cents, price, k) = divide_64(debt_cents * k, price * 200), keeping every intermediate in u64. divide_64 truncates; every band and cap is arranged so truncation favors the protocol. Debt is asserted below 2^32 cents wherever it is priced.
  • Pruning and the anti-DOS rule. A covenant with a match must be pruned against the spending environment before encoding; untaken branches become hidden nodes, the CMR is preserved, and the pruned program fits the natural per-input budget - all STYX branches run at roughly 1,100 to 1,800 WU (1.1 to 1.8M milliWU) against a 4,000,050 WU consensus ceiling, well under a tenth of a percent of it, and every transaction relays as standard, with no annex.
  • Taproot under NUMS. The covenants rebuild tapleaf, tapbranch, and taptweak hashes bit-for-bit in Simplicity (tag sha256("TapLeaf/elements"), data-leaf version 0xc4), which is what makes address reconstruction - and therefore state-in-address - possible at all.
  • check_lock_height is a lower bound only. It proves a tick's height was reached, never that it is recent - the root reason every freshness property in STYX is a ratchet. Its jet semantics also make far-future heights unsatisfiable (chapter Εʹ).

Gotchas recorded in the build log

  • jet::sig_all_hash() commits to all inputs' annexes - attach any annex before signing (moot after pruning: no annex is needed).
  • A SimplicityHL witness value can be read once; bind it to a let to reuse.
  • Every declared witness needs a value even on a pruned branch - the "missing witness" trap that killed a two-tick redemption design.
  • BitMachine::exec does not enforce the anti-DOS case check: a local preflight can pass while the node rejects. satisfy_with_env gives the node's verdict.
  • An issuance attached to an unsigned input is rejected; hop genesis funds through a signed wallet coin first.
  • SimplicityHL has no includes - each program duplicates its helpers, which is why the five files share ~200 lines of identical hashing and quorum code.

3Compiling and verifying the covenants

The frozen CMRs are only meaningful under a pinned toolchain - same source, same compiler, same roots. The v1 pins:

  • SimplicityHL at git rev 63cd0924c44fc2fa0d774ef5083a3123865fb4d0 (v0.6.0-rc.0 line), consumed as a pinned cargo git dependency; covenants compile in-process, no separate simc binary needed.
  • elementsd with Simplicity: built from the ElementsProject simplicity branch, rev f957d3cd..., label liquid-testnet-2024-10-08.

To verify the covenants against this spec: compile the five .simf files with the pinned SimplicityHL rev (against fixed dummy parameters, as the golden-CMR gate does) and compare the resulting CMRs to the table in chapter Θʹ. To verify behavior, run the lifecycle against a regtest elementsd started with Simplicity active from genesis (-evbparams=simplicity:-1:::) - every accept and reject in this spec is reproducible as a node verdict. Reproducible compilation is what makes the golden-CMR gate and the deploy preflight meaningful; keep the pins.

4Provenance

The design grew through four on-node stages, each one proven against a real Simplicity node before the next was attempted: a single vault (covenant-enforced open, borrow, and oracle-priced liquidation), many vaults on one shared pot (per-vault debt committed in the address), owner-signed operations, and finally the complete v1 - the fee model, the liquidation ladder, the reserve, and redemptions. Every design decision along the way was recorded with its rationale and its rejected alternatives; this specification is the synthesis of that record, and for v1 it is the source of truth. The frozen covenant source, pinned by the golden CMRs, is the artifact it describes.