@veridex/sdk 1.0.0-beta.16 → 1.0.0-beta.17

package/dist/index.mjs

@@ -546,17 +546,36 @@ function sleep(ms) {
 }
 
 // src/core/PasskeyManager.ts
-function detectRpId() {
+var VERIDEX_RP_ID = "veridex.network";
+function detectRpId(forceLocal) {
   if (typeof window === "undefined") return "localhost";
   const hostname = window.location.hostname;
   if (hostname === "localhost" || hostname === "127.0.0.1" || /^\d+\.\d+\.\d+\.\d+$/.test(hostname)) {
     return hostname;
   }
-  const parts = hostname.split(".");
-  if (parts.length <= 2) {
-    return hostname;
+  if (forceLocal) {
+    const parts = hostname.split(".");
+    if (parts.length <= 2) {
+      return hostname;
+    }
+    return parts.slice(-2).join(".");
+  }
+  return VERIDEX_RP_ID;
+}
+async function supportsRelatedOrigins() {
+  if (typeof window === "undefined" || !window.PublicKeyCredential) {
+    return false;
+  }
+  if ("getClientCapabilities" in PublicKeyCredential) {
+    try {
+      const getCapabilities = PublicKeyCredential.getClientCapabilities;
+      const capabilities = await getCapabilities();
+      return capabilities?.relatedOrigins === true;
+    } catch {
+      return false;
+    }
   }
-  return parts.slice(-2).join(".");
+  return false;
 }
 var PasskeyManager = class _PasskeyManager {
   config;
@@ -1702,9 +1721,10 @@ function getChainName(wormholeChainId) {
 
 // src/core/BalanceManager.ts
 var DEFAULT_RPC_URLS = {
+  10002: "https://ethereum-sepolia-rpc.publicnode.com",
+  10003: "https://sepolia-rollup.arbitrum.io/rpc",
   10004: "https://sepolia.base.org",
-  10005: "https://sepolia.optimism.io",
-  10003: "https://sepolia-rollup.arbitrum.io/rpc"
+  10005: "https://sepolia.optimism.io"
 };
 var TESTNET_TOKEN_PRICES = {
   ETH: 2500,
@@ -1939,9 +1959,10 @@ var DEFAULT_POLLING_INTERVAL = 2e3;
 var DEFAULT_REQUIRED_CONFIRMATIONS = 1;
 var DEFAULT_TIMEOUT = 3e5;
 var DEFAULT_RPC_URLS2 = {
+  10002: "https://ethereum-sepolia-rpc.publicnode.com",
+  10003: "https://sepolia-rollup.arbitrum.io/rpc",
   10004: "https://sepolia.base.org",
-  10005: "https://sepolia.optimism.io",
-  10003: "https://sepolia-rollup.arbitrum.io/rpc"
+  10005: "https://sepolia.optimism.io"
 };
 var TransactionTracker = class {
   config;
@@ -11054,161 +11075,1130 @@ var EVMClient = class {
   }
 };
 
-// src/presets.ts
-var CHAIN_NAMES = {
-  // EVM L2s (Hub-capable)
-  BASE: "base",
-  OPTIMISM: "optimism",
-  ARBITRUM: "arbitrum",
-  SCROLL: "scroll",
-  BLAST: "blast",
-  MANTLE: "mantle",
-  // EVM L1s
-  ETHEREUM: "ethereum",
-  POLYGON: "polygon",
-  BSC: "bsc",
-  AVALANCHE: "avalanche",
-  FANTOM: "fantom",
-  CELO: "celo",
-  MOONBEAM: "moonbeam",
-  // Non-EVM
-  SOLANA: "solana",
-  APTOS: "aptos",
-  SUI: "sui",
-  STARKNET: "starknet",
-  NEAR: "near",
-  SEI: "sei"
+// src/chains/stacks/StacksSigner.ts
+var P256_ORDER = BigInt(
+  "0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551"
+);
+var P256_HALF_ORDER = P256_ORDER / 2n;
+function compressPublicKey(x, y) {
+  const prefix = y % 2n === 0n ? 2 : 3;
+  const xBytes = bigintToBytes(x, 32);
+  const compressed = new Uint8Array(33);
+  compressed[0] = prefix;
+  compressed.set(xBytes, 1);
+  return compressed;
+}
+function rsToCompactSignature(r, s) {
+  const normalizedS = s > P256_HALF_ORDER ? P256_ORDER - s : s;
+  const compact = new Uint8Array(64);
+  compact.set(bigintToBytes(r, 32), 0);
+  compact.set(bigintToBytes(normalizedS, 32), 32);
+  return compact;
+}
+function parseDERSignature2(der) {
+  if (der[0] !== 48) {
+    throw new Error("Invalid DER signature: expected SEQUENCE tag 0x30");
+  }
+  let offset = 2;
+  if (der[offset] !== 2) {
+    throw new Error("Invalid DER signature: expected INTEGER tag 0x02 for r");
+  }
+  offset++;
+  const rLen = der[offset];
+  offset++;
+  const rBytes = der.slice(offset, offset + rLen);
+  offset += rLen;
+  if (der[offset] !== 2) {
+    throw new Error("Invalid DER signature: expected INTEGER tag 0x02 for s");
+  }
+  offset++;
+  const sLen = der[offset];
+  offset++;
+  const sBytes = der.slice(offset, offset + sLen);
+  return {
+    r: bytesToBigint(rBytes),
+    s: bytesToBigint(sBytes)
+  };
+}
+function derToCompactSignature(der) {
+  const { r, s } = parseDERSignature2(der);
+  return rsToCompactSignature(r, s);
+}
+async function computeKeyHash2(compressedPubkey) {
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", compressedPubkey.buffer);
+  const hashArray = new Uint8Array(hashBuffer);
+  return "0x" + bytesToHex(hashArray);
+}
+async function computeKeyHashFromCoords(x, y) {
+  const compressed = compressPublicKey(x, y);
+  return computeKeyHash2(compressed);
+}
+async function buildRegistrationHash(nonce) {
+  const message = `veridex:register:${nonce}`;
+  const encoded = new TextEncoder().encode(message);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded.buffer);
+  return new Uint8Array(hashBuffer);
+}
+async function buildSessionRegistrationHash(sessionKeyHash, duration, maxValue, nonce) {
+  const cleanHash = sessionKeyHash.replace("0x", "");
+  const message = `veridex:session:${cleanHash}:${duration}:${maxValue}:${nonce}`;
+  const encoded = new TextEncoder().encode(message);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded.buffer);
+  return new Uint8Array(hashBuffer);
+}
+async function buildRevocationHash(sessionHash, nonce) {
+  const cleanHash = sessionHash.replace("0x", "");
+  const message = `veridex:revoke:${cleanHash}:${nonce}`;
+  const encoded = new TextEncoder().encode(message);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded.buffer);
+  return new Uint8Array(hashBuffer);
+}
+async function buildExecuteHash(actionType, amount, recipient, nonce) {
+  const message = `veridex:execute:${actionType}:${amount}:${recipient}:${nonce}`;
+  const encoded = new TextEncoder().encode(message);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded.buffer);
+  return new Uint8Array(hashBuffer);
+}
+async function buildWithdrawalHash(amount, recipient, nonce) {
+  const message = `veridex:withdraw:${amount}:${recipient}:${nonce}`;
+  const encoded = new TextEncoder().encode(message);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded.buffer);
+  return new Uint8Array(hashBuffer);
+}
+function bigintToBytes(value, length) {
+  const hex = value.toString(16).padStart(length * 2, "0");
+  const bytes = new Uint8Array(length);
+  for (let i = 0; i < length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function bytesToBigint(bytes) {
+  let start = 0;
+  while (start < bytes.length - 1 && bytes[start] === 0) {
+    start++;
+  }
+  let result = 0n;
+  for (let i = start; i < bytes.length; i++) {
+    result = result << 8n | BigInt(bytes[i]);
+  }
+  return result;
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function hexToBytes(hex) {
+  const clean = hex.replace("0x", "");
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+// src/chains/stacks/StacksAddressUtils.ts
+var STACKS_MAINNET_PREFIX = "SP";
+var STACKS_TESTNET_PREFIX = "ST";
+var C32_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function isValidStacksPrincipal(address) {
+  if (!address || typeof address !== "string") {
+    return false;
+  }
+  const parts = address.split(".");
+  if (parts.length > 2) {
+    return false;
+  }
+  const standardPart = parts[0];
+  const contractName = parts[1];
+  if (!isValidStandardPrincipal(standardPart)) {
+    return false;
+  }
+  if (contractName !== void 0) {
+    if (!isValidContractName(contractName)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isValidStandardPrincipal(address) {
+  if (!address || address.length < 5) {
+    return false;
+  }
+  const prefix = address.slice(0, 2);
+  if (prefix !== STACKS_MAINNET_PREFIX && prefix !== STACKS_TESTNET_PREFIX) {
+    return false;
+  }
+  if (address.length < 38 || address.length > 42) {
+    return false;
+  }
+  const body = address.slice(1).toUpperCase();
+  for (const char of body) {
+    if (!C32_ALPHABET.includes(char)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isValidContractName(name) {
+  if (!name || name.length === 0 || name.length > 128) {
+    return false;
+  }
+  if (!/^[a-zA-Z]/.test(name)) {
+    return false;
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(name)) {
+    return false;
+  }
+  return true;
+}
+function getNetworkFromAddress(address) {
+  const prefix = address.slice(0, 2);
+  if (prefix === STACKS_MAINNET_PREFIX) {
+    return "mainnet";
+  }
+  return "testnet";
+}
+function getContractPrincipal(deployerAddress, contractName) {
+  if (!isValidStandardPrincipal(deployerAddress)) {
+    throw new Error(`Invalid deployer address: ${deployerAddress}`);
+  }
+  if (!isValidContractName(contractName)) {
+    throw new Error(`Invalid contract name: ${contractName}`);
+  }
+  return `${deployerAddress}.${contractName}`;
+}
+function parseContractPrincipal(contractPrincipal) {
+  const dotIndex = contractPrincipal.indexOf(".");
+  if (dotIndex === -1) {
+    throw new Error(
+      `Not a contract principal: ${contractPrincipal}. Expected format: address.contract-name`
+    );
+  }
+  return {
+    address: contractPrincipal.slice(0, dotIndex),
+    contractName: contractPrincipal.slice(dotIndex + 1)
+  };
+}
+function isContractPrincipal(address) {
+  return address.includes(".");
+}
+function getStacksExplorerTxUrl(txId, network = "testnet") {
+  const cleanTxId = txId.startsWith("0x") ? txId : `0x${txId}`;
+  const chainParam = network === "testnet" ? "&chain=testnet" : "";
+  return `https://explorer.hiro.so/txid/${cleanTxId}?${chainParam}`;
+}
+function getStacksExplorerAddressUrl(address, network = "testnet") {
+  const chainParam = network === "testnet" ? "?chain=testnet" : "";
+  return `https://explorer.hiro.so/address/${address}${chainParam}`;
+}
+
+// src/chains/stacks/StacksClient.ts
+var STACKS_ACTION_TYPES = {
+  TRANSFER_STX: 1,
+  TRANSFER_SBTC: 2,
+  CONTRACT_CALL: 3
 };
-var CHAIN_PRESETS = {
-  // ────────────────────────────────────────────────────────────────────────
-  // BASE - Primary Hub Chain
-  // ────────────────────────────────────────────────────────────────────────
-  base: {
-    displayName: "Base",
-    type: "evm",
-    canBeHub: true,
-    testnet: {
-      name: "Base Sepolia",
-      chainId: 84532,
-      wormholeChainId: 10004,
-      rpcUrl: "https://sepolia.base.org",
-      explorerUrl: "https://sepolia.basescan.org",
-      isEvm: true,
-      contracts: {
-        hub: "0x66D87dE68327f48A099c5B9bE97020Feab9a7c82",
-        vaultFactory: "0xCFaEb5652aa2Ee60b2229dC8895B4159749C7e53",
-        vaultImplementation: "0x0d13367C16c6f0B24eD275CC67C7D9f42878285c",
-        wormholeCoreBridge: "0x79A1027a6A159502049F10906D333EC57E95F083",
-        tokenBridge: "0x86F55A04690fd7815A3D802bD587e83eA888B239"
-      }
-    },
-    mainnet: {
-      name: "Base",
-      chainId: 8453,
-      wormholeChainId: 30,
-      rpcUrl: "https://mainnet.base.org",
-      explorerUrl: "https://basescan.org",
-      isEvm: true,
-      contracts: {
-        // TODO: Deploy mainnet contracts
-        wormholeCoreBridge: "0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6",
-        tokenBridge: "0x8d2de8d2f73F1F4cAB472AC9A881C9b123C79627"
-      }
+var HIRO_API = {
+  testnet: "https://api.testnet.hiro.so",
+  mainnet: "https://api.hiro.so"
+};
+var StacksClient = class {
+  config;
+  rpcUrl;
+  spokeContract;
+  vaultContract;
+  wormholeVerifierContract;
+  vaultVaaContract;
+  networkType;
+  constructor(clientConfig) {
+    this.networkType = clientConfig.network || "testnet";
+    this.rpcUrl = clientConfig.rpcUrl || HIRO_API[this.networkType];
+    if (clientConfig.spokeContractAddress && isContractPrincipal(clientConfig.spokeContractAddress)) {
+      const parsed = parseContractPrincipal(clientConfig.spokeContractAddress);
+      this.spokeContract = { address: parsed.address, name: parsed.contractName };
+    } else {
+      this.spokeContract = null;
     }
-  },
-  // ────────────────────────────────────────────────────────────────────────
-  // OPTIMISM - Secondary Hub / Spoke
-  // ────────────────────────────────────────────────────────────────────────
-  optimism: {
-    displayName: "Optimism",
-    type: "evm",
-    canBeHub: true,
-    testnet: {
-      name: "Optimism Sepolia",
-      chainId: 11155420,
-      wormholeChainId: 10005,
-      rpcUrl: "https://sepolia.optimism.io",
-      explorerUrl: "https://sepolia-optimism.etherscan.io",
-      isEvm: true,
-      contracts: {
-        vaultFactory: "0xA5653d54079ABeCe780F8d9597B2bc4B09fe464A",
-        vaultImplementation: "0x8099b1406485d2255ff89Ce5Ea18520802AFC150",
-        wormholeCoreBridge: "0x31377888146f3253211EFEf5c676D41ECe7D58Fe",
-        tokenBridge: "0x99737Ec4B815d816c49A385943baf0380e75c0Ac"
-      }
-    },
-    mainnet: {
-      name: "Optimism",
-      chainId: 10,
-      wormholeChainId: 24,
-      rpcUrl: "https://mainnet.optimism.io",
-      explorerUrl: "https://optimistic.etherscan.io",
-      isEvm: true,
-      contracts: {
-        wormholeCoreBridge: "0xEe91C335eab126dF5fDB3797EA9d6aD93aeC9722",
-        tokenBridge: "0x1D68124e65faFC907325e3EDbF8c4d84499DAa8b"
-      }
+    if (clientConfig.vaultContractAddress && isContractPrincipal(clientConfig.vaultContractAddress)) {
+      const parsed = parseContractPrincipal(clientConfig.vaultContractAddress);
+      this.vaultContract = { address: parsed.address, name: parsed.contractName };
+    } else {
+      this.vaultContract = null;
     }
-  },
-  // ────────────────────────────────────────────────────────────────────────
-  // ARBITRUM
-  // ────────────────────────────────────────────────────────────────────────
-  arbitrum: {
-    displayName: "Arbitrum",
-    type: "evm",
-    canBeHub: true,
-    testnet: {
-      name: "Arbitrum Sepolia",
-      chainId: 421614,
-      wormholeChainId: 10003,
-      rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc",
-      explorerUrl: "https://sepolia.arbiscan.io",
-      isEvm: true,
-      contracts: {
-        vaultFactory: "0xd36D3D5DB59d78f1E33813490F72DABC15C9B07c",
-        vaultImplementation: "0xB10ACf39eBF17fc33F722cBD955b7aeCB0611bc4",
-        wormholeCoreBridge: "0x6b9C8671cdDC8dEab9c719bB87cBd3e782bA6a35",
-        tokenBridge: "0xC7A204bDBFe983FCD8d8E61D02b475D4073fF97e"
-      }
-    },
-    mainnet: {
-      name: "Arbitrum",
-      chainId: 42161,
-      wormholeChainId: 23,
-      rpcUrl: "https://arb1.arbitrum.io/rpc",
-      explorerUrl: "https://arbiscan.io",
-      isEvm: true,
+    if (clientConfig.wormholeVerifierAddress && isContractPrincipal(clientConfig.wormholeVerifierAddress)) {
+      const parsed = parseContractPrincipal(clientConfig.wormholeVerifierAddress);
+      this.wormholeVerifierContract = { address: parsed.address, name: parsed.contractName };
+    } else {
+      this.wormholeVerifierContract = null;
+    }
+    if (clientConfig.vaultVaaContractAddress && isContractPrincipal(clientConfig.vaultVaaContractAddress)) {
+      const parsed = parseContractPrincipal(clientConfig.vaultVaaContractAddress);
+      this.vaultVaaContract = { address: parsed.address, name: parsed.contractName };
+    } else {
+      this.vaultVaaContract = null;
+    }
+    if (this.spokeContract && !this.vaultContract) {
+      this.vaultContract = {
+        address: this.spokeContract.address,
+        name: "veridex-vault"
+      };
+    }
+    if (this.spokeContract && !this.wormholeVerifierContract) {
+      this.wormholeVerifierContract = {
+        address: this.spokeContract.address,
+        name: "veridex-wormhole-verifier"
+      };
+    }
+    if (this.spokeContract && !this.vaultVaaContract) {
+      this.vaultVaaContract = {
+        address: this.spokeContract.address,
+        name: "veridex-vault-vaa"
+      };
+    }
+    this.config = {
+      name: `Stacks ${this.networkType}`,
+      chainId: this.networkType === "mainnet" ? 1 : 2147483648,
+      wormholeChainId: clientConfig.wormholeChainId,
+      rpcUrl: this.rpcUrl,
+      explorerUrl: this.networkType === "testnet" ? "https://explorer.hiro.so/?chain=testnet" : "https://explorer.hiro.so",
+      isEvm: false,
       contracts: {
-        wormholeCoreBridge: "0xa5f208e072434bC67592E4C49C1B991BA79BCA46",
-        tokenBridge: "0x0b2402144Bb366A632D14B83F244D2e0e21bD39c"
+        hub: clientConfig.spokeContractAddress,
+        wormholeCoreBridge: "",
+        wormholeVerifier: this.wormholeVerifierContract ? `${this.wormholeVerifierContract.address}.${this.wormholeVerifierContract.name}` : void 0,
+        vaultVaa: this.vaultVaaContract ? `${this.vaultVaaContract.address}.${this.vaultVaaContract.name}` : void 0
       }
+    };
+  }
+  // ========================================================================
+  // ChainClient Interface - Configuration
+  // ========================================================================
+  getConfig() {
+    return this.config;
+  }
+  // ========================================================================
+  // ChainClient Interface - Nonce & Fees
+  // ========================================================================
+  /**
+   * Get the current nonce for a user identity from the spoke contract.
+   * Calls the read-only function `get-nonce` on veridex-spoke.
+   */
+  async getNonce(userKeyHash) {
+    if (!this.spokeContract) {
+      return 0n;
     }
-  },
-  // ────────────────────────────────────────────────────────────────────────
-  // ETHEREUM
-  // ────────────────────────────────────────────────────────────────────────
-  ethereum: {
-    displayName: "Ethereum",
-    type: "evm",
-    canBeHub: false,
-    testnet: {
-      name: "Sepolia",
-      chainId: 11155111,
-      wormholeChainId: 10002,
-      rpcUrl: "https://ethereum-sepolia-rpc.publicnode.com",
-      explorerUrl: "https://sepolia.etherscan.io",
-      isEvm: true,
-      contracts: {
-        vaultFactory: "0x07F608AFf6d63b68029488b726d895c4Bb593038",
-        vaultImplementation: "0xD66153fccFB6731fB6c4944FbD607ba86A76a1f6",
-        wormholeCoreBridge: "0x4a8bc80Ed5a4067f1CCf107057b8270E0cC11A78",
-        tokenBridge: "0xDB5492265f6038831E89f495670FF909aDe94bd9"
+    try {
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "get-nonce",
+        [`0x${userKeyHash.replace("0x", "")}`]
+      );
+      if (result && result.value !== void 0) {
+        return BigInt(result.value);
       }
-    },
-    mainnet: {
-      name: "Ethereum",
-      chainId: 1,
-      wormholeChainId: 2,
+      return 0n;
+    } catch {
+      return 0n;
+    }
+  }
+  /**
+   * Get the Wormhole message fee.
+   * Phase 1: No Wormhole integration, returns 0.
+   */
+  async getMessageFee() {
+    return 0n;
+  }
+  // ========================================================================
+  // ChainClient Interface - Payload Building
+  // ========================================================================
+  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);
+  }
+  // ========================================================================
+  // ChainClient Interface - Dispatch
+  // ========================================================================
+  /**
+   * Direct dispatch is not supported on Stacks in Phase 1.
+   * Stacks actions are executed via sponsored transactions through the relayer.
+   */
+  async dispatch(_signature, _publicKeyX, _publicKeyY, _targetChain, _actionPayload, _nonce, _signer) {
+    throw new Error(
+      "Direct dispatch not supported on Stacks in Phase 1. Use dispatchGasless() to route through the relayer, which sponsors Stacks transactions. Phase 2 will add Wormhole cross-chain dispatch support."
+    );
+  }
+  /**
+   * Dispatch an action via the relayer (gasless/sponsored).
+   *
+   * Flow:
+   * 1. User signs action with Passkey (on client)
+   * 2. SDK submits to relayer with targetChain=60 (Stacks)
+   * 3. Relayer builds Clarity contract-call transaction
+   * 4. Relayer sponsors the transaction (pays STX gas)
+   * 5. Relayer broadcasts to Stacks network
+   * 6. Transaction confirmed on Stacks
+   */
+  async dispatchGasless(signature, publicKeyX, publicKeyY, targetChain, actionPayload, nonce, relayerUrl) {
+    const keyHash = await computeKeyHashFromCoords(publicKeyX, publicKeyY);
+    const compressedPubkey = compressPublicKey(publicKeyX, publicKeyY);
+    const compactSig = rsToCompactSignature(signature.r, signature.s);
+    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"),
+      compressedPubkey: "0x" + bytesToHex(compressedPubkey),
+      compactSignature: "0x" + bytesToHex(compactSig),
+      targetChain,
+      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
+    };
+  }
+  // ========================================================================
+  // ChainClient Interface - Vault Management
+  // ========================================================================
+  /**
+   * Get vault address for a user.
+   * On Stacks, vaults are map-based within the vault contract.
+   * The "vault address" is the vault contract principal itself.
+   */
+  async getVaultAddress(userKeyHash) {
+    if (!this.vaultContract) {
+      return null;
+    }
+    const exists = await this.vaultExists(userKeyHash);
+    if (!exists) {
+      return null;
+    }
+    return `${this.vaultContract.address}.${this.vaultContract.name}`;
+  }
+  /**
+   * Compute vault address deterministically.
+   * On Stacks, all vaults live in the same contract (map-based).
+   */
+  computeVaultAddress(_userKeyHash) {
+    if (!this.vaultContract) {
+      throw new Error("Vault contract not configured");
+    }
+    return `${this.vaultContract.address}.${this.vaultContract.name}`;
+  }
+  /**
+   * Check if a vault (identity) exists for a user.
+   * Queries the spoke contract's `identity-exists` read-only function.
+   */
+  async vaultExists(userKeyHash) {
+    if (!this.spokeContract) {
+      return false;
+    }
+    try {
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "identity-exists",
+        [`0x${userKeyHash.replace("0x", "")}`]
+      );
+      return result === true || result?.value === true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Create a vault (register identity) on Stacks.
+   * Must be done via Hub dispatch or relayer in Phase 1.
+   */
+  async createVault(userKeyHash, _signer) {
+    throw new Error(
+      `Vault creation on Stacks requires Passkey signature verification. Use createVaultViaRelayer() for sponsored identity registration, or call register-identity directly with a signed Stacks transaction. KeyHash=${userKeyHash}`
+    );
+  }
+  /**
+   * Create a vault with a sponsor wallet.
+   * On Stacks, this registers an identity via sponsored transaction.
+   */
+  async createVaultSponsored(userKeyHash, _sponsorPrivateKey, _rpcUrl) {
+    throw new Error(
+      `Sponsored vault creation on Stacks requires the user to sign with their Passkey. Use createVaultViaRelayer() which handles the sponsored transaction flow. KeyHash=${userKeyHash}`
+    );
+  }
+  /**
+   * Create a vault via the relayer (sponsored/gasless).
+   * The relayer will sponsor the register-identity transaction.
+   */
+  async createVaultViaRelayer(userKeyHash, relayerUrl) {
+    const response = await fetch(`${relayerUrl}/api/v1/stacks/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 || this.computeVaultAddress(userKeyHash),
+      transactionHash: result.transactionHash || "",
+      blockNumber: 0,
+      gasUsed: 0n,
+      alreadyExisted: result.alreadyExists || false,
+      sponsoredBy: "relayer"
+    };
+  }
+  async estimateVaultCreationGas(_userKeyHash) {
+    return 10000n;
+  }
+  getFactoryAddress() {
+    return void 0;
+  }
+  getImplementationAddress() {
+    return void 0;
+  }
+  // ========================================================================
+  // Stacks-Specific: Balance Queries
+  // ========================================================================
+  /**
+   * Get native STX balance for an address.
+   */
+  async getNativeBalance(address) {
+    try {
+      const response = await fetch(
+        `${this.rpcUrl}/v2/accounts/${address}?proof=0`
+      );
+      if (!response.ok) {
+        return 0n;
+      }
+      const data = await response.json();
+      return BigInt(data.balance || "0");
+    } catch {
+      return 0n;
+    }
+  }
+  /**
+   * Get vault STX balance for an identity.
+   * Queries the vault contract's `get-stx-balance` read-only function.
+   */
+  async getVaultStxBalance(keyHash) {
+    if (!this.vaultContract) {
+      return 0n;
+    }
+    try {
+      const result = await this.callReadOnly(
+        this.vaultContract.address,
+        this.vaultContract.name,
+        "get-stx-balance",
+        [`0x${keyHash.replace("0x", "")}`]
+      );
+      if (result && result.value !== void 0) {
+        return BigInt(result.value);
+      }
+      return 0n;
+    } catch {
+      return 0n;
+    }
+  }
+  /**
+   * Get vault sBTC balance for an identity.
+   */
+  async getVaultSbtcBalance(keyHash) {
+    if (!this.vaultContract) {
+      return 0n;
+    }
+    try {
+      const result = await this.callReadOnly(
+        this.vaultContract.address,
+        this.vaultContract.name,
+        "get-sbtc-balance",
+        [`0x${keyHash.replace("0x", "")}`]
+      );
+      if (result && result.value !== void 0) {
+        return BigInt(result.value);
+      }
+      return 0n;
+    } catch {
+      return 0n;
+    }
+  }
+  // ========================================================================
+  // Stacks-Specific: Identity & Session Queries
+  // ========================================================================
+  /**
+   * Get identity info from the spoke contract.
+   */
+  async getIdentity(keyHash) {
+    if (!this.spokeContract) {
+      return null;
+    }
+    try {
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "get-identity",
+        [`0x${keyHash.replace("0x", "")}`]
+      );
+      if (!result || result.value === void 0) {
+        return null;
+      }
+      const val = result.value;
+      return {
+        compressedPubkey: val["compressed-pubkey"]?.value || "",
+        owner: val.owner?.value || "",
+        nonce: BigInt(val.nonce?.value || 0),
+        createdAt: BigInt(val["created-at"]?.value || 0)
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get session info from the spoke contract.
+   */
+  async getSession(keyHash, sessionHash) {
+    if (!this.spokeContract) {
+      return null;
+    }
+    try {
+      const cleanKeyHash = `0x${keyHash.replace("0x", "")}`;
+      const cleanSessionHash = `0x${sessionHash.replace("0x", "")}`;
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "get-session",
+        [cleanKeyHash, cleanSessionHash]
+      );
+      if (!result || result.value === void 0) {
+        return null;
+      }
+      const val = result.value;
+      return {
+        sessionPubkey: val["session-pubkey"]?.value || "",
+        expiry: BigInt(val.expiry?.value || 0),
+        maxValue: BigInt(val["max-value"]?.value || 0),
+        spent: BigInt(val.spent?.value || 0),
+        revoked: val.revoked?.value === true,
+        createdAt: BigInt(val["created-at"]?.value || 0)
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Check if a session is currently active.
+   */
+  async checkSessionActive(keyHash, sessionHash) {
+    if (!this.spokeContract) {
+      return false;
+    }
+    try {
+      const cleanKeyHash = `0x${keyHash.replace("0x", "")}`;
+      const cleanSessionHash = `0x${sessionHash.replace("0x", "")}`;
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "is-session-active",
+        [cleanKeyHash, cleanSessionHash]
+      );
+      return result?.value === true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get remaining spending budget for a session.
+   */
+  async getRemainingBudget(keyHash, sessionHash) {
+    if (!this.spokeContract) {
+      return 0n;
+    }
+    try {
+      const cleanKeyHash = `0x${keyHash.replace("0x", "")}`;
+      const cleanSessionHash = `0x${sessionHash.replace("0x", "")}`;
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "get-remaining-budget",
+        [cleanKeyHash, cleanSessionHash]
+      );
+      if (result && result.value !== void 0) {
+        return BigInt(result.value);
+      }
+      return 0n;
+    } catch {
+      return 0n;
+    }
+  }
+  // ========================================================================
+  // Stacks-Specific: Protocol Status
+  // ========================================================================
+  /**
+   * Check if the spoke contract is paused.
+   */
+  async isProtocolPaused() {
+    if (!this.spokeContract) {
+      return false;
+    }
+    try {
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "is-paused",
+        []
+      );
+      return result === true || result?.value === true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get global identity count.
+   */
+  async getIdentityCount() {
+    if (!this.spokeContract) {
+      return 0n;
+    }
+    try {
+      const result = await this.callReadOnly(
+        this.spokeContract.address,
+        this.spokeContract.name,
+        "get-identity-count",
+        []
+      );
+      return BigInt(result?.value || result || 0);
+    } catch {
+      return 0n;
+    }
+  }
+  /**
+   * Get total STX deposited across all vaults.
+   */
+  async getTotalStxDeposited() {
+    if (!this.vaultContract) {
+      return 0n;
+    }
+    try {
+      const result = await this.callReadOnly(
+        this.vaultContract.address,
+        this.vaultContract.name,
+        "get-total-stx-deposited",
+        []
+      );
+      return BigInt(result?.value || result || 0);
+    } catch {
+      return 0n;
+    }
+  }
+  // ========================================================================
+  // Session Management (Issue #13)
+  // ========================================================================
+  /**
+   * Register a session key on the Stacks spoke.
+   * On Stacks, sessions are managed directly on the spoke contract
+   * (unlike EVM spokes where sessions are on the Hub).
+   */
+  async registerSession(_params) {
+    throw new Error(
+      "Session registration on Stacks requires a Passkey signature. Build a register-session transaction with the Passkey signature, then submit via the relayer for sponsored execution."
+    );
+  }
+  /**
+   * Revoke a session key on the Stacks spoke.
+   */
+  async revokeSession(_params) {
+    throw new Error(
+      "Session revocation on Stacks requires a Passkey signature. Build a revoke-session transaction with the Passkey signature, then submit via the relayer for sponsored execution."
+    );
+  }
+  /**
+   * Check if a session is active.
+   */
+  async isSessionActive(userKeyHash, sessionKeyHash) {
+    const active = await this.checkSessionActive(userKeyHash, sessionKeyHash);
+    const session = await this.getSession(userKeyHash, sessionKeyHash);
+    return {
+      isActive: active,
+      expiry: session ? Number(session.expiry) : 0,
+      maxValue: session?.maxValue ?? 0n,
+      chainScopes: [this.config.wormholeChainId]
+    };
+  }
+  /**
+   * Get all sessions for a user.
+   * Note: Clarity maps don't support enumeration, so this requires
+   * off-chain indexing or event log parsing.
+   */
+  async getUserSessions(_userKeyHash) {
+    throw new Error(
+      'Enumerating all sessions is not supported on Stacks (Clarity maps are not iterable). Use checkSessionActive() with a known session hash, or query the Stacks event log for "session-registered" print events via the Hiro API.'
+    );
+  }
+  // ========================================================================
+  // Stacks-Specific: Transaction Status
+  // ========================================================================
+  /**
+   * Get the status of a Stacks transaction.
+   */
+  async getTransactionStatus(txId) {
+    try {
+      const cleanTxId = txId.startsWith("0x") ? txId : `0x${txId}`;
+      const response = await fetch(
+        `${this.rpcUrl}/extended/v1/tx/${cleanTxId}`
+      );
+      if (!response.ok) {
+        return { status: "not_found" };
+      }
+      const data = await response.json();
+      const txStatus = data.tx_status;
+      if (txStatus === "success") {
+        return {
+          status: "success",
+          blockHeight: data.block_height
+        };
+      }
+      if (txStatus === "pending") {
+        return { status: "pending" };
+      }
+      if (txStatus === "abort_by_response" || txStatus === "abort_by_post_condition") {
+        return {
+          status: "failed",
+          error: `Transaction aborted: ${txStatus}`
+        };
+      }
+      return { status: "pending" };
+    } catch {
+      return { status: "not_found" };
+    }
+  }
+  /**
+   * Wait for a transaction to be confirmed.
+   *
+   * @param txId - Transaction ID
+   * @param maxAttempts - Maximum polling attempts (default: 60)
+   * @param pollIntervalMs - Polling interval in milliseconds (default: 5000)
+   */
+  async waitForConfirmation(txId, maxAttempts = 60, pollIntervalMs = 5e3) {
+    for (let i = 0; i < maxAttempts; i++) {
+      const status = await this.getTransactionStatus(txId);
+      if (status.status === "success") {
+        return { confirmed: true, blockHeight: status.blockHeight };
+      }
+      if (status.status === "failed") {
+        throw new Error(`Transaction failed: ${status.error}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    return { confirmed: false };
+  }
+  // ========================================================================
+  // Stacks-Specific: Network Info
+  // ========================================================================
+  /**
+   * Get Stacks network info (block height, network version, etc.).
+   */
+  async getNetworkInfo() {
+    const response = await fetch(`${this.rpcUrl}/v2/info`);
+    if (!response.ok) {
+      throw new Error(`Failed to get Stacks network info: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return {
+      networkId: data.network_id,
+      stacksBlockHeight: data.stacks_tip_height,
+      burnBlockHeight: data.burn_block_height,
+      serverVersion: data.server_version
+    };
+  }
+  /**
+   * Get the current Stacks block height.
+   * Used for session expiry calculations.
+   */
+  async getCurrentBlockHeight() {
+    const info = await this.getNetworkInfo();
+    return info.stacksBlockHeight;
+  }
+  // ========================================================================
+  // Internal: Read-Only Contract Calls via Hiro API
+  // ========================================================================
+  /**
+   * Call a read-only Clarity function via the Hiro API.
+   * Uses the /v2/contracts/call-read endpoint.
+   */
+  async callReadOnly(contractAddress, contractName, functionName, args) {
+    const url = `${this.rpcUrl}/v2/contracts/call-read/${contractAddress}/${contractName}/${functionName}`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        sender: contractAddress,
+        arguments: args
+      })
+    });
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      throw new Error(
+        `Read-only call failed: ${contractAddress}.${contractName}::${functionName} - ${response.status}: ${errorText}`
+      );
+    }
+    const data = await response.json();
+    if (!data.okay) {
+      throw new Error(
+        `Read-only call returned error: ${contractAddress}.${contractName}::${functionName} - ${data.cause || "Unknown cause"}`
+      );
+    }
+    return this.parseClarityValue(data.result);
+  }
+  /**
+   * Parse a hex-encoded Clarity value from the API response.
+   * This is a simplified parser for common Clarity types.
+   */
+  parseClarityValue(hex) {
+    if (!hex || hex === "0x") {
+      return null;
+    }
+    const bytes = hexToBytes(hex);
+    if (bytes.length === 0) {
+      return null;
+    }
+    const typeId = bytes[0];
+    switch (typeId) {
+      // int (0x00)
+      case 0: {
+        let value = 0n;
+        for (let i = 1; i < 17 && i < bytes.length; i++) {
+          value = value << 8n | BigInt(bytes[i]);
+        }
+        return { value };
+      }
+      // uint (0x01)
+      case 1: {
+        let value = 0n;
+        for (let i = 1; i < 17 && i < bytes.length; i++) {
+          value = value << 8n | BigInt(bytes[i]);
+        }
+        return { value };
+      }
+      // buffer (0x02)
+      case 2: {
+        const len = bytes[1] << 24 | bytes[2] << 16 | bytes[3] << 8 | bytes[4];
+        const bufValue = bytes.slice(5, 5 + len);
+        return { value: "0x" + bytesToHex(bufValue) };
+      }
+      // bool true (0x03)
+      case 3:
+        return true;
+      // bool false (0x04)
+      case 4:
+        return false;
+      // optional none (0x09)
+      case 9:
+        return null;
+      // optional some (0x0a)
+      case 10:
+        return this.parseClarityValue("0x" + bytesToHex(bytes.slice(1)));
+      // response ok (0x07)
+      case 7:
+        return this.parseClarityValue("0x" + bytesToHex(bytes.slice(1)));
+      // response err (0x08)
+      case 8: {
+        const errVal = this.parseClarityValue("0x" + bytesToHex(bytes.slice(1)));
+        throw new Error(`Clarity error: ${JSON.stringify(errVal)}`);
+      }
+      // tuple (0x0c)
+      case 12: {
+        return { value: hex };
+      }
+      default:
+        return { value: hex };
+    }
+  }
+};
+
+// src/presets.ts
+var CHAIN_NAMES = {
+  // EVM L2s (Hub-capable)
+  BASE: "base",
+  OPTIMISM: "optimism",
+  ARBITRUM: "arbitrum",
+  SCROLL: "scroll",
+  BLAST: "blast",
+  MANTLE: "mantle",
+  // EVM L1s
+  ETHEREUM: "ethereum",
+  POLYGON: "polygon",
+  BSC: "bsc",
+  AVALANCHE: "avalanche",
+  FANTOM: "fantom",
+  CELO: "celo",
+  MOONBEAM: "moonbeam",
+  // Non-EVM
+  SOLANA: "solana",
+  APTOS: "aptos",
+  SUI: "sui",
+  STARKNET: "starknet",
+  STACKS: "stacks",
+  NEAR: "near",
+  SEI: "sei"
+};
+var CHAIN_PRESETS = {
+  // ────────────────────────────────────────────────────────────────────────
+  // BASE - Primary Hub Chain
+  // ────────────────────────────────────────────────────────────────────────
+  base: {
+    displayName: "Base",
+    type: "evm",
+    canBeHub: true,
+    testnet: {
+      name: "Base Sepolia",
+      chainId: 84532,
+      wormholeChainId: 10004,
+      rpcUrl: "https://sepolia.base.org",
+      explorerUrl: "https://sepolia.basescan.org",
+      isEvm: true,
+      contracts: {
+        hub: "0x66D87dE68327f48A099c5B9bE97020Feab9a7c82",
+        vaultFactory: "0xCFaEb5652aa2Ee60b2229dC8895B4159749C7e53",
+        vaultImplementation: "0x0d13367C16c6f0B24eD275CC67C7D9f42878285c",
+        wormholeCoreBridge: "0x79A1027a6A159502049F10906D333EC57E95F083",
+        tokenBridge: "0x86F55A04690fd7815A3D802bD587e83eA888B239"
+      }
+    },
+    mainnet: {
+      name: "Base",
+      chainId: 8453,
+      wormholeChainId: 30,
+      rpcUrl: "https://mainnet.base.org",
+      explorerUrl: "https://basescan.org",
+      isEvm: true,
+      contracts: {
+        // TODO: Deploy mainnet contracts
+        wormholeCoreBridge: "0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6",
+        tokenBridge: "0x8d2de8d2f73F1F4cAB472AC9A881C9b123C79627"
+      }
+    }
+  },
+  // ────────────────────────────────────────────────────────────────────────
+  // OPTIMISM - Secondary Hub / Spoke
+  // ────────────────────────────────────────────────────────────────────────
+  optimism: {
+    displayName: "Optimism",
+    type: "evm",
+    canBeHub: true,
+    testnet: {
+      name: "Optimism Sepolia",
+      chainId: 11155420,
+      wormholeChainId: 10005,
+      rpcUrl: "https://sepolia.optimism.io",
+      explorerUrl: "https://sepolia-optimism.etherscan.io",
+      isEvm: true,
+      contracts: {
+        vaultFactory: "0xA5653d54079ABeCe780F8d9597B2bc4B09fe464A",
+        vaultImplementation: "0x8099b1406485d2255ff89Ce5Ea18520802AFC150",
+        wormholeCoreBridge: "0x31377888146f3253211EFEf5c676D41ECe7D58Fe",
+        tokenBridge: "0x99737Ec4B815d816c49A385943baf0380e75c0Ac"
+      }
+    },
+    mainnet: {
+      name: "Optimism",
+      chainId: 10,
+      wormholeChainId: 24,
+      rpcUrl: "https://mainnet.optimism.io",
+      explorerUrl: "https://optimistic.etherscan.io",
+      isEvm: true,
+      contracts: {
+        wormholeCoreBridge: "0xEe91C335eab126dF5fDB3797EA9d6aD93aeC9722",
+        tokenBridge: "0x1D68124e65faFC907325e3EDbF8c4d84499DAa8b"
+      }
+    }
+  },
+  // ────────────────────────────────────────────────────────────────────────
+  // ARBITRUM
+  // ────────────────────────────────────────────────────────────────────────
+  arbitrum: {
+    displayName: "Arbitrum",
+    type: "evm",
+    canBeHub: true,
+    testnet: {
+      name: "Arbitrum Sepolia",
+      chainId: 421614,
+      wormholeChainId: 10003,
+      rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc",
+      explorerUrl: "https://sepolia.arbiscan.io",
+      isEvm: true,
+      contracts: {
+        vaultFactory: "0xd36D3D5DB59d78f1E33813490F72DABC15C9B07c",
+        vaultImplementation: "0xB10ACf39eBF17fc33F722cBD955b7aeCB0611bc4",
+        wormholeCoreBridge: "0x6b9C8671cdDC8dEab9c719bB87cBd3e782bA6a35",
+        tokenBridge: "0xC7A204bDBFe983FCD8d8E61D02b475D4073fF97e"
+      }
+    },
+    mainnet: {
+      name: "Arbitrum",
+      chainId: 42161,
+      wormholeChainId: 23,
+      rpcUrl: "https://arb1.arbitrum.io/rpc",
+      explorerUrl: "https://arbiscan.io",
+      isEvm: true,
+      contracts: {
+        wormholeCoreBridge: "0xa5f208e072434bC67592E4C49C1B991BA79BCA46",
+        tokenBridge: "0x0b2402144Bb366A632D14B83F244D2e0e21bD39c"
+      }
+    }
+  },
+  // ────────────────────────────────────────────────────────────────────────
+  // ETHEREUM
+  // ────────────────────────────────────────────────────────────────────────
+  ethereum: {
+    displayName: "Ethereum",
+    type: "evm",
+    canBeHub: false,
+    testnet: {
+      name: "Sepolia",
+      chainId: 11155111,
+      wormholeChainId: 10002,
+      rpcUrl: "https://ethereum-sepolia-rpc.publicnode.com",
+      explorerUrl: "https://sepolia.etherscan.io",
+      isEvm: true,
+      contracts: {
+        vaultFactory: "0x07F608AFf6d63b68029488b726d895c4Bb593038",
+        vaultImplementation: "0xD66153fccFB6731fB6c4944FbD607ba86A76a1f6",
+        wormholeCoreBridge: "0x4a8bc80Ed5a4067f1CCf107057b8270E0cC11A78",
+        tokenBridge: "0xDB5492265f6038831E89f495670FF909aDe94bd9"
+      }
+    },
+    mainnet: {
+      name: "Ethereum",
+      chainId: 1,
+      wormholeChainId: 2,
       rpcUrl: "https://eth.llamarpc.com",
       explorerUrl: "https://etherscan.io",
       isEvm: true,
@@ -11671,6 +12661,49 @@ var CHAIN_PRESETS = {
     }
   },
   // ────────────────────────────────────────────────────────────────────────
+  // STACKS
+  // ────────────────────────────────────────────────────────────────────────
+  stacks: {
+    displayName: "Stacks",
+    type: "stacks",
+    canBeHub: false,
+    testnet: {
+      name: "Stacks Testnet",
+      chainId: 2147483648,
+      // CAIP-2: stacks:2147483648
+      wormholeChainId: 60,
+      // Official Wormhole chain ID for Stacks
+      rpcUrl: "https://api.testnet.hiro.so",
+      explorerUrl: "https://explorer.hiro.so/?chain=testnet",
+      isEvm: false,
+      contracts: {
+        // Spoke contract: identity + session management
+        hub: "ST1CKNN84MDPCJRQDHDCY34GMRKQ3TASNNDJQDRTN.veridex-spoke",
+        // Vault contract: STX/sBTC custody
+        vaultFactory: "ST1CKNN84MDPCJRQDHDCY34GMRKQ3TASNNDJQDRTN.veridex-vault",
+        wormholeCoreBridge: "",
+        // Phase 2: Wormhole integration contracts
+        wormholeVerifier: "ST1CKNN84MDPCJRQDHDCY34GMRKQ3TASNNDJQDRTN.veridex-wormhole-verifier",
+        vaultVaa: "ST1CKNN84MDPCJRQDHDCY34GMRKQ3TASNNDJQDRTN.veridex-vault-vaa"
+      },
+      hubChainId: 10004
+      // Base Sepolia
+    },
+    mainnet: {
+      name: "Stacks",
+      chainId: 1,
+      // CAIP-2: stacks:1
+      wormholeChainId: 60,
+      rpcUrl: "https://api.hiro.so",
+      explorerUrl: "https://explorer.hiro.so",
+      isEvm: false,
+      contracts: {
+        // TODO: Deploy mainnet contracts
+        wormholeCoreBridge: ""
+      }
+    }
+  },
+  // ────────────────────────────────────────────────────────────────────────
   // NEAR
   // ────────────────────────────────────────────────────────────────────────
   near: {
@@ -11793,6 +12826,13 @@ function createChainClient(chain, network, customRpcUrl) {
         wormholeChainId: config.wormholeChainId,
         network: network === "testnet" ? "sepolia" : "mainnet"
       });
+    case "stacks":
+      return new StacksClient({
+        rpcUrl,
+        spokeContractAddress: config.contracts.hub || void 0,
+        wormholeChainId: config.wormholeChainId,
+        network
+      });
     case "near":
     case "cosmos":
       throw new Error(`Chain type "${preset.type}" is not yet supported. Coming soon!`);
@@ -11848,8 +12888,8 @@ function createSessionSDK(chain = "base", config = {}) {
 }
 
 // src/core/CrossOriginAuth.ts
-var VERIDEX_RP_ID = "veridex.network";
 var DEFAULT_AUTH_PORTAL_URL = "https://auth.veridex.network";
+var DEFAULT_RELAYER_URL = "https://amused-kameko-veridex-demo-37453117.koyeb.app/api/v1";
 var AUTH_MESSAGE_TYPES = {
   AUTH_REQUEST: "VERIDEX_AUTH_REQUEST",
   AUTH_RESPONSE: "VERIDEX_AUTH_RESPONSE",
@@ -11862,6 +12902,7 @@ var CrossOriginAuth = class {
     this.config = {
       rpId: config.rpId ?? VERIDEX_RP_ID,
       authPortalUrl: config.authPortalUrl ?? DEFAULT_AUTH_PORTAL_URL,
+      relayerUrl: config.relayerUrl ?? DEFAULT_RELAYER_URL,
       mode: config.mode ?? "popup",
       popupFeatures: config.popupFeatures ?? "width=500,height=600,left=100,top=100",
       timeout: config.timeout ?? 12e4,
@@ -12049,6 +13090,84 @@ var CrossOriginAuth = class {
   getAuthPortalUrl() {
     return this.config.authPortalUrl;
   }
+  // ========================================================================
+  // Server-Side Session Tokens (ADR-0018)
+  // ========================================================================
+  /**
+   * Create a server-validated session token via the relayer.
+   * Call this after authenticating (via ROR or auth portal) to get a
+   * server-side session that the relayer can verify on subsequent requests.
+   */
+  async createServerSession(session, options) {
+    const keyHash = session.credential?.keyHash;
+    if (!keyHash) {
+      throw new Error("Session must include credential with keyHash");
+    }
+    const response = await fetch(`${this.config.relayerUrl}/session/create`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        keyHash,
+        appOrigin: typeof window !== "undefined" ? window.location.origin : "",
+        sessionPublicKey: session.sessionPublicKey || "",
+        permissions: options?.permissions ?? ["read", "transfer"],
+        expiresInMs: options?.expiresInMs ?? 36e5,
+        signature: session.signature
+      })
+    });
+    if (!response.ok) {
+      const data2 = await response.json().catch(() => ({ error: "Unknown error" }));
+      throw new Error(data2.error || `Failed to create server session: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.session;
+  }
+  /**
+   * Validate an existing server session token.
+   * Returns the session details if valid, null if expired/revoked.
+   */
+  async validateServerSession(sessionId) {
+    const response = await fetch(`${this.config.relayerUrl}/session/${encodeURIComponent(sessionId)}`);
+    if (!response.ok) {
+      return null;
+    }
+    const data = await response.json();
+    if (!data.valid) {
+      return null;
+    }
+    return data.session;
+  }
+  /**
+   * Revoke a server session token.
+   */
+  async revokeServerSession(sessionId) {
+    const response = await fetch(`${this.config.relayerUrl}/session/${encodeURIComponent(sessionId)}`, {
+      method: "DELETE"
+    });
+    return response.ok;
+  }
+  /**
+   * Full authentication flow: authenticate + create server session.
+   * Automatically detects ROR support and falls back to auth portal.
+   */
+  async authenticateAndCreateSession(options) {
+    let session;
+    if (await this.supportsRelatedOrigins()) {
+      const result = await this.authenticate();
+      session = {
+        address: "",
+        sessionPublicKey: "",
+        expiresAt: Date.now() + (options?.expiresInMs ?? 36e5),
+        signature: result.signature,
+        credential: result.credential
+      };
+    } else {
+      session = await this.connectWithVeridex();
+    }
+    const serverSession = await this.createServerSession(session, options);
+    session.serverSessionId = serverSession.id;
+    return { session, serverSession };
+  }
 };
 function createCrossOriginAuth(config) {
   return new CrossOriginAuth(config);
@@ -13102,6 +14221,72 @@ var EVMHubClientAdapter = class {
   }
 };
 
+// src/chains/stacks/StacksPostConditions.ts
+function buildStxWithdrawalPostConditions(contractPrincipal, amount) {
+  return [
+    {
+      type: "stx",
+      principal: contractPrincipal,
+      comparison: "eq",
+      amount
+    }
+  ];
+}
+function buildStxDepositPostConditions(senderPrincipal, amount) {
+  return [
+    {
+      type: "stx",
+      principal: senderPrincipal,
+      comparison: "eq",
+      amount
+    }
+  ];
+}
+function buildSbtcWithdrawalPostConditions(contractPrincipal, amount, sbtcContractAddress = "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4", sbtcContractName = "sbtc-token") {
+  return [
+    {
+      type: "ft",
+      principal: contractPrincipal,
+      comparison: "eq",
+      amount,
+      contractAddress: sbtcContractAddress,
+      contractName: sbtcContractName,
+      tokenName: "sbtc-token"
+    }
+  ];
+}
+function buildExecutePostConditions(actionType, contractPrincipal, amount) {
+  switch (actionType) {
+    case 1:
+      return buildStxWithdrawalPostConditions(contractPrincipal, amount);
+    case 2:
+      return buildSbtcWithdrawalPostConditions(contractPrincipal, amount);
+    default:
+      return [];
+  }
+}
+function validatePostConditions(postConditions, expectedAmount) {
+  if (postConditions.length === 0) {
+    return {
+      valid: false,
+      error: "No post-conditions attached. Asset transfers require post-conditions for safety."
+    };
+  }
+  const hasMatchingAmount = postConditions.some((pc) => {
+    if (pc.type === "stx" || pc.type === "ft") {
+      return pc.amount === expectedAmount && pc.comparison === "eq";
+    }
+    return false;
+  });
+  if (!hasMatchingAmount) {
+    return {
+      valid: false,
+      error: `No post-condition matches expected amount ${expectedAmount}. Ensure exact-match post-conditions are attached.`
+    };
+  }
+  return { valid: true };
+}
+
 // src/constants/errors.ts
 var ERROR_RANGES = {
   /** Core protocol errors (paused, unauthorized, limits, etc.) */
@@ -13352,6 +14537,7 @@ export {
   ACTION_TYPES,
   ARBITRUM_SEPOLIA_TOKENS,
   AUTH_MESSAGE_TYPES,
+  AptosClient,
   BASE_SEPOLIA_TOKENS,
   BalanceManager,
   CHAIN_DISPLAY_INFO,
@@ -13364,10 +14550,12 @@ export {
   CrossOriginAuth,
   DEFAULT_AUTH_PORTAL_URL,
   DEFAULT_REFRESH_BUFFER,
+  DEFAULT_RELAYER_URL,
   DEFAULT_SESSION_DURATION,
   ERROR_MESSAGES,
   ERROR_RANGES,
   ETHEREUM_SEPOLIA_TOKENS,
+  EVMClient,
   EVMHubClientAdapter,
   EVM_ZERO_ADDRESS,
   GUARDIAN_CONFIG,
@@ -13386,9 +14574,14 @@ export {
   QueryHubStateError,
   QueryPortfolioError,
   RelayerClient,
+  STACKS_ACTION_TYPES,
   SessionError,
   SessionManager,
+  SolanaClient,
   SpendingLimitsManager,
+  StacksClient,
+  StarknetClient,
+  SuiClient,
   TESTNET_CHAINS,
   TOKEN_REGISTRY,
   TransactionParser,
@@ -13410,6 +14603,10 @@ export {
   base64URLEncode,
   buildChallenge,
   buildGaslessChallenge,
+  buildSbtcWithdrawalPostConditions,
+  buildExecutePostConditions as buildStacksExecutePostConditions,
+  buildStxDepositPostConditions,
+  buildStxWithdrawalPostConditions,
   calculatePercentage,
   computeKeyHash,
   computeSessionKeyHash,
@@ -13475,6 +14672,10 @@ export {
   getExplorerUrl,
   getHubChains,
   getSequenceFromTxReceipt,
+  getContractPrincipal as getStacksContractPrincipal,
+  getStacksExplorerAddressUrl,
+  getStacksExplorerTxUrl,
+  getNetworkFromAddress as getStacksNetworkFromAddress,
   getSuggestedAction,
   getSupportedChainIds,
   getSupportedChains,
@@ -13496,14 +14697,19 @@ export {
   isQueryExecutionError,
   isQueryParsingError,
   isRetryableError,
+  isContractPrincipal as isStacksContractPrincipal,
   isValidBytes32,
   isValidEvmAddress,
+  isValidContractName as isValidStacksContractName,
+  isValidStacksPrincipal,
+  isValidStandardPrincipal as isValidStacksStandardPrincipal,
   isValidWormholeChainId,
   logTransactionSummary,
   normalizeEmitterAddress,
   padTo32Bytes,
   parseAmount,
   parseDERSignature,
+  parseContractPrincipal as parseStacksContractPrincipal,
   parseVAA,
   parseVAABytes,
   parseVeridexError,
@@ -13515,10 +14721,22 @@ export {
   sendAuthResponse,
   signWithSessionKey,
   solanaAddressToBytes32,
+  buildExecuteHash as stacksBuildExecuteHash,
+  buildRegistrationHash as stacksBuildRegistrationHash,
+  buildRevocationHash as stacksBuildRevocationHash,
+  buildSessionRegistrationHash as stacksBuildSessionRegistrationHash,
+  buildWithdrawalHash as stacksBuildWithdrawalHash,
+  compressPublicKey as stacksCompressPublicKey,
+  computeKeyHash2 as stacksComputeKeyHash,
+  computeKeyHashFromCoords as stacksComputeKeyHashFromCoords,
+  derToCompactSignature as stacksDerToCompactSignature,
+  rsToCompactSignature as stacksRsToCompactSignature,
+  supportsRelatedOrigins,
   supportsRelayer,
   trimTo20Bytes,
   validateEmitter,
   validateSessionConfig,
+  validatePostConditions as validateStacksPostConditions,
   verifySessionSignature,
   waitForGuardianSignatures
 };