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

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

@@ -5,8 +5,19 @@ import type { ConfidentialAirdropFactoryClient } from "./factory.js";
 import type { MerkleAirdropClient } from "./merkle.js";
 import { type MerkleLeafInput } from "./merkle-tree.js";
 import type { DeploymentMode } from "./constants.js";
-import type { BuiltCampaign, CampaignRecipient, MerkleAirdropParams } from "./types.js";
-export type { BuiltCampaign, CampaignEntry, CampaignRecipient } from "./types.js";
+import type { BuiltCampaign, CampaignRecipient, MerkleAirdropParams, PlannedCampaign } from "./types.js";
+export type { BuiltCampaign, CampaignEntry, CampaignRecipient, PlannedCampaign } from "./types.js";
+/**
+ * Recipients per relayer request: an input ciphertext packs at most 2048 bits, so 2048 / 64
+ * euint64 values share one proof.
+ *
+ * `@zama-fhe/sdk` does not check this client-side, so the campaign builders chunk every
+ * roster to this size. Each entry carries its own chunk's proof, so a claim is identical
+ * whichever chunk its leaf came from.
+ *
+ * @alpha
+ */
+export declare const MERKLE_BATCH_LIMIT: number;
 /**
  * Reject the campaign shapes that produce an unusable or misleading tree,
  * before any encryption work is done.
@@ -46,45 +57,12 @@ export declare function validateCampaignRecipients(recipients: readonly Campaign
  * pattern as `buildMerkleTreeInternal` in `./merkle-tree.js`.
  */
 export declare function validateCampaignRecipientsInternal(recipients: readonly CampaignRecipient[], method: string): void;
-/**
- * Who will submit the claims, for every builder that encrypts a roster.
- *
- * Follows the same shared-option pattern as `WriteAccountOverride`, because the choice
- * applies identically to all four builders and is frozen once the root is published.
- *
- * @alpha
- */
-export interface CampaignSubmitterOption {
-    /**
-     * The single address that will send every `claim` in this campaign.
-     *
-     * Omit for a **self-claim** campaign: each recipient's input is bound to that
-     * recipient, one relayer request each, and only they can claim.
-     *
-     * Set it for a **relayed** campaign: the whole roster is bound to this one address and
-     * batched, so a single `inputProof` covers up to 32 recipients and only this address
-     * can submit. That batching is the point — one proof cannot be bound to many
-     * addresses, so per-recipient binding and batching are mutually exclusive.
-     *
-     * An input ciphertext packs at most 2048 bits, so a `euint64` roster is chunked at 32
-     * recipients per request; a longer roster simply issues more requests. Nothing about a
-     * claim changes, since every chunk's proof is bound to the same submitter.
-     *
-     * Either way the leaf still commits each recipient's own `account`, so payout and
-     * accounting are unaffected by who submits.
-     *
-     * **Frozen at publication.** An FHEVM handle encodes its `(instance, userAddress)`
-     * binding, so re-pointing a leaf at a different submitter means re-encrypting, which
-     * changes the handle and therefore the root. Choose before publishing, not after.
-     */
-    submitter?: Address;
-}
 /**
  * Inputs for {@link buildMerkleCampaign}.
  *
  * @alpha
  */
-export interface BuildMerkleCampaignArgs extends CampaignSubmitterOption {
+export interface BuildMerkleCampaignArgs {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     recipients: readonly CampaignRecipient[];
@@ -96,9 +74,7 @@ export interface BuildMerkleCampaignArgs extends CampaignSubmitterOption {
  * @alpha
  */
 export interface EncryptedCampaignLeaf extends MerkleLeafInput {
-    /** The only address that can submit this leaf — what `handle`/`inputProof` are bound to. */
-    boundTo: Address;
-    /** The KMS input proof binding `handle` to `(instance, boundTo)`. Required at claim time, unused by the tree. */
+    /** The KMS input proof binding `handle` to `(instance, instance)`. Required at claim time, unused by the tree. */
     inputProof: Hex;
 }
 /**
@@ -106,7 +82,7 @@ export interface EncryptedCampaignLeaf extends MerkleLeafInput {
  *
  * @alpha
  */
-export interface EncryptCampaignAmountsArgs extends CampaignSubmitterOption {
+export interface EncryptCampaignAmountsArgs {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     recipients: readonly CampaignRecipient[];
@@ -119,17 +95,15 @@ export interface EncryptCampaignAmountsArgs extends CampaignSubmitterOption {
  * publishing a root, or to hand them to something else that builds the tree.
  * If you just want a campaign, {@link buildMerkleCampaign} does both.
  *
- * **Request count follows `submitter`.** Omitted: one relayer request per recipient,
- * issued concurrently, each bound to that recipient. Set: one batched request per 32
- * recipients (the 2048-bit input-ciphertext limit), every leaf claimable only by that
- * submitter.
+ * One relayer request per 32 recipients, issued concurrently; every leaf is submittable
+ * by any address.
  *
  * **The output is not reproducible.** Encryption is randomised, so calling this
  * twice with the same roster yields different handles and therefore a different
  * root. Persist what you get back; you cannot regenerate it.
  *
  * @param args The live instance, the roster, and an eager or lazy encryptor.
- * @returns One `{ account, boundTo, handle, inputProof }` per roster entry, in roster order.
+ * @returns One `{ account, handle, inputProof }` per roster entry, in roster order.
  * @throws {@link InvalidArgumentError} on any roster problem {@link validateCampaignRecipients} rejects, or a zero `instance`.
  * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
  *
@@ -142,8 +116,7 @@ export interface EncryptCampaignAmountsArgs extends CampaignSubmitterOption {
 export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs): Promise<readonly EncryptedCampaignLeaf[]>;
 /**
  * Encrypt every recipient's cumulative total, then build the tree those ciphertexts
- * belong to. Binding follows `submitter`: omitted, each input is bound to its own
- * recipient; set, the whole roster is bound to that one submitter.
+ * belong to. Every input is bound to `(instance, instance)`.
  *
  * Use this on the **mutable-root** path: the instance already exists, so its
  * address is known and encryption can bind to it directly. Publish the returned
@@ -160,9 +133,8 @@ export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs)
  * claim, and no amount of on-chain data will reconstruct it. Persist the
  * entries when this resolves and serve each recipient theirs.
  *
- * **Relayer load follows `submitter`.** A self-claim roster fans out one request per
- * recipient; a relayed roster issues one per 32. Either way, split the roster across
- * calls yourself if your relayer rate-limits.
+ * One relayer request per 32 recipients, issued concurrently; every leaf is submittable
+ * by any address. Split the roster across calls yourself if your relayer rate-limits.
  *
  * **Already hold the handles?** This function encrypts unconditionally, and
  * encryption is randomised — so re-encrypting handles that exist elsewhere
@@ -185,13 +157,13 @@ export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs)
  *
  * @alpha
  */
-export declare function buildMerkleCampaign({ instance, recipients, encryptor, submitter, }: BuildMerkleCampaignArgs): Promise<BuiltCampaign>;
+export declare function buildMerkleCampaign({ instance, recipients, encryptor, }: BuildMerkleCampaignArgs): Promise<BuiltCampaign>;
 /**
  * Inputs for {@link planMerkleCampaign}.
  *
  * @alpha
  */
-export interface PlanMerkleCampaignArgs extends CampaignSubmitterOption {
+export interface PlanMerkleCampaignArgs {
     factory: ConfidentialAirdropFactoryClient;
     /** The exact params the subsequent `createMerkleAirdrop` will use, except `merkleRoot` — supply the planned root there. */
     params: MerkleAirdropParams;
@@ -202,19 +174,6 @@ export interface PlanMerkleCampaignArgs extends CampaignSubmitterOption {
     recipients: readonly CampaignRecipient[];
     encryptor: EncryptorSource;
 }
-/**
- * A campaign built against a not-yet-deployed instance, plus the evidence needed to trust the prediction.
- *
- * @alpha
- */
-export interface PlannedCampaign extends BuiltCampaign {
-    /** Where `createMerkleAirdrop({ mode, userSalt })` from `creator` will land. Every entry is bound to this address. */
-    predictedAddress: Address;
-    /** The factory's Merkle init-code hash read BEFORE the address was predicted. */
-    initCodeHashBefore: Hex;
-    /** The same hash read AFTER. Always equal to `initCodeHashBefore` on a returned plan - a difference throws instead. */
-    initCodeHashAfter: Hex;
-}
 /**
  * Build a campaign for an instance that does not exist yet, so its root can be
  * baked in at create time.
@@ -249,6 +208,13 @@ export interface PlannedCampaign extends BuiltCampaign {
  * `preflightCreate` (`./guards.js`) for those, or let `createMerkleAirdrop`
  * enforce them at send time.
  *
+ * **Create from the plan.** Pass the returned plan as `plan` to
+ * `createMerkleAirdrop` / `createAndFundMerkleAirdrop` (and to
+ * `preflightCreate`). That pins `predictedAddress`, checks the root, and
+ * re-judges drift against `initCodeHashAfter` just before the send, so an
+ * implementation rotation after planning is refused rather than deployed at an
+ * address the entries are not bound to.
+ *
  * **Distribution is yours** — same as {@link buildMerkleCampaign}: the chain
  * keeps only the root, so each recipient must be handed their own
  * `(handle, inputProof, merkleProof)` out of band or they cannot claim.
@@ -267,17 +233,18 @@ export interface PlannedCampaign extends BuiltCampaign {
  *   params: { ...params, merkleRoot: plan.root, isMerkleRootMutable: false },
  *   mode: "clone",
  *   userSalt,
+ *   plan,
  * });
  *
  * @alpha
  */
-export declare function planMerkleCampaign({ factory, params, mode, creator, userSalt, recipients, encryptor, submitter, }: PlanMerkleCampaignArgs): Promise<PlannedCampaign>;
+export declare function planMerkleCampaign({ factory, params, mode, creator, userSalt, recipients, encryptor, }: PlanMerkleCampaignArgs): Promise<PlannedCampaign>;
 /**
  * Inputs for {@link rotateMerkleRoot}.
  *
  * @alpha
  */
-export interface RotateMerkleRootArgs extends WriteAccountOverride, CampaignSubmitterOption {
+export interface RotateMerkleRootArgs extends WriteAccountOverride {
     /** The live instance. Its `address` is read off the client — nothing is predicted here. */
     airdrop: MerkleAirdropClient;
     /** The FULL updated roster: cumulative totals, not the deltas since the last root. */
@@ -311,11 +278,8 @@ export interface RotatedCampaign extends BuiltCampaign {
  * entries to every recipient**, including the ones whose total was unchanged —
  * the chain stores only the root, so an un-updated recipient is simply stuck.
  *
- * **`submitter` is not remembered across rotations.** It is read from THIS call, not from
- * the campaign being replaced, so omitting it on a rotation rebuilds a relayed campaign as
- * a self-claim one - every new entry becomes claimable only by its own recipient, and the
- * relayer that was settling for them can no longer submit anything. Pass the same
- * `submitter` again to keep a relayed campaign relayed.
+ * One relayer request per 32 recipients, issued concurrently; every leaf is submittable
+ * by any address.
  *
  * Requires `MERKLE_ADMIN_ROLE` on the instance and an instance created with
  * `isMerkleRootMutable: true`.
@@ -335,4 +299,4 @@ export interface RotatedCampaign extends BuiltCampaign {
  *
  * @alpha
  */
-export declare function rotateMerkleRoot({ airdrop, recipients, encryptor, submitter, account, }: RotateMerkleRootArgs): Promise<RotatedCampaign>;
+export declare function rotateMerkleRoot({ airdrop, recipients, encryptor, account, }: RotateMerkleRootArgs): Promise<RotatedCampaign>;

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

@@ -0,0 +1,21 @@
+import type { Address } from "viem";
+/**
+ * Predict the compliance-manager clone the factory deploys for an instance.
+ *
+ * Mirrors `AirdropFactory`: `Clones.cloneDeterministic(managerImpl,
+ * keccak256(abi.encode(predictedInstance, "compliance")))`, sent from the
+ * factory. The salt derives from the instance address, so the clone moves in
+ * lockstep with it.
+ *
+ * @param args.factory The factory that performs the create (the CREATE2 deployer).
+ * @param args.managerImplementation The implementation the clone is made from.
+ * @param args.airdrop The instance address the create lands at.
+ * @returns The checksummed clone address.
+ *
+ * @alpha
+ */
+export declare function predictComplianceManagerClone(args: {
+    factory: Address;
+    managerImplementation: Address;
+    airdrop: Address;
+}): Address;

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

@@ -3,7 +3,7 @@
  *
  * @alpha
  */
-export declare const AIRDROP_CONTRACTS_COMMIT = "c5c12c2087f61bcd5bd1daa802563ed3cd68f002";
+export declare const AIRDROP_CONTRACTS_COMMIT = "005980df194e0dc66053bd517e9759bd4d580047";
 /**
  * Deployment shell selected at create time. Mirrors the contract's `DeploymentMode` enum
  * (`IConfidentialAirdropTypes.sol`): `enum DeploymentMode { Clone, UUPS }`.
@@ -31,6 +31,8 @@ export declare const DEDUP_MODE: {
 };
 /** @alpha */
 export type DedupMode = keyof typeof DEDUP_MODE;
+/** {@link DEDUP_MODE} inverted: the contract's ordinal to the SDK's name. */
+export declare const DEDUP_MODE_BY_ORDINAL: ReadonlyMap<number, DedupMode>;
 /**
  * The largest value `CommonAirdropParams.maxAcceptedGasFee` can carry - the
  * `uint96` ceiling. Passing it accepts whatever fee the factory resolves, which

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

@@ -1,7 +1,7 @@
 import type { Address, Hex } from "viem";
 import type { EncryptedInput, EncryptedViewResult } from "../fhe/types.js";
 import { AirdropBaseClient, type AirdropBaseClientConfig, type WriteAccountOverride } from "./airdrop-base.js";
-import type { DedupMode } from "./constants.js";
+import { type DedupMode } from "./constants.js";
 /**
  * EIP-712 domain name every `ECDSAConfidentialAirdrop` instance shares. Set once, at `initialize`.
  *
@@ -50,19 +50,12 @@ export declare const CLAIM_TYPEHASH: `0x${string}`;
 /** @alpha */
 export interface EcdsaAirdropClientConfig extends AirdropBaseClientConfig {
     /**
-     * The replay-protection policy this instance was deployed with
-     * (`perAddress` / `perDedupId` / `both` / `none`).
+     * The replay-protection policy this instance was created with, as configured on
+     * this client. Purely informational - no method branches on it.
      *
-     * Required at construction because the contract exposes **no on-chain
-     * getter** for it: `ECDSADedupStorage.dedupMode`
-     * (`ConfidentialAirdropECDSAStorage.sol`) is a private field inside an
-     * ERC-7201 namespaced storage struct, unreachable through any ABI-visible
-     * read — every other constant this client exposes (`SIGNER_ROLE`,
-     * `CLAIM_TYPEHASH`, `DOMAIN_SEPARATOR`) has a public getter; this one does
-     * not. Pass the same value used at
-     * `factory.createEcdsaAirdrop({ params: { dedupMode } })` time.
+     * @deprecated Read the policy from the chain with {@link EcdsaAirdropClient.readDedupMode}.
      */
-    dedupMode: DedupMode;
+    dedupMode?: DedupMode | undefined;
 }
 /**
  * Inputs shared by {@link EcdsaAirdropClient.claim} and {@link EcdsaAirdropClient.claimAndUnwrap}.
@@ -73,12 +66,19 @@ export interface EcdsaClaimArgs extends WriteAccountOverride {
     /**
      * Payout destination. Omit (or pass the zero address) to default to the
      * sending account — mirrors the contract's own `to == address(0)` redirect
-     * rule. Authorization (the signature), replay dedup and the FHE input
-     * proof all stay bound to the sending account regardless of `to`; this
-     * field only redirects where the tokens (and the recipient ACL) land.
+     * rule. Authorization (the signature), replay dedup and a non-empty FHE
+     * input proof all stay bound to the sending account regardless of `to`;
+     * this field only redirects where the tokens (and the recipient ACL) land.
      */
     to?: Address;
-    /** The claimant's encrypted allocation, bound to `(airdrop, sendingAccount)` at encryption time. */
+    /**
+     * The claimant's encrypted allocation.
+     *
+     * A non-empty `inputProof` binds the handle to `(airdrop, sendingAccount)`. An empty one
+     * (`"0x"`) skips verification: a zero handle becomes an encrypted zero, and a nonzero handle
+     * is accepted only if the sender and the instance already hold ACL on it, else it reverts.
+     * See the guide's "Encryption binding differs by path".
+     */
     encryptedInput: EncryptedInput;
     /** The off-chain claim id bound into the signature. */
     dedupId: Hex;
@@ -95,6 +95,7 @@ export interface EcdsaClaimArgs extends WriteAccountOverride {
  * @alpha
  */
 export interface GetClaimAmountArgs extends WriteAccountOverride {
+    /** The claimant's encrypted allocation; the same empty-proof rule as {@link EcdsaClaimArgs.encryptedInput}. */
     encryptedInput: EncryptedInput;
     dedupId: Hex;
     deadline: bigint;
@@ -141,15 +142,21 @@ export interface IsSignatureValidArgs {
  * amount against the contract's `msg.value != gasFee()` revert.
  *
  * @example
- * const airdrop = new EcdsaAirdropClient({ publicClient, walletClient, address, dedupMode: "perAddress" });
+ * const airdrop = new EcdsaAirdropClient({ publicClient, walletClient, address });
  * const hash = await airdrop.claim({ encryptedInput, dedupId, deadline, signer, signature });
  *
  * @alpha
  */
 export declare class EcdsaAirdropClient extends AirdropBaseClient {
-    /** @see EcdsaAirdropClientConfig.dedupMode */
-    readonly dedupMode: DedupMode;
+    /** @deprecated Read the policy from the chain with {@link EcdsaAirdropClient.readDedupMode}. */
+    readonly dedupMode: DedupMode | undefined;
     constructor(config: EcdsaAirdropClientConfig);
+    /**
+     * Read the instance's frozen replay policy from the chain (`dedupMode()`).
+     *
+     * @throws {@link TokenOpsSdkError} when the contract returns an ordinal this SDK does not know.
+     */
+    readDedupMode(): Promise<DedupMode>;
     /**
      * Claim a signed encrypted allocation, delivering the tokens to `to`
      * (defaults to the sending account).
@@ -158,12 +165,18 @@ export declare class EcdsaAirdropClient extends AirdropBaseClient {
      * depth EIP-712 digest guard. Requires `msg.value == gasFee()` exactly —
      * handled for you; see the class TSDoc.
      *
+     * An empty `inputProof` is accepted only for a zero handle or one the sender and the
+     * instance already hold ACL on; see {@link EcdsaClaimArgs.encryptedInput}.
+     *
      * @throws {@link ClaimNotStartedError} before `startTime`.
      * @throws {@link ClaimWindowClosedError} after `endTime`.
      * @throws {@link SignatureExpiredError} after `args.deadline` has passed.
      * @throws {@link InvalidSignatureError} when `signer` lacks `SIGNER_ROLE` or the signature does not verify.
      * @throws {@link AlreadyClaimedError} on an address or digest replay.
      * @throws {@link DedupIdConsumedError} on a `dedupId` replay under `perDedupId`/`both`.
+     * @throws {@link FheHandleNotAllowedError} on an empty proof for a nonzero handle the sender
+     *   holds no ACL on (`SenderNotAllowedToUseHandle`); the ACL's `SenderNotAllowed`, when only the
+     *   instance lacks it, surfaces as a raw `ContractRevertError`.
      * @returns The transaction hash.
      */
     claim(args: EcdsaClaimArgs): Promise<Hex>;
@@ -173,12 +186,22 @@ export declare class EcdsaAirdropClient extends AirdropBaseClient {
      * `TokenNotUnwrappable` (surfaced as `FeatureDisabledError`) on a
      * non-unwrappable campaign.
      *
-     * Same replay consumption and `msg.value == gasFee()` requirement as
-     * {@link claim}.
+     * Same replay consumption, empty-proof rule and `msg.value == gasFee()`
+     * requirement as {@link claim}.
+     *
+     * **Discloses the amount immediately.** With the stock wrapper the unwrapped amount is
+     * publicly decryptable from this claim transaction (the emitted `unwrapRequestId` is its
+     * handle), so anyone can learn it at once; `finalizeUnwrap` only releases the ERC-20. Only
+     * {@link claim} keeps the amount confidential.
      *
-     * @returns The transaction hash. The underlying ERC-20 is released later by
-     *   a separate, permissionless `finalizeUnwrap` — this hash is only the
-     *   unwrap request.
+     * @throws {@link FheHandleNotAllowedError} on an empty proof for a nonzero handle the sender
+     *   holds no ACL on (`SenderNotAllowedToUseHandle`); the ACL's `SenderNotAllowed`, when only the
+     *   instance lacks it, surfaces as a raw `ContractRevertError`.
+     * @returns The transaction hash. It is only the unwrap request: the underlying
+     *   ERC-20 is released later by the wrapper's permissionless `finalizeUnwrap`. Read
+     *   its `unwrapRequestId` with {@link AirdropBaseClient.readUnwrapRequest} (or
+     *   {@link AirdropBaseClient.parseUnwrapRequest} over a receipt you hold), then
+     *   finalize with Zama's `sdk.createToken(wrapper).finalizeUnwrap(unwrapRequestId)`.
      */
     claimAndUnwrap(args: EcdsaClaimArgs): Promise<Hex>;
     /**
@@ -201,9 +224,17 @@ export declare class EcdsaAirdropClient extends AirdropBaseClient {
      * the result is recovered from the receipt's ACL `Allowed` event, never
      * from a simulation. See {@link AirdropBaseClient}'s class TSDoc.
      *
+     * The same empty-proof rule as {@link claim} applies; see {@link EcdsaClaimArgs.encryptedInput}.
+     *
      * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`.
-     * @throws {@link AlreadyClaimedError} when this recipient's dedup slot is consumed.
+     * @throws {@link AlreadyClaimedError} when this recipient's dedup slot or this exact digest is consumed.
      * @throws {@link DedupIdConsumedError} when this `dedupId`'s slot is consumed.
+     * @throws {@link SignatureExpiredError} when `deadline` has passed.
+     * @throws {@link InvalidSignatureError} when the voucher was not signed by the instance's signer.
+     * @throws {@link PausedError} / {@link ClaimNotStartedError} / {@link ClaimWindowClosedError} when the campaign is paused or outside its claim window.
+     * @throws {@link FheHandleNotAllowedError} on an empty proof for a nonzero handle the sender
+     *   holds no ACL on (`SenderNotAllowedToUseHandle`); the ACL's `SenderNotAllowed`, when only the
+     *   instance lacks it, surfaces as a raw `ContractRevertError`.
      */
     getClaimAmount(args: GetClaimAmountArgs): Promise<EncryptedViewResult>;
     /**
@@ -216,10 +247,19 @@ export declare class EcdsaAirdropClient extends AirdropBaseClient {
      * invalid signature, an already-consumed digest, or an already-deduped
      * claim per this instance's `dedupMode`).
      *
+     * **Signer services should pre-check every voucher with this**, as an `eth_call` from the
+     * claimant while the window is open. It is `false` while paused, before `startTime` or past
+     * the deadline, so before the window opens verify off-chain with a `SignatureChecker`-equivalent
+     * check. It is also `false` for every voucher once the `SIGNER_ROLE` key is EIP-7702-delegated,
+     * although the key still holds the role; see the guide's "The ECDSA signer key".
+     *
      * @returns Whether the signature is currently valid and unconsumed for `args.recipient`.
      */
     isSignatureValid(args: IsSignatureValidArgs): Promise<boolean>;
-    /** `bytes32` identifier for the role that must authorize a claim signature. */
+    /**
+     * `bytes32` identifier for the role that must authorize a claim signature. Hold it on a
+     * dedicated key that is never EIP-7702-delegated; see {@link isSignatureValid}.
+     */
     SIGNER_ROLE(): Promise<Hex>;
     /**
      * The live on-chain `CLAIM_TYPEHASH`. Prefer the module-level
@@ -269,7 +309,7 @@ export interface Eip712Domain {
  * Create an {@link EcdsaAirdropClient}. Mirrors viem's `create*` convention.
  *
  * @example
- * const airdrop = createEcdsaAirdropClient({ publicClient, walletClient, address, dedupMode: "perAddress" });
+ * const airdrop = createEcdsaAirdropClient({ publicClient, walletClient, address });
  *
  * @alpha
  */

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

@@ -79,20 +79,26 @@ export interface EncryptUint64BatchArgs {
  * The handle and proof are bound to `contractAddress` and `userAddress` — they
  * cannot be replayed against a different contract or sender. The binding must
  * name whichever contract calls `FHE.fromExternal` and whichever account sends
- * that transaction, and for airdrops those differ between the two flows:
+ * that transaction, and for airdrops those differ between the flows:
  *
  * - **Claiming** (`EcdsaAirdropClient.claim` / `claimAndUnwrap`): bind to
  *   `(airdropInstanceAddress, recipientAddress)`. The `userAddress` MUST be
  *   the **recipient** — the account that sends the claim — not the admin.
+ *   This binding is checked only for a non-empty proof; an ECDSA claim with an
+ *   empty proof (`"0x"`) skips verification and needs a zero handle or one the
+ *   claimant and the instance already hold ACL on. Merkle claims always reject
+ *   an empty proof.
  * - **Funding** (`ConfidentialAirdropFactoryClient.fundAirdrop` /
  *   `createAndFund*`, i.e. a hand-built `FundInput.encryptedInput`):
  *   bind to `(factoryAddress, funderAddress)`. The factory, not the instance,
- *   is what calls `FHE.fromExternal` on the pool amount, and the funder is the
- *   admin sending the create/fund transaction. A proof bound to the instance
- *   reverts inside `FHE.fromExternal`.
+ *   is what calls `FHE.fromExternal` on the pool amount, and the funder is
+ *   whoever sends the create-and-fund or fund transaction. A proof bound to the
+ *   instance reverts inside `FHE.fromExternal`.
+ * - **Merkle leaves**: bind each Merkle leaf to `(instance, instance)`, never
+ *   `(instance, recipient)`; the campaign builders do this for you.
  *
- * Either way `FHE.fromExternal` rejects a proof bound to any other pair, so
- * the binding is a hard requirement, not a convention.
+ * Either way a non-empty proof bound to any other pair is rejected, so the
+ * binding is a hard requirement, not a convention.
  *
  * **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
@@ -153,6 +159,13 @@ export declare function encryptUint64Batch({ encryptor, contractAddress, userAdd
  * `signer` as an explicit parameter and verifies the signature against it,
  * so the signature alone proves who signed.
  *
+ * **`SIGNER_ROLE` must be a dedicated key that is never EIP-7702-delegated** (or an
+ * ERC-1271 contract signer over this digest). A delegation gives the key code, so
+ * `SignatureChecker` switches to ERC-1271 against the delegate and every outstanding
+ * voucher fails (`InvalidSignature`), although the key still holds the role. Pre-check
+ * each voucher with `EcdsaAirdropClient.isSignatureValid`; see the guide's "The ECDSA
+ * signer key".
+ *
  * **Replay is bounded by the instance's `dedupMode`, not by this function.**
  * Every mode consumes the EIP-712 digest, so the exact same signature bytes
  * can never be replayed once used — but that is only ONE of two possible

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

@@ -1,5 +1,5 @@
 import type { Address, Hex } from "viem";
-import { TokenOpsSdkError } from "../core/errors.js";
+import { InvalidArgumentError, TokenOpsSdkError } from "../core/errors.js";
 import type { RevertNameMapper } from "../core/revert-mapper.js";
 /**
  * A Merkle campaign's per-account claim state (`claimedAmount`) sits at an
@@ -166,6 +166,70 @@ export declare class PredictionDriftError extends TokenOpsSdkError {
         cause?: unknown;
     });
 }
+/**
+ * A create reverted because one of its {@link CreateCommitments} no longer matches what the
+ * factory would deploy: the airdrop implementation, the compliance-manager implementation
+ * or the creator's resolved platform delegate moved between quote and send. Nothing was
+ * deployed and the salt is unused. Re-quote; for `airdrop`, also rebuild anything bound to
+ * the old prediction (Merkle leaves, vouchers, encrypted inputs).
+ *
+ * @alpha
+ */
+export declare class CreateCommitmentMismatchError extends TokenOpsSdkError {
+    readonly name = "CreateCommitmentMismatchError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        field: "airdrop" | "complianceManagerImpl" | "complianceDelegate";
+        expected?: Address;
+        actual?: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        field: "airdrop" | "complianceManagerImpl" | "complianceDelegate";
+        expected?: Address;
+        actual?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * `withdrawConfidential` reverted with `ClawbackRequiresPause`: the campaign is unpaused and
+ * still inside its claim window, so the clawback is refused. Pause first (`PAUSER_ROLE`), or
+ * run it outside the window (before `startTime` or after `endTime`).
+ *
+ * @alpha
+ */
+export declare class ClawbackRequiresPauseError extends TokenOpsSdkError {
+    readonly name = "ClawbackRequiresPauseError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * `rescueNativeToken` reverted with `NativeRescueRequiresZeroFee`: the instance charges a gas
+ * fee, so its ETH is fee revenue and belongs to `withdrawGasFee`.
+ *
+ * @alpha
+ */
+export declare class NativeRescueRequiresZeroFeeError extends TokenOpsSdkError {
+    readonly name = "NativeRescueRequiresZeroFeeError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        cause?: unknown;
+    });
+}
 /**
  * Factory `create*` reverted with `UpgradeabilityNotAllowed`: the creator's effective upgradeability policy is off.
  *
@@ -186,7 +250,7 @@ export declare class UpgradeabilityNotAllowedError extends TokenOpsSdkError {
     });
 }
 /**
- * `planInstanceRoleSplit` (`roles.ts`, Task 13) refuses to plan a
+ * `planInstanceRoleSplit` (`roles.ts`) refuses to plan a
  * `FEE_COLLECTOR_ROLE` grant: the role is its own role-admin (not
  * `DEFAULT_ADMIN_ROLE`), so a grant issued from the caller's admin role would
  * simply fail on-chain with `AccessControlUnauthorizedAccount`. An existing
@@ -375,3 +439,14 @@ export declare class UnrecognisedAirdropError extends TokenOpsSdkError {
     });
 }
 export declare const airdropProductMapper: RevertNameMapper;
+/**
+ * The typed form of the factory's `GasFeeExceedsMaximum(gasFee, maxGasFee)`, shared by the
+ * revert mapper and `preflightCreate` so both paths surface one error code.
+ *
+ * @internal
+ */
+export declare function gasFeeExceedsMaximumError(args: {
+    method: string;
+    gasFee: bigint | undefined;
+    maxGasFee: bigint | undefined;
+}): InvalidArgumentError;