@tokenops/sdk 2.0.0-alpha.2 → 2.0.0-alpha.3

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

@@ -14,7 +14,8 @@ export interface DisableCustomFeeArgs extends WriteAccountOverride {
  * Requires `FEE_MANAGER_ROLE`.
  *
  * **Invalidates:** `useFactoryCustomFee({ creator })` for the TARGET creator -
- * `variables.creator`, never the sending admin.
+ * `variables.creator`, never the sending admin. Also every `useResolveGasFee`
+ * entry: dropping the override sends this creator back to the default.
  *
  * @example
  * const disableCustomFee = useDisableCustomFee();

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

@@ -16,9 +16,10 @@ export interface FactoryRenounceRoleArgs extends WriteAccountOverride {
  * resolved sending account. To remove a role from somebody else use
  * {@link useFactoryRevokeRole}.
  *
- * **No floor stops a sole admin renouncing here**, unlike an airdrop instance's
- * `LastAdmin` guard. A sole `DEFAULT_ADMIN_ROLE` holder renouncing freezes role
- * administration permanently; grant a successor first.
+ * **A sole `DEFAULT_ADMIN_ROLE` holder cannot renounce** (audit-14): the factory
+ * carries the same `LastAdmin` floor the instances do, so the call reverts
+ * instead of freezing role administration permanently. Grant the successor
+ * first, then renounce.
  *
  * **Invalidates:** every {@link useFactoryHasRole} entry for this factory
  * (prefix, all role/holder pairs), plus its {@link useFactoryRoleMembers} entry

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

@@ -14,13 +14,15 @@ export interface FactoryRevokeRoleArgs extends WriteAccountOverride {
  *
  * Requires `DEFAULT_ADMIN_ROLE`, which administers all five factory roles.
  *
- * **The factory declares no "never empty" floor.** Revoking the last
- * `DEFAULT_ADMIN_ROLE` holder succeeds and permanently freezes role
- * administration - 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, with no way to rotate them. On the live deployment all
- * five roles sit on one key, so show {@link useFactoryRoleMembers}'s `count`
- * next to the button and grant the successor first.
+ * **`DEFAULT_ADMIN_ROLE` is floored at one live member** (audit-14). Revoking
+ * the last holder reverts `LastAdmin` rather than succeeding and freezing role
+ * administration, which is what it used to do. Granting the role to the zero
+ * address reverts `ZeroAdminGrant`, so the floor cannot be satisfied with a
+ * member nobody controls either.
+ *
+ * On the live deployment all five roles sit on one key, so a handover is two
+ * steps: grant the successor, then revoke. Show {@link useFactoryRoleMembers}'s
+ * `count` next to the button and disable it at `1n`.
  *
  * **Invalidates:** this factory's {@link useFactoryHasRole} entry for exactly
  * `(role, holder)` and its {@link useFactoryRoleMembers} entry for `role`.

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

@@ -26,10 +26,11 @@ export interface UseFactoryRoleMembersArgs extends AirdropHookOptions<FactoryRol
  * trusting a fixed string that describes one deployment at one moment.
  *
  * `count` is bundled with the list rather than split into its own hook because
- * it is what a UI needs in the same render to decide whether a revoke is safe -
- * the factory declares no "never empty" floor, so revoking the last
- * `DEFAULT_ADMIN_ROLE` holder succeeds and permanently freezes all role
- * administration.
+ * it is what a UI needs in the same render to decide whether a revoke will be
+ * accepted: since audit-14 the factory floors `DEFAULT_ADMIN_ROLE` at one live
+ * member, so revoking or renouncing the last holder reverts `LastAdmin`.
+ * Disable the button at `count === 1n` rather than letting the user burn gas
+ * discovering it.
  *
  * Unpaginated: factory role sets are operator-sized, not user-sized.
  *
@@ -40,7 +41,7 @@ export interface UseFactoryRoleMembersArgs extends AirdropHookOptions<FactoryRol
  *
  * @example
  * const { data } = useFactoryRoleMembers({ role: roles?.DEFAULT_ADMIN_ROLE });
- * const lastAdmin = data?.count === 1n;
+ * const lastAdmin = data?.count === 1n; // revoke/renounce would revert LastAdmin
  *
  * @alpha
  */

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

@@ -17,7 +17,8 @@ export interface SetCustomFeeArgs extends WriteAccountOverride {
  * **Invalidates:** `useFactoryCustomFee({ creator })` for the TARGET creator -
  * `variables.creator`, never the sending admin. `account` is the submitter and
  * has no cache entry of its own here, so keying the invalidation off it would
- * refresh the wrong row and leave the edited one stale.
+ * refresh the wrong row and leave the edited one stale. Also every
+ * `useResolveGasFee` entry, since an override is what that hook resolves.
  *
  * @example
  * const setCustomFee = useSetCustomFee();

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

@@ -15,9 +15,11 @@ export interface SetDefaultGasFeeArgs extends WriteAccountOverride {
  * instance's `gasFee()` is baked in at create time, so no deployed campaign's
  * fee changes.
  *
- * **Invalidates:** this factory's `useFactoryFees` entry (fn `"fees"`) only.
- * Deliberately NOT any instance's fn `"gasFee"` key - those are immutable
- * per instance and invalidating them would refetch unchanged values.
+ * **Invalidates:** this factory's `useFactoryFees` entry (fn `"fees"`) and every
+ * `useResolveGasFee` entry - the default is what resolves for every creator
+ * without an override, so all of them move at once. Deliberately NOT any
+ * instance's fn `"gasFee"` key: those are frozen at create and invalidating
+ * them would refetch unchanged values.
  *
  * @example
  * const setDefaultFee = useSetDefaultGasFee();

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

@@ -0,0 +1,33 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetMaxGasFeeArgs extends WriteAccountOverride {
+    /** The factory-wide ceiling in wei, `uint96` on-chain. `0n` admits only a zero fee. */
+    maxGasFee: bigint;
+}
+/**
+ * Set the factory's ceiling on every fee `setDefaultGasFee` / `setCustomFee` may
+ * configure, and on the fee resolved at create.
+ *
+ * Requires `DEFAULT_ADMIN_ROLE`, deliberately not `FEE_MANAGER_ROLE` (audit-09):
+ * the fee manager moves fees only within a bound the admin owns. This is the
+ * one fee control that is not a fee-manager operation.
+ *
+ * **Lowering it does not rewrite an already-configured fee.** The stale value
+ * stays in storage and reverts `GasFeeExceedsMaximum` at the next create until
+ * it is lowered too, so a reduction is two steps, not one.
+ *
+ * **Invalidates:** this factory's `useFactoryFees` entry (fn `"fees"`, which
+ * carries `maxGasFee`) and every `useResolveGasFee` entry, since the ceiling
+ * bounds what any creator's fee can resolve to. Deliberately NOT any instance's
+ * fn `"gasFee"` key - an instance's fee is frozen at create and cannot move.
+ *
+ * @example
+ * const setCeiling = useSetMaxGasFee();
+ * await setCeiling.mutateAsync({ maxGasFee: parseEther("0.5") });
+ *
+ * @alpha
+ */
+export declare function useSetMaxGasFee(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetMaxGasFeeArgs>;

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

@@ -137,7 +137,7 @@ export interface WriteAccountOverride {
  * do not care about (an admin panel listing campaigns, say). The ECDSA and
  * Merkle clients extend it and add their own claim path.
  *
- * What it encapsulates beyond the raw ABI is the encrypted-view protocol: five
+ * What it encapsulates beyond the raw ABI is the encrypted-view protocol: six
  * of the contract's disclosure entrypoints look like getters and are not —
  * they mutate ACL state, so they are transactions, and their result must be
  * recovered from the receipt. See {@link extractGrantedHandle}.
@@ -217,8 +217,12 @@ export declare class AirdropBaseClient {
      * Sweep a plain ERC-20 that was sent to the instance by mistake. Requires
      * `RESCUER_ROLE`.
      *
-     * The campaign's own token is ERC-7984, not ERC-20, so it cannot be reached
-     * through this path — use {@link withdrawConfidential} for the pool.
+     * Passing the campaign's own token reverts `CannotRescueAirdropToken`
+     * (audit-05), matching {@link rescueOtherConfidentialToken}. ERC-7984 and
+     * ERC-20 are not disjoint in practice - a wrapper token answers both
+     * interfaces - so "the pool token is confidential, therefore out of reach
+     * here" was never a guarantee, only an assumption. Use
+     * {@link withdrawConfidential} for the pool.
      *
      * @returns The transaction hash.
      */
@@ -469,10 +473,38 @@ export declare class AirdropBaseClient {
      * @alpha
      */
     deploymentMode(): Promise<DeploymentMode>;
+    /**
+     * Re-grant the compliance-manager clone on the instance's current pool
+     * balance, and return the handle it was granted on.
+     *
+     * **Permissionless, and deliberately so** (audit-04). The token rotates the
+     * instance's balance handle on every incoming transfer, including one no
+     * airdrop code observes - a third party transferring in directly - and
+     * grants the fresh handle to the token and the holder only. Without this the
+     * compliance clone's grant can be stranded on a handle the token has already
+     * replaced, with no admin necessarily around to restore it. There is no
+     * argument to abuse: the only handle read is `address(this)`'s own balance,
+     * and the only grantee is the clone wired at initialization.
+     *
+     * This is therefore the normative way to obtain a readable live-balance
+     * handle - and it is a **snapshot, not a subscription**. Grants are
+     * append-only, so the handle this returns stays readable forever; but the
+     * next incoming transfer rotates the instance to a NEW handle the clone was
+     * never granted on. A compliance reader that refreshes once and stops is
+     * reading a stale balance, not a live one. Call it again after any transfer
+     * in, or before each read.
+     *
+     * @returns `{ handle, hash }` - the handle the compliance clone may now decrypt.
+     * @throws {@link ReceiptEventNotFoundError} when the transaction granted no ACL to the clone.
+     */
+    refreshComplianceBalance(args?: WriteAccountOverride): Promise<EncryptedViewResult>;
     /**
      * Read the instance's own remaining pool balance as a handle the **caller**
      * can decrypt. Requires `DISCLOSURE_ADMIN_ROLE`.
      *
+     * Also re-grants the compliance-manager clone on the same handle (audit-04),
+     * so an admin read doubles as a {@link refreshComplianceBalance}.
+     *
      * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`.
      * @throws {@link ReceiptEventNotFoundError} when the transaction granted no ACL to the caller.
      */
@@ -515,11 +547,18 @@ export declare class AirdropBaseClient {
     /**
      * Grant `party` decrypt access to a handle you already hold.
      *
-     * Two gates apply on-chain: the caller must itself be allowed on the handle
-     * (bypassed by `DISCLOSURE_ADMIN_ROLE`), and the *instance* must be allowed
-     * on it — so an arbitrary handle from another contract cannot be laundered
-     * through this campaign. A failure of the first surfaces as
-     * `FheHandleNotAllowedError`.
+     * Two gates apply on-chain. Gate #1: the handle must be **persistently**
+     * user-decryptable in the `(caller, instance)` context - BOTH legs, and a
+     * transient allowance does not satisfy either (audit-06). `DISCLOSURE_ADMIN_ROLE`
+     * bypasses gate #1 only. Gate #2: the instance must be allowed on the handle,
+     * so an arbitrary handle from another contract cannot be laundered through
+     * this campaign.
+     *
+     * **The transient case is the trap.** An `euint64` that just came back from
+     * an FHE op carries a transient allowance, which used to be enough here and
+     * no longer is. Handles worth disclosing come from the encrypted views on
+     * this client, whose grants are persistent. A gate #1 failure surfaces as
+     * `FheHandleNotAllowedError` carrying the offending handle.
      *
      * @param args.handle An existing `euint64` handle — a public pointer, not a value.
      * @returns The transaction hash. No new handle is produced.

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

@@ -3,7 +3,7 @@
  *
  * @alpha
  */
-export declare const AIRDROP_CONTRACTS_COMMIT = "7175ac82f467f0f88c05aba1a4536892999b4251";
+export declare const AIRDROP_CONTRACTS_COMMIT = "c5c12c2087f61bcd5bd1daa802563ed3cd68f002";
 /**
  * Deployment shell selected at create time. Mirrors the contract's `DeploymentMode` enum
  * (`IConfidentialAirdropTypes.sol`): `enum DeploymentMode { Clone, UUPS }`.
@@ -31,3 +31,11 @@ export declare const DEDUP_MODE: {
 };
 /** @alpha */
 export type DedupMode = keyof typeof DEDUP_MODE;
+/**
+ * The largest value `CommonAirdropParams.maxAcceptedGasFee` can carry - the
+ * `uint96` ceiling. Passing it accepts whatever fee the factory resolves, which
+ * is the opt-out, not the default.
+ *
+ * @alpha
+ */
+export declare const UINT96_MAX: bigint;

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

@@ -186,11 +186,24 @@ export declare class EcdsaAirdropClient extends AirdropBaseClient {
      * consuming either replay guard — the same input can still be claimed for
      * real afterwards. No fee.
      *
+     * **It is repeatable, not unconditional** (audit-07). While the claim is
+     * still available this may be called any number of times; once it is not,
+     * this reverts with the same error the consuming claim would raise, in the
+     * same order: the mode's dedup slot first (`AddressAlreadyClaimed` /
+     * `DedupIdAlreadyClaimed`), the EIP-712 digest second (`SignatureAlreadyUsed`).
+     * A rejected preview performs no FHE op, grants no ACL and emits nothing.
+     *
+     * So this is not a probe for "has this been claimed" - use
+     * {@link isSignatureValid}, which never reverts and answers the same
+     * question for free. Reach for this when you want the AMOUNT.
+     *
      * An encrypted view: the contract calls `FHE.allow(amount, msg.sender)`, so
      * the result is recovered from the receipt's ACL `Allowed` event, never
      * from a simulation. See {@link AirdropBaseClient}'s class TSDoc.
      *
      * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`.
+     * @throws {@link AlreadyClaimedError} when this recipient's dedup slot is consumed.
+     * @throws {@link DedupIdConsumedError} when this `dedupId`'s slot is consumed.
      */
     getClaimAmount(args: GetClaimAmountArgs): Promise<EncryptedViewResult>;
     /**

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

@@ -315,4 +315,63 @@ export declare class ClaimWindowClosedError extends TokenOpsSdkError {
         cause?: unknown;
     });
 }
+/**
+ * `create*` refused the fee the factory resolved for this creator: it landed
+ * above their `CommonAirdropParams.maxAcceptedGasFee`.
+ *
+ * The fee is frozen into the instance at initialization and is immutable
+ * afterwards, while the value that resolves is set by the factory's fee manager.
+ * The bound is how a creator declines a fee raised between planning and sending
+ * - so the fix is a deliberate one: re-send with a higher bound, or wait for the
+ * fee to come down. Raising the bound to {@link UINT96_MAX} accepts whatever the
+ * factory charges, now and at every later re-plan.
+ *
+ * @alpha
+ */
+export declare class GasFeeNotAcceptedError extends TokenOpsSdkError {
+    readonly name = "GasFeeNotAcceptedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        /** The fee the factory resolved for this creator, in wei. */
+        resolvedFee?: bigint;
+        /** The bound the creator declared, in wei. */
+        maxAcceptedGasFee?: bigint;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        resolvedFee?: bigint;
+        maxAcceptedGasFee?: bigint;
+        cause?: unknown;
+    });
+}
+/**
+ * The canonical factory's registry does not contain this address, so it is not
+ * an airdrop this SDK deployed.
+ *
+ * Instances are the wrong place to ask. An address with the same ABI, the same
+ * events and a pool the deployer controls is trivial to stand up, and nothing
+ * observable at the instance distinguishes it - `factory.isAirdrop` against a
+ * factory address taken from `src/core/addresses.ts` is the only check that
+ * means anything (audit-10).
+ *
+ * @alpha
+ */
+export declare class UnrecognisedAirdropError extends TokenOpsSdkError {
+    readonly name = "UnrecognisedAirdropError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        factory: Address;
+    };
+    constructor(args: {
+        method: string;
+        /** The address that failed the check. */
+        contractAddress: Address;
+        /** The factory whose registry was consulted. */
+        factory: Address;
+        cause?: unknown;
+    });
+}
 export declare const airdropProductMapper: RevertNameMapper;

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

@@ -1,19 +1,15 @@
+import type { AbiParameterToPrimitiveType, ExtractAbiFunction } from "abitype";
 import type { Account, Address, Hex, PublicClient, WalletClient } from "viem";
 import { type SdkTelemetry } from "../core/telemetry.js";
 import type { EncryptedInput } from "../fhe/types.js";
+import { airdropFactoryAbi as factoryAbi } from "./abis/factory.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;
-}
+type ContractMerkleParams = AbiParameterToPrimitiveType<ExtractAbiFunction<typeof factoryAbi, "createMerkleConfidentialAirdrop">["inputs"][0]>;
+/** The on-chain `CommonAirdropParams` struct, field-for-field, straight off the ABI. */
+type ContractCommonParams = ContractMerkleParams["common"];
 /**
  * Convert the SDK's `"clone"` / `"uups"` name to the contract's
  * `DeploymentMode` ordinal.
@@ -362,11 +358,26 @@ export declare class ConfidentialAirdropFactoryClient {
      * @returns The page, possibly shorter than `limit`.
      */
     airdrops(offset: bigint, limit: bigint): Promise<readonly Address[]>;
+    /**
+     * Whether THIS factory created `candidate` - the genuineness check (audit-10).
+     *
+     * Nothing observable at an instance proves which factory, if any, deployed
+     * it: an attacker can deploy a contract with the same ABI, the same events
+     * and a pool it controls. The only trustworthy question is whether the
+     * canonical factory's own registry contains the address, which is why this
+     * read has to be addressed to a factory taken from
+     * `src/core/addresses.ts` rather than one the instance names.
+     *
+     * @param candidate The address to check.
+     * @returns True when this factory's registry contains `candidate`.
+     */
+    isAirdrop(candidate: Address): Promise<boolean>;
     /**
      * The compliance-manager clone bound to an instance.
      *
-     * 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.
+     * Doubles as a provenance check, though a weaker one than {@link isAirdrop}:
+     * the factory records this mapping only for instances it deployed, so a zero
+     * address means the instance is not ours.
      *
      * @param airdrop Instance address.
      * @returns The clone address, or the zero address when unknown to this factory.
@@ -403,6 +414,37 @@ export declare class ConfidentialAirdropFactoryClient {
     feeCollector(): Promise<Address>;
     /** Per-claim gas fee new instances default to absent a {@link setCustomFee} override. */
     defaultGasFee(): Promise<bigint>;
+    /** The factory's own ceiling on every configurable fee and every create-time resolved fee. */
+    maxGasFee(): Promise<bigint>;
+    /**
+     * Set the factory's ceiling on every fee `setDefaultGasFee`/`setCustomFee`
+     * may configure, and on the fee resolved at create.
+     *
+     * Requires `DEFAULT_ADMIN_ROLE`, deliberately not `FEE_MANAGER_ROLE`: the fee
+     * manager moves fees only within a bound the admin controls. `0n` admits a
+     * zero fee and nothing else.
+     *
+     * Lowering it below an already-configured fee does not rewrite that fee - the
+     * stale value stays in storage and reverts `GasFeeExceedsMaximum` at the next
+     * create until it is lowered too.
+     *
+     * @throws {@link InvalidArgumentError} when `maxGasFee` is below a currently configured fee (`GasFeeExceedsMaximum`).
+     */
+    setMaxGasFee(maxGasFee: bigint, account?: Account | Address): Promise<Hex>;
+    /**
+     * The per-claim fee a `create*` from `creator` would freeze into the new
+     * instance right now: their {@link getCustomFee} override when enabled, else
+     * {@link defaultGasFee}.
+     *
+     * This is the number `CommonAirdropParams.maxAcceptedGasFee` is checked
+     * against, so it is also what to show a creator before they choose a bound.
+     * It is a snapshot, not a quote: `FEE_MANAGER_ROLE` can move it between this
+     * read and the create, which is exactly what the bound exists to catch.
+     *
+     * @param creator The account that will send `create*`.
+     * @returns The resolved fee in wei.
+     */
+    resolveGasFee(creator: Address): Promise<bigint>;
     /**
      * Point future `createEcdsaAirdrop*` calls at a new ECDSA implementation.
      * Requires `IMPL_MANAGER_ROLE`. Does not affect already-deployed instances —
@@ -571,17 +613,15 @@ export declare class ConfidentialAirdropFactoryClient {
     /**
      * 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.
+     * **The factory floors `DEFAULT_ADMIN_ROLE` at one live member** (audit-14),
+     * matching the instances. Renouncing or revoking the sole holder reverts
+     * `LastAdmin`, and granting the role to the zero address reverts
+     * `ZeroAdminGrant`, so the set can neither be emptied nor satisfied by a
+     * member nobody controls. Before audit-14 this succeeded and froze role
+     * administration permanently; it no longer does.
+     *
+     * A handover is still available and is the supported way out: grant the
+     * successor first, then renounce.
      *
      * @returns The transaction hash.
      */

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

@@ -1,6 +1,6 @@
 import type { Address, Hex, PublicClient } from "viem";
 import type { PreflightResult } from "../core/preflight.js";
-import type { DeploymentMode } from "./constants.js";
+import { type DeploymentMode } from "./constants.js";
 import { type AirdropVariant } from "./errors.js";
 import type { ConfidentialAirdropFactoryClient } from "./factory.js";
 import type { EcdsaAirdropParams, MerkleAirdropParams } from "./types.js";
@@ -104,6 +104,49 @@ export interface AssertSaltAvailableArgs {
  * @alpha
  */
 export declare function assertSaltAvailable(args: AssertSaltAvailableArgs): Promise<void>;
+/**
+ * The slice of {@link ConfidentialAirdropFactoryClient} {@link assertGasFeeAccepted}
+ * reads. Structural so this module keeps its runtime-import-free shape; the real
+ * client satisfies it as-is.
+ *
+ * @alpha
+ */
+export interface GasFeeResolver {
+    address: Address;
+    resolveGasFee(creator: Address): Promise<bigint>;
+}
+/**
+ * Inputs for {@link assertGasFeeAccepted}.
+ *
+ * @alpha
+ */
+export interface AssertGasFeeAcceptedArgs {
+    factory: GasFeeResolver;
+    /** The account that will send `create*`; fee overrides are per-creator. */
+    creator: Address;
+    /** `CommonAirdropParams.maxAcceptedGasFee`, in wei. */
+    maxAcceptedGasFee: bigint;
+    /** Label for the thrown error. */
+    method: string;
+}
+/**
+ * Refuse a create whose resolved per-claim fee exceeds the creator's declared bound.
+ *
+ * The contract enforces this too. Doing it here buys the reason: the revert
+ * carries the two numbers but not which factory knob produced them, and a
+ * creator who sees `resolvedFee` next to their own bound can tell a raised
+ * default from a custom override they did not know they had.
+ *
+ * The range check is not redundant with the comparison - a bound outside
+ * `uint96` silently wraps at the ABI edge and could encode as a SMALLER number
+ * than intended, turning "accept anything" into "accept almost nothing".
+ *
+ * @throws {@link InvalidArgumentError} when `maxAcceptedGasFee` is negative or above `UINT96_MAX`.
+ * @throws {@link GasFeeNotAcceptedError} when the factory resolves a fee above the bound.
+ *
+ * @alpha
+ */
+export declare function assertGasFeeAccepted(args: AssertGasFeeAcceptedArgs): Promise<void>;
 /**
  * Inputs for {@link assertPredictionFresh}.
  *
@@ -163,7 +206,8 @@ export type PreflightCreateArgs = PreflightCreateCommon & ({
  * transaction, instead of throwing on the first problem.
  *
  * Same checks and the same typed errors the write path enforces: chain
- * support, the Merkle/UUPS refusal, the creator's effective
+ * support, the Merkle/UUPS refusal, the creator's resolved gas fee against
+ * `common.maxAcceptedGasFee`, the creator's effective
  * upgradeability policy when `mode: "uups"` is requested, the stock-wrapper
  * probe when `unwrappable` is set, a salt collision on the predicted
  * address, and - when `expectedInitCodeHash` is supplied - implementation
@@ -222,6 +266,40 @@ export interface ClaimPreflightTarget {
         signature: Hex;
     }) => Promise<boolean>;
 }
+/**
+ * The slice of {@link ConfidentialAirdropFactoryClient} the genuineness check reads.
+ *
+ * @alpha
+ */
+export interface AirdropRegistry {
+    readonly address: Address;
+    /**
+     * The chain this factory is bound to. Checked against the instance's own
+     * `chainId` before the registry is consulted - a registry answer from the
+     * wrong chain is worse than no answer, because it reads as a `true`.
+     */
+    readonly chainId: number;
+    isAirdrop(candidate: Address): Promise<boolean>;
+}
+/**
+ * Refuse an instance the canonical factory's registry does not contain.
+ *
+ * The factory has to be one the caller already trusts - taken from
+ * `src/core/addresses.ts`, not read off the instance. An instance that names
+ * its own factory proves nothing: a fake instance names a fake factory, which
+ * answers `true`.
+ *
+ * @throws {@link UnrecognisedAirdropError} when the registry does not contain `airdrop`.
+ *
+ * @alpha
+ */
+export declare function assertKnownAirdrop(args: {
+    factory: AirdropRegistry;
+    airdrop: Address;
+    /** The chain the instance being vetted lives on. */
+    chainId: number;
+    method: string;
+}): Promise<void>;
 /**
  * The signature material {@link preflightClaim} needs to check an ECDSA claim.
  *
@@ -265,6 +343,13 @@ export interface PreflightClaimArgs {
      * `isSignatureValid`, it adds the authorisation check to the report.
      */
     signature?: EcdsaClaimPreflightSignature | undefined;
+    /**
+     * The canonical factory, from `src/core/addresses.ts`. Supplying it adds the
+     * genuineness check (audit-10): every other blocker here describes a claim
+     * that will fail, but a claim against a look-alike instance SUCCEEDS and
+     * delivers nothing. Omitting it skips that one check.
+     */
+    factory?: AirdropRegistry | undefined;
 }
 /**
  * The three argument-relation rules the Merkle claim path enforces before it touches the