@mysten/sui 2.23.2 → 2.25.0

package/docs/clients/grpc.md

@@ -1,46 +1,70 @@
 # SuiGrpcClient
 
-> Connect to Sui through gRPC with SuiGrpcClient.
+> Connect to Sui over gRPC, with native service clients and real-time subscriptions
 
-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:
+`SuiGrpcClient` talks to the full node gRPC API. It is the recommended default for application code
+and SDK integrations: it reads directly from a full node, and it is the only client with real-time
+subscriptions.
 
 ```typescript
 
-const grpcClient = new SuiGrpcClient({
-	network: 'testnet',
-	baseUrl: 'https://fullnode.testnet.sui.io:443',
+const client = new SuiGrpcClient({
+	network: 'mainnet',
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
 });
 ```
 
 For local development:
 
 ```typescript
-const grpcClient = new SuiGrpcClient({
+const client = new SuiGrpcClient({
 	network: 'localnet',
 	baseUrl: 'http://127.0.0.1:9000',
 });
 ```
 
+Reading data, executing transactions, and querying history all work the same way here as on any
+client. See [Querying data](/sui/clients/querying) and
+[Signing and execution](/sui/transactions/signing-and-execution). The rest of this page covers what
+is specific to gRPC.
+
+## gRPC-specific options
+
+Top-level gRPC methods are a superset of the shared API, adding fields where the transport exposes
+more data than the common shape can carry:
+
+| Option              | Available on                                                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `include.protoJson` | `getTransaction`, `executeTransaction`, `signAndExecuteTransaction`, `waitForTransaction`, `simulateTransaction` |
+
+`protoJson` returns the raw protobuf response alongside the parsed result, which is useful when you
+need a field the unified shape does not expose yet:
+
+```typescript
+const result = await client.getTransaction({
+	digest: 'ABC123...',
+	include: {
+		effects: true,
+		protoJson: true,
+	},
+});
+
+const transaction = result.Transaction ?? result.FailedTransaction;
+console.log(transaction.digest, result.protoJson);
+```
+
 ## 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.
+the Fetch API. The `GrpcWebFetchTransport` class, `GrpcWebOptions` type, and `RpcTransport` type are
+re-exported from `@mysten/sui/grpc`, so you can configure a transport without adding
+`@protobuf-ts/*` as a direct dependency.
 
 ### 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:
+The default transport uses the gRPC-web protocol over HTTP/1.1 or HTTP/2. Pass
+`GrpcWebFetchTransport` options to customize it:
 
 ```typescript
 
@@ -50,7 +74,7 @@ const transport = new GrpcWebFetchTransport({
 	// Additional transport options like fetchInit
 });
 
-const grpcClient = new SuiGrpcClient({
+const client = new SuiGrpcClient({
 	network: 'testnet',
 	transport,
 });
@@ -58,18 +82,14 @@ const grpcClient = new SuiGrpcClient({
 
 ### 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
+For server-side applications (Node.js, Bun, and others), use the native gRPC transport with
+`@protobuf-ts/grpc-transport` and `@grpc/grpc-js`. This speaks HTTP/2 and the native gRPC protocol
 rather than the gRPC-web translation layer.
 
-Install the required packages:
-
-```bash
+```npm
 npm install @protobuf-ts/grpc-transport @grpc/grpc-js
 ```
 
-Then create the client with a `GrpcTransport`:
-
 ```typescript
 
 const transport = new GrpcTransport({
@@ -77,96 +97,71 @@ const transport = new GrpcTransport({
 	channelCredentials: ChannelCredentials.createSsl(),
 });
 
-const grpcClient = new SuiGrpcClient({
+const client = new SuiGrpcClient({
 	network: 'testnet',
 	transport,
 });
 ```
 
-For local development without TLS:
+For local development without TLS, use `ChannelCredentials.createInsecure()` and a plain
+`host: '127.0.0.1:9000'`.
 
-```typescript
+## Read masks
 
-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:
+gRPC responses are opt-in. A request names the fields it wants in a `readMask`, and the server
+returns only those. Paths are proto field names in `snake_case`, and nested fields are dotted:
 
 ```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>',
+const { response } = await client.ledgerService.getTransaction({
+	digest: 'ABC123...',
+	readMask: { paths: ['digest', 'effects.status', 'transaction.sender'] },
 });
 ```
 
-To query additional data not available in the core API, you can use the service clients directly:
+A field you did not ask for comes back unset, which is the most common surprise when moving from a
+JSON-RPC mindset: an empty field usually means it was not requested rather than that it has no
+value.
 
-### Transaction execution service
+The top-level methods build masks for you from their `include` options, adding the paths each option
+needs on top of the handful every result carries. That is the main reason to prefer them: field
+selection and the mapping back into the unified shape are handled for you.
 
-```typescript
-const { response } = await grpcClient.transactionExecutionService.executeTransaction({
-	transaction: {
-		bcs: {
-			value: transactionBytes,
-		},
-	},
-	signatures: signatures.map((sig) => ({
-		bcs: { value: fromBase64(sig) },
-		signature: { oneofKind: undefined },
-	})),
-});
+## Using service clients
 
-// 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'}`);
-}
-```
+`SuiGrpcClient` exposes the generated service clients as properties, so any RPC the node serves is
+reachable even where the shared API has no method for it:
+
+| Property                       | Service                                   |
+| ------------------------------ | ----------------------------------------- |
+| `ledgerService`                | Ledger reads, and the streaming list RPCs |
+| `stateService`                 | Live object and balance state             |
+| `transactionExecutionService`  | Transaction execution                     |
+| `subscriptionService`          | Real-time streams                         |
+| `movePackageService`           | Move package metadata                     |
+| `nameService`                  | SuiNS lookup and reverse lookup           |
+| `signatureVerificationService` | Signature verification                    |
+| `forkingService`               | Admin APIs, for `sui-fork` instances only |
 
-### Ledger service
+The clients are generated with [protobuf-ts](https://github.com/timostamm/protobuf-ts). Each call
+takes the request message and an optional `RpcOptions`, where `abort` carries an `AbortSignal`:
 
 ```typescript
-// Get transaction by digest
-const { response } = await grpcClient.ledgerService.getTransaction({
-	digest: '0x123...',
-});
+const controller = new AbortController();
 
-// Get current epoch information
-const { response: epochInfo } = await grpcClient.ledgerService.getEpoch({});
+const { response } = await client.nameService.lookupName(
+	{ name: 'example.sui' },
+	{ abort: controller.signal },
+);
 ```
 
-The ledger service also provides streaming `listCheckpoints`, `listTransactions`, and `listEvents`
-RPCs. For most use cases, prefer the corresponding
-[core API query methods](/sui/clients/core#query-methods) (`listTransactions` and `listEvents`),
-which handle pagination and filter construction for you. The raw RPCs additionally support DNF
-filters (combined, negated, and additional predicates like `affected_address` and `package_write`)
-and checkpoint range bounds that the core API does not expose:
+Request and response shapes come from the proto definitions, so the generated types are the
+reference for what each RPC accepts. Filters on the list and subscribe RPCs are one place worth
+knowing the shape: a filter is a list of `terms` ORed together, each term a list of `literals` ANDed
+together, and `negated: true` inverts a literal.
 
 ```typescript
-// Transactions that affected an address but were not sent by it:
-const stream = grpcClient.ledgerService.listTransactions({
+// Transactions that affected an address but were not sent by it
+const stream = client.ledgerService.listTransactions({
 	filter: {
 		terms: [
 			{
@@ -188,21 +183,116 @@ const stream = grpcClient.ledgerService.listTransactions({
 	},
 	readMask: { paths: ['digest'] },
 });
+```
 
-for await (const frame of stream.responses) {
-	if (frame.transaction) {
-		console.log(frame.transaction.digest);
-	}
+An absent filter matches everything; a present filter needs at least one term.
+
+## Generated types and helpers
+
+`@mysten/sui/grpc` re-exports everything you need to work with the generated API, so nothing has to
+depend on `@protobuf-ts/*` or the proto files directly.
+
+`GrpcTypes` is a namespace holding every generated message interface and enum. Use it to type values
+you pass around, and to reference enums by name rather than by number:
+
+```typescript
+
+function describe(status: GrpcTypes.ExecutionStatus) {
+	return status.success ? 'succeeded' : status.error?.description;
 }
+
+const ordering = GrpcTypes.Ordering.DESCENDING;
+```
+
+Two helpers map a raw protobuf response into the same shape the top-level methods return, which is
+useful when you drop to a service client for the request but still want the unified result:
+
+```typescript
+
+const { response } = await client.ledgerService.getTransaction({
+	digest: 'ABC123...',
+	readMask: { paths: ['digest', 'effects'] },
+});
+
+// Same discriminated union that client.getTransaction() returns
+const result = parseGrpcTransactionResponse(response.transaction!, {
+	include: { effects: true },
+});
 ```
 
-### Subscription service
+`parseGrpcSimulateTransactionResponse` does the same for `SimulateTransactionResponse`.
 
-Subscribe to filtered, real-time streams of checkpoints, transactions, or events. Streams begin at
-the current tip of the chain:
+| Export                                                    | Use                                                   |
+| --------------------------------------------------------- | ----------------------------------------------------- |
+| `GrpcTypes`                                               | Generated message interfaces and enums                |
+| `parseGrpcTransactionResponse`                            | Raw `ExecutedTransaction` to the unified result shape |
+| `parseGrpcSimulateTransactionResponse`                    | Raw simulation response to the unified result shape   |
+| `GrpcWebFetchTransport`, `GrpcWebOptions`, `RpcTransport` | Configuring a [transport](#transport-options)         |
+| `SuiGrpcClientOptions`, `GrpcTransactionInclude`, …       | Typing your own wrappers around the client            |
+| `isSuiGrpcClient`                                         | Type guard for narrowing an unknown client            |
+
+## Streaming responses
+
+The list and subscribe RPCs return server streams rather than a single response, consumed with
+`for await` over `stream.responses`. Both use the same frame shape.
+
+A list RPC is a stream of frames, not a single response. Each frame either delivers one item or just
+reports progress, and every frame carries a `watermark` whose `cursor` is a safe resume point.
+Exactly one frame of a successful stream carries `end`, reporting why the scan stopped.
+
+This matters because a single request does not necessarily reach the end of the range you asked for:
+the server bounds how much ledger a filtered scan reads, so a stream can stop early and report
+`SCAN_LIMIT`. Reissue from the last watermark cursor until the reason says the scan is genuinely
+finished:
 
 ```typescript
-const stream = grpcClient.subscriptionService.subscribeTransactions({
+
+let resumeFrom: Uint8Array | undefined;
+let reason: GrpcTypes.QueryEndReason | undefined;
+
+// One request can stop before the range is exhausted, so scan until the range bound is reached
+do {
+	const stream = client.ledgerService.listEvents({
+		readMask: { paths: ['event_type', 'transaction_digest', 'event_index'] },
+		// Bound the scan. Without an end, this walks the whole ledger to the current tip
+		startCheckpoint: 1_000_000n,
+		endCheckpoint: 1_000_100n,
+		options: {
+			after: resumeFrom,
+			limit: 100,
+			ordering: GrpcTypes.Ordering.ASCENDING,
+		},
+	});
+
+	for await (const frame of stream.responses) {
+		// The latest watermark is always the safe place to resume from
+		resumeFrom = frame.watermark?.cursor ?? resumeFrom;
+		reason = frame.end?.reason ?? reason;
+
+		if (frame.event) {
+			console.log(frame.event.eventType, frame.event.transactionDigest);
+		}
+	}
+} while (reason === GrpcTypes.QueryEndReason.SCAN_LIMIT);
+```
+
+`options.after` and `options.before` are ledger-position bounds that mean the same thing in both
+directions (ordering only controls the order of items within the interval), and they intersect with
+the checkpoint range when both are given.
+
+## Subscriptions
+
+`subscriptionService` provides filtered, real-time streams. Each subscription pairs with the list
+RPC of the same name: same filter message, same item and watermark shapes, same cursor semantics.
+
+| Method                  | Yields                                          |
+| ----------------------- | ----------------------------------------------- |
+| `subscribeCheckpoints`  | Checkpoints, and progress-only cursor frames    |
+| `subscribeTransactions` | Executed transactions, and progress-only frames |
+| `subscribeEvents`       | Emitted events, and progress-only frames        |
+
+```typescript
+const stream = client.subscriptionService.subscribeTransactions({
 	filter: {
 		terms: [
 			{
@@ -220,59 +310,66 @@ const stream = grpcClient.subscriptionService.subscribeTransactions({
 
 for await (const frame of stream.responses) {
 	if (frame.transaction) {
-		console.log(frame.transaction.digest);
+		console.log(frame.transaction.digest, frame.transaction.effects?.status?.success);
 	}
 }
 ```
 
-### State service
+Omit `filter` to receive everything.
+
+### Frames and watermarks
+
+A subscription behaves like an unbounded ascending scan, so its frames work the same way as a
+[list RPC's](#streaming-responses), with two differences: checkpoint frames are checkpoint-granular
+and carry a `cursor` sequence number instead of a watermark, and the first frame of a filtered
+subscription is always progress-only, establishing the start position. Progress also keeps advancing
+with bounded staleness while nothing matches, which is what keeps a sparse filter alive. Track the
+cursor on every frame, not just the ones with items:
 
 ```typescript
-// List owned objects
-const { response } = await grpcClient.stateService.listOwnedObjects({
-	owner: '0xabc...',
-	objectType: '0x2::coin::Coin<0x2::sui::SUI>',
-});
+let lastCursor: Uint8Array | undefined;
 
-// Get dynamic fields
-const { response: fields } = await grpcClient.stateService.listDynamicFields({
-	parent: '0x123...',
-});
+for await (const frame of stream.responses) {
+	lastCursor = frame.watermark?.cursor ?? lastCursor;
+
+	if (frame.transaction) {
+		await handleTransaction(frame.transaction);
+	}
+}
 ```
 
-### Move package service
+### Cancelling a subscription
+
+Subscription streams have no successful end. They run until the client cancels them, or until the
+server terminates them with a gRPC status. Pass an `AbortSignal` through `RpcOptions`:
 
 ```typescript
-// Get function information
-const { response } = await grpcClient.movePackageService.getFunction({
-	packageId: '0x2',
-	moduleName: 'coin',
-	name: 'value',
-});
-```
+const controller = new AbortController();
 
-### Name service
+const stream = client.subscriptionService.subscribeEvents(
+	{ readMask: { paths: ['event_type', 'transaction_digest'] } },
+	{ abort: controller.signal },
+);
 
-```typescript
-// Reverse lookup address to get name
-const { response } = await grpcClient.nameService.reverseLookupName({
-	address: '0xabc...',
-});
+// Later, to tear the stream down
+controller.abort();
 ```
 
-### Signature verification service
+### Recovering missed data
 
-```typescript
-// Verify a signature
-const { response } = await grpcClient.signatureVerificationService.verifySignature({
-	message: {
-		name: 'TransactionData',
-		value: messageBytes,
-	},
-	signature: {
-		bcs: { value: signatureBytes },
-		signature: { oneofKind: undefined },
-	},
-	jwks: [],
-});
-```
+Subscriptions do not resume: a new subscription starts at the current tip, so anything that happened
+while you were disconnected is skipped. Close the gap with the paired list RPC, scanning between the
+last cursor you processed and the cursor the new subscription reported in its first frame. Pass them
+as `options.after` and `options.before`. The indexed tip the list RPC reads from can trail the
+subscription's start position, so repeat the scan until a terminal frame reports `CURSOR_BOUND`
+rather than `LEDGER_TIP`.
+
+A durable consumer therefore keeps two pieces of state: the last cursor it processed, and the start
+cursor of each new subscription. On reconnect, open the subscription first, buffer its frames,
+replay the gap, then drain the buffer.
+
+Checkpoint subscriptions recover differently. `subscribeCheckpoints` reports its position as a
+checkpoint sequence number rather than a watermark cursor, and `listCheckpoints` bounds a scan with
+`startCheckpoint` and `endCheckpoint` rather than `options.after` and `options.before`. Replay that
+gap by listing from the sequence number after the last one you processed, up to the sequence number
+the new subscription started at.

package/docs/clients/index.md

@@ -1,28 +1,22 @@
 # Sui Clients
 
-> Choose and configure gRPC, GraphQL, or JSON-RPC clients for the Sui network.
+> Choose between SuiGrpcClient and SuiGraphQLClient and understand their shared API
 
-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:
+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.
 
-- Native API: Full access to everything the underlying API offers
-- [Core API](/sui/clients/core): A consistent interface across all clients for common operations
+| 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         |
 
-## Available clients
+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.
 
-| 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).
+> **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
 
@@ -33,26 +27,76 @@ 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...' });
 
-// Use the Core API for transport-agnostic operations
-const { object } = await client.core.getObject({ objectId: '0x...' });
+const { object } = await client.getObject({
+	objectId: '0x...',
+	include: { content: true },
+});
 ```
 
-## Native vs core API
+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',
+});
+```
 
-### Native API
+## Three ways to call a client
 
-Each client exposes the full capabilities of its underlying transport. Use the native API when you
-need transport-specific features or want maximum control:
+Each client exposes the same functionality through three surfaces, aimed at different callers.
+
+### Top-level methods
+
+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({
+	owner: '0x...',
+	include: { display: true },
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction,
+	signer,
+	include: { effects: true, balanceChanges: true },
+});
+```
+
+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.
+
+### `client.core`
 
-// gRPC - access various service clients to call any gRPC method
-const { response } = await grpcClient.stateService.listOwnedObjects({ owner: '0x...' });
+The transport-agnostic contract, for libraries that must work with whichever client their caller
+supplies:
 
-// GraphQL - write type-safe custom queries using the graphql function
+```typescript
+
+	return client.core.getObject({
+		objectId,
+		include: { content: true },
+	});
+}
+```
+
+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.
+
+### Native APIs
+
+Each client also exposes its transport in full, for the cases the shared API does not cover:
+
+```typescript
+// gRPC: generated service clients, read masks, and streams
+const { response } = await grpcClient.ledgerService.getServiceInfo({});
+
+// GraphQL: type-safe custom queries
 const result = await graphqlClient.query({
 	query: graphql(`
 		query {
@@ -60,36 +104,28 @@ 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.
+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.