@zama-fhe/sdk 1.0.0 → 1.0.1

package/README.md

@@ -6,6 +6,10 @@ A TypeScript SDK for building privacy-preserving token applications using Fully
 
 ```bash
 pnpm add @zama-fhe/sdk
+# or
+npm install @zama-fhe/sdk
+# or
+yarn add @zama-fhe/sdk
 ```
 
 ### Peer dependencies
@@ -21,22 +25,23 @@ pnpm add @zama-fhe/sdk
 ### Browser
 
 ```ts
-import { TokenSDK, RelayerWeb, IndexedDBStorage } from "@zama-fhe/sdk";
+import { ZamaSDK, RelayerWeb, IndexedDBStorage } from "@zama-fhe/sdk";
 import { ViemSigner } from "@zama-fhe/sdk/viem";
+import { mainnet, sepolia } from "viem/chains";
 
 // 1. Create signer and relayer
-const signer = new ViemSigner(walletClient, publicClient);
+const signer = new ViemSigner({ walletClient, publicClient });
 
-const sdk = new TokenSDK({
+const sdk = new ZamaSDK({
   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",
       },
     },
@@ -51,7 +56,7 @@ const token = sdk.createToken("0xEncryptedERC20Address");
 // const token = sdk.createToken("0xEncryptedERC20Address", "0xWrapperAddress");
 
 // 3. Shield (wrap) public tokens into confidential tokens
-const wrapTx = await token.wrap(1000n);
+const { txHash } = await token.shield(1000n);
 
 // 4. Check decrypted balance
 const balance = await token.balanceOf();
@@ -64,29 +69,30 @@ 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 { ZamaSDK } from "@zama-fhe/sdk";
+import { RelayerNode, asyncLocalStorage } from "@zama-fhe/sdk/node";
 import { ViemSigner } from "@zama-fhe/sdk/viem";
+import { mainnet, sepolia } from "viem/chains";
 
-const signer = new ViemSigner(walletClient, publicClient);
+const signer = new ViemSigner({ walletClient, publicClient });
 
-const sdk = new TokenSDK({
+const sdk = new ZamaSDK({
   relayer: new RelayerNode({
     getChainId: () => signer.getChainId(),
     poolSize: 4, // number of worker threads (default: min(CPUs, 4))
     transports: {
-      [1]: {
-        relayerUrl: "https://relayer.zama.ai",
+      [mainnet.id]: {
         network: "https://mainnet.infura.io/v3/YOUR_KEY",
+        auth: { __type: "ApiKeyHeader", value: process.env.RELAYER_API_KEY },
       },
-      [11155111]: {
-        relayerUrl: "https://relayer.zama.ai",
+      [sepolia.id]: {
         network: "https://sepolia.infura.io/v3/YOUR_KEY",
+        auth: { __type: "ApiKeyHeader", value: process.env.RELAYER_API_KEY },
       },
     },
   }),
   signer,
-  storage: new MemoryStorage(),
+  storage: asyncLocalStorage,
 });
 
 const token = sdk.createToken("0xEncryptedERC20Address");
@@ -95,15 +101,15 @@ const balance = await token.balanceOf();
 
 ## Core Concepts
 
-### TokenSDK
+### ZamaSDK
 
 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({
+const sdk = new ZamaSDK({
   relayer, // RelayerSDK — either RelayerWeb (browser) or RelayerNode (Node.js)
   signer, // GenericSigner
-  storage, // GenericStringStorage
+  storage, // GenericStorage
 });
 
 // Read-only — balances, metadata, decryption. No wrapper needed.
@@ -137,8 +143,8 @@ Full read/write interface for a single confidential ERC-20. Extends `ReadonlyTok
 
 | 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).                                                                                 |
+| `shield(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). |
+| `shieldETH(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).                                                                                                                              |
@@ -153,80 +159,206 @@ Full read/write interface for a single confidential ERC-20. Extends `ReadonlyTok
 | `balanceOf(owner?)`                        | Decrypt and return the plaintext balance.                                                                                                                                                                    |
 | `decryptHandles(handles, owner?)`          | Batch-decrypt arbitrary encrypted handles.                                                                                                                                                                   |
 
-All write methods return the transaction hash (`Address`).
+All write methods return a `TransactionResult` object:
+
+```ts
+interface TransactionResult {
+  txHash: Hex;
+  receipt: TransactionReceipt;
+}
+```
 
 ### 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.                                              |
+| 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.                             |
+| `allow()`                             | Ensure FHE decrypt credentials exist (generates/signs if needed).           |
+| `allow(...tokens)` _(static)_         | Pre-authorize multiple tokens with a single wallet signature.               |
+| `isAllowed()`                         | Whether a session signature is currently cached for this token.             |
+| `revoke()`                            | Clear the session signature for the connected wallet.                       |
+| `credentials.allow(...addresses)`     | Pre-authorize and cache the session signature for specific token addresses. |
+| `credentials.revoke(...addresses?)`   | Clear the session signature for the connected wallet.                       |
+| `credentials.isAllowed()`             | Whether a session signature is currently cached.                            |
+| `credentials.isExpired(address?)`     | Whether stored credentials are past their expiration time.                  |
+| `credentials.clear()`                 | Delete stored credentials for the connected wallet.                         |
+| `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);
+await ReadonlyToken.allow(...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);
+const balances = await ReadonlyToken.batchDecryptBalances(tokens, { owner });
 
 // Decrypt pre-fetched handles for multiple tokens
-const balances = await ReadonlyToken.batchDecryptBalances(tokens, handles, owner);
+const balances = await ReadonlyToken.batchDecryptBalances(tokens, { handles, owner });
+```
+
+### Pending Unshield Persistence
+
+The unshield flow is two-phase: unwrap tx, then finalize. If the page reloads between phases, the unwrap tx hash is lost. Use these utilities to persist it:
+
+```ts
+import { savePendingUnshield, loadPendingUnshield, clearPendingUnshield } from "@zama-fhe/sdk";
+
+// Save the unwrap hash before finalization
+await savePendingUnshield(storage, wrapperAddress, unwrapTxHash);
+
+// On next load, check for pending unshields
+const pending = await loadPendingUnshield(storage, wrapperAddress);
+if (pending) {
+  await token.resumeUnshield(pending);
+  await clearPendingUnshield(storage, wrapperAddress);
+}
 ```
 
 ### Storage
 
-FHE credentials (keypair + EIP-712 signature) are persisted to storage. Three options:
+FHE credentials (encrypted keypair + metadata) are persisted to `storage`. The wallet signature is kept in `sessionStorage` (in-memory by default) — never written to disk. Two storage roles:
+
+**Credential storage** (`storage`) — persists encrypted keypairs:
+
+| Storage             | Use case                                                 |
+| ------------------- | -------------------------------------------------------- |
+| `indexedDBStorage`  | Browser apps — persists across page reloads and sessions |
+| `memoryStorage`     | Tests, scripts, throwaway sessions                       |
+| `asyncLocalStorage` | Node.js servers — isolate credentials per request        |
+| Custom              | Implement the `GenericStorage` interface                 |
+
+**Session storage** (`sessionStorage`) — holds wallet signatures for the current session:
 
-| 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.   |
+| Storage                | Use case                                                    |
+| ---------------------- | ----------------------------------------------------------- |
+| Default (in-memory)    | Standard web apps — signature lost on reload, user re-signs |
+| `chromeSessionStorage` | MV3 web extensions — survives service worker restarts       |
+| Custom                 | Implement the `GenericStorage` 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>;
+interface GenericStorage<T = unknown> {
+  get(key: string): Promise<T | null>;
+  set(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
 }
 ```
 
+#### Web Extension Example
+
+For MV3 extensions, use the built-in `chromeSessionStorage` singleton to share the wallet signature across popup, background, and content script contexts:
+
+```ts
+import { ZamaSDK, indexedDBStorage, chromeSessionStorage } from "@zama-fhe/sdk";
+
+const sdk = new ZamaSDK({
+  relayer,
+  signer,
+  storage: indexedDBStorage, // encrypted keypairs (persistent)
+  sessionStorage: chromeSessionStorage, // wallet signatures (ephemeral, shared across contexts)
+});
+```
+
 ## Configuration Reference
 
-### `TokenSDKConfig`
+### `ZamaSDKConfig`
 
-| Field     | Type                   | Description                                              |
-| --------- | ---------------------- | -------------------------------------------------------- |
-| `relayer` | `RelayerSDK`           | Relayer backend (`RelayerWeb` or `RelayerNode` instance) |
-| `signer`  | `GenericSigner`        | Wallet signer interface.                                 |
-| `storage` | `GenericStringStorage` | Credential storage backend.                              |
+| Field            | Type                   | Description                                                                                                                            |
+| ---------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `relayer`        | `RelayerSDK`           | Relayer backend (`RelayerWeb` or `RelayerNode` instance)                                                                               |
+| `signer`         | `GenericSigner`        | Wallet signer interface.                                                                                                               |
+| `storage`        | `GenericStorage`       | Credential storage backend.                                                                                                            |
+| `sessionStorage` | `GenericStorage`       | Optional. Session storage for wallet signatures. Default: in-memory (lost on reload). Use `chrome.storage.session` for web extensions. |
+| `keypairTTL`     | `number`               | Optional. Seconds the ML-KEM re-encryption keypair remains valid. Default: `86400` (1 day). Must be positive.                          |
+| `sessionTTL`     | `number`               | Optional. Seconds the session signature remains valid. Default: `2592000` (30 days). `0` = re-sign every operation.                    |
+| `onEvent`        | `ZamaSDKEventListener` | Optional. Structured event listener for debugging.                                                                                     |
+
+#### Structured Event Listener
+
+The `onEvent` callback receives typed events at key lifecycle points. Event payloads never contain sensitive data (amounts, keys, proofs) — only metadata useful for debugging and telemetry.
+
+```ts
+const sdk = new ZamaSDK({
+  relayer,
+  signer,
+  storage,
+  onEvent: ({ type, tokenAddress, ...event }) => {
+    console.debug(`[Zama] ${type}`, {
+      tokenAddress: tokenAddress?.slice(0, 10),
+      ...event,
+    });
+  },
+});
+```
+
+**Event types:**
+
+| Category               | Events                                                                                                                                                               | Key fields                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Credentials            | `credentials:loading`, `credentials:cached`, `credentials:expired`, `credentials:creating`, `credentials:created`, `credentials:revoked`, `credentials:allowed`      | `contractAddresses`                                              |
+| Encryption             | `encrypt:start`, `encrypt:end`, `encrypt:error`                                                                                                                      | `durationMs` (end/error), `error` (error)                        |
+| Decryption             | `decrypt:start`, `decrypt:end`, `decrypt:error`                                                                                                                      | `durationMs` (end/error), `error` (error)                        |
+| Transactions           | `transaction:error`                                                                                                                                                  | `operation` (`"transfer"`, `"wrap"`, `"approve"`, etc.), `error` |
+| Write confirmations    | `wrap:submitted`, `transfer:submitted`, `transferFrom:submitted`, `approve:submitted`, `approveUnderlying:submitted`, `unwrap:submitted`, `finalizeUnwrap:submitted` | `txHash`                                                         |
+| Unshield orchestration | `unshield:phase1_submitted`, `unshield:phase2_started`, `unshield:phase2_submitted`                                                                                  | `txHash`, `operationId`                                          |
+
+All events carry `tokenAddress`, `timestamp`, and an optional `operationId` (set on unshield phase events to correlate multi-step operations).
+
+**Dispatching events to other systems:**
+
+The `onEvent` callback is a simple function — you can bridge it to any event system:
+
+```ts
+// Fan out to multiple listeners with EventEmitter
+import { EventEmitter } from "events";
+const emitter = new EventEmitter();
+const sdk = new ZamaSDK({
+  // ...
+  onEvent: (event) => emitter.emit(event.type, event),
+});
+emitter.on("encrypt:start", (e) => {
+  /* listener A */
+});
+emitter.on("encrypt:start", (e) => {
+  /* listener B */
+});
+
+// Bridge to DOM CustomEvent (e.g. for cross-framework communication)
+const sdk = new ZamaSDK({
+  // ...
+  onEvent: (event) => window.dispatchEvent(new CustomEvent(event.type, { detail: event })),
+});
+
+// Collect into React state
+const [events, setEvents] = useState<ZamaSDKEvent[]>([]);
+const sdk = new ZamaSDK({
+  // ...
+  onEvent: (event) => setEvents((prev) => [...prev, event]),
+});
+```
 
 ### `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.                                    |
+| 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.                                       |
+| `threads`    | `number`                              | Optional. WASM thread count for parallel FHE ops (4–8 recommended). Requires COOP/COEP headers. |
 
 #### `RelayerWebSecurityConfig`
 
@@ -235,6 +367,8 @@ interface GenericStringStorage {
 | `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. |
 
+> **Security note:** `RelayerWeb` loads FHE WASM from a CDN at runtime. The `integrityCheck` option (enabled by default) verifies the SHA-384 hash of the bundle before execution, protecting against CDN compromise or MITM attacks. Only disable it in local development or testing.
+
 ### `RelayerNodeConfig` (Node.js)
 
 | Field        | Type                                  | Description                                                                                        |
@@ -252,21 +386,26 @@ Both the main entry (`@zama-fhe/sdk`) and the `/node` sub-path re-export preset
 | `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:
+Each preset provides contract addresses and default relayer URL. Override `network` (RPC URL) for your environment. Browser apps should override `relayerUrl` with a proxy; server-side apps add `auth`:
 
 ```ts
 import { SepoliaConfig, MainnetConfig } from "@zama-fhe/sdk";
 
+// Browser — proxy through your backend
 const transports = {
-  [11155111]: {
+  [SepoliaConfig.chainId]: {
     ...SepoliaConfig,
-    relayerUrl: "/api/proxy",
+    relayerUrl: "https://your-app.com/api/relayer/11155111",
     network: "https://sepolia.infura.io/v3/KEY",
   },
-  [1]: {
-    ...MainnetConfig,
-    relayerUrl: "/api/proxy",
-    network: "https://mainnet.infura.io/v3/KEY",
+};
+
+// Node.js — auth is safe server-side
+const transports = {
+  [SepoliaConfig.chainId]: {
+    ...SepoliaConfig,
+    network: "https://sepolia.infura.io/v3/KEY",
+    auth: { __type: "ApiKeyHeader", value: process.env.RELAYER_API_KEY },
   },
 };
 ```
@@ -279,10 +418,10 @@ The `GenericSigner` interface has six methods. Any Web3 library can back it.
 interface GenericSigner {
   getChainId(): Promise<number>;
   getAddress(): Promise<Address>;
-  signTypedData(typedData: EIP712TypedData): Promise<Address>;
-  writeContract(config: ContractCallConfig): Promise<Address>;
+  signTypedData(typedData: EIP712TypedData): Promise<Hex>;
+  writeContract(config: ContractCallConfig): Promise<Hex>;
   readContract(config: ContractCallConfig): Promise<unknown>;
-  waitForTransactionReceipt(hash: Address): Promise<TransactionReceipt>;
+  waitForTransactionReceipt(hash: Hex): Promise<TransactionReceipt>;
 }
 ```
 
@@ -293,7 +432,7 @@ interface GenericSigner {
 ```ts
 import { ViemSigner } from "@zama-fhe/sdk/viem";
 
-const signer = new ViemSigner(walletClient, publicClient);
+const signer = new ViemSigner({ walletClient, publicClient });
 ```
 
 **ethers** — `@zama-fhe/sdk/ethers`
@@ -301,14 +440,14 @@ const signer = new ViemSigner(walletClient, publicClient);
 ```ts
 import { EthersSigner } from "@zama-fhe/sdk/ethers";
 
-const signer = new EthersSigner(ethersSigner);
+const signer = new EthersSigner({ signer: 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.
+> **High-level vs low-level:** `token.shield()` / `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 {
@@ -466,8 +605,8 @@ Individual topic hashes are accessible via the `Topics` object: `Topics.Confiden
 | `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                                                                 |
+| `decodeOnChainEvent(log)`         | `OnChainEvent \| null` — tries all decoders                                                                            |
+| `decodeOnChainEvents(logs)`       | `OnChainEvent[]` — batch decode, skips unrecognized logs                                                               |
 
 ### Finder Helpers
 
@@ -535,7 +674,7 @@ interface ActivityItem {
   fee?: ActivityAmount;
   success?: boolean;
   metadata: ActivityLogMetadata;
-  rawEvent: TokenEvent;
+  rawEvent: OnChainEvent;
 }
 
 interface ActivityLogMetadata {
@@ -547,10 +686,10 @@ interface ActivityLogMetadata {
 
 ## Error Handling
 
-All SDK errors extend `TokenError`. Use `instanceof` to catch specific error types:
+All SDK errors extend `ZamaError`. Use `instanceof` to catch specific error types:
 
 ```ts
-import { TokenError, SigningRejectedError, EncryptionFailedError } from "@zama-fhe/sdk";
+import { ZamaError, SigningRejectedError, EncryptionFailedError } from "@zama-fhe/sdk";
 
 try {
   await token.confidentialTransfer(to, amount);
@@ -561,7 +700,7 @@ try {
   if (error instanceof EncryptionFailedError) {
     // FHE encryption failed
   }
-  if (error instanceof TokenError) {
+  if (error instanceof ZamaError) {
     // Any other SDK error — check error.code for details
   }
 }
@@ -577,10 +716,24 @@ try {
 | `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).                          |
+| `InvalidKeypairError`       | `INVALID_KEYPAIR`        | Relayer rejected FHE keypair (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. |
 
+### `matchZamaError`
+
+Pattern-match on error codes without `instanceof` chains. Falls through to the `_` wildcard if no handler matches. Returns `undefined` for non-SDK errors when no `_` handler is provided.
+
+```ts
+import { matchZamaError } from "@zama-fhe/sdk";
+
+matchZamaError(error, {
+  SIGNING_REJECTED: () => toast("Please approve in wallet"),
+  TRANSACTION_REVERTED: (e) => toast(`Tx failed: ${e.message}`),
+  _: () => toast("Unknown error"),
+});
+```
+
 **Distinguishing "no ciphertext" from "zero balance":**
 
 ```ts