@tokenops/sdk 1.1.1 → 1.6.0

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";
@@ -70,7 +71,7 @@ export { useAirdropIsSignatureClaimed, type UseAirdropIsSignatureClaimedArgs, }
 export { useAirdropIsSignatureValid, type UseAirdropIsSignatureValidArgs, } from "./useAirdropIsSignatureValid.js";
 export { useAirdropHasRole, type UseAirdropHasRoleArgs } from "./useAirdropHasRole.js";
 export { useClaim } from "./useClaim.js";
-export { useGetClaimAmount } from "./useGetClaimAmount.js";
+export { useAccessClaimAmount, useGetClaimAmount } from "./useAccessClaimAmount.js";
 export { useWithdraw, type UseWithdrawArgs } from "./useWithdraw.js";
 export { useSetPaused, type UseSetPausedArgs } from "./useSetPaused.js";
 export { useExtendClaimWindow, type UseExtendClaimWindowArgs } from "./useExtendClaimWindow.js";
@@ -82,9 +83,11 @@ 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";
+export { useIsOperator, type UseIsOperatorOptions } from "../../fhe/react/useIsOperator.js";
+export { useEnsureOperator, type UseEnsureOperatorOptions, type EnsureOperatorVariables, } from "../../fhe/react/useEnsureOperator.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";
@@ -70,7 +71,7 @@ export { useAirdropIsSignatureClaimed, type UseAirdropIsSignatureClaimedArgs, }
 export { useAirdropIsSignatureValid, type UseAirdropIsSignatureValidArgs, } from "./useAirdropIsSignatureValid.js";
 export { useAirdropHasRole, type UseAirdropHasRoleArgs } from "./useAirdropHasRole.js";
 export { useClaim } from "./useClaim.js";
-export { useGetClaimAmount } from "./useGetClaimAmount.js";
+export { useAccessClaimAmount, useGetClaimAmount } from "./useAccessClaimAmount.js";
 export { useWithdraw, type UseWithdrawArgs } from "./useWithdraw.js";
 export { useSetPaused, type UseSetPausedArgs } from "./useSetPaused.js";
 export { useExtendClaimWindow, type UseExtendClaimWindowArgs } from "./useExtendClaimWindow.js";
@@ -82,9 +83,11 @@ 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";
+export { useIsOperator, type UseIsOperatorOptions } from "../../fhe/react/useIsOperator.js";
+export { useEnsureOperator, type UseEnsureOperatorOptions, type EnsureOperatorVariables, } from "../../fhe/react/useEnsureOperator.js";

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

@@ -1,17 +1,20 @@
-import { useMemoFactoryClient, buildQueryKey, useMemoAirdropClient } from '../../chunk-XWDVPV42.js';
-export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError } from '../../chunk-XXXDQSHE.js';
-import { signClaimAuthorization } from '../../chunk-OQZAZIAS.js';
-export { encryptUint64, encryptUint64Batch, resolveEncryptor, signClaimAuthorization } from '../../chunk-OQZAZIAS.js';
-import '../../chunk-FYQ2UW4T.js';
-import '../../chunk-JFLEEXKP.js';
-import '../../chunk-M7V2EDPB.js';
-import '../../chunk-BE2AIZ3K.js';
+import { useMemoFactoryClient, buildQueryKey, useMemoAirdropClient } from '../../chunk-CNP4L3GF.js';
+export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError } from '../../chunk-S2XD75JM.js';
+import { signClaimAuthorization } from '../../chunk-UE5XK2SY.js';
+export { encryptUint64, encryptUint64Batch, resolveEncryptor, signClaimAuthorization } from '../../chunk-UE5XK2SY.js';
+export { useEnsureOperator, useIsOperator } from '../../chunk-U57COLUE.js';
+import { useWagmiAccount } from '../../chunk-FT4LNBOS.js';
+import '../../chunk-4KJ66YRH.js';
+import '../../chunk-YPYCWLYP.js';
+import '../../chunk-7VELUOMI.js';
+import '../../chunk-6WSNS3UV.js';
+import '../../chunk-QKKBBH7I.js';
+import '../../chunk-46T67CE2.js';
+import { MissingClientError, MissingWalletClientError } 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, TokenOpsSdkError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../../chunk-DRSPMIZ7.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 { 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 +63,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 +316,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(
@@ -329,15 +355,16 @@ function useClaim(options) {
     }
   });
 }
-function useGetClaimAmount(options) {
+function useAccessClaimAmount(options) {
   const { client } = useMemoAirdropClient(options);
   return useMutation({
     mutationFn: async (args) => {
-      if (!client) throw new MissingClientError("useGetClaimAmount", "airdrop");
+      if (!client) throw new MissingClientError("useAccessClaimAmount", "airdrop");
       return client.getClaimAmount(args);
     }
   });
 }
+var useGetClaimAmount = useAccessClaimAmount;
 function useWithdraw(options) {
   const { client } = useMemoAirdropClient(options);
   return useMutation({
@@ -427,4 +454,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 { useAccessClaimAmount, 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/useAccessClaimAmount.d.ts

@@ -12,20 +12,26 @@ import { type AirdropHookOptions } from "./_shared.js";
  * plaintext amount. The handle is only valid after the tx lands.
  *
  * Does **not** consume the claim (the `claimedSignatures` bit is not set).
- * Call {@link useAirdropClaim} when the user is ready to transfer tokens.
+ * Call {@link useClaim} when the user is ready to transfer tokens.
  *
- * **Encryptor resolution.** The hook-level `encryptor` (from
- * {@link AirdropHookOptions}) is forwarded lazily to the SDK client. You can
- * also pass `encryptor` per-mutation via `args.encryptor` to override it. If
- * neither is present, the SDK throws `Missing encryptor — pass encryptor…`
- * verbatim.
+ * Submits the admin-issued `{ encryptedInput, signature }` pair verbatim. The
+ * SDK does NOT re-encrypt — the signature commits to the exact handle.
  *
  * @example
- * // `signature` is the EIP-712 admin signature delivered to the recipient
- * // — same value the recipient passes to `useAirdropClaim`. Sourced from your
- * // server API or, for admin-dashboard flows, from `useSignClaimAuthorization`.
- * const view = useAccessClaimAmount({ address: airdropAddress, encryptor: () => useZamaSDK().relayer });
- * view.mutate({ amount: 1_000_000n, signature });
+ * // `encryptedInput` + `signature` are the admin-issued payload delivered to
+ * // the recipient (same pair the recipient passes to `useClaim`). Sourced
+ * // from your server API or, for admin-dashboard flows, by combining
+ * // `encryptUint64({ userAddress: recipient, ... })` with
+ * // `useSignClaimAuthorization`.
+ * const view = useAccessClaimAmount({ address: airdropAddress });
+ * view.mutate({ encryptedInput, signature });
  * // view.data → { handle: "0x...", hash: "0x..." }
  */
 export declare function useAccessClaimAmount(options: AirdropHookOptions): UseMutationResult<EncryptedViewResult, Error, GetClaimAmountArgs>;
+/**
+ * @deprecated Renamed to {@link useAccessClaimAmount}. Both submit a transaction, and the
+ *   `useGet*` name reads as a free query — which misled bounty builders. This
+ *   is the same function object, not a wrapper: behavior, argument types and
+ *   thrown errors are identical. Removed in the next major.
+ */
+export declare const useGetClaimAmount: typeof useAccessClaimAmount;

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,16 @@ 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.
+ *
+ * **An unfunded pool is the opposite case — it reverts loudly.** Do not
+ * generalize the silent-zero rule above to a clone whose pool was never
+ * funded: that claim throws {@link FheHandleNotAllowedError} (the FHEVM ACL
+ * rejects `FHE.allowTransient` on an uninitialized handle). It is not
+ * preflight-detectable either — the pool balance is an encrypted `euint64` the
+ * SDK cannot read in plaintext — so surface the error rather than reporting a
+ * silent no-op success. See `preflightClaim` for the same caveat.
+ *
  * @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/react/useSignClaimAuthorization.d.ts

@@ -16,7 +16,7 @@ export interface UseSignClaimAuthorizationOptions {
  * Sign a `Claim(address recipient, bytes32 encryptedAmount)` EIP-712
  * authorization. The signer (pulled from wagmi's `useWalletClient()`) must
  * hold `DEFAULT_ADMIN_ROLE` on the airdrop clone for the produced signature
- * to be accepted by {@link useClaim} / {@link useGetClaimAmount}.
+ * to be accepted by {@link useClaim} / {@link useAccessClaimAmount}.
  *
  * Mutation throws {@link TokenOpsSdkError} if no wallet is connected.
  *

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,58 @@ 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` does not mean "not approved" on its own** — it is also `false`
+ *   when approval could not be determined at all: the token address was
+ *   structurally invalid (read skipped), or the address is not an ERC-7984
+ *   token (read failed). Do not render an "approve the factory" prompt off
+ *   this field alone; check `blockerErrors` for
+ *   `TOKENOPS_OPERATOR_NOT_APPROVED` first, which is present only when the
+ *   approval genuinely is the missing step.
+ * - `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`. `false` also covers "could not determine" — an invalid or
+     * non-ERC-7984 token; branch on `blockerErrors` rather than this field alone.
+     */
+    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>;
 /**

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

@@ -18,6 +18,61 @@ export declare class NotRegisteredError extends TokenOpsSdkError {
         cause?: unknown;
     });
 }
+/**
+ * Wallet-mode disperse: the user's registered sub-wallet pair has not (fully)
+ * approved the singleton as an ERC-7984 operator on the token, so the
+ * singleton cannot move funds held by the sub-wallets. Surfaced by
+ * `preflightDisperse` in `wallet` / `wallet-token-fee` mode.
+ *
+ * Remediation: call `approveUserWalletsForToken(token)` on the singleton —
+ * the per-wallet approval states are in `context` (and mirrored on
+ * `PreflightReport.hasApprovedSubwallets`).
+ */
+export declare class SubwalletsNotApprovedError extends TokenOpsSdkError {
+    readonly name = "SubwalletsNotApprovedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        user: Address;
+        token: Address;
+        wallet0Approved: boolean;
+        wallet1Approved: boolean;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        user: Address;
+        token: Address;
+        wallet0Approved: boolean;
+        wallet1Approved: boolean;
+        cause?: unknown;
+    });
+}
+/**
+ * Direct-mode disperse: the sender has not approved the singleton as an
+ * ERC-7984 operator on the token, so `disperseConfidentialTokenDirect` would
+ * revert with the raw `ERC7984UnauthorizedSpender` selector (`0x79f2cb38`).
+ * Surfaced by `preflightDisperse` in `direct` mode.
+ *
+ * Remediation: call `setOperator()` / `ensureOperator()` (exported from
+ * `@tokenops/sdk/fhe`) with the singleton address before dispersing.
+ */
+export declare class SingletonNotApprovedError extends TokenOpsSdkError {
+    readonly name = "SingletonNotApprovedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        user: Address;
+        token: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        user: Address;
+        token: Address;
+        cause?: unknown;
+    });
+}
 /**
  * The user has already registered — `register(token)` is single-use per user.
  * Use `approveUserWalletsForToken(token)` to grant the existing wallet pair