@tokenops/sdk 2.0.0-alpha.3 → 2.0.0-alpha.4

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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).
 
+## [2.0.0-alpha.4] - 2026-10-01
+
+> **Pre-release built against external-audit fixes that have not merged yet.** Continues the `2.0.0-alpha` line. `/fhe-airdrop` in this build targets `tokenops-fhe-airdrop-v2` at commit `005980df194e0dc66053bd517e9759bd4d580047` (branch `fix/external-audit-2026-09`), which carries the fixes for the external audit on top of the internal round but is still under review. Every Sepolia `fheAirdrop` address moved again in this build, to a preview deployment from `005980d` with the CREATE3 salt version `sdk-preview-13cad511`, set at deploy time; the contracts branch is unchanged and still names `2.0.2`, which is already consumed on Sepolia, so a redeploy needs its own fresh salt version. The factory is now `0xD5906f366Ff50909F403c8EDfDe680015563046a`. 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
+
+- **Every Merkle leaf input is bound to `(instance, instance)`, and anyone may submit a claim** (ext-audit-17). The contract now verifies each input against the airdrop itself, so the campaign builders encrypt every roster the same way: batched `MERKLE_BATCH_LIMIT` (32) values per proof, one relayer request per chunk, chunks concurrent. The payout still goes to `entry.account`, only `account` may redirect with `to`, and `claimAndUnwrap` stays self-only. A stranger who submits first settles the leaf confidentially, so a redirect or unwrap the recipient intended no longer happens; integrators check `getClaimedAmount` before offering a claim. ECDSA claims are unchanged.
+- **Removed `submitter`, `CampaignSubmitterOption` and `CampaignEntry.boundTo`**, from `encryptCampaignAmounts`, `buildMerkleCampaign`, `planMerkleCampaign`, `rotateMerkleRoot` and their hooks. Removed rather than deprecated: the contract rejects any other binding, so an ignored option would mislead. Entries built under earlier alphas were bound differently and cannot be claimed against this factory.
+- **`CreateAirdropResult` gained `managerImplementation` and `complianceDelegate`.** All three compliance fields are now read from the create receipt's `ComplianceManagerCloned` log instead of a follow-up registry call.
+- **Indexers: two event topics moved.** `AirdropInitialized` was reshaped (it drops `deploymentBlockNumber`, now a getter, and gains the window, `canExtendClaimWindow`, `unwrappable` and `complianceManager`; the variant-specific fields arrive in the new `ECDSAAirdropInitialized(dedupMode)` and `MerkleAirdropInitialized(merkleRoot, isMerkleRootMutable)`), and the factory's `ComplianceManagerCloned` gained `managerImplementation`. A filter on either old signature matches nothing. The SDK resolves creates from `ConfidentialAirdropCreated` and is unaffected.
+- **Factory compliance is ON from construction** (ext-audit-16). The constructor seeds a non-zero platform delegate with the default ON, so there is no post-deploy wiring step; `setComplianceDelegate` rotates but can never clear it, and `setDefaultDelegateToCompliance(true)` no longer depends on a prior delegate write.
+- **Local fixtures: the factory constructor takes the compliance delegate** as a trailing argument and starts with compliance ON (ext-audit-16). `test/fhe-airdrop/helpers/deploy-v2.ts` passes it; a fixture that deploys the factory itself must do the same.
+- **The React create, register, split and disperse hooks resolve `Mined | Pending`.** `useCreateManager`, `useCreateManagerAndGetAddress`, `useSplitVesting`, `useRegister`, `useDisperse`, `useWithdrawTokenFee`, `useSingletonWithdrawTokenFee` and the four airdrop create hooks accept `waitForReceipt`, and a hook cannot overload on it, so `data` / `mutateAsync` now resolve to the union of the mined result and its `Pending*Result`. Those fields now type as `X | undefined` on `data`, so code that used `data.manager`, `data.newVestingId`, `data.wallets` or `data.distributions` as `Address` / `Hex` / arrays no longer compiles. Headless calls are unaffected: the option is not on the base argument types, so a call or wrapper that never passes it keeps the mined result type. Migration: `if (data.pending) return;` before the read narrows to the mined result.
+
+### Added
+
+- **Receipt-free writes for Safe / multisig signers.** A threshold Safe's `safeTxHash` never mines until owners co-sign, so every write that waited for its receipt hung. These now take `waitForReceipt?: boolean` (default `true`) and, with `false`, return on submission without polling: `/fhe-vesting` `createManager`, `createManagerAndGetAddress`, `splitVesting`; `/fhe-disperse` `register`, `disperse` (all three modes), `withdrawTokenFee`; `/fhe-airdrop` `createEcdsaAirdrop`, `createMerkleAirdrop`, `createAndFundEcdsaAirdrop`, `createAndFundMerkleAirdrop`. Their hooks pass the option through. The option stays off the exported argument types (`CreateManagerArgs`, `SplitVestingArgs`, `RegisterArgs`, `DisperseArgs`, `WithdrawTokenFeeArgs`, `CreateAirdropArgs`, `CreateMerkleAirdropArgs`): each method takes `Args & ReceiptMode<...>` instead, with the new `ReceiptMode` exported from the root and each product subpath, so a value typed as one of those types still resolves to the mined overload, and a runtime `boolean` is typed `Args & ReceiptMode`. Each method is overloaded on the literal: without `waitForReceipt: false` it returns the mined result exactly as before, every receipt-derived field set; with it, a new `Pending*Result` (`PendingCreateManagerResult`, `PendingSplitVestingResult`, `PendingRegisterResult`, `PendingDisperseResult`, `PendingWithdrawTokenFeeResult`, `PendingCreateAirdropResult`) whose receipt-derived field is `undefined`. Every pending result carries `pending: true` (the shared `PendingWrite` type, exported from the root and each product subpath) and every mined result declares `pending?: never` (`MinedWrite`), so `if (result.pending)` narrows the same way in all three products. A pending airdrop create still carries every address, built from its commitments, because the factory reverts unless it deploys exactly there. Encrypted views and disclosures are deliberately excluded: a Safe cannot user-decrypt in-session. `register` now takes the exported `RegisterArgs`, and `WithdrawTokenFeeArgs` is exported from `/fhe-disperse`. The ERC-7984 operator approval the funding flows need (`setOperator`, `ensureOperator`, `useEnsureOperator`) already took `waitForReceipt`; a Safe passes `false` there too.
+- **`predictComplianceManagerClone`** (`/fhe-airdrop/advanced`), the compliance clone the factory deploys for an instance address.
+- **`encodeInstanceRoleSplit`** with `InstanceRoleCall` and `InstanceRoleConstants`: a `planInstanceRoleSplit` plan as the ordered `grantRole` / `revokeRole` calls a Safe submits as one MultiSend batch. `grantInstanceRoles` stays receipt-bound, since each step must mine before the next simulates.
+- **Create commitments** (ext-audit-09, -12). Every create now commits to the instance address, the compliance-manager implementation and the compliance delegate, and the factory reverts before consuming the salt when any of them drifted. The SDK quotes all three at send time; new `CreateCommitments` type, `CreateAirdropArgs.expected?: Partial<CreateCommitments>` to pin any of them instead, `factory.quoteCreateCommitments(...)`, `factory.resolveComplianceDelegate(creator)`, and a new `PreflightCreateResult` (what `preflightCreate` now returns) whose `commitments` is what the create would be sent with (`usePreflightCreateAirdrop` accepts `expected`). `quoteCreateCommitments` takes the new `AirdropVariantParams`, which ties `variant` to its params type. `preflightCreate` reports a pinned field that differs from the fresh quote as a `CreateCommitmentMismatchError` blocker. A planned Merkle campaign is created from its plan (next entry); `expected: { airdrop: plan.predictedAddress }` remains the lower-level way to pin the address alone.
+- **Create a planned Merkle campaign from its plan.** `createMerkleAirdrop`, `createAndFundMerkleAirdrop`, their hooks, and the Merkle arm of `preflightCreate` / `usePreflightCreateAirdrop` take `plan?: PlannedCampaign` (new `CreateMerkleAirdropArgs`). A plan pins `expected.airdrop` to `plan.predictedAddress`, so the instance can no longer land at a fresh prediction its leaves are not bound to after an implementation rotation. The write path refuses before any RPC when `params.merkleRoot` differs from `plan.root` or a caller-supplied `expected.airdrop` differs from `plan.predictedAddress` (`InvalidArgumentError`), and refuses before the send when the factory's live Merkle init-code hash no longer equals `plan.initCodeHashAfter` (`PredictionDriftError`). `preflightCreate` reports the same conditions as blockers, plus an `expectedInitCodeHash` that disagrees with the plan. The ECDSA creates do not take `plan`.
+- **`CreateCommitmentMismatchError`** (`TOKENOPS_CREATE_COMMITMENT_MISMATCH`), mapping `PredictionMismatch`, `ManagerImplementationMismatch` and `ComplianceDelegateMismatch`, with `context.field` (`"airdrop" | "complianceManagerImpl" | "complianceDelegate"`), `expected` and `actual`.
+- **`EcdsaAirdropClient.readDedupMode()`** and **`useDedupMode`** (ext-audit-06). `EcdsaAirdropClientConfig.dedupMode` and the hook options that required it are now optional (see Deprecated).
+- **`TOKENOPS_UNEXPECTED_CONTRACT_RESPONSE`** joins `TokenOpsSdkErrorCode`: a read that succeeded but returned a value this SDK cannot interpret. `readDedupMode()` throws it, with `context.{contractAddress, ordinal}`, for a `DedupMode` ordinal it does not know. Potentially breaking for an exhaustive `switch (err.code)` with a `never` check, which needs a case for it.
+- **`canExtendClaimWindow()`** and **`deploymentBlockNumber()`** on every instance, both also returned by `useAirdropConfig`; **`factory.tokenOf(airdrop)`** and **`useTokenOf`**, the token `fundAirdrop` pulls (ext-audit-03, -06).
+- **`rescueNativeToken({ recipient })`** and **`useRescueNativeToken`** (`RESCUER_ROLE`), sweeping ETH from a zero-fee campaign (ext-audit-07).
+- **`ClawbackRequiresPauseError`** (`TOKENOPS_CLAWBACK_REQUIRES_PAUSE`): `withdrawConfidential` is refused while the campaign is unpaused inside its claim window (ext-audit-11). **`NativeRescueRequiresZeroFeeError`** (`TOKENOPS_NATIVE_RESCUE_REQUIRES_ZERO_FEE`) for a rescue on a fee-charging campaign.
+- `InvalidImplementation` and `UninitializedHandle` map to `InvalidArgumentError`. `InitializationMismatch` and `UninitializedDelivery` are deliberately left to `ContractRevertError`: a platform or token fault, not a state a caller can act on.
+- **`parseUnwrapRequest(receipt | logs)`**, **`readUnwrapRequest(hash)`** (on every instance client) and **`useUnwrapRequest`**, with the new `UnwrapRequest` and `UnwrapRequestSource` types. They decode the instance's `ClaimedAndUnwrapInitiated` event into `{ claimant, beneficiary, claimKey, unwrapRequestId }`, so the `finalizeUnwrap` that releases the underlying ERC-20 can be sent without decoding logs by hand (with Zama's SDK, `sdk.createToken(wrapper).finalizeUnwrap(unwrapRequestId)`). `claimAndUnwrap` itself still returns a bare hash. Only this instance's event counts; two in one transaction throw `ReceiptEventAmbiguousError`.
+- **`MERKLE_BATCH_LIMIT`** is exported.
+- **`/fhe-airdrop/react` now exports `GasFeeNotAcceptedError`, `UnrecognisedAirdropError`, `UINT96_MAX` and `UseDedupModeArgs`**, matching the headless barrel. The hooks could already raise both errors, and `UINT96_MAX` is the accept-any value for `common.maxAcceptedGasFee`.
+
+### Deprecated
+
+- **`EcdsaAirdropClientConfig.dedupMode`, `EcdsaAirdropClient.dedupMode` and the `dedupMode` option of the ECDSA hooks.** No method branches on them; read the policy from the chain with `readDedupMode()` / `useDedupMode`. They will be removed before `2.0.0`.
+
+### Fixed
+
+- **`preflightCreate` blocks a resolved fee above the factory's `maxGasFee` ceiling.** Lowering the ceiling never rewrites a configured fee, so a create could revert `GasFeeExceedsMaximum` while the preflight reported `ready: true`. The blocker is the same `InvalidArgumentError` (on `gasFee`) that the revert maps to, so a UI sees one code on both paths.
+- **`preflightCreate` blocks params the instance initializer would revert on.** A zero `common.token` (`ZeroToken`), an `endTime` less than 60 seconds ahead of the local clock (`EndTimeInPast`), a `startTime` after `endTime` (`InvalidStartTime`) or equal to it (`InvalidDuration`), a zero `merkleRoot` on an immutable-root campaign (`ZeroMerkleRoot`) and a zero ECDSA `signer` (`ZeroSigner`) are each an `InvalidArgumentError` blocker naming the field. These revert after the factory's own checks, so `ready` was `true` for a create that could never land. The write path still surfaces them through its simulate.
+- **A create whose resolved fee exceeds both the factory's `maxGasFee` ceiling and the creator's `maxAcceptedGasFee` now reports the ceiling.** The factory checks the ceiling first (`GasFeeExceedsMaximum`), but the write path only compared against the creator's bound and threw `GasFeeNotAcceptedError`, so a creator who raised their bound then hit the ceiling. The four `create*` methods now read `maxGasFee()` alongside the resolved fee and throw the ceiling's `InvalidArgumentError` (on `gasFee`) first, matching `preflightCreate`.
+- `setEcdsaImplementation`, `setMerkleImplementation` and `setComplianceManagerImpl` document the `InvalidImplementation` revert (a codeless address or an EIP-7702 designator), not only the zero-address one.
+- **The docs said `dedupMode` could not be read from the chain.** The contract now exposes it, and `docs/fhe-airdrop/README.md`, the root README and the migration guide describe the getter and the init event instead of telling consumers to record the value themselves.
+- The docs now state that `claimAndUnwrap` publishes the unwrapped amount from the claim transaction on, not at `finalizeUnwrap` (ext-audit-13).
+- **`preflightDisperse` checks the sender's singleton approval in every mode.** `DisperseConfidential` pulls from `msg.sender` in the wallet, direct and wallet-token-fee entrypoints and in the token-fee pull, but the preflight only read `isOperator(sender, singleton)` in direct mode, so a wallet-mode sender who had approved only the subwallets got `ready: true` and then an `ERC7984UnauthorizedSpender` revert. It now reads the approval for every mode and reports `SingletonNotApprovedError` whenever it is missing; the subwallet blocker stays for the wallet modes. `PreflightReport.hasApprovedSingleton` narrows from `boolean | null` to `boolean`: code that tested it for truthiness is unaffected, while a check for `=== null` (the old wallet-mode value) no longer matches.
+- Airdrop revert decoding keeps the arguments the ABI carries: `InvalidMerkleProof` puts `{ leaf, merkleRoot }` and `InvalidImplementation` the rejected address in `context.value`, and `EndTimeInPast` / `InvalidDuration` now map in the airdrop mapper with both timestamps in the message and `context.value`, instead of the default mapper's argument-free bucket.
+- **`ClaimNotStartedError` and `ClaimWindowClosedError` now carry their times from a real revert.** The contract's `uint32` start / end time decodes as a `number` in viem, which the mapper dropped, so `startTime` / `endTime` (and the "Opens at" / "Closed at" message detail) were `undefined` on chain-decoded errors; `currentTime` was likewise lost. Both are now read whether viem returns a `number` or a `bigint`.
+- **Docs: ECDSA empty proofs, the signer key and `claimAndUnwrap` disclosure.** The ECDSA claim TSDoc and guide no longer say every input is bound to `(instance, claimant)`: only a non-empty proof is, while an empty proof accepts a zero handle or one the claimant and instance already hold ACL on, and campaigns that may reissue vouchers should use `perDedupId` or `both`. `SIGNER_ROLE` is documented as a key that must never be EIP-7702-delegated, with `isSignatureValid` as the pre-check. `claimAndUnwrap` and its hooks now state that the amount is public from the claim transaction, not at `finalizeUnwrap`.
+- **Create preflights no longer go stale after a write that moves them.** The nine factory-admin hooks that move a create's commitments or fee checks (`useSetComplianceDelegate`, `useSetDefaultDelegateToCompliance`, `useSetCompliancePolicy`, `useClearCompliancePolicy`, `useSetComplianceManagerImpl`, `useSetDefaultGasFee`, `useSetCustomFee`, `useDisableCustomFee`, `useSetMaxGasFee`) and the four create hooks now invalidate every cached `usePreflightCreateAirdrop` report on the factory. A create also consumes its salt, so a cached `ready: true` for it is now invalidated too.
+- **`useComplianceManagerOf` no longer caches a zero answer forever** (the new `useTokenOf` follows the same policy). A non-zero mapping is still held indefinitely, but a zero (not created yet, or not from this factory) stays stale, the same policy as `useIsAirdrop`. The four create hooks also invalidate both entries for the address they deploy, so a zero read of a predicted address updates as soon as the create lands.
+
 ## [2.0.0-alpha.3] - 2026-09-16
 
 > **Pre-release built against internally-audited, externally-unaudited contracts.** Continues the `2.0.0-alpha` line. `/fhe-airdrop` in this build targets `tokenops-fhe-airdrop-v2` at commit `c5c12c2087f61bcd5bd1daa802563ed3cd68f002`, which closes the internal audit round (audit-03 through audit-16) but has not completed an external security audit. Every Sepolia `fheAirdrop` address moved again in this build. 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.**

package/README.md

@@ -21,24 +21,24 @@ 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`                | **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                                                                                                                 |
+| 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, external-audit fixes unmerged** — `alpha` dist-tag, factory live on Sepolia | ECDSA + Merkle confidential airdrop campaigns — see [Compatibility](#compatibility)                                                                                            |
+| `@tokenops/sdk/fhe-airdrop/react`          | **v2, external-audit fixes unmerged**                                             | React/wagmi hooks for recipients, campaign creators, campaign owners and the compliance manager                                                                                |
+| `@tokenops/sdk/fhe-airdrop/advanced`       | **v2, external-audit fixes unmerged**                                             | Prediction-freshness / salt-availability guards and `predictComplianceManagerClone` (instance-address prediction itself is on the headline `ConfidentialAirdropFactoryClient`) |
+| `@tokenops/sdk/fhe-airdrop/advanced/react` | **v2, external-audit fixes unmerged**                                             | 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"`.
 
@@ -46,11 +46,13 @@ The canonical exports map is in [`package.json`](https://github.com/VestingLabs/
 
 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.3`           | v2 (internal audit only) | `c5c12c2`       | Sepolia |
-| `2.0.0-alpha.1`-`alpha.2` | v2 (unaudited)           | `7175ac8`       | Sepolia |
-| `1.x`                     | v1                       | n/a             | Sepolia |
+| SDK             | Airdrop contracts                             | Contract commit | Chains  |
+| --------------- | --------------------------------------------- | --------------- | ------- |
+| `2.0.0-alpha.4` | v2 (external audit fixes, preview deployment) | `005980d`       | Sepolia |
+| `2.0.0-alpha.3` | v2 (internal audit only)                      | `c5c12c2`       | Sepolia |
+| `2.0.0-alpha.2` | v2 (unaudited)                                | `7175ac8`       | Sepolia |
+| `2.0.0-alpha.1` | v2 (unaudited)                                | `8e5b144`       | Sepolia |
+| `1.x`           | v1                                            | n/a             | Sepolia |
 
 Alpha builds are pinned to a contract generation, and every generation so far has moved every
 deployed address. An instance created through one generation's factory is unreachable from a
@@ -271,9 +273,10 @@ function DeployManager({
               "0x0000000000000000000000000000000000000000000000000000000000000001" as `0x${string}`,
           },
           {
-            onSuccess: ({ manager }) => {
+            onSuccess: (result) => {
               queryClient.invalidateQueries({ queryKey: ["tokenops-sdk", "fhe-vesting"] });
-              onDeployed(manager);
+              // A hook resolves `Mined | Pending`; only a pending result lacks `manager`.
+              if (!result.pending) onDeployed(result.manager);
             },
           },
         )
@@ -290,7 +293,7 @@ See [Confidential Vesting — React hooks on docs.tokenops.xyz](https://docs.tok
 
 ## Quickstart — confidential airdrop
 
-> **v2, internally audited only.** `/fhe-airdrop` targets `tokenops-fhe-airdrop-v2` (`c5c12c2`, 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).
+> **v2, external-audit fixes not yet merged.** `/fhe-airdrop` targets `tokenops-fhe-airdrop-v2` (`005980d`, a preview deployment on 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.
 
@@ -324,9 +327,8 @@ const now = Math.floor(Date.now() / 1000);
 const userSalt = "0x0000000000000000000000000000000000000000000000000000000000000001" as const;
 const token = process.env.TOKEN as `0x${string}`;
 
-// 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.
+// Create. There is no `admin` field - the factory injects `admin = msg.sender`.
+// `dedupMode` is frozen here; read it back later with `readDedupMode()`.
 const { airdrop: airdropAddress } = await factory.createEcdsaAirdrop({
   params: {
     common: {
@@ -336,6 +338,7 @@ const { airdrop: airdropAddress } = await factory.createEcdsaAirdrop({
       canExtendClaimWindow: false,
       unwrappable: false,
       complianceAdmin: zeroAddress, // zero => msg.sender
+      maxAcceptedGasFee: 2_000_000_000_000_000n, // 0.002 ETH; a higher resolved fee reverts
     },
     signer: account.address, // SIGNER_ROLE holder authorising claims
     dedupMode: "perAddress",
@@ -384,12 +387,11 @@ const airdrop = createEcdsaAirdropClient({
   publicClient,
   walletClient,
   address: airdropAddress,
-  dedupMode: "perAddress", // must match what was passed at create — no getter exists
 });
 await airdrop.claim({ encryptedInput, dedupId, deadline, signer: account.address, signature });
 ```
 
-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.
+See [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md) for the full API reference, the Merkle campaign flow, guardrails, and the external-audit status warning.
 
 ### Quickstart — confidential airdrop (React hooks)
 
@@ -451,9 +453,10 @@ function AdminPanel({
           canExtendClaimWindow: false,
           unwrappable: false,
           complianceAdmin: "0x0000000000000000000000000000000000000000",
+          maxAcceptedGasFee: 2_000_000_000_000_000n, // 0.002 ETH
         },
         signer: "0xYourSignerAddress" as `0x${string}`,
-        dedupMode: "perAddress", // record this — no on-chain getter exists later
+        dedupMode: "perAddress", // frozen at create; `useDedupMode` reads it back
       },
       mode: "clone",
       userSalt:
@@ -518,9 +521,7 @@ function RecipientClaim({
     signature: `0x${string}`;
   };
 }) {
-  // `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" });
+  const claim = useEcdsaClaim({ address: airdropAddress });
 
   return (
     <button onClick={() => claim.mutate(claimPayload)} disabled={claim.isPending}>
@@ -780,6 +781,41 @@ function FaucetPanel() {
 
 See [Testnet Faucet — React hooks on docs.tokenops.xyz](https://docs.tokenops.xyz/sdk/testnet-faucet#react-hooks) for the full hook catalogue (reads, mints, metadata), address overrides, and query-key reference.
 
+## Safe and multisig signers
+
+A threshold Safe's submission returns a `safeTxHash` that does not mine until the other owners
+co-sign, so a write that waits for its receipt would hang. These writes take
+`waitForReceipt: false` (default `true`) and return as soon as the submission hash is known; their
+React hooks pass the option through.
+
+The ERC-7984 operator approval every funding flow needs first is the same: `setOperator`,
+`ensureOperator` and `useEnsureOperator` (`@tokenops/sdk/fhe`) wait for their receipt by default,
+so a Safe passes `waitForReceipt: false` there too and lets the approval execute before the
+funding transaction does. That covers vesting funding, every `disperse` mode and the airdrop
+`createAndFund*` / `fundAirdrop` paths.
+
+Each method is overloaded on the literal. Called without `waitForReceipt: false`, it returns the
+mined result with every field set. Called with it, it returns a `Pending*Result` carrying
+`pending: true` (the shared `PendingWrite` shape). The option is not part of the exported `*Args`
+types, so a wrapper typed with one of them still gets the mined result; a runtime `boolean` goes
+through the exported `ReceiptMode` (`args: CreateManagerArgs & ReceiptMode`) and gets the union of
+the two. A hook cannot overload, so its `data` is that union too, and `if (data.pending)` narrows
+it the same way in every product:
+
+| Product         | Method                                                                                                 | Pending result's receipt-derived field                                                 |
+| --------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `/fhe-vesting`  | `createManager`, `createManagerAndGetAddress`                                                          | `manager: undefined` - read the executed tx's `ManagerCreated` log                     |
+| `/fhe-vesting`  | `splitVesting`                                                                                         | `newVestingId: undefined` - read the `VestingSplit` log                                |
+| `/fhe-disperse` | `register`                                                                                             | `wallets: undefined` - read the `UserRegistered` log                                   |
+| `/fhe-disperse` | `disperse`                                                                                             | `distributions: undefined` - read the `WalletDistribution` / `DirectDistribution` logs |
+| `/fhe-disperse` | `withdrawTokenFee`                                                                                     | `transferredHandle: undefined` - read the `TokenFeeWithdrawn` log                      |
+| `/fhe-airdrop`  | `createEcdsaAirdrop`, `createMerkleAirdrop`, `createAndFundEcdsaAirdrop`, `createAndFundMerkleAirdrop` | none: every address is the committed one                                               |
+
+Airdrop role splits go through `planInstanceRoleSplit` plus `encodeInstanceRoleSplit` as one
+MultiSend batch; see [Safe and multisig signers](docs/fhe-airdrop/README.md#safe-and-multisig-signers).
+Encrypted views and disclosures have no receipt-free option: their handle is only useful to an
+account that can user-decrypt in-session, so run them from an EOA or a delegate.
+
 ## Peer dependencies
 
 | Package                 | Range        | Required for                                                                   |

package/SUPPORT.md

@@ -42,6 +42,6 @@ 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).
+- Module docs (v2, external-audit fixes unmerged): [`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-NGU4JYIR.js → chunk-2ND7US2I.js}

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

package/dist/{chunk-U3TBQRT7.js → chunk-3ZSPRHR3.js}

@@ -1,7 +1,8 @@
-import { createConfidentialAirdropFactoryClient, resolveEncryptor, createAirdropBaseClient, createMerkleAirdropClient, createComplianceManagerClient, createEcdsaAirdropClient } from './chunk-BXX5TETM.js';
-import { getFheAirdropFactoryAddress } from './chunk-6HCT4QIX.js';
+import { createConfidentialAirdropFactoryClient, resolveEncryptor, createAirdropBaseClient, createMerkleAirdropClient, createComplianceManagerClient, createEcdsaAirdropClient } from './chunk-67Q6KSVV.js';
+import { getFheAirdropFactoryAddress } from './chunk-GHGF65LN.js';
 import { DeploymentAddressUnavailableError } from './chunk-QBJ7O2B4.js';
 import { useRef, useMemo } from 'react';
+import { isAddressEqual, zeroAddress } from 'viem';
 import { usePublicClient, useWalletClient } from 'wagmi';
 
 var FHE_AIRDROP_KEY = "tokenops-sdk";
@@ -37,6 +38,10 @@ function normalizeKeyArg(value) {
   if (typeof value === "string" && value.startsWith("0x")) return value.toLowerCase();
   return value;
 }
+function staleUntilNonZeroAddress(query) {
+  const data = query.state.data;
+  return data !== void 0 && !isAddressEqual(data, zeroAddress) ? Infinity : 0;
+}
 function tryResolveAirdropFactoryAddress(override, chainId) {
   if (override) return override;
   if (chainId === void 0) return void 0;
@@ -161,7 +166,7 @@ function useMemoEcdsaAirdropClient(opts) {
       publicClient,
       ...walletClient ? { walletClient } : {},
       address: opts.address,
-      dedupMode: opts.dedupMode,
+      ...opts.dedupMode !== void 0 ? { dedupMode: opts.dedupMode } : {},
       ...chainId !== void 0 ? { chainId } : {},
       ...telemetry ? { telemetry } : {}
     });
@@ -174,6 +179,7 @@ var AIRDROP_FN = {
   // instance reads
   claimedAmount: "getClaimedAmount",
   paused: "paused",
+  dedupMode: "dedupMode",
   window: "window",
   config: "config",
   merkleRoot: "merkleRoot",
@@ -190,20 +196,29 @@ var AIRDROP_FN = {
   resolvedGasFee: "resolvedGasFee",
   customFee: "customFee",
   implementations: "implementations",
+  tokenOf: "tokenOf",
+  complianceManagerOf: "complianceManagerOf",
   compliancePolicy: "compliancePolicy",
   upgradeabilityPolicy: "upgradeabilityPolicy",
   factoryHasRole: "factoryHasRole",
   factoryRoleMembers: "factoryRoleMembers",
+  effectiveDelegateToCompliance: "effectiveDelegateToCompliance",
+  effectiveUpgradeable: "effectiveUpgradeable",
+  complianceDelegate: "complianceDelegate",
+  ecdsaInitCodeHash: "getEcdsaInitCodeHash",
+  predictEcdsaAddress: "predictEcdsaAirdropAddress",
+  merkleInitCodeHash: "getMerkleInitCodeHash",
+  predictMerkleAddress: "predictMerkleAirdropAddress",
   // compliance-manager reads
   complianceInfo: "complianceInfo",
   activeDelegate: "isActiveDelegate",
-  clientDelegates: "clientDelegates",
   complianceHasRole: "complianceHasRole",
   complianceRoleMembers: "complianceRoleMembers"
 };
 var airdropKeys = {
   /** One account's cumulative delivered total. Keyed on the CLAIM IDENTITY, never the sender. */
   claimedAmount: (s, account) => airdropQueryKey({ ...s, fn: AIRDROP_FN.claimedAmount, args: [account] }),
+  dedupMode: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.dedupMode, args: [] }),
   paused: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.paused, args: [] }),
   window: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.window, args: [] }),
   config: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.config, args: [] }),
@@ -221,15 +236,17 @@ var airdropKeys = {
   isSignatureValidAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.isSignatureValid }),
   fees: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.fees, args: [] }),
   customFee: (s, creator) => airdropQueryKey({ ...s, fn: AIRDROP_FN.customFee, args: [creator] }),
-  customFeeAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.customFee }),
   resolvedGasFee: (s, creator) => airdropQueryKey({ ...s, fn: AIRDROP_FN.resolvedGasFee, args: [creator] }),
   /** Every creator's resolved fee; the default and any override both move it. */
   resolvedGasFeeAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.resolvedGasFee }),
+  registry: (s, offset, limit) => airdropQueryKey({ ...s, fn: AIRDROP_FN.registry, args: [offset, limit] }),
   /** Every registry page, whatever offset/limit was queried. */
   registryAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.registry }),
   isAirdrop: (s, candidate) => airdropQueryKey({ ...s, fn: AIRDROP_FN.isAirdrop, args: [candidate] }),
   /** Every genuineness answer from this factory; a create adds one address. */
   isAirdropAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.isAirdrop }),
+  tokenOf: (s, airdrop) => airdropQueryKey({ ...s, fn: AIRDROP_FN.tokenOf, args: [airdrop] }),
+  complianceManagerOf: (s, airdrop) => airdropQueryKey({ ...s, fn: AIRDROP_FN.complianceManagerOf, args: [airdrop] }),
   implementations: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.implementations, args: [] }),
   compliancePolicy: (s, creator) => airdropQueryKey({ ...s, fn: AIRDROP_FN.compliancePolicy, args: [creator] }),
   compliancePolicyAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.compliancePolicy }),
@@ -238,16 +255,42 @@ var airdropKeys = {
   factoryHasRole: (s, role, holder) => airdropQueryKey({ ...s, fn: AIRDROP_FN.factoryHasRole, args: [role, holder] }),
   factoryHasRoleAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.factoryHasRole }),
   factoryRoleMembers: (s, role) => airdropQueryKey({ ...s, fn: AIRDROP_FN.factoryRoleMembers, args: [role] }),
-  factoryRoleMembersAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.factoryRoleMembers }),
+  effectiveDelegateToCompliance: (s, creator) => airdropQueryKey({ ...s, fn: AIRDROP_FN.effectiveDelegateToCompliance, args: [creator] }),
+  /** Every creator's effective compliance default; the factory-wide default moves them all. */
+  effectiveDelegateToComplianceAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.effectiveDelegateToCompliance }),
+  effectiveUpgradeable: (s, creator) => airdropQueryKey({ ...s, fn: AIRDROP_FN.effectiveUpgradeable, args: [creator] }),
+  /** Every creator's effective upgradeability; the factory-wide default moves them all. */
+  effectiveUpgradeableAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.effectiveUpgradeable }),
+  complianceDelegate: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.complianceDelegate, args: [] }),
+  /** Keyed on `mode` only: `params` does not affect the hash (see `useEcdsaInitCodeHash`). */
+  ecdsaInitCodeHash: (s, mode) => airdropQueryKey({ ...s, fn: AIRDROP_FN.ecdsaInitCodeHash, args: [mode] }),
+  ecdsaInitCodeHashAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.ecdsaInitCodeHash }),
+  predictEcdsaAddress: (s, mode, deployer, userSalt) => airdropQueryKey({ ...s, fn: AIRDROP_FN.predictEcdsaAddress, args: [mode, deployer, userSalt] }),
+  predictEcdsaAddressAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.predictEcdsaAddress }),
+  merkleInitCodeHash: (s, mode) => airdropQueryKey({ ...s, fn: AIRDROP_FN.merkleInitCodeHash, args: [mode] }),
+  merkleInitCodeHashAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.merkleInitCodeHash }),
+  predictMerkleAddress: (s, mode, deployer, userSalt) => airdropQueryKey({
+    ...s,
+    fn: AIRDROP_FN.predictMerkleAddress,
+    args: [mode, deployer, userSalt]
+  }),
+  predictMerkleAddressAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.predictMerkleAddress }),
   complianceInfo: (s) => airdropQueryKey({ ...s, fn: AIRDROP_FN.complianceInfo, args: [] }),
   activeDelegate: (s, delegate) => airdropQueryKey({ ...s, fn: AIRDROP_FN.activeDelegate, args: [delegate] }),
-  activeDelegateAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.activeDelegate }),
-  clientDelegates: (s, index) => airdropQueryKey({ ...s, fn: AIRDROP_FN.clientDelegates, args: [index] }),
-  clientDelegatesAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.clientDelegates }),
   complianceHasRole: (s, role, holder) => airdropQueryKey({ ...s, fn: AIRDROP_FN.complianceHasRole, args: [role, holder] }),
   complianceHasRoleAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.complianceHasRole }),
-  complianceRoleMembers: (s, role) => airdropQueryKey({ ...s, fn: AIRDROP_FN.complianceRoleMembers, args: [role] }),
-  complianceRoleMembersAll: (s) => airdropQueryKeyPrefix({ ...s, fn: AIRDROP_FN.complianceRoleMembers })
+  complianceRoleMembers: (s, role) => airdropQueryKey({ ...s, fn: AIRDROP_FN.complianceRoleMembers, args: [role] })
 };
+function invalidateAfterCreate(queryClient, scope, airdrop) {
+  for (const queryKey of [
+    airdropKeys.registryAll(scope),
+    airdropKeys.isAirdropAll(scope),
+    airdropKeys.preflightCreateAll(scope),
+    airdropKeys.tokenOf(scope, airdrop),
+    airdropKeys.complianceManagerOf(scope, airdrop)
+  ]) {
+    void queryClient.invalidateQueries({ queryKey });
+  }
+}
 
-export { AIRDROP_FN, airdropKeys, airdropQueryKey, airdropQueryKeyPrefix, useMemoAirdropBaseClient, useMemoAirdropFactoryClient, useMemoComplianceManagerClient, useMemoEcdsaAirdropClient, useMemoMerkleAirdropClient };
+export { AIRDROP_FN, airdropKeys, airdropQueryKey, airdropQueryKeyPrefix, invalidateAfterCreate, staleUntilNonZeroAddress, useMemoAirdropBaseClient, useMemoAirdropFactoryClient, useMemoComplianceManagerClient, useMemoEcdsaAirdropClient, useMemoMerkleAirdropClient };