@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

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

@@ -0,0 +1,21 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseIsMerkleRootMutableArgs = AirdropInstanceHookOptions<boolean>;
+/**
+ * Whether this `MerkleConfidentialAirdrop` instance permits root rotation at
+ * all. This is the read that decides whether a UI offers `useSetMerkleRoot` -
+ * on a `false` instance the rotation reverts with `FeatureDisabledError`
+ * (`feature: "merkleRootRotation"`) rather than failing a role check.
+ *
+ * **Fixed at create time, never toggled** - hence `staleTime: Infinity` and
+ * hence deliberately NOT bundled with {@link useMerkleRoot}, which rotates.
+ * Bundling would refetch an immutable value on every rotation and would force
+ * `useSetMerkleRoot`'s single-key invalidation to become coarser.
+ *
+ * @example
+ * const { data: canRotate } = useIsMerkleRootMutable({ address: merkleAirdropAddress });
+ *
+ * @alpha
+ */
+export declare function useIsMerkleRootMutable(args: UseIsMerkleRootMutableArgs): UseQueryResult<boolean, Error>;

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

@@ -0,0 +1,46 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import { type EcdsaAirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseIsSignatureValidArgs extends EcdsaAirdropInstanceHookOptions<boolean> {
+    /** The address the signature was made out to. The digest binds `msg.sender`, so the read is simulated FROM this address. */
+    recipient?: Address;
+    /** The external encrypted allocation handle. No input proof: a view never calls `FHE.fromExternal`. */
+    encryptedAmountHandle?: Hex;
+    /** The off-chain claim id bound into the signature. */
+    dedupId?: Hex;
+    /** Unix seconds the signature expires at. */
+    deadline?: bigint;
+    /** The `SIGNER_ROLE` holder that authorized the claim. */
+    signer?: Address;
+    /** The EIP-712 signature from `signClaimAuthorization`. */
+    signature?: Hex;
+}
+/**
+ * Whether an ECDSA claim authorization would be accepted right now for `recipient`,
+ * without spending an FHE op or a transaction.
+ *
+ * Never reverts - `false` covers every failure mode (paused, outside the claim window,
+ * 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.
+ *
+ * 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`.
+ *
+ * @example
+ * const { data: claimable } = useIsSignatureValid({
+ *   address: airdropAddress,
+ *   dedupMode: "perAddress",
+ *   recipient, encryptedAmountHandle, dedupId, deadline, signer, signature,
+ * });
+ *
+ * @alpha
+ */
+export declare function useIsSignatureValid(args: UseIsSignatureValidArgs): UseQueryResult<boolean, Error>;

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

@@ -0,0 +1,22 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { MerkleClaimArgs } from "../merkle.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * Claim the outstanding amount for a proof-bearing entry on a
+ * `MerkleConfidentialAirdrop` instance.
+ *
+ * **Invalidates:** `useClaimedAmount` for `entry.account` on this instance — the read
+ * whose cumulative-delivered value a successful claim changes. The contract advances
+ * `claimedAmount[account]`, keyed on the entry's claim identity and NOT on whoever sent
+ * the transaction, so a relayed claim must invalidate the recipient's cache entry rather
+ * than the relayer's. Other accounts' cached reads, and every other instance's cache,
+ * are left untouched.
+ *
+ * @example
+ * const claim = useMerkleClaim({ address: airdropAddress });
+ * await claim.mutateAsync({ entry }); // relayers pass a relayed entry unchanged
+ *
+ * @alpha
+ */
+export declare function useMerkleClaim(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, MerkleClaimArgs>;

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

@@ -0,0 +1,29 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { MerkleClaimArgs } from "../merkle.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * Claim a proof-bearing Merkle entry and route the allocation straight into the
+ * wrapper's unwrap, making `to` the underlying ERC-20 beneficiary.
+ *
+ * **Self-only, unlike {@link useMerkleClaim}.** This entrypoint takes no claim identity:
+ * the leaf, the accounting and the input proof are all `msg.sender`, so an entry whose
+ * `account` is not the submitter is refused before the write. Gate the button on
+ * `submitter === entry.account` and fall back to `useMerkleClaim` for relayed claims.
+ * Also requires an unwrappable campaign - see `useAirdropConfig().unwrappable`.
+ *
+ * **Invalidates:** `useClaimedAmount` for the SENDING account on this instance. The
+ * contract advances `claimedAmount[msg.sender]` here, so the key is built from the
+ * sender resolved in `onMutate` (`variables.account ?? walletClient.account`) and NOT
+ * from `entry.account` the way {@link useMerkleClaim} does it. The two identities are
+ * equal on this path by construction - the client refuses a mismatch - but the
+ * divergence is deliberate: `claim` records the explicit claim identity, this records
+ * the caller. Do not unify them.
+ *
+ * @example
+ * const unwrapClaim = useMerkleClaimAndUnwrap({ address: airdropAddress });
+ * await unwrapClaim.mutateAsync({ entry, to: erc20Beneficiary });
+ *
+ * @alpha
+ */
+export declare function useMerkleClaimAndUnwrap(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, MerkleClaimArgs>;

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

@@ -0,0 +1,15 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseMerkleRootArgs = AirdropInstanceHookOptions<Hex>;
+/**
+ * Read a `MerkleConfidentialAirdrop` instance's currently published root.
+ * Proofs presented to `useMerkleClaim` must verify against this exact value.
+ *
+ * @example
+ * const { data: root } = useMerkleRoot({ address: merkleAirdropAddress });
+ *
+ * @alpha
+ */
+export declare function useMerkleRoot(args: UseMerkleRootArgs): UseQueryResult<Hex, Error>;

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

@@ -0,0 +1,53 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import { type PlanMerkleCampaignArgs, type PlannedCampaign } from "../campaign.js";
+import { type AirdropClientOptions } from "./_shared.js";
+/**
+ * Variables for {@link usePlanMerkleCampaign} — the create arguments the campaign
+ * is planned against. The factory client and the encryptor come from the hook
+ * options instead.
+ *
+ * @alpha
+ */
+export type UsePlanMerkleCampaignArgs = Omit<PlanMerkleCampaignArgs, "factory" | "encryptor">;
+/**
+ * Build a campaign for a Merkle instance that does not exist yet, so its root
+ * can be baked in at create time — the **immutable-root** path.
+ *
+ * That path is otherwise circular: the root must be known before
+ * `createMerkleAirdrop`, the root depends on every ciphertext, and every
+ * ciphertext binds to an instance address the create has not produced. This
+ * hook breaks it with the factory's CREATE2 prediction oracle, then feeds
+ * `root` to {@link useCreateMerkleAirdrop} (or
+ * {@link useCreateAndFundMerkleAirdrop}) with the SAME `mode`, `creator` and
+ * `userSalt`. `initCodeHashAfter` is what `preflightCreateAirdrop`'s
+ * `expectedInitCodeHash` wants.
+ *
+ * **Surface {@link PredictionDriftError}, never swallow it.** It means the
+ * factory's Merkle implementation pointer moved mid-build, so every entry is
+ * bound to an address the create will not produce. There is no on-chain repair
+ * on an immutable-root instance — the only remedy is a fresh plan.
+ *
+ * **The returned `entries` ARE the campaign — persist them.** The chain keeps
+ * only the root, so a recipient without their own
+ * `(handle, inputProof, merkleProof)` triple can never claim. Also pick a
+ * fresh `userSalt` per campaign: two campaigns sharing
+ * `(variant, mode, creator, userSalt)` predict the same address however
+ * different their params.
+ *
+ * **Invalidates:** nothing. Two init-code-hash reads and a prediction — no
+ * state moves until the create lands.
+ *
+ * @throws {@link DeploymentAddressUnavailableError} when no factory is deployed for the connected chain.
+ * @throws {@link PredictionDriftError} when the factory's Merkle implementation pointer moved mid-build.
+ * @throws {@link InvalidArgumentError} on a duplicate, zero-address or out-of-`uint64`-range roster entry.
+ * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
+ *
+ * @example
+ * const plan = usePlanMerkleCampaign({ encryptor: () => sdk.relayer });
+ * const { root, entries, predictedAddress } = await plan.mutateAsync({
+ *   params, mode: "clone", creator, userSalt, recipients,
+ * });
+ *
+ * @alpha
+ */
+export declare function usePlanMerkleCampaign(options?: AirdropClientOptions): UseMutationResult<PlannedCampaign, Error, UsePlanMerkleCampaignArgs>;

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

@@ -0,0 +1,46 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import type { PreflightResult } from "../../core/preflight.js";
+import type { DedupMode } from "../constants.js";
+import type { AirdropVariant } from "../errors.js";
+import { type EcdsaClaimPreflightSignature } from "../guards.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UsePreflightClaimArgs extends AirdropInstanceHookOptions<PreflightResult> {
+    /** Which variant this instance is - picks the client the preflight reads through. */
+    variant: AirdropVariant;
+    /** ECDSA campaigns only; ignored on `variant: "merkle"`. Defaults to `"none"`. */
+    dedupMode?: DedupMode;
+    /** The account that will SEND the claim and therefore pays the exact-equality gas fee. On a relayed Merkle claim this is the relayer. */
+    claimant?: Address;
+    /** Merkle campaigns only: the claim identity, when it is not the submitter. Defaults to `claimant`. */
+    account?: Address;
+    /** The payout destination, if one will be passed. */
+    to?: Address;
+    /** Set for `claimAndUnwrap`, which is always submitted for the caller. */
+    entrypoint?: "claim" | "claimAndUnwrap";
+    /** ECDSA campaigns only: adds the authorisation check to the report. */
+    signature?: EcdsaClaimPreflightSignature;
+}
+/**
+ * Report what would stop a claim right now - chain support, the pause flag, both ends of
+ * the claim window, whether `claimant` can cover the exact-equality gas fee, the Merkle
+ * argument-relation rules when `account`/`entrypoint` are given, and for an ECDSA
+ * campaign given `signature`, whether the authorisation is valid and unconsumed.
+ *
+ * **`ready: true` does not mean the claimant has anything to claim.** The allocation is
+ * encrypted, so an SDK-side "nothing to claim" would require decrypting it; this checks
+ * only what is decidable without the ciphertext. Use it to disable a button, not to
+ * promise a payout.
+ *
+ * Every field below `variant` feeds the blockers and is therefore part of the cache key.
+ * The fee check reads `claimant`'s live ETH balance, so keep `staleTime` short - the
+ * default 0 is right for a claim button.
+ *
+ * @example
+ * const { data } = usePreflightClaim({ address: airdropAddress, variant: "merkle", claimant });
+ * <button disabled={!data?.ready}>Claim</button>
+ *
+ * @alpha
+ */
+export declare function usePreflightClaim(args: UsePreflightClaimArgs): UseQueryResult<PreflightResult, Error>;

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

@@ -1,51 +1,67 @@
 import { type UseQueryResult } from "@tanstack/react-query";
 import type { Address, Hex } from "viem";
-import type { AirdropParams, CreateAirdropPreflightReport } from "../types.js";
-import { type BaseHookOptions } from "./_shared.js";
-export interface UsePreflightCreateAirdropArgs extends BaseHookOptions {
-    /** The airdrop parameters that will be passed to the create call. */
-    params?: AirdropParams;
-    /** The address that will send the create transaction (`msg.sender`). */
+import type { PreflightResult } from "../../core/preflight.js";
+import type { DeploymentMode } from "../constants.js";
+import type { EcdsaAirdropParams, MerkleAirdropParams } from "../types.js";
+import { type AirdropHookOptions } from "./_shared.js";
+/** The variant-independent half of {@link UsePreflightCreateAirdropArgs}. */
+/** @alpha */
+export interface PreflightCreateAirdropCommon extends AirdropHookOptions<PreflightResult> {
+    mode?: DeploymentMode;
+    /** The account that will send `create*`. CREATE2 salts are per-deployer. */
     creator?: Address;
-    /**
-     * The `userSalt` planned for the create call. Optional — when supplied, the
-     * report also carries `predictedAirdrop` and `alreadyDeployed`.
-     */
     userSalt?: Hex;
     /**
-     * Set `true` when the plan is `useCreateAndFundConfidentialAirdrop` — a
-     * missing factory-operator approval then becomes a blocker instead of
-     * informational `isFactoryOperator` state.
+     * Pass `plan.initCodeHashAfter` to turn the implementation-drift check on.
+     * Omitting it skips that one check.
      */
-    funding?: boolean;
+    expectedInitCodeHash?: Hex;
 }
 /**
- * Read-only preflight for `useCreateConfidentialAirdrop` /
- * `useCreateAndFundConfidentialAirdrop` — wraps
- * {@link ConfidentialAirdropFactoryClient.preflightCreateAirdrop} as a
- * TanStack query.
+ * `variant` and `params` are correlated, mirroring the headless
+ * `PreflightCreateArgs` discriminated union rather than widening to a
+ * cross-product (CLAUDE.md Pitfall #2). The all-undefined member is what lets
+ * a component call the hook unconditionally while a create form fills in.
+ *
+ * @alpha
+ */
+export type UsePreflightCreateAirdropArgs = PreflightCreateAirdropCommon & ({
+    variant?: undefined;
+    params?: undefined;
+} | {
+    variant: "ecdsa";
+    params?: EcdsaAirdropParams;
+} | {
+    variant: "merkle";
+    params?: MerkleAirdropParams;
+});
+/**
+ * Read-only preflight for `useCreateEcdsaAirdrop` / `useCreateMerkleAirdrop`.
+ * Runs every create-time guardrail the write path enforces - chain support,
+ * the Merkle/UUPS refusal, the creator's effective upgradeability policy for
+ * `mode: "uups"`, the stock-wrapper probe when `params.common.unwrappable` is
+ * set, a salt collision on the predicted address, and implementation drift
+ * when `expectedInitCodeHash` is supplied.
  *
- * The report carries `isFactoryOperator`, `gasFee`, `predictedAirdrop`,
- * `alreadyDeployed`, `ready`, `blockers` (human-readable strings) and
- * `blockerErrors` (typed `TokenOpsSdkError`s, index-aligned with `blockers` —
- * branch on `error.code`).
+ * **The point is disabling the submit button, not catching after the fact.**
+ * `blockers` carries the same typed errors `create*` would have thrown, so a
+ * UI branches on `error.code` here exactly as it does in `onError`.
  *
- * Checks: structural `params` validation (non-zero token/admin, timestamp
- * ordering, end time in the future), ERC-7984 operator approval of the
- * factory on `params.token` (blocker only with `funding: true`), and — when
- * `userSalt` is set — whether a clone already exists at the predicted CREATE2
- * address. The creator's confidential token balance is NOT checked
- * (encrypted; an underfunded create-and-fund silently moves an encrypted
- * zero) — see the headless method's TSDoc.
+ * Disabled until `variant`, `params`, `mode`, `creator` and `userSalt` are all
+ * set. Refetch after the user changes their target mode or the factory's
+ * implementation pointer moves.
  *
- * Hook is disabled until `params` and `creator` are both set. Refetch after
- * the user calls `setOperator` (e.g. via `queryClient.invalidateQueries` or a
- * `refetchInterval`).
+ * @remarks
+ * Named `…Airdrop` rather than `…Create` so a consumer importing both this and
+ * `/fhe-vesting/react`'s `usePreflightCreateVesting` has no collision.
  *
  * @example
  * const { data: report } = usePreflightCreateAirdrop({
- *   params, creator, userSalt, funding: true,
+ *   variant: "merkle", params, mode: "clone", creator, userSalt,
+ *   expectedInitCodeHash: plan.initCodeHashAfter,
  * });
- * if (report?.ready) { /* enable submit *\/ }
+ * const canSubmit = report?.ready === true;
+ *
+ * @alpha
  */
-export declare function usePreflightCreateAirdrop(args?: UsePreflightCreateAirdropArgs): UseQueryResult<CreateAirdropPreflightReport, Error>;
+export declare function usePreflightCreateAirdrop(args?: UsePreflightCreateAirdropArgs): UseQueryResult<PreflightResult, Error>;

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

@@ -0,0 +1,30 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface RescueERC20Args extends WriteAccountOverride {
+    /** The stranded plain ERC-20. Never the campaign's own token, which is ERC-7984. */
+    token: Address;
+    /** Where the swept balance goes. */
+    recipient: Address;
+}
+/**
+ * Sweep a plain ERC-20 that was sent to an airdrop instance by mistake.
+ * Requires `RESCUER_ROLE`.
+ *
+ * The campaign's own token is ERC-7984, not ERC-20, so the distribution pool
+ * cannot be reached through this path at all — use
+ * {@link useWithdrawConfidential} (`TREASURY_ROLE`) for the pool, and
+ * {@link useRescueOtherConfidentialToken} for a stranded ERC-7984.
+ *
+ * **Invalidates:** nothing. This subpath has no read hook over arbitrary
+ * ERC-20 balances held by the instance.
+ *
+ * @example
+ * const rescue = useRescueERC20({ address: airdropAddress });
+ * await rescue.mutateAsync({ token: strandedErc20, recipient: treasuryAddress });
+ *
+ * @alpha
+ */
+export declare function useRescueERC20(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, RescueERC20Args>;

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

@@ -0,0 +1,34 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface RescueOtherConfidentialTokenArgs extends WriteAccountOverride {
+    /**
+     * The stranded ERC-7984. Passing the campaign's own token reverts
+     * `CannotRescueAirdropToken`.
+     */
+    token: Address;
+    /** Where the swept balance goes. */
+    recipient: Address;
+}
+/**
+ * Sweep a *different* ERC-7984 token that was sent to an airdrop instance by
+ * mistake. Requires `RESCUER_ROLE`.
+ *
+ * Passing the campaign's own token reverts `CannotRescueAirdropToken` — the
+ * guard that stops a rescuer draining the distribution pool without
+ * `TREASURY_ROLE`. Compare `token` against `useAirdropConfig().data?.token`
+ * before submitting so the user is told before paying gas, and route pool
+ * sweeps through {@link useWithdrawConfidential} instead.
+ *
+ * **Invalidates:** nothing. This subpath has no read hook over third-party
+ * confidential balances held by the instance.
+ *
+ * @example
+ * const rescue = useRescueOtherConfidentialToken({ address: airdropAddress });
+ * await rescue.mutateAsync({ token: strandedErc7984, recipient: treasuryAddress });
+ *
+ * @alpha
+ */
+export declare function useRescueOtherConfidentialToken(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, RescueOtherConfidentialTokenArgs>;

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

@@ -0,0 +1,37 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface RevokeComplianceDelegateArgs extends WriteAccountOverride {
+    /** The client delegate to revoke. Must currently be active, and must not be the platform delegate. */
+    delegate: Address;
+}
+/**
+ * Revoke a client delegate's user-decryption delegation. `options.address` is
+ * the CLONE. Requires `DELEGATION_ADMIN_ROLE` on it.
+ *
+ * **Cannot revoke the platform compliance delegate** - that slot is
+ * irrevocable by construction, and targeting it reverts. Only the addresses in
+ * {@link useComplianceInfo}'s `clientDelegates` are revocable.
+ *
+ * The same gateway lag applies on the way out: the revocation is effective
+ * on-chain immediately, but a revoked delegate may still complete a delegated
+ * decrypt for a short window afterwards.
+ *
+ * **Invalidates:** this clone's {@link useComplianceInfo} entry and its
+ * {@link useIsActiveDelegate} entry for exactly `delegate`, both keyed on the
+ * clone address.
+ *
+ * @remarks
+ * Not in the same block as {@link useAddComplianceDelegate} for the same
+ * delegate - the FHEVM ACL refuses both writes at one height with an opaque
+ * revert.
+ *
+ * @example
+ * const revoke = useRevokeComplianceDelegate({ address: managerAddress });
+ * await revoke.mutateAsync({ delegate: formerOfficer });
+ *
+ * @alpha
+ */
+export declare function useRevokeComplianceDelegate(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, RevokeComplianceDelegateArgs>;

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

@@ -0,0 +1,52 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type CampaignSubmitterOption, type RotatedCampaign } from "../campaign.js";
+import type { CampaignRecipient } from "../types.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * Variables for {@link useRotateMerkleRoot}.
+ *
+ * @alpha
+ */
+export interface UseRotateMerkleRootArgs extends CampaignSubmitterOption, WriteAccountOverride {
+    /** The FULL updated roster, carrying each account's new CUMULATIVE total — never the delta since the last root. */
+    recipients: readonly CampaignRecipient[];
+}
+/**
+ * Rebuild a campaign against updated totals and publish the new root in one
+ * call.
+ *
+ * **`recipients` must carry CUMULATIVE totals, not deltas.** `claimedAmount`
+ * survives a rotation and a claim pays
+ * `newTotal - min(newTotal, alreadyDelivered)`, so passing increments pays the
+ * increment minus everything already delivered — encrypted zero for most
+ * rosters. A total below what an account already received pays nothing; a
+ * rotation cannot claw back.
+ *
+ * The root is published LAST, so a failed rebuild leaves the previous campaign
+ * intact and claimable. Once it lands the old proofs stop verifying:
+ * **distribute the new entries to every recipient**, including those whose
+ * total did not change, or they are stuck.
+ *
+ * Requires `MERKLE_ADMIN_ROLE` and an instance created with
+ * `isMerkleRootMutable: true`. Distinct from {@link useSetMerkleRoot}, which
+ * publishes a root you already built.
+ *
+ * **Invalidates:** this instance's `useMerkleRoot` entry only. Explicitly NOT
+ * `useClaimedAmount`: a rotation changes no account's delivered total (it is
+ * keyed by account, not by root), so invalidating it would fan out a pointless
+ * RPC per mounted recipient row.
+ *
+ * @throws {@link FeatureDisabledError} when the instance was created with `isMerkleRootMutable: false`.
+ * @throws {@link InvalidArgumentError} on a duplicate, zero-address or out-of-`uint64`-range roster entry.
+ * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
+ *
+ * @example
+ * const rotate = useRotateMerkleRoot({ address: airdrop, encryptor: () => sdk.relayer });
+ * const { root, entries, hash } = await rotate.mutateAsync({
+ *   recipients: [{ recipient: alice, cumulativeTotal: 1_500_000n }], // was 1_000_000n
+ * });
+ *
+ * @alpha
+ */
+export declare function useRotateMerkleRoot(options: AirdropInstanceClientOptions): UseMutationResult<RotatedCampaign, Error, UseRotateMerkleRootArgs>;

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

@@ -0,0 +1,22 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * Rotate the published root on a `MerkleConfidentialAirdrop` instance.
+ * Requires `MERKLE_ADMIN_ROLE`.
+ *
+ * **Invalidates:** only this instance's `useMerkleRoot` entry — a rotation
+ * on one campaign must never blow away another campaign's cached root
+ * (CLAUDE.md-adjacent requirement for this subpath: precise, not
+ * namespace-wide, invalidation).
+ *
+ * @example
+ * const setRoot = useSetMerkleRoot({ address: airdropAddress });
+ * await setRoot.mutateAsync({ newRoot });
+ *
+ * @alpha
+ */
+export declare function useSetMerkleRoot(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, {
+    newRoot: Hex;
+} & WriteAccountOverride>;

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

@@ -1,31 +1,42 @@
 import { type UseMutationResult } from "@tanstack/react-query";
 import type { Address, Hex } from "viem";
-export interface UseSignClaimAuthorizationArgs {
-    /** The deployed airdrop clone address (EIP-712 verifying contract). */
-    airdropAddress: Address;
-    /** Address authorised to claim. */
+import type { Signature } from "../../core/brands.js";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface SignClaimAuthorizationArgs extends WriteAccountOverride {
+    /** The account the signature entitles. Bound into the digest. */
     recipient: Address;
-    /** `externalEuint64` handle bytes32 — pass `encrypted.handle` from `encryptUint64`. */
+    /** The 32-byte encrypted-amount handle the recipient will present with this signature. */
     encryptedAmountHandle: Hex;
-}
-export interface UseSignClaimAuthorizationOptions {
-    /** Override the chain id used for the wagmi `useWalletClient` lookup. Defaults to the connected chain. */
-    chainId?: number;
+    /** Replay-scoping id, interpreted per the instance's deploy-time `dedupMode`. */
+    dedupId: Hex;
+    /** Unix seconds after which the signature is worthless. */
+    deadline: bigint;
 }
 /**
- * Sign a `Claim(address recipient, bytes32 encryptedAmount)` EIP-712
- * authorization. The signer (pulled from wagmi's `useWalletClient()`) must
- * hold `DEFAULT_ADMIN_ROLE` on the airdrop clone for the produced signature
- * to be accepted by {@link useClaim} / {@link useAccessClaimAmount}.
+ * Sign a v2 `Claim(address recipient, bytes32 encryptedAmount, bytes32
+ * dedupId, uint256 deadline)` authorization for an `ECDSAConfidentialAirdrop`
+ * instance. The signer must hold `SIGNER_ROLE` on that instance.
+ *
+ * `airdrop` and `chainId` come from the hook's own options, so a component
+ * supplies only the claim fields.
  *
- * Mutation throws {@link TokenOpsSdkError} if no wallet is connected.
+ * **Under `perDedupId` and `none` the contract enforces no per-recipient
+ * ceiling.** Every mode consumes the EIP-712 digest, so the exact signature
+ * bytes cannot be replayed - but under `perDedupId` the same ciphertext
+ * signed for two different `dedupId`s is claimable twice, and under `none`
+ * every distinct signature is independently claimable with no on-chain
+ * ceiling at all. The signing UI is then the ONLY bound on total payout. See
+ * {@link signClaimAuthorization}.
+ *
+ * **Invalidates:** nothing. The signature is produced off-chain and lands no
+ * transaction, so no cached read moves until the recipient claims.
  *
  * @example
- * const sign = useSignClaimAuthorization();
- * const signature = await sign.mutateAsync({
- *   airdropAddress,
- *   recipient,
- *   encryptedAmountHandle: encrypted.handle,
- * });
+ * const sign = useSignClaimAuthorization({ address: airdropAddress });
+ * const signature = await sign.mutateAsync({ recipient, encryptedAmountHandle, dedupId, deadline });
+ *
+ * @alpha
  */
-export declare function useSignClaimAuthorization(options?: UseSignClaimAuthorizationOptions): UseMutationResult<Hex, Error, UseSignClaimAuthorizationArgs>;
+export declare function useSignClaimAuthorization(options: AirdropInstanceClientOptions): UseMutationResult<Signature, Error, SignClaimAuthorizationArgs>;

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

@@ -0,0 +1,23 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * Sweep an airdrop instance's entire remaining confidential balance to
+ * `recipient`. Requires `TREASURY_ROLE`. The amount is not a parameter and
+ * never appears in plaintext anywhere — the contract reads its own encrypted
+ * balance and moves all of it.
+ *
+ * **Invalidates:** nothing. No read hook in this subpath's list exposes the
+ * confidential pool balance (see {@link useFundAirdrop}'s TSDoc for the same
+ * reasoning), so there is no cached query left stale by a withdrawal.
+ *
+ * @example
+ * const withdraw = useWithdrawConfidential({ address: airdropAddress });
+ * await withdraw.mutateAsync({ recipient: treasuryAddress });
+ *
+ * @alpha
+ */
+export declare function useWithdrawConfidential(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, {
+    recipient: Address;
+} & WriteAccountOverride>;