@mysten/sui 2.30.0 → 2.31.1

package/docs/transactions/allowances.md

@@ -0,0 +1,176 @@
+# Allowances
+
+> Create allowances and spend from another account's address balance
+
+An [allowance](https://docs.sui.io/references/framework/sui_sui/allowance) lets a **spender** use a
+**funder's** address balance, subject to spending limits. The spender signs transactions that use
+it. The network must have allowance support enabled (protocol v137 or later).
+
+## Creating an allowance
+
+This non-app allowance permits up to 100 USDC of spending over 24 hours. `funder` is the signer
+creating the allowance. Replace `0xUsdcPackage::usdc::USDC` with your network's USDC type; amounts
+use its six decimal places.
+
+```tsx
+
+const USDC = '0xUsdcPackage::usdc::USDC';
+const balanceType = `0x2::balance::Balance<${USDC}>`;
+const expirationMs = BigInt(Date.now() + 24 * 60 * 60 * 1000);
+const tx = new Transaction();
+
+// RateLimit is a Move type, so construct its empty option with a Move call.
+const noRateLimit = tx.moveCall({
+	target: '0x1::option::none',
+	typeArguments: ['0x2::allowance::RateLimit'],
+});
+
+tx.moveCall({
+	target: '0x2::allowance::new',
+	typeArguments: [balanceType],
+	arguments: [
+		tx.pure.string('USDC spending allowance'),
+		tx.pure.address(spenderAddress),
+		tx.pure.option('u256', 100_000_000n), // Lifetime cap: 100 USDC
+		tx.pure.option('u64', null), // No delayed start
+		tx.pure.option('u64', expirationMs),
+		noRateLimit,
+	],
+});
+
+const result = await client.core.signAndExecuteTransaction({
+	transaction: tx,
+	signer: funder,
+	include: { effects: true },
+});
+
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(result.FailedTransaction.status.error?.message ?? 'Allowance creation failed');
+}
+
+// This transaction creates one shared object: the allowance.
+const allowance = result.Transaction.effects!.changedObjects.find(
+	(change) => change.idOperation === 'Created' && change.outputOwner?.$kind === 'Shared',
+);
+if (!allowance) throw new Error('No allowance was created');
+
+const allowanceId = allowance.objectId;
+await client.core.waitForTransaction({ digest: result.Transaction.digest });
+// Give allowanceId to the spender.
+```
+
+`allowance::new` takes `Balance<USDC>` as its type argument; the spending helpers take `USDC`.
+Creation also sends the funder an `AllowanceCap`, which can revoke the allowance.
+
+Creating an allowance does not reserve or deposit funds. The funder must have enough USDC in its
+[address balance](https://docs.sui.io/onchain-finance/asset-custody/address-balances/using-address-balances#sending-funds)
+when the spender withdraws.
+
+### Limits and expiration
+
+An allowance requires both a lifetime cap and an expiration, unless it has a recurring rate limit.
+Lifetime caps must be positive `u256` amounts. Start and expiration times use Unix milliseconds; if
+both are set, the start must be earlier. Names can be at most 128 bytes.
+
+For recurring spending, use `allowance::periodic_rate_limit(period_ms, limit)` or
+`allowance::monthly_rate_limit(limit)`. Wrap the result in `0x1::option::some<RateLimit>` and pass
+it as the last argument to `allowance::new`. A rate limit can replace the lifetime cap and
+expiration, or apply alongside them.
+
+## Spending from an allowance
+
+Pass the shared allowance ID and sign with the spender's key:
+
+```tsx
+
+const USDC = '0xUsdcPackage::usdc::USDC';
+const tx = new Transaction();
+const balance = tx.balance({
+	allowance: '0xAllowanceId',
+	balance: 10_000_000n, // 10 USDC
+	type: USDC,
+});
+
+tx.moveCall({
+	target: '0xPackage::pool::deposit',
+	typeArguments: [USDC],
+	arguments: [tx.object('0xPoolId'), balance],
+});
+
+await client.core.signAndExecuteTransaction({ transaction: tx, signer: spender });
+```
+
+Use `tx.coin()` instead when the next operation expects a `Coin<T>`. Both helpers default to SUI, so
+pass `type: USDC` explicitly. Each amount must fit in a `u64`.
+
+The SDK looks up the funder from the allowance ID. Spending draws only from that funder's address
+balance and must satisfy the allowance's limits and expiration. The sender or a sponsor must pay gas
+separately; do not combine `allowance` with `useGasCoin`.
+
+### Using a known funder
+
+Pass the funder alongside the ID to skip the allowance lookup:
+
+```tsx
+
+const USDC = '0xUsdcPackage::usdc::USDC';
+const tx = new Transaction();
+const coin = tx.coin({
+	allowance: { objectId: '0xAllowanceId', funder: '0xFunderAddress' },
+	balance: 10_000_000n, // 10 USDC
+	type: USDC,
+});
+tx.transferObjects([coin], '0xRecipientAddress');
+```
+
+This skips the SDK's coin type and app binding checks; incorrect references fail on-chain. Building
+may still need a client to resolve object versions and gas.
+
+## App-bound allowances
+
+App-bound allowances require a `SpendPermit<A>` from the app as well as the spender's signature.
+Pass the permit and app type to `tx.balance()` or `tx.coin()`:
+
+```tsx
+
+const USDC = '0xUsdcPackage::usdc::USDC';
+const tx = new Transaction();
+const permit = tx.moveCall({
+	target: '0xAppPackage::subscriptions::authorize_payment',
+	arguments: [tx.object('0xSubscriptionId')],
+});
+const balance = tx.balance({
+	balance: 10_000_000n, // 10 USDC
+	type: USDC,
+	allowance: {
+		objectId: '0xAllowanceId',
+		app: { type: '0xAppPackage::subscriptions::APP', permit },
+	},
+});
+// Pass balance to the app's next operation.
+```
+
+To create an app-bound allowance, the funder calls `allowance::propose_for_app`. The app accepts the
+proposal through `allowance::issue` with a `SettingsPermit<A>`.
+
+The authorization function and its arguments are defined by the app. The SDK handles the framework's
+`app_balance_spend` call. Add `funder` to the allowance reference to skip the metadata lookup.
+
+A permit authorizes one spend but does not bind its amount or recipient. Apps that need to enforce
+those must redeem the withdrawal inside their own Move function, using `tx.withdrawal()` as the
+input.
+
+```tsx
+
+const tx = new Transaction();
+const withdrawal = tx.withdrawal({
+	amount: 10_000_000n,
+	type: '0xUsdcPackage::usdc::USDC',
+	from: 'allowance',
+	allowance: '0xAllowanceId',
+	funder: '0xFunderAddress',
+});
+// Pass withdrawal to the app's Move function that redeems it.
+```
+
+`from: 'allowance'` requires both `allowance` and `funder`; this helper does not look them up.

package/docs/transactions/coins-and-balances.md

@@ -20,7 +20,8 @@ invalidated by other transactions from the same address executing concurrently.
 ## `tx.coin` and `tx.balance`
 
 `tx.coin()` and `tx.balance()` are the recommended ways to get tokens in a transaction. They
-automatically draw from both coin objects and address balances.
+automatically draw from both coin objects and address balances. To spend funds authorized by another
+account, see [Allowances](./allowances.mdx).
 
 ### Getting a `Coin`
 
@@ -74,11 +75,11 @@ tx.moveCall({
 
 ### Options
 
-| Option       | Type               | Default    | Description                                                              |
-| ------------ | ------------------ | ---------- | ------------------------------------------------------------------------ |
-| `balance`    | `bigint \| number` | _required_ | Amount in base units (MIST for SUI)                                      |
-| `type`       | `string`           | SUI        | Coin type. Defaults to `0x2::sui::SUI`                                   |
-| `useGasCoin` | `boolean`          | `true`     | For SUI, split from the gas coin. Set `false` for sponsored transactions |
+| Option       | Type                         | Default    | Description                                                                             |
+| ------------ | ---------------------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `balance`    | `bigint \| number \| string` | _required_ | Amount in base units (MIST for SUI); use safe integer numbers or bigint/decimal strings |
+| `type`       | `string`                     | SUI        | Coin type T, not Balance<T>. Defaults to `0x2::sui::SUI`                          |
+| `useGasCoin` | `boolean`                    | `true`     | For SUI, allow splitting the gas coin. Set `false` for sponsored transactions           |
 
 For SUI, `tx.coin()` splits from the gas coin by default. For sponsored transactions where the gas
 coin belongs to the sponsor, set `useGasCoin: false`:
@@ -89,7 +90,7 @@ tx.transferObjects([tx.coin({ balance: 100n, useGasCoin: false })], recipient);
 
 ### `coinWithBalance`
 
-`coinWithBalance()` is a standalone alias for `tx.coin()`:
+`coinWithBalance()` is a standalone helper for sender-funded coins:
 
 ```tsx
 
@@ -100,7 +101,8 @@ tx.transferObjects([coinWithBalance({ balance: 1_000_000_000 })], recipient);
 ## How resolution works
 
 When you call `tx.coin()` or `tx.balance()`, the SDK adds a placeholder intent to the transaction.
-At build time, the resolver replaces it with concrete commands based on the sender's funds:
+For sender-funded requests, the resolver replaces it at build time with concrete commands based on
+the sender's funds:
 
 - **`tx.balance()` with sufficient address balance:** Uses a direct `FundsWithdrawal` through
   `balance::redeem_funds`. No coin objects are used, so the transaction has no versioned object
@@ -115,7 +117,8 @@ At build time, the resolver replaces it with concrete commands based on the send
 The resolver prefers address balances when possible to avoid introducing versioned object
 dependencies.
 
-Zero-balance requests resolve to `balance::zero` or `coin::zero` with no network lookups.
+Sender-funded zero-balance requests resolve to `balance::zero` or `coin::zero` with no network
+lookups.
 
 ## Checking balances
 

package/package.json

@@ -3,7 +3,7 @@
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui TypeScript API",
   "homepage": "https://sdk.mystenlabs.com",
-  "version": "2.30.0",
+  "version": "2.31.1",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [

package/src/bcs/bcs.ts

@@ -96,6 +96,10 @@ export const WithdrawalType = bcs.enum('WithdrawalType', {
 export const WithdrawFrom = bcs.enum('WithdrawFrom', {
 	Sender: null,
 	Sponsor: null,
+	SenderAllowance: bcs.struct('SenderAllowance', {
+		funder: Address,
+		allowance: Address,
+	}),
 });
 
 // Rust: crates/sui-types/src/transaction.rs

package/src/bcs/types.ts

@@ -44,7 +44,8 @@ export function isPureArg(arg: any): arg is PureArg {
 
 type Reservation = { MaxAmountU64: number | string };
 type WithdrawalTypeArg = { Balance: TypeTag };
-type WithdrawFrom = { Sender: null } | { Sponsor: null };
+type WithdrawFrom =
+	{ Sender: null } | { Sponsor: null } | { SenderAllowance: { funder: string; allowance: string } };
 type FundsWithdrawalArg = {
 	reservation: Reservation;
 	typeArg: WithdrawalTypeArg;

package/src/client/core-resolver.ts

@@ -22,6 +22,9 @@ import { transactionUsesGasCoin } from '../transactions/resolution-utils.js';
 // The maximum objects that can be fetched at once using multiGetObjects.
 const MAX_OBJECTS_PER_FETCH = 50;
 
+// The gas payment limit is inclusive as of protocol version 96.
+const MAX_GAS_PAYMENT_OBJECTS = 256;
+
 // An amount of gas (in gas units) that is added to transactions as an overhead to ensure transactions do not fail.
 const GAS_SAFE_OVERHEAD = 1000n;
 const MAX_GAS = 50_000_000_000;
@@ -66,10 +69,12 @@ export async function coreClientResolveTransactionPlugin(
 	for (const input of transactionData.inputs) {
 		if (input.$kind !== 'FundsWithdrawal' || !normalizedGasPayer) continue;
 		if (normalizeStructTag(input.FundsWithdrawal.typeArg.Balance) !== SUI_TYPE_ARG) continue;
-
-		const withdrawalOwner = input.FundsWithdrawal.withdrawFrom.Sender
-			? transactionData.sender
-			: gasPayer;
+		const source = input.FundsWithdrawal.withdrawFrom;
+		const withdrawalOwner = source.SenderAllowance
+			? source.SenderAllowance.funder
+			: source.Sender
+				? transactionData.sender
+				: gasPayer;
 		if (
 			withdrawalOwner &&
 			normalizeSuiAddress(withdrawalOwner) === normalizedGasPayer &&
@@ -235,12 +240,13 @@ function setGasPayment({
 	if (usesGasCoin && reservationAmount > 0n && chainIdentifier && epoch) {
 		transactionData.gasData.payment = [
 			createCoinReservationRef(reservationAmount, gasPayer, chainIdentifier, epoch),
-			...paymentCoins,
+			// The reservation occupies one entry in the gas payment limit.
+			...paymentCoins.slice(0, MAX_GAS_PAYMENT_OBJECTS - 1),
 		];
 	} else if (!filteredCoins.length) {
 		throw new Error('No valid gas coins found for the transaction.');
 	} else {
-		transactionData.gasData.payment = paymentCoins;
+		transactionData.gasData.payment = paymentCoins.slice(0, MAX_GAS_PAYMENT_OBJECTS);
 	}
 }
 

package/src/client/transaction-resolver.ts

@@ -20,7 +20,7 @@ import {
 	TransactionExpiration_TransactionExpirationKind,
 } from '../grpc/proto/sui/rpc/v2/transaction.js';
 import type { ObjectReference } from '../grpc/proto/sui/rpc/v2/object_reference.js';
-import type { Input } from '../grpc/proto/sui/rpc/v2/input.js';
+import type { FundsWithdrawal, Input } from '../grpc/proto/sui/rpc/v2/input.js';
 import { FundsWithdrawal_Source, Input_InputKind } from '../grpc/proto/sui/rpc/v2/input.js';
 import type { Command } from '../grpc/proto/sui/rpc/v2/transaction.js';
 import type { Argument } from '../grpc/proto/sui/rpc/v2/argument.js';
@@ -102,10 +102,7 @@ function callArgToGrpcInput(arg: CallArg): Input {
 							? BigInt(withdrawal.reservation.MaxAmountU64)
 							: undefined,
 					coinType: withdrawal.typeArg.$kind === 'Balance' ? withdrawal.typeArg.Balance : undefined,
-					source:
-						withdrawal.withdrawFrom.$kind === 'Sponsor'
-							? FundsWithdrawal_Source.SPONSOR
-							: FundsWithdrawal_Source.SENDER,
+					...tsWithdrawFromToGrpc(withdrawal.withdrawFrom),
 				},
 			};
 		}
@@ -115,6 +112,46 @@ function callArgToGrpcInput(arg: CallArg): Input {
 	}
 }
 
+function tsWithdrawFromToGrpc(
+	withdrawFrom: Extract<CallArg, { FundsWithdrawal: unknown }>['FundsWithdrawal']['withdrawFrom'],
+): Pick<FundsWithdrawal, 'source' | 'funder' | 'allowance'> {
+	switch (withdrawFrom.$kind) {
+		case 'Sender':
+			return { source: FundsWithdrawal_Source.SENDER };
+		case 'Sponsor':
+			return { source: FundsWithdrawal_Source.SPONSOR };
+		case 'SenderAllowance':
+			return {
+				source: FundsWithdrawal_Source.SENDER_ALLOWANCE,
+				funder: withdrawFrom.SenderAllowance.funder,
+				allowance: withdrawFrom.SenderAllowance.allowance,
+			};
+		default:
+			throw new Error(`Unknown WithdrawFrom kind: ${JSON.stringify(withdrawFrom)}`);
+	}
+}
+
+function grpcWithdrawFromToTs(
+	withdrawal: FundsWithdrawal | undefined,
+): Extract<CallArg, { FundsWithdrawal: unknown }>['FundsWithdrawal']['withdrawFrom'] {
+	switch (withdrawal?.source) {
+		case FundsWithdrawal_Source.SPONSOR:
+			return { $kind: 'Sponsor', Sponsor: true };
+		case FundsWithdrawal_Source.SENDER_ALLOWANCE:
+			if (!withdrawal.funder || !withdrawal.allowance) {
+				throw new Error(
+					`SENDER_ALLOWANCE withdrawal is missing funder or allowance: ${JSON.stringify(withdrawal)}`,
+				);
+			}
+			return {
+				$kind: 'SenderAllowance',
+				SenderAllowance: { funder: withdrawal.funder, allowance: withdrawal.allowance },
+			};
+		default:
+			return { $kind: 'Sender', Sender: true };
+	}
+}
+
 /**
  * Converts a TypeScript Argument to gRPC Argument
  */
@@ -429,10 +466,7 @@ function grpcInputToCallArg(input: Input): CallArg {
 						$kind: 'Balance' as const,
 						Balance: input.fundsWithdrawal?.coinType ?? '0x2::sui::SUI',
 					},
-					withdrawFrom:
-						input.fundsWithdrawal?.source === FundsWithdrawal_Source.SPONSOR
-							? { $kind: 'Sponsor' as const, Sponsor: true as const }
-							: { $kind: 'Sender' as const, Sender: true as const },
+					withdrawFrom: grpcWithdrawFromToTs(input.fundsWithdrawal),
 				},
 			};