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

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

@@ -0,0 +1,29 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetCustomFeeArgs extends WriteAccountOverride {
+    /** The creator whose fee is being overridden - NOT the admin sending the transaction. */
+    creator: Address;
+    /** Wei charged per claim for this creator's future instances, `uint96` on-chain. */
+    gasFee: bigint;
+}
+/**
+ * Override the factory's default per-claim gas fee for one creator.
+ *
+ * Requires `FEE_MANAGER_ROLE`.
+ *
+ * **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. Also every
+ * `useResolveGasFee` entry, since an override is what that hook resolves.
+ *
+ * @example
+ * const setCustomFee = useSetCustomFee();
+ * await setCustomFee.mutateAsync({ creator, gasFee: 0n });
+ *
+ * @alpha
+ */
+export declare function useSetCustomFee(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetCustomFeeArgs>;

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

@@ -0,0 +1,31 @@
+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 SetDefaultDelegateToComplianceArgs extends WriteAccountOverride {
+    /** Whether new instances default to delegating compliance disclosure to the platform delegate. */
+    on: boolean;
+}
+/**
+ * Set the factory-wide default for whether new instances delegate compliance
+ * disclosure to the platform delegate. Requires `COMPLIANCE_WIRING_ROLE`.
+ *
+ * **Ordering is load-bearing.** `on: true` reverts `ZeroComplianceDelegate`
+ * unless {@link useSetComplianceDelegate} has already set a delegate - read
+ * {@link useFactoryComplianceDelegate} first and sequence the two writes.
+ *
+ * **Invalidates:** the `fn "effectiveDelegateToCompliance"` PREFIX and the
+ * `fn "compliancePolicy"` PREFIX - every cached creator at once, because this
+ * write is chain-wide: any creator without an override moves with the
+ * default, and {@link useFactoryCompliancePolicy}'s bundle carries the
+ * resolved `effective` field. Contrast {@link useSetCompliancePolicy}, which
+ * stays keyed on the one creator it targets.
+ *
+ * @example
+ * const setDefault = useSetDefaultDelegateToCompliance();
+ * await setDefault.mutateAsync({ on: true });
+ *
+ * @alpha
+ */
+export declare function useSetDefaultDelegateToCompliance(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetDefaultDelegateToComplianceArgs>;

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

@@ -0,0 +1,30 @@
+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 SetDefaultGasFeeArgs extends WriteAccountOverride {
+    /** Wei charged per claim, `uint96` on-chain. */
+    gasFee: bigint;
+}
+/**
+ * Set the per-claim gas fee that new instances default to when their creator
+ * has no `setCustomFee` override.
+ *
+ * Requires `FEE_MANAGER_ROLE`. Affects only instances created afterwards: an
+ * instance's `gasFee()` is baked in at create time, so no deployed campaign's
+ * fee changes.
+ *
+ * **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();
+ * await setDefaultFee.mutateAsync({ gasFee: parseEther("0.0001") });
+ *
+ * @alpha
+ */
+export declare function useSetDefaultGasFee(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetDefaultGasFeeArgs>;

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

@@ -0,0 +1,27 @@
+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 SetDefaultUpgradeableArgs extends WriteAccountOverride {
+    /** Whether creators without an override may deploy `mode: "uups"`. */
+    allowed: boolean;
+}
+/**
+ * Set the factory-wide default for whether a `create*` may deploy
+ * `mode: "uups"`. Requires `UPGRADE_MANAGER_ROLE`.
+ *
+ * **Invalidates:** the `fn "effectiveUpgradeable"`,
+ * `fn "upgradeabilityPolicy"` and `fn `preflightCreate`` PREFIXES.
+ * Prefix invalidation is correct here because the write is chain-wide: every
+ * cached creator without an override moves with the default, and a preflight
+ * result is exactly the thing that flips between allowed and
+ * `UpgradeabilityNotAllowedError`.
+ *
+ * @example
+ * const setDefault = useSetDefaultUpgradeable();
+ * await setDefault.mutateAsync({ allowed: false });
+ *
+ * @alpha
+ */
+export declare function useSetDefaultUpgradeable(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetDefaultUpgradeableArgs>;

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

@@ -0,0 +1,34 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetEcdsaImplementationArgs extends WriteAccountOverride {
+    /** The new ECDSA implementation. The zero address reverts. */
+    implementation: Address;
+}
+/**
+ * Point future `createEcdsaAirdrop*` calls at a new ECDSA implementation.
+ *
+ * Requires `IMPL_MANAGER_ROLE`. Deployed instances are untouched - a clone
+ * stays bound to the implementation live when it was created.
+ *
+ * **Moving this pointer moves every future predicted address.** Any campaign
+ * plan built before this write is stale, and on an immutable-root instance
+ * its entries would be unclaimable; that is what `PredictionDriftError`
+ * exists to catch.
+ *
+ * **Invalidates:** `useFactoryImplementations` (fn `"implementations"`), plus
+ * the fn `"getEcdsaInitCodeHash"`, `"predictEcdsaAirdropAddress"` and
+ * ``preflightCreate`` PREFIXES - every cached args combination of each,
+ * because the init-code hash, the predicted address and the create preflight
+ * all shift together with the pointer. Invalidating the predictions is what
+ * stops a mounted UI offering a dead address.
+ *
+ * @example
+ * const setEcdsaImpl = useSetEcdsaImplementation();
+ * await setEcdsaImpl.mutateAsync({ implementation: newEcdsaImpl });
+ *
+ * @alpha
+ */
+export declare function useSetEcdsaImplementation(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetEcdsaImplementationArgs>;

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

@@ -0,0 +1,27 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetFeeCollectorArgs extends WriteAccountOverride {
+    /** Where accrued claim-fee ETH withdraws to. The zero address reverts. */
+    feeCollector: Address;
+}
+/**
+ * Redirect where the factory's accrued claim-fee ETH withdraws to.
+ *
+ * Requires `FEE_MANAGER_ROLE`. The headless factory method takes positional
+ * args, so this hook adapts its object-shaped variables to
+ * `setFeeCollector(feeCollector, account?)`.
+ *
+ * **Invalidates:** this factory's `useFactoryFees` entry (fn `"fees"`), which
+ * bundles `feeCollector` with `defaultGasFee`. Nothing else moves - deployed
+ * instances hold no copy of the collector.
+ *
+ * @example
+ * const setCollector = useSetFeeCollector();
+ * await setCollector.mutateAsync({ feeCollector: treasuryAddress });
+ *
+ * @alpha
+ */
+export declare function useSetFeeCollector(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetFeeCollectorArgs>;

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/advanced/react/useSetMerkleImplementation.d.ts

@@ -0,0 +1,30 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetMerkleImplementationArgs extends WriteAccountOverride {
+    /** The new Merkle implementation. The zero address reverts. */
+    implementation: Address;
+}
+/**
+ * Point future `createMerkleAirdrop*` calls at a new Merkle implementation.
+ *
+ * Requires `IMPL_MANAGER_ROLE`. Deployed instances are untouched.
+ *
+ * **Same prediction-drift hazard as {@link useSetEcdsaImplementation}, with a
+ * worse blast radius.** Merkle campaigns are commonly immutable-root: a plan
+ * whose entries were bound to an address predicted before this write has no
+ * on-chain repair, so re-plan rather than re-point.
+ *
+ * **Invalidates:** `useFactoryImplementations` (fn `"implementations"`), plus
+ * the fn `"getMerkleInitCodeHash"`, `"predictMerkleAirdropAddress"` and
+ * ``preflightCreate`` PREFIXES - every cached args combination of each.
+ *
+ * @example
+ * const setMerkleImpl = useSetMerkleImplementation();
+ * await setMerkleImpl.mutateAsync({ implementation: newMerkleImpl });
+ *
+ * @alpha
+ */
+export declare function useSetMerkleImplementation(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetMerkleImplementationArgs>;

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

@@ -0,0 +1,31 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetUpgradeabilityPolicyArgs extends WriteAccountOverride {
+    /** The creator the override applies to - not the admin sending the transaction. */
+    creator: Address;
+    /** Whether that creator may deploy `mode: "uups"`. */
+    allowed: boolean;
+}
+/**
+ * Override the factory's default upgradeability policy for one creator.
+ * Requires `UPGRADE_MANAGER_ROLE`.
+ *
+ * This is the write that flips whether that creator's next `mode: "uups"`
+ * create is refused with `UpgradeabilityNotAllowedError`.
+ *
+ * **Invalidates:** `fn "effectiveUpgradeable"` and
+ * `fn "upgradeabilityPolicy"` keyed on `args.creator` - the TARGET creator,
+ * never the sending admin - plus the `fn `preflightCreate`` PREFIX,
+ * which is keyed on the whole create payload rather than the creator alone
+ * and so cannot be narrowed here.
+ *
+ * @example
+ * const setPolicy = useSetUpgradeabilityPolicy();
+ * await setPolicy.mutateAsync({ creator, allowed: true });
+ *
+ * @alpha
+ */
+export declare function useSetUpgradeabilityPolicy(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetUpgradeabilityPolicyArgs>;

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.
@@ -588,6 +627,14 @@ export declare class AirdropBaseClient {
     protected mapRevert(method: string, err: unknown, account: Account | Address): TokenOpsSdkError;
     protected requireWallet(method: string): WalletClient;
     protected resolveAccount(wallet: WalletClient, override: Account | Address | undefined, method: string): Account | Address;
+    /**
+     * The address that will actually send the transaction, as a plain `Address`.
+     *
+     * Needed by any method whose arguments must be validated against the sender before
+     * the write — on the Merkle variant the claim identity, the payout destination and
+     * the submitter are three separate addresses with rules between them.
+     */
+    protected resolveSender(override: Account | Address | undefined, method: string): Address;
 }
 /**
  * Create an {@link AirdropBaseClient}. Mirrors viem's `create*` convention.

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

@@ -46,12 +46,45 @@ 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 {
+export interface BuildMerkleCampaignArgs extends CampaignSubmitterOption {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     recipients: readonly CampaignRecipient[];
@@ -63,7 +96,9 @@ export interface BuildMerkleCampaignArgs {
  * @alpha
  */
 export interface EncryptedCampaignLeaf extends MerkleLeafInput {
-    /** The KMS input proof binding `handle` to `(instance, recipient)`. Required at claim time, unused by the tree. */
+    /** 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. */
     inputProof: Hex;
 }
 /**
@@ -71,7 +106,7 @@ export interface EncryptedCampaignLeaf extends MerkleLeafInput {
  *
  * @alpha
  */
-export interface EncryptCampaignAmountsArgs {
+export interface EncryptCampaignAmountsArgs extends CampaignSubmitterOption {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     recipients: readonly CampaignRecipient[];
@@ -84,17 +119,17 @@ export interface EncryptCampaignAmountsArgs {
  * publishing a root, or to hand them to something else that builds the tree.
  * If you just want a campaign, {@link buildMerkleCampaign} does both.
  *
- * **One relayer request per recipient, issued concurrently.** Each input binds
- * to `(instance, that recipient)`, so they cannot share a proof: a single
- * batched proof binds every value to one account and produces a campaign only
- * that account can claim against.
+ * **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.
  *
  * **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 `{ recipient, handle, inputProof }` per roster entry, in roster order.
+ * @returns One `{ account, boundTo, 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`.
  *
@@ -106,8 +141,9 @@ export interface EncryptCampaignAmountsArgs {
  */
 export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs): Promise<readonly EncryptedCampaignLeaf[]>;
 /**
- * Encrypt every recipient's cumulative total against their own address, then
- * build the tree those ciphertexts belong to.
+ * 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.
  *
  * 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
@@ -124,10 +160,9 @@ 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.
  *
- * **One relayer request per recipient, issued concurrently.** Each input has a
- * different `userAddress`, so they cannot share a proof — see the note on
- * `encryptUint64Batch` below. Large rosters fan out correspondingly; chunk the
- * roster yourself if your relayer rate-limits.
+ * **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.
  *
  * **Already hold the handles?** This function encrypts unconditionally, and
  * encryption is randomised — so re-encrypting handles that exist elsewhere
@@ -146,17 +181,17 @@ export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs)
  *   encryptor,
  * });
  * await airdrop.setMerkleRoot({ newRoot: root });
- * // then hand `entries[i]` to `entries[i].recipient`, out of band
+ * // then hand `entries[i]` to `entries[i].account`, out of band
  *
  * @alpha
  */
-export declare function buildMerkleCampaign({ instance, recipients, encryptor, }: BuildMerkleCampaignArgs): Promise<BuiltCampaign>;
+export declare function buildMerkleCampaign({ instance, recipients, encryptor, submitter, }: BuildMerkleCampaignArgs): Promise<BuiltCampaign>;
 /**
  * Inputs for {@link planMerkleCampaign}.
  *
  * @alpha
  */
-export interface PlanMerkleCampaignArgs {
+export interface PlanMerkleCampaignArgs extends CampaignSubmitterOption {
     factory: ConfidentialAirdropFactoryClient;
     /** The exact params the subsequent `createMerkleAirdrop` will use, except `merkleRoot` — supply the planned root there. */
     params: MerkleAirdropParams;
@@ -236,13 +271,13 @@ export interface PlannedCampaign extends BuiltCampaign {
  *
  * @alpha
  */
-export declare function planMerkleCampaign({ factory, params, mode, creator, userSalt, recipients, encryptor, }: PlanMerkleCampaignArgs): Promise<PlannedCampaign>;
+export declare function planMerkleCampaign({ factory, params, mode, creator, userSalt, recipients, encryptor, submitter, }: PlanMerkleCampaignArgs): Promise<PlannedCampaign>;
 /**
  * Inputs for {@link rotateMerkleRoot}.
  *
  * @alpha
  */
-export interface RotateMerkleRootArgs extends WriteAccountOverride {
+export interface RotateMerkleRootArgs extends WriteAccountOverride, CampaignSubmitterOption {
     /** 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. */
@@ -276,6 +311,12 @@ 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.
+ *
  * Requires `MERKLE_ADMIN_ROLE` on the instance and an instance created with
  * `isMerkleRootMutable: true`.
  *
@@ -294,4 +335,4 @@ export interface RotatedCampaign extends BuiltCampaign {
  *
  * @alpha
  */
-export declare function rotateMerkleRoot({ airdrop, recipients, encryptor, account, }: RotateMerkleRootArgs): Promise<RotatedCampaign>;
+export declare function rotateMerkleRoot({ airdrop, recipients, encryptor, submitter, account, }: RotateMerkleRootArgs): Promise<RotatedCampaign>;

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

@@ -3,7 +3,7 @@
  *
  * @alpha
  */
-export declare const AIRDROP_CONTRACTS_COMMIT = "8e5b144bdbcdf35b9f36b62f5257d795bf954e8e";
+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>;
     /**