@haneullabs/haneul 2.5.1 → 2.13.0

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

@@ -0,0 +1,350 @@
+# @haneullabs/dapp-kit
+
+> Migrate @haneullabs/dapp-kit to 2.0
+
+This guide helps you migrate from the original `@haneullabs/dapp-kit` (legacy) to the new
+`@haneullabs/dapp-kit-react` package.
+
+> **Note:** The legacy `@haneullabs/dapp-kit` package will continue to work with the latest SDK, but
+> it only supports JSON-RPC and will not receive further updates. We recommend migrating to
+> `@haneullabs/dapp-kit-react` for new features and gRPC support.
+
+## Overview
+
+The new dApp Kit SDK represents a complete rewrite with these key changes:
+
+- **Framework agnostic**: Split into `@haneullabs/dapp-kit-core` (framework-agnostic) and
+  `@haneullabs/dapp-kit-react` (React bindings)
+- **No React Query dependency**: Direct promise-based API instead of mutation hooks
+- **Web Components**: UI components built with Lit Elements for cross-framework compatibility
+- **Smaller bundle size**: No React Query dependency, lighter state management with nanostores
+- **Better SSR support**: Compatible with SSR frameworks like Next.js
+- **Cross-framework compatibility**: Core functionality can be used in vanilla JS, Vue, React, and
+  other frameworks
+
+## Step-by-Step Migration
+
+### 1. Update Dependencies
+
+Remove the old package and install the new ones:
+
+```bash
+npm uninstall @haneullabs/dapp-kit
+npm i @haneullabs/dapp-kit-react @haneullabs/dapp-kit-core @haneullabs/haneul
+```
+
+### 2. Create dApp Kit Instance
+
+Create a new instance of the dApp Kit using the `createDAppKit` function and register the global
+type.
+
+```tsx
+// dapp-kit.ts
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.haneul.io:443',
+};
+
+	networks: ['testnet'],
+	createClient(network) {
+		return new HaneulGrpcClient({ network, baseUrl: GRPC_URLS[network] });
+	},
+});
+
+// global type registration necessary for the hooks to work correctly
+declare module '@haneullabs/dapp-kit-react' {
+	interface Register {
+		dAppKit: typeof dAppKit;
+	}
+}
+```
+
+### 3. Register Types
+
+The `declare module` block in the previous step registers your dApp Kit instance's type globally.
+This enables all hooks like `useDAppKit()`, `useCurrentNetwork()`, and `useCurrentClient()` to
+automatically infer the correct types based on your configuration (e.g., your specific networks and
+client type).
+
+```tsx
+declare module '@haneullabs/dapp-kit-react' {
+	interface Register {
+		dAppKit: typeof dAppKit;
+	}
+}
+```
+
+Without this registration, hooks return generic types and you lose type safety for things like
+network names. If you prefer not to use global type registration, you can pass the `dAppKit`
+instance explicitly to each hook instead:
+
+```tsx
+const connection = useWalletConnection({ dAppKit });
+const network = useCurrentNetwork({ dAppKit });
+```
+
+### 4. Replace Provider Setup
+
+Replace the nested dApp Kit providers with a single unified provider. You can keep your existing
+`QueryClientProvider` for data fetching.
+
+```diff
+  // App.tsx
+  import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+- import { HaneulClientProvider, WalletProvider } from '@haneullabs/dapp-kit';
++ import { DAppKitProvider } from '@haneullabs/dapp-kit-react';
++ import { dAppKit } from './dapp-kit.ts';
+
+  export function App() {
+  	const queryClient = new QueryClient();
+- 	const networkConfig = {
+- 		mainnet: { url: 'https://mainnet.haneul.io:443' },
+- 		testnet: { url: 'https://testnet.haneul.io:443' },
+- 	};
+
+  	return (
+  		<QueryClientProvider client={queryClient}>
+- 			<HaneulClientProvider networks={networkConfig} defaultNetwork="mainnet">
+- 				<WalletProvider>
+- 					<App />
+- 				</WalletProvider>
+- 			</HaneulClientProvider>
++ 			<DAppKitProvider dAppKit={dAppKit}>
++ 				<App />
++ 			</DAppKitProvider>
+  		</QueryClientProvider>
+  	);
+  }
+```
+
+### 5. Configuration Option Changes
+
+The `createDAppKit` function has different configuration options than the old `WalletProvider`:
+
+| Old (`WalletProvider`) | New (`createDAppKit`) | Notes                                                                |
+| ---------------------- | --------------------- | -------------------------------------------------------------------- |
+| -                      | `networks` (required) | List of network identifiers your app supports                        |
+| -                      | `createClient`        | Function to create a client for each network                         |
+| -                      | `defaultNetwork`      | Network to use by default (defaults to first in `networks`)          |
+| `autoConnect` (false)  | `autoConnect` (true)  | Default changed from `false` to `true`                               |
+| `enableUnsafeBurner`   | `enableBurnerWallet`  | Renamed                                                              |
+| `slushWallet`          | `slushWalletConfig`   | Renamed                                                              |
+| `storage`              | `storage`             | Unchanged                                                            |
+| `storageKey`           | `storageKey`          | Unchanged                                                            |
+| `preferredWallets`     | -                     | Removed                                                              |
+| `walletFilter`         | -                     | Removed (wallets filtered by network compatibility)                  |
+| `theme`                | -                     | Removed (UI components are now web components with built-in styling) |
+| -                      | `walletInitializers`  | New option for registering custom wallets                            |
+
+### 6. Update Hook Usage
+
+The new dApp Kit has a dramatically simplified hook API. Most hooks from the original version have
+been replaced with direct action calls through `useDAppKit()`.
+
+**Available hooks in the new version:**
+
+- `useDAppKit()` - Access the dAppKit instance for calling actions
+- `useCurrentClient()` - Get the blockchain client (renamed from `useHaneulClient`)
+- `useCurrentAccount()` - Get the current connected account
+- `useCurrentWallet()` - Get the current connected wallet
+- `useWallets()` - Get the list of available wallets
+- `useWalletConnection()` - Get the current wallet connection status
+- `useCurrentNetwork()` - Get the current network
+
+**Removed hooks:**
+
+All wallet action hooks have been replaced with direct action calls via `useDAppKit()`:
+
+- `useConnectWallet` -> Use `dAppKit.connectWallet()`
+- `useDisconnectWallet` -> Use `dAppKit.disconnectWallet()`
+- `useSignTransaction` -> Use `dAppKit.signTransaction()`
+- `useSignAndExecuteTransaction` -> Use `dAppKit.signAndExecuteTransaction()`
+- `useSignPersonalMessage` -> Use `dAppKit.signPersonalMessage()`
+- `useSwitchAccount` -> Use `dAppKit.switchAccount()`
+
+All data fetching hooks have been removed (giving you flexibility to use your preferred solution):
+
+- `useHaneulClientQuery` -> Use `useCurrentClient()` with your data fetching solution
+- `useHaneulClientMutation` -> Use `useCurrentClient()` with your data fetching solution
+- `useHaneulClientInfiniteQuery` -> Use `useCurrentClient()` with your data fetching solution
+- `useHaneulClientQueries` -> Use `useCurrentClient()` with your data fetching solution
+- `useResolveHaneulNSNames` -> Use `useCurrentClient()` directly
+
+Other removed hooks:
+
+- `useAutoConnectWallet` -> Auto-connect is enabled by default
+- `useAccounts` -> Use `useWalletConnection()` to access `connection.wallet.accounts`
+- `useWalletStore` -> Use specific hooks like `useWalletConnection()` instead
+
+### 7. Replace Mutation Patterns
+
+The built-in mutation hooks have been removed. Use TanStack Query's `useMutation` with
+`useDAppKit()` to get similar functionality.
+
+**Chain parameter replaced with network:**
+
+In the old dapp-kit, you could optionally pass a `chain` parameter (e.g., `haneul:mainnet`) to
+methods like `signTransaction` and `signAndExecuteTransaction`. In the new dapp-kit, use the
+`network` parameter instead - the chain is automatically derived from the network.
+
+```diff
+- const { mutateAsync: signAndExecute } = useSignAndExecuteTransaction();
+- await signAndExecute({ transaction, chain: 'haneul:mainnet' });
++ const dAppKit = useDAppKit();
++ await dAppKit.signAndExecuteTransaction({ transaction, network: 'mainnet' });
+```
+
+**Mutation example:**
+
+```diff
+- import { useSignAndExecuteTransaction } from '@haneullabs/dapp-kit';
++ import { useMutation } from '@tanstack/react-query';
++ import { useDAppKit } from '@haneullabs/dapp-kit-react';
+  import type { Transaction } from '@haneullabs/haneul/transactions';
+
+  export function ExampleComponent({ transaction }: { transaction: Transaction }) {
+- 	const { mutateAsync: signAndExecute } = useSignAndExecuteTransaction();
++ 	const dAppKit = useDAppKit();
++
++ 	const { mutateAsync: signAndExecute } = useMutation({
++ 		mutationFn: (tx: Transaction) => dAppKit.signAndExecuteTransaction({ transaction: tx }),
++ 	});
+
+  	const handleClick = async () => {
+- 		await signAndExecute(
+- 			{ transaction },
+- 			{
+- 				onSuccess: (result: any) => console.log(result),
+- 				onError: (error: any) => console.error(error),
+- 			},
+- 		);
++ 		await signAndExecute(transaction, {
++ 			onSuccess: (result) => console.log(result),
++ 			onError: (error) => console.error(error),
++ 		});
+  	};
+
+  	return <button onClick={handleClick}>Sign and Execute</button>;
+  }
+```
+
+**Alternative: Direct promise-based calls**
+
+If you don't need React Query's state management, you can call `dAppKit` methods directly:
+
+```tsx
+
+	const dAppKit = useDAppKit();
+
+	const handleClick = async () => {
+		try {
+			const result = await dAppKit.signAndExecuteTransaction({ transaction });
+			console.log(result);
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
+	return <button onClick={handleClick}>Sign and Execute</button>;
+}
+```
+
+### 8. Replace Data Fetching Patterns
+
+The built-in data fetching hooks have been removed. Use TanStack Query's `useQuery` with
+`useCurrentClient()` to get similar functionality:
+
+```diff
+- import { useHaneulClientQuery } from '@haneullabs/dapp-kit';
++ import { useQuery } from '@tanstack/react-query';
++ import { useCurrentClient } from '@haneullabs/dapp-kit-react';
+
+  export function ExampleComponent({ objectId }: { objectId: string }) {
++ 	const client = useCurrentClient();
++
+- 	const { data, isLoading, error } = useHaneulClientQuery('getObject', {
+- 		id: objectId,
+- 	});
++ 	const { data, isLoading, error } = useQuery({
++ 		queryKey: ['object', objectId],
++ 		queryFn: () => client.core.getObject({ objectId }),
++ 	});
+  	// ...
+  }
+```
+
+**Alternative: Direct data fetching**
+
+If you don't need React Query's caching and state management, you can fetch data directly:
+
+```tsx
+
+	const client = useCurrentClient();
+	const [data, setData] = useState(null);
+	const [isLoading, setIsLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+
+	useEffect(() => {
+		client.core
+			.getObject({ objectId })
+			.then((result) => setData(result.object ?? null))
+			.catch((err) => setError(err.message))
+			.finally(() => setIsLoading(false));
+	}, [client, objectId]);
+	// ...
+}
+```
+
+### 9. Update The Remaining Code
+
+The following hooks from the original dApp Kit are not available anymore:
+
+- `useHaneulClientQuery` → Use `useQuery` from `@tanstack/react-query`
+- `useHaneulClientMutation` → Use `useMutation` from `@tanstack/react-query`
+- `useHaneulClientInfiniteQuery` → Use `useInfiniteQuery` from `@tanstack/react-query`
+- `useResolveHaneulNSNames` → Use `useCurrentClient()` with the haneulns extension
+
+> **Warning:** The `reportTransactionEffects` feature is planned for deprecation in the
+> [Wallet Standard](https://docs.haneul.io/standards/wallet-standard) and so the dApp Kit provides
+> no replacement.
+
+The following have been removed:
+
+- `useReportTransactionEffects` hook
+- `reportTransactionEffects` callback from `useSignTransaction`
+- Automatic transaction effects reporting from `useSignAndExecuteTransaction`
+
+## CSS and Theming Changes
+
+The new dApp Kit no longer bundles a CSS file. If you were importing the old CSS file, remove the
+import:
+
+```diff
+- import '@haneullabs/dapp-kit/dist/full/index.css';
+```
+
+The new dApp Kit uses web components with built-in styling that can be customized using CSS custom
+properties. See the [Theming documentation](/dapp-kit/theming) for details on customizing the
+appearance of dApp Kit components.
+
+**Quick theme setup:**
+
+```css
+:root {
+	--primary: #4f46e5;
+	--primary-foreground: #ffffff;
+	--background: #ffffff;
+	--foreground: #0f172a;
+	--border: #e2e8f0;
+	--radius: 0.5rem;
+}
+```
+
+## Removing TanStack Query
+
+If you were only using `@tanstack/react-query` for dApp Kit and don't need it for other parts of
+your application, you can now remove it:
+
+```bash
+npm uninstall @tanstack/react-query
+```

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

@@ -0,0 +1,33 @@
+# @haneullabs/deepbook-v3
+
+> Migrate @haneullabs/deepbook-v3 to 2.0
+
+This package now exports a client extension that integrates with Haneul clients.
+
+```diff
+- import { HaneulClient, getFullnodeUrl } from '@haneullabs/haneul/client';
+- import { DeepBookClient } from '@haneullabs/deepbook-v3';
++ import { HaneulGrpcClient } from '@haneullabs/haneul/grpc'; // or HaneulJsonRpcClient, HaneulGraphQLClient
++ import { deepbook } from '@haneullabs/deepbook-v3';
+
+- const haneulClient = new HaneulClient({ url: getFullnodeUrl('mainnet') });
+- const deepBookClient = new DeepBookClient({
+-   client: haneulClient,
+-   address: myAddress,
+-   env: 'mainnet',
+-   balanceManagers: { ... },
+- });
++ const client = new HaneulGrpcClient({
++   baseUrl: 'https://fullnode.mainnet.haneul.io:443',
++   network: 'mainnet',
++ }).$extend(
++   deepbook({
++     address: myAddress,
++     // network is auto-detected from the client
++     balanceManagers: { ... },
++   }),
++ );
+
+- await deepBookClient.checkManagerBalance(manager, asset);
++ await client.deepbook.checkManagerBalance(manager, asset);
+```