@account-kit/privy-integration 4.68.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Alchemy Insights, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,372 @@
+# @account-kit/privy-integration
+
+Add gas sponsorship and smart wallet features to your Privy app in under 5 minutes.
+
+## What This Package Does
+
+If you're already using [Privy](https://privy.io) for authentication, this package lets you upgrade your users' wallets with:
+
+- **🔄 EIP-7702 Delegation** - Upgrade EOAs to smart accounts without migration
+- **⛽ Gas Sponsorship** - Pay gas fees for your users via Alchemy Gas Manager
+- **💱 Token Swaps** - Execute swaps through Alchemy's swap infrastructure
+- **🚀 Batched Transactions** - Send multiple operations in a single transaction
+
+All while keeping Privy as your authentication provider. No need to change your auth flow or migrate user accounts.
+
+## Why Use This?
+
+**Already using Privy?** Add smart account features without changing your existing setup:
+
+- Drop-in React hooks that replace Privy's transaction hooks
+- Automatic EIP-7702 delegation to upgrade wallets on-the-fly
+- Route transactions through Alchemy's infrastructure for sponsorship and reliability
+
+## Installation
+
+```bash
+npm install @account-kit/privy-integration
+# or
+yarn add @account-kit/privy-integration
+# or
+pnpm add @account-kit/privy-integration
+```
+
+## Quick Start
+
+### 1. Wrap Your App with Both Providers
+
+**Important:** `AlchemyProvider` must be nested **inside** `PrivyProvider` to access authentication state.
+
+```tsx
+import { PrivyProvider } from "@privy-io/react-auth";
+import { AlchemyProvider } from "@account-kit/privy-integration";
+
+function App() {
+  return (
+    <PrivyProvider
+      appId="your-privy-app-id"
+      config={
+        {
+          /* your privy config */
+        }
+      }
+    >
+      <AlchemyProvider
+        apiKey="your-alchemy-api-key"
+        policyId="your-gas-policy-id" // optional, for gas sponsorship
+      >
+        <YourApp />
+      </AlchemyProvider>
+    </PrivyProvider>
+  );
+}
+```
+
+### 2. Send Gasless Transactions
+
+```tsx
+import { useAlchemySendTransaction } from "@account-kit/privy-integration";
+
+function SendButton() {
+  const { sendTransaction, isLoading, error, data } =
+    useAlchemySendTransaction();
+
+  const handleSend = async () => {
+    try {
+      const result = await sendTransaction({
+        to: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
+        data: "0x...",
+        value: "1000000000000000000", // 1 ETH
+      });
+
+      console.log("Transaction hash:", result.txnHash);
+    } catch (err) {
+      console.error("Transaction failed:", err);
+    }
+  };
+
+  return (
+    <button onClick={handleSend} disabled={isLoading}>
+      {isLoading ? "Sending..." : "Send Transaction"}
+    </button>
+  );
+}
+```
+
+### 3. Execute Token Swaps
+
+```tsx
+import {
+  useAlchemyPrepareSwap,
+  useAlchemySubmitSwap,
+} from "@account-kit/privy-integration";
+
+function SwapButton() {
+  const { prepareSwap } = useAlchemyPrepareSwap();
+  const { submitSwap, isLoading } = useAlchemySubmitSwap();
+
+  const handleSwap = async () => {
+    try {
+      // Step 1: Get quote and prepare swap
+      // Two modes available:
+
+      // Option A: Specify exact amount to swap FROM
+      const preparedSwap = await prepareSwap({
+        fromToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+        toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+        fromAmount: "0xde0b6b3a7640000", // Swap exactly 1 ETH
+      });
+
+      // Option B: Specify minimum amount to receive TO
+      /* const preparedSwap = await prepareSwap({
+        fromToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+        toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+        minimumToAmount: "0x5f5e100", // Receive at least 100 USDC (6 decimals)
+      }); */
+
+      console.log(
+        "Quote expiry:",
+        new Date(parseInt(preparedSwap.quote.expiry) * 1000),
+      );
+
+      // Step 2: Execute swap
+      const result = await submitSwap(preparedSwap);
+      console.log("Swap confirmed:", result.txnHash);
+    } catch (err) {
+      console.error("Swap failed:", err);
+    }
+  };
+
+  return (
+    <button onClick={handleSwap} disabled={isLoading}>
+      {isLoading ? "Swapping..." : "Swap Tokens"}
+    </button>
+  );
+}
+```
+
+## Configuration
+
+### AlchemyProvider Props
+
+| Prop                 | Type                 | Required      | Description                                                                                          |
+| -------------------- | -------------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
+| `apiKey`             | `string`             | Conditional\* | Your Alchemy API key for @account-kit/infra transport                                                |
+| `jwt`                | `string`             | Conditional\* | JWT token for authentication (alternative to `apiKey`)                                               |
+| `rpcUrl`             | `string`             | Conditional\* | Custom RPC URL (can be used alone or with `jwt`)                                                     |
+| `policyId`           | `string \| string[]` | No            | Gas Manager policy ID(s) for sponsorship. If array is provided, backend uses first applicable policy |
+| `disableSponsorship` | `boolean`            | No            | Set to `true` to disable gas sponsorship by default (default: `false`)                               |
+
+\* **Required configuration (pick one):**
+
+- `apiKey` alone
+- `jwt` alone
+- `rpcUrl` alone
+- `rpcUrl` + `jwt` together
+
+### Transaction Options
+
+Control sponsorship per transaction:
+
+```tsx
+// Sponsored transaction (default if policyId is set and disableSponsorship is not true)
+await sendTransaction({ to: "0x...", data: "0x..." });
+
+// Disable sponsorship for this specific transaction
+await sendTransaction(
+  { to: "0x...", data: "0x..." },
+  { disableSponsorship: true },
+);
+```
+
+## API Reference
+
+### Hooks
+
+#### `useAlchemySendTransaction()`
+
+Send transactions with optional gas sponsorship.
+
+**Returns:**
+
+- `sendTransaction(input, options?)` - Send a transaction
+- `isLoading` - Loading state
+- `error` - Error object if failed
+- `data` - Transaction result with `txnHash`
+- `reset()` - Reset hook state
+
+#### `useAlchemyPrepareSwap()`
+
+Request swap quotes and prepare swap calls.
+
+**Returns:**
+
+- `prepareSwap(request)` - Get quote and prepare swap (returns full response with `quote` and call data)
+- `isLoading` - Loading state
+- `error` - Error object if failed
+- `data` - Prepared swap result
+- `reset()` - Reset hook state
+
+#### `useAlchemySubmitSwap()`
+
+Sign and submit prepared swap calls.
+
+**Returns:**
+
+- `submitSwap(preparedSwap)` - Execute prepared swap (accepts result from `prepareSwap`)
+- `isLoading` - Loading state
+- `error` - Error object if failed
+- `data` - Swap result with `txnHash`
+- `reset()` - Reset hook state
+
+#### `useAlchemyClient()`
+
+Get the underlying smart wallet client (advanced use cases).
+
+**Returns:**
+
+- `getClient()` - Async function that returns `SmartWalletClient`
+
+## How It Works
+
+### EIP-7702 Delegation
+
+This package uses [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) to upgrade your users' Privy wallets into smart accounts **without requiring them to deploy new contracts or migrate funds**.
+
+When a user sends their first transaction:
+
+1. Their EOA signs an EIP-7702 authorization
+2. The authorization delegates to Alchemy's smart account implementation
+3. The transaction is executed with smart account features (batching, sponsorship, etc.)
+4. Gas is optionally sponsored by your Gas Manager policy
+
+### Smart Wallet Client
+
+Under the hood, this package:
+
+1. Connects to your user's Privy embedded wallet
+2. Wraps it with `WalletClientSigner` from `@aa-sdk/core`
+3. Creates a `SmartWalletClient` with EIP-7702 support
+4. Routes transactions through Alchemy infrastructure
+5. Automatically handles sponsorship via Gas Manager policies
+
+## Get Your API Keys
+
+### Alchemy API Key
+
+1. Go to [Alchemy Dashboard](https://dashboard.alchemy.com/)
+2. Create or select an app
+3. Copy your API key
+
+### Gas Manager Policy ID (Optional)
+
+1. Go to [Gas Manager](https://dashboard.alchemy.com/gas-manager)
+2. Create a new policy with your desired rules
+3. Copy the policy ID
+
+### Privy App ID
+
+1. Go to [Privy Dashboard](https://dashboard.privy.io/)
+2. Create or select an app
+3. Copy your app ID
+
+## Migration from Privy Transactions
+
+If you're currently using Privy's `useSendTransaction` hook:
+
+### Before
+
+```tsx
+import { useSendTransaction } from "@privy-io/react-auth";
+
+const { sendTransaction } = useSendTransaction({
+  onSuccess: (txHash) => console.log(txHash),
+});
+```
+
+### After
+
+```tsx
+import { useAlchemySendTransaction } from "@account-kit/privy-integration";
+
+const { sendTransaction, data } = useAlchemySendTransaction();
+
+// Now with gas sponsorship!
+```
+
+The API is nearly identical, making migration seamless.
+
+## Advanced Usage
+
+### Access the Smart Wallet Client
+
+For advanced use cases, access the underlying client:
+
+```tsx
+import { useAlchemyClient } from "@account-kit/privy-integration";
+
+function AdvancedComponent() {
+  const { getClient } = useAlchemyClient();
+
+  const doAdvancedOperation = async () => {
+    const client = await getClient();
+
+    // Use any SmartWalletClient method
+    const address = await client.getAddress();
+
+    // Batch multiple calls
+    await client.sendCalls({
+      from: address,
+      calls: [
+        { to: "0x...", data: "0x..." },
+        { to: "0x...", data: "0x..." },
+      ],
+      capabilities: {
+        eip7702Auth: true,
+        paymasterService: { policyId: "your-policy-id" },
+      },
+    });
+  };
+
+  return <button onClick={doAdvancedOperation}>Advanced Op</button>;
+}
+```
+
+## Troubleshooting
+
+### TypeScript error: "Type ... is not assignable to type 'AlchemyProviderConfig'"
+
+The provider requires exactly one valid transport configuration. Valid combinations:
+
+- `apiKey` only
+- `jwt` only
+- `rpcUrl` only
+- `rpcUrl` + `jwt` together
+
+Invalid combinations like `apiKey` + `jwt` will now show TypeScript errors.
+
+### Swaps failing with "Received raw calls"
+
+The swap API should return prepared calls by default. This error means the API returned raw calls. Ensure you're not setting `returnRawCalls: true` in the request.
+
+## Examples
+
+Check out the [`examples/`](../../examples/) directory for complete applications:
+
+- **Privy Integration Demo** - Demos sponsored transactions and sponsored swaps
+
+## Resources
+
+- [Alchemy Smart Wallet Documentation](https://www.alchemy.com/docs/wallets/)
+- [EIP-7702 Specification](https://eips.ethereum.org/EIPS/eip-7702)
+- [Gas Manager Dashboard](https://dashboard.alchemy.com/services/gas-manager/overview)
+
+## Support
+
+- [Discord](https://discord.gg/alchemy)
+- [GitHub Issues](https://github.com/alchemyplatform/aa-sdk/issues)
+- [Alchemy Support](https://www.alchemy.com/support)
+
+## License
+
+MIT

package/dist/esm/Provider.d.ts

@@ -0,0 +1,61 @@
+import { type PropsWithChildren } from "react";
+import type { SmartWalletClient } from "@account-kit/wallet-client";
+import type { AlchemyProviderConfig } from "./types.js";
+/**
+ * Client cache stored in React tree (similar to QueryClient in React Query)
+ *
+ * @internal
+ */
+interface ClientCache {
+    client: SmartWalletClient | null;
+    cacheKey: string | null;
+}
+/**
+ * Provider component that configures Alchemy infrastructure for transaction handling
+ * Must be nested INSIDE PrivyProvider to access authentication state
+ * Automatically manages client cache lifecycle and resets on logout
+ *
+ * @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
+ * @param {string | string[]} [props.policyId] - Gas Manager policy ID(s)
+ * @param {boolean} [props.disableSponsorship] - Set to true to disable sponsorship by default (default: false)
+ * @returns {JSX.Element} Provider component
+ *
+ * @example
+ * ```tsx
+ * <PrivyProvider appId="...">
+ *   <AlchemyProvider
+ *     apiKey="your-alchemy-api-key"
+ *     policyId="your-gas-policy-id"
+ *   >
+ *     <YourApp />
+ *   </AlchemyProvider>
+ * </PrivyProvider>
+ * ```
+ */
+export declare function AlchemyProvider({ children, ...config }: PropsWithChildren<AlchemyProviderConfig>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access Alchemy provider configuration
+ * Must be used within an <AlchemyProvider> component
+ *
+ * @returns {AlchemyProviderConfig} The current Alchemy configuration
+ * @throws {Error} If used outside of AlchemyProvider
+ *
+ * @example
+ * ```tsx
+ * const config = useAlchemyConfig();
+ * console.log('Policy ID:', config.policyId);
+ * ```
+ */
+export declare function useAlchemyConfig(): AlchemyProviderConfig;
+/**
+ * Hook to access the client cache (internal use only)
+ *
+ * @internal
+ * @returns {ClientCache} The client cache object
+ */
+export declare function useClientCache(): ClientCache;
+export {};

package/dist/esm/Provider.js

@@ -0,0 +1,100 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useRef, useEffect, } from "react";
+import { usePrivy } from "@privy-io/react-auth";
+const AlchemyContext = createContext(null);
+const ClientCacheContext = createContext(null);
+/**
+ * Provider component that configures Alchemy infrastructure for transaction handling
+ * Must be nested INSIDE PrivyProvider to access authentication state
+ * Automatically manages client cache lifecycle and resets on logout
+ *
+ * @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
+ * @param {string | string[]} [props.policyId] - Gas Manager policy ID(s)
+ * @param {boolean} [props.disableSponsorship] - Set to true to disable sponsorship by default (default: false)
+ * @returns {JSX.Element} Provider component
+ *
+ * @example
+ * ```tsx
+ * <PrivyProvider appId="...">
+ *   <AlchemyProvider
+ *     apiKey="your-alchemy-api-key"
+ *     policyId="your-gas-policy-id"
+ *   >
+ *     <YourApp />
+ *   </AlchemyProvider>
+ * </PrivyProvider>
+ * ```
+ */
+export function AlchemyProvider({ children, ...config }) {
+    const { authenticated, user } = usePrivy();
+    // 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({
+        client: null,
+        cacheKey: null,
+    });
+    // Track previous state to detect logout and wallet changes
+    const prevAuthenticatedRef = useRef(authenticated);
+    const prevWalletAddressRef = useRef(user?.wallet?.address);
+    // Automatically reset cache when user logs out or switches wallets
+    useEffect(() => {
+        const wasAuthenticated = prevAuthenticatedRef.current;
+        const prevWalletAddress = prevWalletAddressRef.current;
+        const currentWalletAddress = user?.wallet?.address;
+        // Reset cache on logout
+        if (wasAuthenticated && !authenticated) {
+            cache.current.client = 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.cacheKey = null;
+        }
+        // Update refs for next render
+        prevAuthenticatedRef.current = authenticated;
+        prevWalletAddressRef.current = currentWalletAddress;
+    }, [authenticated, user?.wallet?.address]);
+    return (_jsx(AlchemyContext.Provider, { value: config, children: _jsx(ClientCacheContext.Provider, { value: cache.current, children: children }) }));
+}
+/**
+ * Hook to access Alchemy provider configuration
+ * Must be used within an <AlchemyProvider> component
+ *
+ * @returns {AlchemyProviderConfig} The current Alchemy configuration
+ * @throws {Error} If used outside of AlchemyProvider
+ *
+ * @example
+ * ```tsx
+ * const config = useAlchemyConfig();
+ * console.log('Policy ID:', config.policyId);
+ * ```
+ */
+export function useAlchemyConfig() {
+    const context = useContext(AlchemyContext);
+    if (!context) {
+        throw new Error("useAlchemyConfig must be used within <AlchemyProvider />");
+    }
+    return context;
+}
+/**
+ * Hook to access the client cache (internal use only)
+ *
+ * @internal
+ * @returns {ClientCache} The client cache object
+ */
+export function useClientCache() {
+    const context = useContext(ClientCacheContext);
+    if (!context) {
+        throw new Error("useClientCache must be used within <AlchemyProvider />. Make sure AlchemyProvider is nested inside PrivyProvider.");
+    }
+    return context;
+}
+//# sourceMappingURL=Provider.js.map

package/dist/esm/Provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Provider.js","sourceRoot":"","sources":["../../src/Provider.tsx"],"names":[],"mappings":";AAAA,OAAO,EAEL,aAAa,EACb,UAAU,EACV,MAAM,EACN,SAAS,GACV,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIhD,MAAM,cAAc,GAAG,aAAa,CAA+B,IAAI,CAAC,CAAC;AAYzE,MAAM,kBAAkB,GAAG,aAAa,CAAqB,IAAI,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,QAAQ,EACR,GAAG,MAAM,EACgC;IACzC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;IAE3C,uFAAuF;IACvF,qFAAqF;IACrF,MAAM,KAAK,GAAG,MAAM,CAAc;QAChC,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IAEH,2DAA2D;IAC3D,MAAM,oBAAoB,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;IACnD,MAAM,oBAAoB,GAAG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3D,mEAAmE;IACnE,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,gBAAgB,GAAG,oBAAoB,CAAC,OAAO,CAAC;QACtD,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,OAAO,CAAC;QACvD,MAAM,oBAAoB,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC;QAEnD,wBAAwB;QACxB,IAAI,gBAAgB,IAAI,CAAC,aAAa,EAAE,CAAC;YACvC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YAC5B,KAAK,CAAC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAChC,CAAC;QAED,2DAA2D;QAC3D,IACE,aAAa;YACb,iBAAiB;YACjB,oBAAoB;YACpB,iBAAiB,KAAK,oBAAoB,EAC1C,CAAC;YACD,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YAC5B,KAAK,CAAC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAChC,CAAC;QAED,8BAA8B;QAC9B,oBAAoB,CAAC,OAAO,GAAG,aAAa,CAAC;QAC7C,oBAAoB,CAAC,OAAO,GAAG,oBAAoB,CAAC;IACtD,CAAC,EAAE,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAE3C,OAAO,CACL,KAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YACpC,KAAC,kBAAkB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,CAAC,OAAO,YAC9C,QAAQ,GACmB,GACN,CAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mHAAmH,CACpH,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["import {\n  type PropsWithChildren,\n  createContext,\n  useContext,\n  useRef,\n  useEffect,\n} from \"react\";\nimport { usePrivy } from \"@privy-io/react-auth\";\nimport type { SmartWalletClient } from \"@account-kit/wallet-client\";\nimport type { AlchemyProviderConfig } from \"./types.js\";\n\nconst AlchemyContext = createContext<AlchemyProviderConfig | null>(null);\n\n/**\n * Client cache stored in React tree (similar to QueryClient in React Query)\n *\n * @internal\n */\ninterface ClientCache {\n  client: SmartWalletClient | null;\n  cacheKey: string | null;\n}\n\nconst ClientCacheContext = createContext<ClientCache | null>(null);\n\n/**\n * Provider component that configures Alchemy infrastructure for transaction handling\n * Must be nested INSIDE PrivyProvider to access authentication state\n * Automatically manages client cache lifecycle and resets on logout\n *\n * @param {PropsWithChildren<AlchemyProviderConfig>} props - Component props\n * @param {React.ReactNode} props.children - React children to wrap with Alchemy configuration\n * @param {string} [props.apiKey] - Your Alchemy API key\n * @param {string} [props.jwt] - JWT token for authentication\n * @param {string} [props.rpcUrl] - Custom RPC URL\n * @param {string | string[]} [props.policyId] - Gas Manager policy ID(s)\n * @param {boolean} [props.disableSponsorship] - Set to true to disable sponsorship by default (default: false)\n * @returns {JSX.Element} Provider component\n *\n * @example\n * ```tsx\n * <PrivyProvider appId=\"...\">\n *   <AlchemyProvider\n *     apiKey=\"your-alchemy-api-key\"\n *     policyId=\"your-gas-policy-id\"\n *   >\n *     <YourApp />\n *   </AlchemyProvider>\n * </PrivyProvider>\n * ```\n */\nexport function AlchemyProvider({\n  children,\n  ...config\n}: PropsWithChildren<AlchemyProviderConfig>) {\n  const { authenticated, user } = usePrivy();\n\n  // Store cache in a ref - persists across renders but scoped to this component instance\n  // This makes it SSR-safe (each request gets its own cache) and React StrictMode-safe\n  const cache = useRef<ClientCache>({\n    client: null,\n    cacheKey: null,\n  });\n\n  // Track previous state to detect logout and wallet changes\n  const prevAuthenticatedRef = useRef(authenticated);\n  const prevWalletAddressRef = useRef(user?.wallet?.address);\n\n  // Automatically reset cache when user logs out or switches wallets\n  useEffect(() => {\n    const wasAuthenticated = prevAuthenticatedRef.current;\n    const prevWalletAddress = prevWalletAddressRef.current;\n    const currentWalletAddress = user?.wallet?.address;\n\n    // Reset cache on logout\n    if (wasAuthenticated && !authenticated) {\n      cache.current.client = null;\n      cache.current.cacheKey = null;\n    }\n\n    // Reset cache on wallet address change (account switching)\n    if (\n      authenticated &&\n      prevWalletAddress &&\n      currentWalletAddress &&\n      prevWalletAddress !== currentWalletAddress\n    ) {\n      cache.current.client = null;\n      cache.current.cacheKey = null;\n    }\n\n    // Update refs for next render\n    prevAuthenticatedRef.current = authenticated;\n    prevWalletAddressRef.current = currentWalletAddress;\n  }, [authenticated, user?.wallet?.address]);\n\n  return (\n    <AlchemyContext.Provider value={config}>\n      <ClientCacheContext.Provider value={cache.current}>\n        {children}\n      </ClientCacheContext.Provider>\n    </AlchemyContext.Provider>\n  );\n}\n\n/**\n * Hook to access Alchemy provider configuration\n * Must be used within an <AlchemyProvider> component\n *\n * @returns {AlchemyProviderConfig} The current Alchemy configuration\n * @throws {Error} If used outside of AlchemyProvider\n *\n * @example\n * ```tsx\n * const config = useAlchemyConfig();\n * console.log('Policy ID:', config.policyId);\n * ```\n */\nexport function useAlchemyConfig(): AlchemyProviderConfig {\n  const context = useContext(AlchemyContext);\n  if (!context) {\n    throw new Error(\"useAlchemyConfig must be used within <AlchemyProvider />\");\n  }\n  return context;\n}\n\n/**\n * Hook to access the client cache (internal use only)\n *\n * @internal\n * @returns {ClientCache} The client cache object\n */\nexport function useClientCache(): ClientCache {\n  const context = useContext(ClientCacheContext);\n  if (!context) {\n    throw new Error(\n      \"useClientCache must be used within <AlchemyProvider />. Make sure AlchemyProvider is nested inside PrivyProvider.\",\n    );\n  }\n  return context;\n}\n"]}

package/dist/esm/hooks/internal/useEmbeddedWallet.d.ts

@@ -0,0 +1,10 @@
+import { 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 declare function useEmbeddedWallet(): () => PrivyWallet;

package/dist/esm/hooks/internal/useEmbeddedWallet.js

@@ -0,0 +1,22 @@
+import { useCallback } from "react";
+import { useWallets, } 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(() => {
+        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;
+}
+//# sourceMappingURL=useEmbeddedWallet.js.map

package/dist/esm/hooks/internal/useEmbeddedWallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEmbeddedWallet.js","sourceRoot":"","sources":["../../../../src/hooks/internal/useEmbeddedWallet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EACL,UAAU,GAEX,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;IAEjC,MAAM,iBAAiB,GAAG,WAAW,CAAC,GAAgB,EAAE;QACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,KAAK,OAAO,CAAC,CAAC;QACrE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,2EAA2E,CAC5E,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,OAAO,iBAAiB,CAAC;AAC3B,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport {\n  useWallets,\n  type ConnectedWallet as PrivyWallet,\n} from \"@privy-io/react-auth\";\n\n/**\n * Internal hook to get the Privy embedded wallet\n * Shared across multiple hooks to avoid duplication\n *\n * @internal\n * @returns {() => PrivyWallet} Function that returns the embedded wallet\n * @throws {Error} If embedded wallet is not found\n */\nexport function useEmbeddedWallet() {\n  const { wallets } = useWallets();\n\n  const getEmbeddedWallet = useCallback((): PrivyWallet => {\n    const embedded = wallets.find((w) => w.walletClientType === \"privy\");\n    if (!embedded) {\n      throw new Error(\n        \"Privy embedded wallet not found. Please ensure the user is authenticated.\",\n      );\n    }\n    return embedded;\n  }, [wallets]);\n\n  return getEmbeddedWallet;\n}\n"]}

package/dist/esm/hooks/useAlchemyClient.d.ts

@@ -0,0 +1,17 @@
+import { type SmartWalletClient } from "@account-kit/wallet-client";
+/**
+ * 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 declare function useAlchemyClient(): {
+    getClient: () => Promise<SmartWalletClient>;
+};