@mysten/docs 0.1.1

package/dist/sui/migrations/sui-2.0/dapp-kit.md

@@ -0,0 +1,350 @@
+# @mysten/dapp-kit
+
+> Migrate @mysten/dapp-kit to 2.0
+
+This guide helps you migrate from the original `@mysten/dapp-kit` (legacy) to the new
+`@mysten/dapp-kit-react` package.
+
+> **Note:** The legacy `@mysten/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
+> `@mysten/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 `@mysten/dapp-kit-core` (framework-agnostic) and
+  `@mysten/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 @mysten/dapp-kit
+npm i @mysten/dapp-kit-react @mysten/dapp-kit-core @mysten/sui
+```
+
+### 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.sui.io:443',
+};
+
+	networks: ['testnet'],
+	createClient(network) {
+		return new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] });
+	},
+});
+
+// global type registration necessary for the hooks to work correctly
+declare module '@mysten/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 '@mysten/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 { SuiClientProvider, WalletProvider } from '@mysten/dapp-kit';
++ import { DAppKitProvider } from '@mysten/dapp-kit-react';
++ import { dAppKit } from './dapp-kit.ts';
+
+  export function App() {
+  	const queryClient = new QueryClient();
+- 	const networkConfig = {
+- 		mainnet: { url: 'https://mainnet.sui.io:443' },
+- 		testnet: { url: 'https://testnet.sui.io:443' },
+- 	};
+
+  	return (
+  		<QueryClientProvider client={queryClient}>
+- 			<SuiClientProvider networks={networkConfig} defaultNetwork="mainnet">
+- 				<WalletProvider>
+- 					<App />
+- 				</WalletProvider>
+- 			</SuiClientProvider>
++ 			<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 `useSuiClient`)
+- `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):
+
+- `useSuiClientQuery` -> Use `useCurrentClient()` with your data fetching solution
+- `useSuiClientMutation` -> Use `useCurrentClient()` with your data fetching solution
+- `useSuiClientInfiniteQuery` -> Use `useCurrentClient()` with your data fetching solution
+- `useSuiClientQueries` -> Use `useCurrentClient()` with your data fetching solution
+- `useResolveSuiNSNames` -> 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., `sui: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: 'sui:mainnet' });
++ const dAppKit = useDAppKit();
++ await dAppKit.signAndExecuteTransaction({ transaction, network: 'mainnet' });
+```
+
+**Mutation example:**
+
+```diff
+- import { useSignAndExecuteTransaction } from '@mysten/dapp-kit';
++ import { useMutation } from '@tanstack/react-query';
++ import { useDAppKit } from '@mysten/dapp-kit-react';
+  import type { Transaction } from '@mysten/sui/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 { useSuiClientQuery } from '@mysten/dapp-kit';
++ import { useQuery } from '@tanstack/react-query';
++ import { useCurrentClient } from '@mysten/dapp-kit-react';
+
+  export function ExampleComponent({ objectId }: { objectId: string }) {
++ 	const client = useCurrentClient();
++
+- 	const { data, isLoading, error } = useSuiClientQuery('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:
+
+- `useSuiClientQuery` → Use `useQuery` from `@tanstack/react-query`
+- `useSuiClientMutation` → Use `useMutation` from `@tanstack/react-query`
+- `useSuiClientInfiniteQuery` → Use `useInfiniteQuery` from `@tanstack/react-query`
+- `useResolveSuiNSNames` → Use `useCurrentClient()` with the suins extension
+
+> **Warning:** The `reportTransactionEffects` feature is planned for deprecation in the [Wallet
+> Standard](https://docs.sui.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 '@mysten/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/dist/sui/migrations/sui-2.0/deepbook-v3.md

@@ -0,0 +1,33 @@
+# @mysten/deepbook-v3
+
+> Migrate @mysten/deepbook-v3 to 2.0
+
+This package now exports a client extension that integrates with Sui clients.
+
+```diff
+- import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+- import { DeepBookClient } from '@mysten/deepbook-v3';
++ import { SuiGrpcClient } from '@mysten/sui/grpc'; // or SuiJsonRpcClient, SuiGraphQLClient
++ import { deepbook } from '@mysten/deepbook-v3';
+
+- const suiClient = new SuiClient({ url: getFullnodeUrl('mainnet') });
+- const deepBookClient = new DeepBookClient({
+-   client: suiClient,
+-   address: myAddress,
+-   env: 'mainnet',
+-   balanceManagers: { ... },
+- });
++ const client = new SuiGrpcClient({
++   baseUrl: 'https://fullnode.mainnet.sui.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);
+```

package/dist/sui/migrations/sui-2.0/index.md

@@ -0,0 +1,158 @@
+# Migrate to 2.0
+
+> Migration guide for Sui TypeScript SDK 2.0
+
+This guide covers the breaking changes across the latest release of all the `@mysten/*` packages.
+
+The primary goal of this release is to support the new GRPC and GraphQL APIs across all the mysten
+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, Mysten
+packages will now be published as ESM only packages.
+
+## Quick Reference
+
+| Package                                                               | Key Changes                                                                              |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| [@mysten/sui](/sui/migrations/sui-2.0/sui)                            | Client API stabilization, SuiClient removal, BCS schema alignment, transaction executors |
+| [@mysten/dapp-kit](/sui/migrations/sui-2.0/dapp-kit)                  | Complete rewrite with framework-agnostic core                                            |
+| [@mysten/kiosk](/sui/migrations/sui-2.0/kiosk)                        | Client extension pattern, low-level helpers removed, KioskTransaction pattern            |
+| [@mysten/zksend](/sui/migrations/sui-2.0/zksend)                      | Client extension pattern                                                                 |
+| [@mysten/suins](/sui/migrations/sui-2.0/suins)                        | Client extension pattern                                                                 |
+| [@mysten/deepbook-v3](/sui/migrations/sui-2.0/deepbook-v3)            | Client extension pattern                                                                 |
+| [@mysten/walrus](/sui/migrations/sui-2.0/walrus)                      | Client extension pattern, requires client instead of RPC URL                             |
+| [@mysten/seal](/sui/migrations/sui-2.0/seal)                          | Client extension pattern                                                                 |
+| [@mysten/wallet-standard](/sui/migrations/sui-2.0/wallet-builders)    | Removal of reportTransactionEffects, new core API response format                        |
+| [Migrating from JSON-RPC](/sui/migrations/sui-2.0/json-rpc-migration) | Migrate from deprecated JSON-RPC to gRPC and GraphQL                                     |
+
+## Common Migration Patterns
+
+### ESM Migration
+
+All `@mysten/*` 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., `@mysten/sui/client`,
+`@mysten/sui/transactions`).
+
+If you maintain a library that depends on any of the `@mysten/*` 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 `SuiClient` to `SuiJsonRpcClient`:
+
+```diff
+- import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
++ import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';
+
+- const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
++ const client = new SuiJsonRpcClient({
++   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 { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';
++ import { SuiGrpcClient } from '@mysten/sui/grpc';
+
+- const client = new SuiJsonRpcClient({ url, network: 'mainnet' });
++ const client = new SuiGrpcClient({ 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 SuiJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet', // Required
+});
+
+const graphqlClient = new SuiGraphQLClient({
+	url: 'https://sui-mainnet.mystenlabs.com/graphql',
+	network: 'mainnet', // Required
+});
+
+const grpcClient = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.sui.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 SuiJsonRpcClient({ url, network: 'mainnet' });
+const graphqlClient = new SuiGraphQLClient({ url, network: 'mainnet' });
+const grpcClient = new SuiGrpcClient({ baseUrl, network: 'mainnet' });
+```
+
+## Package-Specific Guides
+
+For detailed migration instructions, see the SDK-specific guides:
+
+- **[@mysten/sui](/sui/migrations/sui-2.0/sui)** - Core SDK changes including client API, BCS
+  schemas, transactions, zkLogin, and GraphQL
+- **[@mysten/dapp-kit](/sui/migrations/sui-2.0/dapp-kit)** - Complete migration guide for the new
+  dApp Kit architecture
+- **[@mysten/kiosk](/sui/migrations/sui-2.0/kiosk)** - Kiosk SDK now exports a client extension,
+  low-level helpers removed
+- **[@mysten/zksend](/sui/migrations/sui-2.0/zksend)** - zkSend SDK now exports a client extension
+- **[@mysten/suins](/sui/migrations/sui-2.0/suins)** - SuiNS now exports a client extension
+- **[@mysten/deepbook-v3](/sui/migrations/sui-2.0/deepbook-v3)** - DeepBook DEX now exports a client
+  extension
+- **[@mysten/walrus](/sui/migrations/sui-2.0/walrus)** - Walrus storage now exports a client
+  extension
+- **[@mysten/seal](/sui/migrations/sui-2.0/seal)** - Seal encryption now exports a client extension
+
+## Transport Migration
+
+- **[Migrating from JSON-RPC](/sui/migrations/sui-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 Sui ecosystem:
+
+- **[Wallet Builders](/sui/migrations/sui-2.0/wallet-builders)** - Guide for wallet implementations
+  adapting to `reportTransactionEffects` removal and new core API response format
+- **[SDK Maintainers](/sui/migrations/sui-2.0/sdk-maintainers)** - Guide for SDK authors migrating
+  to `ClientWithCoreApi` and the new transport-agnostic architecture