@mysten/dapp-kit-react 2.0.0 → 2.0.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import * as _mysten_dapp_kit_core5 from "@mysten/dapp-kit-core";
+import * as _mysten_dapp_kit_core0 from "@mysten/dapp-kit-core";
 import { DAppKit, DefaultExpectedDppKit, RegisteredDAppKit } from "@mysten/dapp-kit-core";
 import * as react0 from "react";
 import { PropsWithChildren } from "react";
@@ -7,7 +7,7 @@ import * as nanostores0 from "nanostores";
 export * from "@mysten/dapp-kit-core";
 
 //#region src/components/DAppKitProvider.d.ts
-declare const DAppKitContext: react0.Context<_mysten_dapp_kit_core5.DAppKit<any, _mysten_dapp_kit_core5.ClientWithCoreApi> | null>;
+declare const DAppKitContext: react0.Context<_mysten_dapp_kit_core0.DAppKit<any, _mysten_dapp_kit_core0.ClientWithCoreApi> | null>;
 type DAppKitProviderProps = PropsWithChildren<{
   dAppKit: DefaultExpectedDppKit;
 }>;
@@ -25,7 +25,7 @@ type UseWalletsOptions<TDAppKit extends DAppKit> = {
 };
 declare function useWallets<TDAppKit extends DAppKit<any> = RegisteredDAppKit>({
   dAppKit
-}?: UseWalletsOptions<TDAppKit>): _mysten_dapp_kit_core5.UiWallet[];
+}?: UseWalletsOptions<TDAppKit>): _mysten_dapp_kit_core0.UiWallet[];
 //#endregion
 //#region src/hooks/useWalletConnection.d.ts
 type UseWalletConnectionOptions<TDAppKit extends DAppKit<any>> = {
@@ -43,8 +43,8 @@ declare function useWalletConnection<TDAppKit extends DAppKit = RegisteredDAppKi
   readonly isReconnecting: false;
   readonly isDisconnected: true;
 } | {
-  readonly wallet: _mysten_dapp_kit_core5.UiWallet;
-  readonly account: _mysten_dapp_kit_core5.UiWalletAccount;
+  readonly wallet: _mysten_dapp_kit_core0.UiWallet;
+  readonly account: _mysten_dapp_kit_core0.UiWalletAccount;
   readonly status: "connected";
   readonly supportedIntents: string[];
   readonly isConnected: true;
@@ -61,8 +61,8 @@ declare function useWalletConnection<TDAppKit extends DAppKit = RegisteredDAppKi
   readonly isReconnecting: false;
   readonly isDisconnected: false;
 } | {
-  readonly wallet: _mysten_dapp_kit_core5.UiWallet;
-  readonly account: _mysten_dapp_kit_core5.UiWalletAccount;
+  readonly wallet: _mysten_dapp_kit_core0.UiWallet;
+  readonly account: _mysten_dapp_kit_core0.UiWalletAccount;
   readonly status: "reconnecting";
   readonly supportedIntents: string[];
   readonly isConnected: false;
@@ -77,7 +77,7 @@ type UseCurrentAccountOptions<TDAppKit extends DAppKit> = {
 };
 declare function useCurrentAccount<TDAppKit extends DAppKit<any> = RegisteredDAppKit>({
   dAppKit
-}?: UseCurrentAccountOptions<TDAppKit>): _mysten_dapp_kit_core5.UiWalletAccount | null;
+}?: UseCurrentAccountOptions<TDAppKit>): _mysten_dapp_kit_core0.UiWalletAccount | null;
 //#endregion
 //#region src/hooks/useCurrentWallet.d.ts
 type UseCurrentWalletOptions<TDAppKit extends DAppKit> = {
@@ -85,7 +85,7 @@ type UseCurrentWalletOptions<TDAppKit extends DAppKit> = {
 };
 declare function useCurrentWallet<TDAppKit extends DAppKit<any> = RegisteredDAppKit>({
   dAppKit
-}?: UseCurrentWalletOptions<TDAppKit>): _mysten_dapp_kit_core5.UiWallet | null;
+}?: UseCurrentWalletOptions<TDAppKit>): _mysten_dapp_kit_core0.UiWallet | null;
 //#endregion
 //#region src/hooks/useCurrentClient.d.ts
 type UseCurrentClientOptions<TDAppKit extends DAppKit<any>> = {

package/docs/actions/connect-wallet.md

@@ -0,0 +1,68 @@
+# Connect Wallet
+
+> Programmatically connect to a Sui wallet
+
+The dApp Kit SDK provides an action for wallet connection, allowing users to connect, disconnect,
+and switch between wallets and accounts.
+
+> The [Connect Button](../web-components/connect-button) Web Component provides a complete wallet
+> connection UI.
+
+## Usage
+
+> Auto-connect is enabled by default and will attempt to restore the previous wallet connection on
+> page reload. This provides a seamless user experience but can be
+> [disabled](../dapp-kit-instance#disabling-auto-connect) if needed.
+
+The `connectWallet` action prompts a wallet to connect and authorize accounts for your application:
+
+```typescript
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+// Connect to a specific wallet
+const result = await dAppKit.connectWallet({
+	wallet: myWallet, // UiWallet instance
+	account: myAccount, // Optional: specific account to select
+});
+
+console.log('Connected accounts:', result.accounts);
+```
+
+## Parameters
+
+- **`wallet`** - The `UiWallet` instance to connect to
+- **`account`** (optional) - A specific `UiWalletAccount` to set as the selected account. Defaults
+  to the first authorized account
+
+## Return Value
+
+Returns a `Promise` that resolves to an object containing:
+
+- **`accounts`** - Array of authorized `UiWalletAccount` instances
+
+## Example
+
+```typescript
+const wallets = dAppKit.stores.$wallets.get();
+
+const unsubscribe = dAppKit.stores.$connection.subscribe((connection) => {
+	if (connection.isConnected) {
+		console.log(`Connected account address: ${connection.account.address}`);
+	} else {
+		console.log({ connection });
+	}
+});
+
+if (wallets.length > 0) {
+	try {
+		const { accounts } = await dAppKit.connectWallet({
+			wallet: wallets[0],
+		});
+		console.log('Available accounts:', accounts);
+	} catch (error) {
+		console.error('Connection failed:', error);
+	}
+}
+```

package/docs/actions/disconnect-wallet.md

@@ -0,0 +1,37 @@
+# Disconnect Wallet
+
+> Programmatically disconnect from a Sui wallet
+
+The `disconnectWallet` action terminates the connection with the currently connected wallet.
+
+> The [Connect Button](../web-components/connect-button) Web Component provides a complete wallet
+> connection UI.
+
+## Usage
+
+> **Note:** The disconnect action clears the connection state locally and attempts to notify the
+> wallet. Even if the wallet notification fails, the local state is always cleared to ensure a clean
+> disconnection.
+>
+> Note that wallets may or may not implement the `disconnect` feature. Calling `disconnectWallet`
+> doesn't necessarily mean that the wallet accounts will be disconnected from the dApp within the
+> wallet itself - this is determined by each wallet's implementation.
+
+```typescript
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+await dAppKit.disconnectWallet();
+```
+
+## Parameters
+
+None.
+
+## Return Value
+
+Returns a `Promise` that resolves to `void` when the disconnection is complete.
+
+> The action may throw `WalletNotConnectedError` if no wallet is connected. However, wallet-specific
+> disconnect failures are logged but don't prevent the local connection state from being cleared.

package/docs/actions/sign-and-execute-transaction.md

@@ -0,0 +1,95 @@
+# Sign and Execute Transaction
+
+> Sign and execute a transaction using the connected wallet
+
+The `signAndExecuteTransaction` action prompts the connected wallet to sign and immediately execute
+a transaction on the Sui network. This is the most common way to execute transactions in your dApp.
+
+## Usage
+
+```typescript
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+const tx = new Transaction();
+// No need to manually set sender - it's done automatically
+tx.transferObjects([coinWithBalance({ balance: 123 })], '0xrecipient...');
+
+const result = await dAppKit.signAndExecuteTransaction({
+	transaction: tx,
+});
+
+if (result.FailedTransaction) {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+console.log('Transaction digest:', result.Transaction.digest);
+```
+
+## Parameters
+
+- **`transaction`** - `Transaction | string` - The transaction to sign and execute. Can be either a
+  Transaction instance or base64-encoded bcs bytes for the transaction.
+- **`signal`** (optional) - `AbortSignal` - An abort signal to cancel the transaction request.
+
+## Return Value
+
+Returns a `Promise` that resolves to a `TransactionResult` discriminated union:
+
+```typescript
+type TransactionResult =
+	| { $kind: 'Transaction'; Transaction: Transaction }
+	| { $kind: 'FailedTransaction'; FailedTransaction: Transaction };
+```
+
+The `Transaction` object contains:
+
+- **`digest`** - `string` - The transaction digest (unique identifier for the executed transaction)
+- **`signatures`** - `string[]` - The signatures as base64-encoded strings
+- **`epoch`** - `string | null` - The epoch in which the transaction was executed
+- **`status`** - `ExecutionStatus` - The execution status with `success: boolean` and
+  `error: string | null`
+- **`effects`** - `TransactionEffects | null` - The parsed transaction effects (may be `null` if
+  effects parsing fails for unknown effect versions)
+- **`transaction`** - `TransactionData` - The parsed transaction data
+
+```typescript
+const result = await dAppKit.signAndExecuteTransaction({ transaction });
+
+if (result.FailedTransaction) {
+	console.error('Transaction failed:', result.FailedTransaction.status.error?.message);
+	return;
+}
+
+// Access the successful transaction results
+const tx = result.Transaction;
+console.log('Digest:', tx.digest);
+console.log('Signatures:', tx.signatures);
+console.log('Epoch:', tx.epoch);
+```
+
+## Transaction Building
+
+When passing a Transaction instance, the action automatically:
+
+1. Sets the sender address if not already set
+2. Builds the transaction using the current network's client
+3. Converts it to the appropriate format for the wallet
+4. Submits the transaction to the network
+
+## Wallet Compatibility
+
+- The action transparently handles both `sui:signAndExecuteTransaction` and
+  `sui:signAndExecuteTransactionBlock` wallet-standard features
+- The wallet handles network submission and response
+- Some wallets (Enoki, Enoki Connect, WalletConnect) may use the dApp Kit client and execute
+  transactions within the application as an implementation detail
+
+```typescript
+// The action automatically detects and uses the appropriate method
+// No special configuration needed
+const result = await dAppKit.signAndExecuteTransaction({
+	transaction: tx,
+});
+```

package/docs/actions/sign-personal-message.md

@@ -0,0 +1,57 @@
+# Sign Personal Message
+
+> Sign an arbitrary message with the connected wallet
+
+The `signPersonalMessage` action prompts the connected wallet to sign a personal message. This is
+useful for authentication, proof of ownership, or other scenarios where you need cryptographic proof
+that a user controls a specific account.
+
+## Usage
+
+```typescript
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+const message = new TextEncoder().encode('Please sign this message');
+const result = await dAppKit.signPersonalMessage({
+	message,
+});
+
+console.log('Message bytes:', result.bytes);
+console.log('Signature:', result.signature);
+```
+
+## Parameters
+
+- **`message`** - `Uint8Array` - The message to sign as a byte array
+
+## Return Value
+
+Returns a `Promise` that resolves to an object containing:
+
+- **`bytes`** - `string` - Base64 encoded message bytes
+- **`signature`** - `string` - Base64 encoded signature
+
+## Message Format
+
+The message parameter must be a `Uint8Array`. Common patterns for creating byte arrays:
+
+```typescript
+const textMessage = new TextEncoder().encode('Hello, Sui!');
+await dAppKit.signPersonalMessage({ message: textMessage });
+
+const jsonMessage = new TextEncoder().encode(
+	JSON.stringify({ action: 'sign', timestamp: Date.now() }),
+);
+await dAppKit.signPersonalMessage({ message: jsonMessage });
+```
+
+## Security Considerations
+
+### Message Content
+
+- Always display the message content clearly to users before signing
+- Avoid signing opaque or encoded data that users cannot understand
+- Include human-readable prefixes for different message types
+- Consider adding timestamps to prevent replay attacks

package/docs/actions/sign-transaction.md

@@ -0,0 +1,64 @@
+# Sign Transaction
+
+> Sign a transaction without executing it
+
+The `signTransaction` action prompts the connected wallet to sign a transaction without executing
+it. This is useful when you need a signed transaction for later execution or for multi-signature
+scenarios.
+
+## Usage
+
+```typescript
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+const tx = new Transaction();
+// No need to manually set sender - it's done automatically
+tx.transferObjects([coinWithBalance({ balance: 123 })], '0xrecipient...');
+
+// Sign the transaction without executing it
+const { bytes, signature } = await dAppKit.signTransaction({
+	transaction: tx,
+});
+```
+
+## Parameters
+
+- **`transaction`** - `Transaction | string` - The transaction to sign. Can be either a Transaction
+  instance or base64-encoded bcs bytes for the transaction.
+- **`signal`** (optional) - `AbortSignal` - An abort signal to cancel the signing request.
+
+## Return Value
+
+Returns a `Promise` that resolves to an object containing:
+
+- **`bytes`** - `string` - The signed transaction as a base64-encoded BCS string
+- **`signature`** - `string` - The signature as a base64-encoded string
+
+```typescript
+const result = await dAppKit.signTransaction({ transaction });
+console.log('Signed transaction bytes:', result.bytes);
+console.log('Signature:', result.signature);
+```
+
+## Transaction Building
+
+When passing a Transaction instance, the action automatically:
+
+1. Sets the sender address if not already set
+2. Builds the transaction using the current network's client
+3. Converts it to the appropriate format for the wallet
+
+## Wallet Compatibility
+
+- The action transparently handles both `sui:signTransaction` and `sui:signTransactionBlock`
+  wallet-standard features
+
+```typescript
+// The action automatically detects and uses the appropriate method
+// No special configuration needed
+const result = await dAppKit.signTransaction({
+	transaction: tx,
+});
+```

package/docs/actions/switch-account.md

@@ -0,0 +1,36 @@
+# Switch Account
+
+> Switch the active account in the connected wallet
+
+The `switchAccount` action changes the currently selected account to a different account from the
+connected wallet.
+
+> **Note:** The "current account" is a dApp Kit concept that tracks which account is active within
+> your application. Changing the active account in the dApp does not affect the wallet itself, and
+> wallets are not notified when the active account changes.
+
+> Account switching is integrated into the [Connect Button](../web-components/connect-button) Web
+> Component. When a wallet is connected with multiple accounts, the button provides an account
+> selector.
+
+## Usage
+
+```typescript
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+// Switch to a different account
+dAppKit.switchAccount({
+	account: anotherAccount, // UiWalletAccount from the connected wallet
+});
+```
+
+## Parameters
+
+- **`account`** - `UiWalletAccount` - The account to switch to. Must be an account that belongs to
+  the currently connected wallet.
+
+## Return Value
+
+Returns `void`. The action completes synchronously and updates the connection state immediately.

package/docs/actions/switch-network.md

@@ -0,0 +1,36 @@
+# Switch Network
+
+> Switch the active network for the dApp Kit instance
+
+The `switchNetwork` action changes the currently selected network that the dApp Kit client is
+configured to use.
+
+> **Note:** Network switching only affects your dApp's client connection. The wallet itself is not
+> affected by this change, and wallets are not notified when the network changes in the dApp.
+
+## Usage
+
+```typescript
+const GRPC_URLS = {
+	mainnet: 'https://fullnode.mainnet.sui.io:443',
+	testnet: 'https://fullnode.testnet.sui.io:443',
+} as const;
+
+const dAppKit = createDAppKit({
+	networks: ['mainnet', 'testnet'],
+	defaultNetwork: 'mainnet',
+	createClient: (network) => new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] }),
+});
+
+// Switch to a different network
+dAppKit.switchNetwork('testnet');
+```
+
+## Parameters
+
+- **`network`** - `TNetworks[number]` - The network to switch to. Must be one of the networks
+  configured when creating the dApp Kit instance.
+
+## Return Value
+
+Returns `void`. The action completes synchronously and updates the network state immediately.

package/docs/dapp-kit-instance.md

@@ -0,0 +1,163 @@
+# DApp Kit Instance
+
+> Create and configure a DAppKit instance for wallet and client management
+
+The `createDAppKit` function is the foundation of your Sui dApp. It creates an instance that manages
+wallet connections, network configuration, and provides access to the Sui client.
+
+## Creating a dApp Kit Instance
+
+The core of the dApp Kit SDK is the `createDAppKit` function, which creates an instance that manages
+all dApp functionality:
+
+```typescript
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.sui.io:443',
+};
+
+	networks: ['testnet'],
+	createClient: (network) => new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] }),
+});
+```
+
+> **Note:** If you use the React bindings, there are two ways to ensure type safety with hooks:
+>
+> 1. [Register the global dAppKit type](./getting-started/react#1-create-a-dapp-kit-instance) once,
+>    and all hooks will be properly typed
+> 2. Pass the dAppKit instance explicitly to each hook: `useWalletConnection({ dAppKit })`
+
+This instance provides:
+
+- Wallet connection management
+- Network switching capabilities
+- Client access for blockchain interactions
+- State stores for reactive updates
+
+## Parameters
+
+- **autoConnect** (optional) - Enables automatically connecting to the most recently used wallet
+  account (default: `true`)
+- **networks** - A list of networks supported by the application (e.g. `['mainnet', 'testnet']`)
+- **defaultNetwork** (optional) - Initial network to use (default: first network in the array)
+- **createClient** - Creates a new client instance for the given network
+- **enableBurnerWallet** (optional) - Enable development-only burner wallet (default: `false`)
+- **storage** (optional) - Configures how the most recently connected to wallet account is stored
+  (default: `localStorage`, set to `null` to disable)
+- **storageKey** (optional) - The key to use to store the most recently connected wallet account
+  (default: `'mysten-dapp-kit:selected-wallet-and-address'`)
+- **walletInitializers** (optional) - A list of wallet initializers used for registering additional
+  wallet standard wallets.
+- **slushWalletConfig** (optional) - Configuration for Slush wallet (set to `null` to disable the
+  wallet)
+
+## Return Value
+
+```ts
+{
+    // Actions
+    connectWallet: (args: { wallet: UiWallet; account?: UiWalletAccount }) => Promise<{ accounts: UiWalletAccount[]; }>;
+    disconnectWallet: () => Promise<void>;
+    switchAccount: (args: { account: UiWalletAccount }) => Promise<void>;
+    switchNetwork: (network: string) => void;
+    signTransaction: (args: { transaction: Transaction | string; signal?: AbortSignal }) => Promise<SignedTransaction>;
+    signAndExecuteTransaction: (args: { transaction: Transaction | string; signal?: AbortSignal }) => Promise<TransactionResult>;
+    signPersonalMessage: (args: { message: Uint8Array }) => Promise<SignedPersonalMessage>;
+
+    // Properties
+    networks: string[];
+    stores:  {
+        $wallets: DAppKitStores['$compatibleWallets'];
+        $connection: DAppKitStores['$connection'];
+        $currentNetwork: ReadableAtom<TNetworks[number]>;
+        $currentClient: ReadableAtom<Client>;
+    };
+    getClient: (network?: string) => Client;
+}
+```
+
+Read more about [actions](./actions/connect-wallet) and [stores](./state).
+
+## Basic Usage
+
+```ts
+// dapp-kit.ts
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.sui.io:443',
+};
+
+	networks: ['testnet'],
+	createClient: (network) => new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] }),
+});
+```
+
+```ts
+// connect-wallet-and-log.ts
+
+	wallet,
+	account,
+}: {
+	wallet: UiWallet;
+	account: UiWalletAccount;
+}) {
+	const result = await dAppKit.connectWallet({
+		wallet,
+		account,
+	});
+	console.log('Connected accounts:', result.accounts);
+}
+```
+
+> If you use the React bindings, see [Getting Started in React](./getting-started/react) and
+> [DAppKitProvider](./react/dapp-kit-provider).
+
+## Development Configuration
+
+For development environments, enable the burner wallet:
+
+```typescript
+
+	networks: ['localnet'],
+	defaultNetwork: 'localnet',
+	createClient: () => new SuiGrpcClient({ network: 'localnet', baseUrl: 'http://127.0.0.1:9000' }),
+	enableBurnerWallet: true, // Dev-only feature
+});
+```
+
+## Auto-Connect Behavior
+
+By default, dApp Kit automatically reconnects to the previously connected wallet.
+
+### Disabling Auto-Connect
+
+```typescript
+
+	networks: ['mainnet'],
+	createClient: () =>
+		new SuiGrpcClient({ network: 'mainnet', baseUrl: 'https://fullnode.mainnet.sui.io:443' }),
+	autoConnect: false,
+});
+```
+
+## Custom Wallet Integration
+
+Add support for custom wallets using wallet initializers:
+
+```typescript
+
+	networks: ['mainnet'],
+	createClient: () =>
+		new SuiGrpcClient({ network: 'mainnet', baseUrl: 'https://fullnode.mainnet.sui.io:443' }),
+	walletInitializers: [
+		{
+			id: 'Custom Wallets',
+			initialize() {
+				const wallets = [new CustomWallet()];
+				const walletsApi = getWallets();
+				return { unregister: walletsApi.register(...wallets) };
+			},
+		},
+	],
+});
+```