@tokenops/sdk 1.1.1 → 1.5.1

package/dist/{chunk-56UI7LUR.cjs → chunk-67OV5CX2.cjs}

@@ -208,6 +208,23 @@ var AccessDeniedError = class extends TokenOpsSdkError {
     });
   }
 };
+var OPERATOR_NOT_APPROVED_REMEDIATION = "The token has not approved this contract as an operator. Call `setOperator()` (see `/fhe` operators) before this transaction.";
+var OperatorNotApprovedError = class extends TokenOpsSdkError {
+  name = "OperatorNotApprovedError";
+  constructor(args) {
+    super(OPERATOR_NOT_APPROVED_REMEDIATION, {
+      code: "TOKENOPS_OPERATOR_NOT_APPROVED",
+      cause: args.cause,
+      context: {
+        method: args.method,
+        contractAddress: args.contractAddress,
+        tokenAddress: args.tokenAddress,
+        holder: args.holder,
+        spender: args.spender
+      }
+    });
+  }
+};
 var InsufficientFeeError = class extends TokenOpsSdkError {
   name = "InsufficientFeeError";
   constructor(args) {
@@ -497,6 +514,8 @@ exports.MissingEncryptorError = MissingEncryptorError;
 exports.MissingPublicClientError = MissingPublicClientError;
 exports.MissingWalletClientError = MissingWalletClientError;
 exports.NetworkError = NetworkError;
+exports.OPERATOR_NOT_APPROVED_REMEDIATION = OPERATOR_NOT_APPROVED_REMEDIATION;
+exports.OperatorNotApprovedError = OperatorNotApprovedError;
 exports.PausedError = PausedError;
 exports.ReceiptEventAmbiguousError = ReceiptEventAmbiguousError;
 exports.ReceiptEventNotFoundError = ReceiptEventNotFoundError;

package/dist/{chunk-WRCUDSUJ.js → chunk-6BMP4ICG.js}

@@ -1,6 +1,6 @@
-import { normaliseAddress } from './chunk-BE2AIZ3K.js';
+import { normaliseAddress } from './chunk-ZA673I3O.js';
 import { withTelemetry } from './chunk-Q2GP5UDC.js';
-import { TokenOpsContractError } from './chunk-IVE3QEGD.js';
+import { TokenOpsContractError } from './chunk-QBJ7O2B4.js';
 
 // src/fhe/operators.ts
 var ERC7984_SET_OPERATOR_ABI = [

package/dist/{chunk-XXXDQSHE.js → chunk-6R4KNAPK.js}

@@ -1,7 +1,7 @@
-import { getFhevmAclAddress, requireFhevmAclAddress, ACL_ALLOWED_EVENT } from './chunk-FYQ2UW4T.js';
-import { SDK_VERSION, mapContractRevert, isContractRevert } from './chunk-JFLEEXKP.js';
+import { getFhevmAclAddress, requireFhevmAclAddress, ACL_ALLOWED_EVENT } from './chunk-ZWXJTBZO.js';
+import { SDK_VERSION, mapContractRevert, isContractRevert } from './chunk-SG65XWH7.js';
 import { withTelemetry } from './chunk-Q2GP5UDC.js';
-import { TokenOpsSdkError, PausedError, InsufficientFeeError, ReceiptEventNotFoundError, ReceiptEventAmbiguousError, InvalidArgumentError, MissingWalletClientError, MissingAccountError, InsufficientBalanceError, InvalidSignatureError } from './chunk-IVE3QEGD.js';
+import { TokenOpsSdkError, PausedError, InsufficientFeeError, ReceiptEventNotFoundError, ReceiptEventAmbiguousError, InvalidArgumentError, MissingWalletClientError, MissingAccountError, InsufficientBalanceError, InvalidSignatureError } from './chunk-QBJ7O2B4.js';
 import { parseEventLogs, isAddress } from 'viem';
 
 // src/fhe-airdrop/abis/cloneable.ts
@@ -1358,6 +1358,8 @@ var ConfidentialAirdropClient = class {
    * {@link signClaimAuthorization}. The signature commits to that handle, so the SDK
    * does NOT re-encrypt — submit the admin-issued payload as-is.
    *
+   * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+   *
    * @returns Transaction hash.
    * @example
    * const fee = await airdrop.gasFee();

package/dist/{chunk-XSNLAS5M.js → chunk-AOP6HMPW.js}

@@ -1,4 +1,4 @@
-import { InvalidArgumentError } from './chunk-IVE3QEGD.js';
+import { InvalidArgumentError } from './chunk-QBJ7O2B4.js';
 
 // src/fhe/scale-ratio.ts
 var FHE_SPLIT_DENOMINATOR = 90090000n;

package/dist/{chunk-SAGJIEQK.cjs → chunk-C7BRZXJA.cjs}

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkVDXVNZCO_cjs = require('./chunk-VDXVNZCO.cjs');
-var chunk3ZRHDTEX_cjs = require('./chunk-3ZRHDTEX.cjs');
-var chunkCQIPRNS7_cjs = require('./chunk-CQIPRNS7.cjs');
+var chunkKLKI352M_cjs = require('./chunk-KLKI352M.cjs');
+var chunkPUPKNW3R_cjs = require('./chunk-PUPKNW3R.cjs');
+var chunkJK4XMMKM_cjs = require('./chunk-JK4XMMKM.cjs');
 var chunkVJKZWYYJ_cjs = require('./chunk-VJKZWYYJ.cjs');
 var chunk66IHPTOK_cjs = require('./chunk-66IHPTOK.cjs');
-var chunk56UI7LUR_cjs = require('./chunk-56UI7LUR.cjs');
+var chunk67OV5CX2_cjs = require('./chunk-67OV5CX2.cjs');
 var viem = require('viem');
 
 // src/fhe-vesting/abis/factory.ts
@@ -444,10 +444,10 @@ var ConfidentialVestingFactoryClient = class {
     this.publicClient = config.publicClient;
     this.walletClient = config.walletClient;
     const chainId = config.chainId ?? config.publicClient.chain?.id;
-    const addressOverride = config.address ? chunkCQIPRNS7_cjs.normaliseAddress(config.address) : void 0;
-    const resolved = addressOverride ?? (chainId === void 0 ? void 0 : chunk3ZRHDTEX_cjs.getFheVestingFactoryAddress(chainId));
+    const addressOverride = config.address ? chunkJK4XMMKM_cjs.normaliseAddress(config.address) : void 0;
+    const resolved = addressOverride ?? (chainId === void 0 ? void 0 : chunkPUPKNW3R_cjs.getFheVestingFactoryAddress(chainId));
     if (!resolved) {
-      throw new chunk56UI7LUR_cjs.DeploymentAddressUnavailableError({
+      throw new chunk67OV5CX2_cjs.DeploymentAddressUnavailableError({
         reason: chainId === void 0 ? "chain-id-missing" : "registry-not-deployed",
         product: "fheVesting",
         contract: "confidentialVestingFactory",
@@ -463,7 +463,7 @@ var ConfidentialVestingFactoryClient = class {
       hasWallet: !!this.walletClient,
       aclResolved: true,
       // factory has no ACL dependency; constant for funnel-shape parity with manager.
-      sdkVersion: chunkVDXVNZCO_cjs.SDK_VERSION
+      sdkVersion: chunkKLKI352M_cjs.SDK_VERSION
     });
   }
   // ----------------------- writes -----------------------
@@ -653,12 +653,12 @@ var ConfidentialVestingFactoryClient = class {
     });
     const ours = events.filter((ev) => ev.address.toLowerCase() === this.address.toLowerCase());
     if (ours.length === 0) {
-      throw new chunk56UI7LUR_cjs.TokenOpsSdkError(
+      throw new chunk67OV5CX2_cjs.TokenOpsSdkError(
         `${method}: no ManagerCreated event from factory ${this.address} in tx ${hash}`
       );
     }
     if (ours.length > 1) {
-      throw new chunk56UI7LUR_cjs.TokenOpsSdkError(
+      throw new chunk67OV5CX2_cjs.TokenOpsSdkError(
         `${method}: ${ours.length} ManagerCreated events from factory ${this.address} in tx ${hash}; ambiguous result`
       );
     }
@@ -666,7 +666,7 @@ var ConfidentialVestingFactoryClient = class {
   }
   #requireWallet(method) {
     if (!this.walletClient) {
-      throw new chunk56UI7LUR_cjs.MissingWalletClientError(method);
+      throw new chunk67OV5CX2_cjs.MissingWalletClientError(method);
     }
     return this.walletClient;
   }
@@ -674,7 +674,7 @@ var ConfidentialVestingFactoryClient = class {
     const wallet = this.#requireWallet(functionName);
     const acct = account ?? wallet.account;
     if (!acct) {
-      throw new chunk56UI7LUR_cjs.MissingAccountError(String(functionName));
+      throw new chunk67OV5CX2_cjs.MissingAccountError(String(functionName));
     }
     await this.#preflightWrite(String(functionName), functionName, args, acct);
     try {
@@ -691,7 +691,7 @@ var ConfidentialVestingFactoryClient = class {
     }
   }
   #mapRevert(method, err, account) {
-    return chunkVDXVNZCO_cjs.mapContractRevert(err, {
+    return chunkKLKI352M_cjs.mapContractRevert(err, {
       method,
       contractAddress: this.address,
       abi: confidentialVestingFactoryAbi,
@@ -716,7 +716,7 @@ var ConfidentialVestingFactoryClient = class {
         ...value !== void 0 ? { value } : {}
       });
     } catch (err) {
-      if (chunkVDXVNZCO_cjs.isContractRevert(err)) {
+      if (chunkKLKI352M_cjs.isContractRevert(err)) {
         throw this.#mapRevert(method, err, accountAddress(account));
       }
     }

package/dist/{chunk-OQZAZIAS.js → chunk-DUZIIRPF.js}

@@ -1,10 +1,11 @@
-import { SDK_VERSION, mapContractRevert, isContractRevert } from './chunk-JFLEEXKP.js';
-import { getFheAirdropFactoryAddress } from './chunk-M7V2EDPB.js';
-import { normaliseAddress } from './chunk-BE2AIZ3K.js';
+import { erc7984OperatorAbi } from './chunk-7VELUOMI.js';
+import { SDK_VERSION, mapContractRevert, isContractRevert } from './chunk-SG65XWH7.js';
+import { getFheAirdropFactoryAddress } from './chunk-XGGTQQFH.js';
+import { normaliseAddress } from './chunk-ZA673I3O.js';
 import { withTelemetry } from './chunk-Q2GP5UDC.js';
 import { asExternalInputProof, asEncryptedHandle, asSignature, asTxHash } from './chunk-KWFFIJYX.js';
-import { InvalidArgumentError, TokenOpsSdkError, MissingAccountError, DeploymentAddressUnavailableError, MissingWalletClientError, MissingEncryptorError } from './chunk-IVE3QEGD.js';
-import { bytesToHex, parseEventLogs } from 'viem';
+import { InvalidArgumentError, TokenOpsSdkError, MissingAccountError, DeploymentAddressUnavailableError, OperatorNotApprovedError, AlreadyInitializedError, MissingWalletClientError, MissingEncryptorError } from './chunk-QBJ7O2B4.js';
+import { bytesToHex, isAddress, parseEventLogs } from 'viem';
 
 // src/fhe-airdrop/abis/factory.ts
 var confidentialAirdropFactoryAbi = [
@@ -1116,6 +1117,14 @@ var ConfidentialAirdropFactoryClient = class {
    * Prerequisites: caller must have set this factory as an operator on the
    * token: `token.setOperator(factoryAddress, deadline)`.
    *
+   * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+   *
+   * **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
+   * ERC-20. Amount parameters are base units of the token's actual decimals:
+   * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+   * transparent TTT test token uses 18 decimals.
+   *
    * Symmetric with {@link ConfidentialAirdropFactoryClient.createConfidentialAirdrop}
    * — both return `{ hash, airdrop }` parsed from the
    * `ConfidentialAirdropCreated` event.
@@ -1178,6 +1187,14 @@ var ConfidentialAirdropFactoryClient = class {
    * Prerequisites: caller must have set this factory as an operator on the token:
    * `token.setOperator(factoryAddress, deadline)`
    *
+   * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+   *
+   * **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
+   * ERC-20. Amount parameters are base units of the token's actual decimals:
+   * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+   * transparent TTT test token uses 18 decimals.
+   *
    * @returns Transaction hash.
    */
   async fundConfidentialAirdrop(args) {
@@ -1247,6 +1264,14 @@ var ConfidentialAirdropFactoryClient = class {
    * Symmetry with {@link ConfidentialAirdropFactoryClient.createConfidentialAirdropAndGetAddress}
    * — use this when you also need to seed the pool in the same transaction.
    *
+   * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+   *
+   * **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
+   * ERC-20. Amount parameters are base units of the token's actual decimals:
+   * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+   * transparent TTT test token uses 18 decimals.
+   *
    * Internally: {@link ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop} →
    * {@link PublicClient.waitForTransactionReceipt} →
    * `parseEventLogs({ eventName: "ConfidentialAirdropCreated" })`.
@@ -1329,6 +1354,149 @@ var ConfidentialAirdropFactoryClient = class {
   async getInitCodeHash(args) {
     return this.#read("getInitCodeHash", [toAbiParams(args.params), args.gasFee]);
   }
+  // ----------------------- preflight -----------------------
+  /**
+   * Read-only preflight for {@link createConfidentialAirdrop} /
+   * {@link createAndFundConfidentialAirdrop}. Runs the
+   * deterministic-from-off-chain checks and reports blockers both as
+   * human-readable strings (`blockers`) and as typed {@link TokenOpsSdkError}s
+   * (`blockerErrors`), index-aligned.
+   *
+   * Preflight is **opt-in**. Consumers who have already validated state can
+   * skip this call and invoke the write directly — they'll receive the same
+   * typed errors at write time via the revert mapper.
+   *
+   * Report fields: `isFactoryOperator`, `gasFee`, `predictedAirdrop`,
+   * `alreadyDeployed`, `ready`, `blockers`, `blockerErrors` — see
+   * {@link CreateAirdropPreflightReport} for the meaning of each.
+   *
+   * Checks performed (all read-only, no gas):
+   * - Structural `params` validation mirroring the factory + clone
+   *   `initialize` requirements (`InvalidArgumentError` blockers): `token` and
+   *   `admin` are checksummed non-zero addresses,
+   *   `startTimestamp < endTimestamp`, and `endTimestamp` is in the future
+   *   (the clone's `initialize` reverts with `EndTimeInPast`).
+   * - Operator: creator has approved this factory as an ERC-7984 operator on
+   *   `params.token` — a blocker only when `funding: true`
+   *   ({@link OperatorNotApprovedError}); otherwise informational via
+   *   `isFactoryOperator`.
+   * - Collision (only when `userSalt` is supplied): bytecode already at the
+   *   predicted CREATE2 address means a repeat create with the same
+   *   `(params, userSalt, gasFee)` would revert
+   *   ({@link AlreadyInitializedError} blocker).
+   *
+   * **Not preflight-detectable — read before trusting `ready: true`:** the
+   * creator's confidential token balance is an encrypted `euint64` the SDK
+   * cannot read in plaintext, and an underfunded `createAndFund` does **not**
+   * revert — the ERC-7984 transfer silently moves an encrypted zero. Confirm
+   * the creator's balance covers the pool before submitting.
+   *
+   * @param args See {@link PreflightCreateAirdropArgs}.
+   * @returns A {@link CreateAirdropPreflightReport}.
+   */
+  async preflightCreateAirdrop(args) {
+    const { params, creator, userSalt, funding } = args;
+    const blockers = [];
+    const blockerErrors = [];
+    const pushBlocker = (err) => {
+      blockerErrors.push(err);
+      blockers.push(err.message);
+    };
+    const tokenOk = isAddress(params.token, { strict: true }) && params.token !== ZERO_ADDRESS;
+    if (!tokenOk) {
+      pushBlocker(
+        new InvalidArgumentError({
+          method: "createConfidentialAirdrop",
+          argument: "params.token",
+          reason: "must be a valid, non-zero EIP-55 checksummed address",
+          value: params.token
+        })
+      );
+    }
+    const adminOk = isAddress(params.admin, { strict: true }) && params.admin !== ZERO_ADDRESS;
+    if (!adminOk) {
+      pushBlocker(
+        new InvalidArgumentError({
+          method: "createConfidentialAirdrop",
+          argument: "params.admin",
+          reason: "must be a valid, non-zero EIP-55 checksummed address",
+          value: params.admin
+        })
+      );
+    }
+    if (params.startTimestamp >= params.endTimestamp) {
+      pushBlocker(
+        new InvalidArgumentError({
+          method: "createConfidentialAirdrop",
+          argument: "params.startTimestamp/params.endTimestamp",
+          reason: "startTimestamp must be strictly less than endTimestamp",
+          value: { startTimestamp: params.startTimestamp, endTimestamp: params.endTimestamp }
+        })
+      );
+    }
+    const [block, customFee, defaultFee, isFactoryOperator] = await Promise.all([
+      this.publicClient.getBlock(),
+      this.getCustomFee(creator),
+      this.defaultGasFee(),
+      tokenOk ? this.publicClient.readContract({
+        address: params.token,
+        abi: erc7984OperatorAbi,
+        functionName: "isOperator",
+        args: [creator, this.address]
+      }) : Promise.resolve(false)
+    ]);
+    const gasFee = customFee.enabled ? customFee.gasFee : defaultFee;
+    if (params.endTimestamp <= Number(block.timestamp)) {
+      pushBlocker(
+        new InvalidArgumentError({
+          method: "createConfidentialAirdrop",
+          argument: "params.endTimestamp",
+          reason: "must be in the future (the clone's initialize reverts with EndTimeInPast)",
+          value: params.endTimestamp
+        })
+      );
+    }
+    if (funding === true && !isFactoryOperator) {
+      pushBlocker(
+        new OperatorNotApprovedError({
+          method: "createAndFundConfidentialAirdrop",
+          contractAddress: this.address,
+          tokenAddress: params.token,
+          holder: creator,
+          spender: this.address
+        })
+      );
+    }
+    let predictedAirdrop;
+    let alreadyDeployed;
+    if (userSalt !== void 0 && tokenOk && adminOk) {
+      predictedAirdrop = await this.#read("predictAirdropAddress", [
+        toAbiParams(params),
+        userSalt,
+        creator,
+        gasFee
+      ]);
+      const bytecode = await this.publicClient.getCode({ address: predictedAirdrop });
+      alreadyDeployed = bytecode !== void 0 && bytecode !== "0x";
+      if (alreadyDeployed) {
+        pushBlocker(
+          new AlreadyInitializedError({
+            method: "createConfidentialAirdrop",
+            contractAddress: predictedAirdrop
+          })
+        );
+      }
+    }
+    return {
+      isFactoryOperator,
+      gasFee,
+      predictedAirdrop,
+      alreadyDeployed,
+      ready: blockers.length === 0,
+      blockers,
+      blockerErrors
+    };
+  }
   // ----------------------- internals -----------------------
   /**
    * Wait for the receipt of a clone-deploy tx and parse the
@@ -1470,6 +1638,7 @@ var ConfidentialAirdropFactoryClient = class {
 function createConfidentialAirdropFactoryClient(config) {
   return new ConfidentialAirdropFactoryClient(config);
 }
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 function accountAddress(account) {
   return typeof account === "string" ? account : account.address;
 }

package/dist/{chunk-Q7ARQSUH.cjs → chunk-FAXIIH5R.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk56UI7LUR_cjs = require('./chunk-56UI7LUR.cjs');
+var chunk67OV5CX2_cjs = require('./chunk-67OV5CX2.cjs');
 var viem = require('viem');
 
 var FHEVM_ACL_ADDRESS_BY_CHAIN = {
@@ -16,7 +16,7 @@ function getFhevmAclAddress(chainId) {
 }
 function requireFhevmAclAddress(chainId, clientLabel) {
   if (chainId === void 0) {
-    throw new chunk56UI7LUR_cjs.DeploymentAddressUnavailableError({
+    throw new chunk67OV5CX2_cjs.DeploymentAddressUnavailableError({
       reason: "chain-id-missing",
       product: "fhevm",
       contract: "acl",
@@ -26,7 +26,7 @@ function requireFhevmAclAddress(chainId, clientLabel) {
   }
   const addr = FHEVM_ACL_ADDRESS_BY_CHAIN[chainId];
   if (addr) return addr;
-  throw new chunk56UI7LUR_cjs.DeploymentAddressUnavailableError({
+  throw new chunk67OV5CX2_cjs.DeploymentAddressUnavailableError({
     reason: "registry-unknown-chain",
     product: "fhevm",
     contract: "acl",

package/dist/chunk-FT4LNBOS.js

@@ -0,0 +1,11 @@
+import * as wagmi from 'wagmi';
+
+// src/core/wagmi-compat.ts
+var wagmiModule = wagmi;
+var useWagmiAccount = wagmiModule.useConnection ?? wagmiModule.useAccount ?? (() => {
+  throw new Error(
+    "@tokenops/sdk: the installed `wagmi` package exposes neither `useConnection` (v3) nor `useAccount` (v2). Install wagmi ^2.0.0 or ^3.0.0 \u2014 the SDK's /react subpaths support both majors."
+  );
+});
+
+export { useWagmiAccount };

package/dist/{chunk-QE7ZONJ2.js → chunk-IJFQ5L4I.js}

@@ -1,9 +1,9 @@
-import { SDK_VERSION, isContractRevert, mapContractRevert } from './chunk-JFLEEXKP.js';
-import { getConfidentialTestTokenAddress, getTestTokenAddress } from './chunk-M7V2EDPB.js';
-import { normaliseAddress } from './chunk-BE2AIZ3K.js';
+import { SDK_VERSION, isContractRevert, mapContractRevert } from './chunk-SG65XWH7.js';
+import { getConfidentialTestTokenAddress, getTestTokenAddress } from './chunk-XGGTQQFH.js';
+import { normaliseAddress } from './chunk-ZA673I3O.js';
 import { withTelemetry } from './chunk-Q2GP5UDC.js';
 import { asEncryptedHandle, asTxHash } from './chunk-KWFFIJYX.js';
-import { TokenOpsSdkError, UnsupportedChainError, DeploymentAddressUnavailableError, TokenOpsContractError, ReceiptEventNotFoundError, ReceiptEventAmbiguousError, MissingWalletClientError, MissingAccountError, InvalidArgumentError } from './chunk-IVE3QEGD.js';
+import { TokenOpsSdkError, UnsupportedChainError, DeploymentAddressUnavailableError, TokenOpsContractError, ReceiptEventNotFoundError, ReceiptEventAmbiguousError, MissingWalletClientError, MissingAccountError, InvalidArgumentError } from './chunk-QBJ7O2B4.js';
 import { sepolia } from 'viem/chains';
 import { parseEventLogs } from 'viem';