@iota/dapp-kit 0.0.0-experimental-20250610130929

package/src/hooks/useIotaClientQueries.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { UseQueryResult } from '@tanstack/react-query';
+import { useQueries } from '@tanstack/react-query';
+
+import { useIotaClientContext } from './useIotaClient.js';
+import type { IotaRpcMethods, UseIotaClientQueryOptions } from './useIotaClientQuery.js';
+
+type IotaClientQueryOptions = IotaRpcMethods[keyof IotaRpcMethods] extends infer Method
+    ? Method extends {
+          name: infer M extends keyof IotaRpcMethods;
+          params?: infer P;
+      }
+        ? undefined extends P
+            ? {
+                  method: M;
+                  params?: P;
+                  options?: UseIotaClientQueryOptions<M, unknown>;
+              }
+            : {
+                  method: M;
+                  params: P;
+                  options?: UseIotaClientQueryOptions<M, unknown>;
+              }
+        : never
+    : never;
+
+export type UseIotaClientQueriesResults<Args extends readonly IotaClientQueryOptions[]> = {
+    -readonly [K in keyof Args]: Args[K] extends {
+        method: infer M extends keyof IotaRpcMethods;
+        readonly options?:
+            | {
+                  select?: (...args: any[]) => infer R;
+              }
+            | object;
+    }
+        ? UseQueryResult<unknown extends R ? IotaRpcMethods[M]['result'] : R>
+        : never;
+};
+
+export function useIotaClientQueries<
+    const Queries extends readonly IotaClientQueryOptions[],
+    Results = UseIotaClientQueriesResults<Queries>,
+>({
+    queries,
+    combine,
+}: {
+    queries: Queries;
+    combine?: (results: UseIotaClientQueriesResults<Queries>) => Results;
+}): Results {
+    const iotaContext = useIotaClientContext();
+
+    return useQueries({
+        combine: combine as never,
+        queries: queries.map((query) => {
+            const { method, params, options: { queryKey = [], ...restOptions } = {} } = query;
+
+            return {
+                ...restOptions,
+                queryKey: [iotaContext.network, method, params, ...queryKey],
+                queryFn: async () => {
+                    return await iotaContext.client[method](params as never);
+                },
+            };
+        }) as [],
+    });
+}

package/src/hooks/useIotaClientQuery.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IotaClient } from '@iota/iota-sdk/client';
+import type { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { useQuery } from '@tanstack/react-query';
+
+import type { PartialBy } from '../types/utilityTypes.js';
+import { useIotaClientContext } from './useIotaClient.js';
+
+export type IotaRpcMethodName = {
+    [K in keyof IotaClient]: IotaClient[K] extends
+        | ((input: any) => Promise<any>)
+        | (() => Promise<any>)
+        ? K
+        : never;
+}[keyof IotaClient];
+
+export type IotaRpcMethods = {
+    [K in IotaRpcMethodName]: IotaClient[K] extends (input: infer P) => Promise<infer R>
+        ? {
+              name: K;
+              result: R;
+              params: P;
+          }
+        : IotaClient[K] extends () => Promise<infer R>
+          ? {
+                name: K;
+                result: R;
+                params: undefined | object;
+            }
+          : never;
+};
+
+export type UseIotaClientQueryOptions<T extends keyof IotaRpcMethods, TData> = PartialBy<
+    Omit<UseQueryOptions<IotaRpcMethods[T]['result'], Error, TData, unknown[]>, 'queryFn'>,
+    'queryKey'
+>;
+
+export function useIotaClientQuery<
+    T extends keyof IotaRpcMethods,
+    TData = IotaRpcMethods[T]['result'],
+>(
+    ...args: undefined extends IotaRpcMethods[T]['params']
+        ? [
+              method: T,
+              params?: IotaRpcMethods[T]['params'],
+              options?: UseIotaClientQueryOptions<T, TData>,
+          ]
+        : [
+              method: T,
+              params: IotaRpcMethods[T]['params'],
+              options?: UseIotaClientQueryOptions<T, TData>,
+          ]
+): UseQueryResult<TData, Error> {
+    const [method, params, { queryKey = [], ...options } = {}] = args as [
+        method: T,
+        params?: IotaRpcMethods[T]['params'],
+        options?: UseIotaClientQueryOptions<T, TData>,
+    ];
+
+    const iotaContext = useIotaClientContext();
+
+    return useQuery({
+        ...options,
+        queryKey: [iotaContext.network, method, params, ...queryKey],
+        queryFn: async () => {
+            return (await iotaContext.client[method](
+                params as never,
+            )) as IotaRpcMethods[T]['result'];
+        },
+    });
+}

package/src/hooks/wallet/useAccounts.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { WalletAccount } from '@iota/wallet-standard';
+
+import { useWalletStore } from './useWalletStore.js';
+
+/**
+ * Retrieves a list of connected accounts authorized by the dApp.
+ */
+export function useAccounts(): readonly WalletAccount[] {
+    return useWalletStore((state) => state.accounts);
+}

package/src/hooks/wallet/useAutoConnectWallet.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { useQuery } from '@tanstack/react-query';
+import { useLayoutEffect, useState } from 'react';
+
+import { getWalletUniqueIdentifier } from '../../utils/walletUtils.js';
+import { useConnectWallet } from './useConnectWallet.js';
+import { useCurrentWallet } from './useCurrentWallet.js';
+import { useWallets } from './useWallets.js';
+import { useWalletStore } from './useWalletStore.js';
+
+export function useAutoConnectWallet(): 'disabled' | 'idle' | 'attempted' {
+    const { mutateAsync: connectWallet } = useConnectWallet();
+    const autoConnectEnabled = useWalletStore((state) => state.autoConnectEnabled);
+    const lastConnectedWalletName = useWalletStore((state) => state.lastConnectedWalletName);
+    const lastConnectedAccountAddress = useWalletStore(
+        (state) => state.lastConnectedAccountAddress,
+    );
+    const wallets = useWallets();
+    const { isConnected } = useCurrentWallet();
+
+    const [clientOnly, setClientOnly] = useState(false);
+    useLayoutEffect(() => {
+        setClientOnly(true);
+    }, []);
+
+    const { data, isError } = useQuery({
+        queryKey: [
+            '@iota/dapp-kit',
+            'autoconnect',
+            {
+                isConnected,
+                autoConnectEnabled,
+                lastConnectedWalletName,
+                lastConnectedAccountAddress,
+                walletCount: wallets.length,
+            },
+        ],
+        queryFn: async () => {
+            if (!autoConnectEnabled) {
+                return 'disabled';
+            }
+
+            if (!lastConnectedWalletName || !lastConnectedAccountAddress || isConnected) {
+                return 'attempted';
+            }
+
+            const wallet = wallets.find(
+                (wallet) => getWalletUniqueIdentifier(wallet) === lastConnectedWalletName,
+            );
+            if (wallet) {
+                await connectWallet({
+                    wallet,
+                    accountAddress: lastConnectedAccountAddress,
+                    silent: true,
+                });
+            }
+
+            return 'attempted';
+        },
+        enabled: autoConnectEnabled,
+        persister: undefined,
+        gcTime: 0,
+        staleTime: 0,
+        networkMode: 'always',
+        retry: false,
+        retryOnMount: false,
+        refetchInterval: false,
+        refetchIntervalInBackground: false,
+        refetchOnMount: false,
+        refetchOnReconnect: false,
+        refetchOnWindowFocus: false,
+    });
+
+    if (!autoConnectEnabled) {
+        return 'disabled';
+    }
+
+    // We always initialize with "idle" so that in SSR environments, we guarantee that the initial render states always agree:
+    if (!clientOnly) {
+        return 'idle';
+    }
+
+    if (isConnected) {
+        return 'attempted';
+    }
+
+    if (!lastConnectedWalletName) {
+        return 'attempted';
+    }
+
+    return isError ? 'attempted' : (data ?? 'idle');
+}

package/src/hooks/wallet/useConnectWallet.ts

@@ -0,0 +1,91 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { isSupportedChain } from '@iota/wallet-standard';
+import type {
+    StandardConnectInput,
+    StandardConnectOutput,
+    WalletAccount,
+    WalletWithRequiredFeatures,
+} from '@iota/wallet-standard';
+import type { UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { useMutation } from '@tanstack/react-query';
+
+import { walletMutationKeys } from '../../constants/walletMutationKeys.js';
+import { useWalletStore } from './useWalletStore.js';
+
+type ConnectWalletArgs = {
+    /** The wallet to connect to. */
+    wallet: WalletWithRequiredFeatures;
+
+    /** An optional account address to connect to. Defaults to the first authorized account. */
+    accountAddress?: string;
+} & StandardConnectInput;
+
+type ConnectWalletResult = StandardConnectOutput;
+
+type UseConnectWalletMutationOptions = Omit<
+    UseMutationOptions<ConnectWalletResult, Error, ConnectWalletArgs, unknown>,
+    'mutationFn'
+>;
+
+/**
+ * Mutation hook for establishing a connection to a specific wallet.
+ */
+export function useConnectWallet({
+    mutationKey,
+    ...mutationOptions
+}: UseConnectWalletMutationOptions = {}): UseMutationResult<
+    ConnectWalletResult,
+    Error,
+    ConnectWalletArgs,
+    unknown
+> {
+    const setWalletConnected = useWalletStore((state) => state.setWalletConnected);
+    const setConnectionStatus = useWalletStore((state) => state.setConnectionStatus);
+
+    return useMutation({
+        mutationKey: walletMutationKeys.connectWallet(mutationKey),
+        mutationFn: async ({ wallet, accountAddress, ...connectArgs }) => {
+            try {
+                setConnectionStatus('connecting');
+
+                const connectResult =
+                    await wallet.features['standard:connect'].connect(connectArgs);
+                const connectedIotaAccounts = connectResult.accounts.filter((account) =>
+                    account.chains.some(isSupportedChain),
+                );
+                const selectedAccount = getSelectedAccount(connectedIotaAccounts, accountAddress);
+
+                setWalletConnected(
+                    wallet,
+                    connectedIotaAccounts,
+                    selectedAccount,
+                    connectResult.supportedIntents,
+                );
+
+                return { accounts: connectedIotaAccounts };
+            } catch (error) {
+                setConnectionStatus('disconnected');
+                throw error;
+            }
+        },
+        ...mutationOptions,
+    });
+}
+
+function getSelectedAccount(connectedAccounts: readonly WalletAccount[], accountAddress?: string) {
+    if (connectedAccounts.length === 0) {
+        return null;
+    }
+
+    if (accountAddress) {
+        const selectedAccount = connectedAccounts.find(
+            (account) => account.address === accountAddress,
+        );
+        return selectedAccount ?? connectedAccounts[0];
+    }
+
+    return connectedAccounts[0];
+}

package/src/hooks/wallet/useCurrentAccount.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { WalletAccount } from '@iota/wallet-standard';
+
+import { useWalletStore } from './useWalletStore.js';
+
+/**
+ * Retrieves the wallet account that is currently selected, if one exists.
+ */
+export function useCurrentAccount(): WalletAccount | null {
+    return useWalletStore((state) => state.currentAccount);
+}

package/src/hooks/wallet/useCurrentWallet.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { useWalletStore } from './useWalletStore.js';
+
+/**
+ * Retrieves the wallet that is currently connected to the dApp, if one exists.
+ */
+export function useCurrentWallet() {
+    const currentWallet = useWalletStore((state) => state.currentWallet);
+    const connectionStatus = useWalletStore((state) => state.connectionStatus);
+    const supportedIntents = useWalletStore((state) => state.supportedIntents);
+
+    switch (connectionStatus) {
+        case 'connecting':
+            return {
+                connectionStatus,
+                currentWallet: null,
+                isDisconnected: false,
+                isConnecting: true,
+                isConnected: false,
+                supportedIntents: [],
+            } as const;
+        case 'disconnected':
+            return {
+                connectionStatus,
+                currentWallet: null,
+                isDisconnected: true,
+                isConnecting: false,
+                isConnected: false,
+                supportedIntents: [],
+            } as const;
+        case 'connected': {
+            return {
+                connectionStatus,
+                currentWallet: currentWallet!,
+                isDisconnected: false,
+                isConnecting: false,
+                isConnected: true,
+                supportedIntents,
+            } as const;
+        }
+    }
+}

package/src/hooks/wallet/useDisconnectWallet.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { useMutation } from '@tanstack/react-query';
+
+import { walletMutationKeys } from '../../constants/walletMutationKeys.js';
+import { WalletNotConnectedError } from '../../errors/walletErrors.js';
+import { useCurrentWallet } from './useCurrentWallet.js';
+import { useWalletStore } from './useWalletStore.js';
+
+type UseDisconnectWalletError = WalletNotConnectedError | Error;
+
+type UseDisconnectWalletMutationOptions = Omit<
+    UseMutationOptions<void, UseDisconnectWalletError, void, unknown>,
+    'mutationFn'
+>;
+
+/**
+ * Mutation hook for disconnecting from an active wallet connection, if currently connected.
+ */
+export function useDisconnectWallet({
+    mutationKey,
+    ...mutationOptions
+}: UseDisconnectWalletMutationOptions = {}): UseMutationResult<
+    void,
+    UseDisconnectWalletError,
+    void
+> {
+    const { currentWallet } = useCurrentWallet();
+    const setWalletDisconnected = useWalletStore((state) => state.setWalletDisconnected);
+
+    return useMutation({
+        mutationKey: walletMutationKeys.disconnectWallet(mutationKey),
+        mutationFn: async () => {
+            if (!currentWallet) {
+                throw new WalletNotConnectedError('No wallet is connected.');
+            }
+
+            try {
+                // Wallets aren't required to implement the disconnect feature, so we'll
+                // optionally call the disconnect feature if it exists and reset the UI
+                // state on the frontend at a minimum.
+                await currentWallet.features['standard:disconnect']?.disconnect();
+            } catch (error) {
+                console.error(
+                    'Failed to disconnect the application from the current wallet.',
+                    error,
+                );
+            }
+
+            setWalletDisconnected();
+        },
+        ...mutationOptions,
+    });
+}

package/src/hooks/wallet/useReportTransactionEffects.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { toB64 } from '@iota/iota-sdk/utils';
+import type { IotaReportTransactionEffectsInput } from '@iota/wallet-standard';
+import type { UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { useMutation } from '@tanstack/react-query';
+
+import { walletMutationKeys } from '../../constants/walletMutationKeys.js';
+import type { WalletFeatureNotSupportedError } from '../../errors/walletErrors.js';
+import {
+    WalletNoAccountSelectedError,
+    WalletNotConnectedError,
+} from '../../errors/walletErrors.js';
+import type { PartialBy } from '../../types/utilityTypes.js';
+import { useCurrentAccount } from './useCurrentAccount.js';
+import { useCurrentWallet } from './useCurrentWallet.js';
+
+type UseReportTransactionEffectsArgs = Omit<
+    PartialBy<IotaReportTransactionEffectsInput, 'account' | 'chain'>,
+    'effects'
+> & {
+    effects: string | number[];
+};
+
+type UseReportTransactionEffectsError =
+    | WalletFeatureNotSupportedError
+    | WalletNoAccountSelectedError
+    | WalletNotConnectedError
+    | Error;
+
+type UseReportTransactionEffectsMutationOptions = Omit<
+    UseMutationOptions<
+        void,
+        UseReportTransactionEffectsError,
+        UseReportTransactionEffectsArgs,
+        unknown
+    >,
+    'mutationFn'
+>;
+
+/**
+ * Mutation hook for prompting the user to sign a message.
+ */
+export function useReportTransactionEffects({
+    mutationKey,
+    ...mutationOptions
+}: UseReportTransactionEffectsMutationOptions = {}): UseMutationResult<
+    void,
+    UseReportTransactionEffectsError,
+    UseReportTransactionEffectsArgs
+> {
+    const { currentWallet } = useCurrentWallet();
+    const currentAccount = useCurrentAccount();
+
+    return useMutation({
+        mutationKey: walletMutationKeys.reportTransactionEffects(mutationKey),
+        mutationFn: async ({
+            effects,
+            chain = currentWallet?.chains[0],
+            account = currentAccount,
+        }) => {
+            if (!currentWallet) {
+                throw new WalletNotConnectedError('No wallet is connected.');
+            }
+
+            if (!account) {
+                throw new WalletNoAccountSelectedError(
+                    'No wallet account is selected to report transaction effects for',
+                );
+            }
+
+            const reportTransactionEffectsFeature =
+                currentWallet.features['iota:reportTransactionEffects'];
+
+            if (reportTransactionEffectsFeature) {
+                return await reportTransactionEffectsFeature.reportTransactionEffects({
+                    effects: Array.isArray(effects) ? toB64(new Uint8Array(effects)) : effects,
+                    account,
+                    chain: chain ?? currentWallet?.chains[0],
+                });
+            }
+        },
+        ...mutationOptions,
+    });
+}