@veridex/sdk 1.0.0-beta.1

package/dist/chains/evm/index.js

@@ -0,0 +1,1233 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/chains/evm/index.ts
+var evm_exports = {};
+__export(evm_exports, {
+  EVMClient: () => EVMClient,
+  EVMHubClientAdapter: () => EVMHubClientAdapter
+});
+module.exports = __toCommonJS(evm_exports);
+
+// src/chains/evm/EVMClient.ts
+var import_ethers2 = require("ethers");
+
+// src/payload.ts
+var import_ethers = require("ethers");
+
+// src/constants.ts
+var ACTION_TRANSFER = 1;
+var ACTION_EXECUTE = 2;
+var ACTION_BRIDGE = 4;
+
+// src/payload.ts
+function encodeTransferAction(token, recipient, amount) {
+  const tokenPadded = padTo32Bytes(token);
+  const recipientPadded = padTo32Bytes(recipient);
+  const amountBytes = import_ethers.ethers.zeroPadValue(import_ethers.ethers.toBeHex(amount), 32);
+  return import_ethers.ethers.concat([
+    import_ethers.ethers.toBeHex(ACTION_TRANSFER, 1),
+    tokenPadded,
+    recipientPadded,
+    amountBytes
+  ]);
+}
+function encodeBridgeAction(token, amount, targetChain, recipient) {
+  const tokenPadded = padTo32Bytes(token);
+  const amountBytes = import_ethers.ethers.zeroPadValue(import_ethers.ethers.toBeHex(amount), 32);
+  const targetChainBytes = import_ethers.ethers.toBeHex(targetChain, 2);
+  const recipientPadded = padTo32Bytes(recipient);
+  return import_ethers.ethers.concat([
+    import_ethers.ethers.toBeHex(ACTION_BRIDGE, 1),
+    tokenPadded,
+    amountBytes,
+    targetChainBytes,
+    recipientPadded
+  ]);
+}
+function encodeExecuteAction(target, value, data) {
+  const targetPadded = padTo32Bytes(target);
+  const valueBytes = import_ethers.ethers.zeroPadValue(import_ethers.ethers.toBeHex(value), 32);
+  const dataBytes = import_ethers.ethers.getBytes(data);
+  const dataLengthBytes = import_ethers.ethers.toBeHex(dataBytes.length, 2);
+  return import_ethers.ethers.concat([
+    import_ethers.ethers.toBeHex(ACTION_EXECUTE, 1),
+    targetPadded,
+    valueBytes,
+    dataLengthBytes,
+    data
+  ]);
+}
+function padTo32Bytes(address) {
+  if (address.toLowerCase() === "native") {
+    return "0x" + "0".repeat(64);
+  }
+  if (address.startsWith("0x")) {
+    const hex2 = address.replace("0x", "");
+    if (!/^[0-9a-fA-F]*$/.test(hex2)) {
+      throw new Error(`Invalid address: ${address}. Expected hex string or 'native'.`);
+    }
+    return "0x" + hex2.padStart(64, "0");
+  }
+  const base58Chars = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+  for (const char of address) {
+    if (!base58Chars.includes(char)) {
+      throw new Error(`Invalid address: ${address}. Contains invalid base58 character '${char}'.`);
+    }
+  }
+  let value = BigInt(0);
+  for (const char of address) {
+    value = value * 58n + BigInt(base58Chars.indexOf(char));
+  }
+  let hex = value.toString(16);
+  if (hex.length > 64) {
+    throw new Error(`Invalid address: ${address}. Decoded value too large for 32 bytes.`);
+  }
+  return "0x" + hex.padStart(64, "0");
+}
+
+// src/chains/evm/EVMClient.ts
+var PROXY_BYTECODE_PREFIX = "0x3d602d80600a3d3981f3363d3d373d3d3d363d73";
+var PROXY_BYTECODE_SUFFIX = "5af43d82803e903d91602b57fd5bf3";
+var ERC20_ABI = [
+  "function balanceOf(address owner) view returns (uint256)",
+  "function decimals() view returns (uint8)",
+  "function symbol() view returns (string)",
+  "function name() view returns (string)",
+  "function allowance(address owner, address spender) view returns (uint256)",
+  "function transfer(address to, uint256 amount) returns (bool)",
+  "function approve(address spender, uint256 amount) returns (bool)"
+];
+var HUB_ABI = [
+  "function dispatch(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) signature, uint256 publicKeyX, uint256 publicKeyY, uint16 targetChain, bytes actionPayload, uint256 nonce) payable returns (uint64 sequence)",
+  "function getNonce(bytes32 userKeyHash) view returns (uint256)",
+  "function getMessageFee() view returns (uint256)",
+  "function getVaultAddress(bytes32 userKeyHash) view returns (address)",
+  "function vaultExists(bytes32 userKeyHash) view returns (bool)",
+  "function createVault(bytes32 userKeyHash) returns (address)",
+  // Issue #9/#10: New Hub methods for Query-based execution
+  "function getUserState(bytes32 userKeyHash) view returns (bytes32 keyHash, uint256 nonce, bytes32 lastActionHash)",
+  "function getUserLastActionHash(bytes32 userKeyHash) view returns (bytes32)",
+  // Issue #13: Session key management
+  "function registerSession(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32 sessionKeyHash, uint256 duration, uint256 maxValue, bool requireUV) external",
+  "function isSessionActive(bytes32 userKeyHash, bytes32 sessionKeyHash) view returns (bool active, uint256 expiry, uint256 maxValue, uint256 sessionIndex)",
+  "function revokeSession(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32 sessionKeyHash, bool requireUV) external",
+  "function getUserSessions(bytes32 userKeyHash) view returns (tuple(bytes32 sessionKeyHash, uint256 expiry, uint256 maxValue, bool revoked)[])",
+  "function getUserSessionCount(bytes32 userKeyHash) view returns (uint256)",
+  // Issue #22: Backup Passkey / Multi-Key Identity management
+  "function registerIdentity(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY) external",
+  "function addBackupKey(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, uint256 newPublicKeyX, uint256 newPublicKeyY, uint256 nonce) external payable returns (uint64 sequence)",
+  "function removeKey(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32 keyToRemove, uint256 nonce) external payable returns (uint64 sequence)",
+  "function getIdentityForKey(bytes32 keyHash) view returns (bytes32)",
+  "function getAuthorizedKeys(bytes32 identity) view returns (bytes32[])",
+  "function getAuthorizedKeyCount(bytes32 identity) view returns (uint256)",
+  "function isAuthorizedForIdentity(bytes32 identity, bytes32 keyHash) view returns (bool)",
+  "function isIdentityRoot(bytes32 keyHash) view returns (bool)",
+  "function getIdentityState(bytes32 keyHash) view returns (bytes32 identity, uint256 keyCount, uint256 maxKeys, bool isRoot)",
+  // Issue #23: Social Recovery / Guardian Management
+  "function setupGuardians(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32[] guardians, uint256 threshold) external payable returns (uint64 sequence)",
+  "function addGuardian(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32 guardianKeyHash) external payable returns (uint64 sequence)",
+  "function removeGuardian(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32 guardianKeyHash) external payable returns (uint64 sequence)",
+  "function initiateRecovery(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32 identityToRecover, bytes32 newOwnerKeyHash) external payable returns (uint64 sequence)",
+  "function approveRecovery(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY, bytes32 identityToRecover) external payable returns (uint64 sequence)",
+  "function executeRecovery(bytes32 identityToRecover, uint256 newPublicKeyX, uint256 newPublicKeyY) external payable returns (uint64 sequence)",
+  "function cancelRecovery(tuple(bytes authenticatorData, string clientDataJSON, uint256 challengeIndex, uint256 typeIndex, uint256 r, uint256 s) auth, uint256 publicKeyX, uint256 publicKeyY) external payable returns (uint64 sequence)",
+  "function getGuardians(bytes32 identityKeyHash) view returns (bytes32[] guardians, uint256 threshold, bool isConfigured)",
+  "function getRecoveryStatus(bytes32 identityKeyHash) view returns (bool isActive, bytes32 newOwnerKeyHash, uint256 initiatedAt, uint256 approvalCount, uint256 threshold, uint256 canExecuteAt, uint256 expiresAt)",
+  "function hasGuardianApproved(bytes32 identityKeyHash, bytes32 guardianKeyHash) view returns (bool hasApproved)"
+];
+var FACTORY_ABI = [
+  "function createVault(bytes32 ownerKeyHash) returns (address vault)",
+  "function getVault(bytes32 ownerKeyHash) view returns (address)",
+  "function computeVaultAddress(bytes32 ownerKeyHash) view returns (address vault)",
+  "function vaultExists(bytes32 ownerKeyHash) view returns (bool)",
+  "function implementation() view returns (address)"
+];
+var EVMClient = class {
+  config;
+  provider;
+  hubContract;
+  factoryContract = null;
+  cachedImplementation = null;
+  constructor(config) {
+    this.config = {
+      name: config.name ?? `EVM Chain ${config.chainId}`,
+      chainId: config.chainId,
+      wormholeChainId: config.wormholeChainId,
+      rpcUrl: config.rpcUrl,
+      explorerUrl: config.explorerUrl ?? "",
+      isEvm: true,
+      contracts: {
+        hub: config.hubContractAddress,
+        vaultFactory: config.vaultFactory,
+        vaultImplementation: config.vaultImplementation,
+        wormholeCoreBridge: config.wormholeCoreBridge,
+        tokenBridge: config.tokenBridge
+      }
+    };
+    this.provider = new import_ethers2.ethers.JsonRpcProvider(config.rpcUrl);
+    this.hubContract = new import_ethers2.ethers.Contract(
+      config.hubContractAddress,
+      HUB_ABI,
+      this.provider
+    );
+    if (config.vaultFactory) {
+      this.factoryContract = new import_ethers2.ethers.Contract(
+        config.vaultFactory,
+        FACTORY_ABI,
+        this.provider
+      );
+    }
+    if (config.vaultImplementation) {
+      this.cachedImplementation = config.vaultImplementation;
+    }
+  }
+  getConfig() {
+    return this.config;
+  }
+  async getNonce(userKeyHash) {
+    const nonce = await this.hubContract.getNonce(userKeyHash);
+    return BigInt(nonce.toString());
+  }
+  /**
+   * Get user state from Hub (Issue #9/#10)
+   * Returns comprehensive state including last action hash
+   */
+  async getUserState(userKeyHash) {
+    try {
+      const result = await this.hubContract.getUserState(userKeyHash);
+      return {
+        keyHash: result[0],
+        nonce: BigInt(result[1].toString()),
+        lastActionHash: result[2]
+      };
+    } catch (error) {
+      const nonce = await this.getNonce(userKeyHash);
+      return {
+        keyHash: userKeyHash,
+        nonce,
+        lastActionHash: import_ethers2.ethers.ZeroHash
+      };
+    }
+  }
+  /**
+   * Get user's last action hash from Hub (Issue #9/#10)
+   * Returns zero hash if user has no actions yet
+   */
+  async getUserLastActionHash(userKeyHash) {
+    try {
+      return await this.hubContract.getUserLastActionHash(userKeyHash);
+    } catch (error) {
+      return import_ethers2.ethers.ZeroHash;
+    }
+  }
+  // ==========================================================================
+  // Session Management Methods (Issue #13)
+  // ==========================================================================
+  /**
+   * Register a new session key for temporary authentication
+   * Enables native L1 speed for repeat transactions without biometric auth
+   * 
+   * @param params Session registration parameters
+   * @param signer Ethereum signer to pay gas
+   * @returns Transaction receipt
+   */
+  async registerSession(params, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: params.signature.authenticatorData,
+      clientDataJSON: params.signature.clientDataJSON,
+      challengeIndex: params.signature.challengeIndex,
+      typeIndex: params.signature.typeIndex,
+      r: params.signature.r,
+      s: params.signature.s
+    };
+    const tx = await hubWithSigner.registerSession(
+      authTuple,
+      params.publicKeyX,
+      params.publicKeyY,
+      params.sessionKeyHash,
+      params.duration,
+      params.maxValue,
+      params.requireUV
+    );
+    return await tx.wait();
+  }
+  /**
+   * Check if a session is currently active (queryable via Wormhole CCQ)
+   * 
+   * @param userKeyHash Hash of the user's Passkey public key
+   * @param sessionKeyHash Hash of the session key to check
+   * @returns Session validation result
+   */
+  async isSessionActive(userKeyHash, sessionKeyHash) {
+    const result = await this.hubContract.isSessionActive(userKeyHash, sessionKeyHash);
+    return {
+      active: result[0],
+      expiry: Number(result[1]),
+      maxValue: BigInt(result[2].toString()),
+      sessionIndex: Number(result[3])
+    };
+  }
+  /**
+   * Revoke a session key immediately
+   * 
+   * @param params Session revocation parameters
+   * @param signer Ethereum signer to pay gas
+   * @returns Transaction receipt
+   */
+  async revokeSession(params, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: params.signature.authenticatorData,
+      clientDataJSON: params.signature.clientDataJSON,
+      challengeIndex: params.signature.challengeIndex,
+      typeIndex: params.signature.typeIndex,
+      r: params.signature.r,
+      s: params.signature.s
+    };
+    const tx = await hubWithSigner.revokeSession(
+      authTuple,
+      params.publicKeyX,
+      params.publicKeyY,
+      params.sessionKeyHash,
+      params.requireUV
+    );
+    return await tx.wait();
+  }
+  /**
+   * Get all sessions for a user
+   * 
+   * @param userKeyHash Hash of the user's Passkey public key
+   * @returns Array of all sessions (active and expired/revoked)
+   */
+  async getUserSessions(userKeyHash) {
+    const sessions = await this.hubContract.getUserSessions(userKeyHash);
+    return sessions.map((s) => ({
+      sessionKeyHash: s.sessionKeyHash,
+      expiry: Number(s.expiry),
+      maxValue: BigInt(s.maxValue.toString()),
+      revoked: s.revoked
+    }));
+  }
+  /**
+   * Get the number of sessions for a user
+   * 
+   * @param userKeyHash Hash of the user's Passkey public key
+   * @returns Number of sessions
+   */
+  async getUserSessionCount(userKeyHash) {
+    const count = await this.hubContract.getUserSessionCount(userKeyHash);
+    return Number(count);
+  }
+  async getMessageFee() {
+    const fee = await this.hubContract.getMessageFee();
+    return BigInt(fee.toString());
+  }
+  async buildTransferPayload(params) {
+    return encodeTransferAction(
+      params.token,
+      params.recipient,
+      params.amount
+    );
+  }
+  async buildExecutePayload(params) {
+    return encodeExecuteAction(
+      params.target,
+      params.value,
+      params.data
+    );
+  }
+  async buildBridgePayload(params) {
+    return encodeBridgeAction(
+      params.token,
+      params.amount,
+      params.destinationChain,
+      params.recipient
+    );
+  }
+  async dispatch(signature, publicKeyX, publicKeyY, targetChain, actionPayload, nonce, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const signatureTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.dispatch(
+      signatureTuple,
+      publicKeyX,
+      publicKeyY,
+      targetChain,
+      actionPayload,
+      nonce,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const dispatchEvent = receipt.logs.find((log) => {
+      try {
+        const parsed = hubWithSigner.interface.parseLog(log);
+        return parsed?.name === "ActionDispatched";
+      } catch {
+        return false;
+      }
+    });
+    let sequence = 0n;
+    if (dispatchEvent) {
+      const parsed = hubWithSigner.interface.parseLog(dispatchEvent);
+      sequence = BigInt(parsed?.args?.sequence?.toString() ?? "0");
+    }
+    const keyHash = import_ethers2.ethers.keccak256(
+      import_ethers2.ethers.AbiCoder.defaultAbiCoder().encode(
+        ["uint256", "uint256"],
+        [publicKeyX, publicKeyY]
+      )
+    );
+    return {
+      transactionHash: receipt.hash,
+      sequence,
+      userKeyHash: keyHash,
+      targetChain,
+      blockNumber: receipt.blockNumber
+    };
+  }
+  /**
+   * Dispatch an action to the Hub via relayer (gasless)
+   * The relayer pays for gas and submits the transaction on behalf of the user
+   */
+  async dispatchGasless(signature, publicKeyX, publicKeyY, targetChain, actionPayload, nonce, relayerUrl) {
+    const keyHash = import_ethers2.ethers.keccak256(
+      import_ethers2.ethers.AbiCoder.defaultAbiCoder().encode(
+        ["uint256", "uint256"],
+        [publicKeyX, publicKeyY]
+      )
+    );
+    const message = import_ethers2.ethers.keccak256(
+      import_ethers2.ethers.AbiCoder.defaultAbiCoder().encode(
+        ["bytes32", "uint16", "bytes", "uint256"],
+        [keyHash, targetChain, actionPayload, nonce]
+      )
+    );
+    const request = {
+      messageHash: message,
+      r: "0x" + signature.r.toString(16).padStart(64, "0"),
+      s: "0x" + signature.s.toString(16).padStart(64, "0"),
+      publicKeyX: "0x" + publicKeyX.toString(16).padStart(64, "0"),
+      publicKeyY: "0x" + publicKeyY.toString(16).padStart(64, "0"),
+      targetChain,
+      actionPayload,
+      nonce: Number(nonce)
+    };
+    const response = await fetch(`${relayerUrl}/api/v1/submit`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(request)
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: response.statusText }));
+      throw new Error(`Relayer submission failed: ${error.error || response.statusText}`);
+    }
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(`Relayer submission failed: ${result.error}`);
+    }
+    return {
+      transactionHash: result.txHash,
+      sequence: BigInt(result.sequence || "0"),
+      userKeyHash: keyHash,
+      targetChain
+    };
+  }
+  async getVaultAddress(userKeyHash) {
+    try {
+      if (this.factoryContract) {
+        const address2 = await this.factoryContract.getVault(userKeyHash);
+        if (address2 !== import_ethers2.ethers.ZeroAddress) {
+          return address2;
+        }
+      }
+      const address = await this.hubContract.getVaultAddress(userKeyHash);
+      if (address === import_ethers2.ethers.ZeroAddress) {
+        return null;
+      }
+      return address;
+    } catch (error) {
+      console.error("Error getting vault address:", error);
+      return null;
+    }
+  }
+  /**
+   * Compute vault address deterministically without querying the chain
+   * Uses CREATE2 with EIP-1167 minimal proxy pattern
+   */
+  computeVaultAddress(userKeyHash) {
+    const factoryAddress = this.getFactoryAddress();
+    const implementationAddress = this.getImplementationAddress();
+    if (!factoryAddress || !implementationAddress) {
+      throw new Error("Factory and implementation addresses required for address computation");
+    }
+    const salt = import_ethers2.ethers.keccak256(
+      import_ethers2.ethers.solidityPacked(
+        ["address", "bytes32"],
+        [factoryAddress, userKeyHash]
+      )
+    );
+    const initCode = this.buildProxyInitCode(implementationAddress);
+    const initCodeHash = import_ethers2.ethers.keccak256(initCode);
+    const create2Data = import_ethers2.ethers.solidityPacked(
+      ["bytes1", "address", "bytes32", "bytes32"],
+      ["0xff", factoryAddress, salt, initCodeHash]
+    );
+    const hash = import_ethers2.ethers.keccak256(create2Data);
+    return import_ethers2.ethers.getAddress("0x" + hash.slice(26));
+  }
+  /**
+   * Build EIP-1167 minimal proxy initcode
+   */
+  buildProxyInitCode(implementationAddress) {
+    const impl = implementationAddress.toLowerCase().replace("0x", "");
+    return PROXY_BYTECODE_PREFIX + impl + PROXY_BYTECODE_SUFFIX;
+  }
+  async vaultExists(userKeyHash) {
+    try {
+      if (this.factoryContract) {
+        return await this.factoryContract.vaultExists(userKeyHash);
+      }
+      if (this.hubContract.vaultExists) {
+        try {
+          return await this.hubContract.vaultExists(userKeyHash);
+        } catch {
+          return false;
+        }
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+  async createVault(userKeyHash, signer) {
+    const exists = await this.vaultExists(userKeyHash);
+    if (exists) {
+      const address = await this.getVaultAddress(userKeyHash);
+      if (address) {
+        return {
+          address,
+          transactionHash: "",
+          blockNumber: 0,
+          gasUsed: 0n,
+          alreadyExisted: true
+        };
+      }
+    }
+    let tx;
+    if (this.factoryContract) {
+      const factoryWithSigner = this.factoryContract.connect(signer);
+      tx = await factoryWithSigner.createVault(userKeyHash);
+    } else {
+      const hubWithSigner = this.hubContract.connect(signer);
+      tx = await hubWithSigner.createVault(userKeyHash);
+    }
+    const receipt = await tx.wait();
+    if (!receipt) {
+      throw new Error("Transaction failed - no receipt");
+    }
+    const vaultAddress = await this.getVaultAddress(userKeyHash);
+    if (!vaultAddress) {
+      throw new Error("Failed to create vault - address not found after creation");
+    }
+    return {
+      address: vaultAddress,
+      transactionHash: receipt.hash,
+      blockNumber: receipt.blockNumber,
+      gasUsed: receipt.gasUsed,
+      alreadyExisted: false
+    };
+  }
+  /**
+   * Create a vault with a sponsor wallet paying for gas
+   * 
+   * @param userKeyHash - The user's passkey hash
+   * @param sponsorPrivateKey - Private key of the wallet that will pay gas
+   * @param rpcUrl - Optional RPC URL to use (defaults to client's RPC)
+   * @returns VaultCreationResult with address and transaction details
+   */
+  async createVaultSponsored(userKeyHash, sponsorPrivateKey, rpcUrl) {
+    const exists = await this.vaultExists(userKeyHash);
+    if (exists) {
+      const address = await this.getVaultAddress(userKeyHash);
+      if (address) {
+        return {
+          address,
+          transactionHash: "",
+          blockNumber: 0,
+          gasUsed: 0n,
+          alreadyExisted: true
+        };
+      }
+    }
+    const provider = rpcUrl ? new import_ethers2.ethers.JsonRpcProvider(rpcUrl) : this.provider;
+    const sponsorWallet = new import_ethers2.ethers.Wallet(sponsorPrivateKey, provider);
+    const sponsorBalance = await provider.getBalance(sponsorWallet.address);
+    const estimatedGas = await this.estimateVaultCreationGas(userKeyHash);
+    const feeData = await provider.getFeeData();
+    const estimatedCost = estimatedGas * (feeData.gasPrice ?? 1000000000n);
+    if (sponsorBalance < estimatedCost) {
+      throw new Error(
+        `Sponsor wallet has insufficient funds. Balance: ${import_ethers2.ethers.formatEther(sponsorBalance)} ETH, Estimated cost: ${import_ethers2.ethers.formatEther(estimatedCost)} ETH`
+      );
+    }
+    let tx;
+    if (this.factoryContract) {
+      const factoryWithSponsor = this.factoryContract.connect(sponsorWallet);
+      tx = await factoryWithSponsor.createVault(userKeyHash);
+    } else {
+      const hubWithSponsor = this.hubContract.connect(sponsorWallet);
+      tx = await hubWithSponsor.createVault(userKeyHash);
+    }
+    const receipt = await tx.wait();
+    if (!receipt) {
+      throw new Error("Transaction failed - no receipt");
+    }
+    const vaultAddress = await this.getVaultAddress(userKeyHash);
+    if (!vaultAddress) {
+      throw new Error("Failed to create vault - address not found after creation");
+    }
+    return {
+      address: vaultAddress,
+      transactionHash: receipt.hash,
+      blockNumber: receipt.blockNumber,
+      gasUsed: receipt.gasUsed,
+      alreadyExisted: false,
+      sponsoredBy: sponsorWallet.address
+    };
+  }
+  async estimateVaultCreationGas(userKeyHash) {
+    try {
+      if (this.factoryContract) {
+        return await this.factoryContract.createVault.estimateGas(userKeyHash);
+      }
+      return await this.hubContract.createVault.estimateGas(userKeyHash);
+    } catch (error) {
+      console.warn("Gas estimation failed, returning default:", error);
+      return 150000n;
+    }
+  }
+  getFactoryAddress() {
+    return this.config.contracts.vaultFactory;
+  }
+  getImplementationAddress() {
+    return this.config.contracts.vaultImplementation ?? this.cachedImplementation ?? void 0;
+  }
+  /**
+   * Fetch implementation address from factory contract
+   */
+  async fetchImplementationAddress() {
+    if (this.cachedImplementation) {
+      return this.cachedImplementation;
+    }
+    if (!this.factoryContract) {
+      return null;
+    }
+    try {
+      this.cachedImplementation = await this.factoryContract.implementation();
+      return this.cachedImplementation;
+    } catch (error) {
+      console.error("Error fetching implementation address:", error);
+      return null;
+    }
+  }
+  /**
+   * Get the provider instance
+   */
+  getProvider() {
+    return this.provider;
+  }
+  // ========================================================================
+  // Balance Methods (Phase 2)
+  // ========================================================================
+  /**
+   * Get native token balance for an address
+   */
+  async getNativeBalance(address) {
+    return await this.provider.getBalance(address);
+  }
+  /**
+   * Get ERC20 token balance for an address
+   */
+  async getTokenBalance(tokenAddress, ownerAddress) {
+    const contract = new import_ethers2.ethers.Contract(tokenAddress, ERC20_ABI, this.provider);
+    return await contract.balanceOf(ownerAddress);
+  }
+  /**
+   * Get token allowance
+   */
+  async getTokenAllowance(tokenAddress, ownerAddress, spenderAddress) {
+    const contract = new import_ethers2.ethers.Contract(tokenAddress, ERC20_ABI, this.provider);
+    return await contract.allowance(ownerAddress, spenderAddress);
+  }
+  /**
+   * Estimate gas for a dispatch transaction
+   */
+  async estimateDispatchGas(signature, publicKeyX, publicKeyY, targetChain, actionPayload, nonce) {
+    const signatureTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    try {
+      const gasEstimate = await this.hubContract.dispatch.estimateGas(
+        signatureTuple,
+        publicKeyX,
+        publicKeyY,
+        targetChain,
+        actionPayload,
+        nonce,
+        { value: messageFee }
+      );
+      return gasEstimate;
+    } catch (error) {
+      console.warn("Gas estimation failed, using default:", error);
+      return 500000n;
+    }
+  }
+  /**
+   * Get current gas price
+   */
+  async getGasPrice() {
+    const feeData = await this.provider.getFeeData();
+    return feeData.gasPrice ?? feeData.maxFeePerGas ?? 0n;
+  }
+  /**
+   * Get current block number
+   */
+  async getBlockNumber() {
+    return await this.provider.getBlockNumber();
+  }
+  /**
+   * Get transaction receipt
+   */
+  async getTransactionReceipt(hash) {
+    return await this.provider.getTransactionReceipt(hash);
+  }
+  /**
+   * Wait for transaction confirmation
+   */
+  async waitForTransaction(hash, confirmations = 1) {
+    return await this.provider.waitForTransaction(hash, confirmations);
+  }
+  // ==========================================================================
+  // Backup Passkey / Multi-Key Identity Methods (Issue #22)
+  // ==========================================================================
+  /**
+   * Get the identity for a given key hash
+   * Returns zero hash if key is not registered to any identity
+   * 
+   * @param keyHash Hash of the passkey to look up
+   * @returns Identity (first passkey's keyHash) or zero hash
+   */
+  async getIdentityForKey(keyHash) {
+    try {
+      return await this.hubContract.getIdentityForKey(keyHash);
+    } catch (error) {
+      return import_ethers2.ethers.ZeroHash;
+    }
+  }
+  /**
+   * Get all authorized keys for an identity
+   * 
+   * @param identity The identity key hash (first passkey's keyHash)
+   * @returns Array of authorized key hashes
+   */
+  async getAuthorizedKeys(identity) {
+    try {
+      return await this.hubContract.getAuthorizedKeys(identity);
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get count of authorized keys for an identity
+   * 
+   * @param identity The identity key hash
+   * @returns Number of authorized keys
+   */
+  async getAuthorizedKeyCount(identity) {
+    try {
+      const count = await this.hubContract.getAuthorizedKeyCount(identity);
+      return Number(count);
+    } catch (error) {
+      return 0;
+    }
+  }
+  /**
+   * Check if a key is authorized for an identity
+   * 
+   * @param identity The identity key hash
+   * @param keyHash The key hash to check
+   * @returns Whether the key is authorized
+   */
+  async isAuthorizedForIdentity(identity, keyHash) {
+    try {
+      return await this.hubContract.isAuthorizedForIdentity(identity, keyHash);
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Check if a key is the root identity key
+   * 
+   * @param keyHash The key hash to check
+   * @returns Whether the key is a root identity
+   */
+  async isIdentityRootKey(keyHash) {
+    try {
+      return await this.hubContract.isIdentityRoot(keyHash);
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Get comprehensive identity state for a key
+   * 
+   * @param keyHash Hash of any key in the identity
+   * @returns Identity state including count, max, and root status
+   */
+  async getIdentityState(keyHash) {
+    try {
+      const result = await this.hubContract.getIdentityState(keyHash);
+      return {
+        identity: result[0],
+        keyCount: Number(result[1]),
+        maxKeys: Number(result[2]),
+        isRoot: result[3]
+      };
+    } catch (error) {
+      return {
+        identity: import_ethers2.ethers.ZeroHash,
+        keyCount: 0,
+        maxKeys: 5,
+        isRoot: false
+      };
+    }
+  }
+  /**
+   * Register a new identity with the first passkey
+   * This makes the passkey the root identity key
+   * 
+   * @param signature WebAuthn signature
+   * @param publicKeyX Passkey public key X coordinate
+   * @param publicKeyY Passkey public key Y coordinate
+   * @param signer Ethereum signer to pay gas
+   * @returns Transaction receipt and identity hash
+   */
+  async registerIdentity(signature, publicKeyX, publicKeyY, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const tx = await hubWithSigner.registerIdentity(
+      authTuple,
+      publicKeyX,
+      publicKeyY
+    );
+    const receipt = await tx.wait();
+    const keyHash = import_ethers2.ethers.keccak256(
+      import_ethers2.ethers.solidityPacked(["uint256", "uint256"], [publicKeyX, publicKeyY])
+    );
+    return { receipt, identity: keyHash };
+  }
+  /**
+   * Add a backup passkey to an existing identity
+   * Requires WebAuthn signature from an authorized key
+   * 
+   * @param signature WebAuthn signature from existing authorized key
+   * @param publicKeyX Existing key's X coordinate
+   * @param publicKeyY Existing key's Y coordinate
+   * @param newPublicKeyX New backup key's X coordinate
+   * @param newPublicKeyY New backup key's Y coordinate
+   * @param nonce Current nonce for the signing key
+   * @param signer Ethereum signer to pay gas
+   * @returns Transaction receipt and sequence number
+   */
+  async addBackupKey(signature, publicKeyX, publicKeyY, newPublicKeyX, newPublicKeyY, nonce, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.addBackupKey(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      newPublicKeyX,
+      newPublicKeyY,
+      nonce,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    let sequence = 0n;
+    for (const log of receipt.logs) {
+      try {
+        const parsed = this.hubContract.interface.parseLog({
+          topics: log.topics,
+          data: log.data
+        });
+        if (parsed?.name === "Dispatched") {
+          sequence = BigInt(parsed.args[3]);
+          break;
+        }
+      } catch {
+      }
+    }
+    return { receipt, sequence };
+  }
+  /**
+   * Remove a passkey from an identity
+   * Cannot remove the last remaining key
+   * 
+   * @param signature WebAuthn signature from an authorized key
+   * @param publicKeyX Signing key's X coordinate
+   * @param publicKeyY Signing key's Y coordinate
+   * @param keyToRemove Hash of the key to remove
+   * @param nonce Current nonce for the signing key
+   * @param signer Ethereum signer to pay gas
+   * @returns Transaction receipt and sequence number
+   */
+  async removeKey(signature, publicKeyX, publicKeyY, keyToRemove, nonce, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.removeKey(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      keyToRemove,
+      nonce,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    let sequence = 0n;
+    for (const log of receipt.logs) {
+      try {
+        const parsed = this.hubContract.interface.parseLog({
+          topics: log.topics,
+          data: log.data
+        });
+        if (parsed?.name === "Dispatched") {
+          sequence = BigInt(parsed.args[3]);
+          break;
+        }
+      } catch {
+      }
+    }
+    return { receipt, sequence };
+  }
+  // =========================================================================
+  //                      SOCIAL RECOVERY METHODS (Issue #23)
+  // =========================================================================
+  /**
+   * Setup guardians for an identity
+   * @param signature WebAuthn signature from owner
+   * @param publicKeyX Owner's public key X coordinate
+   * @param publicKeyY Owner's public key Y coordinate
+   * @param guardians Array of guardian key hashes
+   * @param threshold Required approvals for recovery
+   * @param signer Ethers signer for transaction
+   */
+  async setupGuardians(signature, publicKeyX, publicKeyY, guardians, threshold, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.setupGuardians(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      guardians,
+      threshold,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const sequence = this._extractSequenceFromReceipt(receipt);
+    return { receipt, sequence };
+  }
+  /**
+   * Add a guardian to an identity
+   */
+  async addGuardian(signature, publicKeyX, publicKeyY, guardianKeyHash, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.addGuardian(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      guardianKeyHash,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const sequence = this._extractSequenceFromReceipt(receipt);
+    return { receipt, sequence };
+  }
+  /**
+   * Remove a guardian from an identity
+   */
+  async removeGuardian(signature, publicKeyX, publicKeyY, guardianKeyHash, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.removeGuardian(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      guardianKeyHash,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const sequence = this._extractSequenceFromReceipt(receipt);
+    return { receipt, sequence };
+  }
+  /**
+   * Initiate recovery as a guardian
+   */
+  async initiateRecovery(signature, publicKeyX, publicKeyY, identityToRecover, newOwnerKeyHash, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.initiateRecovery(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      identityToRecover,
+      newOwnerKeyHash,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const sequence = this._extractSequenceFromReceipt(receipt);
+    return { receipt, sequence };
+  }
+  /**
+   * Approve recovery as a guardian
+   */
+  async approveRecovery(signature, publicKeyX, publicKeyY, identityToRecover, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.approveRecovery(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      identityToRecover,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const sequence = this._extractSequenceFromReceipt(receipt);
+    return { receipt, sequence };
+  }
+  /**
+   * Execute recovery after timelock (anyone can call)
+   */
+  async executeRecovery(identityToRecover, newPublicKeyX, newPublicKeyY, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.executeRecovery(
+      identityToRecover,
+      newPublicKeyX,
+      newPublicKeyY,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const sequence = this._extractSequenceFromReceipt(receipt);
+    return { receipt, sequence };
+  }
+  /**
+   * Cancel recovery as owner
+   */
+  async cancelRecovery(signature, publicKeyX, publicKeyY, signer) {
+    const hubWithSigner = this.hubContract.connect(signer);
+    const authTuple = {
+      authenticatorData: signature.authenticatorData,
+      clientDataJSON: signature.clientDataJSON,
+      challengeIndex: signature.challengeIndex,
+      typeIndex: signature.typeIndex,
+      r: signature.r,
+      s: signature.s
+    };
+    const messageFee = await this.getMessageFee();
+    const tx = await hubWithSigner.cancelRecovery(
+      authTuple,
+      publicKeyX,
+      publicKeyY,
+      { value: messageFee }
+    );
+    const receipt = await tx.wait();
+    const sequence = this._extractSequenceFromReceipt(receipt);
+    return { receipt, sequence };
+  }
+  /**
+   * Get guardians for an identity
+   */
+  async getGuardians(identityKeyHash) {
+    const result = await this.hubContract.getGuardians(identityKeyHash);
+    return {
+      guardians: result.guardians,
+      threshold: result.threshold,
+      isConfigured: result.isConfigured
+    };
+  }
+  /**
+   * Get recovery status for an identity
+   */
+  async getRecoveryStatus(identityKeyHash) {
+    const result = await this.hubContract.getRecoveryStatus(identityKeyHash);
+    return {
+      isActive: result.isActive,
+      newOwnerKeyHash: result.newOwnerKeyHash,
+      initiatedAt: result.initiatedAt,
+      approvalCount: result.approvalCount,
+      threshold: result.threshold,
+      canExecuteAt: result.canExecuteAt,
+      expiresAt: result.expiresAt
+    };
+  }
+  /**
+   * Check if a guardian has approved recovery
+   */
+  async hasGuardianApproved(identityKeyHash, guardianKeyHash) {
+    return this.hubContract.hasGuardianApproved(identityKeyHash, guardianKeyHash);
+  }
+  /**
+   * Helper to extract sequence from transaction receipt
+   */
+  _extractSequenceFromReceipt(receipt) {
+    for (const log of receipt.logs) {
+      try {
+        const parsed = this.hubContract.interface.parseLog({
+          topics: log.topics,
+          data: log.data
+        });
+        if (parsed?.name === "Dispatch") {
+          return BigInt(parsed.args.sequence);
+        }
+      } catch {
+      }
+    }
+    return 0n;
+  }
+};
+
+// src/chains/evm/EVMHubClientAdapter.ts
+var EVMHubClientAdapter = class {
+  constructor(evmClient, signer) {
+    this.evmClient = evmClient;
+    this.signer = signer;
+  }
+  /**
+   * Register a session on the Hub
+   * 
+   * @param params Registration parameters with Passkey signature
+   * @returns Promise that resolves when registration completes
+   */
+  async registerSession(params) {
+    await this.evmClient.registerSession(params, this.signer);
+  }
+  /**
+   * Revoke a session on the Hub
+   * 
+   * @param params Revocation parameters with Passkey signature
+   * @returns Promise that resolves when revocation completes
+   */
+  async revokeSession(params) {
+    await this.evmClient.revokeSession(params, this.signer);
+  }
+  /**
+   * Update the signer (e.g., when switching accounts)
+   * 
+   * @param signer New Ethereum signer
+   */
+  updateSigner(signer) {
+    this.signer = signer;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EVMClient,
+  EVMHubClientAdapter
+});
+//# sourceMappingURL=index.js.map