@gvnrdao/dh-lit-actions 0.0.14 → 0.0.15

package/out/ucd-mint-validator.js

@@ -0,0 +1,2153 @@
+(() => {
+  // src/constants/chunks/liquidation.ts
+  var ACTIVE_LOAN_LIQUIDATION_THRESHOLD_BPS = 13e3;
+  var EXPIRED_LOAN_MIN_LIQUIDATION_THRESHOLD_BPS = 11e3;
+  var EXPIRED_LOAN_MAX_LIQUIDATION_THRESHOLD_BPS = 2e4;
+  var GRACE_PERIOD_DAYS = 30;
+
+  // src/constants/chunks/decimals.ts
+  var SATOSHIS_PER_BITCOIN = 100000000n;
+  var PRICE_ORACLE_DECIMALS = 100000000n;
+  var UCD_TOKEN_DECIMALS = 1000000000000000000n;
+
+  // src/constants/chunks/price-oracle.ts
+  var PRICE_ORACLE_OUTLIER_DEVIATION_THRESHOLD = 0.02;
+  var PRICE_ORACLE_DISPERSION_THRESHOLD = 0.05;
+
+  // src/constants/chunks/bitcoin.ts
+  var BITCOIN_DEFAULT_MIN_CONFIRMATIONS = 6;
+
+  // src/constants/chunks/quantum-time.ts
+  var QUANTUM_WINDOW_SECONDS = 100;
+  var DEAD_ZONE_SECONDS = 16;
+  var SAFE_EXECUTION_WINDOW_SECONDS = QUANTUM_WINDOW_SECONDS - DEAD_ZONE_SECONDS;
+
+  // deployments/deployment.sepolia.json
+  var deployment_sepolia_default = {
+    network: "sepolia",
+    chainId: 11155111,
+    timestamp: "2025-10-24T23:22:01.396Z",
+    deployer: "0x2767441E044aCd9bbC21a759fB0517494875092d",
+    contracts: {
+      UpgradeValidator: "0x4246830c4bF03a6f4460ecEB9e6470562a5Cd0bB",
+      UCDToken: "0x86060Fa5B3E01E003b8aFd9C1295F1F444a7dC60",
+      UCDController: "0xEE24c338e394610b503768Ba7D8A8c26efdD3Aeb",
+      PriceFeedConsumer: "0xA285198196B8f4f658DC81bf4e99A5DC6c191694",
+      BTCProofValidator: "0x79469590b41AF8b21276914da7f18FF136B59afB",
+      UCDMintingRewards: "0x914740bA9b454d1B3C116A9F55C0929487b7E052",
+      PositionManagerCoreModule: "0x0f7E84538026Efdd118168b27f6da00035c75697",
+      TermManagerModule: "0x73f0e9151bbEa3cB8b21628E2aAd54C3f6b3968A",
+      LoanOperationsManagerModule: "0x71128A4e728ca4B6976E05aC77E50Ad7fe98Ae37",
+      CollateralManagerModule: "0xAb9205f4b559F945Ae45c0857fc5c30d699509E1",
+      LiquidationManagerModule: "0xe5A72334ED5e0F962be02229b36685d5Bb331cCF",
+      CircuitBreakerModule: "0x55eE4Bb05008b73AebcAfa5FbC745348E645d8c6",
+      CommunityManagerModule: "0x4E4481B0B3B08804C1d32A19Af66130426D82e89",
+      AdminModule: "0xF96F14605f870A0cC2589A5d2b1D77E379762Af2",
+      PositionManagerViews: "0x7bc05DBC27BBdab374E3FEBB4Efaa6CDE082fc27",
+      PositionManager: "0xAC8d7b714865D4F304b80cd037b517796D56E4Ce",
+      MockUSDC: "0x43670cD40c3c4a7acBA5B06B84b8Dd97D7E08f82",
+      MockUSDT: "0xF8b7fB38b17a310960E47805Be9adba0b0e0394D",
+      SimplePSMV2: "0x8C2D7C833b40eD23Bf1EABAf8B9105C80FD686A2",
+      OperationAuthorizationRegistry: "0x400B85A6A901fdbF08f048cD5f3e37B8DD6c0D66"
+    },
+    upgraded: {
+      LoanOperationsManagerModule: {
+        previousImplementation: "0xFa3E83992d964E46d82Bb1F92844a8aC909130B2",
+        newImplementation: "0xFa3E83992d964E46d82Bb1F92844a8aC909130B2",
+        upgradedAt: "2025-10-24T23:22:01.396Z",
+        upgradedBy: "0x2767441E044aCd9bbC21a759fB0517494875092d"
+      }
+    }
+  };
+
+  // deployments/deployment.localhost.json
+  var deployment_localhost_default = {
+    network: "localhost",
+    chainId: 1337,
+    timestamp: "2025-10-19T17:53:35.461Z",
+    deployer: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
+    contracts: {
+      UpgradeValidator: "0xa513E6E4b8f2a923D98304ec87F64353C4D5C853",
+      UCDToken: "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
+      UCDController: "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
+      PriceFeedConsumer: "0x8A791620dd6260079BF849Dc5567aDC3F2FdC318",
+      BTCProofValidator: "0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e",
+      UCDMintingRewards: "0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82",
+      PositionManagerCoreModule: "0x0B306BF915C4d645ff596e518fAf3F9669b97016",
+      TermManagerModule: "0x9A9f2CCfdE556A7E9Ff0848998Aa4a0CFD8863AE",
+      LoanOperationsManagerModule: "0x3Aa5ebB10DC797CAC828524e59A333d0A371443c",
+      CollateralManagerModule: "0x59b670e9fA9D0A427751Af201D676719a970857b",
+      LiquidationManagerModule: "0x322813Fd9A801c5507c9de605d63CEA4f2CE6c44",
+      CircuitBreakerModule: "0x4A679253410272dd5232B3Ff7cF5dbB88f295319",
+      CommunityManagerModule: "0x09635F643e140090A9A8Dcd712eD6285858ceBef",
+      AdminModule: "0x67d269191c92Caf3cD7723F116c85e6E9bf55933",
+      PositionManagerViews: "0xE6E340D132b5f46d1e472DebcD681B2aBc16e57E",
+      PositionManager: "0x84eA74d481Ee0A5332c457a4d796187F6Ba67fEB"
+    }
+  };
+
+  // src/config/network-config.ts
+  var NETWORK_DEPLOYMENTS = {
+    sepolia: deployment_sepolia_default,
+    localhost: deployment_localhost_default
+  };
+  function getNetworkConfig(network) {
+    const normalizedNetwork = network.toLowerCase();
+    if (!NETWORK_DEPLOYMENTS[normalizedNetwork]) {
+      console.warn(
+        `Warning: Network "${network}" not found, defaulting to sepolia`
+      );
+      return NETWORK_DEPLOYMENTS.sepolia;
+    }
+    return NETWORK_DEPLOYMENTS[normalizedNetwork];
+  }
+
+  // src/constants/chunks/loan-status.ts
+  function loanStatusToString(status) {
+    switch (status) {
+      case 0 /* PENDING_DEPOSIT */:
+        return "PENDING_DEPOSIT";
+      case 1 /* PENDING_MINT */:
+        return "PENDING_MINT";
+      case 2 /* ACTIVE */:
+        return "ACTIVE";
+      case 3 /* EXPIRED */:
+        return "EXPIRED";
+      case 4 /* LIQUIDATABLE */:
+        return "LIQUIDATABLE";
+      case 5 /* LIQUIDATED */:
+        return "LIQUIDATED";
+      case 6 /* REPAID */:
+        return "REPAID";
+      case 7 /* CLOSED */:
+        return "CLOSED";
+      default:
+        return `UNKNOWN(${status})`;
+    }
+  }
+  function getValidMintingStatuses() {
+    return [
+      0 /* PENDING_DEPOSIT */,
+      1 /* PENDING_MINT */,
+      2 /* ACTIVE */
+    ];
+  }
+
+  // src/constants/chunks/bitcoin-network-config.ts
+  var EVMChain = /* @__PURE__ */ ((EVMChain2) => {
+    EVMChain2["SEPOLIA"] = "sepolia";
+    EVMChain2["ETHEREUM"] = "ethereum";
+    return EVMChain2;
+  })(EVMChain || {});
+  var CHAIN_TO_BITCOIN_NETWORK = {
+    ["sepolia" /* SEPOLIA */]: "testnet" /* TESTNET */,
+    ["ethereum" /* ETHEREUM */]: "mainnet" /* MAINNET */
+  };
+  var APPROVED_BITCOIN_PROVIDERS = {
+    ["testnet" /* TESTNET */]: [
+      {
+        url: "https://diamond-hands-btc-faucet-6b39a1072059.herokuapp.com/api",
+        network: "testnet" /* TESTNET */,
+        minConfirmations: 1,
+        name: "Diamond Hands Faucet"
+      }
+    ],
+    ["mainnet" /* MAINNET */]: [
+      {
+        url: "https://blockstream.info/api",
+        network: "mainnet" /* MAINNET */,
+        minConfirmations: 6,
+        name: "Blockstream Mainnet"
+      },
+      {
+        url: "https://mempool.space/api",
+        network: "mainnet" /* MAINNET */,
+        minConfirmations: 6,
+        name: "Mempool.space Mainnet"
+      }
+    ]
+  };
+  function validateChain(chain) {
+    const normalized = chain.toLowerCase().trim();
+    if (normalized === "sepolia") {
+      return "sepolia" /* SEPOLIA */;
+    }
+    if (normalized === "ethereum" || normalized === "mainnet") {
+      return "ethereum" /* ETHEREUM */;
+    }
+    throw new Error(
+      `Unsupported EVM chain: "${chain}". Supported chains: ${Object.values(EVMChain).join(", ")}`
+    );
+  }
+  function getBitcoinNetworkForChain(chain) {
+    return CHAIN_TO_BITCOIN_NETWORK[chain];
+  }
+  function validateBitcoinProvider(providerUrl, bitcoinNetwork) {
+    const providers = APPROVED_BITCOIN_PROVIDERS[bitcoinNetwork];
+    const config = providers.find((p) => p.url === providerUrl);
+    if (!config) {
+      const approvedUrls = providers.map((p) => `${p.name} (${p.url})`).join(", ");
+      throw new Error(
+        `Bitcoin provider not approved for ${bitcoinNetwork}. Provided URL: ${providerUrl}. Approved providers: ${approvedUrls}`
+      );
+    }
+    return config;
+  }
+  function getBitcoinProviderConfig(chain, providerUrl) {
+    const validatedChain = validateChain(chain);
+    const bitcoinNetwork = getBitcoinNetworkForChain(validatedChain);
+    const providerConfig = validateBitcoinProvider(providerUrl, bitcoinNetwork);
+    if (providerConfig.network !== bitcoinNetwork) {
+      throw new Error(
+        `Bitcoin provider network mismatch. Provider ${providerConfig.name} is for ${providerConfig.network}, but chain ${chain} requires ${bitcoinNetwork}`
+      );
+    }
+    return providerConfig;
+  }
+
+  // src/modules/quantum-time.module.ts
+  function getQuantumStart(timestamp) {
+    return Math.floor(timestamp / QUANTUM_WINDOW_SECONDS) * QUANTUM_WINDOW_SECONDS;
+  }
+  function getCurrentQuantumTimestamp() {
+    const now = Math.floor(Date.now() / 1e3);
+    return getQuantumStart(now);
+  }
+  function isInDeadZone(now) {
+    const currentTime = now ?? Math.floor(Date.now() / 1e3);
+    const timeInQuantum = currentTime % QUANTUM_WINDOW_SECONDS;
+    return timeInQuantum >= 92 || timeInQuantum < 8;
+  }
+  async function waitForSafeQuantumMoment() {
+    const now = Math.floor(Date.now() / 1e3);
+    const timeInQuantum = now % QUANTUM_WINDOW_SECONDS;
+    if (!isInDeadZone(now)) {
+      return;
+    }
+    let waitSeconds;
+    if (timeInQuantum >= 92) {
+      waitSeconds = 100 - timeInQuantum + 8;
+    } else {
+      waitSeconds = 8 - timeInQuantum;
+    }
+    console.log(
+      `[Quantum] Waiting ${waitSeconds}s for safe moment (current time in quantum: ${timeInQuantum}s)`
+    );
+    await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1e3));
+    console.log(`[Quantum] Safe quantum ready: ${getCurrentQuantumTimestamp()}`);
+  }
+  function validateQuantumTimestamp(timestampOnSignature, now) {
+    const currentTime = now ?? Math.floor(Date.now() / 1e3);
+    const currentQuantum = getQuantumStart(currentTime);
+    const signatureQuantum = getQuantumStart(timestampOnSignature);
+    if (signatureQuantum !== currentQuantum) {
+      throw new Error(
+        `[Quantum] Invalid timestamp: signature from quantum ${signatureQuantum}, current quantum is ${currentQuantum}`
+      );
+    }
+  }
+
+  // src/modules/authorization.module.ts
+  var AuthorizationModule = class {
+    /**
+     * Verify owner signature for position action
+     *
+     * Validates that:
+     * 1. Waits for safe quantum moment (if in dead zone)
+     * 2. Timestamp is within valid quantum window
+     * 3. Message includes: LIT action name, caller address, position, timestamp, params
+     * 4. Recovered signer matches claimed caller address
+     * 5. Caller address matches expected owner
+     *
+     * @param litActionName - Name of the LIT action (e.g., "ucd-mint-validator")
+     * @param auth - Authorization parameters
+     * @param expectedOwner - Expected owner address from contract
+     * @param actionParams - Action-specific parameters to include in message
+     * @returns True if authorized
+     */
+    static async verifyOwnerSignature(litActionName, auth, expectedOwner, actionParams) {
+      await waitForSafeQuantumMoment();
+      try {
+        validateQuantumTimestamp(auth.timestamp);
+      } catch (error) {
+        console.error(
+          "[Authorization] Quantum timestamp validation failed:",
+          error
+        );
+        return false;
+      }
+      const message = this.buildAuthorizationMessage(
+        litActionName,
+        auth.callerAddress,
+        auth.positionId,
+        auth.timestamp,
+        actionParams
+      );
+      let recoveredAddress;
+      try {
+        recoveredAddress = await this.recoverSigner(message, auth.signature);
+      } catch (error) {
+        console.error("[Authorization] Signature recovery failed:", error);
+        return false;
+      }
+      if (recoveredAddress.toLowerCase() !== auth.callerAddress.toLowerCase()) {
+        console.error(
+          `[Authorization] Caller address mismatch:`,
+          `
+  Claimed: ${auth.callerAddress}`,
+          `
+  Recovered: ${recoveredAddress}`
+        );
+        return false;
+      }
+      const isAuthorized = auth.callerAddress.toLowerCase() === expectedOwner.toLowerCase();
+      if (!isAuthorized) {
+        console.error(
+          `[Authorization] Not authorized:`,
+          `
+  Caller: ${auth.callerAddress}`,
+          `
+  Owner: ${expectedOwner}`
+        );
+      }
+      return isAuthorized;
+    }
+    /**
+     * Build authorization message for signing
+     *
+     * Creates deterministic message from parameters for signature verification.
+     *
+     * Message structure:
+     * keccak256(litActionName, callerAddress, positionId, timestamp, actionParams...)
+     *
+     * @param litActionName - Name of the LIT action
+     * @param callerAddress - Ethereum address of caller
+     * @param positionId - Position identifier
+     * @param timestamp - Quantum timestamp
+     * @param actionParams - Action-specific parameters
+     * @returns Message hash for signing
+     */
+    static buildAuthorizationMessage(litActionName, callerAddress, positionId, timestamp, actionParams) {
+      const sortedKeys = Object.keys(actionParams).sort();
+      const values = sortedKeys.map((key) => actionParams[key]);
+      const types = [
+        "string",
+        // litActionName
+        "address",
+        // callerAddress
+        "bytes32",
+        // positionId
+        "uint256",
+        // timestamp
+        ...sortedKeys.map(() => "bytes32")
+        // action params
+      ];
+      const allValues = [
+        litActionName,
+        callerAddress,
+        positionId,
+        timestamp,
+        ...values
+      ];
+      const messageHash = ethers.utils.solidityKeccak256(types, allValues);
+      return messageHash;
+    }
+    /**
+     * Recover signer address from signature
+     *
+     * Uses EIP-191 standard (Ethereum Signed Message)
+     *
+     * @param messageHash - Keccak256 hash of the message
+     * @param signature - Signature to verify
+     * @returns Recovered signer address
+     */
+    static async recoverSigner(messageHash, signature) {
+      try {
+        const messageHashBytes = ethers.utils.arrayify(messageHash);
+        const prefixedHash = ethers.utils.hashMessage(messageHashBytes);
+        const recoveredAddress = ethers.utils.recoverAddress(
+          prefixedHash,
+          signature
+        );
+        return recoveredAddress;
+      } catch (error) {
+        console.error("[Authorization] Signature recovery failed:", error);
+        throw new Error(
+          `Failed to recover signer: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    /**
+     * Verify position owner authorization for mintUCD action
+     *
+     * @param auth - Authorization parameters
+     * @param positionOwner - Position owner address from contract
+     * @param amount - UCD amount to mint (in wei)
+     * @returns True if authorized
+     */
+    static async verifyMintAuthorization(auth, positionOwner, amount) {
+      return this.verifyOwnerSignature(
+        "ucd-mint-validator",
+        auth,
+        positionOwner,
+        {
+          action: ethers.utils.keccak256(ethers.utils.toUtf8Bytes("mintUCD")),
+          amount: ethers.utils.hexZeroPad(ethers.utils.hexlify(amount), 32)
+        }
+      );
+    }
+    /**
+     * Verify position owner authorization for withdrawal action
+     *
+     * @param auth - Authorization parameters
+     * @param positionOwner - Position owner address from contract
+     * @param btcAddress - Bitcoin address to withdraw to
+     * @param satoshis - Amount in satoshis
+     * @returns True if authorized
+     */
+    static async verifyWithdrawalAuthorization(auth, positionOwner, btcAddress, satoshis) {
+      return this.verifyOwnerSignature(
+        "btc-withdrawal-validator",
+        auth,
+        positionOwner,
+        {
+          action: ethers.utils.keccak256(ethers.utils.toUtf8Bytes("withdraw")),
+          btcAddress: ethers.utils.keccak256(
+            ethers.utils.toUtf8Bytes(btcAddress)
+          ),
+          satoshis: ethers.utils.hexZeroPad(ethers.utils.hexlify(satoshis), 32)
+        }
+      );
+    }
+    /**
+     * Verify position owner authorization for repayment action
+     *
+     * @param auth - Authorization parameters
+     * @param positionOwner - Position owner address from contract
+     * @param amount - UCD amount to repay (in wei)
+     * @returns True if authorized
+     */
+    static async verifyRepaymentAuthorization(auth, positionOwner, amount) {
+      return this.verifyOwnerSignature(
+        "ucd-repayment-validator",
+        auth,
+        positionOwner,
+        {
+          action: ethers.utils.keccak256(ethers.utils.toUtf8Bytes("repay")),
+          amount: ethers.utils.hexZeroPad(ethers.utils.hexlify(amount), 32)
+        }
+      );
+    }
+  };
+
+  // src/modules/bitcoin-data-provider.module.ts
+  var DEFAULT_MIN_CONFIRMATIONS = BITCOIN_DEFAULT_MIN_CONFIRMATIONS;
+  var BitcoinDataProvider = class {
+    constructor(config) {
+      this.config = config;
+      this.timeout = config.timeout || 1e4;
+    }
+    /**
+     * Fetch all UTXOs for a Bitcoin address
+     *
+     * @param address - Bitcoin address (legacy, segwit, or taproot)
+     * @returns Array of UTXOs
+     */
+    async getUTXOs(address) {
+      if (this.config.rpcHelper) {
+        return await this.fetchUTXOsFromRPC(address);
+      }
+      try {
+        return await this.fetchUTXOsFromProvider(
+          this.config.providerUrl,
+          address
+        );
+      } catch (error) {
+        console.warn(`[Bitcoin Data] Primary provider failed: ${error.message}`);
+        if (this.config.fallbackProviders && this.config.fallbackProviders.length > 0) {
+          const sortedFallbacks = [...this.config.fallbackProviders].sort(
+            (a, b) => a.priority - b.priority
+          );
+          for (const fallback of sortedFallbacks) {
+            try {
+              console.log(
+                `[Bitcoin Data] Trying fallback: ${fallback.name} (${fallback.url})`
+              );
+              return await this.fetchUTXOsFromProvider(fallback.url, address);
+            } catch (fallbackError) {
+              console.warn(
+                `[Bitcoin Data] Fallback ${fallback.name} failed: ${fallbackError.message}`
+              );
+              continue;
+            }
+          }
+        }
+        throw new Error(`Failed to fetch UTXOs: ${error.message}`);
+      }
+    }
+    /**
+     * Fetch UTXOs using Bitcoin RPC (for regtest/testing)
+     */
+    async fetchUTXOsFromRPC(address) {
+      if (!this.config.rpcHelper) {
+        throw new Error("RPC helper not configured");
+      }
+      const wallet = this.config.rpcWallet || "";
+      const unspentOutputs = await this.config.rpcHelper.listUnspent(
+        wallet,
+        address
+      );
+      const utxos = unspentOutputs.map((utxo) => ({
+        txid: utxo.txid,
+        vout: utxo.vout,
+        satoshis: BigInt(Math.round(utxo.amount * 1e8)),
+        // BTC to satoshis as bigint
+        confirmations: utxo.confirmations
+      }));
+      return utxos;
+    }
+    /**
+     * Detect provider format from URL
+     *
+     * Determines which API format a provider uses based on its URL.
+     *
+     * @param providerUrl Provider base URL
+     * @returns Provider format type
+     */
+    detectProviderFormat(providerUrl) {
+      if (providerUrl.includes("diamond-hands-btc-faucet")) {
+        return "diamond-hands-faucet" /* DIAMOND_HANDS_FAUCET */;
+      }
+      return "blockstream" /* BLOCKSTREAM */;
+    }
+    /**
+     * Parse Diamond Hands Faucet UTXO response
+     *
+     * Expected format:
+     * {
+     *   "success": true,
+     *   "address": "...",
+     *   "utxos": [{txid, vout, amount, confirmations, scriptPubKey}],
+     *   "totalBalance": 33000000,
+     *   "utxoCount": 6
+     * }
+     *
+     * @param data Raw response from faucet API
+     * @returns Array of normalized UTXOs
+     */
+    parseDiamondHandsFaucetUTXOs(data) {
+      if (!data.success) {
+        throw new Error(
+          `Diamond Hands Faucet error: ${data.error || data.message || "Unknown error"}`
+        );
+      }
+      if (!Array.isArray(data.utxos)) {
+        throw new Error(
+          "Invalid Diamond Hands Faucet response: utxos must be an array"
+        );
+      }
+      const utxos = data.utxos.map((utxo) => ({
+        txid: utxo.txid,
+        vout: utxo.vout,
+        satoshis: BigInt(utxo.amount),
+        // Faucet uses "amount" (satoshis)
+        confirmations: utxo.confirmations || 0
+      }));
+      return utxos;
+    }
+    /**
+     * Parse Blockstream/Mempool.space UTXO response
+     *
+     * Expected format: Array of {txid, vout, value, confirmations}
+     *
+     * @param data Raw response from provider API
+     * @returns Array of normalized UTXOs
+     */
+    parseBlockstreamUTXOs(data) {
+      if (!Array.isArray(data)) {
+        throw new Error(
+          "Invalid Blockstream response format: expected an array"
+        );
+      }
+      const utxos = data.map((utxo) => ({
+        txid: utxo.txid,
+        vout: utxo.vout !== void 0 ? utxo.vout : utxo.n,
+        satoshis: BigInt(utxo.value !== void 0 ? utxo.value : utxo.satoshis),
+        confirmations: utxo.confirmations || 0
+      }));
+      return utxos;
+    }
+    /**
+     * Internal method to fetch UTXOs from a specific provider
+     *
+     * Supports multiple provider API formats:
+     * - Blockstream/Mempool.space: /api/address/{address}/utxos
+     * - Diamond Hands Faucet: /api/faucet/utxos/{address}
+     */
+    async fetchUTXOsFromProvider(providerUrl, address) {
+      const format = this.detectProviderFormat(providerUrl);
+      let endpoint;
+      if (format === "diamond-hands-faucet" /* DIAMOND_HANDS_FAUCET */) {
+        endpoint = `${providerUrl}/api/faucet/utxos/${address}`;
+      } else {
+        endpoint = `${providerUrl}/api/address/${address}/utxos`;
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(endpoint, { signal: controller.signal });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          throw new Error(
+            `Bitcoin provider error: ${response.status} ${response.statusText}`
+          );
+        }
+        const data = await response.json();
+        if (format === "diamond-hands-faucet" /* DIAMOND_HANDS_FAUCET */) {
+          return this.parseDiamondHandsFaucetUTXOs(data);
+        } else {
+          return this.parseBlockstreamUTXOs(data);
+        }
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error.name === "AbortError") {
+          throw new Error(`Request timeout after ${this.timeout}ms`);
+        }
+        throw error;
+      }
+    }
+    /**
+     * Get complete UTXO set with balance summary
+     *
+     * This is the SINGLE method that vault-balance module should call.
+     * Returns everything needed to know about Bitcoin network state for an address.
+     *
+     * @param address - Bitcoin address
+     * @param minConfirmations - Minimum confirmations for "confirmed" status (default: 6)
+     * @returns Complete UTXO set with balance breakdown
+     */
+    async getUTXOSet(address, minConfirmations = DEFAULT_MIN_CONFIRMATIONS) {
+      const utxos = await this.getUTXOs(address);
+      const totalBalance = utxos.reduce((sum, utxo) => sum + utxo.satoshis, 0n);
+      const confirmedBalance = utxos.filter((utxo) => utxo.confirmations >= minConfirmations).reduce((sum, utxo) => sum + utxo.satoshis, 0n);
+      const unconfirmedBalance = totalBalance - confirmedBalance;
+      return {
+        utxos,
+        totalBalance,
+        totalUTXOs: utxos.length,
+        confirmedBalance,
+        unconfirmedBalance
+      };
+    }
+    /**
+     * Get transaction with confirmation count
+     *
+     * Checks if transaction exists on Bitcoin network and returns confirmation count.
+     * Used to validate authorized spends have been broadcasted.
+     *
+     * @param txid - Transaction ID to check
+     * @returns Transaction with confirmation count, or null if not found
+     */
+    async getTransaction(txid) {
+      if (this.config.rpcHelper) {
+        try {
+          const wallet = this.config.rpcWallet || "";
+          const tx = await this.config.rpcHelper.getTransaction(wallet, txid);
+          return {
+            txid: tx.txid,
+            confirmations: tx.confirmations || 0
+          };
+        } catch (error) {
+          if (error.message?.includes("Invalid or non-wallet transaction") || error.code === -5) {
+            return null;
+          }
+          throw error;
+        }
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(
+          `${this.config.providerUrl}/api/tx/${txid}`,
+          {
+            signal: controller.signal
+          }
+        );
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          if (response.status === 404) {
+            return null;
+          }
+          throw new Error(
+            `Bitcoin provider error: ${response.status} ${response.statusText}`
+          );
+        }
+        const data = await response.json();
+        if (data.status) {
+          return {
+            txid: data.txid,
+            confirmations: data.status.confirmed ? data.status.block_height ? 1 : 0 : 0
+          };
+        }
+        return null;
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error.name === "AbortError") {
+          throw new Error(`Request timeout after ${this.timeout}ms`);
+        }
+        if (error.message?.includes("404")) {
+          return null;
+        }
+        throw error;
+      }
+    }
+    // FUTURE: Multi-provider consensus methods will be added here
+    // async getUTXOsWithConsensus(address: string): Promise<UTXO[]> {
+    //   // Fetch from all providers
+    //   // Return UTXOs that appear in 2+ sources
+    //   // Use median value if amounts differ
+    // }
+  };
+
+  // src/modules/price-oracle.module.ts
+  var PriceOracleModule = class {
+    constructor(sources) {
+      this.sources = sources || this.getDefaultSources();
+      this.sources.sort((a, b) => a.priority - b.priority);
+    }
+    getDefaultSources() {
+      return [
+        {
+          name: "CoinGecko",
+          fetchPrice: async () => {
+            const url = new URL("https://api.coingecko.com/api/v3/simple/price");
+            url.searchParams.set("ids", "bitcoin");
+            url.searchParams.set("vs_currencies", "usd");
+            const response = await fetch(url.toString());
+            if (!response.ok) {
+              throw new Error(`CoinGecko API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            const price = data.bitcoin.usd;
+            const allPrices = await Lit.Actions.broadcastAndCollect({
+              name: "coinGeckoPrice",
+              value: price.toString()
+            });
+            const prices = allPrices.map((p) => parseFloat(p));
+            prices.sort((a, b) => a - b);
+            return prices[Math.floor(prices.length / 2)];
+          },
+          priority: 1
+        },
+        {
+          name: "Binance",
+          fetchPrice: async () => {
+            const url = new URL("https://api.binance.com/api/v3/ticker/price");
+            url.searchParams.set("symbol", "BTCUSDT");
+            const response = await fetch(url.toString());
+            if (!response.ok) {
+              throw new Error(`Binance API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            const price = parseFloat(data.price);
+            const allPrices = await Lit.Actions.broadcastAndCollect({
+              name: "binancePrice",
+              value: price.toString()
+            });
+            const prices = allPrices.map((p) => parseFloat(p));
+            prices.sort((a, b) => a - b);
+            return prices[Math.floor(prices.length / 2)];
+          },
+          priority: 2
+        },
+        {
+          name: "Coinbase",
+          fetchPrice: async () => {
+            const response = await fetch("https://api.coinbase.com/v2/prices/BTC-USD/spot");
+            if (!response.ok) {
+              throw new Error(`Coinbase API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            const price = parseFloat(data.data.amount);
+            const allPrices = await Lit.Actions.broadcastAndCollect({
+              name: "coinbasePrice",
+              value: price.toString()
+            });
+            const prices = allPrices.map((p) => parseFloat(p));
+            prices.sort((a, b) => a - b);
+            return prices[Math.floor(prices.length / 2)];
+          },
+          priority: 3
+        }
+      ];
+    }
+    /**
+     * Get BTC price in USD with 8 decimals
+     * Fetches from real price sources in priority order
+     */
+    async getBTCPrice() {
+      console.log(`[Price Oracle] Fetching BTC price from external sources...`);
+      for (const source of this.sources) {
+        try {
+          console.log(`[Price Oracle] Trying ${source.name}...`);
+          const priceUSD = await source.fetchPrice();
+          console.log(
+            `[Price Oracle] \u2705 ${source.name}: $${priceUSD.toLocaleString()}`
+          );
+          const priceWith8Decimals = BigInt(Math.floor(priceUSD * 1e8));
+          console.log(
+            `[Price Oracle] Price with 8 decimals: ${priceWith8Decimals}`
+          );
+          return priceWith8Decimals;
+        } catch (error) {
+          console.warn(
+            `[Price Oracle] \u26A0\uFE0F  ${source.name} failed: ${error.message}`
+          );
+          continue;
+        }
+      }
+      throw new Error("All price sources failed");
+    }
+    /**
+     * Consensus across multiple sources with outlier detection
+     * Returns median price from valid sources after filtering outliers
+     *
+     * Master's Wisdom: Two-Path Validation
+     * 1. If ONE source is outlier (>2% from median) → FILTER it, continue with remaining
+     * 2. If ALL sources too dispersed (>5% spread) → REJECT all, throw error
+     *
+     * Logic Flow:
+     * 1. Calculate initial median from all sources
+     * 2. Filter individual outliers (>2% from median)
+     * 3. If outliers found: remove them, require minimum 2 sources remaining
+     * 4. Recalculate median from valid sources only
+     * 5. Check if remaining sources are too dispersed (max/min ratio > 1.05)
+     * 6. Return final median or throw appropriate error
+     */
+    async getBTCPriceConsensus() {
+      console.log(`[Price Oracle] Fetching BTC price with consensus...`);
+      const results = await Promise.allSettled(
+        this.sources.map(async (source) => {
+          const price = await source.fetchPrice();
+          return { source: source.name, price };
+        })
+      );
+      const successful = results.filter((r) => r.status === "fulfilled").map((r) => r.value);
+      if (successful.length === 0) {
+        throw new Error("No price sources returned data");
+      }
+      console.log(
+        `[Price Oracle] Got prices from ${successful.length}/${this.sources.length} sources:`
+      );
+      successful.forEach((s) => {
+        console.log(`   ${s.source}: $${s.price.toLocaleString()}`);
+      });
+      const prices = successful.map((s) => s.price);
+      prices.sort((a, b) => a - b);
+      const initialMedian = prices[Math.floor(prices.length / 2)];
+      const minPrice = prices[0];
+      const maxPrice = prices[prices.length - 1];
+      const dispersionRatio = maxPrice / minPrice;
+      const validPrices = successful.filter((s) => {
+        const deviation = Math.abs(s.price - initialMedian) / initialMedian;
+        return deviation <= PRICE_ORACLE_OUTLIER_DEVIATION_THRESHOLD;
+      });
+      if (dispersionRatio > 1 + PRICE_ORACLE_DISPERSION_THRESHOLD && validPrices.length === successful.length) {
+        throw new Error(
+          `Price consensus failed: sources too dispersed (${((dispersionRatio - 1) * 100).toFixed(1)}% spread)`
+        );
+      }
+      if (validPrices.length < successful.length) {
+        const outliers = successful.filter(
+          (s) => !validPrices.find((v) => v.source === s.source)
+        );
+        console.log(`[Price Oracle] \u26A0\uFE0F  Detected ${outliers.length} outlier(s):`);
+        outliers.forEach((o) => {
+          const deviation = Math.abs(o.price - initialMedian) / initialMedian;
+          console.log(
+            `   ${o.source}: $${o.price.toLocaleString()} (${(deviation * 100).toFixed(1)}% deviation)`
+          );
+        });
+        if (validPrices.length < 2) {
+          throw new Error(
+            "Price consensus failed: insufficient valid sources after outlier removal"
+          );
+        }
+        console.log(
+          `[Price Oracle] \u2705 Outliers filtered, continuing with ${validPrices.length} valid sources`
+        );
+        const validPricesOnly = validPrices.map((v) => v.price);
+        validPricesOnly.sort((a, b) => a - b);
+        const finalMedian = validPricesOnly[Math.floor(validPricesOnly.length / 2)];
+        console.log(
+          `[Price Oracle] \u2705 Consensus price (median): $${finalMedian.toLocaleString()}`
+        );
+        return BigInt(Math.floor(finalMedian * 1e8));
+      }
+      console.log(
+        `[Price Oracle] \u2705 Consensus price (median): $${initialMedian.toLocaleString()}`
+      );
+      return BigInt(Math.floor(initialMedian * 1e8));
+    }
+  };
+
+  // src/modules/vault-balance.module.ts
+  var VaultBalanceModule = class {
+    constructor(config) {
+      this.config = config;
+      this.bitcoinProvider = config.bitcoinProvider;
+    }
+    /**
+     * Calculate trusted balance for a position
+     *
+     * This is the main entry point for determining available balance.
+     *
+     * CRITICAL: Validates that all authorized spends have been properly broadcasted
+     * to Bitcoin network with sufficient confirmations. Throws errors if:
+     * 1. Authorized transaction not found on network (not broadcasted)
+     * 2. Authorized transaction has insufficient confirmations (network updating)
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Complete breakdown of vault balance
+     * @throws Error if authorized spends are in invalid state
+     */
+    async calculateTrustedBalance(positionId, vaultAddress) {
+      const minConfirmations = this.config.minConfirmations || 6;
+      const utxoSet = await this.bitcoinProvider.getUTXOSet(
+        vaultAddress,
+        minConfirmations
+      );
+      const authorizedSpends = await this.getAuthorizedSpendsFromContract(positionId);
+      for (const spend of authorizedSpends) {
+        const utxoStillExists = utxoSet.utxos.some(
+          (utxo) => utxo.txid === spend.txid && utxo.vout === spend.vout
+        );
+        if (utxoStillExists) {
+          throw new Error(
+            `Authorized UTXO ${spend.txid}:${spend.vout} not yet spent. Transaction was authorized in smart contract but not signed and broadcasted to Bitcoin network. Complete the transaction by signing and broadcasting it.`
+          );
+        }
+      }
+      const authorizedBalance = authorizedSpends.reduce(
+        (sum, spend) => sum + spend.satoshis,
+        0n
+      );
+      const availableUTXOs = utxoSet.utxos.filter(
+        (utxo) => !this.isUTXOAuthorized(utxo, authorizedSpends)
+      );
+      const availableBalance = availableUTXOs.reduce(
+        (sum, utxo) => sum + utxo.satoshis,
+        0n
+      );
+      return {
+        // Total from Bitcoin
+        totalUTXOs: utxoSet.utxos,
+        totalBalance: utxoSet.totalBalance,
+        // Authorized from Contract
+        authorizedUTXOs: authorizedSpends,
+        authorizedBalance,
+        // Available = Total - Authorized (THIS IS THE TRUSTED BALANCE)
+        availableUTXOs,
+        availableBalance,
+        // Metadata
+        vaultAddress,
+        positionId,
+        timestamp: Date.now()
+      };
+    }
+    /**
+     * Get just the trusted balance amount
+     *
+     * Convenience method when you only need the number.
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Available balance in satoshis
+     */
+    async getTrustedBalance(positionId, vaultAddress) {
+      const result = await this.calculateTrustedBalance(positionId, vaultAddress);
+      return result.availableBalance;
+    }
+    /**
+     * Get available UTXOs that can be used for new authorizations
+     *
+     * This is useful when you need to select specific UTXOs for authorization.
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Array of available UTXOs
+     */
+    async getAvailableUTXOs(positionId, vaultAddress) {
+      const result = await this.calculateTrustedBalance(positionId, vaultAddress);
+      return result.availableUTXOs;
+    }
+    /**
+     * Check if a specific UTXO is available for authorization
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @param txid - Transaction ID of the UTXO
+     * @param vout - Output index of the UTXO
+     * @returns True if UTXO is available, false otherwise
+     */
+    async isUTXOAvailable(positionId, vaultAddress, txid, vout) {
+      const availableUTXOs = await this.getAvailableUTXOs(
+        positionId,
+        vaultAddress
+      );
+      return availableUTXOs.some(
+        (utxo) => utxo.txid === txid && utxo.vout === vout
+      );
+    }
+    /**
+     * Check if a UTXO is authorized (appears in authorized spends)
+     *
+     * @param utxo - The UTXO to check
+     * @param authorizedSpends - List of authorized spends from contract
+     * @returns True if UTXO is authorized, false otherwise
+     */
+    isUTXOAuthorized(utxo, authorizedSpends) {
+      return authorizedSpends.some(
+        (spend) => spend.txid === utxo.txid && spend.vout === utxo.vout
+      );
+    }
+    /**
+     * Query smart contract for authorized spends
+     *
+     * Calls the contract's getAuthorizedSpends(positionId) view function
+     * to retrieve all authorized Bitcoin spends for this position.
+     *
+     * Contract struct AuthorizedSpend:
+     * - txid: string
+     * - vout: uint32
+     * - satoshis: uint256
+     * - authorizedAt: uint256 (timestamp)
+     *
+     * @param positionId - The position ID to query
+     * @returns Array of authorized spends for this position
+     */
+    async getAuthorizedSpendsFromContract(positionId) {
+      const positionIdBytes32 = positionId.startsWith("0x") ? positionId : `0x${positionId.padStart(64, "0")}`;
+      const getAuthorizedSpendsABI = [
+        {
+          inputs: [
+            { internalType: "bytes32", name: "positionId", type: "bytes32" }
+          ],
+          name: "getAuthorizedSpends",
+          outputs: [
+            {
+              components: [
+                { internalType: "string", name: "txid", type: "string" },
+                { internalType: "uint32", name: "vout", type: "uint32" },
+                { internalType: "uint256", name: "satoshis", type: "uint256" },
+                {
+                  internalType: "string",
+                  name: "targetAddress",
+                  type: "string"
+                },
+                {
+                  internalType: "uint256",
+                  name: "targetAmount",
+                  type: "uint256"
+                },
+                {
+                  internalType: "string",
+                  name: "changeAddress",
+                  type: "string"
+                },
+                {
+                  internalType: "uint256",
+                  name: "authorizedAt",
+                  type: "uint256"
+                }
+              ],
+              internalType: "struct LoanOperationsManager.AuthorizedSpend[]",
+              name: "",
+              type: "tuple[]"
+            }
+          ],
+          stateMutability: "view",
+          type: "function"
+        }
+      ];
+      let rpcUrl;
+      if (this.config.rpcUrl) {
+        rpcUrl = this.config.rpcUrl;
+      } else {
+        rpcUrl = await Lit.Actions.getRpcUrl({ chain: this.config.chain });
+      }
+      const provider = new ethers.providers.JsonRpcProvider(rpcUrl);
+      const contract = new ethers.Contract(
+        this.config.contractAddress,
+        getAuthorizedSpendsABI,
+        provider
+      );
+      const result = await contract.getAuthorizedSpends(positionIdBytes32);
+      return result.map((spend) => ({
+        txid: spend.txid,
+        vout: Number(spend.vout),
+        satoshis: BigInt(spend.satoshis.toString()),
+        positionId,
+        targetAddress: spend.targetAddress,
+        targetAmount: BigInt(spend.targetAmount.toString()),
+        changeAddress: spend.changeAddress,
+        timestamp: Number(spend.authorizedAt)
+      }));
+    }
+  };
+  function createVaultBalanceModule(config) {
+    return new VaultBalanceModule(config);
+  }
+
+  // src/modules/business-rules-math.module.ts
+  function calculateTermStartFromExpiry(expiryTimestamp, termLengthMonths) {
+    if (expiryTimestamp === 0) {
+      return 0;
+    }
+    const SECONDS_PER_DAY = 86400;
+    const DAYS_PER_MONTH = 30;
+    const termDurationSeconds = termLengthMonths * DAYS_PER_MONTH * SECONDS_PER_DAY;
+    return expiryTimestamp - termDurationSeconds;
+  }
+  function calculateTermStatus(termStartTimestamp, selectedTermMonths) {
+    if (termStartTimestamp === 0) {
+      return {
+        termDurationDays: 0,
+        termLengthDays: selectedTermMonths * 30,
+        isExpired: false,
+        daysUntilExpiry: selectedTermMonths * 30,
+        daysIntoGracePeriod: 0
+      };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    const termLengthDays = selectedTermMonths * 30;
+    const termDurationSeconds = now - termStartTimestamp;
+    const termDurationDays = Math.floor(termDurationSeconds / 86400);
+    const isExpired = termDurationDays > termLengthDays;
+    const daysUntilExpiry = Math.max(0, termLengthDays - termDurationDays);
+    const daysIntoGracePeriod = Math.max(0, termDurationDays - termLengthDays);
+    return {
+      termDurationDays,
+      termLengthDays,
+      isExpired,
+      daysUntilExpiry,
+      daysIntoGracePeriod
+    };
+  }
+  function calculateLiquidationThreshold(isExpired, daysIntoGracePeriod) {
+    if (!isExpired) {
+      return ACTIVE_LOAN_LIQUIDATION_THRESHOLD_BPS;
+    }
+    const day = Math.min(daysIntoGracePeriod, GRACE_PERIOD_DAYS);
+    const daySquared = day * day;
+    const escalation = daySquared * (EXPIRED_LOAN_MAX_LIQUIDATION_THRESHOLD_BPS - EXPIRED_LOAN_MIN_LIQUIDATION_THRESHOLD_BPS) / (GRACE_PERIOD_DAYS * GRACE_PERIOD_DAYS);
+    const threshold = EXPIRED_LOAN_MIN_LIQUIDATION_THRESHOLD_BPS + escalation;
+    return threshold;
+  }
+  function calculateCollateralMetrics(availableBTCSats, btcPriceUsd, ucdDebt) {
+    if (ucdDebt === 0n) {
+      return {
+        collateralValueUsd: 0n,
+        collateralRatioBps: Number.MAX_SAFE_INTEGER
+      };
+    }
+    const collateralValueUsd = availableBTCSats * btcPriceUsd / (SATOSHIS_PER_BITCOIN * PRICE_ORACLE_DECIMALS);
+    const ratioBigInt = collateralValueUsd * UCD_TOKEN_DECIMALS * 10000n / ucdDebt;
+    const collateralRatioBps = Number(ratioBigInt);
+    return {
+      collateralValueUsd,
+      collateralRatioBps
+    };
+  }
+  function hasSufficientCollateralForDebt(collateralValueUsd, currentDebt, additionalDebt, requiredRatioBps) {
+    const newTotalDebt = currentDebt + additionalDebt;
+    if (newTotalDebt === 0n) {
+      return true;
+    }
+    const newCollateralRatioBps = Number(
+      collateralValueUsd * UCD_TOKEN_DECIMALS * 10000n / newTotalDebt
+    );
+    return newCollateralRatioBps >= requiredRatioBps;
+  }
+  function calculateFeeBps(amount, feeBps) {
+    if (amount < 0n) {
+      throw new Error("Amount cannot be negative");
+    }
+    if (feeBps < 0 || feeBps > 1e4) {
+      throw new Error(
+        "Fee basis points must be between 0 and 10000 (0% to 100%)"
+      );
+    }
+    const fee = amount * BigInt(feeBps) / 10000n;
+    return fee;
+  }
+  function calculateBtcValueUsd(btcSats, btcPriceUsd8Decimals) {
+    if (btcSats < 0n) {
+      throw new Error("BTC amount cannot be negative");
+    }
+    if (btcPriceUsd8Decimals <= 0n) {
+      throw new Error("BTC price must be positive");
+    }
+    const valueUsd = btcSats * btcPriceUsd8Decimals / SATOSHIS_PER_BITCOIN;
+    return valueUsd;
+  }
+  function calculateCollateralRatioBps(collateralValueUsd8Decimals, debtUsd18Decimals) {
+    if (collateralValueUsd8Decimals < 0n) {
+      throw new Error("Collateral value cannot be negative");
+    }
+    if (debtUsd18Decimals <= 0n) {
+      throw new Error("Debt must be positive to calculate ratio");
+    }
+    const scaledCollateral = collateralValueUsd8Decimals * 10000000000n;
+    const ratioBps = scaledCollateral * 10000n / debtUsd18Decimals;
+    const ratioBpsNumber = Number(ratioBps);
+    if (ratioBpsNumber < 0 || ratioBpsNumber > 1e8) {
+      throw new Error(
+        `Collateral ratio out of bounds: ${ratioBpsNumber} bps (${ratioBpsNumber / 100}%)`
+      );
+    }
+    return ratioBpsNumber;
+  }
+  function isCollateralSufficient(collateralValueUsd8Decimals, debtUsd18Decimals, minimumRatioBps) {
+    if (minimumRatioBps < 0 || minimumRatioBps > 1e6) {
+      throw new Error(
+        "Minimum ratio must be between 0 and 1000000 bps (0% to 10000%)"
+      );
+    }
+    const actualRatioBps = calculateCollateralRatioBps(
+      collateralValueUsd8Decimals,
+      debtUsd18Decimals
+    );
+    return actualRatioBps >= minimumRatioBps;
+  }
+  function bpsToPercent(basisPoints) {
+    return basisPoints / 100;
+  }
+
+  // src/modules/protocol-parameters.module.ts
+  var ProtocolParametersModule = class {
+    constructor(config) {
+      this.termManagerAddress = config.termManagerAddress;
+      this.loanOpsManagerAddress = config.loanOpsManagerAddress;
+      this.chain = config.chain;
+    }
+    /**
+     * Get liquidation threshold from LoanOperationsManager
+     *
+     * @returns Liquidation threshold in basis points
+     */
+    async getLiquidationThreshold() {
+      const abi = [
+        {
+          inputs: [],
+          name: "liquidationThreshold",
+          outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
+          stateMutability: "view",
+          type: "function"
+        }
+      ];
+      try {
+        const result = await Lit.Actions.call({
+          chain: this.chain,
+          contractAddress: this.loanOpsManagerAddress,
+          abi,
+          methodName: "liquidationThreshold",
+          params: []
+        });
+        return Number(result);
+      } catch (error) {
+        console.error(
+          "[ProtocolParameters] Error fetching liquidation threshold:",
+          error.message
+        );
+        throw new Error(
+          `Failed to fetch liquidation threshold: ${error.message}`
+        );
+      }
+    }
+    /**
+     * Get term-specific fees from TermManager
+     *
+     * @param termMonths Loan term in months
+     * @returns Term fees (origination and extension) in basis points
+     */
+    async getTermFees(termMonths) {
+      const abi = [
+        {
+          inputs: [
+            { internalType: "uint256", name: "_termMonths", type: "uint256" }
+          ],
+          name: "getTermFees",
+          outputs: [
+            { internalType: "uint88", name: "originationFee", type: "uint88" },
+            { internalType: "uint88", name: "extensionFee", type: "uint88" }
+          ],
+          stateMutability: "view",
+          type: "function"
+        }
+      ];
+      try {
+        const result = await Lit.Actions.call({
+          chain: this.chain,
+          contractAddress: this.termManagerAddress,
+          abi,
+          methodName: "getTermFees",
+          params: [termMonths]
+        });
+        return {
+          originationFeeBps: Number(result[0]),
+          extensionFeeBps: Number(result[1])
+        };
+      } catch (error) {
+        console.error(
+          "[ProtocolParameters] Error fetching term fees:",
+          error.message
+        );
+        throw new Error(`Failed to fetch term fees: ${error.message}`);
+      }
+    }
+  };
+  function createProtocolParametersModule(config) {
+    return new ProtocolParametersModule(config);
+  }
+
+  // src/modules/vault-snapshot.ts
+  var VaultSnapshotModule = class {
+    constructor(config) {
+      this.config = config;
+    }
+    /**
+     * Get complete vault snapshot
+     *
+     * This is the main entry point. Returns everything you need to know
+     * about a vault's health in a single call.
+     *
+     * @param positionId - Position to snapshot
+     * @returns Complete VaultSnapshot with all metrics
+     */
+    async getVaultSnapshot(positionId) {
+      const positionState = await this.queryPositionState(positionId);
+      const balanceResult = await this.config.vaultBalance.calculateTrustedBalance(
+        positionId,
+        positionState.vaultAddress
+      );
+      const btcPriceUsd = await this.config.priceOracle.getBTCPrice();
+      const protocolParams = createProtocolParametersModule({
+        termManagerAddress: this.config.termManagerAddress,
+        loanOpsManagerAddress: this.config.loanOpsManagerAddress,
+        chain: this.config.chain
+      });
+      const [liquidationThresholdBps, termFees] = await Promise.all([
+        protocolParams.getLiquidationThreshold(),
+        protocolParams.getTermFees(positionState.selectedTerm)
+      ]);
+      const termStatus = calculateTermStatus(
+        positionState.termStartTimestamp,
+        positionState.selectedTerm
+      );
+      const currentLiquidationThreshold = calculateLiquidationThreshold(
+        termStatus.isExpired,
+        termStatus.daysIntoGracePeriod
+      );
+      const collateralMetrics = calculateCollateralMetrics(
+        balanceResult.availableBalance,
+        btcPriceUsd,
+        positionState.ucdDebt
+      );
+      const isLiquidatable = collateralMetrics.collateralRatioBps < currentLiquidationThreshold;
+      const marginToLiquidationBps = collateralMetrics.collateralRatioBps - currentLiquidationThreshold;
+      return {
+        // Raw state
+        positionId: positionState.positionId,
+        pkpId: positionState.pkpId,
+        borrower: positionState.borrower,
+        vaultAddress: positionState.vaultAddress,
+        ucdDebt: positionState.ucdDebt,
+        termStartTimestamp: positionState.termStartTimestamp,
+        selectedTerm: positionState.selectedTerm,
+        isActive: positionState.isActive,
+        status: positionState.status,
+        // Loan status enum value (0-7)
+        // Bitcoin state
+        totalBTCSats: balanceResult.totalBalance,
+        totalUTXOs: balanceResult.totalUTXOs,
+        authorizedSpendsSats: balanceResult.authorizedBalance,
+        availableBTCSats: balanceResult.availableBalance,
+        availableUTXOs: balanceResult.availableUTXOs,
+        // Price data
+        btcPriceUsd,
+        // Calculated metrics
+        collateralValueUsd: collateralMetrics.collateralValueUsd,
+        collateralRatioBps: collateralMetrics.collateralRatioBps,
+        // Term status
+        termDurationDays: termStatus.termDurationDays,
+        termLengthDays: termStatus.termLengthDays,
+        isExpired: termStatus.isExpired,
+        daysUntilExpiry: termStatus.daysUntilExpiry,
+        daysIntoGracePeriod: termStatus.daysIntoGracePeriod,
+        // Liquidation risk
+        currentLiquidationThreshold,
+        isLiquidatable,
+        marginToLiquidationBps,
+        // Protocol parameters (from smart contracts)
+        liquidationThresholdBps,
+        originationFeeBps: termFees.originationFeeBps,
+        extensionFeeBps: termFees.extensionFeeBps,
+        // Metadata
+        timestamp: Date.now()
+      };
+    }
+    /**
+     * Query position state from smart contract
+     *
+     * Gets the simple state that contract stores:
+     * - positionId, pkpId, borrower, vaultAddress
+     * - ucdDebt
+     * - termStartTimestamp
+     * - selectedTerm
+     * - isActive
+     * - status
+     */
+    async queryPositionState(positionId) {
+      const positionIdBytes32 = positionId.startsWith("0x") ? positionId : `0x${positionId.padStart(64, "0")}`;
+      const getPositionDetailsABI = [
+        {
+          inputs: [
+            { internalType: "bytes32", name: "positionId", type: "bytes32" }
+          ],
+          name: "getPositionDetails",
+          outputs: [
+            {
+              components: [
+                { internalType: "bytes32", name: "positionId", type: "bytes32" },
+                { internalType: "bytes32", name: "pkpId", type: "bytes32" },
+                { internalType: "uint256", name: "ucdDebt", type: "uint256" },
+                {
+                  internalType: "string",
+                  name: "vaultAddress",
+                  type: "string"
+                },
+                { internalType: "address", name: "borrower", type: "address" },
+                { internalType: "uint40", name: "createdAt", type: "uint40" },
+                { internalType: "uint40", name: "lastUpdated", type: "uint40" },
+                {
+                  internalType: "uint16",
+                  name: "selectedTerm",
+                  type: "uint16"
+                },
+                { internalType: "uint40", name: "expiryAt", type: "uint40" },
+                { internalType: "bool", name: "isActive", type: "bool" },
+                {
+                  internalType: "enum LoanStatusLib.LoanStatus",
+                  name: "status",
+                  type: "uint8"
+                }
+              ],
+              internalType: "struct IPositionManagerCore.Position",
+              name: "",
+              type: "tuple"
+            }
+          ],
+          stateMutability: "view",
+          type: "function"
+        }
+      ];
+      let rpcUrl;
+      if (this.config.rpcUrl) {
+        rpcUrl = this.config.rpcUrl;
+      } else {
+        rpcUrl = await Lit.Actions.getRpcUrl({ chain: this.config.chain });
+      }
+      const provider = new ethers.providers.JsonRpcProvider(rpcUrl);
+      const contract = new ethers.Contract(
+        this.config.contractAddress,
+        getPositionDetailsABI,
+        provider
+      );
+      const position = await contract.getPositionDetails(positionIdBytes32);
+      const expiryAt = Number(position.expiryAt);
+      const selectedTermMonths = Number(position.selectedTerm);
+      const termStartTimestamp = calculateTermStartFromExpiry(
+        expiryAt,
+        selectedTermMonths
+      );
+      return {
+        positionId: position.positionId,
+        pkpId: position.pkpId,
+        borrower: position.borrower,
+        vaultAddress: position.vaultAddress,
+        ucdDebt: BigInt(position.ucdDebt.toString()),
+        termStartTimestamp,
+        selectedTerm: selectedTermMonths,
+        isActive: position.isActive,
+        status: Number(position.status)
+        // Extract loan status enum value (0-7)
+      };
+    }
+    /**
+     * Quick check if position is liquidatable
+     *
+     * Convenience method when you only need to know if position can be liquidated.
+     *
+     * @param positionId - Position to check
+     * @returns True if position is liquidatable
+     */
+    async isLiquidatable(positionId) {
+      const snapshot = await this.getVaultSnapshot(positionId);
+      return snapshot.isLiquidatable;
+    }
+    /**
+     * Get collateral ratio for position
+     *
+     * Convenience method when you only need the collateral ratio.
+     *
+     * @param positionId - Position to check
+     * @returns Collateral ratio in basis points
+     */
+    async getCollateralRatio(positionId) {
+      const snapshot = await this.getVaultSnapshot(positionId);
+      return snapshot.collateralRatioBps;
+    }
+    /**
+     * Get available BTC balance
+     *
+     * Convenience method when you only need available balance.
+     *
+     * @param positionId - Position to check
+     * @returns Available BTC in satoshis
+     */
+    async getAvailableBalance(positionId) {
+      const snapshot = await this.getVaultSnapshot(positionId);
+      return snapshot.availableBTCSats;
+    }
+    /**
+     * Check if position has sufficient collateral for new debt
+     *
+     * Used by minting authorization to validate new mints.
+     *
+     * @param positionId - Position to check
+     * @param additionalDebt - Additional UCD debt to add
+     * @param requiredRatioBps - Required collateral ratio (e.g., 13000 for 130%)
+     * @returns True if sufficient collateral exists
+     */
+    async hasSufficientCollateral(positionId, additionalDebt, requiredRatioBps) {
+      const snapshot = await this.getVaultSnapshot(positionId);
+      return hasSufficientCollateralForDebt(
+        snapshot.collateralValueUsd,
+        snapshot.ucdDebt,
+        additionalDebt,
+        requiredRatioBps
+      );
+    }
+  };
+  function createVaultSnapshotModule(config) {
+    return new VaultSnapshotModule(config);
+  }
+
+  // src/modules/system-health.module.ts
+  var SystemHealthModule = class {
+    /**
+     * Check if contract is paused
+     * @param chain Chain identifier
+     * @param contractAddress Contract address to check
+     * @returns True if contract is paused
+     */
+    static async checkPaused(chain, contractAddress) {
+      const pausedAbi = [{
+        inputs: [],
+        name: "paused",
+        outputs: [{ internalType: "bool", name: "", type: "bool" }],
+        stateMutability: "view",
+        type: "function"
+      }];
+      try {
+        const result = await Lit.Actions.call({
+          chain,
+          contractAddress,
+          abi: pausedAbi,
+          methodName: "paused",
+          params: []
+        });
+        return Boolean(result);
+      } catch (error) {
+        console.error(`Failed to check pause state for ${contractAddress}:`, error);
+        return false;
+      }
+    }
+    /**
+     * Check oracle emergency mode
+     * @param chain Chain identifier
+     * @param contractAddress Price feed contract address
+     * @returns True if oracle is in emergency mode
+     */
+    static async checkOracleEmergency(chain, contractAddress) {
+      const emergencyModeAbi = [{
+        inputs: [],
+        name: "emergencyMode",
+        outputs: [{ internalType: "bool", name: "", type: "bool" }],
+        stateMutability: "view",
+        type: "function"
+      }];
+      try {
+        const result = await Lit.Actions.call({
+          chain,
+          contractAddress,
+          abi: emergencyModeAbi,
+          methodName: "emergencyMode",
+          params: []
+        });
+        return Boolean(result);
+      } catch (error) {
+        console.error(`Failed to check oracle emergency mode for ${contractAddress}:`, error);
+        return false;
+      }
+    }
+    /**
+     * Check circuit breaker status
+     * @param chain Chain identifier
+     * @param contractAddress Circuit breaker contract address
+     * @returns True if circuit breaker is triggered
+     */
+    static async checkCircuitBreaker(chain, contractAddress) {
+      const circuitBreakerAbi = [{
+        inputs: [],
+        name: "isTriggered",
+        outputs: [{ internalType: "bool", name: "", type: "bool" }],
+        stateMutability: "view",
+        type: "function"
+      }];
+      try {
+        const result = await Lit.Actions.call({
+          chain,
+          contractAddress,
+          abi: circuitBreakerAbi,
+          methodName: "isTriggered",
+          params: []
+        });
+        return Boolean(result);
+      } catch (error) {
+        console.error(`Failed to check circuit breaker for ${contractAddress}:`, error);
+        return false;
+      }
+    }
+    /**
+     * Check UCD token transfers paused
+     * @param chain Chain identifier
+     * @param contractAddress UCD token contract address
+     * @returns True if transfers are paused
+     */
+    static async checkTransfersPaused(chain, contractAddress) {
+      const transfersPausedAbi = [{
+        inputs: [],
+        name: "transfersPaused",
+        outputs: [{ internalType: "bool", name: "", type: "bool" }],
+        stateMutability: "view",
+        type: "function"
+      }];
+      try {
+        const result = await Lit.Actions.call({
+          chain,
+          contractAddress,
+          abi: transfersPausedAbi,
+          methodName: "transfersPaused",
+          params: []
+        });
+        return Boolean(result);
+      } catch (error) {
+        console.error(`Failed to check transfers paused for ${contractAddress}:`, error);
+        return false;
+      }
+    }
+  };
+
+  // src/ucd-mint-validator.ts
+  var go = async () => {
+    const MIN_BTC_PRICE_USD = 1000000000000n;
+    const MAX_BTC_PRICE_USD = 100000000000000n;
+    const MAX_TIMESTAMP_AGE_MS = 5 * 60 * 1e3;
+    const ABI_REMAINING_MINT_CAPACITY = [
+      {
+        inputs: [],
+        name: "getRemainingMintCapacity",
+        outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function"
+      }
+    ];
+    const ABI_MAX_SUPPLY = [
+      {
+        inputs: [],
+        name: "maxSupply",
+        outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function"
+      }
+    ];
+    const ABI_CURRENT_SUPPLY = [
+      {
+        inputs: [],
+        name: "getCurrentSupply",
+        outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function"
+      }
+    ];
+    const ABI_MINIMUM_LOAN_VALUE_WEI = [
+      {
+        inputs: [],
+        name: "minimumLoanValueWei",
+        outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function"
+      }
+    ];
+    const ABI_MAXIMUM_LOAN_VALUE_UCD = [
+      {
+        inputs: [],
+        name: "maximumLoanValueUcd",
+        outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function"
+      }
+    ];
+    console.log("[Step 0] Validating configuration...");
+    const chain = globalThis.chain;
+    const bitcoinProviderUrl = globalThis.bitcoinProviderUrl;
+    if (!chain) {
+      throw new Error(
+        'Missing required parameter: "chain". Must be "sepolia" or "ethereum"'
+      );
+    }
+    if (!bitcoinProviderUrl) {
+      throw new Error(
+        'Missing required parameter: "bitcoinProviderUrl". Must be an approved Bitcoin RPC provider URL'
+      );
+    }
+    const validatedChain = validateChain(chain);
+    const bitcoinNetwork = getBitcoinNetworkForChain(validatedChain);
+    const bitcoinProviderConfig = getBitcoinProviderConfig(
+      chain,
+      bitcoinProviderUrl
+    );
+    console.log(`  \u2705 Chain: ${chain} (${validatedChain})`);
+    console.log(`  \u2705 Bitcoin Network: ${bitcoinNetwork}`);
+    console.log(
+      `  \u2705 Bitcoin Provider: ${bitcoinProviderConfig.name} (${bitcoinProviderConfig.url})`
+    );
+    console.log(
+      `  \u2705 Min Confirmations: ${bitcoinProviderConfig.minConfirmations}`
+    );
+    const networkConfig = getNetworkConfig(chain);
+    const POSITION_MANAGER_ADDRESS = networkConfig.contracts.PositionManager;
+    const LOAN_OPS_MANAGER_ADDRESS = networkConfig.contracts.LoanOperationsManagerModule;
+    const TERM_MANAGER_ADDRESS = networkConfig.contracts.TermManagerModule;
+    const UCD_CONTROLLER_ADDRESS = networkConfig.contracts.UCDController;
+    console.log(`  \u2705 Contract addresses loaded for ${chain}`);
+    console.log("[Step 0.5] Critical system health checks...");
+    const CIRCUIT_BREAKER_ADDRESS = networkConfig.contracts.CircuitBreakerModule;
+    const PRICE_FEED_ADDRESS = networkConfig.contracts.PriceFeedConsumer;
+    const UCD_TOKEN_ADDRESS = networkConfig.contracts.UCDToken;
+    const ucdControllerPaused = await SystemHealthModule.checkPaused(
+      chain,
+      UCD_CONTROLLER_ADDRESS
+    );
+    if (ucdControllerPaused) {
+      throw new Error(
+        "UCD Controller is paused - minting operations are currently disabled. Contact protocol administrators for more information."
+      );
+    }
+    console.log("  \u2705 UCD Controller is active");
+    const circuitBreakerTriggered = await SystemHealthModule.checkCircuitBreaker(
+      chain,
+      CIRCUIT_BREAKER_ADDRESS
+    );
+    if (circuitBreakerTriggered) {
+      throw new Error(
+        "Circuit breaker has been triggered - protocol operations are halted. This is an emergency safety measure. Contact protocol administrators."
+      );
+    }
+    console.log("  \u2705 Circuit breaker is not triggered");
+    const oracleEmergency = await SystemHealthModule.checkOracleEmergency(
+      chain,
+      PRICE_FEED_ADDRESS
+    );
+    if (oracleEmergency) {
+      throw new Error(
+        "Price oracle is in emergency mode - price feeds are unreliable. Minting operations are temporarily disabled for safety."
+      );
+    }
+    console.log("  \u2705 Price oracle is operational");
+    const transfersPaused = await SystemHealthModule.checkTransfersPaused(
+      chain,
+      UCD_TOKEN_ADDRESS
+    );
+    if (transfersPaused) {
+      console.log("  \u26A0\uFE0F  WARNING: UCD token transfers are currently paused");
+      console.log("  \u26A0\uFE0F  Minting will succeed but tokens cannot be transferred until unpaused");
+      console.log("  \u26A0\uFE0F  Tokens will remain in your position and can be used for debt repayment");
+    }
+    console.log("  \u2705 System health checks complete");
+    const auth = globalThis.auth;
+    if (!auth || typeof auth !== "object") {
+      throw new Error('Missing or invalid "auth" parameter - must be an object');
+    }
+    if (!auth.positionId) {
+      throw new Error("auth.positionId is required");
+    }
+    if (!auth.callerAddress) {
+      throw new Error("auth.callerAddress is required");
+    }
+    if (typeof auth.timestamp !== "number") {
+      throw new Error("auth.timestamp must be a number");
+    }
+    if (!auth.signature) {
+      throw new Error("auth.signature is required");
+    }
+    const currentTime = Date.now();
+    const timestampAge = currentTime - auth.timestamp;
+    if (timestampAge < 0) {
+      throw new Error(
+        `auth.timestamp is in the future: ${auth.timestamp} vs current ${currentTime}. This may indicate clock synchronization issues.`
+      );
+    }
+    if (timestampAge > MAX_TIMESTAMP_AGE_MS) {
+      throw new Error(
+        `auth.timestamp is too old: ${Math.round(timestampAge / 1e3)}s ago (max ${Math.round(MAX_TIMESTAMP_AGE_MS / 1e3)}s). Please refresh your authorization and try again.`
+      );
+    }
+    console.log(`  \u2705 Timestamp validation passed (${Math.round(timestampAge / 1e3)}s old)`);
+    if (globalThis.amount === void 0 || globalThis.amount === null) {
+      throw new Error('Missing required parameter: "amount"');
+    }
+    const amount = BigInt(globalThis.amount);
+    if (amount <= 0n) {
+      throw new Error(`Amount must be positive, got: ${amount.toString()} wei`);
+    }
+    console.log("  Fetching protocol mint limits...");
+    const minLoanValueResult = await Lit.Actions.call({
+      chain,
+      contractAddress: LOAN_OPS_MANAGER_ADDRESS,
+      abi: ABI_MINIMUM_LOAN_VALUE_WEI,
+      methodName: "minimumLoanValueWei",
+      params: []
+    });
+    const MIN_MINT_AMOUNT = BigInt(minLoanValueResult.toString());
+    const maxLoanValueUcdResult = await Lit.Actions.call({
+      chain,
+      contractAddress: LOAN_OPS_MANAGER_ADDRESS,
+      abi: ABI_MAXIMUM_LOAN_VALUE_UCD,
+      methodName: "maximumLoanValueUcd",
+      params: []
+    });
+    const maxLoanValueUcd = BigInt(maxLoanValueUcdResult.toString());
+    const MAX_MINT_AMOUNT = maxLoanValueUcd * 1000000000000000000n;
+    console.log(`  \u2705 Protocol limits loaded from LoanOperationsManager`);
+    console.log(`  - Minimum: ${MIN_MINT_AMOUNT.toString()} wei`);
+    console.log(`  - Maximum: ${MAX_MINT_AMOUNT.toString()} wei`);
+    if (amount < MIN_MINT_AMOUNT) {
+      throw new Error(
+        `Amount too small: ${amount.toString()} wei. Minimum: ${MIN_MINT_AMOUNT.toString()} wei`
+      );
+    }
+    if (amount > MAX_MINT_AMOUNT) {
+      throw new Error(
+        `Amount too large: ${amount.toString()} wei. Maximum: ${MAX_MINT_AMOUNT.toString()} wei`
+      );
+    }
+    const publicKey = globalThis.publicKey;
+    if (!publicKey) {
+      throw new Error('Missing required parameter: "publicKey"');
+    }
+    if (typeof publicKey !== "string" || publicKey.length === 0) {
+      throw new Error("Invalid publicKey: must be non-empty string");
+    }
+    let currentStep = "0.5";
+    try {
+      console.log("[UCD Mint Validator] Started");
+      console.log(`  Position: ${auth.positionId}`);
+      console.log(`  Amount: ${amount.toString()} wei`);
+      const bitcoinProvider = new BitcoinDataProvider({
+        providerUrl: bitcoinProviderConfig.url
+      });
+      const priceOracle = new PriceOracleModule();
+      const vaultBalance = createVaultBalanceModule({
+        contractAddress: LOAN_OPS_MANAGER_ADDRESS,
+        chain,
+        bitcoinProvider,
+        minConfirmations: bitcoinProviderConfig.minConfirmations
+      });
+      currentStep = "1";
+      console.log("[Step 1] Getting vault snapshot...");
+      const vaultSnapshot = createVaultSnapshotModule({
+        contractAddress: POSITION_MANAGER_ADDRESS,
+        termManagerAddress: TERM_MANAGER_ADDRESS,
+        loanOpsManagerAddress: LOAN_OPS_MANAGER_ADDRESS,
+        chain,
+        vaultBalance,
+        priceOracle
+      });
+      const snapshot = await vaultSnapshot.getVaultSnapshot(auth.positionId);
+      if (snapshot.btcPriceUsd < MIN_BTC_PRICE_USD || snapshot.btcPriceUsd > MAX_BTC_PRICE_USD) {
+        throw new Error(
+          `Bitcoin price ${snapshot.btcPriceUsd} is outside acceptable range (${MIN_BTC_PRICE_USD} - ${MAX_BTC_PRICE_USD}). This may indicate oracle manipulation or stale price data. Please try again later.`
+        );
+      }
+      console.log(`  \u2705 BTC price validation passed: $${(Number(snapshot.btcPriceUsd) / 1e8).toFixed(2)}`);
+      currentStep = "2";
+      console.log("[Step 2] Authenticating caller...");
+      const isAuthorized = await AuthorizationModule.verifyMintAuthorization(
+        auth,
+        snapshot.borrower,
+        // Expected owner from contract
+        amount
+      );
+      if (!isAuthorized) {
+        throw new Error("Caller not authorized");
+      }
+      console.log("  \u2705 Caller authorized");
+      currentStep = "3";
+      console.log("[Step 3] Validating position state...");
+      const validMintingStates = getValidMintingStatuses();
+      if (!validMintingStates.includes(snapshot.status)) {
+        throw new Error(
+          `Invalid position status for minting: ${loanStatusToString(
+            snapshot.status
+          )}. Must be PENDING_DEPOSIT, PENDING_MINT, or ACTIVE. Current status prevents minting operations.`
+        );
+      }
+      console.log(
+        `  \u2705 Position status valid for minting: ${loanStatusToString(
+          snapshot.status
+        )}`
+      );
+      if (snapshot.isExpired) {
+        throw new Error(
+          `Loan term expired ${snapshot.daysIntoGracePeriod} days ago - minting rejected. Must repay or extend term first.`
+        );
+      }
+      if (snapshot.isLiquidatable) {
+        throw new Error(
+          `Position is liquidatable (${bpsToPercent(
+            snapshot.collateralRatioBps
+          )}% < ${bpsToPercent(
+            snapshot.currentLiquidationThreshold
+          )}%) - minting rejected. Add collateral first.`
+        );
+      }
+      console.log("  \u2705 Position is healthy");
+      console.log(`  - Term: ${snapshot.daysUntilExpiry} days remaining`);
+      console.log(
+        `  - Current ratio: ${bpsToPercent(snapshot.collateralRatioBps)}%`
+      );
+      console.log(
+        `  - Liquidation threshold: ${bpsToPercent(
+          snapshot.currentLiquidationThreshold
+        )}%`
+      );
+      currentStep = "4";
+      console.log("[Step 4] Calculating fees...");
+      const mintFee = calculateFeeBps(amount, snapshot.originationFeeBps);
+      console.log(
+        `  Mint fee: ${mintFee.toString()} wei (${bpsToPercent(snapshot.originationFeeBps)}%)`
+      );
+      currentStep = "4a";
+      console.log("[Step 4a] Validating daily mint limit...");
+      const totalMintAmount = amount + mintFee;
+      const remainingCapacity = await Lit.Actions.call({
+        chain,
+        contractAddress: UCD_CONTROLLER_ADDRESS,
+        abi: ABI_REMAINING_MINT_CAPACITY,
+        methodName: "getRemainingMintCapacity",
+        params: []
+      });
+      const remainingCapacityBigInt = BigInt(remainingCapacity.toString());
+      if (totalMintAmount > remainingCapacityBigInt) {
+        throw new Error(
+          `Daily mint limit would be exceeded: attempting to mint ${totalMintAmount.toString()} wei (${amount.toString()} + ${mintFee.toString()} fee), but only ${remainingCapacityBigInt.toString()} wei remaining in daily capacity`
+        );
+      }
+      console.log("  \u2705 Daily mint limit check passed");
+      console.log(
+        `  - Mint amount (with fee): ${totalMintAmount.toString()} wei`
+      );
+      console.log(
+        `  - Remaining capacity: ${remainingCapacityBigInt.toString()} wei`
+      );
+      currentStep = "4b";
+      console.log("[Step 4b] Validating max supply limit...");
+      const maxSupplyResult = await Lit.Actions.call({
+        chain,
+        contractAddress: UCD_CONTROLLER_ADDRESS,
+        abi: ABI_MAX_SUPPLY,
+        methodName: "maxSupply",
+        params: []
+      });
+      const maxSupply = BigInt(maxSupplyResult.toString());
+      if (maxSupply > 0n) {
+        const currentSupplyResult = await Lit.Actions.call({
+          chain,
+          contractAddress: UCD_CONTROLLER_ADDRESS,
+          abi: ABI_CURRENT_SUPPLY,
+          methodName: "getCurrentSupply",
+          params: []
+        });
+        const currentSupply = BigInt(currentSupplyResult.toString());
+        const projectedSupply = currentSupply + totalMintAmount;
+        if (projectedSupply > maxSupply) {
+          throw new Error(
+            `Max supply would be exceeded: minting ${totalMintAmount.toString()} wei (${amount.toString()} + ${mintFee.toString()} fee) would result in total supply of ${projectedSupply.toString()} wei, exceeding max supply of ${maxSupply.toString()} wei`
+          );
+        }
+        console.log("  \u2705 Max supply check passed");
+        console.log(`  - Current supply: ${currentSupply.toString()} wei`);
+        console.log(`  - After mint: ${projectedSupply.toString()} wei`);
+        console.log(`  - Max supply: ${maxSupply.toString()} wei`);
+        console.log(
+          `  - Remaining capacity: ${(maxSupply - currentSupply).toString()} wei`
+        );
+      } else {
+        console.log("  \u2705 Max supply unlimited (not enforced)");
+      }
+      currentStep = "5";
+      console.log("[Step 5] Calculating new state...");
+      const newDebt = snapshot.ucdDebt + amount + mintFee;
+      const newCollateral = snapshot.availableBTCSats;
+      console.log(`  Current debt: ${snapshot.ucdDebt.toString()} wei`);
+      console.log(`  New debt: ${newDebt.toString()} wei`);
+      console.log(`  Available collateral: ${newCollateral.toString()} sats`);
+      currentStep = "6";
+      console.log("[Step 6] Validating collateral ratio after mint...");
+      const collateralValueUsd8Dec = calculateBtcValueUsd(
+        newCollateral,
+        snapshot.btcPriceUsd
+      );
+      const newCollateralRatioBps = calculateCollateralRatioBps(
+        collateralValueUsd8Dec,
+        newDebt
+      );
+      console.log(
+        `  New collateral ratio: ${bpsToPercent(newCollateralRatioBps)}%`
+      );
+      console.log(
+        `  Minimum required: ${bpsToPercent(snapshot.liquidationThresholdBps)}%`
+      );
+      if (!isCollateralSufficient(
+        collateralValueUsd8Dec,
+        newDebt,
+        snapshot.liquidationThresholdBps
+      )) {
+        throw new Error(
+          `Insufficient collateral: ${bpsToPercent(
+            newCollateralRatioBps
+          )}% < ${bpsToPercent(snapshot.liquidationThresholdBps)}%`
+        );
+      }
+      console.log("  \u2705 Sufficient collateral");
+      currentStep = "7";
+      console.log("[Step 7] Building authorization message...");
+      const authorizedSpendsHash = ethers.utils.keccak256(
+        // @ts-ignore - ethers available in LIT runtime
+        ethers.utils.defaultAbiCoder.encode(
+          ["uint256"],
+          // Simplified: just use total authorized amount
+          [snapshot.authorizedSpendsSats]
+        )
+      );
+      const messageParams = {
+        authorizedSpendsHash,
+        btcPrice: snapshot.btcPriceUsd.toString(),
+        mintAmount: amount.toString(),
+        mintFee: mintFee.toString(),
+        newCollateral: newCollateral.toString(),
+        newDebt: newDebt.toString()
+      };
+      const message = ethers.utils.keccak256(
+        // @ts-ignore - ethers available in LIT runtime
+        ethers.utils.defaultAbiCoder.encode(
+          [
+            "bytes32",
+            "bytes32",
+            "bytes32",
+            "bytes32",
+            "bytes32",
+            "bytes32",
+            "uint256"
+          ],
+          [
+            auth.positionId,
+            // @ts-ignore - ethers available in LIT runtime
+            ethers.utils.hexZeroPad(
+              ethers.utils.hexlify(BigInt(messageParams.authorizedSpendsHash)),
+              32
+            ),
+            // @ts-ignore - ethers available in LIT runtime
+            ethers.utils.hexZeroPad(
+              ethers.utils.hexlify(BigInt(messageParams.btcPrice)),
+              32
+            ),
+            // @ts-ignore - ethers available in LIT runtime
+            ethers.utils.hexZeroPad(
+              ethers.utils.hexlify(BigInt(messageParams.mintAmount)),
+              32
+            ),
+            // @ts-ignore - ethers available in LIT runtime
+            ethers.utils.hexZeroPad(
+              ethers.utils.hexlify(BigInt(messageParams.mintFee)),
+              32
+            ),
+            // @ts-ignore - ethers available in LIT runtime
+            ethers.utils.hexZeroPad(
+              ethers.utils.hexlify(BigInt(messageParams.newCollateral)),
+              32
+            ),
+            // @ts-ignore - ethers available in LIT runtime
+            ethers.utils.hexZeroPad(
+              ethers.utils.hexlify(BigInt(messageParams.newDebt)),
+              32
+            ),
+            auth.timestamp
+          ]
+        )
+      );
+      currentStep = "8";
+      console.log("[Step 8] Signing authorization...");
+      const signature = await Lit.Actions.signEcdsa({
+        // @ts-ignore - ethers available in LIT runtime
+        toSign: ethers.utils.arrayify(message),
+        publicKey,
+        sigName: "ucdMintAuth"
+      });
+      console.log("[UCD Mint Validator] \u2705 Complete");
+      Lit.Actions.setResponse({
+        response: JSON.stringify({
+          approved: true,
+          positionId: auth.positionId,
+          mintAmount: amount.toString(),
+          mintFee: mintFee.toString(),
+          newDebt: newDebt.toString(),
+          newCollateral: newCollateral.toString(),
+          newCollateralRatioBps,
+          btcPrice: snapshot.btcPriceUsd.toString(),
+          authorizedSpendsHash,
+          signature,
+          timestamp: auth.timestamp,
+          validatorPkp: publicKey
+        })
+      });
+    } catch (error) {
+      console.error("[UCD Mint Validator] \u274C Failed:", error.message);
+      console.error(`[UCD Mint Validator] Failed at step: ${currentStep}`);
+      Lit.Actions.setResponse({
+        response: JSON.stringify({
+          approved: false,
+          reason: error.message || error.toString(),
+          failedStep: currentStep,
+          positionId: auth?.positionId,
+          timestamp: Date.now()
+        })
+      });
+    }
+  };
+  go();
+})();