@account-kit/privy-integration 4.75.4 → 4.76.0

package/src/adapters/types.ts

@@ -0,0 +1,71 @@
+import type { Address, Authorization } from "viem";
+import type { AuthorizationRequest } from "@aa-sdk/core";
+
+/**
+ * Platform-agnostic embedded wallet interface
+ * Abstracts differences between @privy-io/react-auth and @privy-io/expo
+ */
+export interface EmbeddedWallet {
+  /** Wallet address */
+  address: Address;
+
+  /** Chain ID as a string (may be CAIP-2 format like "eip155:1" or numeric string like "1") */
+  chainId: string;
+
+  /** Get EVM provider for the wallet */
+  getEthereumProvider(): Promise<any>;
+}
+
+/**
+ * Platform-agnostic Privy auth state
+ */
+export interface PrivyAuthState {
+  /** Whether user is authenticated */
+  authenticated: boolean;
+
+  /** User object (platform-specific, used for cache invalidation) */
+  user: any;
+}
+
+/**
+ * Adapter interface that each platform must implement
+ * Provides platform-specific Privy functionality
+ */
+export interface PrivyAdapter {
+  /**
+   * Hook to get embedded wallet
+   * Must be called as a React hook (follows rules of hooks)
+   *
+   * @param preferredAddress - Optional address to find a specific wallet
+   */
+  useEmbeddedWallet(preferredAddress?: string): () => EmbeddedWallet;
+
+  /**
+   * Hook to get Privy authentication state
+   * Must be called as a React hook (follows rules of hooks)
+   */
+  usePrivyAuth(): PrivyAuthState;
+
+  /**
+   * Hook to get current wallet address (for cache invalidation)
+   * Returns undefined if no wallet is available
+   * Must be called as a React hook (follows rules of hooks)
+   *
+   * @param preferredAddress - Optional address to find a specific wallet
+   */
+  useWalletAddress(preferredAddress?: string): string | undefined;
+
+  /**
+   * Hook to get EIP-7702 authorization signer (optional, web only)
+   * Must be called as a React hook (follows rules of hooks)
+   *
+   * @param preferredAddress - Optional address to find a specific wallet
+   */
+  useAuthorizationSigner?(
+    preferredAddress?: string,
+  ):
+    | ((
+        auth: AuthorizationRequest<number>,
+      ) => Promise<Authorization<number, true>>)
+    | null;
+}

package/src/adapters/web.native.ts

@@ -0,0 +1,6 @@
+/**
+ * React Native stub for web adapter
+ * This file prevents Metro from importing @privy-io/react-auth
+ */
+
+export const webAdapter = null;

package/src/adapters/web.ts

@@ -0,0 +1,113 @@
+import { useCallback } from "react";
+import {
+  useWallets,
+  usePrivy,
+  useSign7702Authorization,
+  type ConnectedWallet as PrivyWallet,
+} from "@privy-io/react-auth";
+import { isAddressEqual, type Authorization } from "viem";
+import type { AuthorizationRequest } from "@aa-sdk/core";
+import type { PrivyAdapter, EmbeddedWallet, PrivyAuthState } from "./types.js";
+
+/**
+ * Web adapter for @privy-io/react-auth
+ * Implements platform-specific hooks for React web applications
+ */
+export const webAdapter: PrivyAdapter = {
+  useEmbeddedWallet(preferredAddress?: string) {
+    const { wallets } = useWallets();
+
+    const getEmbeddedWallet = useCallback((): EmbeddedWallet => {
+      const privyWallets = wallets.filter(
+        (w) => w.walletClientType === "privy",
+      );
+
+      if (privyWallets.length === 0) {
+        throw new Error(
+          "Privy embedded wallet not found. Please ensure the user is authenticated.",
+        );
+      }
+
+      // If a preferred address is specified, find that wallet
+      const embedded = preferredAddress
+        ? privyWallets.find((w) =>
+            isAddressEqual(
+              w.address as `0x${string}`,
+              preferredAddress as `0x${string}`,
+            ),
+          )
+        : privyWallets[0];
+
+      if (!embedded) {
+        throw new Error(
+          preferredAddress
+            ? `Privy embedded wallet with address ${preferredAddress} not found.`
+            : "Privy embedded wallet not found. Please ensure the user is authenticated.",
+        );
+      }
+
+      return adaptWebWallet(embedded);
+    }, [wallets, preferredAddress]);
+
+    return getEmbeddedWallet;
+  },
+
+  usePrivyAuth(): PrivyAuthState {
+    const { user } = usePrivy();
+    return { authenticated: !!user, user };
+  },
+
+  useWalletAddress(preferredAddress?: string): string | undefined {
+    const { wallets } = useWallets();
+    const privyWallets = wallets.filter((w) => w.walletClientType === "privy");
+
+    // If a preferred address is specified, find that wallet
+    if (preferredAddress) {
+      const wallet = privyWallets.find((w) =>
+        isAddressEqual(
+          w.address as `0x${string}`,
+          preferredAddress as `0x${string}`,
+        ),
+      );
+      return wallet?.address;
+    }
+
+    // Otherwise return the first embedded wallet
+    return privyWallets[0]?.address;
+  },
+
+  useAuthorizationSigner(_preferredAddress?: string) {
+    const { signAuthorization } = useSign7702Authorization();
+
+    return useCallback(
+      async (
+        unsignedAuth: AuthorizationRequest<number>,
+      ): Promise<Authorization<number, true>> => {
+        const signature = await signAuthorization({
+          ...unsignedAuth,
+          contractAddress: unsignedAuth.address ?? unsignedAuth.contractAddress,
+        });
+
+        return {
+          ...unsignedAuth,
+          ...signature,
+        };
+      },
+      [signAuthorization],
+    );
+  },
+};
+
+/**
+ * Adapts a Privy web wallet to the common EmbeddedWallet interface
+ *
+ * @param {PrivyWallet} wallet - The Privy web wallet to adapt
+ * @returns {EmbeddedWallet} The adapted wallet following the common interface
+ */
+function adaptWebWallet(wallet: PrivyWallet): EmbeddedWallet {
+  return {
+    address: wallet.address as `0x${string}`,
+    chainId: wallet.chainId || "1",
+    getEthereumProvider: () => wallet.getEthereumProvider(),
+  };
+}

package/src/context/AlchemyContext.tsx

@@ -0,0 +1,185 @@
+import {
+  type PropsWithChildren,
+  createContext,
+  useContext,
+  useRef,
+  useEffect,
+} from "react";
+import type { SmartWalletClient } from "@account-kit/wallet-client";
+import type { SmartContractAccount } from "@aa-sdk/core";
+import type { AlchemyProviderConfig } from "../types.js";
+import type { PrivyAdapter } from "../adapters/types.js";
+
+/**
+ * Normalized config with defaults applied
+ *
+ * @internal
+ */
+export type NormalizedAlchemyConfig = AlchemyProviderConfig &
+  Required<Pick<AlchemyProviderConfig, "accountAuthMode">>;
+
+/**
+ * Context for Alchemy configuration
+ */
+const AlchemyConfigContext = createContext<NormalizedAlchemyConfig | null>(
+  null,
+);
+
+/**
+ * Context for the platform adapter
+ */
+const AdapterContext = createContext<PrivyAdapter | null>(null);
+
+/**
+ * Client cache stored in React tree (similar to QueryClient in React Query)
+ *
+ * @internal
+ */
+interface ClientCache {
+  client: SmartWalletClient | null;
+  account: SmartContractAccount | null;
+  cacheKey: string | null;
+}
+
+const ClientCacheContext = createContext<ClientCache | null>(null);
+
+/**
+ * Props for AlchemyContextProvider
+ */
+interface AlchemyContextProviderProps extends PropsWithChildren {
+  config: AlchemyProviderConfig;
+  adapter: PrivyAdapter;
+}
+
+/**
+ * Internal provider component that manages Alchemy context
+ * Used by both web and React Native providers
+ *
+ * @internal
+ * @param {AlchemyContextProviderProps} props - Component props
+ * @param {React.ReactNode} props.children - React children to wrap with context
+ * @param {AlchemyProviderConfig} props.config - Alchemy configuration
+ * @param {PrivyAdapter} props.adapter - Platform adapter
+ * @returns {JSX.Element} Context provider component
+ */
+export function AlchemyContextProvider({
+  children,
+  config,
+  adapter,
+}: AlchemyContextProviderProps) {
+  const { authenticated } = adapter.usePrivyAuth();
+  const walletAddress = adapter.useWalletAddress(config.walletAddress);
+
+  // Normalize config with default values
+  const normalizedConfig: NormalizedAlchemyConfig = {
+    ...config,
+    accountAuthMode: config.accountAuthMode ?? "eip7702",
+  };
+
+  // Store cache in a ref - persists across renders but scoped to this component instance
+  // This makes it SSR-safe (each request gets its own cache) and React StrictMode-safe
+  const cache = useRef<ClientCache>({
+    client: null,
+    account: null,
+    cacheKey: null,
+  });
+
+  // Track previous state to detect logout and wallet changes
+  const prevAuthenticatedRef = useRef(authenticated);
+  const prevWalletAddressRef = useRef(walletAddress);
+
+  // Automatically reset cache when user logs out or switches wallets
+  useEffect(() => {
+    const wasAuthenticated = prevAuthenticatedRef.current;
+    const prevWalletAddress = prevWalletAddressRef.current;
+    const currentWalletAddress = walletAddress;
+
+    // Reset cache on logout
+    if (wasAuthenticated && !authenticated) {
+      cache.current.client = null;
+      cache.current.account = null;
+      cache.current.cacheKey = null;
+    }
+
+    // Reset cache on wallet address change (account switching)
+    if (
+      authenticated &&
+      prevWalletAddress &&
+      currentWalletAddress &&
+      prevWalletAddress !== currentWalletAddress
+    ) {
+      cache.current.client = null;
+      cache.current.account = null;
+      cache.current.cacheKey = null;
+    }
+
+    // Update refs for next render
+    prevAuthenticatedRef.current = authenticated;
+    prevWalletAddressRef.current = currentWalletAddress;
+  }, [authenticated, walletAddress]);
+
+  return (
+    <AlchemyConfigContext.Provider value={normalizedConfig}>
+      <AdapterContext.Provider value={adapter}>
+        <ClientCacheContext.Provider value={cache.current}>
+          {children}
+        </ClientCacheContext.Provider>
+      </AdapterContext.Provider>
+    </AlchemyConfigContext.Provider>
+  );
+}
+
+/**
+ * Hook to access Alchemy provider configuration
+ * Must be used within an <AlchemyProvider> component
+ *
+ * @returns {NormalizedAlchemyConfig} The current Alchemy configuration with defaults applied
+ * @throws {Error} If used outside of AlchemyProvider
+ *
+ * @example
+ * ```tsx
+ * const config = useAlchemyConfig();
+ * console.log('Policy ID:', config.policyId);
+ * console.log('Auth Mode:', config.accountAuthMode); // Always defined
+ * ```
+ */
+export function useAlchemyConfig(): NormalizedAlchemyConfig {
+  const context = useContext(AlchemyConfigContext);
+  if (!context) {
+    throw new Error("useAlchemyConfig must be used within <AlchemyProvider />");
+  }
+  return context;
+}
+
+/**
+ * Hook to access the platform adapter
+ * Must be used within an <AlchemyProvider> component
+ *
+ * @internal
+ * @returns {PrivyAdapter} The platform adapter
+ */
+export function useAdapter(): PrivyAdapter {
+  const context = useContext(AdapterContext);
+  if (!context) {
+    throw new Error(
+      "useAdapter must be used within <AlchemyProvider />. Make sure AlchemyProvider is nested inside PrivyProvider.",
+    );
+  }
+  return context;
+}
+
+/**
+ * Hook to access the client cache (internal use only)
+ *
+ * @internal
+ * @returns {ClientCache} The client cache object
+ */
+export function useClientCache(): ClientCache {
+  const context = useContext(ClientCacheContext);
+  if (!context) {
+    throw new Error(
+      "useClientCache must be used within <AlchemyProvider />. Make sure AlchemyProvider is nested inside PrivyProvider.",
+    );
+  }
+  return context;
+}

package/src/hooks/internal/useEmbeddedWallet.ts

@@ -1,29 +1,15 @@
-import { useCallback } from "react";
-import {
-  useWallets,
-  type ConnectedWallet as PrivyWallet,
-} from "@privy-io/react-auth";
+import { useAdapter, useAlchemyConfig } from "../../context/AlchemyContext.js";
 
 /**
  * Internal hook to get the Privy embedded wallet
- * Shared across multiple hooks to avoid duplication
+ * Uses the platform adapter to abstract differences between web and React Native
  *
  * @internal
- * @returns {() => PrivyWallet} Function that returns the embedded wallet
+ * @returns {() => EmbeddedWallet} Function that returns the embedded wallet
  * @throws {Error} If embedded wallet is not found
  */
 export function useEmbeddedWallet() {
-  const { wallets } = useWallets();
-
-  const getEmbeddedWallet = useCallback((): PrivyWallet => {
-    const embedded = wallets.find((w) => w.walletClientType === "privy");
-    if (!embedded) {
-      throw new Error(
-        "Privy embedded wallet not found. Please ensure the user is authenticated.",
-      );
-    }
-    return embedded;
-  }, [wallets]);
-
-  return getEmbeddedWallet;
+  const adapter = useAdapter();
+  const config = useAlchemyConfig();
+  return adapter.useEmbeddedWallet(config.walletAddress);
 }

package/src/hooks/useAlchemyClient.ts

@@ -1,23 +1,20 @@
 import { useCallback } from "react";
 import {
   WalletClientSigner,
-  type AuthorizationRequest,
   ConnectionConfigSchema,
   type SmartContractAccount,
 } from "@aa-sdk/core";
-import {
-  createWalletClient,
-  custom,
-  type Address,
-  type Authorization,
-} from "viem";
-import { useSign7702Authorization } from "@privy-io/react-auth";
+import { createWalletClient, custom, type Address } from "viem";
 import {
   createSmartWalletClient,
   type SmartWalletClient,
 } from "@account-kit/wallet-client";
 import { alchemy } from "@account-kit/infra";
-import { useAlchemyConfig, useClientCache } from "../Provider.js";
+import {
+  useAlchemyConfig,
+  useClientCache,
+  useAdapter,
+} from "../context/AlchemyContext.js";
 import { getChain } from "../util/getChain.js";
 import { useEmbeddedWallet } from "./internal/useEmbeddedWallet.js";
 
@@ -40,42 +37,43 @@ export type AlchemyClientResult = {
  * ```
  */
 export function useAlchemyClient() {
-  const { signAuthorization } = useSign7702Authorization();
+  const adapter = useAdapter();
   const config = useAlchemyConfig();
+  const signAuthorizationFn =
+    adapter.useAuthorizationSigner?.(config.walletAddress) || null;
   const cache = useClientCache();
   const getEmbeddedWallet = useEmbeddedWallet();
 
-  const getEmbeddedWalletChain = useCallback(() => {
-    const embedded = getEmbeddedWallet();
+  const getClient = useCallback(async (): Promise<AlchemyClientResult> => {
+    const embeddedWallet = getEmbeddedWallet();
+
+    // IMPORTANT: Get provider FIRST to ensure chain ID is updated
+    // The provider fetch triggers chain ID update in the adapter
+    const provider = await embeddedWallet.getEthereumProvider();
+
+    // NOW get the chain from the SAME wallet instance with updated chain ID
     // Handle CAIP-2 format like "eip155:1"
-    const chainIdStr = embedded.chainId?.toString();
+    const chainIdStr = embeddedWallet.chainId?.toString();
 
     if (!chainIdStr) {
       throw new Error(
         "Embedded wallet chainId is not set. Please ensure the wallet is connected to a network.",
       );
     }
-
     const numericChainId = chainIdStr.includes(":")
       ? chainIdStr.split(":")[1]
       : chainIdStr;
-
     const parsedChainId = Number(numericChainId);
-
     if (isNaN(parsedChainId)) {
       throw new Error(
         `Failed to parse chainId from embedded wallet. Received: ${chainIdStr}`,
       );
     }
 
-    return getChain(parsedChainId);
-  }, [getEmbeddedWallet]);
-
-  const getClient = useCallback(async (): Promise<AlchemyClientResult> => {
-    const embeddedWallet = getEmbeddedWallet();
-    const chain = getEmbeddedWalletChain();
+    const chain = getChain(parsedChainId);
 
     // Generate a cache key based on configuration and wallet address
+    // IMPORTANT: Include whether authorization signing is supported in cache key
     const currentCacheKey = JSON.stringify({
       address: embeddedWallet.address,
       chainId: chain.id,
@@ -84,6 +82,7 @@ export function useAlchemyClient() {
       rpcUrl: config.rpcUrl,
       policyId: config.policyId,
       accountAuthMode: config.accountAuthMode,
+      supportsSignAuthorization: !!signAuthorizationFn,
     });
 
     // Return cached client and account if configuration hasn't changed
@@ -91,9 +90,6 @@ export function useAlchemyClient() {
       return { client: cache.client, account: cache.account };
     }
 
-    // Configuration changed or no cache exists, create new client
-    const provider = await embeddedWallet.getEthereumProvider();
-
     // Create base signer from Privy wallet
     const baseSigner = new WalletClientSigner(
       createWalletClient({
@@ -106,19 +102,10 @@ export function useAlchemyClient() {
 
     // Optionally extend signer with EIP-7702 authorization support
     const signer =
-      config.accountAuthMode === "eip7702"
+      config.accountAuthMode === "eip7702" && !!signAuthorizationFn
         ? {
             ...baseSigner,
-            signAuthorization: async (
-              unsignedAuth: AuthorizationRequest<number>,
-            ): Promise<Authorization<number, true>> => {
-              const signature = await signAuthorization({
-                ...unsignedAuth,
-                contractAddress:
-                  unsignedAuth.address ?? unsignedAuth.contractAddress,
-              });
-              return { ...unsignedAuth, ...signature };
-            },
+            signAuthorization: signAuthorizationFn,
           }
         : baseSigner;
 
@@ -166,8 +153,7 @@ export function useAlchemyClient() {
     return { client: cache.client, account: cache.account };
   }, [
     getEmbeddedWallet,
-    getEmbeddedWalletChain,
-    signAuthorization,
+    signAuthorizationFn,
     config.apiKey,
     config.jwt,
     config.rpcUrl,

package/src/hooks/useAlchemySendTransaction.ts

@@ -1,7 +1,7 @@
 import { useCallback, useState } from "react";
 import { type Hex, isHex } from "viem";
 import { useAlchemyClient } from "./useAlchemyClient.js";
-import { useAlchemyConfig } from "../Provider.js";
+import { useAlchemyConfig } from "../context/AlchemyContext.js";
 import type {
   UnsignedTransactionRequest,
   SendTransactionOptions,

package/src/hooks/useAlchemySolanaTransaction.ts

@@ -7,7 +7,7 @@ import {
   TransactionInstruction,
   VersionedTransaction,
 } from "@solana/web3.js";
-import { useAlchemyConfig } from "../Provider.js";
+import { useAlchemyConfig } from "../context/AlchemyContext.js";
 import { createSolanaSponsoredTransaction } from "../util/createSolanaSponsoredTransaction.js";
 import { useSignTransaction, useWallets } from "@privy-io/react-auth/solana";
 import { createSolanaTransaction } from "../util/createSolanaTransaction.js";

package/src/providers/ReactNativeProvider.tsx

@@ -0,0 +1,49 @@
+import type { PropsWithChildren } from "react";
+import { AlchemyContextProvider } from "../context/AlchemyContext.js";
+import { reactNativeAdapter } from "../adapters/react-native.js";
+import type { AlchemyProviderConfig } from "../types.js";
+
+/**
+ * Provider component for React Native (Expo) applications
+ * Must be nested INSIDE PrivyProvider from @privy-io/expo
+ *
+ * @param {PropsWithChildren<AlchemyProviderConfig>} props - Component props
+ * @param {React.ReactNode} props.children - React children to wrap with Alchemy configuration
+ * @param {string} [props.apiKey] - Your Alchemy API key
+ * @param {string} [props.jwt] - JWT token for authentication
+ * @param {string} [props.rpcUrl] - Custom RPC URL for EVM chains
+ * @param {string} [props.solanaRpcUrl] - Custom RPC URL for Solana
+ * @param {string | string[]} [props.policyId] - Gas Manager policy ID(s) for EVM chains
+ * @param {string | string[]} [props.solanaPolicyId] - Gas Manager policy ID(s) for Solana
+ * @param {boolean} [props.disableSponsorship] - Set to true to disable sponsorship by default (default: false)
+ * @param {'eip7702' | 'owner'} [props.accountAuthMode] - Authorization mode for EVM smart accounts (default: 'eip7702')
+ * @param {string} [props.walletAddress] - Optional: Specify which wallet address to use (defaults to first wallet in array)
+ * @returns {JSX.Element} Provider component
+ *
+ * @example
+ * ```tsx
+ * import { PrivyProvider } from '@privy-io/expo';
+ * import { AlchemyProvider } from '@account-kit/privy-integration/react-native';
+ *
+ * <PrivyProvider appId="..." clientId="...">
+ *   <AlchemyProvider
+ *     apiKey="your-alchemy-api-key"
+ *     policyId="your-gas-policy-id"
+ *     accountAuthMode="eip7702"
+ *     walletAddress="0x123..." // Optional: specify which wallet to use
+ *   >
+ *     <YourApp />
+ *   </AlchemyProvider>
+ * </PrivyProvider>
+ * ```
+ */
+export function AlchemyProvider({
+  children,
+  ...config
+}: PropsWithChildren<AlchemyProviderConfig>) {
+  return (
+    <AlchemyContextProvider config={config} adapter={reactNativeAdapter}>
+      {children}
+    </AlchemyContextProvider>
+  );
+}

package/src/providers/WebProvider.native.tsx

@@ -0,0 +1,11 @@
+/**
+ * React Native stub for WebProvider
+ * This file prevents Metro from importing web-specific code
+ */
+
+export function AlchemyProvider() {
+  throw new Error(
+    "This module requires @privy-io/react-auth which is not available in React Native. " +
+      'Import from "@account-kit/privy-integration/react-native" instead.',
+  );
+}

package/src/providers/WebProvider.tsx

@@ -0,0 +1,49 @@
+import type { PropsWithChildren } from "react";
+import { AlchemyContextProvider } from "../context/AlchemyContext.js";
+import { webAdapter } from "../adapters/web.js";
+import type { AlchemyProviderConfig } from "../types.js";
+
+/**
+ * Provider component for React web applications
+ * Must be nested INSIDE PrivyProvider from @privy-io/react-auth
+ *
+ * @param {PropsWithChildren<AlchemyProviderConfig>} props - Component props
+ * @param {React.ReactNode} props.children - React children to wrap with Alchemy configuration
+ * @param {string} [props.apiKey] - Your Alchemy API key
+ * @param {string} [props.jwt] - JWT token for authentication
+ * @param {string} [props.rpcUrl] - Custom RPC URL for EVM chains
+ * @param {string} [props.solanaRpcUrl] - Custom RPC URL for Solana
+ * @param {string | string[]} [props.policyId] - Gas Manager policy ID(s) for EVM chains
+ * @param {string | string[]} [props.solanaPolicyId] - Gas Manager policy ID(s) for Solana
+ * @param {boolean} [props.disableSponsorship] - Set to true to disable sponsorship by default (default: false)
+ * @param {'eip7702' | 'owner'} [props.accountAuthMode] - Authorization mode for EVM smart accounts (default: 'eip7702')
+ * @param {string} [props.walletAddress] - Optional: Specify which wallet address to use (defaults to first embedded wallet)
+ * @returns {JSX.Element} Provider component
+ *
+ * @example
+ * ```tsx
+ * import { PrivyProvider } from '@privy-io/react-auth';
+ * import { AlchemyProvider } from '@account-kit/privy-integration';
+ *
+ * <PrivyProvider appId="...">
+ *   <AlchemyProvider
+ *     apiKey="your-alchemy-api-key"
+ *     policyId="your-gas-policy-id"
+ *     accountAuthMode="eip7702"
+ *     walletAddress="0x123..." // Optional: specify which wallet to use
+ *   >
+ *     <YourApp />
+ *   </AlchemyProvider>
+ * </PrivyProvider>
+ * ```
+ */
+export function AlchemyProvider({
+  children,
+  ...config
+}: PropsWithChildren<AlchemyProviderConfig>) {
+  return (
+    <AlchemyContextProvider config={config} adapter={webAdapter}>
+      {children}
+    </AlchemyContextProvider>
+  );
+}