@tokenops/sdk 1.5.1 → 2.0.0-alpha.1

package/dist/fhe/operators.d.ts

@@ -14,6 +14,7 @@ import { type SdkTelemetry } from "../core/telemetry.js";
  *
  * `uint48` upper bound (`2**48 - 1 ≈ 8.9e+14`) is comfortably past year 9999
  * in unix seconds, so a "far-future" deadline is structurally safe.
+ * @public
  */
 export declare const ERC7984_SET_OPERATOR_ABI: readonly [{
     readonly type: "function";
@@ -35,8 +36,10 @@ export declare const ERC7984_SET_OPERATOR_ABI: readonly [{
  * about expiry — typical for local-chain dev loops and end-to-end fixture
  * setup. For production flows, scope the deadline to the expected operation
  * window (e.g. `Date.now()/1000 + 3600`).
+ * @public
  */
 export declare const ERC7984_OPERATOR_MAX_DEADLINE: bigint;
+/** @public */
 export interface SetOperatorArgs {
     /** Read-only viem client for receipt waiting. */
     publicClient: PublicClient;
@@ -108,16 +111,17 @@ export interface SetOperatorArgs {
  * await setOperator({
  *   publicClient,
  *   walletClient,
- *   token: DEPLOYED_ADDRESSES.tokens.testConfidential[31337]!,
+ *   token: "0xYourToken", // ERC-7984 token address
  *   spender: manager,
  *   // deadline defaults to ERC7984_OPERATOR_MAX_DEADLINE (forever).
  * });
  *
- * // Now safe to call manager.createVesting / factory.fundConfidentialAirdrop / etc.
+ * // Now safe to call manager.createVesting / factory.fundAirdrop / etc.
  * ```
  *
  * @throws {@link TokenOpsContractError} if the writeContract or receipt-wait
  *   step throws. The original viem error is attached as the cause.
+ * @public
  */
 export declare function setOperator(args: SetOperatorArgs): Promise<Hex>;
 /**
@@ -125,6 +129,7 @@ export declare function setOperator(args: SetOperatorArgs): Promise<Hex>;
  * minus the `deadline` field — revoke is a fixed `until=0` call that cannot
  * accept a non-zero deadline (the ERC-7984 contract treats `0` as the revoke
  * convention; any non-zero `until` would be a re-grant, not a revoke).
+ * @public
  */
 export interface RevokeOperatorArgs {
     /** Read-only viem client for receipt waiting. */
@@ -177,7 +182,7 @@ export interface RevokeOperatorArgs {
  * await revokeOperator({
  *   publicClient,
  *   walletClient,
- *   token: DEPLOYED_ADDRESSES.tokens.testConfidential[31337]!,
+ *   token: "0xYourToken", // ERC-7984 token address
  *   spender: staleManager, // old manager clone after deploying a new one
  * });
  * // `staleManager` can no longer call `confidentialTransferFrom` against
@@ -186,5 +191,157 @@ export interface RevokeOperatorArgs {
  *
  * @throws {@link TokenOpsContractError} if the writeContract or receipt-wait
  *   step throws. The original viem error is attached as the cause.
+ * @public
  */
 export declare function revokeOperator(args: RevokeOperatorArgs): Promise<Hex>;
+/**
+ * Arguments for {@link isOperator}. Read-only — no wallet required.
+ *
+ * @public
+ */
+export interface IsOperatorArgs {
+    /** Read-only viem client the `isOperator` view call goes through. */
+    publicClient: PublicClient;
+    /** ERC-7984 token contract address. */
+    token: Address;
+    /** Account that owns the tokens (the operator-authorization granter). */
+    holder: Address;
+    /**
+     * Address whose operator status is being checked — typically a manager
+     * clone (`/fhe-vesting`), an airdrop clone/factory (`/fhe-airdrop`), or
+     * the disperse singleton (`/fhe-disperse`).
+     */
+    spender: Address;
+    /** Optional telemetry sink — span emits as `fhe.isOperator`. */
+    telemetry?: SdkTelemetry;
+}
+/**
+ * Check whether `spender` is currently an authorized ERC-7984 operator for
+ * `holder` on `token`. Read-only sibling of {@link setOperator} — the
+ * contract-side check is `until >= block.timestamp`, so an expired grant
+ * reads `false` here without any revoke transaction having happened.
+ *
+ * Use this to gate UX ("Approve operator" button vs "Create vesting" button)
+ * or as a cheap pre-check before flows that would otherwise fail with
+ * {@link OperatorNotApprovedError} — the SDK's mapping of the on-chain
+ * `ERC7984UnauthorizedSpender` revert, whose message is the canonical
+ * {@link OPERATOR_NOT_APPROVED_REMEDIATION} copy. For a check-then-set in
+ * one call, see {@link ensureOperator}.
+ *
+ * @example
+ * ```ts
+ * import { isOperator } from "@tokenops/sdk/fhe";
+ *
+ * const authorized = await isOperator({
+ *   publicClient,
+ *   token,
+ *   holder: account.address,
+ *   spender: manager,
+ * });
+ * if (!authorized) {
+ *   // prompt the user to run setOperator / ensureOperator first
+ * }
+ * ```
+ *
+ * @throws {@link TokenOpsContractError} if the read call itself fails (RPC
+ *   error, non-ERC-7984 token). The original viem error is attached as the
+ *   cause.
+ * @public
+ */
+export declare function isOperator(args: IsOperatorArgs): Promise<boolean>;
+/**
+ * Arguments for {@link ensureOperator}. Same shape as {@link SetOperatorArgs}
+ * except `deadline` is **required**: `ensureOperator` only sends a
+ * transaction when the authorization is missing, so the expiry it would
+ * grant must be an explicit caller decision — the SDK refuses to default a
+ * security-sensitive approval window (a silent
+ * {@link ERC7984_OPERATOR_MAX_DEADLINE} would grant "forever").
+ * @public
+ */
+export interface EnsureOperatorArgs {
+    /** Read-only viem client for the `isOperator` pre-check + receipt waiting. */
+    publicClient: PublicClient;
+    /** Wallet client used to send the `setOperator` call (only when needed). */
+    walletClient: WalletClient;
+    /**
+     * Account that owns the tokens. Same `Account | Address` semantics and
+     * fallback hierarchy as {@link SetOperatorArgs} — also used to derive the
+     * `holder` for the read-side `isOperator` pre-check.
+     */
+    account?: Account | Address;
+    /** ERC-7984 token contract address. */
+    token: Address;
+    /** Address being authorized to pull tokens. */
+    spender: Address;
+    /**
+     * `uint48` unix timestamp after which the operator authorization expires.
+     * Required — scope it to the expected operation window (e.g.
+     * `BigInt(Math.floor(Date.now() / 1000) + 3600)` for one hour). Pass
+     * {@link ERC7984_OPERATOR_MAX_DEADLINE} only when you explicitly want a
+     * never-expiring grant (local dev loops, test fixtures).
+     */
+    deadline: bigint;
+    /**
+     * If `true` (default), waits for the transaction to be mined before
+     * returning. Only relevant when a transaction is actually sent.
+     */
+    waitForReceipt?: boolean;
+    /** Optional telemetry sink — span emits as `fhe.ensureOperator`. */
+    telemetry?: SdkTelemetry;
+}
+/**
+ * Result of {@link ensureOperator}.
+ *
+ * @public
+ */
+export interface EnsureOperatorResult {
+    /**
+     * `true` when the authorization was already in place and no transaction
+     * was sent; `false` when this call performed the `setOperator` write.
+     */
+    alreadyOperator: boolean;
+    /**
+     * Transaction hash of the `setOperator` call, or `null` when no
+     * transaction was needed (`alreadyOperator === true`).
+     */
+    hash: Hex | null;
+}
+/**
+ * Idempotent operator authorization: check {@link isOperator} first and call
+ * {@link setOperator} only when the grant is missing. The no-op path sends
+ * no transaction and costs one `eth_call`.
+ *
+ * This is the recommended pre-step before any flow that pulls tokens from
+ * the caller's balance (`createVesting` / `batchCreateVesting`,
+ * `fundAirdrop` / `createAndFund{Ecdsa,Merkle}Airdrop`, disperse
+ * registration) — skipping it fails with {@link OperatorNotApprovedError},
+ * the SDK's mapping of the on-chain `ERC7984UnauthorizedSpender` revert,
+ * whose message is the canonical {@link OPERATOR_NOT_APPROVED_REMEDIATION}
+ * copy.
+ *
+ * **Note on expiry:** the pre-check only tells you the grant is currently
+ * active, not until when. If an existing grant expires mid-flow,
+ * `ensureOperator` will not have refreshed it — pass a fresh
+ * {@link setOperator} call instead when you need to extend a window.
+ *
+ * @example
+ * ```ts
+ * import { ensureOperator } from "@tokenops/sdk/fhe";
+ *
+ * const oneHour = BigInt(Math.floor(Date.now() / 1000) + 3600);
+ * const { alreadyOperator, hash } = await ensureOperator({
+ *   publicClient,
+ *   walletClient,
+ *   token,
+ *   spender: manager,
+ *   deadline: oneHour,
+ * });
+ * // Now safe to call manager.createVesting / factory.fundAirdrop / etc.
+ * ```
+ *
+ * @throws {@link TokenOpsContractError} if no holder account can be
+ *   resolved, if `deadline` is outside `(0, 2**48 - 1]`, or if the
+ *   read/write/receipt step fails.
+ * @public
+ */
+export declare function ensureOperator(args: EnsureOperatorArgs): Promise<EnsureOperatorResult>;

package/dist/fhe/react/index.cjs

@@ -1,7 +1,13 @@
 'use strict';
 
+var chunk7AFPOE7N_cjs = require('../../chunk-7AFPOE7N.cjs');
+require('../../chunk-ZQUE2B3Q.cjs');
+require('../../chunk-KFRDLKMA.cjs');
+require('../../chunk-FWHYQZ5E.cjs');
+require('../../chunk-JK4XMMKM.cjs');
 require('../../chunk-66IHPTOK.cjs');
 var chunk67OV5CX2_cjs = require('../../chunk-67OV5CX2.cjs');
+require('../../chunk-VJKZWYYJ.cjs');
 var react = require('react');
 
 function resolveUserDecryptor(source) {
@@ -83,6 +89,14 @@ function serializableSlice(v) {
   return out;
 }
 
+Object.defineProperty(exports, "useEnsureOperator", {
+  enumerable: true,
+  get: function () { return chunk7AFPOE7N_cjs.useEnsureOperator; }
+});
+Object.defineProperty(exports, "useIsOperator", {
+  enumerable: true,
+  get: function () { return chunk7AFPOE7N_cjs.useIsOperator; }
+});
 Object.defineProperty(exports, "TokenOpsContractError", {
   enumerable: true,
   get: function () { return chunk67OV5CX2_cjs.TokenOpsContractError; }

package/dist/fhe/react/index.d.cts

@@ -7,4 +7,6 @@
  * `EncryptedHandle` return value).
  */
 export { useDecryptedHandle, type UseDecryptedHandleOptions, type UseDecryptedHandleResult, type UserDecryptor, type UserDecryptorSource, } from "./use-decrypted-handle.js";
+export { useIsOperator, type UseIsOperatorOptions } from "./useIsOperator.js";
+export { useEnsureOperator, type UseEnsureOperatorOptions, type EnsureOperatorVariables, } from "./useEnsureOperator.js";
 export { TokenOpsSdkError, isTokenOpsSdkError, TokenOpsValidationError, TokenOpsContractError, } from "../../core/errors.js";

package/dist/fhe/react/index.d.ts

@@ -7,4 +7,6 @@
  * `EncryptedHandle` return value).
  */
 export { useDecryptedHandle, type UseDecryptedHandleOptions, type UseDecryptedHandleResult, type UserDecryptor, type UserDecryptorSource, } from "./use-decrypted-handle.js";
+export { useIsOperator, type UseIsOperatorOptions } from "./useIsOperator.js";
+export { useEnsureOperator, type UseEnsureOperatorOptions, type EnsureOperatorVariables, } from "./useEnsureOperator.js";
 export { TokenOpsSdkError, isTokenOpsSdkError, TokenOpsValidationError, TokenOpsContractError, } from "../../core/errors.js";

package/dist/fhe/react/index.js

@@ -1,6 +1,12 @@
+export { useEnsureOperator, useIsOperator } from '../../chunk-AXIPOR3C.js';
+import '../../chunk-FT4LNBOS.js';
+import '../../chunk-4TSDNZQ3.js';
+import '../../chunk-7VELUOMI.js';
+import '../../chunk-ZA673I3O.js';
 import '../../chunk-KWFFIJYX.js';
 import { TokenOpsValidationError } from '../../chunk-QBJ7O2B4.js';
 export { TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, isTokenOpsSdkError } from '../../chunk-QBJ7O2B4.js';
+import '../../chunk-Q2GP5UDC.js';
 import { useState, useRef, useEffect } from 'react';
 
 function resolveUserDecryptor(source) {

package/dist/fhe/react/useEnsureOperator.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Cross-product mutation hook over {@link ensureOperator} — check-then-set
+ * operator authorization that sends no transaction when the grant already
+ * exists.
+ *
+ * Lives in `/fhe/react` (not a product subpath) because the operator
+ * prerequisite is identical across all three product flows; the product
+ * `react/` barrels re-export it for discoverability.
+ */
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Account, Address } from "viem";
+import type { SdkTelemetry } from "../../core/telemetry.js";
+import { type EnsureOperatorResult } from "../operators.js";
+/** Hook-level options for {@link useEnsureOperator}. */
+export interface UseEnsureOperatorOptions {
+    /** Override the chain id used for client resolution. */
+    chainId?: number | undefined;
+    /** Optional telemetry adapter — forwarded to the headless helper. */
+    telemetry?: SdkTelemetry | undefined;
+}
+/** Per-mutation variables for {@link useEnsureOperator}. */
+export interface EnsureOperatorVariables {
+    /** ERC-7984 token contract address. */
+    token: Address;
+    /** Address being authorized to pull tokens. */
+    spender: Address;
+    /**
+     * `uint48` unix timestamp after which the authorization expires. Required
+     * — the expiry window is an explicit caller decision (see
+     * {@link ensureOperator}). Pass `ERC7984_OPERATOR_MAX_DEADLINE` only when
+     * you explicitly want a never-expiring grant.
+     */
+    deadline: bigint;
+    /** Override the from-account; defaults to the connected wallet's account. */
+    account?: Account | Address;
+    /** If `true` (default), waits for the transaction to be mined. */
+    waitForReceipt?: boolean;
+}
+/**
+ * Ensure `spender` is an ERC-7984 operator for the connected account on
+ * `token`, sending a `setOperator` transaction only when the grant is
+ * missing. Resolves to `{ alreadyOperator, hash }` — `hash` is `null` on
+ * the no-op path.
+ *
+ * This is the mutation half of the operator-prerequisite pair; use
+ * {@link useIsOperator} for the read side, and invalidate/refetch it after
+ * this mutation succeeds.
+ *
+ * @example
+ * ```tsx
+ * const ensure = useEnsureOperator();
+ * const oneHour = BigInt(Math.floor(Date.now() / 1000) + 3600);
+ * ensure.mutate({ token, spender: manager, deadline: oneHour });
+ * ```
+ */
+export declare function useEnsureOperator(options?: UseEnsureOperatorOptions): UseMutationResult<EnsureOperatorResult, Error, EnsureOperatorVariables>;

package/dist/fhe/react/useIsOperator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cross-product query hook over {@link isOperator} — "is `spender` currently
+ * an authorized ERC-7984 operator for `holder` on `token`?".
+ *
+ * Lives in `/fhe/react` (not a product subpath) because the operator
+ * prerequisite is identical across all three product flows; the product
+ * `react/` barrels re-export it for discoverability.
+ */
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import type { SdkTelemetry } from "../../core/telemetry.js";
+/** Options accepted by {@link useIsOperator}. */
+export interface UseIsOperatorOptions {
+    /** ERC-7984 token contract address. Query stays disabled while `undefined`. */
+    token?: Address | undefined;
+    /**
+     * Address whose operator status is being checked — typically a manager
+     * clone, an airdrop factory/clone, or the disperse singleton. Query stays
+     * disabled while `undefined`.
+     */
+    spender?: Address | undefined;
+    /**
+     * Account that owns the tokens. Defaults to the connected wallet's
+     * account. Query stays disabled while neither is available.
+     */
+    holder?: Address | undefined;
+    /** Override the chain id used for client resolution. */
+    chainId?: number | undefined;
+    /** Set `false` to pause the query without unmounting. Defaults to `true`. */
+    enabled?: boolean | undefined;
+    /** Optional telemetry adapter — forwarded to the headless helper. */
+    telemetry?: SdkTelemetry | undefined;
+}
+/**
+ * Read `spender`'s ERC-7984 operator status for `holder` on `token`.
+ *
+ * Typical use: gate the "create" call-to-action behind the operator
+ * prerequisite so builders never hit {@link OperatorNotApprovedError} — the
+ * SDK's mapping of the on-chain `ERC7984UnauthorizedSpender` revert, whose
+ * message is the canonical {@link OPERATOR_NOT_APPROVED_REMEDIATION} copy:
+ *
+ * @example
+ * ```tsx
+ * const { data: authorized } = useIsOperator({ token, spender: manager });
+ * return authorized
+ *   ? <CreateVestingButton />
+ *   : <ApproveOperatorButton />; // wire to useEnsureOperator
+ * ```
+ *
+ * After a successful {@link useEnsureOperator} / `setOperator` mutation,
+ * invalidate this query (its key starts with
+ * `["tokenops-sdk", "fhe", "isOperator", ...]`) or refetch it.
+ */
+export declare function useIsOperator(options?: UseIsOperatorOptions): UseQueryResult<boolean, Error>;

package/dist/fhe/sepolia-encryptor-web.d.ts

@@ -3,9 +3,10 @@ import type { Encryptor } from "../fhe-vesting/encryption.js";
 import { type EncryptorInitPhase, type SepoliaEncryptorLogger } from "./sepolia-encryptor.js";
 /**
  * Configuration for {@link createSepoliaEncryptorWeb}. Minimal by design:
- * the browser path doesn't expose worker pool sizing or storage knobs (the
- * Web Worker is single-threaded by default, and `RelayerWeb` already
- * defaults to `IndexedDBStorage` for FHE artifact caching).
+ * the browser path doesn't expose storage knobs (`RelayerWeb` already
+ * defaults to `IndexedDBStorage` for FHE artifact caching). Worker-pool
+ * sizing is the one opt-in performance knob — see `threads`; the default
+ * stays single-threaded so no special headers are required.
  */
 export interface CreateSepoliaEncryptorWebOpts {
     /** Viem `PublicClient` — used only to resolve the chain id for the
@@ -68,6 +69,20 @@ export interface CreateSepoliaEncryptorWebOpts {
      * swallowed so a UI observer can never break encryption.
      */
     onPhase?: (phase: EncryptorInitPhase) => void;
+    /**
+     * Opt-in WASM worker-pool size for multi-threaded encryption (forwarded
+     * to `RelayerWeb`'s config). `4`–`8` gives ~2–3× faster encryption but
+     * requires the page to be **cross-origin isolated** — headers
+     * `Cross-Origin-Opener-Policy: same-origin` and
+     * `Cross-Origin-Embedder-Policy: require-corp` — without which browsers
+     * hide `SharedArrayBuffer` and encryption silently falls back to
+     * single-threaded. The SDK logs a loud warning when `threads > 1` is set
+     * on a non-isolated page.
+     *
+     * Omit for the default single-threaded worker — no special headers
+     * required.
+     */
+    threads?: number;
 }
 /**
  * Returned by {@link createSepoliaEncryptorWeb}. Same structural

package/dist/fhe/types.d.ts

@@ -13,6 +13,7 @@ import type { Hex } from "viem";
  * The current SDK only produces uint64 ciphertexts. If a future version
  * adds encryption helpers for other widths (e.g. `encryptUint128`), this
  * type may be specialised; existing uint64 usage will keep type-checking.
+ * @public
  */
 export interface EncryptedInput {
     handle: Hex;
@@ -24,6 +25,7 @@ export interface EncryptedInput {
  * encryptor returns from a batched `encrypt({ values: [...] })` call.
  *
  * `handles[i]` corresponds to the i-th plaintext value passed in.
+ * @public
  */
 export interface EncryptedInputs {
     handles: Hex[];
@@ -37,6 +39,7 @@ export interface EncryptedInputs {
  * Pass `handle` to the Zama relayer's `userDecrypt` to obtain the plaintext.
  * `hash` is the tx that committed the persistent ACL grant — surface it if
  * your UI needs to show the receipt.
+ * @public
  */
 export interface EncryptedViewResult {
     handle: Hex;
@@ -48,15 +51,18 @@ export interface EncryptedViewResult {
  * match the rest of the SDK or the on-chain calldata layout (the contracts
  * accept `bytes inputProof`). This alias points at the corrected shape and
  * will be removed in the next major.
+ * @public
  */
 export type EncryptedInput64 = EncryptedInput;
 /**
  * @deprecated Use `Hex` from `viem` directly. This alias added no narrowing
  * beyond `Hex` and will be removed in the next major.
+ * @public
  */
 export type EncryptedHandle = Hex;
 /**
  * @deprecated Use `Hex` from `viem` directly. This alias added no narrowing
  * beyond `Hex` and will be removed in the next major.
+ * @public
  */
 export type ExternalInputProof = Hex;