SuiGrpcClient

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.

import { SuiGrpcClient } from '@mysten/sui/grpc';

const client = new SuiGrpcClient({
	network: 'mainnet',
	baseUrl: 'https://fullnode.mainnet.sui.io:443',
});

For local development:

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 and 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:

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:

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, which works in browsers and Node.js through 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. Pass GrpcWebFetchTransport options to customize it:

import { SuiGrpcClient, GrpcWebFetchTransport } from '@mysten/sui/grpc';

const transport = new GrpcWebFetchTransport({
	baseUrl: 'https://your-custom-grpc-endpoint.com',
	format: 'binary', // default is 'text' (base64-encoded)
	// Additional transport options like fetchInit
});

const client = new SuiGrpcClient({
	network: 'testnet',
	transport,
});

Native gRPC transport

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.

npm install @protobuf-ts/grpc-transport @grpc/grpc-js

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { GrpcTransport } from '@protobuf-ts/grpc-transport';
import { ChannelCredentials } from '@grpc/grpc-js';

const transport = new GrpcTransport({
	host: 'fullnode.testnet.sui.io:443',
	channelCredentials: ChannelCredentials.createSsl(),
});

const client = new SuiGrpcClient({
	network: 'testnet',
	transport,
});

For local development without TLS, use ChannelCredentials.createInsecure() and a plain host: '127.0.0.1:9000'.

Read masks

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:

const { response } = await client.ledgerService.getTransaction({
	digest: 'ABC123...',
	readMask: { paths: ['digest', 'effects.status', 'transaction.sender'] },
});

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.

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.

Using service clients

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:

The clients are generated with protobuf-ts. Each call takes the request message and an optional RpcOptions, where abort carries an AbortSignal:

const controller = new AbortController();

const { response } = await client.nameService.lookupName(
	{ name: 'example.sui' },
	{ abort: controller.signal },
);

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.

// Transactions that affected an address but were not sent by it
const stream = client.ledgerService.listTransactions({
	filter: {
		terms: [
			{
				literals: [
					{
						negated: false,
						predicate: {
							oneofKind: 'affectedAddress',
							affectedAddress: { address: '0xabc...' },
						},
					},
					{
						negated: true,
						predicate: { oneofKind: 'sender', sender: { address: '0xabc...' } },
					},
				],
			},
		],
	},
	readMask: { paths: ['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:

import { GrpcTypes } from '@mysten/sui/grpc';

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:

import { parseGrpcTransactionResponse } from '@mysten/sui/grpc';

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 },
});

parseGrpcSimulateTransactionResponse does the same for SimulateTransactionResponse.

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:

import { GrpcTypes } from '@mysten/sui/grpc';

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.

const stream = client.subscriptionService.subscribeTransactions({
	filter: {
		terms: [
			{
				literals: [
					{
						negated: false,
						predicate: { oneofKind: 'sender', sender: { address: '0xabc...' } },
					},
				],
			},
		],
	},
	readMask: { paths: ['digest', 'effects.status'] },
});

for await (const frame of stream.responses) {
	if (frame.transaction) {
		console.log(frame.transaction.digest, frame.transaction.effects?.status?.success);
	}
}

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, 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:

let lastCursor: Uint8Array | undefined;

for await (const frame of stream.responses) {
	lastCursor = frame.watermark?.cursor ?? lastCursor;

	if (frame.transaction) {
		await handleTransaction(frame.transaction);
	}
}

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:

const controller = new AbortController();

const stream = client.subscriptionService.subscribeEvents(
	{ readMask: { paths: ['event_type', 'transaction_digest'] } },
	{ abort: controller.signal },
);

// Later, to tear the stream down
controller.abort();

Recovering missed data

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.