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

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

@@ -65,6 +65,34 @@ export declare class NonStockWrapperError extends TokenOpsSdkError {
         cause?: unknown;
     });
 }
+/**
+ * A third party tried to redirect someone else's Merkle payout.
+ *
+ * `to` may differ from the claim identity only when the submitter IS that identity, so a
+ * relayer must leave `to` at `account` (or omit it). Raised by the SDK before the write
+ * and mapped from the contract's `UnauthorizedRedirect` revert, since the rule is decidable
+ * from the arguments alone — same two-producer shape as {@link NonStockWrapperError}.
+ *
+ * Carries all three addresses because the relation is the error: `to` on its own is a
+ * perfectly good address, and blaming it alone would be misleading.
+ *
+ * @alpha
+ */
+export declare class UnauthorizedRedirectError extends TokenOpsSdkError {
+    readonly name = "UnauthorizedRedirectError";
+    readonly context: {
+        constraint: "merkle-third-party-redirect";
+        account?: Address;
+        to?: Address;
+        submitter?: Address;
+    };
+    constructor(args?: {
+        account?: Address;
+        to?: Address;
+        submitter?: Address;
+        cause?: unknown;
+    });
+}
 /**
  * The two campaign variants, as used to label a prediction guard's context.
  *
@@ -287,4 +315,63 @@ export declare class ClaimWindowClosedError extends TokenOpsSdkError {
         cause?: unknown;
     });
 }
+/**
+ * `create*` refused the fee the factory resolved for this creator: it landed
+ * above their `CommonAirdropParams.maxAcceptedGasFee`.
+ *
+ * The fee is frozen into the instance at initialization and is immutable
+ * afterwards, while the value that resolves is set by the factory's fee manager.
+ * The bound is how a creator declines a fee raised between planning and sending
+ * - so the fix is a deliberate one: re-send with a higher bound, or wait for the
+ * fee to come down. Raising the bound to {@link UINT96_MAX} accepts whatever the
+ * factory charges, now and at every later re-plan.
+ *
+ * @alpha
+ */
+export declare class GasFeeNotAcceptedError extends TokenOpsSdkError {
+    readonly name = "GasFeeNotAcceptedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        /** The fee the factory resolved for this creator, in wei. */
+        resolvedFee?: bigint;
+        /** The bound the creator declared, in wei. */
+        maxAcceptedGasFee?: bigint;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        resolvedFee?: bigint;
+        maxAcceptedGasFee?: bigint;
+        cause?: unknown;
+    });
+}
+/**
+ * The canonical factory's registry does not contain this address, so it is not
+ * an airdrop this SDK deployed.
+ *
+ * Instances are the wrong place to ask. An address with the same ABI, the same
+ * events and a pool the deployer controls is trivial to stand up, and nothing
+ * observable at the instance distinguishes it - `factory.isAirdrop` against a
+ * factory address taken from `src/core/addresses.ts` is the only check that
+ * means anything (audit-10).
+ *
+ * @alpha
+ */
+export declare class UnrecognisedAirdropError extends TokenOpsSdkError {
+    readonly name = "UnrecognisedAirdropError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        factory: Address;
+    };
+    constructor(args: {
+        method: string;
+        /** The address that failed the check. */
+        contractAddress: Address;
+        /** The factory whose registry was consulted. */
+        factory: Address;
+        cause?: unknown;
+    });
+}
 export declare const airdropProductMapper: RevertNameMapper;

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

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

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

@@ -1,6 +1,6 @@
 import type { Address, Hex, PublicClient } from "viem";
 import type { PreflightResult } from "../core/preflight.js";
-import type { DeploymentMode } from "./constants.js";
+import { type DeploymentMode } from "./constants.js";
 import { type AirdropVariant } from "./errors.js";
 import type { ConfidentialAirdropFactoryClient } from "./factory.js";
 import type { EcdsaAirdropParams, MerkleAirdropParams } from "./types.js";
@@ -104,6 +104,49 @@ export interface AssertSaltAvailableArgs {
  * @alpha
  */
 export declare function assertSaltAvailable(args: AssertSaltAvailableArgs): Promise<void>;
+/**
+ * The slice of {@link ConfidentialAirdropFactoryClient} {@link assertGasFeeAccepted}
+ * reads. Structural so this module keeps its runtime-import-free shape; the real
+ * client satisfies it as-is.
+ *
+ * @alpha
+ */
+export interface GasFeeResolver {
+    address: Address;
+    resolveGasFee(creator: Address): Promise<bigint>;
+}
+/**
+ * Inputs for {@link assertGasFeeAccepted}.
+ *
+ * @alpha
+ */
+export interface AssertGasFeeAcceptedArgs {
+    factory: GasFeeResolver;
+    /** The account that will send `create*`; fee overrides are per-creator. */
+    creator: Address;
+    /** `CommonAirdropParams.maxAcceptedGasFee`, in wei. */
+    maxAcceptedGasFee: bigint;
+    /** Label for the thrown error. */
+    method: string;
+}
+/**
+ * Refuse a create whose resolved per-claim fee exceeds the creator's declared bound.
+ *
+ * The contract enforces this too. Doing it here buys the reason: the revert
+ * carries the two numbers but not which factory knob produced them, and a
+ * creator who sees `resolvedFee` next to their own bound can tell a raised
+ * default from a custom override they did not know they had.
+ *
+ * The range check is not redundant with the comparison - a bound outside
+ * `uint96` silently wraps at the ABI edge and could encode as a SMALLER number
+ * than intended, turning "accept anything" into "accept almost nothing".
+ *
+ * @throws {@link InvalidArgumentError} when `maxAcceptedGasFee` is negative or above `UINT96_MAX`.
+ * @throws {@link GasFeeNotAcceptedError} when the factory resolves a fee above the bound.
+ *
+ * @alpha
+ */
+export declare function assertGasFeeAccepted(args: AssertGasFeeAcceptedArgs): Promise<void>;
 /**
  * Inputs for {@link assertPredictionFresh}.
  *
@@ -163,7 +206,8 @@ export type PreflightCreateArgs = PreflightCreateCommon & ({
  * transaction, instead of throwing on the first problem.
  *
  * Same checks and the same typed errors the write path enforces: chain
- * support, the Merkle/UUPS refusal, the creator's effective
+ * support, the Merkle/UUPS refusal, the creator's resolved gas fee against
+ * `common.maxAcceptedGasFee`, the creator's effective
  * upgradeability policy when `mode: "uups"` is requested, the stock-wrapper
  * probe when `unwrappable` is set, a salt collision on the predicted
  * address, and - when `expectedInitCodeHash` is supplied - implementation
@@ -207,6 +251,11 @@ export interface ClaimPreflightTarget {
      * the two blocked the claim.
      */
     paused(): Promise<boolean>;
+    /**
+     * Create-time flag; `claimAndUnwrap` reverts `TokenNotUnwrappable` when false. Optional
+     * so a hand-rolled target stays valid — the unwrap blocker is simply not reported then.
+     */
+    unwrappable?: () => Promise<boolean>;
     /** Present on `EcdsaAirdropClient` only. */
     isSignatureValid?: (args: {
         recipient: Address;
@@ -217,6 +266,40 @@ export interface ClaimPreflightTarget {
         signature: Hex;
     }) => Promise<boolean>;
 }
+/**
+ * The slice of {@link ConfidentialAirdropFactoryClient} the genuineness check reads.
+ *
+ * @alpha
+ */
+export interface AirdropRegistry {
+    readonly address: Address;
+    /**
+     * The chain this factory is bound to. Checked against the instance's own
+     * `chainId` before the registry is consulted - a registry answer from the
+     * wrong chain is worse than no answer, because it reads as a `true`.
+     */
+    readonly chainId: number;
+    isAirdrop(candidate: Address): Promise<boolean>;
+}
+/**
+ * Refuse an instance the canonical factory's registry does not contain.
+ *
+ * The factory has to be one the caller already trusts - taken from
+ * `src/core/addresses.ts`, not read off the instance. An instance that names
+ * its own factory proves nothing: a fake instance names a fake factory, which
+ * answers `true`.
+ *
+ * @throws {@link UnrecognisedAirdropError} when the registry does not contain `airdrop`.
+ *
+ * @alpha
+ */
+export declare function assertKnownAirdrop(args: {
+    factory: AirdropRegistry;
+    airdrop: Address;
+    /** The chain the instance being vetted lives on. */
+    chainId: number;
+    method: string;
+}): Promise<void>;
 /**
  * The signature material {@link preflightClaim} needs to check an ECDSA claim.
  *
@@ -237,14 +320,58 @@ export interface EcdsaClaimPreflightSignature {
  */
 export interface PreflightClaimArgs {
     airdrop: ClaimPreflightTarget;
-    /** The account that will send the claim - not the payout destination. */
+    /**
+     * The account that will SEND the claim, and therefore pays the exact-equality gas fee.
+     * On a relayed Merkle claim this is the relayer, not the entitled account.
+     */
     claimant: Address;
+    /**
+     * Merkle campaigns only: the claim identity, when it is not the submitter. Defaults to
+     * `claimant`. Supplying it enables the two argument-relation checks the contract makes
+     * before any FHE work — the zero identity and the third-party redirect rule.
+     */
+    account?: Address | undefined;
+    /** The payout destination, if one will be passed. Omitted means "defaults to `account`". */
+    to?: Address | undefined;
+    /**
+     * Set for `claimAndUnwrap`, which has no `account` parameter and is always submitted for
+     * the caller — so a claim identity that is not the submitter can never settle through it.
+     */
+    entrypoint?: "claim" | "claimAndUnwrap" | undefined;
     /**
      * ECDSA campaigns only. Supplied together with a client that exposes
      * `isSignatureValid`, it adds the authorisation check to the report.
      */
     signature?: EcdsaClaimPreflightSignature | undefined;
+    /**
+     * The canonical factory, from `src/core/addresses.ts`. Supplying it adds the
+     * genuineness check (audit-10): every other blocker here describes a claim
+     * that will fail, but a claim against a look-alike instance SUCCEEDS and
+     * delivers nothing. Omitting it skips that one check.
+     */
+    factory?: AirdropRegistry | undefined;
 }
+/**
+ * The three argument-relation rules the Merkle claim path enforces before it touches the
+ * 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.
+ *
+ * @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 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;
 /**
  * Report what would stop `claim` / `claimAndUnwrap` right now, without sending
  * anything.
@@ -252,7 +379,9 @@ export interface PreflightClaimArgs {
  * Checks the chain, the pause flag, the claim window on both ends, whether the
  * claimant can cover the instance's exact-equality gas fee, and - for an ECDSA
  * campaign given `signature` - whether the authorisation is currently valid and
- * unconsumed.
+ * unconsumed. Given `account` or `entrypoint`, it also checks the Merkle claim path's
+ * three argument relations: the zero identity, the third-party redirect rule, and
+ * `claimAndUnwrap`'s self-only constraint.
  *
  * The pause is read on its own rather than through `isClaimWindowActive()`:
  * that read ANDs the pause and the window together, so a `false` from it