@tokenops/sdk 1.1.1 → 1.6.0

package/dist/fhe/index.js

@@ -1,11 +1,11 @@
-export { ERC7984_OPERATOR_MAX_DEADLINE, ERC7984_SET_OPERATOR_ABI, revokeOperator, setOperator } from '../chunk-WRCUDSUJ.js';
+export { ERC7984_OPERATOR_MAX_DEADLINE, ERC7984_SET_OPERATOR_ABI, ensureOperator, isOperator, revokeOperator, setOperator } from '../chunk-4KJ66YRH.js';
+export { FHE_SPLIT_DENOMINATOR, scaleRatio, share } from '../chunk-PD7ME2BT.js';
+export { ACL_ALLOWED_EVENT, FHEVM_ACL_ADDRESS_BY_CHAIN, getFhevmAclAddress, requireFhevmAclAddress } from '../chunk-YPYCWLYP.js';
 export { erc7984OperatorAbi } from '../chunk-7VELUOMI.js';
-export { FHE_SPLIT_DENOMINATOR, scaleRatio, share } from '../chunk-XSNLAS5M.js';
-export { ACL_ALLOWED_EVENT, FHEVM_ACL_ADDRESS_BY_CHAIN, getFhevmAclAddress, requireFhevmAclAddress } from '../chunk-FYQ2UW4T.js';
-import { normaliseAddress } from '../chunk-BE2AIZ3K.js';
+import { normaliseAddress } from '../chunk-46T67CE2.js';
+import { TokenOpsContractError } from '../chunk-DRSPMIZ7.js';
+export { AccessDeniedError, AlreadyInitializedError, BatchTooLargeError, ContractRevertError, DecryptionFailedError, DeploymentAddressUnavailableError, EncryptionFailedError, FeatureDisabledError, FheHandleNotAllowedError, InsufficientBalanceError, InsufficientFeeError, InsufficientGasFundsError, InvalidArgumentError, InvalidSignatureError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, NetworkError, OperatorNotApprovedError, PausedError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ReentrancyError, RelayerUnreachableError, SigningFailedError, TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../chunk-DRSPMIZ7.js';
 import { withTelemetry } from '../chunk-Q2GP5UDC.js';
-import { TokenOpsContractError } from '../chunk-IVE3QEGD.js';
-export { AccessDeniedError, AlreadyInitializedError, BatchTooLargeError, ContractRevertError, DecryptionFailedError, DeploymentAddressUnavailableError, EncryptionFailedError, FeatureDisabledError, FheHandleNotAllowedError, InsufficientBalanceError, InsufficientFeeError, InsufficientGasFundsError, InvalidArgumentError, InvalidSignatureError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, NetworkError, PausedError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ReentrancyError, RelayerUnreachableError, SigningFailedError, TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../chunk-IVE3QEGD.js';
 import { RelayerWeb, MainnetConfig, SepoliaConfig } from '@zama-fhe/sdk';
 
 // src/fhe/mock-encryptor.ts
@@ -22,7 +22,8 @@ async function requirePeerDep(spec, hint) {
     throw new Error(
       `@tokenops/sdk: peer dependency "${spec}" is required for createMockEncryptor.
   install it with: ${hint}
-  underlying error: ${String(err)}`
+  underlying error: ${String(err)}`,
+      { cause: err }
     );
   }
 }
@@ -302,12 +303,21 @@ async function requirePeerDep2(spec, hint) {
     throw new Error(
       `@tokenops/sdk: peer dependency "${spec}" is required for createSepoliaEncryptor.
   install it with: ${hint}
-  underlying error: ${String(err)}`
+  underlying error: ${String(err)}`,
+      { cause: err }
     );
   }
 }
 async function createSepoliaEncryptor(options = {}) {
   const chainId = options.chainId ?? SEPOLIA_CHAIN_ID;
+  const firePhase = (phase) => {
+    if (!options.onPhase) return;
+    try {
+      options.onPhase(phase);
+    } catch {
+    }
+  };
+  firePhase("initializing");
   const zamaSdkNode = await requirePeerDep2(
     "@zama-fhe/sdk/node",
     "pnpm add @zama-fhe/sdk@^3"
@@ -336,11 +346,29 @@ async function createSepoliaEncryptor(options = {}) {
     fheArtifactStorage: options.fheArtifactStorage,
     fheArtifactCacheTTL: options.fheArtifactCacheTTL
   });
+  let initState = "idle";
   return {
     instance,
     chainId,
     async encrypt({ values, contractAddress, userAddress }) {
-      return instance.encrypt({ values, contractAddress, userAddress });
+      const startedInit = initState === "idle";
+      if (startedInit) {
+        initState = "in-flight";
+        firePhase("downloading-params");
+      }
+      try {
+        const result = await instance.encrypt({ values, contractAddress, userAddress });
+        if (initState !== "ready") {
+          initState = "ready";
+          firePhase("ready");
+        }
+        return result;
+      } catch (err) {
+        if (startedInit && initState === "in-flight") {
+          initState = "idle";
+        }
+        throw err;
+      }
     },
     terminate() {
       instance.terminate();
@@ -374,10 +402,36 @@ function createSepoliaEncryptorWeb(opts) {
     },
     ...opts.logger
   } : void 0;
+  const firePhase = (phase) => {
+    if (!opts.onPhase) return;
+    try {
+      opts.onPhase(phase);
+    } catch {
+    }
+  };
+  firePhase("initializing");
+  const onStatusChange = opts.onPhase ? (status) => {
+    if (status === "initializing") {
+      firePhase("downloading-params");
+    } else if (status === "ready") {
+      firePhase("ready");
+    }
+  } : void 0;
+  if (opts.threads !== void 0 && opts.threads > 1) {
+    const isolated = globalThis.crossOriginIsolated === true;
+    if (!isolated) {
+      const warn = safeLogger?.warn ?? console.warn;
+      warn(
+        `@tokenops/sdk: createSepoliaEncryptorWeb({ threads: ${opts.threads} }) \u2014 this page is NOT cross-origin isolated, so SharedArrayBuffer is unavailable and encryption will run single-threaded. Serve \`Cross-Origin-Opener-Policy: same-origin\` + \`Cross-Origin-Embedder-Policy: require-corp\` to enable the worker pool, or omit \`threads\`.`
+      );
+    }
+  }
   const instance = new RelayerWeb({
     transports: { [chainId]: transportConfig },
     getChainId: () => Promise.resolve(chainId),
-    logger: safeLogger
+    logger: safeLogger,
+    onStatusChange,
+    ...opts.threads !== void 0 ? { threads: opts.threads } : {}
   });
   return Promise.resolve({
     instance,

package/dist/fhe/mock-erc7984.d.ts

@@ -76,12 +76,12 @@ export interface MintMockERC7984Result {
  *
  * @example
  * ```ts
- * import { mintMockERC7984, DEPLOYED_ADDRESSES } from "@tokenops/sdk";
+ * import { mintMockERC7984 } from "@tokenops/sdk/fhe";
  *
  * const { hash, blockNumber } = await mintMockERC7984({
  *   publicClient,
  *   walletClient,
- *   token: DEPLOYED_ADDRESSES.tokens.testConfidential[11155111]!,
+ *   token: "0xYourMockToken", // MockERC7984Token address
  *   to: walletClient.account!.address,
  *   amount: 1_000_000n,
  * });
@@ -119,12 +119,12 @@ export interface MockErc7984Client {
  *
  * @example
  * ```ts
- * import { createMockErc7984Client, DEPLOYED_ADDRESSES } from "@tokenops/sdk/fhe";
+ * import { createMockErc7984Client } from "@tokenops/sdk/fhe";
  *
  * const token = createMockErc7984Client({
  *   publicClient,
  *   walletClient,
- *   address: DEPLOYED_ADDRESSES.tokens.testConfidential[11155111]!,
+ *   address: "0xYourMockToken", // MockERC7984Token address
  * });
  *
  * await token.mint({ to: alice, amount: 1_000_000n });

package/dist/fhe/operators.d.ts

@@ -108,7 +108,7 @@ 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).
  * });
@@ -177,7 +177,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
@@ -188,3 +188,143 @@ export interface RevokeOperatorArgs {
  *   step throws. The original viem error is attached as the cause.
  */
 export declare function revokeOperator(args: RevokeOperatorArgs): Promise<Hex>;
+/** Arguments for {@link isOperator}. Read-only — no wallet required. */
+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.
+ */
+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").
+ */
+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}. */
+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`,
+ * `fundConfidentialAirdrop` / `createAndFundConfidentialAirdrop`, 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.fundConfidentialAirdrop / 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.
+ */
+export declare function ensureOperator(args: EnsureOperatorArgs): Promise<EnsureOperatorResult>;

package/dist/fhe/react/index.cjs

@@ -1,7 +1,12 @@
 'use strict';
 
-require('../../chunk-66IHPTOK.cjs');
-var chunk56UI7LUR_cjs = require('../../chunk-56UI7LUR.cjs');
+var chunkWOEETTH7_cjs = require('../../chunk-WOEETTH7.cjs');
+require('../../chunk-ZQUE2B3Q.cjs');
+require('../../chunk-4ZCXK4VI.cjs');
+require('../../chunk-FWHYQZ5E.cjs');
+require('../../chunk-VR3FREBX.cjs');
+var chunk2RNW4MIJ_cjs = require('../../chunk-2RNW4MIJ.cjs');
+require('../../chunk-VJKZWYYJ.cjs');
 var react = require('react');
 
 function resolveUserDecryptor(source) {
@@ -35,7 +40,7 @@ function useDecryptedHandle(opts) {
       setState({
         status: "error",
         value: void 0,
-        error: new chunk56UI7LUR_cjs.TokenOpsValidationError(
+        error: new chunk2RNW4MIJ_cjs.TokenOpsValidationError(
           "useDecryptedHandle: no `userDecryptor` resolved \u2014 pass `userDecryptor: () => useZamaSDK().relayer` (or an eager RelayerSDK / MockFhevmInstance).",
           { method: "useDecryptedHandle" }
         )
@@ -52,7 +57,7 @@ function useDecryptedHandle(opts) {
         });
         const plain = result[handleStr];
         if (plain === void 0) {
-          throw new chunk56UI7LUR_cjs.TokenOpsValidationError(
+          throw new chunk2RNW4MIJ_cjs.TokenOpsValidationError(
             `useDecryptedHandle: relayer returned no value for handle ${handleStr} on contract ${contractStr} \u2014 check ACL grant + (handle, contractAddress, userAddress) triple`,
             { method: "useDecryptedHandle", contractAddress: contractStr }
           );
@@ -83,20 +88,28 @@ function serializableSlice(v) {
   return out;
 }
 
+Object.defineProperty(exports, "useEnsureOperator", {
+  enumerable: true,
+  get: function () { return chunkWOEETTH7_cjs.useEnsureOperator; }
+});
+Object.defineProperty(exports, "useIsOperator", {
+  enumerable: true,
+  get: function () { return chunkWOEETTH7_cjs.useIsOperator; }
+});
 Object.defineProperty(exports, "TokenOpsContractError", {
   enumerable: true,
-  get: function () { return chunk56UI7LUR_cjs.TokenOpsContractError; }
+  get: function () { return chunk2RNW4MIJ_cjs.TokenOpsContractError; }
 });
 Object.defineProperty(exports, "TokenOpsSdkError", {
   enumerable: true,
-  get: function () { return chunk56UI7LUR_cjs.TokenOpsSdkError; }
+  get: function () { return chunk2RNW4MIJ_cjs.TokenOpsSdkError; }
 });
 Object.defineProperty(exports, "TokenOpsValidationError", {
   enumerable: true,
-  get: function () { return chunk56UI7LUR_cjs.TokenOpsValidationError; }
+  get: function () { return chunk2RNW4MIJ_cjs.TokenOpsValidationError; }
 });
 Object.defineProperty(exports, "isTokenOpsSdkError", {
   enumerable: true,
-  get: function () { return chunk56UI7LUR_cjs.isTokenOpsSdkError; }
+  get: function () { return chunk2RNW4MIJ_cjs.isTokenOpsSdkError; }
 });
 exports.useDecryptedHandle = useDecryptedHandle;

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,11 @@
-import '../../chunk-KWFFIJYX.js';
-import { TokenOpsValidationError } from '../../chunk-IVE3QEGD.js';
-export { TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, isTokenOpsSdkError } from '../../chunk-IVE3QEGD.js';
+export { useEnsureOperator, useIsOperator } from '../../chunk-U57COLUE.js';
+import '../../chunk-FT4LNBOS.js';
+import '../../chunk-4KJ66YRH.js';
+import '../../chunk-7VELUOMI.js';
+import '../../chunk-46T67CE2.js';
+import { TokenOpsValidationError } from '../../chunk-DRSPMIZ7.js';
+export { TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, isTokenOpsSdkError } from '../../chunk-DRSPMIZ7.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

@@ -1,11 +1,12 @@
 import type { PublicClient, WalletClient } from "viem";
 import type { Encryptor } from "../fhe-vesting/encryption.js";
-import { type SepoliaEncryptorLogger } from "./sepolia-encryptor.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
@@ -42,6 +43,46 @@ export interface CreateSepoliaEncryptorWebOpts {
      * background on why).
      */
     logger?: SepoliaEncryptorLogger;
+    /**
+     * Observe the encryptor's initialization lifecycle (see
+     * {@link EncryptorInitPhase}) — the signal to drive a loading state around
+     * the first in-browser encryption, which downloads several MB of FHE
+     * public material.
+     *
+     * `RelayerWeb` initializes lazily (Web Worker spawn + FHE param fetch
+     * happen inside the first operation), so phases map onto its REAL status
+     * events, not timers:
+     *
+     * - `"initializing"` fires synchronously while this helper constructs the
+     *   `RelayerWeb` instance.
+     * - `"downloading-params"` fires when the worker's lazy init actually
+     *   starts (upstream status `"initializing"`) — worker bring-up plus the
+     *   FHE public key + params fetch. Near-instant when the IndexedDB
+     *   artifact cache is warm.
+     * - `"ready"` fires when upstream reports `"ready"`.
+     *
+     * `"downloading-params"` / `"ready"` can fire again if the underlying
+     * relayer re-initializes (chain switch, stale artifact cache). Init
+     * failures surface as rejections from the pending operation — there is no
+     * error phase. No fake progress: no percentages, byte counts, or timers —
+     * upstream exposes no download-progress API. Callback exceptions are
+     * 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/sepolia-encryptor.d.ts

@@ -5,6 +5,24 @@ import type { Encryptor } from "../fhe-vesting/encryption.js";
 export declare const SEPOLIA_CHAIN_ID: 11155111;
 /** Mainnet chain id (`1`). Same use as {@link SEPOLIA_CHAIN_ID}. */
 export declare const MAINNET_CHAIN_ID: 1;
+/**
+ * Lifecycle phase reported by the `onPhase` callback of
+ * {@link createSepoliaEncryptor} / `createSepoliaEncryptorWeb`.
+ *
+ * - `"initializing"` — the helper started constructing the underlying Zama
+ *   relayer instance (module resolution + constructor; cheap and local).
+ * - `"downloading-params"` — the relayer's real lazy initialization began:
+ *   worker bring-up plus fetching the FHE public key and public params
+ *   (several MB on a cold cache; near-instant when served from cache).
+ * - `"ready"` — initialization completed; subsequent encrypts skip the
+ *   download entirely.
+ *
+ * Phases carry **no** percentages, byte counts, or time estimates — neither
+ * `@zama-fhe/sdk@3` nor the underlying relayer SDK exposes any
+ * download-progress API, so anything finer-grained would be fabricated.
+ * If upstream later exposes real progress this union will widen.
+ */
+export type EncryptorInitPhase = "initializing" | "downloading-params" | "ready";
 /** Subset of `@zama-fhe/sdk/node`'s `GenericLogger` we accept. Mirrored
  * structurally so consumers don't need to import the optional peer dep just
  * to type-narrow a logger arg. */
@@ -69,6 +87,26 @@ export interface CreateSepoliaEncryptorOptions {
      * that want to exercise the fetch path).
      */
     fheArtifactCacheTTL?: number;
+    /**
+     * Observe the encryptor's initialization lifecycle (see
+     * {@link EncryptorInitPhase}). `RelayerNode` initializes its worker pool
+     * lazily and exposes no status events, so the phases bracket the first
+     * operation that triggers the real init:
+     *
+     * - `"initializing"` fires when this helper starts (module load +
+     *   `RelayerNode` construction).
+     * - `"downloading-params"` fires immediately before the first `encrypt`
+     *   call, which is what actually spawns the worker pool and fetches the
+     *   FHE public key + params.
+     * - `"ready"` fires once that first `encrypt` resolves. If it rejects,
+     *   `"ready"` is not fired and the next attempt re-fires
+     *   `"downloading-params"` (the underlying SDK retries init from scratch).
+     *
+     * No fake progress: no percentages, byte counts, or timers — upstream
+     * exposes no download-progress API. Callback exceptions are swallowed so
+     * a UI observer can never break encryption.
+     */
+    onPhase?: (phase: EncryptorInitPhase) => void;
 }
 /**
  * Returned by {@link createSepoliaEncryptor}. Carries the underlying