@tokenops/sdk 1.5.1 → 2.0.0-alpha.1

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 confidential airdrops                                                                                                              |
+| `@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**                                             | `usePredictEcdsaAirdropAddress` / `usePredictMerkleAirdropAddress`                                                                                       |
+| `@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**) | `8e5b144`       | 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` (`8e5b144`, 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 (including the Merkle-side `useCreateMerkleAirdrop` / `useMerkleClaim` / `useSetMerkleRoot`), encryptor wiring, address overrides, and query-key reference.
 
 ## Quickstart — confidential disperse
 

package/SECURITY.md

@@ -46,7 +46,7 @@ The following are **not in scope** for this SDK's security policy:
 
 **Encryptor binding is address-scoped.** Input proofs from `encryptUint64` are bound to `(contractAddress, userAddress)` — they cannot be replayed against a different contract or submitted by a different sender. Do not reuse proofs across different contract deployments.
 
-**Operator approvals (`setOperator`) have a deadline.** Set the deadline appropriately for your use case. The SDK exports `ERC_7984_OPERATOR_MAX_DEADLINE` for production flows and warns when the deadline is in the past.
+**Operator approvals (`setOperator`) have a deadline — scope it in production.** The SDK exports `ERC7984_OPERATOR_MAX_DEADLINE` (the `uint48` max, effectively forever) as the default when a consumer doesn't care about expiry — appropriate for local-chain dev loops and test fixtures, not for production. For production flows, scope the deadline to the expected operation window (e.g. `Date.now()/1000 + 3600`) and call `revokeOperator` when the authorization is no longer needed. The SDK validates that the deadline is within the `uint48` range but does **not** warn when a supplied deadline is already in the past — a past-but-otherwise-valid deadline is accepted silently.
 
 ## Supported Versions
 
@@ -54,6 +54,12 @@ The following are **not in scope** for this SDK's security policy:
 | ------- | ------------------ |
 | 1.x     | :white_check_mark: |
 
+## Known Advisories
+
+Open Dependabot alerts against this repo are all **transitive** — the SDK's only runtime dependency is `abitype`. The remaining alerts (e.g. `axios`, reached via `wagmi` → `@wagmi/connectors` → `@base-org/account` → `@coinbase/cdp-sdk`; and `hono`, reached via `porto`) come in through the `wagmi` **peer** dependency tree, not through anything this SDK ships at runtime.
+
+This repo's `pnpm.overrides` pin those transitive versions for our own lockfile, which fixes CI and our security dashboard — but that pin has no effect for consumers, who resolve their own `wagmi`/peer dependency tree at install time. Consumers running `npm audit` (or similar) against their own install may still see these advisories; that reflects their resolved tree, not a vulnerability this SDK ships. Real remediation is upstream, in `wagmi`'s own dependency graph.
+
 ## Acknowledgments
 
 We will acknowledge reporters in the relevant release notes unless they request anonymity.

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`.

package/dist/{chunk-YQIBBEFJ.js → chunk-335Z2W67.js}

@@ -1,4 +1,4 @@
-import { ConfidentialVestingFactoryClient, confidentialVestingFactoryAbi } from './chunk-OXTLPTO3.js';
+import { ConfidentialVestingFactoryClient, confidentialVestingFactoryAbi } from './chunk-EAJ7SYHE.js';
 
 // src/fhe-vesting/advanced/factory-advanced.ts
 var ConfidentialVestingFactoryAdvancedClient = class extends ConfidentialVestingFactoryClient {

package/dist/{chunk-2NCLOQ56.cjs → chunk-3QHNYEQD.cjs}

@@ -1,6 +1,8 @@
 'use strict';
 
+var chunk66IHPTOK_cjs = require('./chunk-66IHPTOK.cjs');
 var chunk67OV5CX2_cjs = require('./chunk-67OV5CX2.cjs');
+var viem = require('viem');
 
 // src/fhe/scale-ratio.ts
 var FHE_SPLIT_DENOMINATOR = 90090000n;
@@ -133,7 +135,82 @@ function toIntegerBigInt(value, method, argument) {
   }
   return BigInt(value);
 }
+function resolveEncryptor(source) {
+  if (source === void 0) return void 0;
+  return typeof source === "function" ? source() : source;
+}
+var MAX_UINT642 = (1n << 64n) - 1n;
+function assertUint64(value, label) {
+  if (value < 0n || value > MAX_UINT642) {
+    throw new chunk67OV5CX2_cjs.InvalidArgumentError({
+      method: "encryptUint64",
+      argument: label,
+      reason: `does not fit in uint64 (0..2^64-1)`,
+      value
+    });
+  }
+}
+async function encryptUint64({
+  encryptor,
+  contractAddress,
+  userAddress,
+  value
+}) {
+  assertUint64(value, "value");
+  const { handles, inputProof } = await encryptor.encrypt({
+    values: [{ value, type: "euint64" }],
+    contractAddress,
+    userAddress
+  });
+  if (handles.length !== 1) {
+    throw new chunk67OV5CX2_cjs.InvalidArgumentError({
+      method: "encryptUint64",
+      argument: "handles",
+      reason: `expected 1 handle, got ${handles.length}`,
+      value: handles.length
+    });
+  }
+  return {
+    handle: chunk66IHPTOK_cjs.asEncryptedHandle(viem.bytesToHex(handles[0])),
+    inputProof: chunk66IHPTOK_cjs.asExternalInputProof(viem.bytesToHex(inputProof))
+  };
+}
+async function encryptUint64Batch({
+  encryptor,
+  contractAddress,
+  userAddress,
+  values
+}) {
+  if (values.length === 0) {
+    throw new chunk67OV5CX2_cjs.InvalidArgumentError({
+      method: "encryptUint64Batch",
+      argument: "values",
+      reason: "must be non-empty"
+    });
+  }
+  values.forEach((v, i) => assertUint64(v, `values[${i}]`));
+  const { handles, inputProof } = await encryptor.encrypt({
+    values: values.map((value) => ({ value, type: "euint64" })),
+    contractAddress,
+    userAddress
+  });
+  if (handles.length !== values.length) {
+    throw new chunk67OV5CX2_cjs.InvalidArgumentError({
+      method: "encryptUint64Batch",
+      argument: "handles",
+      reason: `expected ${values.length} handles, got ${handles.length}`,
+      value: handles.length
+    });
+  }
+  return {
+    handles: handles.map((h) => chunk66IHPTOK_cjs.asEncryptedHandle(viem.bytesToHex(h))),
+    inputProof: chunk66IHPTOK_cjs.asExternalInputProof(viem.bytesToHex(inputProof))
+  };
+}
 
 exports.FHE_SPLIT_DENOMINATOR = FHE_SPLIT_DENOMINATOR;
+exports.encryptUint64 = encryptUint64;
+exports.encryptUint64Batch = encryptUint64Batch;
+exports.resolveEncryptor = resolveEncryptor;
 exports.scaleRatio = scaleRatio;
 exports.share = share;