@veridex/sdk 1.0.0-beta.1

package/dist/chains/starknet/index.js

@@ -0,0 +1,534 @@
+"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/starknet/index.ts
+var starknet_exports = {};
+__export(starknet_exports, {
+  StarknetClient: () => StarknetClient
+});
+module.exports = __toCommonJS(starknet_exports);
+
+// src/chains/starknet/StarknetClient.ts
+var import_crypto = require("crypto");
+var import_starknet = require("starknet");
+
+// 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/starknet/StarknetClient.ts
+var FELT252_MAX = BigInt("0x0800000000000000000000000000000000000000000000000000000000000000") - 1n;
+var U128_MAX = BigInt("0x100000000000000000000000000000000");
+function toStarknetU256(keyHash) {
+  const cleanHash = keyHash.replace("0x", "").padStart(64, "0");
+  const value = BigInt("0x" + cleanHash);
+  const low = value % U128_MAX;
+  const high = value / U128_MAX;
+  return [
+    "0x" + low.toString(16),
+    "0x" + high.toString(16)
+  ];
+}
+var StarknetClient = class {
+  config;
+  provider;
+  hubRpcUrl;
+  hubContractAddress;
+  constructor(config) {
+    this.config = {
+      name: `Starknet ${config.network || "mainnet"}`,
+      chainId: 0,
+      wormholeChainId: config.wormholeChainId,
+      rpcUrl: config.rpcUrl,
+      explorerUrl: config.network === "sepolia" ? "https://sepolia.starkscan.co" : "https://starkscan.co",
+      isEvm: false,
+      contracts: {
+        hub: config.spokeContractAddress,
+        wormholeCoreBridge: config.bridgeContractAddress ?? ""
+      }
+    };
+    this.hubRpcUrl = config.hubRpcUrl;
+    this.hubContractAddress = config.hubContractAddress;
+    this.provider = new import_starknet.RpcProvider({ nodeUrl: config.rpcUrl });
+  }
+  getConfig() {
+    return this.config;
+  }
+  async getNonce(_userKeyHash) {
+    return 0n;
+  }
+  async getMessageFee() {
+    return 0n;
+  }
+  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) {
+    void signature;
+    void publicKeyX;
+    void publicKeyY;
+    void targetChain;
+    void actionPayload;
+    void nonce;
+    void signer;
+    throw new Error(
+      "Direct dispatch not supported on Starknet. Starknet actions are executed via the Veridex Hub (Base Sepolia) + custom bridge. Use dispatchGasless() to route through relayer, which will submit attestations to the bridge."
+    );
+  }
+  async dispatchGasless(signature, publicKeyX, publicKeyY, targetChain, actionPayload, nonce, relayerUrl) {
+    const keyHash = this.computeKeyHash(publicKeyX, publicKeyY);
+    const request = {
+      signature: {
+        r: "0x" + signature.r.toString(16).padStart(64, "0"),
+        s: "0x" + signature.s.toString(16).padStart(64, "0"),
+        authenticatorData: signature.authenticatorData,
+        clientDataJSON: signature.clientDataJSON,
+        challengeIndex: signature.challengeIndex,
+        typeIndex: signature.typeIndex
+      },
+      publicKeyX: "0x" + publicKeyX.toString(16).padStart(64, "0"),
+      publicKeyY: "0x" + publicKeyY.toString(16).padStart(64, "0"),
+      targetChain,
+      // 50001 for Starknet
+      actionPayload,
+      userNonce: 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 errorText = await response.text().catch(() => "Unknown error");
+      throw new Error(
+        `Relayer submission failed: ${response.status} ${response.statusText}. Error: ${errorText}`
+      );
+    }
+    const result = await response.json();
+    return {
+      transactionHash: result.transactionHash ?? result.txHash ?? result.hubTxHash,
+      sequence: BigInt(result.sequence || 0),
+      userKeyHash: keyHash,
+      targetChain
+    };
+  }
+  // Note: getVaultAddress is now defined in the Social Recovery section below
+  // with enhanced spoke contract querying support.
+  computeVaultAddress(userKeyHash) {
+    const clean = userKeyHash.replace(/^0x/, "");
+    return "0x" + clean;
+  }
+  async vaultExists(userKeyHash) {
+    if (!this.config.contracts.hub) {
+      return false;
+    }
+    try {
+      const vaultAddress = await this.getVaultAddress(userKeyHash);
+      if (!vaultAddress) {
+        return false;
+      }
+      const anyProvider = this.provider;
+      if (typeof anyProvider.getClassHashAt === "function") {
+        await anyProvider.getClassHashAt(vaultAddress);
+        return true;
+      }
+    } catch {
+    }
+    return false;
+  }
+  async createVault(userKeyHash, signer) {
+    void signer;
+    throw new Error(
+      `Vault creation on Starknet must be done via Hub dispatch + custom bridge attestation. Use Hub client (Base Sepolia) to dispatch a CREATE_VAULT action with targetChain=50001. KeyHash=${userKeyHash}`
+    );
+  }
+  async createVaultSponsored(userKeyHash, sponsorPrivateKey, rpcUrl) {
+    void userKeyHash;
+    void sponsorPrivateKey;
+    void rpcUrl;
+    throw new Error(
+      "Vault creation on Starknet must be done via Hub dispatch + custom bridge attestation. Use Hub client (Base Sepolia) with sponsor key to dispatch CREATE_VAULT action."
+    );
+  }
+  /**
+   * Create a vault via the relayer (sponsored/gasless)
+   * This is the recommended way to create Starknet vaults
+   * 
+   * The relayer will dispatch a vault creation action from Hub via custom bridge to Starknet spoke
+   */
+  async createVaultViaRelayer(userKeyHash, relayerUrl) {
+    const response = await fetch(`${relayerUrl}/api/v1/starknet/vault`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        userKeyHash,
+        chainId: this.config.wormholeChainId
+      })
+    });
+    const result = await response.json();
+    if (!response.ok || !result.success) {
+      throw new Error(result.error || "Failed to create vault via relayer");
+    }
+    return {
+      address: result.vaultAddress,
+      transactionHash: result.transactionHash || "",
+      blockNumber: 0,
+      gasUsed: 0n,
+      alreadyExisted: result.alreadyExists || false,
+      sponsoredBy: "relayer"
+    };
+  }
+  /**
+   * Get vault info via relayer (includes existence check)
+   */
+  async getVaultViaRelayer(userKeyHash, relayerUrl) {
+    const response = await fetch(
+      `${relayerUrl}/api/v1/starknet/vault/${userKeyHash}?chainId=${this.config.wormholeChainId}`
+    );
+    if (!response.ok) {
+      throw new Error("Failed to get vault info from relayer");
+    }
+    const result = await response.json();
+    return {
+      vaultAddress: result.vaultAddress,
+      exists: result.exists
+    };
+  }
+  async estimateVaultCreationGas(_userKeyHash) {
+    return 0n;
+  }
+  getFactoryAddress() {
+    return void 0;
+  }
+  getImplementationAddress() {
+    return void 0;
+  }
+  // ========================================================================
+  // Balance utility (best-effort)
+  // ========================================================================
+  async getNativeBalance(address) {
+    try {
+      const anyProvider = this.provider;
+      if (typeof anyProvider.getBalance === "function") {
+        const res = await anyProvider.getBalance(address);
+        return BigInt(res);
+      }
+    } catch {
+    }
+    return 0n;
+  }
+  getProvider() {
+    return this.provider;
+  }
+  // ========================================================================
+  // Session Management (Issue #13)
+  // ========================================================================
+  /**
+   * Register a session key on the Hub (must be called via Hub client)
+   * Starknet spokes validate sessions via CCQ, but registration happens on Hub
+   * 
+   * @throws Error - Session management must be done via Hub chain
+   */
+  async registerSession(_params) {
+    throw new Error(
+      "Session registration must be performed on the Hub chain (Base). Use EVMClient connected to the Hub to call registerSession()."
+    );
+  }
+  /**
+   * Revoke a session key on the Hub (must be called via Hub client)
+   * 
+   * @throws Error - Session management must be done via Hub chain
+   */
+  async revokeSession(_params) {
+    throw new Error(
+      "Session revocation must be performed on the Hub chain (Base). Use EVMClient connected to the Hub to call revokeSession()."
+    );
+  }
+  /**
+   * Check if a session is active by querying the Hub
+   * This method queries the Hub contract directly for session validation
+   * 
+   * @param userKeyHash - Hash of user's Passkey public key
+   * @param sessionKeyHash - Hash of session key to validate
+   * @returns Session validation result with expiry and limits
+   */
+  async isSessionActive(userKeyHash, sessionKeyHash) {
+    if (!this.hubRpcUrl || !this.hubContractAddress) {
+      throw new Error(
+        "Hub configuration required for session validation. Provide hubRpcUrl and hubContractAddress in StarknetClientConfig."
+      );
+    }
+    throw new Error(
+      "isSessionActive requires Hub client integration. Use EVMClient.isSessionActive() on the Hub chain, then pass the result to session execution on Starknet."
+    );
+  }
+  /**
+   * Get all sessions for a user from the Hub
+   * 
+   * @param userKeyHash - Hash of user's Passkey public key
+   * @returns Array of all sessions (active and expired/revoked)
+   */
+  async getUserSessions(userKeyHash) {
+    if (!this.hubRpcUrl || !this.hubContractAddress) {
+      throw new Error(
+        "Hub configuration required for session queries. Provide hubRpcUrl and hubContractAddress in StarknetClientConfig."
+      );
+    }
+    throw new Error(
+      `getUserSessions requires Hub client integration. Use EVMClient.getUserSessions() on the Hub chain. User: ${userKeyHash}`
+    );
+  }
+  // ========================================================================
+  // Query-Based Execution (Issue #9/#10)
+  // ========================================================================
+  /**
+   * Get user state from Hub (comprehensive state query)
+   * Returns key hash, nonce, and last action hash for CCQ validation
+   * 
+   * @param userKeyHash - Hash of user's Passkey public key
+   * @returns User state with nonce and last action hash
+   */
+  async getUserState(userKeyHash) {
+    if (!this.hubRpcUrl || !this.hubContractAddress) {
+      throw new Error(
+        "Hub configuration required for state queries. Provide hubRpcUrl and hubContractAddress in StarknetClientConfig."
+      );
+    }
+    throw new Error(
+      `getUserState requires Hub client integration. Use EVMClient.getUserState() on the Hub chain. User: ${userKeyHash}`
+    );
+  }
+  /**
+   * Get user's last action hash from Hub
+   * Used for optimistic execution and nonce validation
+   * 
+   * @param userKeyHash - Hash of user's Passkey public key
+   * @returns Last action hash (zero hash if no actions)
+   */
+  async getUserLastActionHash(userKeyHash) {
+    if (!this.hubRpcUrl || !this.hubContractAddress) {
+      throw new Error(
+        "Hub configuration required for action hash queries. Provide hubRpcUrl and hubContractAddress in StarknetClientConfig."
+      );
+    }
+    throw new Error(
+      `getUserLastActionHash requires Hub client integration. Use EVMClient.getUserLastActionHash() on the Hub chain. User: ${userKeyHash}`
+    );
+  }
+  /**
+   * Execute with query-based validation (faster than VAA, ~23s vs 60-90s)
+   * Uses Wormhole CCQ to validate Hub state, then executes on Starknet
+   * 
+   * @param params Query execution parameters with CCQ response
+   * @returns Dispatch result with transaction hash
+   * 
+   * @remarks
+   * Query-based execution flow:
+   * 1. Query Hub state via Wormhole CCQ
+   * 2. Validate Guardian signatures on query response
+   * 3. Execute on Starknet with validated state
+   * 4. Hub state must be < 60s stale (enforced by QueryVerifier)
+   */
+  async executeWithQuery(_params) {
+    throw new Error(
+      "Query-based execution on Starknet requires relayer integration. Use relayer API to submit query-validated transactions. Relayer will call veridex_spoke::execute_with_query on Starknet."
+    );
+  }
+  // ========================================================================
+  // Internal helpers
+  // ========================================================================
+  computeKeyHash(publicKeyX, publicKeyY) {
+    const xHex = publicKeyX.toString(16).padStart(64, "0");
+    const yHex = publicKeyY.toString(16).padStart(64, "0");
+    const combined = Buffer.from(xHex + yHex, "hex");
+    const hash = (0, import_crypto.createHash)("sha256").update(combined).digest("hex");
+    return "0x" + hash;
+  }
+  buildMessageHash(keyHash, targetChain, actionPayload, nonce) {
+    const keyHashBuffer = Buffer.from(keyHash.replace(/^0x/, ""), "hex");
+    const targetChainBuffer = Buffer.alloc(2);
+    targetChainBuffer.writeUInt16BE(targetChain);
+    const payloadBuffer = Buffer.from(actionPayload.replace(/^0x/, ""), "hex");
+    const nonceHex = nonce.toString(16).padStart(64, "0");
+    const nonceBuffer = Buffer.from(nonceHex, "hex");
+    const combined = Buffer.concat([keyHashBuffer, targetChainBuffer, payloadBuffer, nonceBuffer]);
+    const hash = (0, import_crypto.createHash)("sha256").update(combined).digest("hex");
+    return "0x" + hash;
+  }
+  // ============================================================================
+  // Social Recovery Methods (Issue #23)
+  // ============================================================================
+  // 
+  // Note: Social recovery is managed on the Hub chain (EVM).
+  // Starknet spokes receive and execute recovery VAAs broadcast from the Hub.
+  // The relayer service handles submitting recovery transactions to Starknet.
+  //
+  // SDK users should use EVMClient methods for guardian management and
+  // recovery initiation on the Hub chain.
+  // ============================================================================
+  /**
+   * Get vault address by owner key hash
+   * 
+   * @param ownerKeyHash - Owner's passkey hash
+   * @returns Vault address on Starknet (felt252 as hex string)
+   */
+  async getVaultAddress(ownerKeyHash) {
+    try {
+      const spokeAddress = this.config.contracts.hub;
+      if (!spokeAddress) {
+        throw new Error("Spoke contract address not configured");
+      }
+      const [low, high] = toStarknetU256(ownerKeyHash);
+      const result = await this.provider.callContract({
+        contractAddress: spokeAddress,
+        entrypoint: "get_vault",
+        calldata: [low, high]
+      });
+      const vaultAddress = result[0];
+      if (vaultAddress === "0x0" || vaultAddress === "0") {
+        return null;
+      }
+      return vaultAddress;
+    } catch (error) {
+      console.error("Error getting vault address:", error);
+      return null;
+    }
+  }
+  /**
+   * Check if vault exists and get basic info
+   * 
+   * @param ownerKeyHash - Owner's passkey hash  
+   * @returns Vault info or null if not found
+   */
+  async getVaultInfo(ownerKeyHash) {
+    const vaultAddress = await this.getVaultAddress(ownerKeyHash);
+    if (!vaultAddress) {
+      return null;
+    }
+    return {
+      address: vaultAddress,
+      ownerKeyHash
+    };
+  }
+  /**
+   * Check if spoke contract is paused
+   * 
+   * @returns Whether the protocol is paused
+   */
+  async isProtocolPaused() {
+    try {
+      const spokeAddress = this.config.contracts.hub;
+      if (!spokeAddress) {
+        throw new Error("Spoke contract address not configured");
+      }
+      const result = await this.provider.callContract({
+        contractAddress: spokeAddress,
+        entrypoint: "is_paused",
+        calldata: []
+      });
+      return result[0] === "0x1" || result[0] === "1";
+    } catch (error) {
+      console.error("Error checking pause status:", error);
+      return false;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StarknetClient
+});
+//# sourceMappingURL=index.js.map