@tokenops/sdk 1.6.0 → 2.0.0-alpha.1

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

@@ -0,0 +1,297 @@
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "./airdrop-base.js";
+import { type EncryptorSource } from "./encryption.js";
+import type { ConfidentialAirdropFactoryClient } from "./factory.js";
+import type { MerkleAirdropClient } from "./merkle.js";
+import { type MerkleLeafInput } from "./merkle-tree.js";
+import type { DeploymentMode } from "./constants.js";
+import type { BuiltCampaign, CampaignRecipient, MerkleAirdropParams } from "./types.js";
+export type { BuiltCampaign, CampaignEntry, CampaignRecipient } from "./types.js";
+/**
+ * Reject the campaign shapes that produce an unusable or misleading tree,
+ * before any encryption work is done.
+ *
+ * Five rules, each of which is silent rather than loud if left unchecked:
+ *
+ * - **Well-formed address.** A malformed one would otherwise escape as a raw
+ *   viem `InvalidAddressError` out of the zero-address check below - an
+ *   untyped throw from the function whose job is producing typed ones.
+ * - **No duplicate recipient.** `claimedAmount` is a cumulative running total
+ *   keyed by account alone (`ConfidentialAirdropMerkleStorage`), and a claim
+ *   pays `total - min(total, claimed)`. Two leaves for one account under one
+ *   root therefore pay `max(totalA, totalB)`, in either claim order — never
+ *   the sum the author almost certainly intended.
+ * - **No zero address.** A zero-address leaf is unclaimable and silently
+ *   burns its share of the pool.
+ * - **`uint64` range.** The contract's `euint64` arithmetic cannot represent
+ *   anything else; a wider total would be rejected far downstream, at
+ *   encryption time.
+ * - **Non-empty.** An empty tree has no root to publish.
+ *
+ * @param recipients The campaign roster to check.
+ * @throws {@link InvalidArgumentError} on any of the five. The thrown error
+ *   never carries a `cumulativeTotal`: the totals are the confidential part of
+ *   a confidential airdrop, so they are named by index, never by value.
+ *
+ * @alpha
+ */
+export declare function validateCampaignRecipients(recipients: readonly CampaignRecipient[]): void;
+/**
+ * Real implementation behind {@link validateCampaignRecipients}, parameterised
+ * on the function name a thrown {@link InvalidArgumentError} blames.
+ *
+ * Not part of the public surface - exported from this module only so the
+ * orchestrators can attribute a roster failure to themselves rather than to a
+ * validator the caller never invoked. Neither barrel re-exports it. Same
+ * pattern as `buildMerkleTreeInternal` in `./merkle-tree.js`.
+ */
+export declare function validateCampaignRecipientsInternal(recipients: readonly CampaignRecipient[], method: string): void;
+/**
+ * Inputs for {@link buildMerkleCampaign}.
+ *
+ * @alpha
+ */
+export interface BuildMerkleCampaignArgs {
+    /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
+    instance: Address;
+    recipients: readonly CampaignRecipient[];
+    encryptor: EncryptorSource;
+}
+/**
+ * One recipient's encrypted allocation, ready to be fed to {@link buildMerkleTree}.
+ *
+ * @alpha
+ */
+export interface EncryptedCampaignLeaf extends MerkleLeafInput {
+    /** The KMS input proof binding `handle` to `(instance, recipient)`. Required at claim time, unused by the tree. */
+    inputProof: Hex;
+}
+/**
+ * Inputs for {@link encryptCampaignAmounts}.
+ *
+ * @alpha
+ */
+export interface EncryptCampaignAmountsArgs {
+    /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
+    instance: Address;
+    recipients: readonly CampaignRecipient[];
+    encryptor: EncryptorSource;
+}
+/**
+ * Encrypt a plaintext roster into per-recipient handles, without building a tree.
+ *
+ * Use this when you want the two stages apart — to persist the handles before
+ * publishing a root, or to hand them to something else that builds the tree.
+ * If you just want a campaign, {@link buildMerkleCampaign} does both.
+ *
+ * **One relayer request per recipient, issued concurrently.** Each input binds
+ * to `(instance, that recipient)`, so they cannot share a proof: a single
+ * batched proof binds every value to one account and produces a campaign only
+ * that account can claim against.
+ *
+ * **The output is not reproducible.** Encryption is randomised, so calling this
+ * twice with the same roster yields different handles and therefore a different
+ * root. Persist what you get back; you cannot regenerate it.
+ *
+ * @param args The live instance, the roster, and an eager or lazy encryptor.
+ * @returns One `{ recipient, handle, inputProof }` per roster entry, in roster order.
+ * @throws {@link InvalidArgumentError} on any roster problem {@link validateCampaignRecipients} rejects, or a zero `instance`.
+ * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
+ *
+ * @example
+ * const leaves = await encryptCampaignAmounts({ instance: airdrop, recipients, encryptor });
+ * const { root, entries } = buildMerkleTree({ instance: airdrop, leaves });
+ *
+ * @alpha
+ */
+export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs): Promise<readonly EncryptedCampaignLeaf[]>;
+/**
+ * Encrypt every recipient's cumulative total against their own address, then
+ * build the tree those ciphertexts belong to.
+ *
+ * Use this on the **mutable-root** path: the instance already exists, so its
+ * address is known and encryption can bind to it directly. Publish the returned
+ * `root` with {@link MerkleAirdropClient.setMerkleRoot} — or let
+ * {@link rotateMerkleRoot} do both in one call. For an instance whose root is
+ * fixed at create time, use {@link planMerkleCampaign} instead: this function
+ * cannot help you, because there is no address to encrypt against yet.
+ *
+ * **Distribution is yours.** The returned `entries` are the campaign — nothing
+ * about them is recoverable from the chain. The instance stores only the
+ * 32-byte root; there is no getter that maps an account to its handle, its
+ * input proof, or its Merkle branch, and no event that emits them. A recipient
+ * who does not hold their own `(handle, inputProof, merkleProof)` triple cannot
+ * claim, and no amount of on-chain data will reconstruct it. Persist the
+ * entries when this resolves and serve each recipient theirs.
+ *
+ * **One relayer request per recipient, issued concurrently.** Each input has a
+ * different `userAddress`, so they cannot share a proof — see the note on
+ * `encryptUint64Batch` below. Large rosters fan out correspondingly; chunk the
+ * roster yourself if your relayer rate-limits.
+ *
+ * **Already hold the handles?** This function encrypts unconditionally, and
+ * encryption is randomised — so re-encrypting handles that exist elsewhere
+ * produces a tree committing to handles nobody holds. Use
+ * {@link buildMerkleTree} directly instead.
+ *
+ * @param args The live instance, the roster, and an eager or lazy encryptor.
+ * @returns The root to publish and one proof-bearing {@link CampaignEntry} per recipient, in roster order.
+ * @throws {@link InvalidArgumentError} on any roster problem {@link validateCampaignRecipients} rejects, or a zero `instance`.
+ * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
+ *
+ * @example
+ * const { root, entries } = await buildMerkleCampaign({
+ *   instance: airdrop.address,
+ *   recipients: [{ recipient: alice, cumulativeTotal: 1_000_000n }],
+ *   encryptor,
+ * });
+ * await airdrop.setMerkleRoot({ newRoot: root });
+ * // then hand `entries[i]` to `entries[i].recipient`, out of band
+ *
+ * @alpha
+ */
+export declare function buildMerkleCampaign({ instance, recipients, encryptor, }: BuildMerkleCampaignArgs): Promise<BuiltCampaign>;
+/**
+ * Inputs for {@link planMerkleCampaign}.
+ *
+ * @alpha
+ */
+export interface PlanMerkleCampaignArgs {
+    factory: ConfidentialAirdropFactoryClient;
+    /** The exact params the subsequent `createMerkleAirdrop` will use, except `merkleRoot` — supply the planned root there. */
+    params: MerkleAirdropParams;
+    mode: DeploymentMode;
+    /** The account that will send `createMerkleAirdrop`. CREATE2 salts are per-deployer. */
+    creator: Address;
+    userSalt: Hex;
+    recipients: readonly CampaignRecipient[];
+    encryptor: EncryptorSource;
+}
+/**
+ * A campaign built against a not-yet-deployed instance, plus the evidence needed to trust the prediction.
+ *
+ * @alpha
+ */
+export interface PlannedCampaign extends BuiltCampaign {
+    /** Where `createMerkleAirdrop({ mode, userSalt })` from `creator` will land. Every entry is bound to this address. */
+    predictedAddress: Address;
+    /** The factory's Merkle init-code hash read BEFORE the address was predicted. */
+    initCodeHashBefore: Hex;
+    /** The same hash read AFTER. Always equal to `initCodeHashBefore` on a returned plan - a difference throws instead. */
+    initCodeHashAfter: Hex;
+}
+/**
+ * Build a campaign for an instance that does not exist yet, so its root can be
+ * baked in at create time.
+ *
+ * This is the **immutable-root** path, and it exists because that path is
+ * otherwise circular: the root must be known before `createMerkleAirdrop`, the
+ * root depends on every recipient's ciphertext, and every ciphertext is bound
+ * to the instance address `createMerkleAirdrop` has not produced yet. The
+ * factory's `predictMerkleAirdropAddress` oracle breaks it — encryption binds
+ * to the predicted address, and the create call then lands exactly there.
+ *
+ * **Passing the planned root back in `params` is safe.** A predicted address
+ * commits only to `(implementation, mode, deployer, userSalt)`; the params
+ * struct is accepted by the oracle and ignored
+ * (`predictECDSAAirdropAddress` does not even name its params argument). So
+ * calling this with a placeholder root and then creating with the real one does
+ * not move the address. The corollary is the trap: two campaigns sharing a
+ * `(variant, mode, creator, userSalt)` tuple predict the SAME address however
+ * different their params — pick a fresh `userSalt` per campaign.
+ *
+ * **Drift is judged, the rest is not.** The factory's Merkle init-code hash is
+ * read once BEFORE `predictMerkleAirdropAddress` and once AFTER the campaign
+ * is built, so the window brackets the prediction itself as well as the
+ * build — an implementation-pointer swap landing in either gap is caught. A
+ * difference between the two means the factory's Merkle implementation
+ * pointer moved and `predictedAddress` is stale: every entry would be bound
+ * to an address the create will not produce, so this function throws
+ * {@link PredictionDriftError} rather than hand back a campaign that cannot
+ * be claimed. Both observations are still returned on the success path, for
+ * callers that want to record them. What it does NOT check is whether
+ * `creator` may deploy `mode` and whether the salt is free - run
+ * `preflightCreate` (`./guards.js`) for those, or let `createMerkleAirdrop`
+ * enforce them at send time.
+ *
+ * **Distribution is yours** — same as {@link buildMerkleCampaign}: the chain
+ * keeps only the root, so each recipient must be handed their own
+ * `(handle, inputProof, merkleProof)` out of band or they cannot claim.
+ *
+ * @param args The factory client, the create arguments the campaign is planned against, the roster and an encryptor.
+ * @returns The built campaign, the predicted instance address, and the two init-code-hash observations.
+ * @throws {@link InvalidArgumentError} on any roster problem {@link validateCampaignRecipients} rejects.
+ * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
+ * @throws {@link PredictionDriftError} when the factory's Merkle implementation pointer moved mid-build.
+ *
+ * @example
+ * const plan = await planMerkleCampaign({
+ *   factory, params, mode: "clone", creator, userSalt, recipients, encryptor,
+ * });
+ * await factory.createMerkleAirdrop({
+ *   params: { ...params, merkleRoot: plan.root, isMerkleRootMutable: false },
+ *   mode: "clone",
+ *   userSalt,
+ * });
+ *
+ * @alpha
+ */
+export declare function planMerkleCampaign({ factory, params, mode, creator, userSalt, recipients, encryptor, }: PlanMerkleCampaignArgs): Promise<PlannedCampaign>;
+/**
+ * Inputs for {@link rotateMerkleRoot}.
+ *
+ * @alpha
+ */
+export interface RotateMerkleRootArgs extends WriteAccountOverride {
+    /** The live instance. Its `address` is read off the client — nothing is predicted here. */
+    airdrop: MerkleAirdropClient;
+    /** The FULL updated roster: cumulative totals, not the deltas since the last root. */
+    recipients: readonly CampaignRecipient[];
+    encryptor: EncryptorSource;
+}
+/**
+ * A rebuilt campaign together with the transaction that published its root.
+ *
+ * @alpha
+ */
+export interface RotatedCampaign extends BuiltCampaign {
+    /** The `setMerkleRoot` transaction hash. */
+    hash: Hex;
+}
+/**
+ * Republish a campaign with updated cumulative totals: rebuild every entry
+ * against the live instance, then set the new root.
+ *
+ * **A rotation is a top-up, not a second payout.** `claimedAmount` survives the
+ * rotation, and a claim against the new root pays
+ * `newTotal - min(newTotal, alreadyDelivered)` — so `recipients` must carry
+ * each account's new CUMULATIVE total, never the increment. Passing increments
+ * pays out the increment minus everything already delivered, which for most
+ * rosters is encrypted zero. A total lower than what an account already
+ * received pays nothing; a rotation cannot claw back.
+ *
+ * Every entry is re-encrypted because the tree commits to handles, and a new
+ * total is a new ciphertext. Entries from the previous root do not survive:
+ * once the root moves, the old proofs no longer verify. **Distribute the new
+ * entries to every recipient**, including the ones whose total was unchanged —
+ * the chain stores only the root, so an un-updated recipient is simply stuck.
+ *
+ * Requires `MERKLE_ADMIN_ROLE` on the instance and an instance created with
+ * `isMerkleRootMutable: true`.
+ *
+ * @param args The live client, the full updated roster, an encryptor and an optional sending account.
+ * @returns The new root, the rebuilt entries, and the `setMerkleRoot` transaction hash.
+ * @throws {@link InvalidArgumentError} on any roster problem {@link validateCampaignRecipients} rejects.
+ * @throws {@link MissingEncryptorError} when `encryptor` resolves to `undefined`.
+ * @throws {@link FeatureDisabledError} when the instance was created with `isMerkleRootMutable: false`.
+ *
+ * @example
+ * const { root, entries, hash } = await rotateMerkleRoot({
+ *   airdrop,
+ *   recipients: [{ recipient: alice, cumulativeTotal: 1_500_000n }], // was 1_000_000n
+ *   encryptor,
+ * });
+ *
+ * @alpha
+ */
+export declare function rotateMerkleRoot({ airdrop, recipients, encryptor, account, }: RotateMerkleRootArgs): Promise<RotatedCampaign>;

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

@@ -0,0 +1,302 @@
+import type { Address, Hex, PublicClient, WalletClient } from "viem";
+import { type SdkTelemetry } from "../core/telemetry.js";
+import type { WriteAccountOverride } from "./airdrop-base.js";
+/**
+ * Whether `error` is the relayer's transient "the ACL hasn't propagated to
+ * the gateway yet" condition — as opposed to a genuine, non-retryable
+ * failure (a malformed handle, an unauthenticated request, an unrelated
+ * server error, etc.).
+ *
+ * **Why this exists:** after {@link ComplianceManagerClient.addDelegate}
+ * lands, a delegate is authorized on-chain immediately, but the gateway that
+ * serves a delegated read needs time to observe that change. Calling it in
+ * that window fails with the *same* HTTP status a permission failure or an
+ * unrelated server error would use, so a caller that treats every failure of
+ * that status as "access denied" will conclude the delegation is broken and
+ * go debug the wrong thing, when the correct response is to retry with
+ * backoff.
+ *
+ * The SDK does not call the relayer's delegated-decrypt itself (that call
+ * belongs to the relayer client the consumer already holds) — this function
+ * only classifies whatever error that call throws, so a caller can
+ * distinguish "retry me" from "this delegation really doesn't exist."
+ *
+ * **What counts as a match**, verified against the shipped `@zama-fhe/sdk`
+ * source rather than assumed (see the module comment above):
+ * - `error.code === "DELEGATION_NOT_PROPAGATED"` or
+ *   `error.name === "DelegationNotPropagatedError"` — an exact discriminator,
+ *   true regardless of status or message. This is how the SDK's own
+ *   `ConfidentialFungibleToken#decryptBalanceAs` reports the condition, and
+ *   that error carries no status field at all.
+ * - Otherwise, a status of `400` **or** `500` (read from `.status`,
+ *   `.statusCode`, `.cause.status`, or `.cause.statusCode` — a raw relayer
+ *   error may report it on any of those four) combined with a message (read
+ *   from `.message` or `.cause.message`) that names the propagation
+ *   condition — see {@link matchesPropagationMessage}.
+ *
+ * **Erring broad is the correct trade-off here**, not erring narrow: this
+ * classifier only gates whether a caller retries a read. A false positive
+ * costs a handful of unnecessary retries; a false negative sends an engineer
+ * to debug correct delegation wiring that was never broken. The matcher is
+ * therefore permissive about status and phrasing, while still refusing to
+ * classify a message that says nothing about propagation — an unrelated 400
+ * or 500 (bad signature, malformed handle, a genuine outage) still returns
+ * `false`.
+ *
+ * @param error The error thrown by a relayer's delegated-decrypt call — a
+ *   plain object, an `Error` subclass, or the `@zama-fhe/sdk` package's own
+ *   `DelegationNotPropagatedError` / `RelayerRequestFailedError` all satisfy
+ *   this; only duck-typed field access is used, so no import of
+ *   `@zama-fhe/sdk` (an optional peer dependency) is required.
+ * @returns `true` for the propagation condition, in any of the shapes above.
+ *
+ * @example
+ * try {
+ *   await relayer.delegatedUserDecrypt({ handle, delegate });
+ * } catch (err) {
+ *   if (isAclPropagationError(err)) {
+ *     // retry with backoff — the delegation is fine, the gateway just hasn't caught up yet
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ *
+ * @alpha
+ */
+export declare function isAclPropagationError(error: unknown): boolean;
+/** @alpha */
+export interface ComplianceManagerClientConfig {
+    publicClient: PublicClient;
+    walletClient?: WalletClient | undefined;
+    /** The `ComplianceRoleManager` clone — read it off `factory.createX(...)`'s result, or `factory.complianceManagerOf(airdrop)`. */
+    address: Address;
+    /**
+     * Chain id used for the support check. 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;
+    /**
+     * Optional telemetry sink. When provided, the SDK emits a
+     * `fhe-airdrop.client.init` event on construction and brackets write
+     * methods with named spans (`fhe-airdrop.compliance.addDelegate`, …).
+     * Defaults to a no-op.
+     */
+    telemetry?: SdkTelemetry | undefined;
+}
+/**
+ * Client for one `ComplianceRoleManager` clone — the per-airdrop-instance
+ * contract that holds account-level user-decryption delegations, so a
+ * compliance team or platform operator can decrypt an airdrop's handles
+ * without the airdrop contract itself granting them ACL one handle at a time.
+ *
+ * One clone serves exactly one airdrop instance (see {@link airdrop}), is
+ * created and `initialize`d atomically by the factory inside `createX(...)` —
+ * **this client never exposes `initialize`**, since calling it directly would
+ * either revert (already initialized) or, on a stand-alone clone nobody else
+ * has wired, produce a delegation nobody intended. There is consequently no
+ * externally observable "deployed but not yet wired" state: by the time an
+ * address is reachable through this client, `initialize` has already run.
+ *
+ * Two delegate slots exist per clone:
+ * - **The platform compliance delegate** — set once, at `initialize`, iff the
+ *   factory's compliance policy was ON for that creator at create time.
+ *   {@link complianceDelegate} returns the zero address when the policy was
+ *   OFF; because of the point above, a zero return is unambiguous — it always
+ *   means "this clone was created with the policy off," never "not wired
+ *   yet." This delegate is **irrevocable by construction**: no method on this
+ *   contract (or this client) ever revokes it.
+ * - **Client delegates** — zero or more addresses the client adds/removes
+ *   itself via {@link addDelegate} / {@link revokeDelegate}, gated by
+ *   {@link DELEGATION_ADMIN_ROLE}.
+ *
+ * **The propagation gotcha** (see {@link isAclPropagationError}'s TSDoc for
+ * the full mechanics): {@link addDelegate} and {@link revokeDelegate} are
+ * effective on-chain the instant their transaction lands, but the Zama
+ * gateway that serves a delegated read observes that change out of band, with
+ * a lag. A caller who wires a delegate and immediately attempts a delegated
+ * decrypt should expect the SDK-observed shapes of this condition — an HTTP
+ * 400 reading "ACL check not propagated" from the gateway directly, or, via
+ * `@zama-fhe/sdk`'s own `decryptBalanceAs`, an HTTP 500 wrapped as a
+ * `DelegationNotPropagatedError` — for a short window (the SDK's own guidance
+ * is 1-2 minutes), and should **retry with backoff** rather than conclude the
+ * delegation failed. This client does not call the relayer's delegated-decrypt
+ * itself (that belongs to whatever relayer client the consumer already
+ * holds); it only gives you {@link isAclPropagationError} to classify the
+ * error that call throws.
+ *
+ * @example
+ * const compliance = new ComplianceManagerClient({ publicClient, walletClient, address });
+ * await compliance.addDelegate({ delegate: complianceOfficer });
+ * // ... later, from wherever `delegatedUserDecrypt` is called:
+ * // if (isAclPropagationError(err)) { retry with backoff; }
+ *
+ * @alpha
+ */
+export declare class ComplianceManagerClient {
+    #private;
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient | undefined;
+    readonly address: Address;
+    readonly chainId: number;
+    constructor(config: ComplianceManagerClientConfig);
+    /**
+     * Add a client delegate: grants `delegate` permanent (never-expiring)
+     * user-decryption delegation over this clone's airdrop. Requires
+     * {@link DELEGATION_ADMIN_ROLE}.
+     *
+     * Effective on-chain immediately; see the class TSDoc for the gateway
+     * propagation lag before `delegatedUserDecrypt` catches up.
+     *
+     * @throws {@link InvalidArgumentError} (`argument: "delegate"`) when `delegate` is the zero address
+     *   (`ZeroDelegate`), already an active client delegate (`DelegateAlreadyAdded`), or targets the
+     *   irrevocable platform compliance delegate (`CannotManageComplianceDelegate`).
+     * @returns The transaction hash.
+     */
+    addDelegate(args: {
+        delegate: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Revoke a client delegate. Requires {@link DELEGATION_ADMIN_ROLE}.
+     *
+     * Effective on-chain immediately — but off-chain, gateway-served
+     * `delegatedUserDecrypt` calls stop succeeding only once the gateway
+     * observes the revocation, which is not instantaneous either. Cannot target
+     * the platform compliance delegate, which is irrevocable by construction.
+     *
+     * **Not in the same block as {@link addDelegate} for the same delegate.**
+     * The FHEVM ACL rejects an add and a revoke of one delegate within a single
+     * block (`AlreadyDelegatedOrRevokedInSameBlock`), and because that revert
+     * comes from the ACL rather than from this contract, it surfaces as an
+     * opaque {@link ContractRevertError} with no decodable selector — nothing
+     * names the delegate or the cause. Batching an add and a revoke into one
+     * multicall, or sending both inside one block, is the way to hit it; wait a
+     * block between them. This is the sequencing counterpart to the propagation
+     * gotcha on the class TSDoc: that one is the gateway lagging the chain, this
+     * one is the chain refusing two conflicting writes at the same height.
+     *
+     * @throws {@link InvalidArgumentError} (`argument: "delegate"`) when `delegate` is the zero address
+     *   (`ZeroDelegate`), not currently an active client delegate (`DelegateNotFound`), or targets the
+     *   irrevocable platform compliance delegate (`CannotManageComplianceDelegate`).
+     * @returns The transaction hash.
+     */
+    revokeDelegate(args: {
+        delegate: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /** The one airdrop instance this clone serves — set once, at `initialize`. */
+    airdrop(): Promise<Address>;
+    /**
+     * The platform compliance delegate.
+     *
+     * @returns The delegate address, or the zero address when this clone was
+     *   created with the platform compliance policy OFF. Because `initialize`
+     *   always runs atomically before this client can reach the clone (see the
+     *   class TSDoc), a zero return never means "not wired yet" — there is no
+     *   such observable state on this contract. It unambiguously means "no
+     *   platform delegate for this airdrop."
+     */
+    complianceDelegate(): Promise<Address>;
+    /** The current set of active client delegates (excludes the platform compliance delegate, if any). */
+    clientDelegates(): Promise<readonly Address[]>;
+    /**
+     * Authoritative active-delegate check for `delegate` — reads the ACL
+     * expiration date directly rather than the contract's `EnumerableSet`
+     * mirror, so it reflects the platform compliance delegate too (which never
+     * appears in {@link clientDelegates}).
+     *
+     * On-chain truth only: a `true` result means the delegation is live in the
+     * ACL, not that the gateway has caught up with it yet — see the class
+     * TSDoc's propagation note.
+     */
+    isActiveDelegate(delegate: Address): Promise<boolean>;
+    /** Gates {@link addDelegate} / {@link revokeDelegate}. */
+    DELEGATION_ADMIN_ROLE(): Promise<Hex>;
+    /**
+     * OpenZeppelin's root role (`bytes32(0)`), read from the clone rather than
+     * hard-coded. It administers {@link DELEGATION_ADMIN_ROLE}.
+     */
+    DEFAULT_ADMIN_ROLE(): Promise<Hex>;
+    /**
+     * Whether `holder` holds `role`.
+     *
+     * The role subject is called `holder`, not `account`: on the writes below
+     * `account` already means "who sends this transaction", and one key cannot
+     * be both.
+     *
+     * @param args.role A `bytes32` from {@link DELEGATION_ADMIN_ROLE} or {@link DEFAULT_ADMIN_ROLE}.
+     */
+    hasRole(args: {
+        role: Hex;
+        holder: Address;
+    }): Promise<boolean>;
+    /** The role whose holders may {@link grantRole} and {@link revokeRole} `role`. */
+    getRoleAdmin(role: Hex): Promise<Hex>;
+    /** How many accounts hold `role`. */
+    getRoleMemberCount(role: Hex): Promise<bigint>;
+    /**
+     * The `index`-th holder of `role`, in `EnumerableSet` order - which is not
+     * stable across grants and revokes. Prefer {@link getRoleMembers}.
+     */
+    getRoleMember(args: {
+        role: Hex;
+        index: bigint;
+    }): Promise<Address>;
+    /**
+     * Every account currently holding `role`.
+     *
+     * With {@link DELEGATION_ADMIN_ROLE} this answers "who may add or revoke a
+     * delegate on this clone?" - the administrative counterpart to
+     * {@link clientDelegates}, which answers "who may currently decrypt?".
+     */
+    getRoleMembers(role: Hex): Promise<readonly Address[]>;
+    /**
+     * Grant `role` to `holder`. Requires the role's admin role
+     * ({@link getRoleAdmin}).
+     *
+     * This is how a second operator is added to {@link DELEGATION_ADMIN_ROLE} -
+     * the delegation verbs themselves are unaffected, the grant only widens who
+     * may call them.
+     *
+     * @returns The transaction hash.
+     */
+    grantRole(args: {
+        role: Hex;
+        holder: Address;
+    } & WriteAccountOverride): Promise<Hex>;
+    /**
+     * Revoke `role` from `holder`. Requires the role's admin role.
+     *
+     * Revoking a delegation admin does **not** revoke the delegations they
+     * created: an existing delegate keeps decrypting until
+     * {@link revokeDelegate} is called for it explicitly.
+     *
+     * @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, so this method takes no holder and fills the confirmation from
+     * the resolved sending account. Renouncing for somebody else is not a call
+     * that can succeed; use {@link revokeRole} to remove another account's role.
+     *
+     * @returns The transaction hash.
+     */
+    renounceRole(args: {
+        role: Hex;
+    } & WriteAccountOverride): Promise<Hex>;
+}
+/**
+ * Create a {@link ComplianceManagerClient}. Mirrors viem's `create*` convention.
+ *
+ * @example
+ * const compliance = createComplianceManagerClient({ publicClient, walletClient, address });
+ *
+ * @alpha
+ */
+export declare function createComplianceManagerClient(config: ComplianceManagerClientConfig): ComplianceManagerClient;

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

@@ -0,0 +1,33 @@
+/**
+ * Contract commit every vendored ABI and deployed address in this module resolves against.
+ *
+ * @alpha
+ */
+export declare const AIRDROP_CONTRACTS_COMMIT = "8e5b144bdbcdf35b9f36b62f5257d795bf954e8e";
+/**
+ * Deployment shell selected at create time. Mirrors the contract's `DeploymentMode` enum
+ * (`IConfidentialAirdropTypes.sol`): `enum DeploymentMode { Clone, UUPS }`.
+ *
+ * @alpha
+ */
+export declare const DEPLOYMENT_MODE: {
+    readonly clone: 0;
+    readonly uups: 1;
+};
+/** @alpha */
+export type DeploymentMode = keyof typeof DEPLOYMENT_MODE;
+/**
+ * Replay-protection policy for ECDSA campaigns. Mirrors the contract's `DedupMode` enum
+ * (`IECDSAConfidentialAirdropTypes.sol`):
+ * `enum DedupMode { PerAddress, PerDedupId, Both, None }`.
+ *
+ * @alpha
+ */
+export declare const DEDUP_MODE: {
+    readonly perAddress: 0;
+    readonly perDedupId: 1;
+    readonly both: 2;
+    readonly none: 3;
+};
+/** @alpha */
+export type DedupMode = keyof typeof DEDUP_MODE;