@mysten/sui 2.22.0 → 2.23.1

package/src/graphql/queries/transactions.graphql

@@ -71,6 +71,32 @@ query getTransactionBlock(
 	}
 }
 
+query listTransactions(
+	$filter: TransactionFilter
+	$first: Int
+	$after: String
+	$last: Int
+	$before: String
+	$includeTransaction: Boolean = false
+	$includeEffects: Boolean = false
+	$includeEvents: Boolean = false
+	$includeBalanceChanges: Boolean = false
+	$includeObjectTypes: Boolean = false
+	$includeBcs: Boolean = false
+) {
+	transactions(filter: $filter, first: $first, after: $after, last: $last, before: $before) {
+		pageInfo {
+			hasNextPage
+			hasPreviousPage
+			startCursor
+			endCursor
+		}
+		nodes {
+			...TRANSACTION_FIELDS
+		}
+	}
+}
+
 fragment TRANSACTION_FIELDS on Transaction {
 	digest
 	transactionJson @include(if: $includeTransaction)
@@ -157,6 +183,9 @@ query resolveTransaction(
 			transaction {
 				transactionBcs
 				effects {
+					epoch {
+						epochId
+					}
 					status
 					executionError {
 						message

package/src/grpc/client.ts

@@ -127,6 +127,15 @@ export interface GrpcSimulateTransactionOptions<
 	Include extends GrpcSimulateTransactionInclude = {},
 > extends SuiClientTypes.SimulateTransactionOptions<Include> {
 	include?: Include & GrpcSimulateTransactionInclude;
+	/**
+	 * Overrides whether the server selects gas payment during simulation.
+	 *
+	 * When not set, gas selection is enabled only when the transaction's gas payment is explicitly
+	 * set to an empty list (`[]`), which indicates gas is paid from the sender's address balance.
+	 * Transactions with gas coins set are simulated as-is, and transactions without a gas payment
+	 * are simulated with a mocked gas coin.
+	 */
+	doGasSelection?: boolean;
 }
 
 export class SuiGrpcClient extends BaseClient implements SuiClientTypes.TransportMethods {
@@ -296,6 +305,16 @@ export class SuiGrpcClient extends BaseClient implements SuiClientTypes.Transpor
 		return this.core.getDynamicField(input);
 	}
 
+	listTransactions<Include extends SuiClientTypes.TransactionInclude = {}>(
+		input: SuiClientTypes.ListTransactionsOptions<Include>,
+	): Promise<SuiClientTypes.ListTransactionsResponse<Include>> {
+		return this.core.listTransactions(input);
+	}
+
+	listEvents(input: SuiClientTypes.ListEventsOptions): Promise<SuiClientTypes.ListEventsResponse> {
+		return this.core.listEvents(input);
+	}
+
 	getMoveFunction(
 		input: SuiClientTypes.GetMoveFunctionOptions,
 	): Promise<SuiClientTypes.GetMoveFunctionResponse> {

package/src/grpc/core.ts

@@ -43,12 +43,24 @@ import {
 	transactionToGrpcTransaction,
 	grpcTransactionToTransactionData,
 } from '../client/transaction-resolver.js';
+import { setAddressBalanceTransactionExpirationFromSimulatedEpoch } from '../client/address-balance-transaction-expiration.js';
+import { transactionBytesHaveEmptyGasPayment } from '../client/utils.js';
 import { Value } from './proto/google/protobuf/struct.js';
 import { ExecutedTransaction } from './proto/sui/rpc/v2/executed_transaction.js';
 import {
 	SimulateTransactionRequest_TransactionChecks,
 	SimulateTransactionResponse,
 } from './proto/sui/rpc/v2/transaction_execution_service.js';
+import type { QueryEnd, QueryOptions } from './proto/sui/rpc/v2/query_options.js';
+import { Ordering, QueryEndReason } from './proto/sui/rpc/v2/query_options.js';
+import type { ResolvedPagination } from '../client/query-filters.js';
+import {
+	resolveEventFilter,
+	resolvePagination,
+	resolveTransactionFilter,
+	validateTransactionQuery,
+} from '../client/query-filters.js';
+import { toGrpcEventFilter, toGrpcTransactionFilter } from './filters.js';
 
 export interface GrpcCoreClientOptions extends CoreClientOptions {
 	client: SuiGrpcClient;
@@ -386,8 +398,9 @@ export class GrpcCoreClient extends CoreClient {
 		);
 	}
 	async simulateTransaction<Include extends SuiClientTypes.SimulateTransactionInclude = {}>(
-		options: SuiClientTypes.SimulateTransactionOptions<Include>,
+		options: SuiClientTypes.SimulateTransactionOptions<Include> & { doGasSelection?: boolean },
 	): Promise<SuiClientTypes.SimulateTransactionResult<Include>> {
+		// The simulated transaction is nested one level deeper in the response
 		const paths = transactionReadMaskPaths(options.include, 'transaction.');
 		if (options.include?.commandResults) {
 			paths.push('command_outputs');
@@ -397,6 +410,15 @@ export class GrpcCoreClient extends CoreClient {
 			await options.transaction.prepareForSerialization({ client: this });
 		}
 
+		// A gas payment explicitly set to an empty list means gas is paid from the sender's
+		// address balance, so the server needs to perform gas selection rather than simulating
+		// with a mocked gas coin.
+		const doGasSelection =
+			options.doGasSelection ??
+			(options.transaction instanceof Uint8Array
+				? transactionBytesHaveEmptyGasPayment(options.transaction)
+				: options.transaction.getData().gasData.payment?.length === 0);
+
 		const { response } = await this.#client.transactionExecutionService.simulateTransaction(
 			{
 				transaction:
@@ -410,7 +432,7 @@ export class GrpcCoreClient extends CoreClient {
 				readMask: {
 					paths,
 				},
-				doGasSelection: false,
+				doGasSelection,
 				checks:
 					options.checksEnabled === false
 						? SimulateTransactionRequest_TransactionChecks.DISABLED
@@ -566,6 +588,158 @@ export class GrpcCoreClient extends CoreClient {
 		return this.#client.listDynamicFields(options);
 	}
 
+	async listTransactions<Include extends SuiClientTypes.TransactionInclude = {}>(
+		options: SuiClientTypes.ListTransactionsOptions<Include>,
+	): Promise<SuiClientTypes.ListTransactionsResponse<Include>> {
+		const paths = transactionReadMaskPaths(options.include);
+
+		const filter = options.filter
+			? await resolveTransactionFilter(this.mvr, options.filter, options.signal)
+			: undefined;
+		const pagination = resolvePagination(options);
+		validateTransactionQuery(filter, pagination);
+
+		const call = this.#client.ledgerService.listTransactions(
+			{
+				readMask: { paths },
+				filter: filter && toGrpcTransactionFilter(filter),
+				// Request one extra item as lookahead: the server reports its item limit as reached
+				// without scanning past it, so an exact-limit final page is otherwise
+				// indistinguishable from one with more results
+				options: toGrpcQueryOptions(pagination, pagination.limit + 1),
+			},
+			{ abort: options.signal },
+		);
+
+		const transactions: SuiClientTypes.TransactionResult<Include>[] = [];
+		let startCursor: string | null = null;
+		let endCursor: string | null = null;
+		let frontier: string | null = null;
+		let end: QueryEnd | undefined;
+		let sawLookaheadItem = false;
+
+		for await (const frame of call.responses) {
+			if (frame.watermark?.cursor) {
+				frontier = toBase64(frame.watermark.cursor);
+			}
+			if (frame.transaction) {
+				if (transactions.length >= pagination.limit) {
+					sawLookaheadItem = true;
+				} else {
+					startCursor ??= frontier;
+					endCursor = frontier;
+					transactions.push(
+						parseGrpcTransactionResponse(frame.transaction, { include: options.include }),
+					);
+				}
+			}
+			if (frame.end) {
+				end = frame.end;
+			}
+		}
+
+		// ITEM_LIMIT without the lookahead item means the server clamped the requested limit to
+		// its own maximum, so the filled page is still evidence of a possible next page
+		const hasNextPage =
+			sawLookaheadItem ||
+			end?.reason === QueryEndReason.SCAN_LIMIT ||
+			end?.reason === QueryEndReason.ITEM_LIMIT;
+
+		return {
+			transactions,
+			hasNextPage,
+			startCursor,
+			// Scans that stopped early without filling the page continue from the scan frontier
+			// (so already-scanned positions are not revisited), full pages continue after the last
+			// returned item, and terminal pages have no positions to continue from
+			endCursor: sawLookaheadItem ? endCursor : hasNextPage ? (frontier ?? endCursor) : endCursor,
+		};
+	}
+
+	async listEvents(
+		options: SuiClientTypes.ListEventsOptions,
+	): Promise<SuiClientTypes.ListEventsResponse> {
+		const pagination = resolvePagination(options);
+		const call = this.#client.ledgerService.listEvents(
+			{
+				readMask: {
+					paths: [
+						'package_id',
+						'module',
+						'sender',
+						'event_type',
+						'contents',
+						'json',
+						'checkpoint',
+						'transaction_digest',
+						'event_index',
+					],
+				},
+				filter: options.filter
+					? toGrpcEventFilter(await resolveEventFilter(this.mvr, options.filter, options.signal))
+					: undefined,
+				// Request one extra item as lookahead: the server reports its item limit as reached
+				// without scanning past it, so an exact-limit final page is otherwise
+				// indistinguishable from one with more results
+				options: toGrpcQueryOptions(pagination, pagination.limit + 1),
+			},
+			{ abort: options.signal },
+		);
+
+		const events: SuiClientTypes.EventEntry[] = [];
+		let startCursor: string | null = null;
+		let endCursor: string | null = null;
+		let frontier: string | null = null;
+		let end: QueryEnd | undefined;
+		let sawLookaheadItem = false;
+
+		for await (const frame of call.responses) {
+			if (frame.watermark?.cursor) {
+				frontier = toBase64(frame.watermark.cursor);
+			}
+			if (frame.event) {
+				if (events.length >= pagination.limit) {
+					sawLookaheadItem = true;
+				} else {
+					startCursor ??= frontier;
+					endCursor = frontier;
+					const event = frame.event;
+					events.push({
+						packageId: normalizeSuiAddress(event.packageId!),
+						module: event.module!,
+						sender: normalizeSuiAddress(event.sender!),
+						eventType: normalizeStructTag(event.eventType!),
+						bcs: event.contents?.value ?? new Uint8Array(),
+						json: event.json ? (Value.toJson(event.json) as Record<string, unknown>) : null,
+						checkpoint: event.checkpoint?.toString() ?? null,
+						transactionDigest: event.transactionDigest!,
+						eventIndex: event.eventIndex!,
+					});
+				}
+			}
+			if (frame.end) {
+				end = frame.end;
+			}
+		}
+
+		// ITEM_LIMIT without the lookahead item means the server clamped the requested limit to
+		// its own maximum, so the filled page is still evidence of a possible next page
+		const hasNextPage =
+			sawLookaheadItem ||
+			end?.reason === QueryEndReason.SCAN_LIMIT ||
+			end?.reason === QueryEndReason.ITEM_LIMIT;
+
+		return {
+			events,
+			hasNextPage,
+			startCursor,
+			// Scans that stopped early without filling the page continue from the scan frontier
+			// (so already-scanned positions are not revisited), full pages continue after the last
+			// returned item, and terminal pages have no positions to continue from
+			endCursor: sawLookaheadItem ? endCursor : hasNextPage ? (frontier ?? endCursor) : endCursor,
+		};
+	}
+
 	async verifyZkLoginSignature(
 		options: SuiClientTypes.VerifyZkLoginSignatureOptions,
 	): Promise<SuiClientTypes.ZkLoginVerifyResponse> {
@@ -720,14 +894,15 @@ export class GrpcCoreClient extends CoreClient {
 				snapshot.sender = '0x0000000000000000000000000000000000000000000000000000000000000000';
 			}
 			const grpcTransaction = transactionDataToGrpcTransaction(snapshot);
+			const doGasSelection =
+				!options.onlyTransactionKind &&
+				(snapshot.gasData.budget == null || snapshot.gasData.payment == null);
 
 			let response;
 			try {
 				const result = await client.transactionExecutionService.simulateTransaction({
 					transaction: grpcTransaction,
-					doGasSelection:
-						!options.onlyTransactionKind &&
-						(snapshot.gasData.budget == null || snapshot.gasData.payment == null),
+					doGasSelection,
 					// Kind-only txns are never executed directly and do not have sender, so skip validation checks.
 					checks: options.onlyTransactionKind
 						? SimulateTransactionRequest_TransactionChecks.DISABLED
@@ -739,6 +914,7 @@ export class GrpcCoreClient extends CoreClient {
 							'transaction.transaction.expiration',
 							'transaction.transaction.kind',
 							'transaction.effects.status',
+							'transaction.effects.epoch',
 						],
 					},
 				});
@@ -770,17 +946,35 @@ export class GrpcCoreClient extends CoreClient {
 			}
 
 			applyGrpcResolvedTransaction(transactionData, response.transaction.transaction, options);
+			await setAddressBalanceTransactionExpirationFromSimulatedEpoch({
+				transactionData,
+				client,
+				epoch: response.transaction.effects?.epoch,
+				originalTransactionData: snapshot,
+				isTransactionKindOnly: !!options.onlyTransactionKind,
+				doGasSelection,
+			});
 
 			return await next();
 		};
 	}
 }
 
+function toGrpcQueryOptions(pagination: ResolvedPagination, limit: number): QueryOptions {
+	return {
+		limit,
+		ordering: pagination.descending ? Ordering.DESCENDING : Ordering.ASCENDING,
+		after: pagination.after ? fromBase64(pagination.after) : undefined,
+		before: pagination.before ? fromBase64(pagination.before) : undefined,
+	};
+}
+
 function transactionReadMaskPaths(
 	include: SuiClientTypes.TransactionInclude | undefined,
 	prefix = '',
-) {
+): string[] {
 	const paths = ['digest', 'transaction.digest', 'signatures', 'effects.status'];
+
 	if (include?.transaction) {
 		paths.push(
 			'transaction.sender',
@@ -802,6 +996,7 @@ function transactionReadMaskPaths(
 		paths.push('events');
 	}
 	if (include?.objectTypes) {
+		// Use effects.changed_objects to match JSON-RPC behavior (which uses objectChanges)
 		paths.push('effects.changed_objects.object_type');
 		paths.push('effects.changed_objects.object_id');
 	}

package/src/grpc/filters.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ResolvedEventFilter, ResolvedTransactionFilter } from '../client/query-filters.js';
+import type { EventFilter, TransactionFilter } from './proto/sui/rpc/v2/filter.js';
+
+export function toGrpcTransactionFilter(filter: ResolvedTransactionFilter): TransactionFilter {
+	return {
+		terms: [
+			{
+				literals: [
+					filter.$kind === 'sender'
+						? {
+								negated: false,
+								predicate: { oneofKind: 'sender', sender: { address: filter.sender } },
+							}
+						: {
+								negated: false,
+								predicate: {
+									oneofKind: 'moveCall',
+									moveCall: {
+										function: [filter.package, filter.module, filter.function]
+											.filter(Boolean)
+											.join('::'),
+									},
+								},
+							},
+				],
+			},
+		],
+	};
+}
+
+export function toGrpcEventFilter(filter: ResolvedEventFilter): EventFilter {
+	return {
+		terms: [
+			{
+				literals: [
+					filter.$kind === 'sender'
+						? {
+								negated: false,
+								predicate: { oneofKind: 'sender', sender: { address: filter.sender } },
+							}
+						: filter.$kind === 'emitModule'
+							? {
+									negated: false,
+									predicate: {
+										oneofKind: 'emitModule',
+										emitModule: { module: `${filter.package}::${filter.module}` },
+									},
+								}
+							: {
+									negated: false,
+									predicate: {
+										oneofKind: 'eventType',
+										eventType: {
+											eventType:
+												filter.$kind === 'eventTypeModule'
+													? `${filter.package}::${filter.module}`
+													: filter.eventType,
+										},
+									},
+								},
+				],
+			},
+		],
+	};
+}

package/src/grpc/proto/sui/rpc/v2/event.ts

@@ -81,6 +81,37 @@ export interface Event {
 	 * @generated from protobuf field: optional google.protobuf.Value json = 6;
 	 */
 	json?: Value;
+	/**
+	 * The sequence number of the checkpoint that includes the transaction
+	 * that emitted this event. Populated when the event is delivered on its
+	 * own (for example via `LedgerService.ListEvents`); left unset when the
+	 * event is carried inside its transaction's `events` list, where the
+	 * enclosing `ExecutedTransaction` already provides this context.
+	 *
+	 * @generated from protobuf field: optional uint64 checkpoint = 7;
+	 */
+	checkpoint?: bigint;
+	/**
+	 * The digest of the transaction that emitted this event.
+	 *
+	 * @generated from protobuf field: optional string transaction_digest = 8;
+	 */
+	transactionDigest?: string;
+	/**
+	 * Zero-based position of the emitting transaction within its containing
+	 * checkpoint. For clients verifying authenticated event streams this
+	 * index is part of the BCS-encoded `EventCommitment` leaf used to
+	 * construct the per-checkpoint merkle root.
+	 *
+	 * @generated from protobuf field: optional uint64 transaction_index = 9;
+	 */
+	transactionIndex?: bigint;
+	/**
+	 * Zero-based index of this event within its transaction's event list.
+	 *
+	 * @generated from protobuf field: optional uint32 event_index = 10;
+	 */
+	eventIndex?: number;
 }
 // @generated message type with reflection information, may provide speed optimized methods
 class TransactionEvents$Type extends MessageType<TransactionEvents> {
@@ -106,6 +137,24 @@ class Event$Type extends MessageType<Event> {
 			{ no: 4, name: 'event_type', kind: 'scalar', opt: true, T: 9 /*ScalarType.STRING*/ },
 			{ no: 5, name: 'contents', kind: 'message', T: () => Bcs },
 			{ no: 6, name: 'json', kind: 'message', T: () => Value },
+			{
+				no: 7,
+				name: 'checkpoint',
+				kind: 'scalar',
+				opt: true,
+				T: 4 /*ScalarType.UINT64*/,
+				L: 0 /*LongType.BIGINT*/,
+			},
+			{ no: 8, name: 'transaction_digest', kind: 'scalar', opt: true, T: 9 /*ScalarType.STRING*/ },
+			{
+				no: 9,
+				name: 'transaction_index',
+				kind: 'scalar',
+				opt: true,
+				T: 4 /*ScalarType.UINT64*/,
+				L: 0 /*LongType.BIGINT*/,
+			},
+			{ no: 10, name: 'event_index', kind: 'scalar', opt: true, T: 13 /*ScalarType.UINT32*/ },
 		]);
 	}
 }

package/src/grpc/proto/sui/rpc/v2/executed_transaction.ts

@@ -80,6 +80,13 @@ export interface ExecutedTransaction {
 	 * @generated from protobuf field: optional sui.rpc.v2.ObjectSet objects = 9;
 	 */
 	objects?: ObjectSet;
+	/**
+	 * Zero-based position of this transaction within the checkpoint that
+	 * includes it.
+	 *
+	 * @generated from protobuf field: optional uint64 transaction_index = 10;
+	 */
+	transactionIndex?: bigint;
 }
 // @generated message type with reflection information, may provide speed optimized methods
 class ExecutedTransaction$Type extends MessageType<ExecutedTransaction> {
@@ -113,6 +120,14 @@ class ExecutedTransaction$Type extends MessageType<ExecutedTransaction> {
 				T: () => BalanceChange,
 			},
 			{ no: 9, name: 'objects', kind: 'message', T: () => ObjectSet },
+			{
+				no: 10,
+				name: 'transaction_index',
+				kind: 'scalar',
+				opt: true,
+				T: 4 /*ScalarType.UINT64*/,
+				L: 0 /*LongType.BIGINT*/,
+			},
 		]);
 	}
 }