@mysten/deepbook-v3 2.6.4 → 2.8.0

package/src/predict/config/generated.ts

@@ -2,6 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { AccountConfig } from '../../account.js';
 import type { DeepbookPredictConfig } from '../../contracts/deepbook_predict/config-arguments.js';
+import type { DeepbookPredictMathConfig } from '../../contracts/deepbook_predict_math/config-arguments.js';
+import type { DeepbookPredictOrdersConfig } from '../../contracts/deepbook_predict_orders/config-arguments.js';
+import { PredictInputError } from '../errors.js';
 import type { PredictConfig } from './types.js';
 
 /**
@@ -39,3 +42,50 @@ export function toGeneratedConfig(cfg: PredictConfig): GeneratedConfig {
 		accountRegistry: cfg.objects.accountRegistry,
 	};
 }
+
+/**
+ * {@link GeneratedConfig} plus the order-flow companion (`deepbook_predict_orders`) and the math
+ * library: the slice the queued-order thunks and reads take. A queued order calls the companion,
+ * which calls into Predict, so one object carries both packages' keys. `predictOrdersPackageIdV1`
+ * is the companion's original ID, which types `OrderFlow` and the queue events.
+ */
+export type OrdersGeneratedConfig = GeneratedConfig &
+	DeepbookPredictOrdersConfig &
+	DeepbookPredictMathConfig & {
+		predictOrdersPackageId: string;
+		predictOrdersPackageIdV1: string;
+		orderDesk: string;
+		queueRegistry: string;
+	};
+
+/**
+ * Project a config that records delayed execution onto {@link OrdersGeneratedConfig}. Throws
+ * `PredictInputError` while the config lacks the Predict upgrade, the companion package, its desk
+ * or its queue registry: building a queued order against a guessed package would abort on chain
+ * or, worse, address the wrong one.
+ */
+export function toOrdersConfig(cfg: PredictConfig): OrdersGeneratedConfig {
+	const { predictDelayedExecution, predictOrders, predictOrdersV1, predictMath } = cfg.packages;
+	const { orderDesk, queueRegistry } = cfg.objects;
+	if (!predictDelayedExecution || !predictOrders || !orderDesk || !queueRegistry) {
+		const missing = [
+			!predictDelayedExecution && '`packages.predictDelayedExecution`',
+			!predictOrders && '`packages.predictOrders`',
+			!orderDesk && '`objects.orderDesk`',
+			!queueRegistry && '`objects.queueRegistry`',
+		].filter(Boolean);
+		throw new PredictInputError(
+			`delayed execution isn't recorded for ${cfg.network} in this SDK version (missing ` +
+				`${missing.join(', ')}): pass a \`config\` that records the Predict upgrade, the ` +
+				'`deepbook_predict_orders` package, its order desk and its queue registry',
+		);
+	}
+	return {
+		...toGeneratedConfig(cfg),
+		predictOrdersPackageId: predictOrders,
+		predictOrdersPackageIdV1: predictOrdersV1 ?? predictOrders,
+		predictMathPackageId: predictMath,
+		orderDesk,
+		queueRegistry,
+	};
+}

package/src/predict/config/mainnet.ts

@@ -18,10 +18,24 @@ export const MAINNET_CONFIG: PredictConfig = Object.freeze({
 	// The record widens `network` to `string` so the published types don't pin a literal;
 	// this file is the mainnet config by construction.
 	network: 'mainnet',
-	packages: MAINNET_PREDICT.packages,
-	objects: MAINNET_PREDICT.objects,
+	// Delayed execution (DBU-885) is recorded on Mainnet. The generated record carries the package
+	// IDs that move with upgrades (Predict, `deepbook_predict_orders`, `deepbook_predict_math`) and
+	// the Lazer `State`. The three IDs pinned below are in no publication record and never move:
+	// the Predict version that introduced delayed execution (Mainnet v4), which defines its new
+	// types and events, and the `OrderDesk` and `QueueRegistry` that `deepbook_predict_orders`'s
+	// `init` shared at publish.
+	packages: Object.freeze({
+		...MAINNET_PREDICT.packages,
+		predictDelayedExecution: '0x98235c5842831c9b5f51dc637cf34c91db2aca5510802eb6ebfec63f5b71a7bb',
+	}),
+	objects: Object.freeze({
+		...MAINNET_PREDICT.objects,
+		orderDesk: '0x87b0a87262aacf58eaff567eed2fb7cb0f9cbc1f5ce33ef79216cd26d13a1b5b',
+		queueRegistry: '0x8d4f0c671862f065ac7f2c2cb24abc47cf75ed8fc8e5e52c1d4bdfa53eee164f',
+	}),
 	quoteCoinType: MAINNET_PREDICT.quoteCoinType,
 	coinTypes: MAINNET_PREDICT.coinTypes,
 	units: MAINNET_PREDICT.units,
 	underlyings: MAINNET_PREDICT.underlyings,
+	oracle: MAINNET_PREDICT.oracle,
 });

package/src/predict/config/testnet.ts

@@ -18,10 +18,24 @@ export const TESTNET_CONFIG: PredictConfig = Object.freeze({
 	// The record widens `network` to `string` so the published types don't pin a literal;
 	// this file is the testnet config by construction.
 	network: 'testnet',
-	packages: TESTNET_PREDICT.packages,
-	objects: TESTNET_PREDICT.objects,
+	// Delayed execution (DBU-885) is recorded on Testnet. The generated record carries the package
+	// IDs that move with upgrades (Predict, `deepbook_predict_orders`, `deepbook_predict_math`) and
+	// the Lazer `State`. The three IDs pinned below are in no publication record and never move:
+	// the Predict version that introduced delayed execution (Testnet v5), which defines its new
+	// types and events, and the `OrderDesk` and `QueueRegistry` that `deepbook_predict_orders`'s
+	// `init` shared at publish.
+	packages: Object.freeze({
+		...TESTNET_PREDICT.packages,
+		predictDelayedExecution: '0x0654ecbed7c0f2645d9de7cb6cf08e65c2ee05cdbb39a415f17a6bd1cd92e267',
+	}),
+	objects: Object.freeze({
+		...TESTNET_PREDICT.objects,
+		orderDesk: '0x160fc026c4143f3dec36acfc6556379d54661d37fe28ad837b6a85e42aeddfea',
+		queueRegistry: '0xe9d75ed05b089d52a660a94b94963cdc89aeb7f3c75b57f76771454c81faae1f',
+	}),
 	quoteCoinType: TESTNET_PREDICT.quoteCoinType,
 	coinTypes: TESTNET_PREDICT.coinTypes,
 	units: TESTNET_PREDICT.units,
 	underlyings: TESTNET_PREDICT.underlyings,
+	oracle: TESTNET_PREDICT.oracle,
 });

package/src/predict/config/types.ts

@@ -1,11 +1,42 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
-/** The three published Move packages a Predict deployment spans. */
+/**
+ * The published Move packages a Predict deployment spans.
+ *
+ * Delayed execution (DBU-885) ships as three packages: the Predict upgrade, the order-flow
+ * companion `deepbook_predict_orders` (a fresh publish), and the math library
+ * `deepbook_predict_math` (a fresh publish). The queued-order builders, reads and decoders need
+ * `predictDelayedExecution`, `predictOrders`, `objects.orderDesk` and `objects.queueRegistry` all
+ * recorded, and throw
+ * `PredictInputError` otherwise rather than address the wrong package. Pass a custom `config`
+ * (a localnet publish) to use them before a network record exists.
+ */
 export interface PredictPackages {
 	/** Latest published package ID, used for Move calls. */
 	predict: string;
 	/** Original ID for v1 structs/events. Omit only for an unupgraded custom deployment. */
 	predictV1?: string;
+	/**
+	 * The Predict version that introduced delayed execution (Mainnet v4, Testnet v5): the
+	 * defining ID of the Predict types and events that version added (`ExpiryPnlRealized`,
+	 * `FlushOperatorUpdated`, `OrderFlowUpdated`, `OrderReceipt`). A later upgrade does not move
+	 * it, so it is pinned once per network rather than read from the latest publication.
+	 */
+	predictDelayedExecution?: string;
+	/**
+	 * Latest published `deepbook_predict_orders` package ID: the call target of every queued-order
+	 * entry point (`queue::enqueue_*`, `commit`, `resolve`, `refund`, `settle_step`, …), the queue
+	 * reads and the desk setters.
+	 */
+	predictOrders?: string;
+	/**
+	 * Original `deepbook_predict_orders` ID, which types `MarketQueue`, `OrderDesk`, the queue
+	 * events and the `OrderFlow` witness. Omit until the package is first upgraded: it then
+	 * defaults to `predictOrders`.
+	 */
+	predictOrdersV1?: string;
+	/** The `deepbook_predict_math` package ID, for its pure calls and layouts. */
+	predictMath?: string;
 	account: string;
 	propbook: string;
 }
@@ -36,6 +67,17 @@ export interface PredictConfig {
 		poolVault: string;
 		oracleRegistry: string;
 		accountRegistry: string;
+		/**
+		 * The order-flow companion's shared `OrderDesk`: the delayed-execution policy and the
+		 * companion's version floor. Created once, by the package's `init` at publish.
+		 */
+		orderDesk?: string;
+		/**
+		 * The order-flow companion's shared `QueueRegistry`, created next to the desk by the same
+		 * `init`. Each market's `MarketQueue` sits at an ID derived from it and the market
+		 * (`deriveQueueId`), and `queue::create_and_share` writes it.
+		 */
+		queueRegistry?: string;
 	};
 	/**
 	 * The deployment's settlement coin type. Always read this rather than assuming a type:
@@ -58,4 +100,12 @@ export interface PredictConfig {
 		positionQuantityDecimals: number;
 	};
 	underlyings: Record<string, UnderlyingConfig>; // keyed by symbol, e.g. "BTC"
+	/**
+	 * Oracle objects only the delayed-execution filler needs. Optional: traders never pass
+	 * them, and a filler can name the Lazer `State` per call instead.
+	 */
+	oracle?: {
+		/** Pyth Lazer's shared `State`, which carries the current Lazer package ID. */
+		pythLazerState?: string;
+	};
 }

package/src/predict/cost.ts

@@ -31,9 +31,9 @@
 // against current account and market state, including the execution gates these previews
 // do not check (ownership, pauses, trade window, oracle freshness and cash backing).
 //
-// The fee POLICY is a per-market snapshot taken at creation (`StrikeExposureConfig`), and the
-// chain exposes no getter for `base_fee`/`min_fee` — take it from the market's `MarketCreated`
-// event (an indexer, or `decode`), or use {@link SHIPPED_FEE_POLICY} for the shipped template.
+// The fee POLICY is a per-market snapshot taken at creation (`StrikeExposureConfig`). The
+// chain exposes no getter for `base_fee`/`min_fee`, so `read.feePolicy(market)` decodes it from
+// the `ExpiryMarket` object. The market's `MarketCreated` event carries it too.
 
 import { PredictInputError } from './errors.js';
 import type { PricerInputs } from './pricing.js';
@@ -53,7 +53,14 @@ export const MIN_PREMIUM = 1_000_000n;
 export const BUILDER_FEE_MULTIPLIER = 100_000_000n;
 /** `constants::max_builder_fee_rate` — cap on the builder fee as a share of quantity (0.5%). */
 export const MAX_BUILDER_FEE_RATE = 5_000_000n;
-/** `constants::fee_incentive_subsidy_rate` — sponsor share of a trader's mint fee (20%). */
+/**
+ * The default sponsor share of a trader's mint fee (20%), and the rate the chain reads while the
+ * admin hasn't set one.
+ * @deprecated From delayed execution (DBU-885) the rate is admin-set: read it with
+ * `protocol_config::fee_incentive_subsidy_rate` (`read.queue(...).protocol.feeIncentiveSubsidyRate`)
+ * and pass it as `feeIncentiveSubsidyRate`. A hardcoded 20% underquotes every mint once the rate
+ * moves.
+ */
 export const FEE_INCENTIVE_SUBSIDY_RATE = 200_000_000n;
 /** `order::max_quantity_lots` — the order ID's 32-bit lot field. */
 export const MAX_QUANTITY_LOTS = (1n << 32n) - 1n;
@@ -130,8 +137,8 @@ export function sqrtDown(x: bigint): bigint {
 /**
  * One market's fee policy: the `StrikeExposureConfig` it snapshotted at creation, in raw 1e9
  * rates. Snapshotted means later admin changes do NOT reprice a market already trading, so
- * read it per market (the `MarketCreated` event carries every field) rather than assuming the
- * template. The last three are the inventory-impact parameters, inert while
+ * read it per market with `read.feePolicy(market)` (the `MarketCreated` event carries every field
+ * too) rather than assuming the template. The last three are the inventory-impact parameters, inert while
  * `inventoryImpactMaxRate` is `0n` (the shipped value).
  */
 export interface FeePolicy {
@@ -158,9 +165,11 @@ export interface FeePolicy {
 /**
  * The shipped template (`config_constants` defaults): 10% Bernoulli fee, a 2.2% per-leg floor,
  * a one-day ramp window that is inert at a 1.0 multiplier, a 1%–99% entry band, and inventory
- * impact disabled. A market that was created under these values charges exactly this; one
- * created after an admin change does not, which is why the per-market snapshot is the real
- * answer. Verify against the deployment's `MarketCreated` before pricing money on it.
+ * impact disabled. Neither recorded deployment's template matches it any more: both charge a
+ * 20.4% Bernoulli fee, ramp it to 3× over the last 60 s and admit entries in 25%–75% (checked
+ * 2026-10-09), so a live market's costs from this policy come out low. Pass
+ * `read.feePolicy(market)` instead. This stays for tests and for a deployment still on the
+ * defaults.
  */
 export const SHIPPED_FEE_POLICY: FeePolicy = Object.freeze({
 	baseFee: 100_000_000n,
@@ -347,11 +356,17 @@ export function builderFee(fee: bigint, quantity: bigint, hasBuilderCode: boolea
 }
 
 /** `expiry_market::fee_incentive_subsidy_amount` — a sponsor pays part of the trader's MINT
- * fee, bounded by the expiry's remaining sponsored balance. Mints only; redeems pay in full. */
-export function feeIncentiveSubsidy(fee: bigint, feeIncentiveBalance: bigint): bigint {
+ * fee, bounded by the expiry's remaining sponsored balance. Mints only; redeems pay in full.
+ * `rate` is the protocol's `fee_incentive_subsidy_rate` (1e9-scaled), 20% when omitted. */
+export function feeIncentiveSubsidy(
+	fee: bigint,
+	feeIncentiveBalance: bigint,
+	rate: bigint = FEE_INCENTIVE_SUBSIDY_RATE,
+): bigint {
 	assertUint(fee, 'fee');
 	assertUint(feeIncentiveBalance, 'feeIncentiveBalance');
-	return min(mulDown(fee, FEE_INCENTIVE_SUBSIDY_RATE), feeIncentiveBalance);
+	assertUint(rate, 'feeIncentiveSubsidyRate', FLOAT_SCALING);
+	return min(mulDown(fee, rate), feeIncentiveBalance);
 }
 
 /**
@@ -534,7 +549,15 @@ interface MintInputsBase {
 	builderCode?: boolean;
 	/** The expiry's remaining sponsored fee balance (`fee_incentive_balance`). Default `0n`. */
 	feeIncentiveBalance?: number | bigint;
-	/** Per-unit congestion surcharge rate — see {@link congestionPenaltyRate}. Default `0n`. */
+	/**
+	 * The protocol's admin-set mint fee subsidy rate (`protocol_config::fee_incentive_subsidy_rate`),
+	 * 1e9-scaled. Defaults to the 20% the chain reads while unset.
+	 */
+	feeIncentiveSubsidyRate?: bigint;
+	/**
+	 * Per-unit congestion surcharge rate — see {@link congestionPenaltyRate}. Default `0n`. A
+	 * queued (delayed-execution) fill pays no congestion penalty, so queued previews keep it 0.
+	 */
 	penaltyRate?: bigint;
 	/** Pre-trade payout-tree terms. Required when inventory impact is enabled. */
 	book?: MintBookTerms;
@@ -663,7 +686,11 @@ function mintQuoteAt(
 } {
 	const premium = mulDown(rangeProbability(boundaries), quantity);
 	const fee = tradingFee(inputs.fees, boundaries, quantity, timeToExpiryMs);
-	const subsidy = feeIncentiveSubsidy(fee, rawAmount(inputs.feeIncentiveBalance ?? 0n));
+	const subsidy = feeIncentiveSubsidy(
+		fee,
+		rawAmount(inputs.feeIncentiveBalance ?? 0n),
+		inputs.feeIncentiveSubsidyRate,
+	);
 	const builder = builderFee(fee, quantity, inputs.builderCode ?? false);
 	const penalty = mulDown(inputs.penaltyRate ?? 0n, quantity);
 	const impact = inputs.book ? mintInventoryImpact(inputs.fees, inputs.book, quantity) : 0n;
@@ -1008,6 +1035,27 @@ export function decodeOrderRange(orderId: bigint, lotSize: bigint = POSITION_LOT
 	};
 }
 
+/**
+ * What an order pays at settlement, raw USDC: its full quantity when the settlement price lies
+ * in `(lower, higher]`, else 0. The mirror of `strike_exposure::settled_order_payout`, which
+ * rounds the settlement price up to the market's tick grid (`range_codec::limit_tick`) before
+ * comparing it with the order's ticks, so a price inside a tick counts as that tick's upper edge.
+ * Pass `read.settlement`'s `settlementPriceRaw` and `tickSizeRaw`, and the config's
+ * `units.positionLotSize` when it isn't the default.
+ */
+export function settledPayout(
+	orderId: bigint,
+	settlementPriceRaw: bigint,
+	tickSizeRaw: bigint,
+	lotSize: bigint = POSITION_LOT_SIZE,
+): bigint {
+	if (tickSizeRaw <= 0n) throw new PredictInputError('tickSizeRaw must be positive');
+	const { lowerTick, higherTick, quantity } = decodeOrderRange(orderId, lotSize);
+	const limit = (settlementPriceRaw + tickSizeRaw - 1n) / tickSizeRaw;
+	const inRange = lowerTick < limit && (higherTick === POS_INF_TICK || limit <= higherTick);
+	return inRange ? quantity : 0n;
+}
+
 /** The strikes an {@link OrderRange} prices against, in USD, with `null` for each infinite
  * side — the shape {@link boundaryProbabilities} takes. `tickSize` is the market's raw tick
  * size (`ActiveMarket.tickSize` in USD, or the raw value from the deployment). */