@tokenops/sdk 1.0.0 → 1.5.1

package/dist/fhe/sepolia-encryptor.d.ts

@@ -5,6 +5,24 @@ import type { Encryptor } from "../fhe-vesting/encryption.js";
 export declare const SEPOLIA_CHAIN_ID: 11155111;
 /** Mainnet chain id (`1`). Same use as {@link SEPOLIA_CHAIN_ID}. */
 export declare const MAINNET_CHAIN_ID: 1;
+/**
+ * Lifecycle phase reported by the `onPhase` callback of
+ * {@link createSepoliaEncryptor} / `createSepoliaEncryptorWeb`.
+ *
+ * - `"initializing"` — the helper started constructing the underlying Zama
+ *   relayer instance (module resolution + constructor; cheap and local).
+ * - `"downloading-params"` — the relayer's real lazy initialization began:
+ *   worker bring-up plus fetching the FHE public key and public params
+ *   (several MB on a cold cache; near-instant when served from cache).
+ * - `"ready"` — initialization completed; subsequent encrypts skip the
+ *   download entirely.
+ *
+ * Phases carry **no** percentages, byte counts, or time estimates — neither
+ * `@zama-fhe/sdk@3` nor the underlying relayer SDK exposes any
+ * download-progress API, so anything finer-grained would be fabricated.
+ * If upstream later exposes real progress this union will widen.
+ */
+export type EncryptorInitPhase = "initializing" | "downloading-params" | "ready";
 /** Subset of `@zama-fhe/sdk/node`'s `GenericLogger` we accept. Mirrored
  * structurally so consumers don't need to import the optional peer dep just
  * to type-narrow a logger arg. */
@@ -69,6 +87,26 @@ export interface CreateSepoliaEncryptorOptions {
      * that want to exercise the fetch path).
      */
     fheArtifactCacheTTL?: number;
+    /**
+     * Observe the encryptor's initialization lifecycle (see
+     * {@link EncryptorInitPhase}). `RelayerNode` initializes its worker pool
+     * lazily and exposes no status events, so the phases bracket the first
+     * operation that triggers the real init:
+     *
+     * - `"initializing"` fires when this helper starts (module load +
+     *   `RelayerNode` construction).
+     * - `"downloading-params"` fires immediately before the first `encrypt`
+     *   call, which is what actually spawns the worker pool and fetches the
+     *   FHE public key + params.
+     * - `"ready"` fires once that first `encrypt` resolves. If it rejects,
+     *   `"ready"` is not fired and the next attempt re-fires
+     *   `"downloading-params"` (the underlying SDK retries init from scratch).
+     *
+     * No fake progress: no percentages, byte counts, or timers — upstream
+     * exposes no download-progress API. Callback exceptions are swallowed so
+     * a UI observer can never break encryption.
+     */
+    onPhase?: (phase: EncryptorInitPhase) => void;
 }
 /**
  * Returned by {@link createSepoliaEncryptor}. Carries the underlying

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

@@ -4,9 +4,9 @@ import { ConfidentialAirdropFactoryClient, type ConfidentialAirdropFactoryClient
  * 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
+ * **Why this is "advanced" surface.** Most 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

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

@@ -1,21 +1,22 @@
 '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');
+var chunk4WPGQSNT_cjs = require('../../chunk-4WPGQSNT.cjs');
+require('../../chunk-TIUKIY5V.cjs');
+require('../../chunk-FWHYQZ5E.cjs');
+require('../../chunk-KLKI352M.cjs');
+require('../../chunk-PUPKNW3R.cjs');
+require('../../chunk-JK4XMMKM.cjs');
 require('../../chunk-VJKZWYYJ.cjs');
 require('../../chunk-66IHPTOK.cjs');
-require('../../chunk-56UI7LUR.cjs');
+require('../../chunk-67OV5CX2.cjs');
 
 
 
 Object.defineProperty(exports, "ConfidentialAirdropFactoryAdvancedClient", {
   enumerable: true,
-  get: function () { return chunkT5LVV3KY_cjs.ConfidentialAirdropFactoryAdvancedClient; }
+  get: function () { return chunk4WPGQSNT_cjs.ConfidentialAirdropFactoryAdvancedClient; }
 });
 Object.defineProperty(exports, "createConfidentialAirdropFactoryAdvancedClient", {
   enumerable: true,
-  get: function () { return chunkT5LVV3KY_cjs.createConfidentialAirdropFactoryAdvancedClient; }
+  get: function () { return chunk4WPGQSNT_cjs.createConfidentialAirdropFactoryAdvancedClient; }
 });

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

@@ -1,13 +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).
+ * client to keep the common path lean.
  *
  * 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).
+ * `createConfidentialAirdrop` returns `{ hash, airdrop }` directly.
  */
 export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient, } from "./factory-advanced.js";
 export type { PredictAirdropArgs } from "../factory.js";

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

@@ -1,13 +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).
+ * client to keep the common path lean.
  *
  * 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).
+ * `createConfidentialAirdrop` returns `{ hash, airdrop }` directly.
  */
 export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient, } from "./factory-advanced.js";
 export type { PredictAirdropArgs } from "../factory.js";

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

@@ -1,8 +1,9 @@
-export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient } from '../../chunk-ZHFLRKFY.js';
-import '../../chunk-UOG4PJL5.js';
-import '../../chunk-JFLEEXKP.js';
-import '../../chunk-COPFW5Z4.js';
-import '../../chunk-BE2AIZ3K.js';
+export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient } from '../../chunk-ODLTEGHB.js';
+import '../../chunk-DUZIIRPF.js';
+import '../../chunk-7VELUOMI.js';
+import '../../chunk-SG65XWH7.js';
+import '../../chunk-XGGTQQFH.js';
+import '../../chunk-ZA673I3O.js';
 import '../../chunk-Q2GP5UDC.js';
 import '../../chunk-KWFFIJYX.js';
-import '../../chunk-IVE3QEGD.js';
+import '../../chunk-QBJ7O2B4.js';

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

@@ -1,16 +1,17 @@
 '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');
+var chunkT46YXSBP_cjs = require('../../../chunk-T46YXSBP.cjs');
+require('../../../chunk-MCRBVJGZ.cjs');
+var chunk4WPGQSNT_cjs = require('../../../chunk-4WPGQSNT.cjs');
+var chunkTIUKIY5V_cjs = require('../../../chunk-TIUKIY5V.cjs');
+require('../../../chunk-FAXIIH5R.cjs');
+require('../../../chunk-FWHYQZ5E.cjs');
+require('../../../chunk-KLKI352M.cjs');
+var chunkPUPKNW3R_cjs = require('../../../chunk-PUPKNW3R.cjs');
+require('../../../chunk-JK4XMMKM.cjs');
 require('../../../chunk-VJKZWYYJ.cjs');
 require('../../../chunk-66IHPTOK.cjs');
-require('../../../chunk-56UI7LUR.cjs');
+require('../../../chunk-67OV5CX2.cjs');
 var react = require('react');
 var reactQuery = require('@tanstack/react-query');
 var wagmi = require('wagmi');
@@ -23,22 +24,22 @@ function usePredictAirdropAddress(args = {}) {
     ...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 resolvedAddress = address ?? (resolvedChainId === void 0 ? void 0 : chunkPUPKNW3R_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({
+    return chunk4WPGQSNT_cjs.createConfidentialAirdropFactoryAdvancedClient({
       publicClient: resolvedPublicClient,
       ...walletClient ? { walletClient } : {},
       address: resolvedAddress,
       ...resolvedChainId !== void 0 ? { chainId: resolvedChainId } : {},
-      encryptor: () => chunk6ECAHP5O_cjs.resolveEncryptor(encryptorSourceRef.current)
+      encryptor: () => chunkTIUKIY5V_cjs.resolveEncryptor(encryptorSourceRef.current)
     });
   }, [resolvedPublicClient, walletClient, resolvedAddress, resolvedChainId]);
   return reactQuery.useQuery({
-    queryKey: chunkK6MFFDBJ_cjs.buildQueryKey(
+    queryKey: chunkT46YXSBP_cjs.buildQueryKey(
       "factory:predictAirdropAddress",
       resolvedChainId,
       resolvedAddress,

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

@@ -1,5 +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.
+ * subpath stays lean; pre-mine address prediction lives here.
  */
 export { usePredictAirdropAddress, type UsePredictAirdropAddressArgs, } from "./usePredictAirdropAddress.js";

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

@@ -1,5 +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.
+ * subpath stays lean; pre-mine address prediction lives here.
  */
 export { usePredictAirdropAddress, type UsePredictAirdropAddressArgs, } from "./usePredictAirdropAddress.js";

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

@@ -1,14 +1,15 @@
-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 { buildQueryKey } from '../../../chunk-ORFTDNFZ.js';
+import '../../../chunk-6R4KNAPK.js';
+import { createConfidentialAirdropFactoryAdvancedClient } from '../../../chunk-ODLTEGHB.js';
+import { resolveEncryptor } from '../../../chunk-DUZIIRPF.js';
+import '../../../chunk-ZWXJTBZO.js';
+import '../../../chunk-7VELUOMI.js';
+import '../../../chunk-SG65XWH7.js';
+import { DEPLOYED_ADDRESSES } from '../../../chunk-XGGTQQFH.js';
+import '../../../chunk-ZA673I3O.js';
 import '../../../chunk-Q2GP5UDC.js';
 import '../../../chunk-KWFFIJYX.js';
-import '../../../chunk-IVE3QEGD.js';
+import '../../../chunk-QBJ7O2B4.js';
 import { useRef, useMemo } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { usePublicClient, useWalletClient } from 'wagmi';

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

@@ -239,6 +239,8 @@ export declare class ConfidentialAirdropClient {
      * {@link signClaimAuthorization}. The signature commits to that handle, so the SDK
      * does NOT re-encrypt — submit the admin-issued payload as-is.
      *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
      * @returns Transaction hash.
      * @example
      * const fee = await airdrop.gasFee();

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

@@ -71,6 +71,14 @@ export interface EncryptUint64BatchArgs {
  * `userAddress` MUST be the **recipient** (not the admin), because the contract's
  * `FHE.fromExternal` rejects proofs bound to any other address.
  *
+ * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+ * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+ * ERC-20. Amount parameters are base units of the token's actual decimals:
+ * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+ * transparent TTT test token uses 18 decimals. `value` (and each entry of
+ * `values` in {@link encryptUint64Batch}) follows this convention when it
+ * encodes a token amount.
+ *
  * @param args Encryption request; `value` must fit in `uint64` (0 to 2^64-1).
  * @returns `{ handle: Hex, inputProof: Hex }` — pass both to the contract.
  * @example

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

@@ -2,7 +2,7 @@ import type { Account, Address, Hex, PublicClient, WalletClient } from "viem";
 import { type TxHash } from "../core/brands.js";
 import { type SdkTelemetry } from "../core/telemetry.js";
 import { type Encryptor, type EncryptorSource } from "./encryption.js";
-import type { AirdropParams, CustomFee, EncryptedInput } from "./types.js";
+import type { AirdropParams, CreateAirdropPreflightReport, CustomFee, EncryptedInput } from "./types.js";
 export interface ConfidentialAirdropFactoryClientConfig {
     publicClient: PublicClient;
     walletClient?: WalletClient;
@@ -106,7 +106,7 @@ export type FundAirdropArgs = (FundAirdropArgsCommon & {
  * and {@link ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop}.
  *
  * Branded `hash: TxHash` and `airdrop: Address` so consumers can't accidentally
- * swap them at the destructure site (R03 S-1 anti-footgun).
+ * swap them at the destructure site.
  */
 export interface CreateAirdropResult {
     /** Tx hash that deployed the clone. */
@@ -114,6 +114,27 @@ export interface CreateAirdropResult {
     /** Address of the deployed clone, parsed from the `ConfidentialAirdropCreated` event. */
     airdrop: Address;
 }
+/** Arguments for {@link ConfidentialAirdropFactoryClient.preflightCreateAirdrop}. */
+export interface PreflightCreateAirdropArgs {
+    /** The airdrop parameters that will be passed to the create call. */
+    params: AirdropParams;
+    /** The address that will send the create transaction (`msg.sender`). */
+    creator: Address;
+    /**
+     * The `userSalt` planned for the create call. Optional — when supplied, the
+     * preflight also predicts the CREATE2 clone address and reports whether a
+     * clone already exists there (a repeat create with the same salt reverts).
+     */
+    userSalt?: Hex;
+    /**
+     * Set `true` when the plan is `createAndFundConfidentialAirdrop` (or a
+     * follow-up `fundConfidentialAirdrop`). Funding pulls tokens from the
+     * creator via `confidentialTransferFrom`, so a missing factory-operator
+     * approval becomes a blocker. When `false`/omitted, the operator state is
+     * still reported (`isFactoryOperator`) but does not block a create-only tx.
+     */
+    funding?: boolean;
+}
 export interface PredictAirdropArgs {
     params: AirdropParams;
     userSalt: Hex;
@@ -146,11 +167,10 @@ export declare class ConfidentialAirdropFactoryClient {
      * Deploy a new airdrop clone via the factory and return its address, parsed
      * from the `ConfidentialAirdropCreated` event in the tx receipt.
      *
-     * **This is the headline factory entry point.** R02 ADR P-1 collapses the
-     * old hash-only + `…AndGetAddress` pair down to one rich-return method —
-     * 90 %+ of consumers want the deployed address back, and the SDK already
-     * waits + parses the event, so there's no reason to make consumers do it
-     * themselves.
+     * **This is the headline factory entry point.** It returns one rich-return
+     * shape: most consumers want the deployed address back, and the SDK already
+     * waits for and parses the event, so there's no reason to make consumers do
+     * it themselves.
      *
      * Internally: `writeContract` → {@link PublicClient.waitForTransactionReceipt} →
      * `parseEventLogs({ eventName: "ConfidentialAirdropCreated" })`.
@@ -173,9 +193,17 @@ export declare class ConfidentialAirdropFactoryClient {
      * Prerequisites: caller must have set this factory as an operator on the
      * token: `token.setOperator(factoryAddress, deadline)`.
      *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
      * Symmetric with {@link ConfidentialAirdropFactoryClient.createConfidentialAirdrop}
      * — both return `{ hash, airdrop }` parsed from the
-     * `ConfidentialAirdropCreated` event (R02 ADR P-1).
+     * `ConfidentialAirdropCreated` event.
      *
      * @example
      * const { hash, airdrop } = await factory.createAndFundConfidentialAirdrop({
@@ -189,6 +217,14 @@ export declare class ConfidentialAirdropFactoryClient {
      * Prerequisites: caller must have set this factory as an operator on the token:
      * `token.setOperator(factoryAddress, deadline)`
      *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
      * @returns Transaction hash.
      */
     fundConfidentialAirdrop(args: FundAirdropArgs): Promise<Hex>;
@@ -219,6 +255,14 @@ export declare class ConfidentialAirdropFactoryClient {
      * Symmetry with {@link ConfidentialAirdropFactoryClient.createConfidentialAirdropAndGetAddress}
      * — use this when you also need to seed the pool in the same transaction.
      *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
      * Internally: {@link ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop} →
      * {@link PublicClient.waitForTransactionReceipt} →
      * `parseEventLogs({ eventName: "ConfidentialAirdropCreated" })`.
@@ -243,9 +287,8 @@ export declare class ConfidentialAirdropFactoryClient {
      * Alias for {@link ConfidentialAirdropFactoryClient.implementation} that matches
      * the contract's storage field name (`_airdropImplementation`).
      *
-     * Shipped proactively in R17 for parity with `fhe-vesting`'s
-     * `managerImplementation()` alias (commit 6f6d7bc, closing
-     * backend-integrator-r14 minor). The airdrop factory has the same
+     * Provided for parity with `fhe-vesting`'s `managerImplementation()` alias.
+     * The airdrop factory has the same
      * LibClone shape mirroring `_airdropImplementation` storage, so server
      * devs reading the Solidity first reach for `factory.airdropImplementation()`
      * via autocomplete and would otherwise hit a TS2551 on the SDK's
@@ -270,6 +313,46 @@ export declare class ConfidentialAirdropFactoryClient {
         params: AirdropParams;
         gasFee: bigint;
     }): Promise<Hex>;
+    /**
+     * Read-only preflight for {@link createConfidentialAirdrop} /
+     * {@link createAndFundConfidentialAirdrop}. Runs the
+     * deterministic-from-off-chain checks and reports blockers both as
+     * human-readable strings (`blockers`) and as typed {@link TokenOpsSdkError}s
+     * (`blockerErrors`), index-aligned.
+     *
+     * Preflight is **opt-in**. Consumers who have already validated state can
+     * skip this call and invoke the write directly — they'll receive the same
+     * typed errors at write time via the revert mapper.
+     *
+     * Report fields: `isFactoryOperator`, `gasFee`, `predictedAirdrop`,
+     * `alreadyDeployed`, `ready`, `blockers`, `blockerErrors` — see
+     * {@link CreateAirdropPreflightReport} for the meaning of each.
+     *
+     * Checks performed (all read-only, no gas):
+     * - Structural `params` validation mirroring the factory + clone
+     *   `initialize` requirements (`InvalidArgumentError` blockers): `token` and
+     *   `admin` are checksummed non-zero addresses,
+     *   `startTimestamp < endTimestamp`, and `endTimestamp` is in the future
+     *   (the clone's `initialize` reverts with `EndTimeInPast`).
+     * - Operator: creator has approved this factory as an ERC-7984 operator on
+     *   `params.token` — a blocker only when `funding: true`
+     *   ({@link OperatorNotApprovedError}); otherwise informational via
+     *   `isFactoryOperator`.
+     * - Collision (only when `userSalt` is supplied): bytecode already at the
+     *   predicted CREATE2 address means a repeat create with the same
+     *   `(params, userSalt, gasFee)` would revert
+     *   ({@link AlreadyInitializedError} blocker).
+     *
+     * **Not preflight-detectable — read before trusting `ready: true`:** the
+     * creator's confidential token balance is an encrypted `euint64` the SDK
+     * cannot read in plaintext, and an underfunded `createAndFund` does **not**
+     * revert — the ERC-7984 transfer silently moves an encrypted zero. Confirm
+     * the creator's balance covers the pool before submitting.
+     *
+     * @param args See {@link PreflightCreateAirdropArgs}.
+     * @returns A {@link CreateAirdropPreflightReport}.
+     */
+    preflightCreateAirdrop(args: PreflightCreateAirdropArgs): Promise<CreateAirdropPreflightReport>;
 }
 /**
  * Create a {@link ConfidentialAirdropFactoryClient}. Mirrors viem's `create*` convention.