@gvnrdao/dh-sdk 0.0.295 → 0.0.297

package/dist/modules/diamond-hands-sdk.d.ts

@@ -952,9 +952,9 @@ export declare class DiamondHandsSDK {
      */
     loanOps(): {
         getProtocolConfig(): Promise<{
-            liquidationThreshold: any;
+            liquidationThreshold: string;
             minimumLoanValueUcd: string;
-            minimumLoanValueWei: any;
+            minimumLoanValueWei: string;
             maxSingleLoanValueUcd: string;
             maxSingleLoanValueWei: string;
         }>;

package/dist/modules/withdrawal-address/withdrawal-address.module.d.ts

@@ -11,17 +11,19 @@
  * Display lists (with the original address strings) come from the subgraph —
  * the contract stores only keccak256(address). This module exposes the
  * authoritative contract reads (isApproved / hashes / timestamps) and the
- * mutating txs.
+ * mutating txs. `getEntries` also enriches with the raw address via
+ * `setGraphClient` (late-injected — see diamond-hands-sdk.ts), best-effort.
  */
 import { type TransactionResponse } from "ethers";
 import type { ContractManager } from "../contract/contract-manager.module";
+import type { DiamondHandsGraph } from "../../graphs/diamond-hands";
 import { Result } from "../../types/result";
 import { SDKError } from "../../utils/error-handler";
 export interface WithdrawalAddressModuleConfig {
     contractManager: ContractManager;
     debug?: boolean;
 }
-/** A single approved-address entry as read from the contract (no raw string — see subgraph for that). */
+/** A single approved-address entry as read from the contract, enriched with the raw address from the subgraph when available. */
 export interface WithdrawalAddressEntry {
     /** keccak256(bytes(normalizedAddress)). */
     addrHash: string;
@@ -36,10 +38,20 @@ export interface WithdrawalAddressEntry {
      * delay after this entry was added.
      */
     approved: boolean;
+    /**
+     * Raw BTC address string, resolved from the subgraph's WithdrawalAddressBook
+     * (indexed from the contract's AddressAdded event log — never on-chain
+     * readable directly). `null` if not yet indexed, the lookup failed, or no
+     * graph client was wired via `setGraphClient`.
+     */
+    address: string | null;
 }
 export declare class WithdrawalAddressModule {
     private readonly config;
+    private graphClient?;
     constructor(config: WithdrawalAddressModuleConfig);
+    /** Late-inject the graph client (constructed after this module in the SDK's constructor). */
+    setGraphClient(graphClient: DiamondHandsGraph): void;
     /** Resolve the registry contract, or fail if it isn't configured for this network. */
     private getRegistry;
     /** True iff the registry is wired for this network (enforcement is active). */

package/dist/server.js

@@ -54,6 +54,238 @@ var VALID_LIT_NETWORKS = [
   DEFAULT_LIT_NETWORKS.CHIPOTLE
 ];
 
+// src/utils/logger.utils.ts
+var Logger = class _Logger {
+  config;
+  static instance = null;
+  constructor(config2 = {}) {
+    this.config = {
+      enabled: config2.enabled ?? true,
+      level: config2.level ?? "info",
+      includeTimestamp: config2.includeTimestamp ?? false,
+      includeContext: config2.includeContext ?? true,
+      maxContextKeys: config2.maxContextKeys ?? 5,
+      verboseInProduction: config2.verboseInProduction ?? false,
+      isProduction: config2.isProduction ?? false
+    };
+  }
+  /**
+   * Get or create singleton logger instance
+   */
+  static getInstance(config2) {
+    if (!_Logger.instance) {
+      _Logger.instance = new _Logger(config2);
+    }
+    return _Logger.instance;
+  }
+  /**
+   * Update logger configuration
+   */
+  updateConfig(config2) {
+    this.config = { ...this.config, ...config2 };
+  }
+  /**
+   * Check if a log level should be output
+   */
+  shouldLog(level) {
+    if (!this.config.enabled)
+      return false;
+    if (this.config.isProduction && !this.config.verboseInProduction) {
+      if (level === "debug" || level === "info") {
+        return false;
+      }
+    }
+    const levels = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3
+    };
+    return levels[level] >= levels[this.config.level];
+  }
+  /**
+   * Format context object for output
+   */
+  formatContext(context) {
+    if (!this.config.includeContext || !context)
+      return "";
+    const keys = Object.keys(context).slice(0, this.config.maxContextKeys);
+    const pairs = keys.map((key) => `${key}=${context[key]}`).join(" ");
+    return pairs ? ` [${pairs}]` : "";
+  }
+  /**
+   * Format timestamp for output
+   */
+  formatTimestamp() {
+    if (!this.config.includeTimestamp)
+      return "";
+    return `[${(/* @__PURE__ */ new Date()).toISOString()}] `;
+  }
+  /**
+   * Core logging method
+   */
+  log(level, message, context) {
+    if (!this.shouldLog(level))
+      return;
+    const timestamp = this.formatTimestamp();
+    const contextStr = this.formatContext(context);
+    const prefix = this.getLevelPrefix(level);
+    const fullMessage = `${timestamp}${prefix}${message}${contextStr}`;
+    switch (level) {
+      case "debug":
+        console.debug(fullMessage);
+        break;
+      case "info":
+        console.info(fullMessage);
+        break;
+      case "warn":
+        console.warn(fullMessage);
+        break;
+      case "error":
+        console.error(fullMessage);
+        break;
+    }
+  }
+  /**
+   * Get prefix for log level
+   */
+  getLevelPrefix(level) {
+    const prefixes = {
+      debug: "\u{1F50D} [DEBUG]",
+      info: "\u2139\uFE0F  [INFO] ",
+      warn: "\u26A0\uFE0F  [WARN] ",
+      error: "\u274C [ERROR]"
+    };
+    return prefixes[level];
+  }
+  /**
+   * Debug level logging
+   */
+  debug(message, context) {
+    this.log("debug", message, context);
+  }
+  /**
+   * Info level logging
+   */
+  info(message, context) {
+    this.log("info", message, context);
+  }
+  /**
+   * Warning level logging
+   */
+  warn(message, context) {
+    this.log("warn", message, context);
+  }
+  /**
+   * Error level logging
+   */
+  error(message, context) {
+    this.log("error", message, context);
+  }
+  /**
+   * Log operation start
+   */
+  startOperation(operation, context) {
+    this.info(`Starting ${operation}`, { operation, ...context });
+  }
+  /**
+   * Log operation completion
+   */
+  completeOperation(operation, context) {
+    this.info(`Completed ${operation}`, { operation, ...context });
+  }
+  /**
+   * Log operation failure
+   */
+  failOperation(operation, error, context) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    this.error(`Failed ${operation}: ${errorMessage}`, { operation, error: errorMessage, ...context });
+  }
+  /**
+   * Log retry attempt
+   */
+  retry(operation, attempt, maxAttempts, error, context) {
+    const errorMessage = error ? `: ${error.message}` : "";
+    this.warn(`Retrying ${operation} (${attempt}/${maxAttempts})${errorMessage}`, {
+      operation,
+      attempt,
+      maxAttempts,
+      ...context
+    });
+  }
+  /**
+   * Log cache operations
+   */
+  cacheHit(key, context) {
+    this.debug(`Cache HIT for ${key}`, { operation: "cache", key, ...context });
+  }
+  cacheMiss(key, context) {
+    this.debug(`Cache MISS for ${key}`, { operation: "cache", key, ...context });
+  }
+  /**
+   * Log network operations
+   */
+  networkRequest(url, method, context) {
+    this.debug(`${method} ${url}`, { operation: "network", url, method, ...context });
+  }
+  networkResponse(url, status, duration, context) {
+    this.debug(`Response ${status} from ${url}${duration ? ` (${duration}ms)` : ""}`, {
+      operation: "network",
+      url,
+      status,
+      duration,
+      ...context
+    });
+  }
+  /**
+   * Log Bitcoin operations
+   */
+  bitcoinOperation(operation, address, context) {
+    this.debug(`Bitcoin ${operation}${address ? ` for ${address}` : ""}`, {
+      operation: "bitcoin",
+      bitcoinOp: operation,
+      address,
+      ...context
+    });
+  }
+  /**
+   * Log contract operations
+   */
+  contractOperation(operation, contract, context) {
+    this.debug(`Contract ${operation}${contract ? ` on ${contract}` : ""}`, {
+      operation: "contract",
+      contractOp: operation,
+      contract,
+      ...context
+    });
+  }
+};
+function getLogger() {
+  return Logger.getInstance();
+}
+var log = {
+  debug: (message, context) => getLogger().debug(message, context),
+  info: (message, context) => getLogger().info(message, context),
+  warn: (message, context) => getLogger().warn(message, context),
+  error: (message, context) => getLogger().error(message, context),
+  // Operation helpers
+  start: (operation, context) => getLogger().startOperation(operation, context),
+  complete: (operation, context) => getLogger().completeOperation(operation, context),
+  fail: (operation, error, context) => getLogger().failOperation(operation, error, context),
+  retry: (operation, attempt, maxAttempts, error, context) => getLogger().retry(operation, attempt, maxAttempts, error, context),
+  // Specialized helpers
+  cache: {
+    hit: (key, context) => getLogger().cacheHit(key, context),
+    miss: (key, context) => getLogger().cacheMiss(key, context)
+  },
+  network: {
+    request: (url, method, context) => getLogger().networkRequest(url, method, context),
+    response: (url, status, duration, context) => getLogger().networkResponse(url, status, duration, context)
+  },
+  bitcoin: (operation, address, context) => getLogger().bitcoinOperation(operation, address, context),
+  contract: (operation, contract, context) => getLogger().contractOperation(operation, contract, context)
+};
+
 // src/constants/chunks/environment.ts
 var possibleEnvPaths = [
   ".env",
@@ -85,7 +317,7 @@ function logEnvDiscoveryOnce() {
   if (process.env.DEBUG_SDK !== "true") {
     return;
   }
-  console.log("[SDK] .env multi-path load", {
+  log.info("[SDK] .env multi-path load", {
     attempted: envPathsAttemptedAbs,
     mergedFromExistingFiles: envPathsMergedAbs,
     note: "later paths override earlier (dotenv)"
@@ -153,9 +385,9 @@ function loadSDKConfig() {
 function envLog(message, ...args) {
   const config2 = loadSDKConfig();
   if (config2.debugMode) {
-    console.log(
+    log.info(
       `[SDK:${config2.environment.toUpperCase()}] ${message}`,
-      ...args
+      args.length > 0 ? { args } : void 0
     );
   }
 }

package/dist/server.mjs

@@ -12,6 +12,238 @@ var VALID_LIT_NETWORKS = [
   DEFAULT_LIT_NETWORKS.CHIPOTLE
 ];
 
+// src/utils/logger.utils.ts
+var Logger = class _Logger {
+  config;
+  static instance = null;
+  constructor(config2 = {}) {
+    this.config = {
+      enabled: config2.enabled ?? true,
+      level: config2.level ?? "info",
+      includeTimestamp: config2.includeTimestamp ?? false,
+      includeContext: config2.includeContext ?? true,
+      maxContextKeys: config2.maxContextKeys ?? 5,
+      verboseInProduction: config2.verboseInProduction ?? false,
+      isProduction: config2.isProduction ?? false
+    };
+  }
+  /**
+   * Get or create singleton logger instance
+   */
+  static getInstance(config2) {
+    if (!_Logger.instance) {
+      _Logger.instance = new _Logger(config2);
+    }
+    return _Logger.instance;
+  }
+  /**
+   * Update logger configuration
+   */
+  updateConfig(config2) {
+    this.config = { ...this.config, ...config2 };
+  }
+  /**
+   * Check if a log level should be output
+   */
+  shouldLog(level) {
+    if (!this.config.enabled)
+      return false;
+    if (this.config.isProduction && !this.config.verboseInProduction) {
+      if (level === "debug" || level === "info") {
+        return false;
+      }
+    }
+    const levels = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3
+    };
+    return levels[level] >= levels[this.config.level];
+  }
+  /**
+   * Format context object for output
+   */
+  formatContext(context) {
+    if (!this.config.includeContext || !context)
+      return "";
+    const keys = Object.keys(context).slice(0, this.config.maxContextKeys);
+    const pairs = keys.map((key) => `${key}=${context[key]}`).join(" ");
+    return pairs ? ` [${pairs}]` : "";
+  }
+  /**
+   * Format timestamp for output
+   */
+  formatTimestamp() {
+    if (!this.config.includeTimestamp)
+      return "";
+    return `[${(/* @__PURE__ */ new Date()).toISOString()}] `;
+  }
+  /**
+   * Core logging method
+   */
+  log(level, message, context) {
+    if (!this.shouldLog(level))
+      return;
+    const timestamp = this.formatTimestamp();
+    const contextStr = this.formatContext(context);
+    const prefix = this.getLevelPrefix(level);
+    const fullMessage = `${timestamp}${prefix}${message}${contextStr}`;
+    switch (level) {
+      case "debug":
+        console.debug(fullMessage);
+        break;
+      case "info":
+        console.info(fullMessage);
+        break;
+      case "warn":
+        console.warn(fullMessage);
+        break;
+      case "error":
+        console.error(fullMessage);
+        break;
+    }
+  }
+  /**
+   * Get prefix for log level
+   */
+  getLevelPrefix(level) {
+    const prefixes = {
+      debug: "\u{1F50D} [DEBUG]",
+      info: "\u2139\uFE0F  [INFO] ",
+      warn: "\u26A0\uFE0F  [WARN] ",
+      error: "\u274C [ERROR]"
+    };
+    return prefixes[level];
+  }
+  /**
+   * Debug level logging
+   */
+  debug(message, context) {
+    this.log("debug", message, context);
+  }
+  /**
+   * Info level logging
+   */
+  info(message, context) {
+    this.log("info", message, context);
+  }
+  /**
+   * Warning level logging
+   */
+  warn(message, context) {
+    this.log("warn", message, context);
+  }
+  /**
+   * Error level logging
+   */
+  error(message, context) {
+    this.log("error", message, context);
+  }
+  /**
+   * Log operation start
+   */
+  startOperation(operation, context) {
+    this.info(`Starting ${operation}`, { operation, ...context });
+  }
+  /**
+   * Log operation completion
+   */
+  completeOperation(operation, context) {
+    this.info(`Completed ${operation}`, { operation, ...context });
+  }
+  /**
+   * Log operation failure
+   */
+  failOperation(operation, error, context) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    this.error(`Failed ${operation}: ${errorMessage}`, { operation, error: errorMessage, ...context });
+  }
+  /**
+   * Log retry attempt
+   */
+  retry(operation, attempt, maxAttempts, error, context) {
+    const errorMessage = error ? `: ${error.message}` : "";
+    this.warn(`Retrying ${operation} (${attempt}/${maxAttempts})${errorMessage}`, {
+      operation,
+      attempt,
+      maxAttempts,
+      ...context
+    });
+  }
+  /**
+   * Log cache operations
+   */
+  cacheHit(key, context) {
+    this.debug(`Cache HIT for ${key}`, { operation: "cache", key, ...context });
+  }
+  cacheMiss(key, context) {
+    this.debug(`Cache MISS for ${key}`, { operation: "cache", key, ...context });
+  }
+  /**
+   * Log network operations
+   */
+  networkRequest(url, method, context) {
+    this.debug(`${method} ${url}`, { operation: "network", url, method, ...context });
+  }
+  networkResponse(url, status, duration, context) {
+    this.debug(`Response ${status} from ${url}${duration ? ` (${duration}ms)` : ""}`, {
+      operation: "network",
+      url,
+      status,
+      duration,
+      ...context
+    });
+  }
+  /**
+   * Log Bitcoin operations
+   */
+  bitcoinOperation(operation, address, context) {
+    this.debug(`Bitcoin ${operation}${address ? ` for ${address}` : ""}`, {
+      operation: "bitcoin",
+      bitcoinOp: operation,
+      address,
+      ...context
+    });
+  }
+  /**
+   * Log contract operations
+   */
+  contractOperation(operation, contract, context) {
+    this.debug(`Contract ${operation}${contract ? ` on ${contract}` : ""}`, {
+      operation: "contract",
+      contractOp: operation,
+      contract,
+      ...context
+    });
+  }
+};
+function getLogger() {
+  return Logger.getInstance();
+}
+var log = {
+  debug: (message, context) => getLogger().debug(message, context),
+  info: (message, context) => getLogger().info(message, context),
+  warn: (message, context) => getLogger().warn(message, context),
+  error: (message, context) => getLogger().error(message, context),
+  // Operation helpers
+  start: (operation, context) => getLogger().startOperation(operation, context),
+  complete: (operation, context) => getLogger().completeOperation(operation, context),
+  fail: (operation, error, context) => getLogger().failOperation(operation, error, context),
+  retry: (operation, attempt, maxAttempts, error, context) => getLogger().retry(operation, attempt, maxAttempts, error, context),
+  // Specialized helpers
+  cache: {
+    hit: (key, context) => getLogger().cacheHit(key, context),
+    miss: (key, context) => getLogger().cacheMiss(key, context)
+  },
+  network: {
+    request: (url, method, context) => getLogger().networkRequest(url, method, context),
+    response: (url, status, duration, context) => getLogger().networkResponse(url, status, duration, context)
+  },
+  bitcoin: (operation, address, context) => getLogger().bitcoinOperation(operation, address, context),
+  contract: (operation, contract, context) => getLogger().contractOperation(operation, contract, context)
+};
+
 // src/constants/chunks/environment.ts
 var possibleEnvPaths = [
   ".env",
@@ -43,7 +275,7 @@ function logEnvDiscoveryOnce() {
   if (process.env.DEBUG_SDK !== "true") {
     return;
   }
-  console.log("[SDK] .env multi-path load", {
+  log.info("[SDK] .env multi-path load", {
     attempted: envPathsAttemptedAbs,
     mergedFromExistingFiles: envPathsMergedAbs,
     note: "later paths override earlier (dotenv)"
@@ -111,9 +343,9 @@ function loadSDKConfig() {
 function envLog(message, ...args) {
   const config2 = loadSDKConfig();
   if (config2.debugMode) {
-    console.log(
+    log.info(
       `[SDK:${config2.environment.toUpperCase()}] ${message}`,
-      ...args
+      args.length > 0 ? { args } : void 0
     );
   }
 }

package/dist/utils/chunks/eip1559-broadcast.utils.d.ts

@@ -3,7 +3,23 @@
  * (e.g. large mintUCD) without manual signDigest / eth_sendRawTransaction.
  */
 import { type Provider, type Signer, type TransactionResponse } from "ethers";
-/** Observed mintUCD + LIT validation can exceed 7M gas; cap avoids block limit issues. */
+/**
+ * Cap on mintUCD's gasLimit. mintUCD dynamically sizes gasLimit via
+ * estimateContractCallGasWithMargin() (real eth_estimateGas + 25% margin) on
+ * mainnet, so this value is NOT normally what gets submitted -- it only
+ * becomes the literal gasLimit if (a) the estimate comes back anomalously
+ * high, or (b) eth_estimateGas itself fails, which is a hard error on
+ * mainnet and only falls back to this raw value on Sepolia/localhost.
+ * Previously 10,000,000 with a comment claiming "mintUCD + LIT validation
+ * can exceed 7M gas" -- no evidence of that was found across 16 real mint
+ * transactions checked (1 mainnet, 15 recent Sepolia, 2026-07-02): the
+ * dynamically-computed gasLimit actually submitted ranged 388,620-886,988.
+ * Lowered to 2,000,000 (~2.25x headroom over the highest real value seen)
+ * for consistency with MAKE_PAYMENT_GAS_CEILING/EXTEND_POSITION_GAS_CEILING's
+ * ~1.5-2x-headroom convention -- a smaller margin than those because this
+ * ceiling is a rarely-hit fallback/cap, not the everyday operating value, so
+ * a little extra buffer for cold-storage variance is cheap insurance.
+ */
 export declare const MINT_UCD_GAS_CEILING: bigint;
 /**
  * Fixed-gas ceiling for the withdrawBTC raw-tx fallback (used when estimateGas
@@ -15,6 +31,63 @@ export declare const MINT_UCD_GAS_CEILING: bigint;
  * while staying well under the block gas limit.
  */
 export declare const WITHDRAW_BTC_GAS_CEILING: bigint;
+/**
+ * Fixed-gas ceiling for makePayment's broadcast (no estimateGas — see the call
+ * site's comment on why). The prior 500,000 limit silently doomed the call: the
+ * full chain (PositionManager -> LoanOperationsManager -> OperationAuthorization-
+ * Registry auth/quantum checks -> UCDController -> UCDToken's reentrancy-guarded
+ * burn(), 9+ nested call frames) needs a measured minimum of 573,821 gas once
+ * EIP-150's 63/64 forwarding rule is accounted for at each hop -- MORE than the
+ * ~481,100 gas a successful run actually consumes, because a tight overall limit
+ * starves the innermost calls of forwarded gas even when the total would
+ * technically fit. Under-gassing surfaced as UCDController's generic
+ * BurnCallFailed() (the real out-of-gas failure deep in UCDToken.burn()'s
+ * reentrancy sentry gets swallowed by the low-level call), which looked
+ * unrelated to gas. Verified live via debug_traceCall + binary search against a
+ * real mainnet revert (2026-07-02). 1M gives ~1.74x headroom over the measured
+ * floor, matching WITHDRAW_BTC_GAS_CEILING's ~2x-headroom convention above.
+ */
+export declare const MAKE_PAYMENT_GAS_CEILING: bigint;
+/**
+ * Fixed-gas ceiling for extendPosition's broadcast. Previously had NO explicit
+ * gasLimit at all -- the only timing-sensitive call in this file that fell
+ * through to ethers' implicit estimateGas, which is exactly the RPC-latency
+ * risk every other call here (makePayment, mintUCD, withdrawBTC, liquidation
+ * commit/reveal) was deliberately hardened against, despite extendPosition
+ * ALSO calling awaitSafeSubmissionWindow just before broadcasting. Grounded in
+ * 10 real recent Sepolia PositionRenewed transactions: gasUsed ranged
+ * 388,150-430,705 (2026-07-02). Not binary-search-verified against a live
+ * revert like MAKE_PAYMENT_GAS_CEILING was -- replaying those specific txs
+ * hits a Gnosis Safe "GS026" (invalid owner) error unrelated to gas, because
+ * eth_call can't faithfully reproduce the embedded Safe-owner signature
+ * context. 1M gives >2x headroom over the observed max.
+ */
+export declare const EXTEND_POSITION_GAS_CEILING: bigint;
+/**
+ * Fixed-gas ceiling for commitLiquidation's broadcast. No liquidation has ever
+ * executed on mainnet OR Sepolia yet (both networks are too new / no position
+ * has needed it), so unlike MAKE_PAYMENT_GAS_CEILING this is NOT verified
+ * against any real transaction -- it is a reasoned estimate only. The commit
+ * phase's on-chain work (auth + quantum checks, no burn/collateral movement)
+ * is similar in shape to makePayment's, so this matches MAKE_PAYMENT_GAS_CEILING.
+ * The prior hardcoded 500,000 followed the exact same "round unverified guess"
+ * pattern that caused MAKE_PAYMENT_GAS_CEILING's real production failure, so
+ * treat this as provisional until a real mainnet liquidation exists to
+ * measure against (see the debug_traceCall + binary-search method used for
+ * makePayment/withdrawBTC).
+ */
+export declare const LIQUIDATION_COMMIT_GAS_CEILING: bigint;
+/**
+ * Fixed-gas ceiling for revealAndLiquidate's broadcast. Same "no real
+ * transaction exists yet to verify against" caveat as
+ * LIQUIDATION_COMMIT_GAS_CEILING. The reveal phase does substantially more
+ * on-chain work than commit or makePayment -- position lookup, liquidation-
+ * eligibility calculation, debt burn, AND collateral/vault handling -- closer
+ * in shape to WITHDRAW_BTC_GAS_CEILING's flow than to MAKE_PAYMENT_GAS_CEILING's.
+ * The prior hardcoded 700,000 was likewise an unverified guess. Treat as
+ * provisional until re-measured against a real liquidation.
+ */
+export declare const LIQUIDATION_REVEAL_GAS_CEILING: bigint;
 /** Headroom on eth_estimateGas (25%). */
 export declare const MINT_UCD_ESTIMATE_MARGIN_BPS = 2500;
 /**