@mysten/sui 2.5.1 → 2.7.0

package/src/client/types.ts

@@ -58,24 +58,54 @@ export namespace SuiClientTypes {
 	}
 
 	export interface ObjectInclude {
+		/**
+		 * Include the BCS-encoded Move struct content of the object.
+		 *
+		 * Returns the raw bytes of the object's Move struct fields — pass directly to
+		 * generated BCS types (e.g., `MyStruct.parse(object.content)`).
+		 */
 		content?: boolean;
+		/**
+		 * Include the digest of the transaction that last mutated this object.
+		 */
 		previousTransaction?: boolean;
+		/**
+		 * Include the full BCS-encoded object envelope. Rarely needed — most metadata
+		 * (owner, version, type) is already available as fields on the object response.
+		 *
+		 * Parse with `bcs.Object.parse(object.objectBcs)` from `@mysten/sui/bcs`.
+		 * Do not pass to a Move struct parser — use `content` for that instead.
+		 */
 		objectBcs?: boolean;
+		/**
+		 * Include the JSON representation of the object's Move struct content.
+		 *
+		 * **Warning:** The exact shape and field names of this data may vary between different
+		 * API implementations (JSON-RPC vs gRPC or GraphQL). For consistent data across APIs,
+		 * use the `content` field and parse the BCS data directly.
+		 */
 		json?: boolean;
+		/**
+		 * Include the Display v2 rendered output for the object.
+		 *
+		 * Returns a map of display field names to their rendered string values.
+		 * Returns `null` if the object's type does not have an associated Display template.
+		 */
+		display?: boolean;
 	}
 
 	export interface GetObjectsOptions<
 		Include extends ObjectInclude = {},
 	> extends CoreClientMethodOptions {
 		objectIds: string[];
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface GetObjectOptions<
 		Include extends ObjectInclude = {},
 	> extends CoreClientMethodOptions {
 		objectId: string;
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface ListOwnedObjectsOptions<
@@ -85,7 +115,7 @@ export namespace SuiClientTypes {
 		limit?: number;
 		cursor?: string | null;
 		type?: string;
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface ListCoinsOptions extends CoreClientMethodOptions {
@@ -133,8 +163,10 @@ export namespace SuiClientTypes {
 		digest: string;
 		owner: ObjectOwner;
 		type: string;
+		/** BCS-encoded Move struct content — pass to generated BCS type parsers. */
 		content: Include extends { content: true } ? Uint8Array<ArrayBuffer> : undefined;
 		previousTransaction: Include extends { previousTransaction: true } ? string | null : undefined;
+		/** Full BCS-encoded object envelope — parse with `bcs.Object` not a struct parser. */
 		objectBcs: Include extends { objectBcs: true } ? Uint8Array<ArrayBuffer> : undefined;
 		/**
 		 * The JSON representation of the object's Move struct content.
@@ -144,6 +176,15 @@ export namespace SuiClientTypes {
 		 * the `content` field and parse the BCS data directly.
 		 */
 		json: Include extends { json: true } ? Record<string, unknown> | null : undefined;
+		/** Display rendered output. `null` if the type has no Display template. */
+		display: Include extends { display: true } ? Display | null : undefined;
+	}
+
+	export interface Display {
+		/** Successfully rendered display field values, keyed by field name. */
+		output: Record<string, string> | null;
+		/** Per-field rendering errors, keyed by field name. `null` if all fields succeeded. */
+		errors: Record<string, string> | null;
 	}
 
 	export interface Coin {
@@ -162,6 +203,13 @@ export namespace SuiClientTypes {
 		valueType: string;
 	} & ({ $kind: 'DynamicField'; childId?: never } | { $kind: 'DynamicObject'; childId: string });
 
+	export type DynamicField = DynamicFieldEntry & {
+		value: DynamicFieldValue;
+		version: string;
+		digest: string;
+		previousTransaction: string | null;
+	};
+
 	export interface ListDynamicFieldsResponse {
 		hasNextPage: boolean;
 		cursor: string | null;
@@ -169,15 +217,7 @@ export namespace SuiClientTypes {
 	}
 
 	export interface GetDynamicFieldResponse {
-		dynamicField: {
-			name: DynamicFieldName;
-			value: DynamicFieldValue;
-			fieldId: string;
-			version: string;
-			digest: string;
-			type: string;
-			previousTransaction: string | null;
-		};
+		dynamicField: DynamicField;
 	}
 
 	export interface GetDynamicObjectFieldOptions<
@@ -185,7 +225,7 @@ export namespace SuiClientTypes {
 	> extends CoreClientMethodOptions {
 		parentId: string;
 		name: DynamicFieldName;
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface GetDynamicObjectFieldResponse<out Include extends ObjectInclude = {}> {
@@ -313,15 +353,22 @@ export namespace SuiClientTypes {
 		  };
 
 	export interface TransactionInclude {
+		/** Include balance changes caused by the transaction. */
 		balanceChanges?: boolean;
+		/** Include parsed transaction effects (gas used, changed objects, status, etc.). */
 		effects?: boolean;
+		/** Include events emitted by the transaction. */
 		events?: boolean;
+		/** Include a map of object IDs to their types for all changed objects. */
 		objectTypes?: boolean;
+		/** Include the parsed transaction data (sender, gas config, inputs, commands). */
 		transaction?: boolean;
+		/** Include the raw BCS-encoded transaction bytes. */
 		bcs?: boolean;
 	}
 
 	export interface SimulateTransactionInclude extends TransactionInclude {
+		/** Include return values and mutated references from each command (simulation only). */
 		commandResults?: boolean;
 	}
 
@@ -346,7 +393,7 @@ export namespace SuiClientTypes {
 		Include extends TransactionInclude = {},
 	> extends CoreClientMethodOptions {
 		digest: string;
-		include?: Include;
+		include?: Include & TransactionInclude;
 	}
 
 	export type WaitForTransactionOptions<Include extends TransactionInclude = {}> =
@@ -364,7 +411,7 @@ export namespace SuiClientTypes {
 		Include extends TransactionInclude = {},
 	> extends CoreClientMethodOptions {
 		result: TransactionResult<any>;
-		include?: Include;
+		include?: Include & TransactionInclude;
 		timeout?: number;
 		digest?: never;
 	}
@@ -374,7 +421,7 @@ export namespace SuiClientTypes {
 	> extends CoreClientMethodOptions {
 		transaction: Uint8Array;
 		signatures: string[];
-		include?: Include;
+		include?: Include & TransactionInclude;
 	}
 
 	export interface SignAndExecuteTransactionOptions<
@@ -383,14 +430,14 @@ export namespace SuiClientTypes {
 		transaction: Uint8Array | TransactionInstance;
 		signer: Signer;
 		additionalSignatures?: string[];
-		include?: Include;
+		include?: Include & TransactionInclude;
 	}
 
 	export interface SimulateTransactionOptions<
 		Include extends SimulateTransactionInclude = {},
 	> extends CoreClientMethodOptions {
 		transaction: Uint8Array | TransactionInstance;
-		include?: Include;
+		include?: Include & SimulateTransactionInclude;
 	}
 
 	export interface GetReferenceGasPriceOptions extends CoreClientMethodOptions {}
@@ -816,6 +863,14 @@ export namespace SuiClientTypes {
 		sender: string;
 		eventType: string;
 		bcs: Uint8Array;
+		/**
+		 * The JSON representation of the event's Move struct data.
+		 *
+		 * **Warning:** The exact shape and field names of this data may vary between different
+		 * API implementations (JSON-RPC vs gRPC or GraphQL). For consistent data across APIs use
+		 * the `bcs` field and parse the BCS data directly.
+		 */
+		json: Record<string, unknown> | null;
 	}
 
 	export interface MoveAbort {

package/src/graphql/client.ts

@@ -9,6 +9,10 @@ import { BaseClient } from '../client/index.js';
 import type { SuiClientTypes } from '../client/index.js';
 import { GraphQLCoreClient } from './core.js';
 import type { TypedDocumentString } from './generated/queries.js';
+import { GetDynamicFieldsDocument } from './generated/queries.js';
+import { fromBase64 } from '@mysten/utils';
+import { normalizeStructTag } from '../utils/sui-types.js';
+import { deriveDynamicFieldID } from '../utils/dynamic-fields.js';
 import type { TransactionPlugin } from '../transactions/index.js';
 
 export type GraphQLDocument<
@@ -66,6 +70,21 @@ export function isSuiGraphQLClient(client: unknown): client is SuiGraphQLClient
 	);
 }
 
+export interface DynamicFieldInclude {
+	value?: boolean;
+}
+
+export type DynamicFieldEntryWithValue<Include extends DynamicFieldInclude = {}> =
+	SuiClientTypes.DynamicFieldEntry & {
+		value: Include extends { value: true } ? SuiClientTypes.DynamicFieldValue : undefined;
+	};
+
+export interface ListDynamicFieldsWithValueResponse<Include extends DynamicFieldInclude = {}> {
+	hasNextPage: boolean;
+	cursor: string | null;
+	dynamicFields: DynamicFieldEntryWithValue<Include>[];
+}
+
 export class SuiGraphQLClient<Queries extends Record<string, GraphQLDocument> = {}>
 	extends BaseClient
 	implements SuiClientTypes.TransportMethods
@@ -220,10 +239,83 @@ export class SuiGraphQLClient<Queries extends Record<string, GraphQLDocument> =
 		return this.core.getReferenceGasPrice();
 	}
 
-	listDynamicFields(
-		input: SuiClientTypes.ListDynamicFieldsOptions,
-	): Promise<SuiClientTypes.ListDynamicFieldsResponse> {
-		return this.core.listDynamicFields(input);
+	async listDynamicFields<Include extends DynamicFieldInclude = {}>(
+		input: SuiClientTypes.ListDynamicFieldsOptions & { include?: Include & DynamicFieldInclude },
+	): Promise<ListDynamicFieldsWithValueResponse<Include>> {
+		const includeValue = input.include?.value ?? false;
+
+		const { data, errors } = await this.query({
+			query: GetDynamicFieldsDocument,
+			variables: {
+				parentId: input.parentId,
+				first: input.limit,
+				cursor: input.cursor,
+				includeValue,
+			},
+		});
+
+		if (errors?.length) {
+			throw errors.length === 1
+				? new Error(errors[0].message)
+				: new AggregateError(errors.map((e) => new Error(e.message)));
+		}
+
+		const result = data?.address?.dynamicFields;
+		if (!result) {
+			throw new Error('Missing response data');
+		}
+
+		return {
+			dynamicFields: result.nodes.map((dynamicField): DynamicFieldEntryWithValue<Include> => {
+				const valueType =
+					dynamicField.value?.__typename === 'MoveObject'
+						? dynamicField.value.contents?.type?.repr!
+						: dynamicField.value?.type?.repr!;
+				const isDynamicObject = dynamicField.value?.__typename === 'MoveObject';
+				const derivedNameType = isDynamicObject
+					? `0x2::dynamic_object_field::Wrapper<${dynamicField.name?.type?.repr}>`
+					: dynamicField.name?.type?.repr!;
+
+				let value: SuiClientTypes.DynamicFieldValue | undefined;
+				if (includeValue) {
+					let valueBcs: Uint8Array;
+					if (dynamicField.value?.__typename === 'MoveValue') {
+						valueBcs = fromBase64(dynamicField.value.bcs ?? '');
+					} else if (dynamicField.value?.__typename === 'MoveObject') {
+						valueBcs = fromBase64(dynamicField.value.contents?.bcs ?? '');
+					} else {
+						valueBcs = new Uint8Array();
+					}
+					value = { type: valueType, bcs: valueBcs };
+				}
+
+				return {
+					$kind: isDynamicObject ? 'DynamicObject' : 'DynamicField',
+					fieldId: deriveDynamicFieldID(
+						input.parentId,
+						derivedNameType,
+						fromBase64(dynamicField.name?.bcs!),
+					),
+					type: normalizeStructTag(
+						isDynamicObject
+							? `0x2::dynamic_field::Field<0x2::dynamic_object_field::Wrapper<${dynamicField.name?.type?.repr}>,0x2::object::ID>`
+							: `0x2::dynamic_field::Field<${dynamicField.name?.type?.repr},${valueType}>`,
+					),
+					name: {
+						type: dynamicField.name?.type?.repr!,
+						bcs: fromBase64(dynamicField.name?.bcs!),
+					},
+					valueType,
+					childId:
+						isDynamicObject && dynamicField.value?.__typename === 'MoveObject'
+							? dynamicField.value.address
+							: undefined,
+					value: (includeValue ? value : undefined) as DynamicFieldEntryWithValue<Include>['value'],
+				} as DynamicFieldEntryWithValue<Include>;
+			}),
+			cursor: result.pageInfo.endCursor ?? null,
+			hasNextPage: result.pageInfo.hasNextPage,
+		};
 	}
 
 	getDynamicField(

package/src/graphql/core.ts

@@ -23,7 +23,6 @@ import {
 	GetCoinMetadataDocument,
 	GetCoinsDocument,
 	GetCurrentSystemStateDocument,
-	GetDynamicFieldsDocument,
 	GetMoveFunctionDocument,
 	GetOwnedObjectsDocument,
 	GetReferenceGasPriceDocument,
@@ -36,8 +35,7 @@ import {
 } from './generated/queries.js';
 import { ObjectError, SimulationError } from '../client/errors.js';
 import { chunk, fromBase64, toBase64 } from '@mysten/utils';
-import { normalizeStructTag, normalizeSuiAddress } from '../utils/sui-types.js';
-import { deriveDynamicFieldID } from '../utils/dynamic-fields.js';
+import { normalizeSuiAddress } from '../utils/sui-types.js';
 import { formatMoveAbortMessage, parseTransactionEffectsBcs } from '../client/utils.js';
 import type { OpenMoveTypeSignatureBody, OpenMoveTypeSignature } from './types.js';
 import {
@@ -86,7 +84,7 @@ export class GraphQLCoreClient extends CoreClient {
 		return extractedData as NonNullable<Data>;
 	}
 
-	async getObjects<Include extends SuiClientTypes.ObjectInclude = object>(
+	async getObjects<Include extends SuiClientTypes.ObjectInclude = {}>(
 		options: SuiClientTypes.GetObjectsOptions<Include>,
 	): Promise<SuiClientTypes.GetObjectsResponse<Include>> {
 		const batches = chunk(options.objectIds, 50);
@@ -102,6 +100,7 @@ export class GraphQLCoreClient extends CoreClient {
 						includePreviousTransaction: options.include?.previousTransaction ?? false,
 						includeObjectBcs: options.include?.objectBcs ?? false,
 						includeJson: options.include?.json ?? false,
+						includeDisplay: options.include?.display ?? false,
 					},
 				},
 				(result) => result.multiGetObjects,
@@ -141,6 +140,11 @@ export class GraphQLCoreClient extends CoreClient {
 								: null
 							: undefined;
 
+						const displayData = mapDisplay(
+							options.include?.display,
+							obj.asMoveObject?.contents?.display,
+						);
+
 						return {
 							objectId: obj.address,
 							version: obj.version?.toString()!,
@@ -152,6 +156,7 @@ export class GraphQLCoreClient extends CoreClient {
 								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'],
 						};
 					}),
 			);
@@ -161,7 +166,7 @@ export class GraphQLCoreClient extends CoreClient {
 			objects: results,
 		};
 	}
-	async listOwnedObjects<Include extends SuiClientTypes.ObjectInclude = object>(
+	async listOwnedObjects<Include extends SuiClientTypes.ObjectInclude = {}>(
 		options: SuiClientTypes.ListOwnedObjectsOptions<Include>,
 	): Promise<SuiClientTypes.ListOwnedObjectsResponse<Include>> {
 		const objects = await this.#graphqlQuery(
@@ -178,6 +183,7 @@ export class GraphQLCoreClient extends CoreClient {
 					includePreviousTransaction: options.include?.previousTransaction ?? false,
 					includeObjectBcs: options.include?.objectBcs ?? false,
 					includeJson: options.include?.json ?? false,
+					includeDisplay: options.include?.display ?? false,
 				},
 			},
 			(result) => result.address?.objects,
@@ -204,6 +210,10 @@ export class GraphQLCoreClient extends CoreClient {
 							? (obj.contents.json as Record<string, unknown>)
 							: null
 						: undefined) as SuiClientTypes.Object<Include>['json'],
+					display: mapDisplay(
+						options.include?.display,
+						obj.contents?.display,
+					) as SuiClientTypes.Object<Include>['display'],
 				}),
 			),
 			hasNextPage: objects.pageInfo.hasNextPage,
@@ -326,7 +336,7 @@ export class GraphQLCoreClient extends CoreClient {
 			}),
 		};
 	}
-	async getTransaction<Include extends SuiClientTypes.TransactionInclude = object>(
+	async getTransaction<Include extends SuiClientTypes.TransactionInclude = {}>(
 		options: SuiClientTypes.GetTransactionOptions<Include>,
 	): Promise<SuiClientTypes.TransactionResult<Include>> {
 		const result = await this.#graphqlQuery(
@@ -347,7 +357,7 @@ export class GraphQLCoreClient extends CoreClient {
 
 		return parseTransaction(result, options.include);
 	}
-	async executeTransaction<Include extends SuiClientTypes.TransactionInclude = object>(
+	async executeTransaction<Include extends SuiClientTypes.TransactionInclude = {}>(
 		options: SuiClientTypes.ExecuteTransactionOptions<Include>,
 	): Promise<SuiClientTypes.TransactionResult<Include>> {
 		const result = await this.#graphqlQuery(
@@ -367,16 +377,9 @@ export class GraphQLCoreClient extends CoreClient {
 			(result) => result.executeTransaction,
 		);
 
-		if (result.errors) {
-			if (result.errors.length === 1) {
-				throw new Error(result.errors[0]);
-			}
-			throw new AggregateError(result.errors.map((error) => new Error(error)));
-		}
-
 		return parseTransaction(result.effects?.transaction!, options.include);
 	}
-	async simulateTransaction<Include extends SuiClientTypes.SimulateTransactionInclude = object>(
+	async simulateTransaction<Include extends SuiClientTypes.SimulateTransactionInclude = {}>(
 		options: SuiClientTypes.SimulateTransactionOptions<Include>,
 	): Promise<SuiClientTypes.SimulateTransactionResult<Include>> {
 		if (!(options.transaction instanceof Uint8Array)) {
@@ -407,10 +410,6 @@ export class GraphQLCoreClient extends CoreClient {
 			(result) => result.simulateTransaction,
 		);
 
-		if (result.error && !result.effects?.transaction) {
-			throw new SimulationError(result.error);
-		}
-
 		const transactionResult = parseTransaction(result.effects?.transaction!, options.include);
 
 		const commandResults =
@@ -558,55 +557,7 @@ export class GraphQLCoreClient extends CoreClient {
 	async listDynamicFields(
 		options: SuiClientTypes.ListDynamicFieldsOptions,
 	): Promise<SuiClientTypes.ListDynamicFieldsResponse> {
-		const result = await this.#graphqlQuery(
-			{
-				query: GetDynamicFieldsDocument,
-				variables: {
-					parentId: options.parentId,
-					first: options.limit,
-					cursor: options.cursor,
-				},
-			},
-			(result) => result.address?.dynamicFields,
-		);
-
-		return {
-			dynamicFields: result.nodes.map((dynamicField): SuiClientTypes.DynamicFieldEntry => {
-				const valueType =
-					dynamicField.value?.__typename === 'MoveObject'
-						? dynamicField.value.contents?.type?.repr!
-						: dynamicField.value?.type?.repr!;
-				const isDynamicObject = dynamicField.value?.__typename === 'MoveObject';
-				const derivedNameType = isDynamicObject
-					? `0x2::dynamic_object_field::Wrapper<${dynamicField.name?.type?.repr}>`
-					: dynamicField.name?.type?.repr!;
-
-				return {
-					$kind: isDynamicObject ? 'DynamicObject' : 'DynamicField',
-					fieldId: deriveDynamicFieldID(
-						options.parentId,
-						derivedNameType,
-						fromBase64(dynamicField.name?.bcs!),
-					),
-					type: normalizeStructTag(
-						isDynamicObject
-							? `0x2::dynamic_field::Field<0x2::dynamic_object_field::Wrapper<${dynamicField.name?.type?.repr}>,0x2::object::ID>`
-							: `0x2::dynamic_field::Field<${dynamicField.name?.type?.repr},${valueType}>`,
-					),
-					name: {
-						type: dynamicField.name?.type?.repr!,
-						bcs: fromBase64(dynamicField.name?.bcs!),
-					},
-					valueType,
-					childId:
-						isDynamicObject && dynamicField.value?.__typename === 'MoveObject'
-							? dynamicField.value.address
-							: undefined,
-				} as SuiClientTypes.DynamicFieldEntry;
-			}),
-			cursor: result.pageInfo.endCursor ?? null,
-			hasNextPage: result.pageInfo.hasNextPage,
-		};
+		return this.#graphqlClient.listDynamicFields(options);
 	}
 
 	async verifyZkLoginSignature(
@@ -617,22 +568,19 @@ export class GraphQLCoreClient extends CoreClient {
 				? ZkLoginIntentScope.TransactionData
 				: ZkLoginIntentScope.PersonalMessage;
 
-		const result = await this.#graphqlQuery(
-			{
-				query: VerifyZkLoginSignatureDocument,
-				variables: {
-					bytes: options.bytes,
-					signature: options.signature,
-					intentScope,
-					author: options.address,
-				},
+		const { data } = await this.#graphqlClient.query({
+			query: VerifyZkLoginSignatureDocument,
+			variables: {
+				bytes: options.bytes,
+				signature: options.signature,
+				intentScope,
+				author: options.address,
 			},
-			(result) => result.verifyZkLoginSignature,
-		);
+		});
 
 		return {
-			success: result.success ?? false,
-			errors: result.error ? [result.error] : [],
+			success: data?.verifyZkLoginSignature?.success ?? false,
+			errors: [],
 		};
 	}
 
@@ -765,12 +713,6 @@ export class GraphQLCoreClient extends CoreClient {
 
 			handleGraphQLErrors(errors);
 
-			if (data?.simulateTransaction?.error) {
-				throw new SimulationError(
-					`Transaction resolution failed: ${data.simulateTransaction.error}`,
-				);
-			}
-
 			const transactionEffects = data?.simulateTransaction?.effects?.transaction?.effects;
 			if (!options.onlyTransactionKind && transactionEffects?.status === ExecutionStatus.Failure) {
 				const executionError = parseGraphQLExecutionError(transactionEffects.executionError);
@@ -815,6 +757,18 @@ export type GraphQLResponseErrors = Array<{
 	path?: (string | number)[];
 }>;
 
+function mapDisplay(
+	include: boolean | undefined,
+	display: { output?: unknown | null; errors?: unknown | null } | null | undefined,
+): SuiClientTypes.Display | null | undefined {
+	if (!include) return undefined;
+	if (!display) return null;
+	return {
+		output: (display.output as Record<string, string> | null) ?? null,
+		errors: (display.errors as Record<string, string> | null) ?? null,
+	};
+}
+
 function handleGraphQLErrors(errors: GraphQLResponseErrors | undefined): void {
 	if (!errors || errors.length === 0) return;
 
@@ -860,7 +814,7 @@ function mapOwner(owner: Object_Owner_FieldsFragment): SuiClientTypes.ObjectOwne
 	}
 }
 
-function parseTransaction<Include extends SuiClientTypes.TransactionInclude = object>(
+function parseTransaction<Include extends SuiClientTypes.TransactionInclude = {}>(
 	transaction: Transaction_FieldsFragment,
 	include?: Include,
 ): SuiClientTypes.TransactionResult<Include> {
@@ -961,6 +915,7 @@ function parseTransaction<Include extends SuiClientTypes.TransactionInclude = ob
 						sender: event.sender?.address!,
 						eventType,
 						bcs: event.contents?.bcs ? fromBase64(event.contents.bcs) : new Uint8Array(),
+						json: (event.contents?.json as Record<string, unknown>) ?? null,
 					};
 				}) ?? [])
 			: undefined) as SuiClientTypes.Transaction<Include>['events'],