@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

package/dist/fhe-airdrop/merkle-tree.d.ts

@@ -0,0 +1,97 @@
+import type { Address, Hex } from "viem";
+/**
+ * Inputs for {@link leafOf}.
+ *
+ * @alpha
+ */
+export interface LeafOfArgs {
+    /** The `MerkleConfidentialAirdrop` instance the leaf is scoped to — `address(this)` on-chain. */
+    instance: Address;
+    /** The claim identity, independent of both the transaction submitter and the payout destination. */
+    account: Address;
+    /** The encrypted handle committing the account's cumulative total allocation. */
+    handle: Hex;
+}
+/**
+ * Compute a Merkle leaf byte-for-byte identical to the contract's `_leafOf` — see the
+ * module comment for the verified derivation.
+ *
+ * @alpha
+ */
+export declare function leafOf(args: LeafOfArgs): Hex;
+/**
+ * The minimum a leaf must carry. `buildMerkleTree` is generic over anything wider, so a
+ * caller's own fields ride along onto the entry.
+ *
+ * Deliberately does NOT include `boundTo`: the tree does not commit the submitter, so it
+ * is not needed to build one. Pass it anyway (alongside `inputProof`) and it rides through
+ * to the entry, which is what makes the result assignable to {@link CampaignEntry}.
+ *
+ * @alpha
+ */
+export interface MerkleLeafInput {
+    /** The claim identity this leaf commits — whose payout and cumulative accounting it keys. */
+    account: Address;
+    /** The encrypted handle committing this account's cumulative total. */
+    handle: Hex;
+}
+/**
+ * Inputs for {@link buildMerkleTree}.
+ *
+ * @alpha
+ */
+export interface BuildMerkleTreeArgs<L extends MerkleLeafInput> {
+    /** The `MerkleConfidentialAirdrop` instance the leaves are scoped to. Not the factory, not the implementation. */
+    instance: Address;
+    leaves: readonly L[];
+}
+/**
+ * A built tree: the root to publish, and every input leaf with its proof attached.
+ *
+ * @alpha
+ */
+export interface BuiltMerkleTree<L extends MerkleLeafInput> {
+    root: Hex;
+    entries: readonly (L & {
+        merkleProof: readonly Hex[];
+    })[];
+}
+/**
+ * Build the Merkle tree a `MerkleConfidentialAirdrop` verifies against, from handles
+ * produced anywhere.
+ *
+ * **Pure.** No relayer, no chain access, no encryptor — same leaves in, same root out.
+ *
+ * **The tree commits to the handle, not the amount, and not the submitter.** `_leafOf`
+ * hashes `(instance, account, handle)`, so whoever encrypted must have bound each input
+ * to `(instance, the intended submitter)`. This function cannot check that: it will
+ * happily build a tree over wrongly-bound handles, and the failure surfaces at claim time
+ * inside the coprocessor.
+ *
+ * **Extra fields ride along.** Whatever a leaf carries beyond `account` and `handle` —
+ * `boundTo`, an `inputProof`, your own row id — comes back on the entry, still aligned
+ * with its proof. Passing `{ account, boundTo, handle, inputProof }` therefore yields a
+ * value structurally assignable to {@link CampaignEntry}.
+ *
+ * @param args The instance the leaves are scoped to, and the leaves.
+ * @returns The root to publish, and one proof-bearing entry per input leaf, in input order.
+ * @throws {@link InvalidArgumentError} on a zero or malformed instance, an empty leaf set, a malformed or zero account, a duplicate account, or a handle that is not 32 bytes.
+ *
+ * @example
+ * const { root, entries } = buildMerkleTree({
+ *   instance: airdrop,
+ *   leaves: [{ account: alice, boundTo: alice, handle, inputProof }],
+ * });
+ * await merkle.setMerkleRoot({ newRoot: root });
+ *
+ * @alpha
+ */
+export declare function buildMerkleTree<L extends MerkleLeafInput>(args: BuildMerkleTreeArgs<L>): BuiltMerkleTree<L>;
+/**
+ * Real implementation behind {@link buildMerkleTree}, parameterised on the function name
+ * a thrown {@link InvalidArgumentError} blames.
+ *
+ * Not part of the public surface — exported only so `buildMerkleCampaign` can call it
+ * with its own name. Neither barrel re-exports it.
+ */
+export declare function buildMerkleTreeInternal<L extends MerkleLeafInput>({ instance, leaves }: BuildMerkleTreeArgs<L>, method: string): BuiltMerkleTree<L>;

package/dist/fhe-airdrop/merkle.d.ts

@@ -0,0 +1,201 @@
+import type { Address, Hex } from "viem";
+import { type EncryptedHandle } from "../core/brands.js";
+import type { EncryptedViewResult } from "../fhe/types.js";
+import { AirdropBaseClient, type AirdropBaseClientConfig, type WriteAccountOverride } from "./airdrop-base.js";
+import type { CampaignEntry } from "./types.js";
+/**
+ * Inputs shared by {@link MerkleAirdropClient.claim} and {@link MerkleAirdropClient.claimAndUnwrap}.
+ *
+ * @alpha
+ */
+export interface MerkleClaimArgs extends WriteAccountOverride {
+    /**
+     * Payout destination. Omit (or pass the zero address) to default to
+     * `entry.account` — note that is the CLAIM IDENTITY, not the sender, so on a
+     * relayed claim omitting `to` still pays the recipient.
+     *
+     * Only the account itself may redirect elsewhere; a third-party submitter passing
+     * a different `to` is refused before the write with
+     * {@link UnauthorizedRedirectError}.
+     */
+    to?: Address;
+    /**
+     * The proof-bearing claim entry, built by a campaign builder (`campaign.ts`).
+     *
+     * `entry.account` is submitted as the claim identity and selects the leaf.
+     * `entry.boundTo` must be the sending account, because the coprocessor verifies
+     * the input proof against the literal caller — the SDK checks this before the
+     * write rather than letting the transaction revert.
+     */
+    entry: CampaignEntry;
+}
+/**
+ * Inputs for {@link MerkleAirdropClient.getClaimAmount}.
+ *
+ * @alpha
+ */
+export interface GetClaimAmountArgs extends WriteAccountOverride {
+    /**
+     * Same binding rule as {@link MerkleClaimArgs.entry}: `entry.boundTo` must be the
+     * calling account. The preview's result is ACL'd to `entry.account`, so a relayer
+     * can confirm a leaf verifies without being able to read the amount.
+     */
+    entry: CampaignEntry;
+}
+/**
+ * Client for one `MerkleConfidentialAirdrop` instance — the variant whose
+ * claims are authorised by inclusion in a published Merkle tree rather than
+ * an off-chain signature. Each leaf commits `(instance, account, handle)`, where
+ * `handle` is that account's CUMULATIVE total allocation, not a per-drop tranche —
+ * see the `@remarks` on {@link getClaimedAmount}.
+ *
+ * `claim` names its claim identity explicitly, so a relayer can settle a leaf on a
+ * recipient's behalf. `claimAndUnwrap` deliberately cannot: it is always submitted
+ * for the caller.
+ *
+ * Adds the claim surface on top of {@link AirdropBaseClient}'s shared
+ * lifecycle/treasury/rescue/role/disclosure methods: `claim` /
+ * `claimAndUnwrap` submit a proof-bearing allocation, `getClaimAmount`
+ * previews the outstanding amount as a decryptable handle, and
+ * `getClaimedAmount` reads an account's running delivered total.
+ *
+ * Every claim entrypoint here takes the exact-equality gas fee
+ * ({@link AirdropBaseClient.gasFee}) automatically — read fresh on every
+ * `claim`/`claimAndUnwrap` call and attached as the transaction's `value`, so
+ * a caller never has to source it themselves or risk sending the wrong
+ * amount against the contract's `msg.value != gasFee()` revert.
+ *
+ * @example
+ * const airdrop = new MerkleAirdropClient({ publicClient, walletClient, address });
+ * const hash = await airdrop.claim({ entry });
+ *
+ * @alpha
+ */
+export declare class MerkleAirdropClient extends AirdropBaseClient {
+    constructor(config: AirdropBaseClientConfig);
+    /**
+     * Claim the outstanding amount for a proof-bearing entry, delivering the tokens to
+     * `to` — which defaults to `entry.account`, the CLAIM IDENTITY, not the sender.
+     *
+     * Requires `msg.value == gasFee()` exactly — handled for you; see the
+     * class TSDoc.
+     *
+     * @remarks
+     * There is no per-leaf consumption on this variant — replay safety is the
+     * accounting itself, not a spent-flag. Re-presenting an already-settled
+     * entry computes an encrypted-zero outstanding amount and pays nothing,
+     * but the gas fee is still charged (the amounts are encrypted, so a
+     * zero-outstanding claim cannot be detected or rejected on-chain).
+     * Presenting two different entries for the SAME recipient under one root
+     * pays whichever entry's cumulative total is higher net of what the other
+     * already delivered — effectively `max`, not `sum`, of the two totals.
+     *
+     * @throws {@link ClaimNotStartedError} before `startTime`.
+     * @throws {@link ClaimWindowClosedError} after `endTime`.
+     * @throws {@link InvalidArgumentError} (`argument: "entry.boundTo"`) when the entry's proof is bound to
+     *   another address, or (`argument: "merkleProof"`) when the proof does not verify against the current root.
+     * @throws {@link UnauthorizedRedirectError} when a third-party submitter passes a `to` other than `entry.account`.
+     * @returns The transaction hash.
+     */
+    claim(args: MerkleClaimArgs): Promise<Hex>;
+    /**
+     * Claim then route the allocation straight into the wrapper's unwrap
+     * (`to` becomes the underlying ERC-20 beneficiary). Reverts
+     * `TokenNotUnwrappable` (surfaced as `FeatureDisabledError`) on a
+     * non-unwrappable campaign.
+     *
+     * Same replay/accounting semantics and `msg.value == gasFee()` requirement
+     * as {@link claim} — see its `@remarks`.
+     *
+     * @remarks
+     * **Self-only by design.** This entrypoint takes no claim identity: releasing an
+     * allocation as a public ERC-20 transfer publishes the amount irreversibly, which is
+     * the recipient's own choice to make. A relayed unwrap is therefore unrepresentable
+     * rather than merely rejected, and an entry whose `account` is not the sender is
+     * refused before the write. A third party can still submit a confidential
+     * {@link claim}.
+     *
+     * @returns The transaction hash. The underlying ERC-20 is released later by
+     *   a separate, permissionless `finalizeUnwrap` — this hash is only the
+     *   unwrap request.
+     */
+    claimAndUnwrap(args: MerkleClaimArgs): Promise<Hex>;
+    /**
+     * Preview the outstanding amount for a proof-bearing entry as a handle the
+     * caller can decrypt. Consumes no accounting and no per-leaf state — the
+     * same entry still pays the same amount after a preview. No fee.
+     *
+     * **Submits a transaction.** The contract calls `FHE.allow(outstanding, account)`, so
+     * the result is recovered from the receipt's ACL `Allowed` event, never from a
+     * simulation. See {@link AirdropBaseClient}'s class TSDoc.
+     *
+     * **`entry.account` is the decryptable party, not the caller.** A relayer previewing on
+     * someone's behalf gets a valid handle it cannot read — that is the contract's intent,
+     * and it is what makes a blind relayed submission possible.
+     *
+     * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`, as `entry.account`.
+     */
+    getClaimAmount(args: GetClaimAmountArgs): Promise<EncryptedViewResult>;
+    /**
+     * Read `account`'s running delivered total as an encrypted handle.
+     *
+     * @remarks
+     * Since round 8 a Merkle leaf commits the recipient's CUMULATIVE total
+     * allocation, not a per-drop tranche, and this getter mirrors that: it
+     * returns the cumulative amount actually DELIVERED so far, not a per-claim
+     * amount. A claim pays `total - min(total, alreadyDelivered)`, where
+     * `alreadyDelivered` is exactly this value.
+     *
+     * Two consequences worth calling out explicitly:
+     * - **A root rotation is a top-up, not a second payout.** Rotating the
+     *   root republishes updated cumulative totals; this value is keyed by
+     *   `account` alone (not by root), so a claim against the new root pays
+     *   only the increase over what this getter already reports.
+     * - **One leaf per recipient per root.** If a tree mistakenly commits two
+     *   leaves for the same recipient, claiming both pays the higher of the
+     *   two totals net of this running value — `max`, not `sum`.
+     *
+     * **An account that has never claimed returns the ZERO handle, which cannot be
+     * decrypted.** It is an uninitialized ciphertext, so nobody holds an ACL on it and
+     * the relayer rejects it with "not authorized to user decrypt handle 0x0…0" rather
+     * than answering zero. Treat `handle === zeroHash` as "nothing delivered yet" and
+     * skip the decrypt; only call `userDecrypt` on a non-zero handle. (A mock FHEVM
+     * instance does answer zero here, so this only bites against a live relayer.)
+     *
+     * @returns The account's cumulative delivered total as an encrypted handle, or the
+     *   zero handle if it has never claimed.
+     */
+    getClaimedAmount(account: Address): Promise<EncryptedHandle>;
+    /** The currently published root. Proofs must verify against this exact value. */
+    merkleRoot(): Promise<Hex>;
+    /** Whether {@link setMerkleRoot} can succeed at all — fixed at create time, never toggled after. */
+    isMerkleRootMutable(): Promise<boolean>;
+    /**
+     * Rotate the published root. Requires `MERKLE_ADMIN_ROLE`.
+     *
+     * A rotation republishes UPDATED cumulative totals — it tops accounts up,
+     * it never claws back: {@link getClaimedAmount}'s running total survives
+     * the rotation and every future claim still nets it out. See that
+     * getter's `@remarks`.
+     *
+     * @throws {@link FeatureDisabledError} (`feature: "merkleRootRotation"`) when the campaign was created
+     *   with `isMerkleRootMutable: false`.
+     * @throws {@link InvalidArgumentError} (`argument: "merkleRoot"`) when `newRoot` is zero — a zero root
+     *   would silently brick every claim with no way to fix it; pause instead.
+     * @returns The transaction hash.
+     */
+    setMerkleRoot(args: {
+        newRoot: Hex;
+    } & WriteAccountOverride): Promise<Hex>;
+    /** Gates {@link setMerkleRoot}. */
+    MERKLE_ADMIN_ROLE(): Promise<Hex>;
+}
+/**
+ * Create a {@link MerkleAirdropClient}. Mirrors viem's `create*` convention.
+ *
+ * @example
+ * const airdrop = createMerkleAirdropClient({ publicClient, walletClient, address });
+ *
+ * @alpha
+ */
+export declare function createMerkleAirdropClient(config: AirdropBaseClientConfig): MerkleAirdropClient;

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

@@ -1,64 +1,135 @@
+import type { UseQueryOptions } from "@tanstack/react-query";
 import type { Address, PublicClient, WalletClient } from "viem";
 import { DeploymentAddressUnavailableError } from "../../core/errors.js";
-import { type Encryptor, type EncryptorSource } from "../encryption.js";
+import type { SdkTelemetry } from "../../core/telemetry.js";
+import { type AirdropBaseClient } from "../airdrop-base.js";
+import type { DedupMode } from "../constants.js";
+import { type EcdsaAirdropClient } from "../ecdsa.js";
+import { type EncryptorSource } from "../encryption.js";
 import { type ConfidentialAirdropFactoryClient } from "../factory.js";
-import { type ConfidentialAirdropClient } from "../airdrop.js";
-/** Common per-hook overrides — every public hook accepts these alongside its own args. */
-export interface BaseHookOptions {
-    /** Override the on-chain contract address. Defaults to {@link getFheAirdropFactoryAddress} keyed by chain id. */
+import { type MerkleAirdropClient } from "../merkle.js";
+import { type ComplianceManagerClient } from "../compliance.js";
+/**
+ * Stable query-key prefix for every hook in this subpath — matches the
+ * sibling subpaths' convention (`FHE_VESTING_KEY`/`FHE_DISPERSE_KEY`/
+ * `TESTNET_FAUCET_KEY` all use `"tokenops-sdk"`; see `src/fhe-vesting/react/_shared.ts`,
+ * `src/fhe-disperse/react/_shared.ts`, `src/testnet-faucet/react/_shared.ts`).
+ *
+ * Not `"tokenops"` — an earlier draft of this file used that value; fixed so
+ * a consumer calling `queryClient.invalidateQueries({ queryKey: ["tokenops-sdk"] })`
+ * to clear every `@tokenops/sdk` cache entry doesn't silently miss this
+ * subpath's queries.
+ */
+export declare const FHE_AIRDROP_KEY: "tokenops-sdk";
+export declare const FHE_AIRDROP_NAMESPACE: "fhe-airdrop";
+/**
+ * Build the TanStack Query key for an `/fhe-airdrop` read.
+ *
+ * Namespaced by chain id AND instance/factory address so cache entries never
+ * bleed across chains or campaigns — two different campaign instances (or
+ * the same instance on two chains) never share a cache slot. Caller-specific
+ * reads (e.g. `getClaimedAmount(account)`) pass `account` as part of `args`,
+ * so switching the connected account changes the key and never serves a
+ * stale value cached under the previous account.
+ *
+ * @returns `["tokenops-sdk", "fhe-airdrop", chainId, address, fn, args]`.
+ *
+ * @alpha
+ */
+export declare function airdropQueryKey(params: {
+    chainId: number | undefined;
+    address: Address | undefined;
+    fn: string;
+    args: ReadonlyArray<unknown>;
+}): unknown[];
+/**
+ * Build the *prefix* of {@link airdropQueryKey} up to (and including) `fn` —
+ * useful for `invalidateQueries({ queryKey: airdropQueryKeyPrefix(...), exact: false })`
+ * when a write affects every cached read for one function regardless of args
+ * (e.g. every `hasRole` entry for one instance, regardless of which
+ * role/holder pair was queried).
+ *
+ * @alpha
+ */
+export declare function airdropQueryKeyPrefix(params: {
+    chainId: number | undefined;
+    address: Address | undefined;
+    fn?: string;
+}): unknown[];
+/**
+ * The client-construction subset of every hook's options — deliberately NOT
+ * generic over `TData`. Client-memo helpers (`useMemoAirdropBaseClient`,
+ * etc.) accept this narrower shape rather than {@link AirdropHookOptions},
+ * because a `useQuery<TData, ...>` per-hook `query` option makes the wider
+ * type invariant in `TData` (the `enabled` callback's parameter type), which
+ * would otherwise force every memo helper to be generic too.
+ *
+ * @alpha
+ */
+export interface AirdropClientOptions {
+    /** Instance or factory address override. Factory hooks default this by chain id; instance hooks require it. */
     address?: Address;
     /** Override the chain id used for default address resolution. Defaults to `usePublicClient().chain?.id`. */
     chainId?: number;
-}
-/** Per-hook overrides for factory hooks that submit encrypted inputs. */
-export interface FactoryHookOptions extends BaseHookOptions {
     /**
-     * Lazy or eager encryptor source. Optional at hook level; **required at call
-     * time** for factory methods that submit encrypted inputs
-     * (`useCreateAndFundConfidentialAirdrop`, `useFundConfidentialAirdrop`).
-     *
-     * Recommended in React: capture `useZamaSDK()` once at the top of your
-     * component and wire `encryptor: () => sdk.relayer` — the SDK
-     * calls this per-encryption so it picks up the live `ZamaSDK` instance
-     * rather than a stale capture (CLAUDE.md Pitfall #3).
+     * Lazy or eager encryptor source. Only consumed by hooks that submit
+     * encrypted inputs (`useFundAirdrop`). Recommended in React: capture
+     * `useZamaSDK()` once and wire `encryptor: () => sdk.relayer` so the SDK
+     * picks up the live context at submit time (CLAUDE.md Pitfall #3) rather
+     * than a stale capture. An eager `Encryptor` instance also type-checks.
      */
     encryptor?: EncryptorSource;
+    /**
+     * Optional telemetry adapter. Forwarded into the headless client so spans
+     * and `*.client.init` events flow through whichever sink the consumer
+     * wires up (PostHog, OTel, Sentry, custom).
+     */
+    telemetry?: SdkTelemetry;
 }
-/** Per-hook overrides for FHE-airdrop *clone* hooks — `address` is required (per-airdrop). */
-export interface AirdropHookOptions {
-    /** Deployed airdrop clone address. Required — there is no chain-level default. */
-    address: Address;
-    /** Override the FHEVM ACL address (defaults to chain-id lookup). */
-    aclAddress?: Address;
-    /** Override the chain id used for ACL/public-client lookup. Defaults to `usePublicClient().chain?.id`. */
-    chainId?: number;
-}
-/** Stable query-key prefix for every hook in this subpath. */
-export declare const FHE_AIRDROP_KEY: "tokenops-sdk";
-export declare const FHE_AIRDROP_NAMESPACE: "fhe-airdrop";
 /**
- * Resolve the FHE-airdrop factory address for `chainId`, mirroring the
- * headless client's resolution. Throws the same {@link TokenOpsSdkError} the
- * headless client would throw at construction time.
+ * Common per-hook overrides — every public read hook accepts these alongside its own args.
+ *
+ * @alpha
  */
-export declare function resolveFactoryAddress(override: Address | undefined, chainId: number | undefined): Address;
+export interface AirdropHookOptions<TData = unknown> extends AirdropClientOptions {
+    /**
+     * Escape hatch for TanStack Query's own cache-behavior options
+     * (`staleTime`, `gcTime`, `select`, `refetchInterval`, …). Cannot override
+     * `queryKey` / `queryFn` — those stay owned by the hook so cache identity
+     * is never at risk of drifting from what was actually fetched.
+     */
+    query?: Omit<UseQueryOptions<TData, Error>, "queryKey" | "queryFn">;
+}
 /**
- * Same as {@link resolveFactoryAddress} but returns `undefined` instead of
- * throwing. Used by query-key builders and `enabled` gates.
+ * Instance-scoped hook options — `address` is required (a campaign instance, not a chain-wide default).
+ *
+ * @alpha
  */
-export declare function tryResolveFactoryAddress(override: Address | undefined, chainId: number | undefined): Address | undefined;
+export type AirdropInstanceHookOptions<TData = unknown> = AirdropHookOptions<TData> & {
+    address: Address;
+};
 /**
- * Memoize an {@link ConfidentialAirdropFactoryClient} keyed on
- * `(publicClient, walletClient, address)`. The encryptor source is passed
- * through as a **lazy** function (mirroring Pitfall #3 from CLAUDE.md): the
- * SDK calls it per-encryption, picking up the live React context at submit
- * time rather than baking in a stale capture.
+ * Non-generic instance-scoped client options, for memo helpers.
  *
- * @returns `{ client, publicClient, walletClient }`. `client` is `undefined`
- *   when no `publicClient` is available (wagmi may briefly return `undefined`
- *   during reconnects) — gate queries with `enabled: !!client`.
+ * @alpha
+ */
+export type AirdropInstanceClientOptions = AirdropClientOptions & {
+    address: Address;
+};
+/**
+ * Resolve the airdrop factory address for `chainId`, mirroring the headless
+ * client's resolution. Returns `undefined` instead of throwing — used by
+ * query-key builders and `enabled` gates.
+ */
+export declare function tryResolveAirdropFactoryAddress(override: Address | undefined, chainId: number | undefined): Address | undefined;
+/**
+ * Memoize a {@link ConfidentialAirdropFactoryClient} keyed on
+ * `(publicClient, walletClient, address, chainId)`. The encryptor source is
+ * threaded through as a lazy ref (CLAUDE.md Pitfall #3): the client calls it
+ * per-encryption, so it always sees the live React value rather than one
+ * baked in at memo time.
  */
-export declare function useMemoFactoryClient(opts?: FactoryHookOptions): {
+export declare function useMemoAirdropFactoryClient(opts?: AirdropClientOptions): {
     client: ConfidentialAirdropFactoryClient | undefined;
     resolutionError: DeploymentAddressUnavailableError | undefined;
     publicClient: PublicClient | undefined;
@@ -67,41 +138,56 @@ export declare function useMemoFactoryClient(opts?: FactoryHookOptions): {
     resolvedAddress: Address | undefined;
 };
 /**
- * Memoize a {@link ConfidentialAirdropClient} keyed on
- * `(publicClient, walletClient, address, aclAddress)`. The airdrop clone
- * client does not encrypt — the recipient submits an admin-issued
- * `{ encryptedInput, signature }` pair as-is — so no encryptor is wired here.
+ * Memoize an {@link AirdropBaseClient} for `opts.address` — the surface
+ * shared by both variants (lifecycle, treasury, rescue, roles, disclosure).
+ * Use this for hooks that don't need a variant-specific method.
  */
-export declare function useMemoAirdropClient(opts: AirdropHookOptions): {
-    client: ConfidentialAirdropClient | undefined;
+export declare function useMemoAirdropBaseClient(opts: AirdropInstanceClientOptions): {
+    client: AirdropBaseClient | undefined;
+    publicClient: PublicClient | undefined;
+    walletClient: WalletClient | undefined;
+    chainId: number | undefined;
+};
+/** Memoize a {@link MerkleAirdropClient} for `opts.address`. */
+export declare function useMemoMerkleAirdropClient(opts: AirdropInstanceClientOptions): {
+    client: MerkleAirdropClient | undefined;
     publicClient: PublicClient | undefined;
     walletClient: WalletClient | undefined;
     chainId: number | undefined;
 };
 /**
- * Resolve the encryptor for a mutation call. Order:
- * 1. Explicit `override` (eager `Encryptor` or lazy `() => Encryptor | undefined`).
- * 2. The hook-level `encryptor` source from the hook options.
+ * Memoize a {@link ComplianceManagerClient} for `opts.address`.
  *
- * Both are resolved per-call (not cached), mirroring the lazy `EncryptorSource`
- * pattern from CLAUDE.md Pitfall #3 — the consumer's React context is the
- * source of truth.
+ * `address` is the manager CLONE, not the airdrop instance and not the factory — read it
+ * from `factory.complianceManagerOf(airdrop)` or off `CreateAirdropResult.complianceManager`.
+ */
+export declare function useMemoComplianceManagerClient(opts: AirdropInstanceClientOptions): {
+    client: ComplianceManagerClient | undefined;
+    publicClient: PublicClient | undefined;
+    walletClient: WalletClient | undefined;
+    chainId: number | undefined;
+};
+/**
+ * Per-hook overrides for {@link useMemoEcdsaAirdropClient} — `dedupMode` has no on-chain getter, so it must be supplied.
  *
- * If both are missing, throws an actionable error. The hook layer does NOT
- * dynamically import `@zama-fhe/react-sdk` — calling `useZamaSDK()` from
- * inside `mutationFn` would violate the rules of hooks. Consumers wire the
- * encryptor at hook construction. The safe pattern is two lines:
- * `const sdk = useZamaSDK();` then `encryptor: () => sdk.relayer` — never
- * `() => useZamaSDK().relayer` inline (that calls a React hook inside a
- * mutation body, violating the rules of hooks).
+ * @alpha
  */
-export declare function resolveCallTimeEncryptor(override: Encryptor | EncryptorSource | undefined, hookLevelSource: EncryptorSource | undefined): Encryptor;
+export type EcdsaAirdropInstanceHookOptions<TData = unknown> = AirdropInstanceHookOptions<TData> & {
+    /** @see EcdsaAirdropClientConfig.dedupMode */
+    dedupMode: DedupMode;
+};
 /**
- * Build a stable TanStack Query key for an FHE-airdrop hook.
+ * Non-generic version of {@link EcdsaAirdropInstanceHookOptions}, for the memo helper.
  *
- * Conventions:
- * - Lowercase the contract address (TanStack uses structural equality; viem
- *   sometimes returns checksummed addresses).
- * - Convert bigints to base-10 strings (TanStack's serializer doesn't handle bigints).
+ * @alpha
  */
-export declare function buildQueryKey(method: string, chainId: number | undefined, address: Address | undefined, ...args: ReadonlyArray<unknown>): ReadonlyArray<unknown>;
+export type EcdsaAirdropInstanceClientOptions = AirdropInstanceClientOptions & {
+    dedupMode: DedupMode;
+};
+/** Memoize an {@link EcdsaAirdropClient} for `opts.address`. */
+export declare function useMemoEcdsaAirdropClient(opts: EcdsaAirdropInstanceClientOptions): {
+    client: EcdsaAirdropClient | undefined;
+    publicClient: PublicClient | undefined;
+    walletClient: WalletClient | undefined;
+    chainId: number | undefined;
+};