@mysten/dapp-kit 1.0.2 → 1.0.4

package/docs/wallet-components/ConnectModal.md

@@ -0,0 +1,66 @@
+# ConnectModal
+
+> React connect modal component
+
+ControlledConnectModalExample, UncontrolledConnectModalExample, } from
+'../../../../examples/wallet-components-client';
+
+The `ConnectModal` component opens a modal that guides the user through connecting their wallet to
+the dApp.
+
+## Controlled example
+
+```tsx
+
+	const currentAccount = useCurrentAccount();
+	const [open, setOpen] = useState(false);
+
+	return (
+		<ConnectModal
+			trigger={
+				<button disabled={!!currentAccount}> {currentAccount ? 'Connected' : 'Connect'}</button>
+			}
+			open={open}
+			onOpenChange={(isOpen) => setOpen(isOpen)}
+		/>
+	);
+}
+```
+
+Click **Connect** to connect your wallet and see the previous code in action:
+
+## Uncontrolled example
+
+```tsx
+
+	const currentAccount = useCurrentAccount();
+
+	return (
+		<ConnectModal
+			trigger={
+				<button disabled={!!currentAccount}> {currentAccount ? 'Connected' : 'Connect'}</button>
+			}
+		/>
+	);
+}
+```
+
+Click **Connect** to connect your wallet and see the previous code in action:
+
+## Controlled props
+
+- `open` - The controlled open state of the dialog.
+- `onOpenChange` - Event handler called when the open state of the dialog changes.
+- `trigger` - The trigger button that opens the dialog.
+- `walletFilter` - A filter function that receives a wallet instance, and returns a boolean
+  indicating whether the wallet should be displayed in the wallet list. By default, all wallets are
+  displayed.
+
+## Uncontrolled props
+
+- `defaultOpen` - The open state of the dialog when it is initially rendered. Use when you do not
+  need to control its open state.
+- `trigger` - The trigger button that opens the dialog.
+- `walletFilter` - A filter function that receives a wallet instance, and returns a boolean
+  indicating whether the wallet should be displayed in the wallet list. By default, all wallets are
+  displayed.

package/docs/wallet-hooks/useAccounts.md

@@ -0,0 +1,36 @@
+# useAccounts
+
+> List wallet accounts
+
+The `useAccounts` hook retrieves a list of connected accounts the dApp authorizes.
+
+```ts
+
+function MyComponent() {
+	const accounts = useAccounts();
+
+	return (
+		<div>
+			<ConnectButton />
+			<h2>Available accounts:</h2>
+			{accounts.length === 0 && <div>No accounts detected</div>}
+			<ul>
+				{accounts.map((account) => (
+					<li key={account.address}>- {account.address}</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Account properties
+
+- `address`: The address of the account, corresponding with a public key.
+- `publicKey`: The public key of the account, represented as a `Uint8Array`.
+- `chains`: The chains the account supports.
+- `features`: The features the account supports.
+- `label`: An optional user-friendly descriptive label or name for the account.
+- `icon`: An optional user-friendly icon for the account.

package/docs/wallet-hooks/useAutoConnectWallet.md

@@ -0,0 +1,29 @@
+# useAutoConnectWallet
+
+> Automatically reconnect to the last connected wallet
+
+The `useAutoConnectWallet` hook retrieves the status for the initial wallet auto-connection process.
+
+```ts
+
+function MyComponent() {
+	const autoConnectionStatus = useAutoConnectWallet();
+
+	return (
+		<div>
+			<ConnectButton />
+			<div>Auto-connection status: {autoConnectionStatus}</div>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Auto-connection status properties
+
+- `disabled` - When the auto-connection functionality is disabled.
+- `idle` - When the initial auto-connection attempt hasn't been made yet.
+- `attempted` - When an auto-connection attempt has been made. This means either that there is no
+  previously connected wallet, the previously connected wallet was not found, or that it has
+  successfully connected to a wallet.

package/docs/wallet-hooks/useConnectWallet.md

@@ -0,0 +1,48 @@
+# useConnectWallet
+
+> Connect a wallet to the dApp
+
+The `useConnectWallet` hook is a mutation hook for establishing a connection to a specific wallet.
+
+```ts
+
+function MyComponent() {
+	const wallets = useWallets();
+	const { mutate: connect } = useConnectWallet();
+
+	return (
+		<div style={{ padding: 20 }}>
+			<ConnectButton />
+			<ul>
+				{wallets.map((wallet) => (
+					<li key={wallet.name}>
+						<button
+							onClick={() => {
+								connect(
+									{ wallet },
+									{
+										onSuccess: () => console.log('connected'),
+									},
+								);
+							}}
+						>
+							Connect to {wallet.name}
+						</button>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Connect arguments
+
+- `args` - Arguments passed to the `connect` function of the wallet.
+  - `wallet` - The wallet to connect to.
+  - `accountAddress` - (optional) The address in the wallet to connect to.
+
+- `options` - Options passed the `useMutation` hook from
+  [@tanstack/react-query](https://tanstack.com/query/latest/docs/react/guides/mutations).

package/docs/wallet-hooks/useCurrentAccount.md

@@ -0,0 +1,36 @@
+# useCurrentAccount
+
+> Get the current wallet account
+
+The `useCurrentAccount` hook retrieves the wallet account that is currently selected, if one exists.
+
+```ts
+
+function MyComponent() {
+	const account = useCurrentAccount();
+
+	return (
+		<div>
+			<ConnectButton />
+			{!account && <div>No account connected</div>}
+			{account && (
+				<div>
+					<h2>Current account:</h2>
+					<div>Address: {account.address}</div>
+				</div>
+			)}
+		</div>
+	);
+}
+```
+
+## Example
+
+## Account properties
+
+- `address`: The address of the account, corresponding with a public key.
+- `publicKey`: The public key of the account, represented as a `Uint8Array`.
+- `chains`: The chains the account supports.
+- `features`: The features the account supports.
+- `label`: An optional user-friendly descriptive label or name for the account.
+- `icon`: An optional user-friendly icon for the account.

package/docs/wallet-hooks/useCurrentWallet.md

@@ -0,0 +1,59 @@
+# useCurrentWallet
+
+> Get the current wallet connection
+
+The `useCurrentWallet` hook retrieves the wallet that is currently connected to the dApp, if one
+exists.
+
+```ts
+
+function MyComponent() {
+	const { currentWallet, connectionStatus } = useCurrentWallet();
+
+	return (
+		<div>
+			<ConnectButton />
+			{connectionStatus === 'connected' ? (
+				<div>
+					<h2>Current wallet:</h2>
+					<div>Name: {currentWallet.name}</div>
+					<div>
+						Accounts:
+						<ul>
+							{currentWallet.accounts.map((account) => (
+								<li key={account.address}>- {account.address}</li>
+							))}
+						</ul>
+					</div>
+				</div>
+			) : (
+				<div>Connection status: {connectionStatus}</div>
+			)}
+		</div>
+	);
+}
+```
+
+## Example
+
+## Wallet properties
+
+- `name` - The name of the wallet.
+- `version` - The version of the wallet as a string.
+- `icon` - A data URL of the wallet icon as an SVG.
+- `accounts` - An array of accounts that are available in the wallet.
+- `features` - An object with all the
+  [wallet-standard](https://github.com/wallet-standard/wallet-standard) features implemented by the
+  wallet.
+- `chains` - An array of chain identifiers that the wallet supports.
+
+## Connection status properties
+
+- `connectionStatus`
+  - `disconnected` - When no wallet is connected to the dApp.
+  - `connecting` - When a wallet connection attempt is in progress.
+  - `connected` - When a wallet is connected to the dApp.
+
+- `isDisconnected` - A derived boolean from the status variable above, provided for convenience.
+- `isConnecting` - A derived boolean from the status variable above, provided for convenience.
+- `isConnected` - A derived boolean from the status variable above, provided for convenience.

package/docs/wallet-hooks/useDisconnectWallet.md

@@ -0,0 +1,26 @@
+# useDisconnectWallet
+
+> Disconnect the current wallet
+
+The `useDisconnectWallet` hook is a mutation hook for disconnecting from an active wallet
+connection, if currently connected.
+
+```ts
+
+function MyComponent() {
+	const { mutate: disconnect } = useDisconnectWallet();
+	return (
+		<div>
+			<ConnectButton />
+
+			<button onClick={() => disconnect()}>Disconnect</button>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Arguments
+
+There are no arguments for `useDisconnectWallet`.

package/docs/wallet-hooks/useSignAndExecuteTransaction.md

@@ -0,0 +1,124 @@
+# useSignAndExecuteTransaction
+
+> Sign and execute a transaction
+
+Use the `useSignAndExecuteTransaction` hook to prompt the user to sign and execute a transaction
+block with their wallet.
+
+```ts
+
+function MyComponent() {
+	const { mutate: signAndExecuteTransaction } = useSignAndExecuteTransaction();
+	const [digest, setDigest] = useState('');
+	const currentAccount = useCurrentAccount();
+
+	return (
+		<div style={{ padding: 20 }}>
+			<ConnectButton />
+			{currentAccount && (
+				<>
+					<div>
+						<button
+							onClick={() => {
+								signAndExecuteTransaction(
+									{
+										transaction: new Transaction(),
+										chain: 'sui:devnet',
+									},
+									{
+										onSuccess: (result) => {
+											console.log('executed transaction', result);
+											setDigest(result.digest);
+										},
+									},
+								);
+							}}
+						>
+							Sign and execute transaction
+						</button>
+					</div>
+					<div>Digest: {digest}</div>
+				</>
+			)}
+		</div>
+	);
+}
+```
+
+## Example
+
+## Return additional data, or executing through GraphQL
+
+To customize how transactions are executed, and what data is returned when executing a transaction,
+you can pass a custom `execute` function.
+
+```ts
+
+	ConnectButton,
+	useSuiClient,
+	useCurrentAccount,
+	useSignAndExecuteTransaction,
+} from '@mysten/dapp-kit';
+
+function MyComponent() {
+	const client = useSuiClient();
+	const { mutate: signAndExecuteTransaction } = useSignAndExecuteTransaction({
+		execute: async ({ bytes, signature }) =>
+			await client.executeTransactionBlock({
+				transactionBlock: bytes,
+				signature,
+				options: {
+					// Raw effects are required so the effects can be reported back to the wallet
+					showRawEffects: true,
+					// Select additional data to return
+					showObjectChanges: true,
+				},
+			}),
+	});
+
+	const [digest, setDigest] = useState('');
+	const currentAccount = useCurrentAccount();
+
+	return (
+		<div style={{ padding: 20 }}>
+			<ConnectButton />
+			{currentAccount && (
+				<>
+					<div>
+						<button
+							onClick={() => {
+								signAndExecuteTransaction(
+									{
+										transaction: new Transaction(),
+										chain: 'sui:devnet',
+									},
+									{
+										onSuccess: (result) => {
+											console.log('object changes', result.objectChanges);
+											setDigest(result.digest);
+										},
+									},
+								);
+							}}
+						>
+							Sign and execute transaction
+						</button>
+					</div>
+					<div>Digest: {digest}</div>
+				</>
+			)}
+		</div>
+	);
+}
+```
+
+## Arguments
+
+- `transaction`: The transaction to sign and execute.
+- `chain`: (optional) The chain identifier the transaction should be signed for. Defaults to the
+  active network of the dApp.
+- `execute`: (optional) A custom function to execute the transaction
+
+In addition to these options, you can also pass any options that the
+[SuiJsonRpcClient.signAndExecuteTransaction](/typedoc/classes/_mysten_sui.client.SuiJsonRpcClient.html#signAndExecuteTransactionBlock)
+method accepts.

package/docs/wallet-hooks/useSignPersonalMessage.md

@@ -0,0 +1,59 @@
+# useSignPersonalMessage
+
+> Sign a personal message with the connected wallet
+
+Use the `useSignPersonalMessage` hook to prompt the user to sign a message with their wallet.
+
+```ts
+
+function MyComponent() {
+	const { mutate: signPersonalMessage } = useSignPersonalMessage();
+	const [message, setMessage] = useState('hello, World!');
+	const [signature, setSignature] = useState('');
+	const currentAccount = useCurrentAccount();
+
+	return (
+		<div style={{ padding: 20 }}>
+			<ConnectButton />
+			{currentAccount && (
+				<>
+					<div>
+						<label>
+							Message:{' '}
+							<input type="text" value={message} onChange={(ev) => setMessage(ev.target.value)} />
+						</label>
+					</div>
+					<button
+						onClick={() => {
+							signPersonalMessage(
+								{
+									message: new TextEncoder().encode(message),
+								},
+								{
+									onSuccess: (result) => setSignature(result.signature),
+								},
+							);
+						}}
+					>
+						Sign message
+					</button>
+					<div>Signature: {signature}</div>
+				</>
+			)}
+		</div>
+	);
+}
+```
+
+## Example
+
+## Arguments
+
+- `message`: The message to sign, as a `Uint8Array`.
+- `chain`: (optional) The chain identifier the message should be signed for. Defaults to the active
+  network of the dApp.
+
+## Result
+
+- `signature`: The signature of the message, as a `Base64`-encoded `string`.
+- `bytes`: The bytes of the message, as a `Base64`-encoded `string`.

package/docs/wallet-hooks/useSignTransaction.md

@@ -0,0 +1,67 @@
+# useSignTransaction
+
+> Sign a transaction without executing it
+
+Use the `useSignTransaction` hook to prompt the user to sign a transaction with their wallet.
+
+```ts
+
+	ConnectButton,
+	useCurrentAccount,
+	useSignTransaction,
+	useSuiClient,
+} from '@mysten/dapp-kit';
+
+function MyComponent() {
+	const { mutateAsync: signTransaction } = useSignTransaction();
+	const [signature, setSignature] = useState('');
+	const client = useSuiClient();
+	const currentAccount = useCurrentAccount();
+
+	return (
+		<div style={{ padding: 20 }}>
+			<ConnectButton />
+			{currentAccount && (
+				<>
+					<div>
+						<button
+							onClick={async () => {
+								const { bytes, signature } = await signTransaction({
+									transaction: new Transaction(),
+									chain: 'sui:devnet',
+								});
+
+								const executeResult = await client.executeTransactionBlock({
+									transactionBlock: bytes,
+									signature,
+									options: {
+										showRawEffects: true,
+									},
+								});
+
+								console.log(executeResult);
+							}}
+						>
+							Sign empty transaction
+						</button>
+					</div>
+					<div>Signature: {signature}</div>
+				</>
+			)}
+		</div>
+	);
+}
+```
+
+## Example
+
+## Arguments
+
+- `transactionBlock`: The transaction to sign.
+- `chain`: (optional) The chain identifier the transaction should be signed for. Defaults to the
+  active network of the dApp.
+
+## Result
+
+- `signature`: The signature of the message, as a Base64-encoded `string`.
+- `bytes`: The serialized transaction bytes, as a Base64-encoded `string`.

package/docs/wallet-hooks/useSwitchAccount.md

@@ -0,0 +1,47 @@
+# useSwitchAccount
+
+> Switch the active wallet account
+
+The `useSwitchAccount` hook is a mutation hook for establishing a connection to a specific wallet.
+
+```ts
+
+function MyComponent() {
+	const { mutate: switchAccount } = useSwitchAccount();
+	const accounts = useAccounts();
+
+	return (
+		<div style={{ padding: 20 }}>
+			<ConnectButton />
+			<ul>
+				{accounts.map((account) => (
+					<li key={account.address}>
+						<button
+							onClick={() => {
+								switchAccount(
+									{ account },
+									{
+										onSuccess: () => console.log(`switched to ${account.address}`),
+									},
+								);
+							}}
+						>
+							Switch to {account.address}
+						</button>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Arguments
+
+- `args` - Arguments passed to the `connect` function of the wallet.
+  - `account` - The account to switch to.
+
+- `options` - Options passed the `useMutation` hook from
+  [@tanstack/react-query](https://tanstack.com/query/latest/docs/react/guides/mutations).

package/docs/wallet-hooks/useWallets.md

@@ -0,0 +1,38 @@
+# useWallets
+
+> List available wallet extensions
+
+The `useWallets` hook returns an array of wallets that are available to the user. The wallets are
+sorted by their priority, with the highest priority wallet being the first in the array.
+
+```ts
+
+function MyComponent() {
+	const wallets = useWallets();
+
+	return (
+		<div>
+			<h2>Installed wallets</h2>
+			{wallets.length === 0 && <div>No wallets installed</div>}
+			<ul>
+				{wallets.map((wallet) => (
+					<li key={wallet.name}>{wallet.name}</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Wallet properties
+
+- `name` - The name of the wallet.
+- `version` - The version of the wallet as a string.
+- `icon` - A data URL of the wallet icon as an SVG.
+- `accounts` - An array of accounts that are available in the wallet.
+- `features` - An object with all the
+  [wallet-standard](https://github.com/wallet-standard/wallet-standard) features implemented by the
+  wallet.
+- `chains` - An array of chain identifiers that the wallet supports.

package/docs/wallet-provider.md

@@ -0,0 +1,37 @@
+# WalletProvider
+
+> React provider for wallet connections
+
+Use `WalletProvider` to set up the necessary context for your React app. Use it at the root of your
+app, so that you can use any of the dApp Kit wallet components underneath it.
+
+```tsx
+function App() {
+	return (
+		<WalletProvider>
+			<YourApp />
+		</WalletProvider>
+	);
+}
+```
+
+The `WalletProvider` manages all wallet state for you, and makes the current wallet state available
+to other dApp Kit hooks and components.
+
+### Props
+
+All props are optional.
+
+- `preferredWallets` - A list of wallets that are sorted to the top of the wallet list.
+- `walletFilter` - A filter function that accepts a wallet and returns a boolean. This filters the
+  list of wallets presented to users when selecting a wallet to connect from, ensuring that only
+  wallets that meet the dApp requirements can connect.
+- `enableUnsafeBurner` - Enables the development-only unsafe burner wallet, useful for testing.
+- `autoConnect` - Enables automatically reconnecting to the most recently used wallet account upon
+  mounting.
+- `slushWallet` - Enables and configures the Slush wallet. Read more about how to
+  [use the Slush integration](./slush).
+- `storage` - Configures how the most recently connected-to wallet account is stored. Set to `null`
+  to disable persisting state entirely. Defaults to using `localStorage` if it is available.
+- `storageKey` - The key to use to store the most recently connected wallet account.
+- `theme` - The theme to use for styling UI components. Defaults to using the light theme.