@mysten/sui 2.16.1 → 2.16.3

package/docs/clients/grpc.md

@@ -0,0 +1,210 @@
+# SuiGrpcClient
+
+> Connect to Sui through gRPC with SuiGrpcClient.
+
+The `SuiGrpcClient` provides access to the Full Node gRPC API.
+
+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).
+
+## Creating a gRPC client
+
+To get started, create a `SuiGrpcClient` instance by specifying a network and base URL:
+
+```typescript
+
+const grpcClient = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+```
+
+For local development:
+
+```typescript
+const grpcClient = new SuiGrpcClient({
+	network: 'localnet',
+	baseUrl: 'http://127.0.0.1:9000',
+});
+```
+
+## Transport options
+
+By default, `SuiGrpcClient` uses `GrpcWebFetchTransport` from
+[protobuf-ts](https://github.com/timostamm/protobuf-ts), which works in browsers and Node.js through
+the Fetch API. You can also provide a custom transport for advanced use cases.
+
+The `GrpcWebFetchTransport` class, `GrpcWebOptions` type, and `RpcTransport` type are all
+re-exported from `@mysten/sui/grpc` for convenience.
+
+### gRPC-web transport (default)
+
+The default transport uses the gRPC-web protocol over HTTP/1.1 or HTTP/2. You can customize it by
+passing `GrpcWebFetchTransport` options directly:
+
+```typescript
+
+const transport = new GrpcWebFetchTransport({
+	baseUrl: 'https://your-custom-grpc-endpoint.com',
+	format: 'binary', // default is 'text' (base64-encoded)
+	// Additional transport options like fetchInit
+});
+
+const grpcClient = new SuiGrpcClient({
+	network: 'testnet',
+	transport,
+});
+```
+
+### Native gRPC transport
+
+For server-side applications (Node.js, Bun, and others), you can use the native gRPC transport with
+`@protobuf-ts/grpc-transport` and `@grpc/grpc-js`. This uses HTTP/2 with the native gRPC protocol
+rather than the gRPC-web translation layer.
+
+Install the required packages:
+
+```bash
+npm install @protobuf-ts/grpc-transport @grpc/grpc-js
+```
+
+Then create the client with a `GrpcTransport`:
+
+```typescript
+
+const transport = new GrpcTransport({
+	host: 'fullnode.testnet.sui.io:443',
+	channelCredentials: ChannelCredentials.createSsl(),
+});
+
+const grpcClient = new SuiGrpcClient({
+	network: 'testnet',
+	transport,
+});
+```
+
+For local development without TLS:
+
+```typescript
+
+const transport = new GrpcTransport({
+	host: '127.0.0.1:9000',
+	channelCredentials: ChannelCredentials.createInsecure(),
+});
+
+const grpcClient = new SuiGrpcClient({
+	network: 'localnet',
+	transport,
+});
+```
+
+## Using service clients
+
+The `SuiGrpcClient` exposes several service clients for lower-level access to the gRPC API. These
+service clients are generated using [protobuf-ts](https://github.com/timostamm/protobuf-ts), which
+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
+
+The gRPC client implements all the [`core`](./core) API methods:
+
+```typescript
+
+const grpcClient = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+// Get coins owned by an address
+await grpcClient.getCoins({
+	owner: '<OWNER_ADDRESS>',
+});
+```
+
+To query additional data not available in the core API, you can use the service clients directly:
+
+### Transaction execution service
+
+```typescript
+const { response } = await grpcClient.transactionExecutionService.executeTransaction({
+	transaction: {
+		bcs: {
+			value: transactionBytes,
+		},
+	},
+	signatures: signatures.map((sig) => ({
+		bcs: { value: fromBase64(sig) },
+		signature: { oneofKind: undefined },
+	})),
+});
+
+// IMPORTANT: Always check the transaction status
+if (!response.finality?.effects?.status?.success) {
+	const error = response.finality?.effects?.status?.error;
+	throw new Error(`Transaction failed: ${error || 'Unknown error'}`);
+}
+```
+
+### Ledger service
+
+```typescript
+// Get transaction by digest
+const { response } = await grpcClient.ledgerService.getTransaction({
+	digest: '0x123...',
+});
+
+// Get current epoch information
+const { response: epochInfo } = await grpcClient.ledgerService.getEpoch({});
+```
+
+### State service
+
+```typescript
+// List owned objects
+const { response } = await grpcClient.stateService.listOwnedObjects({
+	owner: '0xabc...',
+	objectType: '0x2::coin::Coin<0x2::sui::SUI>',
+});
+
+// Get dynamic fields
+const { response: fields } = await grpcClient.stateService.listDynamicFields({
+	parent: '0x123...',
+});
+```
+
+### Move package service
+
+```typescript
+// Get function information
+const { response } = await grpcClient.movePackageService.getFunction({
+	packageId: '0x2',
+	moduleName: 'coin',
+	name: 'transfer',
+});
+```
+
+### Name service
+
+```typescript
+// Reverse lookup address to get name
+const { response } = await grpcClient.nameService.reverseLookupName({
+	address: '0xabc...',
+});
+```
+
+### Signature verification service
+
+```typescript
+// Verify a signature
+const { response } = await grpcClient.signatureVerificationService.verifySignature({
+	message: {
+		name: 'TransactionData',
+		value: messageBytes,
+	},
+	signature: {
+		bcs: { value: signatureBytes },
+		signature: { oneofKind: undefined },
+	},
+	jwks: [],
+});
+```

package/docs/clients/index.md

@@ -0,0 +1,95 @@
+# Sui Clients
+
+> Choose and configure gRPC, GraphQL, or JSON-RPC clients for the Sui network.
+
+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:
+
+- Native API: Full access to everything the underlying API offers
+- [Core API](/sui/clients/core): A consistent interface across all clients for common operations
+
+## Available clients
+
+| 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)           |
+
+All clients are compatible with Mysten SDKs like `@mysten/walrus`, `@mysten/seal` and
+`@mysten/suins`.
+
+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).
+
+## Quick start
+
+```typescript
+
+const client = new SuiGrpcClient({
+	network: 'mainnet',
+	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...' });
+
+// Use the Core API for transport-agnostic operations
+const { object } = await client.core.getObject({ objectId: '0x...' });
+```
+
+## Native vs core API
+
+### 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
+
+// gRPC - access various service clients to call any gRPC method
+const { response } = await grpcClient.stateService.listOwnedObjects({ owner: '0x...' });
+
+// GraphQL - write type-safe custom queries using the graphql function
+const result = await graphqlClient.query({
+	query: graphql(`
+		query {
+			chainIdentifier
+		}
+	`),
+});
+
+// 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.
+
+## 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:
+
+```typescript
+
+const client = new SuiGrpcClient({ network: 'mainnet', baseUrl: '...' }).$extend(walrus());
+
+await client.walrus.writeBlob({ ... });
+```
+
+See [Building SDKs](/sui/sdk-building) for more on creating client extensions.

package/docs/clients/json-rpc.md

@@ -0,0 +1,239 @@
+# SuiJsonRpcClient
+
+> Connect to Sui through JSON-RPC with SuiJsonRpcClient.
+
+> **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.
+
+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`.
+
+```typescript
+
+const client = new SuiJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+});
+
+// Use the Core API
+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.
+
+```typescript
+
+// use getJsonRpcFullnodeUrl to define Devnet RPC location
+const rpcUrl = getJsonRpcFullnodeUrl('devnet');
+
+// create a client connected to devnet
+const client = new SuiJsonRpcClient({ url: rpcUrl, network: 'devnet' });
+
+// get coins owned by an address
+// replace <OWNER_ADDRESS> with actual address in the form of 0x123...
+await client.getCoins({
+	owner: '<OWNER_ADDRESS>',
+});
+```
+
+Network URLs:
+
+- `localnet`: `http://127.0.0.1:9000`
+- `devnet`: `https://fullnode.devnet.sui.io:443`
+- `testnet`: `https://fullnode.testnet.sui.io:443`
+
+For local development, you can run `cargo run --bin sui -- start --with-faucet --force-regenesis` to
+spin up a local network with a local validator, a Full node, and a faucet server. Refer to
+[the Local Network guide](https://docs.sui.io/guides/developer/getting-started/local-network) for
+more information.
+
+## Manually calling unsupported RPC methods
+
+You can use `SuiJsonRpcClient` to call any RPC method the node you're connecting to exposes. Most
+RPC methods are built into `SuiJsonRpcClient`, but you can use `call` to leverage any methods
+available in the RPC.
+
+```typescript
+
+const client = new SuiJsonRpcClient({
+	url: 'https://fullnode.devnet.sui.io:443',
+});
+// asynchronously call suix_getCommitteeInfo
+const committeeInfo = await client.call('suix_getCommitteeInfo', []);
+```
+
+For a full list of available RPC methods, see the
+[RPC documentation](https://docs.sui.io/references/sui-api).
+
+## 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.
+
+```typescript
+
+const client = new SuiJsonRpcClient({
+	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',
+			},
+		},
+	}),
+});
+```
+
+## Pagination
+
+`SuiJsonRpcClient` exposes a number of RPC methods that return paginated results. These methods
+return a result object with 3 fields:
+
+- `data`: The list of results for the current page
+- `nextCursor`: A cursor pointing to the next page of results
+- `hasNextPage`: A boolean indicating whether there are more pages of results
+
+Some APIs also accept an `order` option that can be set to either `ascending` or `descending` to
+change the order in which the results are returned.
+
+You can pass the `nextCursor` to the `cursor` option of the RPC method to retrieve the next page,
+along with a `limit` to specify the page size:
+
+```ts
+const page1 = await client.getCheckpoints({
+	descendingOrder: false,
+	limit: 10,
+});
+
+const page2 =
+	page1.hasNextPage &&
+	(await client.getCheckpoints({
+		descendingOrder: false,
+		cursor: page1.nextCursor,
+		limit: 10,
+	}));
+```
+
+## Methods
+
+In addition to the RPC methods mentioned above, `SuiJsonRpcClient` also exposes some methods for
+working with Transactions.
+
+### `executeTransactionBlock`
+
+```tsx
+const tx = new Transaction();
+
+// add transaction data to tx...
+
+const { bytes, signature } = await tx.sign({ client, signer: keypair });
+
+const result = await client.executeTransactionBlock({
+	transactionBlock: bytes,
+	signature,
+	options: {
+		showEffects: true,
+	},
+});
+```
+
+#### Arguments
+
+- `transactionBlock`: either a Transaction or BCS serialized transaction data bytes as a Uint8Array
+  or as a base-64 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`:
+  - `showBalanceChanges`: Whether to show balance_changes. Default to be False
+  - `showEffects`: Whether to show transaction effects. Default to be False
+  - `showEvents`: Whether to show transaction events. Default to be False
+  - `showInput`: Whether to show transaction input data. Default to be False
+  - `showObjectChanges`: Whether to show object_changes. Default to be False
+  - `showRawInput`: Whether to show bcs-encoded transaction input data
+
+### `signAndExecuteTransaction`
+
+```tsx
+const tx = new Transaction();
+
+// add transaction data to tx...
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+	options: {
+		showEffects: true,
+	},
+});
+
+// IMPORTANT: Always check the transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+```
+
+#### Arguments
+
+- `transaction`: BCS serialized transaction data bytes as a Uint8Array or as a base-64 encoded
+  string.
+- `signer`: A `Keypair` instance to sign the transaction
+- `options`:
+  - `showBalanceChanges`: Whether to show balance_changes. Default to be False
+  - `showEffects`: Whether to show transaction effects. Default to be False
+  - `showEvents`: Whether to show transaction events. Default to be False
+  - `showInput`: Whether to show transaction input data. Default to be False
+  - `showObjectChanges`: Whether to show object_changes. Default to be False
+  - `showRawInput`: Whether to show bcs-encoded transaction input data
+
+### `waitForTransaction`
+
+Wait for a transaction result to be available over the API. This can be used in conjunction with
+`signAndExecuteTransaction` to wait for the transaction to be available through the API. This
+currently polls the `getTransactionBlock` API to check for the transaction.
+
+```tsx
+const tx = new Transaction();
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+const transaction = await client.waitForTransaction({
+	digest: result.Transaction.digest,
+	options: {
+		showEffects: true,
+	},
+});
+```
+
+#### Arguments
+
+- `digest`: the digest of the queried transaction
+- `signal`: An optional abort signal that can be used to cancel the request
+- `timeout`: The amount of time to wait for a transaction. Defaults to one minute.
+- `pollInterval`: The amount of time to wait between checks for the transaction. Defaults to 2
+  seconds.
+- `options`:
+  - `showBalanceChanges`: Whether to show balance_changes. Default to be False
+  - `showEffects`: Whether to show transaction effects. Default to be False
+  - `showEvents`: Whether to show transaction events. Default to be False
+  - `showInput`: Whether to show transaction input data. Default to be False
+  - `showObjectChanges`: Whether to show object_changes. Default to be False
+  - `showRawInput`: Whether to show bcs-encoded transaction input data