Order Lifecycle

1. 01MakerDeepstatePlace a limit order
2. 02DeepstateRewarderReport a top-of-book transition
3. 03RewarderRewarderAccrue sold quantity × wall-clock exposure
4. 04TakerDeepstateExecute against the superior price
5. 05DeepstateVaultRoute the 10 bps protocol fee
6. 06MakerRewarderRegister the engine-verified claimant before deletion
7. 07MakerDeepstateCancel or claim the order and release proceeds
8. 08MakerRewarderDistribute cached DEEP rewards now or from Rewards

Placement

A submitted order first matches crossing liquidity. If quantity remains and the caller permits resting, the engine locks the required collateral and returns the packed resting order.

• A resting NVDA/USDG bid locks USDG quote collateral.
• A resting NVDA/USDG ask locks NVDA base collateral.

If the order becomes the best of an incentivized side, the engine calls the NVDA/USDG rewarder after mutating the book. The first nonzero top reported to a side activates its finite schedule.

Top changes

Whenever placement, fill, or cancellation changes the canonical top, the engine reports the outgoing sold amount and incoming nonce:

• remaining quote collateral for a bid; or
• remaining base quantity for an ask.

The five-word hook ABI is paired with the engine's topOrder view for live claim validation. Hook execution is gas-capped and best-effort. A reverting or over-budget rewarder does not revert the order-book operation, preserving trading availability at the cost of potentially stale reward state.

Fill and proceeds

Taker execution updates tree state before token settlement. Maker proceeds stay associated with the original order until its owner calls cancel, which serves both as cancellation and asynchronous proceeds collection.

For a partially filled order, cancellation returns unfilled collateral plus filled proceeds. For a fully filled order, it returns proceeds. The interface therefore retains the original order row at 100% and labels the action Claim.

Reward preservation

Claimant cache and batch paths implemented

An order with rewards must preserve its engine-verified owner before cancel deletes that record. DeepstateRewarder.registerClaimant(bookId, order) caches the owner under the canonical order id. The order can then be cancelled, and distributeRewards can transfer its stored balance afterward.

The rewarder also supports registerClaimants and distributeRewardsBatch for multiple orders belonging to the same claimant. Mixed-owner batches revert atomically.

The intended interface flow is:

1. If the order has no accrued or live reward, call cancel only.
2. If EIP-5792 atomic calls are supported, batch registration when needed, cancellation, and distribution.
3. Otherwise, submit registration and cancellation sequentially; distribute the cached DEEP from Rewards.

Calling cancel before any claimant registration still destroys the proof needed for a later reward claim.

Reward transfer

Reward distribution clears internal accounting before transferring DEEP to the verified claimant. The DEEP comes from the rewarder's fixed prefunded balance. The rewarder has no mint authority.

Reentrancy and failures

Fill and cancel entry points use the engine's transient reentrancy guard. Hook reverts are swallowed. Token-transfer failures revert the entire matching or cancellation transaction, including state mutation, so an order is not silently deleted after a failed payout.

For EIP-5792 wallets the interface requests atomic execution with forceAtomic: true; a failure in any call reverts the batch. Sequential wallets expose each confirmed transaction separately and rely on the claimant cache between them.