Skip to main content

CLOB (OpshunsClob)

Each options market is an OpshunsClob clone: an ERC-6909 book for a fixed token0 / token1 / premium triple. The mothership OrdersFacet is the user-facing entry for posting, claiming, exercising, and withdrawing. RFQ fills also settle into the same clone via bilateral fillMatched.

For RFQ fill modes (leg-by-leg, FixedPackage, Dutch, Authority), see On-chain fill modes.

What the book is​

ConceptRole
Pair / CLOB addressFactory-deployed clone for one underlying pair + premium token
PairKeyOption terms packed into a bijective ERC-6909 id (type, exercise window, expiry, strike, premium bps, min notional)
Buy / sell inventoryFungible buyId / sellId for the same terms
Resting queuesFIFO bids (premium) and asks (underlying); remainder may enqueue as order NFTs

Ids are a fixed bit layout (not a hash): same terms → same ids; decode recovers terms bit-for-bit. Details live in core OpshunsClob/README.md.

Posting orders (mothership)​

Typical flow:

Wallet → OrdersFacet.orderBuy / orderSell (+ optional Permit2)
       → clone orderBuy(Referral) / orderSell(Referral)
       → cross resting opposite side if possible
       → enqueue remainder (order NFT meta 0xFF…)
  • Buy posts premium against the book.
  • Sell posts underlying.
  • Min-notional floors apply on CLOB posts (BelowMinNotional if too small). RFQ fillMatched skips that gate.
  • Trailing referrer is chosen by the caller (not baked into an RFQ maker quote).

The trading app’s Post to book path for a single call/put talks to this stack. REST helpers: Orders & exclusive fills.

Matching vs RFQ​

Two different ways liquidity clears into the same 6909 inventory:

Resting book​

Makers (or any wallet) leave standing bids/asks. Crosses happen when a counterparty posts or when an RFQ maker’s ClobOffer takes the book.

Bilateral fillMatched​

RFQ / package settlement after the mothership has already pulled ERC-20 premium + underlying:

Settle RFQ fillMatched after mothership has pulled premium + underlying into this core… No ERC-20 pulls — mint + pool accounting only.

  • Does not advance live queue cursors (bilateral mint; no claim queue).
  • Leg-by-leg RFQ uses quoted premiumRateBps in the PairKey.
  • FixedPackage / Dutch settle an absolute package premium first, then fillMatched at 0 bps.

RFQ + book hybrid (leg-by-leg only)​

A maker offer may include ClobOffer{ premiumRateBps, clobAmount } slices:

  1. Mothership takes that size from the book as the maker (orderBuyFrom / orderSellFrom).
  2. Each slice must fill exactly or the entire intent reverts.
  3. Remainder → bilateral fillMatched at the quote’s premiumRateBps.

If clobOffers is empty, the whole size is fillMatched.

FixedPackage and Dutch do not consume resting CLOB offers — only zero-bps fillMatched after package premium.

Lifecycle after mint​

Once you hold buy/sell 6909 inventory you can:

  • Claim / manage queued order NFTs
  • Exercise (American anytime before expiry when startExerciseTimestamp == 0; European-style when start equals expiry)
  • Withdraw residual collateral per product rules

Exact selectors are on OrdersFacet / IOpshunsClob. Prefer mothership entrypoints so approvals and fees stay consistent.

Fees and RFQ mode​

While a fill runs, the mothership may set treasury “in RFQ” so RFQ fee powers apply. See core OpshunsFees/FEES.md. Referral fees on maker-paid legs follow the taker/filler-chosen referrer.

Integrator tips​

  1. Resolve the pair address from the factory / networks registry (opshuns6909_contract in quote intents).
  2. Predict ids with mothership resolvePairKey / clone helpers so off-chain books match on-chain packing (min-notional sentinels are materialized before packing).
  3. Approve the mothership for ERC-20 pulls (or use Permit2 witnesses), not only the clone.
  4. Standard ERC-20 only — no fee-on-transfer or rebasing tokens.