@mysten/sui 2.22.1 → 2.23.1

package/src/client/types.ts

@@ -366,7 +366,12 @@ export namespace SuiClientTypes {
 		balanceChanges?: boolean;
 		/** Include parsed transaction effects (gas used, changed objects, status, etc.). */
 		effects?: boolean;
-		/** Include events emitted by the transaction. */
+		/**
+		 * Include events emitted by the transaction.
+		 *
+		 * On the GraphQL transport, at most the first 50 events of a transaction are returned;
+		 * gRPC and JSON-RPC return the full event list.
+		 */
 		events?: boolean;
 		/** Include a map of object IDs to their types for all changed objects. */
 		objectTypes?: boolean;
@@ -461,6 +466,186 @@ export namespace SuiClientTypes {
 		checksEnabled?: boolean;
 	}
 
+	/** Query methods */
+	export interface TransportMethods {
+		listTransactions: <Include extends TransactionInclude = {}>(
+			options: ListTransactionsOptions<Include>,
+		) => Promise<ListTransactionsResponse<Include>>;
+		listEvents: (options: ListEventsOptions) => Promise<ListEventsResponse>;
+	}
+
+	/**
+	 * A filter matching transactions. Exactly one predicate must be specified.
+	 *
+	 * All predicates are supported identically by every transport.
+	 */
+	export type TransactionFilter =
+		| {
+				/** Match transactions sent by this address. */
+				sender: string;
+				function?: never;
+		  }
+		| {
+				/**
+				 * Match transactions that called a Move function, specified as a
+				 * `::`-delimited Move path: `package`, `package::module`, or
+				 * `package::module::function`.
+				 */
+				function: string;
+				sender?: never;
+		  };
+
+	/**
+	 * A filter matching events. Exactly one predicate must be specified.
+	 *
+	 * All predicates are supported by every transport, with one caveat: on the deprecated
+	 * JSON-RPC transport, an `eventType` naming a generic type must include type arguments —
+	 * a bare generic name (e.g. `0xpkg::mod::Event` for events of type `0xpkg::mod::Event<T>`)
+	 * matches any instantiation on gRPC and GraphQL, but matches nothing on JSON-RPC, which
+	 * compares the full type for exact equality.
+	 */
+	export type EventFilter =
+		| {
+				/** Match events emitted by transactions sent by this address. */
+				sender: string;
+				emitModule?: never;
+				eventType?: never;
+		  }
+		| {
+				/** Match events emitted by a module, specified as `package::module`. */
+				emitModule: string;
+				sender?: never;
+				eventType?: never;
+		  }
+		| {
+				/**
+				 * Match events by type: either every event whose type is defined in a
+				 * module (`package::module`), or events with a fully qualified type
+				 * name (`package::module::Name` or `package::module::Name<T1, T2>`).
+				 *
+				 * A bare generic name (`package::module::Name` without type arguments) matches
+				 * any instantiation on gRPC and GraphQL, but matches nothing on the deprecated
+				 * JSON-RPC transport, which compares the full type for exact equality.
+				 */
+				eventType: string;
+				sender?: never;
+				emitModule?: never;
+		  };
+
+	export interface ListTransactionsOptions<
+		Include extends TransactionInclude = {},
+	> extends CoreClientMethodOptions {
+		filter?: TransactionFilter;
+		/**
+		 * Maximum number of items to return. Defaults to 50.
+		 *
+		 * Servers cap page sizes (50 by default): values above the server's cap cause the
+		 * GraphQL and JSON-RPC transports to throw, while gRPC servers silently truncate
+		 * the page to their configured maximum.
+		 */
+		limit?: number;
+		/**
+		 * Return items strictly after this cursor in ledger order (usually the `endCursor` of
+		 * an ascending page, or the `startCursor` of a descending page to poll for new items).
+		 * Implies `order: 'ascending'`, and cannot be combined with `before`.
+		 */
+		after?: string | null;
+		/**
+		 * Return items strictly before this cursor in ledger order (usually the `endCursor` of
+		 * a descending page). Implies `order: 'descending'`, and cannot be combined with
+		 * `after`.
+		 */
+		before?: string | null;
+		/** Order of returned results. Defaults to `ascending` (oldest first). */
+		order?: 'ascending' | 'descending';
+		include?: Include & TransactionInclude;
+	}
+
+	export interface ListTransactionsResponse<out Include extends TransactionInclude = {}> {
+		transactions: TransactionResult<Include>[];
+		/**
+		 * Whether more items may be available after this page.
+		 *
+		 * gRPC servers bound how much of the ledger a single request scans, so a scan-limited
+		 * query can return fewer items than `limit` (even none) with `hasNextPage: true`;
+		 * continuing from `endCursor` always makes progress through the scanned range.
+		 */
+		hasNextPage: boolean;
+		/**
+		 * Cursor at the first returned item. After a descending read of the most recent
+		 * items, pass as `after` to poll for items added since.
+		 */
+		startCursor: string | null;
+		/**
+		 * Cursor at the last returned item. Continue the query by passing it as `after`
+		 * (ascending) or `before` (descending).
+		 */
+		endCursor: string | null;
+	}
+
+	export interface ListEventsOptions extends CoreClientMethodOptions {
+		filter?: EventFilter;
+		/**
+		 * Maximum number of items to return. Defaults to 50.
+		 *
+		 * Servers cap page sizes (50 by default): values above the server's cap cause the
+		 * GraphQL and JSON-RPC transports to throw, while gRPC servers silently truncate
+		 * the page to their configured maximum.
+		 */
+		limit?: number;
+		/**
+		 * Return items strictly after this cursor in ledger order (usually the `endCursor` of
+		 * an ascending page, or the `startCursor` of a descending page to poll for new items).
+		 * Implies `order: 'ascending'`, and cannot be combined with `before`.
+		 */
+		after?: string | null;
+		/**
+		 * Return items strictly before this cursor in ledger order (usually the `endCursor` of
+		 * a descending page). Implies `order: 'descending'`, and cannot be combined with
+		 * `after`.
+		 */
+		before?: string | null;
+		/** Order of returned results. Defaults to `ascending` (oldest first). */
+		order?: 'ascending' | 'descending';
+	}
+
+	/** An event returned from a query, along with its position in the ledger. */
+	export interface EventEntry extends Event {
+		/**
+		 * The sequence number of the checkpoint containing the emitting transaction.
+		 *
+		 * `null` on the JSON-RPC transport, which does not expose checkpoint
+		 * information for queried events.
+		 */
+		checkpoint: string | null;
+		/** The digest of the transaction that emitted this event. */
+		transactionDigest: string;
+		/** The index of this event within its transaction's event list. */
+		eventIndex: number;
+	}
+
+	export interface ListEventsResponse {
+		events: EventEntry[];
+		/**
+		 * Whether more items may be available after this page.
+		 *
+		 * gRPC servers bound how much of the ledger a single request scans, so a scan-limited
+		 * query can return fewer items than `limit` (even none) with `hasNextPage: true`;
+		 * continuing from `endCursor` always makes progress through the scanned range.
+		 */
+		hasNextPage: boolean;
+		/**
+		 * Cursor at the first returned item. After a descending read of the most recent
+		 * items, pass as `after` to poll for items added since.
+		 */
+		startCursor: string | null;
+		/**
+		 * Cursor at the last returned item. Continue the query by passing it as `after`
+		 * (ascending) or `before` (descending).
+		 */
+		endCursor: string | null;
+	}
+
 	export interface GetReferenceGasPriceOptions extends CoreClientMethodOptions {}
 
 	export interface TransportMethods {

package/src/client/utils.ts

@@ -401,6 +401,19 @@ export function parseTransactionBcs(
 	).snapshot();
 }
 
+/**
+ * Checks whether serialized transaction bytes have a gas payment explicitly set to an empty
+ * list, which indicates gas is paid from the sender's address balance. Returns false for
+ * bytes that can't be parsed as `TransactionData`, leaving validation to the server.
+ */
+export function transactionBytesHaveEmptyGasPayment(bytes: Uint8Array): boolean {
+	try {
+		return bcs.TransactionData.parse(bytes).V1?.gasData.payment?.length === 0;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Extracts just the status from transaction effects BCS without fully parsing.
  * This is optimized for cases where we only need the status (success/failure)

package/src/graphql/client.ts

@@ -70,6 +70,20 @@ export function isSuiGraphQLClient(client: unknown): client is SuiGraphQLClient
 	);
 }
 
+export interface GraphQLSimulateTransactionOptions<
+	Include extends SuiClientTypes.SimulateTransactionInclude = {},
+> extends SuiClientTypes.SimulateTransactionOptions<Include> {
+	/**
+	 * 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 interface DynamicFieldInclude {
 	value?: boolean;
 }
@@ -230,7 +244,7 @@ export class SuiGraphQLClient<Queries extends Record<string, GraphQLDocument> =
 	}
 
 	simulateTransaction<Include extends SuiClientTypes.SimulateTransactionInclude = {}>(
-		input: SuiClientTypes.SimulateTransactionOptions<Include>,
+		input: GraphQLSimulateTransactionOptions<Include>,
 	): Promise<SuiClientTypes.SimulateTransactionResult<Include>> {
 		return this.core.simulateTransaction(input);
 	}
@@ -324,6 +338,16 @@ export class SuiGraphQLClient<Queries extends Record<string, GraphQLDocument> =
 		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/graphql/core.ts

@@ -28,6 +28,8 @@ import {
 	GetOwnedObjectsDocument,
 	GetReferenceGasPriceDocument,
 	GetTransactionBlockDocument,
+	ListEventsDocument,
+	ListTransactionsDocument,
 	MultiGetObjectsDocument,
 	ResolveTransactionDocument,
 	SimulateTransactionDocument,
@@ -36,8 +38,12 @@ import {
 } from './generated/queries.js';
 import { ObjectError, SimulationError } from '../client/errors.js';
 import { chunk, fromBase64, toBase64 } from '@mysten/utils';
-import { normalizeSuiAddress } from '../utils/sui-types.js';
-import { formatMoveAbortMessage, parseTransactionEffectsBcs } from '../client/utils.js';
+import { normalizeStructTag, normalizeSuiAddress } from '../utils/sui-types.js';
+import {
+	formatMoveAbortMessage,
+	parseTransactionEffectsBcs,
+	transactionBytesHaveEmptyGasPayment,
+} from '../client/utils.js';
 import type { OpenMoveTypeSignatureBody, OpenMoveTypeSignature } from './types.js';
 import {
 	transactionDataToGrpcTransaction,
@@ -50,6 +56,12 @@ import { TransactionEffects as TransactionEffectsType } from '../grpc/proto/sui/
 import { Transaction as GrpcTransactionType } from '../grpc/proto/sui/rpc/v2/transaction.js';
 import { TransactionDataBuilder } from '../transactions/TransactionData.js';
 import type { BuildTransactionOptions } from '../transactions/index.js';
+import {
+	resolveEventFilter,
+	resolvePagination,
+	resolveTransactionFilter,
+	validateTransactionQuery,
+} from '../client/query-filters.js';
 
 export class GraphQLCoreClient extends CoreClient {
 	#graphqlClient: SuiGraphQLClient;
@@ -386,12 +398,21 @@ export class GraphQLCoreClient extends CoreClient {
 		return parseTransaction(result.effects?.transaction!, options.include);
 	}
 	async simulateTransaction<Include extends SuiClientTypes.SimulateTransactionInclude = {}>(
-		options: SuiClientTypes.SimulateTransactionOptions<Include>,
+		options: SuiClientTypes.SimulateTransactionOptions<Include> & { doGasSelection?: boolean },
 	): Promise<SuiClientTypes.SimulateTransactionResult<Include>> {
 		if (!(options.transaction instanceof Uint8Array)) {
 			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 result = await this.#graphqlQuery(
 			{
 				query: SimulateTransactionDocument,
@@ -411,6 +432,7 @@ export class GraphQLCoreClient extends CoreClient {
 					includeObjectTypes: options.include?.objectTypes ?? false,
 					includeCommandResults: options.include?.commandResults ?? false,
 					includeBcs: options.include?.bcs ?? false,
+					doGasSelection,
 					checksEnabled: options.checksEnabled ?? true,
 				},
 			},
@@ -593,6 +615,124 @@ export class GraphQLCoreClient extends CoreClient {
 		return this.#graphqlClient.listDynamicFields(options);
 	}
 
+	async listTransactions<Include extends SuiClientTypes.TransactionInclude = {}>(
+		options: SuiClientTypes.ListTransactionsOptions<Include>,
+	): Promise<SuiClientTypes.ListTransactionsResponse<Include>> {
+		const pagination = resolvePagination(options);
+		const { descending, after, before, limit } = pagination;
+		const filter = options.filter
+			? await resolveTransactionFilter(this.mvr, options.filter, options.signal)
+			: undefined;
+		validateTransactionQuery(filter, pagination);
+
+		const transactions = await this.#graphqlQuery(
+			{
+				query: ListTransactionsDocument,
+				signal: options.signal,
+				variables: {
+					filter: filter && {
+						sentAddress: filter.$kind === 'sender' ? filter.sender : undefined,
+						function:
+							filter.$kind === 'function'
+								? [filter.package, filter.module, filter.function].filter(Boolean).join('::')
+								: undefined,
+					},
+					first: descending ? undefined : limit,
+					after,
+					last: descending ? limit : undefined,
+					before,
+					includeTransaction: options.include?.transaction ?? false,
+					includeEffects: options.include?.effects ?? false,
+					includeEvents: options.include?.events ?? false,
+					includeBalanceChanges: options.include?.balanceChanges ?? false,
+					includeObjectTypes: options.include?.objectTypes ?? false,
+					includeBcs: options.include?.bcs ?? false,
+				},
+			},
+			(result) => result.transactions,
+		);
+
+		// Backwards pagination returns nodes in ascending order, so reverse them for descending reads
+		const nodes = descending ? [...transactions.nodes].reverse() : transactions.nodes;
+
+		return {
+			transactions: nodes.map((transaction) => parseTransaction(transaction, options.include)),
+			hasNextPage: descending
+				? transactions.pageInfo.hasPreviousPage
+				: transactions.pageInfo.hasNextPage,
+			startCursor:
+				(descending ? transactions.pageInfo.endCursor : transactions.pageInfo.startCursor) ?? null,
+			endCursor:
+				(descending ? transactions.pageInfo.startCursor : transactions.pageInfo.endCursor) ?? null,
+		};
+	}
+
+	async listEvents(
+		options: SuiClientTypes.ListEventsOptions,
+	): Promise<SuiClientTypes.ListEventsResponse> {
+		const { descending, after, before, limit } = resolvePagination(options);
+		const filter = options.filter
+			? await resolveEventFilter(this.mvr, options.filter, options.signal)
+			: undefined;
+
+		const events = await this.#graphqlQuery(
+			{
+				query: ListEventsDocument,
+				signal: options.signal,
+				variables: {
+					filter: filter && {
+						sender: filter.$kind === 'sender' ? filter.sender : undefined,
+						module:
+							filter.$kind === 'emitModule' ? `${filter.package}::${filter.module}` : undefined,
+						type:
+							filter.$kind === 'eventTypeModule'
+								? `${filter.package}::${filter.module}`
+								: filter.$kind === 'eventType'
+									? filter.eventType
+									: undefined,
+					},
+					first: descending ? undefined : limit,
+					after,
+					last: descending ? limit : undefined,
+					before,
+				},
+			},
+			(result) => result.events,
+		);
+
+		// Backwards pagination returns nodes in ascending order, so reverse them for descending reads
+		const nodes = descending ? [...events.nodes].reverse() : events.nodes;
+
+		return {
+			events: nodes.map((event): SuiClientTypes.EventEntry => {
+				const packageId = event.transactionModule?.package?.address;
+				const module = event.transactionModule?.name;
+				const sender = event.sender?.address;
+				const eventType = event.contents?.type?.repr;
+				const transactionDigest = event.transaction?.digest;
+
+				if (!packageId || !module || !sender || !eventType || !transactionDigest) {
+					throw new Error('listEvents response is missing expected event fields');
+				}
+
+				return {
+					packageId: normalizeSuiAddress(packageId),
+					module,
+					sender: normalizeSuiAddress(sender),
+					eventType: normalizeStructTag(eventType),
+					bcs: event.contents?.bcs ? fromBase64(event.contents.bcs) : new Uint8Array(),
+					json: (event.contents?.json as Record<string, unknown>) ?? null,
+					checkpoint: event.transaction?.effects?.checkpoint?.sequenceNumber?.toString() ?? null,
+					transactionDigest,
+					eventIndex: event.sequenceNumber,
+				};
+			}),
+			hasNextPage: descending ? events.pageInfo.hasPreviousPage : events.pageInfo.hasNextPage,
+			startCursor: (descending ? events.pageInfo.endCursor : events.pageInfo.startCursor) ?? null,
+			endCursor: (descending ? events.pageInfo.startCursor : events.pageInfo.endCursor) ?? null,
+		};
+	}
+
 	async verifyZkLoginSignature(
 		options: SuiClientTypes.VerifyZkLoginSignatureOptions,
 	): Promise<SuiClientTypes.ZkLoginVerifyResponse> {