@zama-fhe/sdk 3.4.0-alpha.9 → 3.4.0

package/dist/esm/{zama-sdk-BhD6nWLL.d.ts → index-DLaQtvYu.d.ts}

@@ -1,10 +1,10 @@
-import { u as FheChain } from "./index-doNE2KoX.js";
-import { C as ChainRouter, Ft as TransactionResult, Gt as FhevmRelayerOptions, Ht as EncryptResult, It as ClearValue, Kt as FhevmRelayerSDK, Lt as DecryptPublicValuesResult, Q as ShieldOptions, R as TransactionOperation, Ut as EncryptedValue, Vt as EncryptParams, at as TransferCallbacks, c as GenericStorage, d as WalletAccount, et as TransferOptions, i as ZamaConfig, l as GenericProvider, n as RelayerConfig, nt as UnwrapResult, o as ZamaConfigGeneric, ot as UnshieldCallbacks, p as WalletAccountListener, q as ZamaSDKEventInput, rt as WrapOptions, s as GenericLogger, tt as UnshieldOptions, u as GenericSigner, x as WriteContractConfig } from "./types-CELdIAFG.js";
-import "./cleartext-_RCZVPOe.js";
-import "./types-DlSUyFe2.js";
-import "./types-Tk8PiPCk.js";
-import "./index-9Cn2VKDw.js";
-import { Address, Hex } from "viem";
+import { u as FheChain } from "./index-S6_V7aAH.js";
+import { $ as UnshieldOptions, Bt as EncryptResult, Ft as DecryptPublicValuesResult, Nt as TransactionResult, Pt as ClearValue, Q as TransferOptions, Vt as EncryptedValue, Wt as FhevmRelayerOptions, X as ShieldOptions, c as GenericStorage, d as WalletAccount, et as UnwrapResult, i as ZamaConfig, it as UnshieldCallbacks, l as GenericProvider, o as ZamaConfigGeneric, qt as RelayerSDK, rt as TransferCallbacks, tt as WrapOptions, u as GenericSigner, zt as EncryptParams } from "./types-CWPSTRF6.js";
+import "./cleartext-CxlICeUh.js";
+import "./types-Dr7AmEs1.js";
+import "./base-signer-BvL-jMNO.js";
+import "./types-BEz-VgR_.js";
+import { Address, Address as Address$1, Hex, Hex as Hex$1 } from "viem";
 import { z } from "zod/mini";
 import { MutationFunctionContext, QueryKey, QueryObserverOptions, skipToken } from "@tanstack/query-core";
 //#region src/config/create.d.ts
@@ -33,17 +33,6 @@ import { MutationFunctionContext, QueryKey, QueryObserverOptions, skipToken } fr
  */
 declare function createConfig<const TChains extends readonly [FheChain, ...FheChain[]]>(params: ZamaConfigGeneric<TChains>): ZamaConfig;
 //#endregion
-//#region src/config/resolve.d.ts
-declare function resolveStorage(storage?: GenericStorage | undefined, permitStorage?: GenericStorage | undefined): {
-  storage: GenericStorage;
-  permitStorage: GenericStorage;
-};
-interface ResolvedChainRelayer {
-  chain: FheChain;
-  relayerConfig: RelayerConfig;
-}
-declare function resolveChainRelayers(chains: readonly FheChain[], relayers: Readonly<Record<number, RelayerConfig>>): Map<number, ResolvedChainRelayer>;
-//#endregion
 //#region src/contracts/confidential-wrapper.d.ts
 /**
  * Returns the contract config to read an encrypted balance.
@@ -17089,19 +17078,25 @@ declare function isHandleDelegatedContract(aclAddress: Address, delegatorAddress
 };
 //#endregion
 //#region src/contracts/wrappers-registry.d.ts
+/** A registered plain-token / confidential-token pairing from the wrappers registry. */
 interface TokenWrapperPair {
+  /** Address of the underlying public ERC-20 token. */
   readonly tokenAddress: Address;
+  /** Address of the paired confidential (ERC-7984) token. */
   readonly confidentialTokenAddress: Address;
+  /** Whether the pairing is currently valid (registered and not revoked). */
   readonly isValid: boolean;
 }
 /** Extended pair with on-chain metadata for both tokens. */
 interface TokenWrapperPairWithMetadata extends TokenWrapperPair {
+  /** On-chain metadata of the underlying public ERC-20 token. */
   readonly underlying: {
     readonly name: string;
     readonly symbol: string;
     readonly decimals: number;
     readonly totalSupply: bigint;
   };
+  /** On-chain metadata of the confidential token. */
   readonly confidential: {
     readonly name: string;
     readonly symbol: string;
@@ -17110,9 +17105,13 @@ interface TokenWrapperPairWithMetadata extends TokenWrapperPair {
 }
 /** Paginated result set modelled after standard API pagination. */
 interface PaginatedResult<T> {
+  /** Items on the current page. */
   readonly items: readonly T[];
+  /** Total number of items across all pages. */
   readonly total: number;
+  /** One-based index of the current page. */
   readonly page: number;
+  /** Maximum number of items per page. */
   readonly pageSize: number;
 }
 /**
@@ -18459,50 +18458,25 @@ declare function isConfidentialTokenValidContract(registry: Address, confidentia
   readonly args: readonly [`0x${string}`];
 };
 //#endregion
-//#region src/query/utils.d.ts
-type StrippedQueryOptionKeys = "gcTime" | "staleTime" | "enabled" | "select" | "refetchInterval" | "refetchOnMount" | "refetchOnWindowFocus" | "refetchOnReconnect" | "retry" | "retryDelay" | "retryOnMount" | "queryFn" | "queryKey" | "queryKeyHashFn" | "initialData" | "initialDataUpdatedAt" | "placeholderData" | "structuralSharing" | "throwOnError" | "meta" | "query" | "pollingInterval";
-/**
- * Remove TanStack behavioral options from a query config object so only domain
- * parameters remain for the lower-level factory.
- *
- * @example
- * ```ts
- * const params = filterQueryOptions({
- *   query: { enabled: false },
- *   gcTime: 60_000,
- *   owner: "0xabc",
- * });
- * // => { owner: "0xabc" }
- * ```
- */
-declare function filterQueryOptions<TOptions extends Record<string, unknown>>(options: TOptions): Omit<TOptions, StrippedQueryOptionKeys>;
+//#region src/query/factory-types.d.ts
 /**
- * Stable hash function for query keys.
- * Sorts object keys recursively and converts bigint values to strings.
- *
- * @remarks
- * bigint values are serialized as decimal strings, so `42n` and `"42"` hash to
- * the same token when they occupy the same position. This collision is accepted
- * by design for the current query-key conventions in this package.
+ * TanStack Query options object returned by the SDK's `*QueryOptions` factories:
+ * `QueryObserverOptions` with `queryKey` and `queryFn` required and the
+ * cache-internal keys (`queryHash`, `queryKeyHashFn`, `throwOnError`) removed.
  */
-declare function hashFn(queryKey: readonly unknown[]): string;
-//#endregion
-//#region src/query/factory-types.d.ts
-type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-type QueryFactoryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<RequiredBy<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, "queryKey">, "queryFn" | "queryHash" | "queryKeyHashFn" | "throwOnError"> & {
+type QueryFactoryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, "queryKey"> & Required<Pick<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, "queryKey">>, "queryFn" | "queryHash" | "queryKeyHashFn" | "throwOnError"> & {
   queryFn: Exclude<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>["queryFn"], typeof skipToken | undefined>;
 };
+/** TanStack Query mutation options object returned by the SDK's `*MutationOptions` factories. */
 interface MutationFactoryOptions<TMutationKey extends readonly unknown[], TVariables, TData, TOnMutateResult = unknown> {
+  /** Cache key identifying the mutation. */
   mutationKey: TMutationKey;
+  /** Runs the mutation for the given variables. */
   mutationFn: (variables: TVariables) => Promise<TData>;
+  /** Optional callback invoked after the mutation succeeds. */
   onSuccess?: (data: TData, variables: TVariables, onMutateResult: TOnMutateResult, context: MutationFunctionContext) => void;
 }
 //#endregion
-//#region src/query/signer-query-context.d.ts
-interface SignerQueryContext {
-  walletAccount?: WalletAccount;
-}
-//#endregion
 //#region src/query/query-keys.d.ts
 /**
  * Canonical query-key namespace for `@zama-fhe/sdk/query`.
@@ -18706,533 +18680,171 @@ declare const zamaQueryKeys: {
   };
 };
 //#endregion
-//#region src/query/invalidation.d.ts
-interface QueryLike {
-  queryKey: readonly unknown[];
-}
-interface QueryFilterLike {
-  queryKey?: readonly unknown[];
-  predicate?: (query: QueryLike) => boolean;
-}
-interface QueryClientLike {
-  invalidateQueries(filters: QueryFilterLike): void | Promise<void>;
-  removeQueries(filters: QueryFilterLike): void;
-}
-declare function invalidateAfterUnwrap(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateAfterWrap(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateBalanceQueries(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateAfterShield(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateAfterUnshield(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateAfterUnshieldSettled(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateAfterTransfer(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateAfterApproveUnderlying(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateAfterSetOperator(queryClient: QueryClientLike, tokenAddress: Address): void;
-declare function invalidateWagmiBalanceQueries(queryClient: QueryClientLike): void;
-declare function invalidateWalletLifecycleQueries(queryClient: QueryClientLike): void;
-//#endregion
-//#region src/query/token-metadata.d.ts
-/** ERC-20 token metadata returned by {@link tokenMetadataQueryOptions}. */
-interface TokenMetadata {
-  name: string;
-  symbol: string;
-  decimals: number;
-}
-interface TokenMetadataQueryConfig {
-  query?: Record<string, unknown>;
-}
-declare function tokenMetadataQueryOptions(sdk: ZamaSDK, tokenAddress: Address, config?: TokenMetadataQueryConfig): QueryFactoryOptions<TokenMetadata, Error, TokenMetadata, ReturnType<typeof zamaQueryKeys.tokenMetadata.token>>;
-//#endregion
-//#region src/query/is-confidential.d.ts
-interface IsConfidentialQueryConfig {
-  query?: Record<string, unknown>;
+//#region src/query/signer-query-context.d.ts
+/** Connected-wallet context threaded into query factories to scope cache keys and gate signer-dependent queries. */
+interface SignerQueryContext {
+  /** Connected wallet account; queries that need a signer stay disabled until it is set. */
+  walletAccount?: WalletAccount;
 }
-declare function isConfidentialQueryOptions(sdk: ZamaSDK, tokenAddress: Address, config?: IsConfidentialQueryConfig): QueryFactoryOptions<boolean, Error, boolean, ReturnType<typeof zamaQueryKeys.isConfidential.token>>;
-declare function isWrapperQueryOptions(sdk: ZamaSDK, tokenAddress: Address, config?: IsConfidentialQueryConfig): QueryFactoryOptions<boolean, Error, boolean, ReturnType<typeof zamaQueryKeys.isWrapper.token>>;
 //#endregion
-//#region src/query/total-supply.d.ts
-interface TotalSupplyQueryConfig {
-  query?: Record<string, unknown>;
+//#region src/query/user-decrypt.d.ts
+/** A single encrypted value to decrypt, paired with the contract that owns it. */
+interface EncryptedInput {
+  /** Encrypted handle to decrypt. */
+  encryptedValue: EncryptedValue;
+  /** Address of the contract the encrypted value belongs to. */
+  contractAddress: Address;
 }
-declare function totalSupplyQueryOptions(sdk: ZamaSDK, tokenAddress: Address, config?: TotalSupplyQueryConfig): QueryFactoryOptions<bigint, Error, bigint, ReturnType<typeof zamaQueryKeys.totalSupply.token>>;
+/** Decrypted clear values keyed by encrypted handle. */
+type DecryptResult = Readonly<Record<EncryptedValue, ClearValue>>;
+/** Builds TanStack Query options for decrypting a batch of encrypted handles into their clear values. */
+declare function decryptValuesQueryOptions(sdk: ZamaSDK, encryptedInputs: EncryptedInput[], signerContext?: SignerQueryContext): QueryFactoryOptions<DecryptResult, Error, DecryptResult, ReturnType<typeof zamaQueryKeys.decryption.encryptedInputs>>;
 //#endregion
-//#region src/schemas/primitives.d.ts
-declare const checksummedTag: unique symbol;
-/** An EVM address that has been put through `getAddress` (EIP-55 checksum form). */
-type ChecksummedAddress = Address & {
-  readonly [checksummedTag]: true;
+//#region src/errors/base.d.ts
+/**
+ * Typed error codes thrown by the SDK.
+ * Use `error.code` or `instanceof` to programmatically handle specific failure modes.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await token.confidentialTransfer("0xTo", 100n);
+ * } catch (e) {
+ *   if (e instanceof SigningRejectedError) {
+ *     // User rejected the wallet signature
+ *   }
+ * }
+ * ```
+ */
+declare const ZamaErrorCode: {
+  /** User rejected the wallet signature prompt. */
+  readonly SigningRejected: "SIGNING_REJECTED";
+  /** Wallet signature failed for a reason other than rejection. */
+  readonly SigningFailed: "SIGNING_FAILED";
+  /** FHE encryption failed. */
+  readonly EncryptionFailed: "ENCRYPTION_FAILED";
+  /** FHE decryption failed. */
+  readonly DecryptionFailed: "DECRYPTION_FAILED";
+  /** On-chain transaction reverted. */
+  readonly TransactionReverted: "TRANSACTION_REVERTED";
+  /** Transport key pair has expired and needs regeneration. */
+  readonly TransportKeyPairExpired: "KEYPAIR_EXPIRED";
+  /** Relayer rejected transport key pair (stale, expired, or malformed). */
+  readonly InvalidTransportKeyPair: "INVALID_KEYPAIR";
+  /** No FHE ciphertext exists for this account (never shielded). */
+  readonly NoCiphertext: "NO_CIPHERTEXT";
+  /** Relayer HTTP request failed. */
+  readonly RelayerRequestFailed: "RELAYER_REQUEST_FAILED";
+  /** The configured signer/account is not entitled (ACL) to decrypt this encrypted value. Don't retry — wait for a grant. */
+  readonly NotEntitled: "NOT_ENTITLED";
+  /** The consumer's RPC provider rate-limited an on-chain read (e.g. HTTP 429 / JSON-RPC -32005). Retryable. */
+  readonly RpcRateLimited: "RPC_RATE_LIMITED";
+  /** SDK configuration is invalid (e.g. forbidden chain ID, unsupported type). */
+  readonly Configuration: "CONFIGURATION";
+  /** Delegation cannot target self (delegate === msg.sender). */
+  readonly DelegationSelfNotAllowed: "DELEGATION_SELF_NOT_ALLOWED";
+  /** Only one delegate/revoke per (delegator, delegate, contract) per block. */
+  readonly DelegationCooldown: "DELEGATION_COOLDOWN";
+  /** No active delegation found for this (delegator, delegate, contract) tuple. */
+  readonly DelegationNotFound: "DELEGATION_NOT_FOUND";
+  /** The delegation has expired. */
+  readonly DelegationExpired: "DELEGATION_EXPIRED";
+  /** Confidential (cToken) balance is insufficient for the requested operation. */
+  readonly InsufficientConfidentialBalance: "INSUFFICIENT_CONFIDENTIAL_BALANCE";
+  /** ERC-20 balance is insufficient for the requested shield amount. */
+  readonly InsufficientERC20Balance: "INSUFFICIENT_ERC20_BALANCE";
+  /** ERC-20 allowance granted to the wrapper is insufficient for the requested wrap amount. */
+  readonly InsufficientAllowance: "INSUFFICIENT_ALLOWANCE";
+  /** Balance validation could not be performed (no cached credentials and decryption not possible). */
+  readonly BalanceCheckUnavailable: "BALANCE_CHECK_UNAVAILABLE";
+  /** Public ERC-20 read (e.g. balanceOf) failed due to a network or contract error. */
+  readonly ERC20ReadFailed: "ERC20_READ_FAILED";
+  /** The new expiration date equals the current one — no on-chain change needed. */
+  readonly DelegationExpiryUnchanged: "DELEGATION_EXPIRY_UNCHANGED";
+  /** Delegate address cannot be the contract address. */
+  readonly DelegationDelegateEqualsContract: "DELEGATION_DELEGATE_EQUALS_CONTRACT";
+  /** Contract address cannot be the sender address. */
+  readonly DelegationContractIsSelf: "DELEGATION_CONTRACT_IS_SELF";
+  /** The ACL contract is paused. */
+  readonly AclPaused: "ACL_PAUSED";
+  /** Expiration date is too soon (must be at least 1 hour in the future). */
+  readonly DelegationExpirationTooSoon: "DELEGATION_EXPIRATION_TOO_SOON";
+  /** Delegation exists on-chain but hasn't propagated to the gateway yet. */
+  readonly DelegationNotPropagated: "DELEGATION_NOT_PROPAGATED";
+  /** Signer and provider are connected to different chains. */
+  readonly ChainMismatch: "CHAIN_MISMATCH";
+  /** Operation requires a signer but none is configured. */
+  readonly SignerNotConfigured: "SIGNER_NOT_CONFIGURED";
+  /** Operation requires a connected wallet account. */
+  readonly WalletNotConnected: "WALLET_NOT_CONNECTED";
+  /** Wallet account discovery is still resolving. */
+  readonly WalletAccountNotReady: "WALLET_ACCOUNT_NOT_READY";
 };
-//#endregion
-//#region src/credentials/schemas.d.ts
-declare const StoredTransportKeyPairSchema: z.ZodMiniObject<{
-  publicKey: z.ZodMiniCustom<`0x${string}`, `0x${string}`>;
-  privateKey: z.ZodMiniCustom<`0x${string}`, `0x${string}`>;
-  createdAt: z.ZodMiniNumberFormat;
-  expiresAt: z.ZodMiniNumberFormat;
-}, z.core.$strip>;
-declare const PermissionSchema: z.ZodMiniObject<{
-  keypairPublicKey: z.ZodMiniCustom<`0x${string}`, `0x${string}`>;
-  contractAddresses: z.ZodMiniArray<z.ZodMiniPipe<z.ZodMiniCustom<`0x${string}`, `0x${string}`>, z.ZodMiniTransform<ChecksummedAddress, `0x${string}`>>>;
-  serializedPermit: z.ZodMiniObject<{
-    version: z.ZodMiniNumberFormat;
-    eip712: z.ZodMiniObject<{
-      domain: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>;
-      primaryType: z.ZodMiniOptional<z.ZodMiniString<string>>;
-      types: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniArray<z.ZodMiniObject<{
-        name: z.ZodMiniString<string>;
-        type: z.ZodMiniString<string>;
-      }, z.core.$strip>>>;
-      message: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>;
-    }, z.core.$strip>;
-    signature: z.ZodMiniCustom<`0x${string}`, `0x${string}`>;
-    signerAddress: z.ZodMiniPipe<z.ZodMiniCustom<`0x${string}`, `0x${string}`>, z.ZodMiniTransform<ChecksummedAddress, `0x${string}`>>;
-  }, z.core.$strip>;
-  startTimestamp: z.ZodMiniNumberFormat;
-  durationDays: z.ZodMiniNumberFormat;
-}, z.core.$strip>;
-//#endregion
-//#region src/credentials/types.d.ts
+/** Union of all {@link ZamaErrorCode} string values. */
+type ZamaErrorCode = (typeof ZamaErrorCode)[keyof typeof ZamaErrorCode];
 /**
- * Serialized transport key pair — ML-KEM public + private key as hex, the shape
- * we persist and hand to the decrypt path. Mirrors `@fhevm/sdk`'s
- * `serializeTransportKeyPair` output; the private half is plaintext, so treat it
- * as sensitive.
+ * Base error thrown by all SDK operations.
+ * Carries a {@link ZamaErrorCode} for programmatic error handling.
+ * Prefer catching specific subclasses (e.g. {@link EncryptionFailedError}).
  */
-interface SerializedTransportKeyPair {
-  publicKey: Hex;
-  privateKey: Hex;
+declare class ZamaError extends Error {
+  /** Machine-readable error code. */
+  readonly code: ZamaErrorCode;
+  /**
+   * Whether the operation that threw this error is safe to retry. Defaults to
+   * {@link RETRYABLE_BY_CODE}'s entry for `code`; only {@link RelayerRequestFailedError}
+   * overrides it per-instance (its retryability depends on the HTTP status).
+   * Prefer {@link isRetryable} over reading this directly, so a new `unknown`
+   * caught value doesn't need an `instanceof ZamaError` check first.
+   */
+  readonly retryable: boolean;
+  constructor(code: ZamaErrorCode, message: string, options?: ErrorOptions & {
+    retryable?: boolean;
+  });
 }
-/** Persisted transport key pair entry with a bounded lifetime. */
-type StoredTransportKeyPair = z.infer<typeof StoredTransportKeyPairSchema>;
 /**
- * A signed EIP-712 permit binding a signer (and optional delegator) to a set of
- * contract addresses for a bounded time window. Wraps the serialized `@fhevm/sdk`
- * permit ({@link SerializedPermit}) alongside the scope/coverage metadata the
- * permission store indexes on.
+ * True if `error` is a {@link ZamaError} whose failure is transient and safe to
+ * retry (rate-limited, back-pressured, a delegation still propagating or in
+ * its per-block cooldown, or a wallet account still resolving).
+ * Compiler-guaranteed to stay in sync with the
+ * taxonomy: every {@link ZamaError} subclass declares its own retryability via
+ * {@link ZamaError.retryable}, so a consumer never has to hardcode a set of
+ * retryable codes.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.decryption.decryptValues([{ encryptedValue, contractAddress }]);
+ * } catch (e) {
+ *   if (isRetryable(e)) {
+ *     // back off and retry (see retryAfterSeconds for a server-suggested delay)
+ *   } else {
+ *     throw e; // terminal — surface it
+ *   }
+ * }
+ * ```
  */
-type Permission = z.infer<typeof PermissionSchema>;
+declare function isRetryable(error: unknown): error is ZamaError & {
+  retryable: true;
+};
 /**
- * Credentials resolved for a decrypt operation: the transport key pair plus the
- * permits covering the requested contracts. A live, in-memory bundle — not a
- * storage record. {@link resolvePermit} extracts one {@link ResolvedPermit} from
- * it per contract.
+ * The server-suggested retry delay, in **seconds**, for a retryable
+ * {@link ZamaError} — unifying the `retryAfter` field that today lives on
+ * {@link RelayerRequestFailedError} and {@link RpcRateLimitError} only.
+ * `undefined` when the error isn't retryable, or is retryable but carries no
+ * server-driven delay (e.g. {@link DelegationNotPropagatedError} — retry that
+ * with your own backoff).
  */
-interface SerializedTransportKeyPairWithPermissions {
-  readonly keypair: SerializedTransportKeyPair;
-  readonly permissions: readonly Permission[];
-}
+declare function retryAfterSeconds(error: unknown): number | undefined;
 //#endregion
-//#region src/wrappers-registry.d.ts
-/**
- * Default wrappers registry addresses for known chains.
- * Only includes chains where a registry is deployed (excludes Hardhat).
- *
- * @deprecated Read `registryAddress` from the chain presets instead (e.g.
- * `sepolia.registryAddress`). Will be removed in the next major version.
- */
-declare const DefaultRegistryAddresses: Record<number, Address>;
-/** Configuration for {@link WrappersRegistry}. */
-interface WrappersRegistryConfig {
-  /** Read-only chain provider used for every registry lookup. */
-  provider: GenericProvider;
-  /**
-   * Per-chain registry address overrides, merged on top of
-   * {@link DefaultRegistryAddresses}. Use this to supply a registry
-   * address for custom or local chains (e.g. Hardhat).
-   *
-   * @example
-   * ```ts
-   * new WrappersRegistry({
-   *   provider,
-   *   registryAddresses: { [31337]: "0xYourHardhatRegistry" },
-   * });
-   * ```
-   */
-  registryAddresses?: Record<number, Address>;
-  /**
-   * How long cached registry results remain valid, in seconds.
-   * Default: `86400` (24 hours).
-   */
-  registryTTL?: number;
-}
-/** Options for {@link WrappersRegistry.listPairs}. */
-interface ListPairsOptions {
-  /** Page number (1-indexed). Default: `1`. */
-  page?: number;
-  /** Number of items per page. Default: `100`. */
-  pageSize?: number;
-  /**
-   * When `true`, fetches on-chain metadata (name, symbol, decimals) for both
-   * the ERC-20 and confidential token, plus totalSupply for the ERC-20.
-   * Default: `false`.
-   */
-  metadata?: boolean;
-}
+//#region src/errors/chain.d.ts
 /**
- * High-level interface for the on-chain token wrappers registry.
+ * Thrown when the signer and provider are connected to different chains at the
+ * start of a write operation.
  *
- * Uses the configured {@link GenericProvider} to resolve the correct registry
- * contract address for the current chain and exposes typed read helpers for
- * every registry query. Results are cached in memory with a configurable TTL
- * (default 24 hours).
- *
- * @example
- * ```ts
- * const registry = new WrappersRegistry({ provider });
- *
- * // Paginated listing
- * const page1 = await registry.listPairs({ page: 1, pageSize: 20 });
- *
- * // Structured lookups
- * const result = await registry.getConfidentialToken(erc20Address);
- * if (result) console.log(result.confidentialTokenAddress);
- *
- * // Force refresh
- * registry.refresh();
- * ```
- */
-declare class WrappersRegistry {
-  #private;
-  readonly provider: GenericProvider;
-  constructor(config: WrappersRegistryConfig);
-  /**
-   * Synchronous lookup of the registry address for a given chain ID.
-   * Returns `undefined` if no address is configured for that chain.
-   */
-  getAddress(chainId: number): Address | undefined;
-  /**
-   * Force-invalidate the in-memory cache. The next call to any read method
-   * will fetch fresh data from the chain.
-   */
-  refresh(): void;
-  /**
-   * The cache TTL in milliseconds.
-   * Exposed so query option factories can set a matching `staleTime`.
-   */
-  get ttlMs(): number;
-  /**
-   * Resolve the registry contract address for the current chain.
-   *
-   * Priority: `registryAddresses[chainId]` \> built-in default.
-   *
-   * @returns The registry contract address for the connected chain.
-   * @throws if no address is configured for the chain. {@link ConfigurationError}
-   */
-  getRegistryAddress(): Promise<Address>;
-  /**
-   * List token wrapper pairs with page-based pagination.
-   *
-   * Internally maps to `getTokenConfidentialTokenPairsSlice` on-chain.
-   *
-   * @param options - Pagination and enrichment options.
-   * @returns A {@link PaginatedResult} of pairs.
-   *
-   * @example
-   * ```ts
-   * const result = await registry.listPairs({ page: 1, pageSize: 20 });
-   * console.log(`${result.total} pairs, showing page ${result.page}`);
-   *
-   * // With on-chain metadata
-   * const withMeta = await registry.listPairs({ metadata: true, pageSize: 10 });
-   * for (const pair of withMeta.items) {
-   *   console.log(pair.underlying.symbol, "→", pair.confidential.symbol);
-   * }
-   * ```
-   */
-  listPairs(options: ListPairsOptions & {
-    metadata: true;
-  }): Promise<PaginatedResult<TokenWrapperPairWithMetadata>>;
-  listPairs(options?: ListPairsOptions): Promise<PaginatedResult<TokenWrapperPair>>;
-  /**
-   * Look up the confidential token for a given plain ERC-20 address.
-   *
-   * @param tokenAddress - The plain ERC-20 token address.
-   * @returns The lookup result, or `null` if the token has never been registered.
-   *   **Note:** revoked tokens (registered then invalidated) return a non-null result
-   *   with `isValid: false`. Check `result.isValid` explicitly rather than using
-   *   `if (result)` to guard against processing revoked tokens.
-   *
-   * @example
-   * ```ts
-   * const result = await registry.getConfidentialToken(usdcAddress);
-   * if (result?.isValid) {
-   *   console.log(result.confidentialTokenAddress);
-   * }
-   * ```
-   */
-  getConfidentialToken(tokenAddress: Address): Promise<{
-    confidentialTokenAddress: Address;
-    isValid: boolean;
-  } | null>;
-  /**
-   * Reverse lookup — find the plain ERC-20 for a given confidential token.
-   *
-   * @param confidentialTokenAddress - The confidential token address.
-   * @returns The lookup result, or `null` if no pair is registered.
-   *
-   * @example
-   * ```ts
-   * const result = await registry.getUnderlyingToken(cUsdcAddress);
-   * if (result) {
-   *   console.log(result.tokenAddress, result.isValid);
-   * }
-   * ```
-   */
-  getUnderlyingToken(confidentialTokenAddress: Address): Promise<{
-    tokenAddress: Address;
-    isValid: boolean;
-  } | null>;
-  /**
-   * Fetch all token wrapper pairs from the registry.
-   *
-   * @returns All registered `TokenWrapperPair` entries.
-   */
-  getTokenPairs(): Promise<readonly TokenWrapperPair[]>;
-  /**
-   * Get the total number of token wrapper pairs.
-   *
-   * @returns The count as a bigint.
-   */
-  getTokenPairsLength(): Promise<bigint>;
-  /**
-   * Fetch a range of token wrapper pairs (paginated by index).
-   *
-   * @param fromIndex - Start index (inclusive).
-   * @param toIndex - End index (exclusive).
-   * @returns The slice of `TokenWrapperPair` entries.
-   */
-  getTokenPairsSlice(fromIndex: bigint, toIndex: bigint): Promise<readonly TokenWrapperPair[]>;
-  /**
-   * Fetch a single token wrapper pair by index.
-   *
-   * @param index - Zero-based pair index.
-   * @returns The `TokenWrapperPair` at that index.
-   */
-  getTokenPair(index: bigint): Promise<TokenWrapperPair>;
-  /**
-   * Look up the confidential token address for a given plain ERC-20 token.
-   *
-   * @param tokenAddress - The plain ERC-20 token address.
-   * @returns A tuple `[isValid, confidentialTokenAddress]`. `isValid` is `true` only for a
-   *   registered, non-revoked wrapper. The address is the zero address when no pair is registered.
-   *   A non-zero address with `isValid=false` means the wrapper was registered but later revoked.
-   */
-  getConfidentialTokenAddress(tokenAddress: Address): Promise<readonly [boolean, Address]>;
-  /**
-   * Reverse lookup — find the plain ERC-20 for a given confidential token.
-   *
-   * @param confidentialTokenAddress - The confidential token address.
-   * @returns A tuple `[isValid, tokenAddress]`. `isValid` is `true` only for a registered,
-   *   non-revoked wrapper. The address is the zero address when no pair is registered.
-   *   A non-zero address with `isValid=false` means the wrapper was registered but later revoked.
-   */
-  getTokenAddress(confidentialTokenAddress: Address): Promise<readonly [boolean, Address]>;
-  /**
-   * Check whether a confidential token is registered and valid.
-   *
-   * @param confidentialTokenAddress - The confidential token address to check.
-   * @returns `true` if the token is a known valid wrapper in the registry.
-   */
-  isConfidentialTokenValid(confidentialTokenAddress: Address): Promise<boolean>;
-}
-//#endregion
-//#region src/query/wrapper-discovery.d.ts
-interface WrapperDiscoveryQueryConfig {
-  /**
-   * Address of any confidential token you control.
-   * Used to scope the query cache key and to gate whether the query
-   * is enabled — it does not affect which wrapper the registry returns.
-   */
-  tokenAddress?: Address;
-  /**
-   * The ERC-20 token address to discover the confidential wrapper for.
-   * The registry is resolved automatically from chain config.
-   */
-  erc20Address?: Address;
-  /**
-   * The resolved registry contract address for the current chain.
-   * Included in the query key so that switching chains invalidates
-   * stale cached results. Pass `undefined` when the chain ID is not
-   * yet known — the query will be disabled.
-   */
-  registryAddress?: Address;
-  query?: Record<string, unknown>;
-}
-declare function wrapperDiscoveryQueryOptions(registry: WrappersRegistry, config: WrapperDiscoveryQueryConfig): QueryFactoryOptions<Address | null, Error, Address | null, ReturnType<typeof zamaQueryKeys.wrapperDiscovery.token>>;
-//#endregion
-//#region src/query/underlying-allowance.d.ts
-interface UnderlyingAllowanceQueryConfig {
-  owner?: Address;
-  query?: Record<string, unknown>;
-}
-declare function underlyingAllowanceQueryOptions(sdk: ZamaSDK, tokenAddress: Address, config: UnderlyingAllowanceQueryConfig): QueryFactoryOptions<bigint, Error, bigint, ReturnType<typeof zamaQueryKeys.underlyingAllowance.scope>>;
-//#endregion
-//#region src/query/pending-unshield.d.ts
-interface PendingUnshieldQueryConfig {
-  query?: Record<string, unknown>;
-}
-/**
- * Query options for reading the unwrap tx hash of an unshield that was
- * interrupted between its two phases (returns `null` if none is pending).
- *
- * Backed by {@link ZamaSDK} storage via `WrappedToken.getPendingUnshield()`.
- * `staleTime: 0` so the value reflects storage on mount; the unshield/unwrap
- * mutations also invalidate this key on success.
- */
-declare function pendingUnshieldQueryOptions(sdk: ZamaSDK, tokenAddress: Address, config?: PendingUnshieldQueryConfig): QueryFactoryOptions<Hex | null, Error, Hex | null, ReturnType<typeof zamaQueryKeys.pendingUnshield.token>>;
-//#endregion
-//#region src/query/confidential-is-operator.d.ts
-interface ConfidentialIsOperatorQueryConfig {
-  holder?: Address;
-  spender?: Address;
-  query?: Record<string, unknown>;
-}
-declare function confidentialIsOperatorQueryOptions(sdk: ZamaSDK, tokenAddress: Address | undefined, config: ConfidentialIsOperatorQueryConfig): QueryFactoryOptions<boolean, Error, boolean, ReturnType<typeof zamaQueryKeys.confidentialIsOperator.scope>>;
-//#endregion
-//#region src/errors/base.d.ts
-/**
- * Typed error codes thrown by the SDK.
- * Use `error.code` or `instanceof` to programmatically handle specific failure modes.
- *
- * @example
- * ```ts
- * try {
- *   await token.confidentialTransfer("0xTo", 100n);
- * } catch (e) {
- *   if (e instanceof SigningRejectedError) {
- *     // User rejected the wallet signature
- *   }
- * }
- * ```
- */
-declare const ZamaErrorCode: {
-  /** User rejected the wallet signature prompt. */
-  readonly SigningRejected: "SIGNING_REJECTED";
-  /** Wallet signature failed for a reason other than rejection. */
-  readonly SigningFailed: "SIGNING_FAILED";
-  /** FHE encryption failed. */
-  readonly EncryptionFailed: "ENCRYPTION_FAILED";
-  /** FHE decryption failed. */
-  readonly DecryptionFailed: "DECRYPTION_FAILED";
-  /** On-chain transaction reverted. */
-  readonly TransactionReverted: "TRANSACTION_REVERTED";
-  /** Transport key pair has expired and needs regeneration. */
-  readonly TransportKeyPairExpired: "KEYPAIR_EXPIRED";
-  /** Relayer rejected transport key pair (stale, expired, or malformed). */
-  readonly InvalidTransportKeyPair: "INVALID_KEYPAIR";
-  /** No FHE ciphertext exists for this account (never shielded). */
-  readonly NoCiphertext: "NO_CIPHERTEXT";
-  /** Relayer HTTP request failed. */
-  readonly RelayerRequestFailed: "RELAYER_REQUEST_FAILED";
-  /** The configured signer/account is not entitled (ACL) to decrypt this encrypted value. Don't retry — wait for a grant. */
-  readonly NotEntitled: "NOT_ENTITLED";
-  /** The consumer's RPC provider rate-limited an on-chain read (e.g. HTTP 429 / JSON-RPC -32005). Retryable. */
-  readonly RpcRateLimited: "RPC_RATE_LIMITED";
-  /** SDK configuration is invalid (e.g. forbidden chain ID, unsupported type). */
-  readonly Configuration: "CONFIGURATION";
-  /** Delegation cannot target self (delegate === msg.sender). */
-  readonly DelegationSelfNotAllowed: "DELEGATION_SELF_NOT_ALLOWED";
-  /** Only one delegate/revoke per (delegator, delegate, contract) per block. */
-  readonly DelegationCooldown: "DELEGATION_COOLDOWN";
-  /** No active delegation found for this (delegator, delegate, contract) tuple. */
-  readonly DelegationNotFound: "DELEGATION_NOT_FOUND";
-  /** The delegation has expired. */
-  readonly DelegationExpired: "DELEGATION_EXPIRED";
-  /** Confidential (cToken) balance is insufficient for the requested operation. */
-  readonly InsufficientConfidentialBalance: "INSUFFICIENT_CONFIDENTIAL_BALANCE";
-  /** ERC-20 balance is insufficient for the requested shield amount. */
-  readonly InsufficientERC20Balance: "INSUFFICIENT_ERC20_BALANCE";
-  /** ERC-20 allowance granted to the wrapper is insufficient for the requested wrap amount. */
-  readonly InsufficientAllowance: "INSUFFICIENT_ALLOWANCE";
-  /** Balance validation could not be performed (no cached credentials and decryption not possible). */
-  readonly BalanceCheckUnavailable: "BALANCE_CHECK_UNAVAILABLE";
-  /** Public ERC-20 read (e.g. balanceOf) failed due to a network or contract error. */
-  readonly ERC20ReadFailed: "ERC20_READ_FAILED";
-  /** The new expiration date equals the current one — no on-chain change needed. */
-  readonly DelegationExpiryUnchanged: "DELEGATION_EXPIRY_UNCHANGED";
-  /** Delegate address cannot be the contract address. */
-  readonly DelegationDelegateEqualsContract: "DELEGATION_DELEGATE_EQUALS_CONTRACT";
-  /** Contract address cannot be the sender address. */
-  readonly DelegationContractIsSelf: "DELEGATION_CONTRACT_IS_SELF";
-  /** The ACL contract is paused. */
-  readonly AclPaused: "ACL_PAUSED";
-  /** Expiration date is too soon (must be at least 1 hour in the future). */
-  readonly DelegationExpirationTooSoon: "DELEGATION_EXPIRATION_TOO_SOON";
-  /** Delegation exists on-chain but hasn't propagated to the gateway yet. */
-  readonly DelegationNotPropagated: "DELEGATION_NOT_PROPAGATED";
-  /** Signer and provider are connected to different chains. */
-  readonly ChainMismatch: "CHAIN_MISMATCH";
-  /** Operation requires a signer but none is configured. */
-  readonly SignerNotConfigured: "SIGNER_NOT_CONFIGURED";
-  /** Operation requires a connected wallet account. */
-  readonly WalletNotConnected: "WALLET_NOT_CONNECTED";
-  /** Wallet account discovery is still resolving. */
-  readonly WalletAccountNotReady: "WALLET_ACCOUNT_NOT_READY";
-};
-/** Union of all {@link ZamaErrorCode} string values. */
-type ZamaErrorCode = (typeof ZamaErrorCode)[keyof typeof ZamaErrorCode];
-/**
- * Base error thrown by all SDK operations.
- * Carries a {@link ZamaErrorCode} for programmatic error handling.
- * Prefer catching specific subclasses (e.g. {@link EncryptionFailedError}).
- */
-declare class ZamaError extends Error {
-  /** Machine-readable error code. */
-  readonly code: ZamaErrorCode;
-  /**
-   * Whether the operation that threw this error is safe to retry. Defaults to
-   * {@link RETRYABLE_BY_CODE}'s entry for `code`; only {@link RelayerRequestFailedError}
-   * overrides it per-instance (its retryability depends on the HTTP status).
-   * Prefer {@link isRetryable} over reading this directly, so a new `unknown`
-   * caught value doesn't need an `instanceof ZamaError` check first.
-   */
-  readonly retryable: boolean;
-  constructor(code: ZamaErrorCode, message: string, options?: ErrorOptions & {
-    retryable?: boolean;
-  });
-}
-/**
- * True if `error` is a {@link ZamaError} whose failure is transient and safe to
- * retry (rate-limited, back-pressured, a delegation still propagating or in
- * its per-block cooldown, or a wallet account still resolving).
- * Compiler-guaranteed to stay in sync with the
- * taxonomy: every {@link ZamaError} subclass declares its own retryability via
- * {@link ZamaError.retryable}, so a consumer never has to hardcode a set of
- * retryable codes.
- *
- * @example
- * ```ts
- * try {
- *   await sdk.decryption.decryptValues([{ encryptedValue, contractAddress }]);
- * } catch (e) {
- *   if (isRetryable(e)) {
- *     // back off and retry (see retryAfterSeconds for a server-suggested delay)
- *   } else {
- *     throw e; // terminal — surface it
- *   }
- * }
- * ```
- */
-declare function isRetryable(error: unknown): error is ZamaError & {
-  retryable: true;
-};
-/**
- * The server-suggested retry delay, in **seconds**, for a retryable
- * {@link ZamaError} — unifying the `retryAfter` field that today lives on
- * {@link RelayerRequestFailedError} and {@link RpcRateLimitError} only.
- * `undefined` when the error isn't retryable, or is retryable but carries no
- * server-driven delay (e.g. {@link DelegationNotPropagatedError} — retry that
- * with your own backoff).
- */
-declare function retryAfterSeconds(error: unknown): number | undefined;
-//#endregion
-//#region src/errors/chain.d.ts
-/**
- * Thrown when the signer and provider are connected to different chains at the
- * start of a write operation.
- *
- * Every write method runs a chain-alignment pre-flight check. If
- * `signer.getChainId()` and `provider.getChainId()` return different values,
- * this error is thrown before any RPC mutation is attempted.
+ * Every write method runs a chain-alignment pre-flight check. If
+ * `signer.getChainId()` and `provider.getChainId()` return different values,
+ * this error is thrown before any RPC mutation is attempted.
  *
  * @example
  * ```ts
@@ -19248,8 +18860,11 @@ declare function retryAfterSeconds(error: unknown): number | undefined;
  * ```
  */
 declare class ChainMismatchError extends ZamaError {
+  /** Name of the operation that triggered the check. */
   readonly operation: string;
+  /** Chain ID the signer is connected to. */
   readonly signerChainId: number;
+  /** Chain ID the provider is connected to. */
   readonly providerChainId: number;
   constructor({ operation, signerChainId, providerChainId }: {
     operation: string;
@@ -19349,8 +18964,11 @@ declare class DecryptionFailedError extends ZamaError {
 //#region src/errors/balance.d.ts
 /** Structured details shared by balance-related errors. */
 interface BalanceErrorDetails {
+  /** Amount the caller requested, in the token's base units. */
   readonly requested: bigint;
+  /** Amount available at the time of the check, in the token's base units. */
   readonly available: bigint;
+  /** Address of the token contract involved. */
   readonly token: Address;
 }
 /** Confidential (cToken) balance is insufficient for the requested operation. */
@@ -19488,6 +19106,7 @@ declare class RpcRateLimitError extends ZamaError {
  * Base class for signer/account readiness failures.
  */
 declare class SignerRequiredError extends ZamaError {
+  /** Name of the operation that required a signer. */
   readonly operation: string;
   constructor(code: ZamaErrorCode, operation: string, message: string, options?: ErrorOptions);
 }
@@ -19537,51 +19156,75 @@ declare class TransactionRevertedError extends ZamaError {
 }
 //#endregion
 //#region src/errors/match.d.ts
-/**
- * Identity type that fails to instantiate unless `T` maps every code to a `ZamaError`.
- * Guards presence + value type only: a wrong-but-valid mapping (a code pointing at a
- * structurally identical sibling class) still compiles — `errors.test-d.ts` backstops that.
- */
-type Complete<T extends Record<ZamaErrorCode, ZamaError>> = T;
 /**
  * Maps each {@link ZamaErrorCode} to the error class thrown with that code, so
  * {@link matchZamaError} handlers receive the matched subtype instead of the base
- * `ZamaError`. Hand-maintained; the `Complete` wrapper fails the build if a code is
- * added without an entry here (or mapped to a non-`ZamaError`).
+ * `ZamaError`.
  */
-type ErrorForCode = Complete<{
+interface ErrorForCode {
+  /** Thrown for {@link ZamaErrorCode.SigningRejected}. */
   [ZamaErrorCode.SigningRejected]: SigningRejectedError;
+  /** Thrown for {@link ZamaErrorCode.SigningFailed}. */
   [ZamaErrorCode.SigningFailed]: SigningFailedError;
+  /** Thrown for {@link ZamaErrorCode.EncryptionFailed}. */
   [ZamaErrorCode.EncryptionFailed]: EncryptionFailedError;
+  /** Thrown for {@link ZamaErrorCode.DecryptionFailed}. */
   [ZamaErrorCode.DecryptionFailed]: DecryptionFailedError;
+  /** Thrown for {@link ZamaErrorCode.TransactionReverted}. */
   [ZamaErrorCode.TransactionReverted]: TransactionRevertedError;
+  /** Thrown for {@link ZamaErrorCode.TransportKeyPairExpired}. */
   [ZamaErrorCode.TransportKeyPairExpired]: TransportKeyPairExpiredError;
+  /** Thrown for {@link ZamaErrorCode.InvalidTransportKeyPair}. */
   [ZamaErrorCode.InvalidTransportKeyPair]: InvalidTransportKeyPairError;
+  /** Thrown for {@link ZamaErrorCode.NoCiphertext}. */
   [ZamaErrorCode.NoCiphertext]: NoCiphertextError;
+  /** Thrown for {@link ZamaErrorCode.RelayerRequestFailed}. */
   [ZamaErrorCode.RelayerRequestFailed]: RelayerRequestFailedError;
+  /** Thrown for {@link ZamaErrorCode.NotEntitled}. */
   [ZamaErrorCode.NotEntitled]: NotEntitledError;
+  /** Thrown for {@link ZamaErrorCode.RpcRateLimited}. */
   [ZamaErrorCode.RpcRateLimited]: RpcRateLimitError;
+  /** Thrown for {@link ZamaErrorCode.Configuration}. */
   [ZamaErrorCode.Configuration]: ConfigurationError;
+  /** Thrown for {@link ZamaErrorCode.DelegationSelfNotAllowed}. */
   [ZamaErrorCode.DelegationSelfNotAllowed]: DelegationSelfNotAllowedError;
+  /** Thrown for {@link ZamaErrorCode.DelegationCooldown}. */
   [ZamaErrorCode.DelegationCooldown]: DelegationCooldownError;
+  /** Thrown for {@link ZamaErrorCode.DelegationNotFound}. */
   [ZamaErrorCode.DelegationNotFound]: DelegationNotFoundError;
+  /** Thrown for {@link ZamaErrorCode.DelegationExpired}. */
   [ZamaErrorCode.DelegationExpired]: DelegationExpiredError;
+  /** Thrown for {@link ZamaErrorCode.InsufficientConfidentialBalance}. */
   [ZamaErrorCode.InsufficientConfidentialBalance]: InsufficientConfidentialBalanceError;
+  /** Thrown for {@link ZamaErrorCode.InsufficientERC20Balance}. */
   [ZamaErrorCode.InsufficientERC20Balance]: InsufficientERC20BalanceError;
+  /** Thrown for {@link ZamaErrorCode.InsufficientAllowance}. */
   [ZamaErrorCode.InsufficientAllowance]: InsufficientAllowanceError;
+  /** Thrown for {@link ZamaErrorCode.BalanceCheckUnavailable}. */
   [ZamaErrorCode.BalanceCheckUnavailable]: BalanceCheckUnavailableError;
+  /** Thrown for {@link ZamaErrorCode.ERC20ReadFailed}. */
   [ZamaErrorCode.ERC20ReadFailed]: ERC20ReadFailedError;
+  /** Thrown for {@link ZamaErrorCode.DelegationExpiryUnchanged}. */
   [ZamaErrorCode.DelegationExpiryUnchanged]: DelegationExpiryUnchangedError;
+  /** Thrown for {@link ZamaErrorCode.DelegationDelegateEqualsContract}. */
   [ZamaErrorCode.DelegationDelegateEqualsContract]: DelegationDelegateEqualsContractError;
+  /** Thrown for {@link ZamaErrorCode.DelegationContractIsSelf}. */
   [ZamaErrorCode.DelegationContractIsSelf]: DelegationContractIsSelfError;
+  /** Thrown for {@link ZamaErrorCode.AclPaused}. */
   [ZamaErrorCode.AclPaused]: AclPausedError;
+  /** Thrown for {@link ZamaErrorCode.DelegationExpirationTooSoon}. */
   [ZamaErrorCode.DelegationExpirationTooSoon]: DelegationExpirationTooSoonError;
+  /** Thrown for {@link ZamaErrorCode.DelegationNotPropagated}. */
   [ZamaErrorCode.DelegationNotPropagated]: DelegationNotPropagatedError;
+  /** Thrown for {@link ZamaErrorCode.ChainMismatch}. */
   [ZamaErrorCode.ChainMismatch]: ChainMismatchError;
+  /** Thrown for {@link ZamaErrorCode.SignerNotConfigured}. */
   [ZamaErrorCode.SignerNotConfigured]: SignerNotConfiguredError;
+  /** Thrown for {@link ZamaErrorCode.WalletNotConnected}. */
   [ZamaErrorCode.WalletNotConnected]: WalletNotConnectedError;
+  /** Thrown for {@link ZamaErrorCode.WalletAccountNotReady}. */
   [ZamaErrorCode.WalletAccountNotReady]: WalletAccountNotReadyError;
-}>;
+}
 /**
  * Pattern-match on a {@link ZamaError} by its error code. Each handler receives the
  * error class for its code, so subclass fields are available without a cast.
@@ -19602,1455 +19245,1226 @@ declare function matchZamaError<R>(error: unknown, handlers: { [K in ZamaErrorCo
   _?: (error: unknown) => R;
 }): R | undefined;
 //#endregion
-//#region src/token/token.d.ts
-/** Options for {@link Token.batchDecryptBalancesAs}. */
-interface BatchDecryptAsOptions {
-  /** The address of the account that delegated decryption rights. */
-  delegatorAddress: Address;
-  /** Pre-fetched encrypted values. When omitted, they are fetched from the chain. */
-  encryptedValues?: EncryptedValue[];
+//#region src/services/decryption-service.d.ts
+/** Options shared by the delegated-decrypt entry points. */
+interface DelegatedDecryptOptions {
   /**
-   * The account whose on-chain balance to read. Defaults to the delegator
-   * address, which is the common case (the delegator grants permission to
-   * decrypt their own balance). Only set this when the account differs
-   * from the delegator.
-   *
-   * Matches the `account` parameter of `confidentialBalanceOf(account)` on-chain.
+   * Ride out the gateway propagation window: when a just-granted delegation
+   * has not yet synced, the delegated decrypt is retried (bounded, ~30s) until
+   * it lands instead of throwing {@link DelegationNotPropagatedError}. Defaults
+   * to `true`. Pass `false` to fail fast on the first not-propagated response.
    */
-  accountAddress?: Address;
-  /** Maximum number of concurrent decrypt calls. Default: 10. */
-  maxConcurrency?: number;
-  /** Called when decryption fails for a single token. Return a fallback bigint. */
-  onError?: (error: Error, address: Address) => bigint;
+  waitForPropagation?: boolean;
 }
-/** Result of {@link Token.batchBalancesOf}. */
-interface BatchBalancesResult {
-  /** Successfully decrypted balances, keyed by token address. */
-  results: Map<Address, bigint>;
-  /** Per-token errors for tokens that failed to decrypt. */
-  errors: Map<Address, ZamaError>;
+/** Per-handle outcome of a batch decrypt: the decrypted value, or a per-item error. */
+interface BatchDecryptItem {
+  /** The encrypted value (handle) being decrypted. */
+  encryptedValue: EncryptedValue;
+  /** Address of the contract the handle belongs to. */
+  contractAddress: Address;
+  /** Decrypted clear value; set when this item succeeded. */
+  value?: ClearValue;
+  /** Error for this item; set when this item failed. */
+  error?: ZamaError;
+}
+/** Result of a batch decrypt: one entry per requested handle, in input order. */
+interface BatchDecryptResult {
+  /** Per-handle outcomes. */
+  items: BatchDecryptItem[];
 }
+//#endregion
+//#region src/namespaces/decryption.d.ts
 /**
- * High-level interface for an ERC-7984 confidential token.
- * Hides FHE complexity (encryption, decryption, EIP-712 signing) behind
- * familiar ERC-20-like methods.
+ * Public namespace for FHE decryption — the canonical way to decrypt.
  *
- * For ERC-7984 wrappers (shield/unshield), use {@link WrappedToken} instead —
- * it extends `Token` with wrapper-specific operations.
+ * Exposed as `sdk.decryption`. Prefer these methods over the low-level
+ * `sdk.relayer.decryptValues` / `decryptPublicValues`: they
+ * assemble the credential bundle (transport key pair, EIP-712 permit) for you,
+ * cache results, and wrap relayer errors. Reach for `sdk.relayer.*` only when
+ * you must control credential assembly by hand.
  *
- * Decryption, credentials, caching, and event emission are handled by the
- * owning {@link ZamaSDK} — this class only exposes token-scoped helpers
- * that delegate to `sdk.decryption.decryptValues` and `sdk.permits.grantPermit`.
+ * Owns the SDK-level guards (signer requirement on
+ * `decryptValues` and `delegatedDecryptValues`, empty-array
+ * short-circuit on `decryptPublicValues`, relayer error wrapping) and delegates the
+ * actual work to the internal {@link DecryptionService} or the relayer directly for
+ * `decryptPublicValues`.
+ *
+ * **Mixed signer requirement:** `decryptValues` and
+ * `delegatedDecryptValues` need a configured signer; `decryptPublicValues`
+ * does not. Each method documents its requirement in its JSDoc.
+ *
+ * **Request chunking:** decrypt requests are split internally to stay under
+ * the relayer's 2048-cleartext-bit per-request budget — callers never need to
+ * size batches themselves.
  */
-declare class Token {
+declare class Decryption {
   #private;
-  readonly sdk: ZamaSDK;
-  readonly address: Address;
-  constructor(sdk: ZamaSDK, address: Address);
-  /** Read the token name from the contract. */
-  name(): Promise<string>;
-  /** Read the token symbol from the contract. */
-  symbol(): Promise<string>;
-  /** Read the token decimals from the contract. */
-  decimals(): Promise<number>;
-  /**
-   * ERC-165 check for {@link ERC7984_INTERFACE_ID} support.
-   *
-   * @returns `true` if the contract implements the ERC-7984 confidential token interface.
-   */
-  isConfidential(): Promise<boolean>;
-  /**
-   * ERC-165 check for IERC7984ERC20Wrapper support.
-   *
-   * @returns `true` if the contract implements the ERC-7984 wrapper interface
-   *   ({@link ERC7984_WRAPPER_INTERFACE_ID}, `0x1f1c62b2`).
-   */
-  isWrapper(): Promise<boolean>;
   /**
-   * Decrypt and return the plaintext balance for the given owner.
-   * Acquires FHE credentials via a wallet signature if none are cached.
-   *
-   * @param owner - Balance owner address.
-   * @returns The decrypted plaintext balance as a bigint.
-   * @throws if FHE decryption fails. {@link DecryptionFailedError}
+   * Decrypt one or more FHE encrypted values. Results are cached — repeated calls
+   * for the same encrypted value skip the relayer round-trip.
    *
-   * @example
-   * ```ts
-   * const balance = await token.balanceOf("0xOwner");
-   * ```
-   */
-  balanceOf(owner: Address): Promise<bigint>;
-  /**
-   * Return the raw encrypted balance without decrypting.
+   * Zero encrypted values are mapped to `0n` without hitting the relayer.
+   * Events (`DecryptStart/End/Error`) are emitted uniformly.
+   * Relayer errors are wrapped into typed SDK errors.
    *
-   * @param owner - Balance owner address.
-   * @returns The encrypted balance as a hex string.
+   * @param encryptedInput - Encrypted values to decrypt, each paired with its contract address.
+   * @param options - Per-call `signal` and `timeout` forwarded to the relayer round-trip.
+   * @returns A record mapping each encrypted value to its decrypted clear-text value.
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
    *
    * @example
    * ```ts
-   * const encryptedValue = await token.confidentialBalanceOf("0xOwner");
+   * const values = await sdk.decryption.decryptValues([
+   *   { encryptedValue: balance, contractAddress: cUSDT },
+   * ]);
+   * console.log(values[balance]); // 1000n
    * ```
    */
-  confidentialBalanceOf(owner: Address): Promise<EncryptedValue>;
+  decryptValues(encryptedInput: EncryptedInput[], options?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<Record<EncryptedValue, ClearValue>>;
   /**
-   * Decrypt the balance of a delegator using delegated decryption credentials.
-   * The connected signer acts as the delegatee who has been granted permission
-   * by the delegator to decrypt their balance.
+   * Decrypt one or more FHE encrypted values using delegated credentials.
    *
-   * Clear values are cached in storage keyed by `(account, token, encryptedValue)`.
-   * Because every on-chain balance change produces a new encrypted value,
-   * stale cache entries are never served. Cache write failures are silently
-   * ignored — they do not affect the returned value.
+   * Mirrors {@link decryptValues} with delegated credentials — same caching and
+   * zero-value short-circuit. Before reading from cache or calling the relayer,
+   * every non-zero encrypted value's contract must have an active delegation from the
+   * delegator to the connected signer; missing or expired delegations fail fast.
    *
-   * @param delegatorAddress - The address of the account that delegated decryption rights.
-   * @param accountAddress - The account whose on-chain balance to read. Defaults
-   *   to the delegator address.
-   * @returns The decrypted plaintext balance as a bigint.
-   * @throws if no active delegation exists. {@link DelegationNotFoundError}
-   * @throws if the delegation has expired. {@link DelegationExpiredError}
-   * @throws if delegated decryption fails. {@link DecryptionFailedError}
+   * @param encryptedInputs - FHE encrypted values paired with their contract addresses.
+   * @param delegatorAddress - The address that granted delegation rights.
+   * @param accountAddress - Address used as the cache key's "requester"
+   *   dimension. Defaults to `delegatorAddress`. Pass the actual account address
+   *   when decrypting on behalf of someone whose balance is stored under a
+   *   different address (e.g. `decryptBalanceAs` with an explicit `accountAddress`).
+   * @param options - Delegated-decrypt options. By default the call rides out the
+   *   gateway propagation window ({@link DelegatedDecryptOptions.waitForPropagation});
+   *   pass `{ waitForPropagation: false }` to fail fast instead.
+   * @returns Map of encrypted value → clear-text value.
    *
    * @example
    * ```ts
-   * const balance = await token.decryptBalanceAs({
-   *   delegatorAddress: "0xDelegator",
-   * });
+   * const values = await sdk.decryption.delegatedDecryptValues([
+   *   { encryptedValue: balance, contractAddress: tokenAddr },
+   * ], delegatorAddr);
+   * console.log(values[balance]); // 1000n
    * ```
    */
-  decryptBalanceAs({ delegatorAddress, accountAddress }: {
-    delegatorAddress: Address;
-    accountAddress?: Address;
-  }): Promise<bigint>;
+  delegatedDecryptValues(encryptedInputs: EncryptedInput[], delegatorAddress: Address, accountAddress?: Address, options?: DelegatedDecryptOptions): Promise<Record<EncryptedValue, ClearValue>>;
   /**
-   * Decrypt confidential balances for multiple tokens in parallel, returning
-   * successes and per-token errors separately. Pre-authorizes all token
-   * addresses in a single wallet signature, then delegates each decrypt to
-   * `sdk.decryption.decryptValues`.
+   * Publicly decrypt one or more FHE encrypted values.
    *
-   * Tokens that fail to decrypt land in `errors` rather than aborting the
-   * whole batch — caller decides how to surface them.
+   * Signer-independent: works without a configured signer.
+   * Returns the decryption proof alongside the clear-text values so callers
+   * can submit on-chain finalization transactions (e.g. `finalizeUnwrap`).
    *
-   * @param tokens - Array of {@link Token} instances bound to the same SDK.
-   * @param owner - Balance owner address.
-   * @returns `{ results, errors }` partitioning the per-token outcomes.
+   * @param encryptedValues - FHE encrypted values to decrypt publicly.
+   * @param options - Per-call `signal` and `timeout` forwarded to the relayer round-trip.
+   * @returns Clear-text values, ABI-encoded values, and the decryption proof.
    *
    * @example
    * ```ts
-   * const { results, errors } = await Token.batchBalancesOf(tokens, owner);
+   * const { clearValues, decryptionProof, abiEncodedClearValues } =
+   *   await sdk.decryption.decryptPublicValues([encryptedValue]);
    * ```
    */
-  static batchBalancesOf(tokens: Token[], owner: Address): Promise<BatchBalancesResult>;
+  decryptPublicValues(encryptedValues: EncryptedValue[], options?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<DecryptPublicValuesResult>;
   /**
-   * Batch decrypt confidential balances as a delegate across multiple tokens.
-   * Mirrors {@link batchBalancesOf} but uses delegated credentials.
+   * Batch-decrypt delegated encrypted values with per-entry error isolation.
    *
-   * **Error handling:** If a per-token decryption fails and no `onError` callback
-   * is provided, errors are collected and thrown as an aggregated
-   * `DecryptionFailedError`. When the relayer returns no value for an encrypted value,
-   * a `DecryptionFailedError` is thrown for that token (never silently returns `0n`).
-   * Pass `onError: () => 0n` to opt into the silent zero behavior.
+   * Attempts a single batch request first. If the batch fails with a non-fatal
+   * error (e.g. one entry is invalid), falls back to per-entry decryption so
+   * healthy entries still resolve. Each item in the result carries either a
+   * decrypted value or an error — callers decide how to surface partial failures.
    *
-   * @param tokens - Array of Token instances to decrypt balances for.
-   * @param options - Delegated decryption configuration.
-   * @returns A Map from token address to decrypted balance.
-   * @throws if no active delegation exists. {@link DelegationNotFoundError}
-   * @throws if the delegation has expired. {@link DelegationExpiredError}
-   * @throws if any decryption fails and no `onError` is provided. {@link DecryptionFailedError}
+   * @param encryptedInputs - FHE encrypted values paired with their contract addresses.
+   * @param delegatorAddress - The address that granted delegation rights.
+   * @param accountAddress - The account on whose behalf decryption is performed. Defaults to `delegatorAddress`.
+   * @param maxConcurrency - Maximum parallel decrypt calls during per-entry fallback.
+   * @param waitForPropagation - Ride out the gateway propagation window on the
+   *   initial batch attempt (default `true`). See {@link DelegatedDecryptOptions.waitForPropagation}.
+   * @returns Per-entry results, each with a value or an error.
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
    *
    * @example
    * ```ts
-   * const balances = await Token.batchDecryptBalancesAs(tokens, {
+   * const result = await sdk.decryption.delegatedBatchDecryptValues({
+   *   encryptedInputs: [
+   *     { encryptedValue: encryptedValue1, contractAddress: tokenA },
+   *     { encryptedValue: encryptedValue2, contractAddress: tokenB },
+   *   ],
    *   delegatorAddress: "0xDelegator",
-   *   onError: (err, addr) => { console.error(addr, err); return 0n; },
+   *   maxConcurrency: 5,
    * });
+   * for (const item of result.items) {
+   *   if (item.error) console.error(item.encryptedValue, item.error);
+   *   else console.log(item.encryptedValue, item.value);
+   * }
    * ```
    */
-  static batchDecryptBalancesAs(tokens: Token[], options: BatchDecryptAsOptions): Promise<Map<Address, bigint>>;
-  private static readBalanceHandlesBatch;
+  delegatedBatchDecryptValues({ encryptedInputs, delegatorAddress, accountAddress, maxConcurrency, waitForPropagation }: {
+    encryptedInputs: EncryptedInput[];
+    delegatorAddress: Address;
+    accountAddress?: Address;
+    maxConcurrency?: number;
+  } & DelegatedDecryptOptions): Promise<BatchDecryptResult>;
+}
+//#endregion
+//#region src/services/delegation-service.d.ts
+/** Delegation activity and expiry, resolved from a single expiry read. */
+interface DelegationStatus {
+  /** Whether the delegation is currently active (exists and not expired). */
+  isActive: boolean;
+  /** Unix timestamp (seconds) when the delegation expires; `0n` if none exists. */
+  expiryTimestamp: bigint;
+}
+//#endregion
+//#region src/namespaces/delegations.d.ts
+/**
+ * Public namespace for on-chain decryption-delegation management.
+ *
+ * Exposed as `sdk.delegations`. Owns the SDK-level guards (signer requirement, chain
+ * alignment, delegator address resolution from the wallet account) and delegates the
+ * actual work to the internal {@link DelegationService}.
+ *
+ * Delegation operations write to the host chain ACL; after a delegation is mined,
+ * the gateway syncs the ACL state via cross-chain event propagation — usually
+ * within ~10 blocks (a few seconds). Delegated decryption rides out that window
+ * with a bounded internal retry, so callers can decrypt right after granting.
+ */
+declare class Delegations {
+  #private;
   /**
-   * Confidential transfer. Encrypts the amount via FHE, then calls the contract.
+   * Delegate decryption rights for a confidential contract to another address.
+   * Calls `ACL.delegateForUserDecryption()` on-chain.
    *
-   * By default, the SDK validates the confidential balance before submitting.
-   * If a cached plaintext balance exists it is used; otherwise, if credentials
-   * are cached, it decrypts on the fly. Set `skipBalanceCheck: true` to bypass
-   * this validation (e.g. for smart wallets).
+   * The delegation is recorded on L1 immediately, but the gateway must sync the
+   * ACL state via cross-chain event propagation — usually within ~10 blocks (a
+   * few seconds). You do not need to wait: delegated decryption rides out that
+   * window with a bounded internal retry, so you can decrypt right after this
+   * resolves.
    *
-   * @param to - Recipient address.
-   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
-   * @param options - Optional: `skipBalanceCheck` (default `false`).
+   * @param contractAddress - The confidential contract address to delegate on.
+   * @param delegateAddress - Address to delegate decryption rights to.
+   * @param expirationDate - Optional expiration date (defaults to permanent delegation via `uint64.max`).
    * @returns The transaction hash and mined receipt.
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
    * @throws if signer and provider are on different chains. {@link ChainMismatchError}
-   * @throws if the balance is less than `amount`. {@link InsufficientConfidentialBalanceError}
-   * @throws if balance validation requires decryption that is not possible. {@link BalanceCheckUnavailableError}
-   * @throws if FHE encryption fails. {@link EncryptionFailedError}
-   * @throws if the on-chain transfer reverts. {@link TransactionRevertedError}
-   *
-   * @example
-   * ```ts
-   * const txHash = await token.confidentialTransfer("0xRecipient", 1000n);
-   * ```
+   * @throws if `expirationDate` is less than 1 hour in the future. {@link DelegationExpirationTooSoonError}
+   * @throws if the delegate equals the connected wallet. {@link DelegationSelfNotAllowedError}
+   * @throws if the delegate equals the contract address. {@link DelegationDelegateEqualsContractError}
+   * @throws if the new expiry equals the current one. {@link DelegationExpiryUnchangedError}
+   * @throws if the delegation transaction reverts. {@link TransactionRevertedError}
    */
-  confidentialTransfer(to: Address, amount: bigint, options?: TransferOptions): Promise<TransactionResult>;
+  delegateDecryption({ contractAddress, delegateAddress, expirationDate }: {
+    contractAddress: Address;
+    delegateAddress: Address;
+    expirationDate?: Date;
+  }): Promise<TransactionResult>;
   /**
-   * Operator encrypted transfer on behalf of another address.
-   * The caller must be an approved operator for `from`.
+   * Revoke decryption delegation for a confidential contract.
+   * Calls `ACL.revokeDelegationForUserDecryption()` on-chain.
    *
-   * @param from - The address to transfer from (caller must be an approved operator).
-   * @param to - Recipient address.
-   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
+   * @param contractAddress - The confidential contract address to revoke delegation on.
+   * @param delegateAddress - Address to revoke delegation from.
    * @returns The transaction hash and mined receipt.
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
+   * @throws if no delegation exists for this (delegator, delegate, contract) tuple. {@link DelegationNotFoundError}
+   * @throws if the revocation transaction reverts. {@link TransactionRevertedError}
+   */
+  revokeDelegation({ contractAddress, delegateAddress }: {
+    contractAddress: Address;
+    delegateAddress: Address;
+  }): Promise<TransactionResult>;
+  /**
+   * Check whether a delegation is active for the given contract address.
    *
-   * @example
-   * ```ts
-   * const txHash = await token.confidentialTransferFrom("0xFrom", "0xTo", 500n);
-   * ```
+   * Signer-independent: works without a configured signer.
+   *
+   * @param contractAddress - The confidential contract address.
+   * @param delegatorAddress - The address that granted the delegation.
+   * @param delegateAddress - The address that received delegation rights.
+   * @returns `true` if the delegation exists and has not expired.
    */
-  confidentialTransferFrom(from: Address, to: Address, amount: bigint, callbacks?: TransferCallbacks): Promise<TransactionResult>;
+  isActive(params: {
+    contractAddress: Address;
+    delegatorAddress: Address;
+    delegateAddress: Address;
+  }): Promise<boolean>;
   /**
-   * ERC-7984 `confidentialTransferAndCall`: encrypted transfer that also invokes
-   * the recipient's receiver hook (`onConfidentialTransferReceived`) in a single
-   * transaction. The caller crafts the opaque `data` payload — the SDK does not
-   * encode, validate, or interpret it.
+   * Get the expiration timestamp of a delegation for the given contract.
    *
-   * Balance validation follows the same rules as {@link Token.confidentialTransfer}.
+   * Signer-independent: works without a configured signer.
    *
-   * @param to - Recipient address. Must implement the ERC-7984 receiver hook.
-   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
-   * @param data - Opaque bytes forwarded to the recipient's receiver hook.
-   * @param options - Optional: `skipBalanceCheck` (default `false`).
-   * @returns The transaction hash and mined receipt.
+   * @param contractAddress - The confidential contract address.
+   * @param delegatorAddress - The address that granted the delegation.
+   * @param delegateAddress - The address that received delegation rights.
+   * @returns Unix timestamp as bigint. `0n` = no delegation. `2^64 - 1` = permanent.
+   */
+  getExpiry(params: {
+    contractAddress: Address;
+    delegatorAddress: Address;
+    delegateAddress: Address;
+  }): Promise<bigint>;
+  /**
+   * Get activity and expiry together in a single on-chain read, instead of
+   * calling {@link isActive} and {@link getExpiry} separately.
    *
-   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
-   * @throws if the balance is less than `amount`. {@link InsufficientConfidentialBalanceError}
-   * @throws if balance validation requires decryption that is not possible. {@link BalanceCheckUnavailableError}
-   * @throws if FHE encryption fails. {@link EncryptionFailedError}
-   * @throws if the on-chain transfer reverts. {@link TransactionRevertedError}
+   * Signer-independent: works without a configured signer.
    *
-   * @example
-   * ```ts
-   * const txHash = await token.confidentialTransferAndCall(
-   *   "0xRecipient",
-   *   1000n,
-   *   "0xabcd", // caller-encoded payload forwarded to the receiver hook
-   * );
-   * ```
+   * @param contractAddress - The confidential contract address.
+   * @param delegatorAddress - The address that granted the delegation.
+   * @param delegateAddress - The address that received delegation rights.
+   * @returns `{ isActive, expiryTimestamp }` — activity and the raw expiry timestamp together.
    */
-  confidentialTransferAndCall(to: Address, amount: bigint, data: Hex, options?: TransferOptions): Promise<TransactionResult>;
+  getStatus(params: {
+    contractAddress: Address;
+    delegatorAddress: Address;
+    delegateAddress: Address;
+  }): Promise<DelegationStatus>;
+}
+//#endregion
+//#region src/namespaces/permits.d.ts
+/**
+ * Public namespace for permit and transport-key-pair management.
+ *
+ * Exposed as `sdk.permits`. Owns the SDK-level guards (chain alignment, empty-array
+ * short-circuit, decrypt-cache invalidation) and delegates the actual work to the
+ * internal {@link CredentialService}.
+ *
+ * The namespace is named `permits` because the user-facing concept is the signed-permit
+ * store. The transport key pair is invisible plumbing — there is no `getTransportKeyPair()`
+ * surfaced; the key pair exists to sign permits and is created automatically when needed.
+ * {@link clear} wipes both the permit store and the transport key pair (permits
+ * cascade-delete with the key pair).
+ *
+ * When `transportKeyPairScope` is configured (opt-in shared-tenant scope for B2B2C/WaaS
+ * operators), {@link clear} and {@link revokePermits} stay signer-level only — they never
+ * touch the shared key pair. {@link revokeTransportKeyPair} is the distinct,
+ * operator-level operation for that.
+ */
+declare class Permits {
+  #private;
   /**
-   * ERC-7984 `confidentialTransferFromAndCall`: operator-initiated encrypted
-   * transfer that also invokes the recipient's receiver hook in a single
-   * transaction. The caller must be an approved operator for `from` and crafts
-   * the opaque `data` payload — the SDK does not encode or interpret it.
+   * Sign and store an EIP-712 permit authorising direct decryption for the
+   * given contract addresses.
    *
-   * @param from - The address to transfer from (caller must be an approved operator).
-   * @param to - Recipient address. Must implement the ERC-7984 receiver hook.
-   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
-   * @param data - Opaque bytes forwarded to the recipient's receiver hook.
-   * @param callbacks - Optional progress callbacks.
-   * @returns The transaction hash and mined receipt.
+   * Idempotent: if a permit covering the requested set already exists, no
+   * wallet prompt occurs. Otherwise the SDK chunks the uncovered subset into
+   * groups of ≤10 contracts and prompts once per chunk; partial mid-flight
+   * rejection is preserved (already-signed chunks are persisted before the
+   * next prompt).
    *
-   * @example
-   * ```ts
-   * const txHash = await token.confidentialTransferFromAndCall(
-   *   "0xFrom",
-   *   "0xRecipient",
-   *   500n,
-   *   "0xabcd",
-   * );
-   * ```
+   * @param contracts - Contract addresses to authorize.
    */
-  confidentialTransferFromAndCall(from: Address, to: Address, amount: bigint, data: Hex, callbacks?: TransferCallbacks): Promise<TransactionResult>;
+  grantPermit(contracts: Address[]): Promise<void>;
   /**
-   * Set operator approval for the confidential token.
-   * Defaults to 1 hour from now if `until` is not specified.
+   * Sign and store an EIP-712 delegation permit authorising decryption on
+   * behalf of `delegator`. Same idempotence/chunking semantics as {@link grantPermit}.
    *
-   * @param operator - The address to set as an operator.
-   * @param until - Optional Unix timestamp for approval expiry. Defaults to now + 1 hour.
-   * @returns The transaction hash and mined receipt.
+   * @param delegator - The address that delegated decryption rights to the connected signer.
+   * @param contracts - Contract addresses to authorize.
+   */
+  grantDelegationPermit(delegator: Address, contracts: Address[]): Promise<void>;
+  /**
+   * Pure store lookup: is there a permit covering `contracts`?
+   * No wallet prompt, no transport key pair generation. Returns `false` when no signer
+   * is configured.
+   */
+  hasPermit(contracts: Address[]): Promise<boolean>;
+  /**
+   * Pure store lookup for a delegation permit. See {@link hasPermit}.
+   *
+   * @param delegator - The address that delegated decryption rights to the connected signer.
+   * @param contracts - Contract addresses to check.
+   * @returns `true` if cached delegation permits cover all requested contracts.
+   */
+  hasDelegationPermit(delegator: Address, contracts: Address[]): Promise<boolean>;
+  /**
+   * Best-effort transport-key-pair prefetch for the connected signer.
+   *
+   * Optional latency optimization: decrypt and permit flows remain correct
+   * without it because they lazily create the transport key pair when needed.
+   *
+   * Silent no-op when no signer is configured or no wallet account is
+   * available. The transport key pair is generated through the relayer dispatcher's
+   * currently active chain — see {@link LifecycleService}, which calls
+   * `switchChain` before fanning the wallet-account change out to listeners,
+   * so any downstream caller (including React adapters) observes the
+   * dispatcher on the wallet chain by the time it invokes warmup.
    *
-   * @example
-   * ```ts
-   * const txHash = await token.setOperator("0xOperator");
-   * ```
+   * Not for pre-warming a shared `transportKeyPairScope`: this call's wallet-account
+   * precondition doesn't conceptually apply to a scope-wide key, and would silently
+   * no-op precisely when an operator is most likely to be calling it (no end-user
+   * connected yet). Use {@link warmTransportKeyPairScope} instead.
    */
-  setOperator(operator: Address, until?: number): Promise<TransactionResult>;
+  warmTransportKeyPair(): Promise<void>;
   /**
-   * Check if a spender is an approved operator for a given holder.
+   * Wipe FHE permits for the current signer.
    *
-   * @param holder - The token holder address.
-   * @param spender - The address to check operator approval for.
-   * @returns `true` if the spender is an approved operator for the holder.
+   * - With no argument: every permit referencing this signer is removed across
+   *   all chains and delegators. The transport key pair survives — use {@link clear} to
+   *   also wipe the transport key pair.
+   * - With a contract list: every signed permit in the direct-decrypt scope
+   *   (current chain) whose immutable payload touches any listed address is
+   *   removed. Delegation permits are not touched in this mode.
    *
-   * @example
-   * ```ts
-   * if (await token.isOperator("0xHolder", "0xSpender")) {
-   *   // spender can call transferFrom on behalf of holder
-   * }
-   * ```
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
    */
-  isOperator(holder: Address, spender: Address): Promise<boolean>;
+  revokePermits(contracts?: Address[]): Promise<void>;
   /**
-   * Read the on-chain encrypted balance for a given owner.
+   * Wipe the transport key pair for the current signer and cascade-delete every permit
+   * (across chains and delegators) referencing it.
    *
-   * @internal
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
    */
-  protected readConfidentialBalanceOf(owner: Address): Promise<EncryptedValue>;
+  clear(): Promise<void>;
   /**
-   * Pre-flight check: decrypt the confidential balance and compare against the
-   * requested amount. If credentials are cached the decrypt happens silently;
-   * if not, throws {@link BalanceCheckUnavailableError} instead of triggering
-   * a surprise EIP-712 popup.
+   * Revoke the shared transport key pair for `transportKeyPairScope` (operator-level
+   * action — no wallet account needs to be connected, but a signer must still be
+   * configured on this SDK instance at construction time).
+   *
+   * Deletes the shared key pair; every permit in the scope embeds its public key, so
+   * they're all treated as stale on next access. Signer-level {@link clear} never does
+   * this — it only ever wipes the calling signer's own permits.
+   *
+   * Not best-effort, unlike most credential-store writes: a storage failure rejects
+   * instead of being logged and swallowed. This is the primitive an operator reaches
+   * for on suspected key compromise — a resolved promise must mean the key pair is
+   * actually gone.
+   *
+   * Stops the SDK from reissuing or reusing the deleted key — does not revoke any
+   * permit already issued under it. A permit is a self-contained, bearer-style EIP-712
+   * signature the relayer accepts independently of this SDK; one exfiltrated alongside
+   * the key remains usable until its own `permitTTL` expiry regardless of this call.
    *
-   * @internal
+   * @param scopeId - Must match the configured `transportKeyPairScope`, as a guard
+   *   against revoking the wrong scope by mistake.
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @throws if no scope is configured, or `scopeId` doesn't match it. {@link ConfigurationError}
+   * @throws if the underlying storage delete fails.
    */
-  protected assertConfidentialBalance(amount: bigint): Promise<void>;
+  revokeTransportKeyPair(scopeId: string): Promise<void>;
   /**
-   * Emit a token-scoped event through the owning {@link ZamaSDK} so that
-   * subscribers see a unified stream.
+   * Warm the shared transport key pair for `transportKeyPairScope` (operator-level —
+   * no wallet account needs to be connected, but a signer must still be configured on
+   * this SDK instance at construction time) — the pre-warm counterpart to
+   * {@link revokeTransportKeyPair}. Prefer this over {@link warmTransportKeyPair} for a
+   * scoped key pair: unlike that method, this never silently no-ops for lack of a
+   * connected wallet, because a scope-wide key was never tied to one in the first place.
    *
-   * @internal
+   * @param scopeId - Must match the configured `transportKeyPairScope`, as a guard
+   *   against warming the wrong scope by mistake.
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @throws if no scope is configured, or `scopeId` doesn't match it. {@link ConfigurationError}
    */
-  protected emit(input: ZamaSDKEventInput): void;
+  warmTransportKeyPairScope(scopeId: string): Promise<void>;
+}
+//#endregion
+//#region src/token/token.d.ts
+/** Options for {@link Token.batchDecryptBalancesAs}. */
+interface BatchDecryptAsOptions {
+  /** The address of the account that delegated decryption rights. */
+  delegatorAddress: Address;
+  /** Pre-fetched encrypted values. When omitted, they are fetched from the chain. */
+  encryptedValues?: EncryptedValue[];
   /**
-   * Submit a token-scoped write transaction through the shared SDK transaction
-   * pipeline. Callers keep pre-flight and operation-specific work local.
+   * The account whose on-chain balance to read. Defaults to the delegator
+   * address, which is the common case (the delegator grants permission to
+   * decrypt their own balance). Only set this when the account differs
+   * from the delegator.
    *
-   * @internal
+   * Matches the `account` parameter of `confidentialBalanceOf(account)` on-chain.
    */
-  protected submitTransaction(params: {
-    operation: TransactionOperation;
-    config: WriteContractConfig;
-    onSubmitted?: (txHash: Hex) => void;
-  }): Promise<TransactionResult>;
-  /** Verify all tokens share the same SDK instance and return it. */
-  private static assertSameSdk;
+  accountAddress?: Address;
+  /** Maximum number of concurrent decrypt calls. Default: 10. */
+  maxConcurrency?: number;
+  /** Called when decryption fails for a single token. Return a fallback bigint. */
+  onError?: (error: Error, address: Address) => bigint;
+}
+/** Result of {@link Token.batchBalancesOf}. */
+interface BatchBalancesResult {
+  /** Successfully decrypted balances, keyed by token address. */
+  results: Map<Address, bigint>;
+  /** Per-token errors for tokens that failed to decrypt. */
+  errors: Map<Address, ZamaError>;
 }
-//#endregion
-//#region src/token/wrapped-token.d.ts
 /**
- * Confidential ERC-20 wrapper (ERC-7984 ERC20Wrapper).
+ * High-level interface for an ERC-7984 confidential token.
+ * Hides FHE complexity (encryption, decryption, EIP-712 signing) behind
+ * familiar ERC-20-like methods.
  *
- * Extends {@link Token} with wrapper-specific operations:
- * - `shield` / `unshield` — convert between the underlying ERC-20 and confidential balance
- * - `unwrap` / `unwrapAll` / `finalizeUnwrap` — low-level two-phase primitives
- * - `underlying` / `allowance` — wrapper reads
+ * For ERC-7984 wrappers (shield/unshield), use {@link WrappedToken} instead —
+ * it extends `Token` with wrapper-specific operations.
  *
- * `WrappedToken.address` is the wrapper contract address itself — the wrapper
- * IS the confidential token.
+ * Decryption, credentials, caching, and event emission are handled by the
+ * owning {@link ZamaSDK} — this class only exposes token-scoped helpers
+ * that delegate to `sdk.decryption.decryptValues` and `sdk.permits.grantPermit`.
  */
-declare class WrappedToken extends Token {
+declare class Token {
   #private;
+  /** The SDK instance this token operates through. */
+  readonly sdk: ZamaSDK;
+  /** Checksummed address of the confidential token contract. */
+  readonly address: Address;
+  constructor(sdk: ZamaSDK, address: Address);
+  /** Read the token name from the contract. */
+  name(): Promise<string>;
+  /** Read the token symbol from the contract. */
+  symbol(): Promise<string>;
+  /** Read the token decimals from the contract. */
+  decimals(): Promise<number>;
   /**
-   * Read the underlying ERC-20 token address from the wrapper contract.
-   *
-   * @returns The underlying ERC-20 token address.
-   */
-  underlying(): Promise<Address>;
-  /**
-   * Check whether the underlying ERC-20 supports ERC-1363 (payable token).
-   * Result is cached per WrappedToken instance (negative results included):
-   * once we know an underlying does not support ERC-1363, subsequent shields
-   * go straight to the `approve` + `wrap` path without re-probing.
-   */
-  isPayable(): Promise<boolean>;
-  /**
-   * Read the ERC-20 allowance granted by `owner` to this wrapper for the
-   * underlying token.
+   * ERC-165 check for {@link ERC7984_INTERFACE_ID} support.
    *
-   * @param owner - The owner address whose allowance to read.
-   * @returns The current allowance as a bigint.
+   * @returns `true` if the contract implements the ERC-7984 confidential token interface.
    */
-  allowance(owner: Address): Promise<bigint>;
+  isConfidential(): Promise<boolean>;
   /**
-   * Shield public ERC-20 tokens into confidential tokens.
-   *
-   * The execution path is decided automatically by ERC-165 introspection on
-   * the underlying ERC-20:
-   * - **`transferAndCall`** (single tx): when the underlying supports
-   *   ERC-1363, no approval is required — the wrapper's `onTransferReceived`
-   *   callback mints confidential tokens directly. `approvalStrategy` is
-   *   **ignored** on this path. See {@link ShieldPath}.
-   * - **`approveAndWrap`** (two-tx fallback): otherwise, an `approve` is
-   *   followed by a `wrap`. Approval is controlled by `approvalStrategy`
-   *   (`"exact"` by default, `"max"` for unlimited, `"skip"` to opt out).
-   *
-   * The ERC-20 balance is validated before submitting (public read, no
-   * signing required) so the call works for all wallet types, including
-   * smart wallets.
-   *
-   * @param amount - The plaintext amount to shield.
-   * @param options - Optional: `approvalStrategy`, `to`, callbacks.
-   * @returns The transaction hash and mined receipt.
-   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
-   * @throws if the ERC-20 balance is less than `amount`. {@link InsufficientERC20BalanceError}
-   * @throws if the ERC-20 approval or shield transaction reverts. {@link TransactionRevertedError}
+   * ERC-165 check for IERC7984ERC20Wrapper support.
    *
-   * @example
-   * ```ts
-   * const txHash = await wrappedToken.shield(1000n);
-   * ```
+   * @returns `true` if the contract implements the ERC-7984 wrapper interface
+   *   ({@link ERC7984_WRAPPER_INTERFACE_ID}, `0x1f1c62b2`).
    */
-  shield(amount: bigint, options?: ShieldOptions): Promise<TransactionResult>;
+  isWrapper(): Promise<boolean>;
   /**
-   * Wrap already-approved underlying ERC-20 into confidential tokens.
-   *
-   * Escape hatch for splitting shield across two signatures: call
-   * {@link approveUnderlying} first, then `wrap`. Most callers should use
-   * {@link shield}, which routes and orchestrates approval automatically.
-   *
-   * Validates the ERC-20 balance and the allowance granted to this wrapper
-   * (public reads, no signing) and fails early with a clear error.
+   * Decrypt and return the plaintext balance for the given owner.
+   * Acquires FHE credentials via a wallet signature if none are cached.
    *
-   * @param amount - The plaintext amount to wrap.
-   * @param options - Optional `to` recipient and `onWrapSubmitted` callback.
-   * @returns The transaction hash and mined receipt.
-   * @throws if reading the ERC-20 balance or allowance fails. {@link ERC20ReadFailedError}
-   * @throws if the ERC-20 balance is less than `amount`. {@link InsufficientERC20BalanceError}
-   * @throws if the allowance granted to the wrapper is less than `amount`. {@link InsufficientAllowanceError}
+   * @param owner - Balance owner address.
+   * @returns The decrypted plaintext balance as a bigint.
+   * @throws if FHE decryption fails. {@link DecryptionFailedError}
    *
    * @example
    * ```ts
-   * await wrappedToken.approveUnderlying(1000n);
-   * await wrappedToken.wrap(1000n);
+   * const balance = await token.balanceOf("0xOwner");
    * ```
    */
-  wrap(amount: bigint, options?: WrapOptions): Promise<TransactionResult>;
+  balanceOf(owner: Address): Promise<bigint>;
   /**
-   * Approve this 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).
+   * Return the raw encrypted balance without decrypting.
    *
-   * @param amount - Optional approval amount. Defaults to max uint256.
-   * @returns The transaction hash and mined receipt.
+   * @param owner - Balance owner address.
+   * @returns The encrypted balance as a hex string.
    *
    * @example
    * ```ts
-   * await wrappedToken.approveUnderlying(); // max approval
-   * await wrappedToken.approveUnderlying(1000n); // exact amount
+   * const encryptedValue = await token.confidentialBalanceOf("0xOwner");
    * ```
    */
-  approveUnderlying(amount?: bigint): Promise<TransactionResult>;
+  confidentialBalanceOf(owner: Address): Promise<EncryptedValue>;
   /**
-   * Unshield a specific amount and finalize in one call.
-   * Orchestrates: unshield → wait for receipt → parse event → finalize.
+   * Decrypt the balance of a delegator using delegated decryption credentials.
+   * The connected signer acts as the delegatee who has been granted permission
+   * by the delegator to decrypt their balance.
    *
-   * By default, the SDK validates the confidential balance before submitting.
-   * Set `skipBalanceCheck: true` to bypass this validation (e.g. for smart wallets).
+   * Clear values are cached in storage keyed by `(account, token, encryptedValue)`.
+   * Because every on-chain balance change produces a new encrypted value,
+   * stale cache entries are never served. Cache write failures are silently
+   * ignored — they do not affect the returned value.
    *
-   * @param amount - The plaintext amount to unshield.
-   * @param options - Optional: `skipBalanceCheck` (default `false`), callbacks.
-   * @returns The finalize transaction hash and mined receipt.
+   * @param delegatorAddress - The address of the account that delegated decryption rights.
+   * @param accountAddress - The account whose on-chain balance to read. Defaults
+   *   to the delegator address.
+   * @returns The decrypted plaintext balance as a bigint.
+   * @throws if no active delegation exists. {@link DelegationNotFoundError}
+   * @throws if the delegation has expired. {@link DelegationExpiredError}
+   * @throws if delegated decryption fails. {@link DecryptionFailedError}
    *
    * @example
    * ```ts
-   * const txHash = await wrappedToken.unshield(500n);
+   * const balance = await token.decryptBalanceAs({
+   *   delegatorAddress: "0xDelegator",
+   * });
    * ```
    */
-  unshield(amount: bigint, options?: UnshieldOptions): Promise<TransactionResult>;
+  decryptBalanceAs({ delegatorAddress, accountAddress }: {
+    delegatorAddress: Address;
+    accountAddress?: Address;
+  }): Promise<bigint>;
   /**
-   * Unshield the entire balance and finalize in one call.
-   * Orchestrates: unshieldAll → wait for receipt → parse event → finalize.
+   * Decrypt confidential balances for multiple tokens in parallel, returning
+   * successes and per-token errors separately. Pre-authorizes all token
+   * addresses in a single wallet signature, then delegates each decrypt to
+   * `sdk.decryption.decryptValues`.
+   *
+   * Tokens that fail to decrypt land in `errors` rather than aborting the
+   * whole batch — caller decides how to surface them.
    *
-   * @param callbacks - Optional progress callbacks for each phase.
-   * @returns The finalize transaction hash and mined receipt.
-   * @throws if the balance is zero. {@link DecryptionFailedError}
+   * @param tokens - Array of {@link Token} instances bound to the same SDK.
+   * @param owner - Balance owner address.
+   * @returns `{ results, errors }` partitioning the per-token outcomes.
    *
    * @example
    * ```ts
-   * const txHash = await wrappedToken.unshieldAll();
+   * const { results, errors } = await Token.batchBalancesOf(tokens, owner);
    * ```
    */
-  unshieldAll(callbacks?: UnshieldCallbacks): Promise<TransactionResult>;
+  static batchBalancesOf(tokens: Token[], owner: Address): Promise<BatchBalancesResult>;
   /**
-   * Resume an in-progress unshield from an existing unwrap tx hash.
-   * Useful when the user already submitted the unwrap but the finalize step
-   * was interrupted (e.g. page reload, network error).
+   * Batch decrypt confidential balances as a delegate across multiple tokens.
+   * Mirrors {@link batchBalancesOf} but uses delegated credentials.
    *
-   * @param unwrapTxHash - The transaction hash of the previously submitted unwrap.
-   * @param callbacks - Optional progress callbacks.
-   * @returns The finalize transaction hash and mined receipt.
+   * **Error handling:** If a per-token decryption fails and no `onError` callback
+   * is provided, errors are collected and thrown as an aggregated
+   * `DecryptionFailedError`. When the relayer returns no value for an encrypted value,
+   * a `DecryptionFailedError` is thrown for that token (never silently returns `0n`).
+   * Pass `onError: () => 0n` to opt into the silent zero behavior.
+   *
+   * @param tokens - Array of Token instances to decrypt balances for.
+   * @param options - Delegated decryption configuration.
+   * @returns A Map from token address to decrypted balance.
+   * @throws if no active delegation exists. {@link DelegationNotFoundError}
+   * @throws if the delegation has expired. {@link DelegationExpiredError}
+   * @throws if any decryption fails and no `onError` is provided. {@link DecryptionFailedError}
    *
    * @example
    * ```ts
-   * const txHash = await wrappedToken.resumeUnshield(previousUnwrapTxHash);
+   * const balances = await Token.batchDecryptBalancesAs(tokens, {
+   *   delegatorAddress: "0xDelegator",
+   *   onError: (err, addr) => { console.error(addr, err); return 0n; },
+   * });
    * ```
    */
-  resumeUnshield(unwrapTxHash: Hex, callbacks?: UnshieldCallbacks): Promise<TransactionResult>;
+  static batchDecryptBalancesAs(tokens: Token[], options: BatchDecryptAsOptions): Promise<Map<Address, bigint>>;
+  private static readBalanceHandlesBatch;
   /**
-   * Return the unwrap tx hash of an unshield that was interrupted between its
-   * two phases, or `null` if none is pending for this wrapper.
+   * Confidential transfer. Encrypts the amount via FHE, then calls the contract.
    *
-   * The SDK persists this automatically when {@link unshield}/{@link unshieldAll}
-   * submit phase 1, and clears it once phase 2 finalizes. Use the returned hash
-   * to surface a "resume" affordance, then pass it to {@link resumeUnshield}.
-   * Resuming is intentionally caller-driven — auto-resuming on load would fire a
-   * wallet transaction unprompted.
+   * By default, the SDK validates the confidential balance before submitting.
+   * If a cached plaintext balance exists it is used; otherwise, if credentials
+   * are cached, it decrypts on the fly. Set `skipBalanceCheck: true` to bypass
+   * this validation (e.g. for smart wallets).
    *
-   * @returns The pending unwrap tx hash, or `null`.
+   * @param to - Recipient address.
+   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
+   * @param options - Optional: `skipBalanceCheck` (default `false`).
+   * @returns The transaction hash and mined receipt.
+   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
+   * @throws if the balance is less than `amount`. {@link InsufficientConfidentialBalanceError}
+   * @throws if balance validation requires decryption that is not possible. {@link BalanceCheckUnavailableError}
+   * @throws if FHE encryption fails. {@link EncryptionFailedError}
+   * @throws if the on-chain transfer reverts. {@link TransactionRevertedError}
    *
    * @example
    * ```ts
-   * const unwrapTxHash = await wrappedToken.getPendingUnshield();
-   * if (unwrapTxHash) await wrappedToken.resumeUnshield(unwrapTxHash);
+   * const txHash = await token.confidentialTransfer("0xRecipient", 1000n);
    * ```
    */
-  getPendingUnshield(): Promise<Hex | null>;
+  confidentialTransfer(to: Address, amount: bigint, options?: TransferOptions): Promise<TransactionResult>;
   /**
-   * Request an unwrap for a specific amount. Encrypts the amount first.
-   * Pass the result's `unwrapRequestId` to {@link finalizeUnwrap} once the
-   * request is processed on-chain.
+   * Operator encrypted transfer on behalf of another address.
+   * The caller must be an approved operator for `from`.
    *
-   * @param amount - The plaintext amount to unwrap (encrypted automatically).
-   * @returns The tx hash, mined receipt, and the `unwrapRequestId` for `finalizeUnwrap`.
+   * @param from - The address to transfer from (caller must be an approved operator).
+   * @param to - Recipient address.
+   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
+   * @returns The transaction hash and mined receipt.
    *
    * @example
    * ```ts
-   * const result = await wrappedToken.unwrap(500n);
-   * await wrappedToken.finalizeUnwrap(result.unwrapRequestId);
+   * const txHash = await token.confidentialTransferFrom("0xFrom", "0xTo", 500n);
    * ```
    */
-  unwrap(amount: bigint): Promise<UnwrapResult>;
+  confidentialTransferFrom(from: Address, to: Address, amount: bigint, callbacks?: TransferCallbacks): Promise<TransactionResult>;
   /**
-   * Request an unwrap for the entire confidential balance.
-   * Uses the on-chain encrypted balance directly (no encryption needed).
-   * Throws if the balance is zero.
+   * ERC-7984 `confidentialTransferAndCall`: encrypted transfer that also invokes
+   * the recipient's receiver hook (`onConfidentialTransferReceived`) in a single
+   * transaction. The caller crafts the opaque `data` payload — the SDK does not
+   * encode, validate, or interpret it.
    *
-   * @returns The tx hash, mined receipt, and the `unwrapRequestId` for `finalizeUnwrap`.
-   * @throws if the balance is zero. {@link DecryptionFailedError}
+   * Balance validation follows the same rules as {@link Token.confidentialTransfer}.
+   *
+   * @param to - Recipient address. Must implement the ERC-7984 receiver hook.
+   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
+   * @param data - Opaque bytes forwarded to the recipient's receiver hook.
+   * @param options - Optional: `skipBalanceCheck` (default `false`).
+   * @returns The transaction hash and mined receipt.
+   *
+   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
+   * @throws if the balance is less than `amount`. {@link InsufficientConfidentialBalanceError}
+   * @throws if balance validation requires decryption that is not possible. {@link BalanceCheckUnavailableError}
+   * @throws if FHE encryption fails. {@link EncryptionFailedError}
+   * @throws if the on-chain transfer reverts. {@link TransactionRevertedError}
    *
    * @example
    * ```ts
-   * const result = await wrappedToken.unwrapAll();
-   * await wrappedToken.finalizeUnwrap(result.unwrapRequestId);
+   * const txHash = await token.confidentialTransferAndCall(
+   *   "0xRecipient",
+   *   1000n,
+   *   "0xabcd", // caller-encoded payload forwarded to the receiver hook
+   * );
    * ```
    */
-  unwrapAll(): Promise<UnwrapResult>;
+  confidentialTransferAndCall(to: Address, amount: bigint, data: Hex, options?: TransferOptions): Promise<TransactionResult>;
   /**
-   * Complete an unwrap by fetching the public decryption proof and finalizing.
-   * Call this once the unwrap request has been processed on-chain.
+   * ERC-7984 `confidentialTransferFromAndCall`: operator-initiated encrypted
+   * transfer that also invokes the recipient's receiver hook in a single
+   * transaction. The caller must be an approved operator for `from` and crafts
+   * the opaque `data` payload — the SDK does not encode or interpret it.
    *
-   * @param unwrapRequestId - The `unwrapRequestId` from an {@link UnwrapResult}
-   *   (`result.unwrapRequestId`) returned by {@link unwrap} / {@link unwrapAll},
-   *   or one decoded from an `UnwrapRequested` event (e.g. when finalizing
-   *   across sessions).
+   * @param from - The address to transfer from (caller must be an approved operator).
+   * @param to - Recipient address. Must implement the ERC-7984 receiver hook.
+   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
+   * @param data - Opaque bytes forwarded to the recipient's receiver hook.
+   * @param callbacks - Optional progress callbacks.
    * @returns The transaction hash and mined receipt.
    *
    * @example
    * ```ts
-   * const { unwrapRequestId } = await wrappedToken.unwrap(500n);
-   * await wrappedToken.finalizeUnwrap(unwrapRequestId);
+   * const txHash = await token.confidentialTransferFromAndCall(
+   *   "0xFrom",
+   *   "0xRecipient",
+   *   500n,
+   *   "0xabcd",
+   * );
    * ```
    */
-  finalizeUnwrap(unwrapRequestId: EncryptedValue): Promise<TransactionResult>;
-}
-//#endregion
-//#region src/query/confidential-balance.d.ts
-interface ConfidentialBalanceQueryConfig {
-  tokenAddress: Address;
-  account?: Address;
-  query?: Record<string, unknown>;
-}
-/** Query options for a single confidential token balance. Auto-gated on `account`. */
-declare function confidentialBalanceQueryOptions(token: Token, config: ConfidentialBalanceQueryConfig, signerContext?: SignerQueryContext): QueryFactoryOptions<bigint, Error, bigint, ReturnType<typeof zamaQueryKeys.confidentialBalance.owner>>;
-//#endregion
-//#region src/query/confidential-balances.d.ts
-interface ConfidentialBalancesQueryConfig {
-  account?: Address;
-  query?: Record<string, unknown>;
-}
-declare function confidentialBalancesQueryOptions(tokens: Token[], config?: ConfidentialBalancesQueryConfig, signerContext?: SignerQueryContext): QueryFactoryOptions<BatchBalancesResult, Error, BatchBalancesResult, ReturnType<typeof zamaQueryKeys.confidentialBalances.tokens>>;
-//#endregion
-//#region src/query/wrappers-registry.d.ts
-interface WrappersRegistryQueryConfig {
-  registryAddress: Address | undefined;
-  query?: Record<string, unknown>;
-}
-declare function tokenPairsQueryOptions(sdk: ZamaSDK, config: WrappersRegistryQueryConfig): QueryFactoryOptions<readonly TokenWrapperPair[], Error, readonly TokenWrapperPair[], ReturnType<typeof zamaQueryKeys.wrappersRegistry.tokenPairs>>;
-interface ConfidentialTokenAddressQueryConfig extends WrappersRegistryQueryConfig {
-  tokenAddress?: Address;
-}
-declare function confidentialTokenAddressQueryOptions(sdk: ZamaSDK, config: ConfidentialTokenAddressQueryConfig): QueryFactoryOptions<readonly [boolean, Address], Error, readonly [boolean, Address], ReturnType<typeof zamaQueryKeys.wrappersRegistry.confidentialTokenAddress>>;
-interface TokenAddressQueryConfig extends WrappersRegistryQueryConfig {
-  confidentialTokenAddress?: Address;
-}
-declare function tokenAddressQueryOptions(sdk: ZamaSDK, config: TokenAddressQueryConfig): QueryFactoryOptions<readonly [boolean, Address], Error, readonly [boolean, Address], ReturnType<typeof zamaQueryKeys.wrappersRegistry.tokenAddress>>;
-declare function tokenPairsLengthQueryOptions(sdk: ZamaSDK, config: WrappersRegistryQueryConfig): QueryFactoryOptions<bigint, Error, bigint, ReturnType<typeof zamaQueryKeys.wrappersRegistry.tokenPairsLength>>;
-interface TokenPairsSliceQueryConfig extends WrappersRegistryQueryConfig {
-  fromIndex?: bigint;
-  toIndex?: bigint;
-}
-declare function tokenPairsSliceQueryOptions(sdk: ZamaSDK, config: TokenPairsSliceQueryConfig): QueryFactoryOptions<readonly TokenWrapperPair[], Error, readonly TokenWrapperPair[], ReturnType<typeof zamaQueryKeys.wrappersRegistry.tokenPairsSlice>>;
-interface TokenPairQueryConfig extends WrappersRegistryQueryConfig {
-  index?: bigint;
-}
-declare function tokenPairQueryOptions(sdk: ZamaSDK, config: TokenPairQueryConfig): QueryFactoryOptions<TokenWrapperPair, Error, TokenWrapperPair, ReturnType<typeof zamaQueryKeys.wrappersRegistry.tokenPair>>;
-interface IsConfidentialTokenValidQueryConfig extends WrappersRegistryQueryConfig {
-  confidentialTokenAddress?: Address;
-}
-declare function isConfidentialTokenValidQueryOptions(sdk: ZamaSDK, config: IsConfidentialTokenValidQueryConfig): QueryFactoryOptions<boolean, Error, boolean, ReturnType<typeof zamaQueryKeys.wrappersRegistry.isConfidentialTokenValid>>;
-interface ListPairsQueryConfig {
-  /**
-   * The registry address for this chain — used as a query key discriminator.
-   * The registry instance already knows how to resolve the address for the
-   * current chain; this field just keeps the TanStack Query cache isolated
-   * per registry contract.
-   */
-  registryAddress: Address | undefined;
-  page?: number;
-  pageSize?: number;
-  metadata?: boolean;
-  query?: Record<string, unknown>;
-}
-/**
- * Query options for paginated listing of token wrapper pairs.
- *
- * Accepts a {@link WrappersRegistry} instance rather than a raw provider so that the
- * class-level TTL cache is shared across multiple `queryFn` executions. Pass
- * `sdk.registry` (the ZamaSDK lazy singleton) to ensure a single shared cache.
- */
-declare function listPairsQueryOptions(registry: WrappersRegistry, config: ListPairsQueryConfig): QueryFactoryOptions<PaginatedResult<TokenWrapperPair | TokenWrapperPairWithMetadata>, Error, PaginatedResult<TokenWrapperPair | TokenWrapperPairWithMetadata>, ReturnType<typeof zamaQueryKeys.wrappersRegistry.listPairs>>;
-//#endregion
-//#region src/query/shield.d.ts
-/** Variables for {@link shieldMutationOptions}. */
-interface ShieldParams extends ShieldOptions {
-  amount: bigint;
-}
-declare function shieldMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.shield", Address], ShieldParams, TransactionResult>;
-//#endregion
-//#region src/query/transfer.d.ts
-/** Variables for {@link confidentialTransferMutationOptions}. */
-interface ConfidentialTransferParams extends TransferOptions {
-  to: Address;
-  amount: bigint;
-}
-declare function confidentialTransferMutationOptions(token: Token): MutationFactoryOptions<readonly ["zama.confidentialTransfer", Address], ConfidentialTransferParams, TransactionResult>;
-//#endregion
-//#region src/query/transfer-and-call.d.ts
-/** Variables for {@link confidentialTransferAndCallMutationOptions}. */
-interface ConfidentialTransferAndCallParams extends TransferOptions {
-  to: Address;
-  amount: bigint;
-  /** Opaque bytes forwarded to the recipient's ERC-7984 receiver hook. */
-  data: Hex;
-}
-declare function confidentialTransferAndCallMutationOptions(token: Token): MutationFactoryOptions<readonly ["zama.confidentialTransferAndCall", Address], ConfidentialTransferAndCallParams, TransactionResult>;
-//#endregion
-//#region src/query/transfer-from.d.ts
-/** Variables for {@link confidentialTransferFromMutationOptions}. */
-interface ConfidentialTransferFromParams {
-  from: Address;
-  to: Address;
-  amount: bigint;
-  /** Optional progress callbacks for the multi-step transfer flow. */
-  callbacks?: TransferCallbacks;
-}
-declare function confidentialTransferFromMutationOptions(token: Token): MutationFactoryOptions<readonly ["zama.confidentialTransferFrom", Address], ConfidentialTransferFromParams, TransactionResult>;
-//#endregion
-//#region src/query/transfer-from-and-call.d.ts
-/** Variables for {@link confidentialTransferFromAndCallMutationOptions}. */
-interface ConfidentialTransferFromAndCallParams {
-  from: Address;
-  to: Address;
-  amount: bigint;
-  /** Opaque bytes forwarded to the recipient's ERC-7984 receiver hook. */
-  data: Hex;
-  /** Optional progress callbacks for the multi-step transfer flow. */
-  callbacks?: TransferCallbacks;
-}
-declare function confidentialTransferFromAndCallMutationOptions(token: Token): MutationFactoryOptions<readonly ["zama.confidentialTransferFromAndCall", Address], ConfidentialTransferFromAndCallParams, TransactionResult>;
-//#endregion
-//#region src/query/set-operator.d.ts
-/** Variables for {@link confidentialSetOperatorMutationOptions}. */
-interface ConfidentialSetOperatorParams {
-  operator: Address;
-  until?: number;
-}
-declare function confidentialSetOperatorMutationOptions(token: Token): MutationFactoryOptions<readonly ["zama.confidentialSetOperator", Address], ConfidentialSetOperatorParams, TransactionResult>;
-//#endregion
-//#region src/query/approve-underlying.d.ts
-/** Variables for {@link approveUnderlyingMutationOptions}. */
-interface ApproveUnderlyingParams {
-  amount?: bigint;
-}
-declare function approveUnderlyingMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.approveUnderlying", Address], ApproveUnderlyingParams, TransactionResult>;
-//#endregion
-//#region src/query/unshield.d.ts
-/** Variables for {@link unshieldMutationOptions}. */
-interface UnshieldParams extends UnshieldOptions {
-  amount: bigint;
-}
-declare function unshieldMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.unshield", Address], UnshieldParams, TransactionResult>;
-//#endregion
-//#region src/query/unshield-all.d.ts
-/** Variables for {@link unshieldAllMutationOptions}. */
-interface UnshieldAllParams extends UnshieldCallbacks {}
-declare function unshieldAllMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.unshieldAll", Address], UnshieldAllParams | void, TransactionResult>;
-//#endregion
-//#region src/query/resume-unshield.d.ts
-/** Variables for {@link resumeUnshieldMutationOptions}. */
-interface ResumeUnshieldParams extends UnshieldCallbacks {
-  unwrapTxHash: Hex;
-}
-declare function resumeUnshieldMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.resumeUnshield", Address], ResumeUnshieldParams, TransactionResult>;
-//#endregion
-//#region src/query/unwrap.d.ts
-/** Variables for {@link unwrapMutationOptions}. */
-interface UnwrapParams {
-  amount: bigint;
-}
-declare function unwrapMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.unwrap", Address], UnwrapParams, UnwrapResult>;
-//#endregion
-//#region src/query/wrap.d.ts
-/** Variables for {@link wrapMutationOptions}. */
-interface WrapParams extends WrapOptions {
-  amount: bigint;
-}
-declare function wrapMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.wrap", Address], WrapParams, TransactionResult>;
-//#endregion
-//#region src/query/unwrap-all.d.ts
-declare function unwrapAllMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.unwrapAll", Address], void, UnwrapResult>;
-//#endregion
-//#region src/query/finalize-unwrap.d.ts
-/** Variables for {@link finalizeUnwrapMutationOptions}. */
-type FinalizeUnwrapParams = {
-  /** Identifier from an `UnwrapRequested` event. */
-  unwrapRequestId: EncryptedValue;
-};
-declare function finalizeUnwrapMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.finalizeUnwrap", Address], FinalizeUnwrapParams, TransactionResult>;
-//#endregion
-//#region src/query/encrypt.d.ts
-declare function encryptMutationOptions(sdk: ZamaSDK): MutationFactoryOptions<readonly ["zama.encrypt"], EncryptParams, EncryptResult>;
-//#endregion
-//#region src/query/user-decrypt.d.ts
-interface EncryptedInput {
-  encryptedValue: EncryptedValue;
-  contractAddress: Address;
-}
-/** Decrypted clear values keyed by encrypted handle. */
-type DecryptResult = Readonly<Record<EncryptedValue, ClearValue>>;
-declare function decryptValuesQueryOptions(sdk: ZamaSDK, encryptedInputs: EncryptedInput[], signerContext?: SignerQueryContext): QueryFactoryOptions<DecryptResult, Error, DecryptResult, ReturnType<typeof zamaQueryKeys.decryption.encryptedInputs>>;
-//#endregion
-//#region src/query/delegated-decrypt.d.ts
-interface DelegatedDecryptValuesMutationParams {
-  encryptedInputs: EncryptedInput[];
-  delegatorAddress: Address;
-}
-declare function delegatedDecryptValuesMutationOptions(sdk: ZamaSDK): MutationFactoryOptions<readonly ["zama.delegatedDecryptValues"], DelegatedDecryptValuesMutationParams, Readonly<Record<EncryptedValue, ClearValue>>>;
-//#endregion
-//#region src/query/public-decrypt.d.ts
-declare function decryptPublicValuesMutationOptions(sdk: ZamaSDK): MutationFactoryOptions<readonly ["zama.decryptPublicValues"], EncryptedValue[], DecryptPublicValuesResult>;
-//#endregion
-//#region src/query/grant-permit.d.ts
-declare function grantPermitMutationOptions(sdk: ZamaSDK): MutationFactoryOptions<readonly ["zama.grantPermit"], Address[], void>;
-//#endregion
-//#region src/query/has-permit.d.ts
-interface HasPermitQueryConfig {
-  /** Contract addresses to check credentials against. */
-  contractAddresses: Address[];
-  /**
-   * Standard TanStack query options. `hasPermit` intentionally overrides cache
-   * timing because permit state is wallet-local, not server state: every fetch
-   * should read the SDK credential service directly.
-   */
-  query?: Record<string, unknown>;
-}
-declare function hasPermitQueryOptions(sdk: ZamaSDK, config: HasPermitQueryConfig, signerContext?: SignerQueryContext): QueryFactoryOptions<boolean, Error, boolean, ReturnType<typeof zamaQueryKeys.hasPermit.scope>>;
-//#endregion
-//#region src/query/revoke-permits.d.ts
-/** TanStack Query mutation factory for {@link Permits.revokePermits}. */
-declare function revokePermitsMutationOptions(sdk: ZamaSDK): MutationFactoryOptions<readonly ["zama.revokePermits"], Address[] | void, void>;
-//#endregion
-//#region src/query/clear-credentials.d.ts
-/** TanStack Query mutation factory for {@link Permits.clear}. */
-declare function clearCredentialsMutationOptions(sdk: ZamaSDK): MutationFactoryOptions<readonly ["zama.clearCredentials"], void, void>;
-//#endregion
-//#region src/query/delegate-decryption.d.ts
-/** Variables for {@link delegateDecryptionMutationOptions}. */
-interface DelegateDecryptionParams {
-  delegateAddress: Address;
-  expirationDate?: Date;
-}
-declare function delegateDecryptionMutationOptions(sdk: ZamaSDK, contractAddress: Address): MutationFactoryOptions<readonly ["zama.delegateDecryption", Address], DelegateDecryptionParams, TransactionResult>;
-//#endregion
-//#region src/query/decrypt-balance-as.d.ts
-/** Variables for {@link decryptBalanceAsMutationOptions}. */
-interface DecryptBalanceAsParams {
-  delegatorAddress: Address;
-  accountAddress?: Address;
-}
-declare function decryptBalanceAsMutationOptions(token: Token): MutationFactoryOptions<readonly ["zama.decryptBalanceAs", Address], DecryptBalanceAsParams, bigint>;
-//#endregion
-//#region src/query/batch-decrypt-balances-as.d.ts
-/** Variables for {@link batchDecryptBalancesAsMutationOptions}. */
-type BatchDecryptBalancesAsParams = BatchDecryptAsOptions;
-declare function batchDecryptBalancesAsMutationOptions(tokens: Token[]): MutationFactoryOptions<readonly ["zama.batchDecryptBalancesAs", ...Address[]], BatchDecryptBalancesAsParams, Map<Address, bigint>>;
-//#endregion
-//#region src/query/revoke-delegation.d.ts
-/** Variables for {@link revokeDelegationMutationOptions}. */
-interface RevokeDelegationParams {
-  delegateAddress: Address;
-}
-declare function revokeDelegationMutationOptions(sdk: ZamaSDK, contractAddress: Address): MutationFactoryOptions<readonly ["zama.revokeDelegation", Address], RevokeDelegationParams, TransactionResult>;
-//#endregion
-//#region src/services/delegation-service.d.ts
-/** Delegation activity and expiry, resolved from a single expiry read. */
-interface DelegationStatus {
-  isActive: boolean;
-  expiryTimestamp: bigint;
-}
-declare class DelegationService {
-  #private;
-  constructor({ provider, router, emitEvent, logger }: {
-    provider: GenericProvider;
-    router: ChainRouter;
-    logger: GenericLogger;
-    emitEvent?: (input: ZamaSDKEventInput, tokenAddress?: Address) => void;
-  });
-  delegateDecryption(signer: GenericSigner, { contractAddress, delegateAddress, delegatorAddress, expirationDate }: {
-    contractAddress: Address;
-    delegateAddress: Address;
-    delegatorAddress: Address;
-    expirationDate?: Date;
-  }): Promise<TransactionResult>;
-  revokeDelegation(signer: GenericSigner, { contractAddress, delegateAddress, delegatorAddress }: {
-    contractAddress: Address;
-    delegateAddress: Address;
-    delegatorAddress: Address;
-  }): Promise<TransactionResult>;
-  isDelegated(params: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<boolean>;
+  confidentialTransferFromAndCall(from: Address, to: Address, amount: bigint, data: Hex, callbacks?: TransferCallbacks): Promise<TransactionResult>;
   /**
-   * Resolve activity and expiry together from a single {@link getDelegationExpiry} read,
-   * instead of two separate round trips through {@link isDelegated} and
-   * {@link getDelegationExpiry}.
-   */
-  getStatus(params: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<DelegationStatus>;
-  getDelegationExpiry({ contractAddress, delegatorAddress, delegateAddress }: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<bigint>;
-  findInactiveDelegations(contractAddresses: readonly Address[], delegatorAddress: Address, delegateAddress: Address): Promise<Map<Address, DelegationNotFoundError | DelegationExpiredError>>;
-  assertDelegationActive(contractAddress: Address, delegatorAddress: Address, delegateAddress: Address): Promise<void>;
-}
-//#endregion
-//#region src/query/delegation-status.d.ts
-interface DelegationStatusQueryConfig {
-  contractAddress: Address | undefined;
-  delegatorAddress?: Address;
-  delegateAddress?: Address;
-  query?: Record<string, unknown>;
-}
-declare function delegationStatusQueryOptions(sdk: ZamaSDK, config: DelegationStatusQueryConfig): QueryFactoryOptions<DelegationStatus, Error, DelegationStatus, ReturnType<typeof zamaQueryKeys.delegationStatus.scope>>;
-//#endregion
-//#region src/credentials/credential-service.d.ts
-/** Configuration for {@link CredentialService}. TTLs are pre-validated by the caller. */
-interface CredentialServiceConfig {
-  router: ChainRouter;
-  signer: GenericSigner;
-  /** Transport key pair lifetime in seconds. Pre-validated. */
-  transportKeyPairTTL: number;
-  /** Permit lifetime in days. Pre-validated. */
-  permitTTL: number;
-  /** Backing storage for transport key pairs (and permits if `permitStorage` is omitted). */
-  storage: GenericStorage;
-  /** Optional dedicated storage for permits; defaults to `storage`. */
-  permitStorage?: GenericStorage;
-  /** SDK-wide logger for credential-path diagnostics. */
-  logger: GenericLogger;
+   * Set operator approval for the confidential token.
+   * Defaults to 1 hour from now if `until` is not specified.
+   *
+   * @param operator - The address to set as an operator.
+   * @param until - Optional Unix timestamp for approval expiry. Defaults to now + 1 hour.
+   * @returns The transaction hash and mined receipt.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.setOperator("0xOperator");
+   * ```
+   */
+  setOperator(operator: Address, until?: number): Promise<TransactionResult>;
   /**
-   * Opt-in shared-tenant scope (B2B2C/WaaS operators). When set, every signer
-   * configured with the same scope shares one transport key pair instead of one
-   * per signer address. Permits stay per-signer regardless — see
-   * {@link revokeTransportKeyPair} for the operator-level counterpart to
-   * signer-level revocation.
+   * Check if a spender is an approved operator for a given holder.
+   *
+   * @param holder - The token holder address.
+   * @param spender - The address to check operator approval for.
+   * @returns `true` if the spender is an approved operator for the holder.
+   *
+   * @example
+   * ```ts
+   * if (await token.isOperator("0xHolder", "0xSpender")) {
+   *   // spender can call transferFrom on behalf of holder
+   * }
+   * ```
    */
-  scope?: string;
+  isOperator(holder: Address, spender: Address): Promise<boolean>;
+  /** Verify all tokens share the same SDK instance and return it. */
+  private static assertSameSdk;
 }
+//#endregion
+//#region src/token/wrapped-token.d.ts
 /**
- * Single facade coordinating the keypair vault and the permission store.
+ * Confidential ERC-20 wrapper (ERC-7984 ERC20Wrapper).
  *
- * `CredentialService` is the only credentials object held by `ZamaSDK`. It accepts identity
- * transitions via `handleWalletAccountChange`.
+ * Extends {@link Token} with wrapper-specific operations:
+ * - `shield` / `unshield` — convert between the underlying ERC-20 and confidential balance
+ * - `unwrap` / `unwrapAll` / `finalizeUnwrap` — low-level two-phase primitives
+ * - `underlying` / `allowance` — wrapper reads
  *
- * Two distinct revocation tiers exist and must not be conflated: {@link clearCredentials}
- * (signer-level, e.g. an end-user "disconnect") only ever removes that signer's own
- * key-pair slot and permits — when a scope is configured, the shared key pair was never
- * stored there, so it's untouched. {@link revokeTransportKeyPair} (operator-level) is
- * the only way to invalidate a scope's shared key pair, and it does so for every signer
- * in the scope at once.
+ * `WrappedToken.address` is the wrapper contract address itself — the wrapper
+ * IS the confidential token.
  */
-declare class CredentialService {
+declare class WrappedToken extends Token {
   #private;
-  constructor(config: CredentialServiceConfig);
   /**
-   * Resolve a keypair and permissions covering `contracts`, minimizing wallet
-   * prompts by reusing or widening existing permits where possible. Empty
-   * `contracts` warms the keypair without prompting.
+   * Read the underlying ERC-20 token address from the wrapper contract.
    *
-   * @returns The resolved keypair and permits covering the requested contracts.
-   * @throws if the user rejects a wallet signature prompt. {@link SigningRejectedError}
-   * @throws if signing fails for any other reason. {@link SigningFailedError}
+   * @returns The underlying ERC-20 token address.
    */
-  grantPermit(contracts: readonly Address[], delegator?: Address): Promise<SerializedTransportKeyPairWithPermissions>;
+  underlying(): Promise<Address>;
   /**
-   * Pure store lookup: are stored permits sufficient to cover `contracts`? No wallet prompt.
-   *
-   * @returns `true` if cached permits cover all requested contracts (vacuously
-   *   true for an empty list); `false` if no keypair exists or coverage is
-   *   incomplete.
+   * Check whether the underlying ERC-20 supports ERC-1363 (payable token).
+   * Result is cached per WrappedToken instance (negative results included):
+   * once we know an underlying does not support ERC-1363, subsequent shields
+   * go straight to the `approve` + `wrap` path without re-probing.
    */
-  hasPermit(contracts: readonly Address[], delegator?: Address): Promise<boolean>;
+  isPayable(): Promise<boolean>;
   /**
-   * Wipe FHE permits for the current signer.
-   *
-   * - With no argument: every permit referencing this signer is removed across
-   *   all chains and delegators. The keypair survives — use
-   *   {@link clearCredentials} to also wipe the keypair.
-   * - With a contract list: every signed permit in the direct-decrypt scope
-   *   (current chain) whose immutable payload touches any listed address is
-   *   removed. Delegated permits are not touched in this mode.
+   * Read the ERC-20 allowance granted by `owner` to this wrapper for the
+   * underlying token.
    *
-   * @throws if reading the signer address fails. {@link SigningFailedError}
+   * @param owner - The owner address whose allowance to read.
+   * @returns The current allowance as a bigint.
    */
-  revokePermits(contracts?: readonly Address[]): Promise<void>;
+  allowance(owner: Address): Promise<bigint>;
   /**
-   * Wipe the keypair for the current signer and cascade-delete every
-   * permission referencing it across all chains and delegators.
+   * Shield public ERC-20 tokens into confidential tokens.
+   *
+   * The execution path is decided automatically by ERC-165 introspection on
+   * the underlying ERC-20:
+   * - **`transferAndCall`** (single tx): when the underlying supports
+   *   ERC-1363, no approval is required — the wrapper's `onTransferReceived`
+   *   callback mints confidential tokens directly. `approvalStrategy` is
+   *   **ignored** on this path. See {@link ShieldPath}.
+   * - **`approveAndWrap`** (two-tx fallback): otherwise, an `approve` is
+   *   followed by a `wrap`. Approval is controlled by `approvalStrategy`
+   *   (`"exact"` by default, `"max"` for unlimited, `"skip"` to opt out).
+   *
+   * The ERC-20 balance is validated before submitting (public read, no
+   * signing required) so the call works for all wallet types, including
+   * smart wallets.
    *
-   * Signer-level only: when a scope is configured, the shared key pair was never
-   * stored under this signer's own slot, so it survives untouched — only this
-   * signer's permits are removed. Use {@link revokeTransportKeyPair} to invalidate
-   * the shared key pair itself.
+   * @param amount - The plaintext amount to shield.
+   * @param options - Optional: `approvalStrategy`, `to`, callbacks.
+   * @returns The transaction hash and mined receipt.
+   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
+   * @throws if the ERC-20 balance is less than `amount`. {@link InsufficientERC20BalanceError}
+   * @throws if the ERC-20 approval or shield transaction reverts. {@link TransactionRevertedError}
    *
-   * @throws if reading the signer address fails. {@link SigningFailedError}
+   * @example
+   * ```ts
+   * const txHash = await wrappedToken.shield(1000n);
+   * ```
    */
-  clearCredentials(): Promise<void>;
+  shield(amount: bigint, options?: ShieldOptions): Promise<TransactionResult>;
   /**
-   * Revoke this scope's shared transport key pair (operator-level action).
+   * Wrap already-approved underlying ERC-20 into confidential tokens.
    *
-   * Deletes the shared key pair. Every permit signed under it embeds the old
-   * public key, so `listUsableAndPrune` treats them all as stale on next access —
-   * no permit is touched directly, and no connected wallet is required. This is
-   * the only operation that can invalidate a shared key pair; signer-level
-   * {@link clearCredentials} never does.
+   * Escape hatch for splitting shield across two signatures: call
+   * {@link approveUnderlying} first, then `wrap`. Most callers should use
+   * {@link shield}, which routes and orchestrates approval automatically.
    *
-   * Not best-effort: unlike {@link clearCredentials}, a storage failure here rejects
-   * instead of being logged and swallowed — see {@link TransportKeyPairVault.clearScope}.
+   * Validates the ERC-20 balance and the allowance granted to this wrapper
+   * (public reads, no signing) and fails early with a clear error.
    *
-   * Only stops the SDK from reissuing or reusing the deleted key going forward — does
-   * not revoke any permit already issued under it. A permit is a self-contained,
-   * bearer-style EIP-712 signature the relayer accepts independently of this SDK's
-   * storage; one already exfiltrated alongside the key remains usable until its own
-   * `permitTTL` expiry regardless of this call.
+   * @param amount - The plaintext amount to wrap.
+   * @param options - Optional `to` recipient and `onWrapSubmitted` callback.
+   * @returns The transaction hash and mined receipt.
+   * @throws if reading the ERC-20 balance or allowance fails. {@link ERC20ReadFailedError}
+   * @throws if the ERC-20 balance is less than `amount`. {@link InsufficientERC20BalanceError}
+   * @throws if the allowance granted to the wrapper is less than `amount`. {@link InsufficientAllowanceError}
    *
-   * @param scopeId - Must match the scope this service was configured with. Requiring
-   *   the caller to name it guards against revoking the wrong scope by mistake.
-   * @throws if no scope is configured, or `scopeId` doesn't match it. {@link ConfigurationError}
-   * @throws if the underlying storage delete fails.
+   * @example
+   * ```ts
+   * await wrappedToken.approveUnderlying(1000n);
+   * await wrappedToken.wrap(1000n);
+   * ```
    */
-  revokeTransportKeyPair(scopeId: string): Promise<void>;
+  wrap(amount: bigint, options?: WrapOptions): Promise<TransactionResult>;
   /**
-   * Warm the signer transport key pair cache for a known address.
+   * Approve this 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).
    *
-   * Best-effort prefetch primitive: correctness still comes from `grantPermit`,
-   * which lazily creates the transport key pair when needed. Errors (storage failure,
-   * relayer 4xx, missing Worker in SSR) are **not** swallowed here — the caller
-   * decides whether to log, ignore, or surface them.
+   * @param amount - Optional approval amount. Defaults to max uint256.
+   * @returns The transaction hash and mined receipt.
    *
-   * Not for pre-warming a shared scope: `address` is ignored for storage keying once
-   * a scope is configured (see {@link TransportKeyPairVault}), so this call's actual
-   * effect wouldn't match its apparent per-signer intent. Use
-   * {@link warmTransportKeyPairScope} instead.
+   * @example
+   * ```ts
+   * await wrappedToken.approveUnderlying(); // max approval
+   * await wrappedToken.approveUnderlying(1000n); // exact amount
+   * ```
    */
-  warmTransportKeyPair(address: Address): Promise<void>;
+  approveUnderlying(amount?: bigint): Promise<TransactionResult>;
   /**
-   * Warm this scope's shared transport key pair (operator-level, no wallet needed) —
-   * the pre-warm counterpart to {@link revokeTransportKeyPair}.
+   * Unshield a specific amount and finalize in one call.
+   * Orchestrates: unshield → wait for receipt → parse event → finalize.
    *
-   * @param scopeId - Must match the scope this service was configured with. Requiring
-   *   the caller to name it guards against warming the wrong scope by mistake.
-   * @throws if no scope is configured, or `scopeId` doesn't match it. {@link ConfigurationError}
+   * By default, the SDK validates the confidential balance before submitting.
+   * Set `skipBalanceCheck: true` to bypass this validation (e.g. for smart wallets).
+   *
+   * @param amount - The plaintext amount to unshield.
+   * @param options - Optional: `skipBalanceCheck` (default `false`), callbacks.
+   * @returns The finalize transaction hash and mined receipt.
+   *
+   * @example
+   * ```ts
+   * const txHash = await wrappedToken.unshield(500n);
+   * ```
    */
-  warmTransportKeyPairScope(scopeId: string): Promise<void>;
+  unshield(amount: bigint, options?: UnshieldOptions): Promise<TransactionResult>;
   /**
-   * Apply a wallet account transition.
+   * Unshield the entire balance and finalize in one call.
+   * Orchestrates: unshieldAll → wait for receipt → parse event → finalize.
    *
-   * Address change clears persisted credentials for the previous account.
-   * Chain-only changes keep credentials intact because permits are chain-scoped
-   * already and stale decrypt plaintext is cleared by `ZamaSDK`.
+   * @param callbacks - Optional progress callbacks for each phase.
+   * @returns The finalize transaction hash and mined receipt.
+   * @throws if the balance is zero. {@link DecryptionFailedError}
+   *
+   * @example
+   * ```ts
+   * const txHash = await wrappedToken.unshieldAll();
+   * ```
    */
-  handleWalletAccountChange(prev?: {
-    address: Address;
-  }, next?: {
-    address: Address;
-  }): Promise<void>;
-}
-//#endregion
-//#region src/services/caching-service.d.ts
-/**
- * Storage-backed cache for decrypted FHE plaintext values.
- *
- * Each entry is keyed by `(requester, contractAddress, handle)` so different
- * signers cannot read each other's cached decryptions.
- */
-declare class CachingService {
-  #private;
-  constructor(storage: GenericStorage, logger: GenericLogger);
-  get(requester: Address, contractAddress: Address, encryptedValue: EncryptedValue): Promise<ClearValue | null>;
-  set(requester: Address, contractAddress: Address, encryptedValue: EncryptedValue, value: ClearValue): Promise<void>;
-  delete(requester: Address, contractAddress: Address, encryptedValue: EncryptedValue): Promise<void>;
-  clearForRequester(requester: Address): Promise<void>;
-  clearAll(): Promise<void>;
-}
-//#endregion
-//#region src/services/decryption-service.d.ts
-/** Options shared by the delegated-decrypt entry points. */
-interface DelegatedDecryptOptions {
+  unshieldAll(callbacks?: UnshieldCallbacks): Promise<TransactionResult>;
   /**
-   * Ride out the gateway propagation window: when a just-granted delegation
-   * has not yet synced, the delegated decrypt is retried (bounded, ~30s) until
-   * it lands instead of throwing {@link DelegationNotPropagatedError}. Defaults
-   * to `true`. Pass `false` to fail fast on the first not-propagated response.
+   * Resume an in-progress unshield from an existing unwrap tx hash.
+   * Useful when the user already submitted the unwrap but the finalize step
+   * was interrupted (e.g. page reload, network error).
+   *
+   * @param unwrapTxHash - The transaction hash of the previously submitted unwrap.
+   * @param callbacks - Optional progress callbacks.
+   * @returns The finalize transaction hash and mined receipt.
+   *
+   * @example
+   * ```ts
+   * const txHash = await wrappedToken.resumeUnshield(previousUnwrapTxHash);
+   * ```
    */
-  waitForPropagation?: boolean;
-}
-interface BatchDecryptItem {
-  encryptedValue: EncryptedValue;
-  contractAddress: Address;
-  value?: ClearValue;
-  error?: ZamaError;
-}
-interface BatchDecryptResult {
-  items: BatchDecryptItem[];
-}
-declare class DecryptionService {
-  #private;
-  constructor({ cache, credentialService, delegationService, router, emitEvent }: {
-    cache: CachingService;
-    credentialService: CredentialService;
-    delegationService: DelegationService;
-    router: ChainRouter;
-    emitEvent: (input: ZamaSDKEventInput) => void;
-  });
-  decryptValues(handles: EncryptedInput[], signerAddress: Address, opts?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<Record<EncryptedValue, ClearValue>>;
-  delegatedDecryptValues(encryptedInputs: EncryptedInput[], delegatorAddress: Address, delegateAddress: Address, accountAddress: Address, opts?: DelegatedDecryptOptions): Promise<Record<EncryptedValue, ClearValue>>;
-  delegatedBatchDecryptHandlesAs({ encryptedInputs, delegatorAddress, delegateAddress, accountAddress, maxConcurrency, waitForPropagation }: {
-    encryptedInputs: EncryptedInput[];
-    delegatorAddress: Address;
-    delegateAddress: Address;
-    accountAddress: Address;
-    maxConcurrency?: number;
-    waitForPropagation?: boolean;
-  }): Promise<BatchDecryptResult>;
-}
-//#endregion
-//#region src/namespaces/decryption.d.ts
-/**
- * Public namespace for FHE decryption — the canonical way to decrypt.
- *
- * Exposed as `sdk.decryption`. Prefer these methods over the low-level
- * `sdk.relayer.decryptValues` / `decryptPublicValues`: they
- * assemble the credential bundle (transport key pair, EIP-712 permit) for you,
- * cache results, and wrap relayer errors. Reach for `sdk.relayer.*` only when
- * you must control credential assembly by hand.
- *
- * Owns the SDK-level guards (signer requirement on
- * `decryptValues` and `delegatedDecryptValues`, empty-array
- * short-circuit on `decryptPublicValues`, relayer error wrapping) and delegates the
- * actual work to the internal {@link DecryptionService} or the relayer directly for
- * `decryptPublicValues`.
- *
- * **Mixed signer requirement:** `decryptValues` and
- * `delegatedDecryptValues` need a configured signer; `decryptPublicValues`
- * does not. Each method documents its requirement in its JSDoc.
- *
- * **Request chunking:** decrypt requests are split internally to stay under
- * the relayer's 2048-cleartext-bit per-request budget — callers never need to
- * size batches themselves.
- */
-declare class Decryption {
-  #private;
-  /** @internal */
-  constructor(opts: {
-    signer: GenericSigner | undefined;
-    provider: GenericProvider;
-    router: ChainRouter;
-    decryptionService: DecryptionService | undefined;
-  });
+  resumeUnshield(unwrapTxHash: Hex, callbacks?: UnshieldCallbacks): Promise<TransactionResult>;
   /**
-   * Decrypt one or more FHE encrypted values. Results are cached — repeated calls
-   * for the same encrypted value skip the relayer round-trip.
+   * Return the unwrap tx hash of an unshield that was interrupted between its
+   * two phases, or `null` if none is pending for this wrapper.
    *
-   * Zero encrypted values are mapped to `0n` without hitting the relayer.
-   * Events (`DecryptStart/End/Error`) are emitted uniformly.
-   * Relayer errors are wrapped into typed SDK errors.
+   * The SDK persists this automatically when {@link unshield}/{@link unshieldAll}
+   * submit phase 1, and clears it once phase 2 finalizes. Use the returned hash
+   * to surface a "resume" affordance, then pass it to {@link resumeUnshield}.
+   * Resuming is intentionally caller-driven — auto-resuming on load would fire a
+   * wallet transaction unprompted.
    *
-   * @param encryptedInput - Encrypted values to decrypt, each paired with its contract address.
-   * @param options - Per-call `signal` and `timeout` forwarded to the relayer round-trip.
-   * @returns A record mapping each encrypted value to its decrypted clear-text value.
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
-   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
+   * @returns The pending unwrap tx hash, or `null`.
    *
    * @example
    * ```ts
-   * const values = await sdk.decryption.decryptValues([
-   *   { encryptedValue: balance, contractAddress: cUSDT },
-   * ]);
-   * console.log(values[balance]); // 1000n
+   * const unwrapTxHash = await wrappedToken.getPendingUnshield();
+   * if (unwrapTxHash) await wrappedToken.resumeUnshield(unwrapTxHash);
    * ```
    */
-  decryptValues(encryptedInput: EncryptedInput[], options?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<Record<EncryptedValue, ClearValue>>;
+  getPendingUnshield(): Promise<Hex | null>;
   /**
-   * Decrypt one or more FHE encrypted values using delegated credentials.
-   *
-   * Mirrors {@link decryptValues} with delegated credentials — same caching and
-   * zero-value short-circuit. Before reading from cache or calling the relayer,
-   * every non-zero encrypted value's contract must have an active delegation from the
-   * delegator to the connected signer; missing or expired delegations fail fast.
-   *
-   * @param encryptedInputs - FHE encrypted values paired with their contract addresses.
-   * @param delegatorAddress - The address that granted delegation rights.
-   * @param accountAddress - Address used as the cache key's "requester"
-   *   dimension. Defaults to `delegatorAddress`. Pass the actual account address
-   *   when decrypting on behalf of someone whose balance is stored under a
-   *   different address (e.g. `decryptBalanceAs` with an explicit `accountAddress`).
-   * @param options - Delegated-decrypt options. By default the call rides out the
-   *   gateway propagation window ({@link DelegatedDecryptOptions.waitForPropagation});
-   *   pass `{ waitForPropagation: false }` to fail fast instead.
-   * @returns Map of encrypted value → clear-text value.
+   * Request an unwrap for a specific amount. Encrypts the amount first.
+   * Pass the result's `unwrapRequestId` to {@link finalizeUnwrap} once the
+   * request is processed on-chain.
+   *
+   * @param amount - The plaintext amount to unwrap (encrypted automatically).
+   * @returns The tx hash, mined receipt, and the `unwrapRequestId` for `finalizeUnwrap`.
    *
    * @example
    * ```ts
-   * const values = await sdk.decryption.delegatedDecryptValues([
-   *   { encryptedValue: balance, contractAddress: tokenAddr },
-   * ], delegatorAddr);
-   * console.log(values[balance]); // 1000n
+   * const result = await wrappedToken.unwrap(500n);
+   * await wrappedToken.finalizeUnwrap(result.unwrapRequestId);
    * ```
    */
-  delegatedDecryptValues(encryptedInputs: EncryptedInput[], delegatorAddress: Address, accountAddress?: Address, options?: DelegatedDecryptOptions): Promise<Record<EncryptedValue, ClearValue>>;
+  unwrap(amount: bigint): Promise<UnwrapResult>;
   /**
-   * Publicly decrypt one or more FHE encrypted values.
-   *
-   * Signer-independent: works without a configured signer.
-   * Returns the decryption proof alongside the clear-text values so callers
-   * can submit on-chain finalization transactions (e.g. `finalizeUnwrap`).
+   * Request an unwrap for the entire confidential balance.
+   * Uses the on-chain encrypted balance directly (no encryption needed).
+   * Throws if the balance is zero.
    *
-   * @param encryptedValues - FHE encrypted values to decrypt publicly.
-   * @param options - Per-call `signal` and `timeout` forwarded to the relayer round-trip.
-   * @returns Clear-text values, ABI-encoded values, and the decryption proof.
+   * @returns The tx hash, mined receipt, and the `unwrapRequestId` for `finalizeUnwrap`.
+   * @throws if the balance is zero. {@link DecryptionFailedError}
    *
    * @example
    * ```ts
-   * const { clearValues, decryptionProof, abiEncodedClearValues } =
-   *   await sdk.decryption.decryptPublicValues([encryptedValue]);
+   * const result = await wrappedToken.unwrapAll();
+   * await wrappedToken.finalizeUnwrap(result.unwrapRequestId);
    * ```
    */
-  decryptPublicValues(encryptedValues: EncryptedValue[], options?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<DecryptPublicValuesResult>;
+  unwrapAll(): Promise<UnwrapResult>;
   /**
-   * Batch-decrypt delegated encrypted values with per-entry error isolation.
-   *
-   * Attempts a single batch request first. If the batch fails with a non-fatal
-   * error (e.g. one entry is invalid), falls back to per-entry decryption so
-   * healthy entries still resolve. Each item in the result carries either a
-   * decrypted value or an error — callers decide how to surface partial failures.
+   * Complete an unwrap by fetching the public decryption proof and finalizing.
+   * Call this once the unwrap request has been processed on-chain.
    *
-   * @param encryptedInputs - FHE encrypted values paired with their contract addresses.
-   * @param delegatorAddress - The address that granted delegation rights.
-   * @param accountAddress - The account on whose behalf decryption is performed. Defaults to `delegatorAddress`.
-   * @param maxConcurrency - Maximum parallel decrypt calls during per-entry fallback.
-   * @param waitForPropagation - Ride out the gateway propagation window on the
-   *   initial batch attempt (default `true`). See {@link DelegatedDecryptOptions.waitForPropagation}.
-   * @returns Per-entry results, each with a value or an error.
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
-   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
+   * @param unwrapRequestId - The `unwrapRequestId` from an {@link UnwrapResult}
+   *   (`result.unwrapRequestId`) returned by {@link unwrap} / {@link unwrapAll},
+   *   or one decoded from an `UnwrapRequested` event (e.g. when finalizing
+   *   across sessions).
+   * @returns The transaction hash and mined receipt.
    *
    * @example
    * ```ts
-   * const result = await sdk.decryption.delegatedBatchDecryptValues({
-   *   encryptedInputs: [
-   *     { encryptedValue: encryptedValue1, contractAddress: tokenA },
-   *     { encryptedValue: encryptedValue2, contractAddress: tokenB },
-   *   ],
-   *   delegatorAddress: "0xDelegator",
-   *   maxConcurrency: 5,
-   * });
-   * for (const item of result.items) {
-   *   if (item.error) console.error(item.encryptedValue, item.error);
-   *   else console.log(item.encryptedValue, item.value);
-   * }
+   * const { unwrapRequestId } = await wrappedToken.unwrap(500n);
+   * await wrappedToken.finalizeUnwrap(unwrapRequestId);
    * ```
    */
-  delegatedBatchDecryptValues({ encryptedInputs, delegatorAddress, accountAddress, maxConcurrency, waitForPropagation }: {
-    encryptedInputs: EncryptedInput[];
-    delegatorAddress: Address;
-    accountAddress?: Address;
-    maxConcurrency?: number;
-  } & DelegatedDecryptOptions): Promise<BatchDecryptResult>;
+  finalizeUnwrap(unwrapRequestId: EncryptedValue): Promise<TransactionResult>;
 }
 //#endregion
-//#region src/namespaces/delegations.d.ts
+//#region src/schemas/primitives.d.ts
+declare const checksummedTag: unique symbol;
+/** An EVM address that has been put through `getAddress` (EIP-55 checksum form). */
+type ChecksummedAddress = Address & {
+  readonly [checksummedTag]: true;
+};
+//#endregion
+//#region src/credentials/types.d.ts
 /**
- * Public namespace for on-chain decryption-delegation management.
- *
- * Exposed as `sdk.delegations`. Owns the SDK-level guards (signer requirement, chain
- * alignment, delegator address resolution from the wallet account) and delegates the
- * actual work to the internal {@link DelegationService}.
- *
- * Delegation operations write to the host chain ACL; after a delegation is mined,
- * the gateway syncs the ACL state via cross-chain event propagation — usually
- * within ~10 blocks (a few seconds). Delegated decryption rides out that window
- * with a bounded internal retry, so callers can decrypt right after granting.
+ * Serialized transport key pair — ML-KEM public + private key as hex, the shape
+ * we persist and hand to the decrypt path. Mirrors `@fhevm/sdk`'s
+ * `serializeTransportKeyPair` output; the private half is plaintext, so treat it
+ * as sensitive.
  */
-declare class Delegations {
-  #private;
-  /** @internal */
-  constructor(opts: {
-    signer: GenericSigner | undefined;
-    provider: GenericProvider;
-    delegationService: DelegationService;
-  });
-  /**
-   * Delegate decryption rights for a confidential contract to another address.
-   * Calls `ACL.delegateForUserDecryption()` on-chain.
-   *
-   * The delegation is recorded on L1 immediately, but the gateway must sync the
-   * ACL state via cross-chain event propagation — usually within ~10 blocks (a
-   * few seconds). You do not need to wait: delegated decryption rides out that
-   * window with a bounded internal retry, so you can decrypt right after this
-   * resolves.
-   *
-   * @param contractAddress - The confidential contract address to delegate on.
-   * @param delegateAddress - Address to delegate decryption rights to.
-   * @param expirationDate - Optional expiration date (defaults to permanent delegation via `uint64.max`).
-   * @returns The transaction hash and mined receipt.
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
-   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
-   * @throws if `expirationDate` is less than 1 hour in the future. {@link DelegationExpirationTooSoonError}
-   * @throws if the delegate equals the connected wallet. {@link DelegationSelfNotAllowedError}
-   * @throws if the delegate equals the contract address. {@link DelegationDelegateEqualsContractError}
-   * @throws if the new expiry equals the current one. {@link DelegationExpiryUnchangedError}
-   * @throws if the delegation transaction reverts. {@link TransactionRevertedError}
-   */
-  delegateDecryption({ contractAddress, delegateAddress, expirationDate }: {
-    contractAddress: Address;
-    delegateAddress: Address;
-    expirationDate?: Date;
-  }): Promise<TransactionResult>;
+interface SerializedTransportKeyPair {
+  /** ML-KEM public key, hex-encoded. */
+  publicKey: Hex;
+  /** ML-KEM private key, hex-encoded (plaintext — treat as sensitive). */
+  privateKey: Hex;
   /**
-   * Revoke decryption delegation for a confidential contract.
-   * Calls `ACL.revokeDelegationForUserDecryption()` on-chain.
-   *
-   * @param contractAddress - The confidential contract address to revoke delegation on.
-   * @param delegateAddress - Address to revoke delegation from.
-   * @returns The transaction hash and mined receipt.
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
-   * @throws if signer and provider are on different chains. {@link ChainMismatchError}
-   * @throws if no delegation exists for this (delegator, delegate, contract) tuple. {@link DelegationNotFoundError}
-   * @throws if the revocation transaction reverts. {@link TransactionRevertedError}
+   * The TKMS version the key pair was generated under, passed back to
+   * `parseTransportKeyPair` so the private key deserializes under the right
+   * version after a KMS/TKMS rotation. Optional — key pairs serialized before
+   * this tag existed carry none.
    */
-  revokeDelegation({ contractAddress, delegateAddress }: {
-    contractAddress: Address;
-    delegateAddress: Address;
-  }): Promise<TransactionResult>;
+  tkmsVersion?: string;
+}
+/** EIP-712 typed-data payload carried by a {@link SerializedPermit}. */
+interface SerializedPermitEip712 {
+  /** EIP-712 domain separator fields. */
+  domain: Record<string, unknown>;
+  /** Name of the primary type being signed. */
+  primaryType?: string;
+  /** EIP-712 type definitions keyed by type name. */
+  types: Record<string, {
+    name: string;
+    type: string;
+  }[]>;
+  /** The typed-data message being signed. */
+  message: Record<string, unknown>;
+}
+/**
+ * The reusable serialized `@fhevm/sdk` decryption permit persisted inside a
+ * {@link Permission} — passed verbatim to `parseSignedDecryptionPermit`.
+ *
+ * Mirrors {@link SerializedPermitSchema}; kept in sync by a `.test-d.ts` guard.
+ */
+interface SerializedPermit {
+  /** Serialization format version. */
+  version: number;
+  /** The EIP-712 typed data that was signed. */
+  eip712: SerializedPermitEip712;
+  /** The signer's EIP-712 signature, hex-encoded. */
+  signature: Hex;
+  /** Address that produced the signature. */
+  signerAddress: ChecksummedAddress;
+}
+/**
+ * A signed EIP-712 permit binding a signer (and optional delegator) to a set of
+ * contract addresses for a bounded time window. Wraps the serialized `@fhevm/sdk`
+ * permit ({@link SerializedPermit}) alongside the scope/coverage metadata the
+ * permission store indexes on.
+ *
+ * Mirrors {@link PermissionSchema}; kept in sync by a `.test-d.ts` guard.
+ */
+interface Permission {
+  /** Public key of the transport key pair this permit is bound to, hex-encoded. */
+  keypairPublicKey: Hex;
+  /** Contract addresses this permit grants decrypt access to. */
+  contractAddresses: ChecksummedAddress[];
+  /** The signed serialized permit. */
+  serializedPermit: SerializedPermit;
+  /** Unix timestamp (seconds) when the permit becomes valid. */
+  startTimestamp: number;
+  /** Validity window length in days from {@link Permission.startTimestamp}. */
+  durationDays: number;
+}
+//#endregion
+//#region src/wrappers-registry.d.ts
+/**
+ * Default wrappers registry addresses for known chains.
+ * Only includes chains where a registry is deployed (excludes Hardhat).
+ *
+ * @deprecated Read `registryAddress` from the chain presets instead (e.g.
+ * `sepolia.registryAddress`). Will be removed in the next major version.
+ */
+declare const DefaultRegistryAddresses: Record<number, Address>;
+/** Configuration for {@link WrappersRegistry}. */
+interface WrappersRegistryConfig {
+  /** Read-only chain provider used for every registry lookup. */
+  provider: GenericProvider;
   /**
-   * Check whether a delegation is active for the given contract address.
-   *
-   * Signer-independent: works without a configured signer.
+   * Per-chain registry address overrides, merged on top of
+   * {@link DefaultRegistryAddresses}. Use this to supply a registry
+   * address for custom or local chains (e.g. Hardhat).
    *
-   * @param contractAddress - The confidential contract address.
-   * @param delegatorAddress - The address that granted the delegation.
-   * @param delegateAddress - The address that received delegation rights.
-   * @returns `true` if the delegation exists and has not expired.
+   * @example
+   * ```ts
+   * new WrappersRegistry({
+   *   provider,
+   *   registryAddresses: { [31337]: "0xYourHardhatRegistry" },
+   * });
+   * ```
    */
-  isActive(params: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<boolean>;
+  registryAddresses?: Record<number, Address>;
   /**
-   * Get the expiration timestamp of a delegation for the given contract.
-   *
-   * Signer-independent: works without a configured signer.
-   *
-   * @param contractAddress - The confidential contract address.
-   * @param delegatorAddress - The address that granted the delegation.
-   * @param delegateAddress - The address that received delegation rights.
-   * @returns Unix timestamp as bigint. `0n` = no delegation. `2^64 - 1` = permanent.
+   * How long cached registry results remain valid, in seconds.
+   * Default: `86400` (24 hours).
    */
-  getExpiry(params: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<bigint>;
+  registryTTL?: number;
+}
+/** Options for {@link WrappersRegistry.listPairs}. */
+interface ListPairsOptions {
+  /** Page number (1-indexed). Default: `1`. */
+  page?: number;
+  /** Number of items per page. Default: `100`. */
+  pageSize?: number;
   /**
-   * Get activity and expiry together in a single on-chain read, instead of
-   * calling {@link isActive} and {@link getExpiry} separately.
-   *
-   * Signer-independent: works without a configured signer.
-   *
-   * @param contractAddress - The confidential contract address.
-   * @param delegatorAddress - The address that granted the delegation.
-   * @param delegateAddress - The address that received delegation rights.
-   * @returns `{ isActive, expiryTimestamp }` — activity and the raw expiry timestamp together.
+   * When `true`, fetches on-chain metadata (name, symbol, decimals) for both
+   * the ERC-20 and confidential token, plus totalSupply for the ERC-20.
+   * Default: `false`.
    */
-  getStatus(params: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<DelegationStatus>;
+  metadata?: boolean;
 }
-//#endregion
-//#region src/namespaces/permits.d.ts
 /**
- * Public namespace for permit and transport-key-pair management.
+ * High-level interface for the on-chain token wrappers registry.
  *
- * Exposed as `sdk.permits`. Owns the SDK-level guards (chain alignment, empty-array
- * short-circuit, decrypt-cache invalidation) and delegates the actual work to the
- * internal {@link CredentialService}.
+ * Uses the configured {@link GenericProvider} to resolve the correct registry
+ * contract address for the current chain and exposes typed read helpers for
+ * every registry query. Results are cached in memory with a configurable TTL
+ * (default 24 hours).
  *
- * The namespace is named `permits` because the user-facing concept is the signed-permit
- * store. The transport key pair is invisible plumbing — there is no `getTransportKeyPair()`
- * surfaced; the key pair exists to sign permits and is created automatically when needed.
- * {@link clear} wipes both the permit store and the transport key pair (permits
- * cascade-delete with the key pair).
+ * @example
+ * ```ts
+ * const registry = new WrappersRegistry({ provider });
+ *
+ * // Paginated listing
+ * const page1 = await registry.listPairs({ page: 1, pageSize: 20 });
  *
- * When `transportKeyPairScope` is configured (opt-in shared-tenant scope for B2B2C/WaaS
- * operators), {@link clear} and {@link revokePermits} stay signer-level only — they never
- * touch the shared key pair. {@link revokeTransportKeyPair} is the distinct,
- * operator-level operation for that.
+ * // Structured lookups
+ * const result = await registry.getConfidentialToken(erc20Address);
+ * if (result) console.log(result.confidentialTokenAddress);
+ *
+ * // Force refresh
+ * registry.refresh();
+ * ```
  */
-declare class Permits {
+declare class WrappersRegistry {
   #private;
-  /** @internal */
-  constructor(opts: {
-    signer: GenericSigner | undefined;
-    provider: GenericProvider;
-    cachingService: CachingService;
-    credentialService: CredentialService | undefined;
-    logger: GenericLogger;
-  });
+  /** Read-only chain access used for registry contract reads. */
+  readonly provider: GenericProvider;
+  constructor(config: WrappersRegistryConfig);
   /**
-   * Sign and store an EIP-712 permit authorising direct decryption for the
-   * given contract addresses.
-   *
-   * Idempotent: if a permit covering the requested set already exists, no
-   * wallet prompt occurs. Otherwise the SDK chunks the uncovered subset into
-   * groups of ≤10 contracts and prompts once per chunk; partial mid-flight
-   * rejection is preserved (already-signed chunks are persisted before the
-   * next prompt).
-   *
-   * @param contracts - Contract addresses to authorize.
+   * Synchronous lookup of the registry address for a given chain ID.
+   * Returns `undefined` if no address is configured for that chain.
    */
-  grantPermit(contracts: Address[]): Promise<void>;
+  getAddress(chainId: number): Address | undefined;
   /**
-   * Sign and store an EIP-712 delegation permit authorising decryption on
-   * behalf of `delegator`. Same idempotence/chunking semantics as {@link grantPermit}.
-   *
-   * @param delegator - The address that delegated decryption rights to the connected signer.
-   * @param contracts - Contract addresses to authorize.
+   * Force-invalidate the in-memory cache. The next call to any read method
+   * will fetch fresh data from the chain.
    */
-  grantDelegationPermit(delegator: Address, contracts: Address[]): Promise<void>;
+  refresh(): void;
   /**
-   * Pure store lookup: is there a permit covering `contracts`?
-   * No wallet prompt, no transport key pair generation. Returns `false` when no signer
-   * is configured.
+   * The cache TTL in milliseconds.
+   * Exposed so query option factories can set a matching `staleTime`.
    */
-  hasPermit(contracts: Address[]): Promise<boolean>;
+  get ttlMs(): number;
   /**
-   * Pure store lookup for a delegation permit. See {@link hasPermit}.
+   * Resolve the registry contract address for the current chain.
    *
-   * @param delegator - The address that delegated decryption rights to the connected signer.
-   * @param contracts - Contract addresses to check.
-   * @returns `true` if cached delegation permits cover all requested contracts.
+   * Priority: `registryAddresses[chainId]` \> built-in default.
+   *
+   * @returns The registry contract address for the connected chain.
+   * @throws if no address is configured for the chain. {@link ConfigurationError}
    */
-  hasDelegationPermit(delegator: Address, contracts: Address[]): Promise<boolean>;
+  getRegistryAddress(): Promise<Address>;
   /**
-   * Best-effort transport-key-pair prefetch for the connected signer.
+   * List token wrapper pairs with page-based pagination.
    *
-   * Optional latency optimization: decrypt and permit flows remain correct
-   * without it because they lazily create the transport key pair when needed.
+   * Internally maps to `getTokenConfidentialTokenPairsSlice` on-chain.
    *
-   * Silent no-op when no signer is configured or no wallet account is
-   * available. The transport key pair is generated through the relayer dispatcher's
-   * currently active chain — see {@link LifecycleService}, which calls
-   * `switchChain` before fanning the wallet-account change out to listeners,
-   * so any downstream caller (including React adapters) observes the
-   * dispatcher on the wallet chain by the time it invokes warmup.
+   * @param options - Pagination and enrichment options.
+   * @returns A {@link PaginatedResult} of pairs.
    *
-   * Not for pre-warming a shared `transportKeyPairScope`: this call's wallet-account
-   * precondition doesn't conceptually apply to a scope-wide key, and would silently
-   * no-op precisely when an operator is most likely to be calling it (no end-user
-   * connected yet). Use {@link warmTransportKeyPairScope} instead.
+   * @example
+   * ```ts
+   * const result = await registry.listPairs({ page: 1, pageSize: 20 });
+   * console.log(`${result.total} pairs, showing page ${result.page}`);
+   *
+   * // With on-chain metadata
+   * const withMeta = await registry.listPairs({ metadata: true, pageSize: 10 });
+   * for (const pair of withMeta.items) {
+   *   console.log(pair.underlying.symbol, "→", pair.confidential.symbol);
+   * }
+   * ```
    */
-  warmTransportKeyPair(): Promise<void>;
+  listPairs(options: ListPairsOptions & {
+    metadata: true;
+  }): Promise<PaginatedResult<TokenWrapperPairWithMetadata>>;
+  /** Lists registered underlying/confidential token pairs; pass `{ metadata: true }` to include on-chain token metadata. */
+  listPairs(options?: ListPairsOptions): Promise<PaginatedResult<TokenWrapperPair>>;
   /**
-   * Wipe FHE permits for the current signer.
+   * Look up the confidential token for a given plain ERC-20 address.
    *
-   * - With no argument: every permit referencing this signer is removed across
-   *   all chains and delegators. The transport key pair survives — use {@link clear} to
-   *   also wipe the transport key pair.
-   * - With a contract list: every signed permit in the direct-decrypt scope
-   *   (current chain) whose immutable payload touches any listed address is
-   *   removed. Delegation permits are not touched in this mode.
+   * @param tokenAddress - The plain ERC-20 token address.
+   * @returns The lookup result, or `null` if the token has never been registered.
+   *   **Note:** revoked tokens (registered then invalidated) return a non-null result
+   *   with `isValid: false`. Check `result.isValid` explicitly rather than using
+   *   `if (result)` to guard against processing revoked tokens.
    *
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @example
+   * ```ts
+   * const result = await registry.getConfidentialToken(usdcAddress);
+   * if (result?.isValid) {
+   *   console.log(result.confidentialTokenAddress);
+   * }
+   * ```
    */
-  revokePermits(contracts?: Address[]): Promise<void>;
+  getConfidentialToken(tokenAddress: Address): Promise<{
+    confidentialTokenAddress: Address;
+    isValid: boolean;
+  } | null>;
   /**
-   * Wipe the transport key pair for the current signer and cascade-delete every permit
-   * (across chains and delegators) referencing it.
+   * Reverse lookup — find the plain ERC-20 for a given confidential token.
    *
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @param confidentialTokenAddress - The confidential token address.
+   * @returns The lookup result, or `null` if no pair is registered.
+   *
+   * @example
+   * ```ts
+   * const result = await registry.getUnderlyingToken(cUsdcAddress);
+   * if (result) {
+   *   console.log(result.tokenAddress, result.isValid);
+   * }
+   * ```
    */
-  clear(): Promise<void>;
+  getUnderlyingToken(confidentialTokenAddress: Address): Promise<{
+    tokenAddress: Address;
+    isValid: boolean;
+  } | null>;
   /**
-   * Revoke the shared transport key pair for `transportKeyPairScope` (operator-level
-   * action — no wallet account needs to be connected, but a signer must still be
-   * configured on this SDK instance at construction time).
+   * Fetch all token wrapper pairs from the registry.
    *
-   * Deletes the shared key pair; every permit in the scope embeds its public key, so
-   * they're all treated as stale on next access. Signer-level {@link clear} never does
-   * this — it only ever wipes the calling signer's own permits.
+   * @returns All registered `TokenWrapperPair` entries.
+   */
+  getTokenPairs(): Promise<readonly TokenWrapperPair[]>;
+  /**
+   * Get the total number of token wrapper pairs.
    *
-   * Not best-effort, unlike most credential-store writes: a storage failure rejects
-   * instead of being logged and swallowed. This is the primitive an operator reaches
-   * for on suspected key compromise — a resolved promise must mean the key pair is
-   * actually gone.
+   * @returns The count as a bigint.
+   */
+  getTokenPairsLength(): Promise<bigint>;
+  /**
+   * Fetch a range of token wrapper pairs (paginated by index).
    *
-   * Stops the SDK from reissuing or reusing the deleted key — does not revoke any
-   * permit already issued under it. A permit is a self-contained, bearer-style EIP-712
-   * signature the relayer accepts independently of this SDK; one exfiltrated alongside
-   * the key remains usable until its own `permitTTL` expiry regardless of this call.
+   * @param fromIndex - Start index (inclusive).
+   * @param toIndex - End index (exclusive).
+   * @returns The slice of `TokenWrapperPair` entries.
+   */
+  getTokenPairsSlice(fromIndex: bigint, toIndex: bigint): Promise<readonly TokenWrapperPair[]>;
+  /**
+   * Fetch a single token wrapper pair by index.
    *
-   * @param scopeId - Must match the configured `transportKeyPairScope`, as a guard
-   *   against revoking the wrong scope by mistake.
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
-   * @throws if no scope is configured, or `scopeId` doesn't match it. {@link ConfigurationError}
-   * @throws if the underlying storage delete fails.
+   * @param index - Zero-based pair index.
+   * @returns The `TokenWrapperPair` at that index.
    */
-  revokeTransportKeyPair(scopeId: string): Promise<void>;
+  getTokenPair(index: bigint): Promise<TokenWrapperPair>;
   /**
-   * Warm the shared transport key pair for `transportKeyPairScope` (operator-level —
-   * no wallet account needs to be connected, but a signer must still be configured on
-   * this SDK instance at construction time) — the pre-warm counterpart to
-   * {@link revokeTransportKeyPair}. Prefer this over {@link warmTransportKeyPair} for a
-   * scoped key pair: unlike that method, this never silently no-ops for lack of a
-   * connected wallet, because a scope-wide key was never tied to one in the first place.
+   * Look up the confidential token address for a given plain ERC-20 token.
    *
-   * @param scopeId - Must match the configured `transportKeyPairScope`, as a guard
-   *   against warming the wrong scope by mistake.
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
-   * @throws if no scope is configured, or `scopeId` doesn't match it. {@link ConfigurationError}
+   * @param tokenAddress - The plain ERC-20 token address.
+   * @returns A tuple `[isValid, confidentialTokenAddress]`. `isValid` is `true` only for a
+   *   registered, non-revoked wrapper. The address is the zero address when no pair is registered.
+   *   A non-zero address with `isValid=false` means the wrapper was registered but later revoked.
    */
-  warmTransportKeyPairScope(scopeId: string): Promise<void>;
+  getConfidentialTokenAddress(tokenAddress: Address): Promise<readonly [boolean, Address]>;
+  /**
+   * Reverse lookup — find the plain ERC-20 for a given confidential token.
+   *
+   * @param confidentialTokenAddress - The confidential token address.
+   * @returns A tuple `[isValid, tokenAddress]`. `isValid` is `true` only for a registered,
+   *   non-revoked wrapper. The address is the zero address when no pair is registered.
+   *   A non-zero address with `isValid=false` means the wrapper was registered but later revoked.
+   */
+  getTokenAddress(confidentialTokenAddress: Address): Promise<readonly [boolean, Address]>;
+  /**
+   * Check whether a confidential token is registered and valid.
+   *
+   * @param confidentialTokenAddress - The confidential token address to check.
+   * @returns `true` if the token is a known valid wrapper in the registry.
+   */
+  isConfidentialTokenValid(confidentialTokenAddress: Address): Promise<boolean>;
 }
 //#endregion
 //#region src/zama-sdk.d.ts
@@ -21064,8 +20478,11 @@ declare class Permits {
  */
 declare class ZamaSDK {
   #private;
+  /** Read-only chain access used for all contract reads. */
   readonly provider: GenericProvider;
+  /** Wallet signer used for write operations, or `undefined` when the SDK is read-only. */
   readonly signer: GenericSigner | undefined;
+  /** Storage for cached permits and transport key pairs. */
   readonly storage: GenericStorage;
   /**
    * A {@link WrappersRegistry} instance auto-configured for the current chain.
@@ -21079,43 +20496,10 @@ declare class ZamaSDK {
   /** FHE decryption (user, delegated user, public). */
   readonly decryption: Decryption;
   constructor(config: ZamaConfig);
-  /**
-   * Subscribe to wallet account transitions.
-   *
-   * @param listener - Called on each transition with a {@link WalletAccountChange} carrying
-   *   `previous` and `next` wallet account snapshots; either may be `undefined` for
-   *   connect and disconnect transitions.
-   * @returns An unsubscribe function; calling it removes the listener.
-   *
-   * @internal
-   */
-  onWalletAccountChange(listener: WalletAccountListener): () => void;
-  /**
-   * The SDK-wide logger, exposed so contract abstractions ({@link Token},
-   * {@link WrappedToken}) can route their best-effort failures through the
-   * same sink. Silent by default.
-   *
-   * @internal
-   */
-  get logger(): GenericLogger;
   /**
    * The single-chain relayer backend for the **currently active** chain.
-   *
-   * @internal
-   */
-  get relayer(): FhevmRelayerSDK;
-  /**
-   * Emit a structured SDK event into the unified SDK event stream.
-   *
-   * Listener exceptions are caught and logged so that a misbehaving subscriber
-   * can never corrupt SDK operations.
-   *
-   * Application code should subscribe via the `onEvent` config option, never
-   * call this directly.
-   *
-   * @internal
    */
-  emitEvent(input: ZamaSDKEventInput, tokenAddress?: Address): void;
+  get relayer(): RelayerSDK;
   /**
    * Create a {@link WrappersRegistry} instance bound to this SDK's provider.
    * Inherits the registry addresses derived from the SDK's chain configs, so
@@ -21211,5 +20595,94 @@ declare class ZamaSDK {
   [Symbol.dispose](): void;
 }
 //#endregion
-export { confidentialTransferAndCallMutationOptions as $, filterQueryOptions as $n, DelegationExpiryUnchangedError as $t, encryptMutationOptions as A, isWrapperQueryOptions as An, confidentialTransferContract as Ar, SigningRejectedError as At, UnshieldAllParams as B, invalidateAfterTransfer as Bn, wrapContract as Br, BalanceErrorDetails as Bt, grantPermitMutationOptions as C, Permission as Cn, approveContract as Cr, WrappedToken as Ct, DecryptResult as D, totalSupplyQueryOptions as Dn, symbolContract as Dr, matchZamaError as Dt, delegatedDecryptValuesMutationOptions as E, TotalSupplyQueryConfig as En, nameContract as Er, Token as Et, wrapMutationOptions as F, QueryFilterLike as Fn, rateContract as Fr, RpcRateLimitError as Ft, approveUnderlyingMutationOptions as G, invalidateBalanceQueries as Gn, DecryptionFailedError as Gt, UnshieldParams as H, invalidateAfterUnshieldSettled as Hn, resolveChainRelayers as Hr, InsufficientAllowanceError as Ht, UnwrapParams as I, QueryLike as In, setOperatorContract as Ir, NotEntitledError as It, ConfidentialTransferFromAndCallParams as J, zamaQueryKeys as Jn, DelegationContractIsSelfError as Jt, ConfidentialSetOperatorParams as K, invalidateWagmiBalanceQueries as Kn, EncryptionFailedError as Kt, unwrapMutationOptions as L, invalidateAfterApproveUnderlying as Ln, underlyingContract as Lr, ConfigurationError as Lt, finalizeUnwrapMutationOptions as M, TokenMetadataQueryConfig as Mn, finalizeUnwrapContract as Mr, SignerRequiredError as Mt, unwrapAllMutationOptions as N, tokenMetadataQueryOptions as Nn, inferredTotalSupplyContract as Nr, WalletAccountNotReadyError as Nt, EncryptedInput as O, IsConfidentialQueryConfig as On, confidentialBalanceOfContract as Or, TransactionRevertedError as Ot, WrapParams as P, QueryClientLike as Pn, isOperatorContract as Pr, WalletNotConnectedError as Pt, ConfidentialTransferAndCallParams as Q, StrippedQueryOptionKeys as Qn, DelegationExpiredError as Qt, ResumeUnshieldParams as R, invalidateAfterSetOperator as Rn, unwrapContract as Rr, RelayerRequestFailedError as Rt, hasPermitQueryOptions as S, WrappersRegistryConfig as Sn, allowanceContract as Sr, confidentialBalanceQueryOptions as St, DelegatedDecryptValuesMutationParams as T, StoredTransportKeyPair as Tn, decimalsContract as Tr, BatchDecryptAsOptions as Tt, unshieldMutationOptions as U, invalidateAfterUnwrap as Un, resolveStorage as Ur, InsufficientConfidentialBalanceError as Ut, unshieldAllMutationOptions as V, invalidateAfterUnshield as Vn, ResolvedChainRelayer as Vr, ERC20ReadFailedError as Vt, ApproveUnderlyingParams as W, invalidateAfterWrap as Wn, createConfig as Wr, InsufficientERC20BalanceError as Wt, ConfidentialTransferFromParams as X, MutationFactoryOptions as Xn, DelegationDelegateEqualsContractError as Xt, confidentialTransferFromAndCallMutationOptions as Y, SignerQueryContext as Yn, DelegationCooldownError as Yt, confidentialTransferFromMutationOptions as Z, QueryFactoryOptions as Zn, DelegationExpirationTooSoonError as Zt, DelegateDecryptionParams as _, WrapperDiscoveryQueryConfig as _n, ERC7984_INTERFACE_ID as _r, tokenPairsQueryOptions as _t, BatchDecryptItem as a, TransportKeyPairExpiredError as an, getTokenAddressContract as ar, IsConfidentialTokenValidQueryConfig as at, revokePermitsMutationOptions as b, ListPairsOptions as bn, isConfidentialWrapperContract as br, confidentialBalancesQueryOptions as bt, DelegationStatusQueryConfig as c, ZamaErrorCode as cn, getTokenPairsLengthContract as cr, TokenPairQueryConfig as ct, RevokeDelegationParams as d, ConfidentialIsOperatorQueryConfig as dn, delegateForUserDecryptionContract as dr, confidentialTokenAddressQueryOptions as dt, DelegationNotFoundError as en, hashFn as er, ConfidentialTransferParams as et, revokeDelegationMutationOptions as f, confidentialIsOperatorQueryOptions as fn, getDelegationExpiryContract as fr, isConfidentialTokenValidQueryOptions as ft, decryptBalanceAsMutationOptions as g, underlyingAllowanceQueryOptions as gn, ERC1363_INTERFACE_ID as gr, tokenPairsLengthQueryOptions as gt, DecryptBalanceAsParams as h, UnderlyingAllowanceQueryConfig as hn, transferAndCallContract as hr, tokenPairQueryOptions as ht, Decryption as i, NoCiphertextError as in, getConfidentialTokenAddressContract as ir, ConfidentialTokenAddressQueryConfig as it, FinalizeUnwrapParams as j, TokenMetadata as jn, confidentialTransferFromContract as jr, SignerNotConfiguredError as jt, decryptValuesQueryOptions as k, isConfidentialQueryOptions as kn, confidentialTotalSupplyContract as kr, SigningFailedError as kt, delegationStatusQueryOptions as l, isRetryable as ln, getTokenPairsSliceContract as lr, TokenPairsSliceQueryConfig as lt, batchDecryptBalancesAsMutationOptions as m, pendingUnshieldQueryOptions as mn, revokeDelegationContract as mr, tokenAddressQueryOptions as mt, Permits as n, DelegationSelfNotAllowedError as nn, TokenWrapperPair as nr, ShieldParams as nt, BatchDecryptResult as o, ChainMismatchError as on, getTokenPairContract as or, ListPairsQueryConfig as ot, BatchDecryptBalancesAsParams as p, PendingUnshieldQueryConfig as pn, isHandleDelegatedContract as pr, listPairsQueryOptions as pt, confidentialSetOperatorMutationOptions as q, invalidateWalletLifecycleQueries as qn, AclPausedError as qt, Delegations as r, InvalidTransportKeyPairError as rn, TokenWrapperPairWithMetadata as rr, shieldMutationOptions as rt, DelegatedDecryptOptions as s, ZamaError as sn, getTokenPairsContract as sr, TokenAddressQueryConfig as st, ZamaSDK as t, DelegationNotPropagatedError as tn, PaginatedResult as tr, confidentialTransferMutationOptions as tt, DelegationStatus as u, retryAfterSeconds as un, isConfidentialTokenValidContract as ur, WrappersRegistryQueryConfig as ut, delegateDecryptionMutationOptions as v, wrapperDiscoveryQueryOptions as vn, ERC7984_WRAPPER_INTERFACE_ID as vr, tokenPairsSliceQueryOptions as vt, decryptPublicValuesMutationOptions as w, SerializedTransportKeyPair as wn, balanceOfContract as wr, BatchBalancesResult as wt, HasPermitQueryConfig as x, WrappersRegistry as xn, supportsInterfaceContract as xr, ConfidentialBalanceQueryConfig as xt, clearCredentialsMutationOptions as y, DefaultRegistryAddresses as yn, isConfidentialTokenContract as yr, ConfidentialBalancesQueryConfig as yt, resumeUnshieldMutationOptions as z, invalidateAfterShield as zn, unwrapFromBalanceContract as zr, BalanceCheckUnavailableError as zt };
-//# sourceMappingURL=zama-sdk-BhD6nWLL.d.ts.map
+//#region src/utils/handles.d.ts
+/** All-zero encrypted-value sentinel — a 32-byte zero handle representing the cleartext value `0`. */
+declare const ZERO_ENCRYPTED_VALUE: "0x0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * Check whether an encrypted value represents the zero value.
+ */
+declare function isEncryptedValueZero(encryptedValue: string): boolean;
+//#endregion
+//#region src/storage/memory-storage.d.ts
+/** In-memory credential store. Credentials are lost on page reload. */
+declare class MemoryStorage implements GenericStorage {
+  #private;
+  /**
+   * Retrieve a value by key.
+   * @returns The stored value, or `null` if the key does not exist.
+   */
+  get<T = unknown>(key: string): Promise<T | null>;
+  /** Store a value under the given key, overwriting any existing entry. */
+  set<T = unknown>(key: string, value: T): Promise<void>;
+  /** Remove the entry for the given key (no-op if absent). */
+  delete(key: string): Promise<void>;
+}
+/** Default singleton for application-wide use. */
+declare const memoryStorage: MemoryStorage;
+//#endregion
+//#region src/storage/indexeddb-storage.d.ts
+/**
+ * IndexedDB-backed {@link GenericStorage}.
+ *
+ * Stores keypair and permit objects keyed by a hashed wallet address. The
+ * SDK delegates security to the storage backend — values are persisted
+ * verbatim with no SDK-layer encryption.
+ */
+declare class IndexedDBStorage implements GenericStorage {
+  #private;
+  constructor(dbName?: string, dbVersion?: number, storeName?: string);
+  /**
+   * Retrieve a value by key.
+   * @returns The stored value, or `null` if the key does not exist.
+   */
+  get<T = unknown>(key: string): Promise<T | null>;
+  /** Store a value under the given key, overwriting any existing entry. */
+  set<T = unknown>(key: string, value: T): Promise<void>;
+  /** Remove the entry for the given key (no-op if absent). */
+  delete(key: string): Promise<void>;
+  /** Remove all stored entries. */
+  clear(): Promise<void>;
+}
+/** Default singleton for application-wide use. */
+declare const indexedDBStorage: IndexedDBStorage;
+//#endregion
+//#region src/storage/chrome-session-storage.d.ts
+/**
+ * {@link GenericStorage} backed by `chrome.storage.session`.
+ *
+ * Use this in MV3 web extensions so the wallet signature survives
+ * service worker restarts and is shared across popup, background,
+ * and content script contexts.
+ *
+ * @example
+ * ```ts
+ * import { ZamaSDK, indexedDBStorage, chromeSessionStorage } from "@zama-fhe/sdk";
+ * import { createConfig } from "@zama-fhe/sdk/viem";
+ *
+ * const config = createConfig({
+ *   chains: [mySepolia],
+ *   publicClient,
+ *   walletClient,
+ *   relayers: { [mySepolia.id]: web() },
+ *   storage: indexedDBStorage, // encrypted transport key pair — persistent
+ *   permitStorage: chromeSessionStorage, // signed permits — ephemeral
+ * });
+ * const sdk = new ZamaSDK(config);
+ * ```
+ */
+declare class ChromeSessionStorage implements GenericStorage {
+  /**
+   * Retrieve a value by key.
+   * @returns The stored value, or `null` if the key does not exist.
+   */
+  get<T = unknown>(key: string): Promise<T | null>;
+  /** Store a value under the given key, overwriting any existing entry. */
+  set(key: string, value: unknown): Promise<void>;
+  /** Remove the entry for the given key (no-op if absent). */
+  delete(key: string): Promise<void>;
+}
+/** Default singleton for application-wide use. */
+declare const chromeSessionStorage: ChromeSessionStorage;
+//#endregion
+export { AclPausedError as $, confidentialTransferContract as $t, BatchDecryptResult as A, getTokenPairsContract as At, WalletNotConnectedError as B, ERC7984_INTERFACE_ID as Bt, BatchDecryptAsOptions as C, QueryFactoryOptions as Ct, DelegationStatus as D, getConfidentialTokenAddressContract as Dt, Delegations as E, TokenWrapperPairWithMetadata as Et, SigningFailedError as F, getDelegationExpiryContract as Ft, BalanceCheckUnavailableError as G, allowanceContract as Gt, NotEntitledError as H, isConfidentialTokenContract as Ht, SigningRejectedError as I, isHandleDelegatedContract as It, InsufficientAllowanceError as J, decimalsContract as Jt, BalanceErrorDetails as K, approveContract as Kt, SignerNotConfiguredError as L, revokeDelegationContract as Lt, ErrorForCode as M, getTokenPairsSliceContract as Mt, matchZamaError as N, isConfidentialTokenValidContract as Nt, Decryption as O, getTokenAddressContract as Ot, TransactionRevertedError as P, delegateForUserDecryptionContract as Pt, EncryptionFailedError as Q, confidentialTotalSupplyContract as Qt, SignerRequiredError as R, transferAndCallContract as Rt, BatchBalancesResult as S, MutationFactoryOptions as St, Permits as T, TokenWrapperPair as Tt, ConfigurationError as U, isConfidentialWrapperContract as Ut, RpcRateLimitError as V, ERC7984_WRAPPER_INTERFACE_ID as Vt, RelayerRequestFailedError as W, supportsInterfaceContract as Wt, InsufficientERC20BalanceError as X, symbolContract as Xt, InsufficientConfidentialBalanceError as Y, nameContract as Yt, DecryptionFailedError as Z, confidentialBalanceOfContract as Zt, SerializedPermit as _, DecryptResult as _t, IndexedDBStorage as a, setOperatorContract as an, DelegationExpiryUnchangedError as at, ChecksummedAddress as b, SignerQueryContext as bt, memoryStorage as c, unwrapFromBalanceContract as cn, DelegationSelfNotAllowedError as ct, ZamaSDK as d, TransportKeyPairExpiredError as dt, confidentialTransferFromContract as en, DelegationContractIsSelfError as et, DefaultRegistryAddresses as f, ChainMismatchError as ft, Permission as g, retryAfterSeconds as gt, WrappersRegistryConfig as h, isRetryable as ht, chromeSessionStorage as i, rateContract as in, DelegationExpiredError as it, DelegatedDecryptOptions as j, getTokenPairsLengthContract as jt, BatchDecryptItem as k, getTokenPairContract as kt, ZERO_ENCRYPTED_VALUE as l, wrapContract as ln, InvalidTransportKeyPairError as lt, WrappersRegistry as m, ZamaErrorCode as mt, Hex$1 as n, inferredTotalSupplyContract as nn, DelegationDelegateEqualsContractError as nt, indexedDBStorage as o, underlyingContract as on, DelegationNotFoundError as ot, ListPairsOptions as p, ZamaError as pt, ERC20ReadFailedError as q, balanceOfContract as qt, ChromeSessionStorage as r, isOperatorContract as rn, DelegationExpirationTooSoonError as rt, MemoryStorage as s, unwrapContract as sn, DelegationNotPropagatedError as st, Address$1 as t, finalizeUnwrapContract as tn, DelegationCooldownError as tt, isEncryptedValueZero as u, createConfig as un, NoCiphertextError as ut, SerializedPermitEip712 as v, EncryptedInput as vt, Token as w, PaginatedResult as wt, WrappedToken as x, zamaQueryKeys as xt, SerializedTransportKeyPair as y, decryptValuesQueryOptions as yt, WalletAccountNotReadyError as z, ERC1363_INTERFACE_ID as zt };
+//# sourceMappingURL=index-DLaQtvYu.d.ts.map