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

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

@@ -0,0 +1,45 @@
+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 AirdropUpgradeToAndCallArgs extends WriteAccountOverride {
+    /** The new implementation the proxy should point at. */
+    newImplementation: Address;
+    /**
+     * Initializer calldata to run against the new implementation, or `"0x"`
+     * (the default) for a plain swap. A non-empty payload is a `delegatecall`:
+     * the new implementation's code executes against THIS instance's storage.
+     */
+    data?: Hex;
+    /**
+     * Wei to attach. Leave unset for a plain swap — ERC-1967 reverts
+     * `ERC1967NonPayable` when value is sent with empty `data`.
+     */
+    value?: bigint;
+}
+/**
+ * Point an airdrop instance's ERC-1967 proxy at a new implementation,
+ * optionally calling into it in the same transaction. Requires
+ * `UPGRADER_ROLE`.
+ *
+ * **Inert on clone-mode instances** — a clone has no implementation slot to
+ * rewrite. Gate the UI on `useAirdropDeploymentMode().data === "uups"`;
+ * `proxiableUUID` cannot tell the two shells apart. Merkle campaigns never
+ * reach this at all, because the SDK refuses to create one in `uups` mode
+ * (`MerkleUupsUnsupportedError`).
+ *
+ * **Non-empty `data` runs as a delegatecall against this instance's own
+ * storage** — a wrong payload can brick the campaign irrecoverably.
+ *
+ * **Invalidates:** nothing. No hook in this subpath reads the instance's
+ * implementation pointer, and `deploymentMode` does not change across an
+ * upgrade.
+ *
+ * @example
+ * const upgrade = useAirdropUpgradeToAndCall({ address: airdropAddress });
+ * await upgrade.mutateAsync({ newImplementation: nextImpl });
+ *
+ * @alpha
+ */
+export declare function useAirdropUpgradeToAndCall(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, AirdropUpgradeToAndCallArgs>;

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

@@ -0,0 +1,32 @@
+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 UseBatchDiscloseHandlesToPartyArgs extends WriteAccountOverride {
+    /** Existing `euint64` handles - public pointers, not values. */
+    handles: readonly Hex[];
+    /** The single address granted decrypt access on every handle. */
+    party: Address;
+}
+/**
+ * Grants one `party` decrypt access to several handles you already hold, in a
+ * single transaction. Produces no new handles, so it returns the transaction
+ * hash.
+ *
+ * The same two gates as `useDiscloseHandleToParty` apply per handle - the
+ * caller allowed on it (unless it holds `DISCLOSURE_ADMIN_ROLE`) and the
+ * instance allowed on it - and the first failure reverts the whole batch,
+ * naming the offending handle. It is all-or-nothing: a partial grant is never
+ * left behind.
+ *
+ * **Invalidates:** nothing. ACL is append-only and no read hook in this
+ * subpath caches who is allowed on a handle.
+ *
+ * @example
+ * const disclose = useBatchDiscloseHandlesToParty({ address: airdropAddress });
+ * await disclose.mutateAsync({ handles: [balanceHandle, claimHandle], party: auditor });
+ *
+ * @alpha
+ */
+export declare function useBatchDiscloseHandlesToParty(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, UseBatchDiscloseHandlesToPartyArgs>;

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

@@ -0,0 +1,68 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type CampaignSubmitterOption } from "../campaign.js";
+import { type EncryptorSource } from "../encryption.js";
+import type { BuiltCampaign, CampaignRecipient } from "../types.js";
+/**
+ * Hook-level config for {@link useBuildMerkleCampaign}. The instance already
+ * exists on the mutable-root path, so no chain client is needed — only the
+ * encryptor.
+ *
+ * @alpha
+ */
+export interface UseBuildMerkleCampaignOptions {
+    /**
+     * 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 useBuildMerkleCampaign}.
+ *
+ * @alpha
+ */
+export interface UseBuildMerkleCampaignArgs 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 roster and build the Merkle tree those ciphertexts belong to, for
+ * an instance that already exists — the **mutable-root** path. Publish the
+ * returned `root` with {@link useSetMerkleRoot}, or let
+ * {@link useRotateMerkleRoot} build and publish in one call. For an instance
+ * whose root is fixed at create time use {@link usePlanMerkleCampaign}: there
+ * is no address to encrypt against yet.
+ *
+ * **The returned `entries` ARE the campaign — persist them before the
+ * component unmounts.** The instance stores only the 32-byte root; there is no
+ * getter and no event that maps an account to its handle, input proof or
+ * Merkle branch. A recipient who does not hold their own
+ * `(handle, inputProof, merkleProof)` triple can never claim, and no on-chain
+ * data reconstructs it. Losing this result to a re-render is the likeliest way
+ * to brick a campaign.
+ *
+ * A mutation rather than a query: encryption is randomised, so the same roster
+ * builds a different root every call and there is no cache identity to key.
+ *
+ * Each entry is `{ account, boundTo, handle, inputProof, merkleProof }` —
+ * `account` selects the leaf and the cumulative accounting, `boundTo` is the
+ * only address the coprocessor accepts as sender. They are equal unless
+ * `submitter` was set.
+ *
+ * **Invalidates:** nothing. Off-chain work only; the root is not published here.
+ *
+ * @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 build = useBuildMerkleCampaign({ encryptor: () => sdk.relayer });
+ * const { root, entries } = await build.mutateAsync({ instance: airdrop, recipients });
+ * await persist(entries); // before anything else
+ *
+ * @alpha
+ */
+export declare function useBuildMerkleCampaign(options?: UseBuildMerkleCampaignOptions): UseMutationResult<BuiltCampaign, Error, UseBuildMerkleCampaignArgs>;

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

@@ -0,0 +1,32 @@
+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 ComplianceGrantRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - from {@link useComplianceRoleConstants}, 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 a compliance-manager clone. `options.address` is the
+ * CLONE. Requires the role's admin role, which is `DEFAULT_ADMIN_ROLE` for
+ * both roles this contract defines.
+ *
+ * This is how a campaign owner hands delegate administration to a compliance
+ * team without giving them anything on the airdrop instance itself - the two
+ * contracts keep separate role sets, and a grant here confers no pause,
+ * treasury or disclosure power over the campaign.
+ *
+ * **Invalidates:** this clone's {@link useComplianceHasRole} entry for exactly
+ * `(role, holder)` and its {@link useComplianceRoleMembers} entry for `role`
+ * (the list and the count both move). Scoped to this clone.
+ *
+ * @example
+ * const grant = useComplianceGrantRole({ address: managerAddress });
+ * await grant.mutateAsync({ role: roles.DELEGATION_ADMIN_ROLE, holder: complianceTeam });
+ *
+ * @alpha
+ */
+export declare function useComplianceGrantRole(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, ComplianceGrantRoleArgs>;

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

@@ -0,0 +1,37 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseComplianceHasRoleArgs extends AirdropInstanceHookOptions<boolean> {
+    /** A `bytes32` role identifier - from {@link useComplianceRoleConstants}, not hand-hashed. */
+    role?: Hex;
+    /** The account to check. Distinct from a delegate: this is who may MANAGE delegates. */
+    holder?: Address;
+}
+/**
+ * Whether `holder` holds `role` on a compliance-manager clone. `address` is
+ * the CLONE.
+ *
+ * With `DELEGATION_ADMIN_ROLE` this is the gate on the delegate surface -
+ * mount {@link useAddComplianceDelegate}'s and
+ * {@link useRevokeComplianceDelegate}'s controls behind it. Holding a role
+ * here grants nothing on the airdrop instance itself; the two contracts have
+ * separate role sets.
+ *
+ * Stays disabled until both `role` and `holder` are defined, so a UI can call
+ * it unconditionally while the role constants are still loading.
+ *
+ * @remarks
+ * Invalidated by {@link useComplianceGrantRole},
+ * {@link useComplianceRevokeRole} and {@link useComplianceRenounceRole}.
+ *
+ * @example
+ * const { data: canDelegate } = useComplianceHasRole({
+ *   address: managerAddress,
+ *   role: roles?.DELEGATION_ADMIN_ROLE,
+ *   holder: account,
+ * });
+ *
+ * @alpha
+ */
+export declare function useComplianceHasRole(args: UseComplianceHasRoleArgs): UseQueryResult<boolean, Error>;

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

@@ -0,0 +1,50 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/**
+ * One compliance-manager clone's wiring - who it serves and who may decrypt
+ * through it, read together.
+ *
+ * @alpha
+ */
+export interface ComplianceInfo {
+    /** The one airdrop instance this clone serves. */
+    airdrop: Address;
+    /**
+     * The platform compliance delegate, or the zero address when this clone was
+     * created with the factory's compliance policy OFF. Never "not wired yet" -
+     * see the hook's TSDoc. Irrevocable when set.
+     */
+    platformDelegate: Address;
+    /** The mutable client-delegate set. Excludes `platformDelegate`. */
+    clientDelegates: readonly Address[];
+}
+/** @alpha */
+export type UseComplianceInfoArgs = AirdropInstanceHookOptions<ComplianceInfo>;
+/**
+ * Read a compliance-manager clone's whole wiring in one round trip - the
+ * airdrop it serves, its platform delegate, and its client-delegate set.
+ *
+ * `address` is the CLONE, not the airdrop instance: resolve it with
+ * {@link useComplianceManagerOf} or take it off `CreateAirdropResult.complianceManager`.
+ *
+ * A zero `platformDelegate` is unambiguous. The factory runs the clone's
+ * `initialize` atomically inside `createX`, so there is no observable
+ * "deployed but not yet wired" state - zero always means "created with the
+ * platform compliance policy off", never "not set up yet".
+ *
+ * `clientDelegates` deliberately omits the platform delegate, so it is not the
+ * answer to "may this address decrypt?" - use {@link useIsActiveDelegate},
+ * which reads the ACL directly and covers both slots.
+ *
+ * @remarks
+ * Invalidated by {@link useAddComplianceDelegate} and
+ * {@link useRevokeComplianceDelegate}.
+ *
+ * @example
+ * const { data } = useComplianceInfo({ address: complianceManagerAddress });
+ * const hasPlatformDelegate = data?.platformDelegate !== "0x0000000000000000000000000000000000000000";
+ *
+ * @alpha
+ */
+export declare function useComplianceInfo(args: UseComplianceInfoArgs): UseQueryResult<ComplianceInfo, Error>;

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

@@ -0,0 +1,32 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseComplianceManagerOfArgs extends AirdropHookOptions<Address> {
+    /** The airdrop instance whose compliance-manager clone to resolve. */
+    airdrop?: Address;
+}
+/**
+ * Resolve the `ComplianceRoleManager` clone bound to an airdrop instance, by
+ * asking the factory. This is the entry point for every other compliance
+ * hook: they are all scoped to the CLONE address, not the instance address.
+ *
+ * **Also a provenance check.** The factory records this mapping only for
+ * instances it deployed, so a zero address means the instance did not come
+ * from this factory - do not mount the compliance hooks on it.
+ *
+ * Cached indefinitely (`staleTime: Infinity`, overridable through `query`):
+ * the mapping is written once, inside `createX`, and never changes.
+ *
+ * @remarks
+ * {@link useComplianceManager} answers the same question from the other side,
+ * by asking the instance for its own clone. Prefer this hook when you hold no
+ * instance client, or when you want the provenance answer as well.
+ *
+ * @example
+ * const { data: manager } = useComplianceManagerOf({ airdrop: airdropAddress });
+ * const { data: info } = useComplianceInfo({ address: manager! });
+ *
+ * @alpha
+ */
+export declare function useComplianceManagerOf(args?: UseComplianceManagerOfArgs): UseQueryResult<Address, Error>;

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

@@ -0,0 +1,38 @@
+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 ComplianceRenounceRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - from {@link useComplianceRoleConstants}, never hand-hashed. */
+    role: Hex;
+}
+/**
+ * Give up a role on a compliance-manager clone yourself. `options.address` is
+ * the CLONE.
+ *
+ * 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 somebody else's role use
+ * {@link useComplianceRevokeRole}.
+ *
+ * No last-admin floor guards this: the sole `DEFAULT_ADMIN_ROLE` holder CAN
+ * renounce, and doing so freezes the clone's delegate set permanently.
+ *
+ * **Invalidates:** every {@link useComplianceHasRole} entry for this clone
+ * (prefix, all role/holder pairs), plus its
+ * {@link useComplianceRoleMembers} 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 clone.
+ *
+ * @example
+ * const renounce = useComplianceRenounceRole({ address: managerAddress });
+ * await renounce.mutateAsync({ role: roles.DELEGATION_ADMIN_ROLE });
+ *
+ * @alpha
+ */
+export declare function useComplianceRenounceRole(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, ComplianceRenounceRoleArgs>;

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

@@ -0,0 +1,36 @@
+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 ComplianceRevokeRoleArgs extends WriteAccountOverride {
+    /** A `bytes32` role identifier - from {@link useComplianceRoleConstants}, 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 a compliance-manager clone.
+ * `options.address` is the CLONE. Requires the role's admin role.
+ *
+ * **Revoking a delegation admin revokes no delegation.** The FHEVM ACL is
+ * append-only, so every delegate that account already added keeps decrypting
+ * until {@link useRevokeComplianceDelegate} is called for it explicitly. This
+ * is the most likely wrong assumption about this button: it removes the power
+ * to add more delegates, nothing else.
+ *
+ * The contract enforces no last-admin floor either - revoking the sole
+ * `DEFAULT_ADMIN_ROLE` holder freezes the clone's delegate set permanently.
+ * Check {@link useComplianceRoleMembers}'s `count` first.
+ *
+ * **Invalidates:** this clone's {@link useComplianceHasRole} entry for exactly
+ * `(role, holder)` and its {@link useComplianceRoleMembers} entry for `role`.
+ * Scoped to this clone.
+ *
+ * @example
+ * const revoke = useComplianceRevokeRole({ address: managerAddress });
+ * await revoke.mutateAsync({ role: roles.DELEGATION_ADMIN_ROLE, holder: formerTeam });
+ *
+ * @alpha
+ */
+export declare function useComplianceRevokeRole(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, ComplianceRevokeRoleArgs>;

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

@@ -0,0 +1,41 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/**
+ * The `bytes32` role identifiers a compliance-manager clone exposes.
+ *
+ * @alpha
+ */
+export interface ComplianceRoleConstants {
+    /** Gates `addDelegate` / `revokeDelegate`. */
+    DELEGATION_ADMIN_ROLE: Hex;
+    /** OpenZeppelin's root role, read off the clone rather than assumed to be `bytes32(0)`. It administers `DELEGATION_ADMIN_ROLE`. */
+    DEFAULT_ADMIN_ROLE: Hex;
+}
+/** @alpha */
+export type UseComplianceRoleConstantsArgs = AirdropInstanceHookOptions<ComplianceRoleConstants>;
+/**
+ * Read a compliance-manager clone's role identifiers. `address` is the CLONE.
+ *
+ * Both values are bytecode constants, so this is cacheable indefinitely
+ * (`staleTime: Infinity` by default, overridable through `query`). Feed them
+ * into {@link useComplianceHasRole}, {@link useComplianceRoleMembers} and the
+ * role mutations rather than hand-hashing `keccak256("DELEGATION_ADMIN_ROLE")`
+ * client-side, which would turn a constant renamed in a future contract
+ * version into a grant of a role nothing checks.
+ *
+ * Bundled despite being only two reads, so the shape matches
+ * {@link useAirdropRoleConstants} and the factory equivalent - and because two
+ * one-line hooks for two constants is the pattern this subpath avoids.
+ *
+ * @example
+ * const { data: roles } = useComplianceRoleConstants({ address: managerAddress });
+ * const { data: canDelegate } = useComplianceHasRole({
+ *   address: managerAddress,
+ *   role: roles?.DELEGATION_ADMIN_ROLE,
+ *   holder: account,
+ * });
+ *
+ * @alpha
+ */
+export declare function useComplianceRoleConstants(args: UseComplianceRoleConstantsArgs): UseQueryResult<ComplianceRoleConstants, Error>;

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

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

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

@@ -0,0 +1,55 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import type { FundInput } from "../factory.js";
+import type { CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams } from "../types.js";
+import { type AirdropClientOptions } from "./_shared.js";
+/**
+ * Variables for {@link useCreateAndFundEcdsaAirdrop} — the create arguments plus
+ * exactly one of `amount` / `encryptedInput`.
+ *
+ * @alpha
+ */
+export type UseCreateAndFundEcdsaAirdropArgs = CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride;
+/**
+ * Deploy an ECDSA-authorised airdrop instance and seed its pool in one
+ * transaction.
+ *
+ * Prerequisite: the funder must already have approved the factory as an
+ * ERC-7984 operator on the token (`token.setOperator(factoryAddress, deadline)`) —
+ * the factory pulls the pool via `confidentialTransferFrom`. Pass `amount`
+ * (plaintext, encrypted against the hook-level `encryptor`) or a pre-built
+ * `encryptedInput`, never both.
+ *
+ * Returns `CreateAirdropResult` unflattened — `{ hash, airdrop,
+ * complianceManager }`; the caller needs the instance address to do anything
+ * with the campaign afterwards.
+ *
+ * **A successful receipt does not prove the pool was funded.** An ERC-7984
+ * transfer moves an encrypted zero instead of reverting when the funder is
+ * short, because reverting would leak the balance.
+ *
+ * **Invalidates:** the factory's registry reads (`useFactoryRegistry`) for
+ * this factory address, whatever page was cached — a new instance moves
+ * `airdropCount()` / `airdrops()`. Nothing else: the new instance has no
+ * cached reads yet, and no read hook here exposes the confidential pool
+ * balance.
+ *
+ * **Never log `amount`.** It is the one plaintext confidential value this
+ * hook sees — keep it out of telemetry, `onError` context and console.
+ *
+ * @throws {@link DeploymentAddressUnavailableError} when no factory is deployed for the connected chain.
+ * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor resolves.
+ * @throws {@link SaltCollisionError} when this `(mode, deployer, userSalt)` tuple already deployed an instance.
+ *
+ * @example
+ * const createAndFund = useCreateAndFundEcdsaAirdrop({ encryptor: () => sdk.relayer });
+ * const { airdrop } = await createAndFund.mutateAsync({
+ *   params: { common, signer, dedupMode: "perAddress" },
+ *   mode: "clone",
+ *   userSalt,
+ *   amount: 1_000_000n,
+ * });
+ *
+ * @alpha
+ */
+export declare function useCreateAndFundEcdsaAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, UseCreateAndFundEcdsaAirdropArgs>;

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

@@ -0,0 +1,52 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import type { FundInput } from "../factory.js";
+import type { CreateAirdropArgs, CreateAirdropResult, MerkleAirdropParams } from "../types.js";
+import { type AirdropClientOptions } from "./_shared.js";
+/**
+ * Variables for {@link useCreateAndFundMerkleAirdrop} — the create arguments plus
+ * exactly one of `amount` / `encryptedInput`.
+ *
+ * @alpha
+ */
+export type UseCreateAndFundMerkleAirdropArgs = CreateAirdropArgs<MerkleAirdropParams> & FundInput & WriteAccountOverride;
+/**
+ * Deploy a Merkle-proof airdrop instance and seed its pool in one transaction.
+ *
+ * Prerequisite: the funder must already have approved the factory as an
+ * ERC-7984 operator on the token (`token.setOperator(factoryAddress, deadline)`).
+ * Pass `amount` (plaintext, encrypted against the hook-level `encryptor`) or a
+ * pre-built `encryptedInput`, never both.
+ *
+ * `mode: "uups"` is rejected before the wallet is even looked up, so the
+ * mutation rejects without prompting for a signature. Returns
+ * `CreateAirdropResult` unflattened — `{ hash, airdrop, complianceManager }`.
+ *
+ * **A successful receipt does not prove the pool was funded.** An ERC-7984
+ * transfer moves an encrypted zero instead of reverting when the funder is
+ * short, because reverting would leak the balance.
+ *
+ * **Invalidates:** the factory's registry reads (`useFactoryRegistry`) for
+ * this factory address, whatever page was cached — a new instance moves
+ * `airdropCount()` / `airdrops()`. Nothing else.
+ *
+ * **Never log `amount`.** It is the one plaintext confidential value this
+ * hook sees — keep it out of telemetry, `onError` context and console.
+ *
+ * @throws {@link MerkleUupsUnsupportedError} when `mode` is `"uups"`.
+ * @throws {@link DeploymentAddressUnavailableError} when no factory is deployed for the connected chain.
+ * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor resolves.
+ * @throws {@link SaltCollisionError} when this `(mode, deployer, userSalt)` tuple already deployed an instance.
+ *
+ * @example
+ * const createAndFund = useCreateAndFundMerkleAirdrop({ encryptor: () => sdk.relayer });
+ * const { airdrop } = await createAndFund.mutateAsync({
+ *   params: { common, merkleRoot: plan.root, isMerkleRootMutable: false },
+ *   mode: "clone",
+ *   userSalt,
+ *   amount: 1_000_000n,
+ * });
+ *
+ * @alpha
+ */
+export declare function useCreateAndFundMerkleAirdrop(options?: AirdropClientOptions): UseMutationResult<CreateAirdropResult, Error, UseCreateAndFundMerkleAirdropArgs>;

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

@@ -0,0 +1,35 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface UseDiscloseHandleToPartyArgs extends WriteAccountOverride {
+    /** An existing `euint64` handle - a public pointer, not a value. */
+    handle: Hex;
+    /** The address granted decrypt access on `handle`. */
+    party: Address;
+}
+/**
+ * Grants `party` decrypt access to a handle you already hold - typically one
+ * returned by `useAdminGetCurrentBalance` or a claim preview, forwarded to an
+ * auditor without ever revealing plaintext.
+ *
+ * Unlike the `admin*Disclose*` hooks this produces no new handle, so it
+ * returns the transaction hash rather than an `EncryptedViewResult`; there is
+ * no ACL event to parse.
+ *
+ * Two gates apply on-chain: the caller must itself be allowed on `handle`
+ * (bypassed by `DISCLOSURE_ADMIN_ROLE`), and the *instance* must be allowed on
+ * it, so a handle minted by an unrelated contract cannot be laundered through
+ * this campaign. A failure of the first surfaces as `FheHandleNotAllowedError`.
+ *
+ * **Invalidates:** nothing. ACL is append-only and no read hook in this
+ * subpath caches who is allowed on a handle.
+ *
+ * @example
+ * const disclose = useDiscloseHandleToParty({ address: airdropAddress });
+ * await disclose.mutateAsync({ handle, party: auditorAddress });
+ *
+ * @alpha
+ */
+export declare function useDiscloseHandleToParty(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, UseDiscloseHandleToPartyArgs>;

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

@@ -10,9 +10,10 @@ import { type EcdsaAirdropInstanceClientOptions } from "./_shared.js";
  * (see {@link EcdsaAirdropClientConfig.dedupMode}); pass the same value used
  * at `createEcdsaAirdrop` time.
  *
- * **Invalidates:** nothing. No exposed read in this subpath tracks per-claim
- * ECDSA state (replay consumption isn't queryable), so there is no cached
- * entry a successful claim could leave stale.
+ * **Invalidates:** the `fn "isSignatureValid"` PREFIX for this instance. A successful
+ * claim consumes the EIP-712 digest, so every cached signature check on this instance
+ * is now stale in the dangerous direction - it still answers `true` for a signature
+ * that can no longer be claimed. Per-claim dedup state itself remains unqueryable.
  *
  * @example
  * const claim = useEcdsaClaim({ address: airdropAddress, dedupMode: "perAddress" });

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

@@ -0,0 +1,27 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { EcdsaClaimArgs } from "../ecdsa.js";
+import { type EcdsaAirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * Claim a signed encrypted allocation and route it straight into the wrapper's unwrap,
+ * making `to` the underlying ERC-20 beneficiary.
+ *
+ * Reverts {@link FeatureDisabledError} on a non-unwrappable campaign - gate the button
+ * on `useAirdropConfig().unwrappable`. Consumes the same replay guards and EIP-712
+ * digest as {@link useEcdsaClaim}.
+ *
+ * `dedupMode` must be supplied - the contract has no on-chain getter for it; pass the
+ * same value used at `createEcdsaAirdrop` time.
+ *
+ * **Invalidates:** nothing, mirroring {@link useEcdsaClaim}. Replay consumption is not
+ * queryable, so no cached read in this subpath tracks the state a successful claim
+ * changes. `useIsSignatureValid` DOES flip to `false` once the digest is consumed, but
+ * it is not invalidated from here - refetch it yourself after a claim.
+ *
+ * @example
+ * const unwrapClaim = useEcdsaClaimAndUnwrap({ address: airdropAddress, dedupMode: "perAddress" });
+ * await unwrapClaim.mutateAsync({ encryptedInput, dedupId, deadline, signer, signature, to });
+ *
+ * @alpha
+ */
+export declare function useEcdsaClaimAndUnwrap(options: EcdsaAirdropInstanceClientOptions): UseMutationResult<Hex, Error, EcdsaClaimArgs>;