@tokenops/sdk 1.5.1 → 2.0.0-alpha.1

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

@@ -0,0 +1,263 @@
+import type { Address, Hex } from "viem";
+import type { EncryptedInput, EncryptedViewResult } from "../fhe/types.js";
+import { AirdropBaseClient, type AirdropBaseClientConfig, type WriteAccountOverride } from "./airdrop-base.js";
+import type { DedupMode } from "./constants.js";
+/**
+ * EIP-712 domain name every `ECDSAConfidentialAirdrop` instance shares. Set once, at `initialize`.
+ *
+ * @alpha
+ */
+export declare const EIP712_DOMAIN_NAME = "ConfidentialAirdrop";
+/**
+ * EIP-712 domain version every `ECDSAConfidentialAirdrop` instance shares.
+ *
+ * @alpha
+ */
+export declare const EIP712_DOMAIN_VERSION = "1";
+/**
+ * The `Claim` struct's EIP-712 type declaration, field-for-field in the
+ * contract's declared order. v2 adds `dedupId` and `deadline` to v1's
+ * two-field struct.
+ *
+ * @alpha
+ */
+export declare const CLAIM_TYPES: {
+    readonly Claim: readonly [{
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "encryptedAmount";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "dedupId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+};
+/**
+ * `CLAIM_TYPEHASH`, computed client-side from {@link CLAIM_TYPES} exactly as
+ * Solidity computes its `bytes32 public constant CLAIM_TYPEHASH`. Exported so
+ * a caller can sanity-check the binding without an RPC round trip;
+ * {@link EcdsaAirdropClient.claimTypehash} reads the live on-chain value for
+ * the paranoid case where an instance was deployed off a diverged contract
+ * build.
+ *
+ * @alpha
+ */
+export declare const CLAIM_TYPEHASH: `0x${string}`;
+/** @alpha */
+export interface EcdsaAirdropClientConfig extends AirdropBaseClientConfig {
+    /**
+     * The replay-protection policy this instance was deployed with
+     * (`perAddress` / `perDedupId` / `both` / `none`).
+     *
+     * Required at construction because the contract exposes **no on-chain
+     * getter** for it: `ECDSADedupStorage.dedupMode`
+     * (`ConfidentialAirdropECDSAStorage.sol`) is a private field inside an
+     * ERC-7201 namespaced storage struct, unreachable through any ABI-visible
+     * read — every other constant this client exposes (`SIGNER_ROLE`,
+     * `CLAIM_TYPEHASH`, `DOMAIN_SEPARATOR`) has a public getter; this one does
+     * not. Pass the same value used at
+     * `factory.createEcdsaAirdrop({ params: { dedupMode } })` time.
+     */
+    dedupMode: DedupMode;
+}
+/**
+ * Inputs shared by {@link EcdsaAirdropClient.claim} and {@link EcdsaAirdropClient.claimAndUnwrap}.
+ *
+ * @alpha
+ */
+export interface EcdsaClaimArgs extends WriteAccountOverride {
+    /**
+     * Payout destination. Omit (or pass the zero address) to default to the
+     * sending account — mirrors the contract's own `to == address(0)` redirect
+     * rule. Authorization (the signature), replay dedup and the FHE input
+     * proof all stay bound to the sending account regardless of `to`; this
+     * field only redirects where the tokens (and the recipient ACL) land.
+     */
+    to?: Address;
+    /** The claimant's encrypted allocation, bound to `(airdrop, sendingAccount)` at encryption time. */
+    encryptedInput: EncryptedInput;
+    /** The off-chain claim id bound into the signature. */
+    dedupId: Hex;
+    /** Unix seconds the signature expires at. Past this, the contract reverts `SignatureExpired`. */
+    deadline: bigint;
+    /** The `SIGNER_ROLE` holder that authorized this claim. */
+    signer: Address;
+    /** The EIP-712 signature from `signClaimAuthorization` (`./encryption.js`). */
+    signature: Hex;
+}
+/**
+ * Inputs for {@link EcdsaAirdropClient.getClaimAmount}.
+ *
+ * @alpha
+ */
+export interface GetClaimAmountArgs extends WriteAccountOverride {
+    encryptedInput: EncryptedInput;
+    dedupId: Hex;
+    deadline: bigint;
+    signer: Address;
+    signature: Hex;
+}
+/**
+ * Inputs for {@link EcdsaAirdropClient.isSignatureValid}.
+ *
+ * @alpha
+ */
+export interface IsSignatureValidArgs {
+    /**
+     * The address the signature was made out to — the contract's digest binds
+     * `msg.sender`, so this read is simulated as an `eth_call` from
+     * `recipient`, not from whatever account the SDK happens to be configured
+     * with. Passing the wrong address always returns `false` for a signature
+     * that would otherwise succeed.
+     */
+    recipient: Address;
+    /** The external encrypted allocation handle — no input proof: this is a view, it never calls `FHE.fromExternal`. */
+    encryptedAmountHandle: Hex;
+    dedupId: Hex;
+    deadline: bigint;
+    signer: Address;
+    signature: Hex;
+}
+/**
+ * Client for one `ECDSAConfidentialAirdrop` instance — the variant whose
+ * claims are authorised by an off-chain EIP-712 signature from a
+ * `SIGNER_ROLE` holder, rather than a Merkle proof.
+ *
+ * Adds the claim surface on top of {@link AirdropBaseClient}'s shared
+ * lifecycle/treasury/rescue/role/disclosure methods: `claim` /
+ * `claimAndUnwrap` submit a signed allocation, `getClaimAmount` previews it
+ * as a decryptable handle without consuming replay state, and
+ * `isSignatureValid` gas-optimistically checks all of the above without
+ * spending an FHE op.
+ *
+ * Every claim entrypoint here takes the exact-equality gas fee
+ * ({@link AirdropBaseClient.gasFee}) automatically — read fresh on every
+ * `claim`/`claimAndUnwrap` call and attached as the transaction's `value`, so
+ * a caller never has to source it themselves or risk sending the wrong
+ * amount against the contract's `msg.value != gasFee()` revert.
+ *
+ * @example
+ * const airdrop = new EcdsaAirdropClient({ publicClient, walletClient, address, dedupMode: "perAddress" });
+ * const hash = await airdrop.claim({ encryptedInput, dedupId, deadline, signer, signature });
+ *
+ * @alpha
+ */
+export declare class EcdsaAirdropClient extends AirdropBaseClient {
+    /** @see EcdsaAirdropClientConfig.dedupMode */
+    readonly dedupMode: DedupMode;
+    constructor(config: EcdsaAirdropClientConfig);
+    /**
+     * Claim a signed encrypted allocation, delivering the tokens to `to`
+     * (defaults to the sending account).
+     *
+     * Consumes this instance's `dedupMode` replay guard(s) and the defense-in-
+     * depth EIP-712 digest guard. Requires `msg.value == gasFee()` exactly —
+     * handled for you; see the class TSDoc.
+     *
+     * @throws {@link ClaimNotStartedError} before `startTime`.
+     * @throws {@link ClaimWindowClosedError} after `endTime`.
+     * @throws {@link SignatureExpiredError} after `args.deadline` has passed.
+     * @throws {@link InvalidSignatureError} when `signer` lacks `SIGNER_ROLE` or the signature does not verify.
+     * @throws {@link AlreadyClaimedError} on an address or digest replay.
+     * @throws {@link DedupIdConsumedError} on a `dedupId` replay under `perDedupId`/`both`.
+     * @returns The transaction hash.
+     */
+    claim(args: EcdsaClaimArgs): Promise<Hex>;
+    /**
+     * Claim then route the allocation straight into the wrapper's unwrap
+     * (`to` becomes the underlying ERC-20 beneficiary). Reverts
+     * `TokenNotUnwrappable` (surfaced as `FeatureDisabledError`) on a
+     * non-unwrappable campaign.
+     *
+     * Same replay consumption and `msg.value == gasFee()` requirement as
+     * {@link claim}.
+     *
+     * @returns The transaction hash. The underlying ERC-20 is released later by
+     *   a separate, permissionless `finalizeUnwrap` — this hash is only the
+     *   unwrap request.
+     */
+    claimAndUnwrap(args: EcdsaClaimArgs): Promise<Hex>;
+    /**
+     * Preview a signed allocation as a handle the caller can decrypt, without
+     * consuming either replay guard — the same input can still be claimed for
+     * real afterwards. No fee.
+     *
+     * An encrypted view: the contract calls `FHE.allow(amount, msg.sender)`, so
+     * the result is recovered from the receipt's ACL `Allowed` event, never
+     * from a simulation. See {@link AirdropBaseClient}'s class TSDoc.
+     *
+     * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`.
+     */
+    getClaimAmount(args: GetClaimAmountArgs): Promise<EncryptedViewResult>;
+    /**
+     * Gas-optimised validity check: would `claim`/`claimAndUnwrap` succeed
+     * right now for `args.recipient`, without spending an FHE op or a
+     * transaction.
+     *
+     * Never reverts — returns `false` for every failure mode (paused, outside
+     * the claim window, past `deadline`, `signer` lacking `SIGNER_ROLE`, an
+     * invalid signature, an already-consumed digest, or an already-deduped
+     * claim per this instance's `dedupMode`).
+     *
+     * @returns Whether the signature is currently valid and unconsumed for `args.recipient`.
+     */
+    isSignatureValid(args: IsSignatureValidArgs): Promise<boolean>;
+    /** `bytes32` identifier for the role that must authorize a claim signature. */
+    SIGNER_ROLE(): Promise<Hex>;
+    /**
+     * The live on-chain `CLAIM_TYPEHASH`. Prefer the module-level
+     * {@link CLAIM_TYPEHASH} constant to avoid an RPC round trip; use this read
+     * only to confirm a specific deployed instance was built off the expected
+     * contract source.
+     */
+    claimTypehash(): Promise<Hex>;
+    /**
+     * The EIP-712 domain separator this instance signs against
+     * (`_domainSeparatorV4()`), bound to `(chainId, address(this))`. Useful for
+     * verifying a signature independently of `walletClient.signTypedData`.
+     */
+    domainSeparator(): Promise<Hex>;
+    /**
+     * The instance's ERC-5267 domain description - the same domain
+     * {@link domainSeparator} hashes, but field by field.
+     *
+     * Use it when something else has to reconstruct the domain rather than
+     * compare a hash: a wallet rendering a typed-data prompt, an independent
+     * verifier, or a cross-check that a deployed instance really was initialized
+     * with {@link EIP712_DOMAIN_NAME} / {@link EIP712_DOMAIN_VERSION} on the
+     * chain you think it is on. `salt` is `bytes32(0)` and `extensions` is empty
+     * - this contract uses OpenZeppelin's plain `EIP712` domain.
+     *
+     * @returns The seven ERC-5267 fields, named. `fields` is the standard's
+     *   bitmap of which of them are actually in use.
+     */
+    eip712Domain(): Promise<Eip712Domain>;
+}
+/**
+ * The ERC-5267 `eip712Domain()` tuple, as named fields.
+ *
+ * @alpha
+ */
+export interface Eip712Domain {
+    /** Bitmap of which of the six domain fields below the contract populates. */
+    fields: Hex;
+    name: string;
+    version: string;
+    chainId: bigint;
+    verifyingContract: Address;
+    salt: Hex;
+    extensions: readonly bigint[];
+}
+/**
+ * Create an {@link EcdsaAirdropClient}. Mirrors viem's `create*` convention.
+ *
+ * @example
+ * const airdrop = createEcdsaAirdropClient({ publicClient, walletClient, address, dedupMode: "perAddress" });
+ *
+ * @alpha
+ */
+export declare function createEcdsaAirdropClient(config: EcdsaAirdropClientConfig): EcdsaAirdropClient;

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

@@ -1,11 +1,13 @@
-import type { Address, WalletClient } from "viem";
-import { type EncryptedHandle, type Signature } from "../core/brands.js";
-import type { EncryptedInput, EncryptedInputs } from "./types.js";
+import type { Account, Address, Hex, WalletClient } from "viem";
+import { type Signature } from "../core/brands.js";
+import type { EncryptedInput, EncryptedInputs } from "../fhe/types.js";
 /**
  * FHE input values, discriminated by ciphertext type. Mirrors the shape of
  * `EncryptInput` from `@zama-fhe/sdk` so that a `RelayerWeb` / `RelayerNode`
  * / `MockFhevmInstance` instance is structurally assignable to {@link Encryptor}
  * without casting.
+ *
+ * @alpha
  */
 export type FheValueInput = {
     value: boolean | bigint;
@@ -20,6 +22,8 @@ export type FheValueInput = {
 /**
  * Subset of `@zama-fhe/sdk` `RelayerSDK` we depend on. Declared structurally so
  * consumers can pass any v3 RelayerSDK without us importing the optional peer dep.
+ *
+ * @alpha
  */
 export interface Encryptor {
     encrypt(params: {
@@ -34,6 +38,8 @@ export interface Encryptor {
 /**
  * Eager or lazy {@link Encryptor} reference. Lazy form for React/Vue/signals
  * hosts where the encryptor lifetime doesn't match the client's.
+ *
+ * @alpha
  */
 export type EncryptorSource = Encryptor | (() => Encryptor | undefined);
 /**
@@ -49,14 +55,18 @@ export type EncryptorSource = Encryptor | (() => Encryptor | undefined);
  * // React — lazy factory picks up the live ZamaSDK context
  * const zamaSDK = useZamaSDK();
  * const resolved = resolveEncryptor(() => zamaSDK.relayer);
+ *
+ * @alpha
  */
 export declare function resolveEncryptor(source: EncryptorSource | undefined): Encryptor | undefined;
+/** @alpha */
 export interface EncryptUint64Args {
     encryptor: Encryptor;
     contractAddress: Address;
     userAddress: Address;
     value: bigint;
 }
+/** @alpha */
 export interface EncryptUint64BatchArgs {
     encryptor: Encryptor;
     contractAddress: Address;
@@ -67,9 +77,22 @@ export interface EncryptUint64BatchArgs {
  * Encrypt a single `uint64` value into an `externalEuint64` handle + KMS input proof.
  *
  * The handle and proof are bound to `contractAddress` and `userAddress` — they
- * cannot be replayed against a different contract or sender. For airdrops the
- * `userAddress` MUST be the **recipient** (not the admin), because the contract's
- * `FHE.fromExternal` rejects proofs bound to any other address.
+ * cannot be replayed against a different contract or sender. The binding must
+ * name whichever contract calls `FHE.fromExternal` and whichever account sends
+ * that transaction, and for airdrops those differ between the two flows:
+ *
+ * - **Claiming** (`EcdsaAirdropClient.claim` / `claimAndUnwrap`): bind to
+ *   `(airdropInstanceAddress, recipientAddress)`. The `userAddress` MUST be
+ *   the **recipient** — the account that sends the claim — not the admin.
+ * - **Funding** (`ConfidentialAirdropFactoryClient.fundAirdrop` /
+ *   `createAndFund*`, i.e. a hand-built `FundInput.encryptedInput`):
+ *   bind to `(factoryAddress, funderAddress)`. The factory, not the instance,
+ *   is what calls `FHE.fromExternal` on the pool amount, and the funder is the
+ *   admin sending the create/fund transaction. A proof bound to the instance
+ *   reverts inside `FHE.fromExternal`.
+ *
+ * Either way `FHE.fromExternal` rejects a proof bound to any other pair, so
+ * the binding is a hard requirement, not a convention.
  *
  * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
  * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
@@ -82,36 +105,91 @@ export interface EncryptUint64BatchArgs {
  * @param args Encryption request; `value` must fit in `uint64` (0 to 2^64-1).
  * @returns `{ handle: Hex, inputProof: Hex }` — pass both to the contract.
  * @example
+ * // Claim side: bound to (instance, recipient).
  * const encrypted = await encryptUint64({
  *   encryptor,
- *   contractAddress: airdropAddress,
+ *   contractAddress: airdrop,
  *   userAddress: recipientAddress, // must be the recipient, not the admin
  *   value: 1_000_000n,             // raw token units; ERC-7984 uses 6 decimals
  * });
  * const signature = await signClaimAuthorization({
  *   walletClient,
- *   airdropAddress,
+ *   airdrop,
+ *   chainId,
  *   recipient: recipientAddress,
  *   encryptedAmountHandle: encrypted.handle,
+ *   dedupId,
+ *   deadline,
  * });
+ * @example
+ * // Funding side: bound to (factory, funder) — NOT to the instance.
+ * const pool = await encryptUint64({
+ *   encryptor,
+ *   contractAddress: factory.address,
+ *   userAddress: funderAddress,
+ *   value: 100_000_000n,
+ * });
+ * await factory.fundAirdrop({ airdrop, encryptedInput: pool });
+ *
+ * @alpha
  */
 export declare function encryptUint64({ encryptor, contractAddress, userAddress, value, }: EncryptUint64Args): Promise<EncryptedInput>;
 /**
  * Encrypt N `uint64` values into N handles bound by a single input proof.
+ *
+ * @alpha
  */
 export declare function encryptUint64Batch({ encryptor, contractAddress, userAddress, values, }: EncryptUint64BatchArgs): Promise<EncryptedInputs>;
 /**
- * Build an EIP712 signature for a `Claim(address recipient, bytes32 encryptedAmount)` struct.
+ * Build the v2 EIP-712 signature over a `Claim(address recipient, bytes32
+ * encryptedAmount, bytes32 dedupId, uint256 deadline)` struct — the
+ * four-field digest `ECDSAConfidentialAirdrop` verifies (see `CLAIM_TYPEHASH`
+ * / `CLAIM_TYPES` in `./ecdsa.js`).
+ *
+ * A `SIGNER_ROLE` holder calls this off-chain; the recipient later presents
+ * the returned signature (together with the matching encrypted input) to
+ * `claim` / `claimAndUnwrap` / `getClaimAmount` / `isSignatureValid`. The
+ * signer is **not** bound into the digest — every claim entrypoint takes
+ * `signer` as an explicit parameter and verifies the signature against it,
+ * so the signature alone proves who signed.
  *
- * The admin calls this to sign a claim authorisation. The resulting `signature`
- * is passed by the recipient to `claim()` or `getClaimAmount()`.
+ * **Replay is bounded by the instance's `dedupMode`, not by this function.**
+ * Every mode consumes the EIP-712 digest, so the exact same signature bytes
+ * can never be replayed once used — but that is only ONE of two possible
+ * replay dimensions, and which second dimension applies depends entirely on
+ * the deploy-time `dedupMode` (`perAddress` / `perDedupId` / `both` /
+ * `none`, ordinals 0–3 in `./constants.js`):
  *
- * @param args Claim signing request. `walletClient` must sign with DEFAULT_ADMIN_ROLE on the airdrop clone.
+ * - `perAddress` — a recipient is capped at one claim, however many valid
+ *   signatures they hold for that address.
+ * - `perDedupId` — signing the **same** encrypted amount for two
+ *   **different** `dedupId`s lets it be claimed **twice** — a 2x drain. Never
+ *   reuse the ciphertext across `dedupId`s that should not both be honoured.
+ * - `both` — both guards apply; either an address or a `dedupId` replay is
+ *   blocked.
+ * - `none` — **neither** dedup map is written. Every distinct signature (any
+ *   new `dedupId` or `deadline` produces a new digest) is independently
+ *   claimable, with no per-address or per-allocation ceiling on-chain at all.
+ *
+ * **The consequence:** under `perDedupId` and `none`, the on-chain contract
+ * enforces no upper bound on total payout to a given recipient or
+ * allocation — the **signing service** is the only thing bounding it, by
+ * never issuing two signatures that should not both be honoured. That
+ * constraint lives in the service that calls this function, not in the
+ * contract.
+ *
+ * @param args Claim signing request. `walletClient` (or `args.account`) must sign with `SIGNER_ROLE` on the airdrop instance.
  * @returns `0x`-prefixed ECDSA signature bytes.
+ *
+ * @alpha
  */
 export declare function signClaimAuthorization(args: {
     walletClient: WalletClient;
-    airdropAddress: Address;
+    airdrop: Address;
+    chainId: number;
     recipient: Address;
-    encryptedAmountHandle: EncryptedHandle;
+    encryptedAmountHandle: Hex;
+    dedupId: Hex;
+    deadline: bigint;
+    account?: Account | Address | undefined;
 }): Promise<Signature>;