@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

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

@@ -0,0 +1,45 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/**
+ * One role's membership on a compliance-manager clone - the set and its size,
+ * read together.
+ *
+ * @alpha
+ */
+export interface ComplianceRoleMembership {
+    /** Every account currently holding the role, in `EnumerableSet` order. Treat it as a set: the order is not stable across grants and revokes. */
+    members: readonly Address[];
+    /** How many accounts hold it. */
+    count: bigint;
+}
+/** @alpha */
+export interface UseComplianceRoleMembersArgs extends AirdropInstanceHookOptions<ComplianceRoleMembership> {
+    /** The role whose members to list - from {@link useComplianceRoleConstants}, not hand-hashed. */
+    role?: Hex;
+}
+/**
+ * List who holds `role` on a compliance-manager clone, with the member count.
+ * `address` is the CLONE.
+ *
+ * With `DELEGATION_ADMIN_ROLE` this answers "who may add or revoke a
+ * delegate?" - the administrative counterpart to
+ * {@link useComplianceInfo}'s `clientDelegates`, which answers "who may
+ * currently decrypt?".
+ *
+ * Unlike an airdrop instance, this contract enforces no "never empty" floor:
+ * emptying `DEFAULT_ADMIN_ROLE` here freezes the clone's delegate set
+ * permanently, so surface `count` before offering the last revoke.
+ * Unpaginated - role sets here are operator-sized.
+ *
+ * @remarks
+ * Invalidated by {@link useComplianceGrantRole},
+ * {@link useComplianceRevokeRole} and {@link useComplianceRenounceRole}.
+ *
+ * @example
+ * const { data } = useComplianceRoleMembers({ address: managerAddress, role: roles?.DEFAULT_ADMIN_ROLE });
+ * const wouldFreezeClone = data?.count === 1n;
+ *
+ * @alpha
+ */
+export declare function useComplianceRoleMembers(args: UseComplianceRoleMembersArgs): UseQueryResult<ComplianceRoleMembership, Error>;

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

@@ -0,0 +1,55 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import type { FundInput } from "../factory.js";
+import type { CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams } from "../types.js";
+import { type AirdropClientOptions } from "./_shared.js";
+/**
+ * Variables for {@link useCreateAndFundEcdsaAirdrop} — the create arguments plus
+ * exactly one of `amount` / `encryptedInput`.
+ *
+ * @alpha
+ */
+export type UseCreateAndFundEcdsaAirdropArgs = CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride;
+/**
+ * Deploy an ECDSA-authorised airdrop instance and seed its pool in one
+ * transaction.
+ *
+ * Prerequisite: the funder must already have approved the factory as an
+ * ERC-7984 operator on the token (`token.setOperator(factoryAddress, deadline)`) —
+ * the factory pulls the pool via `confidentialTransferFrom`. Pass `amount`
+ * (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.
+ *
+ * **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.
+ *
+ * **Never log `amount`.** It is the one plaintext confidential value this
+ * hook sees — keep it out of telemetry, `onError` context and console.
+ *
+ * @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.
+ *
+ * @example
+ * const createAndFund = useCreateAndFundEcdsaAirdrop({ encryptor: () => sdk.relayer });
+ * const { airdrop } = await createAndFund.mutateAsync({
+ *   params: { common, signer, dedupMode: "perAddress" },
+ *   mode: "clone",
+ *   userSalt,
+ *   amount: 1_000_000n,
+ * });
+ *
+ * @alpha
+ */
+export declare function useCreateAndFundEcdsaAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, UseCreateAndFundEcdsaAirdropArgs>;

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

@@ -0,0 +1,52 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import type { FundInput } from "../factory.js";
+import type { CreateAirdropArgs, CreateAirdropResult, MerkleAirdropParams } from "../types.js";
+import { type AirdropClientOptions } from "./_shared.js";
+/**
+ * Variables for {@link useCreateAndFundMerkleAirdrop} — the create arguments plus
+ * exactly one of `amount` / `encryptedInput`.
+ *
+ * @alpha
+ */
+export type UseCreateAndFundMerkleAirdropArgs = CreateAirdropArgs<MerkleAirdropParams> & FundInput & WriteAccountOverride;
+/**
+ * Deploy a Merkle-proof airdrop instance and seed its pool in one transaction.
+ *
+ * Prerequisite: the funder must already have approved the factory as an
+ * ERC-7984 operator on the token (`token.setOperator(factoryAddress, deadline)`).
+ * Pass `amount` (plaintext, encrypted against the hook-level `encryptor`) or a
+ * pre-built `encryptedInput`, never both.
+ *
+ * `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 }`.
+ *
+ * **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.
+ *
+ * **Never log `amount`.** It is the one plaintext confidential value this
+ * hook sees — keep it out of telemetry, `onError` context and console.
+ *
+ * @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.
+ *
+ * @example
+ * const createAndFund = useCreateAndFundMerkleAirdrop({ encryptor: () => sdk.relayer });
+ * const { airdrop } = await createAndFund.mutateAsync({
+ *   params: { common, merkleRoot: plan.root, isMerkleRootMutable: false },
+ *   mode: "clone",
+ *   userSalt,
+ *   amount: 1_000_000n,
+ * });
+ *
+ * @alpha
+ */
+export declare function useCreateAndFundMerkleAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, UseCreateAndFundMerkleAirdropArgs>;

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/useDiscloseHandleToParty.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 AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface UseDiscloseHandleToPartyArgs extends WriteAccountOverride {
+    /** An existing `euint64` handle - a public pointer, not a value. */
+    handle: Hex;
+    /** The address granted decrypt access on `handle`. */
+    party: Address;
+}
+/**
+ * Grants `party` decrypt access to a handle you already hold - typically one
+ * returned by `useAdminGetCurrentBalance` or a claim preview, forwarded to an
+ * auditor without ever revealing plaintext.
+ *
+ * Unlike the `admin*Disclose*` hooks this produces no new handle, so it
+ * 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
+ * this campaign. A failure of the first surfaces as `FheHandleNotAllowedError`.
+ *
+ * **Invalidates:** nothing. ACL is append-only and no read hook in this
+ * subpath caches who is allowed on a handle.
+ *
+ * @example
+ * const disclose = useDiscloseHandleToParty({ address: airdropAddress });
+ * await disclose.mutateAsync({ handle, party: auditorAddress });
+ *
+ * @alpha
+ */
+export declare function useDiscloseHandleToParty(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, UseDiscloseHandleToPartyArgs>;

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

@@ -0,0 +1,24 @@
+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:** the `fn "isSignatureValid"` PREFIX for this instance. A successful
+ * claim consumes the EIP-712 digest, so every cached signature check on this instance
+ * is now stale in the dangerous direction - it still answers `true` for a signature
+ * that can no longer be claimed. Per-claim dedup state itself remains unqueryable.
+ *
+ * @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/useEcdsaClaimAndUnwrap.d.ts

@@ -0,0 +1,27 @@
+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 and route it straight into the wrapper's unwrap,
+ * making `to` the underlying ERC-20 beneficiary.
+ *
+ * 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}.
+ *
+ * `dedupMode` must be supplied - the contract has no on-chain getter for it; pass the
+ * same value used at `createEcdsaAirdrop` time.
+ *
+ * **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.
+ *
+ * @example
+ * const unwrapClaim = useEcdsaClaimAndUnwrap({ address: airdropAddress, dedupMode: "perAddress" });
+ * await unwrapClaim.mutateAsync({ encryptedInput, dedupId, deadline, signer, signature, to });
+ *
+ * @alpha
+ */
+export declare function useEcdsaClaimAndUnwrap(options: EcdsaAirdropInstanceClientOptions): UseMutationResult<Hex, Error, EcdsaClaimArgs>;

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

@@ -0,0 +1,41 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { Eip712Domain } from "../ecdsa.js";
+import { type EcdsaAirdropInstanceHookOptions } from "./_shared.js";
+/**
+ * One `ECDSAConfidentialAirdrop` instance's live EIP-712 identity, read
+ * straight off the deployment.
+ *
+ * @alpha
+ */
+export interface EcdsaDomain {
+    /** The on-chain `CLAIM_TYPEHASH`. Compare against the module `CLAIM_TYPEHASH` constant. */
+    claimTypehash: Hex;
+    /** `_domainSeparatorV4()`, bound to `(chainId, address(this))`. */
+    domainSeparator: Hex;
+    /** The ERC-5267 domain, field by field - what {@link EcdsaDomain.domainSeparator} hashes. */
+    domain: Eip712Domain;
+}
+/** @alpha */
+export type UseEcdsaDomainArgs = EcdsaAirdropInstanceHookOptions<EcdsaDomain>;
+/**
+ * Read an ECDSA instance's `CLAIM_TYPEHASH`, domain separator and ERC-5267
+ * domain in one round trip - the three deployment-verification reads nobody
+ * wants one at a time (same call as {@link useAirdropWindow}).
+ *
+ * **This is the round-trip confirmation, not the common path.** For building
+ * a signature, use the module-level `CLAIM_TYPEHASH` / `EIP712_DOMAIN_NAME` /
+ * `EIP712_DOMAIN_VERSION` constants and skip the RPC. Use this hook to
+ * confirm a deployed instance really was initialized with the domain you
+ * expect, on the chain you think it is on, before a signing service starts
+ * issuing signatures against it.
+ *
+ * All three are bytecode/deploy constants, so `staleTime: Infinity`.
+ *
+ * @example
+ * const { data } = useEcdsaDomain({ address: airdropAddress, dedupMode: "perAddress" });
+ * const built = data?.claimTypehash === CLAIM_TYPEHASH;
+ *
+ * @alpha
+ */
+export declare function useEcdsaDomain(args: UseEcdsaDomainArgs): UseQueryResult<EcdsaDomain, Error>;

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

@@ -0,0 +1,26 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseEffectiveDelegateToComplianceArgs extends AirdropHookOptions<boolean> {
+    /** The creator whose effective delegate-to-compliance policy to read. */
+    creator?: Address;
+}
+/**
+ * Whether `creator`'s NEXT `create*` will wire the platform compliance
+ * delegate into the instance's compliance-manager clone - their
+ * `setCompliancePolicy` override when they have one, else the factory
+ * default. Read it to tell a creator up front that a platform delegate will
+ * hold delegated rights on the campaign they are about to deploy.
+ *
+ * The creator-facing mirror of {@link useEffectiveUpgradeable}: same args
+ * shape, same gating, same subpath - even though the setters that move it
+ * (`setCompliancePolicy` / `clearCompliancePolicy` /
+ * `setDefaultDelegateToCompliance`) are factory-admin surface.
+ *
+ * @example
+ * const { data: willDelegate } = useEffectiveDelegateToCompliance({ creator: deployerAddress });
+ *
+ * @alpha
+ */
+export declare function useEffectiveDelegateToCompliance(args?: UseEffectiveDelegateToComplianceArgs): UseQueryResult<boolean, Error>;

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/useEncryptCampaignAmounts.d.ts

@@ -0,0 +1,59 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type CampaignSubmitterOption, type EncryptedCampaignLeaf } from "../campaign.js";
+import { type EncryptorSource } from "../encryption.js";
+import type { CampaignRecipient } from "../types.js";
+/**
+ * Hook-level config for {@link useEncryptCampaignAmounts}. No chain client is
+ * involved — encryption is relayer work — so only the encryptor is needed.
+ *
+ * @alpha
+ */
+export interface UseEncryptCampaignAmountsOptions {
+    /**
+     * Eager or lazy encryptor. Wire it lazily so the live React context is read
+     * at submit time rather than captured at mount (CLAUDE.md Pitfall #3):
+     * `const sdk = useZamaSDK()` once, then `encryptor: () => sdk.relayer`.
+     */
+    encryptor?: EncryptorSource;
+}
+/**
+ * Variables for {@link useEncryptCampaignAmounts}.
+ *
+ * @alpha
+ */
+export interface UseEncryptCampaignAmountsArgs extends CampaignSubmitterOption {
+    /** 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. */
+    recipients: readonly CampaignRecipient[];
+}
+/**
+ * Encrypt a plaintext roster into per-recipient handles, without building a
+ * tree. Use it to persist the ciphertexts before committing to a root; if you
+ * just want a campaign, {@link useBuildMerkleCampaign} does both stages.
+ *
+ * A mutation rather than a query on purpose: encryption is randomised, so the
+ * same roster yields different handles every call and there is no legitimate
+ * 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.
+ *
+ * **Invalidates:** nothing. Pure off-chain relayer work — no contract state
+ * moves, so no cached read goes stale.
+ *
+ * @throws {@link InvalidArgumentError} on a duplicate, zero-address or out-of-`uint64`-range roster entry, or a zero `instance`.
+ * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
+ *
+ * @example
+ * const encrypt = useEncryptCampaignAmounts({ encryptor: () => sdk.relayer });
+ * const leaves = await encrypt.mutateAsync({ instance: airdrop, recipients });
+ *
+ * @alpha
+ */
+export declare function useEncryptCampaignAmounts(options?: UseEncryptCampaignAmountsOptions): UseMutationResult<readonly EncryptedCampaignLeaf[], Error, UseEncryptCampaignAmountsArgs>;

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/useIsActiveDelegate.d.ts

@@ -0,0 +1,29 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseIsActiveDelegateArgs extends AirdropInstanceHookOptions<boolean> {
+    /** The address to check. Stays disabled until it is defined. */
+    delegate?: Address;
+}
+/**
+ * Whether `delegate` currently holds user-decryption delegation over this
+ * compliance-manager clone's airdrop. `address` is the CLONE.
+ *
+ * Authoritative: it reads the ACL expiration directly rather than the
+ * contract's `EnumerableSet` mirror, so unlike
+ * {@link useComplianceInfo}'s `clientDelegates` it also answers `true` for
+ * the irrevocable platform compliance delegate.
+ *
+ * **On-chain truth only.** A `true` here does not mean the Zama gateway will
+ * serve a delegated decrypt yet - it observes ACL changes out of band, with a
+ * lag the SDK's own guidance puts at 1-2 minutes. A UI that renders
+ * "delegated" off this value must still treat `isAclPropagationError` as a
+ * retry-with-backoff signal rather than a failure.
+ *
+ * @example
+ * const { data: canDecrypt } = useIsActiveDelegate({ address: managerAddress, delegate: officer });
+ *
+ * @alpha
+ */
+export declare function useIsActiveDelegate(args: UseIsActiveDelegateArgs): UseQueryResult<boolean, Error>;