@mysten/deepbook-v3 2.0.0 → 2.1.3

package/src/predict/errors.ts

@@ -0,0 +1,83 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+// Typed errors for the Predict SDK.
+//
+// Two failure kinds cross the SDK boundary:
+//   - PredictInputError — a caller gave us something we rejected before touching
+//     the chain (unknown underlying, malformed argument, …).
+//   - PredictMoveError — a Move `abort` surfaced by a read/simulate. The deployed
+//     Predict packages are compiled with CLEVER ERRORS, so the fullnode decodes the
+//     `E…` error-constant name out of the abort code's high bits and returns it on
+//     the structured execution error. We read that name straight from chain instead
+//     of maintaining a module→code→name table that goes stale on every redeploy.
+
+/** A caller-supplied argument the SDK rejected before building/sending a tx. */
+export class PredictInputError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'PredictInputError';
+	}
+}
+
+/** A Move `abort` decoded from a simulate/read failure. */
+export class PredictMoveError extends Error {
+	readonly module: string;
+	/** Exact u64 abort code — bigint because clever-error encodings pack data
+	 * into the high bits, which Number would silently truncate. */
+	readonly code: bigint;
+	/** The `E…` constant name, decoded from the clever-error abort code by the
+	 * fullnode, or null when the transport surfaced no name (a non-clever abort,
+	 * or a JSON-RPC failure that carries only a line number). */
+	readonly abortName: string | null;
+
+	constructor(module: string, code: bigint, abortName: string | null) {
+		super(
+			abortName
+				? `Move abort in ${module}: ${abortName} (code ${code})`
+				: `Move abort in ${module}: code ${code}`,
+		);
+		this.name = 'PredictMoveError';
+		this.module = module;
+		this.code = code;
+		this.abortName = abortName;
+	}
+}
+
+// The structured MoveAbort execution error surfaced by `@mysten/sui` on a failed
+// simulate/execute. Read structurally rather than via the client's exported
+// `SuiClientTypes.ExecutionError` (`@mysten/sui/client`) so mocked simulate results
+// and future API-shape drift still satisfy it — the same convention reads/inspect.ts
+// uses for its simulate seam. Field provenance:
+//   - `MoveAbort.abortCode`                → u64 abort code as a decimal string.
+//   - `MoveAbort.location.module`          → the aborting module's short name.
+//   - `MoveAbort.cleverError.constantName` → the `E…` error constant, decoded by the
+//     fullnode from the clever-error bits of the abort code and surfaced by the gRPC
+//     (`grpc/core.ts` parseMoveAbort) and GraphQL transports. This is the on-chain
+//     name that replaces the old hand-maintained ABORT_TABLES. JSON-RPC surfaces only
+//     a line number, so `constantName` (and thus `abortName`) is absent there.
+export interface MoveAbortError {
+	MoveAbort?: {
+		abortCode?: string | number | bigint;
+		location?: { module?: string };
+		cleverError?: { constantName?: string };
+	};
+}
+
+/**
+ * Decode a `@mysten/sui` MoveAbort execution error into a {@link PredictMoveError}.
+ * Returns null when `error` carries no MoveAbort (InsufficientGas, a size error, any
+ * non-abort failure), so callers can fall back to a plain Error.
+ *
+ * `abortName` is taken straight from the chain-decoded clever-error constant; it is
+ * null when the abort predates clever errors or the transport didn't surface a name.
+ * `code` stays a bigint — a clever-error abort code packs the module, line, and
+ * constant index into the high bits of the u64 and would lose precision as a Number.
+ */
+export function decodeMoveAbort(error: MoveAbortError | null | undefined): PredictMoveError | null {
+	const abort = error?.MoveAbort;
+	if (!abort) return null;
+	const module = abort.location?.module ?? '';
+	const code = abort.abortCode != null ? BigInt(abort.abortCode) : 0n;
+	const abortName = abort.cleverError?.constantName ?? null;
+	return new PredictMoveError(module, code, abortName);
+}

package/src/predict/index.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+// Public API for `@mysten/deepbook-v3/predict`. The curated surface is the `PredictClient`
+// facade plus the value types, unit conversions, tick helpers, typed errors, and typed
+// execution-result decoders — and the few primitives below that compose predict
+// accounts into PTBs on FOREIGN packages, which no facade shape can cover.
+
+// === Facade === (register as a client extension: `client.$extend(predict({ network }))`)
+export { POSITION_LOT_SIZE, PredictClient, predict } from './client.js';
+export type { PredictCompatibleClient } from './client.js';
+export type {
+	ActiveMarket,
+	CloseOptions,
+	MarketDescriptor,
+	MarketSummary,
+	MintAmountOptions,
+	MintOptions,
+	MintQuote,
+	PoolSummary,
+	RedeemQuote,
+} from './client.js';
+
+// === Composition with foreign packages === auth + deterministic account addressing
+// for PTBs that compose predict accounts with packages this SDK doesn't know (e.g.
+// `deepbook_core_account` spot trading). `deriveAccountWrapperId` is the pure
+// `(cfg, owner)` form of `wrapperIdFor` for contexts with no client instance. These are
+// Predict-config-bound conveniences over `@mysten/deepbook-v3/account`, which owns the
+// shared account primitive — reach for its `AccountContract` to drive it directly.
+export { deriveAccountWrapperId, generateAuth } from './tx/common.js';
+
+// === Config ===
+export {
+	TESTNET_CONFIG,
+	getConfig,
+	getDeployment,
+	getUnits,
+	TESTNET_DEPLOYMENT,
+	TESTNET_UNITS,
+} from './config/index.js';
+export type { PredictConfig, PredictPackages, UnderlyingConfig } from './config/index.js';
+
+// === Units (raw ⇄ human conversions) === domain-specific only; the generic `toRaw`/
+// `fromRaw` primitives stay internal to avoid colliding with consumers' own helpers.
+export {
+	U64_MAX,
+	priceToRaw,
+	probabilityToRaw,
+	rawToPrice,
+	rawToProbability,
+	rawToUsdc,
+	usdcToRaw,
+} from './units.js';
+
+// === Ticks ===
+export { POS_INF_TICK, binaryRangeTicks } from './ticks.js';
+export type { Side } from './ticks.js';
+
+// === Client-side pricing === the deployed SVI digital math (skew-corrected, signed
+// params, roll-down) as a float port, namespaced to keep the top-level surface clean:
+// `pricing.upProbability`, `.boardPricer`, `.rollDown`, `.forward`, types `pricing.Svi` /
+// `pricing.PricerInputs` / `pricing.BoardPricer`. Turnkey path: `client.predict.read.pricer(
+// market)` reads the chain's resolved pricer once, then prices a whole board locally.
+export * as pricing from './pricing.js';
+export type { PricerSnapshot } from './reads/pricing.js';
+
+// === Errors ===
+export { PredictInputError, PredictMoveError, decodeMoveAbort } from './errors.js';
+export type { MoveAbortError } from './errors.js';
+
+// === Client seam + position type used in public read signatures ===
+export type { ReadClient } from './reads/inspect.js';
+export type { OpenPosition } from './reads/positions.js';
+
+// === Execution-result decoder types === the decoders themselves are reached via
+// `client.predict.decode.*`; only the receipt types are needed on the public surface.
+export type {
+	BalanceChangeReceipt,
+	BuilderCodeReceipt,
+	ClaimReceipt,
+	CreateManagerReceipt,
+	DecodableEvent,
+	DecodableTransactionResult,
+	MintReceipt,
+	PlpCancelReceipt,
+	PlpRequestReceipt,
+	RedeemReceipt,
+} from './decode.js';
+
+// The `/sessions` Predict wrappers take `pricer` as a PTB result of this call, so it has to
+// be reachable from the published surface for those builders to be composable at all.
+export { loadLivePricer, type MarketFeeds } from './tx/trade.js';
+// `loadLivePricer` takes the projected config, so the projection and its type have to be
+// reachable too — without them the `/sessions` Predict wrappers cannot be composed at all.
+export { toGeneratedConfig, type GeneratedConfig } from './config/generated.js';

package/src/predict/pricing.ts

@@ -0,0 +1,199 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+// Faithful float port of the deployed `deepbook_predict::pricing::compute_nd2`
+// (testnet `predict-testnet-8-21`, sourceCommit 1f79fe87) — the SVI-adjusted digital
+// probability, WITH the skew-correction term. It operates on the pricer's
+// ALREADY-RESOLVED forward and ALREADY-ROLLED-DOWN SVI, exactly as `load_live_pricer`
+// returns them (decoded by `reads/pricing.ts`). So the two on-chain steps that pick the
+// forward (Pyth-spot vs Block-Scholes, admin flag + freshness) and roll `a`/`b` down by
+// remaining/anchored time already happened on-chain — this module never re-derives them,
+// which is what keeps it faithful.
+//
+// This is the fast client-side board pricer: read one `Pricer` snapshot, then price every
+// strike locally with no further chain calls. `read.price` / `read.quoteMint` (a chain
+// dry-run) stay the authoritative quote at trade time. Divergence vs the chain is up to
+// ~1e-4 in probability, dominated by the chain's fixed-point truncation near ATM when sigma
+// sits at its floor (float64 here is the more precise side, not the less); negligible for
+// display. `tests/testnet/pricing.test.ts` bounds it live against the deployment.
+//
+// The on-chain formula (pricing.move `compute_nd2`, 1f79fe87):
+//   k  = ln(strike / forward)
+//   x  = k - m
+//   w  = a + b·(ρ·x + √(x² + σ²))            // a, b already rolled down
+//   d2 = −(k + w/2) / √w                       // clamped to ±8
+//   w′ = b·(ρ + x/√(x² + σ²))                  // SVI slope
+//   price = N(d2) − φ(d2)·w′ / (2·√w)          // the skew correction, clamped [0,1]
+
+/** Rolled-down SVI parameters for one expiry, in decimal (NOT the chain's 1e9/1e18 integer
+ * scaling) — the surface AFTER Predict's remaining-time roll-down, as carried by the
+ * on-chain `Pricer`. `a`, `rho`, `m` are signed; `b`, `sigma` are non-negative. */
+export interface Svi {
+	a: number;
+	b: number;
+	rho: number;
+	m: number;
+	sigma: number;
+}
+
+/** A resolved pricer snapshot: the forward the contract prices against and its rolled SVI
+ * surface, both in decimal. Produced by `read.pricer(market)`; consume via {@link boardPricer}
+ * or the pure functions below. */
+export interface PricerInputs {
+	/** Forward price the digital settles against, in decimal (same units as `strike`). */
+	forward: number;
+	svi: Svi;
+}
+
+/** Standard normal CDF via erf (Abramowitz–Stegun 7.1.26, |err| < 1.5e-7). */
+function normalCdf(x: number): number {
+	return 0.5 * (1 + erf(x / Math.SQRT2));
+}
+
+/** Standard normal PDF. */
+function normalPdf(x: number): number {
+	return Math.exp(-0.5 * x * x) / Math.sqrt(2 * Math.PI);
+}
+
+function erf(x: number): number {
+	const sign = x >= 0 ? 1 : -1;
+	const ax = Math.abs(x);
+	const t = 1 / (1 + 0.3275911 * ax);
+	const y =
+		1 -
+		((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) *
+			t *
+			Math.exp(-ax * ax);
+	return sign * y;
+}
+
+// Clamp |d2| at 8, matching the chain (`normal_cdf`/`normal_pdf` saturate beyond that).
+function clampD2(d2: number): number {
+	return d2 > 8 ? 8 : d2 < -8 ? -8 : d2;
+}
+
+/** P(settle > strike) — the UP digital, with the SVI skew correction. `inputs.svi` is the
+ * already-rolled surface (no roll-down applied here). `forward` and `strike` share units.
+ * Returns a probability in [0, 1]. */
+export function upProbability(inputs: PricerInputs, strike: number): number {
+	const { forward, svi } = inputs;
+	if (!(forward > 0)) return 0;
+	if (strike <= 0) return 1; // neg-inf limit
+	const { a, b, rho, m, sigma } = svi;
+	const k = Math.log(strike / forward);
+	const km = k - m;
+	const root = Math.sqrt(km * km + sigma * sigma);
+	const inner = rho * km + root; // >= 0 for |rho| <= 1
+	const w = a + b * inner; // total variance
+	// The chain guarantees w > 0 at every strike (assert_min_total_variance_positive at
+	// load time), so this branch is unreachable in practice; return the variance→0 tail
+	// limit rather than throw, so a UI never crashes on a degenerate snapshot.
+	if (w <= 0) return k < 0 ? 1 : 0;
+	const sq = Math.sqrt(w);
+	const d2 = clampD2(-((k + w / 2) / sq));
+	const nd2 = normalCdf(d2);
+	const wPrime = b * (rho + km / root); // SVI slope × b
+	const price = nd2 - (normalPdf(d2) * wPrime) / (2 * sq); // skew correction
+	return price < 0 ? 0 : price > 1 ? 1 : price;
+}
+
+/** P(settle < strike) — the DOWN digital. Exactly `1 − up`, matching the chain's
+ * `range_price(-inf, strike] = up(-inf) − up(strike) = 1 − up(strike)`. */
+export function downProbability(inputs: PricerInputs, strike: number): number {
+	return 1 - upProbability(inputs, strike);
+}
+
+/** Probability mass in `(lower, higher]`, floored at 0 (matches `compute_range_price`'s
+ * saturating subtraction). Use `lower <= 0` for the −∞ bound and `higher = Infinity` for +∞. */
+export function rangeProbability(inputs: PricerInputs, lower: number, higher: number): number {
+	// up(lower) − up(higher), where up(+inf) = 0 and up(<= 0) = 1.
+	const upLower = lower <= 0 ? 1 : upProbability(inputs, lower);
+	const upHigher = higher === Infinity ? 0 : upProbability(inputs, higher);
+	const d = upLower - upHigher;
+	return d < 0 ? 0 : d;
+}
+
+/** Binary probability at `strike` for the given side (`up` = P(>strike), `down` = 1 − up). */
+export function probability(inputs: PricerInputs, strike: number, side: 'up' | 'down'): number {
+	const up = upProbability(inputs, strike);
+	return side === 'up' ? up : 1 - up;
+}
+
+/** Strike where P(settle > strike) = `p`, by bisection (UP is monotone-decreasing in
+ * strike). Null when no crossing exists within ±64% of forward. */
+export function strikeAtProbability(inputs: PricerInputs, p: number): number | null {
+	const { forward } = inputs;
+	if (!(forward > 0) || !(p > 0 && p < 1)) return null;
+	const up = (strike: number) => upProbability(inputs, strike);
+	let r = 0.01;
+	while (up(forward * (1 - r)) < p || up(forward * (1 + r)) > p) {
+		r *= 2;
+		if (r > 0.64) return null;
+	}
+	let lo = forward * (1 - r);
+	let hi = forward * (1 + r);
+	for (let i = 0; i < 64; i++) {
+		const mid = (lo + hi) / 2;
+		if (up(mid) > p) lo = mid;
+		else hi = mid;
+	}
+	return (lo + hi) / 2;
+}
+
+// --- Resolving raw feed data client-side (for consumers that hold their own live oracle
+// feed and want to price with NO chain call, e.g. deepbook-app). The turnkey path is
+// `read.pricer(market)`, which reads these already resolved from the chain's `Pricer`;
+// these two helpers reproduce the on-chain resolution when you'd rather not read the chain.
+
+/** Roll `a` and `b` down by the fraction of anchored time remaining, matching the chain's
+ * `roll_down_svi` (variance decays toward expiry). `remainingMs` = expiry − now;
+ * `anchorTteMs` = expiry − the SVI observation's **batch envelope time** — the same clock the
+ * freshness gate uses, and what the chain anchors on. It is NOT the provider's calibration
+ * (model) time, which stays on the stored observation: using that rolls by the wrong
+ * fraction. `read.pricer` avoids the question entirely (the chain has already rolled).
+ * `rho`, `m`, `sigma` are unchanged. Feed an UNrolled provider surface; the result is what {@link upProbability}
+ * expects. */
+export function rollDown(svi: Svi, remainingMs: number, anchorTteMs: number): Svi {
+	const frac = anchorTteMs > 0 ? remainingMs / anchorTteMs : 0;
+	return { ...svi, a: svi.a * frac, b: svi.b * frac };
+}
+
+/** The forward the contract prices against: Pyth spot re-anchored by the Block-Scholes
+ * basis (`spot · forward/bsSpot`), falling back to the Block-Scholes forward when Pyth is
+ * absent. Pass `pythSpot <= 0` to force the fallback. NOTE: on-chain this branch is also
+ * gated by the admin flag `use_pyth_spot_for_forward` (default on) and a Pyth freshness
+ * window — when the flag is off or the Pyth spot is stale, the chain uses `bsForward`. If
+ * you track that config/freshness, apply it before calling (or use `read.pricer`, which
+ * gets the resolved forward from the chain). */
+export function forward(pythSpot: number, bsSpot: number, bsForward: number): number {
+	if (pythSpot > 0 && bsSpot > 0) return pythSpot * (bsForward / bsSpot);
+	return bsForward;
+}
+
+/** A pricer bound to one resolved snapshot: price a whole board of strikes locally, no
+ * chain calls. Returned by `read.pricer(market)`; also constructable directly from inputs
+ * you already hold (e.g. from a `Pricer` snapshot decoded elsewhere). */
+export interface BoardPricer extends PricerInputs {
+	/** P(settle > strike). */
+	up(strike: number): number;
+	/** P(settle < strike) = 1 − up. */
+	down(strike: number): number;
+	/** P(side wins at strike). */
+	probability(strike: number, side: 'up' | 'down'): number;
+	/** Probability mass in `(lower, higher]` (use `lower<=0`/`higher=Infinity` for the tails). */
+	range(lower: number, higher: number): number;
+	/** Strike where P(> strike) = `p`, or null if outside ±64% of forward. */
+	strikeAtProbability(p: number): number | null;
+}
+
+/** Build a {@link BoardPricer} from a resolved snapshot (decimal forward + rolled SVI). Pure. */
+export function boardPricer(inputs: PricerInputs): BoardPricer {
+	return {
+		forward: inputs.forward,
+		svi: inputs.svi,
+		up: (strike) => upProbability(inputs, strike),
+		down: (strike) => downProbability(inputs, strike),
+		probability: (strike, side) => probability(inputs, strike, side),
+		range: (lower, higher) => rangeProbability(inputs, lower, higher),
+		strikeAtProbability: (p) => strikeAtProbability(inputs, p),
+	};
+}

package/src/predict/reads/balances.ts

@@ -0,0 +1,55 @@
+// 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 { deriveAccountWrapperIdFrom } from '../tx/common.js';
+import { accountMoveCalls as account } from '../../account.js';
+import * as predictAccount from '../../contracts/deepbook_predict/predict_account.js';
+import { inspectReturns, type ReadClient } from './inspect.js';
+import { parseU64LE } from './parse.js';
+
+// An owner's stored account balance for `coinType` (the deployment's quote coin,
+// DUSDC on testnet, unless the caller asks for another). Chains `account::load_account(wrapper)` →
+// `account::balance<T>(account, root, clock)`; the u64 is command 1's return —
+// see packages/account/sources/account.move:{80,86}. The clock is auto-injected by
+// the generated `balance` wrapper; the wrapper id is derived off-chain (no read).
+export async function accountBalance(
+	client: ReadClient,
+	config: GeneratedConfig,
+	owner: string,
+	coinType: string,
+): Promise<bigint> {
+	const tx = new Transaction();
+	const acct = tx.add(
+		account.loadAccount({ config, arguments: { self: deriveAccountWrapperIdFrom(config, owner) } }),
+	);
+	tx.add(account.balance({ config, typeArguments: [coinType], arguments: { self: acct } }));
+	const cmds = await inspectReturns(client, tx);
+	return parseU64LE(cmds[1][0]);
+}
+
+// Whether the owner's account still holds `orderId` on `marketId`. The cheap
+// on-chain validator for app-stored order ids (stale after a full close or a
+// partial-close replacement — see RedeemReceipt.replacementOrderId). Chains
+// `account::load_account(wrapper)` → `predict_account::has_position(account,
+// market_id, order_id)` — see packages/predict/sources/predict_account.move:85.
+export async function hasPosition(
+	client: ReadClient,
+	config: GeneratedConfig,
+	owner: string,
+	marketId: string,
+	orderId: bigint,
+): Promise<boolean> {
+	const tx = new Transaction();
+	const acct = tx.add(
+		account.loadAccount({ config, arguments: { self: deriveAccountWrapperIdFrom(config, owner) } }),
+	);
+	tx.add(
+		predictAccount.hasPosition({
+			config,
+			arguments: { account: acct, expiryMarketId: marketId, orderId },
+		}),
+	);
+	const cmds = await inspectReturns(client, tx);
+	return (cmds[1][0][0] ?? 0) !== 0; // BCS bool: 1 byte
+}

package/src/predict/reads/inspect.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import type { ClientWithCoreApi } from '@mysten/sui/client';
+import type { Transaction } from '@mysten/sui/transactions';
+import { normalizeSuiAddress } from '@mysten/sui/utils';
+import { decodeMoveAbort, type MoveAbortError } from '../errors.js';
+
+// The one network seam every read sits on: any client exposing the core API
+// (`client.core.simulateTransaction`, plus the object reads positions.ts needs).
+// Callers pass a real SuiGrpcClient/SuiJsonRpcClient; tests inject a structural mock.
+export type ReadClient = ClientWithCoreApi;
+
+// The abort payload a failed simulate result carries: the structured gRPC `MoveAbort`
+// arm (`{ abortCode, location: { module }, cleverError: { constantName } }`) plus an
+// optional display `message`. Read structurally so mocks and API-shape drift satisfy it.
+type SimAbortError = MoveAbortError & { message?: string };
+
+// Run a read-only PTB through the gRPC `simulateTransaction` (the devInspect
+// replacement) and return each command's BCS return values, indexed
+// [commandIndex][returnValueIndex].
+//
+// `checksEnabled: false` disables validation so we may inspect non-entry public
+// funs — see SimulateTransactionOptions.checksEnabled in
+// node_modules/@mysten/sui/dist/client/types.d.mts:385-396. Per-command outputs
+// live under `commandResults[i].returnValues[j].bcs` — see
+// SimulateTransactionResult / CommandResult / CommandOutput in that same file at
+// lines 309-348. `commandResults` is only populated when `include.commandResults`
+// is set, so we request it explicitly.
+//
+// A sender is required to simulate; callers rarely have one for a pure read, so we
+// default to the zero address. On abort the result's `$kind` is `FailedTransaction`;
+// we decode the carried abort into a typed PredictMoveError, falling back to a plain
+// Error with the failure message when it isn't a decodable Move abort.
+// Shared failure handling: decode the abort carried by a FailedTransaction
+// into a typed PredictMoveError, else throw a plain Error.
+function throwSimFailure(failed: unknown): never {
+	const status = (failed as { status?: { success: boolean; error?: SimAbortError } })?.status;
+	const error = status && status.success === false ? status.error : undefined;
+	const decoded = error ? decodeMoveAbort(error) : null;
+	if (decoded) throw decoded;
+	throw new Error(error?.message ?? 'simulateTransaction aborted (FailedTransaction)');
+}
+
+// Simulate a full transaction (typically one built by a tx.* builder) and return
+// the events it would emit — the quote path: dry-run the real action, decode the
+// receipt. Sender must be the acting owner so account auth resolves. Throws the
+// same typed errors the real execution would surface.
+export async function simulateWithEvents(
+	client: ReadClient,
+	tx: Transaction,
+	sender: string,
+): Promise<{ eventType?: string; bcs?: Uint8Array | string }[]> {
+	tx.setSender(sender);
+	const result = await client.core.simulateTransaction({
+		transaction: tx,
+		checksEnabled: false,
+		include: { events: true },
+	});
+	if (result.$kind === 'FailedTransaction') throwSimFailure(result.FailedTransaction);
+	return (result.Transaction?.events ?? []) as { eventType?: string; bcs?: Uint8Array }[];
+}
+
+export async function inspectReturns(
+	client: ReadClient,
+	tx: Transaction,
+	sender: string = normalizeSuiAddress('0x0'),
+): Promise<Uint8Array[][]> {
+	tx.setSender(sender);
+	const result = await client.core.simulateTransaction({
+		transaction: tx,
+		checksEnabled: false,
+		include: { commandResults: true },
+	});
+	if (result.$kind === 'FailedTransaction') throwSimFailure(result.FailedTransaction);
+	const commands = result.commandResults;
+	if (!commands) throw new Error('simulateTransaction returned no commandResults');
+	return commands.map((c) => c.returnValues.map((rv) => rv.bcs));
+}