Order Book

Diffusal uses an event-first order book: makers sign order intent off-chain, a caller submits the signed payload on-chain, matching happens off-chain, and settlement is finalized on-chain.

Lifecycle

Stage	Where it happens	Details
Order signing	Off-chain	Maker signs `PlaceOrder` typed data containing `seriesId`, `portfolioId`, `isBuy`, `tick`, `size`, `expiry`, `nonce`, and `deadline`
Order placement	On-chain	Caller submits `placeOrderWithSignature(...)`; contract verifies the signature, emits `OrderRegistered`, and stores compact order data
Matching	Off-chain	Matching engine applies price/time priority and selects crossed orders
Settlement	On-chain	Authorized operator calls `settleMatchByOrderId(makerOrderId, takerOrderId, fillAmount)`
State sync	Off-chain	Data services stream updated orderbook and trade state to clients

Placement

Primary entrypoints:

placeOrderWithSignature(
  bytes32 seriesId,
  uint256 portfolioId,
  bool isBuy,
  uint32 tick,
  uint128 size,
  uint32 expiry,
  uint256 nonce,
  uint256 deadline,
  bytes signature
)

placeOrderWithSeriesParamsWithSignature(
  bytes32 seriesId,
  uint256 portfolioId,
  bool isBuy,
  uint32 tick,
  uint128 size,
  uint32 expiry,
  SeriesParams seriesParams,
  uint256 nonce,
  uint256 deadline,
  bytes signature
)

Notes:

portfolioId routes position/cash impact
tick precision depends on pair configuration
nonce and deadline provide replay protection and bounded signature validity
lazy series registration is supported via placeOrderWithSeriesParamsWithSignature(...)
registerOrderInPortfolio(...) and registerOrderInPortfolioWithSeriesParams(...) still exist as lower-level direct-write alternatives, but they are not the recommended current integration path

Canonical Managed Flow

Call the authenticated managed order placement endpoint to get mode: "typed_data" plus the exact PlaceOrder payload to sign.
Sign the returned typed data with the maker wallet.
Submit the signed payload to placeOrderWithSignature(...).
For lazy series creation, use placeOrderWithSeriesParamsWithSignature(...) with matching typed-data semantics.

Cancellation and Invalidation

Signed maker cancellation: cancelOrderWithSignature(orderId, nonce, deadline, signature)
Direct maker cancellation: cancelOrderById(orderId)
Public invalidation of unfillable orders: invalidateOrder(order, orderId)

Settlement Model

settleMatchByOrderId(...) reads stored order metadata, executes fills, and emits trade/fee events.

Execution path:

Determine buyer/seller and fill premium from order data
Use DiffusalOrderBookAuth for placement/cancel signature recovery and DiffusalOrderBookCoordinator for signed-order validation and match preparation
Delegate position/fee/margin execution to DiffusalOrderBookExecutor
Update fill state and emit settlement/trade events

Why This Model

Signature-first placement allows relayed or API-managed order submission without changing the canonical on-chain function.
Lower calldata surface at settlement time (order IDs vs full signed structs)
Deterministic replay protection through on-chain fill accounting
Clear split of responsibilities:
- orderbook contract = order state and orchestration
- auth/coordinator helpers = signature recovery + validation
- executor contract = position, collateral, and fee execution