@zama-fhe/sdk 1.0.0-alpha.10

package/dist/index.js

@@ -0,0 +1,3563 @@
+import { assertObject, assertString, assertArray, normalizeAddress, supportsInterfaceContract, ERC7984_INTERFACE_ID, ERC7984_WRAPPER_INTERFACE_ID, pLimit, wrapperExistsContract, getWrapperContract, underlyingContract, allowanceContract, nameContract, symbolContract, decimalsContract, confidentialBalanceOfContract, confidentialTransferContract, confidentialTransferFromContract, setOperatorContract, isOperatorContract, wrapContract, wrapETHContract, unwrapContract, unwrapFromBalanceContract, finalizeUnwrapContract, approveContract } from './chunk-PHE3BSIB.js';
+export { DEPLOYMENT_COORDINATOR_ABI, ENCRYPTION_ABI, ERC165_ABI, ERC20_ABI, ERC20_METADATA_ABI, ERC7984_INTERFACE_ID, ERC7984_WRAPPER_INTERFACE_ID, FEE_MANAGER_ABI, FHE_GAS_LIMIT, TRANSFER_BATCHER_ABI, WRAPPER_ABI, allowanceContract, approveContract, balanceOfContract, confidentialBalanceOfContract, confidentialBatchTransferContract, confidentialTotalSupplyContract, confidentialTransferContract, confidentialTransferFromContract, decimalsContract, deploymentCoordinatorContract, finalizeUnwrapContract, getBatchTransferFeeContract, getFeeRecipientContract, getUnwrapFeeContract, getWrapFeeContract, getWrapperContract, isConfidentialTokenContract, isConfidentialWrapperContract, isFinalizeUnwrapOperatorContract, isOperatorContract, nameContract, rateContract, setFinalizeUnwrapOperatorContract, setOperatorContract, supportsInterfaceContract, symbolContract, totalSupplyContract, underlyingContract, unwrapContract, unwrapFromBalanceContract, wrapContract, wrapETHContract, wrapperExistsContract } from './chunk-PHE3BSIB.js';
+import { BaseWorkerClient } from './chunk-WYWAO3QE.js';
+import { ZamaError, EncryptionFailedError, SigningRejectedError, SigningFailedError, DecryptionFailedError, NoCiphertextError, RelayerRequestFailedError, TransactionRevertedError, ApprovalFailedError } from './chunk-6JRD26PS.js';
+export { ApprovalFailedError, ConfigurationError, CredentialExpiredError, DecryptionFailedError, EncryptionFailedError, InvalidCredentialsError, NoCiphertextError, RelayerRequestFailedError, SigningFailedError, SigningRejectedError, TransactionRevertedError, ZamaError, ZamaErrorCode, matchZamaError } from './chunk-6JRD26PS.js';
+import { mergeFhevmConfig, buildEIP712DomainType, withRetry } from './chunk-5QJTGZHY.js';
+export { HardhatConfig, MainnetConfig, SepoliaConfig } from './chunk-5QJTGZHY.js';
+
+// src/worker/worker.client.ts
+var RelayerWorkerClient = class extends BaseWorkerClient {
+  constructor(config) {
+    super(config, config.logger);
+  }
+  createWorker() {
+    return new Worker(new URL("./relayer-sdk.worker.js", import.meta.url));
+  }
+  wireEvents(worker) {
+    worker.onmessage = (event) => this.handleResponse(event.data);
+    worker.onerror = (event) => this.handleWorkerError(event.message);
+    worker.onmessageerror = () => this.handleWorkerMessageError();
+  }
+  postMessage(worker, request) {
+    worker.postMessage(request);
+  }
+  terminateWorker(worker) {
+    worker.terminate();
+  }
+  generateRequestId() {
+    return crypto.randomUUID();
+  }
+  getInitPayload() {
+    return { type: "INIT", payload: this.config };
+  }
+  /**
+   * Update the CSRF token in the worker.
+   * Call this before making authenticated requests to ensure the token is fresh.
+   */
+  async updateCsrf(csrfToken) {
+    await this.sendRequest("UPDATE_CSRF", { csrfToken });
+  }
+};
+
+// src/relayer/relayer-web.ts
+var RELAYER_SDK_VERSION = "0.4.1";
+var CDN_URL = `https://cdn.zama.org/relayer-sdk-js/${RELAYER_SDK_VERSION}/relayer-sdk-js.umd.cjs`;
+var CDN_INTEGRITY = "2bd5401738b74509549bed2029bbbabedd481b10ac260f66e64a4ff3723d6d704180c51e882757c56ca1840491e90e33";
+var RelayerWeb = class {
+  #workerClient = null;
+  #initPromise = null;
+  #ensureLock = null;
+  #terminated = false;
+  #resolvedChainId = null;
+  #status = "idle";
+  #initError;
+  #config;
+  constructor(config) {
+    this.#config = config;
+  }
+  /** Current WASM initialization status. */
+  get status() {
+    return this.#status;
+  }
+  /** The error that caused initialization to fail, if `status` is `"error"`. */
+  get initError() {
+    return this.#initError;
+  }
+  #setStatus(status, error) {
+    this.#status = status;
+    this.#initError = error;
+    this.#config.onStatusChange?.(status, error);
+  }
+  async #getWorkerConfig() {
+    const chainId = await this.#config.getChainId();
+    const { transports, security, threads } = this.#config;
+    if (threads !== void 0 && (!Number.isInteger(threads) || threads < 1)) {
+      throw new Error(`Invalid thread count: ${threads}. Must be a positive integer.`);
+    }
+    if (threads !== void 0 && typeof globalThis.SharedArrayBuffer === "undefined") {
+      this.#config.logger?.warn(
+        "threads option requires SharedArrayBuffer (COOP/COEP headers). Falling back to single-threaded."
+      );
+    }
+    return {
+      cdnUrl: CDN_URL,
+      fhevmConfig: mergeFhevmConfig(chainId, transports[chainId]),
+      csrfToken: security?.getCsrfToken?.() ?? "",
+      integrity: security?.integrityCheck === false ? void 0 : CDN_INTEGRITY,
+      logger: this.#config.logger,
+      // Public API uses `threads` (plural, "how many threads"); upstream
+      // `initSDK` expects `thread` (singular) — rename at the boundary.
+      thread: threads
+    };
+  }
+  /**
+   * Ensure the worker is initialized.
+   * Uses a promise lock to prevent concurrent initialization.
+   * Resets on failure to allow retries.
+   */
+  async #ensureWorker() {
+    if (this.#ensureLock) return this.#ensureLock;
+    this.#ensureLock = this.#ensureWorkerInner();
+    try {
+      return await this.#ensureLock;
+    } finally {
+      this.#ensureLock = null;
+    }
+  }
+  async #ensureWorkerInner() {
+    if (this.#terminated) {
+      this.#terminated = false;
+      this.#workerClient = null;
+      this.#initPromise = null;
+      this.#resolvedChainId = null;
+    }
+    const chainId = await this.#config.getChainId();
+    if (this.#resolvedChainId !== null && chainId !== this.#resolvedChainId) {
+      this.#workerClient?.terminate();
+      this.#workerClient = null;
+      this.#initPromise = null;
+    }
+    this.#resolvedChainId = chainId;
+    if (!this.#initPromise) {
+      this.#setStatus("initializing");
+      this.#initPromise = this.#initWorker().then((client) => {
+        this.#setStatus("ready");
+        return client;
+      }).catch((error) => {
+        this.#initPromise = null;
+        const wrappedError = error instanceof ZamaError ? error : new EncryptionFailedError("Failed to initialize FHE worker", {
+          cause: error instanceof Error ? error : void 0
+        });
+        this.#setStatus("error", wrappedError);
+        throw wrappedError;
+      });
+    }
+    return this.#initPromise;
+  }
+  /**
+   * Initialize the worker (called once via promise lock).
+   */
+  async #initWorker() {
+    const workerConfig = await this.#getWorkerConfig();
+    const client = new RelayerWorkerClient(workerConfig);
+    await client.initWorker();
+    if (this.#terminated) {
+      client.terminate();
+      throw new Error("RelayerWeb was terminated during initialization");
+    }
+    this.#workerClient = client;
+    return client;
+  }
+  /**
+   * Terminate the worker and clean up resources.
+   * Call this when the SDK is no longer needed.
+   */
+  terminate() {
+    this.#terminated = true;
+    if (this.#workerClient) {
+      this.#workerClient.terminate();
+      this.#workerClient = null;
+    }
+    this.#initPromise = null;
+    this.#ensureLock = null;
+  }
+  /**
+   * Refresh the CSRF token in the worker.
+   * Call this before making authenticated network requests.
+   */
+  async #refreshCsrfToken() {
+    if (this.#workerClient) {
+      const token = this.#config.security?.getCsrfToken?.() ?? "";
+      if (token) {
+        await this.#workerClient.updateCsrf(token);
+      }
+    }
+  }
+  /**
+   * Generate a keypair for FHE operations.
+   */
+  async generateKeypair() {
+    const worker = await this.#ensureWorker();
+    const result = await worker.generateKeypair();
+    return {
+      publicKey: result.publicKey,
+      privateKey: result.privateKey
+    };
+  }
+  /**
+   * Create EIP712 typed data for user decryption authorization.
+   */
+  async createEIP712(publicKey, contractAddresses, startTimestamp, durationDays = 7) {
+    const worker = await this.#ensureWorker();
+    const result = await worker.createEIP712({
+      publicKey,
+      contractAddresses,
+      startTimestamp,
+      durationDays
+    });
+    const domain = {
+      name: result.domain.name,
+      version: result.domain.version,
+      chainId: result.domain.chainId,
+      verifyingContract: result.domain.verifyingContract
+    };
+    return {
+      domain,
+      types: {
+        EIP712Domain: buildEIP712DomainType(domain),
+        UserDecryptRequestVerification: result.types.UserDecryptRequestVerification
+      },
+      message: {
+        publicKey: result.message.publicKey,
+        contractAddresses: result.message.contractAddresses,
+        startTimestamp: result.message.startTimestamp,
+        durationDays: result.message.durationDays,
+        extraData: result.message.extraData
+      }
+    };
+  }
+  /**
+   * Encrypt values for use in smart contract calls.
+   * Each value must specify its FHE type (ebool, euint4–256, eaddress).
+   */
+  async encrypt(params) {
+    const { values, contractAddress, userAddress } = params;
+    return withRetry(async () => {
+      const worker = await this.#ensureWorker();
+      await this.#refreshCsrfToken();
+      const result = await worker.encrypt({ values, contractAddress, userAddress });
+      return { handles: result.handles, inputProof: result.inputProof };
+    });
+  }
+  /**
+   * Decrypt ciphertexts using user's private key.
+   * Requires a valid EIP712 signature.
+   */
+  async userDecrypt(params) {
+    return withRetry(async () => {
+      const worker = await this.#ensureWorker();
+      await this.#refreshCsrfToken();
+      const result = await worker.userDecrypt(params);
+      return result.clearValues;
+    });
+  }
+  /**
+   * Public decryption - no authorization needed.
+   * Used for publicly visible encrypted values.
+   */
+  async publicDecrypt(handles) {
+    return withRetry(async () => {
+      const worker = await this.#ensureWorker();
+      await this.#refreshCsrfToken();
+      const result = await worker.publicDecrypt(handles);
+      return {
+        clearValues: result.clearValues,
+        abiEncodedClearValues: result.abiEncodedClearValues,
+        decryptionProof: result.decryptionProof
+      };
+    });
+  }
+  /**
+   * Create EIP712 typed data for delegated user decryption authorization.
+   */
+  async createDelegatedUserDecryptEIP712(publicKey, contractAddresses, delegatorAddress, startTimestamp, durationDays = 7) {
+    const worker = await this.#ensureWorker();
+    return worker.createDelegatedUserDecryptEIP712({
+      publicKey,
+      contractAddresses,
+      delegatorAddress,
+      startTimestamp,
+      durationDays
+    });
+  }
+  /**
+   * Decrypt ciphertexts via delegation.
+   * Requires a valid EIP712 signature from the delegator.
+   */
+  async delegatedUserDecrypt(params) {
+    return withRetry(async () => {
+      const worker = await this.#ensureWorker();
+      await this.#refreshCsrfToken();
+      const result = await worker.delegatedUserDecrypt(params);
+      return result.clearValues;
+    });
+  }
+  /**
+   * Submit a ZK proof to the relayer for verification.
+   */
+  async requestZKProofVerification(zkProof) {
+    return withRetry(async () => {
+      const worker = await this.#ensureWorker();
+      await this.#refreshCsrfToken();
+      return worker.requestZKProofVerification(zkProof);
+    });
+  }
+  /**
+   * Get the TFHE compact public key.
+   */
+  async getPublicKey() {
+    const worker = await this.#ensureWorker();
+    return (await worker.getPublicKey()).result;
+  }
+  /**
+   * Get public parameters for encryption capacity.
+   */
+  async getPublicParams(bits) {
+    const worker = await this.#ensureWorker();
+    return (await worker.getPublicParams(bits)).result;
+  }
+};
+
+// src/abi/batch-swap.abi.ts
+var BATCH_SWAP_ABI = [
+  {
+    inputs: [
+      {
+        internalType: "contract DeploymentCoordinator",
+        name: "coordinator_",
+        type: "address"
+      },
+      {
+        internalType: "contract RegulatedERC7984Upgradeable",
+        name: "fromToken_",
+        type: "address"
+      },
+      {
+        internalType: "contract RegulatedERC7984Upgradeable",
+        name: "toToken_",
+        type: "address"
+      },
+      {
+        internalType: "contract ConfidentialWrapper",
+        name: "fromWrapper_",
+        type: "address"
+      },
+      {
+        internalType: "contract ConfidentialWrapper",
+        name: "toWrapper_",
+        type: "address"
+      },
+      {
+        internalType: "uint256",
+        name: "minBatchDuration_",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "batchExpiry_",
+        type: "uint256"
+      },
+      {
+        internalType: "contract ISwapRoute",
+        name: "swapRoute_",
+        type: "address"
+      },
+      {
+        internalType: "uint256",
+        name: "minDepositors_",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "nonpayable",
+    type: "constructor"
+  },
+  {
+    inputs: [],
+    name: "AlreadyClaimed",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "BatchExpiredBeforeDispatch",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "BatchNotDispatched",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "BatchNotExpiredOrFailed",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "BatchNotFinalized",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "BatchNotOpen",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ExchangeRateOverflow",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "FinalizeNotSupported",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "InsufficientEntropy",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "InvalidBatchExpiry",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "InvalidFromToken",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "InvalidMantissa",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "MinBatchDurationNotMet",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "NoDeposit",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "owner",
+        type: "address"
+      }
+    ],
+    name: "OwnableInvalidOwner",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "account",
+        type: "address"
+      }
+    ],
+    name: "OwnableUnauthorizedAccount",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "RouteInputMismatch",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "RouteOutputMismatch",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "SafeERC20FailedOperation",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "SenderNotAllowed",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "TokenTransferFailed",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "UnknownWrapper",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ZamaProtocolUnsupported",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ZeroAddress",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ZeroCTokenAmount",
+    type: "error"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "plaintextAmount",
+        type: "uint256"
+      }
+    ],
+    name: "BatchDispatchCallback",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "newBatchId",
+        type: "uint256"
+      }
+    ],
+    name: "BatchDispatched",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "BatchExpired",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "BatchFailed",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint64",
+        name: "exchangeRate",
+        type: "uint64"
+      },
+      {
+        indexed: false,
+        internalType: "uint64",
+        name: "mantissa",
+        type: "uint64"
+      }
+    ],
+    name: "BatchFinalized",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "Claimed",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "startIndex",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "endIndex",
+        type: "uint256"
+      }
+    ],
+    name: "ClaimsPushed",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "Deposited",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "operator",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "uint48",
+        name: "until",
+        type: "uint48"
+      }
+    ],
+    name: "FinalizeUnwrapOperatorUpdated",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "previousOwner",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "newOwner",
+        type: "address"
+      }
+    ],
+    name: "OwnershipTransferStarted",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "previousOwner",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "newOwner",
+        type: "address"
+      }
+    ],
+    name: "OwnershipTransferred",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "oldRoute",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "newRoute",
+        type: "address"
+      }
+    ],
+    name: "SwapRouteUpdated",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "to",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "amount",
+        type: "uint256"
+      }
+    ],
+    name: "TokensRescued",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "Withdrawn",
+    type: "event"
+  },
+  {
+    inputs: [],
+    name: "acceptOwnership",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "batchExpiry",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "claim",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "claim",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "confidentialProtocolId",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "coordinator",
+    outputs: [
+      {
+        internalType: "contract DeploymentCoordinator",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "currentBatchId",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "dispatchBatch",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "finalizeBatch",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "fromToken",
+    outputs: [
+      {
+        internalType: "contract RegulatedERC7984Upgradeable",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "fromWrapper",
+    outputs: [
+      {
+        internalType: "contract ConfidentialWrapper",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "getBatch",
+    outputs: [
+      {
+        internalType: "enum Batcher.BatchStatus",
+        name: "status",
+        type: "uint8"
+      },
+      {
+        internalType: "uint256",
+        name: "createdAt",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "dispatchedAt",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "totalDepositedPlaintext",
+        type: "uint256"
+      },
+      {
+        internalType: "uint64",
+        name: "exchangeRate",
+        type: "uint64"
+      },
+      {
+        internalType: "uint64",
+        name: "mantissa",
+        type: "uint64"
+      },
+      {
+        internalType: "uint256",
+        name: "depositCount",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "unwrapRequestId",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "getDepositorCount",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "getDepositors",
+    outputs: [
+      {
+        internalType: "address[]",
+        name: "",
+        type: "address[]"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "hasDeposit",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "isClaimable",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "isClaimed",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "minBatchDuration",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "minDepositors",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "from",
+        type: "address"
+      },
+      {
+        internalType: "euint64",
+        name: "amount",
+        type: "bytes32"
+      },
+      {
+        internalType: "bytes",
+        name: "",
+        type: "bytes"
+      }
+    ],
+    name: "onConfidentialTransferReceived",
+    outputs: [
+      {
+        internalType: "ebool",
+        name: "",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      },
+      {
+        internalType: "uint256",
+        name: "amount",
+        type: "uint256"
+      },
+      {
+        internalType: "euint64",
+        name: "burntAmount",
+        type: "bytes32"
+      },
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      },
+      {
+        internalType: "bytes",
+        name: "data",
+        type: "bytes"
+      }
+    ],
+    name: "onUnwrapFinalizedReceived",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "owner",
+    outputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "pendingOwner",
+    outputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "startIndex",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "count",
+        type: "uint256"
+      }
+    ],
+    name: "pushClaims",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "recoverFailedBatch",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "renounceOwnership",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      },
+      {
+        internalType: "uint256",
+        name: "amount",
+        type: "uint256"
+      }
+    ],
+    name: "rescueTokens",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "operator",
+        type: "address"
+      },
+      {
+        internalType: "uint48",
+        name: "until",
+        type: "uint48"
+      }
+    ],
+    name: "setFinalizeUnwrapOperator",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "contract ISwapRoute",
+        name: "newRoute",
+        type: "address"
+      }
+    ],
+    name: "setSwapRoute",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "swapRoute",
+    outputs: [
+      {
+        internalType: "contract ISwapRoute",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "toToken",
+    outputs: [
+      {
+        internalType: "contract RegulatedERC7984Upgradeable",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "toWrapper",
+    outputs: [
+      {
+        internalType: "contract ConfidentialWrapper",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "newOwner",
+        type: "address"
+      }
+    ],
+    name: "transferOwnership",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "batchId",
+        type: "uint256"
+      }
+    ],
+    name: "withdraw",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    stateMutability: "payable",
+    type: "receive"
+  }
+];
+
+// src/events/onchain-events.ts
+var Topics = {
+  /** `ConfidentialTransfer(address indexed from, address indexed to, bytes32 indexed amount)` */
+  ConfidentialTransfer: "0x67500e8d0ed826d2194f514dd0d8124f35648ab6e3fb5e6ed867134cffe661e9",
+  /** `Wrapped(uint64 mintAmount, uint256 amountIn, uint256 feeAmount, address indexed to_, uint256 indexed mintTxId)` */
+  Wrapped: "0x1f7907f4d84043abe0fb7c74e8865ee5fe93fe4f691c54a7b8fa9d6fb17c7cba",
+  /** `UnwrapRequested(address indexed receiver, bytes32 amount)` */
+  UnwrapRequested: "0x77d02d353c5629272875d11f1b34ec4c65d7430b075575b78cd2502034c469ee",
+  /** `UnwrappedFinalized(bytes32 indexed burntAmountHandle, ...)` */
+  UnwrappedFinalized: "0xc64e7c81b18b674fc5b037d8a0041bfe3332d86c780a4688f404ee01fbabb152",
+  /** `UnwrappedStarted(bool returnVal, uint256 indexed requestId, ...)` */
+  UnwrappedStarted: "0x3838891d4843c6d7f9f494570b6fd8843f4e3c3ddb817c1411760bd31b819806"
+};
+function topicToAddress(topic) {
+  return "0x" + topic.slice(-40);
+}
+function topicToBigInt(topic) {
+  return BigInt(topic);
+}
+function topicToBytes32(topic) {
+  return topic;
+}
+function wordAt(data, index) {
+  const start = 2 + index * 64;
+  const word = data.slice(start, start + 64);
+  return word.length === 64 ? word : word.padEnd(64, "0");
+}
+function wordToAddress(data, index) {
+  return "0x" + wordAt(data, index).slice(-40);
+}
+function wordToBigInt(data, index) {
+  return BigInt("0x" + wordAt(data, index));
+}
+function wordToBool(data, index) {
+  return BigInt("0x" + wordAt(data, index)) !== 0n;
+}
+function wordToBytes32(data, index) {
+  return `0x${wordAt(data, index)}`;
+}
+function decodeConfidentialTransfer(log) {
+  if (log.topics[0] !== Topics.ConfidentialTransfer) return null;
+  if (log.topics.length < 4) return null;
+  return {
+    eventName: "ConfidentialTransfer",
+    from: topicToAddress(log.topics[1]),
+    to: topicToAddress(log.topics[2]),
+    encryptedAmountHandle: topicToBytes32(log.topics[3])
+  };
+}
+function decodeWrapped(log) {
+  if (log.topics[0] !== Topics.Wrapped) return null;
+  if (log.topics.length < 3) return null;
+  return {
+    eventName: "Wrapped",
+    to: topicToAddress(log.topics[1]),
+    mintTxId: topicToBigInt(log.topics[2]),
+    mintAmount: wordToBigInt(log.data, 0),
+    amountIn: wordToBigInt(log.data, 1),
+    feeAmount: wordToBigInt(log.data, 2)
+  };
+}
+function decodeUnwrapRequested(log) {
+  if (log.topics[0] !== Topics.UnwrapRequested) return null;
+  if (log.topics.length < 2) return null;
+  return {
+    eventName: "UnwrapRequested",
+    receiver: topicToAddress(log.topics[1]),
+    encryptedAmount: wordToBytes32(log.data, 0)
+  };
+}
+function decodeUnwrappedFinalized(log) {
+  if (log.topics[0] !== Topics.UnwrappedFinalized) return null;
+  if (log.topics.length < 3) return null;
+  return {
+    eventName: "UnwrappedFinalized",
+    burntAmountHandle: topicToBytes32(log.topics[1]),
+    nextTxId: topicToBigInt(log.topics[2]),
+    finalizeSuccess: wordToBool(log.data, 0),
+    feeTransferSuccess: wordToBool(log.data, 1),
+    burnAmount: wordToBigInt(log.data, 2),
+    unwrapAmount: wordToBigInt(log.data, 3),
+    feeAmount: wordToBigInt(log.data, 4)
+  };
+}
+function decodeUnwrappedStarted(log) {
+  if (log.topics[0] !== Topics.UnwrappedStarted) return null;
+  if (log.topics.length < 4) return null;
+  return {
+    eventName: "UnwrappedStarted",
+    requestId: topicToBigInt(log.topics[1]),
+    txId: topicToBigInt(log.topics[2]),
+    to: topicToAddress(log.topics[3]),
+    returnVal: wordToBool(log.data, 0),
+    refund: wordToAddress(log.data, 1),
+    requestedAmount: wordToBytes32(log.data, 2),
+    burnAmount: wordToBytes32(log.data, 3)
+  };
+}
+function decodeOnChainEvent(log) {
+  return decodeConfidentialTransfer(log) ?? decodeWrapped(log) ?? decodeUnwrapRequested(log) ?? decodeUnwrappedFinalized(log) ?? decodeUnwrappedStarted(log);
+}
+function decodeOnChainEvents(logs) {
+  const events = [];
+  for (const log of logs) {
+    const event = decodeOnChainEvent(log);
+    if (event) events.push(event);
+  }
+  return events;
+}
+function findUnwrapRequested(logs) {
+  for (const log of logs) {
+    const event = decodeUnwrapRequested(log);
+    if (event) return event;
+  }
+  return null;
+}
+function findWrapped(logs) {
+  for (const log of logs) {
+    const event = decodeWrapped(log);
+    if (event) return event;
+  }
+  return null;
+}
+var TOKEN_TOPICS = [
+  Topics.ConfidentialTransfer,
+  Topics.Wrapped,
+  Topics.UnwrapRequested,
+  Topics.UnwrappedFinalized,
+  Topics.UnwrappedStarted
+];
+
+// src/token/memory-storage.ts
+var MemoryStorage = class {
+  #map = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.#map.get(key) ?? null;
+  }
+  async set(key, value) {
+    this.#map.set(key, value);
+  }
+  async delete(key) {
+    this.#map.delete(key);
+  }
+};
+var memoryStorage = new MemoryStorage();
+
+// src/events/sdk-events.ts
+var ZamaSDKEvents = {
+  // Credentials lifecycle
+  CredentialsLoading: "credentials:loading",
+  CredentialsCached: "credentials:cached",
+  CredentialsExpired: "credentials:expired",
+  CredentialsCreating: "credentials:creating",
+  CredentialsCreated: "credentials:created",
+  CredentialsRevoked: "credentials:revoked",
+  CredentialsAllowed: "credentials:allowed",
+  // FHE operations
+  EncryptStart: "encrypt:start",
+  EncryptEnd: "encrypt:end",
+  EncryptError: "encrypt:error",
+  DecryptStart: "decrypt:start",
+  DecryptEnd: "decrypt:end",
+  DecryptError: "decrypt:error",
+  // Write operations
+  TransactionError: "transaction:error",
+  ShieldSubmitted: "shield:submitted",
+  TransferSubmitted: "transfer:submitted",
+  TransferFromSubmitted: "transferFrom:submitted",
+  ApproveSubmitted: "approve:submitted",
+  ApproveUnderlyingSubmitted: "approveUnderlying:submitted",
+  UnwrapSubmitted: "unwrap:submitted",
+  FinalizeUnwrapSubmitted: "finalizeUnwrap:submitted",
+  // Unshield orchestration
+  UnshieldPhase1Submitted: "unshield:phase1_submitted",
+  UnshieldPhase2Started: "unshield:phase2_started",
+  UnshieldPhase2Submitted: "unshield:phase2_submitted"
+};
+
+// src/token/credentials-manager.ts
+async function computeStoreKey(address, chainId) {
+  const hash = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(`${address.toLowerCase()}:${chainId}`)
+  );
+  const hex = Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hex.slice(0, 32);
+}
+var CredentialsManager = class {
+  #relayer;
+  #signer;
+  #storage;
+  #sessionStorage;
+  #durationDays;
+  #onEvent;
+  #createPromise = null;
+  #createPromiseKey = null;
+  constructor(config) {
+    this.#relayer = config.relayer;
+    this.#signer = config.signer;
+    this.#storage = config.storage;
+    this.#sessionStorage = config.sessionStorage;
+    this.#durationDays = config.durationDays;
+    this.#onEvent = config.onEvent ?? Boolean;
+    const chrome2 = typeof globalThis !== "undefined" ? globalThis.chrome : void 0;
+    if (chrome2?.runtime?.id && config.sessionStorage instanceof MemoryStorage) {
+      console.warn(
+        "[zama-sdk] Detected Chrome extension context with in-memory session storage. Session signatures will be lost on service worker restart and won't be shared across contexts. Consider using chromeSessionStorage instead. "
+      );
+    }
+  }
+  #emit(partial) {
+    this.#onEvent({ ...partial, timestamp: Date.now() });
+  }
+  /**
+   * Authorize FHE credentials for one or more contract addresses.
+   * Returns cached credentials if still valid and covering all addresses,
+   * otherwise generates a fresh keypair and requests an EIP-712 signature.
+   * The wallet signature is cached in session storage.
+   *
+   * @example
+   * ```ts
+   * const creds = await credentials.allow("0xTokenAddress");
+   * const creds = await credentials.allow("0xTokenA", "0xTokenB");
+   * ```
+   */
+  async allow(...contractAddresses) {
+    const storeKey = await this.#storeKey();
+    this.#emit({ type: ZamaSDKEvents.CredentialsLoading, contractAddresses });
+    try {
+      const stored = await this.#storage.get(storeKey);
+      if (stored) {
+        const encrypted = stored;
+        this.#assertEncryptedCredentials(encrypted);
+        if (this.#hasLegacySignature(encrypted)) {
+          const creds = await this.#decryptCredentials(encrypted, encrypted.signature);
+          if (this.#isValid(creds, contractAddresses)) {
+            await this.#sessionStorage.set(storeKey, encrypted.signature);
+            const migrated = await this.#encryptCredentials(creds);
+            await this.#storage.set(storeKey, migrated).catch(() => {
+            });
+            this.#emit({ type: ZamaSDKEvents.CredentialsCached, contractAddresses });
+            this.#emit({ type: ZamaSDKEvents.CredentialsAllowed, contractAddresses });
+            return creds;
+          }
+          this.#emit({ type: ZamaSDKEvents.CredentialsExpired, contractAddresses });
+        } else {
+          const sessionSig = await this.#sessionStorage.get(storeKey);
+          if (sessionSig) {
+            const creds = await this.#decryptCredentials(encrypted, sessionSig);
+            if (this.#isValid(creds, contractAddresses)) {
+              this.#emit({ type: ZamaSDKEvents.CredentialsCached, contractAddresses });
+              this.#emit({ type: ZamaSDKEvents.CredentialsAllowed, contractAddresses });
+              return creds;
+            }
+            this.#emit({ type: ZamaSDKEvents.CredentialsExpired, contractAddresses });
+          } else {
+            if (this.#isValidWithoutDecrypt(encrypted, contractAddresses)) {
+              const signature = await this.#sign(encrypted);
+              await this.#sessionStorage.set(storeKey, signature);
+              const creds = await this.#decryptCredentials(encrypted, signature);
+              this.#emit({ type: ZamaSDKEvents.CredentialsCached, contractAddresses });
+              this.#emit({ type: ZamaSDKEvents.CredentialsAllowed, contractAddresses });
+              return creds;
+            }
+            this.#emit({ type: ZamaSDKEvents.CredentialsExpired, contractAddresses });
+          }
+        }
+      }
+    } catch {
+      try {
+        await this.#storage.delete(storeKey);
+      } catch {
+      }
+    }
+    const key = contractAddresses.map((a) => a.toLowerCase()).sort().join(",");
+    if (!this.#createPromise || this.#createPromiseKey !== key) {
+      this.#createPromiseKey = key;
+      this.#createPromise = this.create(contractAddresses).then((creds) => {
+        this.#emit({ type: ZamaSDKEvents.CredentialsAllowed, contractAddresses });
+        return creds;
+      }).finally(() => {
+        this.#createPromise = null;
+        this.#createPromiseKey = null;
+      });
+    }
+    return this.#createPromise;
+  }
+  /**
+   * Check if stored credentials exist and are expired.
+   * Returns `true` if credentials are stored but past their expiration time.
+   * Returns `false` if no credentials are stored or if they are still valid.
+   *
+   * Use this to proactively detect expiration and show appropriate UI
+   * (e.g. "Re-authorizing..." instead of a generic loading state).
+   *
+   * @param contractAddress - Optional contract address to check coverage for.
+   *   When provided, also returns `true` if credentials don't cover this address.
+   *
+   * @example
+   * ```ts
+   * if (await credentials.isExpired("0xTokenAddress")) {
+   *   showReauthorizingUI();
+   * }
+   * ```
+   */
+  async isExpired(contractAddress) {
+    const storeKey = await this.#storeKey();
+    try {
+      const stored = await this.#storage.get(storeKey);
+      if (!stored) return false;
+      const encrypted = stored;
+      this.#assertEncryptedCredentials(encrypted);
+      const requiredContracts = contractAddress ? [contractAddress] : [];
+      return !this.#isValidWithoutDecrypt(encrypted, requiredContracts);
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Revoke the session signature for the connected wallet. Stored credentials
+   * remain intact, but the next decrypt operation will require a fresh wallet
+   * signature.
+   *
+   * @param contractAddresses - Optional addresses included in the revoked event
+   *   for observability. The session signature is always fully revoked since it
+   *   is atomic over all addresses.
+   *
+   * @example
+   * ```ts
+   * await credentials.revoke();
+   * await credentials.revoke("0xTokenA", "0xTokenB");
+   * ```
+   */
+  async revoke(...contractAddresses) {
+    const storeKey = await this.#storeKey();
+    await this.#sessionStorage.delete(storeKey);
+    this.#emit({
+      type: ZamaSDKEvents.CredentialsRevoked,
+      ...contractAddresses.length > 0 && { contractAddresses }
+    });
+  }
+  /**
+   * Whether a session signature is currently cached for the connected wallet.
+   */
+  async isAllowed() {
+    const storeKey = await this.#storeKey();
+    return await this.#sessionStorage.get(storeKey) !== null;
+  }
+  /**
+   * Delete stored credentials for the connected wallet (best-effort).
+   *
+   * @example
+   * ```ts
+   * await credentials.clear();
+   * ```
+   */
+  async clear() {
+    const storeKey = await this.#storeKey();
+    await this.#sessionStorage.delete(storeKey);
+    try {
+      await this.#storage.delete(storeKey);
+    } catch {
+    }
+  }
+  /** Returns a truncated SHA-256 hash of the address and chainId to avoid leaking it in storage. */
+  async #storeKey() {
+    const address = (await this.#signer.getAddress()).toLowerCase();
+    const chainId = await this.#signer.getChainId();
+    return computeStoreKey(address, chainId);
+  }
+  // ── Validation ──────────────────────────────────────────────
+  #assertEncryptedCredentials(data) {
+    assertObject(data, "Stored credentials");
+    assertString(data.publicKey, "credentials.publicKey");
+    assertArray(data.contractAddresses, "credentials.contractAddresses");
+    assertObject(data.encryptedPrivateKey, "credentials.encryptedPrivateKey");
+    assertString(data.encryptedPrivateKey.iv, "encryptedPrivateKey.iv");
+    assertString(data.encryptedPrivateKey.ciphertext, "encryptedPrivateKey.ciphertext");
+  }
+  #hasLegacySignature(data) {
+    return "signature" in data && typeof data.signature === "string";
+  }
+  #isValid(creds, requiredContracts) {
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    const expiresAt = creds.startTimestamp + creds.durationDays * 86400;
+    if (nowSeconds >= expiresAt) return false;
+    const signedSet = new Set(creds.contractAddresses.map((a) => a.toLowerCase()));
+    return requiredContracts.every((addr) => signedSet.has(addr.toLowerCase()));
+  }
+  #isValidWithoutDecrypt(encrypted, requiredContracts) {
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    const expiresAt = encrypted.startTimestamp + encrypted.durationDays * 86400;
+    if (nowSeconds >= expiresAt) return false;
+    const signedSet = new Set(encrypted.contractAddresses.map((a) => a.toLowerCase()));
+    return requiredContracts.every((addr) => signedSet.has(addr.toLowerCase()));
+  }
+  async #sign(encrypted) {
+    const eip712 = await this.#relayer.createEIP712(
+      encrypted.publicKey,
+      encrypted.contractAddresses,
+      encrypted.startTimestamp,
+      encrypted.durationDays
+    );
+    return this.#signer.signTypedData(eip712);
+  }
+  // ── Credential generation ───────────────────────────────────
+  /**
+   * Generate a fresh FHE keypair, create an EIP-712 authorization, and
+   * prompt the user to sign it. Persists the encrypted credentials to storage.
+   *
+   * @example
+   * ```ts
+   * const creds = await credentials.create(["0xTokenAddress"]);
+   * ```
+   */
+  async create(contractAddresses) {
+    this.#emit({ type: ZamaSDKEvents.CredentialsCreating, contractAddresses });
+    try {
+      const storeKey = await this.#storeKey();
+      const keypair = await this.#relayer.generateKeypair();
+      const startTimestamp = Math.floor(Date.now() / 1e3);
+      const eip712 = await this.#relayer.createEIP712(
+        keypair.publicKey,
+        contractAddresses,
+        startTimestamp,
+        this.#durationDays
+      );
+      const signature = await this.#signer.signTypedData(eip712);
+      await this.#sessionStorage.set(storeKey, signature);
+      const creds = {
+        publicKey: keypair.publicKey,
+        privateKey: keypair.privateKey,
+        signature,
+        contractAddresses,
+        startTimestamp,
+        durationDays: this.#durationDays
+      };
+      try {
+        const encrypted = await this.#encryptCredentials(creds);
+        await this.#storage.set(storeKey, encrypted);
+      } catch {
+      }
+      this.#emit({ type: ZamaSDKEvents.CredentialsCreated, contractAddresses });
+      return creds;
+    } catch (error) {
+      const isRejected = error instanceof Error && "code" in error && error.code === 4001 || error instanceof Error && (error.message.includes("rejected") || error.message.includes("denied"));
+      if (isRejected) {
+        throw new SigningRejectedError("User rejected the decrypt authorization signature", {
+          cause: error
+        });
+      }
+      throw new SigningFailedError("Failed to create decrypt credentials", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  // ── AES-GCM encryption (ported from KeypairDB) ─────────────
+  async #encryptCredentials(creds) {
+    const address = (await this.#signer.getAddress()).toLowerCase();
+    const encryptedPrivateKey = await this.#encrypt(creds.privateKey, creds.signature, address);
+    const { privateKey: _, signature: _sig, ...rest } = creds;
+    return { ...rest, encryptedPrivateKey };
+  }
+  async #decryptCredentials(encrypted, signature) {
+    const address = (await this.#signer.getAddress()).toLowerCase();
+    const privateKey = await this.#decrypt(encrypted.encryptedPrivateKey, signature, address);
+    const { encryptedPrivateKey: _, ...rest } = encrypted;
+    return { ...rest, privateKey, signature };
+  }
+  /**
+   * Derives an AES-GCM encryption key from a wallet signature using PBKDF2.
+   * The signature is a secret known only to the wallet holder, providing
+   * meaningful encryption protection for the stored private key.
+   */
+  async #deriveKey(signature, address) {
+    const encoder = new TextEncoder();
+    const keyMaterial = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(signature),
+      "PBKDF2",
+      false,
+      ["deriveKey"]
+    );
+    return crypto.subtle.deriveKey(
+      {
+        name: "PBKDF2",
+        salt: encoder.encode(address),
+        iterations: 6e5,
+        hash: "SHA-256"
+      },
+      keyMaterial,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    );
+  }
+  /** Encrypts a string using AES-GCM with a key derived from the wallet signature. */
+  async #encrypt(plaintext, signature, address) {
+    const key = await this.#deriveKey(signature, address);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const encoder = new TextEncoder();
+    const ciphertext = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv },
+      key,
+      encoder.encode(plaintext)
+    );
+    return {
+      iv: btoa(String.fromCharCode(...iv)),
+      ciphertext: btoa(String.fromCharCode(...new Uint8Array(ciphertext)))
+    };
+  }
+  /** Decrypts AES-GCM encrypted data using a key derived from the wallet signature. */
+  async #decrypt(encrypted, signature, address) {
+    const key = await this.#deriveKey(signature, address);
+    const iv = Uint8Array.from(atob(encrypted.iv), (c) => c.charCodeAt(0));
+    const ciphertext = Uint8Array.from(atob(encrypted.ciphertext), (c) => c.charCodeAt(0));
+    const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertext);
+    return new TextDecoder().decode(plaintext);
+  }
+};
+
+// src/token/balance-cache.ts
+var BALANCES_KEY = "zama:balances";
+function storageKey(tokenAddress, owner, handle) {
+  return `zama:balance:${tokenAddress.toLowerCase()}:${owner.toLowerCase()}:${handle.toLowerCase()}`;
+}
+async function loadCachedBalance({
+  storage,
+  tokenAddress,
+  owner,
+  handle
+}) {
+  try {
+    const raw = await storage.get(storageKey(tokenAddress, owner, handle));
+    return raw !== null ? BigInt(raw) : null;
+  } catch {
+    return null;
+  }
+}
+async function saveCachedBalance(payload) {
+  const { storage, tokenAddress, owner, handle, value } = payload;
+  const key = storageKey(tokenAddress, owner, handle);
+  try {
+    await storage.set(key, value.toString());
+    await trackKey(storage, key);
+  } catch {
+  }
+}
+var trackKeyChains = /* @__PURE__ */ new WeakMap();
+async function trackKey(storage, key) {
+  const prev = trackKeyChains.get(storage) ?? Promise.resolve();
+  const next = prev.then(async () => {
+    const raw = await storage.get(BALANCES_KEY);
+    const keys = raw ? JSON.parse(raw) : [];
+    if (!keys.includes(key)) {
+      keys.push(key);
+      await storage.set(BALANCES_KEY, JSON.stringify(keys));
+    }
+  });
+  trackKeyChains.set(
+    storage,
+    next.catch(() => {
+    })
+  );
+  return next;
+}
+
+// src/token/readonly-token.ts
+var ZERO_HANDLE = "0x0000000000000000000000000000000000000000000000000000000000000000";
+var ReadonlyToken = class {
+  credentials;
+  sdk;
+  signer;
+  address;
+  #storage;
+  #onEvent;
+  constructor(config) {
+    const address = normalizeAddress(config.address, "address");
+    this.credentials = config.credentials ?? new CredentialsManager({
+      relayer: config.relayer,
+      signer: config.signer,
+      storage: config.storage,
+      sessionStorage: config.sessionStorage,
+      durationDays: config.durationDays ?? 1,
+      onEvent: config.onEvent
+    });
+    this.sdk = config.relayer;
+    this.signer = config.signer;
+    this.address = address;
+    this.#storage = config.storage;
+    this.#onEvent = config.onEvent;
+  }
+  /** Access the storage backend (used by static batch methods). */
+  get storage() {
+    return this.#storage;
+  }
+  /** Emit a structured event (no-op when no listener is registered). */
+  emit(partial) {
+    this.#onEvent?.({ ...partial, tokenAddress: this.address, timestamp: Date.now() });
+  }
+  /**
+   * Decrypt and return the plaintext balance for the given owner.
+   * Generates FHE credentials automatically if they don't exist.
+   *
+   * @param owner - Optional balance owner address. Defaults to the connected signer.
+   * @returns The decrypted plaintext balance as a bigint.
+   * @throws {@link DecryptionFailedError} if FHE decryption fails.
+   *
+   * @example
+   * ```ts
+   * const balance = await token.balanceOf();
+   * // or for another address:
+   * const balance = await token.balanceOf("0xOwner");
+   * ```
+   */
+  async balanceOf(owner) {
+    const ownerAddress = owner ? normalizeAddress(owner, "owner") : await this.signer.getAddress();
+    const handle = await this.readConfidentialBalanceOf(ownerAddress);
+    if (this.isZeroHandle(handle)) return BigInt(0);
+    const cached = await loadCachedBalance({
+      storage: this.#storage,
+      tokenAddress: this.address,
+      owner: ownerAddress,
+      handle
+    });
+    if (cached !== null) return cached;
+    const creds = await this.credentials.allow(this.address);
+    const t0 = Date.now();
+    try {
+      this.emit({ type: ZamaSDKEvents.DecryptStart });
+      const result = await this.sdk.userDecrypt({
+        handles: [handle],
+        contractAddress: this.address,
+        signedContractAddresses: creds.contractAddresses,
+        privateKey: creds.privateKey,
+        publicKey: creds.publicKey,
+        signature: creds.signature,
+        signerAddress: ownerAddress,
+        startTimestamp: creds.startTimestamp,
+        durationDays: creds.durationDays
+      });
+      this.emit({ type: ZamaSDKEvents.DecryptEnd, durationMs: Date.now() - t0 });
+      const value = result[handle] ?? BigInt(0);
+      await saveCachedBalance({
+        storage: this.#storage,
+        tokenAddress: this.address,
+        owner: ownerAddress,
+        handle,
+        value
+      });
+      return value;
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.DecryptError,
+        error: toError(error),
+        durationMs: Date.now() - t0
+      });
+      throw wrapDecryptError(error, "Failed to decrypt balance");
+    }
+  }
+  /**
+   * Return the raw encrypted balance handle without decrypting.
+   *
+   * @param owner - Optional balance owner address. Defaults to the connected signer.
+   * @returns The encrypted balance handle as a hex string.
+   *
+   * @example
+   * ```ts
+   * const handle = await token.confidentialBalanceOf();
+   * ```
+   */
+  async confidentialBalanceOf(owner) {
+    const ownerAddress = owner ? normalizeAddress(owner, "owner") : await this.signer.getAddress();
+    return this.readConfidentialBalanceOf(ownerAddress);
+  }
+  /**
+   * ERC-165 check for {@link ERC7984_INTERFACE_ID} support.
+   *
+   * @returns `true` if the contract implements the ERC-7984 confidential token interface.
+   *
+   * @example
+   * ```ts
+   * if (await token.isConfidential()) {
+   *   // Token supports encrypted operations
+   * }
+   * ```
+   */
+  async isConfidential() {
+    const result = await this.signer.readContract(
+      supportsInterfaceContract(this.address, ERC7984_INTERFACE_ID)
+    );
+    return result === true;
+  }
+  /**
+   * ERC-165 check for {@link ERC7984_WRAPPER_INTERFACE_ID} support.
+   *
+   * @returns `true` if the contract implements the ERC-7984 wrapper interface.
+   *
+   * @example
+   * ```ts
+   * if (await token.isWrapper()) {
+   *   // Token is a confidential wrapper
+   * }
+   * ```
+   */
+  async isWrapper() {
+    const result = await this.signer.readContract(
+      supportsInterfaceContract(this.address, ERC7984_WRAPPER_INTERFACE_ID)
+    );
+    return result === true;
+  }
+  /**
+   * Decrypt multiple token balances in parallel.
+   * When `handles` are provided, decrypts them directly (useful for two-phase
+   * polling where handles are already known). When omitted, fetches handles
+   * from the chain first.
+   *
+   * **Error handling:** If a per-token decryption fails and no `onError` callback
+   * is provided, errors are collected and thrown as an aggregated
+   * `DecryptionFailedError`. Pass `onError: () => 0n` for the old silent behavior.
+   *
+   * @param tokens - Array of ReadonlyToken instances to decrypt balances for.
+   * @param options - Optional configuration for handles, owner, error handling, and concurrency.
+   * @returns A Map from token address to decrypted balance.
+   * @throws {@link DecryptionFailedError} if any decryption fails and no `onError` callback is provided.
+   *
+   * @example
+   * ```ts
+   * // Simple one-shot:
+   * const balances = await ReadonlyToken.batchDecryptBalances(tokens);
+   *
+   * // With pre-fetched handles and error callback:
+   * const handles = await Promise.all(tokens.map(t => t.confidentialBalanceOf()));
+   * const balances = await ReadonlyToken.batchDecryptBalances(tokens, {
+   *   handles,
+   *   onError: (err, addr) => { console.error(addr, err); return 0n; },
+   * });
+   * ```
+   */
+  static async batchDecryptBalances(tokens, options) {
+    if (tokens.length === 0) return /* @__PURE__ */ new Map();
+    const { handles, owner, onError, maxConcurrency } = options ?? {};
+    const sdk = tokens[0].sdk;
+    const signer = tokens[0].signer;
+    const signerAddress = owner ?? await signer.getAddress();
+    const resolvedHandles = handles ?? await Promise.all(tokens.map((t) => t.readConfidentialBalanceOf(signerAddress)));
+    if (tokens.length !== resolvedHandles.length) {
+      throw new DecryptionFailedError(
+        `tokens.length (${tokens.length}) must equal handles.length (${resolvedHandles.length})`
+      );
+    }
+    const allAddresses = tokens.map((t) => t.address);
+    const creds = await tokens[0].credentials.allow(...allAddresses);
+    const tokenStorage = tokens[0].storage;
+    const results = /* @__PURE__ */ new Map();
+    const errors = [];
+    const decryptFns = [];
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i];
+      const handle = resolvedHandles[i];
+      if (token.isZeroHandle(handle)) {
+        results.set(token.address, BigInt(0));
+        continue;
+      }
+      const cached = await loadCachedBalance({
+        storage: tokenStorage,
+        tokenAddress: token.address,
+        owner: signerAddress,
+        handle
+      });
+      if (cached !== null) {
+        results.set(token.address, cached);
+        continue;
+      }
+      decryptFns.push(
+        () => sdk.userDecrypt({
+          handles: [handle],
+          contractAddress: token.address,
+          signedContractAddresses: creds.contractAddresses,
+          privateKey: creds.privateKey,
+          publicKey: creds.publicKey,
+          signature: creds.signature,
+          signerAddress,
+          startTimestamp: creds.startTimestamp,
+          durationDays: creds.durationDays
+        }).then(async (result) => {
+          const value = result[handle] ?? BigInt(0);
+          results.set(token.address, value);
+          await saveCachedBalance({
+            storage: tokenStorage,
+            tokenAddress: token.address,
+            owner: signerAddress,
+            handle,
+            value
+          });
+        }).catch((error) => {
+          const err = error instanceof Error ? error : new Error(String(error));
+          if (onError) {
+            results.set(token.address, onError(err, token.address));
+          } else {
+            errors.push({ address: token.address, error: err });
+          }
+        })
+      );
+    }
+    await pLimit(decryptFns, maxConcurrency);
+    if (errors.length > 0) {
+      const message = errors.map((e) => `${e.address}: ${e.error.message}`).join("; ");
+      throw new DecryptionFailedError(
+        `Batch decryption failed for ${errors.length} token(s): ${message}`
+      );
+    }
+    return results;
+  }
+  /**
+   * Look up the wrapper contract for this token via the deployment coordinator.
+   * Returns `null` if no wrapper is deployed.
+   *
+   * @param coordinatorAddress - The deployment coordinator contract address.
+   * @returns The wrapper address, or `null` if no wrapper exists.
+   *
+   * @example
+   * ```ts
+   * const wrapper = await token.discoverWrapper("0xCoordinator");
+   * if (wrapper) {
+   *   const fullToken = sdk.createToken(token.address, wrapper);
+   * }
+   * ```
+   */
+  async discoverWrapper(coordinatorAddress) {
+    const coordinator = normalizeAddress(coordinatorAddress, "coordinatorAddress");
+    const exists = await this.signer.readContract(
+      wrapperExistsContract(coordinator, this.address)
+    );
+    if (!exists) return null;
+    return this.signer.readContract(getWrapperContract(coordinator, this.address));
+  }
+  /**
+   * Read the underlying ERC-20 address from this token's wrapper contract.
+   *
+   * @returns The underlying ERC-20 token address.
+   *
+   * @example
+   * ```ts
+   * const underlying = await token.underlyingToken();
+   * ```
+   */
+  async underlyingToken() {
+    return this.signer.readContract(underlyingContract(this.address));
+  }
+  /**
+   * Read the ERC-20 allowance of the underlying token for a given wrapper.
+   *
+   * @param wrapper - The wrapper contract address to check allowance for.
+   * @param owner - Optional owner address. Defaults to the connected signer.
+   * @returns The current allowance as a bigint.
+   *
+   * @example
+   * ```ts
+   * const allowance = await token.allowance("0xWrapper");
+   * ```
+   */
+  async allowance(wrapper, owner) {
+    const normalizedWrapper = normalizeAddress(wrapper, "wrapper");
+    const underlying = await this.signer.readContract(
+      underlyingContract(normalizedWrapper)
+    );
+    const userAddress = owner ? normalizeAddress(owner, "owner") : await this.signer.getAddress();
+    return this.signer.readContract(
+      allowanceContract(underlying, userAddress, normalizedWrapper)
+    );
+  }
+  /**
+   * Read the token name from the contract.
+   *
+   * @returns The token name string.
+   *
+   * @example
+   * ```ts
+   * const name = await token.name(); // "Wrapped USDC"
+   * ```
+   */
+  async name() {
+    return this.signer.readContract(nameContract(this.address));
+  }
+  /**
+   * Read the token symbol from the contract.
+   *
+   * @returns The token symbol string.
+   *
+   * @example
+   * ```ts
+   * const symbol = await token.symbol(); // "cUSDC"
+   * ```
+   */
+  async symbol() {
+    return this.signer.readContract(symbolContract(this.address));
+  }
+  /**
+   * Read the token decimals from the contract.
+   *
+   * @returns The number of decimals.
+   *
+   * @example
+   * ```ts
+   * const decimals = await token.decimals(); // 6
+   * ```
+   */
+  async decimals() {
+    return this.signer.readContract(decimalsContract(this.address));
+  }
+  /**
+   * Ensure FHE decrypt credentials exist for this token.
+   * Generates a keypair and requests an EIP-712 signature if needed.
+   * Call this before any decrypt operation to avoid mid-flow wallet prompts.
+   *
+   * @returns Resolves when credentials are cached.
+   *
+   * @example
+   * ```ts
+   * await token.allow();
+   * // Credentials are now cached — subsequent decrypts won't prompt
+   * const balance = await token.balanceOf();
+   * ```
+   */
+  async allow() {
+    await this.credentials.allow(this.address);
+  }
+  /**
+   * Whether a session signature is currently cached for the connected wallet.
+   * Use this to check if decrypt operations can proceed without a wallet prompt.
+   */
+  async isAllowed() {
+    return this.credentials.isAllowed();
+  }
+  /**
+   * Revoke the session signature for the connected wallet.
+   * Stored credentials remain intact, but the next decrypt operation
+   * will require a fresh wallet signature.
+   */
+  async revoke(...contractAddresses) {
+    await this.credentials.revoke(...contractAddresses);
+  }
+  /**
+   * Ensure FHE decrypt credentials exist for all given tokens in a single
+   * wallet signature. Call this early (e.g. after loading the token list) so
+   * that subsequent individual decrypt operations reuse cached credentials.
+   *
+   * @param tokens - Array of ReadonlyToken instances to allow.
+   * @returns Resolves when all credentials are cached.
+   *
+   * @example
+   * ```ts
+   * const tokens = addresses.map(a => sdk.createReadonlyToken(a));
+   * await ReadonlyToken.allow(...tokens);
+   * // All tokens now share the same credentials
+   * ```
+   */
+  static async allow(...tokens) {
+    if (tokens.length === 0) return;
+    const allAddresses = tokens.map((t) => t.address);
+    await tokens[0].credentials.allow(...allAddresses);
+  }
+  async readConfidentialBalanceOf(owner) {
+    const result = await this.signer.readContract(
+      confidentialBalanceOfContract(this.address, owner)
+    );
+    return this.normalizeHandle(result);
+  }
+  normalizeHandle(value) {
+    if (typeof value === "string" && value.startsWith("0x")) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return `0x${value.toString(16).padStart(64, "0")}`;
+    }
+    return ZERO_HANDLE;
+  }
+  isZeroHandle(handle) {
+    return handle === ZERO_HANDLE || handle === "0x";
+  }
+  /**
+   * Decrypt a single encrypted handle into a plaintext bigint.
+   * Returns `0n` for zero handles without calling the relayer.
+   *
+   * @param handle - The encrypted balance handle to decrypt.
+   * @param owner - Optional owner address for the decrypt request.
+   * @returns The decrypted plaintext value as a bigint.
+   * @throws {@link DecryptionFailedError} if FHE decryption fails.
+   *
+   * @example
+   * ```ts
+   * const handle = await token.confidentialBalanceOf();
+   * const value = await token.decryptBalance(handle);
+   * ```
+   */
+  async decryptBalance(handle, owner) {
+    if (this.isZeroHandle(handle)) return BigInt(0);
+    const signerAddress = owner ?? await this.signer.getAddress();
+    const cached = await loadCachedBalance({
+      storage: this.#storage,
+      tokenAddress: this.address,
+      owner: signerAddress,
+      handle
+    });
+    if (cached !== null) return cached;
+    const creds = await this.credentials.allow(this.address);
+    const t0 = Date.now();
+    try {
+      this.emit({ type: ZamaSDKEvents.DecryptStart });
+      const result = await this.sdk.userDecrypt({
+        handles: [handle],
+        contractAddress: this.address,
+        signedContractAddresses: creds.contractAddresses,
+        privateKey: creds.privateKey,
+        publicKey: creds.publicKey,
+        signature: creds.signature,
+        signerAddress,
+        startTimestamp: creds.startTimestamp,
+        durationDays: creds.durationDays
+      });
+      this.emit({ type: ZamaSDKEvents.DecryptEnd, durationMs: Date.now() - t0 });
+      const value = result[handle] ?? BigInt(0);
+      await saveCachedBalance({
+        storage: this.#storage,
+        tokenAddress: this.address,
+        owner: signerAddress,
+        handle,
+        value
+      });
+      return value;
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.DecryptError,
+        error: toError(error),
+        durationMs: Date.now() - t0
+      });
+      throw wrapDecryptError(error, "Failed to decrypt balance");
+    }
+  }
+  /**
+   * Batch-decrypt arbitrary encrypted handles in a single relayer call.
+   * Zero handles are returned as 0n without hitting the relayer.
+   *
+   * @param handles - Array of encrypted handles to decrypt.
+   * @param owner - Optional owner address for the decrypt request.
+   * @returns A Map from handle to decrypted bigint value.
+   * @throws {@link DecryptionFailedError} if FHE decryption fails.
+   */
+  async decryptHandles(handles, owner) {
+    const results = /* @__PURE__ */ new Map();
+    const nonZeroHandles = [];
+    for (const handle of handles) {
+      if (this.isZeroHandle(handle)) {
+        results.set(handle, BigInt(0));
+      } else {
+        nonZeroHandles.push(handle);
+      }
+    }
+    if (nonZeroHandles.length === 0) return results;
+    const creds = await this.credentials.allow(this.address);
+    const t0 = Date.now();
+    try {
+      this.emit({ type: ZamaSDKEvents.DecryptStart });
+      const decrypted = await this.sdk.userDecrypt({
+        handles: nonZeroHandles,
+        contractAddress: this.address,
+        signedContractAddresses: creds.contractAddresses,
+        privateKey: creds.privateKey,
+        publicKey: creds.publicKey,
+        signature: creds.signature,
+        signerAddress: owner ?? await this.signer.getAddress(),
+        startTimestamp: creds.startTimestamp,
+        durationDays: creds.durationDays
+      });
+      this.emit({ type: ZamaSDKEvents.DecryptEnd, durationMs: Date.now() - t0 });
+      for (const handle of nonZeroHandles) {
+        results.set(handle, decrypted[handle] ?? BigInt(0));
+      }
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.DecryptError,
+        error: toError(error),
+        durationMs: Date.now() - t0
+      });
+      throw wrapDecryptError(error, "Failed to decrypt handles");
+    }
+    return results;
+  }
+};
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function wrapDecryptError(error, fallbackMessage) {
+  if (error instanceof NoCiphertextError || error instanceof RelayerRequestFailedError) {
+    return error;
+  }
+  const statusCode = error != null && typeof error === "object" && "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : void 0;
+  if (statusCode === 400) {
+    return new NoCiphertextError(
+      error instanceof Error ? error.message : "No ciphertext for this account",
+      { cause: error instanceof Error ? error : void 0 }
+    );
+  }
+  if (statusCode !== void 0) {
+    return new RelayerRequestFailedError(
+      error instanceof Error ? error.message : fallbackMessage,
+      statusCode,
+      { cause: error instanceof Error ? error : void 0 }
+    );
+  }
+  return new DecryptionFailedError(fallbackMessage, {
+    cause: error instanceof Error ? error : void 0
+  });
+}
+
+// src/token/token.ts
+function toError2(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+var Token = class _Token extends ReadonlyToken {
+  static ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+  wrapper;
+  #underlying;
+  #underlyingPromise = null;
+  constructor(config) {
+    super(config);
+    this.wrapper = config.wrapper ? normalizeAddress(config.wrapper, "wrapper") : this.address;
+  }
+  async #getUnderlying() {
+    if (this.#underlying !== void 0) return this.#underlying;
+    if (!this.#underlyingPromise) {
+      this.#underlyingPromise = this.signer.readContract(underlyingContract(this.wrapper)).then((v) => {
+        this.#underlying = v;
+        this.#underlyingPromise = null;
+        return v;
+      }).catch((error) => {
+        this.#underlyingPromise = null;
+        throw error;
+      });
+    }
+    return this.#underlyingPromise;
+  }
+  // WRITE OPERATIONS
+  /**
+   * Confidential transfer. Encrypts the amount via FHE, then calls the contract.
+   * Returns the transaction hash.
+   *
+   * @param to - Recipient address.
+   * @param amount - Plaintext amount to transfer (encrypted automatically via FHE).
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link EncryptionFailedError} if FHE encryption fails.
+   * @throws {@link TransactionRevertedError} if the on-chain transfer reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.confidentialTransfer("0xRecipient", 1000n);
+   * ```
+   */
+  async confidentialTransfer(to, amount, callbacks) {
+    const normalizedTo = normalizeAddress(to, "to");
+    let handles;
+    let inputProof;
+    const t0 = Date.now();
+    try {
+      this.emit({ type: ZamaSDKEvents.EncryptStart });
+      ({ handles, inputProof } = await this.sdk.encrypt({
+        values: [{ value: amount, type: "euint64" }],
+        contractAddress: this.address,
+        userAddress: await this.signer.getAddress()
+      }));
+      this.emit({ type: ZamaSDKEvents.EncryptEnd, durationMs: Date.now() - t0 });
+      safeCallback(() => callbacks?.onEncryptComplete?.());
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.EncryptError,
+        error: toError2(error),
+        durationMs: Date.now() - t0
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new EncryptionFailedError("Failed to encrypt transfer amount", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+    if (handles.length === 0) {
+      throw new EncryptionFailedError("Encryption returned no handles");
+    }
+    try {
+      const txHash = await this.signer.writeContract(
+        confidentialTransferContract(this.address, normalizedTo, handles[0], inputProof)
+      );
+      this.emit({ type: ZamaSDKEvents.TransferSubmitted, txHash });
+      safeCallback(() => callbacks?.onTransferSubmitted?.(txHash));
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "transfer",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("Transfer transaction failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * 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.
+   * @throws {@link EncryptionFailedError} if FHE encryption fails.
+   * @throws {@link TransactionRevertedError} if the on-chain transfer reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.confidentialTransferFrom("0xFrom", "0xTo", 500n);
+   * ```
+   */
+  async confidentialTransferFrom(from, to, amount, callbacks) {
+    const normalizedFrom = normalizeAddress(from, "from");
+    const normalizedTo = normalizeAddress(to, "to");
+    let handles;
+    let inputProof;
+    const t0 = Date.now();
+    try {
+      this.emit({ type: ZamaSDKEvents.EncryptStart });
+      ({ handles, inputProof } = await this.sdk.encrypt({
+        values: [{ value: amount, type: "euint64" }],
+        contractAddress: this.address,
+        userAddress: normalizedFrom
+      }));
+      this.emit({ type: ZamaSDKEvents.EncryptEnd, durationMs: Date.now() - t0 });
+      safeCallback(() => callbacks?.onEncryptComplete?.());
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.EncryptError,
+        error: toError2(error),
+        durationMs: Date.now() - t0
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new EncryptionFailedError("Failed to encrypt transferFrom amount", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+    if (handles.length === 0) {
+      throw new EncryptionFailedError("Encryption returned no handles");
+    }
+    try {
+      const txHash = await this.signer.writeContract(
+        confidentialTransferFromContract(
+          this.address,
+          normalizedFrom,
+          normalizedTo,
+          handles[0],
+          inputProof
+        )
+      );
+      this.emit({ type: ZamaSDKEvents.TransferFromSubmitted, txHash });
+      safeCallback(() => callbacks?.onTransferSubmitted?.(txHash));
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "transferFrom",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("TransferFrom transaction failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * Set operator approval for the confidential token.
+   * Defaults to 1 hour from now if `until` is not specified.
+   *
+   * @param spender - The address to approve as an operator.
+   * @param until - Optional Unix timestamp for approval expiry. Defaults to now + 1 hour.
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link ApprovalFailedError} if the approval transaction fails.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.approve("0xSpender");
+   * ```
+   */
+  async approve(spender, until) {
+    const normalizedSpender = normalizeAddress(spender, "spender");
+    try {
+      const txHash = await this.signer.writeContract(
+        setOperatorContract(this.address, normalizedSpender, until)
+      );
+      this.emit({ type: ZamaSDKEvents.ApproveSubmitted, txHash });
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "approve",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new ApprovalFailedError("Operator approval failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * Check if a spender is an approved operator for a given holder.
+   *
+   * @param spender - The address to check operator approval for.
+   * @param holder - The token holder address. Defaults to the connected wallet.
+   * @returns `true` if the spender is an approved operator for the holder.
+   *
+   * @example
+   * ```ts
+   * if (await token.isApproved("0xSpender")) {
+   *   // spender can call transferFrom on behalf of connected wallet
+   * }
+   * // or check for a specific holder:
+   * if (await token.isApproved("0xSpender", "0xHolder")) { ... }
+   * ```
+   */
+  async isApproved(spender, holder) {
+    const normalizedSpender = normalizeAddress(spender, "spender");
+    const resolvedHolder = holder ? normalizeAddress(holder, "holder") : await this.signer.getAddress();
+    return this.signer.readContract(
+      isOperatorContract(this.address, resolvedHolder, normalizedSpender)
+    );
+  }
+  /**
+   * Shield public ERC-20 tokens into confidential tokens.
+   * Handles ERC-20 approval automatically based on `approvalStrategy`
+   * (`"exact"` by default, `"max"` for unlimited approval, `"skip"` to opt out).
+   *
+   * @param amount - The plaintext amount to shield.
+   * @param options - Optional configuration: `approvalStrategy` (`"exact"` | `"max"` | `"skip"`, default `"exact"`), `fees` (extra ETH for native wrappers).
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link ApprovalFailedError} if the ERC-20 approval step fails.
+   * @throws {@link TransactionRevertedError} if the shield transaction reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.shield(1000n);
+   * // or with exact approval:
+   * const txHash = await token.shield(1000n, { approvalStrategy: "exact" });
+   * ```
+   */
+  async shield(amount, options) {
+    const underlying = await this.#getUnderlying();
+    if (underlying === _Token.ZERO_ADDRESS) {
+      return this.shieldETH(amount, amount + (options?.fees ?? 0n));
+    }
+    const strategy = options?.approvalStrategy ?? "exact";
+    if (strategy !== "skip") {
+      await this.#ensureAllowance(amount, strategy === "max", options?.callbacks);
+    }
+    try {
+      const recipient = options?.to ? normalizeAddress(options.to, "to") : await this.signer.getAddress();
+      const txHash = await this.signer.writeContract(wrapContract(this.wrapper, recipient, amount));
+      this.emit({ type: ZamaSDKEvents.ShieldSubmitted, txHash });
+      safeCallback(() => options?.callbacks?.onShieldSubmitted?.(txHash));
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "shield",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("Shield transaction failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * Shield native ETH into confidential tokens. `value` defaults to `amount`.
+   *
+   * @param amount - The amount of ETH to shield (in wei).
+   * @param value - Optional ETH value to send. Defaults to `amount`.
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link TransactionRevertedError} if the shield transaction reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.shieldETH(1000000000000000000n); // 1 ETH
+   * ```
+   */
+  async shieldETH(amount, value) {
+    try {
+      const userAddress = await this.signer.getAddress();
+      const txHash = await this.signer.writeContract(
+        wrapETHContract(this.wrapper, userAddress, amount, value ?? amount)
+      );
+      this.emit({ type: ZamaSDKEvents.ShieldSubmitted, txHash });
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "shieldETH",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("Shield ETH transaction failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * Request an unwrap for a specific amount. Encrypts the amount first.
+   * Call {@link finalizeUnwrap} after the request is processed on-chain.
+   *
+   * @param amount - The plaintext amount to unwrap (encrypted automatically).
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link EncryptionFailedError} if FHE encryption fails.
+   * @throws {@link TransactionRevertedError} if the unwrap transaction reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.unwrap(500n);
+   * ```
+   */
+  async unwrap(amount) {
+    const userAddress = await this.signer.getAddress();
+    let handles;
+    let inputProof;
+    const t0 = Date.now();
+    try {
+      this.emit({ type: ZamaSDKEvents.EncryptStart });
+      ({ handles, inputProof } = await this.sdk.encrypt({
+        values: [{ value: amount, type: "euint64" }],
+        contractAddress: this.wrapper,
+        userAddress
+      }));
+      this.emit({ type: ZamaSDKEvents.EncryptEnd, durationMs: Date.now() - t0 });
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.EncryptError,
+        error: toError2(error),
+        durationMs: Date.now() - t0
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new EncryptionFailedError("Failed to encrypt unshield amount", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+    if (handles.length === 0) {
+      throw new EncryptionFailedError("Encryption returned no handles");
+    }
+    try {
+      const txHash = await this.signer.writeContract(
+        unwrapContract(this.address, userAddress, userAddress, handles[0], inputProof)
+      );
+      this.emit({ type: ZamaSDKEvents.UnwrapSubmitted, txHash });
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "unwrap",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("Unshield transaction failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * Request an unwrap for the entire confidential balance.
+   * Uses the on-chain balance handle directly (no encryption needed).
+   * Throws if the balance is zero.
+   *
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link DecryptionFailedError} if the balance is zero.
+   * @throws {@link TransactionRevertedError} if the unwrap transaction reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.unwrapAll();
+   * ```
+   */
+  async unwrapAll() {
+    const userAddress = await this.signer.getAddress();
+    const handle = await this.readConfidentialBalanceOf(userAddress);
+    if (this.isZeroHandle(handle)) {
+      throw new DecryptionFailedError("Cannot unshield: balance is zero");
+    }
+    try {
+      const txHash = await this.signer.writeContract(
+        unwrapFromBalanceContract(this.address, userAddress, userAddress, handle)
+      );
+      this.emit({ type: ZamaSDKEvents.UnwrapSubmitted, txHash });
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "unwrap",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("Unshield-all transaction failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * Unshield a specific amount and finalize in one call.
+   * Orchestrates: unshield → wait for receipt → parse event → finalize.
+   *
+   * @param amount - The plaintext amount to unshield.
+   * @param callbacks - Optional progress callbacks for each phase.
+   * @returns The finalize transaction hash and mined receipt.
+   * @throws {@link EncryptionFailedError} if FHE encryption fails.
+   * @throws {@link TransactionRevertedError} if any transaction in the flow reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.unshield(500n);
+   * ```
+   */
+  async unshield(amount, callbacks) {
+    const operationId = crypto.randomUUID();
+    const unwrapResult = await this.unwrap(amount);
+    safeCallback(() => callbacks?.onUnwrapSubmitted?.(unwrapResult.txHash));
+    return this.#waitAndFinalizeUnshield(unwrapResult.txHash, callbacks, operationId);
+  }
+  /**
+   * Unshield the entire balance and finalize in one call.
+   * Orchestrates: unshieldAll → wait for receipt → parse event → finalize.
+   *
+   * @param callbacks - Optional progress callbacks for each phase.
+   * @returns The finalize transaction hash and mined receipt.
+   * @throws {@link DecryptionFailedError} if the balance is zero.
+   * @throws {@link TransactionRevertedError} if any transaction in the flow reverts.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.unshieldAll();
+   * ```
+   */
+  async unshieldAll(callbacks) {
+    const operationId = crypto.randomUUID();
+    const unwrapResult = await this.unwrapAll();
+    safeCallback(() => callbacks?.onUnwrapSubmitted?.(unwrapResult.txHash));
+    return this.#waitAndFinalizeUnshield(unwrapResult.txHash, callbacks, operationId);
+  }
+  /**
+   * 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.
+   * @throws {@link TransactionRevertedError} if finalization fails.
+   *
+   * @example
+   * ```ts
+   * const txHash = await token.resumeUnshield(previousUnwrapTxHash);
+   * ```
+   */
+  async resumeUnshield(unwrapTxHash, callbacks) {
+    return this.#waitAndFinalizeUnshield(unwrapTxHash, callbacks, crypto.randomUUID());
+  }
+  /**
+   * Complete an unwrap by providing the public decryption proof.
+   * Call this after an unshield request has been processed on-chain.
+   *
+   * @param burnAmountHandle - The encrypted amount handle from the `UnwrapRequested` event.
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link DecryptionFailedError} if public decryption fails.
+   * @throws {@link TransactionRevertedError} if the finalize transaction reverts.
+   *
+   * @example
+   * ```ts
+   * const event = findUnwrapRequested(receipt.logs);
+   * const txHash = await token.finalizeUnwrap(event.encryptedAmount);
+   * ```
+   */
+  async finalizeUnwrap(burnAmountHandle) {
+    let clearValue;
+    let decryptionProof;
+    const t0 = Date.now();
+    try {
+      this.emit({ type: ZamaSDKEvents.DecryptStart });
+      const result = await this.sdk.publicDecrypt([burnAmountHandle]);
+      this.emit({ type: ZamaSDKEvents.DecryptEnd, durationMs: Date.now() - t0 });
+      decryptionProof = result.decryptionProof;
+      try {
+        clearValue = BigInt(result.abiEncodedClearValues);
+      } catch {
+        throw new DecryptionFailedError(
+          `Cannot parse decrypted value: ${result.abiEncodedClearValues}`
+        );
+      }
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.DecryptError,
+        error: toError2(error),
+        durationMs: Date.now() - t0
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new DecryptionFailedError("Failed to finalize unshield", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+    try {
+      const txHash = await this.signer.writeContract(
+        finalizeUnwrapContract(this.wrapper, burnAmountHandle, clearValue, decryptionProof)
+      );
+      this.emit({ type: ZamaSDKEvents.FinalizeUnwrapSubmitted, txHash });
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "finalizeUnwrap",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("Failed to finalize unshield", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  /**
+   * Approve this token contract to spend the underlying ERC-20.
+   * Defaults to max uint256. Resets to zero first if there's an existing
+   * non-zero allowance (required by tokens like USDT).
+   *
+   * @param amount - Optional approval amount. Defaults to max uint256.
+   * @returns The transaction hash and mined receipt.
+   * @throws {@link ApprovalFailedError} if the approval transaction fails.
+   *
+   * @example
+   * ```ts
+   * await token.approveUnderlying(); // max approval
+   * await token.approveUnderlying(1000n); // exact amount
+   * ```
+   */
+  async approveUnderlying(amount) {
+    const underlying = await this.#getUnderlying();
+    const approvalAmount = amount ?? 2n ** 256n - 1n;
+    try {
+      if (approvalAmount > 0n) {
+        const userAddress = await this.signer.getAddress();
+        const currentAllowance = await this.signer.readContract(
+          allowanceContract(underlying, userAddress, this.wrapper)
+        );
+        if (currentAllowance > 0n) {
+          await this.signer.writeContract(approveContract(underlying, this.wrapper, 0n));
+        }
+      }
+      const txHash = await this.signer.writeContract(
+        approveContract(underlying, this.wrapper, approvalAmount)
+      );
+      this.emit({ type: ZamaSDKEvents.ApproveUnderlyingSubmitted, txHash });
+      const receipt = await this.signer.waitForTransactionReceipt(txHash);
+      return { txHash, receipt };
+    } catch (error) {
+      this.emit({
+        type: ZamaSDKEvents.TransactionError,
+        operation: "approveUnderlying",
+        error: toError2(error)
+      });
+      if (error instanceof ZamaError) throw error;
+      throw new ApprovalFailedError("ERC-20 approval failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  // PRIVATE HELPERS
+  async #waitAndFinalizeUnshield(unshieldHash, callbacks, operationId) {
+    this.emit({ type: ZamaSDKEvents.UnshieldPhase1Submitted, txHash: unshieldHash, operationId });
+    let receipt;
+    try {
+      receipt = await this.signer.waitForTransactionReceipt(unshieldHash);
+    } catch (error) {
+      if (error instanceof ZamaError) throw error;
+      throw new TransactionRevertedError("Failed to get unshield receipt", {
+        cause: error
+      });
+    }
+    const event = findUnwrapRequested(receipt.logs);
+    if (!event) {
+      throw new TransactionRevertedError("No UnwrapRequested event found in unshield receipt");
+    }
+    this.emit({ type: ZamaSDKEvents.UnshieldPhase2Started, operationId });
+    safeCallback(() => callbacks?.onFinalizing?.());
+    const finalizeResult = await this.finalizeUnwrap(event.encryptedAmount);
+    this.emit({
+      type: ZamaSDKEvents.UnshieldPhase2Submitted,
+      txHash: finalizeResult.txHash,
+      operationId
+    });
+    safeCallback(() => callbacks?.onFinalizeSubmitted?.(finalizeResult.txHash));
+    return finalizeResult;
+  }
+  async #ensureAllowance(amount, maxApproval, callbacks) {
+    const underlying = await this.#getUnderlying();
+    const userAddress = await this.signer.getAddress();
+    const allowance = await this.signer.readContract(
+      allowanceContract(underlying, userAddress, this.wrapper)
+    );
+    if (allowance >= amount) return;
+    try {
+      if (allowance > 0n) {
+        await this.signer.writeContract(approveContract(underlying, this.wrapper, 0n));
+      }
+      const approvalAmount = maxApproval ? 2n ** 256n - 1n : amount;
+      const txHash = await this.signer.writeContract(
+        approveContract(underlying, this.wrapper, approvalAmount)
+      );
+      this.emit({ type: ZamaSDKEvents.ApproveUnderlyingSubmitted, txHash });
+      safeCallback(() => callbacks?.onApprovalSubmitted?.(txHash));
+    } catch (error) {
+      if (error instanceof ZamaError) throw error;
+      throw new ApprovalFailedError("ERC-20 approval failed", {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+};
+function safeCallback(fn) {
+  try {
+    fn();
+  } catch {
+  }
+}
+
+// src/token/zama-sdk.ts
+var ZamaSDK = class {
+  relayer;
+  signer;
+  storage;
+  sessionStorage;
+  credentials;
+  #onEvent;
+  #unsubscribeSigner;
+  #identityReady;
+  #lastAddress = null;
+  #lastChainId = null;
+  constructor(config) {
+    this.relayer = config.relayer;
+    this.signer = config.signer;
+    this.storage = config.storage;
+    this.sessionStorage = config.sessionStorage ?? new MemoryStorage();
+    this.#onEvent = config.onEvent ?? function() {
+    };
+    this.credentials = new CredentialsManager({
+      relayer: this.relayer,
+      signer: this.signer,
+      storage: this.storage,
+      sessionStorage: this.sessionStorage,
+      durationDays: config.credentialDurationDays ?? 1,
+      onEvent: this.#onEvent
+    });
+    this.#identityReady = this.#initIdentity();
+    if (this.signer.subscribe) {
+      this.#unsubscribeSigner = this.signer.subscribe({
+        onDisconnect: () => {
+          void this.#revokeByTrackedIdentity().then(() => {
+            this.#lastAddress = null;
+            this.#lastChainId = null;
+          });
+        },
+        onAccountChange: (newAddress) => {
+          void this.#revokeByTrackedIdentity().then(async () => {
+            this.#lastAddress = newAddress.toLowerCase();
+            try {
+              this.#lastChainId = await this.signer.getChainId();
+            } catch {
+            }
+          });
+        }
+      });
+    }
+  }
+  async #initIdentity() {
+    try {
+      const address = (await this.signer.getAddress()).toLowerCase();
+      const chainId = await this.signer.getChainId();
+      this.#lastAddress = address;
+      this.#lastChainId = chainId;
+    } catch {
+    }
+  }
+  async #revokeByTrackedIdentity() {
+    await this.#identityReady;
+    if (this.#lastAddress == null || this.#lastChainId == null) return;
+    const storeKey = await computeStoreKey(this.#lastAddress, this.#lastChainId);
+    await this.sessionStorage.delete(storeKey);
+    this.#onEvent?.({
+      type: ZamaSDKEvents.CredentialsRevoked,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Create a read-only interface for a confidential token.
+   * Supports balance queries and authorization without a wrapper address.
+   *
+   * @param address - The confidential token contract address.
+   * @returns A {@link ReadonlyToken} instance bound to this SDK's relayer, signer, and storage.
+   */
+  createReadonlyToken(address) {
+    return new ReadonlyToken({
+      relayer: this.relayer,
+      signer: this.signer,
+      storage: this.storage,
+      sessionStorage: this.sessionStorage,
+      credentials: this.credentials,
+      address: normalizeAddress(address, "address"),
+      onEvent: this.#onEvent
+    });
+  }
+  /**
+   * Create a high-level ERC-20-like interface for a confidential token.
+   * Includes write operations (transfer, shield, unshield).
+   *
+   * @param address - The confidential token contract address (also used as wrapper by default).
+   * @param wrapper - Optional explicit wrapper address, if it differs from the token address.
+   * @returns A {@link Token} instance bound to this SDK's relayer, signer, and storage.
+   */
+  createToken(address, wrapper) {
+    return new Token({
+      relayer: this.relayer,
+      signer: this.signer,
+      storage: this.storage,
+      sessionStorage: this.sessionStorage,
+      credentials: this.credentials,
+      address: normalizeAddress(address, "address"),
+      wrapper: wrapper ? normalizeAddress(wrapper, "wrapper") : void 0,
+      onEvent: this.#onEvent
+    });
+  }
+  /**
+   * Pre-authorize FHE credentials for one or more contract addresses.
+   * A single wallet signature covers all addresses, so subsequent decrypt
+   * operations on any of these tokens reuse cached credentials.
+   *
+   * @param contractAddresses - Token contract addresses to authorize.
+   *
+   * @example
+   * ```ts
+   * await sdk.allow("0xTokenA", "0xTokenB");
+   * ```
+   */
+  async allow(...contractAddresses) {
+    await this.credentials.allow(...contractAddresses);
+  }
+  /**
+   * Revoke the session signature for the current signer.
+   * The next decrypt operation will require a fresh wallet signature.
+   *
+   * @param contractAddresses - Optional addresses included in the
+   *   `credentials:revoked` event for observability.
+   *
+   * @example
+   * ```ts
+   * wallet.on("disconnect", () => sdk.revoke());
+   * await sdk.revoke("0xTokenA", "0xTokenB");
+   * ```
+   */
+  async revoke(...contractAddresses) {
+    await this.credentials.revoke(...contractAddresses);
+  }
+  /**
+   * Revoke the session signature for the current signer without requiring
+   * contract addresses. Uses the tracked identity when available (safe during
+   * account switches), falling back to querying the signer directly.
+   *
+   * @example
+   * ```ts
+   * wallet.on("disconnect", () => sdk.revokeSession());
+   * ```
+   */
+  async revokeSession() {
+    await this.#identityReady;
+    const address = this.#lastAddress ?? (await this.signer.getAddress()).toLowerCase();
+    const chainId = this.#lastChainId ?? await this.signer.getChainId();
+    const storeKey = await computeStoreKey(address, chainId);
+    await this.sessionStorage.delete(storeKey);
+    this.#onEvent?.({
+      type: ZamaSDKEvents.CredentialsRevoked,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Whether a session signature is currently cached for the connected wallet.
+   * Use this to check if decrypt operations can proceed without a wallet prompt.
+   */
+  async isAllowed() {
+    return this.credentials.isAllowed();
+  }
+  /**
+   * Unsubscribe from signer lifecycle events without terminating the relayer.
+   * Call this when the SDK instance is being replaced but the relayer is shared
+   * (e.g. React provider remount in Strict Mode).
+   */
+  dispose() {
+    this.#unsubscribeSigner?.();
+    this.#unsubscribeSigner = void 0;
+  }
+  /**
+   * Terminate the relayer backend and clean up resources.
+   * Call this when the SDK is no longer needed (e.g. on unmount or shutdown).
+   */
+  terminate() {
+    this.dispose();
+    this.relayer.terminate();
+  }
+};
+
+// src/token/indexeddb-storage.ts
+var IndexedDBStorage = class {
+  #db = null;
+  #dbPromise = null;
+  #dbName;
+  #dbVersion;
+  #storeName = "credentials";
+  constructor(dbName = "CredentialStore", dbVersion = 1) {
+    this.#dbName = dbName;
+    this.#dbVersion = dbVersion;
+  }
+  #getDB() {
+    if (this.#db) return Promise.resolve(this.#db);
+    if (this.#dbPromise) return this.#dbPromise;
+    this.#dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.#dbName, this.#dbVersion);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(this.#storeName)) {
+          db.createObjectStore(this.#storeName, { keyPath: "key" });
+        }
+      };
+      request.onsuccess = () => {
+        this.#db = request.result;
+        this.#dbPromise = null;
+        this.#db.onversionchange = () => {
+          this.#db?.close();
+          this.#db = null;
+          this.#dbPromise = null;
+        };
+        this.#db.onclose = () => {
+          this.#db = null;
+          this.#dbPromise = null;
+        };
+        resolve(this.#db);
+      };
+      request.onerror = () => {
+        this.#db = null;
+        this.#dbPromise = null;
+        reject(request.error);
+      };
+    });
+    return this.#dbPromise;
+  }
+  async get(key) {
+    const db = await this.#getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.#storeName, "readonly");
+      tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted"));
+      const store = tx.objectStore(this.#storeName);
+      const request = store.get(key);
+      request.onsuccess = () => resolve(request.result?.value ?? null);
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async set(key, value) {
+    const db = await this.#getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.#storeName, "readwrite");
+      tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted"));
+      const store = tx.objectStore(this.#storeName);
+      const request = store.put({ key, value });
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async delete(key) {
+    const db = await this.#getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.#storeName, "readwrite");
+      tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted"));
+      const store = tx.objectStore(this.#storeName);
+      const request = store.delete(key);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async clear() {
+    const db = await this.#getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.#storeName, "readwrite");
+      tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted"));
+      const store = tx.objectStore(this.#storeName);
+      const request = store.clear();
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+};
+var indexedDBStorage = new IndexedDBStorage();
+
+// src/token/chrome-session-storage.ts
+var ChromeSessionStorage = class {
+  async get(key) {
+    const result = await chrome.storage.session.get(key);
+    return result[key] ?? null;
+  }
+  async set(key, value) {
+    await chrome.storage.session.set({ [key]: value });
+  }
+  async delete(key) {
+    await chrome.storage.session.remove(key);
+  }
+};
+var chromeSessionStorage = new ChromeSessionStorage();
+
+// src/token/pending-unshield.ts
+var STORAGE_PREFIX = "zama:pending-unshield:";
+function storageKey2(wrapperAddress) {
+  return `${STORAGE_PREFIX}${wrapperAddress.toLowerCase()}`;
+}
+async function savePendingUnshield(storage, wrapperAddress, unwrapTxHash) {
+  await storage.set(storageKey2(wrapperAddress), unwrapTxHash);
+}
+async function loadPendingUnshield(storage, wrapperAddress) {
+  return await storage.get(storageKey2(wrapperAddress));
+}
+async function clearPendingUnshield(storage, wrapperAddress) {
+  await storage.delete(storageKey2(wrapperAddress));
+}
+
+// src/activity.ts
+function addressesEqual(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function classifyDirection(userAddress, from, to) {
+  const isFrom = from !== void 0 && addressesEqual(userAddress, from);
+  const isTo = to !== void 0 && addressesEqual(userAddress, to);
+  if (isFrom && isTo) return "self";
+  if (isFrom) return "outgoing";
+  return "incoming";
+}
+function eventToActivityItem(event, userAddress, metadata) {
+  switch (event.eventName) {
+    case "ConfidentialTransfer":
+      return buildTransfer(event, userAddress, metadata);
+    case "Wrapped":
+      return buildShield(event, userAddress, metadata);
+    case "UnwrapRequested":
+      return buildUnshieldRequested(event, userAddress, metadata);
+    case "UnwrappedStarted":
+      return buildUnshieldStarted(event, userAddress, metadata);
+    case "UnwrappedFinalized":
+      return buildUnshieldFinalized(event, metadata);
+  }
+}
+function buildTransfer(event, userAddress, metadata) {
+  return {
+    type: "transfer",
+    direction: classifyDirection(userAddress, event.from, event.to),
+    amount: { type: "encrypted", handle: event.encryptedAmountHandle },
+    from: event.from,
+    to: event.to,
+    metadata,
+    rawEvent: event
+  };
+}
+function buildShield(event, userAddress, metadata) {
+  return {
+    type: "shield",
+    direction: classifyDirection(userAddress, void 0, event.to),
+    amount: { type: "clear", value: event.amountIn },
+    to: event.to,
+    fee: event.feeAmount,
+    metadata,
+    rawEvent: event
+  };
+}
+function buildUnshieldRequested(event, userAddress, metadata) {
+  return {
+    type: "unshield_requested",
+    direction: classifyDirection(userAddress, void 0, event.receiver),
+    amount: { type: "encrypted", handle: event.encryptedAmount },
+    to: event.receiver,
+    metadata,
+    rawEvent: event
+  };
+}
+function buildUnshieldStarted(event, userAddress, metadata) {
+  return {
+    type: "unshield_started",
+    direction: classifyDirection(userAddress, void 0, event.to),
+    amount: { type: "encrypted", handle: event.requestedAmount },
+    to: event.to,
+    success: event.returnVal,
+    metadata,
+    rawEvent: event
+  };
+}
+function buildUnshieldFinalized(event, metadata) {
+  return {
+    type: "unshield_finalized",
+    // Finalized events don't carry from/to addresses, always treat as incoming
+    direction: "incoming",
+    amount: { type: "clear", value: event.unwrapAmount },
+    fee: event.feeAmount,
+    success: event.finalizeSuccess,
+    metadata,
+    rawEvent: event
+  };
+}
+function parseActivityFeed(logs, userAddress) {
+  const items = [];
+  for (const log of logs) {
+    const event = decodeOnChainEvent(log);
+    if (!event) continue;
+    const metadata = {
+      transactionHash: log.transactionHash,
+      blockNumber: log.blockNumber,
+      logIndex: log.logIndex
+    };
+    items.push(eventToActivityItem(event, userAddress, metadata));
+  }
+  return items;
+}
+function extractEncryptedHandles(items) {
+  const handles = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    if (item.amount.type === "encrypted" && item.amount.decryptedValue === void 0) {
+      const h = item.amount.handle;
+      if (h !== "0x" && h !== ZERO_HANDLE) {
+        handles.add(h);
+      }
+    }
+  }
+  return [...handles];
+}
+function applyDecryptedValues(items, decryptedMap) {
+  return items.map((item) => {
+    if (item.amount.type !== "encrypted") return item;
+    const value = decryptedMap.get(item.amount.handle);
+    if (value === void 0) return item;
+    return {
+      ...item,
+      amount: {
+        type: "encrypted",
+        handle: item.amount.handle,
+        decryptedValue: value
+      }
+    };
+  });
+}
+function sortByBlockNumber(items) {
+  return [...items].sort((a, b) => {
+    const aBlock = a.metadata.blockNumber;
+    const bBlock = b.metadata.blockNumber;
+    if (aBlock === void 0 && bBlock === void 0) return 0;
+    if (aBlock === void 0) return -1;
+    if (bBlock === void 0) return 1;
+    const aBig = typeof aBlock === "bigint" ? aBlock : BigInt(aBlock);
+    const bBig = typeof bBlock === "bigint" ? bBlock : BigInt(bBlock);
+    if (bBig > aBig) return 1;
+    if (bBig < aBig) return -1;
+    const aIdx = a.metadata.logIndex ?? 0;
+    const bIdx = b.metadata.logIndex ?? 0;
+    return bIdx - aIdx;
+  });
+}
+
+export { BATCH_SWAP_ABI, ChromeSessionStorage, CredentialsManager, IndexedDBStorage, MemoryStorage, ReadonlyToken, RelayerWeb, TOKEN_TOPICS, Token, Topics, ZERO_HANDLE, ZamaSDK, ZamaSDKEvents, applyDecryptedValues, chromeSessionStorage, clearPendingUnshield, decodeConfidentialTransfer, decodeOnChainEvent, decodeOnChainEvents, decodeUnwrapRequested, decodeUnwrappedFinalized, decodeUnwrappedStarted, decodeWrapped, extractEncryptedHandles, findUnwrapRequested, findWrapped, indexedDBStorage, loadPendingUnshield, memoryStorage, parseActivityFeed, savePendingUnshield, sortByBlockNumber };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map