@haneullabs/haneul 2.5.1 → 2.13.0

package/docs/migrations/haneul-2.0/json-rpc-migration.md

@@ -0,0 +1,399 @@
+# Migrating from JSON-RPC
+
+> Migrate from JSON-RPC to the new Core API
+
+This guide covers migrating from `HaneulJsonRpcClient` to the new client APIs. The JSON-RPC API is
+being deprecated in favor of `HaneulGrpcClient` and `HaneulGraphQLClient`.
+
+> **Note:** We recommend using `HaneulGrpcClient` for most operations and `HaneulGraphQLClient` for
+> complex queries like filtering transactions and events.
+
+## Choosing a Client
+
+| Client                | Best For                                                        |
+| --------------------- | --------------------------------------------------------------- |
+| `HaneulGrpcClient`    | Most operations, SDK integrations, real-time data               |
+| `HaneulGraphQLClient` | Complex queries, filtering transactions/events, historical data |
+
+## Quick Migration to gRPC
+
+For most use cases, migrate to `HaneulGrpcClient`:
+
+```diff
+- import { HaneulJsonRpcClient, getJsonRpcFullnodeUrl } from '@haneullabs/haneul/jsonRpc';
++ import { HaneulGrpcClient } from '@haneullabs/haneul/grpc';
+
+- const client = new HaneulJsonRpcClient({
+-   url: getJsonRpcFullnodeUrl('mainnet'),
+-   network: 'mainnet',
+- });
++ const client = new HaneulGrpcClient({
++   baseUrl: 'https://fullnode.mainnet.haneul.io:443',
++   network: 'mainnet',
++ });
+```
+
+Both clients use the same full node URLs, so you can use the same endpoint when migrating.
+
+## Core API Methods
+
+The gRPC client should work with almost all haneullabs SDKs as a drop in replacement for the
+JSON-RPC client. When using the client directly, the methods and data returned will not be exactly
+the same as what was available in JSON-RPC.
+
+## Methods Replaced by Core API
+
+These JSON-RPC methods have direct replacements in the core API:
+
+| JSON-RPC Method              | Core API Replacement                              |
+| ---------------------------- | ------------------------------------------------- |
+| `getCoins`                   | `listCoins`                                       |
+| `getAllCoins`                | `listOwnedObjects` with `type: '0x2::coin::Coin'` |
+| `getAllBalances`             | `listBalances`                                    |
+| `getOwnedObjects`            | `listOwnedObjects`                                |
+| `multiGetObjects`            | `getObjects`                                      |
+| `getDynamicFields`           | `listDynamicFields`                               |
+| `getDynamicFieldObject`      | `getDynamicField`                                 |
+| `devInspectTransactionBlock` | `simulateTransaction` with `checksEnabled: false` |
+| `dryRunTransactionBlock`     | `simulateTransaction`                             |
+| `getNormalizedMoveFunction`  | `getMoveFunction`                                 |
+| `getMoveFunctionArgTypes`    | `getMoveFunction`                                 |
+
+### Example: Migrating devInspectTransactionBlock
+
+```diff
+- const result = await jsonRpcClient.devInspectTransactionBlock({
+-   sender: '0xabc...',
+-   transactionBlock: tx,
+- });
+- const returnValues = result.results?.[0]?.returnValues;
++ const result = await client.core.simulateTransaction({
++   transaction: tx,
++   checksEnabled: false,
++   include: { commandResults: true },
++ });
++ const returnValues = result.commandResults?.[0]?.returnValues;
+```
+
+### Example: Migrating getOwnedObjects
+
+```diff
+- const { data } = await jsonRpcClient.getOwnedObjects({
+-   owner: '0xabc...',
+-   options: { showContent: true },
+- });
++ const { objects } = await grpcClient.listOwnedObjects({
++   owner: '0xabc...',
++   include: { content: true },
++ });
+```
+
+## Methods Replaced by gRPC Services
+
+These JSON-RPC methods can be replaced by calling gRPC service clients directly:
+
+| JSON-RPC Method                     | gRPC Service Replacement          |
+| ----------------------------------- | --------------------------------- |
+| `getCheckpoint`                     | `ledgerService.getCheckpoint`     |
+| `getCheckpoints`                    | `ledgerService.listCheckpoints`   |
+| `getLatestCheckpointSequenceNumber` | `ledgerService.getCheckpoint`     |
+| `getEpochs`                         | `ledgerService.listEpochs`        |
+| `getCurrentEpoch`                   | `ledgerService.getEpoch`          |
+| `getLatestHaneulSystemState`        | `ledgerService.getSystemState`    |
+| `getCommitteeInfo`                  | `ledgerService.getCommittee`      |
+| `getValidatorsApy`                  | `ledgerService.getValidators`     |
+| `getProtocolConfig`                 | `ledgerService.getProtocolConfig` |
+| `getNormalizedMoveModule`           | `movePackageService.getModule`    |
+| `getNormalizedMoveModulesByPackage` | `movePackageService.getPackage`   |
+| `getNormalizedMoveStruct`           | `movePackageService.getStruct`    |
+| `resolveNameServiceAddress`         | `nameService.lookupName`          |
+| `resolveNameServiceNames`           | `nameService.reverseLookupName`   |
+
+### Example: Using gRPC Service Clients
+
+```typescript
+const client = new HaneulGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.haneul.io:443',
+	network: 'mainnet',
+});
+
+// Get checkpoint information
+const { response } = await client.ledgerService.getCheckpoint({
+	sequenceNumber: 12345n,
+});
+
+// Get current epoch
+const { response: epoch } = await client.ledgerService.getEpoch({});
+
+// Get Move module information
+const { response: module } = await client.movePackageService.getModule({
+	packageId: '0x2',
+	moduleName: 'coin',
+});
+
+// Resolve HaneulNS name
+const { response: address } = await client.nameService.lookupName({
+	name: 'example.haneul',
+});
+```
+
+## Methods Requiring GraphQL
+
+Some JSON-RPC methods don't have gRPC equivalents and require using `HaneulGraphQLClient` instead:
+
+| JSON-RPC Method             | GraphQL Alternative                |
+| --------------------------- | ---------------------------------- |
+| `queryTransactionBlocks`    | `transactions` query               |
+| `multiGetTransactionBlocks` | `multiGetTransactionEffects` query |
+| `queryEvents`               | `events` query                     |
+| `getCoinMetadata`           | `coinMetadata` query               |
+| `getTotalSupply`            | `coinMetadata` query               |
+| `getStakes`                 | `address.stakedHaneuls` query      |
+| `getStakesByIds`            | `multiGetObjects` query            |
+| `tryGetPastObject`          | Historical object queries          |
+| `getNetworkMetrics`         | Use indexer                        |
+| `getAddressMetrics`         | Use indexer                        |
+| `getMoveCallMetrics`        | Use indexer                        |
+
+### Setting Up GraphQL Client
+
+```typescript
+const graphqlClient = new HaneulGraphQLClient({
+	url: 'https://haneul-mainnet.haneul-labs.com/graphql',
+	network: 'mainnet',
+});
+```
+
+### Querying Transactions
+
+Replace `queryTransactionBlocks` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query QueryTransactions($sender: HaneulAddress, $first: Int, $after: String) {
+      transactions(
+        first: $first
+        after: $after
+        filter: { sentAddress: $sender }
+      ) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          digest
+          effects {
+            status
+            epoch { epochId }
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		sender: '0xabc...',
+		first: 10,
+	},
+});
+```
+
+**Available transaction filters:**
+
+- `sentAddress` - Filter by sender address
+- `affectedAddress` - Filter by any address involved in the transaction
+- `affectedObject` - Filter by object ID that was affected
+- `function` - Filter by Move function called (e.g., `0x2::coin::transfer`)
+- `kind` - Filter by transaction kind (`SYSTEM` or `PROGRAMMABLE`)
+- `atCheckpoint` / `beforeCheckpoint` / `afterCheckpoint` - Filter by checkpoint
+
+### Querying Events
+
+Replace `queryEvents` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query QueryEvents($type: String, $first: Int, $after: String) {
+      events(
+        first: $first
+        after: $after
+        filter: { type: $type }
+      ) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          transactionModule {
+            package { address }
+            name
+          }
+          sender { address }
+          contents {
+            type { repr }
+            bcs
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		type: '0x2::coin::CoinCreated',
+		first: 10,
+	},
+});
+```
+
+**Available event filters:**
+
+- `type` - Filter by event type (package, package::module, or full type)
+- `module` - Filter by emitting module
+- `sender` - Filter by transaction sender
+- `atCheckpoint` / `beforeCheckpoint` / `afterCheckpoint` - Filter by checkpoint
+
+### Fetching Multiple Transactions
+
+Replace `multiGetTransactionBlocks` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query MultiGetTransactions($digests: [String!]!) {
+      multiGetTransactionEffects(keys: $digests) {
+        transaction {
+          digest
+          transactionBcs
+        }
+        status
+        epoch { epochId }
+      }
+    }
+  `,
+	variables: {
+		digests: ['digest1', 'digest2', 'digest3'],
+	},
+});
+```
+
+### Querying Historical Objects
+
+Replace `tryGetPastObject` with a GraphQL query specifying a version:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query GetObjectAtVersion($id: HaneulAddress!, $version: UInt53!) {
+      object(address: $id, version: $version) {
+        address
+        version
+        digest
+        asMoveObject {
+          contents {
+            type { repr }
+            bcs
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		id: '0x123...',
+		version: 42,
+	},
+});
+```
+
+### Querying Coin Metadata
+
+Replace `getCoinMetadata` and `getTotalSupply` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query GetCoinMetadata($coinType: String!) {
+      coinMetadata(coinType: $coinType) {
+        name
+        symbol
+        description
+        decimals
+        iconUrl
+        supply
+      }
+    }
+  `,
+	variables: {
+		coinType: '0x2::haneul::HANEUL',
+	},
+});
+```
+
+### Querying Staked HANEUL
+
+Replace `getStakes` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query GetStakes($owner: HaneulAddress!) {
+      address(address: $owner) {
+        stakedHaneuls {
+          nodes {
+            principal
+            stakeActivationEpoch
+            estimatedReward
+            contents {
+              bcs
+            }
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		owner: '0xabc...',
+	},
+});
+```
+
+## Response Format Differences
+
+The gRPC client uses the core API response format, which differs from JSON-RPC responses. See the
+[@haneullabs/haneul migration guide](/haneul/migrations/haneul-2.0/haneul#transaction-executors-now-accept-any-client)
+for details on the new response format.
+
+Key differences:
+
+```diff
+// Transaction result access
+- const status = result.effects?.status?.status;
++ const tx = result.Transaction ?? result.FailedTransaction;
++ const status = tx.effects.status.success;
+
+// Include options
+- { showEffects: true, showEvents: true }
++ { effects: true, events: true }
+```
+
+## Client Extensions
+
+Client extensions work the same way with both clients:
+
+```typescript
+const client = new HaneulGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.haneul.io:443',
+	network: 'mainnet',
+}).$extend(deepbook({ address: myAddress }), haneulns());
+
+// Use extended functionality
+await client.deepbook.checkManagerBalance(manager, asset);
+await client.haneulns.getName('0xabc...');
+```
+
+## See Also
+
+- [HaneulGrpcClient Documentation](/haneul/clients/grpc) - Full gRPC client documentation
+- [HaneulGraphQLClient Documentation](/haneul/clients/graphql) - GraphQL client documentation
+- [Core API](/haneul/clients/core) - Transport-agnostic API methods
+- [gRPC Overview](https://docs.haneul.io/concepts/data-access/grpc-overview) - Haneul gRPC API
+  documentation

package/docs/migrations/haneul-2.0/kiosk.md

@@ -0,0 +1,120 @@
+# @haneullabs/kiosk
+
+> Migrate @haneullabs/kiosk to 2.0
+
+This package now exports a client extension that integrates with Haneul clients.
+
+> **Note:** The Kiosk SDK requires `HaneulJsonRpcClient` or `HaneulGraphQLClient`. It does not work
+> with `HaneulGrpcClient` because it uses event queries that are not available in gRPC.
+
+```diff
+- import { HaneulClient, getFullnodeUrl } from '@haneullabs/haneul/client';
+- import { KioskClient, Network } from '@haneullabs/kiosk';
++ import { HaneulJsonRpcClient, getJsonRpcFullnodeUrl } from '@haneullabs/haneul/jsonRpc'; // or HaneulGraphQLClient
++ import { kiosk } from '@haneullabs/kiosk';
+
+- const haneulClient = new HaneulClient({ url: getFullnodeUrl('mainnet') });
+- const kioskClient = new KioskClient({
+-   client: haneulClient,
+-   network: Network.MAINNET,
+- });
++ const client = new HaneulJsonRpcClient({
++   url: getJsonRpcFullnodeUrl('mainnet'),
++   network: 'mainnet',
++ }).$extend(kiosk());
+
+- const ownedKiosks = await kioskClient.getOwnedKiosks({ address: myAddress });
++ const ownedKiosks = await client.kiosk.getOwnedKiosks({ address: myAddress });
+```
+
+## Removed: transactionBlock Parameter
+
+The deprecated `transactionBlock` parameter has been removed from `KioskTransaction`,
+`TransferPolicyTransaction`, and rule resolving functions. Use `transaction` instead:
+
+```diff
+const kioskTx = new KioskTransaction({
+-  transactionBlock: tx,
++  transaction: tx,
+   kioskClient,
+   cap,
+});
+
+const tpTx = new TransferPolicyTransaction({
+-  transactionBlock: tx,
++  transaction: tx,
+   kioskClient,
+   cap,
+});
+```
+
+## Removed: Low-Level Helper Functions
+
+The low-level helper functions have been removed in favor of the `KioskTransaction` and
+`TransferPolicyTransaction` builder classes.
+
+### Kiosk Functions
+
+| Removed Function    | Use Instead              |
+| ------------------- | ------------------------ |
+| `createKiosk`       | `kioskTx.create()`       |
+| `shareKiosk`        | `kioskTx.share()`        |
+| `place`             | `kioskTx.place()`        |
+| `lock`              | `kioskTx.lock()`         |
+| `take`              | `kioskTx.take()`         |
+| `list`              | `kioskTx.list()`         |
+| `delist`            | `kioskTx.delist()`       |
+| `placeAndList`      | `kioskTx.placeAndList()` |
+| `purchase`          | `kioskTx.purchase()`     |
+| `withdrawFromKiosk` | `kioskTx.withdraw()`     |
+| `borrowValue`       | `kioskTx.borrow()`       |
+| `returnValue`       | `kioskTx.return()`       |
+
+### Transfer Policy Functions
+
+| Removed Function                     | Use Instead                                             |
+| ------------------------------------ | ------------------------------------------------------- |
+| `createTransferPolicyWithoutSharing` | `tpTx.create()`                                         |
+| `shareTransferPolicy`                | `tpTx.shareAndTransferCap()`                            |
+| `confirmRequest`                     | Handled automatically by `kioskTx.purchaseAndResolve()` |
+| `removeTransferPolicyRule`           | `tpTx.removeRule()`                                     |
+
+### Personal Kiosk Functions
+
+| Removed Function        | Use Instead                                   |
+| ----------------------- | --------------------------------------------- |
+| `convertToPersonalTx`   | `kioskTx.convertToPersonal()`                 |
+| `transferPersonalCapTx` | Handled automatically by `kioskTx.finalize()` |
+
+### Rule Attachment Functions
+
+| Removed Function            | Use Instead                   |
+| --------------------------- | ----------------------------- |
+| `attachKioskLockRuleTx`     | `tpTx.addLockRule()`          |
+| `attachRoyaltyRuleTx`       | `tpTx.addRoyaltyRule()`       |
+| `attachPersonalKioskRuleTx` | `tpTx.addPersonalKioskRule()` |
+| `attachFloorPriceRuleTx`    | `tpTx.addFloorPriceRule()`    |
+
+## Migration Example
+
+```diff
+- import { createKiosk, shareKiosk, placeAndList } from '@haneullabs/kiosk';
++ import { kiosk, KioskTransaction } from '@haneullabs/kiosk';
++ import { HaneulJsonRpcClient, getJsonRpcFullnodeUrl } from '@haneullabs/haneul/jsonRpc';
+
+- const [kiosk, cap] = createKiosk(tx);
+- shareKiosk(tx, kiosk);
+- placeAndList(tx, itemType, kiosk, cap, item, price);
+
++ const client = new HaneulJsonRpcClient({
++   url: getJsonRpcFullnodeUrl('mainnet'),
++   network: 'mainnet',
++ }).$extend(kiosk());
++
++ const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });
++ kioskTx
++   .create()
++   .placeAndList({ itemType, item, price })
++   .shareAndTransferCap(address)
++   .finalize();
+```

package/docs/migrations/haneul-2.0/sdk-maintainers.md

@@ -0,0 +1,91 @@
+# SDK Maintainers
+
+> Migration guide for SDK maintainers and library authors
+
+# Upgrading SDKs to @haneullabs/haneul@2.0.0
+
+This guide covers the key breaking changes for SDK maintainers building on top of
+`@haneullabs/haneul`.
+
+For comprehensive SDK development patterns, see the [Building SDKs guide](/haneul/sdk-building).
+
+## Use `ClientWithCoreApi`
+
+Accept `ClientWithCoreApi` instead of `HaneulClient` to support all 3 Haneul clients (JSON-RPC,
+GraphQL, gRPC):
+
+```diff
+- import { HaneulClient } from '@haneullabs/haneul/client';
++ import type { ClientWithCoreApi } from '@haneullabs/haneul/client';
+
+-   client: HaneulClient;
++   client: ClientWithCoreApi;
+}
+```
+
+## Access Data via `client.core` methods
+
+All data access methods are namespaced under `client.core`:
+
+```diff
+- const result = await this.client.getObject({ objectId });
++ const result = await this.client.core.getObject({ objectId });
+
+- const result = await this.client.getOwnedObjects({ owner });
++ const result = await this.client.core.listOwnedObjects({ owner });
+```
+
+| v1.x Method                      | v2.0 Method                       |
+| -------------------------------- | --------------------------------- |
+| `client.getObject()`             | `client.core.getObject()`         |
+| `client.getOwnedObjects()`       | `client.core.listOwnedObjects()`  |
+| `client.getDynamicFieldObject()` | `client.core.getDynamicField()`   |
+| `client.getDynamicFields()`      | `client.core.listDynamicFields()` |
+| `client.multiGetObjects()`       | `client.core.getObjects()`        |
+
+See the [Core API documentation](/haneul/clients/core) for all available methods.
+
+## Use Peer Dependencies
+
+Declare `@haneullabs/*` packages as peer dependencies:
+
+```json
+{
+	"peerDependencies": {
+		"@haneullabs/haneul": "^2.0.0"
+	},
+	"devDependencies": {
+		"@haneullabs/haneul": "^2.0.0"
+	}
+}
+```
+
+## Client Extensions
+
+v2.0 introduces client extensions that let users add your SDK to any Haneul client:
+
+```typescript
+
+	return {
+		name: 'mySDK',
+		register: (client: ClientWithCoreApi) => {
+			return new MySDKClient({ client });
+		},
+	};
+}
+
+// Users can then extend any client
+const client = new HaneulGrpcClient({ ... }).$extend(mySDK());
+await client.mySDK.doSomething();
+```
+
+See the [Building SDKs guide](/haneul/sdk-building#client-extensions) for the complete extension
+pattern.
+
+## Code Generation
+
+Use **[@haneullabs/codegen](/codegen)** to generate type-safe TypeScript bindings from your Move
+packages. See the [codegen documentation](/codegen) for setup instructions.
+
+For complete SDK development patterns including client extensions, transaction thunks, and best
+practices, see the [Building SDKs guide](/haneul/sdk-building).

package/docs/migrations/haneul-2.0/seal.md

@@ -0,0 +1,14 @@
+# @haneullabs/seal
+
+> Migrate @haneullabs/seal to 2.0
+
+The deprecated `SealClient.asClientExtension()` static method has been removed. Use the `seal()`
+registration function instead:
+
+```diff
+- import { SealClient } from '@haneullabs/seal';
++ import { seal } from '@haneullabs/seal';
+
+- const client = haneulClient.$extend(SealClient.asClientExtension());
++ const client = haneulClient.$extend(seal());
+```

package/docs/migrations/haneul-2.0/wallet-builders.md

@@ -0,0 +1,66 @@
+# Wallet Builders
+
+> Migration guide for wallet extension developers
+
+This guide covers the breaking changes for wallet builders implementing the
+`@haneullabs/wallet-standard` interface.
+
+## Key Changes
+
+### Removal of `haneul:reportTransactionEffects`
+
+The `haneul:reportTransactionEffects` feature has been removed entirely. If your wallet implements
+this feature, remove it.
+
+### New Core API Response Format
+
+The most significant change is how you obtain BCS-encoded effects for the
+`signAndExecuteTransaction` response. The new core API returns effects in a different structure.
+
+## Migrating `signAndExecuteTransaction`
+
+The wallet standard output format hasn't changed - what's different is how you obtain the BCS
+effects when using the new Haneul client APIs.
+
+```diff
+#signAndExecuteTransaction: HaneulSignAndExecuteTransactionMethod = async ({
+	transaction,
+	signal,
+}) => {
+-	const { bytes, signature } = await Transaction.from(
+-		await transaction.toJSON(),
+-	).sign({ client: haneulClient, signer: keypair });
+-
+-	const { rawEffects, digest } = await haneulClient.executeTransactionBlock({
+-		signature,
+-		transactionBlock: bytes,
+-		options: { showRawEffects: true },
+-	});
++	const parsedTransaction = Transaction.from(await transaction.toJSON());
++	const bytes = await parsedTransaction.build({ client });
++
++	const result = await this.#keypair.signAndExecuteTransaction({
++		transaction: parsedTransaction,
++		client,
++	});
++
++	const tx = result.Transaction ?? result.FailedTransaction;
+
+	return {
+-		bytes,
+-		signature,
+-		digest,
+-		effects: toBase64(new Uint8Array(rawEffects!)),
++		bytes: toBase64(bytes),
++		signature: tx.signatures[0],
++		digest: tx.digest,
++		effects: toBase64(tx.effects.bcs!),
+	};
+};
+```
+
+Key changes:
+
+- Use `signer.signAndExecuteTransaction()` instead of `haneulClient.executeTransactionBlock()`
+- Response is a union type - unwrap with `result.Transaction ?? result.FailedTransaction`
+- BCS effects are in `tx.effects.bcs` (Uint8Array) instead of `rawEffects` (number array)