@gvnrdao/dh-sdk 0.0.337 → 0.0.338

package/dist/sign-guard.mjs

@@ -0,0 +1,941 @@
+// src/utils/sign-guard/errors.ts
+var TxValidationError = class extends Error {
+  constructor(msg) {
+    super(`Refusing to sign server-returned transaction: ${msg}`);
+    this.name = "TxValidationError";
+  }
+};
+
+// src/utils/sign-guard/signable-functions.ts
+import { ethers } from "ethers";
+var SIGNABLE_FUNCTIONS = [
+  "function mintUCD(bytes32 positionId, uint256 mintAmount, uint256 mintFee, uint256 newDebt, uint256 newCollateral, uint256 btcPrice, bytes32 authorizedSpendsHash, bytes32 ucdDebtHash, bytes32 contractHash, uint256 quantumTimestamp, bytes calldata mintValidatorSignature) external returns (bool)",
+  // `makePayment` is the ONLY repayment entry point. A `repayPosition` entry
+  // used to sit here; it is not a function on any deployed contract — the
+  // compiled PositionManager ABI has no `repay*` function at all, and the name
+  // survives only in `archive/` prototypes. Nothing in lit-ops-server, the
+  // lit-actions, or the SDK ever emitted it, and AgentModule never whitelisted
+  // it. A signable-function whitelist should not carry calldata shapes the
+  // protocol cannot execute.
+  "function makePayment(bytes32 positionId, uint256 paymentAmount, uint256 quantumTimestamp, uint256 btcPrice, bytes calldata paymentValidatorSignature) external returns (bool)",
+  "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, uint256 proRataRenewalFee, bytes calldata extensionValidatorSignature) external returns (bool)",
+  "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, bytes calldata extensionValidatorSignature) external returns (bool)",
+  // Struct-version: matches the actual on-chain function signature and the
+  // SDK's calldata builder. An earlier 3-arg declaration was stale and would
+  // silently fail to decode real `withdrawBTC` calldata. networkFee is NOT a
+  // contract param — it is an off-chain Phase-2 BTC tx fee, validated elsewhere.
+  "function withdrawBTC((bytes32 positionId, bytes32 actionHash, bytes32 authorizedSpendsHash, bytes32 ucdDebtHash, bytes32 contractBundleHash, string withdrawalAddress, uint256 totalDeduction, uint256 newCollateral, uint256 quantumTimestamp, uint256 btcPrice, string utxoTxid, uint32 utxoVout) params, bytes withdrawalValidatorSignature, bytes btcSpendAuthSignature) external returns (bool)",
+  // `cancelStaleSpendByOwner` removed in audit #62210 follow-up — the on-chain
+  // function reverts permanently. The trustless replacement
+  // (`cancelStaleSpendWithProof` on BTCSpendAuthorizer) lands via a separate
+  // entry when its LIT Action ships.
+  "function approve(address spender, uint256 amount) external returns (bool)",
+  "function setPositionDelegate(bytes32 positionId, address newDelegate) external",
+  // Position creation. Signed opaquely by the SDK (like withdrawBTC), so
+  // without an entry here it decoded as "<unparseable>" and the CLI's
+  // WithdrawGuard waved it through — the flow that locks the user's BTC
+  // collateral had no client-side pin at all.
+  "function createPosition(bytes32 pkpId, bytes calldata validatorSignature, string mainnetVaultAddress, string regtestVaultAddress, uint256 selectedTermMonths, uint256 validatorVersion, bytes calldata pkpPublicKey) external returns (bytes32 positionId)",
+  // SimplePSMV2 — the PSM exchange pair. Direct EOA calls, never routed through
+  // AgentModule; the parity test documents them as client-only.
+  "function swap(address stablecoin, uint256 amountIn, uint256 minUcdOut) external returns (uint256)",
+  "function redeem(address stablecoin, uint256 ucdAmount, uint256 minStablecoinOut) external returns (uint256)",
+  // BitcoinWithdrawalAddressRegistry — `msg.sender` must be the borrower, so
+  // this too is client-only and never module-whitelisted.
+  "function addAddress(string btcAddress) external"
+];
+var IFACE = new ethers.Interface(SIGNABLE_FUNCTIONS);
+function encodeSignable(fn, args) {
+  return IFACE.encodeFunctionData(fn, args);
+}
+function decodeSignable(data) {
+  try {
+    const parsed = IFACE.parseTransaction({ data });
+    if (!parsed) {
+      throw new TxValidationError(
+        `unsignedTx.data does not decode against the signable-function whitelist`
+      );
+    }
+    return { name: parsed.name, args: parsed.args };
+  } catch (e) {
+    if (e instanceof TxValidationError)
+      throw e;
+    throw new TxValidationError(
+      `unsignedTx.data does not decode against the signable-function whitelist: ${e.message}`
+    );
+  }
+}
+function signableFunctionName(data) {
+  try {
+    const parsed = IFACE.parseTransaction({ data });
+    return parsed ? parsed.name : "<unparseable>";
+  } catch {
+    return "<unparseable>";
+  }
+}
+function signableSelectors() {
+  const out = /* @__PURE__ */ new Map();
+  IFACE.forEachFunction((fn) => out.set(fn.selector, fn.format("sighash")));
+  return out;
+}
+
+// src/utils/sign-guard/fee-ceiling.ts
+import { ethers as ethers2 } from "ethers";
+var MAX_GAS_LIMIT = 5000000n;
+var MAX_FEE_PER_GAS_WEI = 2000000000000n;
+var DEFAULT_MAX_TX_FEE_WEI = 250000000000000000n;
+var DEFAULT_FEE_CEILING = {
+  maxGasLimit: MAX_GAS_LIMIT,
+  maxFeePerGasWei: MAX_FEE_PER_GAS_WEI,
+  maxTxFeeWei: DEFAULT_MAX_TX_FEE_WEI
+};
+function fmtEth(wei) {
+  return `${ethers2.formatEther(wei)} ETH`;
+}
+function fmtGwei(wei) {
+  return `${ethers2.formatUnits(wei, "gwei")} gwei`;
+}
+function worstCaseFeeWei(gasLimit, maxFeePerGas) {
+  if (gasLimit == null || maxFeePerGas == null)
+    return null;
+  return gasLimit * maxFeePerGas;
+}
+function assertFeeCeiling(gasLimit, maxFeePerGas, raise, ceiling = DEFAULT_FEE_CEILING) {
+  if (gasLimit != null && gasLimit > ceiling.maxGasLimit) {
+    raise(`gasLimit ${gasLimit} exceeds the signing ceiling of ${ceiling.maxGasLimit}`);
+  }
+  if (maxFeePerGas != null && maxFeePerGas > ceiling.maxFeePerGasWei) {
+    raise(
+      `maxFeePerGas ${fmtGwei(maxFeePerGas)} exceeds the signing ceiling of ${fmtGwei(ceiling.maxFeePerGasWei)}`
+    );
+  }
+  const worst = worstCaseFeeWei(gasLimit, maxFeePerGas);
+  if (worst != null && worst > ceiling.maxTxFeeWei) {
+    raise(
+      `worst-case transaction fee ${fmtEth(worst)} (gasLimit ${gasLimit} \xD7 ${fmtGwei(maxFeePerGas)}) exceeds the signing ceiling of ${fmtEth(ceiling.maxTxFeeWei)}.${ceiling.raiseHint ? ` ${ceiling.raiseHint}` : ""}`
+    );
+  }
+}
+
+// src/utils/sign-guard/tx-validator.ts
+import { ethers as ethers3 } from "ethers";
+
+// src/constants/chunks/deployment-addresses.ts
+var SEPOLIA_CONTRACTS = {
+  UpgradeValidator: "0x592e650edD9bA26ecc407989fdd6F9cdcDeC27A6",
+  UCDToken: "0xdd817Ff47C9b8f81335Ac579895D8EA321Fa86Df",
+  UCDController: "0x360Bde4e489ee94E26601B206932De09EE60FF04",
+  PriceFeedConsumer: "0xb3Dc64501935a6f0334779126Ee37bE463cee318",
+  PositionManagerCoreModule: "0xfFAA39a08887FeFB697eBC8691A8630CbCC33391",
+  TermManagerModule: "0x94Adc6F9558368B1482197584f1fc7133Ecf835b",
+  LoanOperationsManagerModule: "0x3e05e760a87715207b7F4e8fD35EF7559BcA72C0",
+  CollateralManagerModule: "0x967E92c976Fc0fa8268D37D4d6B7245d912aA7dB",
+  LiquidationManagerModule: "0xC4AB00f39e7ceD812F5C67058C9fa44e15d40e76",
+  CircuitBreakerModule: "0x3D0B2cAE481821E57BA9CC3807bCC0d0D7F18bd8",
+  AdminModule: "0xAcd1f07915b17CA3727e7fE89BdF618A1545a1ed",
+  PositionManagerViews: "0x3b970E41a0668508B4B2ACb83653b2A402F745AE",
+  PositionManager: "0x68e0507D982AEBF1D1C1Af8FBbd842327e2deeFF",
+  OperationAuthorizationRegistry: "0x75f36E772df9616d40b02092642744D6fd702Df8",
+  PKPValidation: "0x8a1365A974F91e92D2dF5C51216EFCD408e209A8",
+  BTCSpendAuthorizer: "0xd7E9Eb5eE53f1d9ee55Dc162bBC7486bE437B6bD",
+  LITActionValidator: "0x54eECd7C90F8A8fac27749Ba30BbE8AFBAccc856",
+  SimplePSMV2: "0x19EcF7BA26e054fd4Ff06009A03070103dbBB058",
+  BitcoinProviderRegistry: "0xbfA0c48B070D0a9A9CD27469AeacFD2d4261cEE2",
+  ContractVersionRegistry: "0x97E43AA6aFF2C0cf659d3aE501658D2Ef6777522",
+  mockUsdcToken: "0x96409A98e0D322d6566b7F44a0fAbD1BD4ce2AEc",
+  mockUsdtToken: "0xF8b7fB38b17a310960E47805Be9adba0b0e0394D",
+  PositionDelegateRegistry: "0x482369De283622E7b05731875ec137d4E3D208F9",
+  FeeRecipientRegistry: "0x95795F8403DDb629E8527B2934C4e71f5fC0C374",
+  BitcoinWithdrawalAddressRegistry: "0x6376D392097F0A81e51BD83960A97EA20eaf1dbe",
+  CarryAgentRegistry: "0x5595CB538D44E6Cf179D20364fD631D0477e69f7",
+  AgentDelegationRegistry: "0x6AE7fc6bE0925126b9D25b1B7Ce5AD5d127ec025",
+  DHAgentDelegate: "0xa5A14489ae883960df6E1463A41a47aBE9Ecc5AF",
+  AgentModuleFactory: "0x1Fd3aCa2C030Cf77ce28Af9694D3Bb3034ACa2E5"
+};
+var MAINNET_CONTRACTS = {
+  MessageHashBuilder: "0xaDE074023F9e87f6AEaF679e36B5d7B93FA22269",
+  LITActionValidator: "0xD2c5d59c2CC5c409AC65ce0A817236aeC6869512",
+  UpgradeValidator: "0xC46Ae71F22e3741A6CF46E399aE914C4868fEbed",
+  UCDToken: "0xaAaB6B05E5EecB015898483d4e6703d7F218850b",
+  UCDController: "0x4b4f8063048bCD59D469219E3f07C6aaDF4f6157",
+  PositionManagerCoreModule: "0xd895B685914c1BE4e1c7aab9f89a90c203DE8d22",
+  TermManagerModule: "0xDB99CdF883ffa38acD099bC39F8d1f4508c9239E",
+  LoanOperationsManagerModule: "0x2561974A40F1AEed1251d0A090A83cF8536FB9E9",
+  BTCSpendAuthorizer: "0xfBbF108486fa07F1B06a811C5b66ed68DD9c508a",
+  CollateralManagerModule: "0x2Eb74FEc478218f5C260aAc78Bb8eC297F9d7135",
+  LiquidationManagerModule: "0x74B28695352E7bf736D6c9F76ccb7B4439477De9",
+  CircuitBreakerModule: "0xF7b545d3a4Ee056D06909AB367E2F7bFFE3cB1BC",
+  AdminModule: "0x0023B71B586795eE5fa4E83E384345C1EC8Bb946",
+  PositionManagerViews: "0x8B57954eA338c6A6bfF1457f71080e25baFF3937",
+  PositionManager: "0x12A1836e56139ccaD8722B89519d84233efc224B",
+  OperationAuthorizationRegistry: "0xD4505645b724754f5170a2027804a4265e860d44",
+  ContractVersionRegistry: "0x5e18f77d01940dA5B1D986D373D9A6ad0767008d",
+  FeeRecipientRegistry: "0x8fbCAAdA198E1C246ecEb2fB021C5A3d8050c6B3",
+  PositionDelegateRegistry: "0xf0aa2678aD4F60f49e8F7725089B5E86B7F8FE4C",
+  BitcoinProviderRegistry: "0x4ab3Fb96e02893Ed6FAa61bad1918390c8DbbFFC",
+  BitcoinWithdrawalAddressRegistry: "0xf667f77FDba7458345f227eB6Bfe4148243E7270",
+  SimplePSMV2: "0xfE0C14B4E614f40Bf58845b4B04CeD17fd116532",
+  PKPValidation: "0x29922d3ccb86516f6C24F89f1eb3068655ca7Fa0",
+  AgentDelegationRegistry: "0x54853b7E91ce2Be34ce65655D80c4447e67187Fa",
+  DHAgentDelegate: "0x70232d0caBe529e29a01A442423d7e03BBd414c8"
+};
+var LOCALHOST_CONTRACTS = {
+  MessageHashBuilder: "0xa82fF9aFd8f496c3d6ac40E2a0F282E47488CFc9",
+  LITActionValidator: "0xa513E6E4b8f2a923D98304ec87F64353C4D5C853",
+  UpgradeValidator: "0x8A791620dd6260079BF849Dc5567aDC3F2FdC318",
+  UCDToken: "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
+  UCDController: "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
+  PositionManagerCoreModule: "0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e",
+  TermManagerModule: "0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82",
+  LoanOperationsManagerModule: "0x68B1D87F95878fE05B998F19b66F4baba5De1aed",
+  BTCSpendAuthorizer: "0xc6e7DF5E7b4f2A278906862b61205850344D4e7d",
+  CollateralManagerModule: "0x322813Fd9A801c5507c9de605d63CEA4f2CE6c44",
+  LiquidationManagerModule: "0x4A679253410272dd5232B3Ff7cF5dbB88f295319",
+  CircuitBreakerModule: "0x0B306BF915C4d645ff596e518fAf3F9669b97016",
+  AdminModule: "0x09635F643e140090A9A8Dcd712eD6285858ceBef",
+  PositionManagerViews: "0x959922bE3CAee4b8Cd9a407cc3ac1C251C2007B1",
+  PositionManager: "0x851356ae760d987E095750cCeb3bC6014560891C",
+  OperationAuthorizationRegistry: "0xc96304e3c037f81dA488ed9dEa1D8F2a48278a75",
+  PKPValidation: "0xD0141E899a65C95a556fE2B27e5982A6DE7fDD7A"
+};
+var ALL_CONTRACTS = {
+  sepolia: SEPOLIA_CONTRACTS,
+  mainnet: MAINNET_CONTRACTS,
+  localhost: LOCALHOST_CONTRACTS
+};
+function getContractsByNetwork(network) {
+  return ALL_CONTRACTS[network] || null;
+}
+
+// src/utils/sign-guard/tx-validator.ts
+function buildValidationContext(network, chainId, feeCeiling) {
+  const sdkKey = chainId === 31337 ? "localhost" : chainId === 11155111 ? "sepolia" : network.toLowerCase();
+  const contracts = getContractsByNetwork(sdkKey);
+  if (!contracts) {
+    throw new TxValidationError(
+      `no SDK contract registry for network='${network}' chainId=${chainId} (sdkKey='${sdkKey}')`
+    );
+  }
+  return feeCeiling ? { chainId, network, contracts, feeCeiling } : { chainId, network, contracts };
+}
+function eqAddr(a, b) {
+  if (!a || !b)
+    return false;
+  try {
+    return ethers3.getAddress(a) === ethers3.getAddress(b);
+  } catch {
+    return false;
+  }
+}
+function readToAddress(tx) {
+  const to = tx["to"];
+  if (typeof to !== "string") {
+    throw new TxValidationError(`unsignedTx.to is missing or not a string`);
+  }
+  return to;
+}
+function readData(tx) {
+  const data = tx["data"];
+  if (typeof data !== "string" || !data.startsWith("0x")) {
+    throw new TxValidationError(`unsignedTx.data missing or malformed`);
+  }
+  return data;
+}
+function readChainId(tx) {
+  const c = tx["chainId"];
+  if (c == null)
+    return null;
+  if (typeof c === "number")
+    return c;
+  if (typeof c === "string")
+    return parseInt(c.startsWith("0x") ? c.slice(2) : c, c.startsWith("0x") ? 16 : 10);
+  if (typeof c === "bigint")
+    return Number(c);
+  return null;
+}
+function readOptionalBigInt(tx, key) {
+  const v = tx[key];
+  if (v == null)
+    return null;
+  try {
+    if (typeof v === "bigint")
+      return v;
+    if (typeof v === "number")
+      return BigInt(v);
+    if (typeof v === "string")
+      return BigInt(v);
+    return BigInt(v.toString());
+  } catch {
+    throw new TxValidationError(`unsignedTx.${key} is present but not a valid integer`);
+  }
+}
+function readValue(tx) {
+  const v = tx["value"];
+  if (v == null)
+    return 0n;
+  if (typeof v === "string")
+    return BigInt(v);
+  if (typeof v === "number")
+    return BigInt(v);
+  if (typeof v === "bigint")
+    return v;
+  const maybe = v;
+  if (typeof maybe.toBigInt === "function")
+    return maybe.toBigInt();
+  if (typeof maybe.toString === "function")
+    return BigInt(maybe.toString());
+  throw new TxValidationError(`unsignedTx.value has unrecognized type`);
+}
+function normalizePositionId(id) {
+  const hex = id.startsWith("0x") ? id : `0x${id}`;
+  return ethers3.zeroPadValue(hex, 32).toLowerCase();
+}
+function requirePositionId(actual, expected) {
+  const txPositionId = String(actual).toLowerCase();
+  if (txPositionId !== normalizePositionId(expected)) {
+    throw new TxValidationError(
+      `positionId mismatch \u2014 tx ${txPositionId}, expected ${normalizePositionId(expected)}`
+    );
+  }
+}
+function validateUnsignedTx(unsignedTx, expected, vctx) {
+  const txChainId = readChainId(unsignedTx);
+  if (txChainId == null) {
+    throw new TxValidationError(
+      `unsignedTx.chainId is missing \u2014 refusing to sign a transaction with no chain binding (client is on ${vctx.chainId})`
+    );
+  }
+  if (txChainId !== vctx.chainId) {
+    throw new TxValidationError(
+      `chainId mismatch \u2014 tx says ${txChainId}, client is on ${vctx.chainId}`
+    );
+  }
+  const value = readValue(unsignedTx);
+  if (value !== 0n) {
+    throw new TxValidationError(
+      `unsignedTx.value is non-zero (${value}); none of the protocol functions accept ETH`
+    );
+  }
+  assertFeeCeiling(
+    readOptionalBigInt(unsignedTx, "gasLimit"),
+    readOptionalBigInt(unsignedTx, "maxFeePerGas") ?? readOptionalBigInt(unsignedTx, "gasPrice"),
+    (msg) => {
+      throw new TxValidationError(msg);
+    },
+    vctx.feeCeiling
+  );
+  const to = readToAddress(unsignedTx);
+  const data = readData(unsignedTx);
+  const { name, args } = decodeSignable(data);
+  const pm = vctx.contracts.PositionManager;
+  switch (expected.kind) {
+    case "mint": {
+      if (name !== "mintUCD") {
+        throw new TxValidationError(`expected mintUCD, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`mintUCD must target PositionManager (${pm}), got ${to}`);
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txMintAmount = BigInt(String(args[1]));
+      if (txMintAmount.toString() !== expected.amountWei) {
+        throw new TxValidationError(`mintAmount mismatch \u2014 tx ${txMintAmount}, expected ${expected.amountWei}`);
+      }
+      const txMintFee = BigInt(String(args[2]));
+      if (txMintFee.toString() !== expected.mintFeeWei) {
+        throw new TxValidationError(`mintFee mismatch \u2014 tx ${txMintFee}, expected ${expected.mintFeeWei}`);
+      }
+      break;
+    }
+    case "repay": {
+      if (name !== "makePayment") {
+        throw new TxValidationError(`expected makePayment, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`${name} must target PositionManager (${pm}), got ${to}`);
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txAmount = BigInt(String(args[1]));
+      if (txAmount.toString() !== expected.amountWei) {
+        throw new TxValidationError(`paymentAmount mismatch \u2014 tx ${txAmount}, expected ${expected.amountWei}`);
+      }
+      break;
+    }
+    case "extend": {
+      if (name !== "extendPosition") {
+        throw new TxValidationError(`expected extendPosition, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`extendPosition must target PositionManager (${pm}), got ${to}`);
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txTerm = Number(args[1]);
+      if (txTerm !== expected.selectedTerm) {
+        throw new TxValidationError(`selectedTerm mismatch \u2014 tx ${txTerm}, expected ${expected.selectedTerm}`);
+      }
+      if (expected.upperBoundProRataFeeWei != null && args.length >= 7) {
+        const txFee = BigInt(String(args[5]));
+        const upper = BigInt(expected.upperBoundProRataFeeWei);
+        if (txFee > upper) {
+          throw new TxValidationError(
+            `proRataRenewalFee=${txFee} exceeds upper bound=${upper}. A compromised validator could otherwise inflate the fee to drain UCD.`
+          );
+        }
+      }
+      break;
+    }
+    case "withdraw-btc": {
+      if (name !== "withdrawBTC") {
+        throw new TxValidationError(`expected withdrawBTC, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`withdrawBTC must target PositionManager (${pm}), got ${to}`);
+      }
+      const paramsTuple = args[0];
+      requirePositionId(paramsTuple[0], expected.positionId);
+      const txWithdrawalAddress = String(paramsTuple[5]);
+      if (txWithdrawalAddress !== expected.btcAddress) {
+        throw new TxValidationError(`btcAddress mismatch \u2014 tx '${txWithdrawalAddress}', expected '${expected.btcAddress}'`);
+      }
+      if (expected.upperBoundTotalDeduction != null) {
+        const txDeduction = BigInt(String(paramsTuple[6]));
+        const upper = BigInt(expected.upperBoundTotalDeduction);
+        if (txDeduction > upper) {
+          throw new TxValidationError(
+            `totalDeduction=${txDeduction} exceeds approved upper bound=${upper}. A compromised validator could otherwise drain collateral beyond the approved amount.`
+          );
+        }
+      }
+      break;
+    }
+    case "ucd-approve": {
+      if (name !== "approve") {
+        throw new TxValidationError(`expected ERC-20 approve, server returned ${name}`);
+      }
+      const ucd = vctx.contracts.UCDToken;
+      if (!eqAddr(to, ucd)) {
+        throw new TxValidationError(`approve must target UCDToken (${ucd}), got ${to}`);
+      }
+      const spender = String(args[0]);
+      const ok = expected.spenderCandidates.some((s) => eqAddr(spender, s));
+      if (!ok) {
+        throw new TxValidationError(
+          `approve spender ${spender} not in expected set ${expected.spenderCandidates.join(", ")}`
+        );
+      }
+      const amt = BigInt(String(args[1]));
+      const min = BigInt(expected.minAmountWei);
+      if (amt < min) {
+        throw new TxValidationError(`approve amount ${amt} is less than required ${min}`);
+      }
+      const SANITY_MAX = min * 1000n;
+      if (amt > SANITY_MAX) {
+        throw new TxValidationError(`approve amount ${amt} exceeds sanity cap ${SANITY_MAX} (1000x requested)`);
+      }
+      break;
+    }
+    case "create-position": {
+      if (name !== "createPosition") {
+        throw new TxValidationError(`expected createPosition, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`createPosition must target PositionManager (${pm}), got ${to}`);
+      }
+      const txTerm = BigInt(String(args[4]));
+      if (txTerm !== BigInt(expected.selectedTerm)) {
+        throw new TxValidationError(`selectedTerm mismatch \u2014 tx ${txTerm}, expected ${expected.selectedTerm}`);
+      }
+      break;
+    }
+    case "set-position-delegate": {
+      if (name !== "setPositionDelegate") {
+        throw new TxValidationError(`expected setPositionDelegate, server returned ${name}`);
+      }
+      if (!eqAddr(to, expected.registryAddress)) {
+        throw new TxValidationError(
+          `setPositionDelegate must target PositionDelegateRegistry (${expected.registryAddress}), got ${to}`
+        );
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txDelegate = String(args[1]);
+      if (!eqAddr(txDelegate, expected.delegate)) {
+        throw new TxValidationError(`delegate mismatch \u2014 tx ${txDelegate}, expected ${expected.delegate}`);
+      }
+      break;
+    }
+    case "bwar-add-address": {
+      if (name !== "addAddress") {
+        throw new TxValidationError(`expected addAddress, decoded ${name}`);
+      }
+      if (!eqAddr(to, expected.registryAddress)) {
+        throw new TxValidationError(
+          `addAddress must target the BitcoinWithdrawalAddressRegistry (${expected.registryAddress}), got ${to}`
+        );
+      }
+      if (String(args[0]) !== expected.btcAddress) {
+        throw new TxValidationError(
+          `btcAddress mismatch \u2014 tx says '${String(args[0])}', user asked for '${expected.btcAddress}'`
+        );
+      }
+      break;
+    }
+    case "stablecoin-approve": {
+      if (name !== "approve") {
+        throw new TxValidationError(`expected ERC-20 approve, server returned ${name}`);
+      }
+      if (!eqAddr(to, expected.tokenAddress)) {
+        throw new TxValidationError(`approve must target the stablecoin token (${expected.tokenAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.spender)) {
+        throw new TxValidationError(`approve spender must be the PSM (${expected.spender}), got ${String(args[0])}`);
+      }
+      if (BigInt(String(args[1])).toString() !== expected.amountUnits) {
+        throw new TxValidationError(
+          `approve amount must be EXACTLY ${expected.amountUnits} (exact-amount rule), got ${BigInt(String(args[1]))}`
+        );
+      }
+      break;
+    }
+    case "ucd-approve-controller": {
+      if (name !== "approve") {
+        throw new TxValidationError(`expected ERC-20 approve, server returned ${name}`);
+      }
+      if (!eqAddr(to, expected.ucdTokenAddress)) {
+        throw new TxValidationError(`approve must target UCDToken (${expected.ucdTokenAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.spender)) {
+        throw new TxValidationError(`approve spender must be the UCDController (${expected.spender}), got ${String(args[0])}`);
+      }
+      if (BigInt(String(args[1])).toString() !== expected.amountWei) {
+        throw new TxValidationError(
+          `approve amount must be EXACTLY ${expected.amountWei} (exact-amount rule), got ${BigInt(String(args[1]))}`
+        );
+      }
+      break;
+    }
+    case "psm-swap": {
+      if (name !== "swap")
+        throw new TxValidationError(`expected swap, server returned ${name}`);
+      if (!eqAddr(to, expected.psmAddress)) {
+        throw new TxValidationError(`swap must target the PSM (${expected.psmAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.stablecoin))
+        throw new TxValidationError(`swap stablecoin mismatch`);
+      if (BigInt(String(args[1])).toString() !== expected.amountIn)
+        throw new TxValidationError(`swap amountIn mismatch`);
+      if (BigInt(String(args[2])).toString() !== expected.minOut)
+        throw new TxValidationError(`swap minUcdOut mismatch`);
+      if (BigInt(expected.minOut) === 0n) {
+        throw new TxValidationError(`swap minUcdOut is 0 \u2014 a slippage floor is mandatory (SlippageProtectionRequired)`);
+      }
+      break;
+    }
+    case "psm-redeem": {
+      if (name !== "redeem")
+        throw new TxValidationError(`expected redeem, server returned ${name}`);
+      if (!eqAddr(to, expected.psmAddress)) {
+        throw new TxValidationError(`redeem must target the PSM (${expected.psmAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.stablecoin))
+        throw new TxValidationError(`redeem stablecoin mismatch`);
+      if (BigInt(String(args[1])).toString() !== expected.amountUcdWei)
+        throw new TxValidationError(`redeem ucdAmount mismatch`);
+      if (BigInt(String(args[2])).toString() !== expected.minOut)
+        throw new TxValidationError(`redeem minStablecoinOut mismatch`);
+      if (BigInt(expected.minOut) === 0n) {
+        throw new TxValidationError(`redeem minStablecoinOut is 0 \u2014 a slippage floor is mandatory (SlippageProtectionRequired)`);
+      }
+      break;
+    }
+    default: {
+      const _exhaustive = expected;
+      throw new TxValidationError(`unhandled expected action kind: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+function readTxFeeFields(unsignedTx) {
+  try {
+    return {
+      gasLimit: readOptionalBigInt(unsignedTx, "gasLimit"),
+      maxFeePerGas: readOptionalBigInt(unsignedTx, "maxFeePerGas") ?? readOptionalBigInt(unsignedTx, "gasPrice")
+    };
+  } catch {
+    return { gasLimit: null, maxFeePerGas: null };
+  }
+}
+function describeUnsignedTx(unsignedTx) {
+  const to = readToAddress(unsignedTx);
+  const data = readData(unsignedTx);
+  return { to, fn: signableFunctionName(data), chainId: readChainId(unsignedTx) };
+}
+
+// src/utils/sign-guard/op-envelope.ts
+import { ethers as ethers4 } from "ethers";
+
+// src/utils/quantum-timing.ts
+var QUANTUM_WINDOW_SECONDS = 60;
+var SLOT_SECONDS = 12;
+var INCLUSION_SLOT_TOLERANCE = 3;
+var INCLUSION_LATENCY_BUDGET = SLOT_SECONDS * INCLUSION_SLOT_TOLERANCE;
+
+// src/utils/sign-guard/op-envelope.ts
+var QUANTUM_SECONDS = QUANTUM_WINDOW_SECONDS;
+var AUTH_VALIDITY_WINDOWS = 3;
+function authValiditySec() {
+  return QUANTUM_SECONDS * AUTH_VALIDITY_WINDOWS;
+}
+function nextQuantumTimestamp(nowMs = Date.now()) {
+  const now = Math.floor(nowMs / 1e3);
+  const currentQuantum = Math.floor(now / QUANTUM_SECONDS) * QUANTUM_SECONDS;
+  return currentQuantum + QUANTUM_SECONDS;
+}
+function isAuthFresh(issuedAtSec, nowSec) {
+  return issuedAtSec <= nowSec && nowSec - issuedAtSec < authValiditySec();
+}
+function isStrictCurrentQuantum(issuedAtSec, nowSec) {
+  return issuedAtSec <= nowSec && Math.floor(issuedAtSec / QUANTUM_SECONDS) === Math.floor(nowSec / QUANTUM_SECONDS);
+}
+function modeForChainId(chainId) {
+  return chainId === 1 ? "prod" : "dev";
+}
+function randomNonceHex(byteLength = 16) {
+  return ethers4.hexlify(ethers4.randomBytes(byteLength));
+}
+var OP_ENVELOPE_LAYOUT = "dh-op-envelope-v1";
+var OP_ENVELOPE_TYPES = ["bytes32", "uint256", "uint256", "uint256", "bytes32"];
+var OP_ENVELOPE_FIELD_ORDER = ["positionId", "timestamp", "chainId", "amount", "action"];
+function stampOpEnvelope(input, quantumTs) {
+  const actionHash = ethers4.keccak256(ethers4.toUtf8Bytes(input.action));
+  const hashHex = ethers4.solidityPackedKeccak256(
+    [...OP_ENVELOPE_TYPES],
+    [input.positionId, quantumTs, input.chainId, input.value, actionHash]
+  );
+  return {
+    fields: {
+      positionId: input.positionId,
+      timestamp: String(quantumTs),
+      chainId: String(input.chainId),
+      amount: input.value.toString(),
+      action: input.action
+    },
+    hashHex
+  };
+}
+async function buildAuthEnvelope(opts) {
+  const timestamp = nextQuantumTimestamp(opts.nowMs);
+  const { hashHex } = stampOpEnvelope(
+    { positionId: opts.positionId, chainId: opts.chainId, value: opts.value, action: opts.action },
+    timestamp
+  );
+  const userSignature = await opts.signAuthMessage(hashHex);
+  return {
+    borrowerAddress: opts.borrowerAddress,
+    userSignature,
+    authMessage: {
+      positionId: opts.positionId,
+      timestamp,
+      chainId: opts.chainId,
+      ...opts.payload,
+      action: opts.action,
+      mode: modeForChainId(opts.chainId),
+      nonce: randomNonceHex()
+    }
+  };
+}
+
+// src/utils/sign-guard/op-specs.ts
+var DELEGATED_OPS = {
+  mint: {
+    action: "mint-ucd",
+    executePath: "/api/lit/mint/execute",
+    payloadKey: "amount",
+    broadcastMetaKey: "mintMeta",
+    refusalMessage: "Mint authorization failed"
+  },
+  repay: {
+    action: "make-payment",
+    executePath: "/api/lit/repay/execute",
+    payloadKey: "paymentAmount",
+    broadcastMetaKey: "repayMeta",
+    refusalMessage: "Repay authorization failed"
+  },
+  renew: {
+    action: "extend-position",
+    executePath: "/api/lit/renew/execute",
+    payloadKey: "newTerm",
+    broadcastMetaKey: "renewMeta",
+    refusalMessage: "Renew authorization failed"
+  }
+};
+var BROADCAST_PATH = "/api/lit/broadcast";
+
+// src/utils/service-endpoint-policy.ts
+function assertSafeServiceEndpoint(endpoint) {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    throw new Error(`Invalid serviceEndpoint: ${endpoint}`);
+  }
+  if (url.protocol === "https:")
+    return;
+  if (url.protocol === "http:") {
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1" || // IPv4 loopback range 127.0.0.0/8 (numeric — not resolvable/hijackable).
+    // Each of the trailing three octets must be a valid 0–255 value.
+    /^127\.(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){2}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/.test(host);
+    if (isLoopback)
+      return;
+    throw new Error(
+      `Refusing to use plaintext http:// for non-loopback endpoint: ${endpoint}. Bearer tokens and signed transactions would travel in cleartext. Use https://\u2026 or run the lit-ops-server on localhost.`
+    );
+  }
+  throw new Error(
+    `Unsupported serviceEndpoint protocol '${url.protocol}': ${endpoint}. Use https:// (or http://localhost for development).`
+  );
+}
+
+// src/utils/sign-guard/lit-ops-client.ts
+var REQUEST_TIMEOUT_MS = 6e4;
+var LitOpsHttpError = class extends Error {
+  status;
+  url;
+  body;
+  constructor(url, status, body) {
+    super(`POST ${url} \u2192 HTTP ${status}: ${body.slice(0, 500)}`);
+    this.name = "LitOpsHttpError";
+    this.status = status;
+    this.url = url;
+    this.body = body;
+  }
+};
+var LitOpsTransportError = class extends Error {
+  url;
+  constructor(url, cause) {
+    super(`lit-ops-server unreachable at ${url}: ${cause.message}`);
+    this.name = "LitOpsTransportError";
+    this.url = url;
+  }
+};
+async function fetchWithTimeout(url, init, timeoutMs = REQUEST_TIMEOUT_MS, fetchImpl = (...a) => fetch(...a)) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetchImpl(url, { ...init, signal: controller.signal });
+  } catch (e) {
+    if (e.name === "AbortError") {
+      throw new Error(`Request to ${url} timed out after ${Math.round(timeoutMs / 1e3)}s`);
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function postJson(url, body, headers, opts = {}) {
+  let resp;
+  try {
+    resp = await fetchWithTimeout(
+      url,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify(body)
+      },
+      opts.timeoutMs,
+      opts.fetchImpl
+    );
+  } catch (e) {
+    if (/timed out/.test(e.message))
+      throw e;
+    throw new LitOpsTransportError(url, e);
+  }
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new LitOpsHttpError(url, resp.status, text);
+  }
+  try {
+    return await resp.json();
+  } catch (e) {
+    throw new Error(`POST ${url} returned non-JSON body: ${e.message}`);
+  }
+}
+function asEnvelope(raw, label) {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error(`${label}: server returned ${raw === null ? "null" : typeof raw}, expected an object`);
+  }
+  const env = raw;
+  if (typeof env["success"] !== "boolean") {
+    throw new Error(`${label}: server response is missing a boolean 'success' field`);
+  }
+  if (env["data"] !== void 0 && (typeof env["data"] !== "object" || env["data"] === null)) {
+    throw new Error(`${label}: server response 'data' is not an object`);
+  }
+  const out = { success: env["success"] };
+  if (env["data"] !== void 0)
+    out.data = env["data"];
+  if (typeof env["error"] === "string")
+    out.error = env["error"];
+  return out;
+}
+async function authorizeWithServer(opts) {
+  assertSafeServiceEndpoint(opts.serviceEndpoint);
+  let execJson;
+  try {
+    const raw = await postJson(
+      `${opts.serviceEndpoint}${opts.executePath}`,
+      {
+        authMessage: opts.envelope.authMessage,
+        userSignature: opts.envelope.userSignature,
+        borrowerAddress: opts.envelope.borrowerAddress
+      },
+      opts.headers,
+      opts
+    );
+    execJson = asEnvelope(raw, "authorization");
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  if (!execJson.success || !execJson.data?.approved) {
+    return { ok: false, error: execJson.data?.error ?? execJson.error ?? opts.refusalMessage };
+  }
+  const unsignedTx = execJson.data.unsignedTx;
+  if (!unsignedTx) {
+    return { ok: false, error: "Server did not return unsigned transaction" };
+  }
+  return { ok: true, outcome: { data: execJson.data, unsignedTx } };
+}
+async function broadcastSignedTx(opts) {
+  assertSafeServiceEndpoint(opts.serviceEndpoint);
+  let broadcastJson;
+  try {
+    const raw = await postJson(
+      `${opts.serviceEndpoint}${BROADCAST_PATH}`,
+      { signedTx: opts.signedTx, ...opts.meta ?? {} },
+      opts.headers,
+      opts
+    );
+    broadcastJson = asEnvelope(raw, "broadcast");
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  if (!broadcastJson.success) {
+    return { ok: false, error: broadcastJson.error ?? "Broadcast failed" };
+  }
+  const outcome = {};
+  if (broadcastJson.data?.txHash !== void 0)
+    outcome.transactionHash = broadcastJson.data.txHash;
+  if (broadcastJson.data?.blockNumber !== void 0)
+    outcome.blockNumber = broadcastJson.data.blockNumber;
+  return { ok: true, outcome };
+}
+
+// src/utils/sign-guard/sign-and-broadcast.ts
+async function signAndBroadcast(opts) {
+  const prefix = opts.errorPrefix ? `${opts.errorPrefix}: ` : "";
+  try {
+    validateUnsignedTx(opts.unsignedTx, opts.expected, opts.vctx);
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  opts.beforeSign?.(opts.unsignedTx);
+  let signedTx;
+  try {
+    const outerTx = await opts.signer.wrapInnerTx(opts.unsignedTx);
+    signedTx = await opts.signer.signTransaction(outerTx);
+  } catch (e) {
+    return { ok: false, error: `${prefix}${e.message}` };
+  }
+  const sent = await broadcastSignedTx({ ...opts.broadcast, signedTx });
+  if (!sent.ok)
+    return { ok: false, error: `${prefix}${sent.error}` };
+  return sent;
+}
+
+// src/utils/sign-guard/extend-fee-bound.ts
+import { ethers as ethers5 } from "ethers";
+var POSITION_DETAILS_ABI = [
+  "function getPositionDetails(bytes32) view returns (tuple(bytes32 positionId, bytes32 pkpId, uint256 ucdDebt, string vaultAddress, address borrower, uint40 createdAt, uint40 lastUpdated, uint16 selectedTerm, uint40 expiryAt, uint8 status, uint40 previousExpiryAt, uint16 totalTerm))"
+];
+var TERM_MANAGER_ABI = [
+  "function getTermFees(uint256 termMonths) view returns (uint88 originationFee, uint88 extensionFee)"
+];
+async function computeExtendFeeUpperBound(provider, contracts, positionId, selectedTerm, onDegraded) {
+  const degrade = (reason) => {
+    onDegraded?.(reason);
+    return null;
+  };
+  const corePm = contracts["PositionManagerCoreModule"];
+  const termMgr = contracts["TermManagerModule"];
+  if (!corePm)
+    return degrade("PositionManagerCoreModule is not in the contract registry");
+  if (!termMgr)
+    return degrade("TermManagerModule is not in the contract registry");
+  const positionIdBytes32 = ethers5.zeroPadValue(
+    positionId.startsWith("0x") ? positionId : `0x${positionId}`,
+    32
+  );
+  let ucdDebt;
+  try {
+    const pm = new ethers5.Contract(corePm, POSITION_DETAILS_ABI, provider);
+    const details = await pm.getFunction("getPositionDetails")(positionIdBytes32);
+    ucdDebt = BigInt(details.ucdDebt?.toString() ?? "0");
+  } catch (e) {
+    return degrade(`getPositionDetails failed on ${corePm}: ${e.message.slice(0, 160)}`);
+  }
+  let extensionFeeRateBps;
+  try {
+    const tm = new ethers5.Contract(termMgr, TERM_MANAGER_ABI, provider);
+    const fees = await tm.getFunction("getTermFees")(selectedTerm);
+    const extensionFee = fees[1];
+    if (extensionFee === void 0)
+      return degrade(`getTermFees(${selectedTerm}) returned no extensionFee`);
+    extensionFeeRateBps = BigInt(extensionFee.toString());
+  } catch (e) {
+    return degrade(`getTermFees(${selectedTerm}) failed on ${termMgr}: ${e.message.slice(0, 160)}`);
+  }
+  const upperBoundFeeWei = ucdDebt * extensionFeeRateBps / 10000n;
+  return { ucdDebt, extensionFeeRateBps, upperBoundFeeWei };
+}
+export {
+  AUTH_VALIDITY_WINDOWS,
+  BROADCAST_PATH,
+  DEFAULT_FEE_CEILING,
+  DEFAULT_MAX_TX_FEE_WEI,
+  DELEGATED_OPS,
+  LitOpsHttpError,
+  LitOpsTransportError,
+  MAX_FEE_PER_GAS_WEI,
+  MAX_GAS_LIMIT,
+  OP_ENVELOPE_FIELD_ORDER,
+  OP_ENVELOPE_LAYOUT,
+  OP_ENVELOPE_TYPES,
+  QUANTUM_SECONDS,
+  REQUEST_TIMEOUT_MS,
+  SIGNABLE_FUNCTIONS,
+  TxValidationError,
+  asEnvelope,
+  assertFeeCeiling,
+  authValiditySec,
+  authorizeWithServer,
+  broadcastSignedTx,
+  buildAuthEnvelope,
+  buildValidationContext,
+  computeExtendFeeUpperBound,
+  decodeSignable,
+  describeUnsignedTx,
+  encodeSignable,
+  fetchWithTimeout,
+  isAuthFresh,
+  isStrictCurrentQuantum,
+  modeForChainId,
+  nextQuantumTimestamp,
+  postJson,
+  randomNonceHex,
+  readTxFeeFields,
+  signAndBroadcast,
+  signableFunctionName,
+  signableSelectors,
+  stampOpEnvelope,
+  validateUnsignedTx,
+  worstCaseFeeWei
+};