​

Hearth — Technical README

​

1. What Hearth is

1. Price discovery, not price smoothing. The clearing price is the crossing point of committed bids and asks that maximizes executed volume (exchange opening-auction rules). The AMM does not set the price — users do, by committing funds to competing quotes.
2. Orders are transactions. A limit order is a TransactionExtraLimitDeposit (XFG or HEAT committed to escrow buckets). There is no gossip, no message signatures, no mempool of unsigned orders. Everything resting in the book is backed by funds that already settled on-chain.
3. One price, once per block, for everyone. The auction is batch-cleared: no ordering races, no MEV by transaction ordering, no front-running a queue.

​

2. Why this is more than “an AMM on a UTXO chain”

• Price-time priority on a privacy chain. The auction orders fills by price, then by deposit block height, then by order hash — a fair queue without revealing the owner (the owner is only an addressHash, a hash of spend+view keys).
• Self-trade exclusion by construction. A key may participate on only one side of the auction per block (its latest order’s side wins), closing the trivial wash-trade path without KYC.
• The mint price reads discovered prices. The HEAT mint TWAP is fed from P_clear (the auction’s last price), falling back to the pool ratio only during bootstrap. Money creation is priced by what people actually paid, not by an inventory curve.
• A treasury that is a market maker. The Treasury LP Manager takes protocol fee income in both assets, pairs them at the pool ratio, and deposits as the protocol’s own LP position — compounding, and driving bootstrap repayment by an owned-reserves check in both legs.

​

3. Architecture

                      ┌──────────────────────────────────┐
   Limit deposit txs  │  escrow buckets (pendingXfg/     │
   (tx-extra backed)  │  pendingHeat) + LimitDepositInfo │
                      └───────────────┬──────────────────┘
                                      ▼
                        Per-block processOrderbookForBlock
                                      │
                   ┌──────────────────┼───────────────────┐
                   ▼                  ▼                   ▼
            height expiry      CALL AUCTION          AMM backstop
            (claimable)    (user-vs-user crossing)  (pool as maker,
                                │                    volume-capped)
                                ▼
              P_clear = max-volume clearing price
                                │
                                ▼
                    mint TWAP ← P_clear (rolling 8-block)

​

3.1 Call auction

• Books are built from resting deposits: BUY_XFG (HEAT budget) → bids; SELL_XFG (XFG) → asks. Prices are in canonical scale: HEAT atomics per XFG atomic × COIN (1e7).
• Clearing price p* maximizes executed volume; ties break by imbalance, then proximity to the previous block’s P_clear, then lower price.
• Fills settle in price-time priority, rationing the larger side at p*.
• Value moves between the two parties’ escrow buckets — the AMM reserves are untouched by auction fills.

​

3.2 Fee model (1% taker, 70/30 split)

• The taker side (the rationed side) pays 1% of its fills’ price value.
• 70% (HEARTH_CD_SHARE_BPS) accrues to cdHearthFeeAccumulator (HEAT-denominated) and is minted into the CD yield vault (CD_APY_POOL) at the epoch boundary; the consumed XFG is burned 50/50 (Eternal Flame / SWF).
• 30% (HEARTH_MAKER_REBATE_BPS) is the maker rebate: distributed to the maker side pro-rata by fill value, with cumulative floors so conservation is exact.
• Exact volume ties have no taker: no fee, no rebate (pure exchange).
• On backstop/AMM fills the pool is the maker: 30% stays in LP reserves, 70% goes to CD yield.

​

3.3 AMM backstop

• Constant-product (xfg × heat = k), used only for the unfilled remainder.
• Volume-capped per block at HEARTH_BACKSTOP_MAX_BPS (500) of the block’s auction volume; uncapped when no auction volume exists (bootstrap).
• LP deposits are balanced-only; shares mint pro-rata (min(amountA·T/reserveA, amountB·T/reserveB)), never single-sided (single-sided mints nothing — no dilution).

​

3.4 Determinism and rollback

• Every fill (auction and backstop) is recorded in m_blockOrderFills with exact moved amounts, fees, and rebates; popBlock reverses them in reverse order.
• The epoch snapshot is captured at block start; dir-1 swap CD-fee HEAT equivalents are recorded per block for exact reversal (pop-time pool rates differ from push-time).
• No RNG, no float, no wall clock: the entire exchange is a pure function of chain state.

​

4. Economic flows

​

5. Key constants (v11)

​

6. Key files

​

7. What was retired (v11)

• The in-band CLOB matcher (OrderbookMatcher), MIN_DISTINCT_PARTIES, and gossiped orders — replaced by the backed auction.
• Single-sided LP mints — balanced deposits only.
• The old 50/50 fee-split and LP “spread reward” formula — replaced by the 70/30 taker/maker model and pool P&L.
• Pre-v11 price scales (Q64.64, 1e8, 1e18) — canonical 1e7 everywhere.

​

8. Status