@mysten/sui 2.24.0 → 2.25.0

package/docs/clients/index.md

@@ -1,33 +1,22 @@
 # Sui Clients
 
-> Choose and configure SuiGrpcClient, SuiGraphQLClient, and legacy JSON-RPC clients
+> Choose between SuiGrpcClient and SuiGraphQLClient and understand their shared API
 
-The Sui TypeScript SDK provides multiple client implementations for interacting with the Sui
-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.
+A client is how your code reads from and writes to the Sui network. There are two to choose from,
+and they implement the same API (the same method names, options, and response shapes), so the choice
+is about which transport suits your application, not about which features you get.
 
-The gRPC and GraphQL clients expose three useful surfaces:
+| Client                                     | Choose it for                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [`SuiGrpcClient`](/sui/clients/grpc)       | The default. Reads from a full node, and the only client with real-time subscriptions |
+| [`SuiGraphQLClient`](/sui/clients/graphql) | Reads from the indexer, and custom queries written against the GraphQL schema         |
 
-- 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
+Both are fully supported primary choices. Pick `SuiGrpcClient` if you have no particular reason to
+prefer one, and `SuiGraphQLClient` when your application wants to query the GraphQL schema directly.
+Because they share an API, moving between them is mostly a matter of changing the constructor.
 
-The deprecated `SuiJsonRpcClient` also exposes `client.core`, but its top-level methods retain their
-legacy JSON-RPC names and response shapes.
-
-## Available clients
-
-| 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     |
-
-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.
+> **Note:** JSON-RPC is deprecated. See the [migration guide](/sui/migrations/sui-2.0/json-rpc-migration) if
+> you maintain existing JSON-RPC code.
 
 ## Quick start
 
@@ -39,20 +28,31 @@ const client = new SuiGrpcClient({
 });
 
 const { balance } = await client.getBalance({ owner: '0x...' });
+
 const { object } = await client.getObject({
 	objectId: '0x...',
 	include: { content: true },
 });
 ```
 
-## Top-level, core, and native APIs
+The same code against GraphQL differs only in how the client is created:
+
+```typescript
+
+const client = new SuiGraphQLClient({
+	network: 'mainnet',
+	url: 'https://graphql.mainnet.sui.io/graphql',
+});
+```
+
+## Three ways to call a client
+
+Each client exposes the same functionality through three surfaces, aimed at different callers.
 
 ### 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.
+The main API for application code. Read data, execute transactions, and query history by calling
+methods directly on the client:
 
 ```typescript
 const { objects } = await client.listOwnedObjects({
@@ -67,23 +67,14 @@ const result = await client.signAndExecuteTransaction({
 });
 ```
 
-Common top-level methods include:
+These are documented in [Querying data](/sui/clients/querying) and
+[Signing and execution](/sui/transactions/signing-and-execution). Where a transport can return more
+than the shared shape carries, it adds options here, such as `include: { protoJson: true }` on gRPC.
 
-| 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`                                                                                          |
+### `client.core`
 
-### 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.
+The transport-agnostic contract, for libraries that must work with whichever client their caller
+supplies:
 
 ```typescript
 
@@ -94,27 +85,18 @@ and the deprecated `SuiJsonRpcClient` implement.
 }
 ```
 
-### 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.
-
-```typescript
+See the [Core API](/sui/clients/core) for the contract and the cross-transport differences to
+account for. Application code does not need this. Call the top-level methods instead.
 
-const grpcClient = new SuiGrpcClient({
-	network: 'mainnet',
-	baseUrl: 'https://fullnode.mainnet.sui.io:443',
-});
+### Native APIs
 
-// gRPC - access various service clients to call any gRPC method
-const { response } = await grpcClient.stateService.listOwnedObjects({ owner: '0x...' });
+Each client also exposes its transport in full, for the cases the shared API does not cover:
 
-const graphqlClient = new SuiGraphQLClient({
-	network: 'mainnet',
-	url: 'https://graphql.mainnet.sui.io/graphql',
-});
+```typescript
+// gRPC: generated service clients, read masks, and streams
+const { response } = await grpcClient.ledgerService.getServiceInfo({});
 
-// GraphQL - write type-safe custom queries using the graphql function
+// GraphQL: type-safe custom queries
 const result = await graphqlClient.query({
 	query: graphql(`
 		query {
@@ -124,19 +106,26 @@ const result = await graphqlClient.query({
 });
 ```
 
-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).
+gRPC adds [raw list RPCs](/sui/clients/grpc#using-service-clients) and
+[subscriptions](/sui/clients/grpc#subscriptions); GraphQL adds
+[custom queries](/sui/clients/graphql#writing-queries) against the schema.
 
 ## Client extensions
 
-All clients support extensions through the `$extend` method, enabling SDKs like
-[@mysten/walrus](https://www.npmjs.com/package/@mysten/walrus) to add functionality:
+Both clients support extensions through `$extend`, which lets SDKs such as
+[@mysten/walrus](https://www.npmjs.com/package/@mysten/walrus) add functionality to a client your
+application already configured:
 
 ```typescript
 
 const client = new SuiGrpcClient({ network: 'mainnet', baseUrl: '...' }).$extend(walrus());
 
-await client.walrus.writeBlob({ ... });
+const { blobId } = await client.walrus.writeBlob({
+	blob: file,
+	deletable: false,
+	epochs: 3,
+	signer: keypair,
+});
 ```
 
-See [Building SDKs](/sui/sdk-building) for more on creating client extensions.
+See [Building SDKs](/sui/sdk-building) for creating your own.