@tokenops/sdk 1.0.0 → 1.5.1

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

@@ -44,6 +44,7 @@ export { useFactoryDefaultGasFee } from "./useFactoryDefaultGasFee.js";
 export { useFactoryFeeCollector } from "./useFactoryFeeCollector.js";
 export { useFactoryCustomFee, type UseFactoryCustomFeeArgs } from "./useFactoryCustomFee.js";
 export { useFactoryInitCodeHash, type UseFactoryInitCodeHashArgs, } from "./useFactoryInitCodeHash.js";
+export { usePreflightCreateAirdrop, type UsePreflightCreateAirdropArgs, } from "./usePreflightCreateAirdrop.js";
 export { useCreateConfidentialAirdropAndGetAddress } from "./useCreateConfidentialAirdropAndGetAddress.js";
 export { useCreateConfidentialAirdrop } from "./useCreateConfidentialAirdrop.js";
 export { useCreateAndFundConfidentialAirdrop } from "./useCreateAndFundConfidentialAirdrop.js";
@@ -82,9 +83,9 @@ export { useAirdropRevokeRole, type UseAirdropRevokeRoleArgs } from "./useAirdro
 export { useSignClaimAuthorization, type UseSignClaimAuthorizationArgs, type UseSignClaimAuthorizationOptions, } from "./useSignClaimAuthorization.js";
 export type { BaseHookOptions, AirdropHookOptions, FactoryHookOptions } from "./_shared.js";
 export { encryptUint64, encryptUint64Batch, resolveEncryptor, signClaimAuthorization, type Encryptor, type EncryptorSource, type EncryptUint64Args, type EncryptUint64BatchArgs, type FheValueInput, } from "../encryption.js";
-export { type AirdropParams, type CustomFee, type EncryptedInput, type EncryptedInputs, } from "../types.js";
+export { type AirdropParams, type CreateAirdropPreflightReport, type CustomFee, type EncryptedInput, type EncryptedInputs, } from "../types.js";
 export type { ClaimArgs, EncryptedViewResult, GetClaimAmountArgs, IsSignatureValidArgs, } from "../airdrop.js";
-export type { CreateAirdropResult, CreateAirdropArgs, CreateAndFundAirdropArgs, FundAirdropArgs, PredictAirdropArgs, } from "../factory.js";
-export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ContractRevertError, PausedError, AccessDeniedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../../core/errors.js";
+export type { CreateAirdropResult, CreateAirdropArgs, CreateAndFundAirdropArgs, FundAirdropArgs, PredictAirdropArgs, PreflightCreateAirdropArgs, } from "../factory.js";
+export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ContractRevertError, PausedError, AccessDeniedError, OperatorNotApprovedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../../core/errors.js";
 export { type PreflightResult } from "../../core/preflight.js";
 export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError } from "../errors.js";

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

@@ -44,6 +44,7 @@ export { useFactoryDefaultGasFee } from "./useFactoryDefaultGasFee.js";
 export { useFactoryFeeCollector } from "./useFactoryFeeCollector.js";
 export { useFactoryCustomFee, type UseFactoryCustomFeeArgs } from "./useFactoryCustomFee.js";
 export { useFactoryInitCodeHash, type UseFactoryInitCodeHashArgs, } from "./useFactoryInitCodeHash.js";
+export { usePreflightCreateAirdrop, type UsePreflightCreateAirdropArgs, } from "./usePreflightCreateAirdrop.js";
 export { useCreateConfidentialAirdropAndGetAddress } from "./useCreateConfidentialAirdropAndGetAddress.js";
 export { useCreateConfidentialAirdrop } from "./useCreateConfidentialAirdrop.js";
 export { useCreateAndFundConfidentialAirdrop } from "./useCreateAndFundConfidentialAirdrop.js";
@@ -82,9 +83,9 @@ export { useAirdropRevokeRole, type UseAirdropRevokeRoleArgs } from "./useAirdro
 export { useSignClaimAuthorization, type UseSignClaimAuthorizationArgs, type UseSignClaimAuthorizationOptions, } from "./useSignClaimAuthorization.js";
 export type { BaseHookOptions, AirdropHookOptions, FactoryHookOptions } from "./_shared.js";
 export { encryptUint64, encryptUint64Batch, resolveEncryptor, signClaimAuthorization, type Encryptor, type EncryptorSource, type EncryptUint64Args, type EncryptUint64BatchArgs, type FheValueInput, } from "../encryption.js";
-export { type AirdropParams, type CustomFee, type EncryptedInput, type EncryptedInputs, } from "../types.js";
+export { type AirdropParams, type CreateAirdropPreflightReport, type CustomFee, type EncryptedInput, type EncryptedInputs, } from "../types.js";
 export type { ClaimArgs, EncryptedViewResult, GetClaimAmountArgs, IsSignatureValidArgs, } from "../airdrop.js";
-export type { CreateAirdropResult, CreateAirdropArgs, CreateAndFundAirdropArgs, FundAirdropArgs, PredictAirdropArgs, } from "../factory.js";
-export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ContractRevertError, PausedError, AccessDeniedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../../core/errors.js";
+export type { CreateAirdropResult, CreateAirdropArgs, CreateAndFundAirdropArgs, FundAirdropArgs, PredictAirdropArgs, PreflightCreateAirdropArgs, } from "../factory.js";
+export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ContractRevertError, PausedError, AccessDeniedError, OperatorNotApprovedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../../core/errors.js";
 export { type PreflightResult } from "../../core/preflight.js";
 export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError } from "../errors.js";

package/dist/fhe-airdrop/react/index.js

@@ -1,17 +1,19 @@
-import { useMemoFactoryClient, buildQueryKey, useMemoAirdropClient } from '../../chunk-HGXNRR25.js';
-export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError } from '../../chunk-XXXDQSHE.js';
-import { signClaimAuthorization } from '../../chunk-UOG4PJL5.js';
-export { encryptUint64, encryptUint64Batch, resolveEncryptor, signClaimAuthorization } from '../../chunk-UOG4PJL5.js';
-import '../../chunk-FYQ2UW4T.js';
-import '../../chunk-JFLEEXKP.js';
-import '../../chunk-COPFW5Z4.js';
-import '../../chunk-BE2AIZ3K.js';
+import { useMemoFactoryClient, buildQueryKey, useMemoAirdropClient } from '../../chunk-ORFTDNFZ.js';
+export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError } from '../../chunk-6R4KNAPK.js';
+import { signClaimAuthorization } from '../../chunk-DUZIIRPF.js';
+export { encryptUint64, encryptUint64Batch, resolveEncryptor, signClaimAuthorization } from '../../chunk-DUZIIRPF.js';
+import { useWagmiAccount } from '../../chunk-FT4LNBOS.js';
+import '../../chunk-ZWXJTBZO.js';
+import '../../chunk-7VELUOMI.js';
+import '../../chunk-SG65XWH7.js';
+import '../../chunk-XGGTQQFH.js';
+import '../../chunk-ZA673I3O.js';
 import '../../chunk-Q2GP5UDC.js';
 import '../../chunk-KWFFIJYX.js';
-import { MissingClientError, MissingWalletClientError } 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, TokenOpsSdkError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../../chunk-IVE3QEGD.js';
+import { MissingClientError, MissingWalletClientError } from '../../chunk-QBJ7O2B4.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, TokenOpsSdkError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../../chunk-QBJ7O2B4.js';
 import { useQuery, useMutation } from '@tanstack/react-query';
-import { useAccount, useWalletClient } from 'wagmi';
+import { useWalletClient } from 'wagmi';
 
 function useConfidentialAirdropFactoryImplementation(options = {}) {
   const { client, chainId, resolvedAddress } = useMemoFactoryClient(options);
@@ -60,6 +62,29 @@ function useFactoryInitCodeHash(args = {}) {
     staleTime: 0
   });
 }
+function usePreflightCreateAirdrop(args = {}) {
+  const { params, creator, userSalt, funding, ...base } = args;
+  const { client, chainId, resolvedAddress } = useMemoFactoryClient(base);
+  return useQuery({
+    queryKey: buildQueryKey(
+      "factory:preflightCreateAirdrop",
+      chainId,
+      resolvedAddress,
+      creator,
+      params,
+      userSalt,
+      funding
+    ),
+    queryFn: () => client.preflightCreateAirdrop({
+      params,
+      creator,
+      ...userSalt !== void 0 ? { userSalt } : {},
+      ...funding !== void 0 ? { funding } : {}
+    }),
+    enabled: !!client && !!params && !!creator,
+    staleTime: 0
+  });
+}
 function useCreateConfidentialAirdropAndGetAddress(options = {}) {
   const { client, resolutionError } = useMemoFactoryClient(options);
   return useMutation({
@@ -290,7 +315,7 @@ function useAirdropIsSignatureClaimed(args) {
 function useAirdropIsSignatureValid(args) {
   const { encryptedAmountHandle, signature, caller, ...base } = args;
   const { client, chainId } = useMemoAirdropClient(base);
-  const { address: connectedAddress } = useAccount();
+  const { address: connectedAddress } = useWagmiAccount();
   const resolvedCaller = caller ?? connectedAddress;
   return useQuery({
     queryKey: buildQueryKey(
@@ -427,4 +452,4 @@ function useSignClaimAuthorization(options = {}) {
   });
 }
 
-export { useAirdropCanExtendClaimWindow, useAirdropClaimTypehash, useAirdropClaimedSignatures, useAirdropDeploymentBlockNumber, useAirdropDomainSeparator, useAirdropEndTime, useAirdropGasFee, useAirdropGrantRole, useAirdropHasClaimEnded, useAirdropHasClaimStarted, useAirdropHasRole, useAirdropIsClaimWindowActive, useAirdropIsPaused, useAirdropIsSignatureClaimed, useAirdropIsSignatureValid, useAirdropRevokeRole, useAirdropStartTime, useAirdropToken, useAirdropWithdrawGasFee, useClaim, useConfidentialAirdropFactoryImplementation, useCreateAndFundConfidentialAirdrop, useCreateAndFundConfidentialAirdropAndGetAddress, useCreateConfidentialAirdrop, useCreateConfidentialAirdropAndGetAddress, useDisableCustomFee, useExtendClaimWindow, useFactoryCustomFee, useFactoryDefaultGasFee, useFactoryFeeCollector, useFactoryInitCodeHash, useFundConfidentialAirdrop, useGetClaimAmount, useSetCustomFee, useSetDefaultGasFee, useSetFeeCollector, useSetPaused, useSignClaimAuthorization, useWithdraw, useWithdrawOtherConfidentialToken, useWithdrawOtherToken };
+export { useAirdropCanExtendClaimWindow, useAirdropClaimTypehash, useAirdropClaimedSignatures, useAirdropDeploymentBlockNumber, useAirdropDomainSeparator, useAirdropEndTime, useAirdropGasFee, useAirdropGrantRole, useAirdropHasClaimEnded, useAirdropHasClaimStarted, useAirdropHasRole, useAirdropIsClaimWindowActive, useAirdropIsPaused, useAirdropIsSignatureClaimed, useAirdropIsSignatureValid, useAirdropRevokeRole, useAirdropStartTime, useAirdropToken, useAirdropWithdrawGasFee, useClaim, useConfidentialAirdropFactoryImplementation, useCreateAndFundConfidentialAirdrop, useCreateAndFundConfidentialAirdropAndGetAddress, useCreateConfidentialAirdrop, useCreateConfidentialAirdropAndGetAddress, useDisableCustomFee, useExtendClaimWindow, useFactoryCustomFee, useFactoryDefaultGasFee, useFactoryFeeCollector, useFactoryInitCodeHash, useFundConfidentialAirdrop, useGetClaimAmount, usePreflightCreateAirdrop, useSetCustomFee, useSetDefaultGasFee, useSetFeeCollector, useSetPaused, useSignClaimAuthorization, useWithdraw, useWithdrawOtherConfidentialToken, useWithdrawOtherToken };

package/dist/fhe-airdrop/react/useAirdropClaim.d.ts

@@ -18,6 +18,8 @@ import { type AirdropHookOptions } from "./_shared.js";
  * `useAirdropIsSignatureClaimed({ user, encryptedAmountHandle })` and any
  * UI counts you computed off it.
  *
+ * **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.
+ *
  * @example
  * const claim = useAirdropClaim({ address: airdropAddress, encryptor: () => useZamaSDK().relayer });
  * claim.mutate({ amount: 1_000_000n, signature });

package/dist/fhe-airdrop/react/useAirdropIsSignatureValid.d.ts

@@ -9,8 +9,9 @@ export interface UseAirdropIsSignatureValidArgs extends AirdropHookOptions {
     /**
      * Caller address — the contract recomputes the struct hash over
      * `(msg.sender, encryptedAmount)`, so validity is caller-specific.
-     * Defaults to the connected wallet via `wagmi`'s `useAccount()`; pass
-     * explicitly to check on behalf of another address.
+     * Defaults to the connected wallet via wagmi's account hook (v2
+     * `useAccount()` / v3 `useConnection()`); pass explicitly to check on
+     * behalf of another address.
      */
     caller?: Address;
 }

package/dist/fhe-airdrop/react/useClaim.d.ts

@@ -22,6 +22,8 @@ import { type AirdropHookOptions } from "./_shared.js";
  * `useAirdropIsSignatureClaimed({ user, encryptedAmountHandle })` and any
  * UI counts you computed off it.
  *
+ * **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.
+ *
  * @example
  * const claim = useClaim({ address: airdropAddress });
  * claim.mutate({ encryptedInput, signature });

package/dist/fhe-airdrop/react/useCreateAndFundConfidentialAirdrop.d.ts

@@ -15,6 +15,14 @@ import { type FactoryHookOptions } from "./_shared.js";
  * **Prerequisites:** caller must have set the 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.
+ *
  * After success, invalidate factory queries that depend on per-creator state:
  *
  * ```ts

package/dist/fhe-airdrop/react/useCreateAndFundConfidentialAirdropAndGetAddress.d.ts

@@ -13,6 +13,14 @@ import { type FactoryHookOptions } from "./_shared.js";
  * Internally: `createAndFundConfidentialAirdrop` → `waitForTransactionReceipt`
  * → `parseEventLogs({ eventName: "ConfidentialAirdropCreated" })`.
  *
+ * **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.
+ *
  * After a successful create, invalidate factory queries that depend on
  * per-creator state:
  *

package/dist/fhe-airdrop/react/useFundConfidentialAirdrop.d.ts

@@ -17,6 +17,14 @@ import { type FactoryHookOptions } from "./_shared.js";
  * **Prerequisites:** caller must have set the 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.
+ *
  * **`args.gasFee` MUST match the fee active for `deployer` at airdrop creation
  * time** — custom fee if `getCustomFee(deployer).enabled`, otherwise
  * `defaultGasFee`. The factory derives the target clone address from this

package/dist/fhe-airdrop/react/usePreflightCreateAirdrop.d.ts

@@ -0,0 +1,51 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { AirdropParams, CreateAirdropPreflightReport } from "../types.js";
+import { type BaseHookOptions } from "./_shared.js";
+export interface UsePreflightCreateAirdropArgs extends BaseHookOptions {
+    /** The airdrop parameters that will be passed to the create call. */
+    params?: AirdropParams;
+    /** The address that will send the create transaction (`msg.sender`). */
+    creator?: Address;
+    /**
+     * The `userSalt` planned for the create call. Optional — when supplied, the
+     * report also carries `predictedAirdrop` and `alreadyDeployed`.
+     */
+    userSalt?: Hex;
+    /**
+     * Set `true` when the plan is `useCreateAndFundConfidentialAirdrop` — a
+     * missing factory-operator approval then becomes a blocker instead of
+     * informational `isFactoryOperator` state.
+     */
+    funding?: boolean;
+}
+/**
+ * Read-only preflight for `useCreateConfidentialAirdrop` /
+ * `useCreateAndFundConfidentialAirdrop` — wraps
+ * {@link ConfidentialAirdropFactoryClient.preflightCreateAirdrop} as a
+ * TanStack query.
+ *
+ * The report carries `isFactoryOperator`, `gasFee`, `predictedAirdrop`,
+ * `alreadyDeployed`, `ready`, `blockers` (human-readable strings) and
+ * `blockerErrors` (typed `TokenOpsSdkError`s, index-aligned with `blockers` —
+ * branch on `error.code`).
+ *
+ * Checks: structural `params` validation (non-zero token/admin, timestamp
+ * ordering, end time in the future), ERC-7984 operator approval of the
+ * factory on `params.token` (blocker only with `funding: true`), and — when
+ * `userSalt` is set — whether a clone already exists at the predicted CREATE2
+ * address. The creator's confidential token balance is NOT checked
+ * (encrypted; an underfunded create-and-fund silently moves an encrypted
+ * zero) — see the headless method's TSDoc.
+ *
+ * Hook is disabled until `params` and `creator` are both set. Refetch after
+ * the user calls `setOperator` (e.g. via `queryClient.invalidateQueries` or a
+ * `refetchInterval`).
+ *
+ * @example
+ * const { data: report } = usePreflightCreateAirdrop({
+ *   params, creator, userSalt, funding: true,
+ * });
+ * if (report?.ready) { /* enable submit *\/ }
+ */
+export declare function usePreflightCreateAirdrop(args?: UsePreflightCreateAirdropArgs): UseQueryResult<CreateAirdropPreflightReport, Error>;

package/dist/fhe-airdrop/types.d.ts

@@ -1,4 +1,5 @@
 import type { Address } from "viem";
+import type { TokenOpsSdkError } from "../core/errors.js";
 export type { EncryptedInput, EncryptedInputs, EncryptedViewResult } from "../fhe/types.js";
 /**
  * Parameters for creating a confidential airdrop.
@@ -19,3 +20,47 @@ export interface CustomFee {
     enabled: boolean;
     gasFee: bigint;
 }
+/**
+ * Report returned by `ConfidentialAirdropFactoryClient.preflightCreateAirdrop`.
+ *
+ * Fields:
+ * - `isFactoryOperator` — `true` when the creator has approved the factory as
+ *   an ERC-7984 operator on `params.token`. Only required when funding in the
+ *   same transaction (`createAndFundConfidentialAirdrop` /
+ *   `fundConfidentialAirdrop`); `false` also when the token address was
+ *   structurally invalid and the read was skipped.
+ * - `gasFee` — the per-claim gas fee (wei) the factory will embed into the
+ *   clone for this creator: the creator's custom fee when one is enabled,
+ *   otherwise `defaultGasFee`. This is the `gasFee` to use for address
+ *   prediction and later `fundConfidentialAirdrop` calls.
+ * - `predictedAirdrop` — deterministic CREATE2 clone address for
+ *   `(params, userSalt, creator, gasFee)`. `undefined` when `userSalt` was not
+ *   supplied or the params were structurally invalid.
+ * - `alreadyDeployed` — `true` when bytecode already exists at
+ *   `predictedAirdrop` (a repeat create with the same salt would revert).
+ *   `undefined` when `predictedAirdrop` is `undefined`.
+ * - `ready` — `true` when no blockers were detected.
+ * - `blockers` — human-readable blocker descriptions. Empty when
+ *   `ready === true`.
+ * - `blockerErrors` — the same blockers as typed `TokenOpsSdkError`s, index-
+ *   aligned with `blockers`. Branch on `error.code` to render UI.
+ */
+export interface CreateAirdropPreflightReport {
+    /** `true` when the creator has approved the factory as operator on `params.token`. */
+    isFactoryOperator: boolean;
+    /** Per-claim gas fee (wei) the factory will embed into the clone for this creator. */
+    gasFee: bigint;
+    /** Predicted CREATE2 clone address. `undefined` without `userSalt` or with invalid params. */
+    predictedAirdrop?: Address;
+    /** `true` when bytecode already exists at `predictedAirdrop`. `undefined` when not predicted. */
+    alreadyDeployed?: boolean;
+    /** `true` when no blockers were detected — green light to submit the write. */
+    ready: boolean;
+    /** Human-readable blocker descriptions. Empty when `ready === true`. */
+    blockers: string[];
+    /**
+     * Typed errors that would otherwise surface at write time, index-aligned
+     * with `blockers`. Empty when `ready === true`.
+     */
+    blockerErrors: TokenOpsSdkError[];
+}

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

@@ -62,6 +62,14 @@ export interface EncryptUint64BatchArgs {
 }
 /**
  * Encrypt a single `uint64` value into an `externalEuint64` handle + KMS input proof.
+ *
+ * **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.
  */
 export declare function encryptUint64({ encryptor, contractAddress, userAddress, value, }: EncryptUint64Args): Promise<EncryptedInput>;
 /**