@mysten/deepbook-v3 2.9.1 → 2.10.0

package/src/contracts/deepbook_predict/order_events.ts

@@ -55,8 +55,9 @@ export const OrderMinted = new MoveStruct({
 		/** Separate inventory-impact charge escrowed for live-close rebates. */
 		inventory_impact_charge: U64,
 		/**
-		 * Builder credited for `builder_fee`; `none` when no builder fee was paid
-		 * (attribution follows the fee — applied once, in the emit helper).
+		 * Builder code the order named, credited with `builder_fee`; `none` when the order
+		 * named none. Recorded even at a zero fee, so attribution covers apps that charge
+		 * nothing.
 		 */
 		builder_code_id: bcs.option(bcs.Address),
 		/** Referrer recorded on the minting account, independent of the fee paid. */
@@ -99,8 +100,9 @@ export const LiveOrderRedeemed = new MoveStruct({
 		/** Separate inventory-impact rebate paid from its isolated escrow. */
 		inventory_impact_rebate: U64,
 		/**
-		 * Builder credited for `builder_fee`; `none` when no builder fee was paid
-		 * (attribution follows the fee — applied once, in the emit helper).
+		 * Builder code the order named, credited with `builder_fee`; `none` when the order
+		 * named none. Recorded even at a zero fee, so attribution covers apps that charge
+		 * nothing.
 		 */
 		builder_code_id: bcs.option(bcs.Address),
 		onchain_timestamp_ms: U64,

package/src/contracts/deepbook_predict/predict_account.ts

@@ -6,9 +6,10 @@
  * Predict's per-account state, stored as an app-data slot on a shared `Account`
  * (the `account` package).
  *
- * This is Predict's account-local state: open positions and sticky builder-code
- * attribution. USDC/PLP custody lives in `Account`. The `PredictApp` witness
- * namespaces this slot, so only Predict writes it.
+ * This is Predict's account-local state: open positions and a sticky builder code.
+ * The sticky code no longer affects fees: a trade names its builder and fee itself
+ * (`expiry_market::admit_mint_with_builder`). USDC/PLP custody lives in `Account`.
+ * The `PredictApp` witness namespaces this slot, so only Predict writes it.
  *
  * Position mutations are package-internal. Builder-code configuration accepts an
  * account `Auth`; the account package decides which owner or authorized
@@ -135,8 +136,10 @@ export interface SetBuilderCodeOptions {
 	};
 }
 /**
- * Set sticky builder-code attribution for future trades using valid account auth.
- * Owner auth and authorized-app auth both satisfy the account borrow boundary.
+ * Set the sticky builder code using valid account auth. Owner auth and
+ * authorized-app auth both satisfy the account borrow boundary. Kept for
+ * compatibility: it no longer affects fees, since a trade names its builder and
+ * fee itself.
  */
 export function setBuilderCode(options: SetBuilderCodeOptions) {
 	const packageAddress =
@@ -164,7 +167,10 @@ export interface UnsetBuilderCodeOptions {
 		predictPackageId?: string;
 	};
 }
-/** Clear sticky builder-code attribution using valid owner or authorized-app auth. */
+/**
+ * Clear the sticky builder code using valid owner or authorized-app auth. Kept for
+ * compatibility: the code no longer affects fees.
+ */
 export function unsetBuilderCode(options: UnsetBuilderCodeOptions) {
 	const packageAddress =
 		options.package ?? options.config?.predictPackageId ?? '@local-pkg/deepbook_predict';

package/src/contracts/deepbook_predict/protocol_config.ts

@@ -161,6 +161,10 @@ export const OrderFlowKey = new MoveTuple({
 	name: `${$moduleName}::OrderFlowKey<phantom W>`,
 	fields: [bcs.bool()],
 });
+export const BuilderFeeCapKey = new MoveTuple({
+	name: `${$moduleName}::BuilderFeeCapKey`,
+	fields: [bcs.bool()],
+});
 export interface IdArguments {
 	config?: RawTransactionArgument<string>;
 }
@@ -366,6 +370,43 @@ export function feeIncentiveSubsidyRate(options: FeeIncentiveSubsidyRateOptions)
 			),
 		});
 }
+export interface BuilderFeeCapArguments {
+	config?: RawTransactionArgument<string>;
+}
+export interface BuilderFeeCapOptions {
+	package?: string;
+	arguments?: BuilderFeeCapArguments;
+	config?: {
+		protocolConfig: ConfigValue;
+		predictPackageId?: string;
+	};
+}
+/**
+ * Return the builder fee cap: the most a trade's builder fee can charge per
+ * contract, in FLOAT_SCALING of a contract's $1 payout. Admission charges a
+ * trade's named fee capped at this value. `public` for SDK and devInspect reads,
+ * so an app can show the fee a trade will actually pay.
+ */
+export function builderFeeCap(options: BuilderFeeCapOptions) {
+	const packageAddress =
+		options.package ?? options.config?.predictPackageId ?? '@local-pkg/deepbook_predict';
+	const argumentsTypes = [null] satisfies (string | null)[];
+	const parameterNames = ['config'];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'protocol_config',
+			function: 'builder_fee_cap',
+			arguments: normalizeMoveArguments(
+				{
+					...options.arguments,
+					config: options.arguments?.config ?? options.config?.protocolConfig,
+				},
+				argumentsTypes,
+				parameterNames,
+			),
+		});
+}
 export interface FeeIncentiveLiveTargetRateArguments {
 	config?: RawTransactionArgument<string>;
 }
@@ -1704,6 +1745,50 @@ export function setFeeIncentiveSubsidyRate(options: SetFeeIncentiveSubsidyRateOp
 			),
 		});
 }
+export interface SetBuilderFeeCapArguments {
+	config?: RawTransactionArgument<string>;
+	AdminCap: RawTransactionArgument<string>;
+	cap: RawTransactionArgument<number | bigint>;
+}
+export interface SetBuilderFeeCapOptions {
+	package?: string;
+	arguments: SetBuilderFeeCapArguments;
+	config?: {
+		protocolConfig: ConfigValue;
+		predictPackageId?: string;
+	};
+}
+/**
+ * Set the builder fee cap: the most a trade's builder fee can charge per contract,
+ * in FLOAT_SCALING of a contract's $1 payout, from `0` up to the whole payout. A
+ * trade that names a higher fee pays the cap. Read when an order is admitted, so
+ * the new cap applies to the next order on every market, and an order already
+ * queued keeps the fee it was admitted with. `0` stops builder fees.
+ *
+ * Not gated on the valuation flag, matching `set_fee_incentive_subsidy_rate`:
+ * nothing in the flush reads the cap, and a builder fee leaves with the trader's
+ * own payment, never market cash.
+ */
+export function setBuilderFeeCap(options: SetBuilderFeeCapOptions) {
+	const packageAddress =
+		options.package ?? options.config?.predictPackageId ?? '@local-pkg/deepbook_predict';
+	const argumentsTypes = [null, null, 'u64', '0x2::clock::Clock'] satisfies (string | null)[];
+	const parameterNames = ['config', 'AdminCap', 'cap'];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'protocol_config',
+			function: 'set_builder_fee_cap',
+			arguments: normalizeMoveArguments(
+				{
+					...options.arguments,
+					config: options.arguments?.config ?? options.config?.protocolConfig,
+				},
+				argumentsTypes,
+				parameterNames,
+			),
+		});
+}
 export interface SetFeeIncentiveLiveTargetRateArguments {
 	config?: RawTransactionArgument<string>;
 	AdminCap: RawTransactionArgument<string>;

package/src/contracts/deepbook_predict_orders/deps/deepbook_predict/expiry_market.ts

@@ -23,6 +23,12 @@
  * the settled payout need only the receipt. The queue itself, its escrow, its
  * policy, and its events live in the companion.
  *
+ * A trade that pays a builder names its code and fee per contract
+ * (`builder_code::BuilderFee`). `admit_mint_with_builder` and
+ * `admit_sell_with_builder` cap the fee at `protocol_config::builder_fee_cap` and
+ * record the code and the capped fee in the receipt, and the fill charges what the
+ * receipt records. The plain admissions name no builder and charge none.
+ *
  * Mainnet USDC is a regulated coin: Sui aborts a transaction that sends it to an
  * address on its deny list, or to anyone while it is globally paused. So the fill,
  * the fee routing, and the settled payout read `sui::deny_list` first and never
@@ -61,10 +67,18 @@ export const OrderReceipt = new MoveStruct({
 		higher_tick: U64,
 		/** The exact mint quantity, or the sell's close quantity. */
 		quantity: U64,
+		/**
+		 * A mint's premium cap. A sell never uses it, so a sell admitted with a builder
+		 * keeps its capped builder fee per contract here.
+		 */
 		max_premium: U64,
 		min_quantity: U64,
 		max_probability: U64,
 		min_probability: U64,
+		/**
+		 * A sell's proceeds floor. A mint never uses it, so a mint admitted with a builder
+		 * keeps its capped builder fee per contract here.
+		 */
 		min_proceeds: U64,
 		/** Earliest Pyth generation time the order may price at. */
 		tau_ms: U64,

package/src/contracts/deepbook_predict_orders/order_flow.ts

@@ -11,6 +11,10 @@
  * goes through a package-only function here, so no caller outside this package can
  * obtain the witness or reach Predict with it. `release` and `try_pay_settled`
  * need no authority and are called directly.
+ *
+ * Admission takes an optional `BuilderFee` and passes it to Predict's
+ * `_with_builder` admission, which records the code and the capped fee in the
+ * receipt for the fill. An order that names none pays no builder fee.
  */
 
 import { MoveTuple } from '../utils/index.js';