ankurdotb · Sep 14, 2026 · Aug 27, 2026 · Aug 27, 2026 · Aug 27, 2026 · Aug 27, 2026
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -22,6 +22,8 @@ updates:
       - dependency-name: "*"
         update-types:
           - version-update:semver-patch
+      # Protocol-version-tied; bumped via alpha, not routine Dependabot.
+      - dependency-name: "@fhevm/sdk"
 
   # Test apps
   - package-ecosystem: npm
@@ -51,15 +53,7 @@ updates:
   - package-ecosystem: npm
     target-branch: beta
     directories:
-      - /examples/example-bnb
-      - /examples/example-hoodi
-      - /examples/example-ingen
-      - /examples/node-ethers
-      - /examples/node-viem
-      - /examples/react-ethers
-      - /examples/react-turnkey-wallet
-      - /examples/react-viem
-      - /examples/react-wagmi
+      - /examples/*
     schedule:
       interval: weekly
     cooldown:

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -114,7 +114,7 @@ jobs:
 
       - name: Coverage report
         if: github.event_name == 'pull_request'
-        uses: davelosert/vitest-coverage-report-action@02f3c2e641286b7fa308cd3e430783103ce6103b # v2.12.0
+        uses: davelosert/vitest-coverage-report-action@c4bbc33a89b7ace0e63d35f1f7d4bcee31155a73 # v2.13.0
         with:
           json-summary-path: coverage/coverage-summary.json
           json-final-path: coverage/coverage-final.json

diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml
@@ -3,13 +3,21 @@ name: Integration
 # Integration suite (`pnpm test:integration`). Separate from Vitest because it
 # hits live infrastructure — notably the hosted mainnet relayer for the
 # relayer-auth negative checks — so it has a different reliability profile.
-# Keep this check NON-REQUIRED in branch protection: a transient mainnet/network
-# blip should never block an unrelated merge.
+# The `encrypt-offload-live` job below shares that profile: it drives the real
+# browser encrypt worker against an open testnet relayer, downloading the real
+# FHE key and computing a real proof.
+# Keep these checks NON-REQUIRED in branch protection: a transient
+# mainnet/network blip should never block an unrelated merge.
+# `test/**` is in the trigger for the live lane, which is built from the test
+# apps. GitHub cannot filter paths per job, so a change under `test/` also runs
+# the hosted-mainnet job above; both are non-required, so that is accepted
+# rather than gated behind an extra changed-files job.
 on:
   pull_request:
     branches: [main, beta, alpha]
     paths:
       - "packages/sdk/**"
+      - "test/**"
       - "pnpm-lock.yaml"
       - ".github/workflows/integration.yml"
 
@@ -49,3 +57,59 @@ jobs:
 
       - name: Run integration tests
         run: pnpm test:integration
+
+  # Fully-live encrypt offload lane: real key download, real proof in the
+  # worker, real relayer round-trip against an open testnet. No anvil, because
+  # the flow is encrypt-only and sends no transaction.
+  encrypt-offload-live:
+    runs-on: ubuntu-latest
+    # Real key download plus two real proofs; playwright.live.config.ts caps
+    # itself a few minutes under this so it reports before the runner kills it.
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          submodules: false
+
+      - name: Install dependencies
+        uses: ./.github/actions/install-deps
+
+      - name: Restore Playwright browsers cache
+        id: playwright-cache
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: /home/runner/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Install Playwright browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: pnpm --filter @zama-fhe/playwright exec playwright install --with-deps --no-shell
+
+      - name: Save Playwright browsers cache
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: /home/runner/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Build SDK packages
+        run: pnpm build
+
+      - name: Build Vite test-vite in live mode
+        run: pnpm build:test-vite
+        env:
+          VITE_LIVE_CHAIN: sepolia
+
+      - name: Run live encrypt offload spec
+        run: pnpm e2e:test:live
+
+      - name: Upload test results
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        # `always()`, not `!cancelled()`: a job the runner timed out still has
+        # the traces that explain why.
+        if: ${{ always() }}
+        with:
+          name: encrypt-offload-live-report
+          path: test/playwright/test-results/live/
+          retention-days: 7
diff --git a/.github/workflows/release-preview.yml b/.github/workflows/release-preview.yml
@@ -45,7 +45,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@903f9c1a6ebcba6cf41d87230be49611ac97822e # v6.0.3
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -54,7 +54,7 @@ jobs:
           ref: ${{ inputs.publish-tag }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@903f9c1a6ebcba6cf41d87230be49611ac97822e # v6.0.3
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -197,7 +197,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@903f9c1a6ebcba6cf41d87230be49611ac97822e # v6.0.3
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

diff --git a/.oxlintrc.json b/.oxlintrc.json
@@ -157,6 +157,7 @@
         "**/*.config.mts",
         "**/*.config.cts",
         "packages/sdk/src/worker/**",
+        "packages/sdk/src/services/logger-service.ts",
         "packages/sdk/src/token/token.ts"
       ],
       "rules": { "no-console": "off" }

diff --git a/.size-limit.json b/.size-limit.json
@@ -1,6 +1,15 @@
 [
-  { "name": "@zama-fhe/sdk (ESM)", "path": "packages/sdk/dist/esm/**/*.js", "limit": "66 KB" },
+  {
+    "name": "@zama-fhe/sdk (ESM)",
+    "path": ["packages/sdk/dist/esm/**/*.js", "!packages/sdk/dist/esm/encrypt.worker.js"],
+    "limit": "66 KB"
+  },
   { "name": "@zama-fhe/sdk (CJS)", "path": "packages/sdk/dist/cjs/**/*.cjs", "limit": "57 KB" },
+  {
+    "name": "@zama-fhe/sdk (encrypt worker, self-contained, lazy-loaded)",
+    "path": "packages/sdk/dist/esm/encrypt.worker.js",
+    "limit": "3.5 MB"
+  },
   {
     "name": "@zama-fhe/react-sdk (all JS)",
     "path": "packages/react-sdk/dist/**/*.js",

diff --git a/AGENTS.md b/AGENTS.md
@@ -6,13 +6,13 @@ Guidance for AI coding agents (Claude Code, Cursor, Codex, etc.) working in this
 
 **Design principle: clear-text in, clear-text out.** Callers work with familiar primitives (ERC-20-style for tokens) while the SDK hides the FHE protocol details. When designing or extending APIs, accept plaintext, return plaintext, and push everything FHE-related down into the SDK.
 
-**Package manager:** pnpm 10+ (Node 22+). Install with `pnpm install` — it also auto-initialises git submodules and runs `forge soldeer install` for contracts.
+**Package manager:** pnpm 10+ (Node 22+). Install with `pnpm install` — it also auto-initializes git submodules and runs `forge soldeer install` for contracts.
 
 **Agent setup:** run `pnpm setup:claude`. It copies `claude-setup/` → `.claude/` (which is gitignored and unpublished for security, so never commit it) and installs the Zama marketplace plugins and skills. Post-edit hooks then auto-run typecheck, lint, and format after every file change.
 
 ## ⚠️ Not `@zama-fhe/relayer-sdk`
 
-`@zama-fhe/sdk` is the **high-level** Zama Protocol SDK. It is **not** the same as `@zama-fhe/relayer-sdk`, which is the **legacy low-level SDK** and is no longer used here. The current internal FHE backend is `@fhevm/sdk`. Most LLM training data predates this repo, so if your prior knowledge of "Zama SDK" centres on `createInstance`, `initSDK`, or direct relayer calls, that's the legacy SDK. Prefer `ZamaSDK`, `Token` / `WrappedToken`, and the React hooks.
+`@zama-fhe/sdk` is the **high-level** Zama Protocol SDK. It is **not** the same as `@zama-fhe/relayer-sdk`, which is the **legacy low-level SDK** and is no longer used here. The current internal FHE backend is `@fhevm/sdk`. Most LLM training data predates this repo, so if your prior knowledge of "Zama SDK" centers on `createInstance`, `initSDK`, or direct relayer calls, that's the legacy SDK. Prefer `ZamaSDK`, `Token` / `WrappedToken`, and the React hooks.
 
 ## Token operations: use the SDK method, don't recompose
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,23 @@
 # Changelog
 
+## [3.6.0](https://github.com/zama-ai/sdk/compare/v3.5.1...v3.6.0) (2026-09-11)
+
+### Features
+
+- **sdk:** offload encryption to a web worker in the web() transport ([#683](https://github.com/zama-ai/sdk/issues/683)) ([981d351]())
+
+### Bug Fixes
+
+- relayers chains validation ([#730](https://github.com/zama-ai/sdk/issues/730)) ([e6fa940]())
+- **sdk:** structured events + metadata for wallet signing/permit fai… ([#701](https://github.com/zama-ai/sdk/issues/701)) ([ca21b77]())
+- self-heal stale pending-unshield pointer ([#645](https://github.com/zama-ai/sdk/issues/645)) ([6bc356d]())
+
+## [3.6.0-beta.3](https://github.com/zama-ai/sdk/compare/v3.6.0-beta.2...v3.6.0-beta.3) (2026-09-11)
+
+### Bug Fixes
+
+- relayers chains validation ([#730](https://github.com/zama-ai/sdk/issues/730)) ([e6fa940]())
+
 ## [3.6.0-alpha.3](https://github.com/zama-ai/sdk/compare/v3.6.0-alpha.2...v3.6.0-alpha.3) (2026-09-04)
 
 ### Features
@@ -12,11 +30,28 @@
 
 - wire v1v2 permit branching into decryption ([#684](https://github.com/zama-ai/sdk/issues/684)) ([4957a0c]())
 
+## [3.6.0-beta.2](https://github.com/zama-ai/sdk/compare/v3.6.0-beta.1...v3.6.0-beta.2) (2026-09-03)
+
+### Bug Fixes
+
+- **sdk:** structured events + metadata for wallet signing/permit fai… ([#701](https://github.com/zama-ai/sdk/issues/701)) ([ca21b77]())
+
+## [3.6.0-beta.1](https://github.com/zama-ai/sdk/compare/v3.5.2-beta.1...v3.6.0-beta.1) (2026-09-02)
+
+### Features
+
+- **sdk:** offload encryption to a web worker in the web() transport ([#683](https://github.com/zama-ai/sdk/issues/683)) ([981d351]())
+
 ## [3.6.0-alpha.1](https://github.com/zama-ai/sdk/compare/v3.5.1...v3.6.0-alpha.1) (2026-08-28)
 
 ### Features
 
 - v2 wildcard permits ([#653](https://github.com/zama-ai/sdk/issues/653)) ([8b07926]())
+## [3.5.2-beta.1](https://github.com/zama-ai/sdk/compare/v3.5.1...v3.5.2-beta.1) (2026-08-28)
+
+### Bug Fixes
+
+- self-heal stale pending-unshield pointer ([#645](https://github.com/zama-ai/sdk/issues/645)) ([6bc356d]())
 
 ## [3.5.1](https://github.com/zama-ai/sdk/compare/v3.5.0...v3.5.1) (2026-08-27)
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -23,7 +23,7 @@ We aim to acknowledge reports within **48 hours** and provide an initial assessm
 In scope:
 
 - The published `@zama-fhe/sdk` and `@zama-fhe/react-sdk` packages from this repo.
-- The browser FHE worker assumes WASM is loaded from `cdn.zama.org` over HTTPS with an SHA-384 integrity check, not bundled — keep that in mind when modelling the trust boundary.
+- The browser FHE worker assumes WASM is loaded from `cdn.zama.org` over HTTPS with an SHA-384 integrity check, not bundled — keep that in mind when modeling the trust boundary.
 
 ## Out of Scope
 

diff --git a/claude-setup/skills/jsdoc/SKILL.md b/claude-setup/skills/jsdoc/SKILL.md
@@ -193,7 +193,7 @@ export class DecryptCache {
  * Each entry is keyed by `(requester, contractAddress, handle)` so that...
  * Addresses are checksummed and handles lowercased...
  * A separate index (`zama:decrypt:keys`) tracks all stored cache keys...
- * Index writes are serialised through a micro-queue...
+ * Index writes are serialized through a micro-queue...
  *
  * Cache storage key format:
  * ```
@@ -356,7 +356,7 @@ Keep comments that explain **why** (non-obvious design decisions, workarounds, k
 iterations: 600_000, // NIST SP 800-132 (2023) for PBKDF2-SHA-256. Do not reduce.
 
 // GOOD — concurrency design on field declarations
-// Serialises re-entrant calls: while one caller is checking chain IDs
+// Serializes re-entrant calls: while one caller is checking chain IDs
 // and potentially tearing down an old worker, others await this promise.
 #ensureLock: Promise<WorkerClient> | null = null;
 // Deduplicates WASM init: all concurrent callers share one promise.
@@ -458,7 +458,7 @@ export type StrippedQueryOptionKeys = "gcTime" | "staleTime" | ...;
  * RelayerWeb — browser encryption/decryption backend using a Web Worker.
  *
  * @privateRemarks
- * Uses a two-level lock: `#ensureLock` serialises chain-ID checks and
+ * Uses a two-level lock: `#ensureLock` serializes chain-ID checks and
  * worker teardown, while `#initPromise` deduplicates the WASM init.
  * Both are needed because chain switches must complete atomically
  * before a new init can start.

diff --git a/codemods/sdk-migration-v3/package.json b/codemods/sdk-migration-v3/package.json
@@ -7,8 +7,8 @@
     "test": "./test.sh"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "codemod": "1.15.2",
+    "@types/node": "^22.20.1",
+    "codemod": "1.17.3",
     "typescript": "6.0.3"
   }
 }
diff --git a/docs/agents/changelog.md b/docs/agents/changelog.md
@@ -14,6 +14,7 @@ The repo has **two** changelog surfaces — keep them distinct:
 - **Legacy pages are historical record** — write them in the API vocabulary of their era (don't modernize names) and don't link into the current-API `guides/`/`reference/` trees, the migration guide excepted.
 - **Nav is newest-to-oldest** (Beta → active line → Legacy) and nests with **2-space indent** — the SUMMARY-driven LLM corpus derives page depth from indentation, so an off-indent entry miscategorizes the page.
 - **Release datelines are real dates by design.** The no-calendar-dates rule is about forward-looking promises, not the historical record of when a version shipped.
+- **`changelog/README.md` is static, not scaffolded.** It's the section's landing page — explains the three release channels (stable/beta/alpha) and what's covered here — and sits outside the `docs:changelog`/`sdk-changelog` machinery entirely. Edit it by hand; it's never touched by promotion or scaffolding.
 
 ## Automation
 

diff --git a/docs/agents/fhevm-sdk-1x-migration.md b/docs/agents/fhevm-sdk-1x-migration.md
@@ -107,7 +107,7 @@ the alpha channel without a major bump.
   `decodeDelegatedForUserDecryption`, `delegateForUserDecryptionContract`, …) — mirror on-chain ACL
   Solidity event names (`Solidity-mirror` convention).
 - **`encrypt`-side `handle` terms** (`EncryptResult.handles`, etc.) — owned by PR #394, out of scope here.
-- **Token-flavoured / delegation hooks** (`useDecryptBalanceAs`, `useBatchDecryptBalancesAs`,
+- **Token-flavored / delegation hooks** (`useDecryptBalanceAs`, `useBatchDecryptBalancesAs`,
   `useDelegateDecryption`) — domain hooks, already well-named.
 - **Genuinely internal modules** — left as-is (public-API-only scope): `services/decryption-service.ts`
   incl. its internal `delegatedBatchDecryptHandlesAs` method, the relayer node/web/cleartext

diff --git a/docs/gitbook/src/SUMMARY.md b/docs/gitbook/src/SUMMARY.md
@@ -16,8 +16,10 @@
 
 ## Changelog
 
+- [Release channels](changelog/README.md)
 - [Beta (unreleased)](changelog/beta.md)
 - [3.x (current)](changelog/v3.md)
+  - [3.6.x](changelog/v3-6.md)
   - [3.5.x](changelog/v3-5.md)
   - [3.4.x](changelog/v3-4.md)
   - [3.3.x](changelog/v3-3.md)

diff --git a/docs/gitbook/src/changelog/README.md b/docs/gitbook/src/changelog/README.md
@@ -0,0 +1,30 @@
+---
+title: Release channels
+description: What stable, beta, and alpha mean for @zama-fhe/sdk, and where to find what changed in each.
+---
+
+# Release channels
+
+`@zama-fhe/sdk` and `@zama-fhe/react-sdk` publish to three npm dist-tags, one per branch:
+
+| Channel    | Install                     | Branch  | Tracks                                      |
+| ---------- | --------------------------- | ------- | ------------------------------------------- |
+| **Stable** | `npm i @zama-fhe/sdk`       | `main`  | Currently deployed mainnet/testnet protocol |
+| **Beta**   | `npm i @zama-fhe/sdk@beta`  | `beta`  | Currently deployed mainnet/testnet protocol |
+| **Alpha**  | `npm i @zama-fhe/sdk@alpha` | `alpha` | Upcoming, not-yet-deployed protocol changes |
+
+Stable and beta both target the protocol version [actually running on mainnet and testnet today](https://docs.zama.org/protocol/changelog) — beta simply carries changes that haven't had a stable release yet. **Alpha is different in kind, not just in stability.** It tracks upcoming protocol changes that aren't deployed anywhere yet, closer to a DevNet than a "more bleeding-edge beta." Code that works on alpha can depend on protocol behavior that doesn't exist on any network you can actually reach yet.
+
+{% hint style="warning" %}
+If you didn't pick `alpha` on purpose, you almost certainly want `beta` or stable instead.
+{% endhint %}
+
+## What's covered here
+
+This changelog section covers `main` and `beta` — the two lines with real deployments behind them:
+
+- [**Beta (unreleased)**](beta.md) — changes on `beta` that haven't shipped in a stable release yet.
+- [**3.x (current)**](v3.md) — plain-language release notes for the current stable major line, one page per minor version.
+- [**Legacy versions**](legacy.md) — release notes for superseded major versions.
+
+`alpha` doesn't get its own page or docs space here: its commits aren't written up until they're synced into `beta`, or reach a stable release on `main`.
diff --git a/docs/gitbook/src/changelog/beta.md b/docs/gitbook/src/changelog/beta.md
@@ -9,4 +9,4 @@ description: Unreleased changes on the prerelease (beta) line — not yet in a s
 **Unreleased.** The changes on this page are on the prerelease (`beta`) line and are **not yet available in a stable release**. They ship with the next stable release, at which point this page is retitled to that version and folded into the version list above. Treat everything here as a preview — details may still change before release.
 {% endhint %}
 
-_Nothing is staged for the next release yet. As beta builds land, run `pnpm docs:changelog` to refresh this page._
+_Nothing is staged for the next release yet._
diff --git a/docs/gitbook/src/changelog/v3-4.md b/docs/gitbook/src/changelog/v3-4.md
@@ -140,7 +140,7 @@ See [Check delegation status](../guides/delegated-decryption.md#4-check-delegati
 
 **Decrypting many encrypted values in one call now works no matter how large the batch.** The KMS gateway caps each decryption request at 2048 cleartext bits — around 32 `euint64` values, but as few as 8 if they are `euint256` — and a batch whose values summed past that cap was rejected outright. Anyone batching heavily (a server-side indexer decrypting amounts pulled from event logs, a dashboard resolving a page of balances) had to guess a safe batch size against an undocumented limit, and any guess broke as soon as a batch mixed widths, because the cost of a value depends on its FHE type: `ebool` costs 2 bits, `eaddress` 160, `euint256` 256.
 
-The SDK now sizes the requests for you. `sdk.decryption.decryptValues` still groups encrypted values by contract, then splits each group into sub-requests whose cumulative bit cost stays under the budget, so an oversized batch becomes several relayer calls instead of one rejected one. `delegatedDecryptValues`, `delegatedBatchDecryptValues`, `Token.batchDecryptBalancesAs`, and the React hooks over them (`useDecryptValues`, `useBatchDecryptBalancesAs`) share the same code path and get the same behaviour. There is nothing to configure and nothing to change: no new option, no new constant to import, and identical call signatures, results, and caching. Public decryption (`decryptPublicValues`) and the low-level `sdk.relayer.*` methods bypass this path and still send exactly the values you hand them.
+The SDK now sizes the requests for you. `sdk.decryption.decryptValues` still groups encrypted values by contract, then splits each group into sub-requests whose cumulative bit cost stays under the budget, so an oversized batch becomes several relayer calls instead of one rejected one. `delegatedDecryptValues`, `delegatedBatchDecryptValues`, `Token.batchDecryptBalancesAs`, and the React hooks over them (`useDecryptValues`, `useBatchDecryptBalancesAs`) share the same code path and get the same behavior. There is nothing to configure and nothing to change: no new option, no new constant to import, and identical call signatures, results, and caching. Public decryption (`decryptPublicValues`) and the low-level `sdk.relayer.*` methods bypass this path and still send exactly the values you hand them.
 
 ### Two-signature shield with `wrap()`