Claiming Rewards

Rewards are keyed by book, sold token, and order nonce. Any account may register or distribute, but the claimant is always read from the matching engine. A caller cannot redirect another maker's DEEP.

Why claimant registration exists

DeepstateV1.cancel deletes the engine's order-owner record after returning unfilled collateral and filled proceeds. registerClaimant(bookId, order) caches that engine-verified owner under the canonical order id while the record still exists.

Registration is permissionless and does not grant the caller any rights. It preserves the verified recipient so accrued rewards remain distributable after cancellation.

registerClaimants(bookIds, orders) performs the same work for multiple live orders. Every resolved order must have the same claimant or the entire batch reverts.

Distribution path

distributeRewards(bookId, order, soldToken):

1. identifies the reward side from soldToken;
2. resolves the cached claimant or lazily registers a still-active order;
3. checks whether the order is the currently tracked top;
4. if current, validates its nonce and live sold amount through topOrder and accrues through block.timestamp;
5. applies the side's remaining immutable cap;
6. clears the stored balance before the external token transfer; and
7. transfers DEEP from the rewarder's prefunded balance to the verified claimant.

For a displaced or cancelled order, distribution pays its stored balance to the registered claimant without changing the current top cursor.

distributeRewardsBatch(bookIds, orders, soldTokens) processes multiple orders belonging to the same claimant and aggregates the result into one DEEP transfer. Mixed claimants revert atomically.

Closing an order

The required ordering for an order that has accrued or is still accumulating rewards is:

rewarder.registerClaimant(bookId, order)
deepstate.cancel(token0, token1, epoch, order)
rewarder.distributeRewards(bookId, order, soldToken)

Registration may be omitted when the claimant is already cached. Distribution may happen in the same atomic wallet batch or later from the Rewards page. An order deleted before either registration path loses its claim because its owner can no longer be proven.

Wallet behavior

The official interface inspects the order's stored balance, active reward cursor, and claimant cache before closing it.

• No rewards: submit only cancel.
• EIP-5792 atomic calls supported: submit registration when needed, cancellation, and distribution in one atomic wallet_sendCalls batch.
• No atomic-call support: submit registration when needed, then cancellation as the next wallet transaction. Distribute the preserved balance from the Rewards page.

Filled orders use the same exit path because cancel is also the engine's proceeds-collection method. A filled row stays visible with 100% progress and changes its action from Cancel to Claim.

Partial and completed orders

A partial fill can reduce the amount at risk while the order remains best. Top-change callbacks settle the prior interval with the outgoing live amount; subsequent accrual uses the engine's current sold amount. A fully filled or displaced order can retain a stored reward after the book moves on, provided the claimant was registered before deletion.

Fixed reward custody

The rewarder holds the complete 1 billion DEEP launch allocation and has no mint authority. Distribution can never create new DEEP. Unearned or undistributed allocation remains in the rewarder, and the contract exposes no owner withdrawal for that balance.