@mysten/dapp-kit-react 2.0.2 → 2.1.0

package/dist/index.d.mts

@@ -2,7 +2,6 @@ import * as _mysten_dapp_kit_core5 from "@mysten/dapp-kit-core";
 import { DAppKit, DefaultExpectedDppKit, RegisteredDAppKit } from "@mysten/dapp-kit-core";
 import * as react0 from "react";
 import { PropsWithChildren } from "react";
-import * as react_jsx_runtime1 from "react/jsx-runtime";
 import * as nanostores0 from "nanostores";
 export * from "@mysten/dapp-kit-core";
 
@@ -14,7 +13,7 @@ type DAppKitProviderProps = PropsWithChildren<{
 declare function DAppKitProvider({
   dAppKit,
   children
-}: DAppKitProviderProps): react_jsx_runtime1.JSX.Element;
+}: DAppKitProviderProps): react0.JSX.Element;
 //#endregion
 //#region src/hooks/useDAppKit.d.ts
 declare function useDAppKit<TDAppKit extends DAppKit<any> = RegisteredDAppKit>(dAppKit?: TDAppKit): TDAppKit;

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/components/DAppKitProvider.tsx","../src/hooks/useDAppKit.ts","../src/hooks/useWallets.ts","../src/hooks/useWalletConnection.ts","../src/hooks/useCurrentAccount.ts","../src/hooks/useCurrentWallet.ts","../src/hooks/useCurrentClient.ts","../src/hooks/useCurrentNetwork.ts"],"mappings":";;;;;;;;;cAOa,cAAA,EAAc,MAAA,CAAA,OAAA,CAAA,sBAAA,CAAA,OAAA,MAAoD,sBAAA,CAApD,iBAAA;AAAA,KAEf,oBAAA,GAAuB,iBAAA;EAClC,OAAA,EAAS,qBAAA;AAAA;AAAA,iBAGM,eAAA,CAAA;EAAkB,OAAA;EAAS;AAAA,GAAY,oBAAA,GAAoB,kBAAA,CAAA,GAAA,CAAA,OAAA;;;iBCN3D,UAAA,kBAA4B,OAAA,QAAe,iBAAA,CAAA,CAAmB,OAAA,GAAU,QAAA,GAAQ,QAAA;;;KCApF,iBAAA,kBAAmC,OAAA;EAC9C,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,UAAA,kBAA4B,OAAA,QAAe,iBAAA,CAAA,CAAA;EAC1D;AAAA,IACE,iBAAA,CAAkB,QAAA,IAAD,sBAAA,CAAe,QAAA;;;KCNvB,0BAAA,kBAA4C,OAAA;EACvD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,mBAAA,kBAAqC,OAAA,GAAU,iBAAA,CAAA,CAAA;EAC9D;AAAA,IACE,0BAAA,CAA2B,QAAA;EAAA;;;;;;;;;mBAAD,sBAAA,CAAA,QAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;KCPjB,wBAAA,kBAA0C,OAAA;EACrD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,iBAAA,kBAAmC,OAAA,QAAe,iBAAA,CAAA,CAAA;EACjE;AAAA,IACE,wBAAA,CAAyB,QAAA,IAAD,sBAAA,CAAe,eAAA;;;KCN9B,uBAAA,kBAAyC,OAAA;EACpD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,gBAAA,kBAAkC,OAAA,QAAe,iBAAA,CAAA,CAAA;EAChE;AAAA,IACE,uBAAA,CAAwB,QAAA,IAAD,sBAAA,CAAe,QAAA;;;KCL7B,uBAAA,kBAAyC,OAAA;EACpD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,gBAAA,kBAAkC,OAAA,QAAe,iBAAA,CAAA,CAAA;EAChE;AAAA,IACE,uBAAA,CAAwB,QAAA,IAEyB,UAAA,CAAW,QAAA;;;KCRnD,wBAAA,kBAA0C,OAAA;EACrD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,iBAAA,kBAAmC,OAAA,QAAe,iBAAA,CAAA,CAAA;EACjE;AAAA,IACE,wBAAA,CAAyB,QAAA,IAAc,WAAA,CAAA,UAAA,CAAA,QAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/components/DAppKitProvider.tsx","../src/hooks/useDAppKit.ts","../src/hooks/useWallets.ts","../src/hooks/useWalletConnection.ts","../src/hooks/useCurrentAccount.ts","../src/hooks/useCurrentWallet.ts","../src/hooks/useCurrentClient.ts","../src/hooks/useCurrentNetwork.ts"],"mappings":";;;;;;;;cAOa,cAAA,EAAc,MAAA,CAAA,OAAA,CAAA,sBAAA,CAAA,OAAA,MAAoD,sBAAA,CAApD,iBAAA;AAAA,KAEf,oBAAA,GAAuB,iBAAA;EAClC,OAAA,EAAS,qBAAA;AAAA;AAAA,iBAGM,eAAA,CAAA;EAAkB,OAAA;EAAS;AAAA,GAAY,oBAAA,GAAoB,MAAA,CAAA,GAAA,CAAA,OAAA;;;iBCN3D,UAAA,kBAA4B,OAAA,QAAe,iBAAA,CAAA,CAAmB,OAAA,GAAU,QAAA,GAAQ,QAAA;;;KCApF,iBAAA,kBAAmC,OAAA;EAC9C,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,UAAA,kBAA4B,OAAA,QAAe,iBAAA,CAAA,CAAA;EAC1D;AAAA,IACE,iBAAA,CAAkB,QAAA,IAAD,sBAAA,CAAe,QAAA;;;KCNvB,0BAAA,kBAA4C,OAAA;EACvD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,mBAAA,kBAAqC,OAAA,GAAU,iBAAA,CAAA,CAAA;EAC9D;AAAA,IACE,0BAAA,CAA2B,QAAA;EAAA;;;;;;;;;mBAAD,sBAAA,CAAA,QAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;KCPjB,wBAAA,kBAA0C,OAAA;EACrD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,iBAAA,kBAAmC,OAAA,QAAe,iBAAA,CAAA,CAAA;EACjE;AAAA,IACE,wBAAA,CAAyB,QAAA,IAAD,sBAAA,CAAe,eAAA;;;KCN9B,uBAAA,kBAAyC,OAAA;EACpD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,gBAAA,kBAAkC,OAAA,QAAe,iBAAA,CAAA,CAAA;EAChE;AAAA,IACE,uBAAA,CAAwB,QAAA,IAAD,sBAAA,CAAe,QAAA;;;KCL7B,uBAAA,kBAAyC,OAAA;EACpD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,gBAAA,kBAAkC,OAAA,QAAe,iBAAA,CAAA,CAAA;EAChE;AAAA,IACE,uBAAA,CAAwB,QAAA,IAEyB,UAAA,CAAW,QAAA;;;KCRnD,wBAAA,kBAA0C,OAAA;EACrD,OAAA,GAAU,QAAA;AAAA;AAAA,iBAGK,iBAAA,kBAAmC,OAAA,QAAe,iBAAA,CAAA,CAAA;EACjE;AAAA,IACE,wBAAA,CAAyB,QAAA,IAAc,WAAA,CAAA,UAAA,CAAA,QAAA"}

package/dist/ui.d.mts

@@ -1,5 +1,5 @@
+import * as React from "react";
 import { ComponentProps } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
 import * as _lit_react0 from "@lit/react";
 import { DAppKitConnectButton, DAppKitConnectModal } from "@mysten/dapp-kit-core/web";
 
@@ -9,7 +9,7 @@ declare const ConnectButtonComponent: _lit_react0.ReactWebComponent<DAppKitConne
 declare function ConnectButton({
   instance,
   ...props
-}: ConnectButtonProps): react_jsx_runtime0.JSX.Element;
+}: ConnectButtonProps): React.JSX.Element;
 //#endregion
 //#region src/components/ConnectModal.d.ts
 type ConnectModalProps = ComponentProps<typeof ConnectModalComponent>;
@@ -17,7 +17,7 @@ declare const ConnectModalComponent: _lit_react0.ReactWebComponent<DAppKitConnec
 declare function ConnectModal({
   instance,
   ...props
-}: ConnectModalProps): react_jsx_runtime0.JSX.Element;
+}: ConnectModalProps): React.JSX.Element;
 //#endregion
 export { ConnectButton, type ConnectButtonProps, ConnectModal, type ConnectModalProps };
 //# sourceMappingURL=ui.d.mts.map

package/dist/ui.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.mts","names":[],"sources":["../src/components/ConnectButton.tsx","../src/components/ConnectModal.tsx"],"mappings":";;;;;;KASY,kBAAA,GAAqB,cAAA,QAAsB,sBAAA;AAAA,cAEjD,sBAAA,EAAsB,WAAA,CAAA,iBAAA,CAAA,oBAAA;AAAA,iBAMZ,aAAA,CAAA;EAAgB,QAAA;EAAA,GAAa;AAAA,GAAS,kBAAA,GAAkB,kBAAA,CAAA,GAAA,CAAA,OAAA;;;KCR5D,iBAAA,GAAoB,cAAA,QAAsB,qBAAA;AAAA,cAEhD,qBAAA,EAAqB,WAAA,CAAA,iBAAA,CAAA,mBAAA;AAAA,iBAMX,YAAA,CAAA;EAAe,QAAA;EAAA,GAAa;AAAA,GAAS,iBAAA,GAAiB,kBAAA,CAAA,GAAA,CAAA,OAAA"}
+{"version":3,"file":"ui.d.mts","names":[],"sources":["../src/components/ConnectButton.tsx","../src/components/ConnectModal.tsx"],"mappings":";;;;;;KASY,kBAAA,GAAqB,cAAA,QAAsB,sBAAA;AAAA,cAEjD,sBAAA,EAAsB,WAAA,CAAA,iBAAA,CAAA,oBAAA;AAAA,iBAMZ,aAAA,CAAA;EAAgB,QAAA;EAAA,GAAa;AAAA,GAAS,kBAAA,GAAkB,KAAA,CAAA,GAAA,CAAA,OAAA;;;KCR5D,iBAAA,GAAoB,cAAA,QAAsB,qBAAA;AAAA,cAEhD,qBAAA,EAAqB,WAAA,CAAA,iBAAA,CAAA,mBAAA;AAAA,iBAMX,YAAA,CAAA;EAAe,QAAA;EAAA,GAAa;AAAA,GAAS,iBAAA,GAAiB,KAAA,CAAA,GAAA,CAAA,OAAA"}

package/docs/actions/connect-wallet.md

@@ -0,0 +1,69 @@
+# Connect Wallet
+
+> Programmatically connect to a Sui wallet using the dApp Kit connectWallet action.
+
+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,39 @@
+# Disconnect Wallet
+
+> Programmatically disconnect from a Sui wallet using the dApp Kit disconnectWallet action.
+
+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.
+> 
+> Wallets might or might not implement the `disconnect` feature. Calling `disconnectWallet`
+> does not necessarily mean that the wallet accounts are disconnected from the app 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 might 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,96 @@
+# Sign and Execute Transaction
+
+> Sign and execute a transaction on the Sui network 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 app.
+
+## 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, and WalletConnect) might 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,58 @@
+# Sign Personal Message
+
+> Sign an arbitrary message with the connected wallet for authentication or proof of ownership.
+
+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,65 @@
+# Sign Transaction
+
+> Sign a Sui transaction without executing it for deferred or multi-signature scenarios.
+
+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,37 @@
+# Switch Account
+
+> Switch the active account in the connected wallet using the dApp Kit switchAccount action.
+
+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 app 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,37 @@
+# Switch Network
+
+> Switch the active network for the dApp Kit instance between mainnet, testnet, and other networks.
+
+The `switchNetwork` action changes the currently selected network that the dApp Kit client is
+configured to use.
+
+> **Note:** Network switching only affects your app's client connection. The wallet itself is not affected by
+> this change, and wallets are not notified when the network changes in the app.
+
+## 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 app. 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 app 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#step-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 (for example,
+  `['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) };
+			},
+		},
+	],
+});
+```