Archived
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]`.
51 lines
2.7 KiB
Markdown
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.
|