@zama-fhe/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Zama
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,649 @@
+# @zama-fhe/sdk
+
+A TypeScript SDK for building privacy-preserving token applications using Fully Homomorphic Encryption (FHE). It abstracts the complexity of encrypted ERC-20 operations — shielding, unshielding, confidential transfers, and balance decryption — behind a clean, high-level API. Works with any Web3 library (viem, ethers, or custom signers).
+
+## Installation
+
+```bash
+pnpm add @zama-fhe/sdk
+```
+
+### Peer dependencies
+
+| Package                 | Version | Required?                                          |
+| ----------------------- | ------- | -------------------------------------------------- |
+| `viem`                  | >= 2    | Optional — for the `@zama-fhe/sdk/viem` adapter    |
+| `ethers`                | >= 6    | Optional — for the `@zama-fhe/sdk/ethers` adapter  |
+| `@zama-fhe/relayer-sdk` | >= 0.4  | Optional — only for `@zama-fhe/sdk/node` (Node.js) |
+
+## Quick Start
+
+### Browser
+
+```ts
+import { TokenSDK, RelayerWeb, IndexedDBStorage } from "@zama-fhe/sdk";
+import { ViemSigner } from "@zama-fhe/sdk/viem";
+
+// 1. Create signer and relayer
+const signer = new ViemSigner(walletClient, publicClient);
+
+const sdk = new TokenSDK({
+  relayer: new RelayerWeb({
+    getChainId: () => signer.getChainId(),
+    transports: {
+      [1]: {
+        relayerUrl: "https://relayer.zama.ai",
+        network: "https://mainnet.infura.io/v3/YOUR_KEY",
+      },
+      [11155111]: {
+        relayerUrl: "https://relayer.zama.ai",
+        network: "https://sepolia.infura.io/v3/YOUR_KEY",
+      },
+    },
+  }),
+  signer,
+  storage: new IndexedDBStorage(),
+});
+
+// 2. Create a token instance (wrapper is auto-discovered if omitted)
+const token = sdk.createToken("0xEncryptedERC20Address");
+// Or provide the wrapper explicitly:
+// const token = sdk.createToken("0xEncryptedERC20Address", "0xWrapperAddress");
+
+// 3. Shield (wrap) public tokens into confidential tokens
+const wrapTx = await token.wrap(1000n);
+
+// 4. Check decrypted balance
+const balance = await token.balanceOf();
+console.log("Confidential balance:", balance);
+
+// 5. Transfer confidential tokens
+const transferTx = await token.confidentialTransfer("0xRecipient", 500n);
+```
+
+### Node.js
+
+```ts
+import { TokenSDK, MemoryStorage } from "@zama-fhe/sdk";
+import { RelayerNode } from "@zama-fhe/sdk/node";
+import { ViemSigner } from "@zama-fhe/sdk/viem";
+
+const signer = new ViemSigner(walletClient, publicClient);
+
+const sdk = new TokenSDK({
+  relayer: new RelayerNode({
+    getChainId: () => signer.getChainId(),
+    poolSize: 4, // number of worker threads (default: min(CPUs, 4))
+    transports: {
+      [1]: {
+        relayerUrl: "https://relayer.zama.ai",
+        network: "https://mainnet.infura.io/v3/YOUR_KEY",
+      },
+      [11155111]: {
+        relayerUrl: "https://relayer.zama.ai",
+        network: "https://sepolia.infura.io/v3/YOUR_KEY",
+      },
+    },
+  }),
+  signer,
+  storage: new MemoryStorage(),
+});
+
+const token = sdk.createToken("0xEncryptedERC20Address");
+const balance = await token.balanceOf();
+```
+
+## Core Concepts
+
+### TokenSDK
+
+Entry point to the SDK. Composes a relayer backend with a signer and storage layer. Acts as a factory for token instances.
+
+```ts
+const sdk = new TokenSDK({
+  relayer, // RelayerSDK — either RelayerWeb (browser) or RelayerNode (Node.js)
+  signer, // GenericSigner
+  storage, // GenericStringStorage
+});
+
+// Read-only — balances, metadata, decryption. No wrapper needed.
+const readonlyToken = sdk.createReadonlyToken("0xTokenAddress");
+
+// Full read/write — shield, unshield, transfer, approve.
+// The token address IS the wrapper (encrypted ERC20 = wrapper contract).
+const token = sdk.createToken("0xTokenAddress");
+// Override wrapper if it differs from the token address (rare):
+// const token = sdk.createToken("0xTokenAddress", "0xWrapperAddress");
+```
+
+The `relayer`, `signer`, and `storage` properties are public and accessible after construction. Low-level FHE operations (`encrypt`, `userDecrypt`, `publicDecrypt`, `generateKeypair`, etc.) are available via `sdk.relayer`. Call `sdk.terminate()` to clean up resources when done.
+
+### Relayer Backends
+
+The `RelayerSDK` interface defines the FHE operations contract. Two implementations are provided:
+
+| Backend       | Import               | Environment | How it works                               |
+| ------------- | -------------------- | ----------- | ------------------------------------------ |
+| `RelayerWeb`  | `@zama-fhe/sdk`      | Browser     | Runs WASM in a Web Worker via CDN          |
+| `RelayerNode` | `@zama-fhe/sdk/node` | Node.js     | Uses `@zama-fhe/relayer-sdk/node` directly |
+
+The `/node` sub-path also exports `NodeWorkerClient` and `NodeWorkerClientConfig` for running FHE operations in a Node.js worker thread.
+
+You can also implement the `RelayerSDK` interface for custom backends.
+
+### Token
+
+Full read/write interface for a single confidential ERC-20. Extends `ReadonlyToken`. The encrypted ERC-20 contract IS the wrapper, so `wrapper` defaults to the token `address`. Pass an explicit `wrapper` only if they differ.
+
+| Method                                     | Description                                                                                                                                                                                                  |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `wrap(amount, options?)`                   | Shield (wrap) public ERC-20 tokens. Handles approval automatically. Options: `{ approvalStrategy: "max" \| "exact" \| "skip" }` (default `"exact"`). `"skip"` bypasses approval (use when already approved). |
+| `wrapETH(amount, value?)`                  | Shield (wrap) native ETH. `value` defaults to `amount`. Use this when the underlying token is the zero address (native ETH).                                                                                 |
+| `unshield(amount, callbacks?)`             | Unwrap a specific amount and finalize in one call. Orchestrates: unwrap → wait receipt → parse event → finalizeUnwrap. Optional `UnshieldCallbacks` for progress tracking.                                   |
+| `unshieldAll(callbacks?)`                  | Unwrap the entire balance and finalize in one call. Orchestrates: unwrapAll → wait receipt → parse event → finalizeUnwrap. Optional `UnshieldCallbacks` for progress tracking.                               |
+| `unwrap(amount)`                           | Request unwrap for a specific amount (low-level, requires manual finalization).                                                                                                                              |
+| `unwrapAll()`                              | Request unwrap for the entire balance (low-level, requires manual finalization).                                                                                                                             |
+| `resumeUnshield(unwrapTxHash, callbacks?)` | Resume an interrupted unshield from an existing unwrap tx hash. Goes straight to wait receipt → finalize.                                                                                                    |
+| `finalizeUnwrap(burnAmountHandle)`         | Complete unwrap with public decryption proof.                                                                                                                                                                |
+| `confidentialTransfer(to, amount)`         | Encrypted transfer. Encrypts amount, then calls the contract.                                                                                                                                                |
+| `confidentialTransferFrom(from, to, amt)`  | Operator encrypted transfer.                                                                                                                                                                                 |
+| `approve(spender, until?)`                 | Set operator approval. `until` defaults to now + 1 hour.                                                                                                                                                     |
+| `isApproved(spender)`                      | Check if a spender is an approved operator.                                                                                                                                                                  |
+| `approveUnderlying(amount?)`               | Approve wrapper to spend underlying ERC-20. Default: max uint256.                                                                                                                                            |
+| `balanceOf(owner?)`                        | Decrypt and return the plaintext balance.                                                                                                                                                                    |
+| `decryptHandles(handles, owner?)`          | Batch-decrypt arbitrary encrypted handles.                                                                                                                                                                   |
+
+All write methods return the transaction hash (`Address`).
+
+### ReadonlyToken
+
+Read-only subset. No wrapper address needed.
+
+| Method                                | Description                                                       |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| `balanceOf(owner?)`                   | Decrypt and return the plaintext balance.                         |
+| `confidentialBalanceOf(owner?)`       | Return the raw encrypted balance handle (no decryption).          |
+| `decryptBalance(handle, owner?)`      | Decrypt a single encrypted handle.                                |
+| `decryptHandles(handles, owner?)`     | Batch-decrypt handles in a single relayer call.                   |
+| `authorize()`                         | Ensure FHE decrypt credentials exist (generates/signs if needed). |
+| `authorizeAll(tokens)` _(static)_     | Pre-authorize multiple tokens with a single wallet signature.     |
+| `isConfidential()`                    | ERC-165 check for ERC-7984 support.                               |
+| `isWrapper()`                         | ERC-165 check for wrapper interface.                              |
+| `discoverWrapper(coordinatorAddress)` | Look up a wrapper for this token via the deployment coordinator.  |
+| `underlyingToken()`                   | Read the underlying ERC-20 address from a wrapper.                |
+| `allowance(wrapper, owner?)`          | Read ERC-20 allowance of the underlying token.                    |
+| `isZeroHandle(handle)`                | Returns `true` if the handle is the zero sentinel.                |
+| `name()` / `symbol()` / `decimals()`  | Read token metadata.                                              |
+
+Static methods for multi-token operations:
+
+```ts
+// Pre-authorize all tokens with a single wallet signature
+const tokens = addresses.map((a) => sdk.createReadonlyToken(a));
+await ReadonlyToken.authorizeAll(tokens);
+// All subsequent decrypts reuse cached credentials — no more wallet prompts
+
+// Decrypt balances for multiple tokens in parallel
+const balances = await ReadonlyToken.batchBalanceOf(tokens, owner);
+
+// Decrypt pre-fetched handles for multiple tokens
+const balances = await ReadonlyToken.batchDecryptBalances(tokens, handles, owner);
+```
+
+### Storage
+
+FHE credentials (keypair + EIP-712 signature) are persisted to storage. Three options:
+
+| Storage            | Use case                                          |
+| ------------------ | ------------------------------------------------- |
+| `MemoryStorage`    | Testing. In-memory `Map`, lost on page reload.    |
+| `IndexedDBStorage` | Browser production. IndexedDB-backed, persistent. |
+| `indexedDBStorage` | Pre-built singleton `IndexedDBStorage` instance.  |
+| Custom             | Implement the `GenericStringStorage` interface.   |
+
+```ts
+interface GenericStringStorage {
+  getItem(key: string): string | Promise<string | null> | null;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+```
+
+## Configuration Reference
+
+### `TokenSDKConfig`
+
+| Field     | Type                   | Description                                              |
+| --------- | ---------------------- | -------------------------------------------------------- |
+| `relayer` | `RelayerSDK`           | Relayer backend (`RelayerWeb` or `RelayerNode` instance) |
+| `signer`  | `GenericSigner`        | Wallet signer interface.                                 |
+| `storage` | `GenericStringStorage` | Credential storage backend.                              |
+
+### `RelayerWebConfig` (browser)
+
+| Field        | Type                                  | Description                                                                                  |
+| ------------ | ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `getChainId` | `() => Promise<number>`               | Resolve the current chain ID. Called lazily; the worker is re-initialized on chain change.   |
+| `transports` | `Record<number, FhevmInstanceConfig>` | Chain-specific configs keyed by chain ID (includes relayerUrl, network, contract addresses). |
+| `security`   | `RelayerWebSecurityConfig`            | Optional. Security options (see below).                                                      |
+| `logger`     | `GenericLogger`                       | Optional. Logger for worker lifecycle and request timing.                                    |
+
+#### `RelayerWebSecurityConfig`
+
+| Field            | Type           | Description                                                                                      |
+| ---------------- | -------------- | ------------------------------------------------------------------------------------------------ |
+| `getCsrfToken`   | `() => string` | Optional. Resolve the CSRF token before each authenticated network request.                      |
+| `integrityCheck` | `boolean`      | Optional. Verify SHA-384 integrity of the CDN bundle. Defaults to `true`. Set `false` for tests. |
+
+### `RelayerNodeConfig` (Node.js)
+
+| Field        | Type                                  | Description                                                                                        |
+| ------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `getChainId` | `() => Promise<number>`               | Resolve the current chain ID. Called lazily; the pool is re-initialized on chain change.           |
+| `transports` | `Record<number, FhevmInstanceConfig>` | Chain-specific configs keyed by chain ID (includes relayerUrl, network, auth, contract addresses). |
+
+### Network Preset Configs
+
+Both the main entry (`@zama-fhe/sdk`) and the `/node` sub-path re-export preset configs so you don't need to import from `@zama-fhe/relayer-sdk` directly:
+
+| Config          | Chain ID | Description                         |
+| --------------- | -------- | ----------------------------------- |
+| `SepoliaConfig` | 11155111 | Sepolia testnet contract addresses. |
+| `MainnetConfig` | 1        | Mainnet contract addresses.         |
+| `HardhatConfig` | 31337    | Local Hardhat node addresses.       |
+
+Each preset provides contract addresses and default values. Override `relayerUrl` and `network` (RPC URL) for your environment:
+
+```ts
+import { SepoliaConfig, MainnetConfig } from "@zama-fhe/sdk";
+
+const transports = {
+  [11155111]: {
+    ...SepoliaConfig,
+    relayerUrl: "/api/proxy",
+    network: "https://sepolia.infura.io/v3/KEY",
+  },
+  [1]: {
+    ...MainnetConfig,
+    relayerUrl: "/api/proxy",
+    network: "https://mainnet.infura.io/v3/KEY",
+  },
+};
+```
+
+## GenericSigner Interface
+
+The `GenericSigner` interface has six methods. Any Web3 library can back it.
+
+```ts
+interface GenericSigner {
+  getChainId(): Promise<number>;
+  getAddress(): Promise<Address>;
+  signTypedData(typedData: EIP712TypedData): Promise<Address>;
+  writeContract(config: ContractCallConfig): Promise<Address>;
+  readContract(config: ContractCallConfig): Promise<unknown>;
+  waitForTransactionReceipt(hash: Address): Promise<TransactionReceipt>;
+}
+```
+
+### Built-in Adapters
+
+**viem** — `@zama-fhe/sdk/viem`
+
+```ts
+import { ViemSigner } from "@zama-fhe/sdk/viem";
+
+const signer = new ViemSigner(walletClient, publicClient);
+```
+
+**ethers** — `@zama-fhe/sdk/ethers`
+
+```ts
+import { EthersSigner } from "@zama-fhe/sdk/ethers";
+
+const signer = new EthersSigner(ethersSigner);
+```
+
+## Contract Call Builders
+
+Every function returns a `ContractCallConfig` object (address, ABI, function name, args) that can be used with any Web3 library. These are the low-level building blocks — they map 1:1 to on-chain contract calls without any orchestration. Use them when the high-level `Token` API doesn't cover your use case.
+
+> **High-level vs low-level:** `token.wrap()` / `token.unshield()` handle the full flow (approval, encryption, receipt waiting, finalization). The contract call builders (`wrapContract()`, `unwrapContract()`, etc.) produce raw call configs for a single contract interaction.
+
+```ts
+interface ContractCallConfig {
+  readonly address: Address;
+  readonly abi: readonly unknown[];
+  readonly functionName: string;
+  readonly args: readonly unknown[];
+  readonly value?: bigint;
+  readonly gas?: bigint;
+}
+```
+
+### ERC-20
+
+| Function                                   | Description              |
+| ------------------------------------------ | ------------------------ |
+| `nameContract(token)`                      | Read token name.         |
+| `symbolContract(token)`                    | Read token symbol.       |
+| `decimalsContract(token)`                  | Read token decimals.     |
+| `balanceOfContract(token, owner)`          | Read ERC-20 balance.     |
+| `allowanceContract(token, owner, spender)` | Read ERC-20 allowance.   |
+| `approveContract(token, spender, value)`   | Approve ERC-20 spending. |
+
+### Encryption (Confidential ERC-20)
+
+| Function                                                                | Description                               |
+| ----------------------------------------------------------------------- | ----------------------------------------- |
+| `confidentialBalanceOfContract(token, user)`                            | Read encrypted balance handle.            |
+| `confidentialTransferContract(token, to, handle, inputProof)`           | Encrypted transfer.                       |
+| `confidentialTransferFromContract(token, from, to, handle, inputProof)` | Operator encrypted transfer.              |
+| `isOperatorContract(token, holder, spender)`                            | Check operator approval.                  |
+| `setOperatorContract(token, spender, timestamp?)`                       | Set operator approval (default: +1 hour). |
+| `confidentialTotalSupplyContract(token)`                                | Read encrypted total supply handle.       |
+| `totalSupplyContract(token)`                                            | Read plaintext total supply.              |
+| `rateContract(token)`                                                   | Read conversion rate.                     |
+| `deploymentCoordinatorContract(token)`                                  | Read deployment coordinator address.      |
+| `isFinalizeUnwrapOperatorContract(token, holder, operator)`             | Check finalize-unwrap operator status.    |
+| `setFinalizeUnwrapOperatorContract(token, operator, timestamp?)`        | Set finalize-unwrap operator.             |
+
+### Wrapper
+
+| Function                                                         | Description                                   |
+| ---------------------------------------------------------------- | --------------------------------------------- |
+| `wrapContract(wrapper, to, amount)`                              | Wrap ERC-20 tokens.                           |
+| `wrapETHContract(wrapper, to, amount, value)`                    | Wrap native ETH.                              |
+| `unwrapContract(token, from, to, encryptedAmount, inputProof)`   | Request unwrap with encrypted amount.         |
+| `unwrapFromBalanceContract(token, from, to, encryptedBalance)`   | Request unwrap using on-chain balance handle. |
+| `finalizeUnwrapContract(wrapper, burntAmount, cleartext, proof)` | Finalize unwrap with decryption proof.        |
+| `underlyingContract(wrapper)`                                    | Read underlying ERC-20 address.               |
+
+### Deployment Coordinator
+
+| Function                                    | Description                  |
+| ------------------------------------------- | ---------------------------- |
+| `getWrapperContract(coordinator, token)`    | Look up wrapper for a token. |
+| `wrapperExistsContract(coordinator, token)` | Check if wrapper exists.     |
+
+### ERC-165
+
+| Function                                        | Description              |
+| ----------------------------------------------- | ------------------------ |
+| `supportsInterfaceContract(token, interfaceId)` | ERC-165 interface check. |
+
+### Fee Manager
+
+| Function                                             | Description                |
+| ---------------------------------------------------- | -------------------------- |
+| `getWrapFeeContract(feeManager, amount, from, to)`   | Calculate wrap fee.        |
+| `getUnwrapFeeContract(feeManager, amount, from, to)` | Calculate unwrap fee.      |
+| `getBatchTransferFeeContract(feeManager)`            | Get batch transfer fee.    |
+| `getFeeRecipientContract(feeManager)`                | Get fee recipient address. |
+
+### Transfer Batcher
+
+| Function                                                                   | Description                         |
+| -------------------------------------------------------------------------- | ----------------------------------- |
+| `confidentialBatchTransferContract(batcher, token, from, transfers, fees)` | Batch multiple encrypted transfers. |
+
+## Library-Specific Contract Helpers
+
+Both the `/viem` and `/ethers` sub-paths export convenience wrappers that execute contract calls directly with library-native clients.
+
+### viem (`@zama-fhe/sdk/viem`)
+
+```ts
+import {
+  readConfidentialBalanceOfContract,
+  writeConfidentialTransferContract,
+  writeWrapContract,
+  // ... more
+} from "@zama-fhe/sdk/viem";
+
+// Read: pass a PublicClient
+const handle = await readConfidentialBalanceOfContract(publicClient, tokenAddress, userAddress);
+
+// Write: pass a WalletClient
+const txHash = await writeConfidentialTransferContract(
+  walletClient,
+  tokenAddress,
+  to,
+  handle,
+  inputProof,
+);
+```
+
+**Read helpers:** `readConfidentialBalanceOfContract`, `readWrapperForTokenContract`, `readUnderlyingTokenContract`, `readWrapperExistsContract`, `readSupportsInterfaceContract`.
+
+**Write helpers:** `writeConfidentialTransferContract`, `writeConfidentialBatchTransferContract`, `writeUnwrapContract`, `writeUnwrapFromBalanceContract`, `writeFinalizeUnwrapContract`, `writeSetOperatorContract`, `writeWrapContract`, `writeWrapETHContract`.
+
+### ethers (`@zama-fhe/sdk/ethers`)
+
+Same set of functions, but read helpers take `Provider | Signer` and write helpers take `Signer`.
+
+```ts
+import {
+  readConfidentialBalanceOfContract,
+  writeConfidentialTransferContract,
+} from "@zama-fhe/sdk/ethers";
+
+const handle = await readConfidentialBalanceOfContract(provider, tokenAddress, userAddress);
+const txHash = await writeConfidentialTransferContract(
+  signer,
+  tokenAddress,
+  to,
+  handle,
+  inputProof,
+);
+```
+
+## Event Decoders
+
+Decode raw log entries from `eth_getLogs` into typed event objects.
+
+### Topics
+
+Use `TOKEN_TOPICS` as the `topics[0]` filter for `getLogs` to capture all confidential token events:
+
+```ts
+import { TOKEN_TOPICS } from "@zama-fhe/sdk";
+
+const logs = await publicClient.getLogs({
+  address: tokenAddress,
+  topics: [TOKEN_TOPICS],
+});
+```
+
+Individual topic hashes are accessible via the `Topics` object: `Topics.ConfidentialTransfer`, `Topics.Wrapped`, `Topics.UnwrapRequested`, `Topics.UnwrappedFinalized`, `Topics.UnwrappedStarted`.
+
+### Decoders
+
+| Function                          | Returns                                                                                                                |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `decodeConfidentialTransfer(log)` | `ConfidentialTransferEvent \| null` — `{ from, to, encryptedAmountHandle }`                                            |
+| `decodeWrapped(log)`              | `WrappedEvent \| null` — `{ mintAmount, amountIn, feeAmount, to, mintTxId }`                                           |
+| `decodeUnwrapRequested(log)`      | `UnwrapRequestedEvent \| null` — `{ receiver, encryptedAmount }`                                                       |
+| `decodeUnwrappedFinalized(log)`   | `UnwrappedFinalizedEvent \| null` — `{ burntAmountHandle, finalizeSuccess, burnAmount, unwrapAmount, feeAmount, ... }` |
+| `decodeUnwrappedStarted(log)`     | `UnwrappedStartedEvent \| null` — `{ returnVal, requestId, txId, to, refund, requestedAmount, burnAmount }`            |
+| `decodeTokenEvent(log)`           | `TokenEvent \| null` — tries all decoders                                                                              |
+| `decodeTokenEvents(logs)`         | `TokenEvent[]` — batch decode, skips unrecognized logs                                                                 |
+
+### Finder Helpers
+
+Convenience functions that decode a logs array and return the first matching event:
+
+```ts
+import { findWrapped, findUnwrapRequested } from "@zama-fhe/sdk";
+
+const wrappedEvent = findWrapped(receipt.logs);
+const unwrapEvent = findUnwrapRequested(receipt.logs);
+```
+
+## Activity Feed Helpers
+
+Transform raw event logs into a user-friendly activity feed with decrypted amounts.
+
+### Pipeline
+
+```ts
+import {
+  parseActivityFeed,
+  extractEncryptedHandles,
+  applyDecryptedValues,
+  sortByBlockNumber,
+} from "@zama-fhe/sdk";
+
+// 1. Parse raw logs into classified activity items
+const items = parseActivityFeed(logs, userAddress);
+
+// 2. Extract encrypted handles that need decryption
+const handles = extractEncryptedHandles(items);
+
+// 3. Decrypt handles (using your token instance)
+const decryptedMap = await token.decryptHandles(handles);
+
+// 4. Apply decrypted values back to activity items
+const enrichedItems = applyDecryptedValues(items, decryptedMap);
+
+// 5. Sort by block number (most recent first)
+const sorted = sortByBlockNumber(enrichedItems);
+```
+
+### Types
+
+```ts
+type ActivityDirection = "incoming" | "outgoing" | "self";
+
+type ActivityType =
+  | "transfer"
+  | "shield"
+  | "unshield_requested"
+  | "unshield_started"
+  | "unshield_finalized";
+
+type ActivityAmount =
+  | { type: "clear"; value: bigint }
+  | { type: "encrypted"; handle: string; decryptedValue?: bigint };
+
+interface ActivityItem {
+  type: ActivityType;
+  direction: ActivityDirection;
+  amount: ActivityAmount;
+  from?: string;
+  to?: string;
+  fee?: ActivityAmount;
+  success?: boolean;
+  metadata: ActivityLogMetadata;
+  rawEvent: TokenEvent;
+}
+
+interface ActivityLogMetadata {
+  transactionHash?: string;
+  blockNumber?: bigint | number;
+  logIndex?: number;
+}
+```
+
+## Error Handling
+
+All SDK errors extend `TokenError`. Use `instanceof` to catch specific error types:
+
+```ts
+import { TokenError, SigningRejectedError, EncryptionFailedError } from "@zama-fhe/sdk";
+
+try {
+  await token.confidentialTransfer(to, amount);
+} catch (error) {
+  if (error instanceof SigningRejectedError) {
+    // User rejected wallet signature
+  }
+  if (error instanceof EncryptionFailedError) {
+    // FHE encryption failed
+  }
+  if (error instanceof TokenError) {
+    // Any other SDK error — check error.code for details
+  }
+}
+```
+
+### Error Classes
+
+| Error Class                 | Code                     | Description                                                               |
+| --------------------------- | ------------------------ | ------------------------------------------------------------------------- |
+| `SigningRejectedError`      | `SIGNING_REJECTED`       | User rejected the wallet signature request.                               |
+| `SigningFailedError`        | `SIGNING_FAILED`         | Wallet signature failed for a non-rejection reason.                       |
+| `EncryptionFailedError`     | `ENCRYPTION_FAILED`      | FHE encryption operation failed.                                          |
+| `DecryptionFailedError`     | `DECRYPTION_FAILED`      | FHE decryption operation failed.                                          |
+| `ApprovalFailedError`       | `APPROVAL_FAILED`        | ERC-20 approval transaction failed.                                       |
+| `TransactionRevertedError`  | `TRANSACTION_REVERTED`   | On-chain transaction reverted.                                            |
+| `InvalidCredentialsError`   | `INVALID_CREDENTIALS`    | Relayer rejected credentials (stale or expired).                          |
+| `NoCiphertextError`         | `NO_CIPHERTEXT`          | No FHE ciphertext exists for this account (e.g. never shielded).          |
+| `RelayerRequestFailedError` | `RELAYER_REQUEST_FAILED` | Relayer HTTP error. Carries a `statusCode` property with the HTTP status. |
+
+**Distinguishing "no ciphertext" from "zero balance":**
+
+```ts
+import { NoCiphertextError, RelayerRequestFailedError } from "@zama-fhe/sdk";
+
+try {
+  const balance = await token.balanceOf();
+} catch (error) {
+  if (error instanceof NoCiphertextError) {
+    // Account has never shielded — show "no confidential balance" in UI
+  }
+  if (error instanceof RelayerRequestFailedError) {
+    console.error(`Relayer returned HTTP ${error.statusCode}`);
+  }
+}
+```
+
+### Unshield Progress Callbacks
+
+`unshield()`, `unshieldAll()`, and `resumeUnshield()` accept optional callbacks for tracking progress through the two-phase unshield flow:
+
+```ts
+import type { UnshieldCallbacks } from "@zama-fhe/sdk";
+
+const callbacks: UnshieldCallbacks = {
+  onUnwrapSubmitted: (txHash) => console.log("Unwrap tx:", txHash),
+  onFinalizing: () => console.log("Waiting for decryption proof..."),
+  onFinalizeSubmitted: (txHash) => console.log("Finalize tx:", txHash),
+};
+
+await token.unshield(500n, callbacks);
+```
+
+Callbacks are safe — a throwing callback will not interrupt the unshield flow.
+
+## RelayerSDK (Low-Level FHE)
+
+Low-level FHE operations are available on the relayer backend via `sdk.relayer`:
+
+| Method                                                                      | Description                                                                            |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `encrypt(params)`                                                           | Encrypt values for smart contract calls. Returns `{ handles, inputProof }`.            |
+| `userDecrypt(params)`                                                       | Decrypt ciphertext handles with the user's FHE private key.                            |
+| `publicDecrypt(handles)`                                                    | Public decryption (no private key needed). Returns `{ clearValues, decryptionProof }`. |
+| `generateKeypair()`                                                         | Generate an FHE keypair. Returns `{ publicKey, privateKey }`.                          |
+| `createEIP712(publicKey, contractAddresses, startTimestamp, durationDays?)` | Create EIP-712 typed data for decrypt authorization. Default duration: 7 days.         |
+| `createDelegatedUserDecryptEIP712(...)`                                     | Create EIP-712 for delegated decryption.                                               |
+| `delegatedUserDecrypt(params)`                                              | Decrypt via delegation.                                                                |
+| `requestZKProofVerification(zkProof)`                                       | Submit a ZK proof for on-chain verification.                                           |
+| `getPublicKey()`                                                            | Get the TFHE compact public key.                                                       |
+| `getPublicParams(bits)`                                                     | Get public parameters for encryption capacity.                                         |
+| `terminate()`                                                               | Terminate the backend and clean up resources.                                          |
+
+## Constants
+
+| Constant                       | Value                             | Description                                   |
+| ------------------------------ | --------------------------------- | --------------------------------------------- |
+| `ZERO_HANDLE`                  | `"0x0000...0000"` (32 zero bytes) | Sentinel for empty/zero encrypted values.     |
+| `ERC7984_INTERFACE_ID`         | `"0x4958f2a4"`                    | ERC-165 interface ID for confidential tokens. |
+| `ERC7984_WRAPPER_INTERFACE_ID` | `"0xd04584ba"`                    | ERC-165 interface ID for wrapper contracts.   |
+
+## Exported ABIs
+
+For direct use with viem, ethers, or any ABI-compatible library:
+
+`ERC20_ABI`, `ERC20_METADATA_ABI`, `ENCRYPTION_ABI`, `WRAPPER_ABI`, `DEPLOYMENT_COORDINATOR_ABI`, `ERC165_ABI`, `FEE_MANAGER_ABI`, `TRANSFER_BATCHER_ABI`, `BATCH_SWAP_ABI`.