Skip to content

docs(orderbook): fix order identifier & balance return types; document TP/SL triggers#222

Merged
poszu merged 1 commit into
mainfrom
docs/orderbook-order-id-and-triggers
Jun 12, 2026
Merged

docs(orderbook): fix order identifier & balance return types; document TP/SL triggers#222
poszu merged 1 commit into
mainfrom
docs/orderbook-order-id-and-triggers

Conversation

@poszu

@poszu poszu commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

Brings the orderbook precompile docs in line with the actual Clob contract interface.

Order identifier — the docs wrongly stated that orders are referenced by their submitOrder tx hash. In the contract, anything that rests in the book is keyed by a computed order_id = keccak256(abi.encode(signer, nonce, sequence)). cancel(canceledOrder), update(updatedOrder), and the getOrders(orderIds) read all take this order_id (verified: node/src/clob/mod.rs stores update.updatedOrder.into() as order_id; the contract param is named orderIds; trading::OrderId::new defines the formula). Corrected the orderbook reference page (the identifier hint block, cancel, update, and getOrders param/return), and the API-reference index's "transaction hashes as identifiers" note, which used the orderbook as its prime example — now reworded with correct examples (bridge withdrawal claim, recovery target) plus an explicit orderbook carve-out.

Balance return types — balanceOf and getBalance are documented as returns (uint256) but the contract returns int256 (signed; native USD is funding-adjusted and can be negative). Fixed both, and documented the previously-missing withdrawableBalance(token, account) read that pairs with them.

TP/SL triggers — added the TriggerType/TriggerGrouping enums and a triggers section documenting submitTrigger, cancelTrigger, and updateTrigger, including the firing-direction table (side × type → mark-price condition) and the fact that triggerOrder is the trigger's order_id (read back via ob_getTriggers), not the submitTrigger tx hash. Signatures verified identical to node/src/clob/contract.rs.

Solver-only (submitSolutions) and admin-only (createOrderBook) methods are intentionally left undocumented.

… TP/SL triggers

Orders, cancels, updates, and the getOrders read are keyed by the computed
order_id = keccak256(abi.encode(signer, nonce, sequence)), not the submitOrder
tx hash. Correct the orderbook precompile reference and the API-reference index's
'transaction hashes as identifiers' note, which used the orderbook as its example.

Fix balanceOf and getBalance return types (int256, not uint256) and document the
withdrawableBalance read.

Document the TP/SL trigger interface (submitTrigger, cancelTrigger, updateTrigger
and the TriggerType/TriggerGrouping enums).
@poszu poszu merged commit 57e8b22 into main Jun 12, 2026
13 checks passed
@poszu poszu deleted the docs/orderbook-order-id-and-triggers branch June 12, 2026 18:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants