@mysten/sui 2.17.0 → 2.18.0

package/docs/clients/core.md

@@ -178,13 +178,14 @@ The `display` field is `null` when the object's type has no registered Display t
 Get the balance of a specific coin type for an owner.
 
 ```typescript
-const balance = await client.core.getBalance({
+const { balance } = await client.core.getBalance({
 	owner: '0xabc...',
 	coinType: '0x2::sui::SUI', // Optional, defaults to SUI
 });
 
-console.log(balance.totalBalance); // Total balance as bigint
-console.log(balance.coinObjectCount); // Number of coin objects
+console.log(balance.balance); // Total balance (coin objects + address balance)
+console.log(balance.coinBalance); // Balance from coin objects only
+console.log(balance.addressBalance); // Balance from address balance only
 ```
 
 ### `listBalances`
@@ -197,7 +198,7 @@ const { balances } = await client.core.listBalances({
 });
 
 for (const balance of balances) {
-	console.log(balance.coinType, balance.totalBalance);
+	console.log(balance.coinType, balance.balance);
 }
 ```
 
@@ -212,7 +213,7 @@ const result = await client.core.listCoins({
 	limit: 10,
 });
 
-for (const coin of result.coins) {
+for (const coin of result.objects) {
 	console.log(coin.objectId, coin.balance);
 }
 ```
@@ -454,7 +455,7 @@ console.log(referenceGasPrice); // bigint
 Get the current system state including epoch information.
 
 ```typescript
-const systemState = await client.core.getCurrentSystemState();
+const { systemState } = await client.core.getCurrentSystemState();
 console.log(systemState.epoch);
 console.log(systemState.systemStateVersion);
 ```
@@ -478,7 +479,7 @@ Get information about a Move function.
 const { function: fn } = await client.core.getMoveFunction({
 	packageId: '0x2',
 	moduleName: 'coin',
-	name: 'transfer',
+	name: 'value',
 });
 
 console.log(fn.name);
@@ -566,7 +567,7 @@ function processObject(obj: SuiClientTypes.Object<{ content: true }>) {
 async function fetchBalance(
 	client: ClientWithCoreApi,
 	owner: string,
-): Promise<SuiClientTypes.CoinBalance> {
+): Promise<SuiClientTypes.Balance> {
 	const { balance } = await client.core.getBalance({ owner });
 	return balance;
 }
@@ -584,7 +585,7 @@ const options: SuiClientTypes.GetObjectOptions<{ content: true }> = {
 | ---------------------- | ------------------------------------------- |
 | `Object<Include>`      | Fetched object with optional included data  |
 | `Coin`                 | Coin object with balance                    |
-| `CoinBalance`          | Balance summary for a coin type             |
+| `Balance`              | Balance summary for a coin type             |
 | `CoinMetadata`         | Metadata for a coin type                    |
 | `Transaction<Include>` | Executed transaction with optional data     |
 | `TransactionResult`    | Success or failure result from execution    |

package/docs/clients/grpc.md

@@ -179,7 +179,7 @@ const { response: fields } = await grpcClient.stateService.listDynamicFields({
 const { response } = await grpcClient.movePackageService.getFunction({
 	packageId: '0x2',
 	moduleName: 'coin',
-	name: 'transfer',
+	name: 'value',
 });
 ```
 

package/docs/index.md

@@ -1,22 +1,55 @@
-# Sui TypeScript SDK Quick Start
+# Sui TypeScript SDK
 
-> The Sui TypeScript SDK is a modular library of tools for interacting with the Sui blockchain.
+> TypeScript SDK for building on the Sui blockchain
 
 The Sui TypeScript SDK is a modular library of tools for interacting with the Sui blockchain. Use it
 to send queries to RPC nodes, build and sign transactions, and interact with a Sui or local network.
 
 ## Installation
 
-```sh npm2yarn
+```npm
 npm i @mysten/sui
 ```
 
+The SDK is published as an ESM only package. Make sure your `package.json` includes
+`"type": "module"`:
+
+```json
+{
+	"type": "module"
+}
+```
+
+If you are using TypeScript, your `tsconfig.json` should use a compatible `moduleResolution` setting
+such as `"NodeNext"`, `"Node16"`, or `"Bundler"`.
+
+## Module packages
+
+The SDK contains a set of modular packages that you can use independently or together. Import just
+what you need to keep your code light and compact.
+
+- [`@mysten/sui/client`](/sui/clients): A client for interacting with Sui RPC nodes.
+- [`@mysten/sui/bcs`](/sui/bcs): A BCS builder with pre-defined types for Sui.
+- [`@mysten/sui/transactions`](/sui/transactions/basics): Utilities for building and interacting
+  with transactions.
+- [`@mysten/sui/keypairs/*`](/sui/cryptography/keypairs): Modular exports for specific KeyPair
+  implementations.
+- [`@mysten/sui/verify`](/sui/cryptography/keypairs#verifying-signatures-without-a-key-pair):
+  Methods for verifying transactions and messages.
+- [`@mysten/sui/cryptography`](/sui/cryptography/keypairs): Shared types and classes for
+  cryptography.
+- [`@mysten/sui/multisig`](/sui/cryptography/multisig): Utilities for working with multisig
+  signatures.
+- [`@mysten/sui/utils`](/sui/utils): Utilities for formatting and parsing various Sui types.
+- [`@mysten/sui/faucet`](#faucet): Methods for requesting SUI from a faucet.
+- [`@mysten/sui/zklogin`](/sui/zklogin): Utilities for working with zkLogin.
+
 ## Network locations
 
 The following table lists the locations for Sui networks.
 
 | Network | Full node                             | faucet                                   |
-| :------ | :------------------------------------ | :--------------------------------------- |
+| ------- | ------------------------------------- | ---------------------------------------- |
 | local   | `http://127.0.0.1:9000` (default)     | `http://127.0.0.1:9123/v2/gas` (default) |
 | Devnet  | `https://fullnode.devnet.sui.io:443`  | `https://faucet.devnet.sui.io/v2/gas`    |
 | Testnet | `https://fullnode.testnet.sui.io:443` | `https://faucet.testnet.sui.io/v2/gas`   |
@@ -31,23 +64,144 @@ The following table lists the locations for Sui networks.
 > (preferred for apps that have high traffic). You can find a list of reliable RPC endpoint providers
 > for Sui on the [Sui Dev Portal](https://sui.io/developers#dev-tools) using the **Node Service** tab.
 
-## Module packages
+## Quick start
 
-The SDK contains a set of modular packages that you can use independently or together. Import just
-what you need to keep your code light and compact.
+Get started in a few minutes. This guide walks you through creating a keypair, funding it from a
+faucet, and checking your balance.
 
-- [`@mysten/sui/client`](/sui/clients): A client for interacting with Sui RPC nodes.
-- [`@mysten/sui/bcs`](/sui/bcs): A BCS builder with pre-defined types for Sui.
-- [`@mysten/sui/transactions`](/sui/transaction-building/basics): Utilities for building and
-  interacting with transactions.
-- [`@mysten/sui/keypairs/*`](/sui/cryptography/keypairs): Modular exports for specific KeyPair
-  implementations.
-- [`@mysten/sui/verify`](/sui/cryptography/keypairs#verifying-signatures-without-a-key-pair):
-  Methods for verifying transactions and messages.
-- [`@mysten/sui/cryptography`](/sui/cryptography/keypairs): Shared types and classes for
-  cryptography.
-- [`@mysten/sui/multisig`](/sui/cryptography/multisig): Utilities for working with multisig
-  signatures.
-- [`@mysten/sui/utils`](/sui/utils): Utilities for formatting and parsing various Sui types.
-- [`@mysten/sui/faucet`](/sui/faucet): Methods for requesting SUI from a faucet.
-- [`@mysten/sui/zklogin`](/sui/zklogin): Utilities for working with zkLogin.
+### Create a project
+
+```sh
+mkdir hello-sui
+cd hello-sui
+npm init -y
+npm pkg set type=module
+npm i @mysten/sui
+```
+
+### Step 1: Create a keypair and get SUI
+
+Create a `setup.ts` file that generates a new keypair, requests SUI from the faucet, and prints your
+secret key for later use:
+
+```typescript
+
+// Generate a new keypair
+const keypair = new Ed25519Keypair();
+
+console.log('Address:', keypair.toSuiAddress());
+console.log('Secret key:', keypair.getSecretKey());
+
+// Request SUI from the devnet faucet
+await requestSuiFromFaucetV2({
+	host: getFaucetHost('devnet'),
+	recipient: keypair.toSuiAddress(),
+});
+
+console.log('Faucet request sent! Save the secret key above for the next step.');
+```
+
+Run it:
+
+```sh
+node setup.ts
+```
+
+Save the secret key that gets printed; you'll use it in the next step.
+
+> **Warning:** Logging secret keys to the console is only appropriate for quick demos like this. In real
+> applications, never log or expose secret keys. Store them securely using environment variables,
+> encrypted keystores, or a secrets manager.
+
+### Step 2: Check your balance
+
+Create a `balance.ts` file that imports your keypair from the secret key and checks the balance:
+
+```typescript
+
+// Import the keypair using the secret key from step 1
+const keypair = Ed25519Keypair.fromSecretKey('suiprivkey1...'); // paste your secret key here
+
+const grpcClient = new SuiGrpcClient({
+	network: 'devnet',
+	baseUrl: 'https://fullnode.devnet.sui.io:443',
+});
+
+const { balance } = await grpcClient.core.getBalance({
+	owner: keypair.toSuiAddress(),
+});
+
+const sui = Number(balance.balance) / Number(MIST_PER_SUI);
+console.log(`Address: ${keypair.toSuiAddress()}`);
+console.log(`Balance: ${sui} SUI`);
+```
+
+Run it:
+
+```sh
+node balance.ts
+```
+
+### Step 3: Transfer SUI
+
+Create a `transfer.ts` file that sends SUI to another address and logs the transaction effects:
+
+```typescript
+
+const keypair = Ed25519Keypair.fromSecretKey('suiprivkey1...'); // paste your secret key here
+const grpcClient = new SuiGrpcClient({
+	network: 'devnet',
+	baseUrl: 'https://fullnode.devnet.sui.io:443',
+});
+
+const tx = new Transaction();
+
+tx.transferObjects(
+	[coinWithBalance({ balance: BigInt(0.1 * Number(MIST_PER_SUI)) })],
+	'0xRecipientAddress', // replace with the recipient's address
+);
+
+const result = await keypair.signAndExecuteTransaction({
+	transaction: tx,
+	client: grpcClient,
+	include: { effects: true, balanceChanges: true },
+});
+
+if (result.$kind === 'FailedTransaction') {
+	console.error('Transaction failed:', result.FailedTransaction.status.error?.message);
+} else {
+	console.log('Transaction digest:', result.Transaction.digest);
+	console.log('Effects:', JSON.stringify(result.Transaction.effects, null, 2));
+	console.log('Balance changes:', JSON.stringify(result.Transaction.balanceChanges, null, 2));
+}
+```
+
+Run it:
+
+```sh
+node transfer.ts
+```
+
+### Faucet
+
+Devnet, Testnet, and local networks include faucets that mint SUI. Use `requestSuiFromFaucetV2` to
+request SUI programmatically:
+
+```typescript
+
+await requestSuiFromFaucetV2({
+	host: getFaucetHost('testnet'),
+	recipient: '0xYourAddress',
+});
+```
+
+> **Note:** Faucets on Devnet and Testnet are rate limited. If you hit the limit, wait before trying again.
+> For Testnet, you can also get SUI through the web UI at `faucet.sui.io` or through the [Sui
+> Discord](https://discord.gg/sui) faucet channels.
+
+## Next steps
+
+- [Building Transactions](/sui/transactions/basics): create and compose transactions
+- [Signing and Execution](/sui/transactions/signing-and-execution): sign and submit transactions
+- [Coins and Balances](/sui/transactions/coins-and-balances): work with tokens
+- [Client Setup](/sui/clients): configure clients for different networks

package/docs/llms-index.md

@@ -1,21 +1,18 @@
 # Sui SDK
 > TypeScript interfaces for Sui
 
-- [Sui TypeScript SDK Quick Start](..md): The Sui TypeScript SDK is a modular library of tools for interacting with the Sui blockchain.
-- [Install Sui TypeScript SDK](./install.md): Install the @mysten/sui package and configure your project.
+- [Sui TypeScript SDK](..md): TypeScript SDK for building on the Sui blockchain
 - [LLM Documentation](./llm-docs.md): Give AI agents access to Sui SDK documentation in your project.
-- [Hello Sui](./hello-sui.md): Build your first Sui application with the TypeScript SDK.
-- [Faucet](./faucet.md): Request test SUI tokens from the faucet on Devnet, Testnet, or local networks.
 - [Sui Clients](./clients.md): Choose and configure gRPC, GraphQL, or JSON-RPC clients for the Sui network.
 - [Core API](./clients/core.md): Transport-agnostic Core API shared by all Sui clients.
 - [SuiGrpcClient](./clients/grpc.md): Connect to Sui through gRPC with SuiGrpcClient.
 - [SuiGraphQLClient](./clients/graphql.md): Connect to Sui through GraphQL with SuiGraphQLClient.
 - [SuiJsonRpcClient](./clients/json-rpc.md): Connect to Sui through JSON-RPC with SuiJsonRpcClient.
-- [Sui Programmable Transaction Basics](./transaction-building/basics.md): Construct programmable transaction blocks with the Transaction API.
-- [Paying for Sui Transactions with Gas Coins](./transaction-building/gas.md): Configure gas budget, price, and coin selection for Sui transactions.
-- [Sponsored Transactions](./transaction-building/sponsored-transactions.md): Pay gas fees on behalf of other users with sponsored transactions.
-- [Building Offline](./transaction-building/offline.md): Build transactions without a network connection.
-- [Transaction Intents](./transaction-building/intents.md): Use high-level intents to simplify transaction building.
+- [Building Transactions](./transactions/basics.md): Construct programmable transaction blocks with the Transaction API
+- [Signing and Execution](./transactions/signing-and-execution.md): Sign transactions and execute them on the Sui network
+- [Coins and Balances](./transactions/coins-and-balances.md): Work with coin objects and address balances in transactions
+- [Commands and Inputs Reference](./transactions/reference.md): Complete reference for transaction commands and input types
+- [Building Offline](./transactions/offline.md): Build transactions without a network connection
 - [Key pairs](./cryptography/keypairs.md): Create and manage Ed25519, Secp256k1, and Secp256r1 keypairs for Sui transaction signing.
 - [Multi-Signature Transactions](./cryptography/multisig.md): Create multi-signature transactions with multiple signers on Sui.
 - [Passkey](./cryptography/passkey.md): Use WebAuthn passkeys for Sui transaction signing.

package/docs/migrations/0.38.md

@@ -13,7 +13,7 @@ earlier version of the SDK, there are some changes you should consider when upda
 
 The Sui TypeScript SDK is now divided into modular components. Before version 0.38.0, you imported
 the complete SDK module. Now, you upload the individual packages of the SDK module instead. See the
-[Module Packages section](#module-packages) for the list of packages.
+[Module Structure section](#module-structure) for the list of packages.
 
 ### Deprecated classes
 
@@ -40,7 +40,7 @@ The Sui TypeScript SDK deprecates the following classes with version 0.38.0:
 
 Signing and sending transactions changes slightly with the deprecation of the `Signer` pattern. For
 an example of transaction signing, see the
-[Sui Programmable Transaction Blocks Basics](/sui/transaction-building/basics) topic.
+[Sui Programmable Transaction Block Basics](/sui/transactions/basics) topic.
 
 ### Faucet requests
 

package/docs/migrations/sui-1.0.md

@@ -11,7 +11,7 @@ highlights:
 
 - [A new GraphQL Client for the newly released Sui GraphQL API](/sui/clients/graphql)
 - [New Transaction Executor classes for efficient Transaction execution](../executors)
-- [New Transaction Intents to simplify common transaction patterns](../transaction-building/intents)
+- [New Transaction Intents to simplify common transaction patterns](../transactions/coins-and-balances)
 - [A new Plugin system for Extending Transaction Building](../plugins)
 
 The majority of changes in this release are in the `@mysten/sui` package, but the changes to API
@@ -24,7 +24,7 @@ As part of the 1.0 release the `@mysten/sui.js` package has been renamed to `@my
 
 To upgrade to the new version, uninstall the old package and install the new one:
 
-```sh npm2yarn
+```npm
 npm uninstall @mysten/sui.js
 npm install @mysten/sui
 ```

package/docs/migrations/sui-2.0/json-rpc-migration.md

@@ -92,22 +92,26 @@ These JSON-RPC methods have direct replacements in the core API:
 
 These JSON-RPC methods can be replaced by calling gRPC service clients directly:
 
-| JSON-RPC Method                     | gRPC Service Replacement                                        |
-| ----------------------------------- | --------------------------------------------------------------- |
-| `getCheckpoint`                     | `ledgerService.getCheckpoint`                                   |
-| `getCheckpoints`                    | `ledgerService.listCheckpoints`                                 |
-| `getLatestCheckpointSequenceNumber` | `ledgerService.getCheckpoint`                                   |
-| `getEpochs`                         | `ledgerService.listEpochs`                                      |
-| `getCurrentEpoch`                   | `ledgerService.getEpoch`                                        |
-| `getLatestSuiSystemState`           | `ledgerService.getSystemState`                                  |
-| `getCommitteeInfo`                  | `ledgerService.getCommittee`                                    |
-| `getValidatorsApy`                  | `ledgerService.getValidators`                                   |
-| `getProtocolConfig`                 | `ledgerService.getProtocolConfig`                               |
-| `getNormalizedMoveModule`           | `movePackageService.getPackage` (response includes all modules) |
-| `getNormalizedMoveModulesByPackage` | `movePackageService.getPackage`                                 |
-| `getNormalizedMoveStruct`           | `movePackageService.getDatatype`                                |
-| `resolveNameServiceAddress`         | `nameService.lookupName`                                        |
-| `resolveNameServiceNames`           | `nameService.reverseLookupName`                                 |
+| JSON-RPC Method                     | gRPC Service Replacement                                         |
+| ----------------------------------- | ---------------------------------------------------------------- |
+| `getCheckpoint`                     | `ledgerService.getCheckpoint`                                    |
+| `getLatestCheckpointSequenceNumber` | `ledgerService.getServiceInfo` (read `checkpointHeight`)         |
+| `getCurrentEpoch`                   | `ledgerService.getEpoch` (omit `epoch` for the current)          |
+| `getLatestSuiSystemState`           | `ledgerService.getEpoch` with `system_state` in the read mask    |
+| `getCommitteeInfo`                  | `ledgerService.getEpoch` with `committee` in the read mask       |
+| `getProtocolConfig`                 | `ledgerService.getEpoch` with `protocol_config` in the read mask |
+| `getCoinMetadata`                   | `stateService.getCoinInfo` (response includes `metadata`)        |
+| `getTotalSupply`                    | `stateService.getCoinInfo` (response includes `treasury`)        |
+| `getNormalizedMoveModule`           | `movePackageService.getPackage` (response includes all modules)  |
+| `getNormalizedMoveModulesByPackage` | `movePackageService.getPackage`                                  |
+| `getNormalizedMoveStruct`           | `movePackageService.getDatatype`                                 |
+| `resolveNameServiceAddress`         | `nameService.lookupName`                                         |
+| `resolveNameServiceNames`           | `nameService.reverseLookupName`                                  |
+
+> **Warning:** `getCheckpoints` and `getEpochs` (paginated listings) have no gRPC equivalent — use the
+> `checkpoints` / `epochs` GraphQL queries instead. `getValidatorsApy` also has no replacement:
+> there is no canonical definition of validator APY, so it must be computed client-side from
+> validator exchange rates (see [Validator APY](#validator-apy) below).
 
 ### Example: using gRPC service clients
 
@@ -118,13 +122,32 @@ const client = new SuiGrpcClient({
 	network: 'mainnet',
 });
 
-// Get checkpoint information
+// Get the latest checkpoint sequence number (replaces getLatestCheckpointSequenceNumber)
+const { response: info } = await client.ledgerService.getServiceInfo({});
+const latestCheckpoint = info.checkpointHeight;
+
+// Get a specific checkpoint by sequence number. `checkpointId` is required (a oneof);
+// the read mask defaults to `sequence_number,digest`, so request more fields as needed.
 const { response } = await client.ledgerService.getCheckpoint({
-	sequenceNumber: 12345n,
+	checkpointId: { oneofKind: 'sequenceNumber', sequenceNumber: latestCheckpoint },
 });
 
-// Get current epoch
-const { response: epoch } = await client.ledgerService.getEpoch({});
+// Get the current epoch (omit `epoch` for the current one). The system state,
+// committee, and protocol config are NOT returned by default — you must request
+// them via the read mask (the default mask is just `epoch`).
+const { response: epoch } = await client.ledgerService.getEpoch({
+	readMask: { paths: ['epoch', 'system_state', 'committee', 'protocol_config'] },
+});
+const systemState = epoch.epoch?.systemState;
+const committee = epoch.epoch?.committee;
+const protocolConfig = epoch.epoch?.protocolConfig;
+
+// Get coin metadata and total supply in one call
+const { response: coinInfo } = await client.stateService.getCoinInfo({
+	coinType: '0x2::sui::SUI',
+});
+const metadata = coinInfo.metadata;
+const totalSupply = coinInfo.treasury?.totalSupply;
 
 // Get Move package information (includes all modules)
 const { response: pkg } = await client.movePackageService.getPackage({
@@ -148,19 +171,21 @@ const { response: address } = await client.nameService.lookupName({
 
 Some JSON-RPC methods don't have gRPC equivalents and require using `SuiGraphQLClient` instead:
 
-| JSON-RPC Method             | GraphQL Alternative                |
-| --------------------------- | ---------------------------------- |
-| `queryTransactionBlocks`    | `transactions` query               |
-| `multiGetTransactionBlocks` | `multiGetTransactionEffects` query |
-| `queryEvents`               | `events` query                     |
-| `getCoinMetadata`           | `coinMetadata` query               |
-| `getTotalSupply`            | `coinMetadata` query               |
-| `getStakes`                 | `address.stakedSuis` query         |
-| `getStakesByIds`            | `multiGetObjects` query            |
-| `tryGetPastObject`          | Historical object queries          |
-| `getNetworkMetrics`         | Use indexer                        |
-| `getAddressMetrics`         | Use indexer                        |
-| `getMoveCallMetrics`        | Use indexer                        |
+| JSON-RPC Method             | GraphQL Alternative                                       |
+| --------------------------- | --------------------------------------------------------- |
+| `queryTransactionBlocks`    | `transactions` query                                      |
+| `multiGetTransactionBlocks` | `multiGetTransactionEffects` query                        |
+| `queryEvents`               | `events` query                                            |
+| `getCheckpoints`            | `checkpoints` query                                       |
+| `getEpochs`                 | `epochs` query                                            |
+| `getCoinMetadata`           | `coinMetadata` query (or gRPC `stateService.getCoinInfo`) |
+| `getTotalSupply`            | `coinMetadata` query (or gRPC `stateService.getCoinInfo`) |
+| `getStakes`                 | `address.stakedSuis` query                                |
+| `getStakesByIds`            | `multiGetObjects` query                                   |
+| `tryGetPastObject`          | Historical object queries                                 |
+| `getNetworkMetrics`         | Use indexer                                               |
+| `getAddressMetrics`         | Use indexer                                               |
+| `getMoveCallMetrics`        | Use indexer                                               |
 
 ### Setting up GraphQL client
 
@@ -364,6 +389,24 @@ const result = await graphqlClient.query({
 });
 ```
 
+## Validator APY
+
+There is **no replacement** for `getValidatorsApy`, and one will not be added. There is no canonical
+definition of validator APY — no other chain's core/general-purpose RPCs offer this endpoint — so it
+must be computed client-side from validator staking-pool exchange rates.
+
+The general approach: read each validator's `exchangeRates` (a table of `pool_token_amount` /
+`sui_amount` per epoch) and estimate the annualized rate from the change in exchange rate over the
+trailing epochs. Two concrete reference implementations:
+
+- The `jsonrpc-alt` implementation in
+  [`sui-indexer-alt-jsonrpc`](https://github.com/MystenLabs/sui/blob/31537d4d9235b9f61dc07a3a71b05ed61a2bda7b/crates/sui-indexer-alt-jsonrpc/src/api/governance.rs#L422-L440),
+  which is compact and readable.
+- [This GraphQL approach](https://github.com/MystenLabs/sui/issues/23832#issuecomment-4437791087),
+  which fetches the precursor exchange-rate information in a single query.
+
+Treat whichever formula you adopt as _a_ definition of validator APY, not _the_ definition.
+
 ## Response format differences
 
 The gRPC client uses the core API response format, which differs from JSON-RPC responses. See the

package/docs/plugins.md

@@ -148,7 +148,7 @@ Adding an intent is similar to adding any other command to a transaction:
 const transaction = new Transaction();
 
 transaction.add(
-	Commands.Intent({
+	TransactionCommands.Intent({
 		name: 'TransferToSender',
 		inputs: {
 			objects: [transaction.object(someId)],
@@ -166,7 +166,7 @@ current transaction instance. This allows us to create a helper that automatical
 function transferToSender(objects: TransactionObjectInput[]) {
 	return (tx: Transaction) => {
 		tx.add(
-			Commands.Intent({
+			TransactionCommands.Intent({
 				name: 'TransferToSender',
 				inputs: {
 					objects: objects.map((obj) => tx.object(obj)),
@@ -214,7 +214,7 @@ async function resolveTransferToSender(
 
 		// This will replace the intent command with the correct TransferObjects command
 		transactionData.replaceCommand(index, [
-			Commands.TransferObjects(
+			TransactionCommands.TransferObjects(
 				// The inputs for intents are not currently typed, so we need to cast to the correct type here
 				transaction.$Intent.inputs.objects as Extract<
 					TransactionObjectArgument,
@@ -243,7 +243,7 @@ function transferToSender(objects: TransactionObjectInput[]) {
 		// As long as we are adding the same function reference, it will only be added once
 		tx.addIntentResolver('TransferToSender', resolveTransferToSender);
 		tx.add(
-			Commands.Intent({
+			TransactionCommands.Intent({
 				name: 'TransferToSender',
 				inputs: {
 					objects: objects.map((obj) => tx.object(obj)),
@@ -255,4 +255,28 @@ function transferToSender(objects: TransactionObjectInput[]) {
 
 const transaction = new Transaction();
 transaction.add(transferToSender(['0x1234']));
-```
+```
+
+## Copying transactions that use custom intents
+
+`Transaction.from` creates a deep copy of a transaction. Copying is synchronous, so any unresolved
+intents are carried over as-is and resolved later when the copy is built or serialized. To do that,
+the copy needs the intent resolvers, but resolvers are functions and cannot be represented in the
+serialized transaction data.
+
+Built-in intents (such as the `CoinWithBalance` intent added by `tx.coin()`) are re-attached
+automatically. For custom intents, pass the resolvers through the `intentResolvers` option so the
+copy knows how to resolve them:
+
+```typescript
+
+const copy = Transaction.from(transaction, {
+	intentResolvers: {
+		TransferToSender: resolveTransferToSender,
+	},
+});
+```
+
+Without this, `Transaction.from` throws if the transaction still contains unresolved custom intents.
+Alternatively, you can `await transaction.prepareForSerialization()` first to resolve the intents
+before copying, but that requires an async call and (for some intents) a client.