@mysten/sui 2.23.2 → 2.25.0

package/docs/llms-index.md

@@ -3,11 +3,12 @@
 
 - [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 between SuiGrpcClient and SuiGraphQLClient and understand their shared API
+- [Querying Data](./clients/querying.md): Read objects, coins, balances, dynamic fields, and history with any Sui client
+- [Executing Transactions](./clients/executing.md): Simulate, execute, and wait for transactions with any Sui client
+- [SuiGrpcClient](./clients/grpc.md): Connect to Sui over gRPC, with native service clients and real-time subscriptions
+- [SuiGraphQLClient](./clients/graphql.md): Connect to Sui over GraphQL and write type-safe custom queries
+- [Core API](./clients/core.md): The transport-agnostic client contract that SDKs and libraries build against
 - [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 +27,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