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

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