@mysten/deepbook-v3 2.6.4 → 2.8.0

package/PREDICT.md

@@ -45,41 +45,35 @@ const withdrawTx = client.predict.tx.withdraw(myAddress, 100); // $100
 // Pick a market. `read.markets()` lists ACTIVE markets — live and not yet settled — which
 // includes a market past its expiry that nobody has settled yet; quoting against one aborts.
 // Expiries are absolute timestamps, so never hardcode one: filter on `expiryMs`, leaving
-// room to quote, sign and land (and clear the pre-expiry no-trade window).
+// room to quote, sign and land (and clear the pre-expiry no-trade window). A window's reference
+// price is set only once the window opens, so a market listed ahead of its window has
+// `referencePrice: null`, and `strike: 'reference'` throws for it until then.
 const markets = await client.predict.read.markets();
 // -> [{ id, expiryMs, tickSize, admissionTickSize, mintPaused, referencePrice }, ...]
-const tradeable = markets.filter((m) => Number(m.expiryMs) > Date.now() + 30_000 && !m.mintPaused);
+const tradeable = markets.filter(
+	(m) => Number(m.expiryMs) > Date.now() + 30_000 && !m.mintPaused && m.referencePrice != null,
+);
 const expiryMs = tradeable[0].expiryMs;
 
-// Describe the position once and reuse it — quoting and minting take the same descriptor.
+// Describe the position once and reuse it: pricing, planning and ordering take the same descriptor.
 const desc = { underlying: 'BTC', expiryMs, strike: 'reference', side: 'up' } as const;
 
-// Quote before you trade: dry-runs your exact mint, real fees, real account.
-const q = await client.predict.read.quoteMint(myAddress, desc, { quantity: 50 });
-q.entryProbability; // your fill (0..1 per $1 payout)
-q.cost; // exact all-in debit
-
-// Trade. `maxCost` is your ceiling on the all-in debit — pass the quote plus a buffer,
-// rounded to 6 decimals, since raw amounts are integers at that scale.
-const mintTx = await client.predict.tx.mint(myAddress, desc, {
-	quantity: 50,
-	maxCost: Math.ceil(q.cost * 1.01 * 1e6) / 1e6,
-});
-// -> sign & execute any of these with your wallet / dapp-kit / signer
-
 // Anonymous board price (no account needed): both sides of any strike.
-const { up, down } = await client.predict.read.price({
-	underlying: 'BTC',
-	expiryMs,
-	strike: 'reference',
-});
+const { up, down } = await client.predict.read.price(desc);
+
+// Trade. Orders are queued: placed now and filled about a second later at Pyth's price, within
+// the plan's slippage, or refunded. `planMint` quotes the order at the current price and turns
+// the slippage (cents per contract, never a percentage) into the limits the enqueue carries.
+// Once the price moves, the reference strike can leave the market's entry band, and `planMint`
+// then throws `entry-band`: see Queued orders for picking a strike near the money.
+const plan = await client.predict.read.planMint(myAddress, desc, { amount: 10, slippageCents: 10 });
+plan.accepting; // false, with plan.refusal, when the enqueue would be refused now
+const { transaction } = await client.predict.tx.enqueuePlan(myAddress, desc, plan);
+// -> sign & execute any of these with your wallet / dapp-kit / signer
 
-// Decode the receipt from the execution result (execute with events included):
-const receipt = client.predict.decode.mint(mintResult);
-receipt.orderId; // PERSIST THIS — needed to redeem/claim later
-receipt.entryProbability; // your fill price (0..1 per $1 payout)
-receipt.premium; // exact cost breakdown
-receipt.fees;
+// Decode the enqueue from the execution result (execute with events included).
+const { recordId } = client.predict.decode.enqueue(result); // PERSIST THIS: sell or follow the order
+const outcome = await client.predict.read.waitForOutcome(desc, recordId); // 'filled' or 'refunded'
 
 // Read: one market's live state (+ NAV) and the pool.
 const market = await client.predict.read.market({ underlying: 'BTC', expiryMs });
@@ -87,6 +81,303 @@ console.log(market?.nav, market?.tickSize, market?.mintPaused);
 const pool = await client.predict.read.pool();
 ```
 
+> **Immediate trades retire with delayed execution.** Until a network's cutover,
+> `read.executionMode()` is `'immediate'` and orders fill in the transaction: quote with
+> `read.quoteMint`, trade with `tx.mint` (`quantity` and a `maxCost` ceiling), and decode with
+> `decode.mint`, whose `orderId` redeems or claims the position. `mint`, `mintAmount`, `mintCost`
+> and `redeem` work only while the config calls a pre-v4 Predict package. Predict v4 always aborts
+> them (`EDelayedExecutionRequired`), and the version watermark bump to 4 retires the older
+> packages. From then on orders are queued: see [Queued orders](#queued-orders-delayed-execution).
+> Branch on `read.executionMode()` rather than a release date.
+
+## Queued orders (delayed execution)
+
+With delayed execution (Predict v4, DBU-885) an order is placed now and filled later, at Pyth's
+signed price for its τ: the Pyth Lazer channel tick at or before placement + the policy delay (800
+ms on the 200 ms channel at launch). A keeper, or anyone running the open filler, commits the price
+and resolves the order: a fill, or a refund with a reason code. A filled mint stays in the market's
+queue as an **Open record**, not in the account. Sell it early with `enqueueSell`, or let the
+queue's settlement walk pay it at settlement.
+
+Delayed execution spans three packages. Predict (upgraded to v4) keeps the markets, pricing, cash
+and settlement. The order-flow package `deepbook_predict_orders` holds the queue: each market has
+one `MarketQueue`, at an ID derived from the package's single `QueueRegistry` and the market
+(`client.predict.queueIdFor(marketId)`, or `deriveQueueId(registry, market)`), and its single
+`OrderDesk` holds the policy (delay, order fee, capacities). The math library
+`deepbook_predict_math` holds the pure pricing math. Every queued-order call goes to
+`deepbook_predict_orders`, while a fill still emits Predict's `OrderMinted` or `LiveOrderRedeemed`.
+
+> Both the Testnet and Mainnet configs record delayed execution. On a network without a record the
+> queued surface throws `PredictInputError`. Pass a `config` with
+> `packages.predictDelayedExecution`, `packages.predictOrders`, `objects.orderDesk` and
+> `objects.queueRegistry` set (a localnet publish) to use it there. Until a network's version
+> watermark reaches 4, `read.executionMode()` returns `'awaiting-cutover'` and Predict's admission
+> refuses enqueues.
+
+```ts
+import { snapStrike } from '@mysten/deepbook-v3/predict';
+
+// Which path is live? 'immediate' | 'awaiting-cutover' | 'delayed' | 'unsupported' | 'retired'.
+const mode = await client.predict.read.executionMode();
+
+// The market's queue: the "pricing delayed" gate, τ / deadline / cutoff preview, the order fee,
+// and the largest mint the market's spare cash takes now.
+const queue = await client.predict.read.queue(desc, myAddress);
+queue.stuck; // show "pricing delayed" and stop offering orders
+queue.acceptingMints; // and queue.acceptingSells: one side can be full while the other is open
+queue.refusal.mint; // the preflight code a mint would get now, or null
+queue.maxMint.budget.maxRaw; // "Max right now" for a budget mint, raw USDC
+
+// A strike near the money. Admission refuses an entry price outside the market's band, which each
+// market snapshots at creation (`read.feePolicy`): 0.25–0.75 on Mainnet, and 0.15–0.85 on Testnet
+// markets created since 2026-10-13. Once the price moves away from a window's reference, the
+// reference strike can sit outside it.
+const pricer = await client.predict.read.pricer(desc);
+const atm = snapStrike(pricer.strikeAtProbability(0.5)!, tradeable[0].admissionTickSize);
+const atmDesc = { ...desc, strike: atm };
+
+// Plan, then queue. `planMint` quotes the order at the current price and turns the slippage into
+// the limits the enqueue carries. Slippage is cents per contract, never a percentage: a contract
+// pays $1, so 10¢ lets a 42¢ contract fill at up to 52¢, fees included.
+const plan = await client.predict.read.planMint(myAddress, atmDesc, {
+	amount: 10,
+	slippageCents: 10,
+});
+const { transaction, preview } = await client.predict.tx.enqueuePlan(myAddress, atmDesc, plan);
+preview.timing.tauMs; // when it prices
+preview.totalDebit; // budget + order fee, debited at enqueue. Unused budget comes back at the fill
+
+// After execution (with events included): the record ID is the handle for everything else.
+// Persist it. `waitForOutcome` keeps polling a record the fullnode doesn't show yet.
+const { recordId } = client.predict.decode.enqueue(result);
+const outcome = await client.predict.read.waitForOutcome(atmDesc, recordId);
+outcome.order?.view; // 'filled' (an Open record holding the position) or 'refunded' (with a reason)
+
+// Sell an Open record early: plan it, then queue the sell with the plan's floors.
+const sellPlan = await client.predict.read.planSell(myAddress, desc, {
+	recordId,
+	quantity: 50,
+	slippageCents: 10,
+});
+const sell = await client.predict.tx.enqueuePlan(myAddress, desc, sellPlan);
+```
+
+The plan and preview types are exported (`MintPlan`, `SellPlan`, `PlanMintOptions`,
+`PlanSellOptions`, `SlippageOptions`, `QueuedOrderPlan`, `QueuedOrderPreview`), so form state can be
+typed without `ReturnType`.
+
+#### After expiry: showing the result
+
+At expiry a keeper settles the market, pays every Open record its settled payout (the full quantity
+in range, 0 out of range) into the owner's account, and cleans the records up. On Testnet all of
+that lands within about a second of expiry. So by the time an app looks:
+
+- `read.order` returns `null` and `waitForOutcome` ends `'gone'` for a filled record. After expiry
+  that means the market paid it out, not that the order was lost.
+- `read.market`, `read.price` and the quotes abort `ELivePricingExpired`.
+- `read.settlement` still works. Keep each filled record's `position.orderId` (from
+  `waitForOutcome`, `read.order` or `decode.queuedFills`) and pass it to `cost.settledPayout`.
+
+```ts
+import { cost } from '@mysten/deepbook-v3/predict';
+
+const s = await client.predict.read.settlement(desc);
+if (s.settled) {
+	const payoutRaw = cost.settledPayout(orderId, s.settlementPriceRaw!, s.tickSizeRaw);
+	const won = payoutRaw > 0n; // payoutRaw is raw USDC, already in the account's balance
+}
+```
+
+The payout also arrives as an `OpenRecordSettled` event (`decode.openRecordPayouts`) in the keeper's
+transaction, which an indexer serves. If the payout walk skipped a record
+(`OpenRecordPayoutSkipped`), the record stays Open until `tx.payOpen` pays it.
+
+#### A purchase form
+
+`read.planMint(owner, market, opts)` returns everything a purchase form shows, for a visitor without
+an account too (the quote then comes from the account-free `quote_mint`, which leaves out an
+account's builder fee). An account whose balance covers the order is quoted at its own pricing, and
+a budget that pricing refuses is never planned from the account-free quote. `amount` plans an all-in
+spend and is the whole debit by default, order fee included (`orderFee: 'exclusive'` charges the fee
+on top). `quantity` plans an exact payout instead.
+
+| Form field                     | Plan field                                                                    |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| Lower / upper bound            | `snapStrike(price, market.admissionTickSize, 'down' \| 'up')` before planning |
+| Trade balance                  | `balance.available` (null without an account), `balance.covers`               |
+| Purchase presets, "Max"        | `maxNow`: the most the market's spare cash and the balance take now           |
+| Payout multiple                | `payoutMultiple` (at the current price, order fee included)                   |
+| Potential payout               | `potentialPayout`, and `minPayout` at the worst price                         |
+| Price per contract             | `pricePerContract`, and `worstPricePerContract` (unsubsidized, plus slippage) |
+| Max slippage                   | `slippageCents` in, `slippage.cents` out (`'auto'` sizes it from the model)   |
+| Order fee                      | `orderFee`, read from the order desk every time                               |
+| "Pricing in about a second"    | `timing.tauMs`, `timing.deadlineMs`                                           |
+| Disabled button and its reason | `accepting`, `refusal` (the preflight code a mint would get now)              |
+
+A budget plan's fill buys what the budget buys at τ and is refunded with the order fee returned when
+that is below `minPayout`. An exact plan's fill is refunded when the entry probability or the all-in
+cost passes its cap. The limits are sized from the price without the fee subsidy, because enqueue
+admission checks the order without it and the subsidy can run out before the fill. A budget plan's
+payout floor is also checked with an exact quote at that quantity, so it never asks for more than
+admission buys. The quote, the payout multiple and `pricePerContract` show the subsidized price the
+fill is expected to charge. A budget plan needs a premium of at least 1 USDC, so a smaller budget,
+or an amount the order fee takes whole, is refused with `min-premium`. `planSell` returns the sell
+side: `proceeds`, `net` (after the order fee, negative when the fee is above the proceeds),
+`minProceeds` and `minNet` at the worst price, and the `enqueueSell` options. A `slippageCents` of
+0, or a few cents, is accepted but leaves the price little room to move between the quote and τ.
+Such an order is often refused at placement (`EOrderFailsLimits`, by the build's dry run or on
+chain, where gas is spent) or refunded at the fill, and a refund keeps the order fee. `'auto'` sizes
+the room from the model.
+
+- **Preflight, typed.** Each `enqueue*` builder reads the market once and refuses, with a
+  `PredictPreflightError` and a `code`, an order the queue or protocol gates would abort: `not-live`
+  (the watermark isn't raised, or Predict doesn't allowlist the order-flow package yet), `no-queue`
+  (the market's `MarketQueue` isn't created yet), `retired` (a Predict upgrade raised the watermark
+  above the Predict code this SDK calls, or the desk's version floor retired the order-flow package
+  it calls), `paused`, `stuck`, `past-cutoff`, `queue-full`, `account-cap`, `fee` (prompt a top-up:
+  a mint needs a balance above the order fee, a sell at least the fee), `market-cash`,
+  `min-premium`, `entry-band`, `below-min-sell`, `record-not-open`, `not-record-owner`. A plan's
+  `accepting` and `refusal` run the same preflight on the plan's order, so the form's button never
+  enables an order its enqueue refuses. A mint plan also refuses `fee` when the balance doesn't
+  cover `totalDebit`, `min-premium` when a budget buys less than the minimum premium without the fee
+  subsidy, and `cost-above-payout` when the unsubsidized cost is above the payout, or for a budget,
+  about the payout. `tx.enqueuePlan` takes the descriptor a mint plan was planned with, or the
+  coordinates `planSell` took for a sell plan. It throws a refused plan's code, and `fee` when the
+  balance now escrows less than the plan's budget. It also throws a `PredictInputError` when called
+  with another owner, market, strike, side or record than the plan's `target`, since the plan's
+  limits fit only that order, and when the order fee rose since the plan, since the plan's debit and
+  a sell's net assume its fee. A plan made with `strike: 'reference'` is refused once the reference
+  strike moves. When the chain refuses to quote a plan, `planMint` throws a typed refusal where it
+  can tell why: `entry-band` for a strike outside the market's entry band, `min-premium` for an
+  order whose premium is below 1 USDC. The probability can still leave the band between plan and
+  placement, which the chain refuses with `EOrderFailsLimits`. A plan on a market past its expiry
+  throws `past-cutoff`, since the chain has no live price to quote. `planSell` throws
+  `record-not-open` for a record that isn't Open, and a `PredictInputError` for more than the record
+  holds, since the chain can't quote either. Two admission conditions are checked only on chain, at
+  placement: the market's SVI age under the order desk's `svi_max_age_ms`, and room in the payout
+  tree for a new strike's boundary nodes. A refused order never fails the rest of a transaction. The
+  order's own price limits are checked only on chain, at placement (`EOrderFailsLimits`), and the
+  preview runs on the local clock, so near the cutoff the chain can still refuse: decode that with
+  `describePredictError`. `EOrderFailsLimits` also covers admission: an entry price outside the
+  market's band, or a premium below the minimum. `planMint` throws `entry-band` when the strike's
+  price is outside the band, before any plan exists, so pick a strike with
+  `pricer.strikeAtProbability` and `snapStrike` rather than offering one far from the money.
+- **Pricing aborts.** Every quote, plan and enqueue loads the market's live pricer, which aborts in
+  Predict's `pricing` module while an oracle input is missing or stale
+  (`EBlockScholesPriceUnavailable`, `EBlockScholesPriceStale`, and the SVI and Pyth forms). These
+  clear once the oracles write again, usually within seconds, and `describePredictError` gives each
+  a "try again" text. The plan's quote can pass and the enqueue still abort, so a submitted order
+  can fail this way too: offer a retry rather than an error page.
+- **Plans are snapshots.** A plan's quote, limits, fee and gates are read once, when it is made, and
+  the SDK never expires a plan. `tx.enqueuePlan` reads the gates and the balance again and refuses a
+  refused plan, a smaller escrow, a fee rise, another target or a moved reference strike, but it
+  keeps the plan's limits. Every enqueue the facade builds starts with
+  `queueTx.assertOrderFeeAtMost`, which aborts the transaction (`option::EOPTION_NOT_SET`, described
+  by `describePredictError`) when the desk's fee rose between building and execution, since the
+  enqueue charges the fee at execution and takes no fee bound. An old plan still places at the old
+  price's limits, which then fill or refund at τ, so plan again when the price has moved or the user
+  has waited. The timing preview (`tauMs`, `deadlineMs`, `beforeCutoff`) runs on the device clock,
+  and the chain's clock decides, so a skewed device clock shows the wrong countdown and can let an
+  order past the cutoff preflight. The market's oracle objects (the Pyth feed and the Block Scholes
+  stores) come from the config, which pins them per deployment: a feed re-bound on chain aborts
+  `EWrongPythFeed` or `EWrongBlockScholesValueStore` until the SDK, or a `config` override, records
+  the new one. A session key's raw `SessionsContract` call skips the facade's preflight and plan
+  binding, so check the plan's `accepting` and send the plan's own strike and limits.
+- **Order states.** `read.order(s)` returns each record with `queue.orderView`: `placed` (with
+  `awaitingPrice` once τ passes), `priced` (the committed price and a countdown to the deadline),
+  then `filled` or `refunded`. A filler that commits a price and resolves the order in one
+  transaction moves it from `placed` straight to `filled`, so a UI can't count on seeing `priced`.
+  Report "Filled" only from the record or the `QueuedOrderFilled` event. For an indexer or event
+  feed, `decode.queueEvents` + `queue.reduceOrderEvents` build the same states.
+- **Refunds.** Keepers refund an unfinished order at its deadline (τ + 5 s). Offer "Refund my order"
+  (`tx.refund(m)`) only when `view.canRequestRefund` is true, 5 s past the deadline. It needs no
+  account or Pyth key and works during a freeze. Never prepend it to other transactions.
+  `queue.REFUND_REASONS` maps each reason to its text and fee treatment: reasons 1 and 2 keep the
+  order fee, the rest return it, 8 means the market couldn't pay at the fill, and 9 means the
+  account's receive address couldn't take USDC (it is on USDC's deny list, or USDC is paused).
+- **Parked funds.** Nothing sends USDC to a denied address. A fill for a denied receive address is
+  refused (reason 9), and a refund or change the address can't take stays in its record
+  (`RecordFundsParked`, `view.parkedRaw`). Once the address is clear, `tx.claimParked(m, recordId)`
+  sends it there. A settled Open record whose payout was skipped (short of cash, or a denied
+  address) is paid with `tx.payOpen(m, recordId)`. Both are permissionless: anyone can send them,
+  and the USDC goes only to the record's own receive address. Each queue call that can send USDC
+  reads Sui's shared `DenyList` (`0x403`) read-only, which the builders add on their own.
+- **Big sells.** A sell's cash need above spare cash sets `preview.needsFunding`. By default the
+  builder adds `rebalance_expiry_cash` after the enqueue so the market is funded at once
+  (`fundMarket: 'auto' | 'always' | 'never'`). A sell still uncovered at the fill is refunded in
+  full and its position returns to an Open record.
+- **Positions.** A filled mint is an Open record in the market's queue, not a position in the
+  account, so `read.positions(owner)` doesn't list it. The SDK has no indexer client, so the app
+  supplies record IDs from its enqueue receipts or its indexer, and reads them with `read.orders`.
+  `claimSettled` still pays positions minted into the account before delayed execution. Pending
+  refunds and proceeds sent to the account show in `read.pendingFunds(owner)` (already counted in
+  `read.balance`).
+- **The open filler.** `tx.fill(m, { payloads })` verifies signed Lazer payloads with the current
+  Lazer package (read from Lazer's `State` per call), commits them and resolves up to `maxOrders`
+  records. Anyone with Lazer access can run one.
+- **Settlement.** After Predict's `try_settle`, the queue's `settle_step` refunds the orders still
+  waiting (reason 5) and then pays each Open record its settled payout to the account's wrapper
+  address (`OpenRecordSettled`, 0 for a loser). One call per transaction until it returns
+  `queue.SETTLE_PHASE.DONE`. DONE means the walk reached the last record: a record the market
+  couldn't pay stays Open with `OpenRecordPayoutSkipped`, for a later `pay_open`. `settle_step` is
+  permissionless, so its refund events carry whoever sent the transaction as `sender`.
+- **Pure helpers** in the `queue` namespace: the cash-need formulas (ported 1:1 from
+  `deepbook_predict_math::math`), `maxMintNow`, `previewTiming`, `orderCutoffMs`, and
+  `slippageBand`, a heuristic `Δp ≈ k · φ(Φ⁻¹(p)) · √(h / T)` for sizing `maxProbability` /
+  `minProbability` that still needs product sign-off. `queueTx` has the thunks for composing an
+  enqueue into your own PTB (`queueTx.enqueueExactCost(toOrdersConfig(cfg), …)`), plus the keeper's
+  `createQueue` (registry, desk and market), `commit`, `resolve`, `refund`, `adminRefund`,
+  `settleStep`, `payOpen`, `claimParked` and `cleanup`. `SessionsContract` has the `enqueue*`
+  session wrappers, which take the `orderDesk` and the `queueRegistry` and need Sessions v3, which
+  `getSessionsConfig` records on both networks.
+
+#### Queued orders from a session key
+
+A session key trades the owner's account, so plan against the owner and send the plan's raw limits
+through the `SessionsContract` wrapper. The session key signs, sends and pays its own gas, and
+`decode.enqueue` and `waitForOutcome` work as they do for an owner's enqueue.
+
+```ts
+import { Transaction } from '@mysten/sui/transactions';
+import { binaryRangeTicks, priceToRaw } from '@mysten/deepbook-v3/predict';
+import { SessionsContract, getSessionsConfig } from '@mysten/deepbook-v3/sessions';
+
+const sessions = new SessionsContract(getSessionsConfig('testnet'));
+const { objects, underlyings } = client.predict.cfg;
+const target = {
+	expiryMarketId: tradeable[0].id,
+	wrapperId: sessions.deriveAccountWrapperId(owner),
+	orderDesk: objects.orderDesk!,
+	queueRegistry: objects.queueRegistry!,
+	protocolConfig: objects.protocolConfig,
+	oracleRegistry: objects.oracleRegistry,
+	pythFeed: underlyings.BTC.pythFeed,
+	blockScholesValueStore: underlyings.BTC.blockScholesValueStore,
+	blockScholesSviStore: underlyings.BTC.blockScholesSviStore,
+};
+const plan = await client.predict.read.planMint(owner, atmDesc, { amount: 10, slippageCents: 10 });
+const { lowerTick, higherTick } = binaryRangeTicks(
+	priceToRaw(atm),
+	'up',
+	priceToRaw(tradeable[0].tickSize),
+);
+const tx = new Transaction();
+tx.add(
+	sessions.enqueueExactCost({
+		...target,
+		lowerTick,
+		higherTick,
+		maxCost: plan.raw.budget,
+		minQuantity: plan.raw.minQuantity,
+	}),
+);
+// Sell an Open record the same way: `enqueueRedeemOpen` with the record's quantity and
+// `planSell(owner, …).raw.minProbability` / `.raw.minProceeds`.
+```
+
+A revoked or expired key aborts `sessions::ESessionNotAuthorized`, which `describePredictError`
+explains along with the other Sessions and account aborts.
+
 ## ⚠ Slippage defaults are UNCAPPED
 
 `mint` mirrors the chain's semantics: when you omit `maxCost` and `maxProbability`, the mint is
@@ -189,9 +480,12 @@ const tx = await client.predict.tx.mint(
 
 - **`client.predict.tx`** — `createManager`, `deposit`, `withdraw`, `mint`, `mintAmount`,
   `mintCost`, `redeem`, `claimSettled`, `supplyPlp`, `withdrawPlp`, `cancelSupplyPlp`,
-  `cancelWithdrawPlp`, `setBuilderCode`, `unsetBuilderCode`. Market-resolving builders
-  (`mint`/`mintAmount`/`mintCost`/`redeem`/`claimSettled`) are async: they resolve the market object
-  from `{ underlying, expiryMs, strike, side }` via the on-chain registry (cached per client).
+  `cancelWithdrawPlp`, `setBuilderCode`, `unsetBuilderCode`, and for queued orders `enqueuePlan`,
+  `enqueueMint`, `enqueueMintAmount`, `enqueueMintCost`, `enqueueSell`, `refund`, `claimParked`,
+  `payOpen`, `fill` (see [Queued orders](#queued-orders-delayed-execution)). Market-resolving
+  builders (`mint`/`mintAmount`/`mintCost`/`redeem`/`claimSettled`) are async: they resolve the
+  market object from `{ underlying, expiryMs, strike, side }` via the on-chain registry (cached per
+  client).
 - **`client.predict.read`** — `markets()` (summaries of the pool's **active** markets — live and not
   yet settled, so a market past expiry that nobody has settled is still listed and quoting against
   it aborts; filter on `expiryMs` and `mintPaused` before trading: id, expiry, tick size, admission
@@ -201,27 +495,42 @@ const tx = await client.predict.tx.mint(
   `quoteMint(owner, m, opts)` / `quoteMintCost(owner, m, opts)` / `quoteRedeem(owner, m, opts)`
   (exact dry-run quotes: real fees from the real code path — and they throw the same typed errors
   the real trade would, so a quote doubles as preflight), `balance(owner)`, `plpBalance(owner)`,
-  `pool()`, `positions(owner)` (chain-only enumeration of open positions),
-  `hasPosition(owner, marketId, orderId)`. All reads run over the client's `simulateTransaction`; no
-  indexer required.
+  `pool()`, `feePolicy(m)` (the market's fee snapshot, for `cost`), `settlement(m)` (the settlement
+  price, which still reads after expiry, when `market` and the quotes abort), `positions(owner)`
+  (chain-only enumeration of open positions), `hasPosition(owner, marketId, orderId)`, and for
+  queued orders `executionMode()`, `queue(m)`, `planMint(owner, m, opts)`,
+  `planSell(owner, m, opts)`, `order(m, id)`, `orders(m, ids)`, `waitForOutcome(m, id)`,
+  `quoteSell(owner, m, opts)`, `pendingFunds(owner)`, `lazerPackages()`. All reads run over the
+  client's `simulateTransaction`; no indexer required.
 - **`client.predict.decode`** — pure execution-result decoders (no network): `mint`, `redeem`,
   `claim`, `createManager`, `deposit`, `withdraw`, `plpRequest`, `plpCancel`, `builderCode`. Each
   singular form throws unless exactly one matching event is present; `mints`, `redeems` and `claims`
   are the plural forms for batched PTBs and return every receipt (the other decoders have no
   plural). Execute transactions with events included and pass the result; receipts come back in SDK
   units with raw bigints alongside. Decoding uses the events' canonical BCS bytes, so it is
-  transport-independent.
+  transport-independent. The queue decoders (`enqueue`, `queueEvents`, `cohortCommits`,
+  `queuedFills`, `queuedRefunds`, `openRecordPayouts`, `marketPayoutsCompleted`, `queueOps`) match
+  the order-flow package's `queue_events` against its original ID
+  (`packages.predictOrdersV1 ?? predictOrders`). `expiryPnlRealized` matches against
+  `packages.predictDelayedExecution`, the Predict version that introduced it, and `policyUpdates`
+  decodes the desk's `DelayedExecutionPolicyUpdated` and Predict's `FlushOperatorUpdated` and
+  `OrderFlowUpdated`. `realizedPnlRaw` sums `expiryPnlRealized` receipts into the pool's gross
+  realized P&L.
 - **PTB composition** — each `client.predict.tx.*` builder returns a finished `Transaction`, so to
   put a Predict call into a PTB you are building, use the generated move-call bindings `/predict`
   exports: one namespace of transaction thunks per Predict module (`plpMoveCalls`,
   `expiryMarketMoveCalls`, `predictAccountMoveCalls`, `protocolConfigMoveCalls`,
   `registryMoveCalls`, `builderCodeMoveCalls`, `marketManagerMoveCalls`, `pricingMoveCalls`,
   `rangeCodecMoveCalls`, `adminMoveCalls` and the cap modules) plus the event layouts
-  (`vaultEvents`, `orderEvents`, `configEvents`, `builderCodeEvents`). Pass
-  `config: toGeneratedConfig(cfg)` — the flat config slice the bindings resolve the shared objects
-  against — and give owner-authorized calls `auth: tx.add(generateAuth(cfg))`, the hot-potato `Auth`
-  the account calls consume. The account itself (create, deposit, share) is
-  `@mysten/deepbook-v3/account`'s `accountRegistryMoveCalls` / `accountMoveCalls`. Also exported:
+  (`vaultEvents`, `orderEvents`, `configEvents`, `builderCodeEvents`). The order-flow package's
+  bindings are `queueMoveCalls`, `deskMoveCalls`, `orderQueueMoveCalls`,
+  `delayedExecutionConfigMoveCalls` and `queueEvents`, and the math library's are
+  `predictMathMoveCalls` and `lazerPriceMoveCalls`. Pass `config: toGeneratedConfig(cfg)` — the flat
+  config slice the bindings resolve the shared objects against, or `toOrdersConfig(cfg)` for the
+  order-flow package, which adds it and its desk — and give owner-authorized calls
+  `auth: tx.add(generateAuth(cfg))`, the hot-potato `Auth` the account calls consume. The account
+  itself (create, deposit, share) is `@mysten/deepbook-v3/account`'s `accountRegistryMoveCalls` /
+  `accountMoveCalls`. Also exported:
   `loadLivePricer(toGeneratedConfig(cfg), { expiryMarketId, ...cfg.underlyings[sym] })` — the
   `pricer` every live trade call borrows, which the `/sessions` Predict wrappers take as a PTB
   result — and `deriveAccountWrapperId(cfg, owner)`.
@@ -248,8 +557,8 @@ const tx = await client.predict.tx.mint(
 
 - **`cost`** — the deployed FEE math as an exact integer port, so an all-in quote costs no chain
   call: `mintCost` (what a mint debits), `mintCostForBudget` (the `mint_exact_cost` budget search),
-  `redeemLiveProceeds` (what a live close credits), plus the components they are built from. See
-  below.
+  `redeemLiveProceeds` (what a live close credits), `settledPayout` (what an order pays at a
+  settlement price), plus the components they are built from. See below.
 
 - **Typed errors** — invalid inputs throw `PredictInputError` before the chain sees them; failed
   simulations throw `PredictMoveError` with the decoded Move abort (`module`, `code`, `abortName`).
@@ -308,7 +617,7 @@ import { cost } from '@mysten/deepbook-v3/predict';
 
 const pricer = await client.predict.read.pricer({ underlying: 'BTC', expiryMs });
 const shape = {
-	fees: cost.SHIPPED_FEE_POLICY, // or the market's own MarketCreated snapshot
+	fees: await client.predict.read.feePolicy({ underlying: 'BTC', expiryMs }), // the market's own
 	expiryMs,
 	probabilities: { pricer, lower: 105_000, upper: null }, // an UP order at $105k
 };
@@ -389,8 +698,10 @@ a zero charge or rebate. The congestion rate defaults to zero (disabled in the s
 when enabled, supply `penaltyRate`, calculated by `cost.congestionPenaltyRate` from the market's
 gas-price EWMA and the transaction's gas price. Supply `builderCode`, `feeIncentiveBalance` and, for
 account-capped budget sizing, `accountBalance` to reflect the account being quoted. The fee
-**policy** is a per-market snapshot taken at creation — use the market's `MarketCreated` event, or
-`cost.SHIPPED_FEE_POLICY` only for a market created under that template.
+**policy** is a per-market snapshot taken at creation: read it with `read.feePolicy(market)`, one
+object read. Don't use `cost.SHIPPED_FEE_POLICY` for a live market. It is the code default, and
+neither recorded deployment's template matches it: both charge about twice its trading fee, ramp the
+fee to 3× over the last 60 s and admit entries in 25%–75%.
 
 Invalid raw domains (including negative amounts/rates, probabilities outside `[0, 1e9]`, and invalid
 lot sizes) throw `PredictInputError` before arithmetic. Supplied book totals must also be
@@ -414,8 +725,8 @@ initial deployment; subsequent package upgrades come from `Published.toml`:
 
 | Network   | Deployment                 | Chain id   | Source commit | `quoteCoinType`                                                                                                            |
 | --------- | -------------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `mainnet` | `deepbook-predict-mainnet` | `35834a8a` | `14a7e8f8`    | Circle native USDC — `0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC`                      |
-| `testnet` | `deepbook-predict-testnet` | `4c78adac` | `a928bd2d`    | mintable test coin, displays as `DUSDC` — `0xc028557a1ed49e42ed091e115aedefd70a442b184c18fbec5c48d5b6c0b8c184::usdc::USDC` |
+| `mainnet` | `deepbook-predict-mainnet` | `35834a8a` | `7b169bde`    | Circle native USDC — `0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC`                      |
+| `testnet` | `deepbook-predict-testnet` | `4c78adac` | `4d752fb8`    | mintable test coin, displays as `DUSDC` — `0xc028557a1ed49e42ed091e115aedefd70a442b184c18fbec5c48d5b6c0b8c184::usdc::USDC` |
 
 Object ids for both are baked into the SDK — `MAINNET_CONFIG` / `TESTNET_CONFIG`, with
 `MAINNET_DEPLOYMENT` / `TESTNET_DEPLOYMENT` and `MAINNET_UNITS` / `TESTNET_UNITS` alongside — and
@@ -429,17 +740,32 @@ Move-call targets resolve from the config's package ids, so a deployment of your
 passing `config` — `predict({ network, config })` or
 `new PredictClient({ client, network, config })` — and `network` is then not consulted.
 
-Testnet uses Predict and Sessions **v2** from deepbookv3 PR #1311. Mainnet remains **v1**.
-`packages.predict` and `sessionsPackageId` are the current Move-call targets; `packages.predictV1`
-and `sessionsPackageIdV1` retain the original IDs for existing struct types, events and
-dynamic-field keys. Custom upgraded configs must supply both IDs. The v1 fallback is only for custom
-deployments that have never been upgraded. A type first introduced in a later version uses that
-version's defining ID (for example, `MintRange` was introduced in v2).
-
-**All-in budget mint (v2 only):** `spend` caps the debit including all trade fees, and `minQuantity`
-is the minimum payout quantity accepted. It may spend less than the budget because of lot rounding,
-balance limits or the contract's sizing constraints. Network gas is separate. `mintAmount` retains
-its existing premium-only budget semantics.
+Mainnet runs Predict **v4** and Testnet Predict **v5**, both built from the same sources, with
+`deepbook_predict_orders` and `deepbook_predict_math` at v1 on both. Sessions is **v3** on both. The
+Published.toml records are in deepbookv3 through PR #1365. `packages.predict` and
+`sessionsPackageId` are the current Move-call targets; `packages.predictV1` and
+`sessionsPackageIdV1` retain the original IDs for existing struct types, events and dynamic-field
+keys. Custom upgraded configs must supply both IDs. The v1 fallback is only for custom deployments
+that have never been upgraded. A type first introduced in a later version uses that version's
+defining ID, and version numbers do not line up across networks, so check the defining ID on each
+one. For example, `MintRange` was introduced in v2 on both networks, and
+`vault_events::UsdcAddedToPlp` is defined by Mainnet v3 (`0x08fa3ef1…`) and Testnet v3
+(`0xb5155d4c…`), neither of them the current call target. The types and events delayed execution
+added are defined by Mainnet v4 and Testnet v5, which the configs record as
+`packages.predictDelayedExecution`.
+
+**Adding USDC to the pool without minting PLP:** `plpMoveCalls.addUsdcToPlp` wraps
+`add_usdc_to_plp`, which pays a `Coin<USDC>` into the pool's idle cash and mints nothing in return.
+Any caller can use it, and the whole amount accrues to existing PLP holders. The chain rejects the
+contribution when the pool has no PLP supply yet, the payment is under 10 USDC, a flush is in
+flight, or pool cash after the contribution would exceed 10 USDC per PLP. `client.predict` has no
+builder or decoder for this entrypoint. Match `UsdcAddedToPlp` against its defining ID, not
+`predictV1`.
+
+**All-in budget mint (v2 and later):** `spend` caps the debit including all trade fees, and
+`minQuantity` is the minimum payout quantity accepted. It may spend less than the budget because of
+lot rounding, balance limits or the contract's sizing constraints. Network gas is separate.
+`mintAmount` retains its existing premium-only budget semantics.
 
 ```ts
 const quote = await client.predict.read.quoteMintCost(myAddress, desc, {
@@ -456,8 +782,8 @@ const tx = await client.predict.tx.mintCost(myAddress, desc, {
 `read.quoteMintCost` simulates the actual budget mint with the owner's current balance and fees; it
 requires an existing funded account. Sessions callers can compose `SessionsContract.mintExactCost`
 with a live pricer using raw Move units. The generated `expiryMarketMoveCalls` also exposes
-`quoteMintExactCostForAccount` for lower-level PTBs. These new entrypoints require the v2 packages;
-do not use them with the recorded v1 Mainnet deployment.
+`quoteMintExactCostForAccount` for lower-level PTBs. These entrypoints require v2 or later. Both
+recorded deployments qualify, but a custom deployment still on v1 does not.
 
 An expired market stays in `read.markets()` until someone settles it — the list is the pool's
 live-and-not-yet-settled set, not a tradeable set. On either network, check `expiryMs` against the
@@ -465,8 +791,10 @@ clock (and `mintPaused`) before quoting rather than assuming the list is tradeab
 
 ## Notes
 
-- **Positions are enumerable on-chain**: `read.positions(owner)` lists every open position (market +
-  order id) straight from the account's position table — one round trip warm, no indexer. Persisting
+- **Account positions are enumerable on-chain**: `read.positions(owner)` lists every open position
+  (market + order id) straight from the account's position table — one round trip warm, no indexer.
+  With delayed execution a filled order is an Open record in the market's queue instead, which this
+  list doesn't include (see [Queued orders](#queued-orders-delayed-execution)). Persisting
   `decode.mint(result).orderId` and applying `decode.redeem(result).replacementOrderId` is still the
   fastest hot path, with `read.positions` as the fresh-start/recovery source and `read.hasPosition`
   as the cheap validator.