How floor-licker/polyfill-rs works
1. What this repo is
- polyfill-rs is a Rust client library for Polymarket’s CLOB API, not an application server.
- The main architectural goal is low-latency market data and trading access, with “zero-allocation hot paths” after warm-up.
2. Top-level library boundary
- src/lib.rs is the public entrypoint and re-exports the main client-facing types.
- Consumers interact primarily through ClobClient, order enums/types, market/book types, and streaming primitives rather than internal modules directly.
3. Request/response client subsystem
- src/client.rs is the core API surface for REST-style operations such as fetching markets, posting orders, and other CLOB calls.
- src/http_config.rs, src/connection_manager.rs, src/dns_cache.rs, src/buffer_pool.rs, and src/config.rs form the transport/performance layer around the client, optimizing request setup, reuse, resolution, and memory reuse.
4. Authentication and trading boundary
- src/auth.rs encapsulates authenticated trading concerns, likely including signing and request credential handling.
- src/orders.rs models order construction and posting, while src/errors.rs defines the failure boundary shared across network, auth, decode, and domain logic.
- README notes the 0.4.x line is V2-native and intentionally breaking for authenticated trading flows, so auth/order handling is a key compatibility boundary.
5. Market data and order book domain model
- src/book.rs is the central order book subsystem, holding market depth and applying updates.
- src/types.rs, src/stream.rs, and src/fill.rs provide the domain types and live-update representations used by the book and stream pipeline.
- The README’s performance notes indicate book creation and new price levels are intentional allocation points, while steady-state updates avoid heap activity.
6. WebSocket / real-time ingestion path
- src/ws_hot_path.rs is a dedicated low-overhead path for decoding and applying websocket book updates.
- src/decode.rs appears to be the shared parsing layer feeding both REST and websocket flows, with an emphasis on fast JSON handling and minimal allocations.
- The data flow here is: websocket message in → decode → domain update → apply to book/fill state.
7. Derived calculations and read-side queries
- src/book.rs likely also owns fast read operations such as mid-price, spread, and depth queries.
- src/utils.rs and src/fill.rs support these computations and transformations, keeping hot read paths simple and branch-efficient.
- The architecture separates ingestion/update cost from frequent query cost so read-side metrics stay fast.
8. Precision and numerical handling
- The README emphasizes fixed-point conversion at ingress and IEEE 754 conversion at egress.
- That means the repo likely treats price/tick math as a domain boundary: internal integer/fixed-point arithmetic for determinism, with float-compatible outputs only when needed for API compatibility.
9. Performance-oriented infrastructure
- src/buffer_pool.rs, src/dns_cache.rs, and src/connection_manager.rs are infrastructure modules aimed at reducing allocation and network setup overhead.
- These pieces support keep-alive behavior, pre-warming, and request reuse so latency-sensitive operations stay predictable.
10. Public examples as usage archetypes
- examples/ contains focused executables for demos, benchmarking, HTTP/2 tuning, keep-alive behavior, and trading/order scenarios.
- These examples act as reference entrypoints for different integration patterns: market reads, websocket handling, and performance evaluation.
11. Benchmarks as a first-class subsystem
- benches/ includes separate benchmarks for book updates, network performance, fill processing, websocket hot paths, and comparison runs.
- This signals that the repo’s architecture is explicitly validated around throughput, allocation behavior, and end-to-end latency rather than only correctness.
12. Testing and validation boundaries
- tests/ includes integration tests for websocket, auth, order posting, price history, and no-alloc hot paths.
- tests/common provides shared test harness support, indicating the repo validates both protocol correctness and performance-sensitive invariants.
13. Tooling and delivery
- CI is defined in .github/workflows/ci.yml, and the repo includes scripts for benchmark runs and integration tests.
- Cargo.toml/Cargo.lock define a standard Rust crate layout; there is no separate runtime service, queue, or database layer in this repository.
Main entry points: client.rs client · lib.rs lib · book.rs book · ws_hot_path.rs ws hot path
Components 18
Library
Public crate entrypoint and core runtime modules
- lib · Public entrypoint that re-exports client-facing types and modules
src/lib.rs - client · Core CLOB API surface for markets, orders, and other request/response calls
src/client.rs - auth · Authenticated trading and request-signing boundary
src/auth.rs - orders · Order construction and posting types
src/orders.rs - errors · Shared error types across network, auth, decode, and domain logic
src/errors.rs - types · Core market, price, and API domain types
src/types.rs - book · Central market depth state and fast read operations
src/book.rs - fill · Fill and execution update representations
src/fill.rs - stream · Live-update and streaming primitives used by realtime flows
src/stream.rs - utils · Support code for derived calculations and transformations
src/utils.rs
Performance layer
Connection, caching, and buffer reuse infrastructure
- config · Client and transport configuration knobs
src/config.rs - http config · HTTP tuning and request setup parameters
src/http_config.rs - conn manager · Manages persistent connections and request reuse
src/connection_manager.rs - dns cache · Caches DNS resolution to reduce network setup overhead
src/dns_cache.rs - buffer pool · Reusable buffers for low-allocation hot paths
src/buffer_pool.rs
Realtime flow
WebSocket ingestion and order book updates
- decode · Shared fast parsing layer for REST and WebSocket payloads
src/decode.rs - ws hot path · Low-overhead WebSocket decode and book-apply path
src/ws_hot_path.rs
Validation
Examples, benchmarks, and tests used to exercise the crate
- examples/tests · Representative demos, benchmarks, integration tests, and CI coverage
Connections 29
- lib → client: re-exports · Public API exposes the main client surface
- lib → auth: re-exports · Public API exposes auth-related types
- lib → orders: re-exports · Public API exposes order types
- lib → book: re-exports · Public API exposes order book types
- lib → stream: re-exports · Public API exposes streaming primitives
- lib → types: re-exports · Public API exposes core domain types
- client → config: uses · Client behavior is driven by runtime config
- client → http config: uses · HTTP tuning is part of request execution
- client → conn manager: uses · Client relies on persistent connection management
- client → dns cache: uses · Network setup benefits from cached DNS resolution
- client → buffer pool: uses · Client reuses buffers on hot paths
- client → auth: authenticates · REST trading flows require authenticated requests
- client → orders: places · Client posts constructed orders
- client → decode: parses · REST responses are decoded through shared parsing code
- decode → errors: fails via · Parsing issues surface through shared errors
- auth → errors: fails via · Authentication and signing errors use shared errors
- orders → types: builds on · Orders are assembled from shared domain types
- book → types: stores · Book state is organized around market domain types
- book → fill: tracks · Book maintains fill and execution state
- book → utils: computes · Derived metrics and queries use helper math
- ws hot path → decode: decodes · WebSocket messages are parsed through the shared decoder
- ws hot path → book: applies · Decoded updates are applied into the order book
- ws hot path → fill: updates · Realtime events update fill state
- ws hot path → stream: emits · Realtime flow produces stream primitives
- stream → types: carries · Streaming payloads use core domain types
- examples/tests → client: exercises · Examples and tests cover client workflows
- examples/tests → book: exercises · Examples and tests validate book behavior
- examples/tests → ws hot path: exercises · Benchmarks and tests validate the WebSocket hot path
- examples/tests → auth: exercises · Integration coverage includes authenticated trading flows