RFC: AX Liquidity Program

Date: 2026-08-03 (updated 2026-08-12)

Status: Part 1 partially built — the pure core, schema, settler, and admin CLI have landed; the snapshotter (book producer), public params API, participant read-out, and all of Part 2 are still unbuilt. See Implementation status.

Related: A-4316 / PR #3291 (alee/mmlp-executable-policy, Andrew Lee, draft) — the program's rules as executable code (rs/policy/mmlp); this engine builds on it (see "Builds on A-4316" below); generic program-payouts module (Part 2 credit path); execution plan liquidity-program.plan.yaml (rendered: docs/plans/liquidity-program.html) — phases, tracks, live PR status; customer notice AX Liquidity Program — Effective September 1, 2026 (the spec); dynamic fee engine (A-4094, shipped; plan retired), which this program sits beside; incremental VolumeRing (PR #3389, branch incremental-volumering-fee-tiering) — the trailing-window accumulator this borrows its cadence shape from; sibling docs price-band-automation (mark / best-bid-ask infra), referral-program + partner-rebate-payouts (USD-credit plumbing). No Linear epic or tickets exist yet — the ticket breakdown at the end is a proposal.

Author: (with Claude)

The program is fully specified to customers and has a hard Sept 1, 2026 effective date (30-day notice already sent), but is completely unbuilt, unowned, and unticketed. This RFC is the engineering plan to close that gap. It is a budgeted, per-product cash reward for resting maker quotes scored on quote quality, not fills — separate from and additive to the volume-tiered fee engine. $200k/month across ~35 products (Appendix B of the spec). The mechanism: snapshot every book once a minute at a random instant, score each trader's two-sided resting size by a quadratic proximity weight around the mark, normalize to per-snapshot shares, and pay each day's per-product pool out pro-rata subject to a 40% anti-concentration cap, a minimum-payout floor, and floor-to-cent settlement.

This was a design document; Part 1 is now substantially built (2026-08-12). The pure scoring/settlement core, the three tables, the epoch settler, and an admin CLI have shipped; the book-reconstruction producer, the public/admin params API, the participant read-out, and the entire Part 2 credit path have not. The Implementation status section maps every RFC proposal to its as-built code (or its absence). The design sections below are preserved as the original plan of record; where a path or crate name diverges from what shipped, the status section is authoritative.

Headline: the RFC's "80% needs no math and can be built before A-4316 lands" bet paid off, but not by building on A-4316 — that PR (#3291 / ax-policy-mmlp) never merged, and a fresh core crate ax-mmlp2 (rs/sdk-internal/mmlp2/) was written instead (see Builds on A-4316, now superseded). The pipeline is wired from the pure core through settlement into the accrual ledger, but the snapshotter that feeds it does not exist, so mmlp.liquidity_snapshots has no producer and the settler currently settles empty epochs. Nothing credits cash.

The RFC's blocking pre-work (does order_log decrement remaining_quantity on partial fills?) gates the snapshotter, and the snapshotter is exactly what's missing. Everything downstream shipped against a stubbed/empty snapshot stream; the CH table's shape is fixed but no code fills it. Q1 remains the top blocker for a live Part 1, unchanged from the original RFC.

The collision is resolved: MMLPv1 was removed in full (A-4812), so only one MMLP remains.

• MMLP-rewards (this RFC): crate ax-mmlp2, schema mmlp.*, host rs/accrual-engine/src/mmlp/.
• MMLP-performance (quoting-obligation monitoring, no cash): removed. It was crate ax-mmlp, schema mm_liquidity_performance.*, routes rs/api-gateway/src/{mmlp_routes,admin_mmlp_routes}.rs. The schema stays in db/postgres/1.sql permanently, together with the ax-mm-reports* S3 buckets its reports rows point at, as historical records. Neither is pending deletion.

mmlp_routes.rs and admin_mmlp_routes.rs now serve only this program, at /mmlp/v2 (client) and /admin/mmlp/v2 (admin). The MMLP_* env prefix is likewise unambiguous, and every var under it belongs to this program.

The build ships as two independent parts, and Part 2 is optional.

• Part 1 — Scoring & accrual (self-contained, v1). Reconstruct books, score, settle each day, and write the computed per-trader amount to an immutable accrual ledger — plus published params and a dashboard that shows accrued rewards. No cash moves. This is pure-compute + read APIs, carries no Finance/Legal gate, and is everything needed to honor the customer-visible promise on Sept 1 (scoring is live, params are published, everyone can see what they earned).
• Part 2 — Payout & credit (separate, later, human-in-the-loop). Turn approved accruals into actual USD credits. This is net-new "a scheduled job moves cash" plumbing that has never existed in AX (see D7) and is blocked on non-eng questions — tax/withholding, currency (USDfiat vs USDC), and an approval policy. Part 2 starts human-gated (an admin approves/pays a period's accruals) and only graduates to an automatic sweep once those gates clear.

Why the seam is here and not elsewhere: the accrual ledger is the clean contract between the two. Part 1's output is a row saying "account X earned $Y for epoch Z, computed and immutable"; Part 2's only job is to credit that row exactly once and mark it paid. Part 1 can run in production for weeks — accruing and displaying — with Part 2 entirely dark, and nothing about Part 1 assumes cash ever moves. This mirrors the partner-rebate-payouts accrual→sweep seam, and is deliberately the same shared plumbing (see D7).

The rest of this RFC labels every table, task, and ticket Part 1 or Part 2.

Superseded (2026-08-12). A-4316 / PR #3291 (ax-policy-mmlp) never merged. Rather than depend on it, the team wrote a fresh core crate ax-mmlp2 (rs/sdk-internal/mmlp2/, #3533 / A-4496) that owns the scorer, waterfall, gates, and params directly — the "interim stub → swap in Andrew's crate" seam described below never materialized because there was no crate to swap in. The reasoning below (don't fork the rules, keep one implementation) still holds in spirit: ax-mmlp2 is now that one implementation, and the customer doc should be generated from it. The A-4316 coordination questions are moot; the live question is whether ax-mmlp2 becomes the doc-generation oracle. The rest of this section is retained for historical context only.

The program's real name is MMLP (Market Maker Liquidity Program), and its rules already exist as code: A-4316 / PR #3291 ships rs/policy/mmlp — the scorer, the settlement math, and the params, default-features = false as the "normative core… the surface a production scorer/payout engine should depend on." The customer doc (the "PDF" this RFC's D2 distrusted) is generated from that code; every worked example is computed by the same functions. This engine builds on that crate — it does not re-implement the rules.

Decision: build on A-4316, don't fork the math. Re-writing scoring/settlement would create two implementations of the rules — the doc says one thing, the engine another — which is the exact drift "codeslaw" exists to prevent.

What is "the rules" (import from ax-policy-mmlp, never fork):

• Scorer (scoring.rs) — score_snapshot, ((v−d)/v)², two-sided min, normalized shares.
• Settlement math (payout.rs) — daily bonus-weighted average, the 40% cap waterfall (doc Appendix A), min-payout threshold, floor-to-cent. This is a rule, not plumbing: a maker disputes "why was I capped / forfeited / floored" against the doc, so its arithmetic must be the one shared implementation — same drift-criticality as scoring.

What is ours (everything around the rules):

• Book acquisition (D4) — his book.rs is a toy book (string traders, f64 prices) for worked examples; reconstructing the real attributed book from order_log and feeding his Book is the engine's job and the blocking crux.
• Snapshotter, persistence, the settlement job (read the day's snapshots, call his math, write accrual rows, conservation check), params storage + API + admin, and all of Part 2.

Start now, leave scoring/settlement a seam. ~80% of the engine (book acquisition, tables, snapshotter/settler scaffolding, params, API, payout) needs no math and can be built before A-4316 lands. The one open seam is a score_snapshot(params, book) -> shares trait with a stub; fill it with ax-policy-mmlp when the PR merges. Never write "our version" of the scorer even temporarily — the interim stub returns fake scores for tests, not a second rulebook.

Params source — now → later (the codeslaw end-state):

• Now: materialize Andrew's policy/mmlp_program.yaml (extended with the real $200k Appendix B) into mmlp.liquidity_programs via an engine-side adapter; the published API reads the DB.
• Later: move that materialization into his crate so the doc and the engine read one source (mirrors fee_program.yaml → fee_schedules).

Also settled by reading the crate:

• f64 scores, Decimal dollars. His deliberate split — real-valued score/share arithmetic (f64), exact Decimal only through dollar settlement, floored at the credit step. Adopt it (supersedes this RFC's earlier "Decimal everywhere"). One check: f64 determinism across platforms vs the "replayable" goal.
• Program cash does not count toward fee-tier volume (his README) — informs D3's combined-take question.

Naming collision (resolved by A-4812): "MMLP" was overloaded — mm_liquidity_performance (quoting-obligation monitoring/reporting, no cash) vs rs/policy/mmlp (this: quote-quality rewards). The performance program has since been removed; see the status section above.

Coordination questions for Andrew (gate, phase 0): (1) A-4316 merge timeline, or do we stack on alee/mmlp-executable-policy? (2) does the normative core stay in rs/policy/mmlp or graduate to sdk-internal for a runtime dependency? (3) is ProductParams / score_snapshot / DailySettlement the frozen API we build against?

Consequence for the decisions below: D2 is largely resolved — the crate is the oracle (pin its output), not "re-derive the AI examples." Phase T1 flips from "write the scorer" to "depend on ax-policy-mmlp + build the book adapter."

Seven decisions gate the build: the three the rollout thread flagged, the architectural fork the spec leaves open, two v1 scope cuts, and the payout-automation split (D7) that structures the whole PR into the two parts above.

The published PDF (§3.1) states sizes are not aggregated across a trader's orders "even at the same price level" — each order is judged individually against q_min. An earlier draft of this RFC recommended the opposite (sum size across a level before gating) for order-splitting invariance; that was reversed to keep the engine faithful to the customer-facing spec, which asserts its own worked numbers are computed by the implementation.

Decision: gate each order individually — an order scores only if its own size ≥ q_min (and d ≤ v); sub-q_min orders are dropped before the side sum. The load-bearing observation still holds that the gate is the only place aggregation matters: all orders at one price share the same distance d, so Σ w·qᵢ = w·Σqᵢ and the score of the surviving orders is unchanged whether summed per-order or per-level. The engine therefore still aggregates qualifying size per (account, side, price) for the score — it just applies the q_min gate to each qᵢ first, not to Σqᵢ. The cost is the loss of split-invariance (a fat-finger split below q_min silently forfeits, and fragmentation is penalized); the benefit is that engine and doc cannot diverge.

At q_min = 1 (shipping today) the two rules coincide — every integer-contract order qualifies individually — so this reversal is behavior-neutral for current params and only bites once a product publishes q_min ≥ 2. Pinned in the scorer test suite so the rule cannot silently regress.

Original framing: the PDF's worked examples were AI-generated and not hand-verified, so re-derive the math and don't trust the tables.

Resolved by A-4316: the doc is now generated from rs/policy/mmlp, and every worked example is computed by the same scoring.rs/payout.rs functions the engine will call — so the crate, not the PDF and not a hand re-derivation, is the source of truth. Recommendation: depend on the crate and pin its output as the insta fixtures; the engine and the doc can never disagree because they run the same code. (As a sanity check this RFC hand-re-derived Examples 1 and 3 and they hold — Ex1 Alice 0.8 / Bob 0.2; Ex3's two-round waterfall conserving to $166.67 with `$66.66 / $66.66 / $33.33` paid — consistent with the crate being correct.) See "Builds on A-4316" above.

The program is additive to fee tiers, so a barely-trading MM on a thin product can collect program cash and deep fee discounts at once; nothing caps the sum. Andrew floated reintroducing a −0.5bps top maker tier; Brett vetoed any negative-fee tier ("introducing −0.5bp makes us lose money").

Recommendation: v1 keeps the program purely additive, adds a per-(MM, product) combined_take metric (program cash earned + notional value of the fee discount vs. the top public maker rate), and defers any cap to a data-driven fast-follow. Negative-fee tiers are out (Brett's veto stands). Rationale: a combined cap couples two independently-budgeted systems and forces a contestable definition of "discount relative to what baseline"; meanwhile the program's own 40% anti-concentration cap and the fixed per-product monthly pool already bound total cash outflow with certainty. The right first move is to measure whether double-dipping is real before building machinery to cap it — the metric is cheap and answers the question. If the data shows abuse, a combined cap or a claw at settlement time slots in without touching the scorer.

This is the central architectural fork and the spec is silent on it. Scoring is per trader, which needs per-order → account attribution at the sample instant. The public L3 book in marketdata-publisher (rs/marketdata-publisher/src/lib.rs) carries no account identity; EP3 is the source of truth for resting orders; order-gateway holds per-account OpenOrders in memory (rs/order-gateway/src/open_orders.rs) but only as live state, not a queryable as-of snapshot.

Two options:

• A — live account-aware snapshotter. A new obligate-singleton service holding a privileged EP3 order/book subscription; at a random instant each minute it walks every book with account attribution and emits scored rows. Accurate live state, but a new always-on writer, and "random instant" means it must continuously hold current state in memory.
• B — reconstruct from order_log. order_log (db/clickhouse/init.sql:83-115) is a full per-order lifecycle event stream carrying account_id, user_id, symbol, side, price, quantity, remaining_quantity, order_state, event_timestamp_ns. An order rests at instant t iff it entered a working state before t and its terminal event is after t (or absent). Pick the random instant per minute after the fact and reconstruct each book from the log.

Recommendation: Option B, contingent on verifying order_log captures intra-life resting-size changes (partial fills). Post-hoc random sampling is strictly more gaming-resistant than a live snapshotter — a trader cannot observe or be tipped off to the sample instant if it is chosen after the minute closes — and it reuses recon-engine + ClickHouse with zero new always-on writers, and it is deterministically replayable for disputes (recompute a whole day from the log). The one risk is precision: the comment at db/clickhouse/init.sql:67-81 says only order_state = Pending carries full details and rows are emitted for state transitions, so partial fills may not decrement resting size in order_log — which would make reconstructed resting size stale between placement and terminal. Verification task (blocking): confirm whether partial fills emit order_log rows with updated remaining_quantity. If yes → Option B as-is. If no → the cheaper fix is to enrich order_log (or a sibling resting_order_events stream) with resting-size deltas — far less than a new live service — and only fall back to Option A if enrichment proves infeasible. The market_snapshots best-bid/offer sampler (db/clickhouse/init.sql:319-336) is the precedent for per-symbol snapshot cadence and an independent cross-check on the reconstructed mark.

The payout formula weights snapshots by B(t). Ship the weighted-average formula in v1 with all windows defaulting to B(t) = 1 (the spec's default), so payouts are correct from day one with no window config. The admin surface to define non-unit windows is a fast-follow — it changes incentives, not correctness, and no product needs a non-unit window on Sept 1.

The spec gates these tools to participants who earned ≥1 reward in the trailing 30 days — which by definition nobody has on Sept 1. Scoring → accrual → published-params API are v1-critical; the dashboard and the on-book band highlight can land in the weeks after launch. But note: a thin "accrued today" read-out is v1-valuable — with Part 2 dark (D7), the accrual number is the only proof to a participant that the program is working, so a minimal accrued-balance view ships in Part 1 even though the full gated dashboard is fast-follow.

The spec tells customers rewards are "credited to the customer's AX account at the end of each daily epoch." But a scheduled liquidity-reward job that moves cash still does not exist in AX. The transaction-engine Deposit mechanism exists, and treasury-engine now has shared settlement consumers for manual and automated Anchorage deposit decisions: treasury_engine.deposit_credit_attempts records immutable request identity, while treasury_engine.deposit_credits owns the canonical one-effect-per-deposit result and its transaction_event_id. Settlement writes ClickHouse before committing Postgres; a later Postgres commit failure can leave an orphan ClickHouse row for reconciliation. That core is deposit-specific and is not runtime wiring for a liquidity sweep; the existing ax_scheduler::run_periodic jobs still only compute and update rows (fee refresh, leaderboard). The partner-rebate monthly sweep is RFC-stage, blocked on tax/withholding, currency (USDfiat vs USDC), and approval policy. Reward cash is plausibly 1099-reportable — a Finance/Legal gate, not an eng one.