# onsails/polyfill2-rs architecture

> Architecture diagram of the GitHub repository onsails/polyfill2-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onsails/polyfill2-rs
- Repository: https://github.com/onsails/polyfill2-rs

## Overview

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: [`src/client.rs`](https://github.com/onsails/polyfill2-rs/blob/main/src/client.rs) (Client), [`src/book.rs`](https://github.com/onsails/polyfill2-rs/blob/main/src/book.rs) (Book), [`src/ws_hot_path.rs`](https://github.com/onsails/polyfill2-rs/blob/main/src/ws_hot_path.rs) (WS hot path), [`src/stream.rs`](https://github.com/onsails/polyfill2-rs/blob/main/src/stream.rs) (Stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core client"]
  node_lib["Crate API<br/>crate entry<br/>[lib.rs]"]
  node_client["Client<br/>orchestrator<br/>[client.rs]"]
  node_auth["Auth<br/>signing<br/>[auth.rs]"]
  node_orders["Orders<br/>order encoding<br/>[orders.rs]"]
end

subgraph group_transport["Transport"]
  node_http_config["HTTP config<br/>transport config<br/>[http_config.rs]"]
  node_conn_mgr["Conn manager<br/>lifecycle"]
  node_stream["Stream<br/>ws ingest<br/>[stream.rs]"]
  node_ws_hot["WS hot path<br/>[ws_hot_path.rs]"]
end

subgraph group_state["Domain state"]
  node_book[("Book<br/>state machine<br/>[book.rs]")]
  node_fill["Fill<br/>market event<br/>[fill.rs]"]
  node_types["Types<br/>[types.rs]"]
end

subgraph group_support["Support"]
  node_decode["Decode<br/>parser<br/>[decode.rs]"]
  node_config["Config<br/>[config.rs]"]
  node_buffer_pool["Buffer pool<br/>memory pool<br/>[buffer_pool.rs]"]
  node_dns_cache["DNS cache<br/>network cache<br/>[dns_cache.rs]"]
  node_errors["Errors<br/>error model<br/>[errors.rs]"]
  node_utils["Utils<br/>helpers<br/>[utils.rs]"]
end

subgraph group_validation["Validation"]
  node_benches["Benchmarks<br/>performance suite<br/>[ws_hot_path.rs]"]
  node_tests["Integration tests<br/>test suite"]
  node_examples["Examples<br/>usage demos<br/>[demo.rs]"]
end

node_lib -->|"re-exports"| node_client
node_client -->|"uses"| node_auth
node_client -->|"creates"| node_orders
node_client -->|"configures"| node_http_config
node_client -->|"manages"| node_conn_mgr
node_client -->|"subscribes"| node_stream
node_stream -->|"feeds"| node_ws_hot
node_ws_hot -->|"parses"| node_decode
node_ws_hot -->|"applies"| node_book
node_book -->|"emits"| node_fill
node_orders -->|"uses"| node_types
node_auth -->|"signs"| node_types
node_client -->|"reads"| node_config
node_client -->|"uses"| node_dns_cache
node_client -->|"uses"| node_buffer_pool
node_decode -->|"reports"| node_errors
node_stream -->|"reports"| node_errors
node_book -->|"reports"| node_errors
node_tests -->|"verifies"| node_client
node_tests -->|"verifies"| node_book
node_benches -->|"measures"| node_ws_hot
node_benches -->|"measures"| node_book
node_examples -->|"demonstrates"| node_client

click node_lib "https://github.com/onsails/polyfill2-rs/blob/main/src/lib.rs"
click node_client "https://github.com/onsails/polyfill2-rs/blob/main/src/client.rs"
click node_auth "https://github.com/onsails/polyfill2-rs/blob/main/src/auth.rs"
click node_orders "https://github.com/onsails/polyfill2-rs/blob/main/src/orders.rs"
click node_http_config "https://github.com/onsails/polyfill2-rs/blob/main/src/http_config.rs"
click node_conn_mgr "https://github.com/onsails/polyfill2-rs/blob/main/src/connection_manager.rs"
click node_stream "https://github.com/onsails/polyfill2-rs/blob/main/src/stream.rs"
click node_ws_hot "https://github.com/onsails/polyfill2-rs/blob/main/src/ws_hot_path.rs"
click node_decode "https://github.com/onsails/polyfill2-rs/blob/main/src/decode.rs"
click node_book "https://github.com/onsails/polyfill2-rs/blob/main/src/book.rs"
click node_fill "https://github.com/onsails/polyfill2-rs/blob/main/src/fill.rs"
click node_types "https://github.com/onsails/polyfill2-rs/blob/main/src/types.rs"
click node_config "https://github.com/onsails/polyfill2-rs/blob/main/src/config.rs"
click node_buffer_pool "https://github.com/onsails/polyfill2-rs/blob/main/src/buffer_pool.rs"
click node_dns_cache "https://github.com/onsails/polyfill2-rs/blob/main/src/dns_cache.rs"
click node_errors "https://github.com/onsails/polyfill2-rs/blob/main/src/errors.rs"
click node_utils "https://github.com/onsails/polyfill2-rs/blob/main/src/utils.rs"
click node_benches "https://github.com/onsails/polyfill2-rs/blob/main/benches/ws_hot_path.rs"
click node_tests "https://github.com/onsails/polyfill2-rs/blob/main/tests/integration_tests.rs"
click node_examples "https://github.com/onsails/polyfill2-rs/blob/main/examples/demo.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lib,node_client,node_auth,node_orders toneBlue
class node_http_config,node_conn_mgr,node_stream,node_ws_hot toneAmber
class node_book,node_fill,node_types toneMint
class node_decode,node_config,node_buffer_pool,node_dns_cache,node_errors,node_utils toneRose
class node_benches,node_tests,node_examples toneIndigo
```

## Components

### Core client

Public crate API and client orchestration.

- [Crate API](https://github.com/onsails/polyfill2-rs/blob/main/src/lib.rs): crate entry · Top-level library entry point and re-exports. · `src/lib.rs`
- [Client](https://github.com/onsails/polyfill2-rs/blob/main/src/client.rs): orchestrator · Primary consumer-facing client that composes auth, config, and transports. · `src/client.rs`
- [Auth](https://github.com/onsails/polyfill2-rs/blob/main/src/auth.rs): signing · Authentication and request signing for Polymarket operations. · `src/auth.rs`
- [Orders](https://github.com/onsails/polyfill2-rs/blob/main/src/orders.rs): order encoding · Order construction, translation, and submission payloads. · `src/orders.rs`

### Transport

HTTP and WebSocket connectivity layers.

- [HTTP config](https://github.com/onsails/polyfill2-rs/blob/main/src/http_config.rs): transport config · HTTP behavior and latency-oriented network tuning. · `src/http_config.rs`
- [Conn manager](https://github.com/onsails/polyfill2-rs/blob/main/src/connection_manager.rs): lifecycle · Connection reuse, keep-alive, and reconnection control. · `src/connection_manager.rs`
- [Stream](https://github.com/onsails/polyfill2-rs/blob/main/src/stream.rs): ws ingest · WebSocket stream handling and event delivery. · `src/stream.rs`
- [WS hot path](https://github.com/onsails/polyfill2-rs/blob/main/src/ws_hot_path.rs): 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.

- [Book](https://github.com/onsails/polyfill2-rs/blob/main/src/book.rs): state machine · In-memory order book state and snapshot/delta application. · `src/book.rs`
- [Fill](https://github.com/onsails/polyfill2-rs/blob/main/src/fill.rs): market event · Fill and execution domain structures. · `src/fill.rs`
- [Types](https://github.com/onsails/polyfill2-rs/blob/main/src/types.rs): domain types · Shared market and order domain types and enums. · `src/types.rs`

### Support

Configuration, memory, decoding, and errors.

- [Decode](https://github.com/onsails/polyfill2-rs/blob/main/src/decode.rs): parser · Parsing of inbound payloads and message shapes. · `src/decode.rs`
- [Config](https://github.com/onsails/polyfill2-rs/blob/main/src/config.rs): runtime config · Client runtime knobs for transport, memory, and depth behavior. · `src/config.rs`
- [Buffer pool](https://github.com/onsails/polyfill2-rs/blob/main/src/buffer_pool.rs): memory pool · Preallocated buffers to reduce heap allocation on hot paths. · `src/buffer_pool.rs`
- [DNS cache](https://github.com/onsails/polyfill2-rs/blob/main/src/dns_cache.rs): network cache · DNS result reuse to reduce connection startup cost. · `src/dns_cache.rs`
- [Errors](https://github.com/onsails/polyfill2-rs/blob/main/src/errors.rs): error model · Unified error types across transport, decode, auth, and domain layers. · `src/errors.rs`
- [Utils](https://github.com/onsails/polyfill2-rs/blob/main/src/utils.rs): helpers · Shared helper functions used across the crate. · `src/utils.rs`

### Validation

Tests, benchmarks, and examples that exercise the client.

- [Benchmarks](https://github.com/onsails/polyfill2-rs/blob/main/benches/ws_hot_path.rs): performance suite · Hot-path and network benchmarks for latency and allocation behavior. · `benches/ws_hot_path.rs`
- [Integration tests](https://github.com/onsails/polyfill2-rs/blob/main/tests/integration_tests.rs): test suite · Integration coverage for auth, WebSocket behavior, orders, and book snapshots. · `tests/integration_tests.rs`
- [Examples](https://github.com/onsails/polyfill2-rs/blob/main/examples/demo.rs): usage demos · Embedding examples and benchmark-oriented programs for consumers. · `examples/demo.rs`

## Connections

- 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.