@haneullabs/haneul 0.1.0 → 2.5.0

package/src/transactions/Transaction.ts

@@ -9,7 +9,7 @@ import { is, parse } from 'valibot';
 import type { SignatureWithBytes, Signer } from '../cryptography/index.js';
 import { normalizeHaneulAddress } from '../utils/haneul-types.js';
 import type { TransactionArgument } from './Commands.js';
-import { Commands } from './Commands.js';
+import { TransactionCommands } from './Commands.js';
 import type { CallArg, Command, Argument, ObjectRef } from './data/internal.js';
 import {
 	ArgumentSchema,
@@ -31,7 +31,8 @@ import { createPure } from './pure.js';
 import { TransactionDataBuilder } from './TransactionData.js';
 import { getIdFromCallArg } from './utils.js';
 import { namedPackagesPlugin } from './plugins/NamedPackagesPlugin.js';
-import type { ClientWithCoreApi } from '../experimental/core.js';
+import { COIN_WITH_BALANCE, resolveCoinBalance } from './intents/CoinWithBalance.js';
+import type { ClientWithCoreApi } from '../client/core.js';
 
 export type TransactionObjectArgument =
 	| Exclude<InferInput<typeof ArgumentSchema>, { Input: unknown; type?: 'pure' }>
@@ -126,35 +127,6 @@ export function isTransaction(obj: unknown): obj is TransactionLike {
 
 export type TransactionObjectInput = string | CallArg | TransactionObjectArgument;
 
-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('@haneullabs/transaction/registry');
-function getGlobalPluginRegistry() {
-	try {
-		const target = globalThis as {
-			[TRANSACTION_REGISTRY_KEY]?: TransactionPluginRegistry;
-		};
-
-		if (!target[TRANSACTION_REGISTRY_KEY]) {
-			target[TRANSACTION_REGISTRY_KEY] = modulePluginRegistry;
-		}
-
-		return target[TRANSACTION_REGISTRY_KEY];
-	} catch {
-		return modulePluginRegistry;
-	}
-}
-
 type InputSection = (CallArg | InputSection)[];
 type CommandSection = (Command | CommandSection)[];
 
@@ -218,41 +190,17 @@ export class Transaction {
 		newTransaction.#commandSection = newTransaction.#data.commands.slice();
 		newTransaction.#availableResults = new Set(newTransaction.#commandSection.map((_, i) => i));
 
-		return newTransaction;
-	}
-
-	/** @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);
-	}
+		if (!newTransaction.isPreparedForSerialization({ supportedIntents: [COIN_WITH_BALANCE] })) {
+			throw new Error(
+				'Transaction has unresolved intents or async thunks. Call `prepareForSerialization` before copying.',
+			);
+		}
 
-	/** @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),
-		);
-	}
+		if (newTransaction.#data.commands.some((cmd) => cmd.$Intent?.name === COIN_WITH_BALANCE)) {
+			newTransaction.addIntentResolver(COIN_WITH_BALANCE, resolveCoinBalance);
+		}
 
-	static unregisterGlobalBuildPlugin(name: string) {
-		getGlobalPluginRegistry().buildPlugins.delete(name);
+		return newTransaction;
 	}
 
 	addSerializationPlugin(step: TransactionPlugin) {
@@ -286,33 +234,28 @@ export class Transaction {
 	setExpiration(expiration?: InferInput<typeof TransactionExpiration> | null) {
 		this.#data.expiration = expiration ? parse(TransactionExpiration, expiration) : null;
 	}
-	setGasPrice(price: number | bigint) {
-		this.#data.gasConfig.price = String(price);
+	setGasPrice(price: number | bigint | string) {
+		this.#data.gasData.price = String(price);
 	}
-	setGasBudget(budget: number | bigint) {
-		this.#data.gasConfig.budget = String(budget);
+	setGasBudget(budget: number | bigint | string) {
+		this.#data.gasData.budget = String(budget);
 	}
 
-	setGasBudgetIfNotSet(budget: number | bigint) {
+	setGasBudgetIfNotSet(budget: number | bigint | string) {
 		if (this.#data.gasData.budget == null) {
-			this.#data.gasConfig.budget = String(budget);
+			this.#data.gasData.budget = String(budget);
 		}
 	}
 
 	setGasOwner(owner: string) {
-		this.#data.gasConfig.owner = owner;
+		this.#data.gasData.owner = owner;
 	}
 	setGasPayment(payments: ObjectRef[]) {
-		this.#data.gasConfig.payment = payments.map((payment) => parse(ObjectRefSchema, payment));
+		this.#data.gasData.payment = payments.map((payment) => parse(ObjectRefSchema, payment));
 	}
 
 	#data: TransactionDataBuilder;
 
-	/** @deprecated Use `getData()` instead. */
-	get blockData() {
-		return serializeV1TransactionData(this.#data.snapshot());
-	}
-
 	/** Get a snapshot of the transaction data, in JSON form: */
 	getData() {
 		return this.#data.snapshot();
@@ -354,10 +297,9 @@ export class Transaction {
 	}
 
 	constructor() {
-		const globalPlugins = getGlobalPluginRegistry();
 		this.#data = new TransactionDataBuilder();
-		this.#buildPlugins = [...globalPlugins.buildPlugins.values()];
-		this.#serializationPlugins = [...globalPlugins.serializationPlugins.values()];
+		this.#buildPlugins = [];
+		this.#serializationPlugins = [];
 	}
 
 	/** Returns an argument for the gas coin, to be used in a transaction. */
@@ -562,7 +504,7 @@ export class Transaction {
 	splitCoins<
 		const Amounts extends (TransactionArgument | SerializedBcs<any> | number | string | bigint)[],
 	>(coin: TransactionObjectArgument | string, amounts: Amounts) {
-		const command = Commands.SplitCoins(
+		const command = TransactionCommands.SplitCoins(
 			typeof coin === 'string' ? this.object(coin) : this.#resolveArgument(coin),
 			amounts.map((amount) =>
 				typeof amount === 'number' || typeof amount === 'bigint' || typeof amount === 'string'
@@ -583,7 +525,7 @@ export class Transaction {
 		sources: (TransactionObjectArgument | string)[],
 	) {
 		return this.add(
-			Commands.MergeCoins(
+			TransactionCommands.MergeCoins(
 				this.object(destination),
 				sources.map((src) => this.object(src)),
 			),
@@ -591,7 +533,7 @@ export class Transaction {
 	}
 	publish({ modules, dependencies }: { modules: number[][] | string[]; dependencies: string[] }) {
 		return this.add(
-			Commands.Publish({
+			TransactionCommands.Publish({
 				modules,
 				dependencies,
 			}),
@@ -609,7 +551,7 @@ export class Transaction {
 		ticket: TransactionObjectArgument | string;
 	}) {
 		return this.add(
-			Commands.Upgrade({
+			TransactionCommands.Upgrade({
 				modules,
 				dependencies,
 				package: packageId,
@@ -634,10 +576,10 @@ export class Transaction {
 				typeArguments?: string[];
 		  }) {
 		return this.add(
-			Commands.MoveCall({
+			TransactionCommands.MoveCall({
 				...input,
 				arguments: args?.map((arg) => this.#normalizeTransactionArgument(arg)),
-			} as Parameters<typeof Commands.MoveCall>[0]),
+			} as Parameters<typeof TransactionCommands.MoveCall>[0]),
 		);
 	}
 	transferObjects(
@@ -645,7 +587,7 @@ export class Transaction {
 		address: TransactionArgument | SerializedBcs<any> | string,
 	) {
 		return this.add(
-			Commands.TransferObjects(
+			TransactionCommands.TransferObjects(
 				objects.map((obj) => this.object(obj)),
 				typeof address === 'string'
 					? this.pure.address(address)
@@ -661,13 +603,42 @@ export class Transaction {
 		type?: string;
 	}) {
 		return this.add(
-			Commands.MakeMoveVec({
+			TransactionCommands.MakeMoveVec({
 				type,
 				elements: elements.map((obj) => this.object(obj)),
 			}),
 		);
 	}
 
+	/**
+	 * Create a FundsWithdrawal input for withdrawing Balance<T> from an address balance accumulator.
+	 * This is used for gas payments from address balances.
+	 *
+	 * @param options.amount - The Amount to withdraw (u64).
+	 * @param options.type - The balance type (e.g., "0x2::haneul::HANEUL"). Defaults to HANEUL.
+	 */
+	withdrawal({ amount, type }: { amount: number | bigint | string; type?: string | null }): {
+		$kind: 'Input';
+		Input: number;
+		type?: 'object';
+	} {
+		const input: CallArg = {
+			$kind: 'FundsWithdrawal',
+			FundsWithdrawal: {
+				// TODO: support entire balance withdrawals once supported
+				reservation: { $kind: 'MaxAmountU64', MaxAmountU64: String(amount) },
+				typeArg: { $kind: 'Balance', Balance: type ?? '0x2::haneul::HANEUL' },
+				withdrawFrom:
+					// fromSponsor === true
+					// 	? { $kind: 'Sponsor', Sponsor: true } :
+					// TODO: currently only supporting withdrawals from sender
+					{ $kind: 'Sender', Sender: true },
+			},
+		};
+
+		return this.#addInput('object', input);
+	}
+
 	/**
 	 * @deprecated Use toJSON instead.
 	 * For synchronous serialization, you can use `getData()`
@@ -701,6 +672,31 @@ export class Transaction {
 		return signer.signTransaction(bytes);
 	}
 
+	/**
+	 * Checks if the transaction is prepared for serialization to JSON.
+	 * This means:
+	 *  - All async thunks have been fully resolved
+	 *  - All transaction intents have been resolved (unless in supportedIntents)
+	 *
+	 * Unlike `isFullyResolved()`, this does not require the sender, gas payment,
+	 * budget, or object versions to be set.
+	 */
+	isPreparedForSerialization(options: { supportedIntents?: string[] } = {}) {
+		if (this.#pendingPromises.size > 0) {
+			return false;
+		}
+
+		if (
+			this.#data.commands.some(
+				(cmd) => cmd.$Intent && !options.supportedIntents?.includes(cmd.$Intent.name),
+			)
+		) {
+			return false;
+		}
+
+		return true;
+	}
+
 	/**
 	 *  Ensures that:
 	 *  - All objects have been fully resolved to a specific version
@@ -713,15 +709,11 @@ export class Transaction {
 	 *  When true, the transaction will always be built to the same bytes and digest (unless the transaction is mutated)
 	 */
 	isFullyResolved() {
-		if (!this.#data.sender) {
+		if (!this.isPreparedForSerialization()) {
 			return false;
 		}
 
-		if (this.#pendingPromises.size > 0) {
-			return false;
-		}
-
-		if (this.#data.commands.some((cmd) => cmd.$Intent)) {
+		if (!this.#data.sender) {
 			return false;
 		}
 

package/src/transactions/TransactionData.ts

@@ -22,7 +22,7 @@ import type { SerializedTransactionDataV2Schema } from './data/v2.js';
 import { hashTypedData } from './hash.js';
 import { getIdFromCallArg, remapCommandArguments } from './utils.js';
 import type { TransactionResult } from './Transaction.js';
-function prepareHaneulAddress(address: string) {
+function prepareSuiAddress(address: string) {
 	return normalizeHaneulAddress(address).replace('0x', '');
 }
 
@@ -92,15 +92,6 @@ export class TransactionDataBuilder implements TransactionData {
 		return toBase58(hash);
 	}
 
-	// @deprecated use gasData instead
-	get gasConfig() {
-		return this.gasData;
-	}
-	// @deprecated use gasData instead
-	set gasConfig(value) {
-		this.gasData = value;
-	}
-
 	version = 2 as const;
 	sender: string | null;
 	expiration: TransactionExpiration | null;
@@ -130,8 +121,6 @@ export class TransactionDataBuilder implements TransactionData {
 		overrides?: {
 			expiration?: TransactionExpiration;
 			sender?: string;
-			// @deprecated use gasData instead
-			gasConfig?: Partial<GasData>;
 			gasData?: Partial<GasData>;
 		};
 		onlyTransactionKind?: boolean;
@@ -156,7 +145,7 @@ export class TransactionDataBuilder implements TransactionData {
 
 		const expiration = overrides?.expiration ?? this.expiration;
 		const sender = overrides?.sender ?? this.sender;
-		const gasData = { ...this.gasData, ...overrides?.gasConfig, ...overrides?.gasData };
+		const gasData = { ...this.gasData, ...overrides?.gasData };
 
 		if (!sender) {
 			throw new Error('Missing transaction sender');
@@ -175,11 +164,11 @@ export class TransactionDataBuilder implements TransactionData {
 		}
 
 		const transactionData = {
-			sender: prepareHaneulAddress(sender),
+			sender: prepareSuiAddress(sender),
 			expiration: expiration ? expiration : { None: true },
 			gasData: {
 				payment: gasData.payment,
-				owner: prepareHaneulAddress(this.gasData.owner ?? sender),
+				owner: prepareSuiAddress(this.gasData.owner ?? sender),
 				price: BigInt(gasData.price),
 				budget: BigInt(gasData.budget),
 			},
@@ -197,7 +186,7 @@ export class TransactionDataBuilder implements TransactionData {
 		).toBytes();
 	}
 
-	addInput<T extends 'object' | 'pure'>(type: T, arg: CallArg) {
+	addInput<T extends 'object' | 'pure' | 'withdrawal'>(type: T, arg: CallArg) {
 		const index = this.inputs.length;
 		this.inputs.push(arg);
 		return { Input: index, type, $kind: 'Input' as const };

package/src/transactions/__tests__/Transaction.test.ts

@@ -5,7 +5,7 @@ import { toBase58 } from '@haneullabs/bcs';
 import { describe, expect, it } from 'vitest';
 
 import { bcs } from '../../bcs/index.js';
-import { Commands, Transaction } from '../index.js';
+import { TransactionCommands, Transaction } from '../index.js';
 import { Inputs } from '../Inputs.js';
 
 it('can construct and serialize an empty tranaction', () => {
@@ -32,7 +32,7 @@ it('receiving transaction argument different from object argument', () => {
 
 it('can be serialized and deserialized to the same values', () => {
 	const tx = new Transaction();
-	tx.add(Commands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
+	tx.add(TransactionCommands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
 	const serialized = tx.serialize();
 	const tx2 = Transaction.from(serialized);
 	expect(serialized).toEqual(tx2.serialize());
@@ -40,14 +40,14 @@ it('can be serialized and deserialized to the same values', () => {
 
 it('allows transfer with the result of split Commands', () => {
 	const tx = new Transaction();
-	const coin = tx.add(Commands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
-	tx.add(Commands.TransferObjects([coin], tx.object('0x2')));
+	const coin = tx.add(TransactionCommands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
+	tx.add(TransactionCommands.TransferObjects([coin], tx.object('0x2')));
 });
 
 it('supports nested results through either array index or destructuring', () => {
 	const tx = new Transaction();
 	const registerResult = tx.add(
-		Commands.MoveCall({
+		TransactionCommands.MoveCall({
 			target: '0x2::game::register',
 		}),
 	);
@@ -73,7 +73,7 @@ describe('offline build', () => {
 
 	it('builds a split transaction', async () => {
 		const tx = setup();
-		tx.add(Commands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
+		tx.add(TransactionCommands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
 		await tx.build();
 	});
 
@@ -84,13 +84,13 @@ describe('offline build', () => {
 		tx.setGasBudget(999);
 
 		// Ensure that setting budget after a clone does not affect the original:
-		expect(tx2.blockData).not.toEqual(tx.blockData);
+		expect(tx2.getData()).not.toEqual(tx.getData());
 
-		// Ensure `blockData` always breaks reference equality:
-		expect(tx.blockData).not.toBe(tx.blockData);
-		expect(tx.blockData.gasConfig).not.toBe(tx.blockData.gasConfig);
-		expect(tx.blockData.transactions).not.toBe(tx.blockData.transactions);
-		expect(tx.blockData.inputs).not.toBe(tx.blockData.inputs);
+		// Ensure `getData()` always breaks reference equality:
+		expect(tx.getData()).not.toBe(tx.getData());
+		expect(tx.getData().gasData).not.toBe(tx.getData().gasData);
+		expect(tx.getData().commands).not.toBe(tx.getData().commands);
+		expect(tx.getData().inputs).not.toBe(tx.getData().inputs);
 	});
 
 	it('can determine the type of inputs for built-in Commands', async () => {
@@ -103,16 +103,16 @@ describe('offline build', () => {
 		const tx = setup();
 		const inputBytes = bcs.U64.serialize(100n).toBytes();
 		// Use bytes directly in pure value:
-		tx.add(Commands.SplitCoins(tx.gas, [tx.pure(inputBytes)]));
+		tx.add(TransactionCommands.SplitCoins(tx.gas, [tx.pure(inputBytes)]));
 		await tx.build();
 	});
 
 	it('builds a more complex interaction', async () => {
 		const tx = setup();
 		const coin = tx.splitCoins(tx.gas, [100]);
-		tx.add(Commands.MergeCoins(tx.gas, [coin, tx.object(Inputs.ObjectRef(ref()))]));
+		tx.add(TransactionCommands.MergeCoins(tx.gas, [coin, tx.object(Inputs.ObjectRef(ref()))]));
 		tx.add(
-			Commands.MoveCall({
+			TransactionCommands.MoveCall({
 				target: '0x2::devnet_nft::mint',
 				typeArguments: [],
 				arguments: [tx.pure.string('foo'), tx.pure.string('bar'), tx.pure.string('baz')],
@@ -125,9 +125,9 @@ describe('offline build', () => {
 		const tx = setup();
 		tx.object(Inputs.ObjectRef(ref()));
 		const coin = tx.splitCoins(tx.gas, [100]);
-		tx.add(Commands.MergeCoins(tx.gas, [coin, tx.object(Inputs.ObjectRef(ref()))]));
+		tx.add(TransactionCommands.MergeCoins(tx.gas, [coin, tx.object(Inputs.ObjectRef(ref()))]));
 		tx.add(
-			Commands.MoveCall({
+			TransactionCommands.MoveCall({
 				target: '0x2::devnet_nft::mint',
 				typeArguments: [],
 				arguments: [tx.object(Inputs.ObjectRef(ref())), tx.object(Inputs.ReceivingRef(ref()))],
@@ -144,9 +144,9 @@ describe('offline build', () => {
 	it('builds a more complex interaction', async () => {
 		const tx = setup();
 		const coin = tx.splitCoins(tx.gas, [100]);
-		tx.add(Commands.MergeCoins(tx.gas, [coin, tx.object(Inputs.ObjectRef(ref()))]));
+		tx.add(TransactionCommands.MergeCoins(tx.gas, [coin, tx.object(Inputs.ObjectRef(ref()))]));
 		tx.add(
-			Commands.MoveCall({
+			TransactionCommands.MoveCall({
 				target: '0x2::devnet_nft::mint',
 				typeArguments: [],
 				arguments: [tx.pure.string('foo'), tx.pure.string('bar'), tx.pure.string('baz')],

package/src/transactions/__tests__/bcs.test.ts

@@ -61,7 +61,7 @@ function ref(): { objectId: string; version: string; digest: string } {
 }
 
 it('can serialize transaction data with a programmable transaction', () => {
-	const sui = normalizeHaneulAddress('0x2');
+	const haneul = normalizeHaneulAddress('0x2');
 	const txData = {
 		$kind: 'V1',
 		V1: {
@@ -69,7 +69,7 @@ it('can serialize transaction data with a programmable transaction', () => {
 			expiration: { $kind: 'None', None: true },
 			gasData: {
 				payment: [ref()],
-				owner: sui,
+				owner: haneul,
 				price: '1',
 				budget: '1000000',
 			},
@@ -121,10 +121,10 @@ it('can serialize transaction data with a programmable transaction', () => {
 						{
 							$kind: 'MoveCall',
 							MoveCall: {
-								package: sui,
+								package: haneul,
 								module: 'display',
 								function: 'new',
-								typeArguments: [`${sui}::capy::Capy`],
+								typeArguments: [`::capy::Capy`],
 								arguments: [
 									// publisher object
 									{
@@ -137,10 +137,10 @@ it('can serialize transaction data with a programmable transaction', () => {
 						{
 							$kind: 'MoveCall',
 							MoveCall: {
-								package: sui,
+								package: haneul,
 								module: 'display',
 								function: 'add_multiple',
-								typeArguments: [`${sui}::capy::Capy`],
+								typeArguments: [`::capy::Capy`],
 								arguments: [
 									// result of the first transaction
 									{
@@ -163,10 +163,10 @@ it('can serialize transaction data with a programmable transaction', () => {
 						{
 							$kind: 'MoveCall',
 							MoveCall: {
-								package: sui,
+								package: haneul,
 								module: 'display',
 								function: 'update_version',
-								typeArguments: [`${sui}::capy::Capy`],
+								typeArguments: [`::capy::Capy`],
 								arguments: [
 									// result of the first transaction again
 									{