docs: fix pointer mismatches between docs and the merged implementation

[claude]

Requested by Giorgos Tsimos · Slack thread

Before: the docs quoted values that don't exist in the deployed system — a wrong chain ID, a wrong precompile address, method signatures and response shapes the node never serves — so anyone following them hit rejected transactions, failed deserialization, or silently wrong reads. After: every quoted value in these pages matches the code on podnetwork/pod main today; each fix below was re-verified against the current implementation (pod @ d6f4b46f) before editing.

Fixes

Audit item numbers refer to the docs audit shared in the Slack thread (HIGH-N / MED-N / LOW-N = report order).

API reference

• HIGH-1 doc/api-reference/README.md — Testnet chain ID said 129301; the network's chain ID is 1293 (0x50d). Ref: pod/node/src/config.rs:28-29, pod/devnet.sh:105.
• HIGH-3 doc/api-reference/json-rpc/README.md — said eth_blockNumber returns the latest past-perfection timestamp in microseconds; it returns the node's wall-clock time in whole seconds (as do receipt blockNumbers). The "timestamps are in microseconds" claim is now scoped to deadlines/TTLs. Ref: pod/node/src/rpc/eth.rs:129-132,190-197.
• HIGH-4 doc/api-reference/json-rpc/openapi.yaml — pod_getVoteBatches documented (from_sequence, to_sequence) nullable ints; the method takes (ranges: [[from, to], …], binary?) and can return either a JSON array or { "data": "<base64>" }. Ref: pod/node/src/rpc/pod.rs:167-172.
• HIGH-5 doc/api-reference/json-rpc/openapi.yaml — ob_getOrderbook said omitting depth returns all price levels; the served snapshot is hard-capped at 10 levels per side. Ref: pod/node/src/clob/mod.rs:637,770-771. (Also adjusted the depth = 20 example in read-market-data.md.)
• HIGH-7 doc/api-reference/json-rpc/openapi.yaml + doc/api-reference/guides/bridge-from-pod.md — claim-proof response documented as {signatures, committee_epoch, proof} hex strings (guide read camelCase auxTxSuffix); the node returns {proof, committee_epoch, aux_tx_suffix} with the byte fields as JSON integer arrays (proof = 0x00 type byte + concatenated signatures, aux_tx_suffix = the tx-hash bytes). Schema, example, and both guide tabs fixed. Ref: pod/node/src/rpc/types.rs:958-963, pod/node/src/rpc/pod.rs:1172-1182.
• HIGH-8 doc/api-reference/market-configurations.md — Backstop said 0.75 × Initial Margin; the sweep triggers at (2/3) × Maintenance Margin (≈ 0.33 × IM). Ref: pod/trading/src/perps/adl.rs:208-212, pod/node/src/config.rs:685-686.
• HIGH-12 doc/api-reference/guides/place-a-spot-order.md, place-a-perpetual-order.md — native-USD deposit examples sent no tx.value, which validation rejects ("CLOB tx value … must equal its native deposit total"); examples now attach the amount as value (and the ABI fragment is payable). Ref: pod/node/src/clob/mod.rs:2088-2093, pod/e2e/src/clob/mod.rs:446-456.
• HIGH-13 doc/api-reference/guides/read-market-data.md — ob_getCandles documented with 4 positional params; it takes (orderbook_id, {resolution, from_ts, to_ts?, limit?}). Ref: pod/node/src/rpc/ob.rs:41-46, pod/node/src/rpc/types.rs:157-162.
• HIGH-14 doc/api-reference/guides/read-market-data.md — order-history filter used nonexistent clob_ids: […] (silently ignored → unfiltered results); the field is singular orderbook_id. Ref: pod/node/src/rpc/types.rs:164-180.
• HIGH-15 doc/api-reference/guides/read-market-data.md — ob_getOrders return shown as a bare array with hash/remainingBase/filledBase; it returns {orders, total_count, next_cursor} with order_id/tx_hash/initial_size/filled_base_amount/filled_quote_amount. Ref: pod/node/src/rpc/types.rs:452-507,951-955.
• HIGH-16 doc/api-reference/guides/recover-locked-account.md — examples read txHash/tx_hash from pod_getRecoveryTargetTx; the response field is hash (and null when not locked). Ref: pod/node/src/rpc/types.rs:1143-1146, pod/node/src/rpc/pod.rs:254-255.
• MED-29 doc/api-reference/applications-precompiles/README.md — examples used deprecated getBalance(token) returns (uint256) with no account (queries address(0)); switched to balanceOf(token, account) returns (int256). Ref: pod/node/src/clob/contract.rs:81-86.
• MED-30 doc/api-reference/applications-precompiles/README.md — token 0x…0001 labeled USDT; it is NVDAx (Tokenized NVIDIA). Ref: pod/docker-compose.yaml:4-6, pod/devnet.sh:33,108.
• MED-32 doc/api-reference/applications-precompiles/orderbook.md — update()'s token param described as choosing the collateral token; the engine ignores it (spot locks in the resting order's own token, perps use cross-margin). Ref: pod/node/src/clob/mod.rs:3270-3296, pod/trading/src/batch.rs:26-38.
• MED-37 openapi.yaml — OrderStatus enum missing margin_canceled and invalid (the latter serialized as {"invalid": "<reason>"}); filter-vs-response value sets noted. Ref: pod/trading/src/order.rs:23-39, pod/node/src/rpc/types.rs:183-197.
• MED-38 openapi.yaml — PositionsResponse missing always-present net_deposits; account_value description missing the resting-spot-buy escrow component. Ref: pod/node/src/rpc/types.rs:758-788, pod/trading/src/engine.rs:396-427.
• MED-40 openapi.yaml — CandleResolution missing 30m, 1w, 1M. Ref: pod/node/src/rpc/types.rs:79-99.
• MED-41 (partial) market-configurations.md — Oracle parameter described as "Pyth asset"; it is a <source>/<asset> spec with four sources (PythNetwork, PythPro, Hyperliquid, Nobi). Ref: pod/node/src/oracle/source.rs:23-66. (The per-market Oracle column values were left as-is — the live testnet assignments are deployment config not present in the repo, so no authoritative replacement values could be verified.)
• MED-42 doc/api-reference/guides/optimistic-auction.md — Rust tab built the key with PRIVATE_KEY.parse(), which SigningKey doesn't support for hex strings; now SigningKey::from_slice(&hex::decode(…)), matching the SDK's own examples. Ref: pod-sdk/rust-sdk/src/provider/mod.rs:83-90, pod-sdk/examples/notary/src/main.rs:156-157.
• MED-43 doc/api-reference/guides/place-a-perpetual-order.md — said oversized reduce-only orders are rejected; they are clamped at match time to the position size (rejection happens only at submission for no-position/same-side). Ref: pod/trading/src/margin.rs:209-215, pod/trading/src/perps/mod.rs:1099-1113.
• LOW-57 openapi.yaml — Order schema missing included_batch (always present) and perp realized_pnl. Ref: pod/node/src/rpc/types.rs:470-492.
• LOW-58 openapi.yaml — Candle schema missing always-present quote_volume. Ref: pod/node/src/rpc/types.rs:101-116.
• LOW-59 openapi.yaml — PerpPosition missing entry_funding (already referenced by its own field formulas). Ref: pod/node/src/rpc/types.rs:922-929.
• LOW-60 openapi.yaml — BackstopTransferResponse missing realized_pnl. Ref: pod/node/src/rpc/types.rs:239-254.
• LOW-61 openapi.yaml — last_clearing_price / high_24h / low_24h / price_change_24h are nullable before a market's first trade; now marked nullable. Ref: pod/node/src/rpc/types.rs:35-47.
• LOW-62 openapi.yaml — eth_estimateGas doesn't just return 21000: fee-exempt tuples return 0 and submitBatch returns 21000 × sub-intents. Ref: pod/node/src/rpc/eth.rs:243-268, pod/node/src/gas.rs:59-141, pod/node/src/clob/contract.rs:292-308.
• LOW-63 rollupboost-priority-auctions.md — "working implementation" link pointed to a third-party personal repo; now points to this repo's examples/optimism-tx-auction.
• LOW-64 bridge-to-pod.md — permit comments now state the required nonstandard 97-byte packed encoding deadline(32) || v(1) || r(32) || s(32). Ref: pod-sdk/protocol/src/Bridge.sol:101,279-296.
• LOW-65 place-a-perpetual-order.md — margin formula said |size| × price / maxLeverage; margin is computed against the mark price. Ref: pod/trading/src/margin.rs:188-190.

Protocol docs

• HIGH-10 doc/api-reference/guides/bridge-to-pod.md, doc/protocol/network-architecture/README.md — told users to pass the 0xEeee… sentinel / "deposit ETH"; Bridge.deposit is non-payable and only accepts whitelisted ERC-20s, so that call always reverts. Ref: pod-sdk/protocol/src/Bridge.sol:298-302,329-356.
• HIGH-17 doc/protocol/margin.md — liquidations described as market orders; they are reduce-only limit orders at the bankruptcy price that rest across batches. Ref: pod/trading/src/perps/liquidation.rs:270-308.
• HIGH-18 doc/protocol/margin.md — withdrawable_cash = min(available_margin, cash) with "unrealized PnL is not withdrawable"; actual is max(0, available_margin) (zero below maintenance). Ref: pod/trading/src/engine.rs:170-188, pod/trading/src/perps/mod.rs:1994-2010.
• HIGH-19 doc/protocol/markets-overview.md, doc/protocol/orderbook.md — batch interval said per-market configurable, 100–200ms expected; it is one global setting, default/current 500ms. Ref: pod/node/src/config.rs:680-682,906-908.
• HIGH-22 doc/protocol/network-architecture/local-ordering.md — recovery precompile address said 0x…04EC0EE4; it is 0x50d0000000000000000000000000000000000003. Ref: pod/node/src/recovery/contract.rs:16.
• HIGH-23 doc/protocol/network-architecture/timestamping.md — named a nonexistent pod_subscribe endpoint; the method is pod_waitPastPerfectTime. Ref: pod/node/src/rpc/pod.rs:247-248.
• HIGH-24 (partial) timestamping.md, censorship-resistance.md — said the full node "returns a past perfect set"; the call returns an empty result and the set is fetched separately (e.g. eth_getLogs, pod_listConfirmedReceipts). Ref: pod/node/src/rpc/pod.rs:1044-1106.
• MED-44 doc/protocol/margin.md — cash formula omitted realized PnL settlement; now cash = deposits − withdrawals + funding_payments + realized_pnl. Ref: pod/trading/src/perps/mod.rs:530-535.
• MED-45 doc/protocol/margin.md — ADL counterparties said sorted by leverage; they are ranked by profit ratio × leverage, non-positive-equity accounts first. Ref: pod/trading/src/perps/adl.rs:592-617.
• MED-46 doc/protocol/margin.md — said "the underwater position itself is also closed"; ADL partially closes only losing legs to ~zero equity, then sweeps the remainder to the backstop. Ref: pod/trading/src/perps/adl.rs:269-305.
• MED-47 network-architecture/README.md, transaction-flow.md — finality said "supermajority (4/5) by stake"; the quorum is count-based n − f under n ≥ 5f + 1 with no stake weighting. Ref: pod/node/src/lib.rs:259,290,326.
• MED-48 local-ordering.md — post-recovery guidance said next nonce = stuck nonce + 1; the recovery tx itself occupies a nonce above the stuck one, and the next usable nonce is recovery nonce + 1. Ref: pod/node/src/recovery/mod.rs:245-251, pod/e2e/src/recovery.rs:124-140.
• MED-49 timestamping.md — heartbeats said every ~20ms; they are an idle fallback (40ms ticker after ~50ms without activity). Ref: pod/node/src/lib.rs:5627-5631.
• MED-51 doc/protocol/orderbook.md — said all markets use 1e18 tick sizes; tick size is per-market with a 1e16 default. Ref: pod/node/src/config.rs:31-32.
• MED-52 doc/protocol/orderbook.md, applications-precompiles/orderbook.md — removed the claimed 10-minute cap on deadline headroom; no upper bound is enforced. Ref: pod/node/src/clob/mod.rs:2876-2901.
• MED-53 doc/protocol/orderbook.md, market-configurations.md — solver said per-market configurable / rotating; there is one global solver key and createOrderBook rejects any other. Ref: pod/node/src/config.rs:673-675, pod/node/src/clob/mod.rs:3052-3060.
• MED-54 doc/protocol/perpetuals.md — max_funding_rate default said 4% per hour; it is 4% per funding window (8h), and both rate params are per-window. Ref: pod/trading/src/perps/config.rs:31-35.
• LOW-67 doc/protocol/margin.md — ADL close price said "last batch price"; it is the previous batch's mark price. Ref: pod/trading/src/perps/adl.rs:326-345.
• LOW-68 doc/protocol/markets-overview.md — "Market precompile" doesn't exist under that name; it is the Orderbook (CLOB) precompile. Ref: pod/node/src/clob/contract.rs.
• LOW-71 timestamping.md — past perfection said to advance on heartbeats specifically; it advances on every signed vote batch (heartbeats are the idle fallback). Ref: pod/node/src/lib.rs:7380-7396.
• LOW-72 doc/protocol/perpetuals.md — parameter named mark_clamp_pct; the config field is mark_price_clamp (default 1%). Ref: pod/trading/src/perps/config.rs:66-71,159-163.

Not included

• HIGH-2, MED-31 (getOrders remainingBase reversed subtraction / startTs duplication) — the precompile getOrders method is being removed in a separate PR, and HIGH-2 is a code bug, not a doc fix.
• HIGH-6 (ob_getOrderbook buy-side ordering / depth truncating from the wrong end) — a code bug in the RPC serialization path; documenting the broken behavior would be wrong once fixed.
• HIGH-9 (deadline examples not aligned to the auction interval) and HIGH-11 (pod_waitPastPerfectTime 500ms cap breaks the auction guide's single call) — fixing requires new example logic (alignment arithmetic, polling loops), not value substitution; suggested as a follow-up examples PR.
• HIGH-20 (claim-proof auto-selection of merkle proofs after upgrades) — forward-looking upgrade narrative needing a conceptual rewrite.
• HIGH-21 (bridge deposits credited via the relayer, not directly by validators) — trust-model/architecture narrative (sequence diagram + entity list) out of scope for pointer fixes.
• HIGH-25 (solver censorship-resistance claims), HIGH-26 (mark-price median formula; its name-only part is fixed as LOW-72), HIGH-27 (funding accrual via cumulative index) — conceptual rewrites per scope; the mechanism descriptions need dedicated treatment.
• Clearing section of doc/protocol/orderbook.md — covered by pod-sdk#231; untouched here.
• MED-28 (ob_ endpoints deprecated in favor of REST + pod_* subscriptions), MED-36 (undocumented subscription types), MED-39 (undocumented ob_getSolutions), MED-33 (undocumented error code 997), LOW-56 (read-only-mode -32000 variant), LOW-69 (Pod-side withdraw limits) — additive documentation of missing surfaces, not mismatch fixes.
• MED-34 (EVM opcode semantics — Pod has no EVM), MED-35 (subscription depth parsed but never applied — likely a code bug), MED-50 / LOW-66 (attestation streaming / client→validator flow narrative), MED-55 (competition scoring metric — product decision), LOW-70 (bridge pinned to Ethereum vs. the Arbitrum deployment — deployment/positioning decision).
• MED-41 table values — the perp markets' per-market oracle identifiers were left unchanged because the live testnet assignments aren't in the repo to verify against.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A74BZVmHFAksnZWVaGBcgi

---

Generated by Claude Code