@zama-fhe/sdk 3.4.0-alpha.2 → 3.4.0-alpha.3

package/dist/esm/{zama-sdk-aaLl2ZlA.d.ts → index-09tK1t8M.d.ts}

@@ -1,10 +1,10 @@
 import { u as FheChain } from "./index-doNE2KoX.js";
-import { $ as TransferOptions, Bt as EncryptedValue, C as ChainRouter, Ht as FhevmRelayerOptions, K as ZamaSDKEventInput, Mt as TransactionResult, Nt as ClearValue, Pt as DecryptPublicValuesResult, R as TransactionOperation, Rt as EncryptParams, Ut as FhevmRelayerSDK, Z as ShieldOptions, c as GenericStorage, d as WalletAccount, et as UnshieldOptions, i as ZamaConfig, l as GenericProvider, n as RelayerConfig, nt as TransferCallbacks, o as ZamaConfigGeneric, p as WalletAccountListener, rt as UnshieldCallbacks, s as GenericLogger, u as GenericSigner, x as WriteContractConfig, zt as EncryptResult } from "./types-nwhfaUCK.js";
-import "./cleartext-Bvx-0y6k.js";
-import "./types-D8g0H49N.js";
-import "./types-CObfaH4A.js";
-import "./index-CDJk5ZAg.js";
-import { Address, Hex } from "viem";
+import { $ as TransferOptions, Bt as EncryptResult, C as ChainRouter, Ft as DecryptPublicValuesResult, K as ZamaSDKEventInput, Nt as TransactionResult, Pt as ClearValue, R as TransactionOperation, Ut as FhevmRelayerOptions, Vt as EncryptedValue, Wt as FhevmRelayerSDK, Z as ShieldOptions, c as GenericStorage, d as WalletAccount, et as UnshieldOptions, i as ZamaConfig, it as UnshieldCallbacks, l as GenericProvider, n as RelayerConfig, o as ZamaConfigGeneric, p as WalletAccountListener, rt as TransferCallbacks, s as GenericLogger, tt as UnwrapResult, u as GenericSigner, x as WriteContractConfig, zt as EncryptParams } from "./types-C5XL-FYs.js";
+import "./cleartext-D2thmTZC.js";
+import "./types-BHavXeSS.js";
+import "./base-signer-DEZW976z.js";
+import "./types-CLSVkR1j.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
@@ -18459,34 +18459,6 @@ 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>;
-/**
- * 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.
- */
-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"> & {
@@ -18498,11 +18470,6 @@ interface MutationFactoryOptions<TMutationKey extends readonly unknown[], TVaria
   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,53 +18673,19 @@ 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 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
+interface SignerQueryContext {
+  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
+interface EncryptedInput {
+  encryptedValue: EncryptedValue;
+  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>>;
+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;
@@ -18820,272 +18753,91 @@ interface SerializedTransportKeyPairWithPermissions {
   readonly permissions: readonly Permission[];
 }
 //#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/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;
 }
 /**
- * High-level interface for the on-chain token wrappers registry.
- *
- * 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);
+ * Single facade coordinating the keypair vault and the permission store.
  *
- * // Force refresh
- * registry.refresh();
- * ```
+ * `CredentialService` is the only credentials object held by `ZamaSDK`. It accepts identity
+ * transitions via `handleWalletAccountChange`.
  */
-declare class WrappersRegistry {
+declare class CredentialService {
   #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>;
+  constructor(config: CredentialServiceConfig);
   /**
-   * 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}`);
+   * 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.
    *
-   * // 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);
-   * }
-   * ```
+   * @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}
    */
-  listPairs(options: ListPairsOptions & {
-    metadata: true;
-  }): Promise<PaginatedResult<TokenWrapperPairWithMetadata>>;
-  listPairs(options?: ListPairsOptions): Promise<PaginatedResult<TokenWrapperPair>>;
+  grantPermit(contracts: readonly Address[], delegator?: Address): Promise<SerializedTransportKeyPairWithPermissions>;
   /**
-   * 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.
+   * Pure store lookup: are stored permits sufficient to cover `contracts`? No wallet prompt.
    *
-   * @example
-   * ```ts
-   * const result = await registry.getConfidentialToken(usdcAddress);
-   * if (result?.isValid) {
-   *   console.log(result.confidentialTokenAddress);
-   * }
-   * ```
+   * @returns `true` if cached permits cover all requested contracts (vacuously
+   *   true for an empty list); `false` if no keypair exists or coverage is
+   *   incomplete.
    */
-  getConfidentialToken(tokenAddress: Address): Promise<{
-    confidentialTokenAddress: Address;
-    isValid: boolean;
-  } | null>;
+  hasPermit(contracts: readonly Address[], delegator?: Address): Promise<boolean>;
   /**
-   * 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.
+   * Wipe FHE permits for the current signer.
    *
-   * @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.
+   * - 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.
    *
-   * @returns All registered `TokenWrapperPair` entries.
+   * @throws if reading the signer address fails. {@link SigningFailedError}
    */
-  getTokenPairs(): Promise<readonly TokenWrapperPair[]>;
+  revokePermits(contracts?: readonly Address[]): Promise<void>;
   /**
-   * Get the total number of token wrapper pairs.
+   * Wipe the keypair for the current signer and cascade-delete every
+   * permission referencing it across all chains and delegators.
    *
-   * @returns The count as a bigint.
+   * @throws if reading the signer address fails. {@link SigningFailedError}
    */
-  getTokenPairsLength(): Promise<bigint>;
+  clearCredentials(): Promise<void>;
   /**
-   * Fetch a range of token wrapper pairs (paginated by index).
+   * Warm the signer transport key pair cache for a known address.
    *
-   * @param fromIndex - Start index (inclusive).
-   * @param toIndex - End index (exclusive).
-   * @returns The slice of `TokenWrapperPair` entries.
+   * 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.
    */
-  getTokenPairsSlice(fromIndex: bigint, toIndex: bigint): Promise<readonly TokenWrapperPair[]>;
+  warmTransportKeyPair(address: Address): Promise<void>;
   /**
-   * Fetch a single token wrapper pair by index.
+   * Apply a wallet account transition.
    *
-   * @param index - Zero-based pair index.
-   * @returns The `TokenWrapperPair` at that index.
+   * 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`.
    */
-  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>;
+  handleWalletAccountChange(prev?: {
+    address: Address;
+  }, next?: {
+    address: Address;
+  }): Promise<void>;
 }
-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
 /**
@@ -19588,1283 +19340,1163 @@ 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/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/delegation-service.d.ts
+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>;
+  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/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>;
+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
 /**
- * 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>;
+  /** @internal */
+  constructor(opts: {
+    signer: GenericSigner | undefined;
+    provider: GenericProvider;
+    router: ChainRouter;
+    decryptionService: DecryptionService | undefined;
+  });
   /**
-   * ERC-165 check for IERC7984ERC20Wrapper support.
+   * Decrypt one or more FHE encrypted values. Results are cached — repeated calls
+   * for the same encrypted value skip the relayer round-trip.
    *
-   * @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.
+   * 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 decrypted plaintext balance as a bigint.
-   * @throws if FHE decryption fails. {@link DecryptionFailedError}
+   * @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 balance = await token.balanceOf("0xOwner");
+   * const values = await sdk.decryption.decryptValues([
+   *   { encryptedValue: balance, contractAddress: cUSDT },
+   * ]);
+   * console.log(values[balance]); // 1000n
    * ```
    */
-  balanceOf(owner: Address): Promise<bigint>;
+  decryptValues(encryptedInput: EncryptedInput[], options?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<Record<EncryptedValue, ClearValue>>;
   /**
-   * Return the raw encrypted balance without decrypting.
+   * Decrypt one or more FHE encrypted values using delegated credentials.
    *
-   * @param owner - Balance owner address.
-   * @returns The encrypted balance as a hex string.
+   * 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.
    *
    * @example
    * ```ts
-   * const encryptedValue = await token.confidentialBalanceOf("0xOwner");
-   * ```
-   */
-  confidentialBalanceOf(owner: Address): Promise<EncryptedValue>;
-  /**
-   * 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.
-   *
-   * 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 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 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/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;
+  /** @internal */
+  constructor(opts: {
+    signer: GenericSigner | undefined;
+    provider: GenericProvider;
+    delegationService: DelegationService;
+  });
   /**
-   * 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);
-   * ```
-   */
-  confidentialTransfer(to: Address, amount: bigint, options?: TransferOptions): Promise<TransactionResult>;
-  /**
-   * Operator encrypted transfer on behalf of another address.
-   * The caller must be an approved operator for `from`.
-   *
-   * @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 txHash = await token.confidentialTransferFrom("0xFrom", "0xTo", 500n);
-   * ```
+   * @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}
    */
-  confidentialTransferFrom(from: Address, to: Address, amount: bigint, callbacks?: TransferCallbacks): Promise<TransactionResult>;
+  delegateDecryption({ contractAddress, delegateAddress, expirationDate }: {
+    contractAddress: Address;
+    delegateAddress: Address;
+    expirationDate?: Date;
+  }): Promise<TransactionResult>;
   /**
-   * 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.
-   *
-   * Balance validation follows the same rules as {@link Token.confidentialTransfer}.
+   * Revoke decryption delegation for a confidential contract.
+   * Calls `ACL.revokeDelegationForUserDecryption()` on-chain.
    *
-   * @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`).
+   * @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 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.confidentialTransferAndCall(
-   *   "0xRecipient",
-   *   1000n,
-   *   "0xabcd", // caller-encoded payload forwarded to the receiver hook
-   * );
-   * ```
+   * @throws if no delegation exists for this (delegator, delegate, contract) tuple. {@link DelegationNotFoundError}
+   * @throws if the revocation transaction reverts. {@link TransactionRevertedError}
    */
-  confidentialTransferAndCall(to: Address, amount: bigint, data: Hex, options?: TransferOptions): Promise<TransactionResult>;
+  revokeDelegation({ contractAddress, delegateAddress }: {
+    contractAddress: Address;
+    delegateAddress: Address;
+  }): Promise<TransactionResult>;
   /**
-   * 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.
+   * Check whether a delegation is active for the given contract address.
    *
-   * @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.
+   * Signer-independent: works without a configured signer.
    *
-   * @example
-   * ```ts
-   * const txHash = await token.confidentialTransferFromAndCall(
-   *   "0xFrom",
-   *   "0xRecipient",
-   *   500n,
-   *   "0xabcd",
-   * );
-   * ```
+   * @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.
    */
-  confidentialTransferFromAndCall(from: Address, to: Address, amount: bigint, data: Hex, callbacks?: TransferCallbacks): Promise<TransactionResult>;
+  isActive(params: {
+    contractAddress: Address;
+    delegatorAddress: Address;
+    delegateAddress: Address;
+  }): Promise<boolean>;
   /**
-   * Set operator approval for the confidential token.
-   * Defaults to 1 hour from now if `until` is not specified.
+   * Get the expiration timestamp of a delegation for the given contract.
    *
-   * @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.
+   * Signer-independent: works without a configured signer.
    *
-   * @example
-   * ```ts
-   * const txHash = await token.setOperator("0xOperator");
-   * ```
+   * @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.
    */
-  setOperator(operator: Address, until?: number): Promise<TransactionResult>;
+  getExpiry(params: {
+    contractAddress: Address;
+    delegatorAddress: Address;
+    delegateAddress: Address;
+  }): Promise<bigint>;
+}
+//#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).
+ */
+declare class Permits {
+  #private;
+  /** @internal */
+  constructor(opts: {
+    signer: GenericSigner | undefined;
+    provider: GenericProvider;
+    cachingService: CachingService;
+    credentialService: CredentialService | undefined;
+    logger: GenericLogger;
+  });
   /**
-   * Check if a spender is an approved operator for a given holder.
+   * Sign and store an EIP-712 permit authorising direct decryption for the
+   * given contract addresses.
    *
-   * @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.
+   * 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
-   * if (await token.isOperator("0xHolder", "0xSpender")) {
-   *   // spender can call transferFrom on behalf of holder
-   * }
-   * ```
+   * @param contracts - Contract addresses to authorize.
    */
-  isOperator(holder: Address, spender: Address): Promise<boolean>;
+  grantPermit(contracts: Address[]): Promise<void>;
   /**
-   * Read the on-chain encrypted balance for a given owner.
+   * Sign and store an EIP-712 delegation permit authorising decryption on
+   * behalf of `delegator`. Same idempotence/chunking semantics as {@link grantPermit}.
    *
-   * @internal
+   * @param delegator - The address that delegated decryption rights to the connected signer.
+   * @param contracts - Contract addresses to authorize.
    */
-  protected readConfidentialBalanceOf(owner: Address): Promise<EncryptedValue>;
+  grantDelegationPermit(delegator: Address, contracts: Address[]): 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.
+   * 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}.
    *
-   * @internal
+   * @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.
    */
-  protected assertConfidentialBalance(amount: bigint): Promise<void>;
+  hasDelegationPermit(delegator: Address, contracts: Address[]): Promise<boolean>;
   /**
-   * Emit a token-scoped event through the owning {@link ZamaSDK} so that
-   * subscribers see a unified stream.
+   * Best-effort transport-key-pair prefetch for the connected signer.
    *
-   * @internal
+   * 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.
    */
-  protected emit(input: ZamaSDKEventInput): void;
+  warmTransportKeyPair(): Promise<void>;
   /**
-   * Submit a token-scoped write transaction through the shared SDK transaction
-   * pipeline. Callers keep pre-flight and operation-specific work local.
+   * Wipe FHE permits for the current signer.
    *
-   * @internal
+   * - 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.
+   *
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
    */
-  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;
+  revokePermits(contracts?: Address[]): Promise<void>;
+  /**
+   * Wipe the transport key pair for the current signer and cascade-delete every permit
+   * (across chains and delegators) referencing it.
+   *
+   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   */
+  clear(): Promise<void>;
 }
 //#endregion
-//#region src/token/wrapped-token.d.ts
+//#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[];
+  /**
+   * 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.
+   */
+  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>;
+}
 /**
- * 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;
+  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>;
   /**
-   * Read the underlying ERC-20 token address from the wrapper contract.
+   * ERC-165 check for {@link ERC7984_INTERFACE_ID} support.
    *
-   * @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.
+   * @returns `true` if the contract implements the ERC-7984 confidential token interface.
    */
-  isPayable(): Promise<boolean>;
+  isConfidential(): Promise<boolean>;
   /**
-   * Read the ERC-20 allowance granted by `owner` to this wrapper for the
-   * underlying token.
+   * ERC-165 check for IERC7984ERC20Wrapper 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 wrapper interface
+   *   ({@link ERC7984_WRAPPER_INTERFACE_ID}, `0x1f1c62b2`).
    */
-  allowance(owner: Address): Promise<bigint>;
+  isWrapper(): 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.
+   * 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 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}
+   * @param owner - Balance owner address.
+   * @returns The decrypted plaintext balance as a bigint.
+   * @throws if FHE decryption fails. {@link DecryptionFailedError}
    *
    * @example
    * ```ts
-   * const txHash = await wrappedToken.shield(1000n);
+   * const balance = await token.balanceOf("0xOwner");
    * ```
    */
-  shield(amount: bigint, options?: ShieldOptions): 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`.
    *
-   * @param callbacks - Optional progress callbacks for each phase.
-   * @returns The finalize transaction hash and mined receipt.
-   * @throws if the balance is zero. {@link DecryptionFailedError}
+   * Tokens that fail to decrypt land in `errors` rather than aborting the
+   * whole batch — caller decides how to surface them.
+   *
+   * @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.
-   * Call {@link finalizeUnwrap} after 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).
+   * @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 txHash = await wrappedToken.unwrap(500n);
+   * const txHash = await token.confidentialTransferFrom("0xFrom", "0xTo", 500n);
    * ```
    */
-  unwrap(amount: bigint): Promise<TransactionResult>;
+  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.
    *
+   * 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 the balance is zero. {@link DecryptionFailedError}
+   *
+   * @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 wrappedToken.unwrapAll();
+   * const txHash = await token.confidentialTransferAndCall(
+   *   "0xRecipient",
+   *   1000n,
+   *   "0xabcd", // caller-encoded payload forwarded to the receiver hook
+   * );
    * ```
    */
-  unwrapAll(): Promise<TransactionResult>;
+  confidentialTransferAndCall(to: Address, amount: bigint, data: Hex, options?: TransferOptions): Promise<TransactionResult>;
   /**
-   * Complete an unwrap by providing the public decryption proof.
-   * Call this after an unshield 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 - `unwrapRequestId` from the `UnwrapRequested` event.
+   * @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 event = findUnwrapRequested(receipt.logs);
-   * const txHash = await wrappedToken.finalizeUnwrap(event.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, TransactionResult>;
-//#endregion
-//#region src/query/unwrap-all.d.ts
-declare function unwrapAllMutationOptions(token: WrappedToken): MutationFactoryOptions<readonly ["zama.unwrapAll", Address], void, TransactionResult>;
-//#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/query/delegation-status.d.ts
-interface DelegationStatusData {
-  isActive: boolean;
-  expiryTimestamp: bigint;
-}
-interface DelegationStatusQueryConfig {
-  contractAddress: Address | undefined;
-  delegatorAddress?: Address;
-  delegateAddress?: Address;
-  query?: Record<string, unknown>;
-}
-declare function delegationStatusQueryOptions(sdk: ZamaSDK, config: DelegationStatusQueryConfig): QueryFactoryOptions<DelegationStatusData, Error, DelegationStatusData, 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;
-}
-/**
- * Single facade coordinating the keypair vault and the permission store.
- *
- * `CredentialService` is the only credentials object held by `ZamaSDK`. It accepts identity
- * transitions via `handleWalletAccountChange`.
- */
-declare class CredentialService {
-  #private;
-  constructor(config: CredentialServiceConfig);
+  confidentialTransferFromAndCall(from: Address, to: Address, amount: bigint, data: Hex, callbacks?: TransferCallbacks): Promise<TransactionResult>;
   /**
-   * 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.
+   * Set operator approval for the confidential token.
+   * Defaults to 1 hour from now if `until` is not specified.
    *
-   * @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}
-   */
-  grantPermit(contracts: readonly Address[], delegator?: Address): Promise<SerializedTransportKeyPairWithPermissions>;
-  /**
-   * Pure store lookup: are stored permits sufficient to cover `contracts`? No wallet prompt.
+   * @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.
    *
-   * @returns `true` if cached permits cover all requested contracts (vacuously
-   *   true for an empty list); `false` if no keypair exists or coverage is
-   *   incomplete.
+   * @example
+   * ```ts
+   * const txHash = await token.setOperator("0xOperator");
+   * ```
    */
-  hasPermit(contracts: readonly Address[], delegator?: Address): Promise<boolean>;
+  setOperator(operator: Address, until?: number): Promise<TransactionResult>;
   /**
-   * Wipe FHE permits for the current signer.
+   * Check if a spender is an approved operator for a given holder.
    *
-   * - 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.
+   * @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.
    *
-   * @throws if reading the signer address fails. {@link SigningFailedError}
+   * @example
+   * ```ts
+   * if (await token.isOperator("0xHolder", "0xSpender")) {
+   *   // spender can call transferFrom on behalf of holder
+   * }
+   * ```
    */
-  revokePermits(contracts?: readonly Address[]): Promise<void>;
+  isOperator(holder: Address, spender: Address): Promise<boolean>;
   /**
-   * Wipe the keypair for the current signer and cascade-delete every
-   * permission referencing it across all chains and delegators.
+   * Read the on-chain encrypted balance for a given owner.
    *
-   * @throws if reading the signer address fails. {@link SigningFailedError}
+   * @internal
    */
-  clearCredentials(): Promise<void>;
+  protected readConfidentialBalanceOf(owner: Address): Promise<EncryptedValue>;
   /**
-   * Warm the signer transport key pair cache for a known address.
+   * 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.
    *
-   * 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.
+   * @internal
    */
-  warmTransportKeyPair(address: Address): Promise<void>;
+  protected assertConfidentialBalance(amount: bigint): Promise<void>;
   /**
-   * Apply a wallet account transition.
+   * Emit a token-scoped event through the owning {@link ZamaSDK} so that
+   * subscribers see a unified stream.
    *
-   * 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`.
+   * @internal
    */
-  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/delegation-service.d.ts
-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>;
-  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/services/decryption-service.d.ts
-/** Options shared by the delegated-decrypt entry points. */
-interface DelegatedDecryptOptions {
+  protected emit(input: ZamaSDKEventInput): void;
   /**
-   * 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.
+   * Submit a token-scoped write transaction through the shared SDK transaction
+   * pipeline. Callers keep pre-flight and operation-specific work local.
+   *
+   * @internal
    */
-  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>;
+  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;
 }
 //#endregion
-//#region src/namespaces/decryption.d.ts
+//#region src/token/wrapped-token.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`.
+ * Confidential ERC-20 wrapper (ERC-7984 ERC20Wrapper).
  *
- * **Mixed signer requirement:** `decryptValues` and
- * `delegatedDecryptValues` need a configured signer; `decryptPublicValues`
- * does not. Each method documents its requirement in its JSDoc.
+ * 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
  *
- * **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.
+ * `WrappedToken.address` is the wrapper contract address itself — the wrapper
+ * IS the confidential token.
  */
-declare class Decryption {
+declare class WrappedToken extends Token {
   #private;
-  /** @internal */
-  constructor(opts: {
-    signer: GenericSigner | undefined;
-    provider: GenericProvider;
-    router: ChainRouter;
-    decryptionService: DecryptionService | undefined;
-  });
   /**
-   * Decrypt one or more FHE encrypted values. Results are cached — repeated calls
-   * for the same encrypted value skip the relayer round-trip.
+   * 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.
+   *
+   * @param owner - The owner address whose allowance to read.
+   * @returns The current allowance as a bigint.
+   */
+  allowance(owner: Address): Promise<bigint>;
+  /**
+   * 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}
+   *
+   * @example
+   * ```ts
+   * const txHash = await wrappedToken.shield(1000n);
+   * ```
+   */
+  shield(amount: bigint, options?: ShieldOptions): Promise<TransactionResult>;
+  /**
+   * 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).
    *
-   * 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 amount - Optional approval amount. Defaults to max uint256.
+   * @returns The transaction hash and mined receipt.
    *
-   * @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
+   * await wrappedToken.approveUnderlying(); // max approval
+   * await wrappedToken.approveUnderlying(1000n); // exact amount
+   * ```
+   */
+  approveUnderlying(amount?: bigint): Promise<TransactionResult>;
+  /**
+   * Unshield a specific amount and finalize in one call.
+   * Orchestrates: unshield → wait for receipt → parse event → finalize.
+   *
+   * 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 values = await sdk.decryption.decryptValues([
-   *   { encryptedValue: balance, contractAddress: cUSDT },
-   * ]);
-   * console.log(values[balance]); // 1000n
+   * const txHash = await wrappedToken.unshield(500n);
    * ```
    */
-  decryptValues(encryptedInput: EncryptedInput[], options?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<Record<EncryptedValue, ClearValue>>;
+  unshield(amount: bigint, options?: UnshieldOptions): Promise<TransactionResult>;
   /**
-   * Decrypt one or more FHE encrypted values using delegated credentials.
+   * Unshield the entire balance and finalize in one call.
+   * Orchestrates: unshieldAll → wait for receipt → parse event → finalize.
    *
-   * 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 callbacks - Optional progress callbacks for each phase.
+   * @returns The finalize transaction hash and mined receipt.
+   * @throws if the balance is zero. {@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 txHash = await wrappedToken.unshieldAll();
+   * ```
+   */
+  unshieldAll(callbacks?: UnshieldCallbacks): Promise<TransactionResult>;
+  /**
+   * 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 values = await sdk.decryption.delegatedDecryptValues([
-   *   { encryptedValue: balance, contractAddress: tokenAddr },
-   * ], delegatorAddr);
-   * console.log(values[balance]); // 1000n
+   * const txHash = await wrappedToken.resumeUnshield(previousUnwrapTxHash);
    * ```
    */
-  delegatedDecryptValues(encryptedInputs: EncryptedInput[], delegatorAddress: Address, accountAddress?: Address, options?: DelegatedDecryptOptions): Promise<Record<EncryptedValue, ClearValue>>;
+  resumeUnshield(unwrapTxHash: Hex, callbacks?: UnshieldCallbacks): Promise<TransactionResult>;
   /**
-   * Publicly decrypt one or more FHE encrypted values.
+   * Return the unwrap tx hash of an unshield that was interrupted between its
+   * two phases, or `null` if none is pending for this wrapper.
    *
-   * 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`).
+   * 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 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 pending unwrap tx hash, or `null`.
    *
    * @example
    * ```ts
-   * const { clearValues, decryptionProof, abiEncodedClearValues } =
-   *   await sdk.decryption.decryptPublicValues([encryptedValue]);
+   * const unwrapTxHash = await wrappedToken.getPendingUnshield();
+   * if (unwrapTxHash) await wrappedToken.resumeUnshield(unwrapTxHash);
    * ```
    */
-  decryptPublicValues(encryptedValues: EncryptedValue[], options?: Pick<FhevmRelayerOptions, "signal" | "timeout">): Promise<DecryptPublicValuesResult>;
+  getPendingUnshield(): Promise<Hex | null>;
   /**
-   * Batch-decrypt delegated encrypted values with per-entry error isolation.
+   * 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.
    *
-   * 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 amount - The plaintext amount to unwrap (encrypted automatically).
+   * @returns The tx hash, mined receipt, and the `unwrapRequestId` for `finalizeUnwrap`.
    *
-   * @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 result = await wrappedToken.unwrap(500n);
+   * await wrappedToken.finalizeUnwrap(result.unwrapRequestId);
+   * ```
+   */
+  unwrap(amount: bigint): Promise<UnwrapResult>;
+  /**
+   * Request an unwrap for the entire confidential balance.
+   * Uses the on-chain encrypted balance directly (no encryption needed).
+   * Throws if the balance is zero.
+   *
+   * @returns The tx hash, mined receipt, and the `unwrapRequestId` for `finalizeUnwrap`.
+   * @throws if the balance is zero. {@link DecryptionFailedError}
    *
    * @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 result = await wrappedToken.unwrapAll();
+   * await wrappedToken.finalizeUnwrap(result.unwrapRequestId);
    * ```
    */
-  delegatedBatchDecryptValues({ encryptedInputs, delegatorAddress, accountAddress, maxConcurrency, waitForPropagation }: {
-    encryptedInputs: EncryptedInput[];
-    delegatorAddress: Address;
-    accountAddress?: Address;
-    maxConcurrency?: number;
-  } & DelegatedDecryptOptions): Promise<BatchDecryptResult>;
+  unwrapAll(): Promise<UnwrapResult>;
+  /**
+   * Complete an unwrap by fetching the public decryption proof and finalizing.
+   * Call this once the unwrap request has been processed on-chain.
+   *
+   * @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 { unwrapRequestId } = await wrappedToken.unwrap(500n);
+   * await wrappedToken.finalizeUnwrap(unwrapRequestId);
+   * ```
+   */
+  finalizeUnwrap(unwrapRequestId: EncryptedValue): Promise<TransactionResult>;
 }
 //#endregion
-//#region src/namespaces/delegations.d.ts
+//#region src/wrappers-registry.d.ts
 /**
- * Public namespace for on-chain decryption-delegation management.
+ * Default wrappers registry addresses for known chains.
+ * Only includes chains where a registry is deployed (excludes Hardhat).
  *
- * 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}.
+ * @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;
+}
+/**
+ * High-level interface for the on-chain token wrappers registry.
  *
- * 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.
+ * 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 Delegations {
+declare class WrappersRegistry {
   #private;
-  /** @internal */
-  constructor(opts: {
-    signer: GenericSigner | undefined;
-    provider: GenericProvider;
-    delegationService: DelegationService;
-  });
+  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;
   /**
-   * 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}
+   * The cache TTL in milliseconds.
+   * Exposed so query option factories can set a matching `staleTime`.
    */
-  delegateDecryption({ contractAddress, delegateAddress, expirationDate }: {
-    contractAddress: Address;
-    delegateAddress: Address;
-    expirationDate?: Date;
-  }): Promise<TransactionResult>;
+  get ttlMs(): number;
   /**
-   * Revoke decryption delegation for a confidential contract.
-   * Calls `ACL.revokeDelegationForUserDecryption()` on-chain.
+   * Resolve the registry contract address for the current 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}
+   * 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}
    */
-  revokeDelegation({ contractAddress, delegateAddress }: {
-    contractAddress: Address;
-    delegateAddress: Address;
-  }): Promise<TransactionResult>;
+  getRegistryAddress(): Promise<Address>;
   /**
-   * Check whether a delegation is active for the given contract address.
+   * List token wrapper pairs with page-based pagination.
    *
-   * Signer-independent: works without a configured signer.
+   * Internally maps to `getTokenConfidentialTokenPairsSlice` on-chain.
    *
-   * @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.
+   * @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);
+   * }
+   * ```
    */
-  isActive(params: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<boolean>;
+  listPairs(options: ListPairsOptions & {
+    metadata: true;
+  }): Promise<PaginatedResult<TokenWrapperPairWithMetadata>>;
+  listPairs(options?: ListPairsOptions): Promise<PaginatedResult<TokenWrapperPair>>;
   /**
-   * Get the expiration timestamp of a delegation for the given contract.
+   * Look up the confidential token for a given plain ERC-20 address.
    *
-   * Signer-independent: works without a configured signer.
+   * @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.
    *
-   * @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.
+   * @example
+   * ```ts
+   * const result = await registry.getConfidentialToken(usdcAddress);
+   * if (result?.isValid) {
+   *   console.log(result.confidentialTokenAddress);
+   * }
+   * ```
    */
-  getExpiry(params: {
-    contractAddress: Address;
-    delegatorAddress: Address;
-    delegateAddress: Address;
-  }): Promise<bigint>;
-}
-//#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).
- */
-declare class Permits {
-  #private;
-  /** @internal */
-  constructor(opts: {
-    signer: GenericSigner | undefined;
-    provider: GenericProvider;
-    cachingService: CachingService;
-    credentialService: CredentialService | undefined;
-    logger: GenericLogger;
-  });
+  getConfidentialToken(tokenAddress: Address): Promise<{
+    confidentialTokenAddress: Address;
+    isValid: boolean;
+  } | null>;
   /**
-   * Sign and store an EIP-712 permit authorising direct decryption for the
-   * given contract addresses.
+   * Reverse lookup — find the plain ERC-20 for a given confidential token.
    *
-   * 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 confidentialTokenAddress - The confidential token address.
+   * @returns The lookup result, or `null` if no pair is registered.
    *
-   * @param contracts - Contract addresses to authorize.
+   * @example
+   * ```ts
+   * const result = await registry.getUnderlyingToken(cUsdcAddress);
+   * if (result) {
+   *   console.log(result.tokenAddress, result.isValid);
+   * }
+   * ```
    */
-  grantPermit(contracts: Address[]): Promise<void>;
+  getUnderlyingToken(confidentialTokenAddress: Address): Promise<{
+    tokenAddress: Address;
+    isValid: boolean;
+  } | null>;
   /**
-   * Sign and store an EIP-712 delegation permit authorising decryption on
-   * behalf of `delegator`. Same idempotence/chunking semantics as {@link grantPermit}.
+   * Fetch all token wrapper pairs from the registry.
    *
-   * @param delegator - The address that delegated decryption rights to the connected signer.
-   * @param contracts - Contract addresses to authorize.
+   * @returns All registered `TokenWrapperPair` entries.
    */
-  grantDelegationPermit(delegator: Address, contracts: Address[]): Promise<void>;
+  getTokenPairs(): Promise<readonly TokenWrapperPair[]>;
   /**
-   * Pure store lookup: is there a permit covering `contracts`?
-   * No wallet prompt, no transport key pair generation. Returns `false` when no signer
-   * is configured.
+   * Get the total number of token wrapper pairs.
+   *
+   * @returns The count as a bigint.
    */
-  hasPermit(contracts: Address[]): Promise<boolean>;
+  getTokenPairsLength(): Promise<bigint>;
   /**
-   * Pure store lookup for a delegation permit. See {@link hasPermit}.
+   * Fetch a range of token wrapper pairs (paginated by index).
    *
-   * @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.
+   * @param fromIndex - Start index (inclusive).
+   * @param toIndex - End index (exclusive).
+   * @returns The slice of `TokenWrapperPair` entries.
    */
-  hasDelegationPermit(delegator: Address, contracts: Address[]): Promise<boolean>;
+  getTokenPairsSlice(fromIndex: bigint, toIndex: bigint): Promise<readonly TokenWrapperPair[]>;
   /**
-   * 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.
+   * Fetch a single token wrapper pair by index.
    *
-   * 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 index - Zero-based pair index.
+   * @returns The `TokenWrapperPair` at that index.
    */
-  warmTransportKeyPair(): Promise<void>;
+  getTokenPair(index: bigint): Promise<TokenWrapperPair>;
   /**
-   * Wipe FHE permits for the current signer.
+   * Look up the confidential token address for a given plain ERC-20 token.
    *
-   * - 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 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.
    *
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @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.
    */
-  revokePermits(contracts?: Address[]): Promise<void>;
+  getTokenAddress(confidentialTokenAddress: Address): Promise<readonly [boolean, Address]>;
   /**
-   * Wipe the transport key pair for the current signer and cascade-delete every permit
-   * (across chains and delegators) referencing it.
+   * Check whether a confidential token is registered and valid.
    *
-   * @throws if no signer is configured. {@link SignerNotConfiguredError}
+   * @param confidentialTokenAddress - The confidential token address to check.
+   * @returns `true` if the token is a known valid wrapper in the registry.
    */
-  clear(): Promise<void>;
+  isConfidentialTokenValid(confidentialTokenAddress: Address): Promise<boolean>;
 }
 //#endregion
 //#region src/zama-sdk.d.ts
@@ -21025,5 +20657,74 @@ declare class ZamaSDK {
   [Symbol.dispose](): void;
 }
 //#endregion
-export { confidentialTransferMutationOptions as $, TokenWrapperPairWithMetadata as $n, DelegationSelfNotAllowedError as $t, encryptMutationOptions as A, tokenMetadataQueryOptions as An, isOperatorContract as Ar, SignerRequiredError as At, UnshieldParams as B, invalidateAfterUnwrap as Bn, createConfig as Br, InsufficientConfidentialBalanceError as Bt, grantPermitMutationOptions as C, TotalSupplyQueryConfig as Cn, symbolContract as Cr, BatchDecryptAsOptions as Ct, DecryptResult as D, isWrapperQueryOptions as Dn, confidentialTransferFromContract as Dr, SigningFailedError as Dt, delegatedDecryptValuesMutationOptions as E, isConfidentialQueryOptions as En, confidentialTransferContract as Er, TransactionRevertedError as Et, unwrapMutationOptions as F, invalidateAfterSetOperator as Fn, unwrapFromBalanceContract as Fr, ConfigurationError as Ft, confidentialSetOperatorMutationOptions as G, SignerQueryContext as Gn, DelegationContractIsSelfError as Gt, ApproveUnderlyingParams as H, invalidateWagmiBalanceQueries as Hn, DecryptionFailedError as Ht, ResumeUnshieldParams as I, invalidateAfterShield as In, wrapContract as Ir, RelayerRequestFailedError as It, ConfidentialTransferFromParams as J, StrippedQueryOptionKeys as Jn, DelegationExpirationTooSoonError as Jt, ConfidentialTransferFromAndCallParams as K, MutationFactoryOptions as Kn, DelegationCooldownError as Kt, resumeUnshieldMutationOptions as L, invalidateAfterTransfer as Ln, ResolvedChainRelayer as Lr, BalanceCheckUnavailableError as Lt, finalizeUnwrapMutationOptions as M, QueryFilterLike as Mn, setOperatorContract as Mr, WalletNotConnectedError as Mt, unwrapAllMutationOptions as N, QueryLike as Nn, underlyingContract as Nr, RpcRateLimitError as Nt, EncryptedInput as O, TokenMetadata as On, finalizeUnwrapContract as Or, SigningRejectedError as Ot, UnwrapParams as P, invalidateAfterApproveUnderlying as Pn, unwrapContract as Pr, NotEntitledError as Pt, ConfidentialTransferParams as Q, TokenWrapperPair as Qn, DelegationNotPropagatedError as Qt, UnshieldAllParams as R, invalidateAfterUnshield as Rn, resolveChainRelayers as Rr, BalanceErrorDetails as Rt, hasPermitQueryOptions as S, StoredTransportKeyPair as Sn, nameContract as Sr, BatchBalancesResult as St, DelegatedDecryptValuesMutationParams as T, IsConfidentialQueryConfig as Tn, confidentialTotalSupplyContract as Tr, matchZamaError as Tt, approveUnderlyingMutationOptions as U, invalidateWalletLifecycleQueries as Un, EncryptionFailedError as Ut, unshieldMutationOptions as V, invalidateBalanceQueries as Vn, InsufficientERC20BalanceError as Vt, ConfidentialSetOperatorParams as W, zamaQueryKeys as Wn, AclPausedError as Wt, ConfidentialTransferAndCallParams as X, hashFn as Xn, DelegationExpiryUnchangedError as Xt, confidentialTransferFromMutationOptions as Y, filterQueryOptions as Yn, DelegationExpiredError as Yt, confidentialTransferAndCallMutationOptions as Z, PaginatedResult as Zn, DelegationNotFoundError as Zt, DelegateDecryptionParams as _, ListPairsOptions as _n, supportsInterfaceContract as _r, ConfidentialBalancesQueryConfig as _t, BatchDecryptItem as a, ZamaErrorCode as an, getTokenPairsSliceContract as ar, TokenAddressQueryConfig as at, revokePermitsMutationOptions as b, Permission as bn, balanceOfContract as br, confidentialBalanceQueryOptions as bt, DelegationStatusData as c, ConfidentialIsOperatorQueryConfig as cn, getDelegationExpiryContract as cr, WrappersRegistryQueryConfig as ct, RevokeDelegationParams as d, pendingUnshieldQueryOptions as dn, transferAndCallContract as dr, listPairsQueryOptions as dt, InvalidTransportKeyPairError as en, getConfidentialTokenAddressContract as er, ShieldParams as et, revokeDelegationMutationOptions as f, UnderlyingAllowanceQueryConfig as fn, ERC1363_INTERFACE_ID as fr, tokenAddressQueryOptions as ft, decryptBalanceAsMutationOptions as g, DefaultRegistryAddresses as gn, isConfidentialWrapperContract as gr, tokenPairsSliceQueryOptions as gt, DecryptBalanceAsParams as h, wrapperDiscoveryQueryOptions as hn, isConfidentialTokenContract as hr, tokenPairsQueryOptions as ht, Decryption as i, ZamaError as in, getTokenPairsLengthContract as ir, ListPairsQueryConfig as it, FinalizeUnwrapParams as j, QueryClientLike as jn, rateContract as jr, WalletAccountNotReadyError as jt, decryptValuesQueryOptions as k, TokenMetadataQueryConfig as kn, inferredTotalSupplyContract as kr, SignerNotConfiguredError as kt, DelegationStatusQueryConfig as l, confidentialIsOperatorQueryOptions as ln, isHandleDelegatedContract as lr, confidentialTokenAddressQueryOptions as lt, batchDecryptBalancesAsMutationOptions as m, WrapperDiscoveryQueryConfig as mn, ERC7984_WRAPPER_INTERFACE_ID as mr, tokenPairsLengthQueryOptions as mt, Permits as n, TransportKeyPairExpiredError as nn, getTokenPairContract as nr, ConfidentialTokenAddressQueryConfig as nt, BatchDecryptResult as o, isRetryable as on, isConfidentialTokenValidContract as or, TokenPairQueryConfig as ot, BatchDecryptBalancesAsParams as p, underlyingAllowanceQueryOptions as pn, ERC7984_INTERFACE_ID as pr, tokenPairQueryOptions as pt, confidentialTransferFromAndCallMutationOptions as q, QueryFactoryOptions as qn, DelegationDelegateEqualsContractError as qt, Delegations as r, ChainMismatchError as rn, getTokenPairsContract as rr, IsConfidentialTokenValidQueryConfig as rt, DelegatedDecryptOptions as s, retryAfterSeconds as sn, delegateForUserDecryptionContract as sr, TokenPairsSliceQueryConfig as st, ZamaSDK as t, NoCiphertextError as tn, getTokenAddressContract as tr, shieldMutationOptions as tt, delegationStatusQueryOptions as u, PendingUnshieldQueryConfig as un, revokeDelegationContract as ur, isConfidentialTokenValidQueryOptions as ut, delegateDecryptionMutationOptions as v, WrappersRegistry as vn, allowanceContract as vr, confidentialBalancesQueryOptions as vt, decryptPublicValuesMutationOptions as w, totalSupplyQueryOptions as wn, confidentialBalanceOfContract as wr, Token as wt, HasPermitQueryConfig as x, SerializedTransportKeyPair as xn, decimalsContract as xr, WrappedToken as xt, clearCredentialsMutationOptions as y, WrappersRegistryConfig as yn, approveContract as yr, ConfidentialBalanceQueryConfig as yt, unshieldAllMutationOptions as z, invalidateAfterUnshieldSettled as zn, resolveStorage as zr, ERC20ReadFailedError as zt };
-//# sourceMappingURL=zama-sdk-aaLl2ZlA.d.ts.map
+//#region src/utils/handles.d.ts
+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;
+  get<T = unknown>(key: string): Promise<T | null>;
+  set<T = unknown>(key: string, value: T): Promise<void>;
+  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);
+  get<T = unknown>(key: string): Promise<T | null>;
+  set<T = unknown>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  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 {
+  get<T = unknown>(key: string): Promise<T | null>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+/** Default singleton for application-wide use. */
+declare const chromeSessionStorage: ChromeSessionStorage;
+//#endregion
+export { DelegationNotPropagatedError as $, rateContract as $t, SignerNotConfiguredError as A, getDelegationExpiryContract as At, ERC20ReadFailedError as B, allowanceContract as Bt, BatchDecryptItem as C, getTokenAddressContract as Ct, TransactionRevertedError as D, getTokenPairsSliceContract as Dt, matchZamaError as E, getTokenPairsLengthContract as Et, NotEntitledError as F, ERC7984_INTERFACE_ID as Ft, AclPausedError as G, symbolContract as Gt, InsufficientERC20BalanceError as H, balanceOfContract as Ht, ConfigurationError as I, ERC7984_WRAPPER_INTERFACE_ID as It, DelegationDelegateEqualsContractError as J, confidentialTransferContract as Jt, DelegationContractIsSelfError as K, confidentialBalanceOfContract as Kt, RelayerRequestFailedError as L, isConfidentialTokenContract as Lt, WalletAccountNotReadyError as M, revokeDelegationContract as Mt, WalletNotConnectedError as N, transferAndCallContract as Nt, SigningFailedError as O, isConfidentialTokenValidContract as Ot, RpcRateLimitError as P, ERC1363_INTERFACE_ID as Pt, DelegationNotFoundError as Q, isOperatorContract as Qt, BalanceCheckUnavailableError as R, isConfidentialWrapperContract as Rt, Decryption as S, getConfidentialTokenAddressContract as St, DelegatedDecryptOptions as T, getTokenPairsContract as Tt, DecryptionFailedError as U, decimalsContract as Ut, InsufficientConfidentialBalanceError as V, approveContract as Vt, EncryptionFailedError as W, nameContract as Wt, DelegationExpiredError as X, finalizeUnwrapContract as Xt, DelegationExpirationTooSoonError as Y, confidentialTransferFromContract as Yt, DelegationExpiryUnchangedError as Z, inferredTotalSupplyContract as Zt, BatchBalancesResult as _, MutationFactoryOptions as _t, IndexedDBStorage as a, ResolvedChainRelayer as an, ZamaError as at, Permits as b, TokenWrapperPair as bt, memoryStorage as c, createConfig as cn, retryAfterSeconds as ct, ZamaSDK as d, StoredTransportKeyPair as dt, setOperatorContract as en, DelegationSelfNotAllowedError as et, DefaultRegistryAddresses as f, DecryptResult as ft, WrappedToken as g, zamaQueryKeys as gt, WrappersRegistryConfig as h, SignerQueryContext as ht, chromeSessionStorage as i, wrapContract as in, ChainMismatchError as it, SignerRequiredError as j, isHandleDelegatedContract as jt, SigningRejectedError as k, delegateForUserDecryptionContract as kt, ZERO_ENCRYPTED_VALUE as l, Permission as lt, WrappersRegistry as m, decryptValuesQueryOptions as mt, Hex$1 as n, unwrapContract as nn, NoCiphertextError as nt, indexedDBStorage as o, resolveChainRelayers as on, ZamaErrorCode as ot, ListPairsOptions as p, EncryptedInput as pt, DelegationCooldownError as q, confidentialTotalSupplyContract as qt, ChromeSessionStorage as r, unwrapFromBalanceContract as rn, TransportKeyPairExpiredError as rt, MemoryStorage as s, resolveStorage as sn, isRetryable as st, Address$1 as t, underlyingContract as tn, InvalidTransportKeyPairError as tt, isEncryptedValueZero as u, SerializedTransportKeyPair as ut, BatchDecryptAsOptions as v, QueryFactoryOptions as vt, BatchDecryptResult as w, getTokenPairContract as wt, Delegations as x, TokenWrapperPairWithMetadata as xt, Token as y, PaginatedResult as yt, BalanceErrorDetails as z, supportsInterfaceContract as zt };
+//# sourceMappingURL=index-09tK1t8M.d.ts.map