@mysten/deepbook-v3 2.0.1 → 2.1.4

package/src/predict/reads/markets.ts

@@ -0,0 +1,222 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { Transaction } from '@mysten/sui/transactions';
+import { type GeneratedConfig } from '../config/generated.js';
+import { type UnderlyingConfig } from '../config/index.js';
+import { PredictMoveError } from '../errors.js';
+import { POS_INF_TICK } from '../ticks.js';
+import { loadLivePricer, type MarketFeeds } from '../tx/trade.js';
+import * as expiryMarket from '../../contracts/deepbook_predict/expiry_market.js';
+import * as plp from '../../contracts/deepbook_predict/plp.js';
+import * as pricing from '../../contracts/deepbook_predict/pricing.js';
+import * as rangeCodec from '../../contracts/deepbook_predict/range_codec.js';
+import * as registry from '../../contracts/deepbook_predict/registry.js';
+import { inspectReturns, type ReadClient } from './inspect.js';
+import { parseOptionalId, parseOptionalU64, parseU64LE, parseVectorOfIds } from './parse.js';
+
+// On-chain ids of the pool's active (live, not-yet-settled) expiry markets.
+// `plp::active_expiry_markets(vault)` — see packages/predict/sources/plp/plp.move:179.
+export async function activeMarketIds(
+	client: ReadClient,
+	config: GeneratedConfig,
+): Promise<string[]> {
+	const tx = new Transaction();
+	tx.add(plp.activeExpiryMarkets({ config }));
+	const [cmd0] = await inspectReturns(client, tx);
+	return parseVectorOfIds(cmd0[0]);
+}
+
+// The expiry market id for one underlying at one expiry, or null if none exists.
+// `registry::expiry_market_id(registry, propbook_underlying_id: u32, expiry: u64):
+// Option<ID>` — see packages/predict/sources/registry/registry.move:53.
+export async function expiryMarketId(
+	client: ReadClient,
+	config: GeneratedConfig,
+	underlying: UnderlyingConfig,
+	expiryMs: bigint,
+): Promise<string | null> {
+	const tx = new Transaction();
+	tx.add(
+		registry.expiryMarketId({
+			config,
+			arguments: { propbookUnderlyingId: underlying.propbookUnderlyingId, expiry: expiryMs },
+		}),
+	);
+	const [cmd0] = await inspectReturns(client, tx);
+	return parseOptionalId(cmd0[0]);
+}
+
+export interface MarketState {
+	expiryMs: bigint;
+	tickSizeRaw: bigint;
+	/**
+	 * The COARSER raw-price step new finite mint boundaries must align to
+	 * (`expiry_market::admission_tick_size`). A numeric strike must be a whole
+	 * multiple of this — the fine `tickSizeRaw` grid alone is not sufficient — or
+	 * the chain aborts `EInvalidAdmissionTick`. The market's reference tick is the
+	 * one finite boundary allowed to bypass it.
+	 */
+	admissionTickSizeRaw: bigint;
+	mintPaused: boolean;
+	/**
+	 * The reference fine-grid tick (Polymarket-style anchor strike: derived
+	 * on-chain from the exact previous-window oracle observation), or null while
+	 * the keeper has not seeded it. Reference PRICE raw = tick * tickSizeRaw.
+	 */
+	referenceTickRaw: bigint | null;
+}
+
+// The per-market state getters, in fixed order. `expiry_market::{expiry,
+// tick_size, mint_paused, reference_tick}` — see
+// packages/predict/sources/expiry_market.move:{101,177,259,187}. reference_tick
+// returns Option (no abort risk). settlement is read separately via
+// `settlementPrice` (its own non-batched getter below).
+const STATE_FNS = [
+	expiryMarket.expiry,
+	expiryMarket.tickSize,
+	expiryMarket.admissionTickSize,
+	expiryMarket.mintPaused,
+	expiryMarket.referenceTick,
+] as const;
+
+function parseStateAt(cmds: Uint8Array[][], base: number): MarketState {
+	return {
+		expiryMs: parseU64LE(cmds[base][0]),
+		tickSizeRaw: parseU64LE(cmds[base + 1][0]),
+		admissionTickSizeRaw: parseU64LE(cmds[base + 2][0]),
+		mintPaused: (cmds[base + 3][0][0] ?? 0) !== 0, // BCS bool: 1 byte
+		referenceTickRaw: parseOptionalU64(cmds[base + 4][0]),
+	};
+}
+
+export async function marketState(
+	client: ReadClient,
+	config: GeneratedConfig,
+	marketId: string,
+): Promise<MarketState> {
+	const [state] = await marketStates(client, config, [marketId]);
+	return state;
+}
+
+// Batched marketState for N markets in ONE PTB (STATE_FNS.length commands per
+// market, same order). Returns states aligned with `marketIds`.
+export async function marketStates(
+	client: ReadClient,
+	config: GeneratedConfig,
+	marketIds: readonly string[],
+): Promise<MarketState[]> {
+	if (marketIds.length === 0) return [];
+	const tx = new Transaction();
+	for (const id of marketIds) {
+		for (const fn of STATE_FNS) {
+			tx.add(fn({ config, arguments: { market: id } }));
+		}
+	}
+	const cmds = await inspectReturns(client, tx);
+	return marketIds.map((_, i) => parseStateAt(cmds, STATE_FNS.length * i));
+}
+
+// Anonymous both-sides pricing for one strike: the chain's own probability for
+// (strike, +inf] and (-inf, strike]. Deployed `pricing::range_price` takes typed
+// `range_codec::Strike`s (NOT raw u64) — each boundary is built via
+// `range_codec::strike_from_tick(tick, tick_size)`, which maps tick 0 → -inf,
+// POS_INF_TICK → +inf, and any finite tick → tick*tick_size. `range_price` is a
+// public fun on the deployed package. Both sides read the SAME pricer in one PTB, so
+// `down` is the chain's number, not 1 − up.
+export async function rangePrices(
+	client: ReadClient,
+	config: GeneratedConfig,
+	marketId: string,
+	feeds: MarketFeeds,
+	strikeRaw: bigint,
+	tickSizeRaw: bigint,
+): Promise<{ upRaw: bigint; downRaw: bigint }> {
+	const tx = new Transaction();
+	const pricer = tx.add(loadLivePricer(config, { expiryMarketId: marketId, ...feeds }));
+	// strikeRaw is a whole tick multiple (the caller validates divisibility), so the
+	// finite boundary is `strike_from_tick(strikeRaw / tickSize, tickSize)`.
+	const strikeTick = strikeRaw / tickSizeRaw;
+	const mkStrike = (tick: bigint) =>
+		tx.add(rangeCodec.strikeFromTick({ config, arguments: { tick, tickSize: tickSizeRaw } }));
+	const strike = mkStrike(strikeTick);
+	const posInf = mkStrike(POS_INF_TICK);
+	const negInf = mkStrike(0n);
+	// UP: (strike, +inf], then DOWN: (-inf, strike] — the last two commands.
+	tx.add(pricing.rangePrice({ config, arguments: { pricer, lower: strike, higher: posInf } }));
+	tx.add(pricing.rangePrice({ config, arguments: { pricer, lower: negInf, higher: strike } }));
+	const cmds = await inspectReturns(client, tx);
+	return {
+		upRaw: parseU64LE(cmds[cmds.length - 2][0]),
+		downRaw: parseU64LE(cmds[cmds.length - 1][0]),
+	};
+}
+
+// Fresh single read of the reference tick — used by mint-at-reference, which
+// must not trust a cached state (the reference is unset early in a window
+// until the keeper seeds it).
+export async function referenceTick(
+	client: ReadClient,
+	config: GeneratedConfig,
+	marketId: string,
+): Promise<bigint | null> {
+	const tx = new Transaction();
+	tx.add(expiryMarket.referenceTick({ config, arguments: { market: marketId } }));
+	const [cmd0] = await inspectReturns(client, tx);
+	return parseOptionalU64(cmd0[0]);
+}
+
+// The recorded settlement price, or null while the market is unsettled.
+//
+// On the deployed package `expiry_market::settlement_price` is public and
+// `destroy_some`s the stored Option — callable here only because simulate runs with
+// checksEnabled:false, and it aborts in std::option (EOPTION_NOT_SET) when the
+// market has not settled; we map exactly that abort (and the public
+// EMarketNotSettled variant, should a future package guard it directly) to null.
+// (A non-aborting `try_settlement_price` also exists on-chain if this ever wants to
+// drop the abort-catch.)
+export async function settlementPrice(
+	client: ReadClient,
+	config: GeneratedConfig,
+	marketId: string,
+): Promise<bigint | null> {
+	const tx = new Transaction();
+	tx.add(expiryMarket.settlementPrice({ config, arguments: { market: marketId } }));
+	try {
+		const [cmd0] = await inspectReturns(client, tx);
+		return parseU64LE(cmd0[0]);
+	} catch (e) {
+		if (
+			e instanceof PredictMoveError &&
+			(e.module === 'option' ||
+				(e.module === 'expiry_market' && e.abortName === 'EMarketNotSettled'))
+		) {
+			return null;
+		}
+		throw e;
+	}
+}
+
+// A market's current NAV mark (the per-expiry recoverable value the flush prices
+// against). Loads a fresh live pricer, then reads `current_nav(market, &pricer)` —
+// see packages/predict/sources/expiry_market.move:236. `Pricer` has copy+drop, so
+// the unconsumed borrow is fine in a read-only inspect.
+export async function currentNav(
+	client: ReadClient,
+	config: GeneratedConfig,
+	marketId: string,
+	underlying: UnderlyingConfig,
+): Promise<bigint> {
+	const tx = new Transaction();
+	const pricer = tx.add(
+		loadLivePricer(config, {
+			expiryMarketId: marketId,
+			pythFeed: underlying.pythFeed,
+			blockScholesValueStore: underlying.blockScholesValueStore,
+			blockScholesSviStore: underlying.blockScholesSviStore,
+		}),
+	);
+	tx.add(expiryMarket.currentNav({ config, arguments: { market: marketId, pricer } }));
+	const cmds = await inspectReturns(client, tx);
+	// current_nav is the last command; load_live_pricer precedes it.
+	return parseU64LE(cmds[cmds.length - 1][0]);
+}

package/src/predict/reads/parse.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+// BCS decoders for the return values of on-chain reads, built on the
+// `@mysten/sui/bcs` codec so the read layer decodes exactly the on-chain Move ABI
+// (u64 LE, vector<ID>, Option) with no hand-rolled byte walking. Round-tripped
+// against `@mysten/sui/bcs` in tests/reads.test.ts.
+
+import { bcs } from '@mysten/sui/bcs';
+
+// BCS u64 → bigint. `bcs.u64()` parses to a decimal string.
+export function parseU64LE(bytes: Uint8Array): bigint {
+	return BigInt(bcs.u64().parse(bytes));
+}
+
+// BCS vector<ID> / vector<address> → full-length 0x lowercase ids
+// (`bcs.Address` already yields normalized ids).
+export function parseVectorOfIds(bytes: Uint8Array): string[] {
+	return bcs.vector(bcs.Address).parse(bytes);
+}
+
+// BCS Option<u64>: None → null, Some(x) → x.
+export function parseOptionalU64(bytes: Uint8Array): bigint | null {
+	const v = bcs.option(bcs.u64()).parse(bytes);
+	return v == null ? null : BigInt(v);
+}
+
+// BCS Option<ID>: None → null, Some(id) → normalized 0x id.
+export function parseOptionalId(bytes: Uint8Array): string | null {
+	return bcs.option(bcs.Address).parse(bytes);
+}

package/src/predict/reads/pool.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { Transaction } from '@mysten/sui/transactions';
+import { type GeneratedConfig } from '../config/generated.js';
+import * as plp from '../../contracts/deepbook_predict/plp.js';
+import { inspectReturns, type ReadClient } from './inspect.js';
+import { parseU64LE } from './parse.js';
+
+export interface PoolStats {
+	plpTotalSupply: bigint;
+	idleBalance: bigint;
+	supplyRequestsPending: bigint;
+	withdrawRequestsPending: bigint;
+}
+
+// The pool's four u64 vault stats batched into one PTB (command order fixed below).
+// `plp::{plp_total_supply, idle_balance, supply_requests_pending,
+// withdraw_requests_pending}(vault)` — see
+// packages/predict/sources/plp/plp.move:{164,149,169,174}.
+export async function poolStats(client: ReadClient, config: GeneratedConfig): Promise<PoolStats> {
+	const tx = new Transaction();
+	for (const fn of [
+		plp.plpTotalSupply,
+		plp.idleBalance,
+		plp.supplyRequestsPending,
+		plp.withdrawRequestsPending,
+	]) {
+		tx.add(fn({ config }));
+	}
+	const cmds = await inspectReturns(client, tx);
+	return {
+		plpTotalSupply: parseU64LE(cmds[0][0]),
+		idleBalance: parseU64LE(cmds[1][0]),
+		supplyRequestsPending: parseU64LE(cmds[2][0]),
+		withdrawRequestsPending: parseU64LE(cmds[3][0]),
+	};
+}

package/src/predict/reads/positions.ts

@@ -0,0 +1,144 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { bcs } from '@mysten/sui/bcs';
+import type { ClientWithCoreApi } from '@mysten/sui/client';
+import { deriveDynamicFieldID, normalizeSuiAddress } from '@mysten/sui/utils';
+import { type GeneratedConfig } from '../config/generated.js';
+import { deriveAccountWrapperIdFrom } from '../tx/common.js';
+import { AccountWrapper } from '../../account.js';
+import { PositionKey, PredictData } from '../../contracts/deepbook_predict/predict_account.js';
+
+// ============================================================================
+// Chain-only position enumeration.
+//
+// Every open position is tracked under the owner's account:
+// `predict_account::PredictData.positions` is a
+// `Table<PositionKey{expiry_market_id, order_id}, Position>` — and Table
+// entries are dynamic fields, so the KEYS (everything redeem/claim need)
+// arrive directly from a dynamic-field listing. No indexer, no simulation.
+//
+// The walk (all parsing is exact BCS via `include: {content: true}`; the account
+// and PredictData struct layouts come from the generated `contracts/*` MoveStructs
+// so they can't drift from the deployed `account`/`predict_account` sources):
+//   1. wrapper object (id derived client-side)     → account UID
+//   2. derived DataKey<PredictApp> field object     → positions Table id
+//   3. listDynamicFields(table)                    → PositionKey per entry
+// Steps 1-2 resolve ids that are immutable once created — cache them per
+// owner (the facade does) and steady state is ONE call per page of positions.
+// ============================================================================
+
+// sui::dynamic_field::Field<DataKey<PredictApp>, PredictData>. DataKey is
+// source-empty, but Move inserts a hidden `dummy_field: bool` into empty
+// structs — so the name occupies ONE zero byte between id and value (and the
+// same byte is the derived-field key, below). The `value` uses the generated
+// `PredictData` layout so it tracks the deployed struct.
+const PredictDataFieldBcs = bcs.struct('Field<DataKey,PredictData>', {
+	id: bcs.Address,
+	name: bcs.bool(), // DataKey's hidden dummy_field
+	value: PredictData,
+});
+
+/** One open position — the coordinates redeem/claim/hasPosition take. */
+export interface OpenPosition {
+	marketId: string;
+	orderId: bigint;
+}
+
+/** Resolved-once ids for an owner's position store (cache these). */
+export interface PositionsHandle {
+	accountUid: string;
+	/** Null until the account's Predict data exists (first trade/builder-code). */
+	positionsTableId: string | null;
+	/** Open-position count at resolution time (from the Table's size). */
+	positionCount: bigint;
+}
+
+async function contentOf(client: ClientWithCoreApi, objectId: string): Promise<Uint8Array | null> {
+	try {
+		const { object } = await client.core.getObject({ objectId, include: { content: true } });
+		return object.content ?? null;
+	} catch (e) {
+		// Only a genuinely absent object means "no positions" (never-onboarded
+		// owner, or no Predict data yet). Anything else — transport failures,
+		// rate limits — must surface, not silently read as an empty portfolio.
+		if (/not.?found|does not exist|deleted|NOT_FOUND/i.test(String(e))) return null;
+		throw e;
+	}
+}
+
+/**
+ * Resolve the immutable id chain for an owner's positions: wrapper → account
+ * UID → PredictData → positions Table. Returns null when the owner has never
+ * created a Predict account.
+ */
+export async function resolvePositionsTable(
+	client: ClientWithCoreApi,
+	config: GeneratedConfig,
+	owner: string,
+): Promise<PositionsHandle | null> {
+	const wrapperContent = await contentOf(client, deriveAccountWrapperIdFrom(config, owner));
+	if (!wrapperContent) return null;
+	const accountUid = normalizeSuiAddress(AccountWrapper.parse(wrapperContent).account.account_id);
+
+	// The PredictData field id is derivable — no listing needed for this hop.
+	const dataFieldId = deriveDynamicFieldID(
+		accountUid,
+		`${config.accountPackageId}::account::DataKey<${config.predictPackageId}::predict_account::PredictApp>`,
+		new Uint8Array([0]), // DataKey's hidden dummy_field: bool = false
+	);
+	const fieldContent = await contentOf(client, dataFieldId);
+	if (!fieldContent) return { accountUid, positionsTableId: null, positionCount: 0n };
+
+	const data = PredictDataFieldBcs.parse(fieldContent).value;
+	return {
+		accountUid,
+		positionsTableId: normalizeSuiAddress(data.positions.id),
+		positionCount: data.positions.size,
+	};
+}
+
+/**
+ * List open positions from a resolved positions Table: one call per page,
+ * keys parsed from the dynamic-field NAMES (no per-entry fetches).
+ */
+export async function positionsFromTable(
+	client: ClientWithCoreApi,
+	positionsTableId: string,
+	opts: { limit?: number; maxPages?: number } = {},
+): Promise<OpenPosition[]> {
+	const limit = opts.limit ?? 1000;
+	const maxPages = opts.maxPages ?? 10;
+	const out: OpenPosition[] = [];
+	let cursor: string | undefined = undefined;
+	for (let page = 0; page < maxPages; page++) {
+		const res = await client.core.listDynamicFields({
+			parentId: positionsTableId,
+			limit,
+			cursor,
+		});
+		for (const entry of res.dynamicFields) {
+			const key = PositionKey.parse(entry.name.bcs);
+			out.push({
+				marketId: normalizeSuiAddress(key.expiry_market_id),
+				orderId: key.order_id,
+			});
+		}
+		if (!res.hasNextPage || !res.cursor) return out;
+		cursor = res.cursor;
+	}
+	throw new Error(
+		`positions listing exceeded ${maxPages} pages (${out.length} so far) — raise maxPages`,
+	);
+}
+
+/** Convenience: resolve + list in one call (uncached; the facade caches). */
+export async function positions(
+	client: ClientWithCoreApi,
+	config: GeneratedConfig,
+	owner: string,
+	opts: { limit?: number; maxPages?: number } = {},
+): Promise<OpenPosition[]> {
+	const handle = await resolvePositionsTable(client, config, owner);
+	if (!handle?.positionsTableId) return [];
+	return positionsFromTable(client, handle.positionsTableId, opts);
+}

package/src/predict/reads/pricing.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { Transaction } from '@mysten/sui/transactions';
+import { type GeneratedConfig } from '../config/generated.js';
+import { Pricer } from '../../contracts/deepbook_predict/pricing.js';
+import type { PricerInputs, Svi } from '../pricing.js';
+import { loadLivePricer, type MarketFeeds } from '../tx/trade.js';
+import { inspectReturns, type ReadClient } from './inspect.js';
+
+// The chain's fixed-point scales for the rolled `PricingSVI` (see the generated
+// `Pricer`/`PricingSVI` struct): forward and rho/m/sigma at 1e9; the rolled `a`/`b` land
+// at 1e18 (roll_down multiplies the 1e9 raw by an extra 1e9). Converting to `number`
+// (float) is deliberate — this is a display pricer; a is a variance ~O(1e-2), so f64's
+// ~15 significant digits are ample and, per pricing.ts, more precise than the chain's
+// fixed point on the short-dated surfaces this prices.
+const FORWARD_SCALE = 1e9;
+const AB_SCALE = 1e18;
+const RMS_SCALE = 1e9; // rho, m, sigma
+
+const i64 = (v: { magnitude: string | number | bigint; is_negative: boolean }): number =>
+	(v.is_negative ? -1 : 1) * Number(v.magnitude);
+
+/** A resolved pricer snapshot read from the chain: the decimal forward + rolled SVI the
+ * client-side math consumes, plus the oracle source timestamps behind it (ms; for
+ * staleness display — Pyth is 0 when no usable spot existed). The Block-Scholes entries are
+ * batch ENVELOPE times (what freshness and the SVI roll-down anchor on), not model times. */
+export interface PricerSnapshot extends PricerInputs {
+	sources: {
+		pythSpotMs: number;
+		blockScholesSpotMs: number;
+		blockScholesForwardMs: number;
+		blockScholesSviMs: number;
+	};
+}
+
+// Decode a `Pricer` (already forward-resolved + roll-down-applied on-chain) into decimal
+// `PricerInputs`. Signed fields (`a`, `rho`, `m`) carry the magnitude/flag pair the chain
+// uses; `b`/`sigma` are non-negative.
+function decodePricer(pricer: ReturnType<typeof Pricer.parse>): PricerSnapshot {
+	const s = pricer.svi;
+	const svi: Svi = {
+		a: ((s.a_is_negative ? -1 : 1) * Number(s.a_magnitude)) / AB_SCALE,
+		b: Number(s.b) / AB_SCALE,
+		rho: i64(s.rho) / RMS_SCALE,
+		m: i64(s.m) / RMS_SCALE,
+		sigma: Number(s.sigma) / RMS_SCALE,
+	};
+	return {
+		forward: Number(pricer.forward) / FORWARD_SCALE,
+		svi,
+		sources: {
+			pythSpotMs: Number(pricer.pyth_spot_source_timestamp_ms),
+			blockScholesSpotMs: Number(pricer.block_scholes_spot_source_timestamp_ms),
+			blockScholesForwardMs: Number(pricer.block_scholes_forward_source_timestamp_ms),
+			blockScholesSviMs: Number(pricer.block_scholes_svi_source_timestamp_ms),
+		},
+	};
+}
+
+// Read one live pricer snapshot for `marketId`: a single simulate of
+// `load_live_pricer` — the chain reads the oracle feeds, picks the forward
+// (Pyth-vs-Block-Scholes admin policy + freshness), and rolls the SVI down to now, then
+// returns the whole `Pricer` by value (copy+drop), whose BCS we decode. One round trip;
+// then a `boardPricer` prices every strike locally.
+//
+// `load_live_pricer` ABORTS (a typed PredictMoveError) when the market is expired, a feed
+// is stale, or the surface fails the pricing-safe envelope — i.e. exactly when the chain
+// itself cannot quote. Callers surface that the same way `read.price` does.
+export async function readPricerSnapshot(
+	client: ReadClient,
+	config: GeneratedConfig,
+	marketId: string,
+	feeds: MarketFeeds,
+): Promise<PricerSnapshot> {
+	const tx = new Transaction();
+	tx.add(loadLivePricer(config, { expiryMarketId: marketId, ...feeds }));
+	const [cmd0] = await inspectReturns(client, tx);
+	return decodePricer(Pricer.parse(cmd0[0]));
+}

package/src/predict/ticks.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { PredictInputError } from './errors.js';
+
+const TICK_BITS = 30n;
+
+/** +inf sentinel tick: the upper bound of an UP range. */
+export const POS_INF_TICK = (1n << TICK_BITS) - 1n;
+
+export type Side = 'up' | 'down';
+
+// Convert a raw binary-range strike to the `(lower_tick, higher_tick)` pair the
+// `mint` entrypoint takes directly (there is no standalone packed range key).
+// An UP order is `(strike, +inf)` -> lower_tick = strike/tick_size, higher_tick =
+// POS_INF_TICK; a DOWN order is `(-inf, strike)` -> lower_tick = 0 (neg-inf),
+// higher_tick = strike/tick_size.
+export function binaryRangeTicks(
+	strikeRaw: bigint,
+	side: Side,
+	tickSize: bigint,
+): { lowerTick: bigint; higherTick: bigint } {
+	// Anything not exactly 'up' used to fall through to DOWN, byte-identical to a real
+	// down mint — no build error, no simulate error, no chain abort. `side` arrives from UI
+	// state, JSON, or a DB column at runtime, where the literal type does not protect.
+	if (side !== 'up' && side !== 'down') {
+		throw new PredictInputError(`side must be 'up' or 'down', got ${JSON.stringify(side)}`);
+	}
+	const tick = strikeRaw / tickSize;
+	if (tick * tickSize !== strikeRaw) {
+		throw new PredictInputError(`strike ${strikeRaw} is not a whole tick multiple of ${tickSize}`);
+	}
+	if (tick <= 0n || tick >= POS_INF_TICK) {
+		throw new PredictInputError(
+			`strike tick ${tick} outside the finite tick domain (1..POS_INF_TICK-1)`,
+		);
+	}
+	const isUp = side === 'up';
+	return {
+		lowerTick: isUp ? tick : 0n,
+		higherTick: isUp ? POS_INF_TICK : tick,
+	};
+}

package/src/predict/tx/authed.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { accountMoveCalls as account } from '../../account.js';
+import * as plp from '../../contracts/deepbook_predict/plp.js';
+import * as predictAccount from '../../contracts/deepbook_predict/predict_account.js';
+import { withAuth } from './common.js';
+
+// Every owner-authorized single call in this SDK, declared rather than written: `withAuth`
+// prepends the `generate_auth` command and fills the generated `auth` argument, so each of these
+// takes exactly its generated options minus that slot. Command order is always auth → call, the
+// call consuming the hot potato. The builder-code pair lives in the PREDICT package's
+// `predict_account` module, not the account package.
+export const depositFunds = withAuth(account.depositFunds);
+export const withdrawFunds = withAuth(account.withdrawFunds);
+export const requestSupply = withAuth(plp.requestSupply);
+export const requestWithdraw = withAuth(plp.requestWithdraw);
+export const cancelSupplyRequest = withAuth(plp.cancelSupplyRequest);
+export const cancelWithdrawRequest = withAuth(plp.cancelWithdrawRequest);
+export const setBuilderCode = withAuth(predictAccount.setBuilderCode);
+export const unsetBuilderCode = withAuth(predictAccount.unsetBuilderCode);

package/src/predict/tx/common.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import type { Transaction, TransactionArgument, TransactionResult } from '@mysten/sui/transactions';
+import { toGeneratedConfig, type GeneratedConfig } from '../config/generated.js';
+import type { PredictConfig } from '../config/index.js';
+import { AccountContract, accountMoveCalls as account } from '../../account.js';
+
+// Predict's accounts ARE the shared on-chain account primitive (`packages/account`), so the
+// builders live in `@mysten/deepbook-v3/account` and this is the thin adapter that drives them with
+// Predict's deployed ids. The generated thunks are still used directly by `withAuth` below, which
+// wraps Predict's own entrypoints too — those take the same `Auth` hot potato.
+export function accountContract(cfg: PredictConfig): AccountContract {
+	return new AccountContract({
+		accountPackageId: cfg.packages.account,
+		accountRegistry: cfg.objects.accountRegistry,
+	});
+}
+
+/**
+ * Owner authority is a hot-potato `Auth` minted from the tx sender (`ctx` is implicit in a PTB)
+ * and consumed by the very next account-loading call (`load_account_mut` inside `deposit_funds` /
+ * `withdraw_funds` / `mint` / …). It resolves to owner auth for whoever signs the transaction.
+ * See `packages/account/sources/account.move`.
+ */
+export function generateAuth(cfg: PredictConfig): (tx: Transaction) => TransactionResult {
+	return account.generateAuth({ config: toGeneratedConfig(cfg) });
+}
+
+// The shape every generated binding shares: options in, one PTB command out.
+type GeneratedCall<Options> = (options: Options) => (tx: Transaction) => TransactionResult;
+
+// The generated options of a call that consumes the hot-potato `Auth`. Codegen types
+// `arguments` as the named form OR a positional tuple; only the named form is used here.
+interface AuthCallOptions {
+	arguments: { auth: TransactionArgument } | readonly unknown[];
+	config?: object;
+	package?: string;
+}
+
+// The named-`arguments` arm of such an options type (the tuple arm has no `auth` property).
+type NamedArguments<Options extends AuthCallOptions> = Extract<
+	Options['arguments'],
+	{ auth: TransactionArgument }
+>;
+
+/**
+ * The options {@link withAuth} leaves to the caller: the generated ones, minus the `auth`
+ * argument it supplies itself, with the projected config required (it is what mints the auth).
+ */
+export type WithAuthOptions<Options extends AuthCallOptions> = Omit<
+	Options,
+	'arguments' | 'config'
+> & {
+	config: GeneratedConfig;
+	arguments: Omit<NamedArguments<Options>, 'auth'>;
+};
+
+/**
+ * Every owner-authorized call in this SDK is the same two commands — mint the hot-potato `Auth`,
+ * then make the generated call that consumes it. This lifts a generated binding into that pair,
+ * so such a builder is declared rather than written: `withAuth(account.depositFunds)` takes
+ * `deposit_funds`'s own options with the `auth` slot already filled.
+ */
+export function withAuth<Options extends AuthCallOptions>(
+	call: GeneratedCall<Options>,
+): (options: WithAuthOptions<Options>) => (tx: Transaction) => TransactionResult {
+	return (options) => (tx) => {
+		const auth = tx.add(account.generateAuth({ config: options.config }));
+		// The one unchecked step: with `Options` still generic, TS cannot see that putting `auth`
+		// back makes the arguments whole again. Callers get the fully checked type above.
+		return tx.add(
+			call({ ...options, arguments: { ...options.arguments, auth } } as unknown as Options),
+		);
+	};
+}
+
+// The derivation must agree with on-chain `derive_address`, so it is owned in one place:
+// `@mysten/deepbook-v3/account`. This projects Predict's config onto that contract.
+export function deriveAccountWrapperIdFrom(
+	config: Pick<GeneratedConfig, 'accountRegistry' | 'accountPackageId'>,
+	owner: string,
+): string {
+	return new AccountContract({
+		accountPackageId: config.accountPackageId,
+		accountRegistry: config.accountRegistry,
+	}).deriveAccountWrapperId(owner);
+}
+
+/** The deterministic id of an owner's canonical account wrapper — no chain read needed. */
+export function deriveAccountWrapperId(cfg: PredictConfig, owner: string): string {
+	return deriveAccountWrapperIdFrom(toGeneratedConfig(cfg), owner);
+}