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

package/dist/fhe-airdrop/advanced/react/useSetDefaultUpgradeable.d.ts

@@ -0,0 +1,27 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetDefaultUpgradeableArgs extends WriteAccountOverride {
+    /** Whether creators without an override may deploy `mode: "uups"`. */
+    allowed: boolean;
+}
+/**
+ * Set the factory-wide default for whether a `create*` may deploy
+ * `mode: "uups"`. Requires `UPGRADE_MANAGER_ROLE`.
+ *
+ * **Invalidates:** the `fn "effectiveUpgradeable"`,
+ * `fn "upgradeabilityPolicy"` and `fn `preflightCreate`` PREFIXES.
+ * Prefix invalidation is correct here because the write is chain-wide: every
+ * cached creator without an override moves with the default, and a preflight
+ * result is exactly the thing that flips between allowed and
+ * `UpgradeabilityNotAllowedError`.
+ *
+ * @example
+ * const setDefault = useSetDefaultUpgradeable();
+ * await setDefault.mutateAsync({ allowed: false });
+ *
+ * @alpha
+ */
+export declare function useSetDefaultUpgradeable(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetDefaultUpgradeableArgs>;

package/dist/fhe-airdrop/advanced/react/useSetEcdsaImplementation.d.ts

@@ -0,0 +1,34 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetEcdsaImplementationArgs extends WriteAccountOverride {
+    /** The new ECDSA implementation. The zero address reverts. */
+    implementation: Address;
+}
+/**
+ * Point future `createEcdsaAirdrop*` calls at a new ECDSA implementation.
+ *
+ * Requires `IMPL_MANAGER_ROLE`. Deployed instances are untouched - a clone
+ * stays bound to the implementation live when it was created.
+ *
+ * **Moving this pointer moves every future predicted address.** Any campaign
+ * plan built before this write is stale, and on an immutable-root instance
+ * its entries would be unclaimable; that is what `PredictionDriftError`
+ * exists to catch.
+ *
+ * **Invalidates:** `useFactoryImplementations` (fn `"implementations"`), plus
+ * the fn `"getEcdsaInitCodeHash"`, `"predictEcdsaAirdropAddress"` and
+ * ``preflightCreate`` PREFIXES - every cached args combination of each,
+ * because the init-code hash, the predicted address and the create preflight
+ * all shift together with the pointer. Invalidating the predictions is what
+ * stops a mounted UI offering a dead address.
+ *
+ * @example
+ * const setEcdsaImpl = useSetEcdsaImplementation();
+ * await setEcdsaImpl.mutateAsync({ implementation: newEcdsaImpl });
+ *
+ * @alpha
+ */
+export declare function useSetEcdsaImplementation(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetEcdsaImplementationArgs>;

package/dist/fhe-airdrop/advanced/react/useSetFeeCollector.d.ts

@@ -0,0 +1,27 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetFeeCollectorArgs extends WriteAccountOverride {
+    /** Where accrued claim-fee ETH withdraws to. The zero address reverts. */
+    feeCollector: Address;
+}
+/**
+ * Redirect where the factory's accrued claim-fee ETH withdraws to.
+ *
+ * Requires `FEE_MANAGER_ROLE`. The headless factory method takes positional
+ * args, so this hook adapts its object-shaped variables to
+ * `setFeeCollector(feeCollector, account?)`.
+ *
+ * **Invalidates:** this factory's `useFactoryFees` entry (fn `"fees"`), which
+ * bundles `feeCollector` with `defaultGasFee`. Nothing else moves - deployed
+ * instances hold no copy of the collector.
+ *
+ * @example
+ * const setCollector = useSetFeeCollector();
+ * await setCollector.mutateAsync({ feeCollector: treasuryAddress });
+ *
+ * @alpha
+ */
+export declare function useSetFeeCollector(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetFeeCollectorArgs>;

package/dist/fhe-airdrop/advanced/react/useSetMerkleImplementation.d.ts

@@ -0,0 +1,30 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetMerkleImplementationArgs extends WriteAccountOverride {
+    /** The new Merkle implementation. The zero address reverts. */
+    implementation: Address;
+}
+/**
+ * Point future `createMerkleAirdrop*` calls at a new Merkle implementation.
+ *
+ * Requires `IMPL_MANAGER_ROLE`. Deployed instances are untouched.
+ *
+ * **Same prediction-drift hazard as {@link useSetEcdsaImplementation}, with a
+ * worse blast radius.** Merkle campaigns are commonly immutable-root: a plan
+ * whose entries were bound to an address predicted before this write has no
+ * on-chain repair, so re-plan rather than re-point.
+ *
+ * **Invalidates:** `useFactoryImplementations` (fn `"implementations"`), plus
+ * the fn `"getMerkleInitCodeHash"`, `"predictMerkleAirdropAddress"` and
+ * ``preflightCreate`` PREFIXES - every cached args combination of each.
+ *
+ * @example
+ * const setMerkleImpl = useSetMerkleImplementation();
+ * await setMerkleImpl.mutateAsync({ implementation: newMerkleImpl });
+ *
+ * @alpha
+ */
+export declare function useSetMerkleImplementation(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetMerkleImplementationArgs>;

package/dist/fhe-airdrop/advanced/react/useSetUpgradeabilityPolicy.d.ts

@@ -0,0 +1,31 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../../airdrop-base.js";
+import { type AirdropClientOptions } from "../../react/_shared.js";
+/** @alpha */
+export interface SetUpgradeabilityPolicyArgs extends WriteAccountOverride {
+    /** The creator the override applies to - not the admin sending the transaction. */
+    creator: Address;
+    /** Whether that creator may deploy `mode: "uups"`. */
+    allowed: boolean;
+}
+/**
+ * Override the factory's default upgradeability policy for one creator.
+ * Requires `UPGRADE_MANAGER_ROLE`.
+ *
+ * This is the write that flips whether that creator's next `mode: "uups"`
+ * create is refused with `UpgradeabilityNotAllowedError`.
+ *
+ * **Invalidates:** `fn "effectiveUpgradeable"` and
+ * `fn "upgradeabilityPolicy"` keyed on `args.creator` - the TARGET creator,
+ * never the sending admin - plus the `fn `preflightCreate`` PREFIX,
+ * which is keyed on the whole create payload rather than the creator alone
+ * and so cannot be narrowed here.
+ *
+ * @example
+ * const setPolicy = useSetUpgradeabilityPolicy();
+ * await setPolicy.mutateAsync({ creator, allowed: true });
+ *
+ * @alpha
+ */
+export declare function useSetUpgradeabilityPolicy(options?: AirdropClientOptions): UseMutationResult<Hex, Error, SetUpgradeabilityPolicyArgs>;

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

@@ -588,6 +588,14 @@ export declare class AirdropBaseClient {
     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.

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

@@ -46,12 +46,45 @@ export declare function validateCampaignRecipients(recipients: readonly Campaign
  * pattern as `buildMerkleTreeInternal` in `./merkle-tree.js`.
  */
 export declare function validateCampaignRecipientsInternal(recipients: readonly CampaignRecipient[], method: string): void;
+/**
+ * Who will submit the claims, for every builder that encrypts a roster.
+ *
+ * Follows the same shared-option pattern as `WriteAccountOverride`, because the choice
+ * applies identically to all four builders and is frozen once the root is published.
+ *
+ * @alpha
+ */
+export interface CampaignSubmitterOption {
+    /**
+     * The single address that will send every `claim` in this campaign.
+     *
+     * Omit for a **self-claim** campaign: each recipient's input is bound to that
+     * recipient, one relayer request each, and only they can claim.
+     *
+     * Set it for a **relayed** campaign: the whole roster is bound to this one address and
+     * batched, so a single `inputProof` covers up to 32 recipients and only this address
+     * can submit. That batching is the point — one proof cannot be bound to many
+     * addresses, so per-recipient binding and batching are mutually exclusive.
+     *
+     * An input ciphertext packs at most 2048 bits, so a `euint64` roster is chunked at 32
+     * recipients per request; a longer roster simply issues more requests. Nothing about a
+     * claim changes, since every chunk's proof is bound to the same submitter.
+     *
+     * Either way the leaf still commits each recipient's own `account`, so payout and
+     * accounting are unaffected by who submits.
+     *
+     * **Frozen at publication.** An FHEVM handle encodes its `(instance, userAddress)`
+     * binding, so re-pointing a leaf at a different submitter means re-encrypting, which
+     * changes the handle and therefore the root. Choose before publishing, not after.
+     */
+    submitter?: Address;
+}
 /**
  * Inputs for {@link buildMerkleCampaign}.
  *
  * @alpha
  */
-export interface BuildMerkleCampaignArgs {
+export interface BuildMerkleCampaignArgs extends CampaignSubmitterOption {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     recipients: readonly CampaignRecipient[];
@@ -63,7 +96,9 @@ export interface BuildMerkleCampaignArgs {
  * @alpha
  */
 export interface EncryptedCampaignLeaf extends MerkleLeafInput {
-    /** The KMS input proof binding `handle` to `(instance, recipient)`. Required at claim time, unused by the tree. */
+    /** The only address that can submit this leaf — what `handle`/`inputProof` are bound to. */
+    boundTo: Address;
+    /** The KMS input proof binding `handle` to `(instance, boundTo)`. Required at claim time, unused by the tree. */
     inputProof: Hex;
 }
 /**
@@ -71,7 +106,7 @@ export interface EncryptedCampaignLeaf extends MerkleLeafInput {
  *
  * @alpha
  */
-export interface EncryptCampaignAmountsArgs {
+export interface EncryptCampaignAmountsArgs extends CampaignSubmitterOption {
     /** The LIVE `MerkleConfidentialAirdrop` instance every input is bound to. Not the factory, not the implementation. */
     instance: Address;
     recipients: readonly CampaignRecipient[];
@@ -84,17 +119,17 @@ export interface EncryptCampaignAmountsArgs {
  * 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.
+ * **Request count follows `submitter`.** Omitted: one relayer request per recipient,
+ * issued concurrently, each bound to that recipient. Set: one batched request per 32
+ * recipients (the 2048-bit input-ciphertext limit), every leaf claimable only by that
+ * submitter.
  *
  * **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.
+ * @returns One `{ account, boundTo, 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`.
  *
@@ -106,8 +141,9 @@ export interface EncryptCampaignAmountsArgs {
  */
 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.
+ * Encrypt every recipient's cumulative total, then build the tree those ciphertexts
+ * belong to. Binding follows `submitter`: omitted, each input is bound to its own
+ * recipient; set, the whole roster is bound to that one submitter.
  *
  * 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
@@ -124,10 +160,9 @@ export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs)
  * 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.
+ * **Relayer load follows `submitter`.** A self-claim roster fans out one request per
+ * recipient; a relayed roster issues one per 32. Either way, split the roster across
+ * calls 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
@@ -146,17 +181,17 @@ export declare function encryptCampaignAmounts(args: EncryptCampaignAmountsArgs)
  *   encryptor,
  * });
  * await airdrop.setMerkleRoot({ newRoot: root });
- * // then hand `entries[i]` to `entries[i].recipient`, out of band
+ * // then hand `entries[i]` to `entries[i].account`, out of band
  *
  * @alpha
  */
-export declare function buildMerkleCampaign({ instance, recipients, encryptor, }: BuildMerkleCampaignArgs): Promise<BuiltCampaign>;
+export declare function buildMerkleCampaign({ instance, recipients, encryptor, submitter, }: BuildMerkleCampaignArgs): Promise<BuiltCampaign>;
 /**
  * Inputs for {@link planMerkleCampaign}.
  *
  * @alpha
  */
-export interface PlanMerkleCampaignArgs {
+export interface PlanMerkleCampaignArgs extends CampaignSubmitterOption {
     factory: ConfidentialAirdropFactoryClient;
     /** The exact params the subsequent `createMerkleAirdrop` will use, except `merkleRoot` — supply the planned root there. */
     params: MerkleAirdropParams;
@@ -236,13 +271,13 @@ export interface PlannedCampaign extends BuiltCampaign {
  *
  * @alpha
  */
-export declare function planMerkleCampaign({ factory, params, mode, creator, userSalt, recipients, encryptor, }: PlanMerkleCampaignArgs): Promise<PlannedCampaign>;
+export declare function planMerkleCampaign({ factory, params, mode, creator, userSalt, recipients, encryptor, submitter, }: PlanMerkleCampaignArgs): Promise<PlannedCampaign>;
 /**
  * Inputs for {@link rotateMerkleRoot}.
  *
  * @alpha
  */
-export interface RotateMerkleRootArgs extends WriteAccountOverride {
+export interface RotateMerkleRootArgs extends WriteAccountOverride, CampaignSubmitterOption {
     /** 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. */
@@ -276,6 +311,12 @@ export interface RotatedCampaign extends BuiltCampaign {
  * 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.
  *
+ * **`submitter` is not remembered across rotations.** It is read from THIS call, not from
+ * the campaign being replaced, so omitting it on a rotation rebuilds a relayed campaign as
+ * a self-claim one - every new entry becomes claimable only by its own recipient, and the
+ * relayer that was settling for them can no longer submit anything. Pass the same
+ * `submitter` again to keep a relayed campaign relayed.
+ *
  * Requires `MERKLE_ADMIN_ROLE` on the instance and an instance created with
  * `isMerkleRootMutable: true`.
  *
@@ -294,4 +335,4 @@ export interface RotatedCampaign extends BuiltCampaign {
  *
  * @alpha
  */
-export declare function rotateMerkleRoot({ airdrop, recipients, encryptor, account, }: RotateMerkleRootArgs): Promise<RotatedCampaign>;
+export declare function rotateMerkleRoot({ airdrop, recipients, encryptor, submitter, account, }: RotateMerkleRootArgs): Promise<RotatedCampaign>;

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

@@ -3,7 +3,7 @@
  *
  * @alpha
  */
-export declare const AIRDROP_CONTRACTS_COMMIT = "8e5b144bdbcdf35b9f36b62f5257d795bf954e8e";
+export declare const AIRDROP_CONTRACTS_COMMIT = "7175ac82f467f0f88c05aba1a4536892999b4251";
 /**
  * Deployment shell selected at create time. Mirrors the contract's `DeploymentMode` enum
  * (`IConfidentialAirdropTypes.sol`): `enum DeploymentMode { Clone, UUPS }`.

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

@@ -65,6 +65,34 @@ export declare class NonStockWrapperError extends TokenOpsSdkError {
         cause?: unknown;
     });
 }
+/**
+ * A third party tried to redirect someone else's Merkle payout.
+ *
+ * `to` may differ from the claim identity only when the submitter IS that identity, so a
+ * relayer must leave `to` at `account` (or omit it). Raised by the SDK before the write
+ * and mapped from the contract's `UnauthorizedRedirect` revert, since the rule is decidable
+ * from the arguments alone — same two-producer shape as {@link NonStockWrapperError}.
+ *
+ * Carries all three addresses because the relation is the error: `to` on its own is a
+ * perfectly good address, and blaming it alone would be misleading.
+ *
+ * @alpha
+ */
+export declare class UnauthorizedRedirectError extends TokenOpsSdkError {
+    readonly name = "UnauthorizedRedirectError";
+    readonly context: {
+        constraint: "merkle-third-party-redirect";
+        account?: Address;
+        to?: Address;
+        submitter?: Address;
+    };
+    constructor(args?: {
+        account?: Address;
+        to?: Address;
+        submitter?: Address;
+        cause?: unknown;
+    });
+}
 /**
  * The two campaign variants, as used to label a prediction guard's context.
  *

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

@@ -207,6 +207,11 @@ export interface ClaimPreflightTarget {
      * the two blocked the claim.
      */
     paused(): Promise<boolean>;
+    /**
+     * Create-time flag; `claimAndUnwrap` reverts `TokenNotUnwrappable` when false. Optional
+     * so a hand-rolled target stays valid — the unwrap blocker is simply not reported then.
+     */
+    unwrappable?: () => Promise<boolean>;
     /** Present on `EcdsaAirdropClient` only. */
     isSignatureValid?: (args: {
         recipient: Address;
@@ -237,14 +242,51 @@ export interface EcdsaClaimPreflightSignature {
  */
 export interface PreflightClaimArgs {
     airdrop: ClaimPreflightTarget;
-    /** The account that will send the claim - not the payout destination. */
+    /**
+     * The account that will SEND the claim, and therefore pays the exact-equality gas fee.
+     * On a relayed Merkle claim this is the relayer, not the entitled account.
+     */
     claimant: Address;
+    /**
+     * Merkle campaigns only: the claim identity, when it is not the submitter. Defaults to
+     * `claimant`. Supplying it enables the two argument-relation checks the contract makes
+     * before any FHE work — the zero identity and the third-party redirect rule.
+     */
+    account?: Address | undefined;
+    /** The payout destination, if one will be passed. Omitted means "defaults to `account`". */
+    to?: Address | undefined;
+    /**
+     * Set for `claimAndUnwrap`, which has no `account` parameter and is always submitted for
+     * the caller — so a claim identity that is not the submitter can never settle through it.
+     */
+    entrypoint?: "claim" | "claimAndUnwrap" | undefined;
     /**
      * ECDSA campaigns only. Supplied together with a client that exposes
      * `isSignatureValid`, it adds the authorisation check to the report.
      */
     signature?: EcdsaClaimPreflightSignature | undefined;
 }
+/**
+ * The three argument-relation rules the Merkle claim path enforces before it touches the
+ * coprocessor. All are decidable from the arguments alone, so both `preflightClaim` and
+ * the client's own write path run them — no RPC, no chance of a wasted fee.
+ *
+ * @param account The claim identity (`claim`'s leading argument).
+ * @param submitter The address that will send the transaction.
+ * @param boundTo The address the entry's input proof is bound to, when known.
+ * @param to The payout destination, if one will be passed.
+ * @param entrypoint `claimAndUnwrap` is self-only; `claim` accepts a third-party submitter.
+ * @throws {@link InvalidArgumentError} on a zero `account`, a proof bound to another address, or a relayed `claimAndUnwrap`.
+ * @throws {@link UnauthorizedRedirectError} when a third party tries to redirect payout.
+ */
+export declare function assertMerkleClaimIdentity(args: {
+    method: string;
+    account: Address;
+    submitter: Address;
+    boundTo?: Address | undefined;
+    to?: Address | undefined;
+    entrypoint?: "claim" | "claimAndUnwrap" | undefined;
+}): void;
 /**
  * Report what would stop `claim` / `claimAndUnwrap` right now, without sending
  * anything.
@@ -252,7 +294,9 @@ export interface PreflightClaimArgs {
  * Checks the chain, the pause flag, the claim window on both ends, whether the
  * claimant can cover the instance's exact-equality gas fee, and - for an ECDSA
  * campaign given `signature` - whether the authorisation is currently valid and
- * unconsumed.
+ * unconsumed. Given `account` or `entrypoint`, it also checks the Merkle claim path's
+ * three argument relations: the zero identity, the third-party redirect rule, and
+ * `claimAndUnwrap`'s self-only constraint.
  *
  * The pause is read on its own rather than through `isClaimWindowActive()`:
  * that read ANDs the pause and the window together, so a `false` from it