@mysten/sui 2.23.2 → 2.24.0

package/docs/clients/core.md

@@ -1,10 +1,15 @@
 # Core API
 
-> Transport-agnostic Core API shared by all Sui clients.
+> Transport-agnostic Core API shared by Sui clients
 
-The Core API is the transport-agnostic interface that all Sui clients implement. It provides a
-consistent set of methods for interacting with the Sui blockchain, regardless of whether you're
-using gRPC, GraphQL, or JSON-RPC.
+The Core API is the transport-agnostic interface shared by Sui clients. It provides a consistent set
+of methods for interacting with the Sui blockchain across `SuiGrpcClient`, `SuiGraphQLClient`, and
+the deprecated `SuiJsonRpcClient`.
+
+For application code, prefer the top-level methods on the concrete client you instantiate, such as
+`grpcClient.getObject()` or `graphqlClient.listTransactions()`. Those methods match the Core API for
+common operations and may expose transport-specific additions. Use `client.core` when writing SDKs,
+libraries, or helpers that accept any `ClientWithCoreApi`.
 
 ## `ClientWithCoreApi`
 
@@ -83,9 +88,7 @@ List objects owned by an address.
 ```typescript
 const result = await client.core.listOwnedObjects({
 	owner: '0xabc...',
-	filter: {
-		StructType: '0x2::coin::Coin<0x2::sui::SUI>',
-	},
+	type: '0x2::coin::Coin<0x2::sui::SUI>',
 	limit: 10,
 });
 
@@ -342,9 +345,12 @@ const result = await client.core.simulateTransaction({
 	},
 });
 
+const simulatedTransaction =
+	result.$kind === 'Transaction' ? result.Transaction : result.FailedTransaction;
+
 // Check simulated effects before signing
-console.log(result.effects);
-console.log(result.balanceChanges);
+console.log(simulatedTransaction.effects);
+console.log(simulatedTransaction.balanceChanges);
 ```
 
 #### Disabling checks
@@ -598,12 +604,27 @@ console.log(fn.typeParameters);
 
 ## Name service methods
 
+### `resolveNameServiceAddress`
+
+Resolve a SuiNS name to its target address. The address is `null` when the name does not exist, has
+expired, or does not have a target address.
+
+```typescript
+const { address } = await client.core.resolveNameServiceAddress({
+	name: 'example.sui',
+});
+
+console.log(address); // e.g., "0x..." or null
+```
+
 ### `defaultNameServiceName`
 
 Resolve an address to its default SuiNS name.
 
 ```typescript
-const { name } = await client.core.defaultNameServiceName({
+const {
+	data: { name },
+} = await client.core.defaultNameServiceName({
 	address: '0xabc...',
 });
 

package/docs/clients/graphql.md

@@ -1,27 +1,60 @@
 # SuiGraphQLClient
 
-> Connect to Sui through GraphQL with SuiGraphQLClient.
+> Connect to Sui through GraphQL with SuiGraphQLClient
 
 The `SuiGraphQLClient` enables type-safe GraphQL queries against the Sui GraphQL API.
 
 For more details on the Sui GraphQL API, see the
 [GraphQL reference](https://docs.sui.io/references/sui-graphql).
 
-The `SuiGraphQLClient` implements all the the [Core API](/sui/clients/core) methods:
+Use `SuiGraphQLClient` when an app needs indexed GraphQL data, historical queries, or custom
+selection sets that are not exposed by the gRPC top-level API.
+
+## Using top-level methods
+
+`SuiGraphQLClient` exposes top-level methods for the same common operations as the
+[Core API](/sui/clients/core). Use them directly in application code:
 
 ```typescript
 
 const client = new SuiGraphQLClient({
-	url: 'https://sui-mainnet.mystenlabs.com/graphql',
+	url: 'https://graphql.mainnet.sui.io/graphql',
 	network: 'mainnet',
 });
 
-const { object } = await client.getObject({ objectId: '0x...' });
+const { object } = await client.getObject({
+	objectId: '0x...',
+	include: { content: true },
+});
+
+const txs = await client.listTransactions({
+	filter: { sender: '0x...' },
+	order: 'descending',
+	limit: 10,
+});
 ```
 
+The same methods are available through `client.core` when SDK code needs the transport-agnostic
+`ClientWithCoreApi` contract.
+
+Common top-level methods:
+
+| Category       | Methods                                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Objects        | `getObject`, `getObjects`, `listOwnedObjects`, `listDynamicFields`, `getDynamicField`                             |
+| Coins          | `listCoins`, `getBalance`, `listBalances`, `getCoinMetadata`                                                      |
+| Transactions   | `getTransaction`, `executeTransaction`, `signAndExecuteTransaction`, `waitForTransaction`                         |
+| Simulation     | `simulateTransaction`                                                                                             |
+| Queries        | `listTransactions`, `listEvents`                                                                                  |
+| Move and names | `getMoveFunction`, `resolveNameServiceAddress`, `defaultNameServiceName`, `mvr.resolvePackage`, `mvr.resolveType` |
+| Verification   | `verifyZkLoginSignature`                                                                                          |
+
+GraphQL-specific top-level options include `doGasSelection` on `simulateTransaction` and
+`include: { value: true }` on `listDynamicFields`.
+
 ## Custom GraphQL queries
 
-To query anything no in the Core API, you can use the `query` method to execute custom GraphQL
+To query anything not in the top-level API, use the `query` method to execute custom GraphQL
 queries.
 
 We'll start by creating our client, and executing a very basic query:
@@ -62,7 +95,9 @@ passed to your query are properly typed.
 const getSuinsName = graphql(`
 	query getSuiName($address: SuiAddress!) {
 		address(address: $address) {
-			defaultSuinsName
+			defaultNameRecord {
+				domain
+			}
 		}
 	}
 `);
@@ -75,7 +110,7 @@ async function getDefaultSuinsName(address: string) {
 		},
 	});
 
-	return result.data?.address?.defaultSuinsName;
+	return result.data?.address?.defaultNameRecord?.domain;
 }
 ```
 
@@ -94,7 +129,7 @@ const chainIdentifierQuery = graphql(`
 `);
 
 function ChainIdentifier() {
-	const { loading, error, data } = useQuery(getPokemonsQuery);
+	const { loading, error, data } = useQuery(chainIdentifierQuery);
 
 	return <div>{data?.chainIdentifier}</div>;
 }

package/docs/clients/grpc.md

@@ -1,8 +1,9 @@
 # SuiGrpcClient
 
-> Connect to Sui through gRPC with SuiGrpcClient.
+> Connect to Sui through gRPC with the recommended SuiGrpcClient
 
-The `SuiGrpcClient` provides access to the Full Node gRPC API.
+The `SuiGrpcClient` provides access to the Full Node gRPC API. It is the recommended default client
+for application code and SDK integrations.
 
 For more complete details on what is available through this API see the
 [gRPC API docs](https://docs.sui.io/develop/accessing-data/grpc/what-is-grpc).
@@ -28,6 +29,74 @@ const grpcClient = new SuiGrpcClient({
 });
 ```
 
+## Using top-level methods
+
+Use top-level methods for most application code. These methods match the shared
+[Core API](/sui/clients/core) option and response shapes, so the same calls can also be written as
+`grpcClient.core.<method>()` when SDK code needs the transport-agnostic `ClientWithCoreApi`
+contract.
+
+```typescript
+
+const grpcClient = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+
+const { balance } = await grpcClient.getBalance({
+	owner: '<OWNER_ADDRESS>',
+});
+
+const { object } = await grpcClient.getObject({
+	objectId: '<OBJECT_ID>',
+	include: { content: true, display: true },
+});
+
+const coins = await grpcClient.listCoins({
+	owner: '<OWNER_ADDRESS>',
+	coinType: '0x2::sui::SUI',
+});
+```
+
+Common top-level methods:
+
+| Category       | Methods                                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Objects        | `getObject`, `getObjects`, `listOwnedObjects`, `listDynamicFields`, `getDynamicField`                             |
+| Coins          | `listCoins`, `getBalance`, `listBalances`, `getCoinMetadata`                                                      |
+| Transactions   | `getTransaction`, `executeTransaction`, `signAndExecuteTransaction`, `waitForTransaction`                         |
+| Simulation     | `simulateTransaction`                                                                                             |
+| Queries        | `listTransactions`, `listEvents`                                                                                  |
+| Move and names | `getMoveFunction`, `resolveNameServiceAddress`, `defaultNameServiceName`, `mvr.resolvePackage`, `mvr.resolveType` |
+| Verification   | `verifyZkLoginSignature`                                                                                          |
+
+### gRPC-specific top-level data
+
+Top-level gRPC methods are a superset of the shared Core API where the transport can expose useful
+gRPC data directly:
+
+```typescript
+const result = await grpcClient.getTransaction({
+	digest: '<TRANSACTION_DIGEST>',
+	include: {
+		effects: true,
+		protoJson: true,
+	},
+});
+
+const tx = result.Transaction ?? result.FailedTransaction;
+console.log(tx.digest, result.protoJson);
+```
+
+gRPC-specific options include:
+
+| Option                     | Methods                                                                                   |
+| -------------------------- | ----------------------------------------------------------------------------------------- |
+| `include.protoJson`        | `getTransaction`, `executeTransaction`, `signAndExecuteTransaction`, `waitForTransaction` |
+| `include.protoJson`        | `simulateTransaction`                                                                     |
+| `doGasSelection`           | `simulateTransaction`                                                                     |
+| `include: { value: true }` | `listDynamicFields`                                                                       |
+
 ## Transport options
 
 By default, `SuiGrpcClient` uses `GrpcWebFetchTransport` from
@@ -105,9 +174,9 @@ service clients are generated using [protobuf-ts](https://github.com/timostamm/p
 provides type-safe gRPC clients for TypeScript. For more details on how to use gRPC with Sui, see
 the [gRPC overview](https://docs.sui.io/develop/accessing-data/grpc/what-is-grpc).
 
-### With the core API
+### Prefer top-level methods first
 
-The gRPC client implements all the [`core`](./core) API methods:
+For common operations, call the top-level method before reaching for raw service clients:
 
 ```typescript
 
@@ -115,13 +184,14 @@ const grpcClient = new SuiGrpcClient({
 	network: 'testnet',
 	baseUrl: 'https://fullnode.testnet.sui.io:443',
 });
-// Get coins owned by an address
-await grpcClient.getCoins({
+
+await grpcClient.listCoins({
 	owner: '<OWNER_ADDRESS>',
 });
 ```
 
-To query additional data not available in the core API, you can use the service clients directly:
+Use the generated service clients directly when you need gRPC methods, read masks, streaming
+behavior, or filters that are not exposed by the top-level API.
 
 ### Transaction execution service
 
@@ -254,8 +324,20 @@ const { response } = await grpcClient.movePackageService.getFunction({
 ### Name service
 
 ```typescript
-// Reverse lookup address to get name
-const { response } = await grpcClient.nameService.reverseLookupName({
+const { address } = await grpcClient.resolveNameServiceAddress({
+	name: 'example.sui',
+});
+```
+
+Use the raw name service when you need the complete gRPC `NameRecord` instead of only its target
+address:
+
+```typescript
+const { response } = await grpcClient.nameService.lookupName({
+	name: 'example.sui',
+});
+
+const { response: reverseResponse } = await grpcClient.nameService.reverseLookupName({
 	address: '0xabc...',
 });
 ```

package/docs/clients/index.md

@@ -1,28 +1,33 @@
 # Sui Clients
 
-> Choose and configure gRPC, GraphQL, or JSON-RPC clients for the Sui network.
+> Choose and configure SuiGrpcClient, SuiGraphQLClient, and legacy JSON-RPC clients
 
 The Sui TypeScript SDK provides multiple client implementations for interacting with the Sui
-network. Each client connects to a different API but provides two levels of access:
+network. For application code, choose one client for your transport and use its top-level methods
+for common reads, writes, and queries. `SuiGrpcClient` is the recommended default.
 
-- Native API: Full access to everything the underlying API offers
-- [Core API](/sui/clients/core): A consistent interface across all clients for common operations
+The gRPC and GraphQL clients expose three useful surfaces:
 
-## Available clients
+- Top-level methods: the main application API, matching the Core API for common operations
+- [Core API](/sui/clients/core): the shared `client.core` contract used by SDKs and libraries
+- Native API: direct access to transport-specific features when the common methods are not enough
+
+The deprecated `SuiJsonRpcClient` also exposes `client.core`, but its top-level methods retain their
+legacy JSON-RPC names and response shapes.
 
-| Client                                                   | API                                                                |
-| -------------------------------------------------------- | ------------------------------------------------------------------ |
-| [`SuiGrpcClient`](/sui/clients/grpc) (recommended)       | [Full Node gRPC](https://docs.sui.io/references/fullnode-protocol) |
-| [`SuiGraphQLClient`](/sui/clients/graphql)               | [GraphQL](https://docs.sui.io/references/sui-graphql)              |
-| [`SuiJsonRpcClient`](/sui/clients/json-rpc) (deprecated) | [JSON-RPC (deprecated)](https://docs.sui.io/sui-api-ref)           |
+## Available clients
 
-All clients are compatible with Mysten SDKs like `@mysten/walrus`, `@mysten/seal` and
-`@mysten/suins`.
+| Client                                                   | Use For                                                                 |
+| -------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [`SuiGrpcClient`](/sui/clients/grpc) (recommended)       | Most application and SDK operations, full node data, execution, streams |
+| [`SuiGraphQLClient`](/sui/clients/graphql)               | Indexed queries, historical data, or custom GraphQL selection sets      |
+| [`SuiJsonRpcClient`](/sui/clients/json-rpc) (deprecated) | Maintaining legacy JSON-RPC code while migrating to gRPC or GraphQL     |
 
-For most application gRPC is a good default. The JSON RPC API has been deprecated and will be
-decommissioned soon. The GraphQL can be used for more advanced query patterns that can not be
-supported directly on full nodes (for example, querying for transactions or events with various
-filters).
+All active Mysten SDKs are designed to accept clients that implement the Core API. `SuiGrpcClient`
+is the default choice for most apps because it uses the full node gRPC API and has the most complete
+top-level SDK surface. Use `SuiGraphQLClient` when the code needs GraphQL-specific indexed queries
+or a custom query shape. JSON-RPC APIs are deprecated in the Sui TypeScript SDK; migrate legacy
+JSON-RPC code to gRPC or GraphQL.
 
 ## Quick start
 
@@ -33,25 +38,82 @@ const client = new SuiGrpcClient({
 	baseUrl: 'https://fullnode.mainnet.sui.io:443',
 });
 
-// Use the native API for full access to transport-specific features
-const { response } = await client.ledgerService.getTransaction({ digest: '0x...' });
+const { balance } = await client.getBalance({ owner: '0x...' });
+const { object } = await client.getObject({
+	objectId: '0x...',
+	include: { content: true },
+});
+```
 
-// Use the Core API for transport-agnostic operations
-const { object } = await client.core.getObject({ objectId: '0x...' });
+## Top-level, core, and native APIs
+
+### Top-level methods
+
+Use top-level methods when writing app code against `SuiGrpcClient` or `SuiGraphQLClient`. These
+methods use the same option and response shapes as the Core API, and a transport can add narrowly
+scoped fields where it has extra native data. For `SuiJsonRpcClient`, use `client.core` for these
+shapes or migrate its legacy top-level calls to gRPC or GraphQL.
+
+```typescript
+const { objects } = await client.listOwnedObjects({
+	owner: '0x...',
+	include: { display: true },
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction,
+	signer,
+	include: { effects: true, balanceChanges: true },
+});
 ```
 
-## Native vs core API
+Common top-level methods include:
+
+| Category       | Methods                                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Objects        | `getObject`, `getObjects`, `listOwnedObjects`, `listDynamicFields`, `getDynamicField`                             |
+| Coins          | `listCoins`, `getBalance`, `listBalances`, `getCoinMetadata`                                                      |
+| Transactions   | `getTransaction`, `executeTransaction`, `signAndExecuteTransaction`, `waitForTransaction`                         |
+| Simulation     | `simulateTransaction`                                                                                             |
+| Queries        | `listTransactions`, `listEvents`                                                                                  |
+| Move and names | `getMoveFunction`, `resolveNameServiceAddress`, `defaultNameServiceName`, `mvr.resolvePackage`, `mvr.resolveType` |
+| Verification   | `verifyZkLoginSignature`                                                                                          |
+
+### Core API
+
+Use `client.core` when building SDKs or libraries that accept any client implementing
+`ClientWithCoreApi`. The Core API is the shared contract that `SuiGrpcClient`, `SuiGraphQLClient`,
+and the deprecated `SuiJsonRpcClient` implement.
+
+```typescript
+
+	return client.core.getObject({
+		objectId,
+		include: { content: true },
+	});
+}
+```
 
 ### Native API
 
 Each client exposes the full capabilities of its underlying transport. Use the native API when you
-need transport-specific features or want maximum control:
+need transport-specific features or want maximum control.
 
 ```typescript
 
+const grpcClient = new SuiGrpcClient({
+	network: 'mainnet',
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+});
+
 // gRPC - access various service clients to call any gRPC method
 const { response } = await grpcClient.stateService.listOwnedObjects({ owner: '0x...' });
 
+const graphqlClient = new SuiGraphQLClient({
+	network: 'mainnet',
+	url: 'https://graphql.mainnet.sui.io/graphql',
+});
+
 // GraphQL - write type-safe custom queries using the graphql function
 const result = await graphqlClient.query({
 	query: graphql(`
@@ -60,25 +122,10 @@ const result = await graphqlClient.query({
 		}
 	`),
 });
-
-// JSON-RPC - call any JSON-RPC method
-const coins = await jsonRpcClient.getCoins({ owner: '0x...' });
-```
-
-### Core API
-
-All clients also implement the [Core API](/sui/clients/core) through `client.core`. This provides a
-consistent interface for common operations that works identically across all transports:
-
-```typescript
-// These methods work the same on any client
-const { object } = await client.core.getObject({ objectId: '0x...' });
-const balance = await client.core.getBalance({ owner: '0x...' });
-await client.core.executeTransaction({ transaction, signatures });
 ```
 
-The Core API is essential for [building SDKs](/sui/sdk-building) that work with any client the user
-chooses.
+For legacy JSON-RPC-only code, see the [`SuiJsonRpcClient` page](/sui/clients/json-rpc) and the
+[JSON-RPC migration guide](/sui/migrations/sui-2.0/json-rpc-migration).
 
 ## Client extensions
 

package/docs/clients/json-rpc.md

@@ -1,13 +1,18 @@
 # SuiJsonRpcClient
 
-> Connect to Sui through JSON-RPC with SuiJsonRpcClient.
+> Maintain legacy JSON-RPC code while migrating to SuiGrpcClient or SuiGraphQLClient
 
-> **Warning:** The Sui JSON-RPC API has been deprecated. We recommend migration to
-> [`SuiGrpcClient`](/sui/clients/grpc) or [`SuiGraphQLClient`](/sui/clients/graphql) as soon as
-> possible.
+> **Warning:** JSON-RPC APIs are deprecated in the Sui TypeScript SDK. Use [`SuiGrpcClient`](/sui/clients/grpc)
+> for most application code, or [`SuiGraphQLClient`](/sui/clients/graphql) for GraphQL-specific
+> indexed queries.
 
-The `SuiJsonRpcClient` connects to a Sui network's JSON-RPC server. It implements the
-[Core API](/sui/clients/core), so it can be used with any SDK that accepts `ClientWithCoreApi`.
+This page exists for maintaining legacy JSON-RPC code. New code should use
+[`SuiGrpcClient`](/sui/clients/grpc) and its top-level methods by default. See
+[Migrating from JSON-RPC](/sui/migrations/sui-2.0/json-rpc-migration) for replacement examples.
+
+The `SuiJsonRpcClient` connects to a Sui network's JSON-RPC server. It also implements the
+[Core API](/sui/clients/core), so SDKs that accept `ClientWithCoreApi` can support it during a
+migration.
 
 ```typescript
 
@@ -22,9 +27,9 @@ const { object } = await client.core.getObject({ objectId: '0x...' });
 
 ## Connecting to a Sui network
 
-To establish a connection to a network, import `SuiJsonRpcClient` from `@mysten/sui/client` and pass
-the relevant URL to the `url` parameter. The following example establishes a connection to Devnet
-and get all `Coin<coin_type>` objects owned by an address.
+To establish a legacy JSON-RPC connection, import `SuiJsonRpcClient` from `@mysten/sui/jsonRpc` and
+pass the relevant URL to the `url` parameter. The following example establishes a connection to
+Devnet and gets all `Coin<coin_type>` objects owned by an address.
 
 ```typescript
 
@@ -62,6 +67,7 @@ available in the RPC.
 
 const client = new SuiJsonRpcClient({
 	url: 'https://fullnode.devnet.sui.io:443',
+	network: 'devnet',
 });
 // asynchronously call suix_getCommitteeInfo
 const committeeInfo = await client.call('suix_getCommitteeInfo', []);
@@ -72,20 +78,16 @@ For a full list of available RPC methods, see the
 
 ## Customizing the transport
 
-The `SuiJsonRpcClient` uses a `Transport` class to manage connections to the RPC node. The default
-`SuiHTTPTransport` (alias for `JsonRpcHTTPTransport`) makes both JSON RPC requests, as well as
-websocket requests for subscriptions. You can construct a custom transport instance if you need to
-pass any custom options, such as headers or timeout values.
+The `SuiJsonRpcClient` uses a transport to manage connections to the RPC node. By default it creates
+a `JsonRpcHTTPTransport` for HTTP JSON-RPC requests. You can construct a custom transport instance
+if you need to pass options such as headers or a custom `fetch` implementation.
 
 ```typescript
 
 const client = new SuiJsonRpcClient({
+	network: 'devnet',
 	transport: new JsonRpcHTTPTransport({
 		url: 'https://fullnode.devnet.sui.io:443',
-		websocket: {
-			reconnectTimeout: 1000,
-			url: 'wss://fullnode.devnet.sui.io:443',
-		},
 		rpc: {
 			headers: {
 				'x-custom-header': 'custom value',
@@ -150,8 +152,8 @@ const result = await client.executeTransactionBlock({
 
 #### Arguments
 
-- `transactionBlock`: either a Transaction or BCS serialized transaction data bytes as a Uint8Array
-  or as a base-64 encoded string.
+- `transactionBlock`: BCS serialized transaction data bytes as a `Uint8Array` or base64-encoded
+  string.
 - `signature`: A signature, or list of signatures committed to the intent message of the transaction
   data, as a base-64 encoded string.
 - `options`:
@@ -178,15 +180,14 @@ const result = await client.signAndExecuteTransaction({
 });
 
 // IMPORTANT: Always check the transaction status
-if (result.$kind === 'FailedTransaction') {
-	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+if (result.effects?.status.status === 'failure') {
+	throw new Error(`Transaction failed: ${result.effects.status.error}`);
 }
 ```
 
 #### Arguments
 
-- `transaction`: BCS serialized transaction data bytes as a Uint8Array or as a base-64 encoded
-  string.
+- `transaction`: A `Transaction` or BCS serialized transaction data bytes as a `Uint8Array`.
 - `signer`: A `Keypair` instance to sign the transaction
 - `options`:
   - `showBalanceChanges`: Whether to show balance_changes. Default to be False
@@ -208,15 +209,18 @@ const tx = new Transaction();
 const result = await client.signAndExecuteTransaction({
 	transaction: tx,
 	signer: keypair,
+	options: {
+		showEffects: true,
+	},
 });
 
 // Check transaction status
-if (result.$kind === 'FailedTransaction') {
-	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+if (result.effects?.status.status === 'failure') {
+	throw new Error(`Transaction failed: ${result.effects.status.error}`);
 }
 
 const transaction = await client.waitForTransaction({
-	digest: result.Transaction.digest,
+	digest: result.digest,
 	options: {
 		showEffects: true,
 	},