@tokenops/sdk 1.6.0 → 2.0.0-alpha.1

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

@@ -0,0 +1,103 @@
+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 claiming account — always `msg.sender` on-chain, never the claim's payout destination. */
+    recipient: Address;
+    /** The encrypted handle committing the recipient's cumulative total allocation. */
+    handle: Hex;
+}
+/**
+ * Compute a Merkle leaf byte-for-byte identical to the contract's
+ * `_leafOf(recipient, inputAmount)` — see the module comment above for the
+ * verified derivation. Mirrors what the campaign builder (`buildMerkleCampaign`,
+ * `campaign.ts`) needs to construct the same tree `StandardMerkleTree` would,
+ * and is useful to any caller who wants to recompute a leaf independently of
+ * the campaign orchestrator.
+ *
+ * @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.
+ *
+ * @alpha
+ */
+export interface MerkleLeafInput {
+    /** The account that will SEND the claim. The contract recomputes the leaf as `_leafOf(msg.sender, inputAmount)`. */
+    recipient: Address;
+    /** The encrypted handle committing this recipient'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. Given the same leaves
+ * it returns the same root, so it can run offline, in a test, or on a machine
+ * that has never seen a private key.
+ *
+ * **The tree commits to the handle, not the amount.** `_leafOf` hashes
+ * `(address(this), recipient, encHandle)`, so whoever encrypted must have bound
+ * each input to `(instance, that recipient)` — `FHE.fromExternal` reverts on any
+ * mismatch. This function cannot check that; it will happily build a tree over
+ * wrongly-bound handles, and the failure surfaces at claim time.
+ *
+ * **Extra fields ride along.** Whatever the leaf carries beyond
+ * `recipient` and `handle` — an `inputProof`, your own row id — comes back on
+ * the entry, still aligned with its proof. Passing
+ * `{ recipient, handle, inputProof }` therefore yields a value structurally
+ * assignable to `CampaignEntry`, which is what `MerkleAirdropClient.claim`
+ * consumes.
+ *
+ * @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 recipient, a duplicate recipient, or a handle that is not 32 bytes.
+ *
+ * @example
+ * const { root, entries } = buildMerkleTree({
+ *   instance: airdrop,
+ *   leaves: [{ recipient: 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 from this module only so
+ * `buildMerkleCampaign` (`campaign.ts`) can call it directly with its own
+ * name, attributing a malformed-handle failure to itself rather than to
+ * `buildMerkleTree`. Neither barrel (`index.ts`) 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,180 @@
+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 the
+     * sending account — mirrors the contract's own `to == address(0)` redirect
+     * rule. The leaf's recipient field, the outstanding-amount accounting and
+     * the FHE input proof all stay bound to the sending account regardless of
+     * `to`; this field only redirects where the tokens (and the recipient ACL)
+     * land.
+     */
+    to?: Address;
+    /**
+     * The recipient's proof-bearing claim entry, built by the campaign
+     * orchestrator (`campaign.ts`, Task 11). `entry.recipient` must equal the
+     * account this call sends from (`args.account`, or the wallet client's
+     * default account): the contract recomputes the leaf as
+     * `_leafOf(msg.sender, inputAmount)`, so submitting `entry.merkleProof`
+     * from any account other than `entry.recipient` recomputes a different
+     * leaf and reverts `InvalidMerkleProof` even though the proof bytes
+     * themselves are untouched.
+     */
+    entry: CampaignEntry;
+}
+/**
+ * Inputs for {@link MerkleAirdropClient.getClaimAmount}.
+ *
+ * @alpha
+ */
+export interface GetClaimAmountArgs extends WriteAccountOverride {
+    /**
+     * Same binding rule as {@link MerkleClaimArgs.entry}: `entry.recipient`
+     * must equal the calling account, since the contract's preview also
+     * recomputes the leaf against `msg.sender`.
+     */
+    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, recipient, handle)`,
+ * where `handle` is the recipient's CUMULATIVE total allocation, not a
+ * per-drop tranche — see the `@remarks` on {@link getClaimedAmount}.
+ *
+ * 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` (defaults to the sending account).
+     *
+     * 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: "merkleProof"`) when the proof does not verify against
+     *   the current root — including when `entry.recipient` does not match the sending 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`.
+     *
+     * @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.
+     *
+     * An encrypted view: the contract calls `FHE.allow(outstanding, msg.sender)`,
+     * so the result is recovered from the receipt's ACL `Allowed` event, never
+     * from a simulation. See {@link AirdropBaseClient}'s class TSDoc.
+     *
+     * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`.
+     */
+    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`.
+     *
+     * The zero handle (uninitialized ciphertext) before an account's first
+     * settled claim decrypts as zero.
+     *
+     * @returns The account's cumulative delivered total, as an encrypted handle.
+     */
+    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,134 @@
+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";
+/**
+ * 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 useMemoFactoryClient(opts?: FactoryHookOptions): {
+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 useMemoAirdropFactoryClient(opts?: AirdropClientOptions): {
     client: ConfidentialAirdropFactoryClient | undefined;
     resolutionError: DeploymentAddressUnavailableError | undefined;
     publicClient: PublicClient | undefined;
@@ -67,41 +137,44 @@ 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.
- *
- * 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.
+ * 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;
+};