@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

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

@@ -0,0 +1,90 @@
+/**
+ * Query-key factories shared by the reads and the writes that invalidate them.
+ *
+ * Internal: neither barrel re-exports this. Consumers who want to invalidate by hand
+ * use the exported {@link airdropQueryKey} / {@link airdropQueryKeyPrefix} builders.
+ *
+ * It exists because a write hook has to rebuild its read's key exactly — same `fn`
+ * label, same `args` order — and a read and a write living in different files with
+ * hand-copied literals is the one drift hazard that no test catches: the write
+ * succeeds, the invalidation silently misses, and the UI shows a stale value. Every
+ * key referenced from more than one file is defined here once.
+ *
+ * A `fn` label used by exactly one hook stays inline in that hook.
+ */
+import type { Address, Hex } from "viem";
+/** Chain + contract scope every key below is built against. */
+interface Scope {
+    chainId: number | undefined;
+    address: Address | undefined;
+}
+/** `fn` labels. Shared so a read and its invalidating write cannot spell one differently. */
+export declare const AIRDROP_FN: {
+    readonly claimedAmount: "getClaimedAmount";
+    readonly paused: "paused";
+    readonly window: "window";
+    readonly config: "config";
+    readonly merkleRoot: "merkleRoot";
+    readonly merkleRootMutable: "isMerkleRootMutable";
+    readonly hasRole: "hasRole";
+    readonly roleMembers: "roleMembers";
+    readonly gasFee: "gasFee";
+    readonly preflightCreate: "preflightCreate";
+    readonly isSignatureValid: "isSignatureValid";
+    readonly fees: "fees";
+    readonly registry: "registry";
+    readonly customFee: "customFee";
+    readonly implementations: "implementations";
+    readonly compliancePolicy: "compliancePolicy";
+    readonly upgradeabilityPolicy: "upgradeabilityPolicy";
+    readonly factoryHasRole: "factoryHasRole";
+    readonly factoryRoleMembers: "factoryRoleMembers";
+    readonly complianceInfo: "complianceInfo";
+    readonly activeDelegate: "isActiveDelegate";
+    readonly clientDelegates: "clientDelegates";
+    readonly complianceHasRole: "complianceHasRole";
+    readonly complianceRoleMembers: "complianceRoleMembers";
+};
+export declare const airdropKeys: {
+    /** One account's cumulative delivered total. Keyed on the CLAIM IDENTITY, never the sender. */
+    readonly claimedAmount: (s: Scope, account: Address | undefined) => unknown[];
+    readonly paused: (s: Scope) => unknown[];
+    readonly window: (s: Scope) => unknown[];
+    readonly config: (s: Scope) => unknown[];
+    readonly gasFee: (s: Scope) => unknown[];
+    readonly merkleRoot: (s: Scope) => unknown[];
+    readonly merkleRootMutable: (s: Scope) => unknown[];
+    readonly hasRole: (s: Scope, role: Hex | undefined, holder: Address | undefined) => unknown[];
+    /** Every cached `hasRole` for this instance, whatever role/holder pair was queried. */
+    readonly hasRoleAll: (s: Scope) => unknown[];
+    readonly roleMembers: (s: Scope, role: Hex | undefined) => unknown[];
+    readonly roleMembersAll: (s: Scope) => unknown[];
+    /** Every cached create-preflight, whatever params/mode/salt combination was queried. */
+    readonly preflightCreateAll: (s: Scope) => unknown[];
+    /** Every cached signature check on this instance; a claim consumes a digest and flips it. */
+    readonly isSignatureValidAll: (s: Scope) => unknown[];
+    readonly fees: (s: Scope) => unknown[];
+    readonly customFee: (s: Scope, creator: Address | undefined) => unknown[];
+    readonly customFeeAll: (s: Scope) => unknown[];
+    /** Every registry page, whatever offset/limit was queried. */
+    readonly registryAll: (s: Scope) => unknown[];
+    readonly implementations: (s: Scope) => unknown[];
+    readonly compliancePolicy: (s: Scope, creator: Address | undefined) => unknown[];
+    readonly compliancePolicyAll: (s: Scope) => unknown[];
+    readonly upgradeabilityPolicy: (s: Scope, creator: Address | undefined) => unknown[];
+    readonly upgradeabilityPolicyAll: (s: Scope) => unknown[];
+    readonly factoryHasRole: (s: Scope, role: Hex | undefined, holder: Address | undefined) => unknown[];
+    readonly factoryHasRoleAll: (s: Scope) => unknown[];
+    readonly factoryRoleMembers: (s: Scope, role: Hex | undefined) => unknown[];
+    readonly factoryRoleMembersAll: (s: Scope) => unknown[];
+    readonly complianceInfo: (s: Scope) => unknown[];
+    readonly activeDelegate: (s: Scope, delegate: Address | undefined) => unknown[];
+    readonly activeDelegateAll: (s: Scope) => unknown[];
+    readonly clientDelegates: (s: Scope, index: bigint | undefined) => unknown[];
+    readonly clientDelegatesAll: (s: Scope) => unknown[];
+    readonly complianceHasRole: (s: Scope, role: Hex | undefined, holder: Address | undefined) => unknown[];
+    readonly complianceHasRoleAll: (s: Scope) => unknown[];
+    readonly complianceRoleMembers: (s: Scope, role: Hex | undefined) => unknown[];
+    readonly complianceRoleMembersAll: (s: Scope) => unknown[];
+};
+export {};

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

@@ -0,0 +1,26 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { EncryptedViewResult } from "../../fhe/types.js";
+import type { GetClaimAmountArgs as EcdsaGetClaimAmountArgs } from "../ecdsa.js";
+import { type EcdsaAirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * **Submits a transaction.** Previews a signed encrypted allocation as an encrypted
+ * handle. Pass `data.handle` to the Zama relayer's `userDecrypt`.
+ *
+ * **The submitter can decrypt what it previews here.** The contract grants the amount
+ * with `FHE.allow(amount, msg.sender)`, unlike {@link useAccessMerkleClaimAmount}, whose
+ * grantee is the entry's claim identity rather than the caller.
+ *
+ * `dedupMode` must be supplied - the contract has no on-chain getter for it; pass the
+ * same value used at `createEcdsaAirdrop` time.
+ *
+ * **Invalidates:** nothing. The preview consumes neither replay guard nor the EIP-712
+ * digest, so the same input is still claimable for real afterwards and no cached read
+ * changes value.
+ *
+ * @example
+ * const preview = useAccessEcdsaClaimAmount({ address: airdropAddress, dedupMode: "perAddress" });
+ * const { handle } = await preview.mutateAsync({ encryptedInput, dedupId, deadline, signer, signature });
+ *
+ * @alpha
+ */
+export declare function useAccessEcdsaClaimAmount(options: EcdsaAirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, EcdsaGetClaimAmountArgs>;

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

@@ -0,0 +1,27 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { EncryptedViewResult } from "../../fhe/types.js";
+import type { GetClaimAmountArgs } from "../merkle.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * **Submits a transaction.** Previews the outstanding amount for a proof-bearing Merkle
+ * entry as an encrypted handle. Pass `data.handle` to the Zama relayer's `userDecrypt`.
+ *
+ * `entry.boundTo` must be the sending account (the coprocessor verifies the input proof
+ * against the literal caller); `entry.account` selects the leaf.
+ *
+ * **`entry.account` is the only party that can decrypt the result, not the submitter.**
+ * The contract grants the outstanding handle with `_outstandingOf(account, account, …)`,
+ * so a third-party submitter gets back a valid handle it learns nothing from - never
+ * offer it a `userDecrypt` action. This is the opposite of
+ * {@link useAccessEcdsaClaimAmount}, whose preview is ACL'd to `msg.sender`.
+ *
+ * **Invalidates:** nothing. The preview consumes no accounting and no per-leaf state, so
+ * no cached read changes value - the same entry still pays the same amount afterwards.
+ *
+ * @example
+ * const preview = useAccessMerkleClaimAmount({ address: airdropAddress });
+ * const { handle } = await preview.mutateAsync({ entry });
+ *
+ * @alpha
+ */
+export declare function useAccessMerkleClaimAmount(options: AirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, GetClaimAmountArgs>;

package/dist/fhe-airdrop/react/useAddComplianceDelegate.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 AddComplianceDelegateArgs extends WriteAccountOverride {
+    /** The account to grant never-expiring user-decryption delegation to. */
+    delegate: Address;
+}
+/**
+ * Grant `delegate` permanent user-decryption delegation over this compliance
+ * clone's airdrop. `options.address` is the CLONE. Requires
+ * `DELEGATION_ADMIN_ROLE` on it (check with {@link useComplianceHasRole}).
+ *
+ * **The gateway lag is this hook's headline.** The delegation is live in the
+ * ACL the instant the transaction lands, but the Zama gateway learns about it
+ * out of band - the SDK's own guidance is 1-2 minutes. Do not tell the user
+ * delegated decryption is ready on success; classify the first delegated
+ * reads' failures with `isAclPropagationError` and retry with backoff.
+ *
+ * **Invalidates:** this clone's {@link useComplianceInfo} entry (the
+ * client-delegate set grew) and its {@link useIsActiveDelegate} entry for
+ * exactly `delegate`. Both keyed on the clone address - the airdrop instance
+ * is a different contract with its own cache namespace and is untouched.
+ *
+ * @remarks
+ * Do not send this and {@link useRevokeComplianceDelegate} for the same
+ * delegate in one block: the FHEVM ACL rejects the pair with an opaque revert
+ * that names neither the delegate nor the cause.
+ *
+ * @example
+ * const add = useAddComplianceDelegate({ address: managerAddress });
+ * await add.mutateAsync({ delegate: complianceOfficer });
+ *
+ * @alpha
+ */
+export declare function useAddComplianceDelegate(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, AddComplianceDelegateArgs>;

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

@@ -0,0 +1,36 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import type { EncryptedViewResult } from "../../fhe/types.js";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface UseAdminBatchDiscloseBalanceToPartiesArgs extends WriteAccountOverride {
+    /**
+     * Every address to grant. Must be non-empty and contain no zero address;
+     * duplicates are wasteful but legal on-chain and are not rejected.
+     */
+    parties: readonly Address[];
+}
+/**
+ * **Submits a transaction.** Discloses the instance's confidential pool
+ * balance to several parties at once. Requires `DISCLOSURE_ADMIN_ROLE`.
+ *
+ * One handle covers the whole batch: the contract reads the balance once and
+ * fans the same handle out, so `data.handle` (recovered from the grant naming
+ * `parties[0]`) is what *every* listed party decrypts. The caller is not a
+ * grantee unless it is in the list.
+ *
+ * An empty list and a zero-address party are rejected client-side as
+ * `InvalidArgumentError` before any gas is spent. Both are decidable from a
+ * form's own state, so validate the rows and show field errors rather than
+ * routing these through `onError`.
+ *
+ * **Invalidates:** nothing. ACL is append-only and no read hook caches grants.
+ *
+ * @example
+ * const disclose = useAdminBatchDiscloseBalanceToParties({ address: airdropAddress });
+ * const { handle } = await disclose.mutateAsync({ parties: [auditor, regulator] });
+ *
+ * @alpha
+ */
+export declare function useAdminBatchDiscloseBalanceToParties(options: AirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, UseAdminBatchDiscloseBalanceToPartiesArgs>;

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

@@ -0,0 +1,31 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import type { EncryptedViewResult } from "../../fhe/types.js";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface UseAdminDiscloseBalanceToPartyArgs extends WriteAccountOverride {
+    /** The address granted decrypt access - and the only address that can use the returned handle. */
+    party: Address;
+}
+/**
+ * **Submits a transaction.** Discloses the instance's confidential pool
+ * balance to `party`. Requires `DISCLOSURE_ADMIN_ROLE`.
+ *
+ * **The grantee is `party`, not the caller.** The handle is recovered from the
+ * ACL `Allowed` event naming `party`, so unless the caller is also `party` the
+ * returned `data.handle` is one it cannot decrypt - hand it to `party` rather
+ * than to your own `userDecrypt`, or the relayer rejects it with "not
+ * authorized to decrypt". As with every encrypted view here, the handle comes
+ * from the receipt and never from a simulation (CLAUDE.md Pitfall #1).
+ *
+ * **Invalidates:** nothing. ACL is append-only and no read hook in this
+ * subpath caches who is allowed on a handle.
+ *
+ * @example
+ * const disclose = useAdminDiscloseBalanceToParty({ address: airdropAddress });
+ * const { handle } = await disclose.mutateAsync({ party: auditorAddress });
+ *
+ * @alpha
+ */
+export declare function useAdminDiscloseBalanceToParty(options: AirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, UseAdminDiscloseBalanceToPartyArgs>;

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

@@ -0,0 +1,27 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { EncryptedViewResult } from "../../fhe/types.js";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * **Submits a transaction.** Reads the instance's remaining confidential pool
+ * balance as an `euint64` handle the caller may decrypt - pass `data.handle`
+ * to the Zama relayer's `userDecrypt`. Requires `DISCLOSURE_ADMIN_ROLE`.
+ *
+ * The name reads like a getter but the entrypoint calls `FHE.allow`, so it is
+ * `nonpayable` and its handle comes from the receipt's ACL `Allowed` event -
+ * never from a simulation, whose handle would carry no grant (CLAUDE.md
+ * Pitfall #1). That is why this is a mutation and not a query.
+ *
+ * **Invalidates:** nothing. It grants ACL and reads no cached state. Note the
+ * converse too: funding and withdrawing move the balance this returns, but a
+ * mutation result is not a cache entry, so no write can refresh it - re-run
+ * this hook after `useFundAirdrop` or `useWithdrawConfidential` to see the
+ * new value.
+ *
+ * @example
+ * const balance = useAdminGetCurrentBalance({ address: airdropAddress });
+ * const { handle } = await balance.mutateAsync();
+ *
+ * @alpha
+ */
+export declare function useAdminGetCurrentBalance(options: AirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, WriteAccountOverride | void>;

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

@@ -0,0 +1,49 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+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`
+ * reads into one.
+ *
+ * @alpha
+ */
+export interface AirdropConfig {
+    /** The ERC-7984 token this campaign distributes. */
+    token: Address;
+    /** The raw variant ordinal from the contract enum: `0` = ECDSA, `1` = Merkle. */
+    airdropType: number;
+    /** {@link airdropType} as a name, so a consumer can pick which variant hook set to mount. */
+    variant: AirdropVariant;
+    /** Whether claimants may unwrap to the underlying ERC-20 as part of a claim. */
+    unwrappable: boolean;
+    /** The instance's own compliance-manager clone. */
+    complianceManager: Address;
+    /** Per-claim ETH fee in wei; `0` on a fee-free campaign. */
+    gasFee: bigint;
+}
+/** @alpha */
+export type UseAirdropConfigArgs = AirdropInstanceHookOptions<AirdropConfig>;
+/**
+ * Read an airdrop instance's immutable configuration in one round trip.
+ *
+ * Bundles `token` / `airdropType` / `unwrappable` / `complianceManager` / `gasFee` -
+ * 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
+ * branch to the ECDSA or Merkle hook set without decoding the enum itself.
+ *
+ * Defaults to `staleTime: Infinity` - none of these values is mutable after create. Pass
+ * `query: { staleTime: 0 }` to override.
+ *
+ * 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.
+ *
+ * @example
+ * const { data: config } = useAirdropConfig({ address: airdropAddress });
+ * if (config?.variant === "merkle") { ... }
+ *
+ * @alpha
+ */
+export declare function useAirdropConfig(args: UseAirdropConfigArgs): UseQueryResult<AirdropConfig, Error>;

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

@@ -0,0 +1,28 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { DeploymentMode } from "../constants.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseAirdropDeploymentModeArgs = AirdropInstanceHookOptions<DeploymentMode>;
+/**
+ * Read which deployment shell an airdrop instance is: a minimal-proxy
+ * `"clone"`, or a `"uups"` ERC-1967 proxy that
+ * {@link useAirdropUpgradeToAndCall} can actually move. Gate any upgrade UI
+ * on this.
+ *
+ * One `eth_getStorageAt` against the ERC-1967 implementation slot, no ABI
+ * involved. It is the only reliable discriminator: `proxiableUUID` reverts on
+ * both shells when called at an instance address, and
+ * `UPGRADE_INTERFACE_VERSION` answers `"5.0.0"` for both.
+ *
+ * @remarks
+ * Defaults to `staleTime: Infinity` — a clone never becomes a proxy, and an
+ * upgrade swaps the implementation without changing the shell. Override via
+ * `query.staleTime` if you need a refetch anyway.
+ *
+ * @example
+ * const { data: mode } = useAirdropDeploymentMode({ address: airdropAddress });
+ * const canUpgrade = mode === "uups";
+ *
+ * @alpha
+ */
+export declare function useAirdropDeploymentMode(args: UseAirdropDeploymentModeArgs): UseQueryResult<DeploymentMode, Error>;

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

@@ -1,16 +1,35 @@
 import { type UseMutationResult } from "@tanstack/react-query";
-import type { Account, Address, Hex } from "viem";
-import { type AirdropHookOptions } from "./_shared.js";
-export interface UseAirdropGrantRoleArgs {
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface AirdropGrantRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - read it from {@link useAirdropRoleConstants}, never hand-hashed. */
     role: Hex;
-    accountTarget: Address;
-    account?: Account | Address;
+    /** The account receiving the role. Distinct from `account`, which is who sends the transaction. */
+    holder: Address;
 }
 /**
- * AccessControl: grant `role` to `accountTarget` on this airdrop clone.
- * Caller must be a member of the role's admin role (typically
- * `DEFAULT_ADMIN_ROLE`).
+ * Grant one role on one airdrop instance.
  *
- * After success, invalidate `useAirdropHasRole({ role, account: accountTarget })`.
+ * Requires the role's admin role, which is `DEFAULT_ADMIN_ROLE` for every role
+ * the instance sets up at `initialize` except `FEE_COLLECTOR_ROLE` - that one
+ * administers itself, so only a current fee collector can add another. Confirm
+ * with {@link useAirdropRoleAdmin} before offering the grant in a UI.
+ *
+ * **Invalidates:** this instance's `useAirdropHasRole` entry for exactly
+ * `(role, holder)`, and its `useAirdropRoleMembers` entry for `role` (the
+ * member list and the count both move). Scoped to this instance - other
+ * campaigns' role caches and other role/holder pairs are untouched.
+ *
+ * For a multi-role split right after create, prefer {@link useGrantInstanceRoles}:
+ * it orders the creator's admin revoke last so the key issuing the grants never
+ * locks itself out mid-sequence.
+ *
+ * @example
+ * const grant = useAirdropGrantRole({ address: airdropAddress });
+ * await grant.mutateAsync({ role: roles.PAUSER_ROLE, holder: opsAddress });
+ *
+ * @alpha
  */
-export declare function useAirdropGrantRole(options: AirdropHookOptions): UseMutationResult<Hex, Error, UseAirdropGrantRoleArgs>;
+export declare function useAirdropGrantRole(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, AirdropGrantRoleArgs>;

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

@@ -0,0 +1,36 @@
+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 AirdropRenounceRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - read it from {@link useAirdropRoleConstants}, never hand-hashed. */
+    role: Hex;
+}
+/**
+ * Give up a role on an airdrop instance yourself.
+ *
+ * Self-only by construction: the contract's `renounceRole(role, callerConfirmation)`
+ * reverts `AccessControlBadConfirmation` unless the confirmation is the sender,
+ * so there is no holder to pass - the headless client fills it from the
+ * resolved sending account. To remove a role from somebody else use
+ * {@link useAirdropRevokeRole}.
+ *
+ * Renouncing runs the same on-chain floors as a revoke, so it is not an escape
+ * hatch from them: the sole remaining `DEFAULT_ADMIN_ROLE` holder cannot
+ * renounce (`LastAdmin`). Grant a successor first.
+ *
+ * **Invalidates:** every `useAirdropHasRole` entry for this instance (prefix,
+ * all role/holder pairs), plus its `useAirdropRoleMembers` entry for `role`.
+ * The prefix is deliberate - the holder here is whichever account the wallet
+ * client resolves at submit time, which need not match any `(role, holder)`
+ * pair a component happens to have cached, and a narrower key would invalidate
+ * nothing while throwing nothing. Still scoped to this instance.
+ *
+ * @example
+ * const renounce = useAirdropRenounceRole({ address: airdropAddress });
+ * await renounce.mutateAsync({ role: roles.DEFAULT_ADMIN_ROLE });
+ *
+ * @alpha
+ */
+export declare function useAirdropRenounceRole(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, AirdropRenounceRoleArgs>;

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

@@ -1,15 +1,33 @@
 import { type UseMutationResult } from "@tanstack/react-query";
-import type { Account, Address, Hex } from "viem";
-import { type AirdropHookOptions } from "./_shared.js";
-export interface UseAirdropRevokeRoleArgs {
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface AirdropRevokeRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - read it from {@link useAirdropRoleConstants}, never hand-hashed. */
     role: Hex;
-    accountTarget: Address;
-    account?: Account | Address;
+    /** The account losing the role. Distinct from `account`, which is who sends the transaction. */
+    holder: Address;
 }
 /**
- * AccessControl: revoke `role` from `accountTarget` on this airdrop clone.
- * Caller must be a member of the role's admin role.
+ * Revoke one role from one holder on one airdrop instance.
  *
- * After success, invalidate `useAirdropHasRole({ role, account: accountTarget })`.
+ * Requires the role's admin role (see {@link useAirdropRoleAdmin};
+ * `FEE_COLLECTOR_ROLE` administers itself).
+ *
+ * Two revocations the contract refuses outright, both pre-checkable with
+ * {@link useAirdropRoleMembers}'s `count`: the last `DEFAULT_ADMIN_ROLE` member
+ * (`LastAdmin`), and the last `FEE_COLLECTOR_ROLE` member of a fee-charging
+ * campaign (`LastFeeCollector`). Grant the successor first, then revoke.
+ *
+ * **Invalidates:** this instance's `useAirdropHasRole` entry for exactly
+ * `(role, holder)`, and its `useAirdropRoleMembers` entry for `role`. Scoped to
+ * this instance only.
+ *
+ * @example
+ * const revoke = useAirdropRevokeRole({ address: airdropAddress });
+ * await revoke.mutateAsync({ role: roles.PAUSER_ROLE, holder: formerOpsAddress });
+ *
+ * @alpha
  */
-export declare function useAirdropRevokeRole(options: AirdropHookOptions): UseMutationResult<Hex, Error, UseAirdropRevokeRoleArgs>;
+export declare function useAirdropRevokeRole(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, AirdropRevokeRoleArgs>;

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

@@ -0,0 +1,28 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseAirdropRoleAdminArgs extends AirdropInstanceHookOptions<Hex> {
+    /** The role whose administrator to read - from {@link useAirdropRoleConstants}, not hand-hashed. */
+    role?: Hex;
+}
+/**
+ * Which role's holders may grant and revoke `role` on an airdrop instance.
+ *
+ * `DEFAULT_ADMIN_ROLE` for everything the instance wires up at `initialize`,
+ * with one exception the instance is alone in this module in having:
+ * `FEE_COLLECTOR_ROLE` is re-parented to itself, so only a current fee
+ * collector can add or remove another. This read is how a UI confirms that
+ * before it lets an admin key attempt a fee-collector grant that
+ * `planInstanceRoleSplit` already refuses to plan.
+ *
+ * Stays idle until `role` is defined, so a component can call it while a form
+ * is still filling in. Set once at initialize, hence `staleTime: Infinity` by
+ * default (overridable through `query`).
+ *
+ * @example
+ * const { data: admin } = useAirdropRoleAdmin({ address, role: roles?.FEE_COLLECTOR_ROLE });
+ *
+ * @alpha
+ */
+export declare function useAirdropRoleAdmin(args: UseAirdropRoleAdminArgs): UseQueryResult<Hex, Error>;