The problemThe assignment

Build the coordinator server for a request-for-quote trading venue. Everything else (taker CLI, four stock makers, wire types, signing) was handed to you. The protocol has no spec document: common/ and the clients are the spec.

What you were given

The three primary challenges (from the README)

How it is graded (roughly in order of weight)

1. Protocol correctness: endpoints, schemas, error codes, and the error precedence you documented.
2. Balance integrity: reservations, atomic settlement, zero-sum conservation under randomized and concurrent load.
3. Signatures: canonical message, tampered / replayed / foreign envelopes, nonce monotonicity across action types.
4. Timing: windows close on time, late orders and accepts refused, reservations released on every terminal path.
5. Concurrency: many simultaneous RFQs, order/cancel storms, slow WS consumers, double-accept races.

Deliverables

• The workspace, building with cargo build --release -p server on stable Rust. Binary contract: --seed, --port, --accept-window-secs (default 5), /health 200 when ready, fully offline.
• Any scripts and tools that helped (you have scripts/smoke.sh and the black-box harness).
• A human-written SOLUTION.md: reconstructed protocol, state structure, atomic settlement, timing races, what you would do differently, how to run anything non-obvious, every policy rule, testing process.
• PROMPTS.md: every prompt to a coding agent, verbatim, in order (yours is appended automatically by a hook).

What you built, in one picture

The problemRFQ basics and units

Nothing rests on a book. A taker asks for a price on a specific size, makers answer with firm one-shot quotes that exist only for that request, and the taker trades on the best one or walks away.

Side conventions (easy to get backwards)

Units given by common

• USD: integer micro-USD. 1_000_000 = $1.
• Asset sizes: integer lots. Each asset has lot_decimals; 1 whole unit = 10^lot_decimals lots (SOL has 3, so 2 SOL = 2,000 lots).
• Prices: integer micro-USD per whole unit.
• Timestamps: unix milliseconds. IDs: UUID v4.
• Notional: floor(size_lots * price / 10^lot_decimals), product in 128 bits. The same single number is debited from the buyer and credited to the seller, so settlement is exactly zero-sum. common/src/types.rs:88

The protocolEndpoints and events

The protocol as reconstructed from common/src/types.rs, common/src/client.rs, and the clients. Router: server/src/lib.rs:31.

HTTP

Every signed body is an Envelope: {"pubkey": "<64 hex>", "nonce": n, "signature": "<128 hex>", "payload": {...}}. Every non-2xx body is {"error":{"code","message"}} on the status the code is grouped under in error_codes.

WebSockets

Event sequence per outcome

No new event types were invented: "failed" reuses the existing rfq_done outcome and TakerEvent::Failed.

Things the code decides for you vs. what it leaves open

See Money policies for the full list, each tagged given or our choice.

The protocolSignatures and nonces

The signed bytes are not the JSON body. They are a domain-separated, colon-delimited ASCII string built from the payload's fields in a fixed order. common/src/signing.rs:1

rfq-v1:{action}:{pubkey_hex}:{nonce}:{field_1}:{field_2}:...
absent optional field  ->  "-"
cancel order ref       ->  "id:{uuid}" or "cid:{u64}"

Why a canonical string instead of signing JSON?

• JSON has no canonical form (key order, whitespace, number formats), so two valid serializations of the same body would have different signatures.
• The rfq-v1 prefix plus the action name is domain separation: decline and subscribe both sign exactly one field, the rfq_id, so without the action name a captured subscribe frame could be replayed as a decline of the taker's RFQ. With it, the bytes differ.
• The pubkey and nonce are inside the signed bytes, so neither can be swapped.

Nonces strictly increasing per pubkey, across all action types

• Clients start at unix millis and fetch_add(1) per request (common/src/client.rs:72), which survives restarts.
• The server stores the last accepted nonce per pubkey and requires nonce > last. server/src/exchange.rs:334
• The WS subscribe frame uses the same nonce sequence.

When is a nonce consumed? our choice

Overlapping requests from one key

Nonce check and nonce write happen in the same critical section as the business logic, so two concurrent requests with nonces 10 and 11 can never both pass a check against 9 and then both commit. A consequence that follows from the protocol: if 11 is processed first, 10 is answered stale_nonce. That is the expected cost of strict monotonicity with out-of-order arrival, and it was left as is on purpose.

The protocolWebSocket feeds

Two feeds with different trust and delivery needs. The core rule: a consumer may be disconnected, but it is never silently skipped. server/src/ws.rs:1

Why disconnect instead of dropping events? our choice

A maker that silently misses rfq_done would never learn it was filled, and it would keep quoting on a wrong inventory picture. A closed socket is a loud, detectable failure (the stock maker exits with "maker feed closed by server"). Blocking the exchange until a slow reader catches up is not an option either: one slow consumer would stall every trader. So: never block, never skip, close the laggard.

Late subscribers our choice

A taker that subscribes after things happened gets a replay snapshot: subscribed, then the current quote if one is held, or the terminal event if the RFQ is over (then close 1000). Authentication, registration and the snapshot happen in one critical section (server/src/app.rs:116), so no event can fall between "take snapshot" and "start listening", and none can be delivered twice.

Why replay the quote: the CLI subscribes right after submit, but a reconnecting or slow client would otherwise have no way to learn the prices or the deadline it is holding. no_quote is not replayed after the fact because the RFQ is already terminal; its terminal expired is.

Event ordering

Events are produced by the state machine into a Vec and dispatched while still holding the lock, using only non-blocking sends. Therefore the order every consumer sees equals the order of state transitions, across both feeds. Nothing awaits under the lock. server/src/app.rs:156

The designArchitecture

Core-first: a pure, clock-free state machine, wrapped by one thin locking layer, wrapped by thin HTTP and WebSocket adapters.

One request, end to end: POST /v1/accept

1. Body<Envelope<AcceptPayload>> parses or 400. server/src/routes.rs:28
2. env.verify() rebuilds the canonical string and checks ed25519, or 401. No lock held. server/src/routes.rs:138
3. app.signed() takes the mutex, samples now after the lock is held, runs advance(now) (applies every overdue close/expiry in time order). server/src/app.rs:74
4. authenticate(): trader exists, nonce fresh, store nonce. server/src/exchange.rs:334
5. accept(): 404 / 403 / 409 / 422 checks, then compute all four resulting balances with checked arithmetic, then write them. server/src/exchange.rs:615
6. Events (taker settled, maker rfq_done) dispatched non-blocking, still under the lock. Lock released; JSON response.

State

Invariants checked after every operation (debug builds and tests)

server/src/exchange.rs:1065

• Conservation: sum of every trader's USD total and of each asset equals the seed (in u128).
• Reservations: per balance, reserved <= total and reserved equals the sum of what that trader's currently live orders hold (not the original amounts on historical orders).
• Room: incoming equals the room promised to its winners; zero where credits cannot overflow; total + incoming <= u64::MAX.
• Structure: order status agrees with its RFQ's state and winners; the cid index holds exactly the live orders with a cid; the timer queue holds exactly the pending transitions.

Why one global mutex?

• Balances are shared across RFQs (one maker quotes many RFQs; a trader can be maker and taker), so per-RFQ locks would not protect them.
• A single serial order makes every rule easy to state: "the first to take the lock wins" decides every race.
• The expensive part (ed25519 verify, ~59% of worker CPU in the storm profile) runs outside the lock. Profile at c=64: about 9% of worker time waiting for the mutex, about 2% holding it. See Performance.

The designMoney policies

Every rule, tagged by whether the shipped code decides it or you did. Graders check that SOLUTION.md states each choice and that the server follows it. Click a card to expand.

The designError precedence

When several things are wrong with one request, which error wins? The README grades "the error precedence you documented". This server's order is pinned, fault combination by fault combination, in server/tests/precedence.rs (254 combinations plus nonce-consumption probes).

Why this order?

• Cheap and stateless first. Shape errors need no lookup, and answering them first means a malformed request can never touch state or consume a nonce.
• Authenticate before revealing anything. 404/403/409 answers leak information about RFQs and orders, so they come only after the caller is proven to be a known trader with a fresh nonce.
• Existence, then ownership, then state. You cannot check who owns something that does not exist, and telling a stranger the state of your order would leak it. So not_your_order beats rfq_not_open.
• Money last. An order that is invalid for structural reasons (too small, duplicate cid) is rejected as such even if the maker is also broke; insufficient balance is only meaningful for an otherwise valid request.
• Exception worth knowing: on place, self_quote_not_allowed is a 422 but is checked right after the state check (409), before order_too_small. On cancel, the order is resolved and authorized before the state is checked, so a late cancel of your own order gets rfq_not_open.

The designTiming and races

Every race is decided by one rule: operations are serialized by the exchange lock, and each one is judged at the time sampled after it acquired the lock, after all overdue transitions have been applied.

The races the graders will throw

Clock policy our choice

The server's now is the host wall clock (unix ms), held monotonic: it never returns less than it already has. server/src/clock.rs:1

Why wall clock: the clients compare server timestamps with their own wall clocks. The CLI counts down to accept_deadline - unix_millis(); the sniper wakes at closes_at - 20ms by its clock. If the server's clock drifts, a published deadline is not honoured when the client's clock reads it.

The designIncoming room (overflow worlds)

The subtlest money rule. It only switches on for a currency whose total across the whole seed exceeds u64::MAX, which no normal seed does, but the graders run "different seed files" and a firm quote must stay firm in every valid seed.

The problem

u64::MAX = 18,446,744,073,709,551,615. In micro-USD that is about $18.4 trillion. Each balance is a u64, and common's seed parser accepts any u64 per balance.

• If a currency's world total fits in u64, conservation means no single balance can ever exceed it, so no credit can overflow. Nothing to do.
• If the world total exceeds u64::MAX (say two makers each seeded with $10T), a balance can be pushed toward the limit by other trades. Then a quote published at close might be impossible to settle at accept because the maker cannot receive the credit. That is a maker-side failure of a firm quote, which the design forbids.

The earlier version checked room at close and again at accept, but another trade could consume the maker's room in between. The adversarial pass reproduced exactly that.

The fix

1. At startup, mark each currency whose seed total exceeds u64::MAX (room_usd, room_assets). server/src/exchange.rs:268
2. At window close, an order is only eligible if both credits fit: the taker can receive what it gets and the maker can receive what it gets, without using room already promised to other quotes (credits_fit). server/src/exchange.rs:529
3. When it wins, in a tracked currency, the winner reserves its credit as incoming on its receiving balance (promote). server/src/exchange.rs:478
4. Every room check is total + incoming + credit <= u64::MAX (has_room), so nobody else's credit can eat promised room. server/src/exchange.rs:76
5. At accept: the maker side is covered by its reservation (debit) and promised room (credit). Only the taker can refuse: no funds, or no room to receive (for example because of room promised to its own winning quotes elsewhere). That fails the RFQ with insufficient_balance.
6. Room is released on every terminal path without a fill, and consumed on fill.

Why not reserve room everywhere?

Where the world total fits in u64, room is guaranteed by conservation, so tracking it adds state and checks that can never fail for a valid reason. Limiting it to overflow currencies keeps the common path identical to the simple design. A related check you worked through: a 40-decimal asset loads and does not break the math, but always rounds to zero notional with u64 size and price, so a_paid_trade_settles_beyond_18_decimals covers a real paid trade at high precision separately.

Evidence

• Unit tests: maker_usd_room_is_held_for_a_published_ask, maker_asset_room_is_held_for_a_published_bid, maker_cannot_spend_room_promised_to_its_quote_by_trading_as_taker, taker_room_used_up_by_its_own_trades_fails_like_insolvency, no_room_is_reserved_where_conservation_already_prevents_overflow, promised_room_is_released_on_every_path_that_ends_without_a_fill, credit_overflow_makes_an_order_ineligible_at_close.
• Black-box: the incoming_room scenario and fuzz --overflow. Seeds 212 and 214 are regression seeds for a harness oracle bug (the server was right; see Testing).

Play with itLifecycle walkthroughs

Step through real flows. Each step runs a JavaScript port of the exchange rules, so balances, reservations and events are computed, not drawn. Use ← → to step.

Balances (total / reserved / available; highlighted cells changed in this step)

Play with itState machine

Six RFQ states from RfqState; two live, four terminal. Click a transition to see what triggers it, what it emits, and where funds go.

Order states (server-internal, not on the wire)

Play with itSandbox

Drive the simulated exchange yourself. Same rules and error codes as the server's business logic (no signatures). Time only moves when you move it, which is how the unit tests drive the core.

Balances

EvidenceTesting

Layered so that each layer catches what the one below cannot, ending in a harness that knows nothing about the implementation.

Why a black-box harness on top

Unit tests and the fuzz model were written alongside the implementation, so they could share a misunderstanding. The black-box harness derives expectations only from the README, common and the shipped clients, plus a short list of documented policies (check.rs policy), and never links server code.

What it checks

• Ledger: when quiet, every balance equals seed + reported trades using only common's notional formula; nothing reserved.
• Reservations at two quiet checkpoints per round equal exactly what live orders and winning quotes should hold.
• Firmness: an accept by a taker who could certainly pay and receive, whose response arrived before the deadline, must settle at exactly the quoted price.
• No double settlement: at most one of any set of racing accepts and declines succeeds, and the feeds agree.
• Feeds: exactly the right event sequence on both feeds, consistent with GET /v1/rfqs/{id}, never before the time they announce.
• Timing evidence: a response that arrived before a deadline proves the request was in time; one sent after it proves it was late; anything else may go either way.
• Conservation is only summed over a single GET /v1/balances response, never across separate reads taken during trading.

Found and fixed along the way

Run it yourself

cargo test -p server                                   # everything incl. black-box quick pass
scripts/smoke.sh                                       # demo + shipped makers and CLI, checks conservation
cargo test --release -p server --test blackbox -- scenarios
cargo test --release -p server --test blackbox -- fuzz --seeds 1..50
cargo test --release -p server --test blackbox -- fuzz --overflow --seeds 1..20 --traders 6
cargo test --release -p server --test blackbox -- bench --workload all --levels 1,4,16,64,256 --secs 8
FUZZ_CASES=5000 cargo test -p server fuzz_core_against_reference_model

# by hand, three terminals
just server
just makers --offline
just submit --asset SOL --size 2 --direction buy

EvidencePerformance

Measured with the black-box bench on an Apple M1 (8 cores, 4 performance), 8 GiB, macOS, release build, harness and server on the same machine, accept window 1 s, 8 s per level. Rates count successes only, and every workload had 0 rejected requests, so fast rejections are not inflating anything.

How to read it

• Normal workload (whole RFQs: submit, subscribe, 4 quotes, accept or expire) scales linearly with sessions because each session spends most of its time waiting through the 1 s windows. It measures correctness under load, not capacity. Server CPU stays at 21% of one core at c=256.
• Storm (place+cancel on 32 open RFQs, 300 RFQs/s churning, 2 maker sockets that cannot keep up) plateaus around 44k ok requests/s from c=16, with the server at about 4.75 cores.
• Where the time goes (10 ms sample profile, storm c=64): ~59% of worker time in ed25519 verification, ~9% waiting on the exchange mutex, ~2% holding it. Signature checks run outside the lock, so the mutex is not the limit at this load. A 1 ms profile inflated lock waits to 33%, so that one is not trusted.
• Notification lateness (how long after closes_at the quote or rfq_window_closed arrives): p50 around 1 ms at every level; storm c=256 p99 13 ms for window_closed.
• Slow consumers: the never-reading maker socket was closed with 1008 "too slow" after about 5,100 events at every level, and no request was delayed by it.

EvidenceHow it was built

From PROMPTS.md (29 prompts so far, including task notifications). Useful when asked how you used AI and where your own judgment came in.

PrepareLimits and next steps

Things to be honest about, and directions to discuss when asked "what would you do differently with more time". These are prompts for your own thinking, not conclusions.

PrepareInterview questions

Likely questions with the facts and code you need to answer them. Try answering out loud before opening each one.

PrepareSOLUTION.md checklist

What the README requires the write-up to contain, plus every policy that must be stated so it is not "graded as an accident". Ticks are saved in this browser. Write the text yourself.