@tokenops/sdk 1.6.0 → 2.0.0-alpha.1

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

@@ -1,364 +1,623 @@
 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, CreateAirdropPreflightReport, CustomFee, EncryptedInput } from "./types.js";
+import type { EncryptedInput } from "../fhe/types.js";
+import type { WriteAccountOverride } from "./airdrop-base.js";
+import { type DeploymentMode } from "./constants.js";
+import { type EncryptorSource } from "./encryption.js";
+import type { CommonAirdropParams, CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams, MerkleAirdropParams } from "./types.js";
+/** The on-chain `CommonAirdropParams` struct, field-for-field. */
+interface ContractCommonParams {
+    token: Address;
+    startTime: number;
+    endTime: number;
+    canExtendClaimWindow: boolean;
+    unwrappable: boolean;
+    complianceAdmin: Address;
+}
+/**
+ * Convert the SDK's `"clone"` / `"uups"` name to the contract's
+ * `DeploymentMode` ordinal.
+ *
+ * The string union is the SDK's currency everywhere else; the ordinal exists
+ * only at the ABI edge. Keeping the conversion in one exported function makes
+ * an inverted mapping a one-line test failure rather than a silently
+ * upgradeable instance.
+ *
+ * @param mode Deployment shell to select.
+ * @returns The `uint8` the factory expects.
+ */
+export declare function toDeploymentModeOrdinal(mode: DeploymentMode): number;
+/**
+ * Project {@link CommonAirdropParams} onto the contract's struct.
+ *
+ * The two shapes are already identical, so this is a re-assembly rather than a
+ * translation — and that is the point: it pins the field set and their order to
+ * the vendored ABI, so a struct change in a future contract commit surfaces
+ * here instead of as a silently mis-encoded tuple.
+ *
+ * @param common Create-time fields shared by both airdrop variants.
+ * @returns The struct in the ABI's declared field order.
+ */
+export declare function toContractCommonParams(common: CommonAirdropParams): ContractCommonParams;
+/** @alpha */
 export interface ConfidentialAirdropFactoryClientConfig {
     publicClient: PublicClient;
     walletClient?: WalletClient;
-    /** Override the on-chain factory address. Falls back to `getFheAirdropFactoryAddress(chainId)`. */
+    /** Override the on-chain factory address. Falls back to {@link requireFheAirdropFactoryAddress} keyed by chain id. */
     address?: Address;
-    /** Explicit chain id used to look up the default factory address. Defaults to `publicClient.chain?.id`. */
+    /**
+     * Chain id used for the support check and the default address lookup.
+     * Defaults to `publicClient.chain?.id`; one of the two must resolve, because
+     * the client refuses to talk to a chain it cannot name.
+     */
     chainId?: number | undefined;
     /**
-     * Default encryptor used by fund methods. Optional at construction time but
-     * required at call time for `createAndFundConfidentialAirdrop` and `fundConfidentialAirdrop`.
+     * Default encryptor for the fund methods. Optional here and required only at
+     * call time, so a React host can hand over a lazy factory that resolves
+     * against whatever relayer the provider currently holds.
      */
     encryptor?: EncryptorSource | 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.factory.createConfidentialAirdrop`, `…createAndFundConfidentialAirdrop`, …).
-     * Defaults to a no-op — zero overhead, zero leakage of consumer-side identifiers.
+     * (`fhe-airdrop.factory.createEcdsaAirdrop`, …). 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;
 }
-export interface CreateAirdropArgs {
-    params: AirdropParams;
-    /** Any unique 32-byte salt. Combined with msg.sender to derive the CREATE2 salt. */
-    userSalt: Hex;
-    account?: Account | Address | undefined;
-}
-/** Common fields for {@link CreateAndFundAirdropArgs} — discriminated below. */
-interface CreateAndFundAirdropArgsCommon {
-    params: AirdropParams;
-    userSalt: Hex;
-    /**
-     * Plaintext token amount. The SDK encrypts via `encryptor`. Mutually
-     * exclusive with `encryptedInput` — supply exactly one.
-     */
-    amount?: bigint;
-    encryptor?: Encryptor;
-    /** Pre-encrypted input — mutually exclusive with `amount`. */
-    encryptedInput?: EncryptedInput;
-    account?: Account | Address;
-}
 /**
- * Discriminated union: provide EITHER an encryptor (the SDK encrypts `amount`)
- * OR a pre-built `encryptedInput`. Passing both is a compile error.
+ * The encrypted pool amount for a fund-style write, as exactly one of a
+ * plaintext the SDK encrypts or a ciphertext the caller already built.
+ *
+ * The union is discriminated with `never` rather than left as two optional
+ * fields so that passing both is a compile error: a stale plaintext sitting
+ * next to a pre-built handle is a silent divergence from what actually moves
+ * on-chain.
+ *
+ * @alpha
  */
-export type CreateAndFundAirdropArgs = (CreateAndFundAirdropArgsCommon & {
-    /** Plaintext token amount. The SDK encrypts via `encryptor`. */
+export type FundInput = {
+    /** Base units of the ERC-7984 token (6 decimals on the TokenOps tokens). */
     amount: bigint;
-    encryptor?: Encryptor | undefined;
+    /** Overrides the client's default encryptor for this call. */
+    encryptor?: EncryptorSource | undefined;
     encryptedInput?: never;
-}) | (CreateAndFundAirdropArgsCommon & {
-    /** Pre-encrypted input — bypasses `encryptor`. */
+} | {
+    /** Must be bound to `(factoryAddress, funderAddress)` — the factory is what calls `FHE.fromExternal`. */
     encryptedInput: EncryptedInput;
     amount?: never;
     encryptor?: never;
-});
-/** Common fields for {@link FundAirdropArgs} — discriminated below. */
-interface FundAirdropArgsCommon {
-    token: Address;
-    params: AirdropParams;
-    userSalt: Hex;
+};
+/**
+ * Inputs for the address-prediction oracles.
+ *
+ * `params` is required because the ABI declares it, but the factory ignores
+ * it: an instance address commits only to `(implementation-for-variant, mode,
+ * deployer, userSalt)`. Changing the token, window, signer or root does NOT
+ * move the predicted address — only `mode`, `deployer` and `userSalt` do.
+ *
+ * @alpha
+ */
+export interface PredictArgs<P> {
+    params: P;
+    mode: DeploymentMode;
+    /** The account that will send `create*` — CREATE2 salts are per-deployer. */
     deployer: Address;
-    /**
-     * Gas fee in wei that was active for the deployer at airdrop creation time.
-     * Must match the value used when the clone was created (custom fee if one was
-     * set for that deployer, otherwise `defaultGasFee`). Determines the CREATE2
-     * salt and the predicted clone address — a mismatch will target the wrong address.
-     *
-     * Obtain via `factory.getCustomFee(deployer)` or `factory.defaultGasFee()`.
-     */
-    gasFee: bigint;
-    /**
-     * Plaintext token amount. The SDK encrypts via `encryptor`. Mutually
-     * exclusive with `encryptedInput` — supply exactly one.
-     */
-    amount?: bigint;
-    encryptor?: Encryptor;
-    /** Pre-encrypted input — mutually exclusive with `amount`. */
-    encryptedInput?: EncryptedInput;
-    account?: Account | Address;
+    userSalt: Hex;
 }
 /**
- * Discriminated union: provide EITHER an encryptor (the SDK encrypts `amount`)
- * OR a pre-built `encryptedInput`. Passing both is a compile error.
+ * Inputs for the init-code-hash reads.
+ *
+ * Narrower than {@link PredictArgs} on purpose: the hash covers the proxy
+ * init-code only, so `deployer` and `userSalt` cannot affect it and are not
+ * worth making a caller invent.
+ *
+ * @alpha
  */
-export type FundAirdropArgs = (FundAirdropArgsCommon & {
-    /** Plaintext token amount. The SDK encrypts via `encryptor`. */
-    amount: bigint;
-    encryptor?: Encryptor | undefined;
-    encryptedInput?: never;
-}) | (FundAirdropArgsCommon & {
-    /** Pre-encrypted input — bypasses `encryptor`. */
-    encryptedInput: EncryptedInput;
-    amount?: never;
-    encryptor?: never;
-});
+export type InitCodeHashArgs<P> = Pick<PredictArgs<P>, "params" | "mode">;
 /**
- * Rich-return shape from {@link ConfidentialAirdropFactoryClient.createConfidentialAirdrop}
- * and {@link ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop}.
+ * The on-chain `CustomFee` struct returned by `getCustomFee`.
  *
- * Branded `hash: TxHash` and `airdrop: Address` so consumers can't accidentally
- * swap them at the destructure site.
+ * @alpha
  */
-export interface CreateAirdropResult {
-    /** Tx hash that deployed the clone. */
-    hash: TxHash;
-    /** Address of the deployed clone, parsed from the `ConfidentialAirdropCreated` event. */
-    airdrop: Address;
+export interface CustomFee {
+    enabled: boolean;
+    /** Wei, `uint96` on-chain. */
+    gasFee: bigint;
 }
-/** 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;
+/**
+ * The on-chain `CompliancePolicy` struct returned by `getCompliancePolicy`.
+ *
+ * @alpha
+ */
+export interface CompliancePolicy {
+    /** Whether this creator has a policy distinct from `effectiveDelegateToCompliance`'s factory default. */
+    overridden: boolean;
+    delegateToCompliance: boolean;
 }
-export interface PredictAirdropArgs {
-    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.
-     */
-    gasFee: bigint;
+/**
+ * The on-chain `UpgradeabilityPolicy` struct returned by `getUpgradeabilityPolicy`.
+ *
+ * @alpha
+ */
+export interface UpgradeabilityPolicy {
+    /** Whether this creator has a policy distinct from `defaultUpgradeable`'s factory default. */
+    overridden: boolean;
+    allowed: boolean;
 }
 /**
- * Typed wrapper around the deployed `ConfidentialAirdropFactory`. Resolves the
- * factory address per chain and encapsulates FHE encryption for fund methods.
+ * States the live role-concentration fact plainly: this management surface
+ * wraps every fee, implementation, compliance and upgradeability admin entry
+ * point the factory exposes, and on the deployed Sepolia factory all of them
+ * are reachable from one key. See the class TSDoc for the full context —
+ * this string exists so a consumer can surface the same fact in their own UI
+ * (e.g. an admin panel warning) without re-deriving it.
+ *
+ * **Check it rather than trust it.** This is a fixed string describing one
+ * deployment at one point in time; role membership is mutable. The claim is
+ * verifiable on whatever chain you are actually connected to by reading the
+ * five role constants ({@link ConfidentialAirdropFactoryClient.DEFAULT_ADMIN_ROLE},
+ * `FEE_MANAGER_ROLE`, `IMPL_MANAGER_ROLE`, `COMPLIANCE_WIRING_ROLE`,
+ * `UPGRADE_MANAGER_ROLE`) and passing each to
+ * {@link ConfidentialAirdropFactoryClient.getRoleMembers} - see that method's
+ * example for the whole check in six lines. A UI that shows this warning
+ * should prefer the live reads and fall back to this string only when it has
+ * no client to read with.
+ *
+ * @alpha
+ */
+export declare const FACTORY_ROLE_CONCENTRATION_NOTE = "The live factory holds all five factory roles on the deployer account.";
+/**
+ * Typed wrapper around the deployed airdrop v2 `AirdropFactory`.
+ *
+ * Encapsulates the three things a raw ABI call leaves to the caller: FHE
+ * encryption of the pool amount (bound to the factory, which is the contract
+ * that calls `FHE.fromExternal`), the `DeploymentMode` / `DedupMode` ordinal
+ * mapping, and resolving the deployed instance plus its compliance-manager
+ * clone out of the receipt.
+ *
+ * Also exposes the factory's fee, implementation, compliance and
+ * upgradeability admin surface. On the live Sepolia deployment all five
+ * factory roles (admin, feeManager, implManager, complianceWiring,
+ * upgradeManager) and the fee collector are held by the deploying account —
+ * the deploy script has no env var to split them. See
+ * {@link FACTORY_ROLE_CONCENTRATION_NOTE}. Nothing below implies separation
+ * exists; splitting roles is a contracts-repo decision, not something this
+ * client can arrange.
  *
  * @example
- * const factory = createConfidentialAirdropFactoryClient({ publicClient, walletClient, encryptor });
- * const hash = await factory.createConfidentialAirdrop({ params, userSalt });
+ * const factory = createConfidentialAirdropFactoryClient({ publicClient, walletClient });
+ * const { airdrop, complianceManager } = await factory.createMerkleAirdrop({
+ *   params, mode: "clone", userSalt,
+ * });
+ *
+ * @alpha
  */
 export declare class ConfidentialAirdropFactoryClient {
     #private;
     readonly publicClient: PublicClient;
     readonly walletClient?: WalletClient;
     readonly address: Address;
+    readonly chainId: number;
     readonly encryptor?: EncryptorSource;
     constructor(config: ConfidentialAirdropFactoryClientConfig);
     /**
-     * Deploy a new airdrop clone via the factory and return its address, parsed
-     * from the `ConfidentialAirdropCreated` event in the tx receipt.
+     * Deploy an ECDSA-authorised airdrop instance.
      *
-     * **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.
+     * The factory injects `admin = msg.sender`; there is no admin field to set.
+     * Split roles afterwards rather than at create time.
      *
-     * Internally: `writeContract` → {@link PublicClient.waitForTransactionReceipt} →
-     * `parseEventLogs({ eventName: "ConfidentialAirdropCreated" })`.
+     * Guardrailed before the send: the stock-wrapper probe when
+     * `params.common.unwrappable` is set, and a salt-collision
+     * check on the predicted address. See {@link preflightCreate} for the
+     * read-only form of the same checks.
      *
-     * For genuine pre-mine prediction (rare), import
-     * `ConfidentialAirdropFactoryAdvancedClient` from
-     * `@tokenops/sdk/fhe-airdrop/advanced` and call `predictAirdropAddress`.
+     * @param args Instance parameters, deployment shell and the caller's salt.
+     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * @throws {@link NonStockWrapperError} when `unwrappable` is set on a token that is not a stock wrapper.
+     * @throws {@link SaltCollisionError} when this `(mode, deployer, userSalt)` tuple already deployed an instance.
+     * @throws {@link UpgradeabilityNotAllowedError} when `mode: "uups"` is not permitted for the creator.
+     * @throws {@link InvalidArgumentError} when `userSalt` was already consumed by this creator and mode.
      *
      * @example
-     * const { hash, airdrop } = await factory.createConfidentialAirdrop({
-     *   params, userSalt,
+     * const { airdrop } = await factory.createEcdsaAirdrop({
+     *   params: { common, signer, dedupMode: "perAddress" },
+     *   mode: "clone",
+     *   userSalt: keccak256(toBytes("campaign-42")),
      * });
      */
-    createConfidentialAirdrop(args: CreateAirdropArgs): Promise<CreateAirdropResult>;
+    createEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride): Promise<CreateAirdropResult>;
     /**
-     * Deploy and fund a new airdrop in a single transaction, and return its
-     * address. The SDK encrypts `amount` into an `externalEuint64` before
-     * passing to the contract.
+     * Deploy a Merkle-proof airdrop instance.
      *
-     * Prerequisites: caller must have set this factory as an operator on the
-     * token: `token.setOperator(factoryAddress, deadline)`.
+     * `mode: "uups"` is refused outright, before any RPC: the Merkle
+     * implementation's per-account claim state occupies an ERC-7201 namespaced
+     * slot that an earlier revision typed differently, so an in-place upgrade
+     * across that change reinterprets live storage. See
+     * {@link MerkleUupsUnsupportedError}.
      *
-     * **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.
+     * @param args Instance parameters, deployment shell and the caller's salt.
+     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * @throws {@link MerkleUupsUnsupportedError} when `mode` is `"uups"`.
+     * @throws {@link NonStockWrapperError} when `unwrappable` is set on a token that is not a stock wrapper.
+     * @throws {@link SaltCollisionError} when this `(mode, deployer, userSalt)` tuple already deployed an instance.
+     * @throws {@link InvalidArgumentError} when the root is zero and `isMerkleRootMutable` is false, or the salt was already used.
+     */
+    createMerkleAirdrop(args: CreateAirdropArgs<MerkleAirdropParams> & WriteAccountOverride): Promise<CreateAirdropResult>;
+    /**
+     * Deploy an ECDSA airdrop and seed its pool in the same transaction.
      *
-     * **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.
+     * Prerequisite: the funder must have approved this factory as an ERC-7984
+     * operator on the token (`token.setOperator(factoryAddress, deadline)`) —
+     * the factory pulls the pool via `confidentialTransferFrom`.
      *
-     * Symmetric with {@link ConfidentialAirdropFactoryClient.createConfidentialAirdrop}
-     * — both return `{ hash, airdrop }` parsed from the
-     * `ConfidentialAirdropCreated` event.
+     * **Silent-zero transfers.** An ERC-7984 transfer does not revert when the
+     * sender's encrypted balance is short; it moves an encrypted zero instead,
+     * because reverting would leak the balance. A successful receipt therefore
+     * does not prove the pool was funded — confirm the funder's balance first.
      *
-     * @example
-     * const { hash, airdrop } = await factory.createAndFundConfidentialAirdrop({
-     *   params, userSalt, amount: 1_000_000n,
-     * });
+     * @param args Create arguments plus exactly one of `amount` / `encryptedInput`.
+     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * @throws {@link NonStockWrapperError} when `unwrappable` is set on a token that is not a stock wrapper.
+     * @throws {@link SaltCollisionError} when this `(mode, deployer, userSalt)` tuple already deployed an instance.
+     * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor is resolvable.
      */
-    createAndFundConfidentialAirdrop(args: CreateAndFundAirdropArgs): Promise<CreateAirdropResult>;
+    createAndFundEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride): Promise<CreateAirdropResult>;
     /**
-     * Fund an existing (or not-yet-deployed) airdrop with encrypted tokens.
+     * Deploy a Merkle airdrop and seed its pool in the same transaction.
+     *
+     * Prerequisite: the funder must have approved this factory as an ERC-7984
+     * operator on the token (`token.setOperator(factoryAddress, deadline)`).
      *
-     * Prerequisites: caller must have set this factory as an operator on the token:
-     * `token.setOperator(factoryAddress, deadline)`
+     * **Silent-zero transfers.** An ERC-7984 transfer does not revert when the
+     * sender's encrypted balance is short; it moves an encrypted zero instead,
+     * because reverting would leak the balance. A successful receipt therefore
+     * does not prove the pool was funded.
      *
-     * **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.
+     * @param args Create arguments plus exactly one of `amount` / `encryptedInput`.
+     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * @throws {@link MerkleUupsUnsupportedError} when `mode` is `"uups"`.
+     * @throws {@link NonStockWrapperError} when `unwrappable` is set on a token that is not a stock wrapper.
+     * @throws {@link SaltCollisionError} when this `(mode, deployer, userSalt)` tuple already deployed an instance.
+     * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor is resolvable.
+     */
+    createAndFundMerkleAirdrop(args: CreateAirdropArgs<MerkleAirdropParams> & FundInput & WriteAccountOverride): Promise<CreateAirdropResult>;
+    /**
+     * Top up the pool of an instance this factory already deployed.
      *
-     * **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.
+     * Funding always routes through the factory rather than the instance: the
+     * factory is what holds the operator approval, calls `FHE.fromExternal`, and
+     * grants the compliance-manager clone its ACL on the amount. Sending tokens
+     * to the instance directly leaves the pool unusable for compliance reads.
      *
-     * @returns Transaction hash.
+     * **Silent-zero transfers.** A short encrypted balance moves an encrypted
+     * zero instead of reverting — the receipt cannot tell you value arrived.
+     *
+     * @param args The instance address plus exactly one of `amount` / `encryptedInput`.
+     * @returns The transaction hash.
+     * @throws {@link InvalidArgumentError} when `airdrop` was not created by this factory (`UnknownAirdrop`).
      */
-    fundConfidentialAirdrop(args: FundAirdropArgs): Promise<Hex>;
+    fundAirdrop(args: {
+        airdrop: Address;
+    } & FundInput & WriteAccountOverride): Promise<Hex>;
     /**
-     * Deploy a new airdrop clone and return its address, parsed from the
-     * `ConfidentialAirdropCreated` event in the tx receipt.
+     * Where an ECDSA `create*` from `deployer` with this `(mode, userSalt)` pair
+     * would land.
      *
-     * Symmetry helper with the fhe-vesting client. Use this when you want a
-     * one-call "deploy and use" shape; otherwise call
-     * {@link ConfidentialAirdropFactoryClient.createConfidentialAirdrop} and parse
-     * the receipt yourself, or call
-     * {@link ConfidentialAirdropFactoryClient.predictAirdropAddress} before mining.
+     * Prediction is a pure address oracle — it answers even for a deployer that
+     * is not currently allowed to deploy the requested `mode`, so a returned
+     * address is not evidence the create will succeed.
      *
-     * Internally: {@link ConfidentialAirdropFactoryClient.createConfidentialAirdrop} →
-     * {@link PublicClient.waitForTransactionReceipt} →
-     * `parseEventLogs({ eventName: "ConfidentialAirdropCreated" })`.
+     * @param args Prediction inputs; only `mode`, `deployer` and `userSalt` affect the result.
+     * @returns The CREATE2 address of the instance.
+     */
+    predictEcdsaAirdropAddress(args: PredictArgs<EcdsaAirdropParams>): Promise<Address>;
+    /**
+     * Where a Merkle `create*` from `deployer` with this `(mode, userSalt)` pair
+     * would land.
      *
-     * @example
-     * const { hash, airdrop } = await factory.createConfidentialAirdropAndGetAddress({
-     *   params, userSalt,
-     * });
+     * @param args Prediction inputs; only `mode`, `deployer` and `userSalt` affect the result.
+     * @returns The CREATE2 address of the instance.
+     */
+    predictMerkleAirdropAddress(args: PredictArgs<MerkleAirdropParams>): Promise<Address>;
+    /**
+     * Init-code hash of the ECDSA proxy the factory would deploy for `mode`.
+     *
+     * Read it once before a campaign build and again after: the hash tracks the
+     * factory's current implementation pointer, so a change between the two
+     * reads means an implementation swap landed mid-flight and any address you
+     * derived from the first read is stale.
+     *
+     * @param args The variant params (unused on-chain) and the deployment shell.
+     * @returns The `bytes32` init-code hash.
      */
-    createConfidentialAirdropAndGetAddress(args: CreateAirdropArgs): Promise<CreateAirdropResult>;
+    getEcdsaInitCodeHash(args: InitCodeHashArgs<EcdsaAirdropParams>): Promise<Hex>;
     /**
-     * Deploy AND fund a new airdrop clone in one tx, returning its address parsed
-     * from the `ConfidentialAirdropCreated` event in the receipt.
+     * Init-code hash of the Merkle proxy the factory would deploy for `mode`.
      *
-     * Symmetry with {@link ConfidentialAirdropFactoryClient.createConfidentialAirdropAndGetAddress}
-     * — use this when you also need to seed the pool in the same transaction.
+     * @param args The variant params (unused on-chain) and the deployment shell.
+     * @returns The `bytes32` init-code hash.
+     */
+    getMerkleInitCodeHash(args: InitCodeHashArgs<MerkleAirdropParams>): Promise<Hex>;
+    /** How many instances this factory has deployed. Also the upper bound for {@link airdropAt}. */
+    airdropCount(): Promise<bigint>;
+    /**
+     * @param index Zero-based position in deployment order.
+     * @returns The instance address.
+     * @throws {@link InvalidArgumentError} when `index >= airdropCount()` (`IndexOutOfBounds`).
+     */
+    airdropAt(index: bigint): Promise<Address>;
+    /**
+     * Page through deployed instances in deployment order.
      *
-     * **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.
+     * The contract clamps to the tail rather than reverting, so an `offset` past
+     * the end returns an empty page — page until the result is short, not until
+     * it throws.
      *
-     * **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.
+     * @param offset Index to start at.
+     * @param limit Maximum entries to return.
+     * @returns The page, possibly shorter than `limit`.
+     */
+    airdrops(offset: bigint, limit: bigint): Promise<readonly Address[]>;
+    /**
+     * The compliance-manager clone bound to an instance.
      *
-     * Internally: {@link ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop} →
-     * {@link PublicClient.waitForTransactionReceipt} →
-     * `parseEventLogs({ eventName: "ConfidentialAirdropCreated" })`.
+     * Doubles as a provenance check: the factory records this mapping only for
+     * instances it deployed, so a zero address means the instance is not ours.
      *
-     * @example
-     * const { hash, airdrop } = await factory.createAndFundConfidentialAirdropAndGetAddress({
-     *   params, userSalt, amount, encryptor,
-     * });
+     * @param airdrop Instance address.
+     * @returns The clone address, or the zero address when unknown to this factory.
      */
-    createAndFundConfidentialAirdropAndGetAddress(args: CreateAndFundAirdropArgs): Promise<CreateAirdropResult>;
-    /** Change the fee collector address. FEE_MANAGER_ROLE only. */
-    setFeeCollector(newFeeCollector: Address, account?: Account | Address): Promise<TxHash>;
-    /** Change the default per-claim gas fee in wei. FEE_MANAGER_ROLE only. */
-    setDefaultGasFee(newGasFee: bigint, account?: Account | Address): Promise<TxHash>;
-    /** Set a per-creator gas fee override. FEE_MANAGER_ROLE only. */
-    setCustomFee(campaignCreator: Address, gasFee: bigint, account?: Account | Address): Promise<TxHash>;
-    /** Remove a per-creator fee override, reverting to `defaultGasFee`. FEE_MANAGER_ROLE only. */
-    disableCustomFee(campaignCreator: Address, account?: Account | Address): Promise<TxHash>;
-    /** Current LibClone implementation address. */
-    implementation(): Promise<Address>;
-    /**
-     * Alias for {@link ConfidentialAirdropFactoryClient.implementation} that matches
-     * the contract's storage field name (`_airdropImplementation`).
-     *
-     * 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
-     * `implementation()` shape. The canonical `implementation()` method is
-     * retained for backwards-compat and cross-factory uniformity.
-     */
-    airdropImplementation(): Promise<Address>;
-    /** Default per-claim gas fee in wei. Used when no custom fee is set for the campaign creator. */
-    defaultGasFee(): Promise<bigint>;
-    /** Address authorized to collect gas fees from airdrop clones. */
+    complianceManagerOf(airdrop: Address): Promise<Address>;
+    /**
+     * Redirect where accrued claim-fee ETH withdraws to. Requires
+     * `FEE_MANAGER_ROLE`.
+     *
+     * @throws {@link InvalidArgumentError} when `feeCollector` is the zero address (`ZeroFeeCollector`).
+     */
+    setFeeCollector(feeCollector: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Set the per-claim gas fee new instances default to when their creator has
+     * no {@link setCustomFee} override. Requires `FEE_MANAGER_ROLE`.
+     *
+     * @param gasFee Wei, fits `uint96` on-chain.
+     */
+    setDefaultGasFee(gasFee: bigint, account?: Account | Address): Promise<Hex>;
+    /**
+     * Override the default gas fee for one creator. Requires `FEE_MANAGER_ROLE`.
+     *
+     * @param gasFee Wei, fits `uint96` on-chain.
+     */
+    setCustomFee(creator: Address, gasFee: bigint, account?: Account | Address): Promise<Hex>;
+    /**
+     * Drop a creator's {@link setCustomFee} override, reverting them to
+     * {@link defaultGasFee}. Requires `FEE_MANAGER_ROLE`.
+     */
+    disableCustomFee(creator: Address, account?: Account | Address): Promise<Hex>;
+    /** A creator's fee override, if any — `enabled: false` means {@link defaultGasFee} applies instead. */
+    getCustomFee(creator: Address): Promise<CustomFee>;
+    /** Current destination for accrued claim-fee ETH withdrawals. */
     feeCollector(): Promise<Address>;
-    /** Per-creator custom fee override. `enabled` is `false` when no override is set. */
-    getCustomFee(campaignCreator: Address): Promise<CustomFee>;
-    /**
-     * Compute the CREATE2 init-code hash for a given set of params and gas fee.
-     * Useful for deriving the clone address off-chain. Use `predictAirdropAddress` from
-     * `@tokenops/sdk/fhe-airdrop/advanced` for the full address derivation.
-     * @param args `{ params, gasFee }` — must match the values used at deploy time.
-     * @returns `bytes32` init-code hash.
-     */
-    getInitCodeHash(args: {
-        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>;
+    /** Per-claim gas fee new instances default to absent a {@link setCustomFee} override. */
+    defaultGasFee(): Promise<bigint>;
+    /**
+     * Point future `createEcdsaAirdrop*` calls at a new ECDSA implementation.
+     * Requires `IMPL_MANAGER_ROLE`. Does not affect already-deployed instances —
+     * clones point at the implementation live when they were created.
+     *
+     * @throws {@link InvalidArgumentError} when `implementation` is the zero address (`ZeroImplementation`).
+     */
+    setEcdsaImplementation(implementation: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Point future `createMerkleAirdrop*` calls at a new Merkle implementation.
+     * Requires `IMPL_MANAGER_ROLE`. Does not affect already-deployed instances.
+     *
+     * @throws {@link InvalidArgumentError} when `implementation` is the zero address (`ZeroImplementation`).
+     */
+    setMerkleImplementation(implementation: Address, account?: Account | Address): Promise<Hex>;
+    /** The implementation address `createEcdsaAirdrop*` currently clones. */
+    ecdsaImplementation(): Promise<Address>;
+    /** The implementation address `createMerkleAirdrop*` currently clones. */
+    merkleImplementation(): Promise<Address>;
+    /**
+     * Point future compliance-manager clones at a new implementation. Requires
+     * `COMPLIANCE_WIRING_ROLE`. Does not affect already-deployed clones.
+     *
+     * @throws {@link InvalidArgumentError} when `implementation` is the zero address (`ZeroComplianceManagerImpl`).
+     */
+    setComplianceManagerImpl(implementation: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Set the platform-designated compliance delegate every compliance-manager
+     * clone wires in. Requires `COMPLIANCE_WIRING_ROLE`.
+     *
+     * **Ordering:** call this before {@link setDefaultDelegateToCompliance}`(true)`
+     * — the contracts' own deploy script does it in this order, and the reverse
+     * reverts `ZeroComplianceDelegate` (turning delegation on with no delegate
+     * set has nothing to delegate to).
+     *
+     * @throws {@link InvalidArgumentError} when `delegate` is the zero address (`ZeroComplianceDelegate`).
+     */
+    setComplianceDelegate(delegate: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Set whether new instances default to delegating compliance disclosure to
+     * {@link complianceDelegate}. Requires `COMPLIANCE_WIRING_ROLE`.
+     *
+     * **Ordering:** call {@link setComplianceDelegate} first when turning this
+     * on — passing `true` while no delegate is set reverts `ZeroComplianceDelegate`.
+     *
+     * @throws {@link InvalidArgumentError} when `on` is `true` and no delegate is set yet (`ZeroComplianceDelegate`).
+     */
+    setDefaultDelegateToCompliance(on: boolean, account?: Account | Address): Promise<Hex>;
+    /**
+     * Override the default delegate-to-compliance policy for one creator.
+     * Requires `COMPLIANCE_WIRING_ROLE`.
+     */
+    setCompliancePolicy(creator: Address, delegateToCompliance: boolean, account?: Account | Address): Promise<Hex>;
+    /**
+     * Drop a creator's {@link setCompliancePolicy} override, reverting them to
+     * the factory's default. Requires `COMPLIANCE_WIRING_ROLE`.
+     */
+    clearCompliancePolicy(creator: Address, account?: Account | Address): Promise<Hex>;
+    /** The compliance-manager implementation new clones currently point at. */
+    complianceManagerImpl(): Promise<Address>;
+    /** The platform-designated compliance delegate wired into new compliance-manager clones. */
+    complianceDelegate(): Promise<Address>;
+    /** A creator's delegate-to-compliance override, if any — `overridden: false` means the factory default applies instead. */
+    getCompliancePolicy(creator: Address): Promise<CompliancePolicy>;
+    /**
+     * The delegate-to-compliance policy that actually applies to `creator` —
+     * their override if `getCompliancePolicy(creator).overridden`, else the
+     * factory default. Prefer this over composing the two reads yourself.
+     */
+    effectiveDelegateToCompliance(creator: Address): Promise<boolean>;
+    /**
+     * Set whether new instances default to permitting `mode: "uups"`. Requires
+     * `UPGRADE_MANAGER_ROLE`.
+     */
+    setDefaultUpgradeable(allowed: boolean, account?: Account | Address): Promise<Hex>;
+    /**
+     * Override the default upgradeability policy for one creator. Requires
+     * `UPGRADE_MANAGER_ROLE`.
+     */
+    setUpgradeabilityPolicy(creator: Address, allowed: boolean, account?: Account | Address): Promise<Hex>;
+    /**
+     * Drop a creator's {@link setUpgradeabilityPolicy} override, reverting them
+     * to the factory default. Requires `UPGRADE_MANAGER_ROLE`.
+     */
+    clearUpgradeabilityPolicy(creator: Address, account?: Account | Address): Promise<Hex>;
+    /** Whether new instances default to permitting `mode: "uups"` absent a per-creator override. */
+    defaultUpgradeable(): Promise<boolean>;
+    /** A creator's upgradeability override, if any — `overridden: false` means {@link defaultUpgradeable} applies instead. */
+    getUpgradeabilityPolicy(creator: Address): Promise<UpgradeabilityPolicy>;
+    /**
+     * The upgradeability policy that actually applies to `creator` — this is a
+     * plain read of the same value `createEcdsaAirdrop`/`createMerkleAirdrop`
+     * consult when validating `mode: "uups"`. This getter does not itself block
+     * a create; `preflightCreate` (`./guards.js`) is what reads it and reports
+     * an {@link UpgradeabilityNotAllowedError} before the transaction is sent.
+     */
+    effectiveUpgradeable(creator: Address): Promise<boolean>;
+    /** `bytes32` identifier for the role gating {@link setFeeCollector}, {@link setDefaultGasFee}, {@link setCustomFee} and {@link disableCustomFee}. */
+    FEE_MANAGER_ROLE(): Promise<Hex>;
+    /** `bytes32` identifier for the role gating {@link setEcdsaImplementation} and {@link setMerkleImplementation}. */
+    IMPL_MANAGER_ROLE(): Promise<Hex>;
+    /** `bytes32` identifier for the role gating the compliance admin methods. */
+    COMPLIANCE_WIRING_ROLE(): Promise<Hex>;
+    /** `bytes32` identifier for the role gating the upgradeability admin methods. */
+    UPGRADE_MANAGER_ROLE(): Promise<Hex>;
+    /**
+     * OpenZeppelin's root role (`bytes32(0)`), read from the factory rather than
+     * hard-coded. It administers all four roles above.
+     */
+    DEFAULT_ADMIN_ROLE(): Promise<Hex>;
+    /**
+     * Whether `holder` holds `role`.
+     *
+     * The role subject is called `holder`, not `account`: on the writes below
+     * `account` already means "who sends this transaction", and one key cannot
+     * be both - an admin granting a role to somebody else is the normal case.
+     *
+     * @param args.role A `bytes32` from one of the role getters above - not a hand-hashed string.
+     */
+    hasRole(args: {
+        role: Hex;
+        holder: Address;
+    }): Promise<boolean>;
+    /** The role whose holders may {@link grantRole} and {@link revokeRole} `role` - `DEFAULT_ADMIN_ROLE` for all five factory roles. */
+    getRoleAdmin(role: Hex): Promise<Hex>;
+    /** How many accounts hold `role`. */
+    getRoleMemberCount(role: Hex): Promise<bigint>;
+    /**
+     * The `index`-th holder of `role`, in `EnumerableSet` order - which is not
+     * stable across grants and revokes. Prefer {@link getRoleMembers} unless you
+     * genuinely want one entry.
+     */
+    getRoleMember(args: {
+        role: Hex;
+        index: bigint;
+    }): Promise<Address>;
+    /**
+     * Every account currently holding `role`.
+     *
+     * Run it over the five role getters to check
+     * {@link FACTORY_ROLE_CONCENTRATION_NOTE} against the chain you are actually
+     * pointed at, rather than taking the note's word for it.
+     *
+     * @example
+     * const roles = await Promise.all([
+     *   factory.DEFAULT_ADMIN_ROLE(),
+     *   factory.FEE_MANAGER_ROLE(),
+     *   factory.IMPL_MANAGER_ROLE(),
+     *   factory.COMPLIANCE_WIRING_ROLE(),
+     *   factory.UPGRADE_MANAGER_ROLE(),
+     * ]);
+     * const holders = await Promise.all(roles.map((role) => factory.getRoleMembers(role)));
+     * const concentrated = new Set(holders.flat().map((a) => a.toLowerCase())).size === 1;
+     */
+    getRoleMembers(role: Hex): Promise<readonly Address[]>;
+    /**
+     * Grant `role` to `holder`. Requires the role's admin role
+     * ({@link getRoleAdmin}).
+     *
+     * @returns The transaction hash.
+     */
+    grantRole(args: {
+        role: Hex;
+        holder: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Revoke `role` from `holder`. Requires the role's admin role.
+     *
+     * Unlike an airdrop instance, the factory declares no "never empty" floor:
+     * revoking the last `DEFAULT_ADMIN_ROLE` member succeeds, and what it
+     * freezes is **role administration**, permanently. `DEFAULT_ADMIN_ROLE`
+     * administers all four operational roles and itself, so with the set empty
+     * no role can ever be granted or revoked again - including putting an admin
+     * back. The four operational roles keep working for whoever already holds
+     * them: a `FEE_MANAGER_ROLE` holder can still call {@link setDefaultGasFee},
+     * an `IMPL_MANAGER_ROLE` holder can still rotate an implementation. The
+     * factory therefore keeps running with exactly the role holders it had at
+     * that moment, with no way to rotate or remove them. Grant the successor
+     * first.
+     *
+     * @returns The transaction hash.
+     */
+    revokeRole(args: {
+        role: Hex;
+        holder: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Give up `role` yourself.
+     *
+     * The contract's signature is `renounceRole(role, callerConfirmation)` and
+     * it reverts `AccessControlBadConfirmation` unless `callerConfirmation` is
+     * the sender, so this method takes no holder and fills the confirmation from
+     * the resolved sending account. Renouncing for somebody else is not a call
+     * that can succeed; use {@link revokeRole} to remove another account's role.
+     *
+     * The same frozen-role-administration warning as {@link revokeRole} applies,
+     * and more sharply - a sole admin renouncing `DEFAULT_ADMIN_ROLE` is not
+     * blocked here the way it is on an instance. Read that warning for what
+     * actually stops working: role grants and revokes, permanently; not the
+     * operational setters, which keep answering to whoever already holds the
+     * role that gates them.
+     *
+     * @returns The transaction hash.
+     */
+    renounceRole(args: {
+        role: Hex;
+    } & WriteAccountOverride): Promise<Hex>;
 }
 /**
  * Create a {@link ConfidentialAirdropFactoryClient}. Mirrors viem's `create*` convention.
  *
  * @example
  * const factory = createConfidentialAirdropFactoryClient({ publicClient, walletClient, encryptor });
+ *
+ * @alpha
  */
 export declare function createConfidentialAirdropFactoryClient(config: ConfidentialAirdropFactoryClientConfig): ConfidentialAirdropFactoryClient;
 export {};