@mysten/sui 2.24.0 → 2.26.0

package/src/client/errors.ts

@@ -1,7 +1,6 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import type { ObjectResponseError } from '../jsonRpc/index.js';
 import type { SuiClientTypes } from './types.js';
 
 export class SuiClientError extends Error {}
@@ -18,33 +17,50 @@ export class SimulationError extends SuiClientError {
 	}
 }
 
+export type ObjectErrorReason = 'notFound' | 'deleted' | 'unknown';
+
+export interface ObjectErrorOptions {
+	/** A transport-neutral reason shared by all Core API clients. */
+	reason: ObjectErrorReason;
+	/** The requested object ID, when the lookup identifies one. */
+	objectId?: string;
+	/** The original transport error or response. */
+	cause?: unknown;
+}
+
+/** An error returned for an individual object lookup. */
 export class ObjectError extends SuiClientError {
+	/** The transport's error code. Use `reason` for transport-neutral handling. */
 	code: string;
+	/** A transport-neutral reason shared by all Core API clients. */
+	readonly reason: ObjectErrorReason;
+	/** The requested object ID, when the lookup identifies one. */
+	readonly objectId?: string;
 
-	constructor(code: string, message: string) {
-		super(message);
+	constructor(code: string, message: string, options?: ObjectErrorOptions) {
+		super(message, { cause: options?.cause });
 		this.code = code;
+		this.reason = options?.reason ?? 'unknown';
+		this.objectId = options?.objectId;
 	}
+}
+
+export type TransactionErrorReason = 'notFound';
+
+const TRANSACTION_ERROR_MESSAGES: Record<TransactionErrorReason, (digest: string) => string> = {
+	notFound: (digest) => `Transaction ${digest} not found`,
+};
+
+/** An error returned by a transaction lookup. */
+export class TransactionError extends SuiClientError {
+	/** A transport-neutral reason shared by all Core API clients. */
+	readonly reason: TransactionErrorReason;
+	/** The requested transaction digest. */
+	readonly digest: string;
 
-	static fromResponse(response: ObjectResponseError, objectId?: string): ObjectError {
-		switch (response.code) {
-			case 'notExists':
-				return new ObjectError(response.code, `Object ${response.object_id} does not exist`);
-			case 'dynamicFieldNotFound':
-				return new ObjectError(
-					response.code,
-					`Dynamic field not found for object ${response.parent_object_id}`,
-				);
-			case 'deleted':
-				return new ObjectError(response.code, `Object ${response.object_id} has been deleted`);
-			case 'displayError':
-				return new ObjectError(response.code, `Display error: ${response.error}`);
-			case 'unknown':
-			default:
-				return new ObjectError(
-					response.code,
-					`Unknown error while loading object${objectId ? ` ${objectId}` : ''}`,
-				);
-		}
+	constructor(reason: TransactionErrorReason, digest: string, options?: { cause?: unknown }) {
+		super(TRANSACTION_ERROR_MESSAGES[reason](digest), options);
+		this.reason = reason;
+		this.digest = digest;
 	}
 }

package/src/client/index.ts

@@ -22,7 +22,15 @@ export {
 	type ClientWithCoreApi,
 };
 
-export { SimulationError } from './errors.js';
+export {
+	ObjectError,
+	SimulationError,
+	SuiClientError,
+	TransactionError,
+	type ObjectErrorOptions,
+	type ObjectErrorReason,
+	type TransactionErrorReason,
+} from './errors.js';
 
 export { ClientCache, type ClientCacheOptions } from './cache.js';
 export { type NamedPackagesOverrides } from './mvr.js';

package/src/client/mvr.ts

@@ -401,6 +401,12 @@ export function raceSignal<T>(promise: Promise<T>, signal?: AbortSignal): Promis
 		return promise;
 	}
 
+	// An `abort` event is not replayed for listeners added after the fact, so a signal that was
+	// already aborted would otherwise resolve normally.
+	if (signal.aborted) {
+		return Promise.reject(signal.reason);
+	}
+
 	return new Promise<T>((resolve, reject) => {
 		const onAbort = () => reject(signal.reason);
 		signal.addEventListener('abort', onAbort, { once: true });

package/src/graphql/client.ts

@@ -249,8 +249,28 @@ export class SuiGraphQLClient<Queries extends Record<string, GraphQLDocument> =
 		return this.core.simulateTransaction(input);
 	}
 
-	getReferenceGasPrice(): Promise<SuiClientTypes.GetReferenceGasPriceResponse> {
-		return this.core.getReferenceGasPrice();
+	getReferenceGasPrice(
+		input?: SuiClientTypes.GetReferenceGasPriceOptions,
+	): Promise<SuiClientTypes.GetReferenceGasPriceResponse> {
+		return this.core.getReferenceGasPrice(input);
+	}
+
+	getCurrentSystemState(
+		input?: SuiClientTypes.GetCurrentSystemStateOptions,
+	): Promise<SuiClientTypes.GetCurrentSystemStateResponse> {
+		return this.core.getCurrentSystemState(input);
+	}
+
+	getProtocolConfig(
+		input?: SuiClientTypes.GetProtocolConfigOptions,
+	): Promise<SuiClientTypes.GetProtocolConfigResponse> {
+		return this.core.getProtocolConfig(input);
+	}
+
+	getChainIdentifier(
+		input?: SuiClientTypes.GetChainIdentifierOptions,
+	): Promise<SuiClientTypes.GetChainIdentifierResponse> {
+		return this.core.getChainIdentifier(input);
 	}
 
 	async listDynamicFields<Include extends DynamicFieldInclude = {}>(
@@ -260,6 +280,7 @@ export class SuiGraphQLClient<Queries extends Record<string, GraphQLDocument> =
 
 		const { data, errors } = await this.query({
 			query: GetDynamicFieldsDocument,
+			signal: input.signal,
 			variables: {
 				parentId: input.parentId,
 				first: input.limit,
@@ -338,6 +359,12 @@ export class SuiGraphQLClient<Queries extends Record<string, GraphQLDocument> =
 		return this.core.getDynamicField(input);
 	}
 
+	getDynamicObjectField<Include extends SuiClientTypes.ObjectInclude = {}>(
+		input: SuiClientTypes.GetDynamicObjectFieldOptions<Include>,
+	): Promise<SuiClientTypes.GetDynamicObjectFieldResponse<Include>> {
+		return this.core.getDynamicObjectField(input);
+	}
+
 	listTransactions<Include extends SuiClientTypes.TransactionInclude = {}>(
 		input: SuiClientTypes.ListTransactionsOptions<Include>,
 	): Promise<SuiClientTypes.ListTransactionsResponse<Include>> {

package/src/graphql/core.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { CoreClient } from '../client/core.js';
+import { raceSignal } from '../client/mvr.js';
 import type { SuiClientTypes } from '../client/types.js';
 import { SUI_TYPE_ARG } from '../utils/constants.js';
 import type { GraphQLQueryOptions, SuiGraphQLClient } from './client.js';
@@ -37,7 +38,7 @@ import {
 	VerifyZkLoginSignatureDocument,
 	ZkLoginIntentScope,
 } from './generated/queries.js';
-import { ObjectError, SimulationError } from '../client/errors.js';
+import { ObjectError, SimulationError, TransactionError } from '../client/errors.js';
 import { chunk, fromBase64, toBase64 } from '@mysten/utils';
 import { normalizeStructTag, normalizeSuiAddress } from '../utils/sui-types.js';
 import {
@@ -85,6 +86,7 @@ export class GraphQLCoreClient extends CoreClient {
 	>(
 		options: GraphQLQueryOptions<Result, Variables>,
 		getData?: (result: Result) => Data,
+		createMissingDataError?: () => Error,
 	): Promise<NonNullable<Data>> {
 		const { data, errors } = await this.#graphqlClient.query(options);
 
@@ -93,7 +95,7 @@ export class GraphQLCoreClient extends CoreClient {
 		const extractedData = data && (getData ? getData(data) : data);
 
 		if (extractedData == null) {
-			throw new Error('Missing response data');
+			throw createMissingDataError?.() ?? new Error('Missing response data');
 		}
 
 		return extractedData as NonNullable<Data>;
@@ -109,6 +111,7 @@ export class GraphQLCoreClient extends CoreClient {
 			const page = await this.#graphqlQuery(
 				{
 					query: MultiGetObjectsDocument,
+					signal: options.signal,
 					variables: {
 						objectKeys: batch.map((address) => ({ address })),
 						includeContent: options.include?.content ?? false,
@@ -122,11 +125,14 @@ export class GraphQLCoreClient extends CoreClient {
 			);
 			results.push(
 				...batch
-					.map((id) => normalizeSuiAddress(id))
+					.map((objectId) => ({ objectId, normalized: normalizeSuiAddress(objectId) }))
 					.map(
-						(id) =>
-							page.find((obj) => obj?.address === id) ??
-							new ObjectError('notFound', `Object ${id} not found`),
+						({ objectId, normalized }) =>
+							page.find((obj) => obj?.address === normalized) ??
+							new ObjectError('notFound', `Object ${normalized} not found`, {
+								reason: 'notFound',
+								objectId,
+							}),
 					)
 					.map((obj) => {
 						if (obj instanceof ObjectError) {
@@ -187,12 +193,16 @@ export class GraphQLCoreClient extends CoreClient {
 		const objects = await this.#graphqlQuery(
 			{
 				query: GetOwnedObjectsDocument,
+				signal: options.signal,
 				variables: {
 					owner: options.owner,
 					limit: options.limit,
 					cursor: options.cursor,
 					filter: options.type
-						? { type: (await this.mvr.resolveType({ type: options.type })).type }
+						? {
+								type: (await this.mvr.resolveType({ type: options.type, signal: options.signal }))
+									.type,
+							}
 						: undefined,
 					includeContent: options.include?.content ?? false,
 					includePreviousTransaction: options.include?.previousTransaction ?? false,
@@ -242,11 +252,12 @@ export class GraphQLCoreClient extends CoreClient {
 		const coins = await this.#graphqlQuery(
 			{
 				query: GetCoinsDocument,
+				signal: options.signal,
 				variables: {
 					owner: options.owner,
 					cursor: options.cursor,
 					first: options.limit,
-					type: `0x2::coin::Coin<${(await this.mvr.resolveType({ type: coinType })).type}>`,
+					type: `0x2::coin::Coin<${(await this.mvr.resolveType({ type: coinType, signal: options.signal })).type}>`,
 				},
 			},
 			(result) => result.address?.objects,
@@ -275,9 +286,10 @@ export class GraphQLCoreClient extends CoreClient {
 		const result = await this.#graphqlQuery(
 			{
 				query: GetBalanceDocument,
+				signal: options.signal,
 				variables: {
 					owner: options.owner,
-					coinType: (await this.mvr.resolveType({ type: coinType })).type,
+					coinType: (await this.mvr.resolveType({ type: coinType, signal: options.signal })).type,
 				},
 			},
 			(result) => result.address?.balance,
@@ -298,10 +310,13 @@ export class GraphQLCoreClient extends CoreClient {
 	async getCoinMetadata(
 		options: SuiClientTypes.GetCoinMetadataOptions,
 	): Promise<SuiClientTypes.GetCoinMetadataResponse> {
-		const coinType = (await this.mvr.resolveType({ type: options.coinType })).type;
+		const coinType = (
+			await this.mvr.resolveType({ type: options.coinType, signal: options.signal })
+		).type;
 
 		const { data, errors } = await this.#graphqlClient.query({
 			query: GetCoinMetadataDocument,
+			signal: options.signal,
 			variables: {
 				coinType,
 			},
@@ -331,6 +346,7 @@ export class GraphQLCoreClient extends CoreClient {
 		const balances = await this.#graphqlQuery(
 			{
 				query: GetAllBalancesDocument,
+				signal: options.signal,
 				variables: {
 					owner: options.owner,
 					limit: options.limit,
@@ -361,6 +377,7 @@ export class GraphQLCoreClient extends CoreClient {
 		const result = await this.#graphqlQuery(
 			{
 				query: GetTransactionBlockDocument,
+				signal: options.signal,
 				variables: {
 					digest: options.digest,
 					includeTransaction: options.include?.transaction ?? false,
@@ -372,6 +389,7 @@ export class GraphQLCoreClient extends CoreClient {
 				},
 			},
 			(result) => result.transaction,
+			() => new TransactionError('notFound', options.digest),
 		);
 
 		return parseTransaction(result, options.include);
@@ -382,6 +400,7 @@ export class GraphQLCoreClient extends CoreClient {
 		const result = await this.#graphqlQuery(
 			{
 				query: ExecuteTransactionDocument,
+				signal: options.signal,
 				variables: {
 					transactionDataBcs: toBase64(options.transaction),
 					signatures: options.signatures,
@@ -417,6 +436,7 @@ export class GraphQLCoreClient extends CoreClient {
 		const result = await this.#graphqlQuery(
 			{
 				query: SimulateTransactionDocument,
+				signal: options.signal,
 				variables: {
 					transaction:
 						options.transaction instanceof Uint8Array
@@ -470,10 +490,13 @@ export class GraphQLCoreClient extends CoreClient {
 			};
 		}
 	}
-	async getReferenceGasPrice(): Promise<SuiClientTypes.GetReferenceGasPriceResponse> {
+	async getReferenceGasPrice(
+		options?: SuiClientTypes.GetReferenceGasPriceOptions,
+	): Promise<SuiClientTypes.GetReferenceGasPriceResponse> {
 		const result = await this.#graphqlQuery(
 			{
 				query: GetReferenceGasPriceDocument,
+				signal: options?.signal,
 			},
 			(result) => result.epoch?.referenceGasPrice,
 		);
@@ -483,10 +506,13 @@ export class GraphQLCoreClient extends CoreClient {
 		};
 	}
 
-	async getProtocolConfig(): Promise<SuiClientTypes.GetProtocolConfigResponse> {
+	async getProtocolConfig(
+		options?: SuiClientTypes.GetProtocolConfigOptions,
+	): Promise<SuiClientTypes.GetProtocolConfigResponse> {
 		const result = await this.#graphqlQuery(
 			{
 				query: GetProtocolConfigDocument,
+				signal: options?.signal,
 			},
 			(result) => result.epoch?.protocolConfigs,
 		);
@@ -509,10 +535,13 @@ export class GraphQLCoreClient extends CoreClient {
 		};
 	}
 
-	async getCurrentSystemState(): Promise<SuiClientTypes.GetCurrentSystemStateResponse> {
+	async getCurrentSystemState(
+		options?: SuiClientTypes.GetCurrentSystemStateOptions,
+	): Promise<SuiClientTypes.GetCurrentSystemStateResponse> {
 		const result = await this.#graphqlQuery(
 			{
 				query: GetCurrentSystemStateDocument,
+				signal: options?.signal,
 			},
 			(result) => result.epoch,
 		);
@@ -744,6 +773,7 @@ export class GraphQLCoreClient extends CoreClient {
 
 		const { data } = await this.#graphqlClient.query({
 			query: VerifyZkLoginSignatureDocument,
+			signal: options.signal,
 			variables: {
 				bytes: options.bytes,
 				signature: options.signature,
@@ -797,8 +827,11 @@ export class GraphQLCoreClient extends CoreClient {
 		const moveFunction = await this.#graphqlQuery(
 			{
 				query: GetMoveFunctionDocument,
+				signal: options.signal,
 				variables: {
-					package: (await this.mvr.resolvePackage({ package: options.packageId })).package,
+					package: (
+						await this.mvr.resolvePackage({ package: options.packageId, signal: options.signal })
+					).package,
 					module: options.moduleName,
 					function: options.name,
 				},
@@ -856,9 +889,11 @@ export class GraphQLCoreClient extends CoreClient {
 	}
 
 	async getChainIdentifier(
-		_options?: SuiClientTypes.GetChainIdentifierOptions,
+		options?: SuiClientTypes.GetChainIdentifierOptions,
 	): Promise<SuiClientTypes.GetChainIdentifierResponse> {
-		return this.cache.read(['chainIdentifier'], async () => {
+		// The result is cached and shared across callers, so the underlying request must
+		// not carry any single caller's signal. Isolate cancellation per-caller instead.
+		const cached = this.cache.read(['chainIdentifier'], async () => {
 			const checkpoint = await this.#graphqlQuery(
 				{
 					query: GetChainIdentifierDocument,
@@ -872,6 +907,8 @@ export class GraphQLCoreClient extends CoreClient {
 				chainIdentifier: checkpoint.digest,
 			};
 		});
+
+		return raceSignal(Promise.resolve(cached), options?.signal);
 	}
 
 	resolveTransactionPlugin() {

package/src/graphql/generated/schema.graphql

@@ -1225,7 +1225,7 @@ type EndOfEpochTransaction {
 	transactions(first: Int, after: String, last: Int, before: String): EndOfEpochTransactionKindConnection
 }
 
-union EndOfEpochTransactionKind = ChangeEpochTransaction | AuthenticatorStateCreateTransaction | AuthenticatorStateExpireTransaction | RandomnessStateCreateTransaction | CoinDenyListStateCreateTransaction | StoreExecutionTimeObservationsTransaction | BridgeStateCreateTransaction | BridgeCommitteeInitTransaction | AccumulatorRootCreateTransaction | CoinRegistryCreateTransaction | DisplayRegistryCreateTransaction | AddressAliasStateCreateTransaction | WriteAccumulatorStorageCostTransaction
+union EndOfEpochTransactionKind = ChangeEpochTransaction | AuthenticatorStateCreateTransaction | AuthenticatorStateExpireTransaction | RandomnessStateCreateTransaction | CoinDenyListStateCreateTransaction | StoreExecutionTimeObservationsTransaction | BridgeStateCreateTransaction | BridgeCommitteeInitTransaction | AccumulatorRootCreateTransaction | CoinRegistryCreateTransaction | DisplayRegistryCreateTransaction | AddressAliasStateCreateTransaction | WriteAccumulatorStorageCostTransaction | ForwardingAddressRegistryCreateTransaction
 
 type EndOfEpochTransactionKindConnection {
 	"""
@@ -1578,6 +1578,16 @@ type FeatureFlag {
 }
 
 
+"""
+System transaction for creating the forwarding address registry.
+"""
+type ForwardingAddressRegistryCreateTransaction {
+	"""
+	A workaround to define an empty variant of a GraphQL union.
+	"""
+	_: Boolean
+}
+
 """
 Access to the gas inputs, after they have been smashed into one coin. The gas coin can only be used by reference, except for with `TransferObjectsTransaction` that can accept it by value.
 """

package/src/graphql/generated/tada-env.ts

@@ -3697,6 +3697,10 @@ const introspection = {
             "kind": "OBJECT",
             "name": "DisplayRegistryCreateTransaction"
           },
+          {
+            "kind": "OBJECT",
+            "name": "ForwardingAddressRegistryCreateTransaction"
+          },
           {
             "kind": "OBJECT",
             "name": "RandomnessStateCreateTransaction"
@@ -4551,6 +4555,22 @@ const introspection = {
         ],
         "interfaces": []
       },
+      {
+        "kind": "OBJECT",
+        "name": "ForwardingAddressRegistryCreateTransaction",
+        "fields": [
+          {
+            "name": "_",
+            "type": {
+              "kind": "SCALAR",
+              "name": "Boolean"
+            },
+            "args": [],
+            "isDeprecated": false
+          }
+        ],
+        "interfaces": []
+      },
       {
         "kind": "OBJECT",
         "name": "GasCoin",

package/src/grpc/client.ts

@@ -246,8 +246,28 @@ export class SuiGrpcClient extends BaseClient implements SuiClientTypes.Transpor
 		return this.core.simulateTransaction(input) as Promise<GrpcSimulateTransactionResult<Include>>;
 	}
 
-	getReferenceGasPrice(): Promise<SuiClientTypes.GetReferenceGasPriceResponse> {
-		return this.core.getReferenceGasPrice();
+	getReferenceGasPrice(
+		input?: SuiClientTypes.GetReferenceGasPriceOptions,
+	): Promise<SuiClientTypes.GetReferenceGasPriceResponse> {
+		return this.core.getReferenceGasPrice(input);
+	}
+
+	getCurrentSystemState(
+		input?: SuiClientTypes.GetCurrentSystemStateOptions,
+	): Promise<SuiClientTypes.GetCurrentSystemStateResponse> {
+		return this.core.getCurrentSystemState(input);
+	}
+
+	getProtocolConfig(
+		input?: SuiClientTypes.GetProtocolConfigOptions,
+	): Promise<SuiClientTypes.GetProtocolConfigResponse> {
+		return this.core.getProtocolConfig(input);
+	}
+
+	getChainIdentifier(
+		input?: SuiClientTypes.GetChainIdentifierOptions,
+	): Promise<SuiClientTypes.GetChainIdentifierResponse> {
+		return this.core.getChainIdentifier(input);
 	}
 
 	async listDynamicFields<Include extends DynamicFieldInclude = {}>(
@@ -305,6 +325,12 @@ export class SuiGrpcClient extends BaseClient implements SuiClientTypes.Transpor
 		return this.core.getDynamicField(input);
 	}
 
+	getDynamicObjectField<Include extends SuiClientTypes.ObjectInclude = {}>(
+		input: SuiClientTypes.GetDynamicObjectFieldOptions<Include>,
+	): Promise<SuiClientTypes.GetDynamicObjectFieldResponse<Include>> {
+		return this.core.getDynamicObjectField(input);
+	}
+
 	listTransactions<Include extends SuiClientTypes.TransactionInclude = {}>(
 		input: SuiClientTypes.ListTransactionsOptions<Include>,
 	): Promise<SuiClientTypes.ListTransactionsResponse<Include>> {