@haneullabs/haneul 0.1.0

package/src/experimental/mvr.ts

@@ -0,0 +1,488 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { chunk, DataLoader } from '@haneullabs/utils';
+import { isValidNamedPackage, isValidNamedType } from '../utils/move-registry.js';
+import type { StructTag } from '../utils/haneul-types.js';
+import {
+	isValidHaneulAddress,
+	normalizeStructTag,
+	normalizeHaneulAddress,
+	parseStructTag,
+} from '../utils/haneul-types.js';
+import type { ClientCache } from './cache.js';
+import type { TransactionDataBuilder } from '../transactions/TransactionData.js';
+import { PACKAGE_VERSION } from '../version.js';
+import type { Experimental_HaneulClientTypes } from './types.js';
+
+const NAME_SEPARATOR = '/';
+const MVR_API_HEADER = {
+	'Mvr-Source': `@haneullabs/haneul@${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_HaneulClientTypes.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_HaneulClientTypes.MvrResolvePackageOptions): Promise<Experimental_HaneulClientTypes.MvrResolvePackageResponse> {
+		if (!hasMvrName(name)) {
+			return {
+				package: name,
+			};
+		}
+		const resolved = await this.#mvrPackageDataLoader.load(name);
+		return {
+			package: resolved,
+		};
+	}
+
+	async resolveType({
+		type,
+	}: Experimental_HaneulClientTypes.MvrResolveTypeOptions): Promise<Experimental_HaneulClientTypes.MvrResolveTypeResponse> {
+		if (!hasMvrName(type)) {
+			return {
+				type,
+			};
+		}
+
+		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_HaneulClientTypes.MvrResolveOptions): Promise<Experimental_HaneulClientTypes.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 (!isValidHaneulAddress(normalizeHaneulAddress(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 (!isValidHaneulAddress(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('.haneul')
+	);
+}
+
+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_HaneulClientTypes.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/utils.ts

@@ -0,0 +1,117 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from '../../bcs/index.js';
+import { TransactionDataBuilder } from '../../transactions/TransactionData.js';
+import type { Experimental_HaneulClientTypes } from '../types.js';
+
+export function parseTransactionBcs(
+	bytes: Uint8Array,
+): Experimental_HaneulClientTypes.TransactionResponse['transaction'] {
+	return {
+		...TransactionDataBuilder.fromBytes(bytes).snapshot(),
+		bcs: bytes,
+	};
+}
+
+export function parseTransactionEffectsBcs(
+	effects: Uint8Array,
+): Experimental_HaneulClientTypes.TransactionEffects {
+	const parsed = bcs.TransactionEffects.parse(effects);
+
+	switch (parsed.$kind) {
+		case 'V1':
+			return parseTransactionEffectsV1({ bytes: effects, effects: parsed.V1 });
+		case 'V2':
+			return parseTransactionEffectsV2({ bytes: effects, effects: parsed.V2 });
+		default:
+			throw new Error(
+				`Unknown transaction effects version: ${(parsed as { $kind: string }).$kind}`,
+			);
+	}
+}
+
+function parseTransactionEffectsV1(_: {
+	bytes: Uint8Array;
+	effects: NonNullable<(typeof bcs.TransactionEffects.$inferType)['V1']>;
+}): Experimental_HaneulClientTypes.TransactionEffects {
+	throw new Error('V1 effects are not supported yet');
+}
+
+function parseTransactionEffectsV2({
+	bytes,
+	effects,
+}: {
+	bytes: Uint8Array;
+	effects: NonNullable<(typeof bcs.TransactionEffects.$inferType)['V2']>;
+}): Experimental_HaneulClientTypes.TransactionEffects {
+	const changedObjects = effects.changedObjects.map(
+		([id, change]): Experimental_HaneulClientTypes.ChangedObject => {
+			return {
+				id,
+				inputState: change.inputState.$kind === 'Exist' ? 'Exists' : 'DoesNotExist',
+				inputVersion: change.inputState.Exist?.[0][0] ?? null,
+				inputDigest: change.inputState.Exist?.[0][1] ?? null,
+				inputOwner: change.inputState.Exist?.[1] ?? null,
+				outputState:
+					change.outputState.$kind === 'NotExist' ? 'DoesNotExist' : change.outputState.$kind,
+				outputVersion:
+					change.outputState.$kind === 'PackageWrite'
+						? change.outputState.PackageWrite?.[0]
+						: change.outputState.ObjectWrite
+							? effects.lamportVersion
+							: null,
+				outputDigest:
+					change.outputState.$kind === 'PackageWrite'
+						? change.outputState.PackageWrite?.[1]
+						: (change.outputState.ObjectWrite?.[0] ?? null),
+				outputOwner: change.outputState.ObjectWrite ? change.outputState.ObjectWrite[1] : null,
+				idOperation: change.idOperation.$kind,
+			};
+		},
+	);
+
+	return {
+		bcs: bytes,
+		digest: effects.transactionDigest,
+		version: 2,
+		status:
+			effects.status.$kind === 'Success'
+				? {
+						success: true,
+						error: null,
+					}
+				: {
+						success: false,
+						// TODO: add command
+						error: effects.status.Failed.error.$kind,
+					},
+		gasUsed: effects.gasUsed,
+		transactionDigest: effects.transactionDigest,
+		gasObject:
+			effects.gasObjectIndex === null ? null : (changedObjects[effects.gasObjectIndex] ?? null),
+		eventsDigest: effects.eventsDigest,
+		dependencies: effects.dependencies,
+		lamportVersion: effects.lamportVersion,
+		changedObjects,
+		unchangedConsensusObjects: effects.unchangedSharedObjects.map(
+			([objectId, object]): Experimental_HaneulClientTypes.UnchangedConsensusObject => {
+				return {
+					kind:
+						object.$kind === 'MutateDeleted'
+							? 'MutateConsensusStreamEnded'
+							: object.$kind === 'ReadDeleted'
+								? 'ReadConsensusStreamEnded'
+								: object.$kind,
+					objectId: objectId,
+					version:
+						object.$kind === 'ReadOnlyRoot'
+							? object.ReadOnlyRoot[0]
+							: (object[object.$kind] as string | null),
+					digest: object.$kind === 'ReadOnlyRoot' ? object.ReadOnlyRoot[1] : null,
+				};
+			},
+		),
+		auxiliaryDataDigest: effects.auxDataDigest,
+	};
+}