@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

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

@@ -0,0 +1,317 @@
+import type { Address, Hex, PublicClient } from "viem";
+import type { PreflightResult } from "../core/preflight.js";
+import type { DeploymentMode } from "./constants.js";
+import { type AirdropVariant } from "./errors.js";
+import type { ConfidentialAirdropFactoryClient } from "./factory.js";
+import type { EcdsaAirdropParams, MerkleAirdropParams } from "./types.js";
+/**
+ * Chains the airdrop v2 contracts are reachable on.
+ *
+ * Beyond the address registry this encodes an FHEVM constraint: every instance
+ * reads `ZamaConfig` at initialize time and reverts with
+ * `ZamaProtocolUnsupported` (declared by `@fhevm/solidity`, reached through
+ * `FHE.setCoprocessor`) anywhere the protocol is absent. An out-of-list chain
+ * can therefore only ever produce a wasted transaction.
+ */
+export declare const SUPPORTED_CHAIN_IDS: readonly number[];
+/**
+ * Refuse a chain the airdrop v2 contracts are not reachable on.
+ *
+ * Every client in this module calls it from its constructor, before resolving
+ * an address: an unsupported chain is a hard "no", whereas a missing registry
+ * entry is a "not deployed there yet", and the two deserve different errors.
+ *
+ * @throws {@link UnsupportedChainError} for anything outside {@link SUPPORTED_CHAIN_IDS}.
+ */
+export declare function assertSupportedChain(chainId: number): void;
+/**
+ * Refuse `mode: "uups"` for a Merkle campaign.
+ *
+ * The Merkle implementation's per-account `claimedAmount` mapping occupies an
+ * ERC-7201 namespaced slot that an earlier revision typed differently, so an
+ * in-place upgrade across that change reinterprets live storage - see
+ * {@link MerkleUupsUnsupportedError} for the full mechanism. Refusing at
+ * create time is what guarantees no SDK-created Merkle instance can ever be
+ * upgraded across it.
+ *
+ * Static: no RPC, so it runs before anything else on the Merkle create paths.
+ * The factory's `defaultUpgradeable == false` currently makes a UUPS create
+ * revert on-chain anyway, but that is a mutable policy owned by an admin key -
+ * this guard does not depend on it.
+ *
+ * @throws {@link MerkleUupsUnsupportedError} when `mode` is `"uups"`.
+ */
+export declare function assertMerkleModeSupported(mode: DeploymentMode): void;
+/** Inputs for {@link assertStockWrapper}. */
+export interface AssertStockWrapperArgs {
+    publicClient: PublicClient;
+    /** The campaign's ERC-7984 token. */
+    token: Address;
+    /** The create-time flag. A `false` here makes this guard a no-op, by design. */
+    unwrappable: boolean;
+}
+/**
+ * Refuse `unwrappable: true` on a token that does not probe as a stock
+ * `ERC7984ERC20Wrapper` — see {@link NonStockWrapperError} for why a
+ * non-stock wrapper breaks `claimAndUnwrap`'s accounting.
+ *
+ * Needs one read, so it runs before the send rather than before the RPC. A
+ * CONTRACT REVERT, a zero-data return, or a zero-address answer from
+ * `underlying()` is taken as "not a stock wrapper": the probe cannot prove a
+ * wrapper is unhooked, only that it presents the stock interface, which is the
+ * strongest statement available off-chain and strictly better than discovering
+ * it at claim time.
+ *
+ * Anything that is not one of those — an RPC timeout, a rate limit, a client
+ * pointed at the wrong chain — is rethrown as itself. Reporting a transport
+ * failure as `NonStockWrapperError` would block a legitimate
+ * `unwrappable: true` create with a diagnosis the caller cannot act on;
+ * `isContractRevert` is the same discriminator the module's `#preflightWrite`
+ * implementations use for exactly this distinction.
+ *
+ * @throws {@link NonStockWrapperError} when `unwrappable` is set and the probe reverts, returns no data, or answers zero.
+ * @throws The underlying transport error, unchanged, when the probe fails for any other reason.
+ */
+export declare function assertStockWrapper(args: AssertStockWrapperArgs): Promise<void>;
+/**
+ * Inputs for {@link assertSaltAvailable}.
+ *
+ * @alpha
+ */
+export interface AssertSaltAvailableArgs {
+    publicClient: PublicClient;
+    /** The address the factory's prediction oracle returned for this tuple. */
+    predictedAddress: Address;
+    variant: AirdropVariant;
+    mode: DeploymentMode;
+    deployer: Address;
+    userSalt: Hex;
+    /** Label for the thrown error. */
+    method: string;
+}
+/**
+ * Refuse a create whose predicted address is already occupied.
+ *
+ * A predicted address commits to `(implementation, mode, deployer, userSalt)`
+ * and nothing else, so reusing a salt collides regardless of how different the
+ * two campaigns' params are - and the contracts' own default salt label
+ * (`airdrop.<type>.<token>.<caller>`) collides on the second campaign a caller
+ * runs against one token. One `eth_getCode` turns that into a named error
+ * instead of a revert the caller has to decode.
+ *
+ * @throws {@link SaltCollisionError} when the predicted address holds code.
+ *
+ * @alpha
+ */
+export declare function assertSaltAvailable(args: AssertSaltAvailableArgs): Promise<void>;
+/**
+ * Inputs for {@link assertPredictionFresh}.
+ *
+ * @alpha
+ */
+export interface AssertPredictionFreshArgs {
+    variant: AirdropVariant;
+    /** Init-code hash read before the prediction was put to use. */
+    initCodeHashBefore: Hex;
+    /** The same hash read after. */
+    initCodeHashAfter: Hex;
+    predictedAddress?: Address | undefined;
+    /** Label for the thrown error. */
+    method: string;
+}
+/**
+ * Judge the two init-code-hash observations a prediction-consuming flow takes
+ * on either side of its work.
+ *
+ * Equal hashes mean the factory's implementation pointer for the variant did
+ * not move, so the predicted address still stands. Different hashes mean it
+ * did, and everything derived from the prediction is stale.
+ *
+ * @throws {@link PredictionDriftError} when the two hashes differ.
+ *
+ * @alpha
+ */
+export declare function assertPredictionFresh(args: AssertPredictionFreshArgs): void;
+/** Fields shared by both variants of {@link PreflightCreateArgs}. */
+interface PreflightCreateCommon {
+    factory: ConfidentialAirdropFactoryClient;
+    mode: DeploymentMode;
+    /** The account that will send `create*`. CREATE2 salts are per-deployer. */
+    creator: Address;
+    userSalt: Hex;
+    /**
+     * The variant's init-code hash observed when the address was predicted -
+     * e.g. `PlannedCampaign.initCodeHashAfter`. Supplying it turns on the
+     * drift check; omitting it skips that one check only.
+     */
+    expectedInitCodeHash?: Hex | undefined;
+}
+/**
+ * Inputs for {@link preflightCreate}.
+ *
+ * @alpha
+ */
+export type PreflightCreateArgs = PreflightCreateCommon & ({
+    variant: "ecdsa";
+    params: EcdsaAirdropParams;
+} | {
+    variant: "merkle";
+    params: MerkleAirdropParams;
+});
+/**
+ * Run every create-time guardrail read-only and report what would block the
+ * transaction, instead of throwing on the first problem.
+ *
+ * Same checks and the same typed errors the write path enforces: chain
+ * support, the Merkle/UUPS refusal, the creator's effective
+ * upgradeability policy when `mode: "uups"` is requested, the stock-wrapper
+ * probe when `unwrappable` is set, a salt collision on the predicted
+ * address, and - when `expectedInitCodeHash` is supplied - implementation
+ * drift since the prediction was taken.
+ *
+ * @returns `{ ready, blockers }`. `blockers` carries the errors `create*`
+ *   would have thrown, so a UI can branch on `error.code` exactly as it does
+ *   in `onError`.
+ *
+ * @example
+ * const { ready, blockers } = await preflightCreate({
+ *   factory, variant: "merkle", params, mode: "clone", creator, userSalt,
+ *   expectedInitCodeHash: plan.initCodeHashAfter,
+ * });
+ * if (!ready) return blockers.map((b) => b.code);
+ *
+ * @alpha
+ */
+export declare function preflightCreate(args: PreflightCreateArgs): Promise<PreflightResult>;
+/**
+ * The subset of an instance client {@link preflightClaim} reads.
+ *
+ * Declared structurally rather than as `AirdropBaseClient` so this module
+ * stays free of a runtime import of the client it guards; `AirdropBaseClient`
+ * and both variant subclasses satisfy it as-is.
+ *
+ * @alpha
+ */
+export interface ClaimPreflightTarget {
+    readonly address: Address;
+    readonly chainId: number;
+    readonly publicClient: PublicClient;
+    hasClaimStarted(): Promise<boolean>;
+    hasClaimEnded(): Promise<boolean>;
+    startTime(): Promise<number>;
+    endTime(): Promise<number>;
+    gasFee(): Promise<bigint>;
+    /**
+     * The raw `PausableUpgradeable` flag, NOT `isClaimWindowActive()` — the
+     * latter ANDs the pause and the window together, which cannot say which of
+     * 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;
+        encryptedAmountHandle: Hex;
+        dedupId: Hex;
+        deadline: bigint;
+        signer: Address;
+        signature: Hex;
+    }) => Promise<boolean>;
+}
+/**
+ * The signature material {@link preflightClaim} needs to check an ECDSA claim.
+ *
+ * @alpha
+ */
+export interface EcdsaClaimPreflightSignature {
+    /** The external handle only - a view never calls `FHE.fromExternal`, so no input proof. */
+    encryptedAmountHandle: Hex;
+    dedupId: Hex;
+    deadline: bigint;
+    signer: Address;
+    signature: Hex;
+}
+/**
+ * Inputs for {@link preflightClaim}.
+ *
+ * @alpha
+ */
+export interface PreflightClaimArgs {
+    airdrop: ClaimPreflightTarget;
+    /**
+     * 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 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.
+ *
+ * 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. 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
+ * cannot say which of the two blocked the claim, whereas the window is already
+ * reported here as two distinct blockers. A paused campaign therefore appears
+ * as its own `PausedError` — the likeliest reason a claim reverts while the
+ * window is open.
+ *
+ * It deliberately does NOT check the claimant's allocation:
+ * that value is encrypted, and an SDK-side "you have nothing to claim" would
+ * require decrypting it.
+ *
+ * @returns `{ ready, blockers }` with the same typed errors the claim would throw.
+ *
+ * @alpha
+ */
+export declare function preflightClaim(args: PreflightClaimArgs): Promise<PreflightResult>;
+export {};