@tokenops/sdk 1.0.0 → 1.5.1

package/dist/fhe-disperse/react/useSingletonCalculateFee.d.ts

@@ -18,6 +18,13 @@ export interface UseSingletonCalculateFeeArgs extends BaseHookOptions {
  *
  * Hook is disabled until `user`, `mode`, and `recipients` are set.
  *
+ * **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. `totalTokens` follows this
+ * convention.
+ *
  * @example
  * const { data: fee } = useSingletonCalculateFee({
  *   user, mode: "direct", recipients: 100,

package/dist/fhe-disperse/react/useSingletonWithdrawTokenFee.d.ts

@@ -10,8 +10,8 @@ import { type DisperseHookOptions } from "./_shared.js";
  * the discriminated SDK shape.
  *
  * `amount` and `encryptedInput` are XOR enforced by the underlying SDK call;
- * the hook surface mirrors the relaxed pre-S-4 shape (callers had been writing
- * it that way for two rounds) and the mutate body routes to the right branch.
+ * the hook surface accepts the relaxed shape and the mutate body routes to the
+ * right branch.
  */
 export interface UseSingletonWithdrawTokenFeeArgs {
     /** ERC-7984 token whose accumulated fee reserve to withdraw from. */
@@ -36,6 +36,12 @@ export interface UseSingletonWithdrawTokenFeeArgs {
  * `amount` is encrypted by the SDK before submission; the contract caps the
  * withdrawal at the available reserve via `FHE.min`.
  *
+ * **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.
+ *
  * **Encryptor resolution.** Pass `encryptor` per-call, or supply it at hook
  * construction via {@link DisperseHookOptions}.`encryptor`. If neither is
  * present, the SDK throws `Missing encryptor — pass encryptor…` verbatim.

package/dist/fhe-disperse/react/useWithdrawTokenFee.d.ts

@@ -43,6 +43,12 @@ export type UseWithdrawTokenFeeArgs = UseWithdrawTokenFeePlaintextArgs | UseWith
  * never both. The contract caps the withdrawal at the available reserve via
  * `FHE.min`.
  *
+ * **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 `{ hash, transferredHandle }` parsed from the `TokenFeeWithdrawn`
  * event. The handle is decryptable by the caller via Zama's `userDecrypt`
  * and reveals the actual transferred amount, which may be less than the

package/dist/fhe-disperse/singleton.d.ts

@@ -153,6 +153,13 @@ export declare class ConfidentialDisperseClient {
      * subtotal1` for the result to match the on-chain computation. Both this
      * SDK and the contract round the BPS multiplication down (floor division).
      *
+     * **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. `totalTokens` follows this
+     * convention.
+     *
      * @throws {TokenOpsSdkError} if mode is `"wallet-token-fee"` and `totalTokens` is not provided.
      */
     calculateFee(args: CalculateFeeArgs): Promise<CalculatedFee>;
@@ -179,6 +186,13 @@ export declare class ConfidentialDisperseClient {
      * - `hasApprovedSubwallets` (wallet modes) or `isOperator(sender, singleton)` (direct mode)
      * - `calculateFee` / `getBatchLimits`
      * - Structural recipient + amount validation
+     *
+     * **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. Pass `amounts[]` in the same
+     * units you will pass to `disperse` so the report reflects the real call.
      */
     preflightDisperse(args: PreflightDisperseArgs): Promise<PreflightReport>;
     /**
@@ -249,6 +263,15 @@ export declare class ConfidentialDisperseClient {
      * 4. Computes `msg.value` for gas-fee modes; `0` for token-fee mode.
      * 5. Dispatches to the correct contract function based on `mode`.
      *
+     * **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. Every entry of `amounts[]`
+     * follows this convention.
+     *
      * @throws {TokenOpsSdkError} on input validation failure (first deterministic error).
      * @throws {TokenOpsSdkError} if no encryptor is available at call time.
      */
@@ -352,6 +375,12 @@ export declare class ConfidentialDisperseClient {
      * encryptor, or pass `encryptedInput` directly. The contract caps the
      * withdrawal at the available reserve via `FHE.min`.
      *
+     * **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 the tx hash plus the **transferred** handle parsed from the
      * `TokenFeeWithdrawn` event. Decrypt the handle via Zama's `userDecrypt`
      * to view the actual amount moved (which can be less than requested when

package/dist/fhe-disperse/subtotals.d.ts

@@ -7,6 +7,12 @@
  *   group1 = remaining baseSize recipients            →  wallet1
  *
  * This matches `_distributeFromWallets` in `DisperseConfidential.sol`.
+ *
+ * **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.
  */
 export declare function computeSubtotals(amounts: bigint[]): {
     group0: bigint;

package/dist/fhe-vesting/advanced/factory-advanced.d.ts

@@ -4,8 +4,8 @@ import { ConfidentialVestingFactoryClient, type ConfidentialVestingFactoryClient
  * Advanced extension of {@link ConfidentialVestingFactoryClient} that re-exposes
  * the CREATE2 address prediction read.
  *
- * **Why this is "advanced" surface.** R02 ADR P-1 + P-2 (alignment-auditor R04
- * top-1): `predictManagerAddress` is block-dependent on a live chain — the
+ * **Why this is "advanced" surface.** `predictManagerAddress` is
+ * block-dependent on a live chain — the
  * factory packs the deployment block number into the clone's immutable args,
  * which feed into the CREATE2 init-code hash. Predict at block N, mine at
  * N+1, and the addresses differ. The vast majority of consumers want

package/dist/fhe-vesting/advanced/index.cjs

@@ -1,21 +1,21 @@
 'use strict';
 
-var chunkQCA7O2Q5_cjs = require('../../chunk-QCA7O2Q5.cjs');
-require('../../chunk-62DF53UQ.cjs');
-require('../../chunk-VDXVNZCO.cjs');
-require('../../chunk-OLDGMKW2.cjs');
-require('../../chunk-CQIPRNS7.cjs');
+var chunkV2PXZVBF_cjs = require('../../chunk-V2PXZVBF.cjs');
+require('../../chunk-C7BRZXJA.cjs');
+require('../../chunk-KLKI352M.cjs');
+require('../../chunk-PUPKNW3R.cjs');
+require('../../chunk-JK4XMMKM.cjs');
 require('../../chunk-VJKZWYYJ.cjs');
 require('../../chunk-66IHPTOK.cjs');
-require('../../chunk-56UI7LUR.cjs');
+require('../../chunk-67OV5CX2.cjs');
 
 
 
 Object.defineProperty(exports, "ConfidentialVestingFactoryAdvancedClient", {
   enumerable: true,
-  get: function () { return chunkQCA7O2Q5_cjs.ConfidentialVestingFactoryAdvancedClient; }
+  get: function () { return chunkV2PXZVBF_cjs.ConfidentialVestingFactoryAdvancedClient; }
 });
 Object.defineProperty(exports, "createConfidentialVestingFactoryAdvancedClient", {
   enumerable: true,
-  get: function () { return chunkQCA7O2Q5_cjs.createConfidentialVestingFactoryAdvancedClient; }
+  get: function () { return chunkV2PXZVBF_cjs.createConfidentialVestingFactoryAdvancedClient; }
 });

package/dist/fhe-vesting/advanced/index.d.cts

@@ -1,12 +1,12 @@
 /**
  * Advanced FHE-vesting primitives — power-user surface kept off the headline
- * client to keep the 90 % path lean (R02 ADR P-2; alignment-auditor R04 top-1).
+ * client to keep the common path lean.
  *
  * Re-exports the {@link ConfidentialVestingFactoryAdvancedClient} subclass,
  * which extends the headline factory client with `predictManagerAddress`. The
  * predict read is block-dependent — see the subclass TSDoc. For the common
  * "deploy and learn the address" case, the headline factory's
- * `createManager` returns `{ hash, manager }` directly (R02 ADR P-1).
+ * `createManager` returns `{ hash, manager }` directly.
  */
 export { ConfidentialVestingFactoryAdvancedClient, createConfidentialVestingFactoryAdvancedClient, } from "./factory-advanced.js";
 export type { PredictManagerArgs } from "../factory.js";

package/dist/fhe-vesting/advanced/index.d.ts

@@ -1,12 +1,12 @@
 /**
  * Advanced FHE-vesting primitives — power-user surface kept off the headline
- * client to keep the 90 % path lean (R02 ADR P-2; alignment-auditor R04 top-1).
+ * client to keep the common path lean.
  *
  * Re-exports the {@link ConfidentialVestingFactoryAdvancedClient} subclass,
  * which extends the headline factory client with `predictManagerAddress`. The
  * predict read is block-dependent — see the subclass TSDoc. For the common
  * "deploy and learn the address" case, the headline factory's
- * `createManager` returns `{ hash, manager }` directly (R02 ADR P-1).
+ * `createManager` returns `{ hash, manager }` directly.
  */
 export { ConfidentialVestingFactoryAdvancedClient, createConfidentialVestingFactoryAdvancedClient, } from "./factory-advanced.js";
 export type { PredictManagerArgs } from "../factory.js";

package/dist/fhe-vesting/advanced/index.js

@@ -1,8 +1,8 @@
-export { ConfidentialVestingFactoryAdvancedClient, createConfidentialVestingFactoryAdvancedClient } from '../../chunk-CMRETRZO.js';
-import '../../chunk-72YGZEQE.js';
-import '../../chunk-JFLEEXKP.js';
-import '../../chunk-COPFW5Z4.js';
-import '../../chunk-BE2AIZ3K.js';
+export { ConfidentialVestingFactoryAdvancedClient, createConfidentialVestingFactoryAdvancedClient } from '../../chunk-YQIBBEFJ.js';
+import '../../chunk-OXTLPTO3.js';
+import '../../chunk-SG65XWH7.js';
+import '../../chunk-XGGTQQFH.js';
+import '../../chunk-ZA673I3O.js';
 import '../../chunk-Q2GP5UDC.js';
 import '../../chunk-KWFFIJYX.js';
-import '../../chunk-IVE3QEGD.js';
+import '../../chunk-QBJ7O2B4.js';

package/dist/fhe-vesting/advanced/react/index.cjs

@@ -1,18 +1,19 @@
 'use strict';
 
-var chunkJFR5J4FL_cjs = require('../../../chunk-JFR5J4FL.cjs');
-require('../../../chunk-SUOG3BQS.cjs');
-require('../../../chunk-NS44KBV5.cjs');
-require('../../../chunk-5SGMJADP.cjs');
-require('../../../chunk-Q7ARQSUH.cjs');
-var chunkQCA7O2Q5_cjs = require('../../../chunk-QCA7O2Q5.cjs');
-require('../../../chunk-62DF53UQ.cjs');
-require('../../../chunk-VDXVNZCO.cjs');
-var chunkOLDGMKW2_cjs = require('../../../chunk-OLDGMKW2.cjs');
-require('../../../chunk-CQIPRNS7.cjs');
+var chunkW7IGCOVL_cjs = require('../../../chunk-W7IGCOVL.cjs');
+require('../../../chunk-5X5WL5CU.cjs');
+require('../../../chunk-TEBM66WA.cjs');
+require('../../../chunk-2NCLOQ56.cjs');
+require('../../../chunk-FAXIIH5R.cjs');
+require('../../../chunk-FWHYQZ5E.cjs');
+var chunkV2PXZVBF_cjs = require('../../../chunk-V2PXZVBF.cjs');
+require('../../../chunk-C7BRZXJA.cjs');
+require('../../../chunk-KLKI352M.cjs');
+var chunkPUPKNW3R_cjs = require('../../../chunk-PUPKNW3R.cjs');
+require('../../../chunk-JK4XMMKM.cjs');
 require('../../../chunk-VJKZWYYJ.cjs');
 require('../../../chunk-66IHPTOK.cjs');
-require('../../../chunk-56UI7LUR.cjs');
+require('../../../chunk-67OV5CX2.cjs');
 var react = require('react');
 var reactQuery = require('@tanstack/react-query');
 var wagmi = require('wagmi');
@@ -35,12 +36,12 @@ function usePredictManagerAddress(args = {}) {
     ...chainId !== void 0 ? { chainId } : {}
   });
   const resolvedChainId = chainId ?? resolvedPublicClient?.chain?.id;
-  const resolvedAddress = address ?? (resolvedChainId === void 0 ? void 0 : chunkOLDGMKW2_cjs.DEPLOYED_ADDRESSES.fheVesting?.confidentialVestingFactory?.[resolvedChainId] ?? void 0);
+  const resolvedAddress = address ?? (resolvedChainId === void 0 ? void 0 : chunkPUPKNW3R_cjs.DEPLOYED_ADDRESSES.fheVesting?.confidentialVestingFactory?.[resolvedChainId] ?? void 0);
   react.useRef(void 0);
   const client = react.useMemo(() => {
     if (!resolvedPublicClient) return void 0;
     if (!resolvedAddress) return void 0;
-    return chunkQCA7O2Q5_cjs.createConfidentialVestingFactoryAdvancedClient({
+    return chunkV2PXZVBF_cjs.createConfidentialVestingFactoryAdvancedClient({
       publicClient: resolvedPublicClient,
       ...walletClient ? { walletClient } : {},
       address: resolvedAddress,
@@ -48,7 +49,7 @@ function usePredictManagerAddress(args = {}) {
     });
   }, [resolvedPublicClient, walletClient, resolvedAddress, resolvedChainId]);
   return reactQuery.useQuery({
-    queryKey: chunkJFR5J4FL_cjs.buildQueryKey(
+    queryKey: chunkW7IGCOVL_cjs.buildQueryKey(
       "factory:predictManagerAddress",
       resolvedChainId,
       resolvedAddress,

package/dist/fhe-vesting/advanced/react/index.d.cts

@@ -1,5 +1,5 @@
 /**
  * React hooks for `@tokenops/sdk/fhe-vesting/advanced`. The headline React
- * subpath stays lean; pre-mine address prediction lives here per R02 ADR P-2.
+ * subpath stays lean; pre-mine address prediction lives here.
  */
 export { usePredictManagerAddress, type UsePredictManagerAddressArgs, } from "./usePredictManagerAddress.js";

package/dist/fhe-vesting/advanced/react/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * React hooks for `@tokenops/sdk/fhe-vesting/advanced`. The headline React
- * subpath stays lean; pre-mine address prediction lives here per R02 ADR P-2.
+ * subpath stays lean; pre-mine address prediction lives here.
  */
 export { usePredictManagerAddress, type UsePredictManagerAddressArgs, } from "./usePredictManagerAddress.js";

package/dist/fhe-vesting/advanced/react/index.js

@@ -1,16 +1,17 @@
-import { buildQueryKey } from '../../../chunk-ECT3NL2L.js';
-import '../../../chunk-52TC6BF7.js';
-import '../../../chunk-ZXCOJY2Z.js';
-import '../../../chunk-XSNLAS5M.js';
-import '../../../chunk-FYQ2UW4T.js';
-import { createConfidentialVestingFactoryAdvancedClient } from '../../../chunk-CMRETRZO.js';
-import '../../../chunk-72YGZEQE.js';
-import '../../../chunk-JFLEEXKP.js';
-import { DEPLOYED_ADDRESSES } from '../../../chunk-COPFW5Z4.js';
-import '../../../chunk-BE2AIZ3K.js';
+import { buildQueryKey } from '../../../chunk-NTZY6IB7.js';
+import '../../../chunk-IXLO7GO5.js';
+import '../../../chunk-WMACINXO.js';
+import '../../../chunk-AOP6HMPW.js';
+import '../../../chunk-ZWXJTBZO.js';
+import '../../../chunk-7VELUOMI.js';
+import { createConfidentialVestingFactoryAdvancedClient } from '../../../chunk-YQIBBEFJ.js';
+import '../../../chunk-OXTLPTO3.js';
+import '../../../chunk-SG65XWH7.js';
+import { DEPLOYED_ADDRESSES } from '../../../chunk-XGGTQQFH.js';
+import '../../../chunk-ZA673I3O.js';
 import '../../../chunk-Q2GP5UDC.js';
 import '../../../chunk-KWFFIJYX.js';
-import '../../../chunk-IVE3QEGD.js';
+import '../../../chunk-QBJ7O2B4.js';
 import { useRef, useMemo } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { usePublicClient, useWalletClient } from 'wagmi';

package/dist/fhe-vesting/encryption.d.ts

@@ -79,6 +79,14 @@ export interface EncryptUint64BatchArgs {
  * The handle and proof are bound to `contractAddress` and `userAddress` — they
  * cannot be replayed against a different contract or sender.
  *
+ * **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. `value` (and each entry of
+ * `values` in {@link encryptUint64Batch}) follows this convention when it
+ * encodes a token amount.
+ *
  * @param args Encryption request; `value` must fit in `uint64` (0 to 2^64-1).
  * @returns `{ handle: Hex, inputProof: Hex }` — pass both to the contract.
  * @example

package/dist/fhe-vesting/factory.d.ts

@@ -72,7 +72,7 @@ export interface PredictManagerArgs {
  * Rich-return shape from {@link ConfidentialVestingFactoryClient.createManager}.
  *
  * Branded `hash: TxHash` and `manager: Address` so consumers can't accidentally
- * swap them at the destructure site (R03 S-1 anti-footgun).
+ * swap them at the destructure site.
  */
 export interface CreateManagerResult {
     /** Transaction hash of the deploy. */
@@ -99,11 +99,10 @@ export declare class ConfidentialVestingFactoryClient {
      * Deploy a new `ConfidentialVestingManager` clone via the factory and return
      * its address, parsed from the `ManagerCreated` event in the tx receipt.
      *
-     * **This is the headline factory entry point.** R02 ADR P-1 collapses the
-     * old hash-only + `…AndGetAddress` pair down to one rich-return method —
-     * the address is only knowable after the tx mines (the factory packs
+     * **This is the headline factory entry point.** It returns one rich-return
+     * shape: the address is only knowable after the tx mines (the factory packs
      * `block.number` into the clone's immutable args), so a hash-only variant
-     * forced consumers to re-derive what the SDK already had to compute.
+     * would force consumers to re-derive what the SDK already had to compute.
      *
      * Calls `createManagerWithOptions` when `splitEnabled` or `pausableEnabled`
      * is provided; otherwise calls the simpler `createManager` entry point.
@@ -178,9 +177,8 @@ export declare class ConfidentialVestingFactoryClient {
      * Alias for {@link ConfidentialVestingFactoryClient.implementation} that matches
      * the contract's storage field name (`_managerImplementation`).
      *
-     * Renamed for clarity per backend-integrator-r14 friction
-     * (`docs/feedback/inbox/2026-05-24-backend-integrator-r14-minor-implementation-vs-manager-implementation-naming.md`):
-     * server devs reading the Solidity reach for `factory.managerImplementation()`
+     * Named for clarity: server devs reading the Solidity reach for
+     * `factory.managerImplementation()`
      * via autocomplete (the contract storage slot name) and hit a TS2551. The
      * canonical `implementation()` method is retained for backwards-compat and
      * cross-factory uniformity (fhe-airdrop exposes the same shape).