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

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

@@ -1,40 +1,11 @@
-import type { AbiParameterToPrimitiveType, ExtractAbiFunction } from "abitype";
 import type { Account, Address, Hex, PublicClient, WalletClient } from "viem";
 import { type SdkTelemetry } from "../core/telemetry.js";
+import type { ReceiptMode } from "../core/pending.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 { DeploymentMode } from "./constants.js";
 import { type EncryptorSource } from "./encryption.js";
-import type { CommonAirdropParams, CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams, MerkleAirdropParams } from "./types.js";
-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.
- *
- * 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;
+import type { AirdropVariantParams, CreateAirdropArgs, CreateAirdropResult, CreateCommitments, CreateMerkleAirdropArgs, EcdsaAirdropParams, MerkleAirdropParams, PendingCreateAirdropResult } from "./types.js";
 /** @alpha */
 export interface ConfidentialAirdropFactoryClientConfig {
     publicClient: PublicClient;
@@ -184,6 +155,14 @@ export declare const FACTORY_ROLE_CONCENTRATION_NOTE = "The live factory holds a
  * exists; splitting roles is a contracts-repo decision, not something this
  * client can arrange.
  *
+ * **Safe / multisig signers.** The four creates take `waitForReceipt: false`
+ * and return the committed addresses with `pending: true` (see
+ * {@link PendingCreateAirdropResult}). `fundAirdrop` and the admin
+ * writes already return a bare hash; the operator approval they need
+ * (`setOperator`, `@tokenops/sdk/fhe`) takes `waitForReceipt: false` as well. A post-create role split goes through
+ * {@link planInstanceRoleSplit} plus {@link encodeInstanceRoleSplit} as one
+ * MultiSend batch, not `grantInstanceRoles`.
+ *
  * @example
  * const factory = createConfidentialAirdropFactoryClient({ publicClient, walletClient });
  * const { airdrop, complianceManager } = await factory.createMerkleAirdrop({
@@ -212,9 +191,14 @@ export declare class ConfidentialAirdropFactoryClient {
      * read-only form of the same checks.
      *
      * @param args Instance parameters, deployment shell and the caller's salt.
-     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * @returns The tx hash, the deployed instance, its compliance-manager clone, the clone's
+     *   implementation and the platform delegate it was wired with. With `waitForReceipt: false`,
+     *   a {@link PendingCreateAirdropResult}.
+     * @throws {@link InvalidArgumentError} on `gasFee` when the resolved fee exceeds the factory's `maxGasFee` ceiling, checked before the creator's bound.
+     * @throws {@link GasFeeNotAcceptedError} when the factory resolves a fee above `common.maxAcceptedGasFee`.
      * @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 CreateCommitmentMismatchError} when a quoted or pinned commitment no longer matches what the factory would deploy.
      * @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.
      *
@@ -225,7 +209,11 @@ export declare class ConfidentialAirdropFactoryClient {
      *   userSalt: keccak256(toBytes("campaign-42")),
      * });
      */
-    createEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride): Promise<CreateAirdropResult>;
+    createEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride & ReceiptMode<true>): Promise<CreateAirdropResult>;
+    /** With `waitForReceipt: false`: returns on submission, before the receipt exists. */
+    createEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride & ReceiptMode<false>): Promise<PendingCreateAirdropResult>;
+    /** With a runtime `boolean`: either result, narrowed by `pending`. */
+    createEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & WriteAccountOverride & ReceiptMode): Promise<CreateAirdropResult | PendingCreateAirdropResult>;
     /**
      * Deploy a Merkle-proof airdrop instance.
      *
@@ -235,14 +223,43 @@ export declare class ConfidentialAirdropFactoryClient {
      * across that change reinterprets live storage. See
      * {@link MerkleUupsUnsupportedError}.
      *
-     * @param args Instance parameters, deployment shell and the caller's salt.
-     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * **Creating from a plan.** Pass the {@link PlannedCampaign} as `plan`, with
+     * `merkleRoot: plan.root`. The plan's leaves are bound to `plan.predictedAddress`, so the
+     * create pins it, refuses a root that differs from `plan.root`, and refuses to send once
+     * the factory's Merkle implementation has moved since the plan was taken
+     * ({@link PredictionDriftError}). A rotation landing after that check is still refused by
+     * the contract ({@link CreateCommitmentMismatchError}). `expected: { airdrop: plan.predictedAddress }`
+     * is the lower-level equivalent of the pin alone.
+     *
+     * @example
+     * const plan = await planMerkleCampaign({
+     *   factory, params, mode, creator, userSalt, recipients, encryptor,
+     * });
+     * await factory.createMerkleAirdrop({
+     *   params: { ...params, merkleRoot: plan.root, isMerkleRootMutable: false },
+     *   mode,
+     *   userSalt,
+     *   plan,
+     * });
+     *
+     * @param args Instance parameters, deployment shell, the caller's salt and, optionally, the plan being realised.
+     * @returns The tx hash, the deployed instance, its compliance-manager clone, the clone's
+     *   implementation and the platform delegate it was wired with. With `waitForReceipt: false`,
+     *   a {@link PendingCreateAirdropResult}.
+     * @throws {@link InvalidArgumentError} on `gasFee` when the resolved fee exceeds the factory's `maxGasFee` ceiling, checked before the creator's bound.
+     * @throws {@link GasFeeNotAcceptedError} when the factory resolves a fee above `common.maxAcceptedGasFee`.
      * @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.
+     * @throws {@link CreateCommitmentMismatchError} when a quoted or pinned commitment no longer matches what the factory would deploy.
+     * @throws {@link PredictionDriftError} when `plan` is given and the factory's Merkle implementation moved since it was taken.
+     * @throws {@link InvalidArgumentError} when the root is zero and `isMerkleRootMutable` is false, the salt was already used, or `params.merkleRoot` / `expected.airdrop` disagrees with `plan`.
      */
-    createMerkleAirdrop(args: CreateAirdropArgs<MerkleAirdropParams> & WriteAccountOverride): Promise<CreateAirdropResult>;
+    createMerkleAirdrop(args: CreateMerkleAirdropArgs & WriteAccountOverride & ReceiptMode<true>): Promise<CreateAirdropResult>;
+    /** With `waitForReceipt: false`: returns on submission, before the receipt exists. */
+    createMerkleAirdrop(args: CreateMerkleAirdropArgs & WriteAccountOverride & ReceiptMode<false>): Promise<PendingCreateAirdropResult>;
+    /** With a runtime `boolean`: either result, narrowed by `pending`. */
+    createMerkleAirdrop(args: CreateMerkleAirdropArgs & WriteAccountOverride & ReceiptMode): Promise<CreateAirdropResult | PendingCreateAirdropResult>;
     /**
      * Deploy an ECDSA airdrop and seed its pool in the same transaction.
      *
@@ -256,12 +273,21 @@ export declare class ConfidentialAirdropFactoryClient {
      * does not prove the pool was funded — confirm the funder's balance first.
      *
      * @param args Create arguments plus exactly one of `amount` / `encryptedInput`.
-     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * @returns The tx hash, the deployed instance, its compliance-manager clone, the clone's
+     *   implementation and the platform delegate it was wired with. With `waitForReceipt: false`,
+     *   a {@link PendingCreateAirdropResult}.
+     * @throws {@link InvalidArgumentError} on `gasFee` when the resolved fee exceeds the factory's `maxGasFee` ceiling, checked before the creator's bound.
+     * @throws {@link GasFeeNotAcceptedError} when the factory resolves a fee above `common.maxAcceptedGasFee`.
      * @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 CreateCommitmentMismatchError} when a quoted or pinned commitment no longer matches what the factory would deploy.
      * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor is resolvable.
      */
-    createAndFundEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride): Promise<CreateAirdropResult>;
+    createAndFundEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride & ReceiptMode<true>): Promise<CreateAirdropResult>;
+    /** With `waitForReceipt: false`: returns on submission, before the receipt exists. */
+    createAndFundEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride & ReceiptMode<false>): Promise<PendingCreateAirdropResult>;
+    /** With a runtime `boolean`: either result, narrowed by `pending`. */
+    createAndFundEcdsaAirdrop(args: CreateAirdropArgs<EcdsaAirdropParams> & FundInput & WriteAccountOverride & ReceiptMode): Promise<CreateAirdropResult | PendingCreateAirdropResult>;
     /**
      * Deploy a Merkle airdrop and seed its pool in the same transaction.
      *
@@ -273,14 +299,31 @@ export declare class ConfidentialAirdropFactoryClient {
      * because reverting would leak the balance. A successful receipt therefore
      * does not prove the pool was funded.
      *
-     * @param args Create arguments plus exactly one of `amount` / `encryptedInput`.
-     * @returns The tx hash, the deployed instance and its compliance-manager clone.
+     * **Creating from a plan.** Pass the {@link PlannedCampaign} as `plan`, with
+     * `merkleRoot: plan.root`, exactly as for {@link createMerkleAirdrop}: the address is pinned,
+     * the root and the Merkle init-code hash are checked, and both checks run before anything is
+     * encrypted. `expected: { airdrop: plan.predictedAddress }` is the lower-level equivalent of
+     * the pin alone.
+     *
+     * @param args Create arguments plus exactly one of `amount` / `encryptedInput`, and optionally the plan being realised.
+     * @returns The tx hash, the deployed instance, its compliance-manager clone, the clone's
+     *   implementation and the platform delegate it was wired with. With `waitForReceipt: false`,
+     *   a {@link PendingCreateAirdropResult}.
+     * @throws {@link InvalidArgumentError} on `gasFee` when the resolved fee exceeds the factory's `maxGasFee` ceiling, checked before the creator's bound.
+     * @throws {@link GasFeeNotAcceptedError} when the factory resolves a fee above `common.maxAcceptedGasFee`.
      * @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 CreateCommitmentMismatchError} when a quoted or pinned commitment no longer matches what the factory would deploy.
      * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor is resolvable.
+     * @throws {@link PredictionDriftError} when `plan` is given and the factory's Merkle implementation moved since it was taken.
+     * @throws {@link InvalidArgumentError} when `params.merkleRoot` or `expected.airdrop` disagrees with `plan`.
      */
-    createAndFundMerkleAirdrop(args: CreateAirdropArgs<MerkleAirdropParams> & FundInput & WriteAccountOverride): Promise<CreateAirdropResult>;
+    createAndFundMerkleAirdrop(args: CreateMerkleAirdropArgs & FundInput & WriteAccountOverride & ReceiptMode<true>): Promise<CreateAirdropResult>;
+    /** With `waitForReceipt: false`: returns on submission, before the receipt exists. */
+    createAndFundMerkleAirdrop(args: CreateMerkleAirdropArgs & FundInput & WriteAccountOverride & ReceiptMode<false>): Promise<PendingCreateAirdropResult>;
+    /** With a runtime `boolean`: either result, narrowed by `pending`. */
+    createAndFundMerkleAirdrop(args: CreateMerkleAirdropArgs & FundInput & WriteAccountOverride & ReceiptMode): Promise<CreateAirdropResult | PendingCreateAirdropResult>;
     /**
      * Top up the pool of an instance this factory already deployed.
      *
@@ -289,12 +332,22 @@ export declare class ConfidentialAirdropFactoryClient {
      * grants the compliance-manager clone its ACL on the amount. Sending tokens
      * to the instance directly leaves the pool unusable for compliance reads.
      *
+     * The token pulled is the one the factory recorded at create ({@link tokenOf}), not
+     * whatever the instance reports today.
+     *
+     * Prerequisite: the funder approved the factory as an ERC-7984 operator on that token
+     * (`setOperator` / `ensureOperator` from `@tokenops/sdk/fhe`). Those wait for their receipt
+     * by default, so a Safe passes `waitForReceipt: false` there too and lets the approval
+     * execute before this transaction does.
+     *
      * **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`).
+     * @throws {@link InvalidArgumentError} when both or neither of `amount` / `encryptedInput` is supplied.
+     * @throws {@link MissingEncryptorError} when `amount` is given and no encryptor is resolvable.
      */
     fundAirdrop(args: {
         airdrop: Address;
@@ -359,7 +412,7 @@ export declare class ConfidentialAirdropFactoryClient {
      */
     airdrops(offset: bigint, limit: bigint): Promise<readonly Address[]>;
     /**
-     * Whether THIS factory created `candidate` - the genuineness check (audit-10).
+     * Whether THIS factory created `candidate` - the genuineness check.
      *
      * 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
@@ -383,6 +436,14 @@ export declare class ConfidentialAirdropFactoryClient {
      * @returns The clone address, or the zero address when unknown to this factory.
      */
     complianceManagerOf(airdrop: Address): Promise<Address>;
+    /**
+     * The token recorded for `airdrop` at create - what {@link fundAirdrop} pulls, regardless
+     * of what the instance reports today.
+     *
+     * @param airdrop Instance address.
+     * @returns The token address, or the zero address when unknown to this factory.
+     */
+    tokenOf(airdrop: Address): Promise<Address>;
     /**
      * Redirect where accrued claim-fee ETH withdraws to. Requires
      * `FEE_MANAGER_ROLE`.
@@ -426,9 +487,8 @@ export declare class ConfidentialAirdropFactoryClient {
      *
      * 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`).
+     * create until it is lowered too. The contract sets no lower bound, so this call
+     * itself does not revert on that account.
      */
     setMaxGasFee(maxGasFee: bigint, account?: Account | Address): Promise<Hex>;
     /**
@@ -451,6 +511,7 @@ export declare class ConfidentialAirdropFactoryClient {
      * clones point at the implementation live when they were created.
      *
      * @throws {@link InvalidArgumentError} when `implementation` is the zero address (`ZeroImplementation`).
+     * @throws {@link InvalidArgumentError} when `implementation` has no code or is an EIP-7702 delegation designator (`InvalidImplementation`).
      */
     setEcdsaImplementation(implementation: Address, account?: Account | Address): Promise<Hex>;
     /**
@@ -458,6 +519,7 @@ export declare class ConfidentialAirdropFactoryClient {
      * Requires `IMPL_MANAGER_ROLE`. Does not affect already-deployed instances.
      *
      * @throws {@link InvalidArgumentError} when `implementation` is the zero address (`ZeroImplementation`).
+     * @throws {@link InvalidArgumentError} when `implementation` has no code or is an EIP-7702 delegation designator (`InvalidImplementation`).
      */
     setMerkleImplementation(implementation: Address, account?: Account | Address): Promise<Hex>;
     /** The implementation address `createEcdsaAirdrop*` currently clones. */
@@ -469,16 +531,17 @@ export declare class ConfidentialAirdropFactoryClient {
      * `COMPLIANCE_WIRING_ROLE`. Does not affect already-deployed clones.
      *
      * @throws {@link InvalidArgumentError} when `implementation` is the zero address (`ZeroComplianceManagerImpl`).
+     * @throws {@link InvalidArgumentError} when `implementation` has no code or is an EIP-7702 delegation designator (`InvalidImplementation`).
      */
     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).
+     * The factory's constructor already seeded a non-zero delegate with delegation ON, so
+     * this only rotates it: it can never be cleared, and the zero address always reverts.
+     * Applies to clones created after it lands; existing clones keep the delegate they were
+     * initialized with.
      *
      * @throws {@link InvalidArgumentError} when `delegate` is the zero address (`ZeroComplianceDelegate`).
      */
@@ -487,10 +550,8 @@ export declare class ConfidentialAirdropFactoryClient {
      * 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`).
+     * The default starts ON at construction (no post-deploy wiring); passing `false` is the
+     * deliberate opt-out. A per-creator {@link setCompliancePolicy} override still wins.
      */
     setDefaultDelegateToCompliance(on: boolean, account?: Account | Address): Promise<Hex>;
     /**
@@ -507,6 +568,24 @@ export declare class ConfidentialAirdropFactoryClient {
     complianceManagerImpl(): Promise<Address>;
     /** The platform-designated compliance delegate wired into new compliance-manager clones. */
     complianceDelegate(): Promise<Address>;
+    /**
+     * The platform delegate a create from `creator` would wire into its compliance clone:
+     * `complianceDelegate()` while the creator's effective policy is ON, the zero address
+     * while it is OFF. This is the value the factory checks `expectedComplianceDelegate`
+     * against.
+     */
+    resolveComplianceDelegate(creator: Address): Promise<Address>;
+    /**
+     * Quote the {@link CreateCommitments} a create from `deployer` will be checked against,
+     * honouring anything already pinned in `expected`. The predicted address comes from the
+     * variant's prediction oracle, the other two from the factory's live configuration.
+     */
+    quoteCreateCommitments(args: AirdropVariantParams & {
+        mode: DeploymentMode;
+        deployer: Address;
+        userSalt: Hex;
+        expected?: Partial<CreateCommitments> | undefined;
+    }): Promise<CreateCommitments>;
     /** A creator's delegate-to-compliance override, if any — `overridden: false` means the factory default applies instead. */
     getCompliancePolicy(creator: Address): Promise<CompliancePolicy>;
     /**
@@ -613,12 +692,11 @@ export declare class ConfidentialAirdropFactoryClient {
     /**
      * Revoke `role` from `holder`. Requires the role's admin role.
      *
-     * **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.
+     * **The factory floors `DEFAULT_ADMIN_ROLE` at one live member**, 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 (which would freeze role administration
+     * permanently) nor satisfied by a member nobody controls.
      *
      * A handover is still available and is the supported way out: grant the
      * successor first, then renounce.
@@ -638,12 +716,9 @@ export declare class ConfidentialAirdropFactoryClient {
      * 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.
+     * The same `DEFAULT_ADMIN_ROLE` floor as {@link revokeRole} applies: the sole admin
+     * cannot renounce, the call reverts `LastAdmin`. Grant a successor first, then
+     * renounce.
      *
      * @returns The transaction hash.
      */
@@ -660,4 +735,3 @@ export declare class ConfidentialAirdropFactoryClient {
  * @alpha
  */
 export declare function createConfidentialAirdropFactoryClient(config: ConfidentialAirdropFactoryClientConfig): ConfidentialAirdropFactoryClient;
-export {};

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

@@ -3,7 +3,7 @@ import type { PreflightResult } from "../core/preflight.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";
+import type { CreateCommitments, EcdsaAirdropParams, MerkleAirdropParams, PlannedCampaign } from "./types.js";
 /**
  * Chains the airdrop v2 contracts are reachable on.
  *
@@ -105,8 +105,8 @@ export interface AssertSaltAvailableArgs {
  */
 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
+ * The slice of {@link ConfidentialAirdropFactoryClient} the create fee checks
+ * read. Structural so this module keeps its runtime-import-free shape; the real
  * client satisfies it as-is.
  *
  * @alpha
@@ -116,7 +116,7 @@ export interface GasFeeResolver {
     resolveGasFee(creator: Address): Promise<bigint>;
 }
 /**
- * Inputs for {@link assertGasFeeAccepted}.
+ * Inputs for {@link assertCreateGasFee}.
  *
  * @alpha
  */
@@ -130,23 +130,31 @@ export interface AssertGasFeeAcceptedArgs {
     method: string;
 }
 /**
- * Refuse a create whose resolved per-claim fee exceeds the creator's declared bound.
+ * Both create-time fee checks, in the order the factory's `_create` runs them:
+ * the resolved fee against the factory's own `maxGasFee` ceiling first
+ * (`GasFeeExceedsMaximum`), then against the creator's `maxAcceptedGasFee`
+ * (`GasFeeNotAccepted`). Reporting the bound first would tell a creator to
+ * raise it when the ceiling would refuse the create anyway.
  *
- * 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 contract enforces both. Doing it here buys the reason: the revert
+ * carries the 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.
+ * @throws {@link InvalidArgumentError} when `maxAcceptedGasFee` is outside `uint96`, or on `gasFee` when the resolved fee exceeds the ceiling.
+ * @throws {@link GasFeeNotAcceptedError} when the resolved fee is within the ceiling but above the bound.
  *
- * @alpha
+ * @internal
  */
-export declare function assertGasFeeAccepted(args: AssertGasFeeAcceptedArgs): Promise<void>;
+export declare function assertCreateGasFee(args: AssertGasFeeAcceptedArgs & {
+    factory: GasFeeResolver & {
+        maxGasFee(): Promise<bigint>;
+    };
+}): Promise<void>;
 /**
  * Inputs for {@link assertPredictionFresh}.
  *
@@ -175,6 +183,38 @@ export interface AssertPredictionFreshArgs {
  * @alpha
  */
 export declare function assertPredictionFresh(args: AssertPredictionFreshArgs): void;
+/**
+ * Inputs for {@link resolvePlannedCreate}.
+ *
+ * @internal
+ */
+export interface ResolvePlannedCreateArgs {
+    /** Label for the thrown error. */
+    method: string;
+    params: MerkleAirdropParams;
+    expected?: Partial<CreateCommitments> | undefined;
+    /** Preflight only; the write path reads the live hash itself. */
+    expectedInitCodeHash?: Hex | undefined;
+    plan?: PlannedCampaign | undefined;
+}
+/**
+ * Fold a {@link PlannedCampaign} into the pins a Merkle create is sent with.
+ *
+ * Without a plan the caller's `expected` and `expectedInitCodeHash` come back
+ * untouched. With one, `expected.airdrop` becomes `plan.predictedAddress` and
+ * the drift check is judged against `plan.initCodeHashAfter`. A caller-supplied
+ * value that disagrees with the plan is refused rather than overridden, so the
+ * plan never silently wins over something the caller wrote down. Static: no RPC.
+ *
+ * @throws {@link InvalidArgumentError} when `params.merkleRoot`, `expected.airdrop`
+ *   or `expectedInitCodeHash` disagrees with the plan.
+ *
+ * @internal
+ */
+export declare function resolvePlannedCreate(args: ResolvePlannedCreateArgs): {
+    expected: Partial<CreateCommitments> | undefined;
+    expectedInitCodeHash: Hex | undefined;
+};
 /** Fields shared by both variants of {@link PreflightCreateArgs}. */
 interface PreflightCreateCommon {
     factory: ConfidentialAirdropFactoryClient;
@@ -183,11 +223,35 @@ interface PreflightCreateCommon {
     creator: Address;
     userSalt: Hex;
     /**
-     * The variant's init-code hash observed when the address was predicted -
-     * e.g. `PlannedCampaign.initCodeHashAfter`. Supplying it turns on the
-     * drift check; omitting it skips that one check only.
+     * The variant's init-code hash observed when the address was predicted.
+     * Supplying it turns on the drift check; omitting it skips that one check
+     * only. A Merkle `plan` supplies `plan.initCodeHashAfter` for you.
      */
     expectedInitCodeHash?: Hex | undefined;
+    /**
+     * Commitments to pin instead of quoting fresh at send time. Anything omitted is read
+     * from the factory just before the transaction. For a {@link PlannedCampaign}, pass
+     * `plan` on the Merkle arm instead; `{ airdrop: plan.predictedAddress }` here is the
+     * lower-level equivalent of its pin.
+     *
+     * The preflight compares each pinned field with the factory's fresh quote and reports a
+     * `CreateCommitmentMismatchError` blocker (with that `field`) when they differ, since the
+     * factory would revert the create on it.
+     */
+    expected?: Partial<CreateCommitments> | undefined;
+}
+/** @alpha */
+export interface PreflightCreateResult extends PreflightResult {
+    /**
+     * The commitments the create would be sent with - the fresh quote with any pinned
+     * `expected` field taking precedence - what an app shows the creator and compares with a
+     * published record. A pinned field that differs from the fresh quote is reported here as
+     * pinned and also as a `CreateCommitmentMismatchError` blocker. Absent when a read
+     * producing the quote failed: with nothing pinned no blocker is added, and with a pin
+     * the failure is a blocker (a typed SDK error) or is rethrown (anything else), so the
+     * mismatch check is never skipped silently.
+     */
+    commitments?: CreateCommitments;
 }
 /**
  * Inputs for {@link preflightCreate}.
@@ -200,33 +264,49 @@ export type PreflightCreateArgs = PreflightCreateCommon & ({
 } | {
     variant: "merkle";
     params: MerkleAirdropParams;
+    /**
+     * The {@link PlannedCampaign} the create will realise. Pins
+     * `expected.airdrop` to `plan.predictedAddress` and turns the drift check
+     * on against `plan.initCodeHashAfter`. A `params.merkleRoot`,
+     * `expected.airdrop` or `expectedInitCodeHash` that disagrees with the
+     * plan is reported as an `InvalidArgumentError` blocker.
+     */
+    plan?: PlannedCampaign | undefined;
 });
 /**
  * Run every create-time guardrail read-only and report what would block the
  * 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 resolved gas fee against
- * `common.maxAcceptedGasFee`, the creator's effective
+ * support, the Merkle/UUPS refusal, params the instance initializer would
+ * revert on (a zero token, an `endTime` less than a minute away, a window
+ * that does not open before it closes, a zero immutable Merkle root, a zero
+ * ECDSA signer; `InvalidArgumentError` naming the field), the creator's resolved gas fee against
+ * `common.maxAcceptedGasFee` and against the factory's `maxGasFee` ceiling
+ * (an `InvalidArgumentError` on `gasFee`, the same error the create's
+ * `GasFeeExceedsMaximum` revert maps to), 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
- * drift since the prediction was taken.
+ * address (the pinned `expected.airdrop` when given), a pinned commitment
+ * that no longer matches the factory's fresh quote, and - when
+ * `expectedInitCodeHash` or a Merkle `plan` is supplied - implementation
+ * drift since the prediction was taken. A `plan` that disagrees with
+ * `params.merkleRoot`, `expected.airdrop` or `expectedInitCodeHash` is an
+ * `InvalidArgumentError` blocker.
  *
- * @returns `{ ready, blockers }`. `blockers` carries the errors `create*`
- *   would have thrown, so a UI can branch on `error.code` exactly as it does
- *   in `onError`.
+ * @returns `{ ready, blockers, commitments }`. `blockers` carries the errors
+ *   `create*` would have thrown, so a UI can branch on `error.code` exactly as
+ *   it does in `onError`; `commitments` is what the create would be sent with.
  *
  * @example
  * const { ready, blockers } = await preflightCreate({
- *   factory, variant: "merkle", params, mode: "clone", creator, userSalt,
- *   expectedInitCodeHash: plan.initCodeHashAfter,
+ *   factory, variant: "merkle", params, mode: "clone", creator, userSalt, plan,
  * });
  * if (!ready) return blockers.map((b) => b.code);
  *
  * @alpha
  */
-export declare function preflightCreate(args: PreflightCreateArgs): Promise<PreflightResult>;
+export declare function preflightCreate(args: PreflightCreateArgs): Promise<PreflightCreateResult>;
 /**
  * The subset of an instance client {@link preflightClaim} reads.
  *
@@ -353,22 +433,21 @@ export interface PreflightClaimArgs {
 }
 /**
  * The three argument-relation rules the Merkle claim path enforces before it touches the
- * coprocessor. All are decidable from the arguments alone, so both `preflightClaim` and
- * the client's own write path run them — no RPC, no chance of a wasted fee.
+ * coprocessor: non-zero account, `claimAndUnwrap` is self-only, and only the account itself
+ * may redirect payout. All are decidable from the arguments alone, so both `preflightClaim`
+ * and the client's own write path run them - no RPC, no chance of a wasted fee.
  *
  * @param account The claim identity (`claim`'s leading argument).
  * @param submitter The address that will send the transaction.
- * @param boundTo The address the entry's input proof is bound to, when known.
  * @param to The payout destination, if one will be passed.
  * @param entrypoint `claimAndUnwrap` is self-only; `claim` accepts a third-party submitter.
- * @throws {@link InvalidArgumentError} on a zero `account`, a proof bound to another address, or a relayed `claimAndUnwrap`.
+ * @throws {@link InvalidArgumentError} on a zero `account` or a third-party `claimAndUnwrap`.
  * @throws {@link UnauthorizedRedirectError} when a third party tries to redirect payout.
  */
 export declare function assertMerkleClaimIdentity(args: {
     method: string;
     account: Address;
     submitter: Address;
-    boundTo?: Address | undefined;
     to?: Address | undefined;
     entrypoint?: "claim" | "claimAndUnwrap" | undefined;
 }): void;