This repository has been archived on 2026-11-16. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
orderbook-collector/docs/adr/0004-exchange-seam.md
T
pascal 1a5bbcd602 feat!: a generic core, and Kalshi through it
The orchestrator, the connection loop and the book thread's shell move to
src/core/, generic over an Exchange and its loss rule (ADR 0004).
Polymarket runs through it unchanged. Kalshi joins: a signed handshake
(KALSHI_KEY_ID_FILE, KALSHI_PRIVATE_KEY_FILE), a reconnect on a skipped
sequence number, first one wins by clock and rank, and its market listing
with markets tracked from three hours before they open.

Breaking: the exchange is now the first argument,
`engineering-challenge <polymarket|kalshi|kalshi-demo> [OUTPUT]`.
2026-11-11 20:54:17 +00:00

51 lines
2.7 KiB
Markdown

# 0004. The exchange seam: a codec and a loss rule per exchange
## Context
Extension 3 asks for a generic service where "the only thing we need to
change is the encoding/decoding on the websocket layer". By M5 everything
lived in `src/polymarket/`, and M6 adds Kalshi. Most of the code is the same
for any exchange (the orchestrator, the connection loop, the book thread's
minute Snapshots, quiet watch and moves, the writer) or plainly per exchange
(URL, handshake, message formats, market listing). One part is neither: how
a loss is detected and how a symbol's two connections are merged
([0003](0003-first-one-wins.md)). Polymarket sends a hash of the whole book
with every change, which both verifies our book and says where a change from
either connection belongs. Kalshi has no hash: it numbers each connection's
messages and gives each market a clock. These are different mechanisms, not
two encodings of one.
## Decision
The seam has three parts. A **shared core** (`src/core/`) that names no
exchange. An **`Exchange` trait** for the websocket layer: the request, the
encoding of subscribe commands, the decoding of frames, the keepalive, and
the market fetcher. And, inside the book thread, a **rule supplied by the
exchange**: what a symbol's book does with an event from one of its
connections (a duplicate, the next change, held, a loss, a resync to ask
for), with its own per-symbol state.
The core understands of an event only the market it belongs to, which
routes it to a book thread, and whether it is a full book, which ends a move.
The event itself is the exchange's own type, handed to the exchange's rule
unread: the rule folds it into the symbol's book, which is the core's and
offers both ways a level changes (set to a quantity, moved by one).
## Why
Decode-only, as the brief's sentence reads, would put both loss rules in the
core, picked by exchange: the "generic" core would know each exchange's
quirks and a third exchange would mean editing it. A whole book thread per
exchange would keep the rules apart but write the minute Snapshots, the
quiet watch and the moves twice. With the rule behind the seam, the core is
really exchange-agnostic and the shell is written once. What the two rules
still share in shape (asking for a fresh book, and again when its connection
leaves or the minute passes) stays in each: their bookkeeping differs, and
Polymarket's was moved, not rewritten.
Trade-off: an exchange is more to write than a codec, and the seam is wider
than the brief asks. The book thread's shell and the rule also meet at more
points than a codec would (the minute's per-symbol questions, a connection
going down), so the rule's interface is the part most likely to move when a
third exchange arrives.