@account-kit/privy-integration 4.68.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@account-kit/privy-integration",
+  "version": "4.68.0",
+  "description": "Use Alchemy gas sponsorship, swaps and more with Privy",
+  "author": "Alchemy",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "./dist/esm/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "typings": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "!dist/**/*.tsbuildinfo",
+    "!vitest.config.ts",
+    "!.env",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/__tests__/**/*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "prebuild": "tsx ./inject-version.ts",
+    "build": "yarn clean && yarn build:esm && yarn build:types",
+    "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
+    "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
+    "clean": "rm -rf ./dist",
+    "test": "vitest --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@privy-io/react-auth": "^2.3.1",
+    "typescript-template": "*"
+  },
+  "dependencies": {
+    "@account-kit/infra": "^4.68.0",
+    "@account-kit/wallet-client": "^4.68.0"
+  },
+  "peerDependencies": {
+    "@privy-io/react-auth": "^2.3.1 || ^3.0.0",
+    "viem": "^2.29.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alchemyplatform/aa-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alchemyplatform/aa-sdk/issues"
+  },
+  "homepage": "https://github.com/alchemyplatform/aa-sdk#readme",
+  "gitHead": "f95d7f917b6d5b6ef9fa53a2bcaa658bd6aa6673"
+}

package/src/hooks/internal/useEmbeddedWallet.ts

@@ -0,0 +1,29 @@
+import { useCallback } from "react";
+import {
+  useWallets,
+  type ConnectedWallet as PrivyWallet,
+} from "@privy-io/react-auth";
+
+/**
+ * Internal hook to get the Privy embedded wallet
+ * Shared across multiple hooks to avoid duplication
+ *
+ * @internal
+ * @returns {() => PrivyWallet} 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;
+}

package/src/hooks/useAlchemyClient.ts

@@ -0,0 +1,160 @@
+import { useCallback } from "react";
+import {
+  WalletClientSigner,
+  type AuthorizationRequest,
+  ConnectionConfigSchema,
+} from "@aa-sdk/core";
+import {
+  createWalletClient,
+  custom,
+  type Address,
+  type Authorization,
+} from "viem";
+import { useSign7702Authorization } from "@privy-io/react-auth";
+import {
+  createSmartWalletClient,
+  type SmartWalletClient,
+} from "@account-kit/wallet-client";
+import { alchemy } from "@account-kit/infra";
+import { useAlchemyConfig, useClientCache } from "../Provider.js";
+import { getChain } from "../util/getChain.js";
+import { useEmbeddedWallet } from "./internal/useEmbeddedWallet.js";
+
+/**
+ * Hook to get and memoize a SmartWalletClient instance
+ * The client is cached in the AlchemyProvider context (React tree scoped)
+ * Automatically clears cache on logout via the provider
+ *
+ * @returns {{ getClient: () => Promise<SmartWalletClient> }} Object containing the smart wallet client getter
+ *
+ * @example
+ * ```tsx
+ * const { getClient } = useAlchemyClient();
+ * const smartWalletClient = await getClient();
+ * ```
+ */
+export function useAlchemyClient() {
+  const { signAuthorization } = useSign7702Authorization();
+  const config = useAlchemyConfig();
+  const cache = useClientCache();
+  const getEmbeddedWallet = useEmbeddedWallet();
+
+  const getEmbeddedWalletChain = useCallback(() => {
+    const embedded = getEmbeddedWallet();
+    // Handle CAIP-2 format like "eip155:1"
+    const chainIdStr = embedded.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<SmartWalletClient> => {
+    const embeddedWallet = getEmbeddedWallet();
+    const chain = getEmbeddedWalletChain();
+
+    // Generate a cache key based on configuration and wallet address
+    const currentCacheKey = JSON.stringify({
+      address: embeddedWallet.address,
+      chainId: chain.id,
+      apiKey: config.apiKey,
+      jwt: config.jwt,
+      rpcUrl: config.rpcUrl,
+      policyId: config.policyId,
+    });
+
+    // Return cached client if configuration hasn't changed
+    if (cache.client && cache.cacheKey === currentCacheKey) {
+      return cache.client;
+    }
+
+    // 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({
+        account: embeddedWallet.address as Address,
+        chain,
+        transport: custom(provider),
+      }),
+      "privy",
+    );
+
+    // Extend signer with EIP-7702 authorization support
+    const signer = {
+      ...baseSigner,
+      signAuthorization: async (
+        unsignedAuth: AuthorizationRequest<number>,
+      ): Promise<Authorization<number, true>> => {
+        const signature = await signAuthorization({
+          ...unsignedAuth,
+          contractAddress: unsignedAuth.address ?? unsignedAuth.contractAddress,
+        });
+
+        return {
+          ...unsignedAuth,
+          ...signature,
+        };
+      },
+    };
+
+    // Determine transport configuration using schema validation
+    // This properly handles combinations like rpcUrl + jwt together
+    const transportConfig = ConnectionConfigSchema.parse({
+      rpcUrl: config.rpcUrl,
+      apiKey: config.apiKey,
+      jwt: config.jwt,
+    });
+
+    const transport = alchemy(transportConfig);
+
+    transport.updateHeaders({
+      "X-Alchemy-Client-Breadcrumb": "privyIntegrationSdk",
+    });
+
+    // Create and cache the smart wallet client in provider context
+    cache.client = createSmartWalletClient({
+      chain,
+      transport,
+      signer,
+      policyIds: config.policyId
+        ? Array.isArray(config.policyId)
+          ? config.policyId
+          : [config.policyId]
+        : undefined,
+    });
+
+    // Store the cache key
+    cache.cacheKey = currentCacheKey;
+
+    return cache.client;
+  }, [
+    getEmbeddedWallet,
+    getEmbeddedWalletChain,
+    signAuthorization,
+    config.apiKey,
+    config.jwt,
+    config.rpcUrl,
+    config.policyId,
+    cache,
+  ]);
+
+  return { getClient };
+}

package/src/hooks/useAlchemyPrepareSwap.ts

@@ -0,0 +1,113 @@
+import { useCallback, useState } from "react";
+import { type Address } from "viem";
+import { swapActions } from "@account-kit/wallet-client/experimental";
+import { useAlchemyClient } from "./useAlchemyClient.js";
+import { useEmbeddedWallet } from "./internal/useEmbeddedWallet.js";
+import type {
+  PrepareSwapRequest,
+  PrepareSwapResult,
+  UsePrepareSwapResult,
+} from "../types";
+
+/**
+ * Hook to request swap quotes and prepare swap calls
+ * Part of the two-step swap process: prepare → submit
+ * Use with `useAlchemySubmitSwap()` to execute the prepared swap
+ *
+ * Supports two modes:
+ * 1. Specify exact amount to swap FROM (`fromAmount`)
+ * 2. Specify minimum amount to receive TO (`minimumToAmount`)
+ *
+ * @returns {UsePrepareSwapResult} Hook result with prepareSwap function and state
+ *
+ * @example Complete swap flow
+ * ```tsx
+ * const { prepareSwap } = useAlchemyPrepareSwap();
+ * const { submitSwap } = useAlchemySubmitSwap();
+ *
+ * // Step 1: Prepare the swap (get quote)
+ * const preparedSwap = await prepareSwap({
+ *   fromToken: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
+ *   toToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *   fromAmount: '0xde0b6b3a7640000', // 1 ETH in hex
+ * });
+ *
+ * // Step 2: Execute the swap
+ * const result = await submitSwap(preparedSwap);
+ * ```
+ *
+ * @example Swap for minimum amount TO
+ * ```tsx
+ * const { prepareSwap } = useAlchemyPrepareSwap();
+ *
+ * // Swap ETH to get at least 100 USDC
+ * const result = await prepareSwap({
+ *   fromToken: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
+ *   toToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *   minimumToAmount: '0x5f5e100', // 100 USDC (6 decimals) in hex
+ * });
+ * console.log('Quote expiry:', new Date(parseInt(result.quote.expiry, 16) * 1000));
+ * ```
+ */
+export function useAlchemyPrepareSwap(): UsePrepareSwapResult {
+  const { getClient } = useAlchemyClient();
+  const getEmbeddedWallet = useEmbeddedWallet();
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setData] = useState<PrepareSwapResult | null>(null);
+
+  const prepareSwap = useCallback(
+    async (request: PrepareSwapRequest): Promise<PrepareSwapResult> => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const client = await getClient();
+        const embeddedWallet = getEmbeddedWallet();
+
+        // Extend client with swap actions
+        const swapClient = client.extend(swapActions);
+
+        // Request the swap quote
+        // Note: Gas sponsorship capabilities are configured on the client itself
+        const response = await swapClient.requestQuoteV0({
+          ...request,
+          from: request.from || (embeddedWallet.address as Address),
+        });
+
+        // Validate that we got prepared calls, not raw calls
+        if (response.rawCalls) {
+          throw new Error(
+            "Received raw calls instead of prepared calls. Ensure returnRawCalls is not set to true.",
+          );
+        }
+
+        setData(response);
+        return response;
+      } catch (err) {
+        const errorObj =
+          err instanceof Error ? err : new Error("Failed to prepare swap");
+        setError(errorObj);
+        throw errorObj;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [getClient, getEmbeddedWallet],
+  );
+
+  const reset = useCallback(() => {
+    setError(null);
+    setData(null);
+    setIsLoading(false);
+  }, []);
+
+  return {
+    prepareSwap,
+    isLoading,
+    error,
+    data,
+    reset,
+  };
+}

package/src/hooks/useAlchemySendTransaction.ts

@@ -0,0 +1,160 @@
+import { useCallback, useState } from "react";
+import { type Address, type Hex, isHex } from "viem";
+import { useAlchemyClient } from "./useAlchemyClient.js";
+import { useAlchemyConfig } from "../Provider.js";
+import { useEmbeddedWallet } from "./internal/useEmbeddedWallet.js";
+import type {
+  UnsignedTransactionRequest,
+  SendTransactionOptions,
+  SendTransactionResult,
+  UseSendTransactionResult,
+} from "../types";
+
+/**
+ * Normalize value to hex format
+ * Accepts bigint, number, decimal string, or hex string
+ *
+ * @param {string | number | bigint} value - Value to normalize
+ * @returns {Hex} Hex string representation of the value
+ */
+function normalizeValue(value: string | number | bigint): Hex {
+  if (typeof value === "bigint") {
+    return `0x${value.toString(16)}`;
+  }
+  if (typeof value === "number") {
+    return `0x${BigInt(value).toString(16)}`;
+  }
+  if (isHex(value)) {
+    return value;
+  }
+  // Assume decimal string
+  return `0x${BigInt(value).toString(16)}`;
+}
+
+/**
+ * Hook to send transactions with optional gas sponsorship via Alchemy
+ * Drop-in alternative to Privy's useSendTransaction hook
+ *
+ * @returns {UseSendTransactionResult} Hook result with sendTransaction function and state
+ *
+ * @example
+ * ```tsx
+ * const { sendTransaction, isLoading, error, data } = useAlchemySendTransaction();
+ *
+ * const handleSend = async () => {
+ *   try {
+ *     const result = await sendTransaction({
+ *       to: '0x...',
+ *       data: '0x...',
+ *       value: '1000000000000000000', // 1 ETH
+ *     });
+ *     console.log('Transaction hash:', result.txnHash);
+ *   } catch (err) {
+ *     console.error('Transaction failed:', err);
+ *   }
+ * };
+ * ```
+ */
+export function useAlchemySendTransaction(): UseSendTransactionResult {
+  const { getClient } = useAlchemyClient();
+  const config = useAlchemyConfig();
+  const getEmbeddedWallet = useEmbeddedWallet();
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setData] = useState<SendTransactionResult | null>(null);
+
+  const sendTransaction = useCallback(
+    async (
+      input: UnsignedTransactionRequest,
+      options?: SendTransactionOptions,
+    ): Promise<SendTransactionResult> => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const client = await getClient();
+        const embeddedWallet = getEmbeddedWallet();
+
+        // Determine if transaction should be sponsored
+        const hasPolicyId = !!config.policyId;
+        const enableSponsorship = !config.disableSponsorship;
+        const shouldSponsor =
+          options?.disableSponsorship !== undefined
+            ? !options.disableSponsorship
+            : hasPolicyId && enableSponsorship;
+
+        // Format the transaction call
+        const formattedCall = {
+          to: input.to,
+          data: input.data,
+          value: input.value ? normalizeValue(input.value) : undefined,
+        };
+
+        // Build capabilities based on sponsorship
+        const policyId = Array.isArray(config.policyId)
+          ? config.policyId[0]
+          : config.policyId;
+
+        const capabilities: {
+          eip7702Auth: true;
+          paymasterService?: { policyId: string };
+        } = { eip7702Auth: true };
+
+        if (shouldSponsor && policyId) {
+          capabilities.paymasterService = { policyId };
+        }
+
+        // Send the transaction
+        const result = await client.sendCalls({
+          from: embeddedWallet.address as Address,
+          calls: [formattedCall],
+          capabilities,
+        });
+
+        if (!result.preparedCallIds || result.preparedCallIds.length === 0) {
+          throw new Error(
+            "No prepared call IDs returned from transaction submission",
+          );
+        }
+
+        // Wait for the transaction to be confirmed
+        const txStatus = await client.waitForCallsStatus({
+          id: result.preparedCallIds[0],
+          timeout: 60_000,
+        });
+
+        const txnHash = txStatus.receipts?.[0]?.transactionHash;
+        if (!txnHash) {
+          throw new Error("Transaction hash not found in receipt");
+        }
+
+        const txResult: SendTransactionResult = { txnHash };
+        setData(txResult);
+        return txResult;
+      } catch (err) {
+        const errorObj =
+          err instanceof Error ? err : new Error("Transaction failed");
+        setError(errorObj);
+        throw errorObj;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [getClient, getEmbeddedWallet, config.policyId, config.disableSponsorship],
+  );
+
+  const reset = useCallback(() => {
+    setError(null);
+    setData(null);
+    setIsLoading(false);
+  }, []);
+
+  return {
+    sendTransaction,
+    isLoading,
+    error,
+    data,
+    reset,
+  };
+}

package/src/hooks/useAlchemySubmitSwap.ts

@@ -0,0 +1,120 @@
+import { useCallback, useState } from "react";
+import { swapActions } from "@account-kit/wallet-client/experimental";
+import { useAlchemyClient } from "./useAlchemyClient.js";
+import type {
+  PrepareSwapResult,
+  SubmitSwapResult,
+  UseSubmitSwapResult,
+} from "../types.js";
+
+/**
+ * Hook to sign and submit prepared swap calls
+ * Part of the two-step swap process: prepare → submit
+ *
+ * @returns {UseSubmitSwapResult} Hook result with submitSwap function and state
+ *
+ * @example
+ * ```tsx
+ * const { prepareSwap } = useAlchemyPrepareSwap();
+ * const { submitSwap, isLoading, error, data } = useAlchemySubmitSwap();
+ *
+ * const handleSwap = async () => {
+ *   try {
+ *     // Step 1: Prepare the swap
+ *     const preparedSwap = await prepareSwap({
+ *       fromToken: '0x...',
+ *       toToken: '0x...',
+ *       fromAmount: '0x...',
+ *     });
+ *
+ *     // Step 2: Submit the swap
+ *     const result = await submitSwap(preparedSwap);
+ *     console.log('Swap confirmed:', result.txnHash);
+ *   } catch (err) {
+ *     console.error('Swap failed:', err);
+ *   }
+ * };
+ * ```
+ */
+export function useAlchemySubmitSwap(): UseSubmitSwapResult {
+  const { getClient } = useAlchemyClient();
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setData] = useState<SubmitSwapResult | null>(null);
+
+  const submitSwap = useCallback(
+    async (preparedSwap: PrepareSwapResult): Promise<SubmitSwapResult> => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const client = await getClient();
+
+        // Extend client with swap actions
+        const swapClient = client.extend(swapActions);
+
+        // Sign the prepared calls
+        const signedCalls = await swapClient.signPreparedCalls(preparedSwap);
+
+        // Send the signed calls
+        const { preparedCallIds } =
+          await swapClient.sendPreparedCalls(signedCalls);
+
+        if (!preparedCallIds || preparedCallIds.length === 0) {
+          throw new Error("No prepared call IDs returned from swap submission");
+        }
+
+        // Wait for the swap to be confirmed
+        const callStatusResult = await swapClient.waitForCallsStatus({
+          id: preparedCallIds[0],
+          timeout: 60_000,
+        });
+
+        // Validate the transaction was successful
+        if (
+          callStatusResult.status !== "success" ||
+          !callStatusResult.receipts ||
+          !callStatusResult.receipts[0]
+        ) {
+          throw new Error(
+            `Swap failed with status ${
+              callStatusResult.status
+            }. Full receipt:\n${JSON.stringify(callStatusResult, null, 2)}`,
+          );
+        }
+
+        const txnHash = callStatusResult.receipts[0].transactionHash;
+        if (!txnHash) {
+          throw new Error("Transaction hash not found in receipt");
+        }
+
+        const result: SubmitSwapResult = { txnHash };
+        setData(result);
+        return result;
+      } catch (err) {
+        const errorObj =
+          err instanceof Error ? err : new Error("Failed to submit swap");
+        setError(errorObj);
+        throw errorObj;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [getClient],
+  );
+
+  const reset = useCallback(() => {
+    setError(null);
+    setData(null);
+    setIsLoading(false);
+  }, []);
+
+  return {
+    submitSwap,
+    isLoading,
+    error,
+    data,
+    reset,
+  };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// Provider
+export { AlchemyProvider, useAlchemyConfig } from "./Provider.js";
+
+// Hooks
+export { useAlchemyClient } from "./hooks/useAlchemyClient.js";
+export { useAlchemySendTransaction } from "./hooks/useAlchemySendTransaction.js";
+export { useAlchemyPrepareSwap } from "./hooks/useAlchemyPrepareSwap.js";
+export { useAlchemySubmitSwap } from "./hooks/useAlchemySubmitSwap.js";
+
+// Types
+export type {
+  AlchemyProviderConfig,
+  UnsignedTransactionRequest,
+  SendTransactionOptions,
+  SendTransactionResult,
+  UseSendTransactionResult,
+  PrepareSwapRequest,
+  PrepareSwapResult,
+  UsePrepareSwapResult,
+  SubmitSwapResult,
+  UseSubmitSwapResult,
+  SwapQuote,
+} from "./types.js";