@tokenops/sdk 1.0.0

package/dist/fhe-airdrop/abis/index.d.ts

@@ -0,0 +1,2 @@
+export { confidentialAirdropFactoryAbi } from "./factory.js";
+export { confidentialAirdropCloneableAbi } from "./cloneable.js";

package/dist/fhe-airdrop/advanced/factory-advanced.d.ts

@@ -0,0 +1,53 @@
+import type { Address } from "viem";
+import { ConfidentialAirdropFactoryClient, type ConfidentialAirdropFactoryClientConfig, type PredictAirdropArgs } from "../factory.js";
+/**
+ * Advanced extension of {@link ConfidentialAirdropFactoryClient} that re-exposes
+ * the CREATE2 address prediction read.
+ *
+ * **Why this is "advanced" surface.** R02 ADR P-1 + P-2 (alignment-auditor R04
+ * top-1): 90 % of consumers want one call back — `createConfidentialAirdrop`
+ * (rich-return, `{ hash, airdrop }`). The factory still emits
+ * `ConfidentialAirdropCreated`, the SDK still parses it, so consumers never
+ * need to ask "what address will this deploy to before mining?" Hoisting
+ * `predictAirdropAddress` onto the headline client surface gave consumers a
+ * footgun: pass the wrong `gasFee` and you predict an address that won't
+ * match the deployed clone.
+ *
+ * For the genuinely-advanced cases — historical address recovery, same-tx
+ * pre-confirmation flows — import this subclass from `@tokenops/sdk/fhe-airdrop/advanced`
+ * and call it explicitly. The headline factory does not include this method.
+ *
+ * @example
+ * import { createConfidentialAirdropFactoryAdvancedClient } from "@tokenops/sdk/fhe-airdrop/advanced";
+ *
+ * const factory = createConfidentialAirdropFactoryAdvancedClient({ publicClient });
+ * const predicted = await factory.predictAirdropAddress({
+ *   params, userSalt, deployer, gasFee: customGasFee,
+ * });
+ */
+export declare class ConfidentialAirdropFactoryAdvancedClient extends ConfidentialAirdropFactoryClient {
+    /**
+     * Compute the deterministic CREATE2 address for an airdrop clone without
+     * deploying it.
+     *
+     * Note: `gasFee` must match what the factory would charge the deployer at
+     * deploy time (custom fee if set, otherwise `defaultGasFee`). Use
+     * `getCustomFee(deployer)` and `defaultGasFee()` to resolve it correctly —
+     * a mismatch silently targets the wrong address.
+     *
+     * For the common "deploy a clone and learn its address" flow, use the
+     * headline `factory.createConfidentialAirdrop` instead — it parses the
+     * address from the tx receipt's `ConfidentialAirdropCreated` event without
+     * any `gasFee` guessing.
+     */
+    predictAirdropAddress(args: PredictAirdropArgs): Promise<Address>;
+}
+/**
+ * Create a {@link ConfidentialAirdropFactoryAdvancedClient}. Mirrors viem's
+ * `create*` convention.
+ *
+ * @example
+ * const factory = createConfidentialAirdropFactoryAdvancedClient({ publicClient, walletClient, encryptor });
+ * const predicted = await factory.predictAirdropAddress({ params, userSalt, deployer, gasFee });
+ */
+export declare function createConfidentialAirdropFactoryAdvancedClient(config: ConfidentialAirdropFactoryClientConfig): ConfidentialAirdropFactoryAdvancedClient;

package/dist/fhe-airdrop/advanced/index.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+var chunkT5LVV3KY_cjs = require('../../chunk-T5LVV3KY.cjs');
+require('../../chunk-6ECAHP5O.cjs');
+require('../../chunk-VDXVNZCO.cjs');
+require('../../chunk-OLDGMKW2.cjs');
+require('../../chunk-CQIPRNS7.cjs');
+require('../../chunk-VJKZWYYJ.cjs');
+require('../../chunk-66IHPTOK.cjs');
+require('../../chunk-56UI7LUR.cjs');
+
+
+
+Object.defineProperty(exports, "ConfidentialAirdropFactoryAdvancedClient", {
+  enumerable: true,
+  get: function () { return chunkT5LVV3KY_cjs.ConfidentialAirdropFactoryAdvancedClient; }
+});
+Object.defineProperty(exports, "createConfidentialAirdropFactoryAdvancedClient", {
+  enumerable: true,
+  get: function () { return chunkT5LVV3KY_cjs.createConfidentialAirdropFactoryAdvancedClient; }
+});

package/dist/fhe-airdrop/advanced/index.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Advanced FHE-airdrop primitives — power-user surface kept off the headline
+ * client to keep the 90 % path lean (R02 ADR P-2; alignment-auditor R04 top-1).
+ *
+ * Re-exports the {@link ConfidentialAirdropFactoryAdvancedClient} subclass,
+ * which extends the headline factory client with `predictAirdropAddress`. Use
+ * this subpath when you genuinely need to compute a clone address before
+ * deploying — historical recovery, deterministic same-tx flows. For the
+ * common "deploy and learn the address" case, the headline factory's
+ * `createConfidentialAirdrop` returns `{ hash, airdrop }` directly (R02 ADR P-1).
+ */
+export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient, } from "./factory-advanced.js";
+export type { PredictAirdropArgs } from "../factory.js";

package/dist/fhe-airdrop/advanced/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Advanced FHE-airdrop primitives — power-user surface kept off the headline
+ * client to keep the 90 % path lean (R02 ADR P-2; alignment-auditor R04 top-1).
+ *
+ * Re-exports the {@link ConfidentialAirdropFactoryAdvancedClient} subclass,
+ * which extends the headline factory client with `predictAirdropAddress`. Use
+ * this subpath when you genuinely need to compute a clone address before
+ * deploying — historical recovery, deterministic same-tx flows. For the
+ * common "deploy and learn the address" case, the headline factory's
+ * `createConfidentialAirdrop` returns `{ hash, airdrop }` directly (R02 ADR P-1).
+ */
+export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient, } from "./factory-advanced.js";
+export type { PredictAirdropArgs } from "../factory.js";

package/dist/fhe-airdrop/advanced/index.js

@@ -0,0 +1,8 @@
+export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient } from '../../chunk-ZHFLRKFY.js';
+import '../../chunk-UOG4PJL5.js';
+import '../../chunk-JFLEEXKP.js';
+import '../../chunk-COPFW5Z4.js';
+import '../../chunk-BE2AIZ3K.js';
+import '../../chunk-Q2GP5UDC.js';
+import '../../chunk-KWFFIJYX.js';
+import '../../chunk-IVE3QEGD.js';

package/dist/fhe-airdrop/advanced/react/index.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+var chunkK6MFFDBJ_cjs = require('../../../chunk-K6MFFDBJ.cjs');
+require('../../../chunk-5SA2HF2W.cjs');
+var chunkT5LVV3KY_cjs = require('../../../chunk-T5LVV3KY.cjs');
+var chunk6ECAHP5O_cjs = require('../../../chunk-6ECAHP5O.cjs');
+require('../../../chunk-Q7ARQSUH.cjs');
+require('../../../chunk-VDXVNZCO.cjs');
+var chunkOLDGMKW2_cjs = require('../../../chunk-OLDGMKW2.cjs');
+require('../../../chunk-CQIPRNS7.cjs');
+require('../../../chunk-VJKZWYYJ.cjs');
+require('../../../chunk-66IHPTOK.cjs');
+require('../../../chunk-56UI7LUR.cjs');
+var react = require('react');
+var reactQuery = require('@tanstack/react-query');
+var wagmi = require('wagmi');
+
+function usePredictAirdropAddress(args = {}) {
+  const { params, userSalt, deployer, gasFee, address, chainId, publicClient, encryptor } = args;
+  const wagmiPublicClient = wagmi.usePublicClient({ ...chainId !== void 0 ? { chainId } : {} });
+  const resolvedPublicClient = publicClient ?? wagmiPublicClient;
+  const { data: walletClient } = wagmi.useWalletClient({
+    ...chainId !== void 0 ? { chainId } : {}
+  });
+  const resolvedChainId = chainId ?? resolvedPublicClient?.chain?.id;
+  const resolvedAddress = address ?? (resolvedChainId === void 0 ? void 0 : chunkOLDGMKW2_cjs.DEPLOYED_ADDRESSES.fheAirdrop?.confidentialAirdropFactory?.[resolvedChainId] ?? void 0);
+  const encryptorSourceRef = react.useRef(encryptor);
+  encryptorSourceRef.current = encryptor;
+  const client = react.useMemo(() => {
+    if (!resolvedPublicClient) return void 0;
+    if (!resolvedAddress) return void 0;
+    return chunkT5LVV3KY_cjs.createConfidentialAirdropFactoryAdvancedClient({
+      publicClient: resolvedPublicClient,
+      ...walletClient ? { walletClient } : {},
+      address: resolvedAddress,
+      ...resolvedChainId !== void 0 ? { chainId: resolvedChainId } : {},
+      encryptor: () => chunk6ECAHP5O_cjs.resolveEncryptor(encryptorSourceRef.current)
+    });
+  }, [resolvedPublicClient, walletClient, resolvedAddress, resolvedChainId]);
+  return reactQuery.useQuery({
+    queryKey: chunkK6MFFDBJ_cjs.buildQueryKey(
+      "factory:predictAirdropAddress",
+      resolvedChainId,
+      resolvedAddress,
+      params,
+      userSalt,
+      deployer,
+      gasFee
+    ),
+    queryFn: () => client.predictAirdropAddress({
+      params,
+      userSalt,
+      deployer,
+      gasFee
+    }),
+    enabled: !!client && !!params && !!userSalt && !!deployer && gasFee !== void 0,
+    staleTime: 0
+  });
+}
+
+exports.usePredictAirdropAddress = usePredictAirdropAddress;

package/dist/fhe-airdrop/advanced/react/index.d.cts

@@ -0,0 +1,5 @@
+/**
+ * React hooks for `@tokenops/sdk/fhe-airdrop/advanced`. The headline React
+ * subpath stays lean; pre-mine address prediction lives here per R02 ADR P-2.
+ */
+export { usePredictAirdropAddress, type UsePredictAirdropAddressArgs, } from "./usePredictAirdropAddress.js";

package/dist/fhe-airdrop/advanced/react/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * React hooks for `@tokenops/sdk/fhe-airdrop/advanced`. The headline React
+ * subpath stays lean; pre-mine address prediction lives here per R02 ADR P-2.
+ */
+export { usePredictAirdropAddress, type UsePredictAirdropAddressArgs, } from "./usePredictAirdropAddress.js";

package/dist/fhe-airdrop/advanced/react/index.js

@@ -0,0 +1,59 @@
+import { buildQueryKey } from '../../../chunk-HGXNRR25.js';
+import '../../../chunk-XXXDQSHE.js';
+import { createConfidentialAirdropFactoryAdvancedClient } from '../../../chunk-ZHFLRKFY.js';
+import { resolveEncryptor } from '../../../chunk-UOG4PJL5.js';
+import '../../../chunk-FYQ2UW4T.js';
+import '../../../chunk-JFLEEXKP.js';
+import { DEPLOYED_ADDRESSES } from '../../../chunk-COPFW5Z4.js';
+import '../../../chunk-BE2AIZ3K.js';
+import '../../../chunk-Q2GP5UDC.js';
+import '../../../chunk-KWFFIJYX.js';
+import '../../../chunk-IVE3QEGD.js';
+import { useRef, useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { usePublicClient, useWalletClient } from 'wagmi';
+
+function usePredictAirdropAddress(args = {}) {
+  const { params, userSalt, deployer, gasFee, address, chainId, publicClient, encryptor } = args;
+  const wagmiPublicClient = usePublicClient({ ...chainId !== void 0 ? { chainId } : {} });
+  const resolvedPublicClient = publicClient ?? wagmiPublicClient;
+  const { data: walletClient } = useWalletClient({
+    ...chainId !== void 0 ? { chainId } : {}
+  });
+  const resolvedChainId = chainId ?? resolvedPublicClient?.chain?.id;
+  const resolvedAddress = address ?? (resolvedChainId === void 0 ? void 0 : DEPLOYED_ADDRESSES.fheAirdrop?.confidentialAirdropFactory?.[resolvedChainId] ?? void 0);
+  const encryptorSourceRef = useRef(encryptor);
+  encryptorSourceRef.current = encryptor;
+  const client = useMemo(() => {
+    if (!resolvedPublicClient) return void 0;
+    if (!resolvedAddress) return void 0;
+    return createConfidentialAirdropFactoryAdvancedClient({
+      publicClient: resolvedPublicClient,
+      ...walletClient ? { walletClient } : {},
+      address: resolvedAddress,
+      ...resolvedChainId !== void 0 ? { chainId: resolvedChainId } : {},
+      encryptor: () => resolveEncryptor(encryptorSourceRef.current)
+    });
+  }, [resolvedPublicClient, walletClient, resolvedAddress, resolvedChainId]);
+  return useQuery({
+    queryKey: buildQueryKey(
+      "factory:predictAirdropAddress",
+      resolvedChainId,
+      resolvedAddress,
+      params,
+      userSalt,
+      deployer,
+      gasFee
+    ),
+    queryFn: () => client.predictAirdropAddress({
+      params,
+      userSalt,
+      deployer,
+      gasFee
+    }),
+    enabled: !!client && !!params && !!userSalt && !!deployer && gasFee !== void 0,
+    staleTime: 0
+  });
+}
+
+export { usePredictAirdropAddress };

package/dist/fhe-airdrop/advanced/react/usePredictAirdropAddress.d.ts

@@ -0,0 +1,49 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex, PublicClient } from "viem";
+import { type EncryptorSource } from "../../encryption.js";
+import { type AirdropParams } from "../../types.js";
+export interface UsePredictAirdropAddressArgs {
+    params?: AirdropParams;
+    userSalt?: Hex;
+    deployer?: Address;
+    /**
+     * Gas fee in wei to embed into the CREATE2 salt computation. Must match the
+     * fee that will be (or was) active for `deployer` at deploy time:
+     * custom fee if `getCustomFee(deployer).enabled`, otherwise `defaultGasFee`.
+     *
+     * Passing the wrong value produces a different address than the deployed
+     * clone — use `useAirdropFactoryCustomFee` and `useAirdropFactoryDefaultGasFee`
+     * from the headline `@tokenops/sdk/fhe-airdrop/react` subpath to resolve it
+     * correctly.
+     */
+    gasFee?: bigint;
+    /** Override the on-chain factory address. Defaults to {@link DEPLOYED_ADDRESSES}. */
+    address?: Address | undefined;
+    /** Override the chain id used for default address resolution. Defaults to `usePublicClient().chain?.id`. */
+    chainId?: number | undefined;
+    /** Override the viem `PublicClient` — bypasses the wagmi context. */
+    publicClient?: PublicClient | undefined;
+    /** Lazy or eager encryptor source. Not required for predict reads, accepted for client-construction symmetry. */
+    encryptor?: EncryptorSource;
+}
+/**
+ * Compute the deterministic CREATE2 address the factory would produce for an
+ * airdrop clone without deploying it.
+ *
+ * **Advanced surface.** This hook lives on the advanced subpath because the
+ * common "deploy and learn the address" flow is better served by
+ * `useCreateConfidentialAirdropAndGetAddress` on the headline React subpath —
+ * which parses the address from the `ConfidentialAirdropCreated` event and
+ * never has to guess the `gasFee` that was active at deploy time.
+ *
+ * The hook is disabled until all four of `params`, `userSalt`, `deployer`, and
+ * `gasFee` are set.
+ *
+ * @example
+ * import { usePredictAirdropAddress } from "@tokenops/sdk/fhe-airdrop/advanced/react";
+ *
+ * const { data: predictedAddress } = usePredictAirdropAddress({
+ *   params, userSalt, deployer, gasFee: defaultGasFee,
+ * });
+ */
+export declare function usePredictAirdropAddress(args?: UsePredictAirdropAddressArgs): UseQueryResult<Address, Error>;

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

@@ -0,0 +1,308 @@
+import type { Account, Address, Hex, PublicClient, WalletClient } from "viem";
+import type { EncryptedHandle, Role, TxHash } from "../core/brands.js";
+import { type PreflightResult } from "../core/preflight.js";
+import { type SdkTelemetry } from "../core/telemetry.js";
+import type { EncryptedInput, EncryptedViewResult } from "./types.js";
+export type { EncryptedViewResult } from "./types.js";
+export interface ConfidentialAirdropClientConfig {
+    publicClient: PublicClient;
+    walletClient?: WalletClient | undefined;
+    /** Deployed airdrop clone address. */
+    address: Address;
+    /**
+     * FHEVM ACL contract address override. When omitted, resolved from
+     * `publicClient.chain?.id` via the SDK's chain registry; the constructor
+     * throws `DeploymentAddressUnavailableError` if neither is available.
+     * Required because `getClaimAmount` filters the receipt for ACL grants
+     * to extract the returned handle.
+     */
+    aclAddress?: Address | undefined;
+    /**
+     * Optional telemetry sink. When provided, the SDK emits a `fhe-airdrop.client.init`
+     * event on construction and brackets public write methods with named spans
+     * (`fhe-airdrop.client.claim`, `…getClaimAmount`, …). Defaults to a no-op —
+     * zero overhead, zero leakage of consumer-side identifiers.
+     *
+     * The shape is structurally compatible with `NoopTelemetry` / `ConsoleTelemetry` /
+     * `TokenOpsTelemetry` exported from `@tokenops/sdk/telemetry`.
+     */
+    telemetry?: SdkTelemetry | undefined;
+}
+/**
+ * Args for `claim()` / `getClaimAmount()`.
+ *
+ * The admin produces `{ encryptedInput, signature }` off-chain (typically
+ * server-side) by encrypting the allocation with `userAddress: recipient`
+ * (the Zama input proof MUST be bound to the recipient — the contract's
+ * `FHE.fromExternal` rejects proofs bound to any other address) and then
+ * signing the resulting handle with {@link signClaimAuthorization}. The
+ * recipient submits exactly that pair — the SDK does not re-encrypt.
+ *
+ * The signature commits to a specific `bytes32` handle via EIP-712, so
+ * re-encrypting the same plaintext locally would produce a different handle
+ * and the signature would no longer match. That is why `encryptedInput` is
+ * required and there is no plaintext `amount` field on this type.
+ */
+export interface ClaimArgs {
+    /** Pre-encrypted external `euint64` input — must match the handle the admin signed. */
+    encryptedInput: EncryptedInput;
+    /** EIP-712 signature from an address with DEFAULT_ADMIN_ROLE on this clone. */
+    signature: Hex;
+    /**
+     * ETH value (in wei) to attach as `msg.value`. Defaults to `gasFee()` fetched
+     * live if omitted.
+     *
+     * Pre-fetch and cache with `await airdrop.gasFee()` when displaying the fee in
+     * the UI before the user clicks submit — this avoids an extra RPC round-trip and
+     * lets you present the exact cost upfront.
+     */
+    value?: bigint;
+    /** Override the submitting account. Defaults to `walletClient.account`. */
+    account?: Account | Address;
+}
+/** Args for {@link ConfidentialAirdropClient.getClaimAmount} — same shape as {@link ClaimArgs} minus `value` (the contract is not payable). */
+export interface GetClaimAmountArgs {
+    /** Pre-encrypted external `euint64` input — must match the handle the admin signed. */
+    encryptedInput: EncryptedInput;
+    /** EIP-712 signature from an address with DEFAULT_ADMIN_ROLE on this clone. */
+    signature: Hex;
+    /** Override the submitting account. Defaults to `walletClient.account`. */
+    account?: Account | Address;
+}
+/** Args for {@link ConfidentialAirdropClient.isSignatureValid}. */
+export interface IsSignatureValidArgs {
+    /** `externalEuint64` handle bytes32 — the same handle the admin signed. */
+    encryptedAmountHandle: Hex;
+    /** EIP-712 admin signature over `Claim(address recipient, bytes32 encryptedAmount)`. */
+    signature: Hex;
+    /**
+     * Address the contract will treat as `msg.sender` during the call.
+     * The on-chain check recomputes the struct hash over `(msg.sender, encryptedAmount)`,
+     * so the result varies per-caller — typically the wallet that intends to claim.
+     */
+    caller: Address;
+}
+/**
+ * Typed wrapper around a deployed `ConfidentialAirdropCloneable` clone.
+ *
+ * The admin issues claims by encrypting the allocation **bound to the
+ * recipient address** (Zama input proofs are bound to `(contractAddress,
+ * userAddress)` — the contract's `FHE.fromExternal` will reject any other
+ * binding) and signing the handle. The recipient calls
+ * {@link ConfidentialAirdropClient.claim} with exactly that `{ encryptedInput,
+ * signature }` pair; the SDK never re-encrypts on the recipient side because
+ * the signature commits to a specific handle.
+ *
+ * @example
+ * const airdrop = createConfidentialAirdropClient({
+ *   publicClient, walletClient,
+ *   address: airdropAddress,
+ * });
+ * await airdrop.claim({ encryptedInput, signature });
+ */
+export declare class ConfidentialAirdropClient {
+    #private;
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    readonly address: Address;
+    constructor(config: ConfidentialAirdropClientConfig);
+    /**
+     * The FHEVM ACL contract address used by encrypted-view methods to parse
+     * `ACL.Allowed` events. Resolved lazily on first access; throws
+     * `DeploymentAddressUnavailableError` if no override was passed and the
+     * SDK does not have an ACL deployed for the connected chain.
+     */
+    get aclAddress(): Address;
+    /** ERC-7984 confidential token this airdrop was deployed for. Immutable arg. */
+    token(): Promise<Address>;
+    /** Per-claim gas fee in wei. Immutable arg. Attached as `msg.value` by `claim()` automatically. */
+    gasFee(): Promise<bigint>;
+    /** Unix timestamp when claims become available. Immutable arg. */
+    startTime(): Promise<number>;
+    /** Whether the admin can extend the claim window past `endTime`. Immutable arg. */
+    canExtendClaimWindow(): Promise<boolean>;
+    /** Unix timestamp when claims end. Mutable — can be extended by admin if `canExtendClaimWindow`. */
+    endTime(): Promise<number>;
+    /** Whether claims are currently paused by the admin. */
+    isPaused(): Promise<boolean>;
+    /** Block number at which this clone was deployed. */
+    deploymentBlockNumber(): Promise<bigint>;
+    /**
+     * Check whether a pre-computed signature hash has been consumed.
+     *
+     * The contract keys claim replay-protection on
+     * `keccak256(abi.encode(CLAIM_TYPEHASH, recipient, bytes32(encryptedAmountHandle)))`.
+     * Use this when you already hold the struct hash (e.g. you computed it server-side
+     * while building the claim payload). For the more common case where you hold the
+     * user address and the encrypted handle, use {@link isSignatureClaimed} instead —
+     * it computes the hash for you.
+     *
+     * @param signatureHash `bytes32` storage key — the EIP-712 struct hash of the Claim.
+     */
+    claimedSignatures(signatureHash: Hex): Promise<boolean>;
+    /** `true` if within the claim time window and not paused. Free read — no gas. */
+    isClaimWindowActive(): Promise<boolean>;
+    /** `true` if the current timestamp is past `START_TIME`. */
+    hasClaimStarted(): Promise<boolean>;
+    /** `true` if the current timestamp is past `endTime`. */
+    hasClaimEnded(): Promise<boolean>;
+    /** EIP-712 domain separator for the clone. Useful for off-chain signing tools. */
+    domainSeparator(): Promise<Hex>;
+    /**
+     * EIP-712 type hash for the `Claim(address recipient, bytes32 encryptedAmount)`
+     * struct. Off-chain signers that don't use {@link signClaimAuthorization}
+     * (e.g. custom HSM-backed signers, ledger flows) need this to assemble the
+     * typed-data payload manually.
+     */
+    claimTypehash(): Promise<Hex>;
+    /**
+     * Check whether a claim has been consumed, given the user address and encrypted amount handle.
+     *
+     * This is the method most frontend developers want. Pass the same `user` and
+     * `encryptedAmountHandle` that appear in the admin-issued claim payload; the contract
+     * recomputes the struct hash internally and looks it up in storage.
+     *
+     * Prefer this over {@link claimedSignatures} unless you already hold the pre-computed
+     * `bytes32` struct hash (e.g. from a server-side indexer).
+     *
+     * @param user Recipient address from the claim authorization.
+     * @param encryptedAmountHandle The `externalEuint64` handle (as `Hex`) from the claim payload.
+     */
+    isSignatureClaimed(user: Address, encryptedAmountHandle: EncryptedHandle): Promise<boolean>;
+    /**
+     * Check whether an admin-issued claim authorization is valid for a specific caller,
+     * without consuming it.
+     *
+     * Returns `false` (not a revert) when the signature is **structurally valid** but
+     * fails one of the on-chain checks: already-claimed, claim window inactive, or the
+     * signer lacks `DEFAULT_ADMIN_ROLE`. The on-chain implementation recomputes the
+     * EIP-712 struct hash over `(msg.sender, encryptedAmount)`, so the result is
+     * caller-specific: a signature issued for recipient A is invalid when checked
+     * against caller B. Pass the address that will actually submit the claim.
+     *
+     * **Throws** {@link InvalidSignatureError} (code `TOKENOPS_INVALID_SIGNATURE`)
+     * when the signature bytes are **structurally malformed** — wrong length, invalid
+     * `s`-value range, or unparseable. The on-chain `ECDSA.recover` reverts before
+     * the boolean logic runs in that case, so consumer code must catch this
+     * separately from the `false` return:
+     *
+     * ```ts
+     * try {
+     *   const ok = await airdrop.isSignatureValid({ encryptedAmountHandle, signature, caller });
+     *   if (!ok) { /* signed by non-admin, window closed, or already claimed *\/ }
+     * } catch (err) {
+     *   if (err instanceof InvalidSignatureError) { /* malformed signature bytes *\/ }
+     * }
+     * ```
+     *
+     * Use this to show a pre-claim validation state in the UI before asking the user to
+     * pay gas.
+     */
+    isSignatureValid(args: IsSignatureValidArgs): Promise<boolean>;
+    /**
+     * Read-only preflight for {@link claim}. Runs the deterministic-from-off-chain
+     * checks in parallel and reports any blockers as typed {@link TokenOpsSdkError}s.
+     * Returns `{ ready: true, blockers: [] }` when the claim is safe to submit.
+     *
+     * Preflight is **opt-in**. Consumers who have already validated state can
+     * skip this call and invoke `claim` directly — they'll receive the same
+     * typed errors at write time via the revert mapper.
+     *
+     * Checks performed (all read-only, no gas):
+     * - Claim window started (`block.timestamp ≥ START_TIME`).
+     * - Claim window not closed (`block.timestamp ≤ endTime`).
+     * - Claims not paused.
+     * - Signature not already redeemed by this caller.
+     * - ETH balance covers `GAS_FEE()` (the `msg.value` the claim must attach).
+     *
+     * The EIP-712 admin-signature check is **not** preflight-detectable — the
+     * SDK cannot verify the signer's role without the contract round-trip — and
+     * will still surface as {@link InvalidSignatureError} at write time.
+     *
+     * Pool balance is also **not** preflight-detectable: the clone's confidential
+     * balance is an encrypted `euint64` handle that the SDK cannot read in
+     * plaintext. An unfunded clone will pass preflight and revert on-chain with
+     * {@link FheHandleNotAllowedError} (the FHEVM ACL rejects `FHE.allowTransient`
+     * on an uninitialized handle). Confirm the pool has been funded before
+     * showing `ready: true`.
+     *
+     * @returns `{ ready, blockers }` — same `code` shape the write would throw.
+     */
+    preflightClaim(args: {
+        caller: Address;
+        encryptedAmountHandle: Hex;
+    }): Promise<PreflightResult>;
+    /**
+     * Claim tokens using an EIP-712 admin signature. Sends `GAS_FEE()` ETH with the tx.
+     *
+     * The `encryptedInput` must be the exact handle the admin signed in
+     * {@link signClaimAuthorization}. The signature commits to that handle, so the SDK
+     * does NOT re-encrypt — submit the admin-issued payload as-is.
+     *
+     * @returns Transaction hash.
+     * @example
+     * const fee = await airdrop.gasFee();
+     * const hash = await airdrop.claim({ encryptedInput, signature });
+     */
+    claim(args: ClaimArgs): Promise<Hex>;
+    /**
+     * **This is a write transaction, not a free view. It costs gas.**
+     *
+     * Verify the admin-signed claim allocation and grant the caller decrypt access
+     * to the encrypted amount. Budget gas and `await` the receipt before calling
+     * the Zama relayer's `userDecrypt` — the handle is only valid after the tx lands.
+     *
+     * Internally the contract calls `FHE.allow(handle, msg.sender)`, which persists
+     * the ACL grant on-chain. The handle is extracted from the receipt's ACL `Allowed`
+     * event — `simulateContract` would return a divergent handle and break decryption.
+     *
+     * Does **not** consume the claim (the `claimedSignatures` bit is not set). Call
+     * {@link claim} when the user is ready to transfer tokens.
+     *
+     * @returns `{ handle, hash }` — `handle` is a `euint64` granted to the caller;
+     *   pass it to the Zama relayer's `userDecrypt` to obtain the plaintext amount.
+     */
+    getClaimAmount(args: GetClaimAmountArgs): Promise<EncryptedViewResult>;
+    /**
+     * Withdraw all confidential tokens to `recipient`. `DEFAULT_ADMIN_ROLE` only.
+     *
+     * Calling on a clone whose pool was **never funded** throws
+     * {@link FheHandleNotAllowedError} (code `TOKENOPS_FHE_HANDLE_NOT_ALLOWED`).
+     * The contract calls `FHE.allowTransient` on the confidential balance handle;
+     * when the handle is uninitialized, the FHEVM ACL contract reverts with
+     * `SenderNotAllowed(address)`. Confirm the pool has been funded (e.g. via the
+     * factory's `createAndFund...` variant or a follow-up `confidentialTransfer`)
+     * before calling.
+     */
+    withdraw(recipient: Address, account?: Account | Address): Promise<Hex>;
+    /** Pause or unpause claims. DEFAULT_ADMIN_ROLE only. */
+    setPaused(paused: boolean, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Extend the claim window end time. DEFAULT_ADMIN_ROLE only.
+     * Requires `CAN_EXTEND_CLAIM_WINDOW == true` or the contract reverts.
+     */
+    extendClaimWindow(newEndTime: number, account?: Account | Address): Promise<TxHash>;
+    /** Rescue accidentally sent ERC20 tokens. DEFAULT_ADMIN_ROLE only. */
+    withdrawOtherToken(tokenAddress: Address, recipient: Address, account?: Account | Address): Promise<Hex>;
+    /** Rescue accidentally sent ERC7984 confidential tokens. DEFAULT_ADMIN_ROLE only. */
+    withdrawOtherConfidentialToken(tokenAddress: Address, recipient: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Withdraw collected ETH gas fees. FEE_COLLECTOR_ROLE only.
+     * Pass `amount = 0n` to withdraw the entire balance.
+     */
+    withdrawGasFee(recipient: Address, amount: bigint, account?: Account | Address): Promise<Hex>;
+    hasRole(role: Role, account: Address): Promise<boolean>;
+    grantRole(role: Role, accountTarget: Address, account?: Account | Address): Promise<TxHash>;
+    revokeRole(role: Role, accountTarget: Address, account?: Account | Address): Promise<TxHash>;
+}
+/**
+ * Create a {@link ConfidentialAirdropClient}. Mirrors viem's `create*` convention.
+ *
+ * @example
+ * const airdrop = createConfidentialAirdropClient({
+ *   publicClient, walletClient,
+ *   address: "0xYourAirdropClone",
+ *   encryptor,
+ * });
+ */
+export declare function createConfidentialAirdropClient(config: ConfidentialAirdropClientConfig): ConfidentialAirdropClient;