@mysten/sui 2.25.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/graphql/core.ts

@@ -38,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 {
@@ -86,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);
 
@@ -94,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>;
@@ -124,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) {
@@ -385,6 +389,7 @@ export class GraphQLCoreClient extends CoreClient {
 				},
 			},
 			(result) => result.transaction,
+			() => new TransactionError('notFound', options.digest),
 		);
 
 		return parseTransaction(result, options.include);

package/src/grpc/core.ts

@@ -1,8 +1,14 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import type { CoreClientOptions, SuiClientTypes } from '../client/index.js';
-import { CoreClient, formatMoveAbortMessage, SimulationError } from '../client/index.js';
+import type { CoreClientOptions, ObjectErrorReason, SuiClientTypes } from '../client/index.js';
+import {
+	CoreClient,
+	formatMoveAbortMessage,
+	ObjectError,
+	SimulationError,
+	TransactionError,
+} from '../client/index.js';
 import { raceSignal } from '../client/mvr.js';
 import type { SuiGrpcClient } from './client.js';
 import type { Owner } from './proto/sui/rpc/v2/owner.js';
@@ -55,6 +61,7 @@ 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 { RpcError } from '@protobuf-ts/runtime-rpc';
+import { GrpcStatusCode } from '@protobuf-ts/grpcweb-transport';
 import {
 	resolveEventFilter,
 	resolvePagination,
@@ -69,8 +76,8 @@ export interface GrpcCoreClientOptions extends CoreClientOptions {
 
 function isNameServiceResolutionMiss(error: unknown): boolean {
 	if (!(error instanceof RpcError)) return false;
-	if (error.code === 'NOT_FOUND') return true;
-	if (error.code !== 'RESOURCE_EXHAUSTED') return false;
+	if (error.code === GrpcStatusCode[GrpcStatusCode.NOT_FOUND]) return true;
+	if (error.code !== GrpcStatusCode[GrpcStatusCode.RESOURCE_EXHAUSTED]) return false;
 
 	try {
 		// The gRPC service currently reports expired names as RESOURCE_EXHAUSTED without a
@@ -124,51 +131,62 @@ export class GrpcCoreClient extends CoreClient {
 			);
 
 			results.push(
-				...response.response.objects.map((object): SuiClientTypes.Object<Include> | Error => {
-					if (object.result.oneofKind === 'error') {
-						// TODO: improve error handling
-						return new Error(object.result.error.message);
-					}
-
-					if (object.result.oneofKind !== 'object') {
-						return new Error('Unexpected result type');
-					}
-
-					const bcsContent = object.result.object.contents?.value ?? undefined;
-					const objectBcs = object.result.object.bcs?.value ?? undefined;
-
-					// Package objects have type "package" which is not a struct tag, so don't normalize it
-					const objectType = object.result.object.objectType;
-					const type =
-						objectType && objectType.includes('::')
-							? normalizeStructTag(objectType)
-							: (objectType ?? '');
-
-					const jsonContent = options.include?.json
-						? object.result.object.json
-							? (Value.toJson(object.result.object.json) as Record<string, unknown>)
-							: null
-						: undefined;
-
-					const displayData = mapDisplayProto(
-						options.include?.display,
-						object.result.object.display,
-					);
-
-					return {
-						objectId: object.result.object.objectId!,
-						version: object.result.object.version?.toString()!,
-						digest: object.result.object.digest!,
-						content: bcsContent as SuiClientTypes.Object<Include>['content'],
-						owner: mapOwner(object.result.object.owner)!,
-						type,
-						previousTransaction: (object.result.object.previousTransaction ??
-							undefined) as SuiClientTypes.Object<Include>['previousTransaction'],
-						objectBcs: objectBcs as SuiClientTypes.Object<Include>['objectBcs'],
-						json: jsonContent as SuiClientTypes.Object<Include>['json'],
-						display: displayData as SuiClientTypes.Object<Include>['display'],
-					};
-				}),
+				...response.response.objects.map(
+					(object, index): SuiClientTypes.Object<Include> | ObjectError => {
+						if (object.result.oneofKind === 'error') {
+							const error = object.result.error;
+							const reason: ObjectErrorReason =
+								error.code === GrpcStatusCode.NOT_FOUND ? 'notFound' : 'unknown';
+							return new ObjectError(String(error.code), error.message, {
+								cause: error,
+								reason,
+								objectId: batch[index],
+							});
+						}
+
+						if (object.result.oneofKind !== 'object') {
+							return new ObjectError('unknown', 'Unexpected result type', {
+								reason: 'unknown',
+								objectId: batch[index],
+							});
+						}
+
+						const bcsContent = object.result.object.contents?.value ?? undefined;
+						const objectBcs = object.result.object.bcs?.value ?? undefined;
+
+						// Package objects have type "package" which is not a struct tag, so don't normalize it
+						const objectType = object.result.object.objectType;
+						const type =
+							objectType && objectType.includes('::')
+								? normalizeStructTag(objectType)
+								: (objectType ?? '');
+
+						const jsonContent = options.include?.json
+							? object.result.object.json
+								? (Value.toJson(object.result.object.json) as Record<string, unknown>)
+								: null
+							: undefined;
+
+						const displayData = mapDisplayProto(
+							options.include?.display,
+							object.result.object.display,
+						);
+
+						return {
+							objectId: object.result.object.objectId!,
+							version: object.result.object.version?.toString()!,
+							digest: object.result.object.digest!,
+							content: bcsContent as SuiClientTypes.Object<Include>['content'],
+							owner: mapOwner(object.result.object.owner)!,
+							type,
+							previousTransaction: (object.result.object.previousTransaction ??
+								undefined) as SuiClientTypes.Object<Include>['previousTransaction'],
+							objectBcs: objectBcs as SuiClientTypes.Object<Include>['objectBcs'],
+							json: jsonContent as SuiClientTypes.Object<Include>['json'],
+							display: displayData as SuiClientTypes.Object<Include>['display'],
+						};
+					},
+				),
 			);
 		}
 
@@ -362,25 +380,32 @@ export class GrpcCoreClient extends CoreClient {
 	async getTransaction<Include extends SuiClientTypes.TransactionInclude = {}>(
 		options: SuiClientTypes.GetTransactionOptions<Include>,
 	): Promise<SuiClientTypes.TransactionResult<Include>> {
-		const { response } = await this.#client.ledgerService.getTransaction(
-			{
-				digest: options.digest,
-				readMask: {
-					paths: transactionReadMaskPaths(options.include),
+		try {
+			const { response } = await this.#client.ledgerService.getTransaction(
+				{
+					digest: options.digest,
+					readMask: {
+						paths: transactionReadMaskPaths(options.include),
+					},
 				},
-			},
-			{ abort: options.signal },
-		);
+				{ abort: options.signal },
+			);
 
-		if (!response.transaction) {
-			throw new Error(`Transaction ${options.digest} not found`);
-		}
+			if (!response.transaction) {
+				throw new TransactionError('notFound', options.digest);
+			}
 
-		return withProtoJson(
-			parseGrpcTransactionResponse(response.transaction, { include: options.include }),
-			options.include,
-			() => ExecutedTransaction.toJson(response.transaction!),
-		);
+			return withProtoJson(
+				parseGrpcTransactionResponse(response.transaction, { include: options.include }),
+				options.include,
+				() => ExecutedTransaction.toJson(response.transaction!),
+			);
+		} catch (error) {
+			if (error instanceof RpcError && error.code === GrpcStatusCode[GrpcStatusCode.NOT_FOUND]) {
+				throw new TransactionError('notFound', options.digest, { cause: error });
+			}
+			throw error;
+		}
 	}
 	async executeTransaction<Include extends SuiClientTypes.TransactionInclude = {}>(
 		options: SuiClientTypes.ExecuteTransactionOptions<Include>,

package/src/jsonRpc/core.ts

@@ -10,6 +10,7 @@ import type {
 	EventId,
 	ExecutionStatus as JsonRpcExecutionStatus,
 	ObjectOwner,
+	ObjectResponseError,
 	SuiMoveAbilitySet,
 	SuiMoveAbort,
 	SuiMoveNormalizedType,
@@ -36,16 +37,73 @@ import { deriveDynamicFieldID } from '../utils/dynamic-fields.js';
 import { SUI_FRAMEWORK_ADDRESS, SUI_SYSTEM_ADDRESS } from '../utils/constants.js';
 import { CoreClient } from '../client/core.js';
 import type { SuiClientTypes } from '../client/types.js';
-import { ObjectError } from '../client/errors.js';
+import { ObjectError, TransactionError } from '../client/errors.js';
 import {
 	formatMoveAbortMessage,
 	parseTransactionBcs,
 	parseTransactionEffectsBcs,
 } from '../client/index.js';
 import type { SuiJsonRpcClient } from './client.js';
+import { JsonRpcError } from './errors.js';
 
 const MAX_GAS = 50_000_000_000;
 
+function mapJsonRpcObjectError(
+	response: ObjectResponseError,
+	requestedObjectId?: string,
+): ObjectError {
+	switch (response.code) {
+		case 'notExists':
+			return new ObjectError(response.code, `Object ${response.object_id} does not exist`, {
+				cause: response,
+				reason: 'notFound',
+				objectId: requestedObjectId ?? response.object_id,
+			});
+		case 'dynamicFieldNotFound':
+			return new ObjectError(
+				response.code,
+				`Dynamic field not found for object ${response.parent_object_id}`,
+				{
+					cause: response,
+					reason: 'notFound',
+					objectId: requestedObjectId ?? response.parent_object_id,
+				},
+			);
+		case 'deleted':
+			return new ObjectError(response.code, `Object ${response.object_id} has been deleted`, {
+				cause: response,
+				reason: 'deleted',
+				objectId: requestedObjectId ?? response.object_id,
+			});
+		case 'displayError':
+			return new ObjectError(response.code, `Display error: ${response.error}`, {
+				cause: response,
+				reason: 'unknown',
+				objectId: requestedObjectId,
+			});
+		case 'unknown':
+		default:
+			return new ObjectError(
+				response.code,
+				`Unknown error while loading object${requestedObjectId ? ` ${requestedObjectId}` : ''}`,
+				{
+					cause: response,
+					reason: 'unknown',
+					objectId: requestedObjectId,
+				},
+			);
+	}
+}
+
+function isJsonRpcTransactionNotFound(error: unknown, digest: string): boolean {
+	if (!(error instanceof JsonRpcError) || error.code !== -32602) return false;
+
+	return (
+		error.message === `Invalid Params: Transaction ${digest} not found` ||
+		error.message === `Could not find the referenced transaction [TransactionDigest(${digest})].`
+	);
+}
+
 function parseJsonRpcExecutionStatus(
 	status: JsonRpcExecutionStatus,
 	abortError?: SuiMoveAbort | null,
@@ -160,7 +218,7 @@ export class JSONRpcCoreClient extends CoreClient {
 
 			for (const [idx, object] of objects.entries()) {
 				if (object.error) {
-					results.push(ObjectError.fromResponse(object.error, batch[idx]));
+					results.push(mapJsonRpcObjectError(object.error, batch[idx]));
 				} else {
 					results.push(parseObject(object.data!, options.include));
 				}
@@ -211,7 +269,7 @@ export class JSONRpcCoreClient extends CoreClient {
 		return {
 			objects: objects.data.map((result) => {
 				if (result.error) {
-					throw ObjectError.fromResponse(result.error);
+					throw mapJsonRpcObjectError(result.error);
 				}
 
 				return parseObject(result.data!, options.include);
@@ -340,22 +398,29 @@ export class JSONRpcCoreClient extends CoreClient {
 	async getTransaction<Include extends SuiClientTypes.TransactionInclude = {}>(
 		options: SuiClientTypes.GetTransactionOptions<Include>,
 	): Promise<SuiClientTypes.TransactionResult<Include>> {
-		const transaction = await this.#jsonRpcClient.getTransactionBlock({
-			digest: options.digest,
-			options: {
-				// showRawInput is always needed to extract signatures from SenderSignedData
-				showRawInput: true,
-				// showEffects is always needed to get status
-				showEffects: true,
-				showObjectChanges: options.include?.objectTypes ?? false,
-				showRawEffects: options.include?.effects ?? false,
-				showEvents: options.include?.events ?? false,
-				showBalanceChanges: options.include?.balanceChanges ?? false,
-			},
-			signal: options.signal,
-		});
+		try {
+			const transaction = await this.#jsonRpcClient.getTransactionBlock({
+				digest: options.digest,
+				options: {
+					// showRawInput is always needed to extract signatures from SenderSignedData
+					showRawInput: true,
+					// showEffects is always needed to get status
+					showEffects: true,
+					showObjectChanges: options.include?.objectTypes ?? false,
+					showRawEffects: options.include?.effects ?? false,
+					showEvents: options.include?.events ?? false,
+					showBalanceChanges: options.include?.balanceChanges ?? false,
+				},
+				signal: options.signal,
+			});
 
-		return parseTransaction(transaction, options.include);
+			return parseTransaction(transaction, options.include);
+		} catch (error) {
+			if (isJsonRpcTransactionNotFound(error, options.digest)) {
+				throw new TransactionError('notFound', options.digest, { cause: error });
+			}
+			throw error;
+		}
 	}
 	/**
 	 * @deprecated JSON-RPC APIs are deprecated in the Sui TypeScript SDK. Use `SuiGrpcClient`

package/src/version.ts

@@ -3,4 +3,4 @@
 
 // This file is generated by genversion.mjs. Do not edit it directly.
 
-export const PACKAGE_VERSION = '2.25.0';
+export const PACKAGE_VERSION = '2.26.0';