0The big idea#

A prediction market that quotes a price for any claim about an unknown number, and gets smarter every time someone trades.

Every market is about a single unknown real number θ (theta) — the outcome that will eventually be observed: “BTC price at month-end”, “the vote share”, “the temperature on Friday”. Until settlement, nobody knows θ. The market maker (the “MM”) holds a belief about it: a probability distribution p(θ). The belief we build all the intuition on is a Gaussian \( \mathcal N(\mu,\sigma^2) \) — a bell curve with a centre μ (its best guess) and a width σ (how unsure it is). A market can also run one of four richer densities — fat-tailed, multi-camp, or a skewed / bimodal shape — chosen at creation; §2 lays out the full family of five. We start with the Gaussian because every other model reuses its machinery.

A contract is a bet that pays some function of the outcome, \( f_C(\theta) \). Its fair price is simply the average payoff under the current belief — what it’s worth if the belief is right. The MM quotes a little above fair to buyers and a little below to sellers (the spread), and that gap is its only source of profit.

Because the belief moves toward informed flow and tightens with volume, the market price is the crowd’s consensus density over θ — readable live. The rest of this document is each of those seven steps, made precise.

1Core concepts & notation#

Money is stored as numeric(20,8) and every arithmetic result is passed through round8 (round-half-even to 8 decimals) — see §17. Formulas below omit the rounding for clarity; the code never does. Positions and MM inventory aggregate by a canonical contract key (type + params normalised to 12 significant figures, contractKey), so two specs that price identically share one book entry.

2The belief model#

The belief is a Gaussian density over the outcome. Everything the engine “knows” at any instant is these two numbers, μ and σ:

From it we read the density, the cumulative probability, and quantiles (for confidence intervals and sampling):

The 80% credible interval the UI shows is \( [\,\mu-1.2816\,\sigma,\ \mu+1.2816\,\sigma\,] \), since \( \Phi^{-1}(0.9)\approx 1.2816 \). Drag μ and σ and watch the mass move and stretch:

The belief is now a family — five shipped models

The Gaussian is the baseline, not the whole story. The belief is an interface — anything that can report mean / variance / pdf / cdf / quantile / sample can drive the engine — and a market now picks one of five shipped models at creation via a model tag. Pricing, reserve, spread, settlement and stats are written against the interface, so they are identical across all five; only the density and its learning rule differ.

The model tag is the creator-facing choice; the belief_kind is the underlying density class. They are not the same column: Gen·basis is a mixture belief run with mode-spawning and the placement primitive switched on, so it shares the mixture's closed-form pricing and responsibility update — it is a behaviour layer over the same density, not a new density. The two general families (Gen·basis ⛓, Gen·exact ★) are detailed in §7 (their updates) and §21 (the design study that produced them).

3Contracts & payoffs#

A contract is defined entirely by its payoff at settlement, \( f_C(\theta^\star) \). A holder of q units receives \( q\cdot f_C(\theta^\star) \). The seven v1 types:

The binary and spread payoffs are indicators (0 or 1), so their fair price is literally a probability. The GAUSSIAN payoff is a smooth “closeness” reward: full payout 1 exactly at \(c\), decaying with distance — the built-in proximity contract.

// packages/core/src/contracts.ts
case 'CALL': return Math.max(0, theta - spec.strike);
case 'GAUSSIAN': return Math.exp(-((theta - c) ** 2) / (2 * w * w));

Extension contracts — wider trade curves (Phase G5)

The orthogonality of belief and contract (the price is just \(\mathbb E_p[f]\)) means a new payoff is "add an \(f\) (+ its kinks, + a closed form where one exists)" — the belief side is untouched. Two tiers were added. G5.1 — bounded, \(f\in[0,1]\) (zero risk-model change, drop in everywhere):

G5.2 — unbounded, conditionally compatible (allowed only where they integrate and where liability can be bounded — see the compatibility table in §4):

4Fair price = E[payoff]#

The single most important equation in the system. The fair price of a contract is the expected payoff under the current belief:

For a Gaussian belief, every v1 contract has a closed form — no integration at runtime. Using \( d=\tfrac{\mu-K}{\sigma} \) (the z-score of the strike — how many σ the mean sits above \(K\), see §2):

Closed forms for the extension contracts (Phase G5)

Every extension contract still prices closed-form under a Gaussian (and, by linearity, \(\text{Price}(f,\sum_k\pi_k\mathcal N_k)=\sum_k\pi_k\,\text{Price}(f,\mathcal N_k)\), under a mixture — including Gen·basis):

The price sensitivity \( \partial\,\text{Price}/\partial\mu \) used by the adverse-selection spread (§5) is kind-agnostic for all of these via the translation identity \( \partial_\mu\mathbb E[f(\theta)]=\mathbb E[f'(\theta)] \): TENT/TRAPEZOID differentiate their CALL decomposition, POLYNOMIAL drops to its derivative polynomial \(\sum_k k\,a_k\theta^{k-1}\), and EXPONENTIAL gives simply \( a\cdot\text{Price} \).

Which contracts are compatible — integrability & boundedness

A contract is usable only if its price \( \mathbb E_p[f] \) is finite (a race between how fast \(f\) grows and how fast the belief's tail \(p\) decays) and its liability is boundable for the reserve (§6). The two conditions:

So EXPONENTIAL is rejected on a Student-t market (its \( \mathbb E[e^{a\theta}] \) is infinite), and a POLYNOMIAL of degree \(n\) needs \(n<\nu\) there. Independently, both unbounded contracts are allowed only on bounded-outcome markets (\(\theta^\star\in[\theta_{\min},\theta_{\max}]\)) so the worst-case payout — and the reserve — is finite; the EXPONENTIAL rate is additionally capped to \(|a|(\theta_{\max}-\theta_{\min})\le 20\). This is a precise, kind-dependent rule enforced at quote and trade (contractBeliefCompatible), not a nicety. A separate well-formedness check (validateContract) also rejects a constant POLYNOMIAL (degree \(\ge 1\) required — a flat payoff is not a bet) and a zero-rate EXPONENTIAL (\(a\ne 0\)).

The plot draws the payoff \( f(\theta) \) and the belief \( p(\theta) \) (green, scaled to fit). The fair price is the area of their product — change the belief or the contract and watch it move:

For arbitrary or custom payoffs without a closed form, the engine falls back to composite Simpson integration over \( \mu\pm10\sigma \) (expectF, 4000 nodes).

5Price sensitivity ∂P/∂μ#

How fast does a contract’s price move when the belief mean shifts by one unit? This derivative \( \partial \text{Price}/\partial\mu \) is the contract’s “delta”, and it feeds the adverse-selection spread (§8). Closed forms again:

Note a CALL’s delta is exactly \( P(\theta\ge K) \): deep in-the-money it tracks μ one-for-one (delta→1), far out it barely reacts (delta→0). That’s the intuition the spread uses to charge more on trades that could move the price a lot.

6Signal extraction#

When someone trades, they reveal information. The engine decodes a trade \( (C, q) \) into a signal \( s \) — the trader’s implied estimate of θ — and a weight \( w \ge 0 \) — how much to trust it. Define direction \( \text{dir}=\operatorname{sign}(q) \) and a clamped signal intensity \( \iota=\min\!\big(1,\ |q|/Q_\text{max}\big)\in[0,1] \). (The spread’s adverse-selection term in §8 uses the un-clamped \( |q|/Q_\text{max} \) instead — solvency-gated fills can exceed \( Q_\text{max} \), and there a larger order should keep widening the quote, whereas the belief must not be moved by more than one full-precision signal.)

The intuition: buying a CALL says “θ is above the strike”; selling it says the opposite. Buying a LINEAR pushes the signal above the current mean; selling pushes below. A range/point bet sets the signal at the target when bought, and pushes it away — along \( \operatorname{sign}(\mu-\text{target}) \) — when sold.

The weight rises with size but treats tiny trades as noise — below the threshold \( q_\text{th} \) it’s near zero:

Because \( \iota \) is clamped to \([0,1]\) and the soft gate \( 1-e^{-|q|/q_\text{th}}\in[0,1) \), the weight is always \( w\in[0,1) \) — an oversized fill (one the reserve gate of §10 let through above \( Q_\text{max} \)) saturates at full intensity rather than over-trusting the trade. The signal magnitude \( (1+\iota) \) saturates at \( 2 \) for the same reason.

7The Bayesian update#

With a signal \( s \) and weight \( w \), the belief updates by the conjugate Normal–Normal rule — a precision-weighted average of the prior and the signal. Precision is inverse variance; the signal’s precision is its weight over the signal-noise variance \( \sigma_\varepsilon^2 \):

The mean slides toward the signal, by an amount set by the relative precisions; the variance can only shrink (more data → more confidence). A floor \( \sigma'^2\ge\sigma_\text{min}^2 \) prevents runaway overconfidence. With the demo default \( \sigma_\varepsilon=\sigma_0 \), a full-weight signal moves μ about halfway to \(s\).

This widget runs the real loop: choose a trade, see the prior (grey) become the posterior (blue). Hit Commit & repeat to feed the posterior back in and watch the belief converge and tighten — the market learning:

Sandbox — watch a trade reshape a Gen·exact belief (v1 vs v2)

Author a shape with the \(\lambda\) knobs (push \(\lambda_2\) negative for a bimodal prior), pick a trade, and the widget runs both updates from the same prior: v1 (fixed shape) only slides and rescales the curve, while v2 (moment-projection) re-fits \((\lambda_3,\lambda_4)\) to the posterior skew/kurtosis. Commit & repeat feeds the v2 posterior back so you can watch order flow sculpt the shape over a stream. Every number is the faithfully-ported engine update — a parity self-check against packages/core logs to the browser console on load.

8The bid–ask spread#

The MM never trades at fair — it adds a half-spread on the way in and subtracts on the way out. The spread is the sum of four risk charges:

• Base — a flat \( s_0 \) (1%) of fair, the minimum edge.
• Inventory — grows with the MM’s post-trade net position \( |\text{mmShort}+q| \); the more lopsided its book, the more it charges to lean further.
• Adverse selection — \( \lambda \) times the trade intensity times the per-σ price move \( \big|\partial P/\partial\mu\big|\,\sigma \); big, price-moving orders pay more (they’re likely informed).
• Volatility — scales with relative uncertainty \( \sigma/\max(|\mu|,\sigma) \); a jittery market quotes wider.

The bid is floored at 0 — the MM can charge to take a contract back but never pays you to hand it over. Drag size and inventory to see which component dominates:

9Execution & position math#

Cost and cash, with signs

Total cost is signed by \( q \). A buy is a positive cost (you pay); a sell is negative (you’re paid). The MM’s cash moves opposite the trader’s wallet:

Average-entry accounting

Positions are long-only in v1 and tracked by average entry. A buy blends the average; a sell realizes P&L against it and leaves the average unchanged until a full close resets it:

Partial fills — solving the feasible size

If the full size would breach solvency (or the buyer’s balance), the engine fills the largest feasible amount. Both constraints tighten monotonically with size, so a 50-step binary search finds the frontier:

// tradeMath.ts · solveFill — feasibility test for a candidate size
const effectiveCash = cash + Math.min(0, totalCost);   // a buy's premium can't back its own risk
const reserveAfter  = requiredReserve(nextBook, belief);
const margin       = reserveAfter > reserveBefore ? openMargin : 1; // 1.2 to open, 1.0 to close
const solvent      = effectiveCash + EPS >= margin * reserveAfter;
const affordable   = side === 'sell' || isInfinite || balance + EPS >= totalCost;

10Reserve & solvency#

The MM is the counterparty to every trade, so it must hold enough cash to pay out in bad outcomes. The liability at a hypothetical outcome θ is what it would owe across its whole book:

The required reserve is the high-quantile (99th-percentile) liability under the belief — a Value-at-Risk. There’s no closed form across a mixed book, so it’s estimated by seeded Monte-Carlo:

// draw 50k θ's from the belief, evaluate L, take the 99th-percentile loss
const draws = belief.sample(n, rng);            // seeded → reproducible
for (...) losses[i] = liability(book, draws[i]);
losses.sort();
return Math.max(0, losses[Math.floor(alpha * (n - 1))]);

A trade is admitted only if cash covers a margin multiple of the post-trade reserve (1.2× when opening risk, 1.0× when closing). The plot shows the liability curve \( L(\theta) \) (red) against the belief; the dashed lines are the reserve and the expected liability — toggle inventory, μ, σ, and cash to trip the gate:

Production uses 50,000 samples seeded with 0x626d6d (“bmm”); this page uses 6,000 for responsiveness — the quantile is within a rounding cent.

11Settlement#

When an admin resolves the market with the true outcome \( \theta^\star \), each position pays its payoff. Full lifecycle (MarketStatus): CREATED → OPEN → RESOLVED(θ*) → SETTLED → CLOSED — a market is born CREATED (configured but not yet trading) and only accepts trades once OPEN. An admin may suspend a live market (OPEN ⇄ SUSPENDED), which halts trading without resolving it — the rapid-price-move circuit breaker of §14 recommends exactly this — or cancel it (→ CANCELLED), which unwinds every open position at cost rather than at payoff (below).

Trader payouts are paid from the pool, but — by design — they do not mutate markets.cash directly; the residual is computed logically so the cash-flow ledger reconciles exactly (see the admin market ledger). The leftover pool after all trader payouts is the LPs’ to claim:

Cancellation refunds

If a market is cancelled instead of resolved, no payoff is computed: every open position is refunded the capital still locked in it — its cost basis — and the MM hands back the premium it had collected. Only non-infinite (real) traders are credited:

Proximity settlement

The GAUSSIAN contract is the proximity-reward mechanism: a point bet at \( c \) with tolerance \( w \) pays \( \exp(-(\theta^\star-c)^2/2w^2) \) — e.g. with \( w=1000 \), being 500 off pays \( \exp(-0.125)\approx 0.8825 \), being 2000 off pays \( \exp(-2)\approx 0.1353 \).

12Liquidity providers#

LPs fund the MM’s cash and own pro-rata shares of its net asset value. The NAV is liquid cash minus the mark-to-model liability; the share price is NAV per share:

Deposits mint shares at the pre-deposit price (so you don’t dilute yourself); withdrawals burn shares for the current value (gated by the same 1.2× reserve rule):

At genesis the creator deposits the reserve \( R_0 \) and is minted \( S_0=R_0 \) shares (price 1). If the MM earns spread income, NAV rises above \( R_0 \) and the LP’s claim grows.

13Stats & metrics#

The “know your trade” analytics and market stats are all expectations under the belief. With fair price \( P=\mathbb E[f] \) and second moment \( m_2=\mathbb E[f^2] \):

The second moment has closed forms too: for indicators \( f\in\{0,1\} \) so \( m_2=P \); for LINEAR \( m_2=\mu^2+\sigma^2 \); for GAUSSIAN it’s a proximity price with width \( w/\sqrt2 \). The kinked CALL/PUT payoffs have a closed \( m_2 \) only under a Student-t belief (an exact truncated-moment form, studentTKinkSecondMoment); under the Gaussian and the other kinds they fall back to the Simpson integrator of §4. Tail risk and win-probability come from the same Monte-Carlo draws:

14Circuit breakers#

After each trade the engine evaluates safety conditions and emits alerts (v1 alerts the admin; it does not auto-suspend). Thresholds compare against the genesis \( \sigma_0 \) and the reserve:

15Capacity & the gate#

The reserve of §10 is not just a number the MM watches — it is a hard ceiling on how much risk a market can take on. A market's capacity is, in one line,

Because the MM is the counterparty (§10), a buy is not pure cash-in — it creates a liability. The premium collected is small; the worst-case payout owed can be large, and it raises the reserve. So every risk-opening trade is checked against the cash that backs it.

The admission gate

Both the quote (preview) and the execute (commit) paths run the identical test inside solveFill, so they can never disagree. A candidate fill of signed size \( q \) is admitted iff:

plus a buyer-side affordability constraint \( \text{balance}\ge\text{totalCost} \) (sells credit the trader, so they skip it). Two subtleties carry all the weight:

• The opening margin \( m=1.2 \). A trade that raises the reserve must be backed by a 20% buffer of cash above the new reserve; a trade that lowers it needs only \( m=1 \). The buffer absorbs the Monte-Carlo sampling error in the reserve and any belief drift between sizing and settlement. (It also surfaces in §14 as the insolvency-risk breaker.)
• effectiveCash excludes a buy's own premium. For a buy \( \text{totalCost}\gt 0 \), so \( \min(0,\text{totalCost})=0 \): the incoming premium is not counted as backing for the risk that same trade creates — otherwise a trade could self-fund unbounded exposure out of its own spread. The premium is still banked into cash (it becomes LP profit); it simply cannot collateralize itself. A sell has \( \text{totalCost}\lt 0 \), so its payout outflow is subtracted.

Partial fills

When the requested size doesn't fit, the engine doesn't reject outright — it sizes down. Both constraints are monotone in \( |q| \) (a bigger buy raises both the reserve and the cost), so solveFill binary-searches the largest feasible fill:

The “no-buy band”

This explains the surprising symptom — an open, solvent market that still refuses every buy, even a tiny one. Let \( \rho=\text{Reserve}/\text{cash} \). The pool is solvent while \( \rho\le 1 \), but it opens new risk only while \( \rho\le 1/1.2\approx 0.83 \) (any buy makes \( \text{Reserve}_{\text{after}}\gt\text{Reserve}_{\text{before}} \), forcing \( m=1.2 \)). So in the band

the market is solvent yet frozen for buys at any size; only trades that shrink the reserve — sells or offsetting bets — can pull \( \rho \) back down and thaw it.

Relaxing the limit — the developer's options

Capacity is \( \text{cash}/\text{risk} \), so there is no free lunch: every way to “bypass” the gate either adds capital, sheds risk, or hands the shortfall to someone. The full treatment with consequences is in docs/capacity/expanding-capacity.md; in brief:

The chosen direction is the soft cap: add a capacity-aware congestion term to the spread (§8) that is ≈ 0 with headroom and rises toward infinity as \( \rho\to 1 \), so the price ramps instead of hitting a wall — while the hard gate above stays as a backstop, so solvency and fixed payouts are untouched. Reference design:

Status: the gate above ships today; the soft cap and the other options are design choices. The soft cap is planned but not yet implemented — see docs/capacity/soft-cap.md and its build plan. Code: tradeMath.ts (solveFill), tradeSvc.ts (acceptance gate), solvency.ts (reserve).

16Config parameters#

Every knob, its symbol, default, and what it tunes. Absolute σ-parameters are derived from the market’s genesis \( \sigma_0 \).

The Gen·basis spawn / mixture-management constants (\(\tau_\text{spawn}\), \(w_\text{min}\), \(w_\text{seed}\), \(\pi_\text{min}\), merge tolerance, the \(K\)-cap) live in mixture_ops.ts (and are consumed by placement.ts), while the Gen·exact shape-fit clamps (\(\lambda_3,\lambda_4\) ranges) live in bayes.ts — rather than in EngineConfig, since they are structural to the general model rather than per-market knobs — see §7.

17Numerics & rounding#

The special functions everything rests on (accurate to ~1e-12, validated against known values):

erf uses a Maclaurin series for \( |z|<2 \) and a Lentz continued fraction in the tails. Randomness flows through a seeded mulberry32 PRNG — never Math.random — so Monte-Carlo reserve and tests are reproducible.

Money & rounding

All money is numeric(20,8). Every arithmetic result goes through round8 — round-half-even (banker’s rounding) to 8 decimals — so repeated operations don’t accumulate floating-point drift and ledgers reconcile to the cent:

// shared/src/money.ts
if (diff > 0.5) rounded = floor + 1;
else if (diff < 0.5) rounded = floor;
else rounded = floor % 2 === 0 ? floor : floor + 1; // tie → even

18Model validation — the Monte-Carlo harness#

Beyond per-function unit tests, sim.ts runs the entire loop end-to-end against synthetic informed traders to confirm the engine actually learns, stays calibrated, and earns its spread. A single run draws a hidden truth, lets noisy-but-informed traders arrive one by one, and settles:

Aggregated over many runs — one seeded RNG threads the whole experiment, so the report is fully reproducible — the summary answers two questions: did the posterior beat the no-learning prior, and is the credible interval honest?

19Price impact — how trades & liquidity move price#

This section ties the earlier pieces together into the one thing a trader actually feels: how much the price moves. There are two distinct effects. A trade leaves a lasting mark — it shifts the belief, so the fair price stays moved after the trade (this is price impact). It also pays a transient round-trip cost — the spread (§8) — that is not a price move at all, just a fee around the mid. We focus on the lasting part.

The lasting move is just the fair price (§4) re-evaluated on the post-trade belief (§7). To first order it factors cleanly into a delta (§5, how much price reacts to the mean) times a mean shift (§7, how far the trade drags the mean):

Both halves are driven by the trade intensity \( \iota=|q|/Q_\text{max} \): the signal reach \( s-\mu \) grows with \( \iota \) (§6) and so does the trust weight \( w \) (§6), which lifts the blend factor \( \kappa \). That single ratio is the lever behind all three charts below — and notice \( Q_\text{max} \) (market depth) sits in the denominator, so more liquidity shrinks every trade’s intensity, hence its impact.

All three plots price the same probe contract — a BINARY_CALL struck at the mean, so its fair price reads directly as the crowd’s probability \( P(\theta\ge K)\in[0,1] \), starting at 0.50. Flip the one switch to see a buy push it up vs a sell push it down:

20Slippage & price impact vs standard prediction markets#

Is a continuous belief market economically competitive with the well-known discrete platforms — Polymarket, Kalshi, Augur (central limit order books), and Manifold, Gnosis/Omen, Futuur (automated market makers)? The two costs a trader actually pays are:

• Price impact — how far the trade leaves the price moved (where the marginal price ends up). This is a lasting effect and a cost to the next trader / to you on the round trip.
• Slippage — the premium you pay over the pre-trade price to fill your order (your average fill minus the mid).

Every automated mechanism shares one law: impact and slippage scale like \( 1/\text{liquidity} \). What differs is the shape of the curve and, crucially, how the cost is packaged. The four families:

Drag liquidity — now log-scaled all the way to the billions, so you can watch every curve collapse toward dead-flat as LP capital grows — and drag trade size to read each mechanism at a chosen order. Flip the soft-cap fix switch (off by default) to overlay the capacity-congestion premium from the soft-cap design onto the BMM line: the faint line is BMM today, the bold line is BMM with the fix, and the dashed marker is the pool's capacity. All start at the same mid (\(0.5\)) on a binary, matched to a common liquidity budget so the comparison is apples-to-apples (calibration is approximate — the shapes and the \(1/\text{liquidity}\) scaling are the real lesson):

21Flexible parametric beliefs — a design study#

The key reframe: in a parametric world flexibility = the number of shape degrees of freedom (DOF), and there is a continuous spectrum between a Gaussian and a histogram:

Every family below already fits the engine: BeliefModel needs only pdf/cdf/mean/variance/sample, and expectF prices any pdf by quadrature when no closed form exists. So the question is which family, traded off along four axes — shape power, pricing cost, update difficulty, and on-chain feasibility. Pick a family and morph it; the scorecard reads its tradeoff live (drawn against the equal-\((\mu,\sigma)\) Gaussian, so any gap is pure shape):

Two threads run through that table. First, pricing path decides on-chain feasibility. Fixed-point chains can afford a polynomial approximation of \(\Phi\) but not \(\Gamma\), the incomplete beta, or a 4000-node quadrature run deterministically across nodes. So the only families whose price is a finite \(\sum_k w_k\,\Phi(\cdot)\) — Gaussian, mixture, and fixed-basis — are realistic on-chain; the special-function families are off-chain-only without heroic effort.

Second, the recommended sweet spot is the fixed-basis Gaussian density: \(N\) narrow bumps on a fixed grid with learnable weights,

It gives near-arbitrary smooth shapes (universal approximation as the grid densifies), prices in closed form as \(\sum_k w_k\cdot\text{price}_k\) — so no quadrature lag and the most on-chain-feasible flexible option — and updates by a trivial weight-only step. Best of all, a “click near \(\theta\)” maps directly onto “raise the weights of nearby bumps”, which is the parametric way to get the paint-the-curve feel without bins.