@mysten/sui 2.17.0 → 2.18.0

package/docs/transactions/signing-and-execution.md

@@ -0,0 +1,401 @@
+# Signing and Execution
+
+> Sign transactions and execute them on the Sui network
+
+Once you've built a transaction, you need to sign it and submit it to the network. For background on
+how transaction signing and finality work at the protocol level, see the Sui documentation on
+[transaction lifecycle](https://docs.sui.io/concepts/transactions/transaction-lifecycle) and
+[transaction auth](https://docs.sui.io/concepts/transactions/transaction-auth).
+
+## Simulating transactions
+
+Use `simulateTransaction` to dry-run a transaction without executing it. This is useful for
+estimating gas costs, checking return values, and validating transactions before executing.
+
+```typescript
+
+const grpcClient = new SuiGrpcClient({
+	network: 'mainnet',
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+});
+
+const result = await grpcClient.simulateTransaction({
+	transaction: tx,
+	include: {
+		effects: true,
+		balanceChanges: true,
+		commandResults: true,
+	},
+});
+
+if (result.$kind === 'FailedTransaction') {
+	console.error('Simulation failed:', result.FailedTransaction.status.error?.message);
+} else {
+	console.log('Balance changes:', result.Transaction.balanceChanges);
+	console.log('Command results:', result.commandResults);
+}
+```
+
+### `include` options
+
+The `include` parameter controls what data is returned from the simulation. All fields are optional
+and default to `false`:
+
+| Field            | Description                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| `effects`        | Execution effects: created, mutated, and deleted objects, gas usage                    |
+| `events`         | Move events emitted during execution                                                   |
+| `balanceChanges` | Token balance changes for each affected address and coin type                          |
+| `objectTypes`    | Map of object ID to type string for all changed objects                                |
+| `transaction`    | The full transaction data (sender, commands, gas config)                               |
+| `bcs`            | Raw BCS-encoded transaction bytes                                                      |
+| `commandResults` | BCS-encoded return values and mutated references from each command _(simulation only)_ |
+
+The `commandResults` field is unique to simulation. It is not available on `executeTransaction`.
+Each entry contains `returnValues` and `mutatedReferences`, both as BCS-encoded `Uint8Array` values
+that you can decode with the [BCS library](/bcs).
+
+## With a keypair (backend or scripts)
+
+The simplest approach. The keypair signs the transaction and submits it to the network in one call:
+
+```typescript
+
+const keypair = Ed25519Keypair.fromSecretKey('suiprivkey1...');
+const grpcClient = new SuiGrpcClient({
+	network: 'mainnet',
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+});
+
+const result = await keypair.signAndExecuteTransaction({
+	transaction: tx,
+	client: grpcClient,
+});
+```
+
+`fromSecretKey` accepts a Bech32-encoded private key (`suiprivkey1...`) or a raw 32-byte
+`Uint8Array`. You can also use `Ed25519Keypair.deriveKeypair(mnemonic)` to derive from a mnemonic
+phrase.
+
+This method automatically sets the sender to the keypair's address, builds the transaction, signs
+it, and executes it. The result includes the transaction data and effects by default.
+
+Available keypair types:
+
+- `Ed25519Keypair` from `@mysten/sui/keypairs/ed25519`
+- `Secp256k1Keypair` from `@mysten/sui/keypairs/secp256k1`
+- `Secp256r1Keypair` from `@mysten/sui/keypairs/secp256r1`
+- `PasskeyKeypair` from `@mysten/sui/keypairs/passkey`
+
+## With dapp-kit (React frontend)
+
+In a React app, use the `useSignAndExecuteTransaction` hook. The user's connected wallet signs and
+submits the transaction:
+
+```tsx
+
+function SendButton() {
+	const { mutate: signAndExecute } = useSignAndExecuteTransaction();
+
+	function handleClick() {
+		const tx = new Transaction();
+		// ... build your transaction ...
+
+		signAndExecute(
+			{ transaction: tx },
+			{
+				onSuccess: (result) => {
+					console.log('Transaction digest:', result.digest);
+				},
+				onError: (error) => {
+					console.error('Transaction failed:', error);
+				},
+			},
+		);
+	}
+
+	return <button onClick={handleClick}>Send</button>;
+}
+```
+
+See the [dapp-kit documentation](/dapp-kit) for full setup instructions.
+
+## Sign without executing
+
+Sometimes you need the signature without immediately executing, such as for multi-sig, sponsored
+transactions, or delayed execution.
+
+### With a keypair
+
+```typescript
+// Build the transaction bytes first
+tx.setSender(keypair.toSuiAddress());
+const bytes = await tx.build({ client: grpcClient });
+
+// Sign the bytes
+const { signature } = await keypair.signTransaction(bytes);
+```
+
+### With dapp-kit
+
+```tsx
+
+function SignButton() {
+	const { mutate: signTransaction } = useSignTransaction();
+
+	function handleClick() {
+		const tx = new Transaction();
+		// ... build your transaction ...
+
+		signTransaction(
+			{ transaction: tx },
+			{
+				onSuccess: ({ bytes, signature }) => {
+					// Send bytes + signature to your backend, sponsor, etc.
+				},
+			},
+		);
+	}
+
+	return <button onClick={handleClick}>Sign</button>;
+}
+```
+
+## Manual execution
+
+When you already have the transaction bytes and signature(s), execute directly through the client:
+
+```typescript
+const result = await grpcClient.executeTransaction({
+	transaction: bytes, // Uint8Array
+	signatures: [signature], // string[]
+	include: {
+		effects: true,
+		events: true,
+		balanceChanges: true,
+		objectTypes: true,
+	},
+});
+```
+
+The `include` parameter controls what data is returned with the result:
+
+| Field            | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `transaction`    | The full transaction data (sender, commands, gas)        |
+| `effects`        | Execution effects (created, mutated, or deleted objects) |
+| `events`         | Move events emitted during execution                     |
+| `balanceChanges` | Token balance changes for each affected address          |
+| `objectTypes`    | Map of object ID to type for changed objects             |
+| `bcs`            | Raw BCS bytes of the transaction                         |
+
+## Observing results
+
+### Checking success or failure
+
+Every transaction result is a discriminated union. Always check which variant you received:
+
+```typescript
+const result = await keypair.signAndExecuteTransaction({
+	transaction: tx,
+	client: grpcClient,
+});
+
+if (result.$kind === 'FailedTransaction') {
+	const { status } = result.FailedTransaction;
+	console.error('Transaction failed:', status.error?.message);
+} else {
+	console.log('Transaction succeeded:', result.Transaction.digest);
+}
+```
+
+You can also use the shorthand:
+
+```typescript
+const tx = result.Transaction ?? result.FailedTransaction;
+if (!tx.status.success) {
+	throw new Error(`Failed: ${tx.status.error?.message}`);
+}
+```
+
+### Waiting for indexing
+
+After a transaction executes, read APIs (like `getBalance` or `getObject`) might not immediately
+show the effects. You must also wait before executing a subsequent transaction that depends on
+objects created or modified by the first one. Use `waitForTransaction` to ensure consistency:
+
+```typescript
+const result = await keypair.signAndExecuteTransaction({
+	transaction: tx,
+	client: grpcClient,
+});
+
+// Wait for the transaction to be indexed
+await grpcClient.waitForTransaction({ result });
+
+// Now reads will reflect the transaction's effects
+const { balance } = await grpcClient.getBalance({ owner: myAddress });
+```
+
+You can also wait by digest:
+
+```typescript
+await grpcClient.waitForTransaction({ digest: result.Transaction.digest });
+```
+
+## Gas configuration
+
+Every Sui transaction costs gas. The SDK handles gas automatically in most cases. It sets the gas
+price, estimates the budget, and selects how to pay. You only need to configure gas explicitly for
+special cases.
+
+### Defaults
+
+When you don't configure gas explicitly, the SDK:
+
+1. **Gas price**: Uses the network's reference gas price
+2. **Gas budget**: Simulates the transaction and uses the result to set an appropriate budget
+3. **Gas payment**: Uses address balances, falling back to coin objects when the balance is below
+   the budget
+
+For most transactions, the defaults work well and you don't need to change anything.
+
+### Explicit gas settings
+
+```typescript
+// Override the reference gas price
+tx.setGasPrice(1500);
+
+// Override the simulated budget (in MIST)
+tx.setGasBudget(50_000_000);
+```
+
+### Gas payment with coin objects
+
+Specify exactly which coins to use for gas. The system merges these coins into a single gas coin
+before execution:
+
+```typescript
+tx.setGasPayment([
+	{ objectId: '0xCoin1', version: '1', digest: 'abc...' },
+	{ objectId: '0xCoin2', version: '2', digest: 'def...' },
+]);
+```
+
+The coins you provide must not overlap with any object inputs in your transaction.
+
+### Gas payment with address balance
+
+To pay gas from your address balance instead of coin objects, pass an empty array:
+
+```typescript
+tx.setGasPayment([]);
+```
+
+This is particularly useful for [offline building](./offline) and
+[sponsored transactions](#sponsored-transactions), because there are no coin object versions to look
+up or coordinate.
+
+### The gas coin (`tx.gas`)
+
+`tx.gas` references the coin used for gas payment. You can split SUI from it, merge coins into it,
+or transfer it to another address:
+
+```typescript
+const [coin] = tx.splitCoins(tx.gas, [1_000_000_000]);
+tx.transferObjects([coin], '0xRecipientAddress');
+```
+
+> **Warning:** `tx.gas` only works when gas is paid from coin objects. If gas is paid from address balances
+> (through `setGasPayment([])`), `tx.gas` is not available. Use [`tx.coin()`](./coins-and-balances)
+> instead, which works in both cases.
+
+## Sponsored transactions
+
+In a sponsored transaction, someone other than the sender pays for gas. There are two flows
+depending on whether gas is paid from coin objects or address balances.
+
+### Coin-based sponsorship
+
+The traditional flow where the sponsor provides specific gas coin objects:
+
+```typescript
+// 1. User builds transaction kind bytes (no gas info)
+const tx = new Transaction();
+// ... add commands ...
+const kindBytes = await tx.build({ client: grpcClient, onlyTransactionKind: true });
+
+// 2. Sponsor wraps with gas info
+const sponsoredTx = Transaction.fromKind(kindBytes);
+sponsoredTx.setSender(userAddress);
+sponsoredTx.setGasOwner(sponsorAddress);
+sponsoredTx.setGasPayment(sponsorGasCoins);
+
+// 3. Build the full transaction
+const fullBytes = await sponsoredTx.build({ client: grpcClient });
+
+// 4. Both parties sign
+const { signature: userSignature } = await userKeypair.signTransaction(fullBytes);
+const { signature: sponsorSignature } = await sponsorKeypair.signTransaction(fullBytes);
+
+// 5. Execute with both signatures
+const result = await grpcClient.executeTransaction({
+	transaction: fullBytes,
+	signatures: [userSignature, sponsorSignature],
+});
+```
+
+> **Warning:** The user must wait for the sponsor to set gas coins before signing, because gas coins are part of
+> the signed transaction data.
+
+### Address balance sponsorship
+
+When the sponsor pays from their address balance instead of specific coins, the flow is simpler
+because there are no coin object references to coordinate:
+
+```typescript
+// 1. User builds and signs the transaction first
+const tx = new Transaction();
+tx.setSender(userAddress);
+tx.setGasOwner(sponsorAddress);
+tx.setGasPayment([]); // empty array = use address balance for gas
+// ... add commands ...
+
+const bytes = await tx.build({ client: grpcClient });
+const { signature: userSignature } = await userKeypair.signTransaction(bytes);
+
+// 2. Sponsor signs (can happen asynchronously)
+const { signature: sponsorSignature } = await sponsorKeypair.signTransaction(bytes);
+
+// 3. Either party executes
+const result = await grpcClient.executeTransaction({
+	transaction: bytes,
+	signatures: [userSignature, sponsorSignature],
+});
+```
+
+The key advantage: the sender can sign before the sponsor, enabling simpler async flows. No need to
+coordinate gas coin selection.
+
+### Sending tokens in sponsored transactions
+
+When building sponsored transactions, set `useGasCoin: false` so the SDK doesn't try to split the
+gas coin (which belongs to the sponsor):
+
+```typescript
+
+const tx = new Transaction();
+
+// Send to address balance (preferred)
+tx.moveCall({
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [
+		tx.balance({ balance: 1_000_000_000n, useGasCoin: false }),
+		tx.pure.address('0xRecipientAddress'),
+	],
+});
+
+// Or send as a coin object
+tx.transferObjects([tx.coin({ balance: 1_000_000_000, useGasCoin: false })], '0xRecipientAddress');
+```

package/package.json

@@ -3,7 +3,7 @@
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui TypeScript API",
   "homepage": "https://sdk.mystenlabs.com",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [
@@ -131,45 +131,45 @@
     "access": "public"
   },
   "devDependencies": {
-    "@0no-co/graphqlsp": "^1.15.2",
-    "@graphql-codegen/add": "^6.0.0",
-    "@graphql-codegen/cli": "^6.1.1",
-    "@graphql-codegen/typed-document-node": "^6.1.5",
-    "@graphql-codegen/typescript": "5.0.7",
-    "@graphql-codegen/typescript-document-nodes": "5.0.7",
-    "@graphql-codegen/typescript-operations": "^5.0.7",
-    "@grpc/grpc-js": "^1.13.3",
+    "@0no-co/graphqlsp": "^1.17.0",
+    "@graphql-codegen/add": "^7.0.1",
+    "@graphql-codegen/cli": "^7.1.2",
+    "@graphql-codegen/typed-document-node": "^7.0.3",
+    "@graphql-codegen/typescript": "6.0.2",
+    "@graphql-codegen/typescript-document-nodes": "6.0.1",
+    "@graphql-codegen/typescript-operations": "^6.0.3",
+    "@grpc/grpc-js": ">=1.14.4",
     "@parcel/watcher": "^2.5.4",
     "@protobuf-ts/grpc-transport": "^2.11.1",
-    "@types/node": "^25.0.8",
+    "@types/node": "^25.9.3",
     "@types/tmp": "^0.2.6",
     "cross-env": "^10.1.0",
     "graphql-config": "^5.1.5",
-    "msw": "^2.12.7",
-    "tmp": "^0.2.5",
+    "msw": "^2.14.6",
+    "tmp": "^0.2.7",
     "ts-retry-promise": "^0.8.1",
-    "typescript": "^5.9.3",
-    "vite": "^8.0.5",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
     "vite-tsconfig-paths": "^6.0.4",
-    "vitest": "^4.0.17",
-    "wait-on": "^9.0.3"
+    "vitest": "^4.1.8",
+    "wait-on": "^9.0.10"
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "^3.2.0",
-    "@noble/curves": "^2.0.1",
-    "@noble/hashes": "^2.0.1",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
     "@protobuf-ts/grpcweb-transport": "^2.11.1",
     "@protobuf-ts/runtime": "^2.11.1",
     "@protobuf-ts/runtime-rpc": "^2.11.1",
-    "@scure/base": "^2.0.0",
-    "@scure/bip32": "^2.0.1",
-    "@scure/bip39": "^2.0.1",
-    "gql.tada": "^1.9.0",
-    "graphql": "^16.12.0",
+    "@scure/base": "^2.2.0",
+    "@scure/bip32": "^2.2.0",
+    "@scure/bip39": "^2.2.0",
+    "gql.tada": "^1.10.1",
+    "graphql": "^16.14.2",
     "poseidon-lite": "0.2.1",
-    "valibot": "^1.2.0",
-    "@mysten/bcs": "^2.0.5",
-    "@mysten/utils": "^0.3.3"
+    "valibot": "^1.4.1",
+    "@mysten/utils": "^0.4.0",
+    "@mysten/bcs": "^2.1.0"
   },
   "scripts": {
     "clean": "rm -rf tsconfig.tsbuildinfo ./dist",

package/src/transactions/Transaction.ts

@@ -139,6 +139,17 @@ type TransactionLike = {
 	getData(): unknown;
 };
 
+export interface TransactionCopyOptions {
+	/**
+	 * A map of intent names to resolvers for any custom intents used in the transaction being copied.
+	 *
+	 * Built-in intents (such as `CoinWithBalance`) are handled automatically. Providing resolvers for
+	 * custom intents lets `Transaction.from` copy a transaction synchronously even when it still
+	 * contains unresolved intents, without first awaiting `prepareForSerialization`.
+	 */
+	intentResolvers?: Record<string, TransactionPlugin>;
+}
+
 /**
  * Transaction Builder
  */
@@ -175,8 +186,15 @@ export class Transaction {
 	 * There are two supported serialized formats:
 	 * - A string returned from `Transaction#serialize`. The serialized format must be compatible, or it will throw an error.
 	 * - A byte array (or base64-encoded bytes) containing BCS transaction data.
+	 *
+	 * When copying an in-memory transaction that uses custom intents, pass resolvers for those intents
+	 * via `options.intentResolvers` so the copy can be created synchronously without first awaiting
+	 * `prepareForSerialization`. Built-in intents (such as `CoinWithBalance`) are handled automatically.
 	 */
-	static from(transaction: string | Uint8Array | TransactionLike) {
+	static from(
+		transaction: string | Uint8Array | TransactionLike,
+		options: TransactionCopyOptions = {},
+	) {
 		const newTransaction = new Transaction();
 
 		if (isTransaction(transaction)) {
@@ -195,14 +213,27 @@ export class Transaction {
 		newTransaction.#commandSection = newTransaction.#data.commands.slice();
 		newTransaction.#availableResults = new Set(newTransaction.#commandSection.map((_, i) => i));
 
-		if (!newTransaction.isPreparedForSerialization({ supportedIntents: [COIN_WITH_BALANCE] })) {
+		// Built-in intents are resolvable by default. Caller-supplied resolvers cover custom intents,
+		// and take precedence so a built-in resolver can be overridden if needed.
+		const intentResolvers = new Map<string, TransactionPlugin>([
+			[COIN_WITH_BALANCE, resolveCoinBalance],
+			...Object.entries(options.intentResolvers ?? {}),
+		]);
+
+		if (
+			!newTransaction.isPreparedForSerialization({
+				supportedIntents: [...intentResolvers.keys()],
+			})
+		) {
 			throw new Error(
-				'Transaction has unresolved intents or async thunks. Call `prepareForSerialization` before copying.',
+				'Transaction has unresolved intents or async thunks. Provide resolvers for any custom intents via the `intentResolvers` option, or call `prepareForSerialization` before copying.',
 			);
 		}
 
-		if (newTransaction.#data.commands.some((cmd) => cmd.$Intent?.name === COIN_WITH_BALANCE)) {
-			newTransaction.addIntentResolver(COIN_WITH_BALANCE, resolveCoinBalance);
+		// Register every resolver so the copy can resolve its intents on build. Resolvers for intents
+		// that aren't present are harmless — a resolver only runs when its intent appears in the data.
+		for (const [intent, resolver] of intentResolvers) {
+			newTransaction.addIntentResolver(intent, resolver);
 		}
 
 		return newTransaction;

package/src/transactions/index.ts

@@ -17,6 +17,7 @@ export {
 	type TransactionObjectInput,
 	type TransactionObjectArgument,
 	type TransactionResult,
+	type TransactionCopyOptions,
 } from './Transaction.js';
 
 export { type SerializedTransactionDataV2 } from './data/v2.js';

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.17.0';
+export const PACKAGE_VERSION = '2.18.0';

package/src/zklogin/jwt-utils.ts

@@ -116,6 +116,9 @@ export function extractClaimValue<R>(claim: Claim, claimName: string): R {
 	return value;
 }
 
+// TODO: root cause of the claim-escaping bug — jwtDecode resolves JSON escapes, but the
+// circuit derives the address seed from raw JWT bytes, so escaped claim values decode
+// differently here than the circuit hashes. Real fix: parse claims over raw bytes.
 export function decodeJwt(jwt: string): Omit<JwtPayload, 'iss' | 'aud' | 'sub'> & {
 	iss: string;
 	aud: string;

package/src/zklogin/utils.ts

@@ -87,6 +87,20 @@ export function hashASCIIStrToField(str: string, maxSize: number) {
 	return poseidonHash(packed);
 }
 
+// Reject claim inputs whose decoded form reveals a JSON escape ('"', '\', control char):
+// the circuit hashes raw JWT bytes, so an escaped value would derive a different address.
+function assertNoJsonEscape(value: string, label: string) {
+	for (let i = 0; i < value.length; i++) {
+		const c = value.charCodeAt(i);
+		if (c < 0x20 || c === 0x22 || c === 0x5c) {
+			throw new Error(
+				`zkLogin ${label} contains a JSON-escaped character (code ${c}); the circuit ` +
+					`hashes raw JWT bytes, so claim values with escapes are not supported`,
+			);
+		}
+	}
+}
+
 export function genAddressSeed(
 	salt: string | bigint,
 	name: string,
@@ -96,6 +110,9 @@ export function genAddressSeed(
 	max_value_length = MAX_KEY_CLAIM_VALUE_LENGTH,
 	max_aud_length = MAX_AUD_VALUE_LENGTH,
 ): bigint {
+	assertNoJsonEscape(name, 'key claim name');
+	assertNoJsonEscape(value, 'key claim value');
+	assertNoJsonEscape(aud, 'aud');
 	return poseidonHash([
 		hashASCIIStrToField(name, max_name_length),
 		hashASCIIStrToField(value, max_value_length),

package/docs/faucet.md

@@ -1,26 +0,0 @@
-# Faucet
-
-> Request test SUI tokens from the faucet on Devnet, Testnet, or local networks.
-
-Devnet, Testnet, and local networks include faucets that mint SUI. You can use the Sui TypeScript
-SDK to call a network's faucet and provide SUI to the address you provide.
-
-To request SUI from a faucet, import the `requestSuiFromFaucetV2` function from the
-`@mysten/sui/faucet` package to your project.
-
-```typescript
-
-```
-
-Use `requestSuiFromFaucetV2` in your TypeScript code to request SUI from the network's faucet.
-
-```typescript
-await requestSuiFromFaucetV2({
-	host: getFaucetHost('testnet'),
-	recipient: <RECIPIENT_ADDRESS>,
-});
-```
-
-> **Note:** Faucets on Devnet and Testnet are rate limited. If you run the script too many times, you surpass
-> the limit and must wait to successfully run it again. For Testnet, the best way to get SUI is
-> through the Web UI: `faucet.sui.io`.