@mysten/sui 2.30.0 → 2.31.0

package/src/transactions/index.ts

@@ -18,6 +18,7 @@ export {
 	type TransactionObjectArgument,
 	type TransactionResult,
 	type TransactionCopyOptions,
+	type WithdrawalOptions,
 } from './Transaction.js';
 
 export { type SerializedTransactionDataV2 } from './data/v2.js';
@@ -48,3 +49,5 @@ export type {
 export { Arguments } from './Arguments.js';
 
 export { isArgument } from './utils.js';
+
+export type { BalanceOptions, AllowanceReference } from './intents/BalanceOptions.js';

package/src/transactions/intents/AllowanceBalance.ts

@@ -0,0 +1,204 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { object, optional, parse, picklist, string } from 'valibot';
+
+import { hasMvrName } from '../../client/mvr.js';
+
+import { ALLOWANCE_BALANCE } from './BalanceIntentNames.js';
+import { resolveBalances } from './ResolveBalances.js';
+
+import { bcs } from '../../bcs/index.js';
+import type { SuiClientTypes } from '../../client/index.js';
+import { normalizeStructTag, normalizeSuiAddress } from '../../utils/sui-types.js';
+import { TransactionCommands } from '../Commands.js';
+import type { Argument } from '../data/internal.js';
+import { Inputs } from '../Inputs.js';
+import { getClient } from '../resolve.js';
+import type { TransactionPlugin } from '../resolve.js';
+import type { Transaction } from '../Transaction.js';
+import type { AllowanceReference } from './BalanceOptions.js';
+
+export { ALLOWANCE_BALANCE } from './BalanceIntentNames.js';
+
+const AllowanceBalanceData = object({
+	objectId: string(),
+	funder: optional(string()),
+	appType: optional(string()),
+	type: string(),
+	amount: string(),
+	outputKind: picklist(['coin', 'balance']),
+});
+
+// Read only the prefix needed for spending. The remaining settings and current_spend
+// are checked by Move, so this does not need to model rate limits or their policy.
+const AllowanceMetadata = bcs.struct('AllowanceMetadata', {
+	id: bcs.Address,
+	funder: bcs.Address,
+	spender: bcs.option(bcs.Address),
+	app: bcs.option(bcs.string()),
+});
+
+export function allowanceBalance({
+	allowance,
+	amount,
+	type = '0x2::sui::SUI',
+	outputKind,
+}: {
+	allowance: string | AllowanceReference;
+	amount: bigint;
+	type?: string;
+	outputKind: 'coin' | 'balance';
+}) {
+	bcs.U64.validate(amount);
+	const objectId = normalizeSuiAddress(
+		typeof allowance === 'string' ? allowance : allowance.objectId,
+	);
+	const reference = typeof allowance === 'string' ? { objectId } : allowance;
+	return (tx: Transaction) => {
+		tx.addIntentResolver(ALLOWANCE_BALANCE, resolveBalances);
+		return tx.add(
+			TransactionCommands.Intent({
+				name: ALLOWANCE_BALANCE,
+				inputs: {
+					allowance: tx.object(objectId),
+					clock: tx.object.clock(),
+					...(reference.app ? { permit: tx.object(reference.app.permit) } : {}),
+				},
+				data: {
+					objectId,
+					funder: reference.funder ? normalizeSuiAddress(reference.funder) : undefined,
+					appType: reference.app ? normalizeStructTag(reference.app.type) : undefined,
+					type: normalizeStructTag(type),
+					amount: String(amount),
+					outputKind,
+				},
+			}),
+		);
+	};
+}
+
+export const resolveAllowanceBalance: TransactionPlugin = async (
+	transactionData,
+	options,
+	next,
+) => {
+	const ids = new Set<string>();
+	const namedTypes = new Set<string>();
+	for (const command of transactionData.commands) {
+		if (command.$kind !== '$Intent' || command.$Intent.name !== ALLOWANCE_BALANCE) continue;
+		const data = parse(AllowanceBalanceData, command.$Intent.data);
+		if (!data.funder) ids.add(data.objectId);
+		for (const type of [data.type, data.appType]) {
+			if (type && hasMvrName(type)) namedTypes.add(type);
+		}
+	}
+
+	const [resolvedTypes, objects] = await Promise.all([
+		namedTypes.size ? getClient(options).core.mvr.resolve({ types: [...namedTypes] }) : undefined,
+		ids.size
+			? getClient(options)
+					.core.getObjects({ objectIds: [...ids], include: { content: true } })
+					.then((result) => result.objects)
+			: [],
+	]);
+	const allowances = new Map<string, SuiClientTypes.Object<{ content: true }>>();
+	for (const object of objects) {
+		if (object instanceof Error) throw object;
+		allowances.set(object.objectId, object);
+	}
+
+	for (let index = 0; index < transactionData.commands.length; index++) {
+		const command = transactionData.commands[index];
+		if (command.$kind !== '$Intent' || command.$Intent.name !== ALLOWANCE_BALANCE) continue;
+		const data = parse(AllowanceBalanceData, command.$Intent.data);
+		if (hasMvrName(data.type)) {
+			const resolved = resolvedTypes?.types[data.type];
+			if (!resolved) throw new Error(`No resolution found for type: ${data.type}`);
+			data.type = normalizeStructTag(resolved.type);
+		}
+		if (data.appType && hasMvrName(data.appType)) {
+			const resolved = resolvedTypes?.types[data.appType];
+			if (!resolved) throw new Error(`No resolution found for type: ${data.appType}`);
+			data.appType = normalizeStructTag(resolved.type);
+		}
+		let funder = data.funder;
+		if (!funder) {
+			const allowance = allowances.get(data.objectId);
+			const expectedType = normalizeStructTag(
+				`0x2::allowance::Allowance<0x2::balance::Balance<${data.type}>>`,
+			);
+			if (!allowance || allowance.type !== expectedType || allowance.owner.$kind !== 'Shared') {
+				throw new Error(`Expected a shared ${expectedType} allowance at ${data.objectId}`);
+			}
+			const metadata = AllowanceMetadata.parse(allowance.content);
+			if (metadata.app !== null && !data.appType) {
+				throw new Error(
+					`Allowance ${data.objectId} is app-bound; pass allowance.app with the app type and SpendPermit`,
+				);
+			}
+			if (
+				data.appType &&
+				(metadata.app === null || normalizeStructTag(metadata.app) !== data.appType)
+			) {
+				throw new Error(`Allowance ${data.objectId} is not bound to app ${data.appType}`);
+			}
+			funder = metadata.funder;
+			const input = command.$Intent.inputs.allowance as Argument;
+			if (input.$kind === 'Input') {
+				transactionData.inputs[input.Input] = Inputs.SharedObjectRef({
+					objectId: data.objectId,
+					initialSharedVersion: allowance.owner.Shared.initialSharedVersion,
+					mutable: true,
+				});
+			}
+		}
+		// Spending mutates the allowance even when the caller supplied the funder
+		// and we did not fetch metadata. Reuse and upgrade its existing input.
+		const allowanceArgument = command.$Intent.inputs.allowance as Argument;
+		if (allowanceArgument.$kind === 'Input') {
+			const input = transactionData.inputs[allowanceArgument.Input];
+			if (input.Object?.SharedObject) input.Object.SharedObject.mutable = true;
+			if (input.UnresolvedObject) input.UnresolvedObject.mutable = true;
+		}
+		const withdrawal = transactionData.addInput(
+			'withdrawal',
+			Inputs.FundsWithdrawal({
+				reservation: { $kind: 'MaxAmountU64', MaxAmountU64: data.amount },
+				typeArg: { $kind: 'Balance', Balance: data.type },
+				withdrawFrom: {
+					$kind: 'SenderAllowance',
+					SenderAllowance: { funder, allowance: data.objectId },
+				},
+			}),
+		);
+		const commands = [
+			TransactionCommands.MoveCall({
+				target: data.appType
+					? '0x2::allowance::app_balance_spend'
+					: '0x2::allowance::balance_spend',
+				typeArguments: data.appType ? [data.type, data.appType] : [data.type],
+				arguments: [
+					command.$Intent.inputs.allowance as Argument,
+					...(data.appType ? [command.$Intent.inputs.permit as Argument] : []),
+					withdrawal,
+					command.$Intent.inputs.clock as Argument,
+				],
+			}),
+		];
+		if (data.outputKind === 'coin') {
+			commands.push(
+				TransactionCommands.MoveCall({
+					target: '0x2::coin::from_balance',
+					typeArguments: [data.type],
+					arguments: [{ $kind: 'Result', Result: index }],
+				}),
+			);
+		}
+		transactionData.replaceCommand(index, commands, {
+			NestedResult: [index + commands.length - 1, 0],
+		});
+		index += commands.length - 1;
+	}
+	return next();
+};

package/src/transactions/intents/BalanceIntentNames.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export const ALLOWANCE_BALANCE = 'AllowanceBalance';
+export const COIN_WITH_BALANCE = 'CoinWithBalance';

package/src/transactions/intents/BalanceOptions.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { TransactionObjectArgument } from '../Transaction.js';
+
+/** An allowance with optional funder metadata and app authorization. */
+export interface AllowanceReference {
+	objectId: string;
+	/** Skip the metadata lookup when the funder is already known. */
+	funder?: string;
+	/** Authorization for an app-bound allowance. */
+	app?: {
+		/** The app type A in SpendPermit<A>. */
+		type: string;
+		/** A SpendPermit<A> from the app, consumed by this spend. */
+		permit: TransactionObjectArgument;
+	};
+}
+
+export type BalanceOptions = {
+	/** The coin type T, not Balance<T>. Defaults to SUI. */
+	type?: string;
+	balance: bigint | number | string;
+} & (
+	| { allowance?: never; useGasCoin?: boolean }
+	| {
+			/** An allowance ID or reference with optional app authorization. Never falls back to sender funds. */
+			allowance: string | AllowanceReference;
+			useGasCoin?: never;
+	  }
+);
+
+export function normalizeBalance(options: BalanceOptions): bigint {
+	if (options.allowance !== undefined && options.useGasCoin !== undefined) {
+		throw new Error('useGasCoin cannot be combined with allowance');
+	}
+	const amount = options.balance;
+	if (typeof amount === 'string' && !/^[0-9]+$/.test(amount)) {
+		throw new Error('Amount must be a non-empty string of decimal digits');
+	}
+	if (typeof amount === 'number' && !Number.isSafeInteger(amount)) {
+		throw new Error('Amount must be a safe integer; use bigint or a string for larger amounts');
+	}
+	return BigInt(amount);
+}

package/src/transactions/intents/CoinWithBalance.ts

@@ -16,8 +16,11 @@ import {
 	union,
 } from 'valibot';
 
+import { ALLOWANCE_BALANCE, COIN_WITH_BALANCE } from './BalanceIntentNames.js';
+import { resolveBalances } from './ResolveBalances.js';
+
 import { bcs } from '../../bcs/index.js';
-import { normalizeStructTag } from '../../utils/sui-types.js';
+import { normalizeStructTag, normalizeSuiAddress } from '../../utils/sui-types.js';
 import { TransactionCommands } from '../Commands.js';
 import type { Argument } from '../data/internal.js';
 import { Inputs } from '../Inputs.js';
@@ -26,7 +29,7 @@ import type { Transaction, TransactionResult } from '../Transaction.js';
 import type { TransactionDataBuilder } from '../TransactionData.js';
 import type { ClientWithCoreApi, SuiClientTypes } from '../../client/index.js';
 
-export const COIN_WITH_BALANCE = 'CoinWithBalance';
+export { COIN_WITH_BALANCE } from './BalanceIntentNames.js';
 const SUI_TYPE = normalizeStructTag('0x2::sui::SUI');
 
 export function coinWithBalance({
@@ -45,7 +48,7 @@ export function coinWithBalance({
 			return coinResult;
 		}
 
-		tx.addIntentResolver(COIN_WITH_BALANCE, resolveCoinBalance);
+		tx.addIntentResolver(COIN_WITH_BALANCE, resolveBalances);
 		const coinType = type === 'gas' ? type : normalizeStructTag(type);
 
 		coinResult = tx.add(
@@ -80,7 +83,7 @@ export function createBalance({
 			return balanceResult;
 		}
 
-		tx.addIntentResolver(COIN_WITH_BALANCE, resolveCoinBalance);
+		tx.addIntentResolver(COIN_WITH_BALANCE, resolveBalances);
 		const coinType = type === 'gas' ? type : normalizeStructTag(type);
 
 		balanceResult = tx.add(
@@ -126,6 +129,25 @@ export async function resolveCoinBalance(
 		throw new Error('Sender must be set to resolve CoinWithBalance');
 	}
 
+	if (transactionData.commands.some((command) => command.$Intent?.name === ALLOWANCE_BALANCE)) {
+		throw new Error(
+			'Resolve AllowanceBalance together with CoinWithBalance, or preserve both intents',
+		);
+	}
+	const reservedByType = new Map<string, bigint>();
+	for (const input of transactionData.inputs) {
+		if (!input.FundsWithdrawal) continue;
+		const { withdrawFrom, typeArg, reservation } = input.FundsWithdrawal;
+		const owner =
+			withdrawFrom.SenderAllowance?.funder ??
+			(withdrawFrom.Sender
+				? transactionData.sender
+				: (transactionData.gasData.owner ?? transactionData.sender));
+		if (normalizeSuiAddress(owner) !== normalizeSuiAddress(transactionData.sender)) continue;
+		const type = normalizeStructTag(typeArg.Balance);
+		reservedByType.set(type, (reservedByType.get(type) ?? 0n) + BigInt(reservation.MaxAmountU64));
+	}
+
 	// First pass: scan intents, collect per-type data, and resolve zero-balance intents in place.
 	for (const [i, command] of transactionData.commands.entries()) {
 		if (command.$kind !== '$Intent' || command.$Intent.name !== COIN_WITH_BALANCE) {
@@ -199,6 +221,7 @@ export async function resolveCoinBalance(
 					client: client!,
 					owner: transactionData.sender!,
 					usedIds,
+					reserved: reservedByType.get(coinType) ?? 0n,
 				});
 
 				coinsByType.set(coinType, coins);
@@ -211,7 +234,10 @@ export async function resolveCoinBalance(
 							coinType: SUI_TYPE,
 						})
 						.then(({ balance }) => {
-							addressBalanceByType.set('gas', BigInt(balance.addressBalance));
+							addressBalanceByType.set(
+								'gas',
+								availableAddressBalance(balance.addressBalance, reservedByType.get(SUI_TYPE) ?? 0n),
+							);
 						})
 				: null,
 		]);
@@ -462,12 +488,14 @@ async function getCoinsAndBalanceOfType({
 	client,
 	owner,
 	usedIds,
+	reserved,
 }: {
 	coinType: string;
 	balance: bigint;
 	client: ClientWithCoreApi;
 	owner: string;
 	usedIds: Set<string>;
+	reserved: bigint;
 }): Promise<{
 	coins: SuiClientTypes.Coin[];
 	balance: bigint;
@@ -477,9 +505,14 @@ async function getCoinsAndBalanceOfType({
 	let remainingBalance = balance;
 	const coins: SuiClientTypes.Coin[] = [];
 	const balanceRequest = client.core.getBalance({ owner, coinType }).then(({ balance }) => {
-		remainingBalance -= BigInt(balance.addressBalance);
-
-		return balance;
+		const addressBalance = availableAddressBalance(balance.addressBalance, reserved);
+		remainingBalance -= addressBalance;
+
+		return {
+			...balance,
+			addressBalance: String(addressBalance),
+			balance: String(BigInt(balance.balance) - reserved),
+		};
 	});
 
 	const [allCoins, balanceResponse] = await Promise.all([loadMoreCoins(), balanceRequest]);
@@ -531,3 +564,13 @@ async function getCoinsAndBalanceOfType({
 		return coins;
 	}
 }
+
+function availableAddressBalance(balance: string, reserved: bigint): bigint {
+	const available = BigInt(balance) - reserved;
+	if (available < 0n) {
+		throw new Error(
+			`Insufficient address balance for existing withdrawals. Required: ${reserved}, Available: ${balance}`,
+		);
+	}
+	return available;
+}

package/src/transactions/intents/ResolveBalances.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IntentResolverOptions } from '../resolve.js';
+import type { TransactionDataBuilder } from '../TransactionData.js';
+import { ALLOWANCE_BALANCE, COIN_WITH_BALANCE } from './BalanceIntentNames.js';
+import { resolveAllowanceBalance } from './AllowanceBalance.js';
+import { resolveCoinBalance } from './CoinWithBalance.js';
+
+export async function resolveBalances(
+	transactionData: TransactionDataBuilder,
+	options: IntentResolverOptions,
+	next: () => Promise<void>,
+) {
+	const intents = new Set(options.intentNames ?? [ALLOWANCE_BALANCE, COIN_WITH_BALANCE]);
+	const shouldResolve = (name: string) =>
+		intents.has(name) &&
+		!options.supportedIntents?.includes(name) &&
+		transactionData.commands.some((command) => command.$Intent?.name === name);
+
+	// Reserve allowance withdrawals before ordinary coin selection, including when
+	// the sender is also the funder. Keep separate intents for wallet negotiation.
+	if (shouldResolve(ALLOWANCE_BALANCE)) {
+		await resolveAllowanceBalance(transactionData, options, async () => {});
+	}
+	if (shouldResolve(COIN_WITH_BALANCE)) {
+		await resolveCoinBalance(transactionData, options, async () => {});
+	}
+	await next();
+}

package/src/transactions/resolve.ts

@@ -28,6 +28,12 @@ export interface SerializeTransactionOptions extends BuildTransactionOptions {
 	supportedIntents?: string[];
 }
 
+/** Options supplied when a registered intent resolver runs. */
+export interface IntentResolverOptions extends SerializeTransactionOptions {
+	/** Intent names assigned to this resolver for this serialization pass. */
+	intentNames?: readonly string[];
+}
+
 export type TransactionPlugin = (
 	transactionData: TransactionDataBuilder,
 	options: BuildTransactionOptions,

package/src/version.ts

@@ -3,4 +3,4 @@
 
 // This file is generated by genversion.mjs. Do not edit it directly.
 
-export const PACKAGE_VERSION = '2.30.0';
+export const PACKAGE_VERSION = '2.31.0';