@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

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

@@ -1,27 +1,255 @@
-import type { Address } from "viem";
+import type { Address, Hex } from "viem";
 import { TokenOpsSdkError } from "../core/errors.js";
+import type { RevertNameMapper } from "../core/revert-mapper.js";
 /**
- * The admin-signed claim signature has already been used. Airdrops use a
- * per-signature replay guard (`claimedSignatures[structHash]`); each signed
- * `(recipient, encryptedAmount)` pair is single-use.
+ * A Merkle campaign's per-account claim state (`claimedAmount`) sits at an
+ * ERC-7201 namespaced slot that a previous revision of the contract typed
+ * differently. Namespaced slots are derived from the namespace string, not
+ * from the field's type, so the retype keeps the same address: an in-place
+ * UUPS upgrade across that change hands existing storage to code that reads it
+ * as the new type, which reinterprets every account's settled claim total and
+ * can re-open claims that were already paid.
+ *
+ * A fresh deployment is unaffected - there is no prior storage to
+ * reinterpret. The constraint the SDK enforces is narrow and static: `mode:
+ * "uups"` is refused for Merkle campaigns at create time, so no Merkle
+ * instance the SDK creates can ever be upgraded across the boundary. Clone
+ * mode is unaffected, and ECDSA campaigns are unaffected in either mode (their
+ * storage lives in a different namespace and was not retyped).
+ *
+ * The refusal does not depend on the factory's `defaultUpgradeable` policy,
+ * which is mutable admin state and could permit UUPS at any time.
+ *
+ * @alpha
+ */
+export declare class MerkleUupsUnsupportedError extends TokenOpsSdkError {
+    readonly name = "MerkleUupsUnsupportedError";
+    readonly context: {
+        constraint: "merkle-uups-storage-retype";
+    };
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * `claimAndUnwrap` routes the claim straight into the wrapper's `unwrap`,
+ * which burns from the airdrop instance's own pooled `ERC7984ERC20Wrapper`
+ * balance rather than from any per-claimant sub-balance — the instance holds
+ * one aggregate confidential balance, not a ledger of individual
+ * entitlements. The wrapper's burn succeeds or fails as a whole against that
+ * POOL balance, so the amount it actually delivers is bounded by what the
+ * pool holds, not by the claimant's own outstanding amount.
+ *
+ * Under a stock `ERC7984ERC20Wrapper` that bound is exact: burn succeeds for
+ * the full requested amount whenever the pool can cover it. A wrapper
+ * composed with transfer hooks, or one wrapping a fee-on-transfer underlying
+ * token, can make the amount actually released diverge from what the
+ * airdrop's own accounting assumed, so a claimant can end up credited against
+ * pool balance that was never theirs.
+ *
+ * Thrown by `assertStockWrapper` (`guards.ts`) when `unwrappable: true` is
+ * requested for a token that doesn't probe as a recognised stock wrapper, and
+ * reused here for the on-chain `TokenNotAWrapper` revert (the same
+ * mechanism, caught on-chain instead of pre-flight).
+ *
+ * @alpha
+ */
+export declare class NonStockWrapperError extends TokenOpsSdkError {
+    readonly name = "NonStockWrapperError";
+    readonly context: {
+        constraint: "wrapper-unwrap-pool-bound";
+        token?: Address;
+    };
+    constructor(args?: {
+        token?: Address;
+        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.
+ *
+ * @alpha
+ */
+export type AirdropVariant = "ecdsa" | "merkle";
+/**
+ * A `create*` was about to be sent for a `(variant, mode, deployer, userSalt)`
+ * tuple whose predicted address already holds code.
+ *
+ * The factory's prediction oracles commit to `(implementation, mode, deployer,
+ * userSalt)` and nothing else - the params struct is accepted and ignored
+ * (`predictECDSAAirdropAddress` does not even name its params argument). Two
+ * campaigns therefore collide on one address however different their token,
+ * window, signer or root, and the contracts' own default salt label
+ * (`airdrop.<type>.<token>.<caller>`) collides on the second campaign a caller
+ * runs for the same token. Thrown before the transaction is sent so the caller
+ * gets a named cause rather than a `SaltAlreadyUsed` revert or, worse, a
+ * `FailedDeployment` from the proxy factory.
+ *
+ * @alpha
+ */
+export declare class SaltCollisionError extends TokenOpsSdkError {
+    readonly name = "SaltCollisionError";
+    readonly context: {
+        method: string;
+        variant: AirdropVariant;
+        mode: string;
+        deployer: Address;
+        userSalt: Hex;
+        predictedAddress: Address;
+    };
+    constructor(args: {
+        method: string;
+        variant: AirdropVariant;
+        mode: string;
+        deployer: Address;
+        userSalt: Hex;
+        predictedAddress: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * The factory's init-code hash for a variant changed between the moment an
+ * address was predicted and the moment the prediction was about to be used.
+ *
+ * The hash tracks the factory's implementation pointer, so a change means
+ * `setEcdsaImplementation` / `setMerkleImplementation` landed in the window.
+ * The predicted address is then stale: a Merkle campaign's every ciphertext is
+ * bound to an address the create will no longer produce, and on an
+ * immutable-root instance there is no on-chain repair. Rebuild against a fresh
+ * prediction.
+ *
+ * @alpha
+ */
+export declare class PredictionDriftError extends TokenOpsSdkError {
+    readonly name = "PredictionDriftError";
+    readonly context: {
+        method: string;
+        variant: AirdropVariant;
+        initCodeHashBefore: Hex;
+        initCodeHashAfter: Hex;
+        predictedAddress?: Address;
+    };
+    constructor(args: {
+        method: string;
+        variant: AirdropVariant;
+        initCodeHashBefore: Hex;
+        initCodeHashAfter: Hex;
+        predictedAddress?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * Factory `create*` reverted with `UpgradeabilityNotAllowed`: the creator's effective upgradeability policy is off.
+ *
+ * @alpha
+ */
+export declare class UpgradeabilityNotAllowedError extends TokenOpsSdkError {
+    readonly name = "UpgradeabilityNotAllowedError";
+    readonly context: {
+        method?: string;
+        contractAddress?: Address;
+        creator?: Address;
+    };
+    constructor(args: {
+        creator?: Address;
+        method?: string;
+        contractAddress?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * `planInstanceRoleSplit` (`roles.ts`, Task 13) 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
+ * `FEE_COLLECTOR_ROLE` holder must call `grantRole` directly.
+ *
+ * @alpha
+ */
+export declare class FeeCollectorSelfAdministeredError extends TokenOpsSdkError {
+    readonly name = "FeeCollectorSelfAdministeredError";
+    readonly context: {
+        requestedGrantee?: Address;
+    };
+    constructor(args?: {
+        requestedGrantee?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * ECDSA claim reverted with `DedupIdAlreadyClaimed`: this `dedupId`'s slot was already consumed under `PerDedupId`/`Both`.
+ *
+ * @alpha
+ */
+export declare class DedupIdConsumedError extends TokenOpsSdkError {
+    readonly name = "DedupIdConsumedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        dedupId?: Hex;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        dedupId?: Hex;
+        cause?: unknown;
+    });
+}
+/**
+ * A claim was already settled for this replay-protection dimension.
+ * `replayGuard` names which on-chain guard fired: `"address"` for ECDSA
+ * `AddressAlreadyClaimed` (the `PerAddress`/`Both` dedup slot), `"signature"`
+ * for `SignatureAlreadyUsed` (the EIP-712 digest replay guard, which is the
+ * ONLY guard active under `DedupMode.None`).
+ *
+ * @alpha
  */
 export declare class AlreadyClaimedError extends TokenOpsSdkError {
     readonly name = "AlreadyClaimedError";
     readonly context: {
         method: string;
         contractAddress: Address;
-        caller?: Address;
+        replayGuard: "address" | "signature";
     };
     constructor(args: {
         method: string;
         contractAddress: Address;
-        caller?: Address;
+        replayGuard: "address" | "signature";
         cause?: unknown;
     });
 }
 /**
- * The airdrop's claim window has not opened yet. `startsAt` is populated
- * when the SDK has read the immutable start time; UIs can render a countdown.
+ * Claim reverted with `ClaimNotStarted`: `block.timestamp` is still before the instance's `startTime`.
+ *
+ * @alpha
  */
 export declare class ClaimNotStartedError extends TokenOpsSdkError {
     readonly name = "ClaimNotStartedError";
@@ -29,19 +257,46 @@ export declare class ClaimNotStartedError extends TokenOpsSdkError {
         method: string;
         contractAddress: Address;
         /** Unix seconds. Multiply by 1000 for `new Date(...)`. */
-        startsAt?: number;
+        startTime?: number;
+        currentTime?: number;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        startTime?: number;
+        currentTime?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * ECDSA claim reverted with `SignatureExpired`: `block.timestamp` is past the signature's `deadline`.
+ * Deliberately distinct from `InvalidSignatureError` — that class's message directs a developer to check
+ * `SIGNER_ROLE` membership, which is the wrong fix here and discards both decoded revert arguments. The fix
+ * for this error is always to re-sign with a later `deadline` via `signClaimAuthorization`.
+ *
+ * @alpha
+ */
+export declare class SignatureExpiredError extends TokenOpsSdkError {
+    readonly name = "SignatureExpiredError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        /** Unix seconds — the signature's expiry, chosen by whoever called `signClaimAuthorization`. */
+        deadline?: bigint;
+        currentTime?: bigint;
     };
     constructor(args: {
         method: string;
         contractAddress: Address;
-        startsAt?: number;
+        deadline?: bigint;
+        currentTime?: bigint;
         cause?: unknown;
     });
 }
 /**
- * The airdrop's claim window has closed. `endedAt` is populated when the SDK
- * has read the current end time. For airdrops with `CAN_EXTEND_CLAIM_WINDOW`
- * set, the admin can extend via `extendClaimWindow`.
+ * Claim reverted with `ClaimWindowFinished`: `block.timestamp` is past the instance's `endTime` (end is inclusive on-chain).
+ *
+ * @alpha
  */
 export declare class ClaimWindowClosedError extends TokenOpsSdkError {
     readonly name = "ClaimWindowClosedError";
@@ -49,12 +304,15 @@ export declare class ClaimWindowClosedError extends TokenOpsSdkError {
         method: string;
         contractAddress: Address;
         /** Unix seconds. Multiply by 1000 for `new Date(...)`. */
-        endedAt?: number;
+        endTime?: number;
+        currentTime?: number;
     };
     constructor(args: {
         method: string;
         contractAddress: Address;
-        endedAt?: number;
+        endTime?: number;
+        currentTime?: number;
         cause?: unknown;
     });
 }
+export declare const airdropProductMapper: RevertNameMapper;