@tokenops/sdk 1.6.0 → 2.0.0-alpha.2

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

@@ -0,0 +1,608 @@
+import type { Abi, Account, Address, Hex, PublicClient, WalletClient } from "viem";
+import { type TokenOpsSdkError } from "../core/errors.js";
+import { type SdkTelemetry } from "../core/telemetry.js";
+import type { EncryptedViewResult } from "../fhe/types.js";
+import type { DeploymentMode } from "./constants.js";
+/**
+ * The minimum of a receipt log this module reads.
+ *
+ * Deliberately narrower than viem's `Log`: `receipt.logs` satisfies it, and so
+ * does a hand-built fixture, which keeps the ACL-extraction contract testable
+ * without inventing block numbers and log indices that play no part in it.
+ */
+export interface AclCandidateLog {
+    address: Address;
+    topics: readonly Hex[];
+    data: Hex;
+}
+/** Inputs for {@link extractGrantedHandle}. */
+export interface ExtractGrantedHandleArgs {
+    /** Receipt logs, unfiltered. */
+    logs: readonly AclCandidateLog[];
+    /** FHEVM ACL contract for the chain — the only address whose `Allowed` events count. */
+    aclAddress: Address;
+    /** The address the grant must name, i.e. the `FHE.allow(handle, <account>)` target. */
+    account: Address;
+    /** Optional: the contract that issued the grant, to exclude allows made by other contracts in the same tx. */
+    caller?: Address | undefined;
+    /** Method label for the thrown error. */
+    method?: string | undefined;
+    /** Transaction hash for the thrown error. */
+    txHash?: Hex | undefined;
+}
+/**
+ * Pull the encrypted handle a transaction granted to `account` out of its
+ * receipt logs.
+ *
+ * This is the module's implementation of CLAUDE.md pitfall 1, and the reason
+ * every encrypted view here is a transaction rather than a `readContract`.
+ * The tempting alternative — `simulateContract(...).result` — returns a
+ * handle that is **wrong but plausible**: an FHE op's output handle is derived
+ * from counters that advance inside the executed transaction, so the simulated
+ * value diverges from the one the executed transaction actually granted ACL
+ * on. Nothing fails at that point. The damage surfaces much later, as a
+ * `userDecrypt` rejected with "User X is not authorized to decrypt handle Y".
+ * The receipt's ACL `Allowed` event is the only source that cannot drift.
+ *
+ * **Last match wins — a defensive default, not a live requirement.** Across
+ * every entrypoint currently routed through `encryptedView`, exactly one
+ * `Allowed` event survives the `account` filter, so the choice between first
+ * and last is moot today:
+ *
+ * - `adminGetCurrentBalance` — a single `FHE.allow(balance, msg.sender)`
+ *   (`ConfidentialAirdropBase.sol:358`).
+ * - `adminDiscloseBalanceToParty` — a single `FHE.allow(balance, party)` (`:367`).
+ * - `adminBatchDiscloseBalanceToParties` — N grants, but the balance is read
+ *   once (`:377`) and the *same* handle is fanned out (`:379`), so every
+ *   candidate carries an identical value and ordering cannot matter.
+ * - `getClaimAmount` on both variants — the sibling grants target other
+ *   addresses: `FHE.allowThis` grants `address(this)` and `_grantCompliance`
+ *   grants the manager clone (`ConfidentialAirdropBase.sol:431`), leaving one
+ *   grant to the caller (`ECDSAConfidentialAirdrop.sol:166-167`,
+ *   `MerkleConfidentialAirdrop.sol:264-266`).
+ *
+ * Last-wins is therefore chosen for entrypoints that do not exist yet, over
+ * `fhe-vesting`'s throw-on-ambiguous: a future compound view that grants twice
+ * should return its final handle rather than fail, and the batch-disclosure
+ * path already shows the shape where N events legitimately carry one answer.
+ *
+ * Note what is NOT a motivating case: the Merkle `claim` path does grant an
+ * intermediate handle before the outstanding one, but `claim` /
+ * `claimAndUnwrap` return void (`IMerkleConfidentialAirdrop.sol:51-70`), so
+ * they run as plain writes and their receipts never reach this function.
+ *
+ * @throws {@link ReceiptEventNotFoundError} when no `Allowed` event names `account`.
+ */
+export declare function extractGrantedHandle(args: ExtractGrantedHandleArgs): Hex;
+/** @alpha */
+export interface AirdropBaseClientConfig {
+    publicClient: PublicClient;
+    walletClient?: WalletClient | undefined;
+    /** The airdrop instance — a factory-deployed clone or UUPS proxy, never the implementation. */
+    address: Address;
+    /**
+     * Chain id used for the support check and the ACL lookup. Defaults to
+     * `publicClient.chain?.id`; one of the two must resolve, because the client
+     * refuses to talk to a chain it cannot name.
+     */
+    chainId?: number | undefined;
+    /**
+     * FHEVM ACL contract address override. Resolved from the chain id via the
+     * SDK's registry when omitted. Required because every encrypted view reads
+     * the granted handle out of this contract's `Allowed` events — pointing it
+     * at the wrong address does not fail loudly, it returns nothing to parse.
+     */
+    aclAddress?: Address | undefined;
+    /**
+     * Optional telemetry sink. When provided, the SDK emits a
+     * `fhe-airdrop.client.init` event on construction and brackets public write
+     * methods with named spans (`fhe-airdrop.airdrop.pause`, …). Defaults to a
+     * no-op — zero overhead, zero leakage of consumer-side identifiers.
+     *
+     * Spans carry the method name and the instance address only. Encrypted
+     * handles may appear; decrypted amounts never do.
+     */
+    telemetry?: SdkTelemetry | undefined;
+}
+/**
+ * Wiring a subclass supplies to the base constructor. Not part of the
+ * consumer-facing config: an application never chooses these, a variant client
+ * always does.
+ */
+export interface AirdropClientInternals {
+    /**
+     * The variant's full ABI — a superset of `confidentialAirdropBaseAbi`. Used for every
+     * read, write, preflight and revert decode, so passing the variant ABI is
+     * what lets an inherited helper carry a variant-only revert (e.g.
+     * `InvalidMerkleProof`) through to its typed error.
+     */
+    abi?: Abi | undefined;
+    /** Telemetry span namespace segment, e.g. `"ecdsa"` for `fhe-airdrop.ecdsa.pause`. */
+    surface?: string | undefined;
+}
+/**
+ * Who sends the transaction, when it should not be the wallet client's own account.
+ *
+ * @alpha
+ */
+export interface WriteAccountOverride {
+    account?: Account | Address | undefined;
+}
+/**
+ * The surface every airdrop v2 instance shares, regardless of how it
+ * authorises a claim.
+ *
+ * `ConfidentialAirdropBase` is the abstract half of both deployed variants, so
+ * this class is usable directly against any instance address whose variant you
+ * do not care about (an admin panel listing campaigns, say). The ECDSA and
+ * Merkle clients extend it and add their own claim path.
+ *
+ * What it encapsulates beyond the raw ABI is the encrypted-view protocol: five
+ * of the contract's disclosure entrypoints look like getters and are not —
+ * they mutate ACL state, so they are transactions, and their result must be
+ * recovered from the receipt. See {@link extractGrantedHandle}.
+ *
+ * @example
+ * const airdrop = new AirdropBaseClient({ publicClient, walletClient, address });
+ * const { handle } = await airdrop.adminGetCurrentBalance();
+ * // `handle` is now decryptable by the caller via the Zama relayer.
+ *
+ * @alpha
+ */
+export declare class AirdropBaseClient {
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient | undefined;
+    readonly address: Address;
+    readonly chainId: number;
+    readonly aclAddress: Address;
+    /** The ABI every inherited helper uses. Subclasses pass their variant's. */
+    protected readonly abi: Abi;
+    /** Telemetry span namespace, e.g. `fhe-airdrop.airdrop`. */
+    protected readonly spanPrefix: string;
+    protected readonly telemetry?: SdkTelemetry | undefined;
+    constructor(config: AirdropBaseClientConfig, internals?: AirdropClientInternals);
+    /**
+     * Halt claiming. Requires `PAUSER_ROLE`.
+     *
+     * Pausing does not stop the clock: `endTime` still passes while paused, so a
+     * long pause can consume the window outright. Pair it with
+     * {@link extendClaimWindow} when the campaign is meant to survive.
+     *
+     * @returns The transaction hash.
+     */
+    pause(args?: WriteAccountOverride): Promise<Hex>;
+    /**
+     * Resume claiming. Requires `PAUSER_ROLE`.
+     *
+     * @returns The transaction hash.
+     */
+    unpause(args?: WriteAccountOverride): Promise<Hex>;
+    /**
+     * Move the campaign's end time forward. Requires `WINDOW_ADMIN_ROLE`.
+     *
+     * Forward-only, and only on an instance created with
+     * `canExtendClaimWindow: true` — otherwise the contract reverts
+     * `ExtensionNotAllowed`, which the SDK surfaces as `FeatureDisabledError`.
+     *
+     * @param args.newEndTime Unix seconds, `uint32` on-chain; must exceed the current `endTime`.
+     * @returns The transaction hash.
+     */
+    extendClaimWindow(args: {
+        newEndTime: number;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Sweep the instance's entire remaining confidential balance to `recipient`.
+     * Requires `TREASURY_ROLE`.
+     *
+     * The amount is not a parameter and never appears in plaintext anywhere:
+     * the contract reads its own encrypted balance and moves all of it.
+     *
+     * @returns The transaction hash.
+     */
+    withdrawConfidential(args: {
+        recipient: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Withdraw accrued claim-fee ETH. Requires `FEE_COLLECTOR_ROLE`.
+     *
+     * @param args.amount Wei. Exceeding the accrued balance reverts `InsufficientFeeBalance`
+     *   (surfaced as `InsufficientBalanceError`) — this is public ETH, not a confidential quantity.
+     * @returns The transaction hash.
+     */
+    withdrawGasFee(args: {
+        recipient: Address;
+        amount: bigint;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Sweep a plain ERC-20 that was sent to the instance by mistake. Requires
+     * `RESCUER_ROLE`.
+     *
+     * The campaign's own token is ERC-7984, not ERC-20, so it cannot be reached
+     * through this path — use {@link withdrawConfidential} for the pool.
+     *
+     * @returns The transaction hash.
+     */
+    rescueERC20(args: {
+        token: Address;
+        recipient: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Sweep a *different* ERC-7984 token that was sent to the instance by
+     * mistake. Requires `RESCUER_ROLE`.
+     *
+     * Passing the campaign's own token reverts `CannotRescueAirdropToken` — the
+     * guard that stops a rescuer draining the pool without `TREASURY_ROLE`.
+     *
+     * @returns The transaction hash.
+     */
+    rescueOtherConfidentialToken(args: {
+        token: Address;
+        recipient: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /** The ERC-7984 token this campaign distributes. */
+    token(): Promise<Address>;
+    /**
+     * The variant ordinal: `0` = ECDSA, `1` = Merkle (contract enum
+     * `AirdropType`). Read it to pick which variant client to construct against
+     * an address you were handed rather than created.
+     */
+    airdropType(): Promise<number>;
+    /** Claim-window open, Unix seconds. */
+    startTime(): Promise<number>;
+    /** Claim-window close, Unix seconds. Movable forward via {@link extendClaimWindow}. */
+    endTime(): Promise<number>;
+    /** Whether claimants may unwrap to the underlying ERC-20 as part of a claim. */
+    unwrappable(): Promise<boolean>;
+    /** The instance's own compliance-manager clone — the only contract granted ACL on campaign handles. */
+    complianceManager(): Promise<Address>;
+    /** Per-claim ETH fee in wei; `0` on a fee-free campaign. */
+    gasFee(): Promise<bigint>;
+    /**
+     * Whether a claim would be accepted right now — in window **and** not
+     * paused. Distinct from `hasClaimStarted() && !hasClaimEnded()`, which
+     * ignores the pause flag.
+     */
+    isClaimWindowActive(): Promise<boolean>;
+    /** Whether `startTime` has passed. Says nothing about the pause flag. */
+    hasClaimStarted(): Promise<boolean>;
+    /** Whether `endTime` has passed. Says nothing about the pause flag. */
+    hasClaimEnded(): Promise<boolean>;
+    /**
+     * Whether claiming is currently halted (`PausableUpgradeable.paused()`).
+     * Independent of the claim window — see {@link isClaimWindowActive}, which
+     * ANDs this together with the window check.
+     */
+    paused(): Promise<boolean>;
+    /** Gates {@link pause} / {@link unpause}. */
+    PAUSER_ROLE(): Promise<Hex>;
+    /** Gates {@link extendClaimWindow}. */
+    WINDOW_ADMIN_ROLE(): Promise<Hex>;
+    /** Gates {@link withdrawConfidential}. */
+    TREASURY_ROLE(): Promise<Hex>;
+    /** Gates {@link rescueERC20} / {@link rescueOtherConfidentialToken}. */
+    RESCUER_ROLE(): Promise<Hex>;
+    /** Gates {@link withdrawGasFee}. The contract refuses to leave it empty on a fee-charging campaign. */
+    FEE_COLLECTOR_ROLE(): Promise<Hex>;
+    /** Gates `upgradeToAndCall` on UUPS instances; inert on clones. */
+    UPGRADER_ROLE(): Promise<Hex>;
+    /** Gates the admin disclosure surface, and bypasses gate #1 of the raw-handle disclosure path. */
+    DISCLOSURE_ADMIN_ROLE(): Promise<Hex>;
+    /**
+     * OpenZeppelin's root role (`bytes32(0)`), read from the instance rather
+     * than hard-coded so a re-parented hierarchy shows up here instead of
+     * silently diverging.
+     *
+     * It administers every role on this instance except `FEE_COLLECTOR_ROLE`,
+     * which administers itself - see {@link getRoleAdmin}.
+     */
+    DEFAULT_ADMIN_ROLE(): Promise<Hex>;
+    /**
+     * The role whose holders may {@link grantRole} and {@link revokeRole} `role`.
+     *
+     * `DEFAULT_ADMIN_ROLE` for everything the instance sets up at `initialize`,
+     * except `FEE_COLLECTOR_ROLE`, which the contract re-parents to itself: only
+     * a current fee collector can add or remove another. That is why
+     * `planInstanceRoleSplit` (`./roles.js`) refuses to plan a fee-collector
+     * grant from an admin key - this read is how a caller confirms it.
+     */
+    getRoleAdmin(role: Hex): Promise<Hex>;
+    /**
+     * Whether `holder` holds `role`.
+     *
+     * The role subject is called `holder`, not `account`, across all three role
+     * methods: on the two writes `account` already means "who sends this
+     * transaction" ({@link WriteAccountOverride}), and one key cannot be both —
+     * a grant made by an admin to somebody else is the normal case, not the
+     * exception.
+     *
+     * @param args.role A `bytes32` from one of the role getters above — not a hand-hashed string.
+     */
+    hasRole(args: {
+        role: Hex;
+        holder: Address;
+    }): Promise<boolean>;
+    /**
+     * Grant `role` to `holder`. Requires the role's admin role
+     * (`DEFAULT_ADMIN_ROLE` unless the instance re-parented it).
+     *
+     * @returns The transaction hash.
+     */
+    grantRole(args: {
+        role: Hex;
+        holder: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Revoke `role` from `holder`. Requires the role's admin role.
+     *
+     * Two revocations are blocked on-chain rather than silently allowed:
+     * removing the last `DEFAULT_ADMIN_ROLE` member (`LastAdmin`) or the last
+     * `FEE_COLLECTOR_ROLE` member of a fee-charging campaign
+     * (`LastFeeCollector`). Both would strand the instance.
+     *
+     * @returns The transaction hash.
+     */
+    revokeRole(args: {
+        role: Hex;
+        holder: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Give up `role` yourself.
+     *
+     * The contract's signature is `renounceRole(role, callerConfirmation)` and
+     * it reverts `AccessControlBadConfirmation` unless `callerConfirmation` is
+     * the sender. This method therefore takes no holder at all and fills the
+     * confirmation from the resolved sending account: renouncing on somebody
+     * else's behalf is not a call that can succeed, so the SDK does not offer a
+     * shape that lets a caller try. To remove a role from another account, use
+     * {@link revokeRole}.
+     *
+     * Renouncing runs through the same `_revokeRole` floors as
+     * {@link revokeRole}, so it is **not** an escape hatch from them. In
+     * particular `DEFAULT_ADMIN_ROLE`'s floor is unconditional: the sole
+     * remaining admin cannot renounce (`LastAdmin`), because an instance with no
+     * admin has no role administrator left to re-grant one. The
+     * renounce-admin-to-freeze-the-instance pattern is deliberately unavailable
+     * here - grant a successor first, then have the predecessor renounce or be
+     * revoked.
+     *
+     * @param args.role A `bytes32` from one of the role getters above.
+     * @returns The transaction hash.
+     */
+    renounceRole(args: {
+        role: Hex;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * How many accounts hold `role`.
+     *
+     * Cheap enough to poll, and the value the contract's own floors are written
+     * against: a revoke of `DEFAULT_ADMIN_ROLE` at count 1 reverts `LastAdmin`,
+     * and of `FEE_COLLECTOR_ROLE` at count 1 on a fee-charging campaign reverts
+     * `LastFeeCollector`.
+     */
+    getRoleMemberCount(role: Hex): Promise<bigint>;
+    /**
+     * The `index`-th holder of `role`, in the contract's own enumeration order.
+     *
+     * Ordering is `EnumerableSet`'s and is not stable across grants and
+     * revokes - index into it only alongside a
+     * {@link getRoleMemberCount} read taken at the same block, or prefer
+     * {@link getRoleMembers}, which returns the whole set in one call.
+     */
+    getRoleMember(args: {
+        role: Hex;
+        index: bigint;
+    }): Promise<Address>;
+    /**
+     * Every account currently holding `role`.
+     *
+     * This is how the campaign's fee collectors are meant to be discovered: the
+     * contract deliberately ships no `feeCollectors()` view and points callers
+     * at `getRoleMembers(FEE_COLLECTOR_ROLE)` instead, so this read is the
+     * supported answer to "who can withdraw this campaign's accrued claim ETH?"
+     * - the membership the `LastFeeCollector` floor exists to keep non-empty.
+     *
+     * One `eth_call` and unpaginated: role sets on an airdrop instance are
+     * operator-sized, not user-sized.
+     */
+    getRoleMembers(role: Hex): Promise<readonly Address[]>;
+    /**
+     * Point this instance's proxy at `newImplementation`, optionally calling
+     * into it in the same transaction. Requires `UPGRADER_ROLE`
+     * (`_authorizeUpgrade` is `onlyRole(UPGRADER_ROLE)`).
+     *
+     * **Inert on clone-mode instances.** A clone has no ERC-1967 implementation
+     * slot to rewrite; the call reverts at the proxy layer rather than doing
+     * anything partial. Call {@link deploymentMode}, or remember the create-time
+     * `mode`, before offering this in a UI. Do NOT reach for
+     * {@link proxiableUUID} - it reverts on clone and UUPS instances alike and
+     * cannot tell them apart.
+     *
+     * **Merkle campaigns cannot reach this at all through the SDK**, because the
+     * SDK refuses to create one in `uups` mode in the first place - see
+     * {@link MerkleUupsUnsupportedError} for the storage-retype reason.
+     *
+     * @param args.data Initializer calldata to run against the new
+     *   implementation, or `"0x"` (the default) for a plain implementation
+     *   swap. A non-empty payload runs with `delegatecall` semantics - it is the
+     *   new implementation's code executing against this instance's storage.
+     * @param args.value Wei to attach. The function is `payable`, but the
+     *   ERC-1967 upgrade path reverts `ERC1967NonPayable` when value is sent
+     *   with empty `data`, so leave it unset for a plain swap.
+     * @returns The transaction hash.
+     */
+    upgradeToAndCall(args: {
+        newImplementation: Address;
+        data?: Hex;
+        value?: bigint;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * The ERC-1822 storage slot this implementation expects a proxy to keep its
+     * implementation address in.
+     *
+     * Succeeds **only when called on the implementation contract directly**,
+     * answering `0x360894...bbc`, and **reverts** `UUPSUnauthorizedCallContext`
+     * through any proxy: OpenZeppelin guards it with `notDelegated`, which
+     * rejects every delegatecall context. That is what makes it a target
+     * implementation's proof of UUPS compliance, not a probe of a live instance.
+     *
+     * **Not a mode discriminator.** This client is always pointed at an
+     * instance, so this call reverts here for `clone` and `uups` alike. Use
+     * {@link deploymentMode} to tell them apart.
+     */
+    proxiableUUID(): Promise<Hex>;
+    /** OpenZeppelin's upgrade-interface version string, e.g. `"5.0.0"`. */
+    upgradeInterfaceVersion(): Promise<string>;
+    /**
+     * Which deployment shell this instance is: a minimal-proxy `clone`, or a
+     * `uups` ERC-1967 proxy that {@link upgradeToAndCall} can actually move.
+     *
+     * Read from the ERC-1967 implementation slot, which a UUPS proxy populates
+     * and a clone never has - a clone's implementation is baked into its runtime
+     * code. One `eth_getStorageAt`, no ABI involved.
+     *
+     * Neither obvious probe works in its place, which is why this exists:
+     * {@link proxiableUUID} carries OpenZeppelin's `notDelegated` guard and so
+     * reverts on both shells when called at an instance address, and
+     * {@link upgradeInterfaceVersion} reads `UPGRADE_INTERFACE_VERSION`, an
+     * implementation constant that answers `"5.0.0"` for both.
+     *
+     * @alpha
+     */
+    deploymentMode(): Promise<DeploymentMode>;
+    /**
+     * Read the instance's own remaining pool balance as a handle the **caller**
+     * can decrypt. Requires `DISCLOSURE_ADMIN_ROLE`.
+     *
+     * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`.
+     * @throws {@link ReceiptEventNotFoundError} when the transaction granted no ACL to the caller.
+     */
+    adminGetCurrentBalance(args?: WriteAccountOverride): Promise<EncryptedViewResult>;
+    /**
+     * Disclose the instance's pool balance to `party`. Requires
+     * `DISCLOSURE_ADMIN_ROLE`.
+     *
+     * The ACL grant goes to `party`, **not** to the caller, so the returned
+     * handle is extracted from the grant naming `party` — and unless the caller
+     * is also `party`, the caller cannot decrypt what it just disclosed.
+     *
+     * @returns `{ handle, hash }` — the handle `party` may now decrypt.
+     */
+    adminDiscloseBalanceToParty(args: {
+        party: Address;
+    } & WriteAccountOverride): Promise<EncryptedViewResult>;
+    /**
+     * Disclose the instance's pool balance to several parties in one
+     * transaction. Requires `DISCLOSURE_ADMIN_ROLE`.
+     *
+     * The contract reads the balance once and fans the *same* handle out to
+     * every party, which is why one handle is returned for the whole batch. It
+     * is recovered from the grant naming the first party.
+     *
+     * The contract's own two argument checks, `EmptyBatch` and `InvalidParty`
+     * (a zero address anywhere in the list), are mirrored client-side and
+     * thrown before the transaction is sent. Both are decidable off-chain from
+     * the argument alone, and both are easy to hit from a UI that maps a form
+     * over rows; paying gas to be told so adds nothing. Nothing beyond those two
+     * is checked here: duplicates, for instance, are wasteful but legal
+     * on-chain, and the SDK does not invent rules the contract does not have.
+     *
+     * @returns `{ handle, hash }` — the single handle every party may now decrypt.
+     * @throws {@link InvalidArgumentError} on an empty list or a zero-address party.
+     */
+    adminBatchDiscloseBalanceToParties(args: {
+        parties: readonly Address[];
+    } & WriteAccountOverride): Promise<EncryptedViewResult>;
+    /**
+     * Grant `party` decrypt access to a handle you already hold.
+     *
+     * Two gates apply on-chain: the caller must itself be allowed on the handle
+     * (bypassed by `DISCLOSURE_ADMIN_ROLE`), and the *instance* must be allowed
+     * on it — so an arbitrary handle from another contract cannot be laundered
+     * through this campaign. A failure of the first surfaces as
+     * `FheHandleNotAllowedError`.
+     *
+     * @param args.handle An existing `euint64` handle — a public pointer, not a value.
+     * @returns The transaction hash. No new handle is produced.
+     */
+    discloseHandleToParty(args: {
+        handle: Hex;
+        party: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Grant `party` decrypt access to several handles at once. Same two gates as
+     * {@link discloseHandleToParty}, applied per handle; the first failure
+     * reverts the batch and names the offending handle.
+     *
+     * @returns The transaction hash. No new handles are produced.
+     */
+    batchDiscloseHandlesToParty(args: {
+        handles: readonly Hex[];
+        party: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Submit a transaction for a function that returns an encrypted handle via
+     * `FHE.allow`, and recover that handle from the receipt.
+     *
+     * Subclasses call this for their claim-preview entrypoints (`getClaimAmount`
+     * on both variants). Simulating instead would return a handle with no ACL
+     * behind it — see {@link extractGrantedHandle} for why.
+     *
+     * @param input.grantee The address the contract grants ACL to. Defaults to
+     *   the sender, which is right for every `msg.sender` grant; disclosure
+     *   entrypoints that grant a third party must pass it explicitly.
+     * @param input.method Label for telemetry and errors. Defaults to `functionName`.
+     * @returns `{ handle, hash }`.
+     */
+    protected encryptedView(input: {
+        functionName: string;
+        args?: readonly unknown[] | undefined;
+        grantee?: Address | undefined;
+        account?: Account | Address | undefined;
+        method?: string | undefined;
+        /** Wei to attach — for fee-charging entrypoints that also return a handle. */
+        value?: bigint | undefined;
+    }): Promise<EncryptedViewResult>;
+    /**
+     * Send a transaction against the instance, mapping any revert to a typed
+     * error. Preflighted first so the revert is decoded before the user pays.
+     */
+    protected write(functionName: string, args?: readonly unknown[], account?: Account | Address, method?: string, value?: bigint): Promise<Hex>;
+    protected read<T = unknown>(functionName: string, args?: readonly unknown[]): Promise<T>;
+    /**
+     * Simulate a write purely to surface typed reverts.
+     *
+     * The simulate's return value is discarded on principle: FHE handles
+     * produced during simulation diverge from the executed transaction's, so the
+     * only trustworthy source for a result is the receipt. What simulation is
+     * good for is letting viem decode a revert against the ABI first.
+     */
+    protected preflightWrite(method: string, functionName: string, args: readonly unknown[], account: Account | Address, value?: bigint): Promise<void>;
+    /**
+     * Map a viem error to the SDK's typed palette.
+     *
+     * `productContext` deliberately carries only public identifiers — the
+     * caller, the chain. Never an amount: the whole point of this module is that
+     * amounts are ciphertext, and an error object is one of the easiest places
+     * for a plaintext to escape into a log.
+     */
+    protected mapRevert(method: string, err: unknown, account: Account | Address): TokenOpsSdkError;
+    protected requireWallet(method: string): WalletClient;
+    protected resolveAccount(wallet: WalletClient, override: Account | Address | undefined, method: string): Account | Address;
+    /**
+     * The address that will actually send the transaction, as a plain `Address`.
+     *
+     * Needed by any method whose arguments must be validated against the sender before
+     * the write — on the Merkle variant the claim identity, the payout destination and
+     * the submitter are three separate addresses with rules between them.
+     */
+    protected resolveSender(override: Account | Address | undefined, method: string): Address;
+}
+/**
+ * Create an {@link AirdropBaseClient}. Mirrors viem's `create*` convention.
+ *
+ * @example
+ * const airdrop = createAirdropBaseClient({ publicClient, walletClient, address });
+ *
+ * @alpha
+ */
+export declare function createAirdropBaseClient(config: AirdropBaseClientConfig): AirdropBaseClient;