@mysten/sui 2.23.1 → 2.24.0

package/docs/executors.md

@@ -1,6 +1,6 @@
 # Transaction Executors
 
-> Manage transaction execution with queuing and parallel strategies.
+> Manage transaction execution with queuing and parallel strategies
 
 The TypeScript SDK ships two `Transaction` executor classes that simplify the processes of
 efficiently executing multiple transactions signed by the same address. These executors help manage
@@ -30,8 +30,8 @@ transactions to finish before sending the next one.
 
 - `client`: An instance of a Sui client (such as `SuiGrpcClient`) used to execute transactions.
 - `signer`: The signer/keypair used for signed transactions.
-- `defaultBudget`: The default budget for transactions, which will be used if the transaction does
-  not specify a budget (default `50_000_000n`).
+- `defaultGasBudget`: The default budget for transactions, which will be used if the transaction
+  does not specify a budget (default `50_000_000n`).
 - `gasMode`: Either `'coins'` (default) to use owned coins for gas, or `'addressBalance'` to pay gas
   from the sender's address balance.
 
@@ -54,10 +54,18 @@ const tx2 = new Transaction();
 const [coin2] = tx2.splitCoins(tx2.gas, [1]);
 tx2.transferObjects([coin2], address2);
 
-const [{ digest: digest1 }, { digest: digest2 }] = await Promise.all([
+const results = await Promise.all([
 	executor.executeTransaction(tx1),
 	executor.executeTransaction(tx2),
 ]);
+
+const [digest1, digest2] = results.map((result) => {
+	if (result.$kind === 'FailedTransaction') {
+		throw new Error(`Transaction failed: ${result.FailedTransaction.status.error.message}`);
+	}
+
+	return result.Transaction.digest;
+});
 ```
 
 ## `ParallelTransactionExecutor`
@@ -83,7 +91,7 @@ way that avoids conflicts between transactions using the same object ids.
 
 `ParallelTransactionExecutor` can be configured with a number of options:
 
-- `client`: An instance of `SuiJsonRpcClient` used to execute transactions.
+- `client`: A client implementing `ClientWithCoreApi`. `SuiGrpcClient` is the recommended default.
 - `signer`: The signer/keypair used for signed transactions.
 - `gasMode`: Either `'coins'` (default) to use owned coins for gas, or `'addressBalance'` to pay gas
   from the sender's address balance. When using `'addressBalance'`, coin-specific options like
@@ -94,20 +102,19 @@ way that avoids conflicts between transactions using the same object ids.
   `200_000_000n`),
 - `minimumCoinBalance`: After executing a transaction, the gasCoin will be reused unless it's
   balance is below this value (default `50_000_000n`),
-- `defaultBudget`: The default budget for transactions, which will be used if the transaction does
-  not specify a budget (default `minimumCoinBalance`),
+- `defaultGasBudget`: The default budget for transactions, which will be used if the transaction
+  does not specify a budget (default `minimumCoinBalance`),
 - `maxPoolSize`: The maximum number of gas coins to keep in the gas pool, which also limits the
   maximum number of concurrent transactions (default 50),
 - `sourceCoins`: An array of coins to use to create the gas pool, defaults to using all coins owned
   by the signer.
-- `epochBoundaryWindow`: Time to wait before or after the expected epoch boundary before re-fetching
-  the gas pool (in milliseconds). Building transactions will be paused for up to 2x this duration
-  around each epoch boundary to ensure the gas price is up-to-date for the next epoch. (default
-  `1000`)
 
 ```ts
 
-const client = new SuiJsonRpcClient({ url: getJsonRpcFullnodeUrl('devnet'), network: 'devnet' });
+const client = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.devnet.sui.io:443',
+	network: 'devnet',
+});
 
 const executor = new ParallelTransactionExecutor({
 	client,
@@ -121,10 +128,18 @@ const tx2 = new Transaction();
 const [coin2] = tx2.splitCoins(tx2.gas, [1]);
 tx2.transferObjects([coin2], address2);
 
-const [{ digest: digest1 }, { digest: digest2 }] = await Promise.all([
+const results = await Promise.all([
 	executor.executeTransaction(tx1),
 	executor.executeTransaction(tx2),
 ]);
+
+const [digest1, digest2] = results.map((result) => {
+	if (result.$kind === 'FailedTransaction') {
+		throw new Error(`Transaction failed: ${result.FailedTransaction.status.error.message}`);
+	}
+
+	return result.Transaction.digest;
+});
 ```
 
 ## Building and executing transactions with executors

package/docs/index.md

@@ -126,7 +126,7 @@ const grpcClient = new SuiGrpcClient({
 	baseUrl: 'https://fullnode.devnet.sui.io:443',
 });
 
-const { balance } = await grpcClient.core.getBalance({
+const { balance } = await grpcClient.getBalance({
 	owner: keypair.toSuiAddress(),
 });
 

package/docs/llms-index.md

@@ -3,11 +3,11 @@
 
 - [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.
-- [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 Clients](./clients.md): Choose and configure SuiGrpcClient, SuiGraphQLClient, and legacy JSON-RPC clients
+- [Core API](./clients/core.md): Transport-agnostic Core API shared by Sui clients
+- [SuiGrpcClient](./clients/grpc.md): Connect to Sui through gRPC with the recommended SuiGrpcClient
+- [SuiGraphQLClient](./clients/graphql.md): Connect to Sui through GraphQL with SuiGraphQLClient
+- [SuiJsonRpcClient](./clients/json-rpc.md): Maintain legacy JSON-RPC code while migrating to SuiGrpcClient or SuiGraphQLClient
 - [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
@@ -26,21 +26,21 @@
 - [Derived Objects](./utils/derived_objects.md): Compute derived object IDs from parent objects for deterministic offline derivation.
 - [BCS](./bcs.md): Binary Canonical Serialization for encoding Sui Move types.
 - [ZkLogin](./zklogin.md): Zero-knowledge authentication with OAuth providers on Sui.
-- [Transaction Executors](./executors.md): Manage transaction execution with queuing and parallel strategies.
+- [Transaction Executors](./executors.md): Manage transaction execution with queuing and parallel strategies
 - [Transaction Plugins](./plugins.md): Extend transaction building with reusable plugins.
-- [Building SDKs](./sdk-building.md): Build custom SDKs on top of the Sui TypeScript SDK.
-- [Migrate to 2.0](./migrations/sui-2.0.md): Migration guide for Sui TypeScript SDK 2.0 covering all @mysten packages.
+- [Building SDKs](./sdk-building.md): Build custom SDKs on top of the Sui TypeScript SDK
+- [Migrate to 2.0](./migrations/sui-2.0.md): Migration guide for Sui TypeScript SDK 2.0 covering all @mysten packages
 - [Agent Migration Prompt](./migrations/sui-2.0/agent-prompt.md): AI agent prompt for automated SDK 2.0 migration of your codebase.
-- [@mysten/sui](./migrations/sui-2.0/sui.md): Migrate @mysten/sui from 1.x to 2.0 with new client APIs and BCS changes.
-- [Migrating from JSON-RPC](./migrations/sui-2.0/json-rpc-migration.md): Migrate from JSON-RPC to the new Core API using SuiGrpcClient or SuiGraphQLClient.
-- [@mysten/dapp-kit](./migrations/sui-2.0/dapp-kit.md): Migrate @mysten/dapp-kit to the new dapp-kit-react package in 2.0.
-- [@mysten/kiosk](./migrations/sui-2.0/kiosk.md): Migrate @mysten/kiosk to 2.0 with client extension pattern and KioskTransaction.
-- [@mysten/zksend](./migrations/sui-2.0/zksend.md): Migrate @mysten/zksend to 2.0 with client extension pattern and simplified API.
-- [@mysten/suins](./migrations/sui-2.0/suins.md): Migrate @mysten/suins to 2.0 with client extension pattern.
-- [@mysten/deepbook-v3](./migrations/sui-2.0/deepbook-v3.md): Migrate @mysten/deepbook-v3 to 2.0 with client extension pattern.
-- [@mysten/walrus](./migrations/sui-2.0/walrus.md): Migrate @mysten/walrus to 2.0 with required client parameter and updated API.
+- [@mysten/sui](./migrations/sui-2.0/sui.md): Migrate @mysten/sui from 1.x to 2.0 with gRPC clients, Core API, and BCS changes
+- [Migrating from JSON-RPC](./migrations/sui-2.0/json-rpc-migration.md): Migrate deprecated JSON-RPC code to shared gRPC and GraphQL top-level methods
+- [@mysten/dapp-kit](./migrations/sui-2.0/dapp-kit.md): Migrate @mysten/dapp-kit to the new dapp-kit-react package in 2.0
+- [@mysten/kiosk](./migrations/sui-2.0/kiosk.md): Migrate @mysten/kiosk to 2.0 with client extension pattern and KioskTransaction
+- [@mysten/zksend](./migrations/sui-2.0/zksend.md): Migrate @mysten/zksend to 2.0 with client extension pattern and simplified API
+- [@mysten/suins](./migrations/sui-2.0/suins.md): Migrate @mysten/suins to 2.0 with client extension pattern
+- [@mysten/deepbook-v3](./migrations/sui-2.0/deepbook-v3.md): Migrate @mysten/deepbook-v3 to 2.0 with client extension pattern
+- [@mysten/walrus](./migrations/sui-2.0/walrus.md): Migrate @mysten/walrus to 2.0 with required client parameter and updated API
 - [@mysten/seal](./migrations/sui-2.0/seal.md): Migrate @mysten/seal to 2.0 with the new registration function pattern.
 - [Wallet Builders](./migrations/sui-2.0/wallet-builders.md): Migration guide for wallet extension developers upgrading to 2.0.
-- [SDK Maintainers](./migrations/sui-2.0/sdk-maintainers.md): Migration guide for SDK maintainers and library authors upgrading to 2.0.
+- [SDK Maintainers](./migrations/sui-2.0/sdk-maintainers.md): Migration guide for SDK maintainers and library authors upgrading to 2.0
 - [Migrate to 1.0](./migrations/sui-1.0.md): Migrate to Sui TypeScript SDK 1.0 with new features and API changes.
 - [Migrate to 0.38.0](./migrations/0.38.md): Migrate from SDK version 0.37 to 0.38 with updated module structure and API changes.

package/docs/migrations/sui-2.0/dapp-kit.md

@@ -1,6 +1,6 @@
 # @mysten/dapp-kit
 
-> Migrate @mysten/dapp-kit to the new dapp-kit-react package in 2.0.
+> Migrate @mysten/dapp-kit to the new dapp-kit-react package in 2.0
 
 This guide helps you migrate from the original `@mysten/dapp-kit` (legacy) to the new
 `@mysten/dapp-kit-react` package.
@@ -271,7 +271,7 @@ The built-in data fetching hooks have been removed. Use TanStack Query's `useQue
 - 	});
 + 	const { data, isLoading, error } = useQuery({
 + 		queryKey: ['object', objectId],
-+ 		queryFn: () => client.core.getObject({ objectId }),
++ 		queryFn: () => client.getObject({ objectId }),
 + 	});
   	// ...
   }
@@ -289,7 +289,7 @@ If you don't need React Query's caching and state management, you can fetch data
 	const [error, setError] = useState<string | null>(null);
 
 	useEffect(() => {
-		client.core
+		client
 			.getObject({ objectId })
 			.then((result) => setData(result.object ?? null))
 			.catch((err) => setError(err.message))

package/docs/migrations/sui-2.0/deepbook-v3.md

@@ -1,13 +1,13 @@
 # @mysten/deepbook-v3
 
-> Migrate @mysten/deepbook-v3 to 2.0 with client extension pattern.
+> Migrate @mysten/deepbook-v3 to 2.0 with client extension pattern
 
 This package now exports a client extension that integrates with Sui clients.
 
 ```diff
 - import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
 - import { DeepBookClient } from '@mysten/deepbook-v3';
-+ import { SuiGrpcClient } from '@mysten/sui/grpc'; // or SuiJsonRpcClient, SuiGraphQLClient
++ import { SuiGrpcClient } from '@mysten/sui/grpc';
 + import { deepbook } from '@mysten/deepbook-v3';
 
 - const suiClient = new SuiClient({ url: getFullnodeUrl('mainnet') });

package/docs/migrations/sui-2.0/index.md

@@ -1,12 +1,12 @@
 # Migrate to 2.0
 
-> Migration guide for Sui TypeScript SDK 2.0 covering all @mysten packages.
+> Migration guide for Sui TypeScript SDK 2.0 covering all @mysten packages
 
 This guide covers the breaking changes across the latest release of all the `@mysten/*` packages.
 
-The primary goal of this release is to support the new GRPC and GraphQL APIs across all the mysten
-SDKs. These releases also include removals of deprecated APIs, some renaming for better consistency,
-and significant internal refactoring to improve maintainability. Starting with this release, Mysten
+The primary goal of this release is to support the gRPC and GraphQL APIs across all Mysten SDKs.
+These releases also include removals of deprecated APIs, some renaming for better consistency, and
+significant internal refactoring to improve maintainability. Starting with this release, Mysten
 packages will now be published as ESM only packages.
 
 ## Quick reference
@@ -65,39 +65,51 @@ updates.
 
 ### Client migration
 
-The most common change across all SDKs is migrating from `SuiClient` to `SuiJsonRpcClient`:
+The recommended app migration is to create one `SuiGrpcClient` and use its top-level methods:
 
 ```diff
 - import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
-+ import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';
++ import { SuiGrpcClient } from '@mysten/sui/grpc';
 
 - const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
-+ const client = new SuiJsonRpcClient({
-+   url: getJsonRpcFullnodeUrl('mainnet'),
++ const client = new SuiGrpcClient({
++   baseUrl: 'https://fullnode.mainnet.sui.io:443',
 +   network: 'mainnet',
 + });
 ```
 
-We also recommend moving from the deprecated JSON RPC APIs to the new gRPC API as soon as possible:
+Then migrate old JSON-RPC method names to the gRPC top-level methods:
 
 ```diff
-- import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';
-+ import { SuiGrpcClient } from '@mysten/sui/grpc';
+- const coins = await client.getCoins({ owner });
++ const coins = await client.listCoins({ owner });
+
+- const txs = await client.queryTransactionBlocks({ filter, options });
++ const txs = await client.listTransactions({ filter, include });
+
+- const events = await client.queryEvents({ query, order: 'descending' });
++ const events = await client.listEvents({ filter, order: 'descending' });
 
-- const client = new SuiJsonRpcClient({ url, network: 'mainnet' });
-+ const client = new SuiGrpcClient({ baseUrl, network: 'mainnet' });
+- const transaction = await client.getTransactionBlock({ digest, options });
++ const transaction = await client.getTransaction({ digest, include });
 ```
 
-The gRPC runs on full nodes so in most cases you should be able to use the same URLs when migrating
-to gRPC.
+The gRPC API runs on full nodes, so in most cases you can use the same full node host when migrating
+from JSON-RPC to gRPC. Standard transaction and event queries are top-level methods on both
+`SuiGrpcClient` and `SuiGraphQLClient`. Use custom GraphQL queries for indexed data, historical
+object versions, or selection sets that are not covered by the shared methods.
+
+`SuiJsonRpcClient` still exists under `@mysten/sui/jsonRpc` for legacy code, but JSON-RPC APIs are
+deprecated in the Sui TypeScript SDK. See
+[Migrating from JSON-RPC](/sui/migrations/sui-2.0/json-rpc-migration) for detailed replacements.
 
 ### Network parameter required
 
 All client constructors now require an explicit `network` parameter:
 
 ```ts
-const client = new SuiJsonRpcClient({
-	url: getJsonRpcFullnodeUrl('mainnet'),
+const grpcClient = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
 	network: 'mainnet', // Required
 });
 
@@ -106,23 +118,32 @@ const graphqlClient = new SuiGraphQLClient({
 	network: 'mainnet', // Required
 });
 
-const grpcClient = new SuiGrpcClient({
-	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+const jsonRpcClient = new SuiJsonRpcClient({
+	url: 'https://fullnode.mainnet.sui.io:443',
 	network: 'mainnet', // Required
 });
 ```
 
 ### `ClientWithCoreApi` Interface
 
-Many SDK methods now accept any client implementing `ClientWithCoreApi`, enabling use with JSON-RPC,
-GraphQL, or gRPC transports:
+Many SDK methods now accept any client implementing `ClientWithCoreApi`. SDKs use
+`client.core.<method>()` so they can work across `SuiGrpcClient`, `SuiGraphQLClient`, and the
+deprecated `SuiJsonRpcClient` while apps keep using the top-level methods on their chosen client:
 
 ```ts
 
-// All of these work with APIs that accept ClientWithCoreApi
-const jsonRpcClient = new SuiJsonRpcClient({ url, network: 'mainnet' });
-const graphqlClient = new SuiGraphQLClient({ url, network: 'mainnet' });
-const grpcClient = new SuiGrpcClient({ baseUrl, network: 'mainnet' });
+const client = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+	network: 'mainnet',
+});
+
+// App code: use top-level methods.
+const { balance } = await client.getBalance({ owner });
+
+// SDK code: accept ClientWithCoreApi and use client.core.
+async function readForSdk(client: ClientWithCoreApi, objectId: string) {
+	return client.core.getObject({ objectId });
+}
 ```
 
 ## Package-specific guides