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

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 });

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

@@ -11,14 +11,21 @@ export interface FactoryFees {
     feeCollector: Address;
     /** Wei charged per claim on a fee-charging campaign, absent a per-creator custom fee. */
     defaultGasFee: bigint;
+    /**
+     * The factory's own ceiling, in wei. Bounds both fee setters and the fee
+     * resolved at create, so it is the upper bound a `maxAcceptedGasFee` ever
+     * has to clear.
+     */
+    maxGasFee: bigint;
 }
 /** @alpha */
 export type UseFactoryFeesArgs = AirdropHookOptions<FactoryFees>;
 /**
- * Read the airdrop factory's default fee configuration — `feeCollector` and
- * `defaultGasFee` in one round trip. For a specific creator's override, read
- * `factory.getCustomFee(creator)` from the headless client directly (not
- * wrapped here — see the module's scope-discipline note).
+ * Read the airdrop factory's chain-wide fee configuration: `feeCollector`,
+ * `defaultGasFee` and `maxGasFee` in one round trip. For the number a specific
+ * creator's `maxAcceptedGasFee` is actually checked against, use
+ * `factory.resolveGasFee(creator)` from the headless client: it folds in that
+ * creator's `getCustomFee` override, which this hook does not read.
  *
  * @example
  * const { data: fees } = useFactoryFees();

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

@@ -15,10 +15,9 @@ import { type AirdropClientOptions } from "./_shared.js";
  * `MissingEncryptorError` only if neither resolves — no encryptor
  * indirection needs duplicating here.
  *
- * **Invalidates:** nothing. No read hook in this subpath's list exposes the
- * confidential pool balance (`adminGetCurrentBalance` is disclosure-gated
- * and intentionally not wrapped here), so there is no cached query this
- * write could leave stale.
+ * **Invalidates:** nothing. No read hook in this subpath caches the confidential
+ * pool balance (`useAdminGetCurrentBalance` is a mutation, so there is nothing to
+ * invalidate).
  *
  * **Never log `amount`.** It is the one plaintext confidential value this
  * hook ever sees — do not pass it to telemetry, `onError` context, or a

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

@@ -22,7 +22,8 @@ export interface GrantInstanceRolesArgs {
  * (regardless of which role/holder pair), since a role split can touch
  * several roles across several accounts in one call and the SDK does not
  * duplicate the on-chain role-constant lookup client-side to invalidate more
- * narrowly. Scoped to this instance only — other campaigns' role caches are
+ * narrowly. It also invalidates every `useAirdropRoleMembers` entry for this
+ * instance. Scoped to this instance only - other campaigns' role caches are
  * untouched.
  *
  * @example

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

@@ -0,0 +1,44 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseIsAirdropArgs extends AirdropHookOptions<boolean> {
+    /** The address to check against the factory's registry. */
+    candidate?: Address;
+}
+/**
+ * Ask the canonical factory whether it created `candidate` - the genuineness
+ * check (audit-10).
+ *
+ * **Run this before trusting an address a user pasted, a link carried, or an
+ * indexer returned.** A look-alike instance with the same ABI, the same events
+ * and a pool the attacker controls is cheap to deploy, and nothing readable at
+ * the instance tells it apart. A claim against one succeeds and delivers
+ * nothing.
+ *
+ * The factory this asks is the one resolved from `src/core/addresses.ts` for
+ * the connected chain, which is what makes the answer worth anything: an
+ * instance that names its own factory names a fake one.
+ *
+ * **Only a `true` is cached.** The registry is append-only, so a `true` can
+ * never become `false` and is safe to hold forever. A `false` is not stable:
+ * the address can be created later by another tab, another service, or the
+ * headless client, none of which reaches this hook's invalidations - so caching
+ * it would serve a stale false negative indefinitely and, for a security check,
+ * in the direction that blocks a legitimate claim. Negative answers therefore
+ * stay fresh and refetch normally. Override either with `query.staleTime`.
+ *
+ * **The `address` override is the trust root.** Like every factory hook this
+ * accepts `address`, and `useMemoAirdropFactoryClient` prefers it over
+ * `src/core/addresses.ts`. That is what makes the hook usable on a local chain,
+ * but it also means an attacker-supplied factory address would answer `true`
+ * for its own look-alike. Pass `address` only from a source you trust at least
+ * as much as the registry; when in doubt, omit it.
+ *
+ * @example
+ * const { data: genuine } = useIsAirdrop({ candidate: fromUrl });
+ * if (genuine === false) return <Warning address={fromUrl} />;
+ *
+ * @alpha
+ */
+export declare function useIsAirdrop(args?: UseIsAirdropArgs): UseQueryResult<boolean, Error>;

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

@@ -24,20 +24,21 @@ export interface UseIsSignatureValidArgs extends EcdsaAirdropInstanceHookOptions
  * past `deadline`, `signer` lacking `SIGNER_ROLE`, an invalid signature, a consumed
  * digest, or an already-deduped claim). `recipient` is load-bearing and part of the
  * cache key: the read is an `eth_call` FROM that address, so passing the wrong one
- * returns `false` for a signature that would otherwise succeed.
+ * returns `false` for a signature that would otherwise succeed. A `SIGNER_ROLE` key that
+ * has been EIP-7702-delegated makes every voucher read `false`; see
+ * `EcdsaAirdropClient.isSignatureValid`.
  *
  * Stays disabled until all six signature fields are defined, so a UI can call it
  * unconditionally while a form fills in.
  *
  * @remarks
  * A successful {@link useEcdsaClaim} / {@link useEcdsaClaimAndUnwrap} flips this to
- * `false` by consuming the digest, but neither claim hook invalidates it - refetch it
- * yourself after a claim rather than trusting a cached `true`.
+ * `false` by consuming the digest; both invalidate it on success. A claim sent outside
+ * these hooks (headless client, another tab) does not, so refetch in that case.
  *
  * @example
  * const { data: claimable } = useIsSignatureValid({
  *   address: airdropAddress,
- *   dedupMode: "perAddress",
  *   recipient, encryptedAmountHandle, dedupId, deadline, signer, signature,
  * });
  *

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

@@ -13,9 +13,12 @@ import { type AirdropInstanceClientOptions } from "./_shared.js";
  * than the relayer's. Other accounts' cached reads, and every other instance's cache,
  * are left untouched.
  *
+ * Anyone may submit an entry; see {@link MerkleClaimArgs.entry} for what a third-party
+ * submission costs the recipient, and check `useClaimedAmount` first.
+ *
  * @example
  * const claim = useMerkleClaim({ address: airdropAddress });
- * await claim.mutateAsync({ entry }); // relayers pass a relayed entry unchanged
+ * await claim.mutateAsync({ entry }); // any address may pass the entry unchanged
  *
  * @alpha
  */