@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

package/CHANGELOG.md

@@ -5,22 +5,91 @@ All notable changes to `@tokenops/sdk` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.6.0](https://github.com/VestingLabs/tokenops-sdk/compare/v1.5.1...v1.6.0) (2026-07-28)
+## [2.0.0-alpha.2] - 2026-09-10
 
+> **Pre-release built against unaudited contracts.** Continues the `2.0.0-alpha` line. `/fhe-airdrop` in this build targets `tokenops-fhe-airdrop-v2`, frozen at commit `7175ac82f467f0f88c05aba1a4536892999b4251`, which has not completed a final security audit. Every Sepolia `fheAirdrop` address moved in this build, and breaking changes may land between any two alpha builds without a major bump (SemVer prerelease semantics). Published on the `alpha` dist-tag; `latest` stays on `1.6.0`. **For internal testing, not production value.**
+>
+> Migration guide: [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md). Support policy: [`SUPPORT.md`](SUPPORT.md).
 
-### Features
+### Changed — BREAKING
+
+- **`MerkleAirdropClient.claim` and `.getClaimAmount` submit an explicit claim identity.** The contracts gained a leading `address account`, which decoupled the leaf/accounting identity from the address the FHE input proof binds to. A relayer can now settle a leaf on a recipient's behalf.
+- **`CampaignEntry` is `{ account, boundTo, handle, inputProof, merkleProof }`.** `recipient` is removed with **no alias**, as are `MerkleLeafInput.recipient` and `LeafOfArgs.recipient`. The field meant "leaf identity and submitter" at once and those are now different addresses, so an alias would have kept compiling while meaning something else. Entries serialised under `2.0.0-alpha.1` must be re-keyed; their handles remain valid, since leaf hashing did not change.
+- **Every Sepolia `fheAirdrop` address moved.** `claim`'s breaking signature forced a fresh Merkle implementation and the deploy script redeploys the whole system, factory included. Instances created through the previous factory are unreachable from this release, and a campaign planned against it now fails `PredictionDriftError`.
+- `claimAndUnwrap` is deliberately **unchanged** and remains submitted for the caller: publishing an allocation as a plain ERC-20 transfer is the recipient's own choice, so a relayed unwrap is unrepresentable rather than rejected. A `submitter`-bound campaign therefore has no unwrap path.
+- `SenderNotAllowedToUseHandle` is gone from the Merkle ABI — that path no longer calls `FHE.fromExternal`.
+
+### Added
+
+- **Batched relayed rosters are chunked at 32 recipients**, the 2048-bit input-ciphertext limit for `euint64`. `@zama-fhe/sdk` does not enforce it client-side, so an unchunked batch would have failed inside the prover; each chunk's proof is bound to the same submitter, so claims are unaffected.
+- **`submitter?: Address` on every campaign builder** (`CampaignSubmitterOption`, accepted by `buildMerkleCampaign`, `encryptCampaignAmounts`, `planMerkleCampaign` and `rotateMerkleRoot`). Omitted keeps per-recipient binding; set binds the whole roster to one address under a single `encryptUint64Batch` call with one shared `inputProof`. The two shapes are mutually exclusive because an input proof carries exactly one `userAddress`, which is why bulk distribution needs a relayer. Shaped so a per-recipient `submitters?: Address[]` stays additive.
+- **`UnauthorizedRedirectError`** (`TOKENOPS_UNAUTHORIZED_REDIRECT`), carrying `account`, `to` and `submitter` — the relation is the error, so blaming a single argument would mislead. Thrown before the write and mapped from the contract revert. `ZeroAccount` maps to `InvalidArgumentError`.
+- **72 React hooks**, completing parity with the headless surface. Recipient, creator, campaign-owner and compliance-manager tiers on `@tokenops/sdk/fhe-airdrop/react`; the factory-admin tier (fee setters, implementation pointers, policy setters) on `@tokenops/sdk/fhe-airdrop/advanced/react`. Includes the encrypted-view mutations (`useAccessMerkleClaimAmount`, `useAccessEcdsaClaimAmount`, `useAdminGetCurrentBalance` and the disclosure family) that submit a transaction and return a handle recovered from the receipt.
+- `useMemoComplianceManagerClient`, so the compliance-manager surface has a hook path at all.
 
-* **fhe:** add operator prerequisite DX helpers (S2, TOK-75) ([#63](https://github.com/VestingLabs/tokenops-sdk/issues/63)) ([ef45c2e](https://github.com/VestingLabs/tokenops-sdk/commit/ef45c2e61529f57a2b2338c7573b466e57fbf2cf))
+### Fixed
+
+- **`useMerkleClaim` invalidated the wrong account.** It keyed `getClaimedAmount` on the transaction sender; the contract keys `claimedAmount` on the claim identity, so every relayed claim invalidated the relayer's cache entry and left the recipient's read stale.
+- **`getClaimAmount` extracted the ACL handle for the wrong grantee.** The contract grants the outstanding handle to `account`, never the caller, so a relayed preview threw `ReceiptEventNotFoundError` after its transaction had already been mined. Silent on the self-preview path.
+- The vendored local-fixture bytecode was a commit behind the vendored ABIs, so local Merkle suites deployed an implementation carrying the old `claim` selector.
+- The ABI generator now emits `@alpha` itself, instead of relying on a hand-added tag that every regeneration silently dropped.
+
+## [1.6.0](https://github.com/VestingLabs/tokenops-sdk/compare/v1.5.1...v1.6.0) (2026-07-28)
+
+### Features
 
+- **fhe:** add operator prerequisite DX helpers (S2, TOK-75) ([#63](https://github.com/VestingLabs/tokenops-sdk/issues/63)) ([ef45c2e](https://github.com/VestingLabs/tokenops-sdk/commit/ef45c2e61529f57a2b2338c7573b466e57fbf2cf))
 
 ### Bug Fixes
 
-* **airdrop:** stop preflightCreateAirdrop throwing on a non-ERC7984 token (TOK-436) ([b650324](https://github.com/VestingLabs/tokenops-sdk/commit/b6503243cb430fe224913fbbb39251586a4d4925))
-* correct operator-deadline guidance in SECURITY.md, record advisory rationale ([b09273d](https://github.com/VestingLabs/tokenops-sdk/commit/b09273d7d911a4dcfdfe8e2ae7f4e3a24c2130e8))
-* **fhe-vesting:** point Sepolia factory at the redeployed address ([0888404](https://github.com/VestingLabs/tokenops-sdk/commit/08884040987d0ebb4326d1fb80a2c2d630a6e3a6))
-* **vesting:** stop preflightCreateVesting throwing on a non-ERC7984 token ([dfbc795](https://github.com/VestingLabs/tokenops-sdk/commit/dfbc795fa7f0fd2aee9e1abfb711e82bca22ec4c))
+- **airdrop:** stop preflightCreateAirdrop throwing on a non-ERC7984 token (TOK-436) ([b650324](https://github.com/VestingLabs/tokenops-sdk/commit/b6503243cb430fe224913fbbb39251586a4d4925))
+- correct operator-deadline guidance in SECURITY.md, record advisory rationale ([b09273d](https://github.com/VestingLabs/tokenops-sdk/commit/b09273d7d911a4dcfdfe8e2ae7f4e3a24c2130e8))
+- **fhe-vesting:** point Sepolia factory at the redeployed address ([0888404](https://github.com/VestingLabs/tokenops-sdk/commit/08884040987d0ebb4326d1fb80a2c2d630a6e3a6))
+- **vesting:** stop preflightCreateVesting throwing on a non-ERC7984 token ([dfbc795](https://github.com/VestingLabs/tokenops-sdk/commit/dfbc795fa7f0fd2aee9e1abfb711e82bca22ec4c))
+
+## [2.0.0-alpha.1] - 2026-09-07
+
+> **Pre-release built against unaudited contracts.** `/fhe-airdrop` in this build targets `tokenops-fhe-airdrop-v2`, frozen at commit `8e5b144bdbcdf35b9f36b62f5257d795bf954e8e`, which has not completed a final security audit. Deployed addresses may change before `2.0.0` GA, and breaking changes may land between any two alpha builds without a major bump (SemVer prerelease semantics). Published on the `alpha` dist-tag; `latest` stays on `1.6.0`. **For internal testing, not production value.**
+>
+> Migration guide: [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md). Support policy: [`SUPPORT.md`](SUPPORT.md).
+
+### Changed — BREAKING
+
+- **`/fhe-airdrop` now targets confidential airdrop v2.** The subpath name is unchanged; everything behind it is new. v1 and v2 are different contract systems, not two versions of one — there is no in-place upgrade path for a deployed v1 airdrop. `AIRDROP_CONTRACTS_COMMIT` pins the contract commit the vendored ABIs were generated from.
+- **`DEPLOYED_ADDRESSES.fheAirdrop` reshaped from one key to four.** Previously a single `confidentialAirdropFactory`; now `{ airdropFactory, ecdsaImplementation, merkleImplementation, complianceManagerImplementation }`. Code reading `DEPLOYED_ADDRESSES.fheAirdrop[chainId]` must read `.airdropFactory[chainId]`. Note this member is `@public`, not `@alpha` — it is the one breaking change outside the alpha-tagged surface.
+- **The EIP-712 claim typehash gained two fields.** A v1 signature will not verify against a v2 instance, or vice versa. Re-issue authorizations from the v2 signing surface; do not port stored signatures.
+- **Claim entrypoints take an explicit `signer`.** The claiming account is no longer inferred from the wallet client, because a Merkle leaf commits the _claimant_ — inferring it silently produced proofs bound to the wrong address.
+- **Role-constant getters renamed to SCREAMING_SNAKE** across all five clients (`DEFAULT_ADMIN_ROLE`, `PAUSER_ROLE`, `MERKLE_ADMIN_ROLE`, `DISCLOSURE_ADMIN_ROLE`, `DELEGATION_ADMIN_ROLE`, `COMPLIANCE_WIRING_ROLE`, `FEE_MANAGER_ROLE`, `FEE_COLLECTOR_ROLE`, `IMPL_MANAGER_ROLE`, `RESCUER_ROLE`). They are contract function names and now read as such.
+
+### Removed — BREAKING
+
+- **The entire v1 `/fhe-airdrop` module** — clients, types, errors, ABIs, advanced surface and examples. There is no deprecation window on the v1 _shape_: it is deleted, not aliased. `1.x` remains fully supported for consumers not ready to migrate; see [`SUPPORT.md`](SUPPORT.md).
+- **44 airdrop-specific React hooks** — 43 from `@tokenops/sdk/fhe-airdrop/react`, and `usePredictAirdropAddress` from `@tokenops/sdk/fhe-airdrop/advanced/react`. The v2 surface is 23 hooks (21 + 2 advanced); the reduction is deliberate, since several v1 hooks wrapped a single contract read with no added value.
+- **`useIsOperator` and `useEnsureOperator` are NOT removed.** They live at `@tokenops/sdk/fhe/react` and are unaffected. If you imported them _via_ `@tokenops/sdk/fhe-airdrop/react`, change the import path; the hooks themselves are unchanged.
+
+### Added — confidential airdrop v2
+
+- **Split clients per variant.** `EcdsaAirdropClient` (signature-authorized claims) and `MerkleAirdropClient` (proof-authorized claims) over a shared `AirdropBaseClient`, plus `ConfidentialAirdropFactoryClient` for creation, funding, fee administration and address prediction.
+- **Merkle campaign construction, in two independently usable stages.** `encryptCampaignAmounts()` is the relayer-only half — one request per recipient, no tree. `buildMerkleTree()` is the pure half: no relayer, no chain access, deterministic, and generic over its leaf type (`L extends MerkleLeafInput`), so an `inputProof` or any caller-defined field rides through onto the returned entry at the same index with no re-correlation. `buildMerkleCampaign()` is unchanged in signature and behaviour and is now the composition of the two. This is what lets a consumer who already holds encrypted handles build a claimable campaign without re-encrypting — necessary because FHE encryption is randomised, so re-encrypting produces a tree committing to handles nobody holds.
+- **`planMerkleCampaign()`** for the immutable-root path, which is otherwise circular: the root must exist before creation, yet every ciphertext binds to the instance address creation has not produced. It uses the factory's CREATE2 prediction and brackets that prediction with two init-code-hash reads, throwing `PredictionDriftError` rather than returning a plan bound to a stale address.
+- **`rotateMerkleRoot()`** — re-encrypt and republish as a top-up. A claim pays `total − min(total, alreadyDelivered)`, so `recipients` must carry each account's new _cumulative_ total, never an increment.
+- **`ComplianceManagerClient`** for the compliance clone: wiring, party disclosure, and role administration.
+- **Instance role splitting and full role administration** — `planInstanceRoleSplit()` and `grantInstanceRoles()`, which confirms each step's receipt before advancing so a dependent revoke cannot be simulated against state that lacks the preceding grant.
+- **Guardrails and preflights** — typed, pre-transaction failures for salt collisions, wrapper assumptions and window state, instead of an opaque revert.
+- **`deploymentMode()`** on `AirdropBaseClient`, reading the ERC-1967 implementation slot. Necessary because `proxiableUUID()` cannot discriminate a clone from a UUPS proxy: OpenZeppelin's `notDelegated` makes it revert through _any_ proxy.
+- **`upgradeToAndCall()`** on `AirdropBaseClient`, and **`eip712Domain()`** on `EcdsaAirdropClient` (EIP-5267 domain discovery).
+- **23 React hooks** across `/fhe-airdrop/react` and `/fhe-airdrop/advanced/react`, wagmi + TanStack Query, sharing the `"tokenops-sdk"` query-key prefix used by every sibling subpath.
+- **Typed error mapping** from v2 revert selectors, and encrypted-view reads that extract handles from the executed receipt's ACL `Allowed` event rather than from `simulateContract()` — a simulated handle carries no ACL and fails later, at the decrypt, far from its cause.
+- **Docs and examples** — [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md) with measured live-relayer throughput, per-recipient storage sizing, and a "bring your own handles" guide; [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md); a README compatibility matrix; and three runnable examples (`fhe-airdrop-merkle-campaign.ts`, `fhe-airdrop-external-handles.ts`, `fhe-airdrop-ecdsa-claim.ts`).
+
+### Fixed
+
+- **`release.yml` no longer defaults a prerelease onto the `latest` dist-tag.** The npm dist-tag is derived from the package version (`alpha` / `beta` / `rc` / `next` / `latest`), and the `workflow_dispatch` override input now defaults to blank so it cannot mask that derivation.
+- **`useAirdropPause` invalidates the `window` query as well as `paused`.** `isClaimWindowActive()` ANDs the pause flag with the window check, so mounted `useAirdropWindow` consumers previously kept a stale `isActive` after either pause transition.
+
+---
 
-## [Unreleased]
+_The sections below were developed against `1.x` and had not yet shipped when `2.0.0-alpha.1` was cut. They are unrelated to the airdrop rewrite, and none of them are breaking._
 
 ### Added — operator prerequisite DX helpers (TOK-75)
 

package/CONTRIBUTING.md

@@ -108,6 +108,8 @@ Pattern: `<type>(<scope>): <imperative description>`. Scope is optional; use the
 
 ## Claude Code Setup
 
-The `claude-setup/` directory contains a `settings.json` and skill definitions that configure Claude Code for this repository. Copy or symlink them to your local `.claude/` to get the same hooks (auto-typecheck, auto-lint on Write/Edit) and skills (jsdoc, tanstack-best-practices) that CI enforces.
+The `claude-setup/` directory contains a `settings.json` and skill definitions (jsdoc, tanstack-best-practices, fhevm-security) that configure Claude Code for this repository. Run `pnpm setup:claude` to install them into your local `.claude/`. It copies on a first run and merges on later ones, so re-running after a pull picks up repo changes without discarding your own settings.
 
-See the `claude-setup/` directory and Zama's [Claude Code plugin model](https://docs.claude.ai/en/docs/claude-code) for details.
+`.claude/` is gitignored, so adoption is opt-in and nothing you put there is shared. `.codex/` and `.agents/` are ignored on the same basis - this repo does not assume which agent you use.
+
+See the `claude-setup/` directory and Anthropic's [Claude Code plugin model](https://docs.claude.ai/en/docs/claude-code) for details.

package/README.md

@@ -21,27 +21,43 @@ Node `>= 22` is required (constraint from `@zama-fhe/sdk`).
 
 All subpaths are independently tree-shakeable. The `/react` paths keep React deps out of the server bundle.
 
-| Subpath                                    | Status                              | Description                                                                                               |
-| ------------------------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `@tokenops/sdk`                            | stable                              | Root re-exports (version, core error types)                                                               |
-| `@tokenops/sdk/telemetry`                  | stable                              | Telemetry sink adapters (`NoopTelemetry`, `ConsoleTelemetry`, `TokenOpsTelemetry`)                        |
-| `@tokenops/sdk/fhe`                        | stable                              | FHE utility helpers (ratio scaling, encrypted-input types, operator helpers)                              |
-| `@tokenops/sdk/fhe/react`                  | stable                              | React hooks for shared FHE utilities                                                                      |
-| `@tokenops/sdk/fhe-vesting`                | factory live on Sepolia             | Confidential vesting (LibClone + packed immutable args)                                                   |
-| `@tokenops/sdk/fhe-vesting/react`          | stable                              | React/wagmi hooks for confidential vesting                                                                |
-| `@tokenops/sdk/fhe-vesting/advanced`       | stable                              | Pre-mine address prediction (`predictManagerAddress`)                                                     |
-| `@tokenops/sdk/fhe-vesting/advanced/react` | stable                              | React hooks for advanced vesting flows                                                                    |
-| `@tokenops/sdk/fhe-airdrop`                | factory live on Sepolia             | ConfidentialAirdrop (EIP-712 gated confidential claims)                                                   |
-| `@tokenops/sdk/fhe-airdrop/react`          | stable                              | React/wagmi hooks for confidential airdrops                                                               |
-| `@tokenops/sdk/fhe-airdrop/advanced`       | stable                              | Pre-mine address prediction (`predictAirdropAddress`)                                                     |
-| `@tokenops/sdk/fhe-airdrop/advanced/react` | stable                              | React hooks for advanced airdrop flows                                                                    |
-| `@tokenops/sdk/fhe-disperse`               | singleton live on mainnet + Sepolia | DisperseConfidential (singleton + per-user wallet-pair clones)                                            |
-| `@tokenops/sdk/fhe-disperse/react`         | stable                              | React/wagmi hooks for confidential disperse                                                               |
-| `@tokenops/sdk/testnet-faucet`             | token pair live on Sepolia          | Testnet faucet for the TokenOps test-token pair — TTT (plain ERC-20) + CTTT (ERC-7984 wrapper); open mint |
-| `@tokenops/sdk/testnet-faucet/react`       | stable                              | React/wagmi hooks for the testnet faucet                                                                  |
+| Subpath                                    | Status                                                        | Description                                                                                                                                              |
+| ------------------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tokenops/sdk`                            | stable                                                        | Root re-exports (version, core error types)                                                                                                              |
+| `@tokenops/sdk/telemetry`                  | stable                                                        | Telemetry sink adapters (`NoopTelemetry`, `ConsoleTelemetry`, `TokenOpsTelemetry`)                                                                       |
+| `@tokenops/sdk/fhe`                        | stable                                                        | FHE utility helpers (ratio scaling, encrypted-input types, operator helpers)                                                                             |
+| `@tokenops/sdk/fhe/react`                  | stable                                                        | React hooks for shared FHE utilities                                                                                                                     |
+| `@tokenops/sdk/fhe-vesting`                | factory live on Sepolia                                       | Confidential vesting (LibClone + packed immutable args)                                                                                                  |
+| `@tokenops/sdk/fhe-vesting/react`          | stable                                                        | React/wagmi hooks for confidential vesting                                                                                                               |
+| `@tokenops/sdk/fhe-vesting/advanced`       | stable                                                        | Pre-mine address prediction (`predictManagerAddress`)                                                                                                    |
+| `@tokenops/sdk/fhe-vesting/advanced/react` | stable                                                        | React hooks for advanced vesting flows                                                                                                                   |
+| `@tokenops/sdk/fhe-airdrop`                | **v2, unaudited** — `alpha` dist-tag, factory live on Sepolia | ECDSA + Merkle confidential airdrop campaigns — see [Compatibility](#compatibility)                                                                      |
+| `@tokenops/sdk/fhe-airdrop/react`          | **v2, unaudited**                                             | React/wagmi hooks for recipients, campaign creators, campaign owners and the compliance manager                                                          |
+| `@tokenops/sdk/fhe-airdrop/advanced`       | **v2, unaudited**                                             | Prediction-freshness / salt-availability guards for CREATE2 address prediction (prediction itself is on the headline `ConfidentialAirdropFactoryClient`) |
+| `@tokenops/sdk/fhe-airdrop/advanced/react` | **v2, unaudited**                                             | Address-prediction hooks plus the factory-admin tier (fee setters, implementation pointers, policy setters)                                              |
+| `@tokenops/sdk/fhe-disperse`               | singleton live on mainnet + Sepolia                           | DisperseConfidential (singleton + per-user wallet-pair clones)                                                                                           |
+| `@tokenops/sdk/fhe-disperse/react`         | stable                                                        | React/wagmi hooks for confidential disperse                                                                                                              |
+| `@tokenops/sdk/testnet-faucet`             | token pair live on Sepolia                                    | Testnet faucet for the TokenOps test-token pair — TTT (plain ERC-20) + CTTT (ERC-7984 wrapper); open mint                                                |
+| `@tokenops/sdk/testnet-faucet/react`       | stable                                                        | React/wagmi hooks for the testnet faucet                                                                                                                 |
 
 The canonical exports map is in [`package.json`](https://github.com/VestingLabs/tokenops-sdk/blob/main/package.json) under `"exports"`.
 
+## Compatibility
+
+Which contract generation a given SDK version talks to, and where that generation is deployed:
+
+| SDK             | Airdrop contracts  | Contract commit | Chains  |
+| --------------- | ------------------ | --------------- | ------- |
+| `2.0.0-alpha.x` | v2 (**unaudited**) | `7175ac8`       | Sepolia |
+| `1.x`           | v1                 | n/a             | Sepolia |
+
+`2.x`'s `/fhe-airdrop` is a full replacement of v1, not an extension — see
+[`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md) for the symbol-by-symbol
+delta and [`SUPPORT.md`](SUPPORT.md) for how long `1.x` keeps receiving fixes. The v1 Sepolia
+factory (`0xbE6A3B78B36684fFee48De77d47Bc3393F5Acd4c`) stays live on-chain; `2.x` simply stops
+addressing it. `/fhe-vesting` and `/fhe-disperse` are unaffected by this table — both are on their
+usual SemVer track regardless of which `/fhe-airdrop` line you install.
+
 ## Quickstart — confidential vesting
 
 ```ts
@@ -268,17 +284,22 @@ See [Confidential Vesting — React hooks on docs.tokenops.xyz](https://docs.tok
 
 ## Quickstart — confidential airdrop
 
+> **v2, unaudited.** `/fhe-airdrop` targets `tokenops-fhe-airdrop-v2` (`7175ac8`, Sepolia only, `alpha` dist-tag) — see [Compatibility](#compatibility). Migrating from `1.x`? See [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md).
+
+Two claim-authorisation variants share one factory: **ECDSA** (an off-chain signature from a `SIGNER_ROLE` holder) and **Merkle** (inclusion in a published tree). The example below is ECDSA — see [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md#quickstart--merkle-campaign) for the Merkle flow.
+
 ```ts
-import { createPublicClient, createWalletClient, http } from "viem";
+import { createPublicClient, createWalletClient, http, zeroAddress } from "viem";
 import { sepolia } from "viem/chains";
 import { privateKeyToAccount } from "viem/accounts";
 import { RelayerNode, SepoliaConfig } from "@zama-fhe/sdk/node";
 import {
   createConfidentialAirdropFactoryClient,
-  createConfidentialAirdropClient,
+  createEcdsaAirdropClient,
   encryptUint64,
   signClaimAuthorization,
 } from "@tokenops/sdk/fhe-airdrop";
+import { setOperator } from "@tokenops/sdk/fhe";
 
 const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
 const rpcUrl = process.env.RPC_URL!;
@@ -291,80 +312,98 @@ const encryptor = new RelayerNode({
 });
 
 // Factory address resolves automatically from DEPLOYED_ADDRESSES on Sepolia.
-const factory = createConfidentialAirdropFactoryClient({
-  publicClient,
-  walletClient,
-  encryptor,
-});
+const factory = createConfidentialAirdropFactoryClient({ publicClient, walletClient, encryptor });
 
 const now = Math.floor(Date.now() / 1000);
 const userSalt = "0x0000000000000000000000000000000000000000000000000000000000000001" as const;
 const token = process.env.TOKEN as `0x${string}`;
-const params = {
-  token,
-  startTimestamp: now + 60,
-  endTimestamp: now + 30 * 86400,
-  canExtendClaimWindow: false,
-  admin: account.address,
-};
-
-// Deploy and read the clone address from the ConfidentialAirdropCreated event.
-// (predictAirdropAddress also works — airdrop immutable args don't pack
-// block.number, so the predicted address is stable across blocks.)
-const { airdrop: airdropAddress } = await factory.createConfidentialAirdropAndGetAddress({
-  params,
+
+// Create. There is no `admin` field — the factory injects `admin = msg.sender`.
+// `dedupMode` is required and cannot be read back from the chain later; record
+// it yourself alongside the deployed address.
+const { airdrop: airdropAddress } = await factory.createEcdsaAirdrop({
+  params: {
+    common: {
+      token,
+      startTime: now + 60,
+      endTime: now + 30 * 86400,
+      canExtendClaimWindow: false,
+      unwrappable: false,
+      complianceAdmin: zeroAddress, // zero => msg.sender
+    },
+    signer: account.address, // SIGNER_ROLE holder authorising claims
+    dedupMode: "perAddress",
+  },
+  mode: "clone",
   userSalt,
 });
 
-// Admin: issue a signed claim authorization for a recipient. Bind the input
-// proof to the RECIPIENT — Zama proofs commit to (contractAddress, userAddress)
-// at encrypt time, and `FHE.fromExternal` on-chain rejects any other binding.
+// Fund. Requires the factory to hold ERC-7984 operator approval first — the
+// FACTORY calls FHE.fromExternal on the pool amount, so the operator grant
+// and the encryption both bind to the factory, not to the airdrop instance.
+await setOperator({ publicClient, walletClient, token, spender: factory.address });
+await factory.fundAirdrop({ airdrop: airdropAddress, amount: 1_000_000n });
+
+// Admin: sign a claim authorization for a recipient. Bind the input proof to
+// the RECIPIENT and to the AIRDROP INSTANCE — Zama proofs commit to
+// (contractAddress, userAddress) at encrypt time, and a claim binds to
+// (instance, claimant), not (factory, funder). Get the pair wrong and
+// `FHE.fromExternal` reverts; it does not silently decrypt to zero.
 // amount is raw token units; ERC-7984 uses 6 decimals, so 1_000_000n = 1 token.
 const recipient = "0xRecipientAddress" as `0x${string}`;
-const encrypted = await encryptUint64({
+const encryptedInput = await encryptUint64({
   encryptor,
   contractAddress: airdropAddress,
   userAddress: recipient,
   value: 1_000_000n,
 });
+const dedupId = "0x0000000000000000000000000000000000000000000000000000000000000001" as const;
+const deadline = BigInt(now + 3600); // signature expires in 1 hour
 const signature = await signClaimAuthorization({
   walletClient,
-  airdropAddress,
+  airdrop: airdropAddress,
+  chainId: sepolia.id,
   recipient,
-  encryptedAmountHandle: encrypted.handle,
+  encryptedAmountHandle: encryptedInput.handle,
+  dedupId,
+  deadline,
 });
-// Deliver { encryptedInput: encrypted, signature } to the recipient via API / email / etc.
+// Deliver { encryptedInput, dedupId, deadline, signer: account.address, signature }
+// to the recipient via API / email / etc.
 
 // User: claim tokens. The SDK submits the admin-issued pair verbatim — no
-// re-encryption. (GAS_FEE() is fetched and attached as msg.value automatically.)
-const airdrop = createConfidentialAirdropClient({
+// re-encryption. The exact-equality gas fee (0 on the live Sepolia deployment
+// today) is fetched fresh and attached as msg.value automatically.
+const airdrop = createEcdsaAirdropClient({
   publicClient,
   walletClient,
   address: airdropAddress,
+  dedupMode: "perAddress", // must match what was passed at create — no getter exists
 });
-await airdrop.claim({ signature, encryptedInput: encrypted });
+await airdrop.claim({ encryptedInput, dedupId, deadline, signer: account.address, signature });
 ```
 
-See [Confidential Airdrop on docs.tokenops.xyz](https://docs.tokenops.xyz/sdk/fhe-airdrop) for the full API reference and claim flow diagram.
+See [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md) for the full API reference, the Merkle campaign flow, guardrails, and the unaudited-contracts warning.
 
 ### Quickstart — confidential airdrop (React hooks)
 
-Uses `@tokenops/sdk/fhe-airdrop/react`. Requires `wagmi`, `@tanstack/react-query`, and `@zama-fhe/react-sdk` as additional peer deps.
+Uses `@tokenops/sdk/fhe-airdrop/react`. Requires `wagmi`, `@tanstack/react-query`, and `@zama-fhe/react-sdk` as additional peer deps. `signClaimAuthorization` is re-exported as a plain function (not a mutation hook) — signing is a synchronous `walletClient.signTypedData` call with no chain state to invalidate.
 
 ```tsx
-import { useQueryClient } from "@tanstack/react-query";
+import { useWalletClient } from "wagmi";
 import { useZamaSDK } from "@zama-fhe/react-sdk";
 import {
-  useCreateConfidentialAirdropAndGetAddress,
-  useSignClaimAuthorization,
-  useClaim,
+  useCreateEcdsaAirdrop,
+  useFundAirdrop,
+  useEcdsaClaim,
   encryptUint64,
+  signClaimAuthorization,
 } from "@tokenops/sdk/fhe-airdrop/react";
 
 // Wrap your app in wagmi's <WagmiProvider> + <QueryClientProvider> +
 // @zama-fhe/react-sdk's <ZamaProvider> before rendering these components.
 
-// --- Admin: deploy a campaign and issue a claim authorization ---
+// --- Admin: deploy a campaign, fund it, and issue a claim authorization ---
 
 function AdminPanel({
   token,
@@ -379,58 +418,79 @@ function AdminPanel({
     airdrop: `0x${string}`,
     payload: {
       encryptedInput: { handle: `0x${string}`; inputProof: `0x${string}` };
+      dedupId: `0x${string}`;
+      deadline: bigint;
+      signer: `0x${string}`;
       signature: `0x${string}`;
     },
   ) => void;
 }) {
-  const queryClient = useQueryClient();
   const zamaSDK = useZamaSDK();
+  const { data: walletClient } = useWalletClient();
 
   // Factory address resolves automatically from DEPLOYED_ADDRESSES on Sepolia.
-  const create = useCreateConfidentialAirdropAndGetAddress();
-
-  // walletClient is pulled from wagmi's useWalletClient() internally.
-  const sign = useSignClaimAuthorization();
+  // `useCreateEcdsaAirdrop` invalidates the factory registry reads for you.
+  const create = useCreateEcdsaAirdrop({ encryptor: () => zamaSDK.relayer });
+  const fund = useFundAirdrop({ encryptor: () => zamaSDK.relayer });
 
   const now = Math.floor(Date.now() / 1000);
 
   async function handleLaunch() {
     const { airdrop } = await create.mutateAsync({
       params: {
-        token,
-        startTimestamp: now + 60,
-        endTimestamp: now + 30 * 86400,
-        canExtendClaimWindow: false,
-        admin: "0xYourAdminAddress" as `0x${string}`,
+        common: {
+          token,
+          startTime: now + 60,
+          endTime: now + 30 * 86400,
+          canExtendClaimWindow: false,
+          unwrappable: false,
+          complianceAdmin: "0x0000000000000000000000000000000000000000",
+        },
+        signer: "0xYourSignerAddress" as `0x${string}`,
+        dedupMode: "perAddress", // record this — no on-chain getter exists later
       },
+      mode: "clone",
       userSalt:
         "0x0000000000000000000000000000000000000000000000000000000000000001" as `0x${string}`,
     });
 
-    queryClient.invalidateQueries({ queryKey: ["tokenops-sdk", "fhe-airdrop"] });
+    await fund.mutateAsync({ airdrop, amount });
 
-    // Encrypt the allocation for the recipient.
-    const encrypted = await encryptUint64({
+    // Encrypt bound to (airdrop instance, recipient) — not the factory.
+    const encryptedInput = await encryptUint64({
       encryptor: zamaSDK.relayer,
       contractAddress: airdrop,
       userAddress: recipient,
       value: amount,
     });
 
-    // Sign the EIP-712 claim authorization.
-    const signature = await sign.mutateAsync({
-      airdropAddress: airdrop,
+    const dedupId = "0x0000000000000000000000000000000000000000000000000000000000000001" as const;
+    const deadline = BigInt(now + 3600);
+
+    // Sign is a plain async function here — walletClient comes from wagmi.
+    const signature = await signClaimAuthorization({
+      walletClient: walletClient!,
+      airdrop,
+      chainId: walletClient!.chain.id,
       recipient,
-      encryptedAmountHandle: encrypted.handle,
+      encryptedAmountHandle: encryptedInput.handle,
+      dedupId,
+      deadline,
     });
 
-    // Deliver { encryptedInput: encrypted, signature } to the recipient via your API / email.
-    onCampaignReady(airdrop, { encryptedInput: encrypted, signature });
+    // Deliver this payload to the recipient via your API / email.
+    onCampaignReady(airdrop, {
+      encryptedInput,
+      dedupId,
+      deadline,
+      signer: "0xYourSignerAddress" as `0x${string}`,
+      signature,
+    });
   }
 
   return (
-    <button onClick={handleLaunch} disabled={create.isPending || sign.isPending}>
-      {create.isPending ? "Deploying…" : sign.isPending ? "Signing…" : "Launch airdrop"}
+    <button onClick={handleLaunch} disabled={create.isPending || fund.isPending}>
+      {create.isPending ? "Deploying…" : fund.isPending ? "Funding…" : "Launch airdrop"}
     </button>
   );
 }
@@ -442,33 +502,29 @@ function RecipientClaim({
   claimPayload,
 }: {
   airdropAddress: `0x${string}`;
-  // The admin-issued payload — encryption bound to this recipient, handle
-  // committed to by the signature. The recipient submits it verbatim.
+  // The admin-issued payload — encryption bound to this recipient and this
+  // instance, handle committed to by the signature. Submitted verbatim.
   claimPayload: {
     encryptedInput: { handle: `0x${string}`; inputProof: `0x${string}` };
+    dedupId: `0x${string}`;
+    deadline: bigint;
+    signer: `0x${string}`;
     signature: `0x${string}`;
   };
 }) {
-  const queryClient = useQueryClient();
-  const claim = useClaim({ address: airdropAddress });
+  // `dedupMode` must match what the campaign was created with — the contract
+  // has no on-chain getter, so a consumer must already know it.
+  const claim = useEcdsaClaim({ address: airdropAddress, dedupMode: "perAddress" });
 
   return (
-    <button
-      onClick={() =>
-        claim.mutate(claimPayload, {
-          onSuccess: () =>
-            queryClient.invalidateQueries({ queryKey: ["tokenops-sdk", "fhe-airdrop"] }),
-        })
-      }
-      disabled={claim.isPending}
-    >
+    <button onClick={() => claim.mutate(claimPayload)} disabled={claim.isPending}>
       {claim.isPending ? "Claiming…" : "Claim tokens"}
     </button>
   );
 }
 ```
 
-See [Confidential Airdrop — React hooks on docs.tokenops.xyz](https://docs.tokenops.xyz/sdk/fhe-airdrop#react-hooks) for the full hook catalogue, encryptor wiring, address overrides, and query-key reference.
+See [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md) for the full hook catalogue across both import paths (`/fhe-airdrop/react` for recipients, creators, owners and compliance; `/fhe-airdrop/advanced/react` for prediction and factory admin), encryptor wiring, address overrides, and query-key reference.
 
 ## Quickstart — confidential disperse
 

package/SUPPORT.md

@@ -0,0 +1,47 @@
+# Support policy
+
+This document states what level of support each `@tokenops/sdk` release line receives. It exists
+because `2.0.0` is a major version driven by a full replacement of the `/fhe-airdrop` module
+(v1 deleted, v2 takes the subpath) — see
+[`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md) for the technical
+delta.
+
+## `1.x`
+
+- **Critical security and correctness fixes only, for 90 days after `2.0.0` reaches `latest`
+  (GA).** After that window, `1.x` receives no further fixes of any kind.
+- **No feature work on `1.x` from the day `release/v2` was opened (2026-09-05).** Every new
+  capability lands on the `2.x` line only, starting from that date.
+- `1.x` is what you stay on if you depend on the v1 `/fhe-airdrop` shape and are not ready to
+  migrate — nothing about `1.x` breaks or is withdrawn by `2.0.0` shipping. Consumers that do not
+  import `/fhe-airdrop` are unaffected by the replacement and can move on their own schedule.
+- The v1 contracts stay live on-chain throughout and beyond this window. This policy governs the
+  SDK's code, not contract uptime.
+
+## `2.x`
+
+- `2.0.0-alpha.x` and `2.0.0-beta.x` are pre-release channels for the airdrop v2 rewrite. No
+  stability promise between alpha builds; breaking changes may land between any two alpha
+  versions without a major bump, per SemVer's prerelease semantics. See the compatibility matrix
+  in [`README.md`](README.md#compatibility) for which contract commit each build speaks to.
+- `2.0.0` (GA, `latest` dist-tag) ships once `tokenops-fhe-airdrop-v2` is audited and its
+  addresses are final. From GA onward, `2.x` follows the SDK's normal SemVer + Conventional
+  Commits support model — the same one `1.x` operated under before this document existed.
+
+## Why `npm deprecate` is not used on the `1.x` range
+
+`npm deprecate` operates on the package as a whole, scoped by version range — it has no concept
+of "deprecate this subpath only." Running it against the `1.x` range would print a deprecation
+warning on every install of `@tokenops/sdk@1.x`, including installs that use only `/fhe-vesting`
+or `/fhe-disperse` — modules that are not being replaced and are not affected by this migration.
+A package-wide deprecation notice would misrepresent the status of code that isn't changing. The
+`1.x` line is fully supported per the window above; only the `/fhe-airdrop` _shape_ is superseded,
+and that message belongs in the migration guide and the module README, not in an npm-wide flag
+that cannot be scoped to one subpath.
+
+## Getting help
+
+- Migrating off v1 `/fhe-airdrop`: [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md).
+- Module docs (v2, unaudited): [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md).
+- Security issues: see [`SECURITY.md`](SECURITY.md).
+- Everything else: open an issue against `VestingLabs/tokenops-sdk`.