Lighter knowledge base

Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). Attribution is required: credit “markpaper — Lighter knowledge base”, link to the original and to the license, and indicate if changes were made.

Reading your account (account?by=index), positions whose sign is stored separately, account value as equity, completeness of the order list, leverage as the initial margin fraction and update_leverage, two scales for the same fraction, and what is known about fees. Facts were verified on the robinhoodchain instance.

Two independent deployments of the same exchange, where the robinhoodchain instance host comes from, which reads are public and which require an auth token, the response shapes for orderBooks / orderBookDetails / account / accountActiveOrders, and which metadata is needed for trading. Facts were verified on the robinhoodchain instance; regular zkLighter mainnet was not verified live.

What is known about Lighter limits: the hard per-L1-address write window (code 23000), how to account for it (sliding window, reserve, seeding after restart), what counts toward it, capacity in writes, and read limits. Facts were verified on the robinhoodchain instance.

The market list on the robinhoodchain instance, */USDG duplicates, market_id, price and size steps, integer base_amount/price values on the wire, two minimums (dollars and lots), and quantization through one function. Facts were verified on the robinhoodchain instance.

How to operate with a separate signer, what to verify at startup, what health information to monitor, a runbook for common failures with primary sources, and a micro-cycle for validation before going live. Facts were verified on the robinhoodchain instance.

The create_order payload, types and time-in-force values, reduceOnly semantics, minimums, identifiers (client_order_index / order_index / order_id), what placement returns (tx_hash, not status), measuring an IoC fill as a position delta, reflection lag after a write, cancellations, retries, error codes, and write budget. Facts were verified on the robinhoodchain instance; writes go through a sidecar built on the official Python SDK.

All Lighter traps in one place: symptom, cause, fix, plus approaches that do not work (and why). The mechanics are detailed in the topic files; this page is the summary and set of invariants.

Why Lighter cannot be signed directly from TS code, how the official Python SDK works, how to move signing into a separate process (a sidecar), what that process must and must not do, and how to verify that a key is bound to the intended account. Facts were verified on the robinhoodchain instance.

Practical knowledge about the Lighter exchange: two independent deployments (regular zkLighter mainnet and an instance on robinhoodchain, commonly called “Robinhood”), the REST API, signing through the official Python SDK and a sidecar signer for TypeScript, markets and quantization, order responses without status, identifiers above 2^53, the 40/60 s write window, account and leverage, operations, and pitfalls. Facts were verified on the robinhoodchain instance; every rule includes its reason a…