thirdweb 5.40.0 → 5.41.0

package/src/react/core/hooks/transaction/useSendAndConfirmTransaction.ts

@@ -2,11 +2,27 @@ import { type UseMutationResult, useMutation } from "@tanstack/react-query";
 import { sendAndConfirmTransaction } from "../../../../transaction/actions/send-and-confirm-transaction.js";
 import type { PreparedTransaction } from "../../../../transaction/prepare-transaction.js";
 import type { TransactionReceipt } from "../../../../transaction/types.js";
-import type { Account } from "../../../../wallets/interfaces/wallet.js";
+import { useActiveAccount } from "../wallets/useActiveAccount.js";
 
-export function useSendAndConfirmTransactionCore(
-  account: Account | undefined,
-): UseMutationResult<TransactionReceipt, Error, PreparedTransaction> {
+/**
+ * A hook to send a transaction.
+ * @returns A mutation object to send a transaction.
+ * @example
+ * ```jsx
+ * import { useSendAndConfirmTransaction } from "thirdweb/react";
+ * const { mutate: sendAndConfirmTx, data: transactionReceipt } = useSendAndConfirmTransaction();
+ *
+ * // later
+ * sendAndConfirmTx(tx);
+ * ```
+ * @transaction
+ */
+export function useSendAndConfirmTransaction(): UseMutationResult<
+  TransactionReceipt,
+  Error,
+  PreparedTransaction
+> {
+  const account = useActiveAccount();
   return useMutation({
     mutationFn: async (transaction) => {
       if (!account) {

package/src/react/core/hooks/transaction/useSendBatchTransaction.ts

@@ -2,11 +2,27 @@ import { type UseMutationResult, useMutation } from "@tanstack/react-query";
 import { sendBatchTransaction } from "../../../../transaction/actions/send-batch-transaction.js";
 import type { WaitForReceiptOptions } from "../../../../transaction/actions/wait-for-tx-receipt.js";
 import type { PreparedTransaction } from "../../../../transaction/prepare-transaction.js";
-import type { Account } from "../../../../wallets/interfaces/wallet.js";
+import { useActiveAccount } from "../wallets/useActiveAccount.js";
 
-export function useSendBatchTransactionCore(
-  account: Account | undefined,
-): UseMutationResult<WaitForReceiptOptions, Error, PreparedTransaction[]> {
+/**
+ * A hook to send a transaction.
+ * @returns A mutation object to send a transaction.
+ * @example
+ * ```jsx
+ * import { useSendBatchTransaction } from "thirdweb/react";
+ * const { mutate: sendBatch, data: transactionResult } = useSendBatchTransaction();
+ *
+ * // later
+ * sendBatch([tx1, tx2]);
+ * ```
+ * @transaction
+ */
+export function useSendBatchTransaction(): UseMutationResult<
+  WaitForReceiptOptions,
+  Error,
+  PreparedTransaction[]
+> {
+  const account = useActiveAccount();
   return useMutation({
     mutationFn: async (transactions) => {
       if (!account) {

package/src/react/core/hooks/wallets/useActiveAccount.ts

@@ -1,7 +1,19 @@
 import { useSyncExternalStore } from "react";
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useActiveAccountCore(manager: ConnectionManager) {
+/**
+ * A hook that returns the active account
+ * @returns The active `Account` or `undefined` if no active account is set.
+ * @example
+ * ```jsx
+ * import { useActiveAccount } from "thirdweb/react";
+ *
+ * const activeAccount = useActiveAccount();
+ * ```
+ * @walletConnection
+ */
+export function useActiveAccount() {
+  const manager = useConnectionManager();
   const store = manager.activeAccountStore;
   return useSyncExternalStore(store.subscribe, store.getValue, store.getValue);
 }

package/src/react/core/hooks/wallets/useActiveWallet.ts

@@ -1,7 +1,19 @@
 import { useSyncExternalStore } from "react";
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useActiveWalletCore(manager: ConnectionManager) {
+/**
+ * A hook that returns the active wallet
+ * @returns The active `Wallet` or `undefined` if no active wallet is set.
+ * @example
+ * ```jsx
+ * import { useActiveWallet } from "thirdweb/react";
+ *
+ * const wallet = useActiveWallet();
+ * ```
+ * @walletConnection
+ */
+export function useActiveWallet() {
+  const manager = useConnectionManager();
   const store = manager.activeWalletStore;
   return useSyncExternalStore(store.subscribe, store.getValue, store.getValue);
 }

package/src/react/core/hooks/wallets/useActiveWalletChain.ts

@@ -1,7 +1,19 @@
 import { useSyncExternalStore } from "react";
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useActiveWalletChainCore(manager: ConnectionManager) {
+/**
+ * A hook that returns the chain the active wallet is connected to
+ * @returns The chain the active wallet is connected to or null if no active wallet.
+ * @example
+ * ```jsx
+ * import { useActiveWalletChain } from "thirdweb/react";
+ *
+ * const activeChain = useActiveWalletChain();
+ * ```
+ * @walletConnection
+ */
+export function useActiveWalletChain() {
+  const manager = useConnectionManager();
   const store = manager.activeWalletChainStore;
   return useSyncExternalStore(store.subscribe, store.getValue, store.getValue);
 }

package/src/react/core/hooks/wallets/useActiveWalletConnectionStatus.ts

@@ -1,9 +1,23 @@
 import { useSyncExternalStore } from "react";
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useActiveWalletConnectionStatusCore(
-  manager: ConnectionManager,
-) {
+/**
+ * A hook that returns the active account's connection status.
+ * @example
+ * ```jsx
+ * import { useActiveWalletConnectionStatus } from "thirdweb/react";
+ *
+ * function Example() {
+ *   const status = useActiveWalletConnectionStatus();
+ *   console.log(status);
+ *   return <div> ... </div>;
+ * }
+ * ```
+ * @returns The active wallet's connection status.
+ * @walletConnection
+ */
+export function useActiveWalletConnectionStatus() {
+  const manager = useConnectionManager();
   const store = manager.activeWalletConnectionStatusStore;
   return useSyncExternalStore(store.subscribe, store.getValue, store.getValue);
 }

package/src/react/core/hooks/wallets/useAutoConnect.ts

@@ -3,25 +3,25 @@ import type { AsyncStorage } from "../../../../utils/storage/AsyncStorage.js";
 import { getUrlToken } from "../../../../wallets/in-app/web/lib/get-url-token.js";
 import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
 import {
-  type ConnectionManager,
   getLastConnectedChain,
   getStoredActiveWalletId,
   getStoredConnectedWalletIds,
 } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 import { setLastAuthProvider } from "../../utils/storage.js";
 import { timeoutPromise } from "../../utils/timeoutPromise.js";
 import type { AutoConnectProps } from "../connection/types.js";
-import { useConnectCore } from "./useConnect.js";
-import { useSetActiveWalletConnectionStatusCore } from "./useSetActiveWalletConnectionStatus.js";
+import { useConnect } from "./useConnect.js";
+import { useSetActiveWalletConnectionStatus } from "./useSetActiveWalletConnectionStatus.js";
 
 export function useAutoConnectCore(
-  manager: ConnectionManager,
   storage: AsyncStorage,
   props: AutoConnectProps & { wallets: Wallet[] },
   getInstalledWallets?: () => Wallet[],
 ) {
-  const setConnectionStatus = useSetActiveWalletConnectionStatusCore(manager);
-  const { connect } = useConnectCore(manager, {
+  const manager = useConnectionManager();
+  const setConnectionStatus = useSetActiveWalletConnectionStatus();
+  const { connect } = useConnect({
     client: props.client,
     accountAbstraction: props.accountAbstraction,
   });

package/src/react/core/hooks/wallets/useCallsStatus.ts

@@ -6,17 +6,29 @@ import {
 import type { ThirdwebClient } from "../../../../client/client.js";
 import { getCallsStatus } from "../../../../wallets/eip5792/get-calls-status.js";
 import type { GetCallsStatusResponse } from "../../../../wallets/eip5792/types.js";
-import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import { useActiveWallet } from "./useActiveWallet.js";
 
-export function useCallsStatusCore(
-  options: {
-    bundleId: string;
-    client: ThirdwebClient;
-    queryOptions?: Pick<UseQueryOptions, "enabled" | "retry">;
-  },
-  wallet?: Wallet,
-): UseQueryResult<GetCallsStatusResponse> {
+/**
+ * A hook to get a call bundle's current status according to [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792).
+ *
+ * @note This function is dependent on the wallet's support for EIP-5792 and could throw an error if it's not supported.
+ *
+ * @returns a React Query object.
+ * @beta
+ * @example
+ * ```tsx
+ * import { useCallsStatus } from "thirdweb/react";
+ * const { data: status, isLoading } = useCallsStatus({ bundleId, client });
+ * ```
+ * @extension EIP5792
+ */
+export function useCallsStatus(options: {
+  bundleId: string;
+  client: ThirdwebClient;
+  queryOptions?: Pick<UseQueryOptions, "enabled" | "retry">;
+}): UseQueryResult<GetCallsStatusResponse> {
   const { client, bundleId } = options;
+  const wallet = useActiveWallet();
 
   return useQuery({
     queryKey: [

package/src/react/core/hooks/wallets/useCapabilities.ts

@@ -7,14 +7,27 @@ import {
   type GetCapabilitiesResult,
   getCapabilities,
 } from "../../../../wallets/eip5792/get-capabilities.js";
-import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import { useActiveWallet } from "./useActiveWallet.js";
 
-export function useCapabilitiesCore(
-  options?: {
-    queryOptions?: Pick<UseQueryOptions, "enabled" | "retry">;
-  },
-  wallet?: Wallet,
-): UseQueryResult<GetCapabilitiesResult> {
+/**
+ * A hook to get the current wallet's capabilities according to [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792).
+ *
+ * @note This function is dependent on the wallet's support for EIP-5792, but will not throw.
+ * **The returned object contains a `message` field detailing any issues with the wallet's support for EIP-5792.**
+ *
+ * @returns a React Query object.
+ * @beta
+ * @example
+ * ```tsx
+ * import { useCapabilities } from "thirdweb/react";
+ * const { data: capabilities, isLoading } = useCapabilities();
+ * ```
+ * @extension EIP5792
+ */
+export function useCapabilities(options?: {
+  queryOptions?: Pick<UseQueryOptions, "enabled" | "retry">;
+}): UseQueryResult<GetCapabilitiesResult> {
+  const wallet = useActiveWallet();
   return useQuery({
     queryKey: [
       "getCapabilities",

package/src/react/core/hooks/wallets/useConnect.ts

@@ -1,14 +1,40 @@
 import { useCallback, useState } from "react";
 import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
-import type {
-  ConnectManagerOptions,
-  ConnectionManager,
-} from "../../../../wallets/manager/index.js";
+import type { ConnectManagerOptions } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useConnectCore(
-  manager: ConnectionManager,
-  options?: ConnectManagerOptions,
-) {
+/**
+ * A hook to set a wallet as active wallet
+ * @returns A function that lets you connect a wallet.
+ * @example
+ * ```jsx
+ * import { useConnect } from "thirdweb/react";
+ * import { createWallet } from "thirdweb/wallets";
+ *
+ * function Example() {
+ *   const { connect, isConnecting, error } = useConnect();
+ *   return (
+ *     <button
+ *       onClick={() =>
+ *         connect(async () => {
+ *           // instantiate wallet
+ *           const wallet = createWallet("io.metamask");
+ *           // connect wallet
+ *           await wallet.connect();
+ *           // return the wallet
+ *           return wallet;
+ *         })
+ *       }
+ *     >
+ *       Connect
+ *     </button>
+ *   );
+ * }
+ * ```
+ * @walletConnection
+ */
+export function useConnect(options?: ConnectManagerOptions) {
+  const manager = useConnectionManager();
   const { connect } = manager;
   const [isConnecting, setIsConnecting] = useState(false);
   const [error, setError] = useState<Error | null>(null);

package/src/react/core/hooks/wallets/useConnectedWallets.ts

@@ -1,7 +1,19 @@
 import { useSyncExternalStore } from "react";
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useConnectedWalletsCore(manager: ConnectionManager) {
+/**
+ * A hook that returns all connected wallets
+ * @returns An array of all connected wallets
+ * @example
+ * ```jsx
+ * import { useConnectedWallets } from "thirdweb/react";
+ *
+ * const wallets = useConnectedWallets();
+ * ```
+ * @walletConnection
+ */
+export function useConnectedWallets() {
+  const manager = useConnectionManager();
   const store = manager.connectedWallets;
   return useSyncExternalStore(store.subscribe, store.getValue, store.getValue);
 }

package/src/react/core/hooks/wallets/useDisconnect.ts

@@ -1,6 +1,27 @@
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useDisconnectCore(manager: ConnectionManager) {
+/**
+ * Disconnect from given account
+ * @example
+ * ```jsx
+ * import { useDisconnect, useActiveWallet } from "thirdweb/react";
+ *
+ * function Example() {
+ *   const { disconnect } = useDisconnect();
+ *   const wallet = useActiveWallet();
+ *
+ *   return (
+ *     <button onClick={() => disconnect(wallet)}>
+ *       Disconnect
+ *     </button>
+ *   );
+ * }
+ * ```
+ * @walletConnection
+ * @returns An object with a function to disconnect an account
+ */
+export function useDisconnect() {
+  const manager = useConnectionManager();
   const disconnect = manager.disconnectWallet;
   return { disconnect };
 }

package/src/react/core/hooks/wallets/useIsAutoConnecting.ts

@@ -1,7 +1,21 @@
 import { useSyncExternalStore } from "react";
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useIsAutoConnectingCore(manager: ConnectionManager) {
+/**
+ * A hook to check if the auto connect is in progress.
+ * @example
+ * ```jsx
+ * function Example() {
+ *   const isAutoConnecting = useIsAutoConnecting();
+ *
+ *   return <div> ... </div>;
+ * }
+ * ```
+ * @returns A boolean indicating if the auto connect is in progress.
+ * @walletConnection
+ */
+export function useIsAutoConnecting() {
+  const manager = useConnectionManager();
   const store = manager.isAutoConnecting;
   return useSyncExternalStore(store.subscribe, store.getValue, store.getValue);
 }

package/src/react/core/hooks/wallets/useSendCalls.ts

@@ -15,24 +15,84 @@ import type {
 import { waitForBundle } from "../../../../wallets/eip5792/wait-for-bundle.js";
 import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
 import { invalidateWalletBalance } from "../../providers/invalidateWalletBalance.js";
+import { useActiveWallet } from "./useActiveWallet.js";
 
-export function useSendCallsCore(
-  {
-    client,
-    waitForResult = true,
-  }: { client: ThirdwebClient; waitForResult?: boolean },
-  wallet?: Wallet,
-): UseMutationResult<
+/**
+ * A hook to send [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) calls to a wallet.
+ * This hook works with all Thirdweb wallets (in-app and smart) and certain injected wallets that already support EIP-5792.
+ * Transactions will be bundled and sponsored when those capabilities are supported, otherwise they will be sent as individual transactions.
+ *
+ * When calls are sent, all contracts that are interacted with will have their corresponding reads revalidated via React Query.
+ *
+ * @note This hook is dependent on the wallet's support for EIP-5792 and could fail.
+ * @note The mutatuon function will use your currently connected wallet by default, but you can pass it a specific wallet to use if you'd like.
+ *
+ * @returns A React Query mutatuon object to interact with {@link sendCalls}
+ * @throws an error if the wallet does not support EIP-5792.
+ * @returns The ID of the bundle of the calls.
+ *
+ * @beta
+ * @example
+ * ```tsx
+ * import { useSendCalls } from "thirdweb/react";
+ *
+ * const sendTx1 = approve({
+      contract: USDT_CONTRACT,
+      amount: 100,
+      spender: "0x33d9B8BEfE81027E2C859EDc84F5636cbb202Ed6",
+    });
+ * const sendTx2 = approve({
+      contract: USDT_CONTRACT,
+      amount: 100,
+      spender: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
+    });
+ * const { mutate: sendCalls, data: bundleId } = useSendCalls({ client });
+ * await sendCalls({
+ *   wallet,
+ *   client,
+ *   calls: [sendTx1, sendTx2],
+ * });
+ * ```
+ * Await the bundle's full confirmation:
+ * ```tsx
+ * const { mutate: sendCalls, data: bundleId } = useSendCalls({ client, waitForResult: true });
+ * await sendCalls({
+ *   wallet,
+ *   client,
+ *   calls: [sendTx1, sendTx2],
+ * });
+ * ```
+ * Sponsor transactions with a paymaster:
+ * ```ts
+ * const { mutate: sendCalls, data: bundleId } = useSendCalls();
+ * await sendCalls({
+ *   client,
+ *   calls: [sendTx1, sendTx2],
+ *   capabilities: {
+ *     paymasterService: {
+ *       url: `https://${CHAIN.id}.bundler.thirdweb.com/${client.clientId}`
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @note We recommend proxying any paymaster calls via an API route you setup and control.
+ * @extension EIP5792
+ */
+export function useSendCalls({
+  client,
+  waitForResult = true,
+}: { client: ThirdwebClient; waitForResult?: boolean }): UseMutationResult<
   GetCallsStatusResponse | WalletSendCallsId,
   Error,
   Omit<SendCallsOptions, "chain" | "wallet"> & { wallet?: Wallet } // Optional wallet override
 > {
-  const connectedWallet = wallet;
+  const activeWallet = useActiveWallet();
   const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (options) => {
-      const { wallet = connectedWallet } = options;
+      const { wallet = activeWallet } = options;
       const chain = wallet?.getChain();
       if (!wallet || !chain) {
         throw new Error(
@@ -55,15 +115,15 @@ export function useSendCallsCore(
     },
     onSettled: async (_result, _error, variables) => {
       // Attempt to invalidate any reads related to the sent transactions
-      const chain = connectedWallet?.getChain();
-      if (!_result || !connectedWallet || !chain) {
+      const chain = activeWallet?.getChain();
+      if (!_result || !activeWallet || !chain) {
         return;
       }
 
       if (typeof _result === "string") {
         await waitForBundle({
           bundleId: _result,
-          wallet: connectedWallet,
+          wallet: activeWallet,
           client,
           chain,
         }).catch((error) => {

package/src/react/core/hooks/wallets/useSendToken.ts

@@ -7,13 +7,31 @@ import { sendTransaction } from "../../../../transaction/actions/send-transactio
 import { prepareTransaction } from "../../../../transaction/prepare-transaction.js";
 import { isAddress } from "../../../../utils/address.js";
 import { toWei } from "../../../../utils/units.js";
-import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import { useActiveWallet } from "./useActiveWallet.js";
 
 /**
  * Send Native or ERC20 tokens from active wallet to given address.
- * @internal
+ * @example
+ * ```tsx
+ * const { mutate: sendToken } = useSendToken(client);
+ *
+ * // send native currency
+ * sendToken({
+ *    receiverAddress: "0x...",
+ *    amount: "0.1",
+ * });
+ *
+ * // send ERC20
+ * sendToken({
+ *   tokenAddress,
+ *   receiverAddress: "0x...",
+ *   amount: "0.5",
+ * });
+ * ```
+ * @wallet
  */
-export function useSendTokenCore(client: ThirdwebClient, wallet?: Wallet) {
+export function useSendToken(client: ThirdwebClient) {
+  const wallet = useActiveWallet();
   return useMutation({
     async mutationFn(option: {
       tokenAddress?: string;

package/src/react/core/hooks/wallets/useSetActiveWallet.ts

@@ -1,5 +1,20 @@
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useSetActiveWalletCore(manager: ConnectionManager) {
+/**
+ * A hook that lets you set the active wallet.
+ * @returns A function that lets you set the active wallet.
+ * @example
+ * ```jsx
+ * import { useSetActiveWallet } from "thirdweb/react";
+ *
+ * const setActiveAccount = useSetActiveWallet();
+ *
+ * // later in your code
+ * await setActiveAccount(account);
+ * ```
+ * @walletConnection
+ */
+export function useSetActiveWallet() {
+  const manager = useConnectionManager();
   return manager.setActiveWallet;
 }

package/src/react/core/hooks/wallets/useSetActiveWalletConnectionStatus.ts

@@ -1,7 +1,20 @@
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useSetActiveWalletConnectionStatusCore(
-  manager: ConnectionManager,
-) {
+/**
+ * A hook that returns the active wallet's connection status.
+ * @example
+ * ```jsx
+ * function Example() {
+ *   const setActiveStatus = useSetActiveWalletConnectionStatus();
+ *
+ *   // when you want to set the connection status of the wallet
+ *   setActiveStatus(status)
+ * }
+ * ```
+ * @returns The active wallet's connection status.
+ * @internal
+ */
+export function useSetActiveWalletConnectionStatus() {
+  const manager = useConnectionManager();
   return manager.activeWalletConnectionStatusStore.setValue;
 }

package/src/react/core/hooks/wallets/useSwitchActiveWalletChain.ts

@@ -1,5 +1,21 @@
-import type { ConnectionManager } from "../../../../wallets/manager/index.js";
+import { useConnectionManager } from "../../providers/connection-manager.js";
 
-export function useSwitchActiveWalletChainCore(manager: ConnectionManager) {
+/**
+ * Switch to blockchain with given chain id in the active wallet.
+ * @returns A function to switch to blockchain with given chain id in the active wallet.
+ * @example
+ * ```jsx
+ * import { useSwitchActiveWalletChain } from "thirdweb/react";
+ * import { sepolia } from "thirdweb/chains";
+ *
+ * const switchChain = useSwitchActiveWalletChain();
+ *
+ * // later in your code
+ * <button onClick={() => switchChain(sepolia)}>Switch Chain</button>
+ * ```
+ * @walletConnection
+ */
+export function useSwitchActiveWalletChain() {
+  const manager = useConnectionManager();
   return manager.switchActiveWalletChain;
 }

package/src/react/core/providers/connection-manager.tsx

@@ -0,0 +1,16 @@
+import { createContext, useContext } from "react";
+import type { ConnectionManager } from "../../../wallets/manager/index.js";
+
+export const ConnectionManagerCtx = createContext<
+  ConnectionManager | undefined
+>(undefined);
+
+export function useConnectionManager() {
+  const connectionManager = useContext(ConnectionManagerCtx);
+  if (!connectionManager) {
+    throw new Error(
+      "useConnectionManager must be used within a ConnectionManager Provider",
+    );
+  }
+  return connectionManager;
+}