@zama-fhe/react-sdk 1.0.0 → 1.0.1

package/README.md

@@ -6,6 +6,10 @@ React hooks for confidential token operations, built on [React Query](https://ta
 
 ```bash
 pnpm add @zama-fhe/react-sdk @tanstack/react-query
+# or
+npm install @zama-fhe/react-sdk @tanstack/react-query
+# or
+yarn add @zama-fhe/react-sdk @tanstack/react-query
 ```
 
 `@zama-fhe/sdk` is included as a direct dependency — no need to install it separately.
@@ -28,11 +32,9 @@ pnpm add @zama-fhe/react-sdk @tanstack/react-query
 import { WagmiProvider, createConfig, http } from "wagmi";
 import { mainnet, sepolia } from "wagmi/chains";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { TokenSDKProvider, RelayerWeb, indexedDBStorage } from "@zama-fhe/react-sdk";
+import { ZamaProvider, RelayerWeb, indexedDBStorage } from "@zama-fhe/react-sdk";
 import { WagmiSigner } from "@zama-fhe/react-sdk/wagmi";
 
-const queryClient = new QueryClient();
-
 const wagmiConfig = createConfig({
   chains: [mainnet, sepolia],
   transports: {
@@ -41,36 +43,38 @@ const wagmiConfig = createConfig({
   },
 });
 
-const signer = new WagmiSigner(wagmiConfig);
+const signer = new WagmiSigner({ config: wagmiConfig });
 
 const relayer = new RelayerWeb({
   getChainId: () => signer.getChainId(),
   transports: {
-    [1]: {
-      relayerUrl: "https://relayer.zama.ai",
+    [mainnet.id]: {
+      relayerUrl: "https://your-app.com/api/relayer/1",
       network: "https://mainnet.infura.io/v3/YOUR_KEY",
     },
-    [11155111]: {
-      relayerUrl: "https://relayer.zama.ai",
+    [sepolia.id]: {
+      relayerUrl: "https://your-app.com/api/relayer/11155111",
       network: "https://sepolia.infura.io/v3/YOUR_KEY",
     },
   },
 });
 
+const queryClient = new QueryClient();
+
 function App() {
   return (
     <WagmiProvider config={wagmiConfig}>
       <QueryClientProvider client={queryClient}>
-        <TokenSDKProvider relayer={relayer} signer={signer} storage={indexedDBStorage}>
+        <ZamaProvider relayer={relayer} signer={signer} storage={indexedDBStorage}>
           <TokenBalance />
-        </TokenSDKProvider>
+        </ZamaProvider>
       </QueryClientProvider>
     </WagmiProvider>
   );
 }
 
 function TokenBalance() {
-  const { data: balance, isLoading } = useConfidentialBalance("0xTokenAddress");
+  const { data: balance, isLoading } = useConfidentialBalance({ tokenAddress: "0xTokenAddress" });
 
   if (isLoading) return <p>Decrypting balance...</p>;
   return <p>Balance: {balance?.toString()}</p>;
@@ -81,42 +85,43 @@ function TokenBalance() {
 
 ```tsx
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { mainnet, sepolia } from "wagmi/chains"; // or define your own chain IDs
 import {
-  TokenSDKProvider,
+  ZamaProvider,
   RelayerWeb,
   useConfidentialBalance,
   useConfidentialTransfer,
-  MemoryStorage,
+  memoryStorage,
 } from "@zama-fhe/react-sdk";
 
-const queryClient = new QueryClient();
-
 const relayer = new RelayerWeb({
   getChainId: () => yourCustomSigner.getChainId(),
   transports: {
-    [1]: {
-      relayerUrl: "https://relayer.zama.ai",
+    [mainnet.id]: {
+      relayerUrl: "https://your-app.com/api/relayer/1",
       network: "https://mainnet.infura.io/v3/YOUR_KEY",
     },
-    [11155111]: {
-      relayerUrl: "https://relayer.zama.ai",
+    [sepolia.id]: {
+      relayerUrl: "https://your-app.com/api/relayer/11155111",
       network: "https://sepolia.infura.io/v3/YOUR_KEY",
     },
   },
 });
 
+const queryClient = new QueryClient();
+
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
-      <TokenSDKProvider relayer={relayer} signer={yourCustomSigner} storage={new MemoryStorage()}>
+      <ZamaProvider relayer={relayer} signer={yourCustomSigner} storage={memoryStorage}>
         <TransferForm />
-      </TokenSDKProvider>
+      </ZamaProvider>
     </QueryClientProvider>
   );
 }
 
 function TransferForm() {
-  const { data: balance } = useConfidentialBalance("0xTokenAddress");
+  const { data: balance } = useConfidentialBalance({ tokenAddress: "0xTokenAddress" });
   const { mutateAsync: transfer, isPending } = useConfidentialTransfer({
     tokenAddress: "0xTokenAddress",
   });
@@ -139,32 +144,60 @@ function TransferForm() {
 
 ## Provider Setup
 
-All setups use `TokenSDKProvider`. Create a signer with the adapter for your library, then pass it directly.
+All setups use `ZamaProvider`. Create a signer with the adapter for your library, then pass it directly.
 
 ```tsx
-import { TokenSDKProvider } from "@zama-fhe/react-sdk";
+import { ZamaProvider } from "@zama-fhe/react-sdk";
 
-<TokenSDKProvider
+<ZamaProvider
   relayer={relayer} // RelayerSDK (RelayerWeb or RelayerNode instance)
   signer={signer} // GenericSigner (WagmiSigner, ViemSigner, EthersSigner, or custom)
-  storage={storage} // GenericStringStorage
+  storage={storage} // GenericStorage
+  sessionStorage={sessionStorage} // Optional. Session storage for wallet signatures. Default: in-memory (lost on reload).
+  keypairTTL={86400} // Optional. Seconds the ML-KEM keypair remains valid. Default: 86400 (1 day).
+  sessionTTL={2592000} // Optional. Seconds the session signature remains valid. Default: 2592000 (30 days). 0 = re-sign every operation.
+  onEvent={(event) => console.debug(event)} // Optional. Structured event listener for debugging.
 >
   {children}
-</TokenSDKProvider>;
+</ZamaProvider>;
+```
+
+## Which Hooks Should I Use?
+
+The React SDK exports hooks from two layers. **Pick one layer per operation — never mix them.**
+
+**Use the main import** (`@zama-fhe/react-sdk`) when you have a `ZamaProvider` in your component tree. These hooks handle FHE encryption, cache invalidation, and error wrapping automatically:
+
+```tsx
+import { useShield, useConfidentialTransfer } from "@zama-fhe/react-sdk";
+
+const { mutateAsync: shield } = useShield({ tokenAddress });
+await shield({ amount: 1000n }); // encryption + approval handled for you
+```
+
+```tsx
+import { ViemSigner } from "@zama-fhe/sdk/viem";
+import { EthersSigner } from "@zama-fhe/sdk/ethers";
+```
+
+The `WagmiSigner` is the only adapter in the react-sdk since wagmi is React-specific:
+
+```tsx
+import { WagmiSigner } from "@zama-fhe/react-sdk/wagmi";
 ```
 
 ## Hooks Reference
 
-All hooks require a `TokenSDKProvider` (or one of its variants) in the component tree.
+All hooks require a `ZamaProvider` (or one of its variants) in the component tree.
 
 ### SDK Access
 
-#### `useTokenSDK`
+#### `useZamaSDK`
 
-Returns the `TokenSDK` instance from context. Use this when you need direct access to the SDK (e.g. for low-level relayer operations).
+Returns the `ZamaSDK` instance from context. Use this when you need direct access to the SDK (e.g. for low-level relayer operations).
 
 ```ts
-function useTokenSDK(): TokenSDK;
+function useZamaSDK(): ZamaSDK;
 ```
 
 #### `useToken`
@@ -191,28 +224,27 @@ Single-token balance with automatic decryption. Uses two-phase polling: polls th
 
 ```ts
 function useConfidentialBalance(
-  tokenAddress: Address,
-  owner?: Address, // defaults to connected wallet
+  config: UseConfidentialBalanceConfig,
   options?: UseConfidentialBalanceOptions,
 ): UseQueryResult<bigint, Error>;
-```
 
-Options extend `UseQueryOptions` and add:
+interface UseConfidentialBalanceConfig {
+  tokenAddress: Address;
+  handleRefetchInterval?: number; // default: 10000ms
+}
+```
 
-| Option                  | Type     | Default | Description                                     |
-| ----------------------- | -------- | ------- | ----------------------------------------------- |
-| `handleRefetchInterval` | `number` | `10000` | Polling interval (ms) for the encrypted handle. |
+Options extend `UseQueryOptions`.
 
 ```tsx
 const {
   data: balance,
   isLoading,
   error,
-} = useConfidentialBalance(
-  "0xTokenAddress",
-  undefined, // use connected wallet
-  { handleRefetchInterval: 5_000 },
-);
+} = useConfidentialBalance({
+  tokenAddress: "0xTokenAddress",
+  handleRefetchInterval: 5_000,
+});
 ```
 
 #### `useConfidentialBalances`
@@ -221,14 +253,21 @@ Multi-token batch balance. Same two-phase polling pattern.
 
 ```ts
 function useConfidentialBalances(
-  tokenAddresses: Address[],
-  owner?: Address,
+  config: UseConfidentialBalancesConfig,
   options?: UseConfidentialBalancesOptions,
 ): UseQueryResult<Map<Address, bigint>, Error>;
+
+interface UseConfidentialBalancesConfig {
+  tokenAddresses: Address[];
+  handleRefetchInterval?: number;
+  maxConcurrency?: number;
+}
 ```
 
 ```tsx
-const { data: balances } = useConfidentialBalances(["0xTokenA", "0xTokenB", "0xTokenC"]);
+const { data: balances } = useConfidentialBalances({
+  tokenAddresses: ["0xTokenA", "0xTokenB", "0xTokenC"],
+});
 
 // balances is a Map<Address, bigint>
 const tokenABalance = balances?.get("0xTokenA");
@@ -236,24 +275,55 @@ const tokenABalance = balances?.get("0xTokenA");
 
 ### Authorization
 
-#### `useAuthorizeAll`
+#### `useTokenAllow`
 
 Pre-authorize FHE decrypt credentials for a list of token addresses with a single wallet signature. Call this early (e.g. after loading the token list) so that subsequent individual decrypt operations reuse cached credentials without prompting the wallet again.
 
 ```ts
-function useAuthorizeAll(): UseMutationResult<void, Error, Address[]>;
+function useTokenAllow(): UseMutationResult<void, Error, Address[]>;
 ```
 
 ```tsx
-const { mutateAsync: authorizeAll, isPending } = useAuthorizeAll();
+const { mutateAsync: tokenAllow, isPending } = useTokenAllow();
 
 // Pre-authorize all known tokens up front
-await authorizeAll(allTokenAddresses);
+await tokenAllow(allTokenAddresses);
 
 // Individual balance decrypts now reuse cached credentials
 const { data: balance } = useConfidentialBalance("0xTokenA");
 ```
 
+#### `useIsTokenAllowed`
+
+Check whether a session signature is cached for a given token. Returns `true` if decrypt operations can proceed without a wallet prompt. Use this to conditionally enable UI elements (e.g. a "Reveal Balances" button).
+
+```ts
+function useIsTokenAllowed(tokenAddress: Address): UseQueryResult<boolean, Error>;
+```
+
+```tsx
+const { data: allowed } = useIsTokenAllowed("0xTokenAddress");
+
+<button disabled={!allowed}>Reveal Balance</button>;
+```
+
+Automatically invalidated when `useTokenAllow` or `useTokenRevoke` succeed.
+
+#### `useTokenRevoke`
+
+Revoke the session signature for the connected wallet. Stored credentials remain intact, but the next decrypt operation will require a fresh wallet signature.
+
+```ts
+function useTokenRevoke(): UseMutationResult<void, Error, Address[]>;
+```
+
+```tsx
+const { mutate: tokenRevoke } = useTokenRevoke();
+
+// Revoke session — addresses are included in the credentials:revoked event
+tokenRevoke(["0xTokenA", "0xTokenB"]);
+```
+
 ### Transfer Hooks
 
 #### `useConfidentialTransfer`
@@ -262,7 +332,7 @@ Encrypted transfer. Encrypts the amount and calls the contract. Automatically in
 
 ```ts
 function useConfidentialTransfer(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, ConfidentialTransferParams>,
 ): UseMutationResult<Address, Error, ConfidentialTransferParams>;
 
@@ -286,7 +356,7 @@ Operator transfer on behalf of another address.
 
 ```ts
 function useConfidentialTransferFrom(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, ConfidentialTransferFromParams>,
 ): UseMutationResult<Address, Error, ConfidentialTransferFromParams>;
 
@@ -299,13 +369,13 @@ interface ConfidentialTransferFromParams {
 
 ### Shield Hooks
 
-#### `useShield` (alias: `useWrap`)
+#### `useShield`
 
 Shield public ERC-20 tokens into confidential tokens. Handles ERC-20 approval automatically.
 
 ```ts
 function useShield(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, ShieldParams>,
 ): UseMutationResult<Address, Error, ShieldParams>;
 
@@ -325,13 +395,13 @@ await shield({ amount: 1000n });
 await shield({ amount: 1000n, approvalStrategy: "max" });
 ```
 
-#### `useShieldETH` (alias: `useWrapETH`)
+#### `useShieldETH`
 
 Shield native ETH into confidential tokens. Use when the underlying token is the zero address (native ETH).
 
 ```ts
 function useShieldETH(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, ShieldETHParams>,
 ): UseMutationResult<Address, Error, ShieldETHParams>;
 
@@ -347,16 +417,17 @@ These hooks orchestrate the full unshield flow in a single call: unwrap → wait
 
 #### `useUnshield`
 
-Unshield a specific amount. Handles the entire unwrap + finalize flow.
+Unshield a specific amount. Handles the entire unwrap + finalize flow. Supports optional progress callbacks to track each step.
 
 ```ts
 function useUnshield(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, UnshieldParams>,
 ): UseMutationResult<Address, Error, UnshieldParams>;
 
 interface UnshieldParams {
   amount: bigint;
+  callbacks?: UnshieldCallbacks;
 }
 ```
 
@@ -365,18 +436,29 @@ const { mutateAsync: unshield, isPending } = useUnshield({
   tokenAddress: "0xTokenAddress",
 });
 
-const finalizeTxHash = await unshield({ amount: 500n });
+const finalizeTxHash = await unshield({
+  amount: 500n,
+  callbacks: {
+    onUnwrapSubmitted: (txHash) => console.log("Unwrap tx:", txHash),
+    onFinalizing: () => console.log("Finalizing..."),
+    onFinalizeSubmitted: (txHash) => console.log("Finalize tx:", txHash),
+  },
+});
 ```
 
 #### `useUnshieldAll`
 
-Unshield the entire balance. Handles the entire unwrap + finalize flow.
+Unshield the entire balance. Handles the entire unwrap + finalize flow. Supports optional progress callbacks.
 
 ```ts
 function useUnshieldAll(
-  config: UseTokenConfig,
-  options?: UseMutationOptions<Address, Error, void>,
-): UseMutationResult<Address, Error, void>;
+  config: UseZamaConfig,
+  options?: UseMutationOptions<Address, Error, UnshieldAllParams | void>,
+): UseMutationResult<Address, Error, UnshieldAllParams | void>;
+
+interface UnshieldAllParams {
+  callbacks?: UnshieldCallbacks;
+}
 ```
 
 ```tsx
@@ -387,6 +469,58 @@ const { mutateAsync: unshieldAll } = useUnshieldAll({
 const finalizeTxHash = await unshieldAll();
 ```
 
+#### `useResumeUnshield`
+
+Resume an interrupted unshield from a saved unwrap tx hash. Useful when the user submitted the unwrap but the finalize step was interrupted (e.g. page reload, network error). Pair with the `savePendingUnshield`/`loadPendingUnshield`/`clearPendingUnshield` utilities for persistence.
+
+```ts
+function useResumeUnshield(
+  config: UseZamaConfig,
+  options?: UseMutationOptions<Address, Error, ResumeUnshieldParams>,
+): UseMutationResult<Address, Error, ResumeUnshieldParams>;
+
+interface ResumeUnshieldParams {
+  unwrapTxHash: Hex;
+  callbacks?: UnshieldCallbacks;
+}
+```
+
+```tsx
+import { loadPendingUnshield, clearPendingUnshield } from "@zama-fhe/react-sdk";
+
+const { mutateAsync: resumeUnshield } = useResumeUnshield({
+  tokenAddress: "0xTokenAddress",
+});
+
+// On mount, check for interrupted unshields
+const pending = await loadPendingUnshield(storage, wrapperAddress);
+if (pending) {
+  await resumeUnshield({ unwrapTxHash: pending });
+  await clearPendingUnshield(storage, wrapperAddress);
+}
+```
+
+#### Pending Unshield Persistence
+
+Save the unwrap tx hash before finalization so interrupted unshields can be resumed after page reloads:
+
+```ts
+import {
+  savePendingUnshield,
+  loadPendingUnshield,
+  clearPendingUnshield,
+} from "@zama-fhe/react-sdk";
+
+// Save before the finalize step
+await savePendingUnshield(storage, wrapperAddress, unwrapTxHash);
+
+// Load on next visit
+const pending = await loadPendingUnshield(storage, wrapperAddress);
+
+// Clear after successful finalization
+await clearPendingUnshield(storage, wrapperAddress);
+```
+
 ### Unwrap Hooks (Low-Level)
 
 These hooks expose the individual unwrap steps. Use them when you need fine-grained control over the flow.
@@ -397,7 +531,7 @@ Request unwrap for a specific amount (requires manual finalization via `useFinal
 
 ```ts
 function useUnwrap(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, UnwrapParams>,
 ): UseMutationResult<Address, Error, UnwrapParams>;
 
@@ -412,7 +546,7 @@ Request unwrap for the entire balance (requires manual finalization).
 
 ```ts
 function useUnwrapAll(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, void>,
 ): UseMutationResult<Address, Error, void>;
 ```
@@ -423,7 +557,7 @@ Complete an unwrap by providing the decryption proof.
 
 ```ts
 function useFinalizeUnwrap(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, FinalizeUnwrapParams>,
 ): UseMutationResult<Address, Error, FinalizeUnwrapParams>;
 
@@ -440,7 +574,7 @@ Set operator approval for the confidential token.
 
 ```ts
 function useConfidentialApprove(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   options?: UseMutationOptions<Address, Error, ConfidentialApproveParams>,
 ): UseMutationResult<Address, Error, ConfidentialApproveParams>;
 
@@ -456,7 +590,7 @@ Check if a spender is an approved operator. Enabled only when `spender` is defin
 
 ```ts
 function useConfidentialIsApproved(
-  config: UseTokenConfig,
+  config: UseZamaConfig,
   spender: Address | undefined,
   options?: Omit<UseQueryOptions<boolean, Error>, "queryKey" | "queryFn">,
 ): UseQueryResult<boolean, Error>;
@@ -464,7 +598,7 @@ function useConfidentialIsApproved(
 
 #### `useUnderlyingAllowance`
 
-Read the ERC-20 allowance of the underlying token for the wrapper.
+Read the underlying ERC-20 allowance granted to the wrapper.
 
 ```ts
 function useUnderlyingAllowance(
@@ -550,6 +684,61 @@ feed?.forEach((item) => {
 });
 ```
 
+### Fee Hooks
+
+#### `useShieldFee`
+
+Read the shield (wrap) fee for a given amount and address pair.
+
+```ts
+function useShieldFee(
+  config: UseFeeConfig,
+  options?: Omit<UseQueryOptions<bigint, Error>, "queryKey" | "queryFn">,
+): UseQueryResult<bigint, Error>;
+
+interface UseFeeConfig {
+  feeManagerAddress: Address;
+  amount: bigint;
+  from: Address;
+  to: Address;
+}
+```
+
+```tsx
+const { data: fee } = useShieldFee({
+  feeManagerAddress: "0xFeeManager",
+  amount: 1000n,
+  from: "0xSender",
+  to: "0xReceiver",
+});
+```
+
+#### `useUnshieldFee`
+
+Read the unshield (unwrap) fee for a given amount and address pair. Same signature as `useShieldFee`.
+
+#### `useBatchTransferFee`
+
+Read the batch transfer fee from the fee manager.
+
+```ts
+function useBatchTransferFee(
+  feeManagerAddress: Address,
+  options?: Omit<UseQueryOptions<bigint, Error>, "queryKey" | "queryFn">,
+): UseQueryResult<bigint, Error>;
+```
+
+#### `useFeeRecipient`
+
+Read the fee recipient address from the fee manager.
+
+```ts
+function useFeeRecipient(
+  feeManagerAddress: Address,
+  options?: Omit<UseQueryOptions<Address, Error>, "queryKey" | "queryFn">,
+): UseQueryResult<Address, Error>;
+```
+
 ### Low-Level FHE Hooks
 
 These hooks expose the raw `RelayerSDK` operations as React Query mutations.
@@ -605,42 +794,36 @@ const { data: value } = useUserDecryptedValue("0xHandleHash");
 
 ## Query Keys
 
-Exported query key factories for manual cache management (invalidation, prefetching, removal).
+Use `zamaQueryKeys` for manual cache management (invalidation, prefetching, removal).
 
 ```ts
-import {
-  confidentialBalanceQueryKeys,
-  confidentialBalancesQueryKeys,
-  confidentialHandleQueryKeys,
-  confidentialHandlesQueryKeys,
-  underlyingAllowanceQueryKeys,
-  activityFeedQueryKeys,
-  decryptionKeys,
-} from "@zama-fhe/react-sdk";
+import { zamaQueryKeys, decryptionKeys } from "@zama-fhe/react-sdk";
 ```
 
-| Factory                         | Keys                                                | Description                         |
-| ------------------------------- | --------------------------------------------------- | ----------------------------------- |
-| `confidentialBalanceQueryKeys`  | `.all`, `.token(address)`, `.owner(address, owner)` | Single-token decrypted balance.     |
-| `confidentialBalancesQueryKeys` | `.all`, `.tokens(addresses, owner)`                 | Multi-token batch balances.         |
-| `confidentialHandleQueryKeys`   | `.all`, `.token(address)`, `.owner(address, owner)` | Single-token encrypted handle.      |
-| `confidentialHandlesQueryKeys`  | `.all`, `.tokens(addresses, owner)`                 | Multi-token batch handles.          |
-| `underlyingAllowanceQueryKeys`  | `.all`, `.token(address, wrapper)`                  | Underlying ERC-20 allowance.        |
-| `activityFeedQueryKeys`         | `.all`, `.token(address)`                           | Activity feed items.                |
-| `decryptionKeys`                | `.value(handle)`                                    | Individual decrypted handle values. |
+| Factory                              | Keys                                                                                     | Description                         |
+| ------------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| `zamaQueryKeys.confidentialBalance`  | `.all`, `.token(address)`, `.owner(address, owner)`                                      | Single-token decrypted balance.     |
+| `zamaQueryKeys.confidentialBalances` | `.all`, `.tokens(addresses, owner)`                                                      | Multi-token batch balances.         |
+| `zamaQueryKeys.confidentialHandle`   | `.all`, `.token(address)`, `.owner(address, owner)`                                      | Single-token encrypted handle.      |
+| `zamaQueryKeys.confidentialHandles`  | `.all`, `.tokens(addresses, owner)`                                                      | Multi-token batch handles.          |
+| `zamaQueryKeys.isAllowed`            | `.all`                                                                                   | Session signature status.           |
+| `zamaQueryKeys.underlyingAllowance`  | `.all`, `.token(address)`, `.scope(address, owner, wrapper)`                             | Underlying ERC-20 allowance.        |
+| `zamaQueryKeys.activityFeed`         | `.all`, `.token(address)`, `.scope(address, userAddress, logsKey, decrypt)`              | Activity feed items.                |
+| `zamaQueryKeys.fees`                 | `.shieldFee(...)`, `.unshieldFee(...)`, `.batchTransferFee(addr)`, `.feeRecipient(addr)` | Fee manager queries.                |
+| `decryptionKeys`                     | `.value(handle)`                                                                         | Individual decrypted handle values. |
 
 ```tsx
 import { useQueryClient } from "@tanstack/react-query";
-import { confidentialBalanceQueryKeys } from "@zama-fhe/react-sdk";
+import { zamaQueryKeys } from "@zama-fhe/react-sdk";
 
 const queryClient = useQueryClient();
 
 // Invalidate all balances
-queryClient.invalidateQueries({ queryKey: confidentialBalanceQueryKeys.all });
+queryClient.invalidateQueries({ queryKey: zamaQueryKeys.confidentialBalance.all });
 
 // Invalidate a specific token's balance
 queryClient.invalidateQueries({
-  queryKey: confidentialBalanceQueryKeys.token("0xTokenAddress"),
+  queryKey: zamaQueryKeys.confidentialBalance.token("0xTokenAddress"),
 });
 ```
 
@@ -673,62 +856,148 @@ All write hooks return `{ mutate, mutateAsync, ...mutation }` from wagmi's `useW
 | `useUnwrapFromBalance()`         | `(token, from, to, encryptedBalance)`            | Unwrap using on-chain handle. |
 | `useFinalizeUnwrap()`            | `(wrapper, burntAmount, cleartext, proof)`       | Finalize unwrap.              |
 | `useSetOperator()`               | `(token, spender, timestamp?)`                   | Set operator approval.        |
-| `useWrap()`                      | `(wrapper, to, amount)`                          | Wrap ERC-20 tokens.           |
-| `useWrapETH()`                   | `(wrapper, to, amount, value)`                   | Wrap native ETH.              |
+| `useShield()`                    | `(wrapper, to, amount)`                          | Shield ERC-20 tokens.         |
+| `useShieldETH()`                 | `(wrapper, to, amount, value)`                   | Shield native ETH.            |
 
 ### Wagmi Signer Adapter
 
 ```ts
 import { WagmiSigner } from "@zama-fhe/react-sdk/wagmi";
 
-const signer = new WagmiSigner(wagmiConfig);
+const signer = new WagmiSigner({ config: wagmiConfig });
 ```
 
-## Viem & Ethers Adapter Hooks
+## Signer Adapters
 
-Both `@zama-fhe/react-sdk/viem` and `@zama-fhe/react-sdk/ethers` export the same set of read/write hooks, but typed for their respective libraries. They also include `Suspense` variants of all read hooks.
+Signer adapters are provided by the core SDK package:
 
-### Read hooks
+```ts
+import { ViemSigner } from "@zama-fhe/sdk/viem";
+import { EthersSigner } from "@zama-fhe/sdk/ethers";
+```
 
-`useConfidentialBalanceOf`, `useWrapperForToken`, `useUnderlyingToken`, `useWrapperExists`, `useSupportsInterface` — plus `*Suspense` variants.
+## Wallet Integration Guide
 
-- **viem:** First parameter is `PublicClient`.
-- **ethers:** First parameter is `Provider | Signer`.
+### SSR / Next.js
 
-### Write hooks
+All components using SDK hooks must be client components. Add `"use client"` at the top of files that import from `@zama-fhe/react-sdk`. FHE operations (encryption, decryption) run in a Web Worker and require browser APIs — they cannot execute on the server.
 
-`useConfidentialTransfer`, `useConfidentialBatchTransfer`, `useUnwrap`, `useUnwrapFromBalance`, `useFinalizeUnwrap`, `useSetOperator`, `useShield`, `useShieldETH`.
+```tsx
+"use client";
 
-- **viem:** Mutation params include `client: WalletClient`.
-- **ethers:** Mutation params include `signer: Signer`.
+import { useConfidentialBalance } from "@zama-fhe/react-sdk";
+```
 
-### Signer adapters
+Place `ZamaProvider` inside your client-only layout. Do **not** create the relayer or signer at the module level in a server component — wrap them in a client component or use lazy initialization.
 
-```ts
-// Re-exported for convenience
-import { ViemSigner } from "@zama-fhe/react-sdk/viem";
-import { EthersSigner } from "@zama-fhe/react-sdk/ethers";
+### FHE Credentials Lifecycle
+
+FHE decrypt credentials are generated once per wallet + token set and cached in the storage backend you provide (e.g. `IndexedDBStorage`). The wallet signature is kept **in memory only** — never persisted to disk. The lifecycle:
+
+1. **First decrypt** — SDK generates an FHE keypair, creates EIP-712 typed data, and prompts the wallet to sign. The encrypted credential is stored; the signature is cached in memory.
+2. **Same session** — Cached credentials and session signature are reused silently (no wallet prompt).
+3. **Page reload** — Encrypted credentials are loaded from storage; the wallet is prompted once to re-sign for the session.
+4. **Expiry** — Credentials expire based on `keypairTTL` (default: 86400s = 1 day). After expiry, the next decrypt regenerates and re-prompts.
+5. **Pre-authorization** — Call `useTokenAllow(tokenAddresses)` early to batch-authorize all tokens in one wallet prompt, avoiding repeated popups.
+6. **Check status** — Use `useIsTokenAllowed(tokenAddress)` to conditionally enable UI elements (e.g. disable "Reveal" until allowed).
+7. **Disconnect** — Call `useTokenRevoke(tokenAddresses)` or `await credentials.revoke()` to clear the session signature from memory.
+
+### Web Extension Support
+
+By default, wallet signatures are stored in memory and lost on page reload (or service worker restart). For MV3 web extensions, use the built-in `chromeSessionStorage` singleton so signatures survive service worker restarts and are shared across popup, background, and content script contexts:
+
+```tsx
+import { chromeSessionStorage } from "@zama-fhe/react-sdk";
+
+<ZamaProvider
+  relayer={relayer}
+  signer={signer}
+  storage={indexedDBStorage}
+  sessionStorage={chromeSessionStorage}
+>
+  <App />
+</ZamaProvider>;
+```
+
+This keeps the encrypted credentials in IndexedDB (persistent) while the unlock signature lives in `chrome.storage.session` (ephemeral, cleared when the browser closes).
+
+### Error-to-User-Message Mapping
+
+Map SDK errors to user-friendly messages in your UI:
+
+```tsx
+import {
+  SigningRejectedError,
+  EncryptionFailedError,
+  DecryptionFailedError,
+  TransactionRevertedError,
+  ApprovalFailedError,
+} from "@zama-fhe/react-sdk";
+
+function getUserMessage(error: Error): string {
+  if (error instanceof SigningRejectedError)
+    return "Transaction cancelled — please approve in your wallet.";
+  if (error instanceof EncryptionFailedError) return "Encryption failed — please try again.";
+  if (error instanceof DecryptionFailedError) return "Decryption failed — please try again.";
+  if (error instanceof ApprovalFailedError) return "Token approval failed — please try again.";
+  if (error instanceof TransactionRevertedError)
+    return "Transaction failed on-chain — check your balance.";
+  return "An unexpected error occurred.";
+}
+```
+
+Or use `matchZamaError` for a more concise pattern:
+
+```tsx
+import { matchZamaError } from "@zama-fhe/react-sdk";
+
+const message = matchZamaError(error, {
+  SIGNING_REJECTED: () => "Transaction cancelled — please approve in your wallet.",
+  ENCRYPTION_FAILED: () => "Encryption failed — please try again.",
+  DECRYPTION_FAILED: () => "Decryption failed — please try again.",
+  APPROVAL_FAILED: () => "Token approval failed — please try again.",
+  TRANSACTION_REVERTED: () => "Transaction failed on-chain — check your balance.",
+  _: () => "An unexpected error occurred.",
+});
+```
+
+### Balance Caching and Refresh
+
+Balance queries use two-phase polling:
+
+1. **Phase 1 (cheap)** — Polls the encrypted balance handle via a read-only RPC call at `handleRefetchInterval` (default: 10s).
+2. **Phase 2 (expensive)** — Only when the handle changes (i.e. balance updated on-chain), triggers an FHE decryption via the relayer.
+
+This means balances update within `handleRefetchInterval` ms of any on-chain change, without wasting decryption resources. Mutation hooks (`useConfidentialTransfer`, `useShield`, `useUnshield`, etc.) automatically invalidate the relevant caches on success, so the UI updates immediately after user actions.
+
+To force a refresh:
+
+```tsx
+const queryClient = useQueryClient();
+queryClient.invalidateQueries({ queryKey: zamaQueryKeys.confidentialBalance.all });
 ```
 
 ## Re-exports from Core SDK
 
 All public exports from `@zama-fhe/sdk` are re-exported from the main entry point. You never need to import from the core package directly.
 
-**Classes:** `RelayerWeb`, `TokenSDK`, `Token`, `ReadonlyToken`, `MemoryStorage`, `IndexedDBStorage`, `indexedDBStorage`, `CredentialsManager`.
+**Classes:** `RelayerWeb`, `ZamaSDK`, `Token`, `ReadonlyToken`, `MemoryStorage`, `memoryStorage`, `IndexedDBStorage`, `indexedDBStorage`, `CredentialsManager`.
 
 **Network configs:** `SepoliaConfig`, `MainnetConfig`, `HardhatConfig`.
 
-**Types:** `Address`, `TokenSDKConfig`, `TokenConfig`, `ReadonlyTokenConfig`, `NetworkType`, `RelayerSDK`, `RelayerSDKStatus`, `EncryptResult`, `EncryptParams`, `UserDecryptParams`, `PublicDecryptResult`, `FHEKeypair`, `EIP712TypedData`, `DelegatedUserDecryptParams`, `KmsDelegatedUserDecryptEIP712Type`, `ZKProofLike`, `InputProofBytesType`, `BatchTransferData`, `StoredCredentials`, `GenericSigner`, `GenericStringStorage`, `ContractCallConfig`, `TransactionReceipt`, `UnshieldCallbacks`.
+**Pending unshield:** `savePendingUnshield`, `loadPendingUnshield`, `clearPendingUnshield`.
+
+**Types:** `Address`, `ZamaSDKConfig`, `ZamaConfig`, `ReadonlyTokenConfig`, `NetworkType`, `RelayerSDK`, `RelayerSDKStatus`, `EncryptResult`, `EncryptParams`, `UserDecryptParams`, `PublicDecryptResult`, `FHEKeypair`, `EIP712TypedData`, `DelegatedUserDecryptParams`, `KmsDelegatedUserDecryptEIP712Type`, `ZKProofLike`, `InputProofBytesType`, `BatchTransferData`, `StoredCredentials`, `GenericSigner`, `GenericStorage`, `ContractCallConfig`, `TransactionReceipt`, `TransactionResult`, `UnshieldCallbacks`.
 
-**Errors:** `TokenError`, `TokenErrorCode`, `SigningRejectedError`, `SigningFailedError`, `EncryptionFailedError`, `DecryptionFailedError`, `ApprovalFailedError`, `TransactionRevertedError`, `InvalidCredentialsError`, `NoCiphertextError`, `RelayerRequestFailedError`.
+**Errors:** `ZamaError`, `ZamaErrorCode`, `SigningRejectedError`, `SigningFailedError`, `EncryptionFailedError`, `DecryptionFailedError`, `ApprovalFailedError`, `TransactionRevertedError`, `InvalidKeypairError`, `NoCiphertextError`, `RelayerRequestFailedError`, `matchZamaError`.
 
 **Constants:** `ZERO_HANDLE`, `ERC7984_INTERFACE_ID`, `ERC7984_WRAPPER_INTERFACE_ID`.
 
 **ABIs:** `ERC20_ABI`, `ERC20_METADATA_ABI`, `DEPLOYMENT_COORDINATOR_ABI`, `ERC165_ABI`, `ENCRYPTION_ABI`, `FEE_MANAGER_ABI`, `TRANSFER_BATCHER_ABI`, `WRAPPER_ABI`, `BATCH_SWAP_ABI`.
 
-**Events:** `RawLog`, `ConfidentialTransferEvent`, `WrappedEvent`, `UnwrapRequestedEvent`, `UnwrappedFinalizedEvent`, `UnwrappedStartedEvent`, `TokenEvent`, `Topics`, `TOKEN_TOPICS`.
+**Events:** `RawLog`, `ConfidentialTransferEvent`, `WrappedEvent`, `UnwrapRequestedEvent`, `UnwrappedFinalizedEvent`, `UnwrappedStartedEvent`, `OnChainEvent`, `Topics`, `TOKEN_TOPICS`.
 
-**Event decoders:** `decodeConfidentialTransfer`, `decodeWrapped`, `decodeUnwrapRequested`, `decodeUnwrappedFinalized`, `decodeUnwrappedStarted`, `decodeTokenEvent`, `decodeTokenEvents`, `findUnwrapRequested`, `findWrapped`.
+**Event decoders:** `decodeConfidentialTransfer`, `decodeWrapped`, `decodeUnwrapRequested`, `decodeUnwrappedFinalized`, `decodeUnwrappedStarted`, `decodeOnChainEvent`, `decodeOnChainEvents`, `findUnwrapRequested`, `findWrapped`.
 
 **Activity feed:** `ActivityDirection`, `ActivityType`, `ActivityAmount`, `ActivityLogMetadata`, `ActivityItem`, `parseActivityFeed`, `extractEncryptedHandles`, `applyDecryptedValues`, `sortByBlockNumber`.