@tokenops/sdk 2.0.0-alpha.1 → 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/useAirdropGrantRole.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 AirdropGrantRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - read it from {@link useAirdropRoleConstants}, never hand-hashed. */
+    role: Hex;
+    /** The account receiving the role. Distinct from `account`, which is who sends the transaction. */
+    holder: Address;
+}
+/**
+ * Grant one role on one airdrop instance.
+ *
+ * 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: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, AirdropGrantRoleArgs>;

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

@@ -0,0 +1,33 @@
+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 AirdropRevokeRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - read it from {@link useAirdropRoleConstants}, never hand-hashed. */
+    role: Hex;
+    /** The account losing the role. Distinct from `account`, which is who sends the transaction. */
+    holder: Address;
+}
+/**
+ * Revoke one role from one holder on one airdrop instance.
+ *
+ * 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: 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>;

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

@@ -0,0 +1,67 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { DedupMode } from "../constants.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/**
+ * The `bytes32` role identifiers an airdrop instance exposes - the eight every
+ * variant shares, plus whichever ninth belongs to the variant asked for.
+ *
+ * @alpha
+ */
+export interface AirdropRoleConstants {
+    /** Gates `pause` / `unpause`. */
+    PAUSER_ROLE: Hex;
+    /** Gates `extendClaimWindow`. */
+    WINDOW_ADMIN_ROLE: Hex;
+    /** Gates `withdrawConfidential`. */
+    TREASURY_ROLE: Hex;
+    /** Gates the ERC-20 / foreign-token rescue surface. */
+    RESCUER_ROLE: Hex;
+    /** Gates `withdrawGasFee`, and administers itself rather than being administered by `DEFAULT_ADMIN_ROLE`. */
+    FEE_COLLECTOR_ROLE: Hex;
+    /** Gates `upgradeToAndCall` on UUPS instances; inert on clones. */
+    UPGRADER_ROLE: Hex;
+    /** Gates the admin disclosure surface. */
+    DISCLOSURE_ADMIN_ROLE: Hex;
+    /** OpenZeppelin's root role, read off the instance rather than assumed to be `bytes32(0)`. */
+    DEFAULT_ADMIN_ROLE: Hex;
+    /** Gates `setMerkleRoot`. Present only when `variant: "merkle"` was requested. */
+    MERKLE_ADMIN_ROLE?: Hex;
+    /** The role whose holders may authorize an ECDSA claim. Present only when `variant: "ecdsa"` was requested. */
+    SIGNER_ROLE?: Hex;
+}
+/** @alpha */
+export interface UseAirdropRoleConstantsArgs extends AirdropInstanceHookOptions<AirdropRoleConstants> {
+    /**
+     * Also read the variant-only role: `MERKLE_ADMIN_ROLE` or `SIGNER_ROLE`.
+     * Omit it for the eight shared constants and neither extra read fires.
+     */
+    variant?: "ecdsa" | "merkle";
+    /**
+     * Only relevant with `variant: "ecdsa"`, and only to keep the client
+     * construction honest - no read here consumes it. Pass the campaign's real
+     * policy if you have it to hand.
+     */
+    dedupMode?: DedupMode;
+}
+/**
+ * Read an airdrop instance's role identifiers in one fan-out.
+ *
+ * Every value is a bytecode constant, so this is cacheable indefinitely
+ * (`staleTime: Infinity` by default, overridable through `query`). Feed the
+ * results into {@link useAirdropHasRole}, {@link useAirdropRoleMembers},
+ * {@link useAirdropRoleAdmin} and the role mutations - hand-hashing
+ * `keccak256("PAUSER_ROLE")` client-side would turn a constant renamed in a
+ * future contract version into a `grantRole` that silently grants a role
+ * nothing checks.
+ *
+ * One bundled hook rather than ten one-liners nobody would call separately: a
+ * UI needs the whole palette to render a role panel at all.
+ *
+ * @example
+ * const { data: roles } = useAirdropRoleConstants({ address, variant: "merkle" });
+ * const { data: isPauser } = useAirdropHasRole({ address, role: roles?.PAUSER_ROLE, holder });
+ *
+ * @alpha
+ */
+export declare function useAirdropRoleConstants(args: UseAirdropRoleConstantsArgs): UseQueryResult<AirdropRoleConstants, Error>;

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

@@ -0,0 +1,49 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/**
+ * One role's membership on an airdrop instance - the set and its size, read
+ * together.
+ *
+ * @alpha
+ */
+export interface AirdropRoleMembership {
+    /** Every account currently holding the role, in the contract's `EnumerableSet` order. */
+    members: readonly Address[];
+    /** How many accounts hold it. The variable the contract's own revoke floors are written against. */
+    count: bigint;
+}
+/** @alpha */
+export interface UseAirdropRoleMembersArgs extends AirdropInstanceHookOptions<AirdropRoleMembership> {
+    /** The role whose members to list - from {@link useAirdropRoleConstants}, not hand-hashed. */
+    role?: Hex;
+}
+/**
+ * List who holds `role` on an airdrop instance, with the member count.
+ *
+ * This is the supported way to discover a campaign's fee collectors: the
+ * contract deliberately ships no `feeCollectors()` view and points callers at
+ * `getRoleMembers(FEE_COLLECTOR_ROLE)` instead.
+ *
+ * `count` is bundled rather than split into its own hook because it is the
+ * variable the contract's revoke floors are written against - a revoke of
+ * `DEFAULT_ADMIN_ROLE` at count 1 reverts `LastAdmin`, and of
+ * `FEE_COLLECTOR_ROLE` at count 1 on a fee-charging campaign reverts
+ * `LastFeeCollector` - so a UI showing the list wants to know in the same
+ * render whether a revoke is possible at all.
+ *
+ * Unpaginated: role sets here are operator-sized, not user-sized.
+ *
+ * @remarks
+ * Invalidated by {@link useAirdropGrantRole}, {@link useAirdropRevokeRole},
+ * {@link useAirdropRenounceRole} and {@link useGrantInstanceRoles}. Member
+ * order is `EnumerableSet`'s and is not stable across grants and revokes -
+ * treat it as a set, not a list.
+ *
+ * @example
+ * const { data } = useAirdropRoleMembers({ address, role: roles?.FEE_COLLECTOR_ROLE });
+ * const canRevoke = (data?.count ?? 0n) > 1n;
+ *
+ * @alpha
+ */
+export declare function useAirdropRoleMembers(args: UseAirdropRoleMembersArgs): UseQueryResult<AirdropRoleMembership, Error>;