@tokenops/sdk 1.5.1 → 2.0.0-alpha.1

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

@@ -1,11 +1,16 @@
 import { type UseQueryResult } from "@tanstack/react-query";
-import { type AirdropHookOptions } from "./_shared.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseAirdropGasFeeArgs = AirdropInstanceHookOptions<bigint>;
 /**
- * Read the airdrop clone's immutable per-claim gas fee (in wei). Attached as
- * `msg.value` by `claim()` automatically when the consumer doesn't pass
- * `value` explicitly.
+ * Read the per-claim ETH fee (wei) an instance charges; `0n` on a fee-free
+ * campaign. Every claim entrypoint (`useEcdsaClaim` / `useMerkleClaim`)
+ * reads this itself and attaches it as `value` — this hook is for a UI that
+ * wants to display the fee before the claimant submits.
  *
  * @example
  * const { data: gasFee } = useAirdropGasFee({ address: airdropAddress });
+ *
+ * @alpha
  */
-export declare function useAirdropGasFee(options: AirdropHookOptions): UseQueryResult<bigint, Error>;
+export declare function useAirdropGasFee(args: UseAirdropGasFeeArgs): UseQueryResult<bigint, Error>;

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

@@ -1,14 +1,23 @@
 import { type UseQueryResult } from "@tanstack/react-query";
 import type { Address, Hex } from "viem";
-import { type AirdropHookOptions } from "./_shared.js";
-export interface UseAirdropHasRoleArgs extends AirdropHookOptions {
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseAirdropHasRoleArgs extends AirdropInstanceHookOptions<boolean> {
+    /** A `bytes32` role identifier — read it from the headless client's role getters (`PAUSER_ROLE()`, etc.), not hand-hashed. */
     role?: Hex;
-    account?: Address;
+    /** The account to check. */
+    holder?: Address;
 }
 /**
- * Read AccessControl: is `account` a member of `role` on this airdrop clone?
+ * Whether `holder` holds `role` on an airdrop instance.
  *
- * The role hashes are stable across deployments (DEFAULT_ADMIN_ROLE,
- * FEE_COLLECTOR_ROLE, etc.).
+ * Stays disabled (no request fired) until both `role` and `holder` are
+ * defined — a UI can call this unconditionally while a form is still being
+ * filled in, with no manual `enabled` guard.
+ *
+ * @example
+ * const { data: isPauser } = useAirdropHasRole({ address, role: pauserRole, holder: account });
+ *
+ * @alpha
  */
 export declare function useAirdropHasRole(args: UseAirdropHasRoleArgs): UseQueryResult<boolean, Error>;

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

@@ -0,0 +1,30 @@
+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";
+/** @alpha */
+export interface AirdropPauseArgs extends WriteAccountOverride {
+    /** `true` calls `pause()`, `false` calls `unpause()`. Both require `PAUSER_ROLE`. */
+    paused: boolean;
+}
+/**
+ * Set an airdrop instance's pause flag. One hook covers both directions —
+ * `paused: true` submits `pause()`, `paused: false` submits `unpause()` —
+ * rather than shipping two near-identical hooks for what is one UI toggle.
+ *
+ * Pausing does not stop the clock: `endTime` still passes while paused. Pair
+ * with `useExtendClaimWindow` when the campaign is meant to survive the
+ * pause.
+ *
+ * **Invalidates:** this instance's `useAirdropPaused` entry, and its
+ * `useAirdropWindow` entry — `isClaimWindowActive` ANDs the pause flag into
+ * `window.isActive`, so a mounted `useAirdropWindow` consumer would otherwise
+ * keep showing a stale `isActive` after a pause/unpause.
+ *
+ * @example
+ * const setPause = useAirdropPause({ address: airdropAddress });
+ * await setPause.mutateAsync({ paused: true });
+ *
+ * @alpha
+ */
+export declare function useAirdropPause(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, AirdropPauseArgs>;

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

@@ -0,0 +1,17 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseAirdropPausedArgs = AirdropInstanceHookOptions<boolean>;
+/**
+ * Whether claiming is currently halted (`PausableUpgradeable.paused()`).
+ *
+ * Distinct from {@link useAirdropWindow}'s `isActive`: this is the pause flag
+ * alone, independent of the claim-window timestamps. Use `isActive` for "can
+ * a claim succeed right now" and this hook for "did an admin explicitly pause".
+ *
+ * @example
+ * const { data: paused } = useAirdropPaused({ address: airdropAddress });
+ *
+ * @alpha
+ */
+export declare function useAirdropPaused(args: UseAirdropPausedArgs): UseQueryResult<boolean, Error>;

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

@@ -1,11 +1,18 @@
 import { type UseQueryResult } from "@tanstack/react-query";
 import type { Address } from "viem";
-import { type AirdropHookOptions } from "./_shared.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseAirdropTokenArgs = AirdropInstanceHookOptions<Address>;
 /**
- * Read the airdrop clone's immutable `TOKEN`. Result is cacheable for the
- * clone's lifetime — the field is baked into the clone's bytecode.
+ * Read the ERC-7984 token an airdrop instance distributes.
+ *
+ * Works against either variant — `token` is declared on the shared
+ * `ConfidentialAirdropBase` surface, so this hook needs no ECDSA/Merkle
+ * distinction.
  *
  * @example
  * const { data: token } = useAirdropToken({ address: airdropAddress });
+ *
+ * @alpha
  */
-export declare function useAirdropToken(options: AirdropHookOptions): UseQueryResult<Address, Error>;
+export declare function useAirdropToken(args: UseAirdropTokenArgs): UseQueryResult<Address, Error>;

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

@@ -0,0 +1,37 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/**
+ * Plaintext claim-window snapshot — combines five `AirdropBaseClient` reads into one.
+ *
+ * @alpha
+ */
+export interface AirdropWindow {
+    /** Claim-window open, Unix seconds. */
+    startTime: number;
+    /** Claim-window close, Unix seconds. Movable forward via `useExtendClaimWindow`. */
+    endTime: number;
+    /** Whether `startTime` has passed. Says nothing about the pause flag. */
+    hasStarted: boolean;
+    /** Whether `endTime` has passed. Says nothing about the pause flag. */
+    hasEnded: boolean;
+    /** In window AND not paused — the actual "would a claim be accepted right now" answer. */
+    isActive: boolean;
+}
+/** @alpha */
+export type UseAirdropWindowArgs = AirdropInstanceHookOptions<AirdropWindow>;
+/**
+ * Read an airdrop instance's claim-window snapshot in one round trip.
+ *
+ * Bundles `startTime` / `endTime` / `hasClaimStarted` / `hasClaimEnded` /
+ * `isClaimWindowActive` — five independent contract reads a UI almost always
+ * wants together (e.g. "claim opens at X, closes at Y, currently active: Z")
+ * — rather than shipping five near-identical one-line hooks nobody would call
+ * separately (the v1 mistake this cutover is deliberately not repeating).
+ *
+ * @example
+ * const { data: window } = useAirdropWindow({ address: airdropAddress });
+ * if (window?.isActive) { ... }
+ *
+ * @alpha
+ */
+export declare function useAirdropWindow(args: UseAirdropWindowArgs): UseQueryResult<AirdropWindow, Error>;

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

@@ -0,0 +1,29 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import type { EncryptedHandle } from "../../core/brands.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseClaimedAmountArgs extends AirdropInstanceHookOptions<EncryptedHandle> {
+    /** The account whose cumulative delivered total to read. */
+    account?: Address;
+}
+/**
+ * Read `account`'s cumulative delivered total on a `MerkleConfidentialAirdrop`
+ * instance, as an encrypted handle — pass it to the Zama relayer's
+ * `userDecrypt` to see the plaintext.
+ *
+ * **Caller-specific — `account` is part of the cache key.** Switching the
+ * connected account (or checking a different address) never serves a value
+ * cached for the previous account; see {@link airdropQueryKey}.
+ *
+ * @remarks
+ * This is the recipient's CUMULATIVE total delivered so far, not a per-claim
+ * amount — see {@link MerkleAirdropClient.getClaimedAmount}'s TSDoc for the
+ * root-rotation and one-leaf-per-recipient consequences of that.
+ *
+ * @example
+ * const { data: claimedHandle } = useClaimedAmount({ address, account });
+ *
+ * @alpha
+ */
+export declare function useClaimedAmount(args: UseClaimedAmountArgs): UseQueryResult<EncryptedHandle, Error>;

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

@@ -0,0 +1,16 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+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.
+ *
+ * @example
+ * const { data: complianceManager } = useComplianceManager({ address: airdropAddress });
+ *
+ * @alpha
+ */
+export declare function useComplianceManager(args: UseComplianceManagerArgs): UseQueryResult<Address, Error>;

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

@@ -0,0 +1,28 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams } 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
+ * 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.
+ *
+ * @example
+ * const create = useCreateEcdsaAirdrop();
+ * const { airdrop, complianceManager } = await create.mutateAsync({
+ *   params: { common, signer, dedupMode: "perAddress" },
+ *   mode: "clone",
+ *   userSalt,
+ * });
+ *
+ * @alpha
+ */
+export declare function useCreateEcdsaAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride>;

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

@@ -0,0 +1,25 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import type { CreateAirdropArgs, CreateAirdropResult, MerkleAirdropParams } 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 }`.
+ *
+ * **Invalidates:** the factory's registry reads (`useFactoryRegistry`) for
+ * this factory address — a new instance changes `airdropCount()` /
+ * `airdrops()`. Nothing else.
+ *
+ * @example
+ * const create = useCreateMerkleAirdrop();
+ * const { airdrop } = await create.mutateAsync({
+ *   params: { common, merkleRoot, isMerkleRootMutable: true },
+ *   mode: "clone",
+ *   userSalt,
+ * });
+ *
+ * @alpha
+ */
+export declare function useCreateMerkleAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, CreateAirdropArgs<MerkleAirdropParams> & WriteAccountOverride>;

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

@@ -0,0 +1,23 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { EcdsaClaimArgs } from "../ecdsa.js";
+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.
+ *
+ * **Invalidates:** nothing. No exposed read in this subpath tracks per-claim
+ * ECDSA state (replay consumption isn't queryable), so there is no cached
+ * entry a successful claim could leave stale.
+ *
+ * @example
+ * const claim = useEcdsaClaim({ address: airdropAddress, dedupMode: "perAddress" });
+ * await claim.mutateAsync({ encryptedInput, dedupId, deadline, signer, signature });
+ *
+ * @alpha
+ */
+export declare function useEcdsaClaim(options: EcdsaAirdropInstanceClientOptions): UseMutationResult<Hex, Error, EcdsaClaimArgs>;

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

@@ -0,0 +1,20 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseEffectiveUpgradeableArgs extends AirdropHookOptions<boolean> {
+    /** The creator whose effective upgradeability policy to read. */
+    creator?: Address;
+}
+/**
+ * Whether `creator`'s NEXT `create*` may deploy `mode: "uups"` — the factory
+ * default, overridden per-creator via `setUpgradeabilityPolicy`. Read this
+ * before offering a UUPS deploy option in a UI; the factory refuses the
+ * create outright when this is `false` (`UpgradeabilityNotAllowedError`).
+ *
+ * @example
+ * const { data: canUseUups } = useEffectiveUpgradeable({ creator: deployerAddress });
+ *
+ * @alpha
+ */
+export declare function useEffectiveUpgradeable(args?: UseEffectiveUpgradeableArgs): UseQueryResult<boolean, Error>;

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

@@ -1,16 +1,21 @@
 import { type UseMutationResult } from "@tanstack/react-query";
-import type { Account, Address, Hex } from "viem";
-import { type AirdropHookOptions } from "./_shared.js";
-export interface UseExtendClaimWindowArgs {
-    newEndTime: number;
-    account?: Account | Address;
-}
+import type { Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
 /**
- * Admin: extend the claim window's `endTime`. Requires
- * `DEFAULT_ADMIN_ROLE` AND `CAN_EXTEND_CLAIM_WINDOW == true` (immutable) — the
- * contract reverts otherwise.
+ * Move an airdrop instance's claim-window end time forward. Requires
+ * `WINDOW_ADMIN_ROLE`, and only succeeds on an instance created with
+ * `canExtendClaimWindow: true`.
+ *
+ * **Invalidates:** only this instance's `useAirdropWindow` entry — `endTime`
+ * is one of the five fields that hook bundles.
  *
- * After success, invalidate `useAirdropEndTime`,
- * `useAirdropHasClaimEnded`, and `useAirdropIsClaimWindowActive`.
+ * @example
+ * const extend = useExtendClaimWindow({ address: airdropAddress });
+ * await extend.mutateAsync({ newEndTime: Math.floor(Date.now() / 1000) + 86_400 });
+ *
+ * @alpha
  */
-export declare function useExtendClaimWindow(options: AirdropHookOptions): UseMutationResult<Hex, Error, UseExtendClaimWindowArgs>;
+export declare function useExtendClaimWindow(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, {
+    newEndTime: number;
+} & WriteAccountOverride>;

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

@@ -0,0 +1,28 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/**
+ * The factory's chain-wide fee configuration.
+ *
+ * @alpha
+ */
+export interface FactoryFees {
+    /** Where withdrawn gas fees go. */
+    feeCollector: Address;
+    /** Wei charged per claim on a fee-charging campaign, absent a per-creator custom fee. */
+    defaultGasFee: 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).
+ *
+ * @example
+ * const { data: fees } = useFactoryFees();
+ *
+ * @alpha
+ */
+export declare function useFactoryFees(args?: UseFactoryFeesArgs): UseQueryResult<FactoryFees, Error>;

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

@@ -0,0 +1,35 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/**
+ * One page of the factory's deployment registry.
+ *
+ * @alpha
+ */
+export interface FactoryRegistryPage {
+    /** Total instances the factory has deployed — the upper bound for paging. */
+    count: bigint;
+    /** Instance addresses in `[offset, offset + limit)` deployment order. */
+    items: readonly Address[];
+}
+/** @alpha */
+export interface UseFactoryRegistryArgs extends AirdropHookOptions<FactoryRegistryPage> {
+    /** Zero-based index to start the page at. Defaults to `0n`. */
+    offset?: bigint;
+    /** Page size. Defaults to `50n`. */
+    limit?: bigint;
+}
+/**
+ * Page through every instance the factory has deployed, plus the total
+ * count — the two reads a "list my campaigns" admin view needs together.
+ *
+ * The contract clamps to the tail rather than reverting on an out-of-range
+ * `offset`, so `items` may come back shorter than `limit` — page until it
+ * does, not until a read throws.
+ *
+ * @example
+ * const { data } = useFactoryRegistry({ offset: 0n, limit: 20n });
+ *
+ * @alpha
+ */
+export declare function useFactoryRegistry(args?: UseFactoryRegistryArgs): UseQueryResult<FactoryRegistryPage, Error>;

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

@@ -0,0 +1,35 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import type { FundInput } from "../factory.js";
+import { type AirdropClientOptions } from "./_shared.js";
+/**
+ * Top up an already-deployed instance's pool through the factory.
+ *
+ * Takes exactly one of `amount` (plaintext — the SDK encrypts it against the
+ * hook-level `encryptor`, or a per-call `encryptor` override) or
+ * `encryptedInput` (already built ciphertext) — see {@link FundInput}. The
+ * lazy `encryptor` on the hook config (CLAUDE.md Pitfall #3) is threaded
+ * through to the underlying `ConfidentialAirdropFactoryClient`, which itself
+ * falls back from a per-call override to this hook-level default and throws
+ * `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.
+ *
+ * **Never log `amount`.** It is the one plaintext confidential value this
+ * hook ever sees — do not pass it to telemetry, `onError` context, or a
+ * console statement.
+ *
+ * @example
+ * const fund = useFundAirdrop({ encryptor: () => sdk.relayer });
+ * await fund.mutateAsync({ airdrop: airdropAddress, amount: 1_000_000n });
+ *
+ * @alpha
+ */
+export declare function useFundAirdrop(options?: AirdropClientOptions): UseMutationResult<Hex, Error, {
+    airdrop: Address;
+} & FundInput & WriteAccountOverride>;

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

@@ -0,0 +1,35 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import { type InstanceRoleAssignment, type RoleGrantOutcome } from "../roles.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface GrantInstanceRolesArgs {
+    assignment: InstanceRoleAssignment;
+    /** Defaults to `true` — the creator's own `DEFAULT_ADMIN_ROLE` is revoked once the new admin is granted. */
+    revokeFromCreator?: boolean;
+}
+/**
+ * Split an airdrop instance's roles after create — one `grantRole` /
+ * `revokeRole` transaction per requested assignment, submitted in the order
+ * `planInstanceRoleSplit` computes.
+ *
+ * **Returns `RoleGrantOutcome[]` unchanged — do not collapse it.** Each step
+ * is its own transaction and can independently fail; flattening the array
+ * into a single success/failure bit destroys exactly the partial-failure
+ * legibility `grantInstanceRoles` was designed to preserve (see `roles.ts`).
+ * Inspect `outcomes.filter(o => o.error)` for what didn't land.
+ *
+ * **Invalidates:** every `useAirdropHasRole` entry for this instance
+ * (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
+ * untouched.
+ *
+ * @example
+ * const grant = useGrantInstanceRoles({ address: airdropAddress });
+ * const outcomes = await grant.mutateAsync({ assignment: { pauser, treasury } });
+ * const failed = outcomes.filter((o) => o.error);
+ *
+ * @alpha
+ */
+export declare function useGrantInstanceRoles(options: AirdropInstanceClientOptions): UseMutationResult<RoleGrantOutcome[], Error, GrantInstanceRolesArgs>;

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

@@ -0,0 +1,34 @@
+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:** the claiming account's `useClaimedAmount` entry for this
+ * instance — the read whose cumulative-delivered value a successful claim
+ * changes. The claiming account is `args.account` if given, else the
+ * connected wallet's own account; other accounts' cached reads, and every
+ * other instance's cache, are left untouched (a `useMerkleClaim` on one
+ * campaign must not invalidate another campaign's `useClaimedAmount`).
+ *
+ * The claimant is resolved once in `onMutate` — synchronously, before the
+ * (async) write runs — and threaded into `onSuccess` via TanStack's mutation
+ * `context`, rather than re-read from `useWalletClient()` after the write
+ * settles. A mutation can outlive several re-renders of its own component
+ * (its `isPending` transition alone triggers one), and `useWalletClient()`'s
+ * data can read back transiently empty across those re-renders even though
+ * the write itself already resolved and used a real account — re-reading it
+ * in `onSuccess` risks silently skipping the invalidation this TSDoc
+ * promises. `onMutate` runs in the same tick `mutate()`/`mutateAsync()` was
+ * called, so it observes the exact same `walletClient` value the write is
+ * about to use.
+ *
+ * @example
+ * const claim = useMerkleClaim({ address: airdropAddress });
+ * await claim.mutateAsync({ entry });
+ *
+ * @alpha
+ */
+export declare function useMerkleClaim(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/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/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>;