@mysten/sui 2.29.0 → 2.31.0

package/docs/transactions/offline.md

@@ -2,69 +2,132 @@
 
 > Build transactions without a network connection
 
-Normally the SDK resolves object versions, estimates gas, and fills in other details by querying the
-network. For offline building of backend services, air-gapped signing, or pre-built transactions,
-you must provide this information yourself. See also the Sui documentation on
+Normally `build()` queries the network to resolve object versions, resolve intents like `tx.coin()`,
+fetch the gas price, estimate the gas budget, pick gas coins, and set an expiration when gas is paid
+from address balance. To build without a client, provide that information yourself. See also the Sui
+documentation on
 [offline signing](https://docs.sui.io/guides/developer/transactions/transaction-auth/offline-signing)
 for the protocol-level details.
 
-## Transactions without owned object inputs
+## Building only the transaction kind
 
-When your transaction only uses shared objects, party objects, and/or address balance withdrawals,
-there are no owned object versions to look up. Use `tx.withdrawal()` directly instead of `tx.coin()`
-or `coinWithBalance` because they require a client to resolve coin objects at build time.
+If the next step only needs the inputs and commands (for example, a sponsor or a backend that fills
+in gas), build with `onlyTransactionKind`. Sender, gas data, and expiration are left out:
 
 ```typescript
 
 const tx = new Transaction();
-
-// Use tx.withdrawal() + coin::redeem_funds to withdraw from address balance.
-// No coin object lookups needed — fully offline.
-const [coin] = tx.moveCall({
-	target: '0x2::coin::redeem_funds',
-	typeArguments: ['0x2::sui::SUI'],
-	arguments: [tx.withdrawal({ amount: 1_000_000_000 })],
+tx.moveCall({
+	target: '0xPackage::module::function',
+	arguments: [tx.pure.u64(100)],
 });
-tx.transferObjects([coin], '0xRecipientAddress');
 
-// Shared/party objects only need objectId + initialSharedVersion (both stable)
+const kindBytes = await tx.build({ onlyTransactionKind: true });
+```
+
+Inputs and intents still need to be resolved. Use full object references, `tx.withdrawal()`, or
+[`assumeSufficientAddressBalances`](#coin-and-balance-intents) so nothing needs a lookup.
+
+## Building full transaction bytes
+
+A full offline build needs the sender and all gas data:
+
+| Method            | Description                                                     |
+| ----------------- | --------------------------------------------------------------- |
+| `setSender()`     | The address executing the transaction                           |
+| `setGasPrice()`   | Reference gas price (query `getReferenceGasPrice()` beforehand) |
+| `setGasBudget()`  | Maximum gas to spend (in MIST). Estimating it requires a client |
+| `setGasPayment()` | Coin object references, or `[]` to pay gas from address balance |
+| `setGasOwner()`   | Only for sponsored transactions. Defaults to the sender         |
+
+### Paying gas from address balance
+
+With `setGasPayment([])`, gas is paid from the gas owner's SUI address balance. Nothing ties the
+transaction to a specific object version, so it also needs a `ValidDuring` expiration for replay
+protection:
+
+```typescript
+
+// Look these up before going offline
+const referenceGasPrice = 1000n;
+const currentEpoch = 100;
+const chainIdentifier = 'Base58ChainIdentifier'; // from getChainIdentifier()
+
+const tx = new Transaction();
+
+// FundsWithdrawal inputs contain the amount and type, so no object lookup is needed
 tx.moveCall({
-	target: '0xPackage::module::function',
-	arguments: [
-		tx.sharedObjectRef({
-			objectId: '0xSharedObjectId',
-			initialSharedVersion: '1',
-			mutable: true,
-		}),
-	],
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.withdrawal({ amount: 1_000_000_000 }), tx.pure.address('0xRecipientAddress')],
 });
 
-// Required configuration for all offline builds
 tx.setSender('0xSenderAddress');
-tx.setGasPrice(1000); // query getReferenceGasPrice() beforehand, or use a known value
+tx.setGasPrice(referenceGasPrice);
 tx.setGasBudget(50_000_000);
-tx.setGasPayment([]); // empty array = pay gas from address balance
+tx.setGasPayment([]);
 
-// Expiration is required when there are no owned objects for gas or inputs
 tx.setExpiration({
 	ValidDuring: {
-		minEpoch: 100, // current epoch
-		maxEpoch: 101, // current epoch + 1
+		minEpoch: currentEpoch,
+		maxEpoch: currentEpoch + 1,
 		minTimestamp: null,
 		maxTimestamp: null,
-		chain: 'mainnet', // or 'testnet', 'devnet'
-		nonce: 0,
+		chain: chainIdentifier,
+		// Must be unique for each transaction in the validity window, including across restarts
+		nonce: await nonceStore.next(),
 	},
 });
 
-// Build without a client
 const bytes = await tx.build();
 ```
 
-This enables fully stateless construction. You only need the sender address, reference gas price,
-epoch, and chain identifier.
+Two otherwise-identical transactions with the same nonce have the same digest, and the second one is
+rejected as a duplicate. Use a counter that survives restarts, not a hard-coded value.
+
+The address balance needs to cover the gas budget on top of any withdrawals. Don't add the budget to
+the withdrawal amount.
+
+`{ Epoch: n }` expiration does not provide replay protection. Use `ValidDuring`.
 
-## Party objects
+### Paying gas with coin objects
+
+Gas coins need an exact version and digest. Other SUI can still come from address balance:
+
+```typescript
+
+const tx = new Transaction();
+tx.moveCall({
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [
+		tx.balance({ balance: 1_000_000, useGasCoin: false }),
+		tx.pure.address('0xRecipientAddress'),
+	],
+});
+
+tx.setSender('0xSenderAddress');
+tx.setGasPrice(1000);
+tx.setGasBudget(50_000_000);
+tx.setGasPayment([{ objectId: '0xGasCoinId', version: '3', digest: 'Base58GasCoinDigest' }]);
+
+// assumeSufficientAddressBalances resolves tx.balance() without a client (see below)
+const bytes = await tx.build({ assumeSufficientAddressBalances: true });
+```
+
+## Object inputs
+
+### Shared and party objects
+
+Shared objects only need `objectId` and `initialSharedVersion`, both of which are stable:
+
+```typescript
+tx.sharedObjectRef({
+	objectId: '0xSharedObjectId',
+	initialSharedVersion: '1',
+	mutable: true,
+});
+```
 
 Party objects are address-owned but consensus-versioned, with per-address permissions. They are
 referenced the same way as shared objects:
@@ -83,12 +146,11 @@ Key properties for offline building:
   becomes a party object
 - **Enable pipelining**: Submit multiple transactions on the same party object without waiting for
   each one to finalize
-- **Cannot be used for gas**: Use address balance for gas payment (`setGasPayment([])`)
+- **Cannot be used for gas**: Pay gas from address balance or with a SUI coin object
 
-## Transactions with owned object inputs
+### Owned and immutable objects
 
-When your transaction uses owned or immutable objects, you must provide the exact version and digest
-for each one:
+Owned and immutable objects need the exact version and digest:
 
 ```typescript
 
@@ -122,71 +184,58 @@ tx.moveCall({
 		}),
 	],
 });
-
-// Gas payment with specific coin objects
-tx.setGasPayment([{ objectId: '0xGasCoinId', version: '3', digest: 'jkl012...' }]);
-
-tx.setSender('0xSenderAddress');
-tx.setGasPrice(1000);
-tx.setGasBudget(50_000_000);
-
-const bytes = await tx.build();
 ```
 
-## Required configuration for all offline builds
+## Coin and balance intents
 
-Every offline-built transaction must have the following:
+`tx.coin()` and `tx.balance()` normally look up the sender's address balance and coin objects. Pass
+`assumeSufficientAddressBalances` to skip the lookups and withdraw from address balance instead:
 
-| Method            | Description                                                     |
-| ----------------- | --------------------------------------------------------------- |
-| `setSender()`     | The address executing the transaction                           |
-| `setGasPrice()`   | Reference gas price (query `getReferenceGasPrice()` beforehand) |
-| `setGasBudget()`  | Maximum gas to spend (in MIST)                                  |
-| `setGasPayment()` | Coin object references, or `[]` for address balance             |
+```typescript
 
-### Expiration
+const tx = new Transaction();
+tx.moveCall({
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0xPackage::module::TOKEN'],
+	arguments: [
+		tx.balance({ type: '0xPackage::module::TOKEN', balance: 1_000_000 }),
+		tx.pure.address('0xRecipientAddress'),
+	],
+});
 
-Set an expiration when your transaction uses no owned objects for gas or inputs. This applies when
-you use address balances for gas (`setGasPayment([])`) with only shared and party object inputs:
+// The sender is still required, since the withdrawal comes from its address balance
+tx.setSender('0xSenderAddress');
 
-```typescript
-tx.setExpiration({
-	ValidDuring: {
-		minEpoch: 100, // current epoch
-		maxEpoch: 101, // typically current epoch + 1
-		minTimestamp: null,
-		maxTimestamp: null,
-		chain: 'mainnet',
-		nonce: 0, // increment for multiple transactions in the same epoch
-	},
+const kindBytes = await tx.build({
+	onlyTransactionKind: true,
+	assumeSufficientAddressBalances: true,
 });
 ```
 
-You can also use epoch-based expiration:
+> **Warning:** Nothing is checked. The transaction builds, then fails at execution if the address balance doesn't
+> cover it.
 
-```typescript
-tx.setExpiration({ Epoch: 100 });
-```
+SUI intents withdraw from address balance too, whether or not the transaction also uses `tx.gas`.
+This matches an online build when the address balance is sufficient. Mixing default and
+`useGasCoin: false` SUI intents in one transaction is still an error.
 
-> **Note:** When building with a client, the SDK sets expiration automatically. You only need the manual
-> configuration above for fully offline builds.
+On a full build, the option also sets an unset gas payment to `[]`, but only when nothing else needs
+a client, the transaction doesn't use `tx.gas`, and a `ValidDuring` or `Validity` expiration is
+already set. Sender, gas price, and gas budget still need to be provided. Once set, the empty
+payment is part of the transaction, the same as calling `setGasPayment([])`.
 
 ## Serialization
 
-### Building to bytes
+`toJSON()` resolves async thunks and intents but does not fill in gas or object versions. Pass
+`supportedIntents` to keep an intent for another system to resolve:
 
 ```typescript
-// Build to BCS bytes (Uint8Array) — fully offline, all data must be provided
-const bytes = await tx.build();
-
-// Build with a client — only makes network requests when there is unresolved data to look up
-const bytes = await tx.build({ client: grpcClient });
-```
+// Intents are resolved, so tx.coin() needs a client or assumeSufficientAddressBalances
+const json = await tx.toJSON({ assumeSufficientAddressBalances: true });
+const restored = Transaction.from(json);
 
-### Converting bytes back to a Transaction
-
-```typescript
-const tx = Transaction.from(bytes);
+// Or keep tx.coin() intents for the receiver to resolve
+const jsonWithIntents = await tx.toJSON({ supportedIntents: ['CoinWithBalance'] });
 ```
 
-This works with BCS byte arrays, base64-encoded strings, and JSON strings (from `toJSON()`).
+`Transaction.from()` accepts JSON strings, BCS bytes, and base64-encoded BCS.

package/package.json

@@ -3,7 +3,7 @@
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui TypeScript API",
   "homepage": "https://sdk.mystenlabs.com",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [
@@ -151,7 +151,7 @@
     "typescript": "^7.0.2",
     "vite": "^8.2.1",
     "vite-tsconfig-paths": "^6.0.4",
-    "vitest": "^4.1.10",
+    "vitest": "^4.1.11",
     "wait-on": "^9.1.0"
   },
   "dependencies": {

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

@@ -17,6 +17,7 @@ import { getPureBcsSchema, isTxContext } from '../transactions/serializer.js';
 import type { TransactionDataBuilder } from '../transactions/TransactionData.js';
 import { chunk } from '@mysten/utils';
 import type { BuildTransactionOptions } from '../transactions/index.js';
+import { transactionUsesGasCoin } from '../transactions/resolution-utils.js';
 
 // The maximum objects that can be fetched at once using multiGetObjects.
 const MAX_OBJECTS_PER_FETCH = 50;
@@ -54,27 +55,23 @@ export async function coreClientResolveTransactionPlugin(
 	next: () => Promise<void>,
 ) {
 	const client = getClient(options);
-
 	const needsGasPrice = !options.onlyTransactionKind && !transactionData.gasData.price;
 	const needsPayment = !options.onlyTransactionKind && !transactionData.gasData.payment;
 	const gasPayer = transactionData.gasData.owner ?? transactionData.sender;
 
-	let usesGasCoin = false;
+	const usesGasCoin = transactionUsesGasCoin(transactionData);
 	let withdrawals = 0n;
 
-	transactionData.mapArguments((arg) => {
-		if (arg.$kind === 'GasCoin') usesGasCoin = true;
-		return arg;
-	});
-
 	const normalizedGasPayer = gasPayer ? normalizeSuiAddress(gasPayer) : null;
 	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 &&

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),
 				},
 			};