@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

package/dist/fhe-airdrop/react/useWithdrawGasFee.d.ts

@@ -0,0 +1,37 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/** @alpha */
+export interface WithdrawGasFeeArgs extends WriteAccountOverride {
+    /** Where the ETH goes. */
+    recipient: Address;
+    /**
+     * Wei. Exceeding the accrued balance reverts `InsufficientFeeBalance`,
+     * surfaced as `InsufficientBalanceError`.
+     */
+    amount: bigint;
+}
+/**
+ * Withdraw an airdrop instance's accrued per-claim fee ETH to `recipient`.
+ *
+ * Requires `FEE_COLLECTOR_ROLE`, which is self-administered on
+ * `ConfidentialAirdropBase` — no other role can grant it, so
+ * {@link useGrantInstanceRoles} cannot bootstrap it from an admin key. Use
+ * `useAirdropRoleMembers(FEE_COLLECTOR_ROLE)` to show who can actually call
+ * this.
+ *
+ * **`amount` is public ETH in wei, not a confidential quantity** — unlike
+ * every other amount in this module it is safe to log and to render.
+ *
+ * **Invalidates:** nothing. No read hook in this subpath exposes the
+ * instance's accrued fee balance, so no cached query is left stale. If such a
+ * read is ever added, this is its invalidator.
+ *
+ * @example
+ * const withdrawFees = useWithdrawGasFee({ address: airdropAddress });
+ * await withdrawFees.mutateAsync({ recipient: treasuryAddress, amount: parseEther("0.1") });
+ *
+ * @alpha
+ */
+export declare function useWithdrawGasFee(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, WithdrawGasFeeArgs>;

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

@@ -0,0 +1,147 @@
+import type { Address, Hex } from "viem";
+import { type TokenOpsSdkError } from "../core/errors.js";
+import type { AirdropBaseClient } from "./airdrop-base.js";
+/**
+ * The on-chain role names this module knows how to grant or revoke.
+ *
+ * @alpha
+ */
+export type RoleName = "DEFAULT_ADMIN_ROLE" | "PAUSER_ROLE" | "WINDOW_ADMIN_ROLE" | "TREASURY_ROLE" | "RESCUER_ROLE" | "DISCLOSURE_ADMIN_ROLE" | "UPGRADER_ROLE" | "MERKLE_ADMIN_ROLE" | "SIGNER_ROLE";
+/**
+ * The roles a campaign creator may hand off after `createEcdsaAirdrop` /
+ * `createMerkleAirdrop`. Every field is optional — pass only the roles you
+ * intend to split.
+ *
+ * `merkleAdmin` only exists on Merkle instances and `signer` only on ECDSA
+ * ones; passing either against the wrong variant is one of
+ * {@link planInstanceRoleSplit}'s three refusals.
+ *
+ * @alpha
+ */
+export interface InstanceRoleAssignment {
+    pauser?: Address;
+    windowAdmin?: Address;
+    treasury?: Address;
+    rescuer?: Address;
+    disclosureAdmin?: Address;
+    upgrader?: Address;
+    merkleAdmin?: Address;
+    signer?: Address;
+    /** Granting this always fails from DEFAULT_ADMIN — see planInstanceRoleSplit. */
+    feeCollector?: Address;
+    /** Transfers DEFAULT_ADMIN_ROLE. Granted first, then revoked from the creator. */
+    admin?: Address;
+}
+/**
+ * One `grantRole`/`revokeRole` transaction {@link grantInstanceRoles} will submit, in order.
+ *
+ * @alpha
+ */
+export interface RoleGrantStep {
+    kind: "grant" | "revoke";
+    role: RoleName;
+    account: Address;
+}
+/**
+ * The outcome of one step from {@link grantInstanceRoles}. Exactly one of
+ * `hash` / `error` is set — never both, never neither. `hash` is set only
+ * once that transaction's receipt has been confirmed with `status ===
+ * "success"`; a transaction that was submitted but mined with a reverted
+ * status is reported as `error`, not `hash`.
+ *
+ * @alpha
+ */
+export interface RoleGrantOutcome {
+    role: string;
+    account: Address;
+    hash?: Hex;
+    error?: TokenOpsSdkError;
+}
+/**
+ * Turn an {@link InstanceRoleAssignment} into an ordered list of
+ * `grantRole`/`revokeRole` steps — a pure function, precisely so its ordering
+ * guarantees are testable without a chain.
+ *
+ * Three requests are refused outright rather than turned into a step that
+ * would only revert on-chain:
+ *
+ * 1. **`feeCollector`.** `FEE_COLLECTOR_ROLE` is self-administered
+ *    (`_setRoleAdmin(FEE_COLLECTOR_ROLE, FEE_COLLECTOR_ROLE)`,
+ *    `ConfidentialAirdropBase.sol:142`) — `DEFAULT_ADMIN_ROLE` cannot grant
+ *    it, only an existing member can, and the campaign creator never is one
+ *    (the factory's collector is seeded instead, `:143`).
+ * 2. **`admin` set to the zero address.** Mirrors the contract's
+ *    unconditional `ZeroAdminGrant` guard (`_grantRole`, `:281`).
+ * 3. **A variant-only role on the wrong campaign** — `merkleAdmin` on an
+ *    ECDSA instance, or `signer` on a Merkle one. Neither role exists there;
+ *    the getter itself would revert.
+ *
+ * `admin`, when present, always produces two steps — grant the new admin,
+ * then revoke `args.caller` — and the revoke is always ORDERED LAST, after
+ * every other step in the plan. `_revokeRole`'s `LastAdmin` floor
+ * (`ConfidentialAirdropBase.sol:261`) blocks removing the sole
+ * `DEFAULT_ADMIN_ROLE` member, so revoking the creator first would strand
+ * every later grant with no admin left to authorize it.
+ *
+ * @throws {@link FeeCollectorSelfAdministeredError} for refusal 1 — a distinct
+ *   condition with a distinct remedy (an existing collector must call
+ *   `grantRole`), so it gets its own type rather than being folded into the
+ *   generic argument error.
+ * @throws {@link InvalidArgumentError} for refusals 2 and 3.
+ *
+ * @alpha
+ */
+export declare function planInstanceRoleSplit(args: {
+    assignment: InstanceRoleAssignment;
+    caller: Address;
+    airdropType: "ecdsa" | "merkle";
+}): RoleGrantStep[];
+/**
+ * Execute an {@link InstanceRoleAssignment} against a live instance:
+ * {@link planInstanceRoleSplit} the steps, then submit them one at a time,
+ * **waiting for each step's receipt before submitting the next.**
+ *
+ * That confirmation is not optional bookkeeping — it is what makes the
+ * `DEFAULT_ADMIN_ROLE` handoff correct. `revokeRole`'s simulate reads
+ * `latest` chain state; if the preceding grant were only submitted and not
+ * yet mined, the revoke would simulate (and the contract would enforce its
+ * `LastAdmin` floor) against a world where the new admin does not exist yet,
+ * reverting a step that should succeed. Confirming first makes each step's
+ * simulate see every effect the plan already committed.
+ *
+ * This makes the executor slower than a fire-and-forget submit loop —
+ * intentionally: correctness of the ordering guarantee in
+ * {@link planInstanceRoleSplit} depends on it.
+ *
+ * **This is several transactions, not one — never atomic.** Each step is
+ * caught individually, so one failing grant or revoke does not abort the
+ * rest; inspect each {@link RoleGrantOutcome} rather than assuming
+ * all-or-nothing. A step whose transaction is submitted but mined with a
+ * reverted status is recorded as a failed outcome (`error` set, not `hash`)
+ * — a submitted-but-reverted transaction is never reported as a success. A
+ * `DEFAULT_ADMIN_ROLE` handoff that fails on the revoke half after the grant
+ * half already landed leaves the instance with TWO admins — not broken, just
+ * not yet what was asked for; re-run with only `assignment.admin` set (and
+ * `revokeFromCreator: true`) to finish it.
+ *
+ * The plan's `caller` and `airdropType` are derived from `airdrop` itself —
+ * the wallet client's default account, and a chain read of `airdropType()` —
+ * so this function's inputs stay limited to what the caller actually chooses.
+ *
+ * @param args.revokeFromCreator When `assignment.admin` is set, whether to
+ *   also revoke the creator's `DEFAULT_ADMIN_ROLE` (the default). Pass `false`
+ *   to grant the new admin only, leaving both addresses as admins — an
+ *   escape hatch for callers not yet ready to give up the creator's access.
+ * @throws {@link FeeCollectorSelfAdministeredError} or {@link InvalidArgumentError} before any
+ *   transaction — but NOT synchronously: the plan is built after an awaited
+ *   `airdropType()` read. See the three refusals on {@link planInstanceRoleSplit}.
+ * @throws {@link MissingWalletClientError} when `airdrop` has no wallet client.
+ * @throws {@link MissingAccountError} when the wallet client has no default account.
+ *
+ * @alpha
+ */
+export declare function grantInstanceRoles(args: {
+    airdrop: AirdropBaseClient;
+    assignment: InstanceRoleAssignment;
+    revokeFromCreator?: boolean;
+}): Promise<RoleGrantOutcome[]>;

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

@@ -1,77 +1,92 @@
-import type { Address } from "viem";
-import type { TokenOpsSdkError } from "../core/errors.js";
-export type { EncryptedInput, EncryptedInputs, EncryptedViewResult } from "../fhe/types.js";
+import type { Address, Hex } from "viem";
+import type { DedupMode, DeploymentMode } from "./constants.js";
 /**
- * Parameters for creating a confidential airdrop.
+ * Create-time fields shared by both variants. There is deliberately no `admin`
+ * field: the factory injects `admin = msg.sender`. Split roles after create
+ * with `grantInstanceRoles` — see `roles.ts`.
  *
- * `startTimestamp` and `endTimestamp` are unix timestamps (uint32). The SDK
- * maps them to the on-chain struct fields `startTime` / `endTime` before
- * encoding — do not pass the on-chain names directly.
+ * @alpha
  */
-export interface AirdropParams {
+export interface CommonAirdropParams {
     token: Address;
-    startTimestamp: number;
-    endTimestamp: number;
+    startTime: number;
+    endTime: number;
     canExtendClaimWindow: boolean;
-    admin: Address;
+    /**
+     * Only valid when `token` is a stock ERC7984ERC20Wrapper: `claimAndUnwrap` burns from the
+     * airdrop instance's pooled wrapper balance, so a hooked or fee-taking wrapper can deliver an
+     * amount the pool balance alone doesn't bound correctly. See {@link NonStockWrapperError}.
+     */
+    unwrappable: boolean;
+    /** Client admin AND client delegate of the compliance clone. Zero means msg.sender. */
+    complianceAdmin: Address;
 }
-/** Custom fee override for a campaign creator. */
-export interface CustomFee {
-    enabled: boolean;
-    gasFee: bigint;
+/** @alpha */
+export interface EcdsaAirdropParams {
+    common: CommonAirdropParams;
+    signer: Address;
+    dedupMode: DedupMode;
+}
+/** @alpha */
+export interface MerkleAirdropParams {
+    common: CommonAirdropParams;
+    /** Zero root is only permitted when `isMerkleRootMutable` is true. */
+    merkleRoot: Hex;
+    isMerkleRootMutable: boolean;
 }
 /**
- * Report returned by `ConfidentialAirdropFactoryClient.preflightCreateAirdrop`.
+ * Arguments shared by both `factory.createEcdsaAirdrop` / `createMerkleAirdrop` entrypoints.
  *
- * Fields:
- * - `isFactoryOperator` — `true` when the creator has approved the factory as
- *   an ERC-7984 operator on `params.token`. Only required when funding in the
- *   same transaction (`createAndFundConfidentialAirdrop` /
- *   `fundConfidentialAirdrop`).
+ * @alpha
+ */
+export interface CreateAirdropArgs<P> {
+    params: P;
+    mode: DeploymentMode;
+    userSalt: Hex;
+}
+/** @alpha */
+export interface CreateAirdropResult {
+    hash: Hex;
+    airdrop: Address;
+    complianceManager: Address;
+}
+/**
+ * One recipient's committed allocation, keyed for `CampaignEntry.merkleProof` construction.
  *
- *   **`false` does not mean "not approved" on its own** — it is also `false`
- *   when approval could not be determined at all: the token address was
- *   structurally invalid (read skipped), or the address is not an ERC-7984
- *   token (read failed). Do not render an "approve the factory" prompt off
- *   this field alone; check `blockerErrors` for
- *   `TOKENOPS_OPERATOR_NOT_APPROVED` first, which is present only when the
- *   approval genuinely is the missing step.
- * - `gasFee` — the per-claim gas fee (wei) the factory will embed into the
- *   clone for this creator: the creator's custom fee when one is enabled,
- *   otherwise `defaultGasFee`. This is the `gasFee` to use for address
- *   prediction and later `fundConfidentialAirdrop` calls.
- * - `predictedAirdrop` — deterministic CREATE2 clone address for
- *   `(params, userSalt, creator, gasFee)`. `undefined` when `userSalt` was not
- *   supplied or the params were structurally invalid.
- * - `alreadyDeployed` — `true` when bytecode already exists at
- *   `predictedAirdrop` (a repeat create with the same salt would revert).
- *   `undefined` when `predictedAirdrop` is `undefined`.
- * - `ready` — `true` when no blockers were detected.
- * - `blockers` — human-readable blocker descriptions. Empty when
- *   `ready === true`.
- * - `blockerErrors` — the same blockers as typed `TokenOpsSdkError`s, index-
- *   aligned with `blockers`. Branch on `error.code` to render UI.
+ * @alpha
  */
-export interface CreateAirdropPreflightReport {
-    /**
-     * `true` when the creator has approved the factory as operator on
-     * `params.token`. `false` also covers "could not determine" — an invalid or
-     * non-ERC-7984 token; branch on `blockerErrors` rather than this field alone.
-     */
-    isFactoryOperator: boolean;
-    /** Per-claim gas fee (wei) the factory will embed into the clone for this creator. */
-    gasFee: bigint;
-    /** Predicted CREATE2 clone address. `undefined` without `userSalt` or with invalid params. */
-    predictedAirdrop?: Address;
-    /** `true` when bytecode already exists at `predictedAirdrop`. `undefined` when not predicted. */
-    alreadyDeployed?: boolean;
-    /** `true` when no blockers were detected — green light to submit the write. */
-    ready: boolean;
-    /** Human-readable blocker descriptions. Empty when `ready === true`. */
-    blockers: string[];
+export interface CampaignRecipient {
+    recipient: Address;
+    /** The recipient's CUMULATIVE total, not a per-drop tranche. A claim pays
+     *  `total - min(total, alreadyDelivered)`. */
+    cumulativeTotal: bigint;
+}
+/**
+ * One recipient's encrypted, proof-bearing claim input — everything `merkle.claim` needs.
+ *
+ * Carries TWO addresses because the contract keys two different things on them:
+ * `account` selects the leaf and the cumulative accounting, `boundTo` is who the
+ * coprocessor will accept as the sender. They are equal on a self-claim campaign
+ * and differ on a relayed one.
+ *
+ * @alpha
+ */
+export interface CampaignEntry {
+    /** The claim identity: whose leaf this is, whose delivered total advances, and where payout defaults. */
+    account: Address;
     /**
-     * Typed errors that would otherwise surface at write time, index-aligned
-     * with `blockers`. Empty when `ready === true`.
+     * The only address that can submit this entry. The FHE input proof is bound to
+     * `(instance, boundTo)`, so any other sender is rejected by the coprocessor —
+     * a leaf cannot be re-pointed at a different submitter without re-encrypting,
+     * which changes the handle and therefore the root.
      */
-    blockerErrors: TokenOpsSdkError[];
+    boundTo: Address;
+    handle: Hex;
+    inputProof: Hex;
+    merkleProof: readonly Hex[];
+}
+/** @alpha */
+export interface BuiltCampaign {
+    root: Hex;
+    entries: readonly CampaignEntry[];
 }