@haneullabs/haneul 2.5.1 → 2.13.0

package/docs/sdk-building.md

@@ -0,0 +1,341 @@
+# Building SDKs
+
+> Build custom SDKs on top of the Haneul TypeScript SDK
+
+This guide covers recommended patterns for building TypeScript SDKs that integrate with the Haneul
+SDK. Following these patterns ensures your SDK integrates seamlessly with the ecosystem, works
+across different transports (JSON-RPC, GraphQL, gRPC), and composes well with other SDKs.
+
+**Key requirement:** All SDKs should depend on [`ClientWithCoreApi`](./clients/core), which is the
+transport-agnostic interface implemented by all Haneul clients. This ensures your SDK works with any
+client the user chooses.
+
+## Package Setup
+
+### Use Haneullabs Packages as Peer Dependencies
+
+SDKs should declare all `@haneullabs/*` packages as **peer dependencies** rather than direct
+dependencies. This ensures users get a single shared instance of each package, avoiding version
+conflicts and duplicate code.
+
+```json title="package.json"
+{
+	"name": "@your-org/your-sdk",
+	"peerDependencies": {
+		"@haneullabs/haneul": "^2.0.0",
+		"@haneullabs/bcs": "^2.0.0"
+	},
+	"devDependencies": {
+		"@haneullabs/haneul": "^2.0.0",
+		"@haneullabs/bcs": "^2.0.0"
+	}
+}
+```
+
+This approach:
+
+- Prevents multiple versions of Haneullabs packages from being bundled
+- Ensures compatibility with user's chosen package versions
+- Reduces bundle size for end users
+- Avoids subtle bugs from mismatched package instances
+- Allows the SDK to work with any compatible client
+
+## Client Extensions
+
+The recommended way to build SDKs is using the **client extension pattern**. This allows your SDK to
+extend the Haneul client with custom functionality. This makes it easier to use custom SDKs across
+the ecosystem without having to build custom bindings (like react context providers) for each
+individual SDK and client.
+
+### Extension Pattern
+
+Client extensions use the `$extend` method to add functionality to any Haneul client. Create a
+factory function that returns a `name` and `register` function:
+
+```typescript
+
+	name?: Name;
+	// Add SDK-specific configuration here
+	apiKey?: string;
+}
+
+	name = 'mySDK' as Name,
+	...options
+}: MySDKOptions<Name> = {}) {
+	return {
+		name,
+		register: (client: ClientWithCoreApi) => {
+			return new MySDKClient({ client, ...options });
+		},
+	};
+}
+
+	#client: ClientWithCoreApi;
+	#apiKey?: string;
+
+	constructor({ client, apiKey }: { client: ClientWithCoreApi; apiKey?: string }) {
+		this.#client = client;
+		this.#apiKey = apiKey;
+	}
+
+	async getResource(id: string) {
+		const result = await this.#client.core.getObject({ objectId: id });
+		// Process and return result
+		return result;
+	}
+}
+```
+
+Users can then extend their client:
+
+```typescript
+const client = new HaneulGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.haneul.io:443',
+}).$extend(mySDK());
+
+// Access your extension
+await client.mySDK.getResource('0x...');
+```
+
+### Real-World Examples
+
+Several official SDKs use this pattern:
+
+- **[@haneullabs/walrus](https://www.npmjs.com/package/@haneullabs/walrus)** - Decentralized storage
+- **[@haneullabs/seal](https://www.npmjs.com/package/@haneullabs/seal)** - Encryption and key
+  management
+
+## SDK Organization
+
+Most Haneullabs SDKs do not strictly follow these patterns yet, but we recommend scoping methods on
+your client extension into the following categories for clarity and consistency:
+
+| Property | Purpose                                                   | Example                             |
+| -------- | --------------------------------------------------------- | ----------------------------------- |
+| Methods  | Top-level operations (execute actions or read/parse data) | `sdk.readBlob()`, `sdk.getConfig()` |
+| `tx`     | Methods that create transactions without executing        | `sdk.tx.registerBlob()`             |
+| `bcs`    | BCS type definitions for encoding/decoding                | `sdk.bcs.MyStruct`                  |
+| `call`   | Methods returning Move calls that can be used with tx.add | `sdk.call.myFunction()`             |
+| `view`   | Methods that use simulate API to read onchain state       | `sdk.view.getState()`               |
+
+```typescript
+
+	#client: ClientWithCoreApi;
+
+	constructor({ client }: { client: ClientWithCoreApi }) {
+		this.#client = client;
+	}
+
+	// Top-level methods - execute actions or read/parse data
+	async executeAction(options: ActionOptions) {
+		const transaction = this.tx.createAction(options);
+		// Execute and return result
+	}
+
+	async getResource(objectId: string) {
+		const { object } = await this.#client.core.getObject({
+			objectId,
+			include: { content: true },
+		});
+		return myModule.MyStruct.parse(object.content);
+	}
+
+	// Transaction builders
+	tx = {
+		createAction: (options: ActionOptions) => {
+			const transaction = new Transaction();
+			transaction.add(this.call.action(options));
+			return transaction;
+		},
+	};
+
+	// Move call helpers - use generated functions with typed options
+	call = {
+		action: (options: ActionOptions) => {
+			return myModule.action({
+				arguments: {
+					obj: options.objectId,
+					amount: options.amount,
+				},
+			});
+		},
+	};
+
+	// View methods - use simulate API to read onchain state
+	view = {
+		getBalance: async (managerId: string) => {
+			const tx = new Transaction();
+			tx.add(myModule.getBalance({ arguments: { manager: managerId } }));
+
+			const res = await this.#client.core.simulateTransaction({
+				transaction: tx,
+				include: { commandResults: true },
+			});
+
+			return bcs.U64.parse(res.commandResults![0].returnValues[0].bcs);
+		},
+	};
+}
+```
+
+## Transaction Building Patterns
+
+### Transaction Thunks
+
+Transaction thunks are functions that accept a `Transaction` and mutate it. This pattern enables
+composition across multiple SDKs in a single transaction.
+
+```typescript
+// Synchronous thunk for operations that don't need async work
+function createResource(options: { name: string }) {
+	return (tx: Transaction): TransactionObjectArgument => {
+		const [resource] = tx.moveCall({
+			target: `${PACKAGE_ID}::module::create`,
+			arguments: [tx.pure.string(options.name)],
+		});
+		return resource;
+	};
+}
+
+// Usage
+const tx = new Transaction();
+const resource = tx.add(createResource({ name: 'my-resource' }));
+tx.transferObjects([resource], recipient);
+```
+
+### Async Thunks
+
+For operations requiring async work (like fetching package IDs or configuration), return async
+thunks. These are used with `tx.add()` exactly like synchronous thunks - the async resolution
+happens automatically before signing:
+
+```typescript
+function createResourceAsync(options: { name: string }) {
+	return async (tx: Transaction): Promise<TransactionObjectArgument> => {
+		// Async work happens here, before the transaction is signed
+		const packageId = await getLatestPackageId();
+
+		const [resource] = tx.moveCall({
+			target: `${packageId}::module::create`,
+			arguments: [tx.pure.string(options.name)],
+		});
+		return resource;
+	};
+}
+
+// Usage is identical to synchronous thunks
+const tx = new Transaction();
+const resource = tx.add(createResourceAsync({ name: 'my-resource' }));
+tx.transferObjects([resource], recipient);
+
+// Async work resolves automatically when the transaction is built/signed
+await signer.signAndExecuteTransaction({ transaction: tx, client });
+```
+
+This pattern is critical for web wallet compatibility - async work that happens during transaction
+construction won't block the popup triggered by user interaction.
+
+## Transaction Execution
+
+### Accept a Signer Parameter
+
+For methods that execute transactions, accept a `Signer` parameter and always use the signer to
+execute the transaction. This enables:
+
+- Wallet integration through dApp Kit
+- Transaction sponsorship
+- Custom signing flows
+
+```typescript
+
+	#client: ClientWithCoreApi;
+
+	async createAndExecute({ signer, ...options }: CreateOptions & { signer: Signer }) {
+		const transaction = this.tx.create(options);
+
+		// Use signAndExecuteTransaction for maximum flexibility
+		const result = await signer.signAndExecuteTransaction({
+			transaction,
+			client: this.#client,
+		});
+
+		return result;
+	}
+}
+```
+
+Using `signAndExecuteTransaction` allows wallets and sponsors to customize execution behavior.
+
+## Code Generation
+
+For SDKs that interact with Move contracts, use **[@haneullabs/codegen](/codegen)** to generate
+type-safe TypeScript bindings from your Move packages.
+
+Benefits include type safety, BCS parsing, IDE support, and MoveRegistry support for human-readable
+package names. See the [codegen documentation](/codegen) for setup instructions.
+
+### Using Generated Code
+
+The generated code provides both Move call functions and BCS struct definitions:
+
+```typescript
+// Generated Move call functions return thunks with typed options
+const tx = new Transaction();
+tx.add(
+	myContract.doSomething({
+		arguments: {
+			obj: '0x123...',
+			amount: 100n,
+		},
+	}),
+);
+
+// Generated BCS types parse on-chain data
+const { object } = await client.core.getObject({
+	objectId: '0x123...',
+	include: { content: true },
+});
+const parsed = myContract.MyStruct.parse(object.content);
+```
+
+See the [codegen documentation](/codegen) for complete setup and configuration options.
+
+## Reading Object Contents
+
+SDKs often need to fetch objects and parse their BCS-encoded content. Use `getObject` with
+`include: { content: true }` and generated BCS types:
+
+```typescript
+async function getResource(objectId: string) {
+	const { object } = await this.#client.core.getObject({
+		objectId,
+		include: { content: true },
+	});
+
+	if (!object) {
+		throw new Error(`Object ${objectId} not found`);
+	}
+
+	// Parse BCS content using generated type
+	return MyStruct.parse(object.content);
+}
+```
+
+For batching multiple object fetches, use `getObjects`:
+
+```typescript
+async function getResources(objectIds: string[]) {
+	const { objects } = await this.#client.core.getObjects({
+		objectIds,
+		include: { content: true },
+	});
+
+	return objects.map((obj) => {
+		if (obj instanceof Error) {
+			throw obj;
+		}
+		return MyStruct.parse(obj.content);
+	});
+}
+```

package/docs/transaction-building/basics.md

@@ -0,0 +1,297 @@
+# Haneul Programmable Transaction Basics
+
+> Construct programmable transaction blocks with the Transaction API
+
+This example starts by constructing a transaction to send HANEUL. To construct transactions, import
+the `Transaction` class and construct it:
+
+```tsx
+const tx = new Transaction();
+```
+
+You can then add commands to the transaction .
+
+```tsx
+// create a new coin with balance 100, based on the coins used as gas payment
+// you can define any balance here
+const [coin] = tx.splitCoins(tx.gas, [100]);
+
+// transfer the split coin to a specific address
+tx.transferObjects([coin], '0xSomeHaneulAddress');
+```
+
+You can attach multiple commands of the same type to a transaction, as well. For example, to get a
+list of transfers and iterate over them to transfer coins to each of them:
+
+```tsx
+interface Transfer {
+	to: string;
+	amount: number;
+}
+
+// procure a list of some Haneul transfers to make
+const transfers: Transfer[] = getTransfers();
+
+const tx = new Transaction();
+
+// first, split the gas coin into multiple coins
+const coins = tx.splitCoins(
+	tx.gas,
+	transfers.map((transfer) => transfer.amount),
+);
+
+// next, create a transfer command for each coin
+transfers.forEach((transfer, index) => {
+	tx.transferObjects([coins[index]], transfer.to);
+});
+```
+
+After you have the transaction defined, you can directly execute it with a signer using
+`signAndExecuteTransaction`.
+
+```tsx
+const result = await client.signAndExecuteTransaction({ signer: keypair, transaction: tx });
+
+// IMPORTANT: Always check the transaction status
+// Transactions can execute but still fail (e.g., insufficient gas, move errors)
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+```
+
+## Observing the results of a transaction
+
+When you use `client.signAndExecuteTransaction` or `client.executeTransactionBlock`, the transaction
+will be finalized on the blockchain before the function resolves, but the effects of the transaction
+may not be immediately observable.
+
+There are 2 ways to observe the results of a transaction. Methods like
+`client.signAndExecuteTransaction` accept an `options` object with options like `showObjectChanges`
+and `showBalanceChanges` (see
+[the HaneulJsonRpcClient docs for more details](/haneul/clients/json-rpc#arguments)). These options
+will cause the request to contain additional details about the effects of the transaction that can
+be immediately displayed to the user, or used for further processing in your application.
+
+The other way effects of transactions can be observed is by querying other RPC methods like
+`client.getBalances` that return objects or balances owned by a specific address. These RPC calls
+depend on the RPC node having indexed the effects of the transaction, which may not have happened
+immediately after a transaction has been executed. To ensure that effects of a transaction are
+represented in future RPC calls, you can use the `waitForTransaction` method on the client:
+
+```typescript
+const result = await client.signAndExecuteTransaction({ signer: keypair, transaction: tx });
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+await client.waitForTransaction({ result });
+```
+
+Once `waitForTransaction` resolves, any future RPC calls will be guaranteed to reflect the effects
+of the transaction.
+
+## Transactions
+
+Programmable Transactions have two key concepts: inputs and commands.
+
+Commands are steps of execution in the transaction. Each command in a Transaction takes a set of
+inputs, and produces results. The inputs for a transaction depend on the kind of command. Haneul
+supports following commands:
+
+- `tx.splitCoins(coin, amounts)` - Creates new coins with the defined amounts, split from the
+  provided coin. Returns the coins so that it can be used in subsequent transactions.
+  - Example: `tx.splitCoins(tx.gas, [100, 200])`
+- `tx.mergeCoins(destinationCoin, sourceCoins)` - Merges the sourceCoins into the destinationCoin.
+  - Example: `tx.mergeCoins(tx.object(coin1), [tx.object(coin2), tx.object(coin3)])`
+- `tx.transferObjects(objects, address)` - Transfers a list of objects to the specified address.
+  - Example: `tx.transferObjects([tx.object(thing1), tx.object(thing2)], myAddress)`
+- `tx.moveCall({ target, arguments, typeArguments  })` - Executes a Move call. Returns whatever the
+  Haneul Move call returns.
+  - Example:
+    `tx.moveCall({ target: '0x2::devnet_nft::mint', arguments: [tx.pure.string(name), tx.pure.string(description), tx.pure.string(image)] })`
+- `tx.makeMoveVec({ type, elements })` - Constructs a vector of objects that can be passed into a
+  `moveCall`. This is required as there’s no way to define a vector as an input.
+  - Example: `tx.makeMoveVec({ elements: [tx.object(id1), tx.object(id2)] })`
+- `tx.publish(modules, dependencies)` - Publishes a Move package. Returns the upgrade capability
+  object.
+
+## Passing inputs to a command
+
+Command inputs can be provided in a number of different ways, depending on the command, and the type
+of value being provided.
+
+#### JavaScript values
+
+For specific command arguments (`amounts` in `splitCoins`, and `address` in `transferObjects`) the
+expected type is known ahead of time, and you can directly pass raw javascript values when calling
+the command method. appropriate Move type automatically.
+
+```ts
+// the amount to split off the gas coin is provided as a pure javascript number
+const [coin] = tx.splitCoins(tx.gas, [100]);
+// the address for the transfer is provided as a pure javascript string
+tx.transferObjects([coin], '0xSomeHaneulAddress');
+```
+
+#### Pure values
+
+When providing inputs that are not on chain objects, the values must be serialized as
+
+[BCS](https://sdk.haneul-labs.com/bcs), which can be done using `tx.pure` eg,
+`tx.pure.address(address)` or `tx.pure(bcs.vector(bcs.U8).serialize(bytes))`.
+
+`tx.pure` can be called as a function that accepts a SerializedBcs object, or as a namespace that
+contains functions for each of the supported types.
+
+```ts
+const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(100)]);
+const [coin] = tx.splitCoins(tx.gas, [tx.pure(bcs.U64.serialize(100))]);
+tx.transferObjects([coin], tx.pure.address('0xSomeHaneulAddress'));
+tx.transferObjects([coin], tx.pure(bcs.Address.serialize('0xSomeHaneulAddress')));
+```
+
+To pass `vector` or `option` types, you can pass use the corresponding methods on `tx.pure`, use
+tx.pure as a function with a type argument, or serialize the value before passing it to tx.pure
+using the bcs sdk:
+
+```ts
+tx.moveCall({
+	target: '0x2::foo::bar',
+	arguments: [
+		// using vector and option methods
+		tx.pure.vector('u8', [1, 2, 3]),
+		tx.pure.option('u8', 1),
+		tx.pure.option('u8', null),
+
+		// Using pure with type arguments
+		tx.pure('vector<u8>', [1, 2, 3]),
+		tx.pure('option<u8>', 1),
+		tx.pure('option<u8>', null),
+		tx.pure('vector<option<u8>>', [1, null, 2]),
+
+		// Using bcs.serialize
+		tx.pure(bcs.vector(bcs.U8).serialize([1, 2, 3])),
+		tx.pure(bcs.option(bcs.U8).serialize(1)),
+		tx.pure(bcs.option(bcs.U8).serialize(null)),
+		tx.pure(bcs.vector(bcs.option(bcs.U8)).serialize([1, null, 2])),
+	],
+});
+```
+
+#### Object references
+
+To use an on chain object as a transaction input, you must pass a reference to that object. This can
+be done by calling `tx.object` with the object id. Transaction arguments that only accept objects
+(like `objects` in `transferObjects`) will automatically treat any provided strings as objects ids.
+For methods like `moveCall` that accept both objects and other types, you must explicitly call
+`tx.object` to convert the id to an object reference.
+
+```ts
+// Object IDs can be passed to some methods like (transferObjects) directly
+tx.transferObjects(['0xSomeObject'], 'OxSomeAddress');
+// tx.object can be used anywhere an object is accepted
+tx.transferObjects([tx.object('0xSomeObject')], 'OxSomeAddress');
+
+tx.moveCall({
+	target: '0x2::nft::mint',
+	// object IDs must be wrapped in moveCall arguments
+	arguments: [tx.object('0xSomeObject')],
+});
+
+// tx.object automatically converts the object ID to receiving transaction arguments if the moveCall expects it
+tx.moveCall({
+	target: '0xSomeAddress::example::receive_object',
+	// 0xSomeAddress::example::receive_object expects a receiving argument and has a Move definition that looks like this:
+	// public fun receive_object<T: key>(parent_object: &mut ParentObjectType, receiving_object: Receiving<ChildObjectType>) { ... }
+	arguments: [tx.object('0xParentObjectID'), tx.object('0xReceivingObjectID')],
+});
+```
+
+When building a transaction, Haneul expects all objects to be fully resolved, including the object
+version. The SDK automatically looks up the current version of objects for any provided object
+reference when building a transaction. If the object reference is used as a receiving argument to a
+`moveCall`, the object reference is automatically converted to a receiving transaction argument.
+This greatly simplifies building transactions, but requires additional RPC calls. You can optimize
+this process by providing a fully resolved object reference instead:
+
+```ts
+// for owned or immutable objects
+tx.object(Inputs.ObjectRef({ digest, objectId, version }));
+
+// for shared objects
+tx.object(Inputs.SharedObjectRef({ objectId, initialSharedVersion, mutable }));
+
+// for receiving objects
+tx.object(Inputs.ReceivingRef({ digest, objectId, version }));
+```
+
+##### Object helpers
+
+There are a handful of specific object types that can be referenced through helper methods on
+tx.object:
+
+```ts
+tx.object.system(),
+tx.object.clock(),
+tx.object.random(),
+tx.object.denyList(),
+
+tx.object.option({
+	type: '0x123::example::Thing',
+	// value can be an Object ID, or any other object reference, or null for `none`
+	value: '0x456',
+}),
+```
+
+#### Transaction results
+
+You can also use the result of a command as an argument in a subsequent commands. Each method on the
+transaction builder returns a reference to the transaction result.
+
+```tsx
+// split a coin object off of the gas object
+const [coin] = tx.splitCoins(tx.gas, [100]);
+// transfer the resulting coin object
+tx.transferObjects([coin], address);
+```
+
+When a command returns multiple results, you can access the result at a specific index either using
+destructuring, or array indexes.
+
+```tsx
+// destructuring (preferred, as it gives you logical local names)
+const [nft1, nft2] = tx.moveCall({ target: '0x2::nft::mint_many' });
+tx.transferObjects([nft1, nft2], address);
+
+// array indexes
+const mintMany = tx.moveCall({ target: '0x2::nft::mint_many' });
+tx.transferObjects([mintMany[0], mintMany[1]], address);
+```
+
+## Get transaction bytes
+
+If you need the transaction bytes, instead of signing or executing the transaction, you can use the
+`build` method on the transaction builder itself.
+
+**Important:** You might need to explicitly call `setSender()` on the transaction to ensure that the
+`sender` field is populated. This is normally done by the signer before signing the transaction, but
+will not be done automatically if you’re building the transaction bytes yourself.
+
+```tsx
+const tx = new Transaction();
+
+// ... add some transactions...
+
+await tx.build({ client });
+```
+
+In most cases, building requires your HaneulJsonRpcClient to fully resolve input values.
+
+If you have transaction bytes, you can also convert them back into a `Transaction` class:
+
+```tsx
+const bytes = getTransactionBytesFromSomewhere();
+const tx = Transaction.from(bytes);
+```

package/docs/transaction-building/gas.md

@@ -0,0 +1,62 @@
+# Paying for Haneul Transactions with Gas Coins
+
+> Configure gas budget, price, and coin selection for transactions
+
+With Programmable Transactions, you can use the gas payment coin to construct coins with a set
+balance using `splitCoin`. This is useful for Haneul payments, and avoids the need for up-front coin
+selection. You can use `tx.gas` to access the gas coin in a transaction, and it is valid as input
+for any arguments, as long as it is used
+[by-reference](https://docs.haneul.io/guides/developer/haneul-101/simulating-refs). Practically
+speaking, this means you can also add to the gas coin with `mergeCoins` and borrow it for Move
+functions with `moveCall`.
+
+You can also transfer the gas coin using `transferObjects`, in the event that you want to transfer
+all of your coin balance to another address.
+
+## Gas configuration
+
+The new transaction builder comes with default behavior for all gas logic, including automatically
+setting the gas price, budget, and selecting coins to be used as gas. This behavior can be
+customized.
+
+### Gas price
+
+By default, the gas price is set to the reference gas price of the network. You can also explicitly
+set the gas price of the transaction by calling `setGasPrice` on the transaction builder.
+
+```tsx
+tx.setGasPrice(gasPrice);
+```
+
+### Budget
+
+By default, the gas budget is automatically derived by executing a dry-run of the transaction
+beforehand. The dry run gas consumption is then used to determine a balance for the transaction. You
+can override this behavior by explicitly setting a gas budget for the transaction, by calling
+`setGasBudget` on the transaction builder.
+
+**Note:** The gas budget is represented in Haneul, and should take the gas price of the transaction
+into account.
+
+```tsx
+tx.setGasBudget(gasBudgetAmount);
+```
+
+### Gas payment
+
+By default, the gas payment is automatically determined by the SDK. The SDK selects all of the users
+coins that are not used as inputs in the transaction.
+
+The list of coins used as gas payment will be merged down into a single gas coin before executing
+the transaction, and all but one of the gas objects will be deleted. The gas coin at the 0-index
+will be the coin that all others are merged into.
+
+```tsx
+// you need to ensure that the coins do not overlap with any
+// of the input objects for the transaction
+tx.setGasPayment([coin1, coin2]);
+```
+
+Gas coins should be objects containing the coins objectId, version, and digest.
+
+<auto-type-table type="{ objectId: string, version: string | number, digest: string }" />