@mysten/sui 1.8.0 → 1.9.0

package/src/transactions/Transaction.ts

@@ -99,19 +99,23 @@ export function isTransaction(obj: unknown): obj is Transaction {
 
 export type TransactionObjectInput = string | CallArg | TransactionObjectArgument;
 
-const modulePluginRegistry = {
-	buildPlugins: [] as TransactionPlugin[],
-	serializationPlugins: [] as TransactionPlugin[],
+interface TransactionPluginRegistry {
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	buildPlugins: Map<string | Function, TransactionPlugin>;
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	serializationPlugins: Map<string | Function, TransactionPlugin>;
+}
+
+const modulePluginRegistry: TransactionPluginRegistry = {
+	buildPlugins: new Map(),
+	serializationPlugins: new Map(),
 };
 
 const TRANSACTION_REGISTRY_KEY = Symbol.for('@mysten/transaction/registry');
 function getGlobalPluginRegistry() {
 	try {
 		const target = globalThis as {
-			[TRANSACTION_REGISTRY_KEY]?: {
-				buildPlugins: TransactionPlugin[];
-				serializationPlugins: TransactionPlugin[];
-			};
+			[TRANSACTION_REGISTRY_KEY]?: TransactionPluginRegistry;
 		};
 
 		if (!target[TRANSACTION_REGISTRY_KEY]) {
@@ -168,12 +172,38 @@ export class Transaction {
 		return newTransaction;
 	}
 
-	static registerGlobalSerializationPlugin(step: TransactionPlugin) {
-		getGlobalPluginRegistry().serializationPlugins.push(step);
+	/** @deprecated global plugins should be registered with a name */
+	static registerGlobalSerializationPlugin(step: TransactionPlugin): void;
+	static registerGlobalSerializationPlugin(name: string, step: TransactionPlugin): void;
+	static registerGlobalSerializationPlugin(
+		stepOrStep: TransactionPlugin | string,
+		step?: TransactionPlugin,
+	) {
+		getGlobalPluginRegistry().serializationPlugins.set(
+			stepOrStep,
+			step ?? (stepOrStep as TransactionPlugin),
+		);
+	}
+
+	static unregisterGlobalSerializationPlugin(name: string) {
+		getGlobalPluginRegistry().serializationPlugins.delete(name);
+	}
+
+	/** @deprecated global plugins should be registered with a name */
+	static registerGlobalBuildPlugin(step: TransactionPlugin): void;
+	static registerGlobalBuildPlugin(name: string, step: TransactionPlugin): void;
+	static registerGlobalBuildPlugin(
+		stepOrStep: TransactionPlugin | string,
+		step?: TransactionPlugin,
+	) {
+		getGlobalPluginRegistry().buildPlugins.set(
+			stepOrStep,
+			step ?? (stepOrStep as TransactionPlugin),
+		);
 	}
 
-	static registerGlobalBuildPlugin(step: TransactionPlugin) {
-		getGlobalPluginRegistry().buildPlugins.push(step);
+	static unregisterGlobalBuildPlugin(name: string) {
+		getGlobalPluginRegistry().buildPlugins.delete(name);
 	}
 
 	addSerializationPlugin(step: TransactionPlugin) {
@@ -277,8 +307,8 @@ export class Transaction {
 	constructor() {
 		const globalPlugins = getGlobalPluginRegistry();
 		this.#data = new TransactionDataBuilder();
-		this.#buildPlugins = [...globalPlugins.buildPlugins];
-		this.#serializationPlugins = [...globalPlugins.serializationPlugins];
+		this.#buildPlugins = [...globalPlugins.buildPlugins.values()];
+		this.#serializationPlugins = [...globalPlugins.serializationPlugins.values()];
 	}
 
 	/** Returns an argument for the gas coin, to be used in a transaction. */

package/src/transactions/index.ts

@@ -47,3 +47,10 @@ export type {
 } from './json-rpc-resolver.js';
 
 export { Arguments } from './Arguments.js';
+
+export {
+	namedPackagesPlugin,
+	type NamedPackagesPluginOptions,
+} from './plugins/NamedPackagesPlugin.js';
+
+export { type NamedPackagesPluginCache } from './plugins/utils.js';

package/src/transactions/plugins/NamedPackagesPlugin.ts

@@ -0,0 +1,129 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { SuiGraphQLClient } from '../../graphql/client.js';
+import type { BuildTransactionOptions } from '../json-rpc-resolver.js';
+import type { TransactionDataBuilder } from '../TransactionData.js';
+import type { NamedPackagesPluginCache, NameResolutionRequest } from './utils.js';
+import { findTransactionBlockNames, listToRequests, replaceNames } from './utils.js';
+
+export type NamedPackagesPluginOptions = {
+	/**
+	 * The SuiGraphQLClient to use for resolving names.
+	 * The endpoint should be the GraphQL endpoint of the network you are targeting.
+	 * For non-mainnet networks, if the plugin doesn't work as expected, you need to validate that the
+	 * RPC provider has support for the `packageByName` and `typeByName` queries (using external resolver).
+	 */
+	suiGraphQLClient: SuiGraphQLClient;
+	/**
+	 * The number of names to resolve in each batch request.
+	 * Needs to be calculated based on the GraphQL query limits.
+	 */
+	pageSize?: number;
+	/**
+	 * Local overrides for the resolution plugin. Pass this to pre-populate
+	 * the cache with known packages / types (especially useful for local or CI testing).
+	 *
+	 * 	Expected format example:
+	 *  {
+	 * 		packages: {
+	 * 			'std@framework': '0x1234',
+	 * 		},
+	 * 		types: {
+	 * 			'std@framework::string::String': '0x1234::string::String',
+	 * 		},
+	 * 	}
+	 *
+	 */
+	overrides?: NamedPackagesPluginCache;
+};
+
+/**
+ * @experimental This plugin is in experimental phase and there might be breaking changes in the future
+ *
+ * Adds named resolution so that you can use .move names in your transactions.
+ * e.g. `app@org::type::Type` will be resolved to `0x1234::type::Type`.
+ * This plugin will resolve all names & types in the transaction block.
+ *
+ * To install this plugin globally in your app, use:
+ * ```
+ * Transaction.registerGlobalSerializationPlugin("namedPackagesPlugin", namedPackagesPlugin({ suiGraphQLClient }));
+ * ```
+ *
+ * You can also define `overrides` to pre-populate name resolutions locally (removes the GraphQL request).
+ */
+export const namedPackagesPlugin = ({
+	suiGraphQLClient,
+	pageSize = 10,
+	overrides = { packages: {}, types: {} },
+}: NamedPackagesPluginOptions) => {
+	const cache = {
+		packages: { ...overrides.packages },
+		types: { ...overrides.types },
+	};
+
+	return async (
+		transactionData: TransactionDataBuilder,
+		_buildOptions: BuildTransactionOptions,
+		next: () => Promise<void>,
+	) => {
+		const names = findTransactionBlockNames(transactionData);
+		const batches = listToRequests(
+			{
+				packages: names.packages.filter((x) => !cache.packages[x]),
+				types: names.types.filter((x) => !cache.types[x]),
+			},
+			pageSize,
+		);
+
+		// now we need to bulk resolve all the names + types, and replace them in the transaction data.
+		(await Promise.all(batches.map((batch) => query(suiGraphQLClient, batch)))).forEach((res) => {
+			Object.assign(cache.types, res.types);
+			Object.assign(cache.packages, res.packages);
+		});
+
+		replaceNames(transactionData, cache);
+
+		await next();
+	};
+
+	async function query(client: SuiGraphQLClient, requests: NameResolutionRequest[]) {
+		const results: NamedPackagesPluginCache = { packages: {}, types: {} };
+		// avoid making a request if there are no names to resolve.
+		if (requests.length === 0) return results;
+
+		// Create multiple queries for each name / type we need to resolve
+		// TODO: Replace with bulk APIs when available.
+		const gqlQuery = `{
+        ${requests.map((req) => {
+					const request = req.type === 'package' ? 'packageByName' : 'typeByName';
+					const fields = req.type === 'package' ? 'address' : 'repr';
+
+					return `${gqlQueryKey(req.id)}: ${request}(name:"${req.name}") {
+                    ${fields}
+                }`;
+				})}
+    }`;
+
+		const result = await client.query({
+			query: gqlQuery,
+			variables: undefined,
+		});
+
+		if (result.errors) throw new Error(JSON.stringify({ query: gqlQuery, errors: result.errors }));
+
+		// Parse the results and create a map of `<name|type> -> <address|repr>`
+		for (const req of requests) {
+			const key = gqlQueryKey(req.id);
+			if (!result.data || !result.data[key]) throw new Error(`No result found for: ${req.name}`);
+			const data = result.data[key] as { address?: string; repr?: string };
+
+			if (req.type === 'package') results.packages[req.name] = data.address!;
+			if (req.type === 'moveType') results.types[req.name] = data.repr!;
+		}
+
+		return results;
+	}
+};
+
+const gqlQueryKey = (idx: number) => `key_${idx}`;

package/src/transactions/plugins/utils.ts

@@ -0,0 +1,118 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isValidNamedPackage, isValidNamedType } from '../../utils/move-registry.js';
+import type { TransactionDataBuilder } from '../TransactionData.js';
+
+export type NamedPackagesPluginCache = {
+	packages: Record<string, string>;
+	types: Record<string, string>;
+};
+
+const NAME_SEPARATOR = '@';
+
+export type NameResolutionRequest = {
+	id: number;
+	type: 'package' | 'moveType';
+	name: string;
+};
+
+/**
+ * Looks up all `.move` names in a transaction block.
+ * Returns a list of all the names found.
+ */
+export const findTransactionBlockNames = (
+	builder: TransactionDataBuilder,
+): { packages: string[]; types: string[] } => {
+	const packages: Set<string> = new Set();
+	const types: Set<string> = new Set();
+
+	for (const command of builder.commands) {
+		if (!('MoveCall' in command)) continue;
+		const tx = command.MoveCall;
+
+		if (!tx) continue;
+
+		const pkg = tx.package.split('::')[0];
+		if (pkg.includes(NAME_SEPARATOR)) {
+			if (!isValidNamedPackage(pkg)) throw new Error(`Invalid package name: ${pkg}`);
+			packages.add(pkg);
+		}
+
+		for (const type of tx.typeArguments ?? []) {
+			if (type.includes(NAME_SEPARATOR)) {
+				if (!isValidNamedType(type)) throw new Error(`Invalid type with names: ${type}`);
+				types.add(type);
+			}
+		}
+	}
+
+	return {
+		packages: [...packages],
+		types: [...types],
+	};
+};
+
+/**
+ * Replace all names & types in a transaction block
+ * with their resolved names/types.
+ */
+export const replaceNames = (builder: TransactionDataBuilder, cache: NamedPackagesPluginCache) => {
+	for (const command of builder.commands) {
+		const tx = command.MoveCall;
+		if (!tx) continue;
+
+		const nameParts = tx.package.split('::');
+		const name = nameParts[0];
+
+		if (name.includes(NAME_SEPARATOR) && !cache.packages[name])
+			throw new Error(`No address found for package: ${name}`);
+
+		nameParts[0] = cache.packages[name];
+		tx.package = nameParts.join('::');
+
+		const types = tx.typeArguments;
+		if (!types) continue;
+
+		for (let i = 0; i < types.length; i++) {
+			if (!types[i].includes(NAME_SEPARATOR)) continue;
+
+			if (!cache.types[types[i]]) throw new Error(`No resolution found for type: ${types[i]}`);
+			types[i] = cache.types[types[i]];
+		}
+
+		tx.typeArguments = types;
+	}
+};
+
+export const listToRequests = (
+	names: { packages: string[]; types: string[] },
+	batchSize: number,
+): NameResolutionRequest[][] => {
+	const results: NameResolutionRequest[] = [];
+	const uniqueNames = deduplicate(names.packages);
+	const uniqueTypes = deduplicate(names.types);
+
+	for (const [idx, name] of uniqueNames.entries()) {
+		results.push({ id: idx, type: 'package', name } as NameResolutionRequest);
+	}
+	for (const [idx, type] of uniqueTypes.entries()) {
+		results.push({
+			id: idx + uniqueNames.length,
+			type: 'moveType',
+			name: type,
+		} as NameResolutionRequest);
+	}
+
+	return batch(results, batchSize);
+};
+
+const deduplicate = <T>(arr: T[]): T[] => [...new Set(arr)];
+
+const batch = <T>(arr: T[], size: number): T[][] => {
+	const batches = [];
+	for (let i = 0; i < arr.length; i += size) {
+		batches.push(arr.slice(i, i + size));
+	}
+	return batches;
+};

package/src/utils/index.ts

@@ -27,3 +27,5 @@ export {
 	SUI_TYPE_ARG,
 	SUI_SYSTEM_STATE_OBJECT_ID,
 } from './constants.js';
+
+export { isValidNamedPackage, isValidNamedType } from './move-registry.js';

package/src/utils/move-registry.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/** The pattern to find an optionally versioned name */
+const NAME_PATTERN = /^([a-z0-9]+(?:-[a-z0-9]+)*)@([a-z0-9]+(?:-[a-z0-9]+)*)(?:\/v(\d+))?$/;
+
+export const isValidNamedPackage = (name: string): boolean => {
+	return NAME_PATTERN.test(name);
+};
+
+/**
+ * Checks if a type contains valid named packages.
+ * This DOES NOT check if the type is a valid Move type.
+ */
+export const isValidNamedType = (type: string): boolean => {
+	// split our type by all possible type delimeters.
+	const splitType = type.split(/::|<|>|,/);
+	for (const t of splitType) {
+		if (t.includes('@') && !isValidNamedPackage(t)) return false;
+	}
+	// TODO: Add `isValidStructTag` check once
+	// it's generally introduced.
+	return true;
+};

package/src/version.ts

@@ -3,5 +3,5 @@
 
 // This file is generated by genversion.mjs. Do not edit it directly.
 
-export const PACKAGE_VERSION = '1.8.0';
-export const TARGETED_RPC_VERSION = '1.33.0';
+export const PACKAGE_VERSION = '1.9.0';
+export const TARGETED_RPC_VERSION = '1.34.0';