Market

A prediction-market engine with an automated market maker.

Overview

Prediction markets (Polymarket, Kalshi, the old internal markets at every big tech company) turn opinions into prices: people buy shares in "YES" or "NO" on some outcome, the price moves with demand, and when the event resolves, each winning share pays out one dollar. The clever part is the market maker. Instead of matching buyers to sellers, an automated market maker (the standard one is Hanson's LMSR) always quotes a price from a cost function, so there is always liquidity and the math is fully determined: every trade has exactly one correct price, cost, and resulting state.

You're going to build the engine. Users trade YES/NO shares against an LMSR market maker, prices update, balances and positions track, and on resolution the winners get paid. It has to be exactly right, and it has to stay right when trades land concurrently on the same market.

Problem Statement

Build the backend and a minimal trading UI for binary prediction markets run by an LMSR market maker. Support creating markets, quoting prices, buying and selling shares (priced by the cost function), tracking per-user balances and positions, and resolving a market so winning shares pay out. Trades on the same market must be atomic: concurrent trades must produce exactly the state that applying them one at a time would, with no lost updates, no negative balances, and no overselling.

The market maker (LMSR)

Each market has a fixed liquidity parameter b (provided). Let q = (q_YES, q_NO) be the net shares outstanding of each outcome.

Cost function:  C(q) = b * ln( exp(q_YES / b) + exp(q_NO / b) )
Price:          p_i  = exp(q_i / b) / ( exp(q_YES / b) + exp(q_NO / b) )
Cost to trade d shares of outcome i:   C(q with q_i += d) - C(q)
                                       (a negative cost is a payout, i.e. a sell)

Prices always sum to 1. Implement these directly; the engineering is the test, not deriving the formula.

Getting Started

Prerequisites

• Node.js 20+
• Any modern framework (Next.js, Vite + React, SvelteKit). Starter is Next.js.

Setup

Dependencies are installed automatically when you initialize the assessment with the Litmus CLI. You're ready to start coding.

Files in the workspace:

• types.ts defines Market, User, Trade, and Outcome.
• data/seed_markets.json has a couple of seed markets and a deterministic example trade sequence to develop against.
• tests/CONTRACT.md is the API contract the grader drives, including the invariants it checks.

Requirements

1. Expose an HTTP API (see tests/CONTRACT.md): create a market, get its prices, trade, get a user's balance and positions, and resolve.
2. LMSR correctness: GET prices equal softmax(q / b) and sum to 1; a trade's cost equals C(q') - C(q) exactly. Each user starts with a fixed balance (provided).
3. Trading: buying d shares of an outcome charges C(q') - C(q) and increases the position; selling (negative d) refunds and decreases it. Reject a trade that would overdraw the balance or sell more shares than the user holds. Balances never go negative; positions never go below zero.
4. Atomicity: concurrent trades on the same market must apply atomically. If N trades on one market land at once, the final q, prices, balances, and positions must equal the result of applying them sequentially. No lost updates.
5. Resolution: resolve(outcome) pays each holder of the winning outcome 1.0 per share into their balance, pays losing shares 0, clears positions, and closes the market to further trades.
6. Accounting integrity: no funds are created or destroyed beyond the market maker's bounded subsidy (LMSR's max loss is b * ln 2 for a binary market). Document your accounting.
7. A minimal trading UI: current prices, the user's positions, buy/sell, and a resolution view. The grader drives the API; keep the UI simple but real.

Examples

Example 1: Price after a buy

POST /markets { question: "Will it rain tomorrow?", b: 100 }   -> { market_id, prices: { YES: 0.5, NO: 0.5 } }
POST /markets/{id}/trade { user_id: "u1", outcome: "YES", shares: 50 }
  -> cost = C([50,0]) - C([0,0]); YES price rises above 0.5; prices still sum to 1

Example 2: Concurrency

20 buys of YES on the same market, fired concurrently.
Final q_YES == 20 * shares, and final prices/balances == applying the 20 trades one at a time.

Example 3: Resolution

POST /markets/{id}/resolve { outcome: "YES" }
  -> every YES share pays 1.0 into the holder's balance; NO shares pay 0; further trades rejected.

Submission Guidelines

What to Submit

• All source code (backend, frontend, anything else you build).

How to Submit

litmus submit

Implementation notes

DESIGN.md is the full design and the reasoning behind each choice. This section is the short version: how to run it, how it's laid out, and how the accounting works (Requirement 6).

Running

npm run dev                    # http://localhost:3000 — API + UI
npm run smoke                  # 52 assertions against a running server
npm run build && npm start     # production build (routes must work here too)

The grader hits the API at the root path (POST /markets, not /api/...). The UI is at /. GET /audit is an extra endpoint — the executable version of the accounting below.

Layout

Atomicity in one paragraph

Every state change goes through one global lock whose critical section is strictly synchronous (withLock<T>(fn: () => T) — the type forbids an await inside). Node runs that block to completion without interleaving, so a read-modify-write is atomic. The lock is global rather than per-market because a user's balance is shared across markets, and a per-market lock could not protect it. The order inside is READ → SCREEN → PRICE → AFFORD → COMMIT → SNAPSHOT: affordability is checked after pricing (you can't know if a trade overdraws until you've priced it) and inside the lock (checking before is the TOCTOU bug that lets two concurrent buys both pass a stale balance check). A rejected trade throws before COMMIT, so it leaves the world byte-for-byte unchanged.

Accounting (Requirement 6)

Where money comes from and goes. Every user is minted with 1000 on first reference. A buy of d shares moves C(q') − C(q) from the user to the market maker; a sell moves it back (a negative cost is a refund). On resolution, the maker pays each holder of the winning outcome 1.0 per share.

What the maker collected is derived, not accumulated. For a market that opened at q = 0, the total the maker has collected is exactly

collected = C(q_final) − C(0)

because trade costs telescope: Σ [C(qₖ) − C(qₖ₋₁)] = C(q_final) − C(q_0). The audit computes collected straight from the current q rather than keeping a running sum — a running total can drift from the truth by accumulated float error; a value derived from q cannot. (The smoke harness keeps an independent running sum and checks the two agree — they do, to relative error < 1e-12.)

The subsidy is bounded by b · ln 2. On resolution with winner W, the maker's net is collected − payout = [C(q_f) − C(0)] − q_W, so its worst-case loss is

payout − collected = q_W − C(q_f) + b·ln2  ≤  b·ln2

since C(q) = b·ln(Σ e^{qᵢ/b}) ≥ b·ln(e^{max(q)/b}) = max(q) ≥ q_W. The bound is tight — equality is the worst case — so /audit checks subsidy ≤ b·ln2 + 1e-6 rather than a strict ≤, which one ulp of float noise would fail on a correct engine.

Global conservation, checked live by GET /audit:

Σ balances  ==  1000 · (users minted)  −  Σ collected  +  Σ payouts

This holds no matter the interleaving of concurrent trades, because it depends only on the final q (order-invariant) and the mint count — not on who traded in which order. /audit returns both sides, the delta (0 on a correct run), each market's subsidy against its ceiling, and the q == Σ positions check for every open market.

One invariant underwrites the rest. A user can only sell shares they hold, and qᵢ moves by the same d as their position, so qᵢ == Σ_users positions[market][i] at all times a market is open. That single identity is what guarantees positions never go below zero, q never goes negative, and resolution can pay out q_W knowing it exactly matches the shares people hold.

Deliberate scope decisions

• In-memory, single process. The contract needs no persistence. This is correct under next dev / next start (one process); it would need a real serializable store behind a cluster or serverless — the withLock seam is where BEGIN … SELECT FOR UPDATE … COMMIT would go. The store logs its pid once so a stray second process is visible rather than silently wrong.
• No slippage protection. A quote can move against you if another trade lands first. Real venues take a max_cost; the contract doesn't ask for one.
• Rejections are all-or-nothing — an overdraw is rejected, not partially filled, matching the contract's "reject a trade that would overdraw."
• shares: 0 is a 200 no-op (cost: 0), not a rejection — it violates no invariant, and the contract only mandates rejecting overdraw and oversell.