@tokenops/sdk 2.0.0-alpha.1 → 2.0.0-alpha.3

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

@@ -11,14 +11,21 @@ export interface FactoryFees {
     feeCollector: Address;
     /** Wei charged per claim on a fee-charging campaign, absent a per-creator custom fee. */
     defaultGasFee: bigint;
+    /**
+     * The factory's own ceiling, in wei. Bounds both fee setters and the fee
+     * resolved at create, so it is the upper bound a `maxAcceptedGasFee` ever
+     * has to clear.
+     */
+    maxGasFee: 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).
+ * Read the airdrop factory's chain-wide fee configuration: `feeCollector`,
+ * `defaultGasFee` and `maxGasFee` in one round trip. For the number a specific
+ * creator's `maxAcceptedGasFee` is actually checked against, use
+ * `factory.resolveGasFee(creator)` from the headless client: it folds in that
+ * creator's `getCustomFee` override, which this hook does not read.
  *
  * @example
  * const { data: fees } = useFactoryFees();

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>;

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

@@ -0,0 +1,44 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseIsAirdropArgs extends AirdropHookOptions<boolean> {
+    /** The address to check against the factory's registry. */
+    candidate?: Address;
+}
+/**
+ * Ask the canonical factory whether it created `candidate` - the genuineness
+ * check (audit-10).
+ *
+ * **Run this before trusting an address a user pasted, a link carried, or an
+ * indexer returned.** A look-alike instance with the same ABI, the same events
+ * and a pool the attacker controls is cheap to deploy, and nothing readable at
+ * the instance tells it apart. A claim against one succeeds and delivers
+ * nothing.
+ *
+ * The factory this asks is the one resolved from `src/core/addresses.ts` for
+ * the connected chain, which is what makes the answer worth anything: an
+ * instance that names its own factory names a fake one.
+ *
+ * **Only a `true` is cached.** The registry is append-only, so a `true` can
+ * never become `false` and is safe to hold forever. A `false` is not stable:
+ * the address can be created later by another tab, another service, or the
+ * headless client, none of which reaches this hook's invalidations - so caching
+ * it would serve a stale false negative indefinitely and, for a security check,
+ * in the direction that blocks a legitimate claim. Negative answers therefore
+ * stay fresh and refetch normally. Override either with `query.staleTime`.
+ *
+ * **The `address` override is the trust root.** Like every factory hook this
+ * accepts `address`, and `useMemoAirdropFactoryClient` prefers it over
+ * `src/core/addresses.ts`. That is what makes the hook usable on a local chain,
+ * but it also means an attacker-supplied factory address would answer `true`
+ * for its own look-alike. Pass `address` only from a source you trust at least
+ * as much as the registry; when in doubt, omit it.
+ *
+ * @example
+ * const { data: genuine } = useIsAirdrop({ candidate: fromUrl });
+ * if (genuine === false) return <Warning address={fromUrl} />;
+ *
+ * @alpha
+ */
+export declare function useIsAirdrop(args?: UseIsAirdropArgs): UseQueryResult<boolean, Error>;

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

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

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

@@ -0,0 +1,46 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import { type EcdsaAirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseIsSignatureValidArgs extends EcdsaAirdropInstanceHookOptions<boolean> {
+    /** The address the signature was made out to. The digest binds `msg.sender`, so the read is simulated FROM this address. */
+    recipient?: Address;
+    /** The external encrypted allocation handle. No input proof: a view never calls `FHE.fromExternal`. */
+    encryptedAmountHandle?: Hex;
+    /** The off-chain claim id bound into the signature. */
+    dedupId?: Hex;
+    /** Unix seconds the signature expires at. */
+    deadline?: bigint;
+    /** The `SIGNER_ROLE` holder that authorized the claim. */
+    signer?: Address;
+    /** The EIP-712 signature from `signClaimAuthorization`. */
+    signature?: Hex;
+}
+/**
+ * Whether an ECDSA claim authorization would be accepted right now for `recipient`,
+ * without spending an FHE op or a transaction.
+ *
+ * Never reverts - `false` covers every failure mode (paused, outside the claim window,
+ * past `deadline`, `signer` lacking `SIGNER_ROLE`, an invalid signature, a consumed
+ * digest, or an already-deduped claim). `recipient` is load-bearing and part of the
+ * cache key: the read is an `eth_call` FROM that address, so passing the wrong one
+ * returns `false` for a signature that would otherwise succeed.
+ *
+ * Stays disabled until all six signature fields are defined, so a UI can call it
+ * unconditionally while a form fills in.
+ *
+ * @remarks
+ * A successful {@link useEcdsaClaim} / {@link useEcdsaClaimAndUnwrap} flips this to
+ * `false` by consuming the digest, but neither claim hook invalidates it - refetch it
+ * yourself after a claim rather than trusting a cached `true`.
+ *
+ * @example
+ * const { data: claimable } = useIsSignatureValid({
+ *   address: airdropAddress,
+ *   dedupMode: "perAddress",
+ *   recipient, encryptedAmountHandle, dedupId, deadline, signer, signature,
+ * });
+ *
+ * @alpha
+ */
+export declare function useIsSignatureValid(args: UseIsSignatureValidArgs): UseQueryResult<boolean, Error>;

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

@@ -6,28 +6,16 @@ import { type AirdropInstanceClientOptions } from "./_shared.js";
  * Claim the outstanding amount for a proof-bearing entry on a
  * `MerkleConfidentialAirdrop` instance.
  *
- * **Invalidates:** the claiming account's `useClaimedAmount` entry for this
- * instance — the read whose cumulative-delivered value a successful claim
- * changes. The claiming account is `args.account` if given, else the
- * connected wallet's own account; other accounts' cached reads, and every
- * other instance's cache, are left untouched (a `useMerkleClaim` on one
- * campaign must not invalidate another campaign's `useClaimedAmount`).
- *
- * The claimant is resolved once in `onMutate` — synchronously, before the
- * (async) write runs — and threaded into `onSuccess` via TanStack's mutation
- * `context`, rather than re-read from `useWalletClient()` after the write
- * settles. A mutation can outlive several re-renders of its own component
- * (its `isPending` transition alone triggers one), and `useWalletClient()`'s
- * data can read back transiently empty across those re-renders even though
- * the write itself already resolved and used a real account — re-reading it
- * in `onSuccess` risks silently skipping the invalidation this TSDoc
- * promises. `onMutate` runs in the same tick `mutate()`/`mutateAsync()` was
- * called, so it observes the exact same `walletClient` value the write is
- * about to use.
+ * **Invalidates:** `useClaimedAmount` for `entry.account` on this instance — the read
+ * whose cumulative-delivered value a successful claim changes. The contract advances
+ * `claimedAmount[account]`, keyed on the entry's claim identity and NOT on whoever sent
+ * the transaction, so a relayed claim must invalidate the recipient's cache entry rather
+ * than the relayer's. Other accounts' cached reads, and every other instance's cache,
+ * are left untouched.
  *
  * @example
  * const claim = useMerkleClaim({ address: airdropAddress });
- * await claim.mutateAsync({ entry });
+ * await claim.mutateAsync({ entry }); // relayers pass a relayed entry unchanged
  *
  * @alpha
  */

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

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

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

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

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

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

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

@@ -0,0 +1,67 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { PreflightResult } from "../../core/preflight.js";
+import type { DeploymentMode } from "../constants.js";
+import type { EcdsaAirdropParams, MerkleAirdropParams } from "../types.js";
+import { type AirdropHookOptions } from "./_shared.js";
+/** The variant-independent half of {@link UsePreflightCreateAirdropArgs}. */
+/** @alpha */
+export interface PreflightCreateAirdropCommon extends AirdropHookOptions<PreflightResult> {
+    mode?: DeploymentMode;
+    /** The account that will send `create*`. CREATE2 salts are per-deployer. */
+    creator?: Address;
+    userSalt?: Hex;
+    /**
+     * Pass `plan.initCodeHashAfter` to turn the implementation-drift check on.
+     * Omitting it skips that one check.
+     */
+    expectedInitCodeHash?: Hex;
+}
+/**
+ * `variant` and `params` are correlated, mirroring the headless
+ * `PreflightCreateArgs` discriminated union rather than widening to a
+ * cross-product (CLAUDE.md Pitfall #2). The all-undefined member is what lets
+ * a component call the hook unconditionally while a create form fills in.
+ *
+ * @alpha
+ */
+export type UsePreflightCreateAirdropArgs = PreflightCreateAirdropCommon & ({
+    variant?: undefined;
+    params?: undefined;
+} | {
+    variant: "ecdsa";
+    params?: EcdsaAirdropParams;
+} | {
+    variant: "merkle";
+    params?: MerkleAirdropParams;
+});
+/**
+ * Read-only preflight for `useCreateEcdsaAirdrop` / `useCreateMerkleAirdrop`.
+ * Runs every create-time guardrail the write path enforces - chain support,
+ * the Merkle/UUPS refusal, the creator's effective upgradeability policy for
+ * `mode: "uups"`, the stock-wrapper probe when `params.common.unwrappable` is
+ * set, a salt collision on the predicted address, and implementation drift
+ * when `expectedInitCodeHash` is supplied.
+ *
+ * **The point is disabling the submit button, not catching after the fact.**
+ * `blockers` carries the same typed errors `create*` would have thrown, so a
+ * UI branches on `error.code` here exactly as it does in `onError`.
+ *
+ * Disabled until `variant`, `params`, `mode`, `creator` and `userSalt` are all
+ * set. Refetch after the user changes their target mode or the factory's
+ * implementation pointer moves.
+ *
+ * @remarks
+ * Named `…Airdrop` rather than `…Create` so a consumer importing both this and
+ * `/fhe-vesting/react`'s `usePreflightCreateVesting` has no collision.
+ *
+ * @example
+ * const { data: report } = usePreflightCreateAirdrop({
+ *   variant: "merkle", params, mode: "clone", creator, userSalt,
+ *   expectedInitCodeHash: plan.initCodeHashAfter,
+ * });
+ * const canSubmit = report?.ready === true;
+ *
+ * @alpha
+ */
+export declare function usePreflightCreateAirdrop(args?: UsePreflightCreateAirdropArgs): UseQueryResult<PreflightResult, Error>;

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

@@ -0,0 +1,36 @@
+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.** Re-grants the compliance-manager clone on the
+ * instance's current pool balance and returns the handle it was granted on.
+ *
+ * **Permissionless** (audit-04), unlike every other disclosure hook here. The
+ * token rotates the instance's balance handle on every incoming transfer,
+ * including a direct one no airdrop code observes, and the clone's existing
+ * grant does not follow. Anyone may restore it because there is no argument to
+ * abuse: the only handle read is the instance's own balance and the only
+ * grantee is the clone wired at initialization.
+ *
+ * The handle comes from the receipt's ACL `Allowed` event naming the CLONE, not
+ * the caller - so unless the connected account is the clone, it cannot decrypt
+ * what this returns. That is also why it is a mutation: the entrypoint calls
+ * `FHE.allow`, so its handle can never come from a simulation (CLAUDE.md
+ * Pitfall #1).
+ *
+ * **A snapshot, not a subscription.** The handle stays readable forever (ACL is
+ * append-only), but the next incoming transfer rotates the instance onto a new
+ * handle the clone was never granted on. Re-run this after any transfer in.
+ *
+ * **Invalidates:** nothing, and nothing invalidates it - a mutation result is
+ * not a cache entry, so no write can refresh it. Re-run it yourself after
+ * `useFundAirdrop` or `useWithdrawConfidential`.
+ *
+ * @example
+ * const refresh = useRefreshComplianceBalance({ address: airdropAddress });
+ * const { handle } = await refresh.mutateAsync();
+ *
+ * @alpha
+ */
+export declare function useRefreshComplianceBalance(options: AirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, WriteAccountOverride | void>;

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

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

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

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