@gasfree-kit/evm-4337 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -4,8 +4,16 @@ var DEFAULT_ENTRY_POINT = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
 var DEFAULT_SAFE_MODULES_VERSION = "0.3.0";
 var DEFAULT_PAYMASTER_ADDRESS = "0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba";
 var DEFAULT_TRANSFER_MAX_FEE = 1e15;
+function getNormalizedSponsorshipPolicyId(config) {
+  const sponsorshipPolicyId = config.sponsorshipPolicyId?.trim() ?? "";
+  if (config.isSponsored && !sponsorshipPolicyId) {
+    throw new Error("sponsorshipPolicyId is required when isSponsored is true");
+  }
+  return sponsorshipPolicyId;
+}
 function getErc4337ConfigForChain(config) {
   const chainConfig = EVM_CHAINS[config.chain];
+  const sponsorshipPolicyId = getNormalizedSponsorshipPolicyId(config);
   return {
     chainId: chainConfig.chainId,
     provider: config.rpcUrl,
@@ -16,7 +24,7 @@ function getErc4337ConfigForChain(config) {
     safeModulesVersion: config.safeModulesVersion ?? DEFAULT_SAFE_MODULES_VERSION,
     transferMaxFee: DEFAULT_TRANSFER_MAX_FEE,
     isSponsored: config.isSponsored,
-    sponsorshipPolicyId: config.sponsorshipPolicyId ?? "",
+    sponsorshipPolicyId,
     paymasterToken: {
       address: config.paymasterTokenAddress ?? chainConfig.usdtAddress
     }
@@ -28,7 +36,8 @@ var GAS_FEE_FALLBACKS = {
   polygon: 100000n,
   celo: 50000n,
   optimism: 100000n,
-  base: 150000n
+  base: 150000n,
+  plasma: 50000n
 };
 var GAS_FEE_ESTIMATES = {
   ethereum: "1.40",
@@ -36,11 +45,639 @@ var GAS_FEE_ESTIMATES = {
   polygon: "0.10",
   celo: "0.05",
   optimism: "0.10",
-  base: "0.15"
+  base: "0.15",
+  plasma: "0.05"
+};
+
+// src/passkey/linkPasskey.ts
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+import { TransactionFailedError as TransactionFailedError2 } from "@gasfree-kit/core";
+
+// src/userOpUtils.ts
+import { Bundler, SendUseroperationResponse } from "abstractionkit";
+import { InsufficientBalanceError, TransactionFailedError } from "@gasfree-kit/core";
+var USER_OP_TIMEOUT_MS = 12e4;
+async function waitForUserOpConfirmation(userOpHash, bundlerUrl, entryPointAddress) {
+  const bundler = new Bundler(bundlerUrl);
+  const response = new SendUseroperationResponse(userOpHash, bundler, entryPointAddress);
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(
+      () => reject(
+        new TransactionFailedError(
+          "evm",
+          `UserOperation confirmation timed out after ${USER_OP_TIMEOUT_MS / 1e3}s. Hash: ${userOpHash}`
+        )
+      ),
+      USER_OP_TIMEOUT_MS
+    );
+  });
+  const receipt = await Promise.race([response.included(), timeoutPromise]);
+  if (!receipt.success) {
+    throw new TransactionFailedError(
+      "evm",
+      `UserOperation reverted. Tx: ${receipt.receipt.transactionHash}`
+    );
+  }
+  return receipt.receipt.transactionHash;
+}
+function handleTransferError(error, chain) {
+  if (!(error instanceof Error)) {
+    return new TransactionFailedError(chain, "Unknown error");
+  }
+  const msg = error.message;
+  if (msg.includes("callData reverts")) {
+    return new TransactionFailedError(
+      chain,
+      "Transaction reverted. Check your balance and try again."
+    );
+  }
+  if (msg.includes("not enough funds")) {
+    return new InsufficientBalanceError(chain, "paymaster token");
+  }
+  if (msg.includes("token balance lower than the required") || msg.includes("token allowance lower than the required")) {
+    return new InsufficientBalanceError(chain, "USDT (insufficient for transfer + gas)");
+  }
+  if (msg.includes("Insufficient") || error instanceof InsufficientBalanceError) {
+    return error;
+  }
+  if (msg.includes("nonce too low")) {
+    return new TransactionFailedError(chain, "Nonce conflict. Please try again.");
+  }
+  if (msg.includes("insufficient funds") || msg.includes("transfer amount exceeds balance")) {
+    return new InsufficientBalanceError(chain, "USDT");
+  }
+  if (msg.includes("transaction underpriced") || msg.includes("max fee per gas less than block base fee")) {
+    return new TransactionFailedError(chain, "Gas price too low. Please try again.");
+  }
+  if (msg.includes("out of gas") || msg.includes("intrinsic gas too low")) {
+    return new TransactionFailedError(chain, "Insufficient gas limit.");
+  }
+  if (msg.includes("execution reverted")) {
+    return new TransactionFailedError(chain, "Transaction reverted on-chain.");
+  }
+  if (msg.includes("504") || msg.includes("Gateway Time-out")) {
+    return new TransactionFailedError(chain, "Network timeout. Please try again.");
+  }
+  return new TransactionFailedError(chain, msg);
+}
+
+// src/passkey/credentialStore.ts
+var STORAGE_KEY = "@gasfree-kit/passkey-credentials";
+function serialize(cred) {
+  return {
+    id: cred.id,
+    publicKey: {
+      x: cred.publicKey.x.toString(),
+      y: cred.publicKey.y.toString()
+    },
+    signerAddress: cred.signerAddress,
+    safeAddress: cred.safeAddress
+  };
+}
+function deserialize(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Invalid stored credential: not an object");
+  }
+  const obj = raw;
+  if (typeof obj.id !== "string" || !obj.id) {
+    throw new Error("Invalid stored credential: missing or invalid id");
+  }
+  if (typeof obj.signerAddress !== "string" || !obj.signerAddress) {
+    throw new Error("Invalid stored credential: missing or invalid signerAddress");
+  }
+  if (typeof obj.safeAddress !== "string" || !obj.safeAddress) {
+    throw new Error("Invalid stored credential: missing or invalid safeAddress");
+  }
+  const pk = obj.publicKey;
+  if (!pk || typeof pk !== "object" || typeof pk.x !== "string" || typeof pk.y !== "string") {
+    throw new Error("Invalid stored credential: missing or invalid publicKey");
+  }
+  let x;
+  let y;
+  try {
+    x = BigInt(pk.x);
+    y = BigInt(pk.y);
+  } catch {
+    throw new Error("Invalid stored credential: publicKey coordinates are not valid integers");
+  }
+  return {
+    id: obj.id,
+    publicKey: { x, y },
+    signerAddress: obj.signerAddress,
+    safeAddress: obj.safeAddress
+  };
+}
+var BrowserCredentialStore = class {
+  readAll() {
+    try {
+      const data = localStorage.getItem(STORAGE_KEY);
+      return data ? JSON.parse(data) : [];
+    } catch {
+      return [];
+    }
+  }
+  writeAll(credentials) {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(credentials));
+  }
+  async save(credential) {
+    const all = this.readAll();
+    const idx = all.findIndex(
+      (c) => c.safeAddress.toLowerCase() === credential.safeAddress.toLowerCase()
+    );
+    const serialized = serialize(credential);
+    if (idx >= 0) {
+      all[idx] = serialized;
+    } else {
+      all.push(serialized);
+    }
+    this.writeAll(all);
+  }
+  async load(safeAddress) {
+    const all = this.readAll();
+    const found = all.find((c) => c.safeAddress.toLowerCase() === safeAddress.toLowerCase());
+    return found ? deserialize(found) : null;
+  }
+  async remove(safeAddress) {
+    const all = this.readAll();
+    const filtered = all.filter((c) => c.safeAddress.toLowerCase() !== safeAddress.toLowerCase());
+    this.writeAll(filtered);
+  }
+  async listAll() {
+    return this.readAll().map(deserialize);
+  }
 };
+var NodeCredentialStore = class {
+  filePath = null;
+  async getFilePath() {
+    if (this.filePath) return this.filePath;
+    const os = await import("os");
+    const path = await import("path");
+    this.filePath = path.join(os.homedir(), ".gasfree-kit", "passkey-credentials.json");
+    return this.filePath;
+  }
+  async ensureDir(filePath) {
+    const path = await import("path");
+    const fs = await import("fs/promises");
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 448 });
+  }
+  async readAll() {
+    try {
+      const fs = await import("fs/promises");
+      const filePath = await this.getFilePath();
+      const data = await fs.readFile(filePath, "utf-8");
+      const parsed = JSON.parse(data);
+      if (!Array.isArray(parsed)) return [];
+      return parsed;
+    } catch {
+      return [];
+    }
+  }
+  async writeAll(credentials) {
+    const fs = await import("fs/promises");
+    const filePath = await this.getFilePath();
+    await this.ensureDir(filePath);
+    const tmpPath = filePath + ".tmp." + Date.now();
+    try {
+      await fs.writeFile(tmpPath, JSON.stringify(credentials, null, 2), {
+        encoding: "utf-8",
+        mode: 384
+      });
+      await fs.rename(tmpPath, filePath);
+      await fs.chmod(filePath, 384);
+    } catch (err) {
+      try {
+        await fs.unlink(tmpPath);
+      } catch {
+      }
+      throw err;
+    }
+  }
+  async save(credential) {
+    const all = await this.readAll();
+    const idx = all.findIndex(
+      (c) => c.safeAddress.toLowerCase() === credential.safeAddress.toLowerCase()
+    );
+    const serialized = serialize(credential);
+    if (idx >= 0) {
+      all[idx] = serialized;
+    } else {
+      all.push(serialized);
+    }
+    await this.writeAll(all);
+  }
+  async load(safeAddress) {
+    const all = await this.readAll();
+    const found = all.find((c) => c.safeAddress.toLowerCase() === safeAddress.toLowerCase());
+    return found ? deserialize(found) : null;
+  }
+  async remove(safeAddress) {
+    const all = await this.readAll();
+    const filtered = all.filter((c) => c.safeAddress.toLowerCase() !== safeAddress.toLowerCase());
+    await this.writeAll(filtered);
+  }
+  async listAll() {
+    return (await this.readAll()).map(deserialize);
+  }
+};
+function createCredentialStore() {
+  const isBrowser = typeof window !== "undefined" && typeof localStorage !== "undefined" && typeof navigator !== "undefined" && typeof navigator.credentials !== "undefined";
+  if (isBrowser) {
+    return new BrowserCredentialStore();
+  }
+  return new NodeCredentialStore();
+}
+
+// src/passkey/rpcUtils.ts
+function sanitizeRpcUrl(rpcUrl) {
+  try {
+    const url = new URL(rpcUrl);
+    return url.origin;
+  } catch {
+    return "(invalid URL)";
+  }
+}
+async function jsonRpcCall(rpcUrl, request) {
+  if (!rpcUrl) {
+    throw new Error("RPC URL is not configured");
+  }
+  const safeUrl = sanitizeRpcUrl(rpcUrl);
+  let response;
+  try {
+    response = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: request.method,
+        params: request.params
+      })
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`RPC network error (${safeUrl}): ${msg}`);
+  }
+  if (!response.ok) {
+    throw new Error(`RPC HTTP ${response.status}: ${response.statusText} (${safeUrl})`);
+  }
+  let json;
+  try {
+    json = await response.json();
+  } catch {
+    throw new Error(`RPC returned non-JSON response (${safeUrl})`);
+  }
+  if (json.error) {
+    const code = json.error.code ? ` (${json.error.code})` : "";
+    throw new Error(`RPC error${code}: ${json.error.message ?? "unknown error"}`);
+  }
+  if (json.result === void 0 || json.result === null) {
+    throw new Error(`RPC returned null result for ${request.method}`);
+  }
+  return json.result;
+}
+async function isContractDeployed(rpcUrl, address) {
+  const code = await jsonRpcCall(rpcUrl, {
+    method: "eth_getCode",
+    params: [address, "latest"]
+  });
+  return code !== "0x" && code !== "0x0";
+}
+async function getSafeOwners(rpcUrl, safeAddress) {
+  const GET_OWNERS_SELECTOR = "0xa0e67e2b";
+  const result = await jsonRpcCall(rpcUrl, {
+    method: "eth_call",
+    params: [{ to: safeAddress, data: GET_OWNERS_SELECTOR }, "latest"]
+  });
+  const hex = result.startsWith("0x") ? result.slice(2) : result;
+  if (hex.length < 128) {
+    throw new Error(`Invalid getOwners response from ${safeAddress}`);
+  }
+  const arrayLength = parseInt(hex.slice(64, 128), 16);
+  const owners = [];
+  for (let i = 0; i < arrayLength; i++) {
+    const start = 128 + i * 64;
+    const ownerHex = hex.slice(start + 24, start + 64);
+    owners.push("0x" + ownerHex);
+  }
+  return owners;
+}
+async function isSafeOwner(rpcUrl, safeAddress, ownerAddress) {
+  const owners = await getSafeOwners(rpcUrl, safeAddress);
+  return owners.some((o) => o.toLowerCase() === ownerAddress.toLowerCase());
+}
+
+// src/passkey/types.ts
+var SAFE_WEBAUTHN_SINGLETON = "0x270d7e4a57e6322f336261f3eae2bade72e68d72";
+var SAFE_WEBAUTHN_SIGNER_PROXY_CREATION_CODE = "61010060405234801561001157600080fd5b506040516101ee3803806101ee83398101604081905261003091610058565b6001600160a01b0390931660805260a09190915260c0526001600160b01b031660e0526100bc565b6000806000806080858703121561006e57600080fd5b84516001600160a01b038116811461008557600080fd5b60208601516040870151606088015192965090945092506001600160b01b03811681146100b157600080fd5b939692955090935050565b60805160a05160c05160e05160ff6100ef60003960006008015260006031015260006059015260006080015260ff6000f3fe608060408190527f00000000000000000000000000000000000000000000000000000000000000003660b681018290527f000000000000000000000000000000000000000000000000000000000000000060a082018190527f00000000000000000000000000000000000000000000000000000000000000008285018190527f00000000000000000000000000000000000000000000000000000000000000009490939192600082376000806056360183885af490503d6000803e8060c3573d6000fd5b503d6000f3fea2646970667358221220ddd9bb059ba7a6497d560ca97aadf4dbf0476f578378554a50d41c6bb654beae64736f6c63430008180033";
+var SAFE_WEBAUTHN_SIGNER_FACTORY = {
+  ethereum: "0xF7488fFbe67327ac9f37D5F722d83Fc900852Fbf",
+  base: "0xF7488fFbe67327ac9f37D5F722d83Fc900852Fbf",
+  arbitrum: "0xF7488fFbe67327ac9f37D5F722d83Fc900852Fbf",
+  optimism: "0xF7488fFbe67327ac9f37D5F722d83Fc900852Fbf",
+  polygon: "0xF7488fFbe67327ac9f37D5F722d83Fc900852Fbf",
+  celo: "0xF7488fFbe67327ac9f37D5F722d83Fc900852Fbf"
+};
+var FCL_P256_VERIFIER = {
+  ethereum: "0xc2b78104907F722DABAc4C69f826a522B2754De4",
+  base: "0xc2b78104907F722DABAc4C69f826a522B2754De4",
+  arbitrum: "0xc2b78104907F722DABAc4C69f826a522B2754De4",
+  optimism: "0xc2b78104907F722DABAc4C69f826a522B2754De4",
+  polygon: "0xc2b78104907F722DABAc4C69f826a522B2754De4",
+  celo: "0xc2b78104907F722DABAc4C69f826a522B2754De4"
+};
+
+// src/passkey/linkPasskey.ts
+var P256_FIELD_PRIME = BigInt(
+  "0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff"
+);
+function validateAndPadAddress(addr) {
+  const hex = addr.startsWith("0x") ? addr.slice(2) : addr;
+  if (!/^[0-9a-fA-F]{40}$/.test(hex)) {
+    throw new Error(`Invalid EVM address for ABI encoding: ${addr}`);
+  }
+  return hex.toLowerCase().padStart(64, "0");
+}
+function validateUint256(value, name) {
+  if (value < 0n) {
+    throw new Error(`Invalid ${name}: ${value}. Must be non-negative.`);
+  }
+  const hex = value.toString(16);
+  if (hex.length > 64) {
+    throw new Error(`Invalid ${name}: exceeds uint256 max.`);
+  }
+  return hex.padStart(64, "0");
+}
+function encodeAddOwnerWithThreshold(owner, threshold) {
+  const selector = "0x0d582f13";
+  return `${selector}${validateAndPadAddress(owner)}${validateUint256(threshold, "threshold")}`;
+}
+function encodeRemoveOwner(prevOwner, owner, threshold) {
+  const selector = "0xf8dc5dd9";
+  return `${selector}${validateAndPadAddress(prevOwner)}${validateAndPadAddress(owner)}${validateUint256(threshold, "threshold")}`;
+}
+function encodeCreateSigner(x, y, verifier) {
+  const selector = "0xa8a65a78";
+  return `${selector}${validateUint256(x, "x")}${validateUint256(y, "y")}${validateAndPadAddress(verifier)}`;
+}
+function extractPublicKeyFromAttestation(credential) {
+  const response = credential.response;
+  const publicKey = response.getPublicKey();
+  if (!publicKey) {
+    throw new Error("Failed to extract public key from WebAuthn attestation");
+  }
+  const keyBytes = new Uint8Array(publicKey);
+  let offset = -1;
+  for (let i = 0; i <= keyBytes.length - 65; i++) {
+    if (keyBytes[i] === 4) {
+      offset = i + 1;
+      break;
+    }
+  }
+  if (offset === -1 || offset + 64 > keyBytes.length) {
+    throw new Error("Could not find P-256 public key in attestation data");
+  }
+  const xBytes = keyBytes.slice(offset, offset + 32);
+  const yBytes = keyBytes.slice(offset + 32, offset + 64);
+  const x = BigInt(
+    "0x" + Array.from(xBytes).map((b) => b.toString(16).padStart(2, "0")).join("")
+  );
+  const y = BigInt(
+    "0x" + Array.from(yBytes).map((b) => b.toString(16).padStart(2, "0")).join("")
+  );
+  if (x === 0n && y === 0n) {
+    throw new Error("Public key is point at infinity (invalid)");
+  }
+  if (x >= P256_FIELD_PRIME || y >= P256_FIELD_PRIME) {
+    throw new Error("Public key coordinates exceed P-256 field prime");
+  }
+  return { x, y };
+}
+function arrayBufferToBase64Url(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function deriveSignerAddress(factoryAddress, x, y, verifierAddress) {
+  const args = BigInt(SAFE_WEBAUTHN_SINGLETON).toString(16).padStart(64, "0") + x.toString(16).padStart(64, "0") + y.toString(16).padStart(64, "0") + BigInt(verifierAddress).toString(16).padStart(64, "0");
+  const initCode = SAFE_WEBAUTHN_SIGNER_PROXY_CREATION_CODE + args;
+  const codeHash = bytesToHex(keccak_256(hexToBytes(initCode)));
+  const salt = "0".repeat(64);
+  const create2Input = "ff" + factoryAddress.slice(2).toLowerCase() + salt + codeHash;
+  const create2Hash = bytesToHex(keccak_256(hexToBytes(create2Input)));
+  return "0x" + create2Hash.slice(24);
+}
+async function linkPasskeyToSafe(seedPhrase, config, passkeyOptions = {}, accountIndex = 0) {
+  const networkConfig = getErc4337ConfigForChain(config);
+  const {
+    wallet,
+    account,
+    address: safeAddress
+  } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+  try {
+    const deployed = await isContractDeployed(networkConfig.provider, safeAddress);
+    if (!deployed) {
+      throw new TransactionFailedError2(
+        config.chain,
+        `Safe account at ${safeAddress} is not yet deployed on-chain. Send a transaction first to deploy it.`
+      );
+    }
+    const {
+      rpId = typeof window !== "undefined" ? window.location.hostname : "localhost",
+      rpName = "Gasfree Kit",
+      userName = "Wallet User",
+      storage = "not_persist"
+    } = passkeyOptions;
+    const signerFactoryAddress = SAFE_WEBAUTHN_SIGNER_FACTORY[config.chain];
+    const p256VerifierAddress = FCL_P256_VERIFIER[config.chain];
+    if (!signerFactoryAddress || !p256VerifierAddress) {
+      throw new TransactionFailedError2(
+        config.chain,
+        `Passkey contracts not available on ${config.chain}`
+      );
+    }
+    const credentialPromise = navigator.credentials.create({
+      publicKey: {
+        rp: { id: rpId, name: rpName },
+        user: {
+          // Use an opaque random handle so the WebAuthn user record does not expose the Safe address.
+          id: crypto.getRandomValues(new Uint8Array(32)).buffer,
+          name: userName,
+          displayName: userName
+        },
+        challenge: Uint8Array.from(crypto.getRandomValues(new Uint8Array(32))).buffer,
+        pubKeyCredParams: [{ alg: -7, type: "public-key" }],
+        // ES256 (P-256)
+        authenticatorSelection: {
+          authenticatorAttachment: "platform",
+          residentKey: "required",
+          userVerification: "required"
+        },
+        timeout: 6e4
+      }
+    });
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(
+        () => reject(new TransactionFailedError2(config.chain, "Passkey registration timed out")),
+        65e3
+      );
+    });
+    const credential = await Promise.race([
+      credentialPromise,
+      timeoutPromise
+    ]);
+    if (!credential) {
+      throw new TransactionFailedError2(config.chain, "Passkey registration was cancelled");
+    }
+    const publicKey = extractPublicKeyFromAttestation(credential);
+    const credentialId = arrayBufferToBase64Url(credential.rawId);
+    const signerAddress = deriveSignerAddress(
+      signerFactoryAddress,
+      publicKey.x,
+      publicKey.y,
+      p256VerifierAddress
+    );
+    const alreadyOwner = await isSafeOwner(networkConfig.provider, safeAddress, signerAddress);
+    if (alreadyOwner) {
+      throw new TransactionFailedError2(
+        config.chain,
+        `Passkey signer ${signerAddress} is already a Safe owner. Cannot link the same passkey twice.`
+      );
+    }
+    const createSignerCalldata = encodeCreateSigner(publicKey.x, publicKey.y, p256VerifierAddress);
+    const deployResult = await account.sendTransaction([
+      {
+        to: signerFactoryAddress,
+        value: 0,
+        data: createSignerCalldata
+      }
+    ]);
+    await waitForUserOpConfirmation(
+      deployResult.hash,
+      networkConfig.bundlerUrl,
+      networkConfig.entryPointAddress
+    );
+    if (!await isContractDeployed(networkConfig.provider, signerAddress)) {
+      throw new TransactionFailedError2(
+        config.chain,
+        `Passkey signer deployment could not be verified at ${signerAddress}`
+      );
+    }
+    const addOwnerCalldata = encodeAddOwnerWithThreshold(signerAddress, 1n);
+    const addOwnerResult = await account.sendTransaction([
+      {
+        to: safeAddress,
+        value: 0,
+        data: addOwnerCalldata
+      }
+    ]);
+    const transactionHash = await waitForUserOpConfirmation(
+      addOwnerResult.hash,
+      networkConfig.bundlerUrl,
+      networkConfig.entryPointAddress
+    );
+    const passkeyCredential = {
+      id: credentialId,
+      publicKey,
+      signerAddress,
+      safeAddress
+    };
+    let persisted = false;
+    if (storage === "persist") {
+      const store = createCredentialStore();
+      await store.save(passkeyCredential);
+      persisted = true;
+    }
+    return {
+      credential: passkeyCredential,
+      safeAddress,
+      transactionHash,
+      persisted
+    };
+  } finally {
+    account.dispose();
+    wallet.dispose();
+  }
+}
+async function isPasskeyLinked(seedPhrase, config, accountIndex = 0) {
+  const store = createCredentialStore();
+  const {
+    wallet,
+    account,
+    address: safeAddress
+  } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+  try {
+    const stored = await store.load(safeAddress);
+    if (stored) {
+      const networkConfig = getErc4337ConfigForChain(config);
+      const onChainOwner = await isSafeOwner(
+        networkConfig.provider,
+        safeAddress,
+        stored.signerAddress
+      );
+      if (onChainOwner) {
+        return { linked: true, signerAddress: stored.signerAddress };
+      }
+      await store.remove(safeAddress);
+    }
+    return { linked: false };
+  } finally {
+    account.dispose();
+    wallet.dispose();
+  }
+}
+async function unlinkPasskeyFromSafe(seedPhrase, config, credential, accountIndex = 0) {
+  const networkConfig = getErc4337ConfigForChain(config);
+  const {
+    wallet,
+    account,
+    address: safeAddress
+  } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+  try {
+    if (credential.safeAddress.toLowerCase() !== safeAddress.toLowerCase()) {
+      throw new TransactionFailedError2(
+        config.chain,
+        `Credential belongs to Safe ${credential.safeAddress}, not ${safeAddress}`
+      );
+    }
+    const owners = await getSafeOwners(networkConfig.provider, safeAddress);
+    const signerLower = credential.signerAddress.toLowerCase();
+    const ownerIndex = owners.findIndex((o) => o.toLowerCase() === signerLower);
+    if (ownerIndex === -1) {
+      throw new TransactionFailedError2(
+        config.chain,
+        `Passkey signer ${credential.signerAddress} is not a Safe owner`
+      );
+    }
+    const SENTINEL = "0x0000000000000000000000000000000000000001";
+    const prevOwner = ownerIndex === 0 ? SENTINEL : owners[ownerIndex - 1];
+    const removeOwnerCalldata = encodeRemoveOwner(prevOwner, credential.signerAddress, 1n);
+    const result = await account.sendTransaction([
+      {
+        to: safeAddress,
+        value: 0,
+        data: removeOwnerCalldata
+      }
+    ]);
+    const transactionHash = await waitForUserOpConfirmation(
+      result.hash,
+      networkConfig.bundlerUrl,
+      networkConfig.entryPointAddress
+    );
+    const store = createCredentialStore();
+    await store.remove(safeAddress);
+    return { transactionHash };
+  } finally {
+    account.dispose();
+    wallet.dispose();
+  }
+}
 
 // src/evmERC4337.ts
-async function setupErc4337Wallet(seedPhrase, config, accountIndex = 0) {
+async function setupErc4337Wallet(seedPhrase, config, accountIndex = 0, passkeyOptions) {
   const networkConfig = getErc4337ConfigForChain(config);
   const WalletManagerEvmErc4337Module = await import("@tetherto/wdk-wallet-evm-erc-4337");
   const WalletManagerEvmErc4337 = WalletManagerEvmErc4337Module.default;
@@ -69,14 +706,17 @@ async function setupErc4337Wallet(seedPhrase, config, accountIndex = 0) {
   );
   const account = await wallet.getAccount(accountIndex);
   const address = await account.getAddress();
-  return { wallet, account, address };
+  let passkey;
+  if (passkeyOptions) {
+    passkey = await linkPasskeyToSafe(seedPhrase, config, passkeyOptions, accountIndex);
+  }
+  return { wallet, account, address, passkey };
 }
 
 // src/evmERC4337TetherTransfer.ts
-import { Bundler, SendUseroperationResponse } from "abstractionkit";
 import {
-  InsufficientBalanceError,
-  TransactionFailedError,
+  InsufficientBalanceError as InsufficientBalanceError2,
+  TransactionFailedError as TransactionFailedError3,
   validateEvmAddress
 } from "@gasfree-kit/core";
 
@@ -128,36 +768,7 @@ function feeToUsdt(feeInWei, nativeTokenPriceUsdt) {
 }
 
 // src/evmERC4337TetherTransfer.ts
-var TetherEVMERC4337Transfer = class {
-  /** Default timeout for UserOp confirmation: 120 seconds. */
-  static USER_OP_TIMEOUT_MS = 12e4;
-  /**
-   * Wait for a UserOperation to be included on-chain via the Candide bundler.
-   * Times out after USER_OP_TIMEOUT_MS to prevent indefinite hangs.
-   */
-  static async waitForUserOpConfirmation(userOpHash, bundlerUrl, entryPointAddress) {
-    const bundler = new Bundler(bundlerUrl);
-    const response = new SendUseroperationResponse(userOpHash, bundler, entryPointAddress);
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(
-        () => reject(
-          new TransactionFailedError(
-            "evm",
-            `UserOperation confirmation timed out after ${this.USER_OP_TIMEOUT_MS / 1e3}s. Hash: ${userOpHash}`
-          )
-        ),
-        this.USER_OP_TIMEOUT_MS
-      );
-    });
-    const receipt = await Promise.race([response.included(), timeoutPromise]);
-    if (!receipt.success) {
-      throw new TransactionFailedError(
-        "evm",
-        `UserOperation reverted. Tx: ${receipt.receipt.transactionHash}`
-      );
-    }
-    return receipt.receipt.transactionHash;
-  }
+var EvmTransfer = class {
   /**
    * Get transaction fee estimate for a USDT transfer.
    *
@@ -250,7 +861,7 @@ var TetherEVMERC4337Transfer = class {
     } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
     try {
       if (recipientAddress.toLowerCase() === senderAddress.toLowerCase()) {
-        throw new TransactionFailedError(config.chain, "Cannot transfer to your own address");
+        throw new TransactionFailedError3(config.chain, "Cannot transfer to your own address");
       }
       const amountInBaseUnits = toUsdtBaseUnitsEvm(amount);
       const balance = await account.getTokenBalance(tokenAddress);
@@ -269,20 +880,20 @@ var TetherEVMERC4337Transfer = class {
         }
         const totalRequired = amountInBaseUnits + gasFeeBaseUnits;
         if (BigInt(balance) < totalRequired) {
-          throw new InsufficientBalanceError(
+          throw new InsufficientBalanceError2(
             config.chain,
             `USDT (need ${formatTokenBalance(totalRequired, 6)} but have ${formatTokenBalance(balance, 6)} \u2014 includes ${formatTokenBalance(gasFeeBaseUnits, 6)} gas fee)`
           );
         }
       } else if (BigInt(balance) < amountInBaseUnits) {
-        throw new InsufficientBalanceError(config.chain, "USDT");
+        throw new InsufficientBalanceError2(config.chain, "USDT");
       }
       const transferResult = await account.transfer({
         token: tokenAddress,
         recipient: recipientAddress,
         amount: amountInBaseUnits
       });
-      const transactionHash = await this.waitForUserOpConfirmation(
+      const transactionHash = await waitForUserOpConfirmation(
         transferResult.hash,
         networkConfig.bundlerUrl,
         networkConfig.entryPointAddress
@@ -294,7 +905,7 @@ var TetherEVMERC4337Transfer = class {
         amount
       };
     } catch (error) {
-      throw this.handleTransferError(error, config.chain);
+      throw handleTransferError(error, config.chain);
     } finally {
       account.dispose();
       wallet.dispose();
@@ -317,7 +928,7 @@ var TetherEVMERC4337Transfer = class {
     try {
       for (const r of recipients) {
         if (r.address.toLowerCase() === senderAddress.toLowerCase()) {
-          throw new TransactionFailedError(config.chain, "Cannot transfer to your own address");
+          throw new TransactionFailedError3(config.chain, "Cannot transfer to your own address");
         }
       }
       const totalAmount = recipients.reduce((sum, r) => sum + toUsdtBaseUnitsEvm(r.amount), 0n);
@@ -326,13 +937,13 @@ var TetherEVMERC4337Transfer = class {
         const gasFeeReserve = GAS_FEE_FALLBACKS[config.chain] ?? 150000n;
         const totalRequired = totalAmount + gasFeeReserve;
         if (BigInt(balance) < totalRequired) {
-          throw new InsufficientBalanceError(
+          throw new InsufficientBalanceError2(
             config.chain,
             `USDT (need ${formatTokenBalance(totalRequired, 6)} but have ${formatTokenBalance(balance, 6)} \u2014 includes ${formatTokenBalance(gasFeeReserve, 6)} gas fee)`
           );
         }
       } else if (BigInt(balance) < totalAmount) {
-        throw new InsufficientBalanceError(config.chain, "USDT");
+        throw new InsufficientBalanceError2(config.chain, "USDT");
       }
       const batchTransactions = recipients.map(({ address, amount }) => {
         const amountBase = toUsdtBaseUnitsEvm(amount);
@@ -343,7 +954,7 @@ var TetherEVMERC4337Transfer = class {
         };
       });
       const transferResult = await account.sendTransaction(batchTransactions);
-      const transactionHash = await this.waitForUserOpConfirmation(
+      const transactionHash = await waitForUserOpConfirmation(
         transferResult.hash,
         networkConfig.bundlerUrl,
         networkConfig.entryPointAddress
@@ -355,64 +966,171 @@ var TetherEVMERC4337Transfer = class {
         recipients
       };
     } catch (error) {
-      throw this.handleTransferError(error, config.chain);
+      throw handleTransferError(error, config.chain);
     } finally {
       account.dispose();
       wallet.dispose();
     }
   }
+};
+
+// src/passkey/passkeyTransfer.ts
+import { TransactionFailedError as TransactionFailedError4, validateEvmAddress as validateEvmAddress2 } from "@gasfree-kit/core";
+var ERC20_BALANCE_OF_SELECTOR = "0x70a08231";
+async function loadSafe4337Pack() {
+  try {
+    const module = await import("@safe-global/relay-kit");
+    return module.Safe4337Pack;
+  } catch {
+    throw new Error(
+      "Passkey transfers require @safe-global/relay-kit. Install it: npm install @safe-global/relay-kit"
+    );
+  }
+}
+async function createPasskeyPack(credential, config) {
+  const Safe4337Pack = await loadSafe4337Pack();
+  const networkConfig = getErc4337ConfigForChain(config);
+  const passkeySigner = {
+    rawId: credential.id,
+    coordinates: {
+      x: credential.publicKey.x,
+      y: credential.publicKey.y
+    }
+  };
+  const paymasterOptions = networkConfig.isSponsored ? {
+    isSponsored: true,
+    paymasterUrl: networkConfig.paymasterUrl,
+    ...networkConfig.sponsorshipPolicyId ? { sponsorshipPolicyId: networkConfig.sponsorshipPolicyId } : {}
+  } : {
+    paymasterAddress: networkConfig.paymasterAddress,
+    paymasterUrl: networkConfig.paymasterUrl
+  };
+  const pack = await Safe4337Pack.init({
+    provider: networkConfig.provider,
+    signer: passkeySigner,
+    bundlerUrl: networkConfig.bundlerUrl,
+    safeAddress: credential.safeAddress,
+    paymasterOptions
+  });
+  return { pack, networkConfig };
+}
+var PasskeyTransfer = class {
   /**
-   * Map raw errors into user-friendly messages.
+   * Send a single token transfer signed by passkey.
+   * Triggers biometric authentication via WebAuthn.
    */
-  static handleTransferError(error, chain) {
-    if (!(error instanceof Error)) {
-      return new TransactionFailedError(chain, "Unknown error");
-    }
-    const msg = error.message;
-    if (msg.includes("callData reverts")) {
-      return new TransactionFailedError(
-        chain,
-        "Transaction reverted. Check your balance and try again."
-      );
+  static async sendToken(credential, config, tokenAddress, amount, recipientAddress) {
+    validateEvmAddress2(tokenAddress, config.chain, "token address");
+    validateEvmAddress2(recipientAddress, config.chain, "recipient address");
+    if (recipientAddress.toLowerCase() === credential.safeAddress.toLowerCase()) {
+      throw new TransactionFailedError4(config.chain, "Cannot transfer to your own address");
     }
-    if (msg.includes("not enough funds")) {
-      return new InsufficientBalanceError(chain, "paymaster token");
-    }
-    if (msg.includes("token balance lower than the required") || msg.includes("token allowance lower than the required")) {
-      return new InsufficientBalanceError(chain, "USDT (insufficient for transfer + gas)");
-    }
-    if (msg.includes("Insufficient") || error instanceof InsufficientBalanceError) {
-      return error;
-    }
-    if (msg.includes("nonce too low")) {
-      return new TransactionFailedError(chain, "Nonce conflict. Please try again.");
-    }
-    if (msg.includes("insufficient funds") || msg.includes("transfer amount exceeds balance")) {
-      return new InsufficientBalanceError(chain, "USDT");
-    }
-    if (msg.includes("transaction underpriced") || msg.includes("max fee per gas less than block base fee")) {
-      return new TransactionFailedError(chain, "Gas price too low. Please try again.");
-    }
-    if (msg.includes("out of gas") || msg.includes("intrinsic gas too low")) {
-      return new TransactionFailedError(chain, "Insufficient gas limit.");
+    try {
+      const { pack } = await createPasskeyPack(credential, config);
+      const amountInBaseUnits = toUsdtBaseUnitsEvm(amount);
+      const transferCalldata = encodeErc20Transfer(recipientAddress, amountInBaseUnits);
+      const safeOperation = await pack.createTransaction({
+        transactions: [
+          {
+            to: tokenAddress,
+            data: transferCalldata,
+            value: "0"
+          }
+        ]
+      });
+      const signedOperation = await pack.signSafeOperation(safeOperation);
+      const userOpHash = await pack.executeTransaction({
+        executable: signedOperation
+      });
+      const receipt = await pack.getUserOperationReceipt(userOpHash);
+      return {
+        success: true,
+        transactionHash: receipt.receipt.transactionHash,
+        chain: config.chain,
+        amount
+      };
+    } catch (error) {
+      throw handleTransferError(error, config.chain);
     }
-    if (msg.includes("execution reverted")) {
-      return new TransactionFailedError(chain, "Transaction reverted on-chain.");
+  }
+  /**
+   * Send a batch token transfer to multiple recipients, signed by passkey.
+   */
+  static async sendBatchToken(credential, config, tokenAddress, recipients) {
+    for (const r of recipients) {
+      validateEvmAddress2(r.address, config.chain, "recipient address");
+      if (r.address.toLowerCase() === credential.safeAddress.toLowerCase()) {
+        throw new TransactionFailedError4(config.chain, "Cannot transfer to your own address");
+      }
     }
-    if (msg.includes("504") || msg.includes("Gateway Time-out")) {
-      return new TransactionFailedError(chain, "Network timeout. Please try again.");
+    try {
+      const { pack } = await createPasskeyPack(credential, config);
+      const transactions = recipients.map(({ address, amount }) => {
+        const amountBase = toUsdtBaseUnitsEvm(amount);
+        return {
+          to: tokenAddress,
+          data: encodeErc20Transfer(address, amountBase),
+          value: "0"
+        };
+      });
+      const safeOperation = await pack.createTransaction({ transactions });
+      const signedOperation = await pack.signSafeOperation(safeOperation);
+      const userOpHash = await pack.executeTransaction({ executable: signedOperation });
+      const receipt = await pack.getUserOperationReceipt(userOpHash);
+      return {
+        success: true,
+        transactionHash: receipt.receipt.transactionHash,
+        chain: config.chain,
+        recipients
+      };
+    } catch (error) {
+      throw handleTransferError(error, config.chain);
     }
-    return new TransactionFailedError(chain, msg);
+  }
+  /**
+   * Check token balance for a passkey-linked Safe account.
+   * Does NOT require biometric — balance is publicly readable via RPC.
+   */
+  static async checkTokenBalance(credential, config, tokenAddress) {
+    validateEvmAddress2(tokenAddress, config.chain, "token address");
+    validateEvmAddress2(credential.safeAddress, config.chain, "safe address");
+    const networkConfig = getErc4337ConfigForChain(config);
+    const addr = (credential.safeAddress.startsWith("0x") ? credential.safeAddress.slice(2) : credential.safeAddress).toLowerCase().padStart(64, "0");
+    const balanceCalldata = `${ERC20_BALANCE_OF_SELECTOR}${addr}`;
+    const result = await jsonRpcCall(networkConfig.provider, {
+      method: "eth_call",
+      params: [{ to: tokenAddress, data: balanceCalldata }, "latest"]
+    });
+    const balance = BigInt(result);
+    const usdBalance = formatTokenBalance(balance, 6);
+    return {
+      message: `${config.chain.toUpperCase()} balances retrieved successfully`,
+      success: true,
+      data: {
+        tokenBalance: balance.toString(),
+        decimals: 6,
+        usdBalance: String(usdBalance)
+      }
+    };
   }
 };
 export {
+  EvmTransfer,
+  FCL_P256_VERIFIER,
   GAS_FEE_ESTIMATES,
   GAS_FEE_FALLBACKS,
-  TetherEVMERC4337Transfer,
+  PasskeyTransfer,
+  SAFE_WEBAUTHN_SIGNER_FACTORY,
+  createCredentialStore,
   encodeErc20Transfer,
   feeToUsdt,
   formatTokenBalance,
   getErc4337ConfigForChain,
+  handleTransferError,
+  isPasskeyLinked,
+  linkPasskeyToSafe,
   setupErc4337Wallet,
-  toUsdtBaseUnitsEvm
+  toUsdtBaseUnitsEvm,
+  unlinkPasskeyFromSafe,
+  waitForUserOpConfirmation
 };