@haneullabs/haneul 2.5.2 → 2.13.0

package/docs/transaction-building/intents.md

@@ -0,0 +1,61 @@
+# Transaction Intents
+
+> Use high-level intents to simplify transaction building
+
+Transaction Intents enable 3rd party SDKs and [Transaction Plugins](../plugins) to more easily add
+complex operations to a Transaction. The Typescript SDK currently only includes a single Intent
+(CoinWithBalance), but more will be added in the future.
+
+## The CoinWithBalance intent
+
+The `CoinWithBalance` intent makes it easy to get a coin with a specific balance. For HANEUL, this
+has generally been done by splitting the gas coin:
+
+```typescript
+const tx = new Transaction();
+
+const [coin] = tx.splitCoins(tx.gas, [100]);
+
+tx.transferObjects([coin], recipient);
+```
+
+This approach works well for HANEUL, but can't be used for other coin types. The CoinWithBalance
+intent solves this by providing a helper function that automatically adds the correct SplitCoins and
+MergeCoins commands to the transaction:
+
+```typescript
+const tx = new Transaction();
+
+// Setting the sender is required for the CoinWithBalance intent to resolve coins when not using the gas coin
+tx.setSender(keypair.toHaneulAddress());
+
+tx.transferObjects(
+	[
+		// Create a HANEUL coin (balance is in GEUNHWA)
+		coinWithBalance({ balance: 100 }),
+		// Create a coin of another type
+		coinWithBalance({ balance: 100, type: '0x123::foo:Bar' }),
+	],
+	recipient,
+);
+```
+
+Splitting the gas coin also causes problems for sponsored transactions. When sponsoring
+transactions, the gas coin comes from the sponsor instead of the transaction sender. Transaction
+sponsors usually do not sponsor transactions that use the gas coin for anything other than gas. To
+transfer HANEUL that does not use the gas coin, you can set the `useGasCoin` option to `false`:
+
+```typescript
+const tx = new Transaction();
+tx.transferObjects([coinWithBalance({ balance: 100, useGasCoin: false })], recipient);
+```
+
+It's important to only set `useGasCoin` option to false for sponsored transactions, otherwise the
+coinWithBalance intent may use all the HANEUL coins, leaving no coins to use for gas.
+
+## How it works
+
+When the `CoinWithBalance` intent is resolved, it will look up the senders owned coins for each type
+that needs to be created. It will then find a set of coins with sufficient balance to cover the
+desired balance, to combine them into a single coin. This coin is then used in a `SplitCoins`
+command to create the desired coin.

package/docs/transaction-building/offline.md

@@ -0,0 +1,71 @@
+# Building Offline
+
+> Build transactions without a network connection
+
+To build a transaction offline (with no `client` required), you need to fully define all of your
+inputs, gas configuration, and expiration.
+
+## Required Configuration
+
+When building offline, you must set the following:
+
+- **Sender address** - The address that will execute the transaction
+- **Gas price** - The price per gas unit (can be obtained from the network beforehand)
+- **Gas budget** - The maximum gas to spend on this transaction
+- **Gas payment** - One or more coin object references to use for gas, or an empty array for Address
+  Balances
+- **Expiration** - Only needed when using address balances for gas
+
+```tsx
+const { referenceGasPrice } = await client.getReferenceGasPrice();
+
+const tx = new Transaction();
+
+tx.setSender('0x<your-address>');
+tx.setGasPrice(referenceGasPrice);
+tx.setGasBudget(50_000_000);
+tx.setGasPayment([
+	{
+		objectId: '0x<gas-coin-object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	},
+]);
+
+// Build the transaction without a client
+const bytes = await tx.build();
+```
+
+## Object References
+
+For objects used in your transaction, you must provide full object references using the `Inputs`
+helper:
+
+```tsx
+// For owned or immutable objects
+tx.object(
+	Inputs.ObjectRef({
+		objectId: '0x<object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	}),
+);
+
+// For shared objects
+tx.object(
+	Inputs.SharedObjectRef({
+		objectId: '0x<object-id>',
+		initialSharedVersion: '<initial-shared-version>',
+		mutable: true,
+	}),
+);
+
+// For receiving objects (objects being received by another object)
+tx.object(
+	Inputs.ReceivingRef({
+		objectId: '0x<object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	}),
+);
+```

package/docs/transaction-building/sponsored-transactions.md

@@ -0,0 +1,22 @@
+# Sponsored Transactions
+
+> Pay gas fees on behalf of other users with sponsored transactions
+
+The transaction builder can support sponsored transactions by using the `onlyTransactionKind` flag
+when building the transaction.
+
+```tsx
+const tx = new Transaction();
+
+// ... add some transactions...
+
+const kindBytes = await tx.build({ provider, onlyTransactionKind: true });
+
+// construct a sponsored transaction from the kind bytes
+const sponsoredtx = Transaction.fromKind(kindBytes);
+
+// you can now set the sponsored transaction data that is required
+sponsoredtx.setSender(sender);
+sponsoredtx.setGasOwner(sponsor);
+sponsoredtx.setGasPayment(sponsorCoins);
+```

package/docs/utils/derived_objects.md

@@ -0,0 +1,80 @@
+# Derived Objects
+
+> Compute derived object IDs from parent objects
+
+Derived objects enable deterministic IDs for objects, enabling offline derivation of object IDs.
+[Click here to read more.](https://docs.haneul.io/concepts/haneul-move-concepts/derived-objects)
+
+To derive an object ID, you can import `deriveObjectID` function exposed from utils.
+
+```typescript
+
+```
+
+To derive any object, you need to have its parent's ID (the object from which it was derived), and
+the key used to generate it.
+
+> **Warning:** It is recommended to verify the on-chain `derived_object::derive_address` match your
+> off-chain calculation (at least once when implementing offline calculations), especially for
+> critical cases like transferring assets.
+
+## Deriving using primitive keys
+
+To derive the IDs using primitive types, you can use the built-in types like this, assuming you have
+a parent object with ID `0xc0ffee`.
+
+```typescript
+// Example 1: On-chain derivation for `0xc0ffee + vector<u8>([0,1,2])
+deriveObjectID('0xc0ffee', 'vector<u8>', bcs.vector(bcs.u8()).serialize([0, 1, 2]).toBytes());
+
+// Example 2: On-chain derivation for `0xc0ffee + address('0x111')`
+deriveObjectID('0xc0ffee', 'address', bcs.Address.serialize('0x111').toBytes());
+
+// Example 3: On-chain derivation for `0xc0ffee + non-ascii string ("foo")`
+deriveObjectID('0xc0ffee', '0x1::string::String', bcs.String.serialize('foo').toBytes());
+```
+
+## Deriving using custom types
+
+To derive IDs using your custom objects, you can use BCS & the known type IDs.
+
+Assuming a custom struct on-chain (for the key) being:
+
+```move
+public struct DemoStruct has copy, store, drop { value: u64 }
+```
+
+you can derive it by doing:
+
+```typescript
+// Assuming we wanted to derive for key `DemoStruct { value: 1 }`.
+const bcsType = bcs.struct('DemoStruct', {
+	value: bcs.u64(),
+});
+
+const key = bcsType.serialize({ value: 1 }).toBytes();
+
+// Derive the object ID for the key `DemoStruct { value: 1 }`.
+deriveObjectID('0xc0ffee', `0xc0ffee::demo::DemoStruct`, key);
+```
+
+### Deriving with fieldless structs
+
+In Move, structs with no user-defined fields automatically get a `dummy_field: bool` injected by the
+compiler. This means their BCS encoding is not empty — it's a single `0x00` byte (the encoding of
+`false`). You can treat this as a constant.
+
+A real-world example is `0x2::coin_registry::CurrencyKey<T>`, which is a fieldless generic struct
+used to derive `Currency` objects from the coin registry (`0xc`) based on their type:
+
+```typescript
+// On-chain: `public struct CurrencyKey<phantom T>() has copy, store, drop`
+// The compiler injects `dummy_field: bool`, always `false`.
+const key = new Uint8Array([0]);
+
+const coinType = '0x2::haneul::HANEUL';
+const currencyId = deriveObjectID('0xc', `0x2::coin_registry::CurrencyKey<${coinType}>`, key);
+```
+
+This applies to any struct with no fields — phantom type parameters don't add any BCS-encoded data,
+so the key is always `new Uint8Array([0])`.

package/docs/utils/index.md

@@ -0,0 +1,53 @@
+# The `@haneullabs/haneul/utils` package
+
+> Utility functions for addresses, coins, and common operations
+
+This package contains some utilities that simplify common operations when working with the Haneul
+TypeScript SDK.
+
+## Constants
+
+A set of constants exported for common uses cases:
+
+- `GEUNHWA_PER_HANEUL`: The conversion rate for GEUNHWA to HANEUL (1,000,000,000)
+- `HANEUL_DECIMALS`: the number of decimals you must shift a GEUNHWA value to convert it to HANEUL
+  (`9`)
+- `HANEUL_ADDRESS_LENGTH`: The number of bytes in a Haneul address (32)
+- `MOVE_STDLIB_ADDRESS`: The address for the Haneul Move standard library
+- `HANEUL_FRAMEWORK_ADDRESS`: The address for the Haneul Framework
+- `HANEUL_SYSTEM_ADDRESS`: The address for the Haneul System module
+- `HANEUL_CLOCK_OBJECT_ID`: The address for the `haneul::clock::Clock` object
+- `HANEUL_SYSTEM_STATE_OBJECT_ID`: The address for the `HaneulSystemState` object
+- `HANEUL_RANDOM_OBJECT_ID`: The address for the `0x2::random::Random` object
+
+## Formatters
+
+You can use the following helpers to format various values:
+
+- `formatAddress`
+- `formatDigest`
+- `normalizeStructTag`
+- `normalizeHaneulAddress`
+- `normalizeHaneulObjectId`
+- `normalizeHaneulNSName`
+- `normalizeHaneulNSName`
+
+## Validators
+
+You can use the following helpers to validate the format of various values (this only validates that
+the value is in the correct format, but does not validate the value is valid for a specific use
+case, or exists on chain).
+
+- `isValidHaneulAddress`
+- `isValidHaneulObjectId`
+- `isValidTransactionDigest`
+- `isValidHaneulNSName`
+
+## Encoding
+
+The following methods are re-exported to help with converting between commonly used encodings
+
+- `fromHex`: Deserializes a hex string to a Uint8Array
+- `toHex`: Serializes a Uint8Array to a hex string
+- `fromBase64`: Deserializes a base64 string to a Uint8Array
+- `toBase64`: Serializes a Uint8Array to a base64 string

package/docs/zklogin.md

@@ -0,0 +1,78 @@
+# ZkLogin
+
+> Zero-knowledge authentication with OAuth providers on Haneul
+
+Utilities for working with zkLogin. Currently contains functionality to create and parse zkLogin
+signatures and compute zkLogin addresses.
+
+To parse a serialized zkLogin signature
+
+```typescript
+const parsedSignature = await parseZkLoginSignature('BQNNMTY4NjAxMzAyO....');
+```
+
+Use `getZkLoginSignature` to serialize a zkLogin signature.
+
+```typescript
+const serializedSignature = await getZkLoginSignature({ inputs, maxEpoch, userSignature });
+```
+
+To compute the address for a given address seed and iss you can use `computeZkLoginAddressFromSeed`
+
+```typescript
+const address = computeZkLoginAddressFromSeed(0n, 'https://accounts.google.com');
+```
+
+To compute an address from jwt:
+
+```typescript
+const address = jwtToAddress(jwtAsString, salt);
+```
+
+To compute an address from a parsed jwt:
+
+```typescript
+const address = computeZkLoginAddress({
+	claimName,
+	claimValue,
+	iss,
+	aud,
+	userSalt: BigInt(salt),
+});
+```
+
+To use zkLogin inside a multisig, see the [Multisig Guide](../haneul/cryptography/multisig) for more
+details.
+
+## Legacy addresses
+
+When zklogin was first introduced, there was an inconsistency in how the address seed was computed.
+For backwards compatibility reasons there are 2 valid addresses for a given set of inputs. Methods
+that produce zklogin addresses all accept a `legacyAddress` boolean flag, either as their last
+parameter, or in their options argument.
+
+```typescript
+
+	computeZkLoginAddress,
+	computeZkLoginAddressFromSeed,
+	jwtToAddress,
+	toZkLoginPublicIdentifier,
+	genAddressSeed,
+} from '@haneullabs/haneul/zklogin';
+
+const address = jwtToAddress(jwtAsString, salt, true);
+const address = computeZkLoginAddressFromSeed(0n, 'https://accounts.google.com', true);
+const address = computeZkLoginAddress({
+	claimName,
+	claimValue,
+	iss,
+	aud,
+	userSalt: BigInt(salt),
+	legacyAddress: true,
+});
+const address = toZkLoginPublicIdentifier(
+	genAddressSeed(userSalt, claimName, claimValue, aud),
+	iss,
+	{ legacyAddress: true },
+).toHaneulAddress();
+```