@mysten/pas 0.0.1

package/src/contracts/sui/dynamic_field.ts

@@ -0,0 +1,171 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+import { type BcsType, bcs } from '@mysten/sui/bcs';
+import { MoveStruct, normalizeMoveArguments, type RawTransactionArgument } from '../utils/index.js';
+import { type Transaction } from '@mysten/sui/transactions';
+const $moduleName = '0x2::dynamic_field';
+export function Field<T0 extends BcsType<any>, T1 extends BcsType<any>>(
+	...typeParameters: [T0, T1]
+) {
+	return new MoveStruct({
+		name: `${$moduleName}::Field<${typeParameters[0].name as T0['name']}, ${typeParameters[1].name as T1['name']}>`,
+		fields: {
+			id: bcs.Address,
+			name: typeParameters[0],
+			value: typeParameters[1],
+		},
+	});
+}
+export interface AddOptions<T0 extends BcsType<any>, T1 extends BcsType<any>> {
+	package?: string;
+	arguments: [
+		RawTransactionArgument<string>,
+		RawTransactionArgument<T0>,
+		RawTransactionArgument<T1>,
+	];
+	typeArguments: [string, string];
+}
+export function add<T0 extends BcsType<any>, T1 extends BcsType<any>>(options: AddOptions<T0, T1>) {
+	const packageAddress =
+		options.package ?? '0x0000000000000000000000000000000000000000000000000000000000000002';
+	const argumentsTypes = [
+		'0x2::object::ID',
+		`${options.typeArguments[0]}`,
+		`${options.typeArguments[1]}`,
+	] satisfies (string | null)[];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'dynamic_field',
+			function: 'add',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes),
+			typeArguments: options.typeArguments,
+		});
+}
+export interface BorrowOptions<T0 extends BcsType<any>> {
+	package?: string;
+	arguments: [RawTransactionArgument<string>, RawTransactionArgument<T0>];
+	typeArguments: [string, string];
+}
+export function borrow<T0 extends BcsType<any>>(options: BorrowOptions<T0>) {
+	const packageAddress =
+		options.package ?? '0x0000000000000000000000000000000000000000000000000000000000000002';
+	const argumentsTypes = ['0x2::object::ID', `${options.typeArguments[0]}`] satisfies (
+		| string
+		| null
+	)[];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'dynamic_field',
+			function: 'borrow',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes),
+			typeArguments: options.typeArguments,
+		});
+}
+export interface BorrowMutOptions<T0 extends BcsType<any>> {
+	package?: string;
+	arguments: [RawTransactionArgument<string>, RawTransactionArgument<T0>];
+	typeArguments: [string, string];
+}
+export function borrowMut<T0 extends BcsType<any>>(options: BorrowMutOptions<T0>) {
+	const packageAddress =
+		options.package ?? '0x0000000000000000000000000000000000000000000000000000000000000002';
+	const argumentsTypes = ['0x2::object::ID', `${options.typeArguments[0]}`] satisfies (
+		| string
+		| null
+	)[];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'dynamic_field',
+			function: 'borrow_mut',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes),
+			typeArguments: options.typeArguments,
+		});
+}
+export interface RemoveOptions<T0 extends BcsType<any>> {
+	package?: string;
+	arguments: [RawTransactionArgument<string>, RawTransactionArgument<T0>];
+	typeArguments: [string, string];
+}
+export function remove<T0 extends BcsType<any>>(options: RemoveOptions<T0>) {
+	const packageAddress =
+		options.package ?? '0x0000000000000000000000000000000000000000000000000000000000000002';
+	const argumentsTypes = ['0x2::object::ID', `${options.typeArguments[0]}`] satisfies (
+		| string
+		| null
+	)[];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'dynamic_field',
+			function: 'remove',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes),
+			typeArguments: options.typeArguments,
+		});
+}
+export interface Exists_Options<T0 extends BcsType<any>> {
+	package?: string;
+	arguments: [RawTransactionArgument<string>, RawTransactionArgument<T0>];
+	typeArguments: [string];
+}
+export function exists_<T0 extends BcsType<any>>(options: Exists_Options<T0>) {
+	const packageAddress =
+		options.package ?? '0x0000000000000000000000000000000000000000000000000000000000000002';
+	const argumentsTypes = ['0x2::object::ID', `${options.typeArguments[0]}`] satisfies (
+		| string
+		| null
+	)[];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'dynamic_field',
+			function: 'exists_',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes),
+			typeArguments: options.typeArguments,
+		});
+}
+export interface RemoveIfExistsOptions<T0 extends BcsType<any>> {
+	package?: string;
+	arguments: [RawTransactionArgument<string>, RawTransactionArgument<T0>];
+	typeArguments: [string, string];
+}
+export function removeIfExists<T0 extends BcsType<any>>(options: RemoveIfExistsOptions<T0>) {
+	const packageAddress =
+		options.package ?? '0x0000000000000000000000000000000000000000000000000000000000000002';
+	const argumentsTypes = ['0x2::object::ID', `${options.typeArguments[0]}`] satisfies (
+		| string
+		| null
+	)[];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'dynamic_field',
+			function: 'remove_if_exists',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes),
+			typeArguments: options.typeArguments,
+		});
+}
+export interface ExistsWithTypeOptions<T0 extends BcsType<any>> {
+	package?: string;
+	arguments: [RawTransactionArgument<string>, RawTransactionArgument<T0>];
+	typeArguments: [string, string];
+}
+export function existsWithType<T0 extends BcsType<any>>(options: ExistsWithTypeOptions<T0>) {
+	const packageAddress =
+		options.package ?? '0x0000000000000000000000000000000000000000000000000000000000000002';
+	const argumentsTypes = ['0x2::object::ID', `${options.typeArguments[0]}`] satisfies (
+		| string
+		| null
+	)[];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'dynamic_field',
+			function: 'exists_with_type',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes),
+			typeArguments: options.typeArguments,
+		});
+}

package/src/contracts/utils/index.ts

@@ -0,0 +1,235 @@
+import {
+	bcs,
+	BcsType,
+	TypeTag,
+	TypeTagSerializer,
+	BcsStruct,
+	BcsEnum,
+	BcsTuple,
+} from '@mysten/sui/bcs';
+import { normalizeSuiAddress } from '@mysten/sui/utils';
+import { TransactionArgument, isArgument } from '@mysten/sui/transactions';
+import { ClientWithCoreApi, SuiClientTypes } from '@mysten/sui/client';
+import { PASClientError } from '../../error.js';
+
+const MOVE_STDLIB_ADDRESS = normalizeSuiAddress('0x1');
+const SUI_FRAMEWORK_ADDRESS = normalizeSuiAddress('0x2');
+
+export type RawTransactionArgument<T> = T | TransactionArgument;
+
+export interface GetOptions<
+	Include extends Omit<SuiClientTypes.ObjectInclude, 'content'> = {},
+> extends SuiClientTypes.GetObjectOptions<Include> {
+	client: ClientWithCoreApi;
+}
+
+export interface GetManyOptions<
+	Include extends Omit<SuiClientTypes.ObjectInclude, 'content'> = {},
+> extends SuiClientTypes.GetObjectsOptions<Include> {
+	client: ClientWithCoreApi;
+}
+
+export function getPureBcsSchema(typeTag: string | TypeTag): BcsType<any> | null {
+	const parsedTag = typeof typeTag === 'string' ? TypeTagSerializer.parseFromStr(typeTag) : typeTag;
+
+	if ('u8' in parsedTag) {
+		return bcs.U8;
+	} else if ('u16' in parsedTag) {
+		return bcs.U16;
+	} else if ('u32' in parsedTag) {
+		return bcs.U32;
+	} else if ('u64' in parsedTag) {
+		return bcs.U64;
+	} else if ('u128' in parsedTag) {
+		return bcs.U128;
+	} else if ('u256' in parsedTag) {
+		return bcs.U256;
+	} else if ('address' in parsedTag) {
+		return bcs.Address;
+	} else if ('bool' in parsedTag) {
+		return bcs.Bool;
+	} else if ('vector' in parsedTag) {
+		const type = getPureBcsSchema(parsedTag.vector);
+		return type ? bcs.vector(type) : null;
+	} else if ('struct' in parsedTag) {
+		const structTag = parsedTag.struct;
+		const pkg = normalizeSuiAddress(structTag.address);
+
+		if (pkg === MOVE_STDLIB_ADDRESS) {
+			if (
+				(structTag.module === 'ascii' || structTag.module === 'string') &&
+				structTag.name === 'String'
+			) {
+				return bcs.String;
+			}
+
+			if (structTag.module === 'option' && structTag.name === 'Option') {
+				const type = getPureBcsSchema(structTag.typeParams[0]);
+				return type ? bcs.option(type) : null;
+			}
+		}
+
+		if (
+			pkg === SUI_FRAMEWORK_ADDRESS &&
+			structTag.module === 'object' &&
+			(structTag.name === 'ID' || structTag.name === 'UID')
+		) {
+			return bcs.Address;
+		}
+	}
+
+	return null;
+}
+
+export function normalizeMoveArguments(
+	args: unknown[] | object,
+	argTypes: readonly (string | null)[],
+	parameterNames?: string[],
+) {
+	const argLen = Array.isArray(args) ? args.length : Object.keys(args).length;
+	if (parameterNames && argLen !== parameterNames.length) {
+		throw new PASClientError(
+			`Invalid number of arguments, expected ${parameterNames.length}, got ${argLen}`,
+		);
+	}
+
+	const normalizedArgs: TransactionArgument[] = [];
+
+	let index = 0;
+	for (const [i, argType] of argTypes.entries()) {
+		if (argType === '0x2::clock::Clock') {
+			normalizedArgs.push((tx) => tx.object.clock());
+			continue;
+		}
+
+		if (argType === '0x2::random::Random') {
+			normalizedArgs.push((tx) => tx.object.random());
+			continue;
+		}
+
+		if (argType === '0x2::deny_list::DenyList') {
+			normalizedArgs.push((tx) => tx.object.denyList());
+			continue;
+		}
+
+		if (argType === '0x3::sui_system::SuiSystemState') {
+			normalizedArgs.push((tx) => tx.object.system());
+			continue;
+		}
+
+		let arg;
+		if (Array.isArray(args)) {
+			if (index >= args.length) {
+				throw new PASClientError(
+					`Invalid number of arguments, expected at least ${index + 1}, got ${args.length}`,
+				);
+			}
+			arg = args[index];
+		} else {
+			if (!parameterNames) {
+				throw new PASClientError(`Expected arguments to be passed as an array`);
+			}
+			const name = parameterNames[index];
+			arg = args[name as keyof typeof args];
+
+			if (arg === undefined) {
+				throw new PASClientError(`Parameter ${name} is required`);
+			}
+		}
+
+		index += 1;
+
+		if (typeof arg === 'function' || isArgument(arg)) {
+			normalizedArgs.push(arg as TransactionArgument);
+			continue;
+		}
+
+		const type = argTypes[i];
+		const bcsType = type === null ? null : getPureBcsSchema(type);
+
+		if (bcsType) {
+			const bytes = bcsType.serialize(arg as never);
+			normalizedArgs.push((tx) => tx.pure(bytes));
+			continue;
+		} else if (typeof arg === 'string') {
+			normalizedArgs.push((tx) => tx.object(arg));
+			continue;
+		}
+
+		throw new PASClientError(`Invalid argument ${stringify(arg)} for type ${type}`);
+	}
+
+	return normalizedArgs;
+}
+
+export class MoveStruct<
+	T extends Record<string, BcsType<any>>,
+	const Name extends string = string,
+> extends BcsStruct<T, Name> {
+	async get<Include extends Omit<SuiClientTypes.ObjectInclude, 'content' | 'json'> = {}>({
+		objectId,
+		...options
+	}: GetOptions<Include>): Promise<
+		SuiClientTypes.Object<Include & { content: true; json: true }> & {
+			json: BcsStruct<T>['$inferType'];
+		}
+	> {
+		const [res] = await this.getMany<Include>({
+			...options,
+			objectIds: [objectId],
+		});
+
+		return res;
+	}
+
+	async getMany<Include extends Omit<SuiClientTypes.ObjectInclude, 'content' | 'json'> = {}>({
+		client,
+		...options
+	}: GetManyOptions<Include>): Promise<
+		Array<
+			SuiClientTypes.Object<Include & { content: true; json: true }> & {
+				json: BcsStruct<T>['$inferType'];
+			}
+		>
+	> {
+		const response = (await client.core.getObjects({
+			...options,
+			include: {
+				...options.include,
+				content: true,
+			},
+		})) as SuiClientTypes.GetObjectsResponse<Include & { content: true }>;
+
+		return response.objects.map((obj) => {
+			if (obj instanceof Error) {
+				throw obj;
+			}
+
+			return {
+				...obj,
+				json: this.parse(obj.content),
+			};
+		});
+	}
+}
+
+export class MoveEnum<
+	T extends Record<string, BcsType<any> | null>,
+	const Name extends string,
+> extends BcsEnum<T, Name> {}
+
+export class MoveTuple<
+	const T extends readonly BcsType<any>[],
+	const Name extends string,
+> extends BcsTuple<T, Name> {}
+
+function stringify(val: unknown) {
+	if (typeof val === 'object') {
+		return JSON.stringify(val, (val: unknown) => val);
+	}
+	if (typeof val === 'bigint') {
+		return val.toString();
+	}
+
+	return val;
+}

package/src/derivation.ts

@@ -0,0 +1,107 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from '@mysten/sui/bcs';
+import { deriveDynamicFieldID, deriveObjectID, normalizeSuiAddress } from '@mysten/sui/utils';
+
+import type { PASPackageConfig } from './types.js';
+
+/**
+ * Derives the account address for a given owner address.
+ *
+ * Accounts are derived using the namespace UID and a AccountKey(owner).
+ * The key structure in Move is: `AccountKey(address)`
+ *
+ * @param owner - The owner address (can be a user address or object address)
+ * @param packageConfig - PAS package configuration
+ * @returns The derived account object ID
+ */
+export function deriveAccountAddress(owner: string, packageConfig: PASPackageConfig): string {
+	const { packageId, namespaceId } = packageConfig;
+
+	// Serialize the AccountKey(address) as the key
+	// AccountKey is a struct with a single field: address
+	const accountKeyBcs = bcs.struct('AccountKey', {
+		owner: bcs.Address,
+	});
+
+	const key = accountKeyBcs.serialize({ owner: normalizeSuiAddress(owner) }).toBytes();
+
+	// The type tag is the AccountKey type from the PAS package
+	const typeTag = `${packageId}::keys::AccountKey`;
+
+	return deriveObjectID(namespaceId, typeTag, key);
+}
+
+const DEFAULT_WRAP_TYPE = (t: string) => `0x2::balance::Balance<${t}>`;
+
+export interface DerivePolicyOptions {
+	/** Transform the asset type before using it in the PolicyKey type tag.
+	 *  Defaults to wrapping with `0x2::balance::Balance<T>`.
+	 *  Pass `(t) => t` to use the raw type. */
+	wrapType?: (assetType: string) => string;
+}
+
+/**
+ * Derives the policy address for a given asset type T.
+ *
+ * Policies are derived using the namespace UID and a PolicyKey<T>().
+ * The key structure in Move is: `PolicyKey<phantom T>()`
+ *
+ * By default the asset type is wrapped as `Balance<T>` to match the current
+ * on-chain convention. Pass `options.wrapType` to override.
+ *
+ * @param assetType - The full type of the asset (e.g., "0x2::sui::SUI")
+ * @param packageConfig - PAS package configuration
+ * @param options - Optional derivation options
+ * @returns The derived policy object ID
+ */
+export function derivePolicyAddress(
+	assetType: string,
+	packageConfig: PASPackageConfig,
+	options?: DerivePolicyOptions,
+): string {
+	const { packageId, namespaceId } = packageConfig;
+
+	const policyKeyBcs = new Uint8Array([0]);
+
+	const wrap = options?.wrapType ?? DEFAULT_WRAP_TYPE;
+	const typeTag = `${packageId}::keys::PolicyKey<${wrap(assetType)}>`;
+	return deriveObjectID(namespaceId, typeTag, policyKeyBcs);
+}
+
+/**
+ * Derives the templates object address for a given package configuration.
+ *
+ * Templates are derived using the namespace UID and a TemplateKey().
+ * The key structure in Move is: `TemplateKey()`
+ *
+ * @param packageConfig - PAS package configuration
+ * @returns The derived templates object ID
+ */
+export function deriveTemplateRegistryAddress(packageConfig: PASPackageConfig): string {
+	const { packageId, namespaceId } = packageConfig;
+
+	// The type tag is the TemplateKey type from the PAS package
+	const typeTag = `${packageId}::keys::TemplateKey`;
+
+	return deriveObjectID(namespaceId, typeTag, new Uint8Array([0]));
+}
+
+/**
+ * Derives the dynamic field address for a template command on the Templates object.
+ *
+ * Templates store Commands as dynamic fields keyed by `TypeName` (the approval type's
+ * `type_name::with_defining_ids` value). The DF key type is `std::type_name::TypeName`
+ * which is a struct with a single `name: String` field.
+ *
+ * @param templatesId - The Templates object ID
+ * @param approvalTypeName - The fully qualified approval type name (e.g., "0x123::demo_usd::TransferApproval")
+ * @returns The derived dynamic field object ID
+ */
+export function deriveTemplateAddress(templatesId: string, approvalTypeName: string): string {
+	// TypeName is a struct { name: String }, serialized as BCS string
+	const key = bcs.string().serialize(approvalTypeName).toBytes();
+
+	return deriveDynamicFieldID(templatesId, '0x1::type_name::TypeName', key);
+}

package/src/error.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Base error class for PAS client errors
+ */
+export class PASClientError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'PASClientError';
+	}
+}
+
+export class PolicyNotFoundError extends PASClientError {
+	constructor(assetType: string, message?: string) {
+		super(message ?? `Policy not found for asset type ${assetType}.`);
+		this.name = 'PolicyNotFoundError';
+	}
+}
+
+export class InvalidObjectOwnershipError extends PASClientError {
+	constructor(objectId: string, ownerKind: string) {
+		super(
+			`Object ${objectId} has ownership kind "${ownerKind}" which is not allowed in PAS templates. ` +
+				`Only shared and immutable objects can be referenced by templates.`,
+		);
+		this.name = 'InvalidObjectOwnershipError';
+	}
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export { PASClient, pas } from './client.js';
+export type { PASClientConfig, PASPackageConfig, PASOptions } from './types.js';
+export * from './error.js';