@mysten/deepbook-v3 2.6.4 → 2.8.0

package/src/contracts/deepbook_predict/order_events.ts

@@ -7,7 +7,9 @@
  *
  * Events carry transition identities and deltas rather than account or market
  * balances. Partial closes link an old order ID to its replacement; the position
- * root remains constant across that chain.
+ * root remains constant across that chain. Queued fills emit `OrderMinted` and
+ * `LiveOrderRedeemed` from inside Predict's order-flow fills; the queue's own
+ * events belong to the order-flow companion package.
  */
 
 import { MoveStruct } from '../utils/index.js';

package/src/contracts/deepbook_predict/plp.ts

@@ -77,10 +77,8 @@ export const PoolValuation = new MoveStruct({
 		started_at_ms: U64,
 		/**
 		 * Drain budgets committed at start (the cap owner's choice), bounding how many
-		 * requests each queue processes at finish. Committing them here — not at finish —
-		 * is what lets `finish_flush` run permissionless: a stranger may complete a flush
-		 * but only ever drains at these budgets, so completion can help LPs, never starve
-		 * them by finishing with a zero budget.
+		 * requests each queue processes at finish. `finish_flush` takes no budget, so the
+		 * flush operator who completes it drains at exactly these.
 		 */
 		supply_budget: bcs.option(U64),
 		withdraw_budget: bcs.option(U64),
@@ -114,7 +112,10 @@ export const PoolVault = new MoveStruct({
 		 * withdraws this balance.
 		 */
 		protocol_reserve_balance: balance.Balance,
-		/** Sponsor-funded USDC reserved for taker fee sponsorship, excluded from PLP NAV. */
+		/**
+		 * Sponsor-funded USDC reserved for taker fee sponsorship, excluded from PLP NAV.
+		 * Admin may reclaim it through `withdraw_fee_incentives`.
+		 */
 		fee_incentive_reserve: balance.Balance,
 		/** PLP share issuance plus queued supply/withdraw escrow. */
 		lp: lp_book.LpBook,
@@ -595,8 +596,8 @@ export interface SnapshotExpiryPricerOptions {
  * a payout tree — so all markets fit one PTB regardless of book size.
  *
  * The oracle feeding this stage must have been written in an EARLIER transaction:
- * `pricing::resolve_live_pricer` refuses a read stamped with the current
- * transaction digest (RP-24), so a keeper cannot refresh and snapshot in one PTB.
+ * `pricing::resolve_live` refuses a read stamped with the current transaction
+ * digest (RP-24), so a keeper cannot refresh and snapshot in one PTB.
  *
  * A market already settled at snapshot time is recorded with no pricer, gets no
  * stamp (settled flows never touch live NAV), and contributes 0. An
@@ -786,6 +787,11 @@ export interface FinishFlushOptions {
  * Because queueing is permissionless and a refunded request returns its escrow in
  * the same transaction, an operator should bound both budgets in production rather
  * than rely on queue length staying small — see RP-12.
+ *
+ * Only an allowlisted flush operator may call it
+ * (`protocol_config::ENotFlushOperator`). Fills move idle cash, so restricting who
+ * completes a flush keeps idle predictable for the keeper that funds markets for
+ * queued orders.
  */
 export function finishFlush(options: FinishFlushOptions) {
 	const packageAddress =
@@ -828,7 +834,10 @@ export interface RebalanceExpiryCashOptions {
  * Permissionless and standalone: anyone may call it at any cadence. Handles all
  * three per-market cases — initial funding of a freshly registered (unfunded)
  * market, ongoing live rebalance/surplus-sweep toward target, and the
- * settled-market sweep (deactivate, return all free cash, materialize profit).
+ * settled-market sweep (deactivate, return all free cash, materialize profit). The
+ * live target covers the market's queued orders' cash need (the waiting cash need
+ * in `expiry_market::order_flow_state`), so the keeper calls this after each
+ * enqueue to fund those orders' fills, and a sweep never takes that cash back.
  * Call `expiry_market::try_settle` first in the same PTB when settlement may be
  * due. An expired unsettled market is a no-op until that transition succeeds. Mint
  * asserts backing but never pulls pool cash, so this is what makes a market
@@ -878,7 +887,9 @@ export interface SponsorFeeIncentivesOptions {
 /**
  * Sponsor taker fee incentives with USDC. Anyone may contribute; the payment joins
  * a pool-level reserve that is excluded from PLP NAV and later allocated to expiry
- * markets by the normal rebalance flow.
+ * markets by the normal rebalance flow. A contribution is not earmarked to its
+ * sponsor: admin can withdraw any of the reserve through
+ * `withdraw_fee_incentives`.
  */
 export function sponsorFeeIncentives(options: SponsorFeeIncentivesOptions) {
 	const packageAddress =
@@ -901,6 +912,136 @@ export function sponsorFeeIncentives(options: SponsorFeeIncentivesOptions) {
 			),
 		});
 }
+export interface WithdrawFeeIncentivesArguments {
+	vault?: RawTransactionArgument<string>;
+	AdminCap: RawTransactionArgument<string>;
+	config?: RawTransactionArgument<string>;
+	amount: RawTransactionArgument<number | bigint>;
+}
+export interface WithdrawFeeIncentivesOptions {
+	package?: string;
+	arguments: WithdrawFeeIncentivesArguments;
+	config?: {
+		poolVault: ConfigValue;
+		protocolConfig: ConfigValue;
+		predictPackageId?: string;
+	};
+}
+/**
+ * Withdraw `amount` USDC of sponsor-funded fee incentives from the pool-level
+ * reserve, for sponsorship the protocol no longer wants to spend. Admin-only.
+ *
+ * Reaches the reserve only. Incentives already allocated to a live market stay in
+ * that market's `fee_incentive_balance` and return to the reserve when its
+ * settled-market sweep runs, after which they can be withdrawn here; setting
+ * `protocol_config::set_fee_incentive_subsidy_rate` to zero stops them being spent
+ * in the meantime. The per-expiry lifetime allocation counters are not credited
+ * back: they bound what a market may ever receive, and a withdrawal does not
+ * change what a market already received.
+ *
+ * Not gated on the valuation flag, in either stage of a flush: the reserve is
+ * excluded from PLP NAV and no flush figure, frozen or live, reads it, so a
+ * withdrawal cannot reach the mark.
+ */
+export function withdrawFeeIncentives(options: WithdrawFeeIncentivesOptions) {
+	const packageAddress =
+		options.package ?? options.config?.predictPackageId ?? '@local-pkg/deepbook_predict';
+	const argumentsTypes = [null, null, null, 'u64'] satisfies (string | null)[];
+	const parameterNames = ['vault', 'AdminCap', 'config', 'amount'];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'plp',
+			function: 'withdraw_fee_incentives',
+			arguments: normalizeMoveArguments(
+				{
+					...options.arguments,
+					vault: options.arguments?.vault ?? options.config?.poolVault,
+					config: options.arguments?.config ?? options.config?.protocolConfig,
+				},
+				argumentsTypes,
+				parameterNames,
+			),
+		});
+}
+export interface AddUsdcToPlpArguments {
+	vault?: RawTransactionArgument<string>;
+	config?: RawTransactionArgument<string>;
+	payment: RawTransactionArgument<string>;
+}
+export interface AddUsdcToPlpOptions {
+	package?: string;
+	arguments: AddUsdcToPlpArguments;
+	config?: {
+		poolVault: ConfigValue;
+		protocolConfig: ConfigValue;
+		predictPackageId?: string;
+	};
+}
+/**
+ * Add USDC straight to pool idle liquidity without minting any PLP. Anyone may
+ * call it; the payment is an outright gift to the existing share base, so the
+ * caller receives nothing back and no share of it is recoverable.
+ *
+ * This is the incentive/top-up path: because no shares are issued, the whole
+ * `payment` lands inside the value the next flush's mark divides by an unchanged
+ * `total_supply`, which raises NAV per PLP for every current holder. It
+ * deliberately does not touch the profit basis — the basis tracks cash sent to and
+ * returned from expiries, so an outside contribution is neither a debit nor a
+ * credit, and the protocol reserve therefore takes no cut of it (`pool_value`
+ * leaves `exclusion` unchanged while `gross_pool_value` grows). Sending the same
+ * USDC through `request_supply` instead mints shares against it, so only the
+ * supply fee would reach existing holders — zero as shipped.
+ *
+ * Three gates, each closing a state this entrypoint would otherwise manufacture:
+ *
+ * - **Bootstrapped pool.** At `total_supply == 0` there is no share base to
+ *   credit; the USDC would only inflate the genesis lock's non-withdrawable stake.
+ * - **Contribution price ceiling.** Pool cash after the contribution — idle plus
+ *   the net cash deployed into active expiries — may price at most
+ *   `contribution_price_ceiling_factor` USDC per PLP, a tenth of the band a flush
+ *   mark needs to be fillable. Above the band every supply and withdraw head is
+ *   refunded (RP-2) and `total_supply` grows only through a supply fill, so
+ *   nothing brings the price back down — a terminal state that an unbounded
+ *   contribution against a small share base would otherwise reach for the price of
+ *   the contribution. The ceiling sits well inside the band because later fills
+ *   only push the price up (rounding and retained fees stay in the pool), so a
+ *   pool left exactly at the band would leave it on the next uneven or fee-charged
+ *   fill. The test is one-sided because a contribution can only move the price up.
+ *   It reads pool cash rather than pool NAV — NAV needs a flush — and counts
+ *   deployed cash because the mark does: `rebalance_expiry_cash` is
+ *   permissionless, so an idle-only test could be emptied into a market and passed
+ *   again. Cash is exactly the protocol-controlled share: the guard forbids this
+ *   entrypoint from _manufacturing_ the degenerate ratio and leaves market-driven
+ *   NAV moves (trader premiums and P&L) to RP-1/RP-2, which own them.
+ * - **No flush in flight.** The seal freezes idle mid-flush, so an ungated
+ *   contribution would land on one side or the other of that capture depending
+ *   only on when the contributor's transaction executed — either paying that
+ *   flush's queued withdrawals or not. `sponsor_fee_incentives` takes the same
+ *   gate. `rebalance_expiry_cash` may run mid-window because it only moves cash
+ *   between two figures the seal already froze; new value is different.
+ */
+export function addUsdcToPlp(options: AddUsdcToPlpOptions) {
+	const packageAddress =
+		options.package ?? options.config?.predictPackageId ?? '@local-pkg/deepbook_predict';
+	const argumentsTypes = [null, null, null] satisfies (string | null)[];
+	const parameterNames = ['vault', 'config', 'payment'];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'plp',
+			function: 'add_usdc_to_plp',
+			arguments: normalizeMoveArguments(
+				{
+					...options.arguments,
+					vault: options.arguments?.vault ?? options.config?.poolVault,
+					config: options.arguments?.config ?? options.config?.protocolConfig,
+				},
+				argumentsTypes,
+				parameterNames,
+			),
+		});
+}
 export interface LockCapitalArguments {
 	vault?: RawTransactionArgument<string>;
 	config?: RawTransactionArgument<string>;

package/src/contracts/deepbook_predict/pricing.ts

@@ -11,16 +11,52 @@
  * an exact source-timestamp spot from Propbook's bounded recent history. The live
  * forward comes from one of two admin-selected sources
  * (`PricingConfig.use_pyth_spot_for_forward`): a fresh positive Pyth spot carrying
- * the Block Scholes basis, or the Block Scholes forward directly. Exact-history
- * reads do not apply live freshness policy.
+ * the Block Scholes basis, or the Block Scholes forward directly. A load falls
+ * back to the Block Scholes forward when the selected Pyth spot is stale or
+ * unavailable; valuation prices on that fallback, while every live trade (mints,
+ * mint quotes, and live redeems) refuses it through `assert_pyth_spot_fresh`.
+ * Exact-history reads do not apply live freshness policy.
+ *
+ * Delayed execution splits that read in two. `load_vol` validates the same live
+ * inputs when an order is admitted and returns the raw Block Scholes basis and SVI
+ * its receipt stores; `pricer_at` later rebuilds a `Pricer` from them at the
+ * order's committed Pyth tick. The `try_*` reads price exactly as `up_price` and
+ * `range_price` do, and return `none` where those abort, so an order-flow fill
+ * never aborts on a surface.
  */
 
 import { MoveStruct, normalizeMoveArguments } from '../utils/index.js';
-import { U128, U64 } from '../../bcs/integers.js';
 import { bcs } from '@mysten/sui/bcs';
+import { U64, U128 } from '../../bcs/integers.js';
 import { type Transaction, type TransactionArgument } from '@mysten/sui/transactions';
 import * as i64 from './deps/fixed_math/i64.js';
 const $moduleName = '@local-pkg/deepbook_predict::pricing';
+export const VolSnapshot = new MoveStruct({
+	name: `${$moduleName}::VolSnapshot`,
+	fields: {
+		/**
+		 * Canonical Propbook Pyth source for the market's underlying; commit finds this
+		 * feed in each Lazer update.
+		 */
+		pyth_source_id: bcs.u32(),
+		/** The matched Block Scholes spot and forward, narrowed to Predict's width. */
+		bs_spot: U64,
+		bs_forward: U64,
+		/** Raw SVI parameters before roll-down, at 1e9. */
+		svi_a: i64.I64,
+		svi_b: U64,
+		svi_rho: i64.I64,
+		svi_m: i64.I64,
+		svi_sigma: U64,
+		/**
+		 * Provider source timestamps of the three reads. The SVI one is also the roll-down
+		 * anchor.
+		 */
+		bs_spot_source_timestamp_ms: U64,
+		bs_forward_source_timestamp_ms: U64,
+		svi_source_timestamp_ms: U64,
+	},
+});
 export const PricingSVI = new MoveStruct({
 	name: `${$moduleName}::PricingSVI`,
 	fields: {
@@ -56,10 +92,13 @@ export const Pricer = new MoveStruct({
 		/**
 		 * Timestamps of the oracle observations this snapshot validated, as trade events
 		 * report them — each observation's own economic clock. Pyth carries its source
-		 * timestamp (`0` only when no usable normalized observation exists); Block Scholes
-		 * spot and forward carry the provider `value_timestamp`, and SVI carries the
-		 * provider `svi_timestamp`. Those timestamps are the clocks freshness gates and
-		 * SVI roll-down use.
+		 * timestamp (`0` only when no usable normalized observation exists; a `pricer_at`
+		 * Pricer carries the committed update's generation time); Block Scholes spot and
+		 * forward carry the provider `value_timestamp`, and SVI carries the provider
+		 * `svi_timestamp`. Those timestamps are the clocks freshness gates and SVI
+		 * roll-down use. The Pyth timestamp, including its `0` sentinel, is also what
+		 * `assert_pyth_spot_fresh` gates live trades on, so it must stay the value the
+		 * load's forward selection read.
 		 */
 		pyth_spot_source_timestamp_ms: U64,
 		block_scholes_spot_source_timestamp_ms: U64,

package/src/contracts/deepbook_predict/pricing_config.ts

@@ -24,7 +24,9 @@ export const PricingConfig = new MoveStruct({
 		use_pyth_spot_for_forward: bcs.bool(),
 		/**
 		 * Fixed wall-clock maximum age for Pyth spot; it does not vary with time to
-		 * expiry.
+		 * expiry. Past it, while `use_pyth_spot_for_forward` is set, a live load falls
+		 * back to the Block Scholes forward, which valuation prices on and every live
+		 * trade (mint, mint quote, live redeem) refuses.
 		 */
 		pyth_spot_freshness_ms: U64,
 		/**