How onsails/polyfill2-rs works
1. What this repository is
- polyfill2 is a Rust client library for Polymarket’s CLOB V2 API.
- It is a migration fork focused on low-latency, zero-allocation hot paths, and compatibility with the V2 API contract.
2. Public surface and crate boundary
- src/lib.rs is the crate entry point and re-exports the client-facing API.
- The primary consumer-facing type is ClobClient, with domain enums/types such as Side and OrderType.
- The library boundary is “Polymarket API client,” not an app; callers embed it into their own async runtime.
3. Transport layer split: HTTP vs WebSocket
- The architecture separates request/response HTTP flows from the real-time WebSocket stream.
- HTTP is used for market discovery, account/order operations, and other REST-style reads/writes.
- WebSocket is used for streaming market/book updates and maintaining live state with minimal per-message overhead.
4. Client orchestration
- src/client.rs is the top-level orchestrator that likely composes config, auth, transport, and domain logic.
- src/connection_manager.rs handles connection lifecycle concerns such as reuse, keep-alive, and reconnection behavior.
- src/stream.rs and src/ws_hot_path.rs represent the real-time ingest path from socket bytes to book updates.
5. Domain model and stateful market data
- src/book.rs holds the order book state and update logic.
- src/fill.rs, src/orders.rs, and src/types.rs define market/order domain structures and transformations.
- The book is the main in-memory state machine: incoming snapshots/deltas are applied to maintain a current market view.
6. Authentication and order posting
- src/auth.rs encapsulates signing/authentication needed for Polymarket operations.
- The README notes a new EIP-712 order schema and updated contract addresses for V2, so auth/order submission is a key boundary.
- src/orders.rs likely translates domain orders into API payloads and signed actions.
7. Network and performance support subsystems
- src/http_config.rs carries client/network tuning choices, including HTTP behavior optimized for payload sizes and latency.
- src/dns_cache.rs provides DNS result reuse to reduce request startup cost.
- src/buffer_pool.rs is used to reduce repeated heap allocations in the networking/decoding path.
- src/config.rs centralizes runtime tuning knobs that affect transport, memory, and book depth behavior.
8. Decoding and hot-path processing
- src/decode.rs handles parsing of inbound payloads, especially WebSocket and JSON message shapes.
- src/ws_hot_path.rs and the README’s benchmarks emphasize the critical path: decode message → apply to book → emit result, with no heap allocation after warm-up.
- This is the latency-sensitive core of the system and the main place where performance measurements matter.
9. Error handling and utilities
- src/errors.rs defines the library’s error model across network, decode, auth, and domain failures.
- src/utils.rs contains shared helpers used across modules.
- src/http_config.rs, src/config.rs, and src/errors.rs form the control plane that keeps the client configurable but safe.
10. Data-flow shape
- Typical read path: caller invokes ClobClient → HTTP request goes through config/auth/transport → JSON is decoded into typed responses.
- Typical streaming path: WebSocket bytes arrive → decode/hot-path logic converts to domain updates → book.rs mutates the live book state.
- Typical trading path: caller creates an order → auth/signing and order encoding happen → HTTP order submission is sent → response/error propagates back.
11. State and memory architecture
- The repo explicitly optimizes for fixed-point arithmetic, cache-friendly data layout, and pre-allocated pools.
- buffer_pool.rs and the book implementation are the main memory-management boundaries.
- The architecture distinguishes cold paths that may allocate from hot paths that must remain allocation-free.
12. Validation, benchmarks, and examples
- tests/ contains integration tests for auth, WebSocket behavior, order posting, book snapshots, and price history.
- benches/ measures the hot paths: book updates, WS decode/apply, network behavior, and comparative performance.
- examples/ provides usage demos and benchmark programs, showing the library is designed to be embedded and performance-tuned by consumers.
13. Operational and delivery tooling
- The repo is built and tested with Cargo, GitHub Actions, and release automation (release-plz).
- docs/TESTING.md and the scripts/ directory support reproducible integration and benchmark workflows.
- These tools matter because performance claims are a major part of the project’s architecture and are continuously validated.
14. External dependencies and boundaries
- The external system boundary is Polymarket’s CLOB V2 API: REST endpoints, WebSocket streams, and signing-compatible order endpoints.
- The library assumes an async Rust runtime (tokio is implied by the examples) and is designed to be consumed from larger trading or market-data systems.
Main entry points: client.rs Client · book.rs Book · ws_hot_path.rs WS hot path · stream.rs Stream
Components 20
Core client
Public crate API and client orchestration.
- Crate API · Top-level library entry point and re-exports.
src/lib.rs - Client · Primary consumer-facing client that composes auth, config, and transports.
src/client.rs - Auth · Authentication and request signing for Polymarket operations.
src/auth.rs - Orders · Order construction, translation, and submission payloads.
src/orders.rs
Transport
HTTP and WebSocket connectivity layers.
- HTTP config · HTTP behavior and latency-oriented network tuning.
src/http_config.rs - Conn manager · Connection reuse, keep-alive, and reconnection control.
src/connection_manager.rs - Stream · WebSocket stream handling and event delivery.
src/stream.rs - WS hot path · Low-allocation decode-and-apply path for incoming socket messages.
src/ws_hot_path.rs
Domain state
Market/order data models and book state.
Support
Configuration, memory, decoding, and errors.
- Decode · Parsing of inbound payloads and message shapes.
src/decode.rs - Config · Client runtime knobs for transport, memory, and depth behavior.
src/config.rs - Buffer pool · Preallocated buffers to reduce heap allocation on hot paths.
src/buffer_pool.rs - DNS cache · DNS result reuse to reduce connection startup cost.
src/dns_cache.rs - Errors · Unified error types across transport, decode, auth, and domain layers.
src/errors.rs - Utils · Shared helper functions used across the crate.
src/utils.rs
Validation
Tests, benchmarks, and examples that exercise the client.
- Benchmarks · Hot-path and network benchmarks for latency and allocation behavior.
benches/ws_hot_path.rs - Integration tests · Integration coverage for auth, WebSocket behavior, orders, and book snapshots.
tests/integration_tests.rs - Examples · Embedding examples and benchmark-oriented programs for consumers.
examples/demo.rs
Connections 23
- Crate API → Client: re-exports · The crate entry point exposes the main client API.
- Client → Auth: uses · Client composes authentication for signed operations.
- Client → Orders: creates · Client builds and submits trading orders.
- Client → HTTP config: configures · Client applies HTTP and latency tuning settings.
- Client → Conn manager: manages · Client coordinates transport lifecycle and reconnect behavior.
- Client → Stream: subscribes · Client opens real-time market streams.
- Stream → WS hot path: feeds · Stream hands socket data to the latency-critical processing path.
- WS hot path → Decode: parses · Hot path decodes inbound wire payloads.
- WS hot path → Book: applies · Decoded updates mutate the live book state.
- Book → Fill: emits · Book state drives fill and execution events.
- Orders → Types: uses · Order encoding depends on shared domain types.
- Auth → Types: signs · Authentication is tied to domain order and request types.
- Client → Config: reads · Client behavior is driven by runtime configuration.
- Client → DNS cache: uses · Client can reuse DNS lookups for lower startup cost.
- Client → Buffer pool: uses · Client reuses buffers to avoid allocations on hot paths.
- Decode → Errors: reports · Parsing failures map into the library error model.
- Stream → Errors: reports · WebSocket and transport failures surface as unified errors.
- Book → Errors: reports · State application and validation errors propagate through the error model.
- Integration tests → Client: verifies · Integration tests exercise the public client boundary.
- Integration tests → Book: verifies · Tests validate snapshot and update logic for the book.
- Benchmarks → WS hot path: measures · Benchmarks focus on the decode/apply hot path.
- Benchmarks → Book: measures · Benchmarks measure order book update performance.
- Examples → Client: demonstrates · Examples show embedding the client in consumer runtimes.