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

package/dist/fhe-airdrop/react/keys.d.ts

@@ -12,7 +12,9 @@
  *
  * A `fn` label used by exactly one hook stays inline in that hook.
  */
+import type { QueryClient } from "@tanstack/react-query";
 import type { Address, Hex } from "viem";
+import type { DeploymentMode } from "../constants.js";
 /** Chain + contract scope every key below is built against. */
 interface Scope {
     chainId: number | undefined;
@@ -22,6 +24,7 @@ interface Scope {
 export declare const AIRDROP_FN: {
     readonly claimedAmount: "getClaimedAmount";
     readonly paused: "paused";
+    readonly dedupMode: "dedupMode";
     readonly window: "window";
     readonly config: "config";
     readonly merkleRoot: "merkleRoot";
@@ -37,19 +40,28 @@ export declare const AIRDROP_FN: {
     readonly resolvedGasFee: "resolvedGasFee";
     readonly customFee: "customFee";
     readonly implementations: "implementations";
+    readonly tokenOf: "tokenOf";
+    readonly complianceManagerOf: "complianceManagerOf";
     readonly compliancePolicy: "compliancePolicy";
     readonly upgradeabilityPolicy: "upgradeabilityPolicy";
     readonly factoryHasRole: "factoryHasRole";
     readonly factoryRoleMembers: "factoryRoleMembers";
+    readonly effectiveDelegateToCompliance: "effectiveDelegateToCompliance";
+    readonly effectiveUpgradeable: "effectiveUpgradeable";
+    readonly complianceDelegate: "complianceDelegate";
+    readonly ecdsaInitCodeHash: "getEcdsaInitCodeHash";
+    readonly predictEcdsaAddress: "predictEcdsaAirdropAddress";
+    readonly merkleInitCodeHash: "getMerkleInitCodeHash";
+    readonly predictMerkleAddress: "predictMerkleAirdropAddress";
     readonly complianceInfo: "complianceInfo";
     readonly activeDelegate: "isActiveDelegate";
-    readonly clientDelegates: "clientDelegates";
     readonly complianceHasRole: "complianceHasRole";
     readonly complianceRoleMembers: "complianceRoleMembers";
 };
 export declare const airdropKeys: {
     /** One account's cumulative delivered total. Keyed on the CLAIM IDENTITY, never the sender. */
     readonly claimedAmount: (s: Scope, account: Address | undefined) => unknown[];
+    readonly dedupMode: (s: Scope) => unknown[];
     readonly paused: (s: Scope) => unknown[];
     readonly window: (s: Scope) => unknown[];
     readonly config: (s: Scope) => unknown[];
@@ -67,15 +79,17 @@ export declare const airdropKeys: {
     readonly isSignatureValidAll: (s: Scope) => unknown[];
     readonly fees: (s: Scope) => unknown[];
     readonly customFee: (s: Scope, creator: Address | undefined) => unknown[];
-    readonly customFeeAll: (s: Scope) => unknown[];
     readonly resolvedGasFee: (s: Scope, creator: Address | undefined) => unknown[];
     /** Every creator's resolved fee; the default and any override both move it. */
     readonly resolvedGasFeeAll: (s: Scope) => unknown[];
+    readonly registry: (s: Scope, offset: bigint | undefined, limit: bigint | undefined) => unknown[];
     /** Every registry page, whatever offset/limit was queried. */
     readonly registryAll: (s: Scope) => unknown[];
     readonly isAirdrop: (s: Scope, candidate: Address | undefined) => unknown[];
     /** Every genuineness answer from this factory; a create adds one address. */
     readonly isAirdropAll: (s: Scope) => unknown[];
+    readonly tokenOf: (s: Scope, airdrop: Address | undefined) => unknown[];
+    readonly complianceManagerOf: (s: Scope, airdrop: Address | undefined) => unknown[];
     readonly implementations: (s: Scope) => unknown[];
     readonly compliancePolicy: (s: Scope, creator: Address | undefined) => unknown[];
     readonly compliancePolicyAll: (s: Scope) => unknown[];
@@ -84,15 +98,40 @@ export declare const airdropKeys: {
     readonly factoryHasRole: (s: Scope, role: Hex | undefined, holder: Address | undefined) => unknown[];
     readonly factoryHasRoleAll: (s: Scope) => unknown[];
     readonly factoryRoleMembers: (s: Scope, role: Hex | undefined) => unknown[];
-    readonly factoryRoleMembersAll: (s: Scope) => unknown[];
+    readonly effectiveDelegateToCompliance: (s: Scope, creator: Address | undefined) => unknown[];
+    /** Every creator's effective compliance default; the factory-wide default moves them all. */
+    readonly effectiveDelegateToComplianceAll: (s: Scope) => unknown[];
+    readonly effectiveUpgradeable: (s: Scope, creator: Address | undefined) => unknown[];
+    /** Every creator's effective upgradeability; the factory-wide default moves them all. */
+    readonly effectiveUpgradeableAll: (s: Scope) => unknown[];
+    readonly complianceDelegate: (s: Scope) => unknown[];
+    /** Keyed on `mode` only: `params` does not affect the hash (see `useEcdsaInitCodeHash`). */
+    readonly ecdsaInitCodeHash: (s: Scope, mode: DeploymentMode) => unknown[];
+    readonly ecdsaInitCodeHashAll: (s: Scope) => unknown[];
+    readonly predictEcdsaAddress: (s: Scope, mode: DeploymentMode, deployer: Address, userSalt: Hex) => unknown[];
+    readonly predictEcdsaAddressAll: (s: Scope) => unknown[];
+    readonly merkleInitCodeHash: (s: Scope, mode: DeploymentMode) => unknown[];
+    readonly merkleInitCodeHashAll: (s: Scope) => unknown[];
+    readonly predictMerkleAddress: (s: Scope, mode: DeploymentMode, deployer: Address, userSalt: Hex) => unknown[];
+    readonly predictMerkleAddressAll: (s: Scope) => unknown[];
     readonly complianceInfo: (s: Scope) => unknown[];
     readonly activeDelegate: (s: Scope, delegate: Address | undefined) => unknown[];
-    readonly activeDelegateAll: (s: Scope) => unknown[];
-    readonly clientDelegates: (s: Scope, index: bigint | undefined) => unknown[];
-    readonly clientDelegatesAll: (s: Scope) => unknown[];
     readonly complianceHasRole: (s: Scope, role: Hex | undefined, holder: Address | undefined) => unknown[];
     readonly complianceHasRoleAll: (s: Scope) => unknown[];
     readonly complianceRoleMembers: (s: Scope, role: Hex | undefined) => unknown[];
-    readonly complianceRoleMembersAll: (s: Scope) => unknown[];
 };
+/**
+ * Invalidate everything a create makes stale, for the four factory create hooks.
+ *
+ * - `registryAll`: the registry gained an instance.
+ * - `isAirdropAll`: `isAirdrop(airdrop)` flipped from false to true.
+ * - `preflightCreateAll`: the create consumed its `(mode, deployer, userSalt)`, so a cached
+ *   `ready: true` for it is now a guaranteed `SaltCollisionError`.
+ * - `tokenOf` / `complianceManagerOf` for `airdrop`: a read of the predicted address taken
+ *   before the create cached a zero.
+ *
+ * A receipt-free create runs this too, before the transaction executes. That is harmless:
+ * the refetch reads the pre-create state and the entries are marked stale again later.
+ */
+export declare function invalidateAfterCreate(queryClient: QueryClient, scope: Scope, airdrop: Address): void;
 export {};

package/dist/fhe-airdrop/react/useAccessEcdsaClaimAmount.d.ts

@@ -10,15 +10,18 @@ import { type EcdsaAirdropInstanceClientOptions } from "./_shared.js";
  * with `FHE.allow(amount, msg.sender)`, unlike {@link useAccessMerkleClaimAmount}, whose
  * grantee is the entry's claim identity rather than the caller.
  *
- * `dedupMode` must be supplied - the contract has no on-chain getter for it; pass the
- * same value used at `createEcdsaAirdrop` time.
+ * An empty `inputProof` is accepted only for a zero handle or one the sender and the
+ * instance already hold ACL on; see `EcdsaClaimArgs.encryptedInput`.
+ *
+ * `dedupMode` is deprecated - no call branches on it. Read the
+ * instance's actual policy with `useDedupMode`.
  *
  * **Invalidates:** nothing. The preview consumes neither replay guard nor the EIP-712
  * digest, so the same input is still claimable for real afterwards and no cached read
  * changes value.
  *
  * @example
- * const preview = useAccessEcdsaClaimAmount({ address: airdropAddress, dedupMode: "perAddress" });
+ * const preview = useAccessEcdsaClaimAmount({ address: airdropAddress });
  * const { handle } = await preview.mutateAsync({ encryptedInput, dedupId, deadline, signer, signature });
  *
  * @alpha

package/dist/fhe-airdrop/react/useAccessMerkleClaimAmount.d.ts

@@ -6,8 +6,8 @@ import { type AirdropInstanceClientOptions } from "./_shared.js";
  * **Submits a transaction.** Previews the outstanding amount for a proof-bearing Merkle
  * entry as an encrypted handle. Pass `data.handle` to the Zama relayer's `userDecrypt`.
  *
- * `entry.boundTo` must be the sending account (the coprocessor verifies the input proof
- * against the literal caller); `entry.account` selects the leaf.
+ * `entry.account` selects the leaf. A leaf someone else already settled previews as an
+ * encrypted zero; see {@link MerkleClaimArgs.entry}.
  *
  * **`entry.account` is the only party that can decrypt the result, not the submitter.**
  * The contract grants the outstanding handle with `_outstandingOf(account, account, …)`,

package/dist/fhe-airdrop/react/useAirdropConfig.d.ts

@@ -3,7 +3,7 @@ import type { Address } from "viem";
 import type { AirdropVariant } from "../errors.js";
 import { type AirdropInstanceHookOptions } from "./_shared.js";
 /**
- * Create-time-immutable instance configuration - combines five `AirdropBaseClient`
+ * Create-time-immutable instance configuration - combines seven `AirdropBaseClient`
  * reads into one.
  *
  * @alpha
@@ -21,13 +21,18 @@ export interface AirdropConfig {
     complianceManager: Address;
     /** Per-claim ETH fee in wei; `0` on a fee-free campaign. */
     gasFee: bigint;
+    /** Whether `extendClaimWindow` is permitted; frozen at create. */
+    canExtendClaimWindow: boolean;
+    /** The block the instance was initialized in (L2 block on Arbitrum). */
+    deploymentBlockNumber: bigint;
 }
 /** @alpha */
 export type UseAirdropConfigArgs = AirdropInstanceHookOptions<AirdropConfig>;
 /**
  * Read an airdrop instance's immutable configuration in one round trip.
  *
- * Bundles `token` / `airdropType` / `unwrappable` / `complianceManager` / `gasFee` -
+ * Bundles `token` / `airdropType` / `unwrappable` / `complianceManager` / `gasFee` /
+ * `canExtendClaimWindow` / `deploymentBlockNumber` -
  * what a UI needs before it can render anything else about a campaign, and how
  * `airdropType` and `unwrappable` get covered without shipping two more one-line hooks
  * nobody would call separately. `variant` is derived from the ordinal so a consumer can
@@ -38,7 +43,7 @@ export type UseAirdropConfigArgs = AirdropInstanceHookOptions<AirdropConfig>;
  *
  * The existing {@link useAirdropToken}, {@link useAirdropGasFee} and
  * {@link useComplianceManager} overlap this bundle and stay: they are one `eth_call`
- * rather than five, which is cheaper for a UI that needs exactly one value.
+ * rather than seven, which is cheaper for a UI that needs exactly one value.
  *
  * @example
  * const { data: config } = useAirdropConfig({ address: airdropAddress });

package/dist/fhe-airdrop/react/useAirdropPause.d.ts

@@ -21,6 +21,11 @@ export interface AirdropPauseArgs extends WriteAccountOverride {
  * `window.isActive`, so a mounted `useAirdropWindow` consumer would otherwise
  * keep showing a stale `isActive` after a pause/unpause.
  *
+ * Not invalidated: {@link usePreflightClaim} (its `PausedError` blocker) and
+ * {@link useIsSignatureValid} (which answers `false` while paused) also move with
+ * the flag. Refetch them if the same session renders both the admin toggle and a
+ * claim form.
+ *
  * @example
  * const setPause = useAirdropPause({ address: airdropAddress });
  * await setPause.mutateAsync({ paused: true });

package/dist/fhe-airdrop/react/useBuildMerkleCampaign.d.ts

@@ -1,6 +1,5 @@
 import { type UseMutationResult } from "@tanstack/react-query";
 import type { Address } from "viem";
-import { type CampaignSubmitterOption } from "../campaign.js";
 import { type EncryptorSource } from "../encryption.js";
 import type { BuiltCampaign, CampaignRecipient } from "../types.js";
 /**
@@ -23,7 +22,7 @@ export interface UseBuildMerkleCampaignOptions {
  *
  * @alpha
  */
-export interface UseBuildMerkleCampaignArgs extends CampaignSubmitterOption {
+export interface UseBuildMerkleCampaignArgs {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     /** CUMULATIVE totals per account, never per-drop tranches. */
@@ -48,10 +47,9 @@ export interface UseBuildMerkleCampaignArgs extends CampaignSubmitterOption {
  * A mutation rather than a query: encryption is randomised, so the same roster
  * builds a different root every call and there is no cache identity to key.
  *
- * Each entry is `{ account, boundTo, handle, inputProof, merkleProof }` —
- * `account` selects the leaf and the cumulative accounting, `boundTo` is the
- * only address the coprocessor accepts as sender. They are equal unless
- * `submitter` was set.
+ * Each entry is `{ account, handle, inputProof, merkleProof }` - `account`
+ * selects the leaf and the cumulative accounting. One relayer request per 32
+ * recipients, issued concurrently; every leaf is submittable by any address.
  *
  * **Invalidates:** nothing. Off-chain work only; the root is not published here.
  *

package/dist/fhe-airdrop/react/useComplianceManager.d.ts

@@ -5,8 +5,8 @@ import { type AirdropInstanceHookOptions } from "./_shared.js";
 export type UseComplianceManagerArgs = AirdropInstanceHookOptions<Address>;
 /**
  * Read an airdrop instance's own compliance-manager clone — the only
- * contract, besides the caller, ever granted ACL on that instance's
- * confidential handles.
+ * contract the instance itself grants persistent ACL on its pool and claim
+ * handles.
  *
  * @example
  * const { data: complianceManager } = useComplianceManager({ address: airdropAddress });

package/dist/fhe-airdrop/react/useComplianceManagerOf.d.ts

@@ -15,8 +15,7 @@ export interface UseComplianceManagerOfArgs extends AirdropHookOptions<Address>
  * instances it deployed, so a zero address means the instance did not come
  * from this factory - do not mount the compliance hooks on it.
  *
- * Cached indefinitely (`staleTime: Infinity`, overridable through `query`):
- * the mapping is written once, inside `createX`, and never changes.
+ * Caching follows the same write-once policy as {@link useTokenOf}.
  *
  * @remarks
  * {@link useComplianceManager} answers the same question from the other side,

package/dist/fhe-airdrop/react/useCreateAndFundEcdsaAirdrop.d.ts

@@ -1,7 +1,8 @@
 import { type UseMutationResult } from "@tanstack/react-query";
+import type { ReceiptMode } from "../../core/pending.js";
 import type { WriteAccountOverride } from "../airdrop-base.js";
 import type { FundInput } from "../factory.js";
-import type { CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams } from "../types.js";
+import type { CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams, PendingCreateAirdropResult } from "../types.js";
 import { type AirdropClientOptions } from "./_shared.js";
 /**
  * Variables for {@link useCreateAndFundEcdsaAirdrop} — the create arguments plus
@@ -9,7 +10,7 @@ import { type AirdropClientOptions } from "./_shared.js";
  *
  * @alpha
  */
-export type UseCreateAndFundEcdsaAirdropArgs = CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride;
+export type UseCreateAndFundEcdsaAirdropArgs = CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride & ReceiptMode;
 /**
  * Deploy an ECDSA-authorised airdrop instance and seed its pool in one
  * transaction.
@@ -20,19 +21,23 @@ export type UseCreateAndFundEcdsaAirdropArgs = CreateAirdropArgs<EcdsaAirdropPar
  * (plaintext, encrypted against the hook-level `encryptor`) or a pre-built
  * `encryptedInput`, never both.
  *
- * Returns `CreateAirdropResult` unflattened — `{ hash, airdrop,
- * complianceManager }`; the caller needs the instance address to do anything
- * with the campaign afterwards.
+ * Returns `CreateAirdropResult` (or `PendingCreateAirdropResult` with `waitForReceipt: false`; both carry every address) unflattened - `{ hash, airdrop,
+ * complianceManager, managerImplementation, complianceDelegate }`; the caller
+ * needs the instance address to do anything with the campaign afterwards.
  *
  * **A successful receipt does not prove the pool was funded.** An ERC-7984
  * transfer moves an encrypted zero instead of reverting when the funder is
  * short, because reverting would leak the balance.
  *
- * **Invalidates:** the factory's registry reads (`useFactoryRegistry`) for
- * this factory address, whatever page was cached — a new instance moves
- * `airdropCount()` / `airdrops()`. Nothing else: the new instance has no
- * cached reads yet, and no read hook here exposes the confidential pool
- * balance.
+ * **Safe / multisig signers:** pass `waitForReceipt: false`; see
+ * {@link ReceiptMode}.
+ *
+ * **Invalidates:** the factory's registry pages, every cached `isAirdrop` answer, every
+ * cached create preflight (the salt is now consumed), and the {@link useTokenOf} /
+ * {@link useComplianceManagerOf} entries for the new address, which may hold a zero
+ * read before the create.
+ * No read hook here caches the confidential pool balance, so the fund leg moves nothing
+ * else.
  *
  * **Never log `amount`.** It is the one plaintext confidential value this
  * hook sees — keep it out of telemetry, `onError` context and console.
@@ -52,4 +57,4 @@ export type UseCreateAndFundEcdsaAirdropArgs = CreateAirdropArgs<EcdsaAirdropPar
  *
  * @alpha
  */
-export declare function useCreateAndFundEcdsaAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, UseCreateAndFundEcdsaAirdropArgs>;
+export declare function useCreateAndFundEcdsaAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult | PendingCreateAirdropResult, Error, UseCreateAndFundEcdsaAirdropArgs>;

package/dist/fhe-airdrop/react/useCreateAndFundMerkleAirdrop.d.ts

@@ -1,7 +1,8 @@
 import { type UseMutationResult } from "@tanstack/react-query";
+import type { ReceiptMode } from "../../core/pending.js";
 import type { WriteAccountOverride } from "../airdrop-base.js";
 import type { FundInput } from "../factory.js";
-import type { CreateAirdropArgs, CreateAirdropResult, MerkleAirdropParams } from "../types.js";
+import type { CreateAirdropResult, CreateMerkleAirdropArgs, PendingCreateAirdropResult } from "../types.js";
 import { type AirdropClientOptions } from "./_shared.js";
 /**
  * Variables for {@link useCreateAndFundMerkleAirdrop} — the create arguments plus
@@ -9,7 +10,7 @@ import { type AirdropClientOptions } from "./_shared.js";
  *
  * @alpha
  */
-export type UseCreateAndFundMerkleAirdropArgs = CreateAirdropArgs<MerkleAirdropParams> & FundInput & WriteAccountOverride;
+export type UseCreateAndFundMerkleAirdropArgs = CreateMerkleAirdropArgs & FundInput & WriteAccountOverride & ReceiptMode;
 /**
  * Deploy a Merkle-proof airdrop instance and seed its pool in one transaction.
  *
@@ -20,23 +21,37 @@ export type UseCreateAndFundMerkleAirdropArgs = CreateAirdropArgs<MerkleAirdropP
  *
  * `mode: "uups"` is rejected before the wallet is even looked up, so the
  * mutation rejects without prompting for a signature. Returns
- * `CreateAirdropResult` unflattened — `{ hash, airdrop, complianceManager }`.
+ * `CreateAirdropResult` (or `PendingCreateAirdropResult` with `waitForReceipt: false`; both carry every address) unflattened - `{ hash, airdrop, complianceManager,
+ * managerImplementation, complianceDelegate }`.
  *
  * **A successful receipt does not prove the pool was funded.** An ERC-7984
  * transfer moves an encrypted zero instead of reverting when the funder is
  * short, because reverting would leak the balance.
  *
- * **Invalidates:** the factory's registry reads (`useFactoryRegistry`) for
- * this factory address, whatever page was cached — a new instance moves
- * `airdropCount()` / `airdrops()`. Nothing else.
+ * **Safe / multisig signers:** pass `waitForReceipt: false`; see
+ * {@link ReceiptMode}.
+ *
+ * **Invalidates:** the factory's registry pages, every cached `isAirdrop` answer, every
+ * cached create preflight (the salt is now consumed), and the {@link useTokenOf} /
+ * {@link useComplianceManagerOf} entries for the new address, which may hold a zero
+ * read before the create.
  *
  * **Never log `amount`.** It is the one plaintext confidential value this
  * hook sees — keep it out of telemetry, `onError` context and console.
  *
+ * **Creating from a plan.** Pass the {@link PlannedCampaign} as `plan`, with
+ * `merkleRoot: plan.root`. The create then pins `plan.predictedAddress`, refuses a root that
+ * differs from the plan's, and refuses to send once the factory's Merkle implementation has
+ * moved since the plan ({@link PredictionDriftError}). Both are checked before anything is
+ * encrypted. `expected: { airdrop: plan.predictedAddress }` is the lower-level equivalent of
+ * the pin alone.
+ *
  * @throws {@link MerkleUupsUnsupportedError} when `mode` is `"uups"`.
  * @throws {@link DeploymentAddressUnavailableError} when no factory is deployed for the connected chain.
  * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor resolves.
  * @throws {@link SaltCollisionError} when this `(mode, deployer, userSalt)` tuple already deployed an instance.
+ * @throws {@link PredictionDriftError} when `plan` is given and the factory's Merkle implementation moved since it was taken.
+ * @throws {@link InvalidArgumentError} when `params.merkleRoot` or `expected.airdrop` disagrees with `plan`.
  *
  * @example
  * const createAndFund = useCreateAndFundMerkleAirdrop({ encryptor: () => sdk.relayer });
@@ -44,9 +59,10 @@ export type UseCreateAndFundMerkleAirdropArgs = CreateAirdropArgs<MerkleAirdropP
  *   params: { common, merkleRoot: plan.root, isMerkleRootMutable: false },
  *   mode: "clone",
  *   userSalt,
+ *   plan,
  *   amount: 1_000_000n,
  * });
  *
  * @alpha
  */
-export declare function useCreateAndFundMerkleAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, UseCreateAndFundMerkleAirdropArgs>;
+export declare function useCreateAndFundMerkleAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult | PendingCreateAirdropResult, Error, UseCreateAndFundMerkleAirdropArgs>;

package/dist/fhe-airdrop/react/useCreateEcdsaAirdrop.d.ts

@@ -1,19 +1,24 @@
 import { type UseMutationResult } from "@tanstack/react-query";
-import type { CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams } from "../types.js";
+import type { ReceiptMode } from "../../core/pending.js";
+import type { CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams, PendingCreateAirdropResult } from "../types.js";
 import type { WriteAccountOverride } from "../airdrop-base.js";
 import { type AirdropClientOptions } from "./_shared.js";
 /**
  * Deploy an ECDSA-authorised airdrop instance via the factory.
  *
- * Returns the headless client's `CreateAirdropResult` unchanged — `{ hash,
- * airdrop, complianceManager }` — never flattened to just a hash: a caller
+ * Returns the headless client's `CreateAirdropResult` (or `PendingCreateAirdropResult` with `waitForReceipt: false`; both carry every address) unchanged - `{ hash,
+ * airdrop, complianceManager, managerImplementation, complianceDelegate }` -
+ * never flattened to just a hash: a caller
  * needs the deployed instance address to do anything with the campaign
  * afterwards.
  *
- * **Invalidates:** the factory's registry reads (`useFactoryRegistry`) for
- * this factory address, since a new instance changes `airdropCount()` /
- * `airdrops()`. Nothing else — the new instance has no cached reads yet, and
- * no other factory or instance state changed.
+ * **Safe / multisig signers:** pass `waitForReceipt: false`; see
+ * {@link ReceiptMode}.
+ *
+ * **Invalidates:** the factory's registry pages, every cached `isAirdrop` answer, every
+ * cached create preflight (the salt is now consumed), and the {@link useTokenOf} /
+ * {@link useComplianceManagerOf} entries for the new address, which may hold a zero
+ * read before the create.
  *
  * @example
  * const create = useCreateEcdsaAirdrop();
@@ -25,4 +30,4 @@ import { type AirdropClientOptions } from "./_shared.js";
  *
  * @alpha
  */
-export declare function useCreateEcdsaAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride>;
+export declare function useCreateEcdsaAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult | PendingCreateAirdropResult, Error, CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride & ReceiptMode>;

package/dist/fhe-airdrop/react/useCreateMerkleAirdrop.d.ts

@@ -1,16 +1,27 @@
 import { type UseMutationResult } from "@tanstack/react-query";
+import type { ReceiptMode } from "../../core/pending.js";
 import type { WriteAccountOverride } from "../airdrop-base.js";
-import type { CreateAirdropArgs, CreateAirdropResult, MerkleAirdropParams } from "../types.js";
+import type { CreateAirdropResult, CreateMerkleAirdropArgs, PendingCreateAirdropResult } from "../types.js";
 import { type AirdropClientOptions } from "./_shared.js";
 /**
  * Deploy a Merkle-proof airdrop instance via the factory.
  *
- * Returns the headless client's `CreateAirdropResult` unchanged — `{ hash,
- * airdrop, complianceManager }`.
+ * Returns the headless client's `CreateAirdropResult` (or `PendingCreateAirdropResult` with `waitForReceipt: false`; both carry every address) unchanged - `{ hash,
+ * airdrop, complianceManager, managerImplementation, complianceDelegate }`.
  *
- * **Invalidates:** the factory's registry reads (`useFactoryRegistry`) for
- * this factory address — a new instance changes `airdropCount()` /
- * `airdrops()`. Nothing else.
+ * **Safe / multisig signers:** pass `waitForReceipt: false`; see
+ * {@link ReceiptMode}.
+ *
+ * **Invalidates:** the factory's registry pages, every cached `isAirdrop` answer, every
+ * cached create preflight (the salt is now consumed), and the {@link useTokenOf} /
+ * {@link useComplianceManagerOf} entries for the new address, which may hold a zero
+ * read before the create.
+ *
+ * **Creating from a plan.** Pass the {@link PlannedCampaign} as `plan`, with
+ * `merkleRoot: plan.root`. The create then pins `plan.predictedAddress`, refuses a root that
+ * differs from the plan's, and refuses to send once the factory's Merkle implementation has
+ * moved since the plan ({@link PredictionDriftError}). `expected: { airdrop: plan.predictedAddress }`
+ * is the lower-level equivalent of the pin alone.
  *
  * @example
  * const create = useCreateMerkleAirdrop();
@@ -20,6 +31,15 @@ import { type AirdropClientOptions } from "./_shared.js";
  *   userSalt,
  * });
  *
+ * @example
+ * // From a plan (immutable root):
+ * await create.mutateAsync({
+ *   params: { ...params, merkleRoot: plan.root, isMerkleRootMutable: false },
+ *   mode: "clone",
+ *   userSalt,
+ *   plan,
+ * });
+ *
  * @alpha
  */
-export declare function useCreateMerkleAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, CreateAirdropArgs<MerkleAirdropParams> & WriteAccountOverride>;
+export declare function useCreateMerkleAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult | PendingCreateAirdropResult, Error, CreateMerkleAirdropArgs & WriteAccountOverride & ReceiptMode>;

package/dist/fhe-airdrop/react/useDedupMode.d.ts

@@ -0,0 +1,16 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { DedupMode } from "../constants.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseDedupModeArgs = AirdropInstanceHookOptions<DedupMode>;
+/**
+ * Read an ECDSA airdrop instance's replay-protection policy from the chain.
+ *
+ * The mode is frozen at creation, so `staleTime: Infinity`.
+ *
+ * @example
+ * const { data: mode } = useDedupMode({ address: airdropAddress });
+ *
+ * @alpha
+ */
+export declare function useDedupMode(args: UseDedupModeArgs): UseQueryResult<DedupMode, Error>;

package/dist/fhe-airdrop/react/useDiscloseHandleToParty.d.ts

@@ -18,9 +18,10 @@ export interface UseDiscloseHandleToPartyArgs extends WriteAccountOverride {
  * returns the transaction hash rather than an `EncryptedViewResult`; there is
  * no ACL event to parse.
  *
- * Two gates apply on-chain: the caller must itself be allowed on `handle`
- * (bypassed by `DISCLOSURE_ADMIN_ROLE`), and the *instance* must be allowed on
- * it, so a handle minted by an unrelated contract cannot be laundered through
+ * Two gates apply on-chain: the handle must be persistently user-decryptable by
+ * the caller in this instance's context (a transient allowance from a fresh FHE op
+ * does not count; `DISCLOSURE_ADMIN_ROLE` bypasses this gate), and the *instance*
+ * must be allowed on it, so a handle minted by an unrelated contract cannot be laundered through
  * this campaign. A failure of the first surfaces as `FheHandleNotAllowedError`.
  *
  * **Invalidates:** nothing. ACL is append-only and no read hook in this

package/dist/fhe-airdrop/react/useEcdsaClaim.d.ts

@@ -6,9 +6,11 @@ import { type EcdsaAirdropInstanceClientOptions } from "./_shared.js";
  * Claim a signed encrypted allocation on an `ECDSAConfidentialAirdrop`
  * instance.
  *
- * `dedupMode` must be supplied — the contract has no on-chain getter for it
- * (see {@link EcdsaAirdropClientConfig.dedupMode}); pass the same value used
- * at `createEcdsaAirdrop` time.
+ * An empty `inputProof` is accepted only for a zero handle or one the sender and the
+ * instance already hold ACL on; see `EcdsaClaimArgs.encryptedInput`.
+ *
+ * `dedupMode` is deprecated - no call branches on it. Read the
+ * instance's actual policy with `useDedupMode`.
  *
  * **Invalidates:** the `fn "isSignatureValid"` PREFIX for this instance. A successful
  * claim consumes the EIP-712 digest, so every cached signature check on this instance
@@ -16,7 +18,7 @@ import { type EcdsaAirdropInstanceClientOptions } from "./_shared.js";
  * that can no longer be claimed. Per-claim dedup state itself remains unqueryable.
  *
  * @example
- * const claim = useEcdsaClaim({ address: airdropAddress, dedupMode: "perAddress" });
+ * const claim = useEcdsaClaim({ address: airdropAddress });
  * await claim.mutateAsync({ encryptedInput, dedupId, deadline, signer, signature });
  *
  * @alpha

package/dist/fhe-airdrop/react/useEcdsaClaimAndUnwrap.d.ts

@@ -8,18 +8,25 @@ import { type EcdsaAirdropInstanceClientOptions } from "./_shared.js";
  *
  * Reverts {@link FeatureDisabledError} on a non-unwrappable campaign - gate the button
  * on `useAirdropConfig().unwrappable`. Consumes the same replay guards and EIP-712
- * digest as {@link useEcdsaClaim}.
+ * digest as {@link useEcdsaClaim}, and the same empty-proof rule.
  *
- * `dedupMode` must be supplied - the contract has no on-chain getter for it; pass the
- * same value used at `createEcdsaAirdrop` time.
+ * **The amount is public from the claim transaction.** With the stock wrapper the unwrapped
+ * amount is publicly decryptable at once (the emitted `unwrapRequestId` is its handle);
+ * `finalizeUnwrap` only releases the ERC-20. Only a plain claim keeps it confidential.
  *
- * **Invalidates:** nothing, mirroring {@link useEcdsaClaim}. Replay consumption is not
- * queryable, so no cached read in this subpath tracks the state a successful claim
- * changes. `useIsSignatureValid` DOES flip to `false` once the digest is consumed, but
- * it is not invalidated from here - refetch it yourself after a claim.
+ * `dedupMode` is deprecated - no call branches on it. Read the
+ * instance's actual policy with `useDedupMode`.
+ *
+ * Resolves to the claim's transaction hash; the underlying ERC-20 moves only at the
+ * wrapper's later `finalizeUnwrap`. Pass the hash to `useUnwrapRequest` for the
+ * `unwrapRequestId` that call takes.
+ *
+ * **Invalidates:** the `fn "isSignatureValid"` PREFIX for this instance, exactly as
+ * {@link useEcdsaClaim} does: the claim consumes the EIP-712 digest, so a cached `true`
+ * is now a guaranteed replay. Per-claim dedup state itself remains unqueryable.
  *
  * @example
- * const unwrapClaim = useEcdsaClaimAndUnwrap({ address: airdropAddress, dedupMode: "perAddress" });
+ * const unwrapClaim = useEcdsaClaimAndUnwrap({ address: airdropAddress });
  * await unwrapClaim.mutateAsync({ encryptedInput, dedupId, deadline, signer, signature, to });
  *
  * @alpha

package/dist/fhe-airdrop/react/useEcdsaDomain.d.ts

@@ -33,7 +33,7 @@ export type UseEcdsaDomainArgs = EcdsaAirdropInstanceHookOptions<EcdsaDomain>;
  * All three are bytecode/deploy constants, so `staleTime: Infinity`.
  *
  * @example
- * const { data } = useEcdsaDomain({ address: airdropAddress, dedupMode: "perAddress" });
+ * const { data } = useEcdsaDomain({ address: airdropAddress });
  * const built = data?.claimTypehash === CLAIM_TYPEHASH;
  *
  * @alpha

package/dist/fhe-airdrop/react/useEncryptCampaignAmounts.d.ts

@@ -1,6 +1,6 @@
 import { type UseMutationResult } from "@tanstack/react-query";
 import type { Address } from "viem";
-import { type CampaignSubmitterOption, type EncryptedCampaignLeaf } from "../campaign.js";
+import { type EncryptedCampaignLeaf } from "../campaign.js";
 import { type EncryptorSource } from "../encryption.js";
 import type { CampaignRecipient } from "../types.js";
 /**
@@ -22,7 +22,7 @@ export interface UseEncryptCampaignAmountsOptions {
  *
  * @alpha
  */
-export interface UseEncryptCampaignAmountsArgs extends CampaignSubmitterOption {
+export interface UseEncryptCampaignAmountsArgs {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     /** CUMULATIVE totals per account, never per-drop tranches. */
@@ -38,11 +38,9 @@ export interface UseEncryptCampaignAmountsArgs extends CampaignSubmitterOption {
  * cache identity to key. **Persist what resolves** — nothing here is
  * recoverable or reproducible.
  *
- * `submitter` decides the shape and the relayer cost. Omitted: one request per
- * recipient, issued concurrently, each input bound to that recipient, so only
- * they can claim — chunk the roster yourself if your relayer rate-limits. Set:
- * a single batched request bound to that one address, one shared `inputProof`
- * for the whole roster, and only that address can submit.
+ * One relayer request per 32 recipients, issued concurrently; every leaf is
+ * submittable by any address. Split the roster yourself if your relayer
+ * rate-limits.
  *
  * **Invalidates:** nothing. Pure off-chain relayer work — no contract state
  * moves, so no cached read goes stale.

package/dist/fhe-airdrop/react/useExtendClaimWindow.d.ts

@@ -8,7 +8,10 @@ import { type AirdropInstanceClientOptions } from "./_shared.js";
  * `canExtendClaimWindow: true`.
  *
  * **Invalidates:** only this instance's `useAirdropWindow` entry — `endTime`
- * is one of the five fields that hook bundles.
+ * is one of the five fields that hook bundles. Not invalidated: the window
+ * blockers of {@link usePreflightClaim} and a cached `false` from
+ * {@link useIsSignatureValid}, both of which a later `endTime` can move; refetch
+ * them if the same session renders a claim form.
  *
  * @example
  * const extend = useExtendClaimWindow({ address: airdropAddress });