@somnia-chain/markets-sdk

@somnia-chain/markets-sdk / index / GetOrderOnchainOptions

Interface: GetOrderOnchainOptions

Defined in: packages/sdk/src/orders.ts:663

Options for one on-chain order read.

Properties

blockNumber?

optional blockNumber?: bigint

Defined in: packages/sdk/src/orders.ts:701

Read the order as of the END of this block instead of at head.

For a maker order a fill has already consumed: the fill removes it in the same transaction, so fill.blockNumber - 1n is the last height that still holds it. OrderFilled names the maker only by id, and the pool keeps no record of a removed order at head.

What this recovers is the maker's IDENTITY state - isBid, owner, userData, expireTimestampNs - which no path changes under a given id, so it is exact at any height the order existed, and which no fill log carries: OrderFilled names the maker by id alone. Only OrderPlaced carries it, and a consumer that was not listening when the maker rested does not have that log - which is the whole case for this read.

price is immutable too, and is the one immutable field NOT to read for: a fill executes at the MAKER's resting price, and the book emits that same price as the fill event's own. Reading the maker order to price a fill is redundant work.

BOTH quantities are block-level, and neither is per-fill. A block read cannot see between transactions, so fullQuantity and quantityRemaining are the values at the block BOUNDARY: an earlier transaction in the fill's own block may have filled this maker, or reduced it - reduceOrder decrements both by the same amount, under the same id. Take quantityFilled and makerRemainingQuantity from the event; no block-level read reconstructs per-transaction size.

Two more edges answer plausibly rather than failing:

  • A PARTIAL fill leaves the order in place, so a read at the fill's OWN block succeeds with a smaller quantityRemaining where a full fill answers null.
  • An order PLACED AND FILLED in one block does not exist at blockNumber - 1n, so that read is null and the caller needs the placement from the same block's OrderPlaced instead.

A recent block answers against a full node. An old one needs ARCHIVE state, so this serves a live tape, not a backfill or a replay of last week.