Crate and module map. For a user reading order (SUBSCRIBE vs REQUEST, bindings caveats), start at README.md in this folder.
| Document | Description |
|---|---|
| README.md | Docs map — start here |
| TUTORIAL.md | Step-by-step getting started |
| PROTOCOL.md | Design rationale, channel directions, migration |
| STREAMING.md | Live SUBSCRIBE paths and gateway WS mapping |
| QUERY.md | Historical REQUEST/RESPONSE paths and REST GET mapping |
| GATEWAY.md | Legacy FIX/REST/WebSocket/OUCH/ITCH gateway deployment |
| SECURITY_AUDIT.md | Security checklist (1.0 sign-off recorded) |
| TODO.md §18 | 1.0 release criteria · §0 backlog |
| DEPLOYMENT.md | HA deployment and operations |
| PUBLISHING.md | Build and install SDKs |
| COMPATIBILITY.md | SPEC vs crate vs git tag; fig.h contract |
| BENCHMARKS.md | msgs/sec, tail latency, Criterion methodology |
| adr/README.md | Architecture decision records |
| adr/0004-fsl-single-source-of-truth.md | FSL schema evolution & multi-language codegen |
| adr/0006-broker-api-parity.md | Native FIG first; broker API parity policy |
| adr/0008-named-gateway-adapters.md | FIX/REST/WS/OUCH/ITCH as named adapters |
| adr/0009-market-data-plane.md | TREE L2 native; ITCH is L2 egress |
| adr/0010-batch-request.md | Atomic multi-action REQUEST |
| ../SPEC.md | Normative wire format specification |
| ../TODO.md | Implementation roadmap |
Generate Rust API docs:
cargo doc --workspace --no-deps --open| Module | Purpose |
|---|---|
frame |
16-byte header encode/decode, streaming FrameDecoder |
ext |
TLV extension tags (29 tags) |
channel |
Channel lifecycle, sequence numbers, per-channel send credits |
session |
Session model; MemorySessionStore, FileSessionStore, optional RedisSessionStore (session-redis feature) |
transport |
TREE transport, FigConnection, 0-RTT, migration, replay cache |
tcp |
TCP downgrade mode (FIG\x01 magic prefix) |
migration |
Connection migration tokens and channel reconstruction |
codec |
CBOR helpers; JSON ↔ CBOR for gateways |
constraints |
decimal64 scale/bounds and constrained-string checks used by generated codecs |
replay |
0-RTT resumption token replay cache |
sbe |
SBE encoder/decoder (encode / encode_into) |
compression |
zstd payload compression |
fragment |
Payload fragmentation and reassembly |
control |
CONTROL frame dispatcher (PING, AUTH_REFRESH, SEQ_RESET, …) |
auth |
Wire auth: token/mTLS types, constant-time verify, refresh hooks — not credential issuance |
jwt |
JWT bearer decode/verify (HS256 for tests/conformance) |
jwt_keys |
RS256 verification from a JWKS/PEM key set, kid rotation, KMS adapter |
session_token |
Server-signed (HMAC-SHA256) session resumption tokens |
replay |
Replay window: per-process or shared Redis cache |
oauth |
OAuth2/OIDC dev introspection stub (venues wire real IdP) |
channel_auth |
Per-channel permission policy |
rate_limit |
Token-bucket rate limiter |
dos |
Connection-level DoS guard and flood detector |
trace |
W3C traceparent ↔ TRACE_ID extension |
observability |
Tracing spans, metrics, Prometheus export |
messages |
Trading message types; channel_path constants for §17 paths |
error |
FrameError, ChannelError, SessionError, FigError |
| Binary | Command | Purpose |
|---|---|---|
fig-observability |
cargo run -p fig-core --features observability-bin --bin fig-observability |
Prometheus /metrics on :9090 |
| Module | Purpose |
|---|---|
fix |
FIX 4.4 parse/serialize, FIG message conversion |
fix_session |
FIX session state machine (logon, heartbeat, resend) |
rest |
HTTP/1.1 parse/serialize, JSON ↔ CBOR |
rest_query |
REST GET → native FIG REQUEST (candles, fills, funding, …) |
ws |
WebSocket RFC 6455 frame mapping |
ws_catalog |
Legacy WS topic → native FIG SUBSCRIBE (Binance/HL reference aliases) |
ws_listener |
HTTP upgrade handler for fig-gateway WS listener |
backend |
proxy_frame (REQUEST/EOF), BackendSession (live SUBSCRIBE) |
sse |
Server-Sent Events ↔ STREAM_ITEM |
soupbin |
SoupBinTCP session framing for OUCH/ITCH |
ouch |
FIG OUCH 4.2-shaped order entry (--ouch-addr) |
itch |
ITCH L2 price-level egress (SoupBin + MoldUDP64) |
| Binary | Command | Purpose |
|---|---|---|
fig-gateway |
FIG_TLS_CA=.fig/dev-ca.pem cargo run -p fig-gateways --bin fig-gateway -- --fig-backend 127.0.0.1:8443 |
REST :8080, WS :8090, FIX :9876; OUCH/ITCH opt-in |
E2E alias round-trip: cargo test -p fig-gateways --test gateway_legacy_ws_alias_e2e
(Binance / Hyperliquid / FIX / REST fixture tables in one test file).
OUCH/ITCH: cargo test -p fig-gateways --test gateway_ouch_itch_e2e.
| Module | Purpose |
|---|---|
parser |
FSL tokenizer and recursive-descent parser |
ast |
Schema AST (messages, types, gateway mappings) |
codegen |
Rust struct codegen |
sbe_codegen |
SBE Rust encode/decode codegen |
target_codegen |
Go, Python, TS, OCaml, Zig, C++, C#, Proto, SBE XML, JSON Schema, FIX YAML |
cargo run -p fig-fsl --bin ftlc -- compile schemas/orders.fsl --lang go --out /tmp/out
cargo run -p fig-fsl --bin ftlc -- validate schemas/orders.fslSupported --lang values: rust, sbe, sbe-go, sbe-cpp, sbe-csharp, sbe-typescript (sbe-ts), sbe-zig, go, proto, sbe-xml, cpp, csharp, python, typescript, ocaml, zig, java, json-schema, fix-yaml, protocol-cpp, protocol-zig.
| Module | Purpose |
|---|---|
server |
FIG server: FigServer::accept_0rtt, held-open subscribe fan-out |
broker_api |
§17 query/subscribe routing and post-fill fan-out |
market_data |
Candles, trades, BBO, ticker aggregation |
account_state |
Balances, positions, funding, ledger |
auth |
Simulator test harness: fig-dev-{account} path scoping (not production issuance) |
market_state |
Session status, security status, price collars |
md_rate |
Public MD rate limits by tier (SPEC §9.3) |
matching |
Price-time matching engine |
orderbook |
Limit order book |
Default listen address: 127.0.0.1:8443 (UDP/TREE).
Native FIG client connecting to 127.0.0.1:8443 by default. Uses FigSdkClient
for seven validated demo flows plus an SBE order demo. Attaches simulator test token
fig-dev-DEMO-ACCT on private paths (see SPEC §9.3 wire semantics; not a
key-issuance API).
| Module | State type | Streams |
|---|---|---|
order_book |
OrderBookState |
book snapshot/delta |
candles |
CandleState |
candle bars |
account |
AccountCache |
balances, positions, margin |
agg_trades |
AggTradeState |
aggregate trades |
funding |
FundingState |
funding payments |
ledger |
LedgerState |
ledger updates |
liquidations |
LiquidationState |
user + public liquidations |
client |
FigSdkClient, LiveSubscription |
request() / request_* (EOF); subscribe_* / subscribe_live (held open) |
Live subscribe: fig_client_subscribe, fig_client_sub_next, fig_client_sub_close
(header: fig.h). REQUEST uses
fig_client_request_and_recv (waits for EOF). Two-connection proof:
cargo test -p fig-ffi --test client_integration.
PyO3 module fig (build with maturin develop -m crates/fig-python/Cargo.toml).
import fig
fig.version() # crate version
c = fig.FigPyClient()
c.connect("127.0.0.1:8443") # TLS verified by default: set FIG_TLS_CA
c.request(".well-known/capabilities", "GET") # -> list[bytes] of encoded response frames
c.subscribe("accounts/A/balances", "accounts/A/balances", "fig-dev-A", 1, 1) # -> list[bytes] snapshot
sub = c.subscribe_live("accounts/A/balances", "accounts/A/balances", "fig-dev-A", 2, 1)
sub.snapshot # property -> list[bytes] of the snapshot frames
try:
frame = sub.next(500) # bytes; None on EOF; raises on timeout
except RuntimeError as e: # RuntimeError("timeout") when nothing arrived
frame = None
sub.close()
c.ping()
token = fig.jwt_encode("alice", 4_000_000_000, "fig-smoke-secret")
fig.jwt_decode_sub(token, "fig-smoke-secret") # "alice"
fig.jwt_verify_bearer(token, "fig-smoke-secret")
c.request_session_status()
c.request_security_status("AAPL")
c.mass_cancel("MC-001", "DEMO", symbol="AAPL", side="buy")
c.post_batch("DEMO", batch_request_cbor) # -> bytes, a CBOR BatchReport
candle = fig.PyCandleState()
candle.apply_bytes(candle_bar_event_cbor)
candle.close_price() # None until a bar is applied
candle.is_final()request and subscribe return lists of encoded frames (decode with
fig.frame_decode_header). subscribe_live returns a subscription whose
snapshot is a property, not a method. Requests are REQUEST-mode; use
subscribe_live (not request) for streams that keep pushing.
Three layers: Criterion mean time, HDR tail latency, wall-clock msgs/sec.
| Suite | Role |
|---|---|
frame_bench, codec_bench, gateway_bench, matching_bench, transport_bench, alloc_bench |
Criterion mean/median + elems/s regression |
fig-latency, latency_bench |
HDR Histogram p50 / p99 / p99.9 per operation |
fig-throughput |
Sustained msgs/sec over FIG_THROUGHPUT_SECS |
fig-load |
Encode/decode flood smoke (CI), not for citing rates |
cargo bench -p fig-bench
cargo bench -p fig-bench --features alloc --bench alloc_bench
cargo run --release -p fig-bench --bin fig-latency
FIG_LATENCY_ITERS=1000 cargo run --release -p fig-bench --bin fig-latency
cargo run --release -p fig-bench --bin fig-throughput
FIG_THROUGHPUT_SECS=1 cargo run --release -p fig-bench --bin fig-throughputSee BENCHMARKS.md for methodology and reference numbers.