@tokenops/sdk 2.0.0-alpha.1 → 2.0.0-alpha.2

package/dist/fhe-airdrop/merkle-tree.d.ts

@@ -7,32 +7,32 @@ import type { Address, Hex } from "viem";
 export interface LeafOfArgs {
     /** The `MerkleConfidentialAirdrop` instance the leaf is scoped to — `address(this)` on-chain. */
     instance: Address;
-    /** The claiming account — always `msg.sender` on-chain, never the claim's payout destination. */
-    recipient: Address;
-    /** The encrypted handle committing the recipient's cumulative total allocation. */
+    /** The claim identity, independent of both the transaction submitter and the payout destination. */
+    account: Address;
+    /** The encrypted handle committing the account's cumulative total allocation. */
     handle: Hex;
 }
 /**
- * Compute a Merkle leaf byte-for-byte identical to the contract's
- * `_leafOf(recipient, inputAmount)` — see the module comment above for the
- * verified derivation. Mirrors what the campaign builder (`buildMerkleCampaign`,
- * `campaign.ts`) needs to construct the same tree `StandardMerkleTree` would,
- * and is useful to any caller who wants to recompute a leaf independently of
- * the campaign orchestrator.
+ * Compute a Merkle leaf byte-for-byte identical to the contract's `_leafOf` — see the
+ * module comment for the verified derivation.
  *
  * @alpha
  */
 export declare function leafOf(args: LeafOfArgs): Hex;
 /**
- * The minimum a leaf must carry. `buildMerkleTree` is generic over anything
- * wider, so a caller's own fields ride along onto the entry.
+ * The minimum a leaf must carry. `buildMerkleTree` is generic over anything wider, so a
+ * caller's own fields ride along onto the entry.
+ *
+ * Deliberately does NOT include `boundTo`: the tree does not commit the submitter, so it
+ * is not needed to build one. Pass it anyway (alongside `inputProof`) and it rides through
+ * to the entry, which is what makes the result assignable to {@link CampaignEntry}.
  *
  * @alpha
  */
 export interface MerkleLeafInput {
-    /** The account that will SEND the claim. The contract recomputes the leaf as `_leafOf(msg.sender, inputAmount)`. */
-    recipient: Address;
-    /** The encrypted handle committing this recipient's cumulative total. */
+    /** The claim identity this leaf commits — whose payout and cumulative accounting it keys. */
+    account: Address;
+    /** The encrypted handle committing this account's cumulative total. */
     handle: Hex;
 }
 /**
@@ -57,34 +57,30 @@ export interface BuiltMerkleTree<L extends MerkleLeafInput> {
     })[];
 }
 /**
- * Build the Merkle tree a `MerkleConfidentialAirdrop` verifies against, from
- * handles produced anywhere.
+ * Build the Merkle tree a `MerkleConfidentialAirdrop` verifies against, from handles
+ * produced anywhere.
  *
- * **Pure.** No relayer, no chain access, no encryptor. Given the same leaves
- * it returns the same root, so it can run offline, in a test, or on a machine
- * that has never seen a private key.
+ * **Pure.** No relayer, no chain access, no encryptor — same leaves in, same root out.
  *
- * **The tree commits to the handle, not the amount.** `_leafOf` hashes
- * `(address(this), recipient, encHandle)`, so whoever encrypted must have bound
- * each input to `(instance, that recipient)` — `FHE.fromExternal` reverts on any
- * mismatch. This function cannot check that; it will happily build a tree over
- * wrongly-bound handles, and the failure surfaces at claim time.
+ * **The tree commits to the handle, not the amount, and not the submitter.** `_leafOf`
+ * hashes `(instance, account, handle)`, so whoever encrypted must have bound each input
+ * to `(instance, the intended submitter)`. This function cannot check that: it will
+ * happily build a tree over wrongly-bound handles, and the failure surfaces at claim time
+ * inside the coprocessor.
  *
- * **Extra fields ride along.** Whatever the leaf carries beyond
- * `recipient` and `handle` — an `inputProof`, your own row id — comes back on
- * the entry, still aligned with its proof. Passing
- * `{ recipient, handle, inputProof }` therefore yields a value structurally
- * assignable to `CampaignEntry`, which is what `MerkleAirdropClient.claim`
- * consumes.
+ * **Extra fields ride along.** Whatever a leaf carries beyond `account` and `handle` —
+ * `boundTo`, an `inputProof`, your own row id — comes back on the entry, still aligned
+ * with its proof. Passing `{ account, boundTo, handle, inputProof }` therefore yields a
+ * value structurally assignable to {@link CampaignEntry}.
  *
  * @param args The instance the leaves are scoped to, and the leaves.
  * @returns The root to publish, and one proof-bearing entry per input leaf, in input order.
- * @throws {@link InvalidArgumentError} on a zero or malformed instance, an empty leaf set, a malformed or zero recipient, a duplicate recipient, or a handle that is not 32 bytes.
+ * @throws {@link InvalidArgumentError} on a zero or malformed instance, an empty leaf set, a malformed or zero account, a duplicate account, or a handle that is not 32 bytes.
  *
  * @example
  * const { root, entries } = buildMerkleTree({
  *   instance: airdrop,
- *   leaves: [{ recipient: alice, handle, inputProof }],
+ *   leaves: [{ account: alice, boundTo: alice, handle, inputProof }],
  * });
  * await merkle.setMerkleRoot({ newRoot: root });
  *
@@ -92,12 +88,10 @@ export interface BuiltMerkleTree<L extends MerkleLeafInput> {
  */
 export declare function buildMerkleTree<L extends MerkleLeafInput>(args: BuildMerkleTreeArgs<L>): BuiltMerkleTree<L>;
 /**
- * Real implementation behind {@link buildMerkleTree}, parameterised on the
- * function name a thrown {@link InvalidArgumentError} blames.
+ * Real implementation behind {@link buildMerkleTree}, parameterised on the function name
+ * a thrown {@link InvalidArgumentError} blames.
  *
- * Not part of the public surface — exported from this module only so
- * `buildMerkleCampaign` (`campaign.ts`) can call it directly with its own
- * name, attributing a malformed-handle failure to itself rather than to
- * `buildMerkleTree`. Neither barrel (`index.ts`) re-exports it.
+ * Not part of the public surface — exported only so `buildMerkleCampaign` can call it
+ * with its own name. Neither barrel re-exports it.
  */
 export declare function buildMerkleTreeInternal<L extends MerkleLeafInput>({ instance, leaves }: BuildMerkleTreeArgs<L>, method: string): BuiltMerkleTree<L>;

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

@@ -10,23 +10,22 @@ import type { CampaignEntry } from "./types.js";
  */
 export interface MerkleClaimArgs 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. The leaf's recipient field, the outstanding-amount accounting 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.
+     * Payout destination. Omit (or pass the zero address) to default to
+     * `entry.account` — note that is the CLAIM IDENTITY, not the sender, so on a
+     * relayed claim omitting `to` still pays the recipient.
+     *
+     * Only the account itself may redirect elsewhere; a third-party submitter passing
+     * a different `to` is refused before the write with
+     * {@link UnauthorizedRedirectError}.
      */
     to?: Address;
     /**
-     * The recipient's proof-bearing claim entry, built by the campaign
-     * orchestrator (`campaign.ts`, Task 11). `entry.recipient` must equal the
-     * account this call sends from (`args.account`, or the wallet client's
-     * default account): the contract recomputes the leaf as
-     * `_leafOf(msg.sender, inputAmount)`, so submitting `entry.merkleProof`
-     * from any account other than `entry.recipient` recomputes a different
-     * leaf and reverts `InvalidMerkleProof` even though the proof bytes
-     * themselves are untouched.
+     * The proof-bearing claim entry, built by a campaign builder (`campaign.ts`).
+     *
+     * `entry.account` is submitted as the claim identity and selects the leaf.
+     * `entry.boundTo` must be the sending account, because the coprocessor verifies
+     * the input proof against the literal caller — the SDK checks this before the
+     * write rather than letting the transaction revert.
      */
     entry: CampaignEntry;
 }
@@ -37,18 +36,22 @@ export interface MerkleClaimArgs extends WriteAccountOverride {
  */
 export interface GetClaimAmountArgs extends WriteAccountOverride {
     /**
-     * Same binding rule as {@link MerkleClaimArgs.entry}: `entry.recipient`
-     * must equal the calling account, since the contract's preview also
-     * recomputes the leaf against `msg.sender`.
+     * Same binding rule as {@link MerkleClaimArgs.entry}: `entry.boundTo` must be the
+     * calling account. The preview's result is ACL'd to `entry.account`, so a relayer
+     * can confirm a leaf verifies without being able to read the amount.
      */
     entry: CampaignEntry;
 }
 /**
  * Client for one `MerkleConfidentialAirdrop` instance — the variant whose
  * claims are authorised by inclusion in a published Merkle tree rather than
- * an off-chain signature. Each leaf commits `(instance, recipient, handle)`,
- * where `handle` is the recipient's CUMULATIVE total allocation, not a
- * per-drop tranche — see the `@remarks` on {@link getClaimedAmount}.
+ * an off-chain signature. Each leaf commits `(instance, account, handle)`, where
+ * `handle` is that account's CUMULATIVE total allocation, not a per-drop tranche —
+ * see the `@remarks` on {@link getClaimedAmount}.
+ *
+ * `claim` names its claim identity explicitly, so a relayer can settle a leaf on a
+ * recipient's behalf. `claimAndUnwrap` deliberately cannot: it is always submitted
+ * for the caller.
  *
  * Adds the claim surface on top of {@link AirdropBaseClient}'s shared
  * lifecycle/treasury/rescue/role/disclosure methods: `claim` /
@@ -71,8 +74,8 @@ export interface GetClaimAmountArgs extends WriteAccountOverride {
 export declare class MerkleAirdropClient extends AirdropBaseClient {
     constructor(config: AirdropBaseClientConfig);
     /**
-     * Claim the outstanding amount for a proof-bearing entry, delivering the
-     * tokens to `to` (defaults to the sending account).
+     * Claim the outstanding amount for a proof-bearing entry, delivering the tokens to
+     * `to` — which defaults to `entry.account`, the CLAIM IDENTITY, not the sender.
      *
      * Requires `msg.value == gasFee()` exactly — handled for you; see the
      * class TSDoc.
@@ -89,8 +92,9 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      *
      * @throws {@link ClaimNotStartedError} before `startTime`.
      * @throws {@link ClaimWindowClosedError} after `endTime`.
-     * @throws {@link InvalidArgumentError} (`argument: "merkleProof"`) when the proof does not verify against
-     *   the current root — including when `entry.recipient` does not match the sending account.
+     * @throws {@link InvalidArgumentError} (`argument: "entry.boundTo"`) when the entry's proof is bound to
+     *   another address, or (`argument: "merkleProof"`) when the proof does not verify against the current root.
+     * @throws {@link UnauthorizedRedirectError} when a third-party submitter passes a `to` other than `entry.account`.
      * @returns The transaction hash.
      */
     claim(args: MerkleClaimArgs): Promise<Hex>;
@@ -103,6 +107,14 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      * Same replay/accounting semantics and `msg.value == gasFee()` requirement
      * as {@link claim} — see its `@remarks`.
      *
+     * @remarks
+     * **Self-only by design.** This entrypoint takes no claim identity: releasing an
+     * allocation as a public ERC-20 transfer publishes the amount irreversibly, which is
+     * the recipient's own choice to make. A relayed unwrap is therefore unrepresentable
+     * rather than merely rejected, and an entry whose `account` is not the sender is
+     * refused before the write. A third party can still submit a confidential
+     * {@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.
@@ -113,11 +125,15 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      * caller can decrypt. Consumes no accounting and no per-leaf state — the
      * same entry still pays the same amount after a preview. No fee.
      *
-     * An encrypted view: the contract calls `FHE.allow(outstanding, msg.sender)`,
-     * so the result is recovered from the receipt's ACL `Allowed` event, never
-     * from a simulation. See {@link AirdropBaseClient}'s class TSDoc.
+     * **Submits a transaction.** The contract calls `FHE.allow(outstanding, account)`, so
+     * the result is recovered from the receipt's ACL `Allowed` event, never from a
+     * simulation. See {@link AirdropBaseClient}'s class TSDoc.
+     *
+     * **`entry.account` is the decryptable party, not the caller.** A relayer previewing on
+     * someone's behalf gets a valid handle it cannot read — that is the contract's intent,
+     * and it is what makes a blind relayed submission possible.
      *
-     * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`.
+     * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`, as `entry.account`.
      */
     getClaimAmount(args: GetClaimAmountArgs): Promise<EncryptedViewResult>;
     /**
@@ -139,10 +155,15 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      *   leaves for the same recipient, claiming both pays the higher of the
      *   two totals net of this running value — `max`, not `sum`.
      *
-     * The zero handle (uninitialized ciphertext) before an account's first
-     * settled claim decrypts as zero.
+     * **An account that has never claimed returns the ZERO handle, which cannot be
+     * decrypted.** It is an uninitialized ciphertext, so nobody holds an ACL on it and
+     * the relayer rejects it with "not authorized to user decrypt handle 0x0…0" rather
+     * than answering zero. Treat `handle === zeroHash` as "nothing delivered yet" and
+     * skip the decrypt; only call `userDecrypt` on a non-zero handle. (A mock FHEVM
+     * instance does answer zero here, so this only bites against a live relayer.)
      *
-     * @returns The account's cumulative delivered total, as an encrypted handle.
+     * @returns The account's cumulative delivered total as an encrypted handle, or the
+     *   zero handle if it has never claimed.
      */
     getClaimedAmount(account: Address): Promise<EncryptedHandle>;
     /** The currently published root. Proofs must verify against this exact value. */

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

@@ -8,6 +8,7 @@ import { type EcdsaAirdropClient } from "../ecdsa.js";
 import { type EncryptorSource } from "../encryption.js";
 import { type ConfidentialAirdropFactoryClient } from "../factory.js";
 import { type MerkleAirdropClient } from "../merkle.js";
+import { type ComplianceManagerClient } from "../compliance.js";
 /**
  * Stable query-key prefix for every hook in this subpath — matches the
  * sibling subpaths' convention (`FHE_VESTING_KEY`/`FHE_DISPERSE_KEY`/
@@ -154,6 +155,18 @@ export declare function useMemoMerkleAirdropClient(opts: AirdropInstanceClientOp
     walletClient: WalletClient | undefined;
     chainId: number | undefined;
 };
+/**
+ * Memoize a {@link ComplianceManagerClient} for `opts.address`.
+ *
+ * `address` is the manager CLONE, not the airdrop instance and not the factory — read it
+ * from `factory.complianceManagerOf(airdrop)` or off `CreateAirdropResult.complianceManager`.
+ */
+export declare function useMemoComplianceManagerClient(opts: AirdropInstanceClientOptions): {
+    client: ComplianceManagerClient | undefined;
+    publicClient: PublicClient | undefined;
+    walletClient: WalletClient | undefined;
+    chainId: number | undefined;
+};
 /**
  * Per-hook overrides for {@link useMemoEcdsaAirdropClient} — `dedupMode` has no on-chain getter, so it must be supplied.
  *