@haneullabs/haneul 0.1.0

package/src/transactions/executor/serial.ts

@@ -0,0 +1,145 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { toBase64 } from '@haneullabs/bcs';
+
+import type { bcs } from '../../bcs/index.js';
+import type { HaneulClient, HaneulTransactionBlockResponseOptions } from '../../client/index.js';
+import type { Signer } from '../../cryptography/keypair.js';
+import type { ObjectCacheOptions } from '../ObjectCache.js';
+import { isTransaction, Transaction } from '../Transaction.js';
+import { CachingTransactionExecutor } from './caching.js';
+import { SerialQueue } from './queue.js';
+
+export class SerialTransactionExecutor {
+	#queue = new SerialQueue();
+	#signer: Signer;
+	#cache: CachingTransactionExecutor;
+	#defaultGasBudget: bigint;
+
+	constructor({
+		signer,
+		defaultGasBudget = 50_000_000n,
+		...options
+	}: Omit<ObjectCacheOptions, 'address'> & {
+		client: HaneulClient;
+		signer: Signer;
+		/** The gasBudget to use if the transaction has not defined it's own gasBudget, defaults to `50_000_000n` */
+		defaultGasBudget?: bigint;
+	}) {
+		this.#signer = signer;
+		this.#defaultGasBudget = defaultGasBudget;
+		this.#cache = new CachingTransactionExecutor({
+			client: options.client,
+			cache: options.cache,
+			onEffects: (effects) => this.#cacheGasCoin(effects),
+		});
+	}
+
+	async applyEffects(effects: typeof bcs.TransactionEffects.$inferType) {
+		return this.#cache.applyEffects(effects);
+	}
+
+	#cacheGasCoin = async (effects: typeof bcs.TransactionEffects.$inferType) => {
+		if (!effects.V2) {
+			return;
+		}
+
+		const gasCoin = getGasCoinFromEffects(effects).ref;
+		if (gasCoin) {
+			this.#cache.cache.setCustom('gasCoin', gasCoin);
+		} else {
+			this.#cache.cache.deleteCustom('gasCoin');
+		}
+	};
+
+	async buildTransaction(transaction: Transaction) {
+		return this.#queue.runTask(() => this.#buildTransaction(transaction));
+	}
+
+	#buildTransaction = async (transaction: Transaction) => {
+		const gasCoin = await this.#cache.cache.getCustom<{
+			objectId: string;
+			version: string;
+			digest: string;
+		}>('gasCoin');
+
+		const copy = Transaction.from(transaction);
+		if (gasCoin) {
+			copy.setGasPayment([gasCoin]);
+		}
+
+		copy.setGasBudgetIfNotSet(this.#defaultGasBudget);
+		copy.setSenderIfNotSet(this.#signer.toHaneulAddress());
+
+		return this.#cache.buildTransaction({ transaction: copy });
+	};
+
+	resetCache() {
+		return this.#cache.reset();
+	}
+
+	waitForLastTransaction() {
+		return this.#cache.waitForLastTransaction();
+	}
+
+	executeTransaction(
+		transaction: Transaction | Uint8Array,
+		options?: HaneulTransactionBlockResponseOptions,
+		additionalSignatures: string[] = [],
+	) {
+		return this.#queue.runTask(async () => {
+			const bytes = isTransaction(transaction)
+				? await this.#buildTransaction(transaction)
+				: transaction;
+
+			const { signature } = await this.#signer.signTransaction(bytes);
+			const results = await this.#cache
+				.executeTransaction({
+					signature: [signature, ...additionalSignatures],
+					transaction: bytes,
+					options,
+				})
+				.catch(async (error) => {
+					await this.resetCache();
+					throw error;
+				});
+
+			const effectsBytes = Uint8Array.from(results.rawEffects!);
+			return {
+				digest: results.digest,
+				effects: toBase64(effectsBytes),
+				data: results,
+			};
+		});
+	}
+}
+
+export function getGasCoinFromEffects(effects: typeof bcs.TransactionEffects.$inferType) {
+	if (!effects.V2) {
+		throw new Error('Unexpected effects version');
+	}
+
+	const gasObjectChange = effects.V2.changedObjects[effects.V2.gasObjectIndex!];
+
+	if (!gasObjectChange) {
+		throw new Error('Gas object not found in effects');
+	}
+
+	const [objectId, { outputState }] = gasObjectChange;
+
+	if (!outputState.ObjectWrite) {
+		throw new Error('Unexpected gas object state');
+	}
+
+	const [digest, owner] = outputState.ObjectWrite;
+
+	return {
+		ref: {
+			objectId,
+			digest,
+			version: effects.V2.lamportVersion,
+		},
+		owner: owner.AddressOwner || owner.ObjectOwner!,
+	};
+}

package/src/transactions/hash.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { blake2b } from '@noble/hashes/blake2b';
+
+/**
+ * Generates a Blake2b hash of typed data as a base64 string.
+ *
+ * @param typeTag type tag (e.g. TransactionData, SenderSignedData)
+ * @param data data to hash
+ */
+export function hashTypedData(typeTag: string, data: Uint8Array): Uint8Array {
+	const typeTagBytes = Array.from(`${typeTag}::`).map((e) => e.charCodeAt(0));
+
+	const dataWithTag = new Uint8Array(typeTagBytes.length + data.length);
+	dataWithTag.set(typeTagBytes);
+	dataWithTag.set(data, typeTagBytes.length);
+
+	return blake2b(dataWithTag, { dkLen: 32 });
+}

package/src/transactions/index.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { NamedPackagesOverrides } from '../experimental/mvr.js';
+
+export { normalizedTypeToMoveTypeSignature, getPureBcsSchema } from './serializer.js';
+
+export { Inputs } from './Inputs.js';
+export {
+	Commands,
+	type TransactionArgument,
+	type TransactionInput,
+	UpgradePolicy,
+} from './Commands.js';
+
+export {
+	Transaction,
+	isTransaction,
+	type TransactionObjectInput,
+	type TransactionObjectArgument,
+	type TransactionResult,
+} from './Transaction.js';
+
+export { type SerializedTransactionDataV2 } from './data/v2.js';
+export { type SerializedTransactionDataV1 } from './data/v1.js';
+
+export type {
+	TransactionData,
+	Argument,
+	ObjectRef,
+	GasData,
+	CallArg,
+	Command,
+	OpenMoveTypeSignature,
+	OpenMoveTypeSignatureBody,
+} from './data/internal.js';
+
+export { TransactionDataBuilder } from './TransactionData.js';
+export { ObjectCache, AsyncCache } from './ObjectCache.js';
+export { SerialTransactionExecutor } from './executor/serial.js';
+export { ParallelTransactionExecutor } from './executor/parallel.js';
+export type { ParallelTransactionExecutorOptions } from './executor/parallel.js';
+export { coinWithBalance } from './intents/CoinWithBalance.js';
+
+export type {
+	BuildTransactionOptions,
+	SerializeTransactionOptions,
+	TransactionPlugin,
+} from './resolve.js';
+
+export { Arguments } from './Arguments.js';
+
+export {
+	namedPackagesPlugin,
+	type NamedPackagesPluginOptions,
+} from './plugins/NamedPackagesPlugin.js';
+
+export type { NamedPackagesOverrides };
+/** @deprecated Use NamedPackagesOverrides instead */
+export type NamedPackagesPluginCache = NamedPackagesOverrides;
+
+export { isArgument } from './utils.js';

package/src/transactions/intents/CoinWithBalance.ts

@@ -0,0 +1,230 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { InferInput } from 'valibot';
+import { bigint, object, parse, string } from 'valibot';
+
+import { bcs } from '../../bcs/index.js';
+import type { CoinStruct, HaneulClient } from '../../client/index.js';
+import { normalizeStructTag } from '../../utils/haneul-types.js';
+import { Commands } from '../Commands.js';
+import type { Argument } from '../data/internal.js';
+import { Inputs } from '../Inputs.js';
+import { getClient } from '../resolve.js';
+import type { BuildTransactionOptions } from '../resolve.js';
+import type { Transaction, TransactionResult } from '../Transaction.js';
+import type { TransactionDataBuilder } from '../TransactionData.js';
+
+const COIN_WITH_BALANCE = 'CoinWithBalance';
+const SUI_TYPE = normalizeStructTag('0x2::haneul::HANEUL');
+
+export function coinWithBalance({
+	type = SUI_TYPE,
+	balance,
+	useGasCoin = true,
+}: {
+	balance: bigint | number;
+	type?: string;
+	useGasCoin?: boolean;
+}): (tx: Transaction) => TransactionResult {
+	let coinResult: TransactionResult | null = null;
+
+	return (tx: Transaction) => {
+		if (coinResult) {
+			return coinResult;
+		}
+
+		tx.addIntentResolver(COIN_WITH_BALANCE, resolveCoinBalance);
+		const coinType = type === 'gas' ? type : normalizeStructTag(type);
+
+		coinResult = tx.add(
+			Commands.Intent({
+				name: COIN_WITH_BALANCE,
+				inputs: {},
+				data: {
+					type: coinType === SUI_TYPE && useGasCoin ? 'gas' : coinType,
+					balance: BigInt(balance),
+				} satisfies InferInput<typeof CoinWithBalanceData>,
+			}),
+		);
+
+		return coinResult;
+	};
+}
+
+const CoinWithBalanceData = object({
+	type: string(),
+	balance: bigint(),
+});
+
+async function resolveCoinBalance(
+	transactionData: TransactionDataBuilder,
+	buildOptions: BuildTransactionOptions,
+	next: () => Promise<void>,
+) {
+	const coinTypes = new Set<string>();
+	const totalByType = new Map<string, bigint>();
+
+	if (!transactionData.sender) {
+		throw new Error('Sender must be set to resolve CoinWithBalance');
+	}
+
+	for (const command of transactionData.commands) {
+		if (command.$kind === '$Intent' && command.$Intent.name === COIN_WITH_BALANCE) {
+			const { type, balance } = parse(CoinWithBalanceData, command.$Intent.data);
+
+			if (type !== 'gas' && balance > 0n) {
+				coinTypes.add(type);
+			}
+
+			totalByType.set(type, (totalByType.get(type) ?? 0n) + balance);
+		}
+	}
+	const usedIds = new Set<string>();
+
+	for (const input of transactionData.inputs) {
+		if (input.Object?.ImmOrOwnedObject) {
+			usedIds.add(input.Object.ImmOrOwnedObject.objectId);
+		}
+		if (input.UnresolvedObject?.objectId) {
+			usedIds.add(input.UnresolvedObject.objectId);
+		}
+	}
+
+	const coinsByType = new Map<string, CoinStruct[]>();
+	const client = getHaneulClient(buildOptions);
+	await Promise.all(
+		[...coinTypes].map(async (coinType) => {
+			coinsByType.set(
+				coinType,
+				await getCoinsOfType({
+					coinType,
+					balance: totalByType.get(coinType)!,
+					client,
+					owner: transactionData.sender!,
+					usedIds,
+				}),
+			);
+		}),
+	);
+
+	const mergedCoins = new Map<string, Argument>();
+
+	mergedCoins.set('gas', { $kind: 'GasCoin', GasCoin: true });
+
+	for (const [index, transaction] of transactionData.commands.entries()) {
+		if (transaction.$kind !== '$Intent' || transaction.$Intent.name !== COIN_WITH_BALANCE) {
+			continue;
+		}
+
+		const { type, balance } = transaction.$Intent.data as {
+			type: string;
+			balance: bigint;
+		};
+
+		if (balance === 0n && type !== 'gas') {
+			transactionData.replaceCommand(
+				index,
+				Commands.MoveCall({ target: '0x2::coin::zero', typeArguments: [type] }),
+			);
+			continue;
+		}
+
+		const commands = [];
+
+		if (!mergedCoins.has(type)) {
+			const [first, ...rest] = coinsByType.get(type)!.map((coin) =>
+				transactionData.addInput(
+					'object',
+					Inputs.ObjectRef({
+						objectId: coin.coinObjectId,
+						digest: coin.digest,
+						version: coin.version,
+					}),
+				),
+			);
+
+			if (rest.length > 0) {
+				commands.push(Commands.MergeCoins(first, rest));
+			}
+
+			mergedCoins.set(type, first);
+		}
+
+		commands.push(
+			Commands.SplitCoins(mergedCoins.get(type)!, [
+				transactionData.addInput('pure', Inputs.Pure(bcs.u64().serialize(balance))),
+			]),
+		);
+
+		transactionData.replaceCommand(index, commands);
+
+		transactionData.mapArguments((arg) => {
+			if (arg.$kind === 'Result' && arg.Result === index) {
+				return {
+					$kind: 'NestedResult',
+					NestedResult: [index + commands.length - 1, 0],
+				};
+			}
+
+			return arg;
+		});
+	}
+
+	return next();
+}
+
+async function getCoinsOfType({
+	coinType,
+	balance,
+	client,
+	owner,
+	usedIds,
+}: {
+	coinType: string;
+	balance: bigint;
+	client: HaneulClient;
+	owner: string;
+	usedIds: Set<string>;
+}): Promise<CoinStruct[]> {
+	let remainingBalance = balance;
+	const coins: CoinStruct[] = [];
+
+	return loadMoreCoins();
+
+	async function loadMoreCoins(cursor: string | null = null): Promise<CoinStruct[]> {
+		const { data, hasNextPage, nextCursor } = await client.getCoins({ owner, coinType, cursor });
+
+		const sortedCoins = data.sort((a, b) => Number(BigInt(b.balance) - BigInt(a.balance)));
+
+		for (const coin of sortedCoins) {
+			if (usedIds.has(coin.coinObjectId)) {
+				continue;
+			}
+
+			const coinBalance = BigInt(coin.balance);
+
+			coins.push(coin);
+			remainingBalance -= coinBalance;
+
+			if (remainingBalance <= 0) {
+				return coins;
+			}
+		}
+
+		if (hasNextPage) {
+			return loadMoreCoins(nextCursor);
+		}
+
+		throw new Error(`Not enough coins of type ${coinType} to satisfy requested balance`);
+	}
+}
+
+export function getHaneulClient(options: BuildTransactionOptions): HaneulClient {
+	const client = getClient(options) as HaneulClient;
+	if (!client.jsonRpc) {
+		throw new Error(`CoinWithBalance intent currently only works with HaneulClient`);
+	}
+
+	return client;
+}

package/src/transactions/object.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Transaction, TransactionObjectInput } from './Transaction.js';
+import { Inputs } from './Inputs.js';
+
+export function createObjectMethods<T>(makeObject: (value: TransactionObjectInput) => T) {
+	function object(value: TransactionObjectInput) {
+		return makeObject(value);
+	}
+
+	object.system = (options?: { mutable?: boolean }) => {
+		const mutable = options?.mutable;
+
+		if (mutable !== undefined) {
+			return object(
+				Inputs.SharedObjectRef({
+					objectId: '0x5',
+					initialSharedVersion: 1,
+					mutable,
+				}),
+			);
+		}
+
+		return object({
+			$kind: 'UnresolvedObject',
+			UnresolvedObject: {
+				objectId: '0x5',
+				initialSharedVersion: 1,
+			},
+		});
+	};
+	object.clock = () =>
+		object(
+			Inputs.SharedObjectRef({
+				objectId: '0x6',
+				initialSharedVersion: 1,
+				mutable: false,
+			}),
+		);
+	object.random = () =>
+		object({
+			$kind: 'UnresolvedObject',
+			UnresolvedObject: {
+				objectId: '0x8',
+				mutable: false,
+			},
+		});
+	object.denyList = (options?: { mutable?: boolean }) => {
+		return object({
+			$kind: 'UnresolvedObject',
+			UnresolvedObject: {
+				objectId: '0x403',
+				mutable: options?.mutable,
+			},
+		});
+	};
+	object.option =
+		({ type, value }: { type: string; value: TransactionObjectInput | null }) =>
+		(tx: Transaction) =>
+			tx.moveCall({
+				typeArguments: [type],
+				target: `0x1::option::${value === null ? 'none' : 'some'}`,
+				arguments: value === null ? [] : [tx.object(value)],
+			});
+
+	return object;
+}

package/src/transactions/plugins/NamedPackagesPlugin.ts

@@ -0,0 +1,111 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ClientCache } from '../../experimental/cache.js';
+import { MvrClient } from '../../experimental/mvr.js';
+import type { BuildTransactionOptions } from '../resolve.js';
+import type { TransactionDataBuilder } from '../TransactionData.js';
+import { findNamesInTransaction, replaceNames } from '../../experimental/mvr.js';
+import type { NamedPackagesOverrides } from '../../experimental/mvr.js';
+
+export type NamedPackagesPluginOptions = {
+	/**
+	 * The URL of the MVR API to use for resolving names.
+	 */
+	url: string;
+	/**
+	 * 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).
+	 *
+	 * The type cache expects ONLY first-level types to ensure the cache is more composable.
+	 *
+	 * 	Expected format example:
+	 *  {
+	 * 		packages: {
+	 * 			'@framework/std': '0x1234',
+	 * 		},
+	 * 		types: {
+	 * 			'@framework/std::string::String': '0x1234::string::String',
+	 * 		},
+	 * 	}
+	 *
+	 */
+	overrides?: NamedPackagesOverrides;
+};
+
+// The original versions of the mvr plugin cached lookups by mutating overrides.
+// We don't want to mutate the options, but we can link our cache to the provided overrides object
+// This preserves the caching across transactions while removing the mutation side effects
+const cacheMap = new WeakMap<object, ClientCache>();
+
+/**
+ * @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. `@org/app::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 = (options?: NamedPackagesPluginOptions) => {
+	let mvrClient: MvrClient | undefined;
+
+	if (options) {
+		const overrides = options.overrides ?? {
+			packages: {},
+			types: {},
+		};
+
+		if (!cacheMap.has(overrides)) {
+			cacheMap.set(overrides, new ClientCache());
+		}
+
+		mvrClient = new MvrClient({
+			cache: cacheMap.get(overrides)!,
+			url: options.url,
+			pageSize: options.pageSize,
+			overrides: overrides,
+		});
+	}
+
+	return async (
+		transactionData: TransactionDataBuilder,
+		buildOptions: BuildTransactionOptions,
+		next: () => Promise<void>,
+	) => {
+		const names = findNamesInTransaction(transactionData);
+
+		if (names.types.length === 0 && names.packages.length === 0) {
+			return next();
+		}
+
+		const resolved = await (mvrClient || getClient(buildOptions).core.mvr).resolve({
+			types: names.types,
+			packages: names.packages,
+		});
+
+		replaceNames(transactionData, resolved);
+
+		await next();
+	};
+};
+
+export function getClient(options: BuildTransactionOptions) {
+	if (!options.client) {
+		throw new Error(
+			`No sui client passed to Transaction#build, but transaction data was not sufficient to build offline.`,
+		);
+	}
+
+	return options.client;
+}

package/src/transactions/pure.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isSerializedBcs } from '@haneullabs/bcs';
+import type { SerializedBcs } from '@haneullabs/bcs';
+
+import { bcs } from '../bcs/index.js';
+import { pureBcsSchemaFromTypeName } from '../bcs/pure.js';
+import type { PureTypeName, ShapeFromPureTypeName, ValidPureTypeName } from '../bcs/pure.js';
+
+export function createPure<T>(makePure: (value: SerializedBcs<any, any> | Uint8Array) => T) {
+	function pure<Type extends PureTypeName>(
+		type: Type extends PureTypeName ? ValidPureTypeName<Type> : Type,
+		value: ShapeFromPureTypeName<Type>,
+	): T;
+
+	function pure(
+		/**
+		 * The pure value, serialized to BCS. If this is a Uint8Array, then the value
+		 * is assumed to be raw bytes, and will be used directly.
+		 */
+		value: SerializedBcs<any, any> | Uint8Array,
+	): T;
+
+	function pure(
+		typeOrSerializedValue?: PureTypeName | SerializedBcs<any, any> | Uint8Array,
+		value?: unknown,
+	): T {
+		if (typeof typeOrSerializedValue === 'string') {
+			return makePure(pureBcsSchemaFromTypeName(typeOrSerializedValue).serialize(value as never));
+		}
+
+		if (typeOrSerializedValue instanceof Uint8Array || isSerializedBcs(typeOrSerializedValue)) {
+			return makePure(typeOrSerializedValue);
+		}
+
+		throw new Error('tx.pure must be called either a bcs type name, or a serialized bcs value');
+	}
+
+	pure.u8 = (value: number) => makePure(bcs.U8.serialize(value));
+	pure.u16 = (value: number) => makePure(bcs.U16.serialize(value));
+	pure.u32 = (value: number) => makePure(bcs.U32.serialize(value));
+	pure.u64 = (value: bigint | number | string) => makePure(bcs.U64.serialize(value));
+	pure.u128 = (value: bigint | number | string) => makePure(bcs.U128.serialize(value));
+	pure.u256 = (value: bigint | number | string) => makePure(bcs.U256.serialize(value));
+	pure.bool = (value: boolean) => makePure(bcs.Bool.serialize(value));
+	pure.string = (value: string) => makePure(bcs.String.serialize(value));
+	pure.address = (value: string) => makePure(bcs.Address.serialize(value));
+	pure.id = pure.address;
+	pure.vector = <Type extends PureTypeName>(
+		type: Type extends PureTypeName ? ValidPureTypeName<Type> : Type,
+		value: Iterable<ShapeFromPureTypeName<Type>> & { length: number },
+	) => {
+		return makePure(
+			bcs.vector(pureBcsSchemaFromTypeName(type as PureTypeName)).serialize(value as never),
+		);
+	};
+	pure.option = <Type extends PureTypeName>(
+		type: Type extends PureTypeName ? ValidPureTypeName<Type> : Type,
+		value: ShapeFromPureTypeName<Type> | null | undefined,
+	) => {
+		return makePure(bcs.option(pureBcsSchemaFromTypeName(type)).serialize(value as never));
+	};
+
+	return pure;
+}