@account-kit/privy-integration 4.71.1 → 4.73.0

package/README.md

@@ -7,9 +7,10 @@ Add gas sponsorship and smart wallet features to your Privy app in under 5 minut
 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
+- **⛽ Gas Sponsorship** - Pay gas fees for your users via Alchemy Gas Manager (EVM & Solana)
 - **💱 Token Swaps** - Execute swaps through Alchemy's swap infrastructure
 - **🚀 Batched Transactions** - Send multiple operations in a single transaction using `sendTransaction([...])`
+- **☀️ Solana Support** - Send sponsored Solana transactions with Privy's embedded Solana wallets
 
 All while keeping Privy as your authentication provider. No need to change your auth flow or migrate user accounts.
 
@@ -31,6 +32,26 @@ yarn add @account-kit/privy-integration
 pnpm add @account-kit/privy-integration
 ```
 
+### Optional: Solana Support
+
+To use Solana features (like `useAlchemySolanaTransaction`), you'll need to install the Solana Web3.js library:
+
+```bash
+npm install @solana/web3.js
+# or
+yarn add @solana/web3.js
+# or
+pnpm add @solana/web3.js
+```
+
+Then import from the `/solana` export:
+
+```tsx
+import { useAlchemySolanaTransaction } from "@account-kit/privy-integration/solana";
+```
+
+> **Note:** The Solana functionality is completely optional. If you only need EVM features, you don't need to install `@solana/web3.js`.
+
 ## Quick Start
 
 ### 1. Wrap Your App with Both Providers
@@ -166,17 +187,81 @@ function SwapButton() {
 }
 ```
 
+### 4. Send Solana Transactions
+
+```tsx
+import { useAlchemySolanaTransaction } from "@account-kit/privy-integration/solana";
+
+function SolanaSendButton() {
+  const { sendTransactionAsync, isPending, error, data } =
+    useAlchemySolanaTransaction({
+      rpcUrl: "https://solana-mainnet.g.alchemy.com/v2/your-api-key",
+      policyId: "your-solana-policy-id", // optional, for gas sponsorship
+    });
+
+  const handleTransfer = async () => {
+    try {
+      // Simple SOL transfer
+      const result = await sendTransactionAsync({
+        transfer: {
+          amount: 1_000_000_000, // 1 SOL in lamports
+          toAddress: "recipient-base58-address",
+        },
+      });
+
+      console.log("Transaction hash:", result.hash);
+    } catch (err) {
+      console.error("Transaction failed:", err);
+    }
+  };
+
+  const handleCustomInstructions = async () => {
+    try {
+      // Custom instructions
+      import { SystemProgram, PublicKey } from "@solana/web3.js";
+
+      const instruction = SystemProgram.transfer({
+        fromPubkey: new PublicKey(walletAddress),
+        toPubkey: new PublicKey(recipientAddress),
+        lamports: 1_000_000,
+      });
+
+      const result = await sendTransactionAsync({
+        instructions: [instruction],
+      });
+
+      console.log("Transaction hash:", result.hash);
+    } catch (err) {
+      console.error("Transaction failed:", err);
+    }
+  };
+
+  return (
+    <>
+      <button onClick={handleTransfer} disabled={isPending}>
+        {isPending ? "Sending..." : "Send SOL"}
+      </button>
+      <button onClick={handleCustomInstructions} disabled={isPending}>
+        {isPending ? "Sending..." : "Custom Instructions"}
+      </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`)                               |
+| 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 for EVM chains (can be used alone or with `jwt`)                                          |
+| `solanaRpcUrl`       | `string`             | No            | Custom RPC URL for Solana (separate from EVM `rpcUrl`)                                                   |
+| `policyId`           | `string \| string[]` | No            | Gas Manager policy ID(s) for EVM sponsorship. If array is provided, backend uses first applicable policy |
+| `solanaPolicyId`     | `string \| string[]` | No            | Gas Manager policy ID(s) for Solana sponsorship                                                          |
+| `disableSponsorship` | `boolean`            | No            | Set to `true` to disable gas sponsorship by default (default: `false`)                                   |
 
 \* **Required configuration (pick one):**
 
@@ -206,7 +291,7 @@ await sendTransaction(
 
 #### `useAlchemySendTransaction()`
 
-Send single or batch transactions with optional gas sponsorship.
+Send single or batch EVM transactions with optional gas sponsorship.
 
 **Returns:**
 
@@ -242,6 +327,29 @@ Sign and submit prepared swap calls.
 - `data` - Swap result with `txnHash`
 - `reset()` - Reset hook state
 
+#### `useAlchemySolanaTransaction(options?)`
+
+Send Solana transactions with optional gas sponsorship via Alchemy.
+
+**Parameters:**
+
+- `options.rpcUrl` - Solana RPC URL (overrides provider config)
+- `options.policyId` - Gas sponsorship policy ID (overrides provider config)
+- `options.walletAddress` - Specific wallet address to use (defaults to first wallet)
+- `options.confirmationOptions` - Transaction confirmation options
+
+**Returns:**
+
+- `sendTransactionAsync(params)` - Send transaction and await result (throws on error)
+  - `params.transfer` - Simple SOL transfer with `amount` (lamports) and `toAddress`
+  - `params.instructions` - Custom Solana transaction instructions array
+- `sendTransaction(params)` - Send transaction (fire-and-forget, errors caught internally)
+- `connection` - Active Solana connection instance
+- `isPending` - Whether a transaction is currently being sent
+- `error` - Error object if failed
+- `data` - Transaction result with `hash` (base58 signature)
+- `reset()` - Reset hook state
+
 #### `useAlchemyClient()`
 
 Get the underlying smart wallet client (advanced use cases).

package/dist/esm/Provider.d.ts

@@ -19,8 +19,10 @@ interface ClientCache {
  * @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 {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)
  * @returns {JSX.Element} Provider component
  *

package/dist/esm/Provider.js

@@ -12,8 +12,10 @@ const ClientCacheContext = createContext(null);
  * @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 {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)
  * @returns {JSX.Element} Provider component
  *

package/dist/esm/Provider.js.map

@@ -1 +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"]}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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 for EVM chains\n * @param {string} [props.solanaRpcUrl] - Custom RPC URL for Solana\n * @param {string | string[]} [props.policyId] - Gas Manager policy ID(s) for EVM chains\n * @param {string | string[]} [props.solanaPolicyId] - Gas Manager policy ID(s) for Solana\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/useAlchemySolanaTransaction.d.ts

@@ -0,0 +1,163 @@
+import { Connection, Transaction, TransactionInstruction, VersionedTransaction } from "@solana/web3.js";
+/**
+ * Type helper for values that can be synchronous or asynchronous
+ *
+ * @template T - The value type
+ */
+export type PromiseOrValue<T> = T | Promise<T>;
+/**
+ * Callback to modify a transaction before it's signed
+ * Useful for adding additional signatures or metadata
+ *
+ * @param transaction - The unsigned transaction to modify
+ * @returns The modified transaction
+ */
+export type PreSend = (this: void, transaction: VersionedTransaction | Transaction) => PromiseOrValue<VersionedTransaction | Transaction>;
+/**
+ * Callback to transform instructions into a custom transaction
+ * Useful for advanced transaction construction (e.g., multi-sig, custom versioning)
+ *
+ * @param instructions - Array of Solana transaction instructions
+ * @returns Constructed transaction (legacy or versioned)
+ */
+export type TransformInstruction = (this: void, instructions: TransactionInstruction[]) => PromiseOrValue<Transaction | VersionedTransaction>;
+/**
+ * Optional transaction lifecycle hooks for advanced use cases
+ */
+export type SolanaTransactionParamOptions = {
+    /** Hook called before signing the transaction */
+    preSend?: PreSend;
+    /** Custom transaction builder from instructions */
+    transformInstruction?: TransformInstruction;
+};
+/**
+ * Parameters for sending a Solana transaction
+ * Supports either a simple transfer or custom instructions
+ */
+export type SolanaTransactionParams = {
+    /** Simple SOL transfer parameters */
+    transfer: {
+        /** Amount in lamports (accepts number or bigint) */
+        amount: number | bigint;
+        /** Recipient's base58-encoded address */
+        toAddress: string;
+    };
+    /** Optional transaction lifecycle hooks */
+    transactionComponents?: SolanaTransactionParamOptions;
+    /** Options for confirming the transaction on-chain */
+    confirmationOptions?: Parameters<Connection["confirmTransaction"]>[1];
+} | {
+    /** Custom Solana transaction instructions */
+    instructions: TransactionInstruction[];
+    /** Optional transaction lifecycle hooks */
+    transactionComponents?: SolanaTransactionParamOptions;
+    /** Options for confirming the transaction on-chain */
+    confirmationOptions?: Parameters<Connection["confirmTransaction"]>[1];
+};
+/**
+ * Result of a successful Solana transaction
+ */
+export interface SolanaTransactionResult {
+    /** Base58-encoded transaction signature (hash) */
+    hash: string;
+}
+/**
+ * Configuration options for useAlchemySolanaTransaction hook
+ */
+export interface UseAlchemySolanaTransactionOptions {
+    /** Solana RPC URL (overrides provider config) */
+    rpcUrl?: string;
+    /** Gas sponsorship policy ID (overrides provider config) */
+    policyId?: string | void;
+    /** Transaction confirmation options */
+    confirmationOptions?: Parameters<Connection["confirmTransaction"]>[1];
+    /** Specific wallet address to use (defaults to first available wallet) */
+    walletAddress?: string;
+}
+/**
+ * Return type of useAlchemySolanaTransaction hook
+ */
+export interface UseAlchemySolanaTransactionResult {
+    /** Active Solana connection instance */
+    readonly connection: Connection | null;
+    /** Transaction result if successful */
+    readonly data: void | SolanaTransactionResult;
+    /** Whether a transaction is currently being sent */
+    readonly isPending: boolean;
+    /** Error if transaction failed */
+    readonly error: Error | null;
+    /** Reset hook state (clears error, data, isPending) */
+    reset(): void;
+    /** Send transaction (fire-and-forget, errors caught internally) */
+    sendTransaction(params: SolanaTransactionParams): void;
+    /** Send transaction and await result (throws on error) */
+    sendTransactionAsync(params: SolanaTransactionParams): Promise<SolanaTransactionResult>;
+}
+/**
+ * Hook to send Solana transactions with optional gas sponsorship via Alchemy
+ * Works with Privy's Solana wallet integration for signing transactions
+ * Supports both simple transfers and custom instruction sets
+ *
+ * @param {UseAlchemySolanaTransactionOptions} [opts] - Configuration options
+ * @param {string} [opts.rpcUrl] - Solana RPC URL (overrides provider config)
+ * @param {string} [opts.policyId] - Gas sponsorship policy ID (overrides provider config)
+ * @param {string} [opts.walletAddress] - Specific wallet address to use (defaults to first wallet)
+ * @param {Parameters<Connection["confirmTransaction"]>[1]} [opts.confirmationOptions] - Transaction confirmation options
+ * @returns {UseAlchemySolanaTransactionResult} Hook result with transaction functions and state
+ *
+ * @example Simple SOL transfer
+ * ```tsx
+ * const { sendTransactionAsync, isPending, error, data } = useAlchemySolanaTransaction({
+ *   rpcUrl: 'https://solana-mainnet.g.alchemy.com/v2/your-api-key',
+ *   policyId: 'your-policy-id', // Optional: for gas sponsorship
+ * });
+ *
+ * const handleTransfer = async () => {
+ *   try {
+ *     const result = await sendTransactionAsync({
+ *       transfer: {
+ *         amount: 1_000_000_000, // 1 SOL in lamports
+ *         toAddress: 'recipient-address',
+ *       },
+ *     });
+ *     console.log('Transaction hash:', result.hash);
+ *   } catch (err) {
+ *     console.error('Transaction failed:', err);
+ *   }
+ * };
+ * ```
+ *
+ * @example Custom instructions
+ * ```tsx
+ * import { SystemProgram, PublicKey } from '@solana/web3.js';
+ *
+ * const { sendTransactionAsync } = useAlchemySolanaTransaction();
+ *
+ * // Build your custom instructions
+ * const transferIx = SystemProgram.transfer({
+ *   fromPubkey: new PublicKey(walletAddress),
+ *   toPubkey: new PublicKey(recipientAddress),
+ *   lamports: 1_000_000,
+ * });
+ *
+ * // Pass instructions array to the hook
+ * const result = await sendTransactionAsync({
+ *   instructions: [transferIx],
+ * });
+ * ```
+ *
+ * @example With provider configuration
+ * ```tsx
+ * // In your provider setup
+ * <AlchemyProvider
+ *   solanaRpcUrl="https://solana-mainnet.g.alchemy.com/v2/..."
+ *   solanaPolicyId="your-solana-policy-id"
+ * >
+ *   <YourApp />
+ * </AlchemyProvider>
+ *
+ * // In your component - uses provider config automatically
+ * const { sendTransactionAsync } = useAlchemySolanaTransaction();
+ * ```
+ */
+export declare function useAlchemySolanaTransaction(opts?: UseAlchemySolanaTransactionOptions): UseAlchemySolanaTransactionResult;

package/dist/esm/hooks/useAlchemySolanaTransaction.js

@@ -0,0 +1,233 @@
+import { useCallback, useMemo, useState } from "react";
+import { Connection, PublicKey, SystemProgram, Transaction, TransactionInstruction, VersionedTransaction, } from "@solana/web3.js";
+import { useAlchemyConfig } from "../Provider.js";
+import { createSolanaSponsoredTransaction } from "../util/createSolanaSponsoredTransaction.js";
+import { useSignTransaction, useWallets } from "@privy-io/react-auth/solana";
+import { createSolanaTransaction } from "../util/createSolanaTransaction.js";
+/**
+ * Hook to send Solana transactions with optional gas sponsorship via Alchemy
+ * Works with Privy's Solana wallet integration for signing transactions
+ * Supports both simple transfers and custom instruction sets
+ *
+ * @param {UseAlchemySolanaTransactionOptions} [opts] - Configuration options
+ * @param {string} [opts.rpcUrl] - Solana RPC URL (overrides provider config)
+ * @param {string} [opts.policyId] - Gas sponsorship policy ID (overrides provider config)
+ * @param {string} [opts.walletAddress] - Specific wallet address to use (defaults to first wallet)
+ * @param {Parameters<Connection["confirmTransaction"]>[1]} [opts.confirmationOptions] - Transaction confirmation options
+ * @returns {UseAlchemySolanaTransactionResult} Hook result with transaction functions and state
+ *
+ * @example Simple SOL transfer
+ * ```tsx
+ * const { sendTransactionAsync, isPending, error, data } = useAlchemySolanaTransaction({
+ *   rpcUrl: 'https://solana-mainnet.g.alchemy.com/v2/your-api-key',
+ *   policyId: 'your-policy-id', // Optional: for gas sponsorship
+ * });
+ *
+ * const handleTransfer = async () => {
+ *   try {
+ *     const result = await sendTransactionAsync({
+ *       transfer: {
+ *         amount: 1_000_000_000, // 1 SOL in lamports
+ *         toAddress: 'recipient-address',
+ *       },
+ *     });
+ *     console.log('Transaction hash:', result.hash);
+ *   } catch (err) {
+ *     console.error('Transaction failed:', err);
+ *   }
+ * };
+ * ```
+ *
+ * @example Custom instructions
+ * ```tsx
+ * import { SystemProgram, PublicKey } from '@solana/web3.js';
+ *
+ * const { sendTransactionAsync } = useAlchemySolanaTransaction();
+ *
+ * // Build your custom instructions
+ * const transferIx = SystemProgram.transfer({
+ *   fromPubkey: new PublicKey(walletAddress),
+ *   toPubkey: new PublicKey(recipientAddress),
+ *   lamports: 1_000_000,
+ * });
+ *
+ * // Pass instructions array to the hook
+ * const result = await sendTransactionAsync({
+ *   instructions: [transferIx],
+ * });
+ * ```
+ *
+ * @example With provider configuration
+ * ```tsx
+ * // In your provider setup
+ * <AlchemyProvider
+ *   solanaRpcUrl="https://solana-mainnet.g.alchemy.com/v2/..."
+ *   solanaPolicyId="your-solana-policy-id"
+ * >
+ *   <YourApp />
+ * </AlchemyProvider>
+ *
+ * // In your component - uses provider config automatically
+ * const { sendTransactionAsync } = useAlchemySolanaTransaction();
+ * ```
+ */
+export function useAlchemySolanaTransaction(opts = {}) {
+    const config = useAlchemyConfig();
+    const { wallets } = useWallets();
+    const { signTransaction } = useSignTransaction();
+    // Resolve the Privy Solana wallet to use
+    const embeddedWallet = useMemo(() => {
+        if (opts.walletAddress) {
+            const w = wallets.find((w) => w.address === opts.walletAddress);
+            if (!w)
+                throw new Error("Specified Solana wallet not found");
+            return w;
+        }
+        return wallets[0];
+    }, [wallets, opts.walletAddress]);
+    // Build Solana connection from rpcUrl (hook override or provider default)
+    const connection = useMemo(() => {
+        const url = opts.rpcUrl || config.solanaRpcUrl;
+        return url ? new Connection(url) : null;
+    }, [opts.rpcUrl, config.solanaRpcUrl]);
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState(null);
+    const [data, setData] = useState(undefined);
+    const resolvedPolicyId = useMemo(() => {
+        if (opts.policyId != null)
+            return opts.policyId || undefined;
+        // Use solanaPolicyId from config, fallback to policyId for backwards compat
+        const configPolicy = config.solanaPolicyId || config.policyId;
+        return Array.isArray(configPolicy) ? configPolicy[0] : configPolicy;
+    }, [opts.policyId, config.solanaPolicyId, config.policyId]);
+    const mapTransformInstructions = useMemo(() => {
+        const addSponsorship = async (instructions) => {
+            const policyId = resolvedPolicyId;
+            if (!policyId)
+                throw new Error("Gas sponsorship requires a policyId (see provider or hook options).");
+            const localConnection = connection || missing("connection");
+            const fromAddress = embeddedWallet?.address;
+            if (!fromAddress)
+                throw new Error("No embedded Solana wallet connected");
+            return createSolanaSponsoredTransaction(instructions, localConnection, policyId, fromAddress);
+        };
+        const createTx = async (instructions) => {
+            const localConnection = connection || missing("connection");
+            const fromAddress = embeddedWallet?.address;
+            if (!fromAddress)
+                throw new Error("No embedded Solana wallet connected");
+            return createSolanaTransaction(instructions, localConnection, fromAddress);
+        };
+        const defaultTransform = !!resolvedPolicyId && !config.disableSponsorship
+            ? addSponsorship
+            : createTx;
+        return {
+            addSponsorship,
+            createTransaction: createTx,
+            default: defaultTransform,
+        };
+    }, [
+        resolvedPolicyId,
+        config.disableSponsorship,
+        connection,
+        embeddedWallet?.address,
+    ]);
+    const buildInstructions = useCallback((params, fromAddress) => {
+        if ("instructions" in params)
+            return params.instructions;
+        return [
+            SystemProgram.transfer({
+                fromPubkey: new PublicKey(fromAddress),
+                toPubkey: new PublicKey(params.transfer.toAddress),
+                lamports: typeof params.transfer.amount === "bigint"
+                    ? Number(params.transfer.amount) // web3.js currently expects number; callers can pass bigint safely
+                    : params.transfer.amount,
+            }),
+        ];
+    }, []);
+    function toUnsignedBytes(tx) {
+        // Serialize the full transaction structure (with placeholder signatures)
+        // Privy expects the complete transaction format, not just the message
+        if (tx instanceof VersionedTransaction) {
+            // VersionedTransaction.serialize() includes signature slots
+            return tx.serialize();
+        }
+        // Legacy Transaction: serialize without requiring all signatures
+        const buf = tx.serialize({
+            requireAllSignatures: false,
+            verifySignatures: false,
+        });
+        return buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    }
+    const sendTransactionAsync = useCallback(async (params) => {
+        setIsPending(true);
+        setError(null);
+        try {
+            const localConnection = connection || missing("connection");
+            if (!embeddedWallet?.address) {
+                throw new Error("No Solana wallet connected via Privy");
+            }
+            const fromAddress = embeddedWallet.address;
+            const { transactionComponents: { preSend, transformInstruction } = {}, confirmationOptions, } = params;
+            const instructions = buildInstructions(params, fromAddress);
+            let transaction;
+            if (transformInstruction) {
+                transaction = await transformInstruction(instructions);
+            }
+            else {
+                transaction = await mapTransformInstructions.default(instructions);
+            }
+            transaction = (await preSend?.(transaction)) || transaction;
+            // Sign the transaction using Privy's useSignTransaction hook
+            const unsignedBytes = toUnsignedBytes(transaction);
+            const { signedTransaction } = await signTransaction({
+                transaction: unsignedBytes,
+                wallet: embeddedWallet,
+            });
+            // Broadcast the signed transaction
+            const hash = await localConnection.sendRawTransaction(signedTransaction, { skipPreflight: false });
+            if (confirmationOptions || opts.confirmationOptions) {
+                await localConnection.confirmTransaction(hash, confirmationOptions || opts.confirmationOptions);
+            }
+            setData({ hash });
+            return { hash };
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setIsPending(false);
+        }
+    }, [
+        embeddedWallet,
+        connection,
+        buildInstructions,
+        mapTransformInstructions,
+        opts.confirmationOptions,
+        signTransaction,
+    ]);
+    const sendTransaction = useCallback((params) => {
+        // Prevent unhandled rejection warnings; error state is already set in sendTransactionAsync
+        sendTransactionAsync(params).catch(() => { });
+    }, [sendTransactionAsync]);
+    const reset = useCallback(() => {
+        setIsPending(false);
+        setError(null);
+        setData(undefined);
+    }, []);
+    return {
+        connection,
+        data,
+        isPending,
+        error,
+        reset,
+        sendTransaction,
+        sendTransactionAsync,
+    };
+}
+function missing(message) {
+    throw new Error(message);
+}
+//# sourceMappingURL=useAlchemySolanaTransaction.js.map