@zama-fhe/react-sdk 1.0.0-alpha.2

package/dist/use-approve-underlying-DAkxWhfm.d.ts

@@ -0,0 +1,784 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { UseQueryOptions, UseMutationOptions, UseQueryResult, UseSuspenseQueryResult } from '@tanstack/react-query';
+import * as _zama_fhe_sdk from '@zama-fhe/sdk';
+import { Address, ZamaSDK, Token, TransactionResult, UnshieldCallbacks, Hex, ReadonlyToken, RawLog, ActivityLogMetadata, ActivityItem } from '@zama-fhe/sdk';
+
+/** Base configuration shared by all mutation hooks that need a Token instance. */
+interface UseZamaConfig {
+    /** Address of the confidential token contract. */
+    tokenAddress: Address;
+    /** Address of the wrapper contract (required for shield/unshield operations). */
+    wrapperAddress?: Address;
+}
+/**
+ * Get a {@link Token} instance, memoized by address pair.
+ * Reads signer and storage from the nearest {@link ZamaProvider}.
+ *
+ * @param config - Token and optional wrapper addresses.
+ * @returns A memoized `Token` instance.
+ *
+ * @example
+ * ```tsx
+ * const token = useToken({ tokenAddress: "0xToken", wrapperAddress: "0xWrapper" });
+ * ```
+ */
+declare function useToken(config: UseZamaConfig): _zama_fhe_sdk.Token;
+
+/** Configuration for {@link useConfidentialBalance}. */
+interface UseConfidentialBalanceConfig {
+    /** Address of the confidential token contract. */
+    tokenAddress: Address;
+    /** Polling interval (ms) for the encrypted handle. Default: 10 000. */
+    handleRefetchInterval?: number;
+}
+/** Query options for the decrypt phase of {@link useConfidentialBalance}. */
+type UseConfidentialBalanceOptions = Omit<UseQueryOptions<bigint, Error>, "queryKey" | "queryFn">;
+/**
+ * Declarative hook to read the connected wallet's confidential token balance.
+ * Uses two-phase polling: cheaply polls the encrypted handle, then only
+ * decrypts when the handle changes (new balance).
+ *
+ * @param config - Token address and optional polling interval.
+ * @param options - React Query options forwarded to the decrypt query.
+ * @returns The decrypt query result plus `handleQuery` for Phase 1 state.
+ *
+ * @example
+ * ```tsx
+ * const { data: balance, isLoading, handleQuery } = useConfidentialBalance({
+ *   tokenAddress: "0x...",
+ * });
+ * ```
+ */
+declare function useConfidentialBalance(config: UseConfidentialBalanceConfig, options?: UseConfidentialBalanceOptions): {
+    handleQuery: _tanstack_react_query.UseQueryResult<`0x${string}`, Error>;
+    data: bigint;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<bigint, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<bigint>;
+} | {
+    handleQuery: _tanstack_react_query.UseQueryResult<`0x${string}`, Error>;
+    data: bigint;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<bigint, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<bigint>;
+} | {
+    handleQuery: _tanstack_react_query.UseQueryResult<`0x${string}`, Error>;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<bigint, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<bigint>;
+} | {
+    handleQuery: _tanstack_react_query.UseQueryResult<`0x${string}`, Error>;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<bigint, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<bigint>;
+} | {
+    handleQuery: _tanstack_react_query.UseQueryResult<`0x${string}`, Error>;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<bigint, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<bigint>;
+} | {
+    handleQuery: _tanstack_react_query.UseQueryResult<`0x${string}`, Error>;
+    data: bigint;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<bigint, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<bigint>;
+};
+
+/** Configuration for {@link useConfidentialBalances}. */
+interface UseConfidentialBalancesConfig {
+    /** Addresses of the confidential token contracts to batch-query. */
+    tokenAddresses: Address[];
+    /** Polling interval (ms) for the encrypted handles. Default: 10 000. */
+    handleRefetchInterval?: number;
+    /** Maximum number of concurrent decrypt calls. Default: `Infinity` (no limit). */
+    maxConcurrency?: number;
+}
+/** Query options for the decrypt phase of {@link useConfidentialBalances}. */
+type UseConfidentialBalancesOptions = Omit<UseQueryOptions<Map<Address, bigint>, Error>, "queryKey" | "queryFn">;
+/**
+ * Declarative hook to read multiple confidential token balances in batch.
+ * Uses two-phase polling: cheaply polls encrypted handles, then only
+ * decrypts when any handle changes.
+ *
+ * @param config - Token addresses and optional polling interval.
+ * @param options - React Query options forwarded to the decrypt query.
+ * @returns The decrypt query result (Map of address → balance) plus `handlesQuery` for Phase 1 state.
+ *
+ * @example
+ * ```tsx
+ * const { data: balances } = useConfidentialBalances({
+ *   tokenAddresses: ["0xTokenA", "0xTokenB"],
+ * });
+ * const balance = balances?.get("0xTokenA");
+ * ```
+ */
+declare function useConfidentialBalances(config: UseConfidentialBalancesConfig, options?: UseConfidentialBalancesOptions): {
+    handlesQuery: _tanstack_react_query.UseQueryResult<`0x${string}`[], Error>;
+    data: Map<`0x${string}`, bigint>;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<Map<`0x${string}`, bigint>, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<Map<`0x${string}`, bigint>>;
+} | {
+    handlesQuery: _tanstack_react_query.UseQueryResult<`0x${string}`[], Error>;
+    data: Map<`0x${string}`, bigint>;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<Map<`0x${string}`, bigint>, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<Map<`0x${string}`, bigint>>;
+} | {
+    handlesQuery: _tanstack_react_query.UseQueryResult<`0x${string}`[], Error>;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<Map<`0x${string}`, bigint>, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<Map<`0x${string}`, bigint>>;
+} | {
+    handlesQuery: _tanstack_react_query.UseQueryResult<`0x${string}`[], Error>;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<Map<`0x${string}`, bigint>, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<Map<`0x${string}`, bigint>>;
+} | {
+    handlesQuery: _tanstack_react_query.UseQueryResult<`0x${string}`[], Error>;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<Map<`0x${string}`, bigint>, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<Map<`0x${string}`, bigint>>;
+} | {
+    handlesQuery: _tanstack_react_query.UseQueryResult<`0x${string}`[], Error>;
+    data: Map<`0x${string}`, bigint>;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<Map<`0x${string}`, bigint>, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<Map<`0x${string}`, bigint>>;
+};
+
+/**
+ * TanStack Query mutation options factory for authorize-all.
+ *
+ * @param sdk - A `ZamaSDK` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+declare function authorizeAllMutationOptions(sdk: ZamaSDK): {
+    mutationKey: readonly ["authorizeAll"];
+    mutationFn: (tokenAddresses: Address[]) => Promise<void>;
+};
+/**
+ * Pre-authorize FHE decrypt credentials for a list of token addresses.
+ * A single wallet signature covers all addresses, so subsequent decrypt
+ * operations on any of these tokens reuse cached credentials.
+ *
+ * @example
+ * ```tsx
+ * const { mutateAsync: authorizeAll, isPending } = useAuthorizeAll();
+ * // Call authorizeAll(allTokenAddresses) before any individual reveal
+ * ```
+ */
+declare function useAuthorizeAll(): _tanstack_react_query.UseMutationResult<void, Error, `0x${string}`[], unknown>;
+
+/** Parameters passed to the `mutate` function of {@link useConfidentialTransferFrom}. */
+interface ConfidentialTransferFromParams {
+    /** Address to transfer from. Caller must be an approved operator. */
+    from: Address;
+    /** Recipient address. */
+    to: Address;
+    /** Amount to transfer (plaintext — encrypted automatically). */
+    amount: bigint;
+}
+/**
+ * TanStack Query mutation options factory for confidential transfer-from.
+ *
+ * @param token - A `Token` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+declare function confidentialTransferFromMutationOptions(token: Token): {
+    mutationKey: readonly ["confidentialTransferFrom", `0x${string}`];
+    mutationFn: ({ from, to, amount }: ConfidentialTransferFromParams) => Promise<TransactionResult>;
+};
+/**
+ * Operator transfer on behalf of another address. Caller must be an approved operator.
+ * Invalidates balance caches on success.
+ *
+ * @param config - Token address (and optional wrapper) identifying the token.
+ * @param options - React Query mutation options.
+ *
+ * @example
+ * ```tsx
+ * const transferFrom = useConfidentialTransferFrom({ tokenAddress: "0x..." });
+ * transferFrom.mutate({ from: "0xOwner", to: "0xRecipient", amount: 500n });
+ * ```
+ */
+declare function useConfidentialTransferFrom(config: UseZamaConfig, options?: UseMutationOptions<TransactionResult, Error, ConfidentialTransferFromParams, Address>): _tanstack_react_query.UseMutationResult<TransactionResult, Error, ConfidentialTransferFromParams, `0x${string}`>;
+
+/** Parameters passed to the `mutate` function of {@link useConfidentialApprove}. */
+interface ConfidentialApproveParams {
+    /** Address to approve as operator. */
+    spender: Address;
+    /** Unix timestamp until which the approval is valid. Defaults to 1 hour from now. */
+    until?: number;
+}
+/**
+ * TanStack Query mutation options factory for confidential approve.
+ *
+ * @param token - A `Token` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+declare function confidentialApproveMutationOptions(token: Token): {
+    mutationKey: readonly ["confidentialApprove", `0x${string}`];
+    mutationFn: ({ spender, until }: ConfidentialApproveParams) => Promise<TransactionResult>;
+};
+/**
+ * Set operator approval for a confidential token. Defaults to 1 hour.
+ *
+ * Errors are {@link ZamaError} subclasses — use `instanceof` to handle specific failures:
+ * - {@link SigningRejectedError} — user rejected the wallet prompt
+ * - {@link TransactionRevertedError} — on-chain transaction reverted
+ *
+ * @param config - Token address (and optional wrapper) identifying the token.
+ * @param options - React Query mutation options.
+ *
+ * @example
+ * ```tsx
+ * const approve = useConfidentialApprove({ tokenAddress: "0x..." });
+ * approve.mutate({ spender: "0xOperator" });
+ * ```
+ */
+declare function useConfidentialApprove(config: UseZamaConfig, options?: UseMutationOptions<TransactionResult, Error, ConfidentialApproveParams, Address>): _tanstack_react_query.UseMutationResult<TransactionResult, Error, ConfidentialApproveParams, `0x${string}`>;
+
+/**
+ * TanStack Query mutation options factory for unwrap-all.
+ *
+ * @param token - A `Token` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+declare function unwrapAllMutationOptions(token: Token): {
+    mutationKey: readonly ["unwrapAll", `0x${string}`];
+    mutationFn: () => Promise<TransactionResult>;
+};
+/**
+ * Request an unwrap for the entire confidential balance.
+ * Uses the on-chain balance handle directly (no encryption needed).
+ * Call {@link useFinalizeUnwrap} after processing, or use {@link useUnshieldAll} for single-call orchestration.
+ *
+ * @param config - Token address (and optional wrapper) identifying the token.
+ * @param options - React Query mutation options.
+ *
+ * @example
+ * ```tsx
+ * const unwrapAll = useUnwrapAll({ tokenAddress: "0x..." });
+ * unwrapAll.mutate();
+ * ```
+ */
+declare function useUnwrapAll(config: UseZamaConfig, options?: UseMutationOptions<TransactionResult, Error, void, Address>): _tanstack_react_query.UseMutationResult<TransactionResult, Error, void, `0x${string}`>;
+
+/** Parameters passed to the `mutate` function of {@link useUnshield}. */
+interface UnshieldParams {
+    /** Amount to unshield (plaintext — encrypted automatically). */
+    amount: bigint;
+    /** Optional progress callbacks for the multi-step unshield flow. */
+    callbacks?: UnshieldCallbacks;
+}
+/**
+ * TanStack Query mutation options factory for unshield.
+ *
+ * @param token - A `Token` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+declare function unshieldMutationOptions(token: Token): {
+    mutationKey: readonly ["unshield", `0x${string}`];
+    mutationFn: ({ amount, callbacks }: UnshieldParams) => Promise<TransactionResult>;
+};
+/**
+ * Unshield a specific amount and finalize in one call.
+ * Orchestrates: unwrap → wait for receipt → parse event → finalize.
+ *
+ * Errors are {@link ZamaError} subclasses — use `instanceof` to handle specific failures:
+ * - {@link SigningRejectedError} — user rejected the wallet prompt
+ * - {@link EncryptionFailedError} — FHE encryption failed during unwrap
+ * - {@link DecryptionFailedError} — public decryption failed during finalize
+ * - {@link TransactionRevertedError} — on-chain transaction reverted
+ *
+ * @param config - Token and wrapper addresses.
+ * @param options - React Query mutation options.
+ *
+ * @example
+ * ```tsx
+ * const unshield = useUnshield({ tokenAddress: "0x...", wrapperAddress: "0x..." });
+ * unshield.mutate({ amount: 500n });
+ * ```
+ */
+declare function useUnshield(config: UseZamaConfig, options?: UseMutationOptions<TransactionResult, Error, UnshieldParams, Address>): _tanstack_react_query.UseMutationResult<TransactionResult, Error, UnshieldParams, `0x${string}`>;
+
+/**
+ * TanStack Query mutation options factory for unshield-all.
+ *
+ * @param token - A `Token` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+/** Parameters passed to the `mutate` function of {@link useUnshieldAll}. */
+interface UnshieldAllParams {
+    /** Optional progress callbacks for the multi-step unshield flow. */
+    callbacks?: UnshieldCallbacks;
+}
+declare function unshieldAllMutationOptions(token: Token): {
+    mutationKey: readonly ["unshieldAll", `0x${string}`];
+    mutationFn: (params?: UnshieldAllParams) => Promise<TransactionResult>;
+};
+/**
+ * Unshield the entire balance and finalize in one call.
+ * Orchestrates: unwrapAll → wait for receipt → parse event → finalize.
+ *
+ * @param config - Token and wrapper addresses.
+ * @param options - React Query mutation options.
+ *
+ * @example
+ * ```tsx
+ * const unshieldAll = useUnshieldAll({ tokenAddress: "0x...", wrapperAddress: "0x..." });
+ * unshieldAll.mutate();
+ * ```
+ */
+declare function useUnshieldAll(config: UseZamaConfig, options?: UseMutationOptions<TransactionResult, Error, UnshieldAllParams | void, Address>): _tanstack_react_query.UseMutationResult<TransactionResult, Error, void | UnshieldAllParams, `0x${string}`>;
+
+/** Parameters passed to the `mutate` function of {@link useResumeUnshield}. */
+interface ResumeUnshieldParams {
+    /** The unwrap transaction hash from a previously interrupted unshield. */
+    unwrapTxHash: Hex;
+    /** Optional progress callbacks for the finalization flow. */
+    callbacks?: UnshieldCallbacks;
+}
+/**
+ * TanStack Query mutation options factory for resume-unshield.
+ *
+ * @param token - A `Token` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+declare function resumeUnshieldMutationOptions(token: Token): {
+    mutationKey: readonly ["resumeUnshield", `0x${string}`];
+    mutationFn: ({ unwrapTxHash, callbacks }: ResumeUnshieldParams) => Promise<TransactionResult>;
+};
+/**
+ * Resume an interrupted unshield from an existing unwrap tx hash.
+ * Useful when the user submitted the unwrap but the finalize step was
+ * interrupted (e.g. page reload, network error).
+ *
+ * Errors are {@link ZamaError} subclasses — use `instanceof` to handle specific failures:
+ * - {@link DecryptionFailedError} — public decryption failed during finalize
+ * - {@link TransactionRevertedError} — on-chain transaction reverted
+ *
+ * @param config - Token and wrapper addresses.
+ * @param options - React Query mutation options.
+ *
+ * @example
+ * ```tsx
+ * const resumeUnshield = useResumeUnshield({ tokenAddress: "0x...", wrapperAddress: "0x..." });
+ * resumeUnshield.mutate({ unwrapTxHash: "0xabc..." });
+ * ```
+ */
+declare function useResumeUnshield(config: UseZamaConfig, options?: UseMutationOptions<TransactionResult, Error, ResumeUnshieldParams, Address>): _tanstack_react_query.UseMutationResult<TransactionResult, Error, ResumeUnshieldParams, `0x${string}`>;
+
+/**
+ * Query key factory for token metadata queries.
+ * Use with `queryClient.invalidateQueries()` / `resetQueries()`.
+ */
+declare const tokenMetadataQueryKeys: {
+    /** Match all token metadata queries. */
+    readonly all: readonly ["tokenMetadata"];
+    /** Match metadata query for a specific token. */
+    readonly token: (tokenAddress: string) => readonly ["tokenMetadata", string];
+};
+/** ERC-20 token metadata (name, symbol, decimals). */
+interface TokenMetadata {
+    /** Human-readable token name (e.g. "Wrapped Ether"). */
+    name: string;
+    /** Short ticker symbol (e.g. "WETH"). */
+    symbol: string;
+    /** Number of decimal places (e.g. 18). */
+    decimals: number;
+}
+/**
+ * TanStack Query options factory for token metadata.
+ * Returns a config object usable with `useQuery`, `prefetchQuery`, `useQueries`, etc.
+ *
+ * @param token - A `ReadonlyToken` instance.
+ * @returns Query options with `queryKey`, `queryFn`, and `staleTime`.
+ *
+ * @example
+ * ```ts
+ * const options = tokenMetadataQueryOptions(token);
+ * await queryClient.prefetchQuery(options);
+ * ```
+ */
+declare function tokenMetadataQueryOptions(token: ReadonlyToken): {
+    readonly queryKey: readonly ["tokenMetadata", string];
+    readonly queryFn: () => Promise<TokenMetadata>;
+    readonly staleTime: number;
+};
+/**
+ * Read ERC-20 token metadata (name, symbol, decimals).
+ * Fetches all three in parallel. Cached indefinitely since metadata is immutable.
+ *
+ * @param tokenAddress - Address of the token contract.
+ * @param options - React Query options (forwarded to `useQuery`).
+ * @returns Query result with `data: TokenMetadata`.
+ *
+ * @example
+ * ```tsx
+ * const { data: metadata } = useTokenMetadata("0xToken");
+ * // metadata?.name, metadata?.symbol, metadata?.decimals
+ * ```
+ */
+declare function useTokenMetadata(tokenAddress: Address, options?: Omit<UseQueryOptions<TokenMetadata, Error>, "queryKey" | "queryFn">): UseQueryResult<TokenMetadata, Error>;
+/**
+ * Suspense variant of {@link useTokenMetadata}.
+ * Suspends rendering until metadata is loaded.
+ *
+ * @param tokenAddress - Address of the token contract.
+ * @returns Suspense query result with `data: TokenMetadata`.
+ *
+ * @example
+ * ```tsx
+ * const { data: metadata } = useTokenMetadataSuspense("0xToken");
+ * ```
+ */
+declare function useTokenMetadataSuspense(tokenAddress: Address): UseSuspenseQueryResult<TokenMetadata, Error>;
+
+/**
+ * Query key factory for activity feed queries.
+ * Use with `queryClient.invalidateQueries()` / `resetQueries()`.
+ */
+declare const activityFeedQueryKeys: {
+    /** Match all activity feed queries. */
+    readonly all: readonly ["activityFeed"];
+    /** Match activity feed queries for a specific token. */
+    readonly token: (tokenAddress: string) => readonly ["activityFeed", string];
+};
+/** Configuration for {@link useActivityFeed}. */
+interface UseActivityFeedConfig {
+    /** Address of the confidential token contract. */
+    tokenAddress: Address;
+    /** Connected wallet address. Pass `undefined` to disable the query. */
+    userAddress: Address | undefined;
+    /** Raw event logs from the provider (viem, ethers, etc.). Pass `undefined` to disable. */
+    logs: readonly (RawLog & Partial<ActivityLogMetadata>)[] | undefined;
+    /** Whether to batch-decrypt encrypted transfer amounts. Default: `true`. */
+    decrypt?: boolean;
+}
+/**
+ * Two-phase activity feed hook.
+ * Phase 1: Instantly parses raw logs into classified {@link ActivityItem}s (sync, cheap).
+ * Phase 2: Batch-decrypts encrypted transfer amounts via the relayer (async).
+ *
+ * The wallet provides logs (from its own provider — viem, ethers, etc.)
+ * and this hook normalizes + decrypts them.
+ *
+ * @param config - Token address, user address, raw logs, and decrypt option.
+ * @returns Query result with `data: ActivityItem[]`.
+ *
+ * @example
+ * ```tsx
+ * const { data: activity } = useActivityFeed({
+ *   tokenAddress: "0xToken",
+ *   userAddress: "0xUser",
+ *   logs: rawLogs,
+ * });
+ * ```
+ */
+declare function useActivityFeed(config: UseActivityFeedConfig): UseQueryResult<ActivityItem[], Error>;
+
+/** Parameters passed to the `mutate` function of {@link useApproveUnderlying}. */
+interface ApproveUnderlyingParams {
+    /** Approval amount. Defaults to max uint256 if omitted. */
+    amount?: bigint;
+}
+/**
+ * TanStack Query mutation options factory for approve-underlying.
+ *
+ * @param token - A `Token` instance.
+ * @returns Mutation options with `mutationKey` and `mutationFn`.
+ */
+declare function approveUnderlyingMutationOptions(token: Token): {
+    mutationKey: readonly ["approveUnderlying", `0x${string}`];
+    mutationFn: ({ amount }: ApproveUnderlyingParams) => Promise<TransactionResult>;
+};
+/**
+ * Approve the wrapper contract to spend the underlying ERC-20.
+ * Defaults to max uint256. Resets to zero first if there's an existing
+ * non-zero allowance (required by tokens like USDT).
+ *
+ * @param config - Token and wrapper addresses.
+ * @param options - React Query mutation options.
+ *
+ * @example
+ * ```tsx
+ * const approve = useApproveUnderlying({ tokenAddress: "0x...", wrapperAddress: "0x..." });
+ * approve.mutate({}); // max approval
+ * approve.mutate({ amount: 1000n }); // exact amount
+ * ```
+ */
+declare function useApproveUnderlying(config: UseZamaConfig, options?: UseMutationOptions<TransactionResult, Error, ApproveUnderlyingParams, Address>): _tanstack_react_query.UseMutationResult<TransactionResult, Error, ApproveUnderlyingParams, `0x${string}`>;
+
+export { type ApproveUnderlyingParams as A, useResumeUnshield as B, type ConfidentialApproveParams as C, useToken as D, useTokenMetadata as E, useTokenMetadataSuspense as F, useUnshield as G, useUnshieldAll as H, useUnwrapAll as I, type ResumeUnshieldParams as R, type TokenMetadata as T, type UseZamaConfig as U, type ConfidentialTransferFromParams as a, type UnshieldAllParams as b, type UnshieldParams as c, type UseActivityFeedConfig as d, type UseConfidentialBalanceConfig as e, type UseConfidentialBalanceOptions as f, type UseConfidentialBalancesConfig as g, type UseConfidentialBalancesOptions as h, activityFeedQueryKeys as i, approveUnderlyingMutationOptions as j, authorizeAllMutationOptions as k, confidentialApproveMutationOptions as l, confidentialTransferFromMutationOptions as m, tokenMetadataQueryOptions as n, unshieldMutationOptions as o, unwrapAllMutationOptions as p, useActivityFeed as q, resumeUnshieldMutationOptions as r, useApproveUnderlying as s, tokenMetadataQueryKeys as t, unshieldAllMutationOptions as u, useAuthorizeAll as v, useConfidentialApprove as w, useConfidentialBalance as x, useConfidentialBalances as y, useConfidentialTransferFrom as z };