@haneullabs/haneul 2.5.2 → 2.13.0

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

@@ -0,0 +1,341 @@
+# @haneullabs/haneul
+
+> Migrate @haneullabs/haneul from 1.x to 2.0
+
+## Removal of HaneulClient Exports
+
+The `@haneullabs/haneul/client` export path has been removed. All JSON-RPC client functionality is
+now exported from `@haneullabs/haneul/jsonRpc`.
+
+**Removed exports:**
+
+- `HaneulClient` (use `HaneulJsonRpcClient` instead)
+- `HaneulClientOptions` (use `HaneulJsonRpcClientOptions` instead)
+- `isHaneulClient` (use `isHaneulJsonRpcClient` instead)
+- `HaneulTransport` (use `JsonRpcTransport` instead)
+- `HaneulTransportRequestOptions` (use `JsonRpcTransportRequestOptions` instead)
+- `HaneulTransportSubscribeOptions` (use `JsonRpcTransportSubscribeOptions` instead)
+- `HaneulHTTPTransportOptions` (use `JsonRpcHTTPTransportOptions` instead)
+- `HaneulHTTPTransport` (use `JsonRpcHTTPTransport` instead)
+- `getFullnodeUrl` (use `getJsonRpcFullnodeUrl` instead)
+- All JSON-RPC types (now exported from `@haneullabs/haneul/jsonRpc`)
+
+**Migration:**
+
+```diff
+- import { HaneulClient, getFullnodeUrl } from '@haneullabs/haneul/client';
++ import { HaneulJsonRpcClient, getJsonRpcFullnodeUrl } from '@haneullabs/haneul/jsonRpc';
+
+- const client = new HaneulClient({
+-   url: getFullnodeUrl('devnet'),
++ const client = new HaneulJsonRpcClient({
++   url: getJsonRpcFullnodeUrl('devnet'),
+    network: 'devnet',
+  });
+```
+
+## Network Parameter Required
+
+When creating a new `HaneulGraphQLClient` or `HaneulJsonRpcClient`, you must now provide a `network`
+parameter:
+
+```ts
+const client = new HaneulGraphQLClient({
+	url: 'https://...',
+	network: 'mainnet', // Required
+});
+
+const client = new HaneulJsonRpcClient({
+	url: 'https://...',
+	network: 'mainnet', // Required
+});
+```
+
+## BCS Schema Changes
+
+Several BCS schemas in `@haneullabs/haneul/bcs` have been updated to align exactly with the Rust
+implementation. These changes affect serialization and deserialization of transaction effects and
+objects.
+
+### ExecutionStatus Changes
+
+**BCS Schema** (when parsing raw effects): The variant was renamed from `Failed` to `Failure`:
+
+```diff
+- effects.status.Failed.error
++ effects.status.Failure.error
+```
+
+**Core API** (gRPC/GraphQL responses): Uses a simplified structure with a `success` boolean:
+
+```typescript
+// Core API returns this structure
+const result = await client.core.getTransaction({ digest, include: { effects: true } });
+const tx = result.Transaction ?? result.FailedTransaction;
+
+if (tx.effects.status.success) {
+	// Transaction succeeded
+} else {
+	const error = tx.effects.status.error;
+}
+```
+
+### Object BCS Schema Changes
+
+Several changes to object BCS schemas:
+
+```diff
+// Renamed Owner enum variant
+const owner = {
+-  ConsensusV2: { owner: addr, startVersion: 1 }
++  ConsensusAddressOwner: { startVersion: 1, owner: addr }
+};
+
+// Renamed Data enum variant
+const data = {
+-  MoveObject: { ... }
++  Move: { ... }
+};
+
+// Renamed exported schema
+- import { ObjectBcs } from '@haneullabs/haneul/bcs';
++ import { bcs } from '@haneullabs/haneul/bcs';
+- const bytes = ObjectBcs.serialize(obj);
++ const bytes = bcs.Object.serialize(obj);
+```
+
+**This affects serialization.** Any existing serialized data with `ConsensusV2` will need to be
+re-serialized with the new `ConsensusAddressOwner` variant.
+
+### UnchangedSharedKind to UnchangedConsensusKind
+
+Transaction effects field renamed:
+
+```diff
+// Field name change
+- effects.unchangedSharedObjects
++ effects.unchangedConsensusObjects
+```
+
+**Removed variants:** `MutateDeleted`, `ReadDeleted`
+
+**New variants:** `MutateConsensusStreamEnded`, `ReadConsensusStreamEnded`, `Cancelled`,
+`PerEpochConfig`
+
+## Experimental Client API Stabilization
+
+The experimental client API has been stabilized and moved from `@haneullabs/haneul/experimental` to
+`@haneullabs/haneul/client`. All `Experimental_` prefixes have been removed.
+
+**Breaking changes:**
+
+- The `@haneullabs/haneul/experimental` module has been removed
+- All `Experimental_` prefixed types and classes have been renamed
+- Client types namespace changed from `Experimental_HaneulClientTypes` to `HaneulClientTypes`
+
+**Migration:**
+
+```diff
+- import {
+-   Experimental_BaseClient,
+-   Experimental_CoreClient,
+-   type Experimental_HaneulClientTypes,
+-   type Experimental_CoreClientOptions,
+- } from '@haneullabs/haneul/experimental';
++ import {
++   BaseClient,
++   CoreClient,
++   type HaneulClientTypes,
++   type CoreClientOptions,
++ } from '@haneullabs/haneul/client';
+
+// Update class extensions
+- class MyClient extends Experimental_CoreClient {
++ class MyClient extends CoreClient {
+    async getObjects(
+-     options: Experimental_HaneulClientTypes.GetObjectsOptions,
+-   ): Promise<Experimental_HaneulClientTypes.GetObjectsResponse> {
++     options: HaneulClientTypes.GetObjectsOptions,
++   ): Promise<HaneulClientTypes.GetObjectsResponse> {
+      // ...
+    }
+  }
+```
+
+**Common renames:**
+
+| Old Name                         | New Name            |
+| -------------------------------- | ------------------- |
+| `Experimental_BaseClient`        | `BaseClient`        |
+| `Experimental_CoreClient`        | `CoreClient`        |
+| `Experimental_HaneulClientTypes` | `HaneulClientTypes` |
+| `Experimental_CoreClientOptions` | `CoreClientOptions` |
+
+## Commands Renamed to TransactionCommands
+
+The `Commands` type exported from `@haneullabs/haneul/transactions` has been renamed to
+`TransactionCommands` because `Commands` is a reserved keyword in React Native.
+
+```diff
+- import { Commands } from '@haneullabs/haneul/transactions';
++ import { TransactionCommands } from '@haneullabs/haneul/transactions';
+
+- const coin = tx.add(Commands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
++ const coin = tx.add(TransactionCommands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
+
+- tx.add(Commands.TransferObjects([coin], recipient));
++ tx.add(TransactionCommands.TransferObjects([coin], recipient));
+```
+
+## GraphQL Schema Consolidation
+
+The SDK now exports a single unified GraphQL schema instead of multiple versioned schemas.
+
+**Removed exports:**
+
+- `@haneullabs/haneul/graphql/schemas/2024.1`
+- `@haneullabs/haneul/graphql/schemas/2024.4`
+- `@haneullabs/haneul/graphql/schemas/latest`
+
+**Migration:**
+
+```diff
+- import { graphql } from '@haneullabs/haneul/graphql/schemas/latest';
+- import { graphql } from '@haneullabs/haneul/graphql/schemas/2024.4';
+- import { graphql } from '@haneullabs/haneul/graphql/schemas/2024.1';
++ import { graphql } from '@haneullabs/haneul/graphql/schema';
+```
+
+## Named Packages Plugin Removed
+
+The `namedPackagesPlugin` and global plugin registry APIs have been removed. MVR (Move Registry)
+resolution is now built directly into the core client.
+
+**Removed:**
+
+- `namedPackagesPlugin` function
+- `NamedPackagesPluginOptions` type (from `@haneullabs/haneul/transactions`)
+- `Transaction.registerGlobalSerializationPlugin()` static method
+- `Transaction.unregisterGlobalSerializationPlugin()` static method
+- `Transaction.registerGlobalBuildPlugin()` static method
+- `Transaction.unregisterGlobalBuildPlugin()` static method
+
+**How it works now:**
+
+MVR name resolution happens automatically during transaction building. The SDK detects `.move` names
+(like `@org/package::module::Type`) and resolves them using the client's MVR resolver.
+
+**Migration:**
+
+```diff
+- import { Transaction, namedPackagesPlugin } from '@haneullabs/haneul/transactions';
+-
+- Transaction.registerGlobalSerializationPlugin(
+-   'namedPackages',
+-   namedPackagesPlugin({
+-     url: 'https://mainnet.mvr.haneul-labs.com',
+-     overrides: myOverrides,
+-   })
+- );
+
++ import { HaneulJsonRpcClient } from '@haneullabs/haneul/jsonRpc';
++ import type { NamedPackagesOverrides } from '@haneullabs/haneul/client';
++
++ const client = new HaneulJsonRpcClient({
++   url: 'https://fullnode.mainnet.haneul.io:443',
++   network: 'mainnet',
++   mvr: {
++     overrides: myOverrides,
++   },
++ });
+```
+
+## Transaction Executors Now Accept Any Client
+
+The transaction executor classes now accept any client implementing `ClientWithCoreApi` instead of
+requiring `HaneulJsonRpcClient` specifically.
+
+**Affected classes:**
+
+- `CachingTransactionExecutor`
+- `SerialTransactionExecutor`
+- `ParallelTransactionExecutor`
+
+**Breaking changes:**
+
+- Constructor `client` parameter type changed from `HaneulJsonRpcClient` to `ClientWithCoreApi`
+- Return type of `executeTransaction()`: `data` property renamed to `result`
+- The second parameter changed from JSON-RPC options to core API include options
+
+**Migration:**
+
+```diff
+
+- import { HaneulJsonRpcClient } from '@haneullabs/haneul/jsonRpc';
++ // Works with any client: HaneulJsonRpcClient, HaneulGrpcClient, or HaneulGraphQLClient
+
+const executor = new SerialTransactionExecutor({
+-   client: jsonRpcClient,
++   client, // Any ClientWithCoreApi-compatible client
+    signer,
+});
+
+const result = await executor.executeTransaction(tx);
+
+// Accessing the transaction result (changed)
+- console.log(result.data.effects?.status.status);
++ const tx = result.Transaction ?? result.FailedTransaction;
++ console.log(tx.effects.status.success);
+```
+
+Include options have also changed:
+
+```diff
+- const result = await executor.executeTransaction(tx, {
+-   showEffects: true,
+-   showEvents: true,
+- });
++ const result = await executor.executeTransaction(tx, {
++   effects: true,
++   events: true,
++ });
+```
+
+## ZkLogin Changes
+
+### legacyAddress Parameter Required
+
+The `legacyAddress` parameter is now **required** for all zkLogin address computation functions.
+
+**Migration (to preserve existing behavior):**
+
+```diff
+// computeZkLoginAddressFromSeed (previous default: true)
+- computeZkLoginAddressFromSeed(seed, iss)
++ computeZkLoginAddressFromSeed(seed, iss, true)
+
+// jwtToAddress (previous default: false)
+- jwtToAddress(jwt, userSalt)
++ jwtToAddress(jwt, userSalt, false)
+
+// computeZkLoginAddress (previous default: false)
+- computeZkLoginAddress({ claimName, claimValue, iss, aud, userSalt })
++ computeZkLoginAddress({ claimName, claimValue, iss, aud, userSalt, legacyAddress: false })
+
+// toZkLoginPublicIdentifier (no previous default)
+- toZkLoginPublicIdentifier(addressSeed, iss)
++ toZkLoginPublicIdentifier(addressSeed, iss, { legacyAddress: false })
+```
+
+## Default Transaction Expiration
+
+Transactions now default the expiration to the current epoch + 1 using `ValidDuring` when built with
+a client. This provides replay protection for all transactions without requiring explicit
+configuration.
+
+**To preserve the old behavior** (no expiration), explicitly set the expiration to `None`:
+
+```typescript
+const tx = new Transaction();
+tx.setExpiration({ None: true });
+```

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

@@ -0,0 +1,42 @@
+# @haneullabs/haneulns
+
+> Migrate @haneullabs/haneulns to 2.0
+
+This package now exports a client extension that integrates with Haneul clients.
+
+```diff
+- import { HaneulClient, getFullnodeUrl } from '@haneullabs/haneul/client';
+- import { HaneulnsClient } from '@haneullabs/haneulns';
++ import { HaneulGrpcClient } from '@haneullabs/haneul/grpc'; // or HaneulJsonRpcClient, HaneulGraphQLClient
++ import { haneulns } from '@haneullabs/haneulns';
+
+- const haneulClient = new HaneulClient({ url: getFullnodeUrl('mainnet') });
+- const haneulnsClient = new HaneulnsClient({
+-   client: haneulClient,
+-   network: 'mainnet',
+- });
++ const client = new HaneulGrpcClient({
++   baseUrl: 'https://fullnode.mainnet.haneul.io:443',
++   network: 'mainnet',
++ }).$extend(haneulns());
+
+- const nameRecord = await haneulnsClient.getNameRecord('example.haneul');
++ const nameRecord = await client.haneulns.getNameRecord('example.haneul');
+```
+
+## Custom Package IDs
+
+For custom deployments or networks other than mainnet/testnet, you can provide custom package info:
+
+```ts
+const customPackageInfo: PackageInfo = {
+	packageId: '0x...',
+	packageIdV1: '0x...',
+	// ... other required fields
+};
+
+const client = new HaneulGrpcClient({
+	baseUrl: 'http://localhost:9000',
+	network: 'localnet',
+}).$extend(haneulns({ packageInfo: customPackageInfo }));
+```

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

@@ -0,0 +1,161 @@
+# Migrate to 2.0
+
+> Migration guide for Haneul TypeScript SDK 2.0
+
+This guide covers the breaking changes across the latest release of all the `@haneullabs/*`
+packages.
+
+The primary goal of this release is to support the new GRPC and GraphQL APIs across all the
+haneullabs SDKs. These releases also include removals of deprecated APIs, some renaming for better
+consistency, and significant internal refactoring to improve maintainability. Starting with this
+release, Haneullabs packages will now be published as ESM only packages.
+
+## Quick Reference
+
+| Package                                                                      | Key Changes                                                                                 |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [@haneullabs/haneul](/haneul/migrations/haneul-2.0/haneul)                   | Client API stabilization, HaneulClient removal, BCS schema alignment, transaction executors |
+| [@haneullabs/dapp-kit](/haneul/migrations/haneul-2.0/dapp-kit)               | Complete rewrite with framework-agnostic core                                               |
+| [@haneullabs/kiosk](/haneul/migrations/haneul-2.0/kiosk)                     | Client extension pattern, low-level helpers removed, KioskTransaction pattern               |
+| [@haneullabs/zksend](/haneul/migrations/haneul-2.0/zksend)                   | Client extension pattern                                                                    |
+| [@haneullabs/haneulns](/haneul/migrations/haneul-2.0/haneulns)               | Client extension pattern                                                                    |
+| [@haneullabs/deepbook-v3](/haneul/migrations/haneul-2.0/deepbook-v3)         | Client extension pattern                                                                    |
+| [@haneullabs/walrus](/haneul/migrations/haneul-2.0/walrus)                   | Client extension pattern, requires client instead of RPC URL                                |
+| [@haneullabs/seal](/haneul/migrations/haneul-2.0/seal)                       | Client extension pattern                                                                    |
+| [@haneullabs/wallet-standard](/haneul/migrations/haneul-2.0/wallet-builders) | Removal of reportTransactionEffects, new core API response format                           |
+| [Migrating from JSON-RPC](/haneul/migrations/haneul-2.0/json-rpc-migration)  | Migrate from deprecated JSON-RPC to gRPC and GraphQL                                        |
+
+## Common Migration Patterns
+
+### ESM Migration
+
+All `@haneullabs/*` packages are now ESM only. If your project does not already use ESM, you will
+need to add `"type": "module"` to your `package.json`:
+
+```json
+{
+	"type": "module"
+}
+```
+
+If you are using TypeScript with `moduleResolution` `"Node"`, `"Classic"`, or `"Node10"`, you will
+need to update your `tsconfig.json` to use `"NodeNext"`, `"Node16"`, or `"Bundler"`:
+
+```json
+{
+	"compilerOptions": {
+		"moduleResolution": "NodeNext",
+		"module": "NodeNext"
+	}
+}
+```
+
+This enables proper resolution of the SDK's subpath exports (e.g., `@haneullabs/haneul/client`,
+`@haneullabs/haneul/transactions`).
+
+If you maintain a library that depends on any of the `@haneullabs/*` packages, you may also need to
+update your library to be ESM only to ensure it works correctly everywhere.
+
+Applications using bundlers and recent Node.js versions (>=22) may still work when using `require`
+to load ESM packages, but we recommend migrating to ESM.
+
+**Why ESM only?** Many packages in the ecosystem (specifically critical cryptography dependencies)
+are now published as ESM only. Supporting CommonJS has prevented us from using the latest versions
+of these dependencies, making our SDKs harder to maintain and risking missing critical security
+updates.
+
+### Client Migration
+
+The most common change across all SDKs is migrating from `HaneulClient` to `HaneulJsonRpcClient`:
+
+```diff
+- import { HaneulClient, getFullnodeUrl } from '@haneullabs/haneul/client';
++ import { HaneulJsonRpcClient, getJsonRpcFullnodeUrl } from '@haneullabs/haneul/jsonRpc';
+
+- const client = new HaneulClient({ url: getFullnodeUrl('mainnet') });
++ const client = new HaneulJsonRpcClient({
++   url: getJsonRpcFullnodeUrl('mainnet'),
++   network: 'mainnet',
++ });
+```
+
+We also recommend moving from the deprecated JSON RPC Apis to the new gRPC API as soon as possible:
+
+```diff
+- import { HaneulJsonRpcClient } from '@haneullabs/haneul/jsonRpc';
++ import { HaneulGrpcClient } from '@haneullabs/haneul/grpc';
+
+- const client = new HaneulJsonRpcClient({ url, network: 'mainnet' });
++ const client = new HaneulGrpcClient({ baseUrl, network: 'mainnet' });
+```
+
+The gRPC runs on full nodes so in most cases you should be able to use the same URLs when migrating
+to gRPC.
+
+### Network Parameter Required
+
+All client constructors now require an explicit `network` parameter:
+
+```ts
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet', // Required
+});
+
+const graphqlClient = new HaneulGraphQLClient({
+	url: 'https://haneul-mainnet.haneul-labs.com/graphql',
+	network: 'mainnet', // Required
+});
+
+const grpcClient = new HaneulGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.haneul.io:443',
+	network: 'mainnet', // Required
+});
+```
+
+### ClientWithCoreApi Interface
+
+Many SDK methods now accept any client implementing `ClientWithCoreApi`, enabling use with JSON-RPC,
+GraphQL, or gRPC transports:
+
+```ts
+// All of these work with APIs that accept ClientWithCoreApi
+const jsonRpcClient = new HaneulJsonRpcClient({ url, network: 'mainnet' });
+const graphqlClient = new HaneulGraphQLClient({ url, network: 'mainnet' });
+const grpcClient = new HaneulGrpcClient({ baseUrl, network: 'mainnet' });
+```
+
+## Package-Specific Guides
+
+For detailed migration instructions, see the SDK-specific guides:
+
+- **[@haneullabs/haneul](/haneul/migrations/haneul-2.0/haneul)** - Core SDK changes including client
+  API, BCS schemas, transactions, zkLogin, and GraphQL
+- **[@haneullabs/dapp-kit](/haneul/migrations/haneul-2.0/dapp-kit)** - Complete migration guide for
+  the new dApp Kit architecture
+- **[@haneullabs/kiosk](/haneul/migrations/haneul-2.0/kiosk)** - Kiosk SDK now exports a client
+  extension, low-level helpers removed
+- **[@haneullabs/zksend](/haneul/migrations/haneul-2.0/zksend)** - zkSend SDK now exports a client
+  extension
+- **[@haneullabs/haneulns](/haneul/migrations/haneul-2.0/haneulns)** - HaneulNS now exports a client
+  extension
+- **[@haneullabs/deepbook-v3](/haneul/migrations/haneul-2.0/deepbook-v3)** - DeepBook DEX now
+  exports a client extension
+- **[@haneullabs/walrus](/haneul/migrations/haneul-2.0/walrus)** - Walrus storage now exports a
+  client extension
+- **[@haneullabs/seal](/haneul/migrations/haneul-2.0/seal)** - Seal encryption now exports a client
+  extension
+
+## Transport Migration
+
+- **[Migrating from JSON-RPC](/haneul/migrations/haneul-2.0/json-rpc-migration)** - Migrate from the
+  deprecated JSON-RPC client to gRPC and GraphQL
+
+## Ecosystem Migration Guides
+
+For wallet builders and SDK maintainers building on the Haneul ecosystem:
+
+- **[Wallet Builders](/haneul/migrations/haneul-2.0/wallet-builders)** - Guide for wallet
+  implementations adapting to `reportTransactionEffects` removal and new core API response format
+- **[SDK Maintainers](/haneul/migrations/haneul-2.0/sdk-maintainers)** - Guide for SDK authors
+  migrating to `ClientWithCoreApi` and the new transport-agnostic architecture