@mysten/sui 1.31.0 → 1.33.0

package/src/experimental/mvr.ts

@@ -0,0 +1,477 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { chunk, DataLoader } from '@mysten/utils';
+import { isValidNamedPackage, isValidNamedType } from '../utils/move-registry.js';
+import type { StructTag } from '../utils/sui-types.js';
+import {
+	isValidSuiAddress,
+	normalizeStructTag,
+	normalizeSuiAddress,
+	parseStructTag,
+} from '../utils/sui-types.js';
+import type { ClientCache } from './cache.js';
+import type { TransactionDataBuilder } from '../transactions/TransactionData.js';
+import { PACKAGE_VERSION } from '../version.js';
+import type { Experimental_SuiClientTypes } from './types.js';
+
+const NAME_SEPARATOR = '/';
+const MVR_API_HEADER = {
+	'Mvr-Source': `@mysten/sui@${PACKAGE_VERSION}`,
+};
+
+export interface MvrClientOptions {
+	cache: ClientCache;
+	url?: string;
+	pageSize?: number;
+	overrides?: {
+		packages?: Record<string, string>;
+		types?: Record<string, string>;
+	};
+}
+
+export class MvrClient implements Experimental_SuiClientTypes.MvrMethods {
+	#cache: ClientCache;
+	#url?: string;
+	#pageSize: number;
+	#overrides: {
+		packages?: Record<string, string>;
+		types?: Record<string, string>;
+	};
+
+	constructor({ cache, url, pageSize = 50, overrides }: MvrClientOptions) {
+		this.#cache = cache;
+		this.#url = url;
+		this.#pageSize = pageSize;
+		this.#overrides = {
+			packages: overrides?.packages,
+			types: overrides?.types,
+		};
+
+		validateOverrides(this.#overrides);
+	}
+
+	get #mvrPackageDataLoader() {
+		return this.#cache.readSync(['#mvrPackageDataLoader', this.#url ?? ''], () => {
+			const loader = new DataLoader<string, string>(async (packages) => {
+				if (!this.#url) {
+					throw new Error(
+						`MVR Api URL is not set for the current client (resolving ${packages.join(', ')})`,
+					);
+				}
+				const resolved = await this.#resolvePackages(packages);
+
+				return packages.map(
+					(pkg) => resolved[pkg] ?? new Error(`Failed to resolve package: ${pkg}`),
+				);
+			});
+			const overrides = this.#overrides?.packages;
+
+			if (overrides) {
+				for (const [pkg, id] of Object.entries(overrides)) {
+					loader.prime(pkg, id);
+				}
+			}
+
+			return loader;
+		});
+	}
+
+	get #mvrTypeDataLoader() {
+		return this.#cache.readSync(['#mvrTypeDataLoader', this.#url ?? ''], () => {
+			const loader = new DataLoader<string, string>(async (types) => {
+				if (!this.#url) {
+					throw new Error(
+						`MVR Api URL is not set for the current client (resolving ${types.join(', ')})`,
+					);
+				}
+				const resolved = await this.#resolveTypes(types);
+
+				return types.map((type) => resolved[type] ?? new Error(`Failed to resolve type: ${type}`));
+			});
+
+			const overrides = this.#overrides?.types;
+
+			if (overrides) {
+				for (const [type, id] of Object.entries(overrides)) {
+					loader.prime(type, id);
+				}
+			}
+
+			return loader;
+		});
+	}
+
+	async #resolvePackages(packages: readonly string[]) {
+		if (packages.length === 0) return {};
+
+		const batches = chunk(packages, this.#pageSize);
+		const results: Record<string, string> = {};
+
+		await Promise.all(
+			batches.map(async (batch) => {
+				const data = await this.#fetch<{ resolution: Record<string, { package_id: string }> }>(
+					'/v1/resolution/bulk',
+					{
+						names: batch,
+					},
+				);
+
+				if (!data?.resolution) return;
+
+				for (const pkg of Object.keys(data?.resolution)) {
+					const pkgData = data.resolution[pkg]?.package_id;
+
+					if (!pkgData) continue;
+
+					results[pkg] = pkgData;
+				}
+			}),
+		);
+
+		return results;
+	}
+
+	async #resolveTypes(types: readonly string[]) {
+		if (types.length === 0) return {};
+
+		const batches = chunk(types, this.#pageSize);
+		const results: Record<string, string> = {};
+
+		await Promise.all(
+			batches.map(async (batch) => {
+				const data = await this.#fetch<{ resolution: Record<string, { type_tag: string }> }>(
+					'/v1/struct-definition/bulk',
+					{
+						types: batch,
+					},
+				);
+
+				if (!data?.resolution) return;
+
+				for (const type of Object.keys(data?.resolution)) {
+					const typeData = data.resolution[type]?.type_tag;
+					if (!typeData) continue;
+
+					results[type] = typeData;
+				}
+			}),
+		);
+
+		return results;
+	}
+
+	async #fetch<T>(url: string, body: Record<string, unknown>): Promise<T> {
+		if (!this.#url) {
+			throw new Error('MVR Api URL is not set for the current client');
+		}
+
+		const response = await fetch(`${this.#url}${url}`, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				...MVR_API_HEADER,
+			},
+			body: JSON.stringify(body),
+		});
+
+		if (!response.ok) {
+			const errorBody = await response.json().catch(() => ({}));
+			throw new Error(`Failed to resolve types: ${errorBody?.message}`);
+		}
+
+		return response.json();
+	}
+
+	async resolvePackage({
+		package: name,
+	}: Experimental_SuiClientTypes.MvrResolvePackageOptions): Promise<Experimental_SuiClientTypes.MvrResolvePackageResponse> {
+		const resolved = await this.#mvrPackageDataLoader.load(name);
+		return {
+			package: resolved,
+		};
+	}
+
+	async resolveType({
+		type,
+	}: Experimental_SuiClientTypes.MvrResolveTypeOptions): Promise<Experimental_SuiClientTypes.MvrResolveTypeResponse> {
+		const mvrTypes = [...extractMvrTypes(type)];
+		const resolvedTypes = await this.#mvrTypeDataLoader.loadMany(mvrTypes);
+
+		const typeMap: Record<string, string> = {};
+
+		for (let i = 0; i < mvrTypes.length; i++) {
+			const resolvedType = resolvedTypes[i];
+			if (resolvedType instanceof Error) {
+				throw resolvedType;
+			}
+			typeMap[mvrTypes[i]] = resolvedType;
+		}
+
+		return {
+			type: replaceMvrNames(type, typeMap),
+		};
+	}
+
+	async resolve({
+		types = [],
+		packages = [],
+	}: Experimental_SuiClientTypes.MvrResolveOptions): Promise<Experimental_SuiClientTypes.MvrResolveResponse> {
+		const mvrTypes = new Set<string>();
+
+		for (const type of types ?? []) {
+			extractMvrTypes(type, mvrTypes);
+		}
+
+		const typesArray = [...mvrTypes];
+		const [resolvedTypes, resolvedPackages] = await Promise.all([
+			typesArray.length > 0 ? this.#mvrTypeDataLoader.loadMany(typesArray) : [],
+			packages.length > 0 ? this.#mvrPackageDataLoader.loadMany(packages) : [],
+		]);
+
+		const typeMap: Record<string, string> = {
+			...this.#overrides?.types,
+		};
+
+		for (const [i, type] of typesArray.entries()) {
+			const resolvedType = resolvedTypes[i];
+			if (resolvedType instanceof Error) {
+				throw resolvedType;
+			}
+			typeMap[type] = resolvedType;
+		}
+
+		const replacedTypes: Record<
+			string,
+			{
+				type: string;
+			}
+		> = {};
+
+		for (const type of types ?? []) {
+			const resolvedType = replaceMvrNames(type, typeMap);
+
+			replacedTypes[type] = {
+				type: resolvedType,
+			};
+		}
+
+		const replacedPackages: Record<
+			string,
+			{
+				package: string;
+			}
+		> = {};
+
+		for (const [i, pkg] of (packages ?? []).entries()) {
+			const resolvedPkg = this.#overrides?.packages?.[pkg] ?? resolvedPackages[i];
+
+			if (resolvedPkg instanceof Error) {
+				throw resolvedPkg;
+			}
+
+			replacedPackages[pkg] = {
+				package: resolvedPkg,
+			};
+		}
+
+		return {
+			types: replacedTypes,
+			packages: replacedPackages,
+		};
+	}
+}
+
+function validateOverrides(overrides?: {
+	packages?: Record<string, string>;
+	types?: Record<string, string>;
+}) {
+	if (overrides?.packages) {
+		for (const [pkg, id] of Object.entries(overrides.packages)) {
+			if (!isValidNamedPackage(pkg)) {
+				throw new Error(`Invalid package name: ${pkg}`);
+			}
+			if (!isValidSuiAddress(normalizeSuiAddress(id))) {
+				throw new Error(`Invalid package ID: ${id}`);
+			}
+		}
+	}
+
+	if (overrides?.types) {
+		for (const [type, val] of Object.entries(overrides.types)) {
+			// validate that types are first-level only.
+			if (parseStructTag(type).typeParams.length > 0) {
+				throw new Error(
+					'Type overrides must be first-level only. If you want to supply generic types, just pass each type individually.',
+				);
+			}
+
+			const parsedValue = parseStructTag(val);
+
+			if (!isValidSuiAddress(parsedValue.address)) {
+				throw new Error(`Invalid type: ${val}`);
+			}
+		}
+	}
+}
+
+/**
+ * Extracts all named types from a given type.
+ */
+export function extractMvrTypes(type: string | StructTag, types = new Set<string>()) {
+	if (typeof type === 'string' && !hasMvrName(type)) return types;
+
+	const tag = isStructTag(type) ? type : parseStructTag(type);
+
+	if (hasMvrName(tag.address)) types.add(`${tag.address}::${tag.module}::${tag.name}`);
+
+	for (const param of tag.typeParams) {
+		extractMvrTypes(param, types);
+	}
+
+	return types;
+}
+
+/**
+ * Traverses a type, and replaces any found names with their resolved equivalents,
+ * based on the supplied type cache.
+ */
+function replaceMvrNames(tag: string | StructTag, typeCache: Record<string, string>): string {
+	const type = isStructTag(tag) ? tag : parseStructTag(tag);
+
+	const typeTag = `${type.address}::${type.module}::${type.name}`;
+	const cacheHit = typeCache[typeTag];
+
+	return normalizeStructTag({
+		...type,
+		address: cacheHit ? cacheHit.split('::')[0] : type.address,
+		typeParams: type.typeParams.map((param) => replaceMvrNames(param, typeCache)),
+	});
+}
+
+export function hasMvrName(nameOrType: string) {
+	return (
+		nameOrType.includes(NAME_SEPARATOR) || nameOrType.includes('@') || nameOrType.includes('.sui')
+	);
+}
+
+function isStructTag(type: string | StructTag): type is StructTag {
+	return (
+		typeof type === 'object' &&
+		'address' in type &&
+		'module' in type &&
+		'name' in type &&
+		'typeParams' in type
+	);
+}
+
+export type NamedPackagesOverrides = {
+	packages: Record<string, string>;
+	types: Record<string, string>;
+};
+
+/**
+ * Looks up all `.move` names in a transaction block.
+ * Returns a list of all the names found.
+ */
+export function findNamesInTransaction(builder: TransactionDataBuilder): {
+	packages: string[];
+	types: string[];
+} {
+	const packages: Set<string> = new Set();
+	const types: Set<string> = new Set();
+
+	for (const command of builder.commands) {
+		switch (command.$kind) {
+			case 'MakeMoveVec':
+				if (command.MakeMoveVec.type) {
+					getNamesFromTypeList([command.MakeMoveVec.type]).forEach((type) => {
+						types.add(type);
+					});
+				}
+				break;
+			case 'MoveCall':
+				const moveCall = command.MoveCall;
+
+				const pkg = moveCall.package.split('::')[0];
+				if (hasMvrName(pkg)) {
+					if (!isValidNamedPackage(pkg)) throw new Error(`Invalid package name: ${pkg}`);
+					packages.add(pkg);
+				}
+
+				getNamesFromTypeList(moveCall.typeArguments ?? []).forEach((type) => {
+					types.add(type);
+				});
+
+				break;
+			default:
+				break;
+		}
+	}
+
+	return {
+		packages: [...packages],
+		types: [...types],
+	};
+}
+
+/**
+ * Replace all names & types in a transaction block
+ * with their resolved names/types.
+ */
+export function replaceNames(
+	builder: TransactionDataBuilder,
+	resolved: Experimental_SuiClientTypes.MvrResolveResponse,
+) {
+	for (const command of builder.commands) {
+		// Replacements for `MakeMoveVec` commands (that can include types)
+		if (command.MakeMoveVec?.type) {
+			if (!hasMvrName(command.MakeMoveVec.type)) continue;
+			if (!resolved.types[command.MakeMoveVec.type])
+				throw new Error(`No resolution found for type: ${command.MakeMoveVec.type}`);
+			command.MakeMoveVec.type = resolved.types[command.MakeMoveVec.type].type;
+		}
+		// Replacements for `MoveCall` commands (that can include packages & types)
+		const tx = command.MoveCall;
+		if (!tx) continue;
+
+		const nameParts = tx.package.split('::');
+		const name = nameParts[0];
+
+		if (hasMvrName(name) && !resolved.packages[name])
+			throw new Error(`No address found for package: ${name}`);
+
+		// Replace package name with address.
+		if (hasMvrName(name)) {
+			nameParts[0] = resolved.packages[name].package;
+			tx.package = nameParts.join('::');
+		}
+
+		const types = tx.typeArguments;
+		if (!types) continue;
+
+		for (let i = 0; i < types.length; i++) {
+			if (!hasMvrName(types[i])) continue;
+
+			if (!resolved.types[types[i]]) throw new Error(`No resolution found for type: ${types[i]}`);
+			types[i] = resolved.types[types[i]].type;
+		}
+
+		tx.typeArguments = types;
+	}
+}
+
+/**
+ * Returns a list of unique types that include a name
+ * from the given list. This list is retrieved from the Transaction Data.
+ */
+function getNamesFromTypeList(types: string[]) {
+	const names = new Set<string>();
+	for (const type of types) {
+		if (hasMvrName(type)) {
+			if (!isValidNamedType(type)) throw new Error(`Invalid type with names: ${type}`);
+			names.add(type);
+		}
+	}
+	return names;
+}

package/src/experimental/transports/graphql.ts

@@ -33,8 +33,14 @@ import { parseTransactionBcs, parseTransactionEffectsBcs } from './utils.js';
 export class GraphQLTransport extends Experimental_CoreClient {
 	#graphqlClient: SuiGraphQLClient;
 
-	constructor(graphqlClient: SuiGraphQLClient) {
-		super({ network: graphqlClient.network });
+	constructor({
+		graphqlClient,
+		mvr,
+	}: {
+		graphqlClient: SuiGraphQLClient;
+		mvr?: Experimental_SuiClientTypes.MvrOptions;
+	}) {
+		super({ network: graphqlClient.network, base: graphqlClient, mvr });
 		this.#graphqlClient = graphqlClient;
 	}
 
@@ -98,13 +104,15 @@ export class GraphQLTransport extends Experimental_CoreClient {
 					}
 					return {
 						id: obj.address,
-						version: obj.version,
+						version: obj.version.toString(),
 						digest: obj.digest!,
 						owner: mapOwner(obj.owner!),
 						type: obj.asMoveObject?.contents?.type?.repr!,
-						content: obj.asMoveObject
-							? fromBase64(obj.asMoveObject?.contents?.bcs!)
-							: new Uint8Array(),
+						content: Promise.resolve(
+							obj.asMoveObject?.contents?.bcs
+								? fromBase64(obj.asMoveObject.contents.bcs)
+								: new Uint8Array(),
+						),
 					};
 				}),
 		};
@@ -128,11 +136,13 @@ export class GraphQLTransport extends Experimental_CoreClient {
 		return {
 			objects: objects.nodes.map((obj) => ({
 				id: obj.address,
-				version: obj.version,
+				version: obj.version.toString(),
 				digest: obj.digest!,
 				owner: mapOwner(obj.owner!),
 				type: obj.contents?.type?.repr!,
-				content: fromBase64(obj.contents?.bcs!),
+				content: Promise.resolve(
+					obj.contents?.bcs ? fromBase64(obj.contents.bcs) : new Uint8Array(),
+				),
 			})),
 			hasNextPage: objects.pageInfo.hasNextPage,
 			cursor: objects.pageInfo.endCursor ?? null,
@@ -159,12 +169,14 @@ export class GraphQLTransport extends Experimental_CoreClient {
 			hasNextPage: coins.pageInfo.hasNextPage,
 			objects: coins.nodes.map((coin) => ({
 				id: coin.address,
-				version: coin.version,
+				version: coin.version.toString(),
 				digest: coin.digest!,
 				owner: mapOwner(coin.owner!),
 				type: coin.contents?.type?.repr!,
 				balance: coin.coinBalance,
-				content: fromBase64(coin.contents?.bcs!),
+				content: Promise.resolve(
+					coin.contents?.bcs ? fromBase64(coin.contents.bcs) : new Uint8Array(),
+				),
 			})),
 		};
 	}

package/src/experimental/transports/jsonRPC.ts

@@ -12,7 +12,6 @@ import type {
 	SuiTransactionBlockResponse,
 	TransactionEffects,
 } from '../../client/index.js';
-import { batch } from '../../transactions/plugins/utils.js';
 import { Transaction } from '../../transactions/Transaction.js';
 import { Experimental_CoreClient } from '../core.js';
 import { ObjectError } from '../errors.js';
@@ -20,17 +19,24 @@ import type { Experimental_SuiClientTypes } from '../types.js';
 import { parseTransactionBcs, parseTransactionEffectsBcs } from './utils.js';
 import { resolveTransactionPlugin } from './json-rpc-resolver.js';
 import { TransactionDataBuilder } from '../../transactions/TransactionData.js';
+import { chunk } from '@mysten/utils';
 
 export class JSONRpcTransport extends Experimental_CoreClient {
 	#jsonRpcClient: SuiClient;
 
-	constructor(jsonRpcClient: SuiClient) {
-		super({ network: jsonRpcClient.network });
+	constructor({
+		jsonRpcClient,
+		mvr,
+	}: {
+		jsonRpcClient: SuiClient;
+		mvr?: Experimental_SuiClientTypes.MvrOptions;
+	}) {
+		super({ network: jsonRpcClient.network, base: jsonRpcClient, mvr });
 		this.#jsonRpcClient = jsonRpcClient;
 	}
 
 	async getObjects(options: Experimental_SuiClientTypes.GetObjectsOptions) {
-		const batches = batch(options.objectIds, 50);
+		const batches = chunk(options.objectIds, 50);
 		const results: Experimental_SuiClientTypes.GetObjectsResponse['objects'] = [];
 
 		for (const batch of batches) {
@@ -67,6 +73,7 @@ export class JSONRpcTransport extends Experimental_CoreClient {
 				showType: true,
 				showBcs: true,
 			},
+			filter: options.type ? { StructType: options.type } : null,
 			signal: options.signal,
 		});
 
@@ -100,12 +107,14 @@ export class JSONRpcTransport extends Experimental_CoreClient {
 					digest: coin.digest,
 					balance: coin.balance,
 					type: `0x2::coin::Coin<${coin.coinType}>`,
-					content: Coin.serialize({
-						id: coin.coinObjectId,
-						balance: {
-							value: coin.balance,
-						},
-					}).toBytes(),
+					content: Promise.resolve(
+						Coin.serialize({
+							id: coin.coinObjectId,
+							balance: {
+								value: coin.balance,
+							},
+						}).toBytes(),
+					),
 					owner: {
 						$kind: 'ObjectOwner' as const,
 						ObjectOwner: options.address,
@@ -267,8 +276,9 @@ function parseObject(object: SuiObjectData): Experimental_SuiClientTypes.ObjectR
 		version: object.version,
 		digest: object.digest,
 		type: object.type!,
-		content:
+		content: Promise.resolve(
 			object.bcs?.dataType === 'moveObject' ? fromBase64(object.bcs.bcsBytes) : new Uint8Array(),
+		),
 		owner: parseOwner(object.owner!),
 	};
 }

package/src/experimental/transports/utils.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { bcs } from '../../bcs/index.js';
-import { TransactionDataBuilder } from '../../transactions/index.js';
+import { TransactionDataBuilder } from '../../transactions/TransactionData.js';
 import type { Experimental_SuiClientTypes } from '../types.js';
 
 export function parseTransactionBcs(

package/src/experimental/types.ts

@@ -37,6 +37,16 @@ export namespace Experimental_SuiClientTypes {
 
 	export interface SuiClientOptions {
 		network: Network;
+		base?: Experimental_BaseClient;
+	}
+
+	export interface MvrOptions {
+		url?: string;
+		pageSize?: number;
+		overrides?: {
+			packages?: Record<string, string>;
+			types?: Record<string, string>;
+		};
 	}
 
 	export interface CoreClientMethodOptions {
@@ -111,7 +121,7 @@ export namespace Experimental_SuiClientTypes {
 		digest: string;
 		owner: ObjectOwner;
 		type: string;
-		content: Uint8Array;
+		content: PromiseLike<Uint8Array>;
 	}
 
 	export interface CoinResponse extends ObjectResponse {
@@ -279,6 +289,54 @@ export namespace Experimental_SuiClientTypes {
 		) => Promise<ResolveNameServiceNamesResponse>;
 	}
 
+	/** MVR methods */
+
+	export interface TransportMethods {
+		mvr: MvrMethods;
+	}
+
+	export interface MvrMethods {
+		resolvePackage: (options: MvrResolvePackageOptions) => Promise<MvrResolvePackageResponse>;
+		resolveType: (options: MvrResolveTypeOptions) => Promise<MvrResolveTypeResponse>;
+		resolve: (options: MvrResolveOptions) => Promise<MvrResolveResponse>;
+	}
+
+	export interface MvrResolvePackageOptions extends CoreClientMethodOptions {
+		package: string;
+	}
+
+	export interface MvrResolveTypeOptions extends CoreClientMethodOptions {
+		type: string;
+	}
+
+	export interface MvrResolveOptions extends CoreClientMethodOptions {
+		packages?: string[];
+		types?: string[];
+	}
+
+	export interface MvrResolvePackageResponse {
+		package: string;
+	}
+
+	export interface MvrResolveTypeResponse {
+		type: string;
+	}
+
+	export interface MvrResolveResponse {
+		packages: Record<
+			string,
+			{
+				package: string;
+			}
+		>;
+		types: Record<
+			string,
+			{
+				type: string;
+			}
+		>;
+	}
+
 	/** ObjectOwner types */
 
 	export interface AddressOwner {