@tokenops/sdk 1.0.0 → 1.5.1

package/dist/{chunk-ZXCOJY2Z.js → chunk-WMACINXO.js}

@@ -1,4 +1,4 @@
-import { TokenOpsSdkError, InvalidArgumentError, DecryptionFailedError, EncryptionFailedError, RelayerUnreachableError, SigningFailedError, UserRejectedSignatureError, UserDecryptNotAllowedError } from './chunk-IVE3QEGD.js';
+import { TokenOpsSdkError, InvalidArgumentError, DecryptionFailedError, EncryptionFailedError, RelayerUnreachableError, SigningFailedError, UserRejectedSignatureError, UserDecryptNotAllowedError } from './chunk-QBJ7O2B4.js';
 
 // src/core/zama-error-mapper.ts
 function mapZamaError(error, args) {

package/dist/{chunk-COPFW5Z4.js → chunk-XGGTQQFH.js}

@@ -1,4 +1,4 @@
-import { DeploymentAddressUnavailableError } from './chunk-IVE3QEGD.js';
+import { DeploymentAddressUnavailableError } from './chunk-QBJ7O2B4.js';
 import { sepolia, mainnet } from 'viem/chains';
 
 var DEPLOYED_ADDRESSES = {
@@ -19,6 +19,23 @@ var DEPLOYED_ADDRESSES = {
       [mainnet.id]: "0x4fC0d28cBe4B82D512Ad0B42F6787480Cc98cC70",
       [sepolia.id]: "0x710dD9885Cc9986EfD234E7719483147a6d8DBb4"
     }
+  },
+  // Testnet-only faucet token pair (see `/testnet-faucet`). The standard
+  // `TokenopsTestToken` (TTT, 18-decimal ERC-20, open mint) and its
+  // confidential ERC-7984 wrapper `ConfidentialTokenopsTestToken` (CTTT,
+  // 6-decimal, open backed faucet mint). Sepolia only — these mint value-less
+  // test tokens to anyone, so they MUST NOT appear on mainnet.
+  // `confidentialTestToken` is the UUPS *proxy* address; call it with the
+  // implementation ABI.
+  testnetFaucet: {
+    testToken: {
+      [sepolia.id]: "0x37a057Fa8C201a7bf8caF32dfa9A0878f577D92b"
+      // mainnet omitted — testnet-only by design.
+    },
+    confidentialTestToken: {
+      [sepolia.id]: "0x258F9D60dc023870e4E3109c894D834D5377361a"
+      // mainnet omitted — testnet-only by design.
+    }
   }
 };
 function getDeployedAddress(product, contract, chainId) {
@@ -56,6 +73,18 @@ function getFheDisperseSingletonAddress(chainId) {
 function requireFheDisperseSingletonAddress(chainId) {
   return requireDeployedAddress("fheDisperse", "disperseConfidentialSingleton", chainId);
 }
+function getTestTokenAddress(chainId) {
+  return getDeployedAddress("testnetFaucet", "testToken", chainId);
+}
+function requireTestTokenAddress(chainId) {
+  return requireDeployedAddress("testnetFaucet", "testToken", chainId);
+}
+function getConfidentialTestTokenAddress(chainId) {
+  return getDeployedAddress("testnetFaucet", "confidentialTestToken", chainId);
+}
+function requireConfidentialTestTokenAddress(chainId) {
+  return requireDeployedAddress("testnetFaucet", "confidentialTestToken", chainId);
+}
 function chainsWithKnownRegistryEntry(product) {
   const productEntry = DEPLOYED_ADDRESSES[product];
   const ids = /* @__PURE__ */ new Set();
@@ -79,4 +108,4 @@ function chainsWithDeployment(product) {
   ).sort((a, b) => a - b);
 }
 
-export { DEPLOYED_ADDRESSES, chainsWithDeployment, chainsWithKnownRegistryEntry, getDeployedAddress, getFheAirdropFactoryAddress, getFheDisperseSingletonAddress, getFheVestingFactoryAddress, requireFheAirdropFactoryAddress, requireFheDisperseSingletonAddress, requireFheVestingFactoryAddress };
+export { DEPLOYED_ADDRESSES, chainsWithDeployment, chainsWithKnownRegistryEntry, getConfidentialTestTokenAddress, getDeployedAddress, getFheAirdropFactoryAddress, getFheDisperseSingletonAddress, getFheVestingFactoryAddress, getTestTokenAddress, requireConfidentialTestTokenAddress, requireFheAirdropFactoryAddress, requireFheDisperseSingletonAddress, requireFheVestingFactoryAddress, requireTestTokenAddress };

package/dist/{chunk-CMRETRZO.js → chunk-YQIBBEFJ.js}

@@ -1,4 +1,4 @@
-import { ConfidentialVestingFactoryClient, confidentialVestingFactoryAbi } from './chunk-72YGZEQE.js';
+import { ConfidentialVestingFactoryClient, confidentialVestingFactoryAbi } from './chunk-OXTLPTO3.js';
 
 // src/fhe-vesting/advanced/factory-advanced.ts
 var ConfidentialVestingFactoryAdvancedClient = class extends ConfidentialVestingFactoryClient {

package/dist/{chunk-BE2AIZ3K.js → chunk-ZA673I3O.js}

@@ -1,4 +1,4 @@
-import { TokenOpsValidationError } from './chunk-IVE3QEGD.js';
+import { TokenOpsValidationError } from './chunk-QBJ7O2B4.js';
 import { isAddress, getAddress } from 'viem';
 
 function normaliseAddress(input) {

package/dist/chunk-ZQUE2B3Q.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+var wagmi = require('wagmi');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var wagmi__namespace = /*#__PURE__*/_interopNamespace(wagmi);
+
+// src/core/wagmi-compat.ts
+var wagmiModule = wagmi__namespace;
+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."
+  );
+});
+
+exports.useWagmiAccount = useWagmiAccount;

package/dist/{chunk-FYQ2UW4T.js → chunk-ZWXJTBZO.js}

@@ -1,4 +1,4 @@
-import { DeploymentAddressUnavailableError } from './chunk-IVE3QEGD.js';
+import { DeploymentAddressUnavailableError } from './chunk-QBJ7O2B4.js';
 import { parseAbiItem } from 'viem';
 
 var FHEVM_ACL_ADDRESS_BY_CHAIN = {

package/dist/core/addresses.d.ts

@@ -24,6 +24,14 @@ export declare const DEPLOYED_ADDRESSES: {
             readonly 11155111: "0x710dD9885Cc9986EfD234E7719483147a6d8DBb4";
         };
     };
+    readonly testnetFaucet: {
+        readonly testToken: {
+            readonly 11155111: "0x37a057Fa8C201a7bf8caF32dfa9A0878f577D92b";
+        };
+        readonly confidentialTestToken: {
+            readonly 11155111: "0x258F9D60dc023870e4E3109c894D834D5377361a";
+        };
+    };
 };
 export type DeployedAddresses = typeof DEPLOYED_ADDRESSES;
 export type ProductKey = keyof DeployedAddresses;
@@ -41,6 +49,20 @@ export declare function getFheAirdropFactoryAddress(chainId: number): Address |
 export declare function requireFheAirdropFactoryAddress(chainId: number): Address;
 export declare function getFheDisperseSingletonAddress(chainId: number): Address | undefined;
 export declare function requireFheDisperseSingletonAddress(chainId: number): Address;
+/**
+ * Address of the standard `TokenopsTestToken` (TTT) — the 18-decimal ERC-20
+ * with an open `mint` that backs the confidential faucet. Testnet-only;
+ * returns `undefined` on chains without a deployment (e.g. mainnet).
+ */
+export declare function getTestTokenAddress(chainId: number): Address | undefined;
+export declare function requireTestTokenAddress(chainId: number): Address;
+/**
+ * Address of the `ConfidentialTokenopsTestToken` (CTTT) UUPS proxy — the
+ * 6-decimal ERC-7984 confidential wrapper with an open backed faucet `mint`.
+ * Testnet-only; returns `undefined` on chains without a deployment.
+ */
+export declare function getConfidentialTestTokenAddress(chainId: number): Address | undefined;
+export declare function requireConfidentialTestTokenAddress(chainId: number): Address;
 /**
  * Chains with a registry entry for `product`, including ones explicitly
  * marked `null` (known chain, not yet deployed). Useful when the consumer

package/dist/core/errors.d.ts

@@ -12,7 +12,7 @@ declare const TOKENOPS_SDK_ERROR_BRAND: unique symbol;
  * on `error.code` in `onError` handlers and UI surfaces. Messages stay
  * human-readable and may evolve between versions.
  */
-export type TokenOpsSdkErrorCode = "TOKENOPS_UNSUPPORTED_CHAIN" | "TOKENOPS_DEPLOYMENT_ADDRESS_UNAVAILABLE" | "TOKENOPS_MISSING_PUBLIC_CLIENT" | "TOKENOPS_MISSING_WALLET_CLIENT" | "TOKENOPS_MISSING_ACCOUNT" | "TOKENOPS_MISSING_ENCRYPTOR" | "TOKENOPS_MISSING_CLIENT" | "TOKENOPS_INVALID_ARGUMENT" | "TOKENOPS_RECEIPT_EVENT_NOT_FOUND" | "TOKENOPS_RECEIPT_EVENT_AMBIGUOUS" | "TOKENOPS_CONTRACT_REVERT" | "TOKENOPS_PAUSED" | "TOKENOPS_ACCESS_DENIED" | "TOKENOPS_INSUFFICIENT_FEE" | "TOKENOPS_INSUFFICIENT_BALANCE" | "TOKENOPS_BATCH_TOO_LARGE" | "TOKENOPS_FEATURE_DISABLED" | "TOKENOPS_TRANSFER_FAILED" | "TOKENOPS_FHE_HANDLE_NOT_ALLOWED" | "TOKENOPS_ALREADY_INITIALIZED" | "TOKENOPS_REENTRANCY" | "TOKENOPS_INVALID_SIGNATURE" | "TOKENOPS_WALLET_REJECTED" | "TOKENOPS_WALLET_CHAIN_MISMATCH" | "TOKENOPS_NETWORK_ERROR" | "TOKENOPS_INSUFFICIENT_GAS_FUNDS" | "TOKENOPS_UNKNOWN_WRITE_FAILURE" | "TOKENOPS_USER_REJECTED" | "TOKENOPS_SIGNING_FAILED" | "TOKENOPS_RELAYER_UNREACHABLE" | "TOKENOPS_ENCRYPTION_FAILED" | "TOKENOPS_DECRYPTION_FAILED" | "TOKENOPS_USER_DECRYPT_NOT_ALLOWED" | "TOKENOPS_VESTING_NOT_FOUND" | "TOKENOPS_NOT_RECIPIENT" | "TOKENOPS_CLAIM_LOCKED" | "TOKENOPS_VESTING_REVOKED" | "TOKENOPS_NOT_REVOCABLE" | "TOKENOPS_VESTING_EXPIRED" | "TOKENOPS_TRANSFER_ALREADY_PENDING" | "TOKENOPS_NO_PENDING_TRANSFER" | "TOKENOPS_NOT_PENDING_RECIPIENT" | "TOKENOPS_TRANSFER_EXPIRED" | "TOKENOPS_ALREADY_CLAIMED" | "TOKENOPS_CLAIM_NOT_STARTED" | "TOKENOPS_CLAIM_WINDOW_CLOSED" | "TOKENOPS_NOT_REGISTERED" | "TOKENOPS_ALREADY_REGISTERED";
+export type TokenOpsSdkErrorCode = "TOKENOPS_UNSUPPORTED_CHAIN" | "TOKENOPS_DEPLOYMENT_ADDRESS_UNAVAILABLE" | "TOKENOPS_MISSING_PUBLIC_CLIENT" | "TOKENOPS_MISSING_WALLET_CLIENT" | "TOKENOPS_MISSING_ACCOUNT" | "TOKENOPS_MISSING_ENCRYPTOR" | "TOKENOPS_MISSING_CLIENT" | "TOKENOPS_INVALID_ARGUMENT" | "TOKENOPS_RECEIPT_EVENT_NOT_FOUND" | "TOKENOPS_RECEIPT_EVENT_AMBIGUOUS" | "TOKENOPS_CONTRACT_REVERT" | "TOKENOPS_PAUSED" | "TOKENOPS_ACCESS_DENIED" | "TOKENOPS_OPERATOR_NOT_APPROVED" | "TOKENOPS_INSUFFICIENT_FEE" | "TOKENOPS_INSUFFICIENT_BALANCE" | "TOKENOPS_BATCH_TOO_LARGE" | "TOKENOPS_FEATURE_DISABLED" | "TOKENOPS_TRANSFER_FAILED" | "TOKENOPS_FHE_HANDLE_NOT_ALLOWED" | "TOKENOPS_ALREADY_INITIALIZED" | "TOKENOPS_REENTRANCY" | "TOKENOPS_INVALID_SIGNATURE" | "TOKENOPS_WALLET_REJECTED" | "TOKENOPS_WALLET_CHAIN_MISMATCH" | "TOKENOPS_NETWORK_ERROR" | "TOKENOPS_INSUFFICIENT_GAS_FUNDS" | "TOKENOPS_UNKNOWN_WRITE_FAILURE" | "TOKENOPS_USER_REJECTED" | "TOKENOPS_SIGNING_FAILED" | "TOKENOPS_RELAYER_UNREACHABLE" | "TOKENOPS_ENCRYPTION_FAILED" | "TOKENOPS_DECRYPTION_FAILED" | "TOKENOPS_USER_DECRYPT_NOT_ALLOWED" | "TOKENOPS_VESTING_NOT_FOUND" | "TOKENOPS_NOT_RECIPIENT" | "TOKENOPS_CLAIM_LOCKED" | "TOKENOPS_VESTING_REVOKED" | "TOKENOPS_NOT_REVOCABLE" | "TOKENOPS_VESTING_EXPIRED" | "TOKENOPS_TRANSFER_ALREADY_PENDING" | "TOKENOPS_NO_PENDING_TRANSFER" | "TOKENOPS_NOT_PENDING_RECIPIENT" | "TOKENOPS_TRANSFER_EXPIRED" | "TOKENOPS_ALREADY_CLAIMED" | "TOKENOPS_CLAIM_NOT_STARTED" | "TOKENOPS_CLAIM_WINDOW_CLOSED" | "TOKENOPS_NOT_REGISTERED" | "TOKENOPS_ALREADY_REGISTERED" | "TOKENOPS_FAUCET_SUPPLY_EXHAUSTED";
 export interface TokenOpsSdkErrorInit {
     code: TokenOpsSdkErrorCode;
     cause?: unknown;
@@ -286,6 +286,46 @@ export declare class AccessDeniedError extends TokenOpsSdkError {
         cause?: unknown;
     });
 }
+/**
+ * Canonical remediation copy for the ERC-7984 operator prerequisite. Kept as
+ * a single exported constant so every surface that mentions the prerequisite
+ * (this error, operator helpers, docs) reuses the exact same wording.
+ * Do NOT reword — the string is shared verbatim with the docs repo.
+ */
+export declare const OPERATOR_NOT_APPROVED_REMEDIATION: "The token has not approved this contract as an operator. Call `setOperator()` (see `/fhe` operators) before this transaction.";
+/**
+ * The ERC-7984 token rejected the product contract as a spender —
+ * `ERC7984UnauthorizedSpender(address holder, address spender)` (selector
+ * `0x79f2cb38`). Raised whenever a TokenOps contract tries to pull
+ * confidential tokens from a holder that never called `setOperator()` for it
+ * (vesting `createVesting`, airdrop funding, disperse pulls). Also surfaced
+ * pre-write as a `blockerErrors[]` entry by the create-side preflights
+ * (`preflightCreateVesting` / `preflightCreateAirdrop`).
+ *
+ * Remediation: call `setOperator()` on the token (see the `/fhe` operator
+ * helpers) with the product contract as operator, then retry.
+ */
+export declare class OperatorNotApprovedError extends TokenOpsSdkError {
+    readonly name = "OperatorNotApprovedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        /** ERC-7984 token whose operator approval is missing (known statically on preflight paths). */
+        tokenAddress?: Address;
+        /** Token holder whose balance the contract tried to pull (decoded from the revert when available). */
+        holder?: Address;
+        /** Address the token refused as a spender — the product contract needing operator approval. */
+        spender?: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        tokenAddress?: Address;
+        holder?: Address;
+        spender?: Address;
+        cause?: unknown;
+    });
+}
 /**
  * Native ETH (gas) fee or token fee did not match what the contract requires.
  * `feeKind === "gas"` means the `msg.value` was wrong; `"token"` means the

package/dist/core/revert-mapper.d.ts

@@ -1,5 +1,82 @@
 import type { Abi, Address } from "viem";
 import { TokenOpsSdkError } from "./errors.js";
+/**
+ * ERC-7984 (Confidential Token) standard error signatures, from the reference
+ * implementation the TokenOps tokens vendor
+ * (`openzeppelin-confidential/ERC7984.sol`). None of the product contracts
+ * declare these in their own ABIs — the revert originates in the *token*, not
+ * the product contract — so {@link mapContractRevert} merges this set into
+ * every decode. Without it, `decodeErrorResult` fails and consumers see a raw
+ * selector hex string (`ContractRevertError: "… reverted with 0x79f2cb38."`).
+ *
+ * Selectors (keccak-256 of the signature, first 4 bytes):
+ *
+ * - `ERC7984UnauthorizedSpender(address,address)` → `0x79f2cb38`
+ * - `ERC7984UnauthorizedCaller(address)`          → `0x782c6ffd`
+ * - `ERC7984UnauthorizedUseOfEncryptedAmount(bytes32,address)` → `0x67cfe805`
+ * - `ERC7984InvalidReceiver(address)`             → `0x8d518801`
+ * - `ERC7984InvalidSender(address)`               → `0xee457ebf`
+ * - `ERC7984ZeroBalance(address)`                 → `0x5ff91cdc`
+ * - `ERC7984InvalidGatewayRequest(uint256)`       → `0x05c5b389`
+ *
+ * `euint64` parameters are `bytes32` at the ABI boundary.
+ */
+export declare const ERC7984_ERRORS_ABI: readonly [{
+    readonly type: "error";
+    readonly name: "ERC7984UnauthorizedSpender";
+    readonly inputs: readonly [{
+        readonly name: "holder";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ERC7984UnauthorizedCaller";
+    readonly inputs: readonly [{
+        readonly name: "caller";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ERC7984UnauthorizedUseOfEncryptedAmount";
+    readonly inputs: readonly [{
+        readonly name: "amount";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "user";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ERC7984InvalidReceiver";
+    readonly inputs: readonly [{
+        readonly name: "receiver";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ERC7984InvalidSender";
+    readonly inputs: readonly [{
+        readonly name: "sender";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ERC7984ZeroBalance";
+    readonly inputs: readonly [{
+        readonly name: "holder";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ERC7984InvalidGatewayRequest";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "uint256";
+    }];
+}];
 /** Per-product mapping: contract error name → typed SDK error constructor. */
 export type RevertNameMapper = (name: string, args: readonly unknown[] | undefined, ctx: RevertMapperContext) => TokenOpsSdkError | undefined;
 /** Context passed into product mappers. `productContext` lets the call site forward args (vestingId, user, etc.) for the mapper to embed in the typed error. */

package/dist/core/telemetry.d.ts

@@ -29,9 +29,6 @@ export interface SdkTelemetry {
      * Adapters that DO implement it should return a NEW telemetry instance —
      * mutating `this` would leak tags across unrelated consumers sharing the
      * same SDK client.
-     *
-     * Added per backend-integrator-r14 nit-positive friction
-     * (`docs/feedback/resolved/2026-05-24-backend-integrator-r14-minor-sdktelemetry-shape-matches-node-logger-pattern-cleanly.md`).
      */
     scope?(tags: SdkTelemetryTags): SdkTelemetry;
 }

package/dist/core/wagmi-compat.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Internal wagmi v2/v3 compatibility layer.
+ *
+ * The SDK supports both wagmi majors (`peerDependencies.wagmi: "^2.0.0 || ^3.0.0"`).
+ * wagmi v3 renamed `useAccount` → `useConnection` (official v2→v3 migration
+ * guide); `usePublicClient` and `useWalletClient` survive unchanged, so hooks
+ * import those from `"wagmi"` directly. Only the account hook needs resolving.
+ *
+ * The fields the SDK reads are shape-identical across both majors: `address`
+ * lives at the top level of both `useAccount()` (v2) and `useConnection()`
+ * (v3) return values, typed `Address | undefined` until connected.
+ *
+ * This module is intentionally NOT exported from any public subpath — it is an
+ * internal helper for the `src/<product>/react/` hook files. We namespace-import
+ * wagmi so the module typechecks against either major: a named import of
+ * `useAccount` would fail `tsc --noEmit` under v3 (and vice versa for
+ * `useConnection` under v2).
+ */
+import type { Address } from "viem";
+/**
+ * Minimal slice of the wagmi account-hook return value the SDK reads.
+ *
+ * Deliberately narrow: widening this to the full upstream shape would force
+ * this module to pick one major's type surface and break typechecking against
+ * the other. Every field listed here has been verified shape-identical in
+ * wagmi v2 `useAccount()` and wagmi v3 `useConnection()`.
+ */
+export interface WagmiAccountResult {
+    /** Connected address from the active connector; `undefined` while disconnected. */
+    address: Address | undefined;
+}
+/**
+ * The installed wagmi major's account hook: `useConnection` (v3) when present,
+ * else `useAccount` (v2). Resolved once at module load — the installed wagmi
+ * major cannot change at runtime.
+ *
+ * This IS a React hook (it aliases one) — the rules of hooks apply at every
+ * call site.
+ */
+export declare const useWagmiAccount: () => WagmiAccountResult;