@gvnrdao/dh-sdk 0.0.306 → 0.0.307

package/dist/index.d.ts

@@ -52,3 +52,5 @@ export { SDKError, ErrorCategory, ErrorSeverity } from './utils/error-handler';
 export { setPositionDelegate, getPositionDelegate } from './utils/position-delegate.utils';
 export { buildBtcExecuteEnvelope, } from './utils/btc-withdrawal-message';
 export type { BtcExecuteSignParams, BtcExecuteSignedEnvelope, } from './utils/btc-withdrawal-message';
+export { reconcileAuthorizedSpend, defaultHttpGetJson, } from './utils/withdrawal-reconciliation.utils';
+export type { PendingWithdrawalStatus, AuthorizedSpendLike, ReconciledWithdrawal, HttpGetJson, } from './utils/withdrawal-reconciliation.utils';

package/dist/index.js

@@ -5591,6 +5591,7 @@ __export(src_exports, {
   createPKPManager: () => createPKPManager,
   createWithdrawalAddressModule: () => createWithdrawalAddressModule,
   default: () => DiamondHandsSDK,
+  defaultHttpGetJson: () => defaultHttpGetJson,
   failure: () => failure,
   fetchProtocolPauseStatus: () => fetchProtocolPauseStatus,
   firstSuccess: () => firstSuccess,
@@ -5614,6 +5615,7 @@ __export(src_exports, {
   mapError: () => mapError,
   match: () => match,
   numericToPositionStatus: () => numericToPositionStatus,
+  reconcileAuthorizedSpend: () => reconcileAuthorizedSpend,
   setPositionDelegate: () => setPositionDelegate,
   success: () => success,
   toPromise: () => toPromise,
@@ -7028,6 +7030,122 @@ async function isLaneGuardActiveOnProvider(provider) {
   }
 }
 
+// src/utils/withdrawal-reconciliation.utils.ts
+var defaultHttpGetJson = async (url) => {
+  const res = await fetch(url, { headers: { accept: "application/json" } });
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  return { status: res.status, body };
+};
+async function reconcileAuthorizedSpend(spend, esploraBaseUrl, httpGetJson = defaultHttpGetJson) {
+  const base = esploraBaseUrl.replace(/\/+$/, "");
+  const fundingRes = await httpGetJson(`${base}/tx/${spend.txid}`);
+  if (fundingRes.status === 404) {
+    return {
+      spend,
+      status: "UNFUNDED",
+      reason: `Funding tx ${spend.txid} not found on the network`
+    };
+  }
+  if (fundingRes.status !== 200) {
+    throw new Error(
+      `Withdrawal reconciliation: esplora /tx/${spend.txid} returned HTTP ${fundingRes.status}`
+    );
+  }
+  const funding = fundingRes.body;
+  if (!funding?.status?.confirmed) {
+    return {
+      spend,
+      status: "UNFUNDED",
+      reason: `Funding tx ${spend.txid} is not confirmed yet`
+    };
+  }
+  const output = funding.vout?.[spend.vout];
+  if (!output || typeof output.value !== "number") {
+    return {
+      spend,
+      status: "CORRUPT",
+      reason: `Authorized vout ${spend.vout} does not exist on tx ${spend.txid} (${funding.vout?.length ?? 0} outputs)`
+    };
+  }
+  const onChainOutputValue = output.value;
+  if (onChainOutputValue !== spend.satoshis) {
+    return {
+      spend,
+      status: "CORRUPT",
+      onChainOutputValue,
+      reason: `Authorization declares ${spend.satoshis} sats for ${spend.txid}:${spend.vout} but the on-chain output is ${onChainOutputValue} sats`
+    };
+  }
+  if (spend.targetAmount > onChainOutputValue) {
+    return {
+      spend,
+      status: "CORRUPT",
+      onChainOutputValue,
+      reason: `Authorized targetAmount ${spend.targetAmount} sats exceeds the ${onChainOutputValue}-sat output it is authorized against`
+    };
+  }
+  const outspendRes = await httpGetJson(
+    `${base}/tx/${spend.txid}/outspend/${spend.vout}`
+  );
+  if (outspendRes.status !== 200) {
+    throw new Error(
+      `Withdrawal reconciliation: esplora outspend for ${spend.txid}:${spend.vout} returned HTTP ${outspendRes.status}`
+    );
+  }
+  const outspend = outspendRes.body;
+  if (outspend?.spent) {
+    const spendingTxid = typeof outspend.txid === "string" && outspend.txid ? outspend.txid : null;
+    if (spendingTxid) {
+      const spendingRes = await httpGetJson(`${base}/tx/${spendingTxid}`);
+      if (spendingRes.status === 200) {
+        const spendingTx = spendingRes.body;
+        const includesOutpoint = (spendingTx.vin ?? []).some(
+          (v) => v.txid === spend.txid && Number(v.vout) === spend.vout
+        );
+        if (includesOutpoint) {
+          const paidToTargetSats = (spendingTx.vout ?? []).filter(
+            (o) => (o.scriptpubkey_address ?? "").toLowerCase() === spend.targetAddress.toLowerCase()
+          ).reduce((sum, o) => sum + (o.value ?? 0), 0);
+          if (paidToTargetSats > 0) {
+            return {
+              spend,
+              status: "EXECUTED",
+              spendingTxid,
+              paidToTargetSats,
+              onChainOutputValue,
+              reason: `Outpoint spent by ${spendingTxid}, paying ${paidToTargetSats} sats to the authorized target \u2014 withdrawal complete`
+            };
+          }
+          return {
+            spend,
+            status: "SPENT_MISMATCH",
+            spendingTxid,
+            onChainOutputValue,
+            reason: `Outpoint spent by ${spendingTxid} which pays the authorized target nothing \u2014 authorization is unexecutable`
+          };
+        }
+      }
+    }
+    return {
+      spend,
+      status: "EXECUTABLE",
+      onChainOutputValue,
+      reason: "Esplora claims the outpoint is spent but no spending tx provably includes it (known regtest-faucet artifact) \u2014 treated as unspent"
+    };
+  }
+  return {
+    spend,
+    status: "EXECUTABLE",
+    onChainOutputValue,
+    reason: "Outpoint confirmed, unspent, and coherent with the authorization"
+  };
+}
+
 // src/utils/btc-withdrawal-message.ts
 var import_ethers6 = require("ethers");
 var QUANTUM_SECONDS = 60;
@@ -21400,6 +21518,41 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       )
     }));
   }
+  /**
+   * Reconcile every pending withdrawal against BITCOIN truth (incident
+   * 2026-07-22): `getPendingWithdrawals` only reflects on-chain
+   * authorizations, and the contract can never know whether the Phase-2 BTC
+   * broadcast happened. Callers MUST use the returned `status` to decide what
+   * to offer:
+   * - EXECUTABLE      → offer Execute (the only status that may).
+   * - EXECUTED        → auto-clear; `spendingTxid` is the completion proof.
+   * - SPENT_MISMATCH  → unexecutable; offer cancelPendingWithdrawal.
+   * - CORRUPT         → authorization contradicts the chain (e.g. declared
+   *                     satoshis ≠ real output value); offer Cancel &
+   *                     re-request — Execute can only die at the signer guard.
+   * - UNFUNDED        → funding tx unknown/unconfirmed; wait.
+   *
+   * @param opts.esploraBaseUrl Esplora API base (e.g. the api proxy
+   *   `/v1/proxy/esplora/<network>`). Falls back to
+   *   `config.bitcoinProviders[0].url`; throws when neither is configured.
+   */
+  async reconcilePendingWithdrawals(positionId, opts) {
+    this.ensureInitialized();
+    const esploraBaseUrl = opts?.esploraBaseUrl ?? this.config.bitcoinProviders?.[0]?.url;
+    if (!esploraBaseUrl) {
+      throw new SDKError({
+        code: "SDK_ESPLORA_NOT_CONFIGURED",
+        message: "reconcilePendingWithdrawals requires opts.esploraBaseUrl or config.bitcoinProviders[0].url",
+        category: "CONFIGURATION" /* CONFIGURATION */,
+        severity: "HIGH" /* HIGH */,
+        originalError: new Error("esplora base URL not configured")
+      });
+    }
+    const spends = await this.getPendingWithdrawals(positionId);
+    return Promise.all(
+      spends.map((spend) => reconcileAuthorizedSpend(spend, esploraBaseUrl))
+    );
+  }
   /**
    * Cancel a pending BTC withdrawal
    *
@@ -23298,6 +23451,7 @@ async function getPositionDelegate(positionId, provider, registryAddress) {
   createLoanQuery,
   createPKPManager,
   createWithdrawalAddressModule,
+  defaultHttpGetJson,
   failure,
   fetchProtocolPauseStatus,
   firstSuccess,
@@ -23321,6 +23475,7 @@ async function getPositionDelegate(positionId, provider, registryAddress) {
   mapError,
   match,
   numericToPositionStatus,
+  reconcileAuthorizedSpend,
   setPositionDelegate,
   success,
   toPromise,

package/dist/index.mjs

@@ -6952,6 +6952,122 @@ async function isLaneGuardActiveOnProvider(provider) {
   }
 }
 
+// src/utils/withdrawal-reconciliation.utils.ts
+var defaultHttpGetJson = async (url) => {
+  const res = await fetch(url, { headers: { accept: "application/json" } });
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  return { status: res.status, body };
+};
+async function reconcileAuthorizedSpend(spend, esploraBaseUrl, httpGetJson = defaultHttpGetJson) {
+  const base = esploraBaseUrl.replace(/\/+$/, "");
+  const fundingRes = await httpGetJson(`${base}/tx/${spend.txid}`);
+  if (fundingRes.status === 404) {
+    return {
+      spend,
+      status: "UNFUNDED",
+      reason: `Funding tx ${spend.txid} not found on the network`
+    };
+  }
+  if (fundingRes.status !== 200) {
+    throw new Error(
+      `Withdrawal reconciliation: esplora /tx/${spend.txid} returned HTTP ${fundingRes.status}`
+    );
+  }
+  const funding = fundingRes.body;
+  if (!funding?.status?.confirmed) {
+    return {
+      spend,
+      status: "UNFUNDED",
+      reason: `Funding tx ${spend.txid} is not confirmed yet`
+    };
+  }
+  const output = funding.vout?.[spend.vout];
+  if (!output || typeof output.value !== "number") {
+    return {
+      spend,
+      status: "CORRUPT",
+      reason: `Authorized vout ${spend.vout} does not exist on tx ${spend.txid} (${funding.vout?.length ?? 0} outputs)`
+    };
+  }
+  const onChainOutputValue = output.value;
+  if (onChainOutputValue !== spend.satoshis) {
+    return {
+      spend,
+      status: "CORRUPT",
+      onChainOutputValue,
+      reason: `Authorization declares ${spend.satoshis} sats for ${spend.txid}:${spend.vout} but the on-chain output is ${onChainOutputValue} sats`
+    };
+  }
+  if (spend.targetAmount > onChainOutputValue) {
+    return {
+      spend,
+      status: "CORRUPT",
+      onChainOutputValue,
+      reason: `Authorized targetAmount ${spend.targetAmount} sats exceeds the ${onChainOutputValue}-sat output it is authorized against`
+    };
+  }
+  const outspendRes = await httpGetJson(
+    `${base}/tx/${spend.txid}/outspend/${spend.vout}`
+  );
+  if (outspendRes.status !== 200) {
+    throw new Error(
+      `Withdrawal reconciliation: esplora outspend for ${spend.txid}:${spend.vout} returned HTTP ${outspendRes.status}`
+    );
+  }
+  const outspend = outspendRes.body;
+  if (outspend?.spent) {
+    const spendingTxid = typeof outspend.txid === "string" && outspend.txid ? outspend.txid : null;
+    if (spendingTxid) {
+      const spendingRes = await httpGetJson(`${base}/tx/${spendingTxid}`);
+      if (spendingRes.status === 200) {
+        const spendingTx = spendingRes.body;
+        const includesOutpoint = (spendingTx.vin ?? []).some(
+          (v) => v.txid === spend.txid && Number(v.vout) === spend.vout
+        );
+        if (includesOutpoint) {
+          const paidToTargetSats = (spendingTx.vout ?? []).filter(
+            (o) => (o.scriptpubkey_address ?? "").toLowerCase() === spend.targetAddress.toLowerCase()
+          ).reduce((sum, o) => sum + (o.value ?? 0), 0);
+          if (paidToTargetSats > 0) {
+            return {
+              spend,
+              status: "EXECUTED",
+              spendingTxid,
+              paidToTargetSats,
+              onChainOutputValue,
+              reason: `Outpoint spent by ${spendingTxid}, paying ${paidToTargetSats} sats to the authorized target \u2014 withdrawal complete`
+            };
+          }
+          return {
+            spend,
+            status: "SPENT_MISMATCH",
+            spendingTxid,
+            onChainOutputValue,
+            reason: `Outpoint spent by ${spendingTxid} which pays the authorized target nothing \u2014 authorization is unexecutable`
+          };
+        }
+      }
+    }
+    return {
+      spend,
+      status: "EXECUTABLE",
+      onChainOutputValue,
+      reason: "Esplora claims the outpoint is spent but no spending tx provably includes it (known regtest-faucet artifact) \u2014 treated as unspent"
+    };
+  }
+  return {
+    spend,
+    status: "EXECUTABLE",
+    onChainOutputValue,
+    reason: "Outpoint confirmed, unspent, and coherent with the authorization"
+  };
+}
+
 // src/utils/btc-withdrawal-message.ts
 import { keccak256 as keccak2563, toUtf8Bytes as toUtf8Bytes3, solidityPackedKeccak256 as solidityPackedKeccak2563, getBytes as getBytes3, zeroPadValue } from "ethers";
 var QUANTUM_SECONDS = 60;
@@ -21328,6 +21444,41 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       )
     }));
   }
+  /**
+   * Reconcile every pending withdrawal against BITCOIN truth (incident
+   * 2026-07-22): `getPendingWithdrawals` only reflects on-chain
+   * authorizations, and the contract can never know whether the Phase-2 BTC
+   * broadcast happened. Callers MUST use the returned `status` to decide what
+   * to offer:
+   * - EXECUTABLE      → offer Execute (the only status that may).
+   * - EXECUTED        → auto-clear; `spendingTxid` is the completion proof.
+   * - SPENT_MISMATCH  → unexecutable; offer cancelPendingWithdrawal.
+   * - CORRUPT         → authorization contradicts the chain (e.g. declared
+   *                     satoshis ≠ real output value); offer Cancel &
+   *                     re-request — Execute can only die at the signer guard.
+   * - UNFUNDED        → funding tx unknown/unconfirmed; wait.
+   *
+   * @param opts.esploraBaseUrl Esplora API base (e.g. the api proxy
+   *   `/v1/proxy/esplora/<network>`). Falls back to
+   *   `config.bitcoinProviders[0].url`; throws when neither is configured.
+   */
+  async reconcilePendingWithdrawals(positionId, opts) {
+    this.ensureInitialized();
+    const esploraBaseUrl = opts?.esploraBaseUrl ?? this.config.bitcoinProviders?.[0]?.url;
+    if (!esploraBaseUrl) {
+      throw new SDKError({
+        code: "SDK_ESPLORA_NOT_CONFIGURED",
+        message: "reconcilePendingWithdrawals requires opts.esploraBaseUrl or config.bitcoinProviders[0].url",
+        category: "CONFIGURATION" /* CONFIGURATION */,
+        severity: "HIGH" /* HIGH */,
+        originalError: new Error("esplora base URL not configured")
+      });
+    }
+    const spends = await this.getPendingWithdrawals(positionId);
+    return Promise.all(
+      spends.map((spend) => reconcileAuthorizedSpend(spend, esploraBaseUrl))
+    );
+  }
   /**
    * Cancel a pending BTC withdrawal
    *
@@ -23226,6 +23377,7 @@ export {
   createPKPManager,
   createWithdrawalAddressModule,
   DiamondHandsSDK as default,
+  defaultHttpGetJson,
   failure,
   fetchProtocolPauseStatus,
   firstSuccess,
@@ -23249,6 +23401,7 @@ export {
   mapError,
   match,
   numericToPositionStatus,
+  reconcileAuthorizedSpend,
   setPositionDelegate,
   success,
   toPromise,

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

@@ -18,6 +18,7 @@ import { SDKError } from "../utils/error-handler";
 import type { CreateLoanRequest, CreateLoanResult, LoanDataDetail, UCDMintRequest, UCDMintResult, PartialPaymentRequest, PartialPaymentResult, BTCWithdrawalResult, RenewPositionRequest, RenewPositionResult, LiquidationRequest, LiquidationResult, ConfirmBalanceRequest, ConfirmBalanceResult, TermsWithFeesResult } from "../interfaces/chunks/loan-operations.i";
 import type { DiamondHandsSDKConfig } from "../interfaces/chunks/config.i";
 import type { PKPData } from "../interfaces/chunks/pkp-integration.i";
+import { type ReconciledWithdrawal } from "../utils/withdrawal-reconciliation.utils";
 import { ContractManager } from "./contract/contract-manager.module";
 import { WithdrawalAddressModule } from "./withdrawal-address/withdrawal-address.module";
 import { BitcoinOperations } from "./bitcoin/bitcoin-operations.module";
@@ -556,6 +557,27 @@ export declare class DiamondHandsSDK {
         authorizedAt: number;
         utxoKey: string;
     }>>;
+    /**
+     * Reconcile every pending withdrawal against BITCOIN truth (incident
+     * 2026-07-22): `getPendingWithdrawals` only reflects on-chain
+     * authorizations, and the contract can never know whether the Phase-2 BTC
+     * broadcast happened. Callers MUST use the returned `status` to decide what
+     * to offer:
+     * - EXECUTABLE      → offer Execute (the only status that may).
+     * - EXECUTED        → auto-clear; `spendingTxid` is the completion proof.
+     * - SPENT_MISMATCH  → unexecutable; offer cancelPendingWithdrawal.
+     * - CORRUPT         → authorization contradicts the chain (e.g. declared
+     *                     satoshis ≠ real output value); offer Cancel &
+     *                     re-request — Execute can only die at the signer guard.
+     * - UNFUNDED        → funding tx unknown/unconfirmed; wait.
+     *
+     * @param opts.esploraBaseUrl Esplora API base (e.g. the api proxy
+     *   `/v1/proxy/esplora/<network>`). Falls back to
+     *   `config.bitcoinProviders[0].url`; throws when neither is configured.
+     */
+    reconcilePendingWithdrawals(positionId: string, opts?: {
+        esploraBaseUrl?: string;
+    }): Promise<Array<ReconciledWithdrawal<Awaited<ReturnType<DiamondHandsSDK["getPendingWithdrawals"]>>[number]>>>;
     /**
      * Cancel a pending BTC withdrawal
      *

package/dist/utils/withdrawal-reconciliation.utils.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pending-withdrawal reconciliation — classify each on-chain authorized spend
+ * (`BTCSpendAuthorizer.getAuthorizedSpends`) against BITCOIN truth before any
+ * UI offers "Execute" or any server invokes the TEE signer.
+ *
+ * Why this exists (incident 2026-07-22, position 0x992d5c…): the contract can
+ * never know whether a Phase-2 BTC broadcast happened, and a pre-P6/#8
+ * authorization could record a `(vout, satoshis)` pair that never matched the
+ * chain (declared 96,049 vs on-chain 33,000). Executing such an entry can only
+ * die at the signer's parent-fetch guard; and an entry whose outpoint was
+ * already spent paying the target is DONE and must auto-clear — while an
+ * entry whose funding tx merely confirmed must NOT be cleared as "complete".
+ *
+ * Statuses:
+ * - EXECUTABLE      — outpoint confirmed, unspent, values coherent → offer Execute.
+ * - EXECUTED        — outpoint spent by a tx that pays the authorized target →
+ *                     auto-clear, show `spendingTxid` as the completion proof.
+ * - SPENT_MISMATCH  — outpoint spent but the spending tx pays the target
+ *                     nothing → unexecutable; surface Cancel.
+ * - CORRUPT         — authorization contradicts the chain (declared value ≠
+ *                     real output value, targetAmount > real value, or vout
+ *                     out of range) → surface Cancel & re-request; never Execute.
+ * - UNFUNDED        — funding tx unknown/unconfirmed → wait; no Execute yet.
+ *
+ * Esplora `spent: true` claims are only trusted when the spending tx can be
+ * fetched AND provably includes this outpoint among its inputs — the regtest
+ * faucet's esplora answers `spent: true` for arbitrary txids, and a false
+ * "executed" here would silently dismiss a withdrawal the user was never paid
+ * for. Unverifiable claims classify as EXECUTABLE (chain truth: no proven
+ * spend); a genuinely-spent outpoint then simply fails downstream, safely.
+ */
+export type PendingWithdrawalStatus = "EXECUTABLE" | "EXECUTED" | "SPENT_MISMATCH" | "CORRUPT" | "UNFUNDED";
+export interface AuthorizedSpendLike {
+    txid: string;
+    vout: number;
+    satoshis: number;
+    targetAddress: string;
+    targetAmount: number;
+}
+export interface ReconciledWithdrawal<T extends AuthorizedSpendLike = AuthorizedSpendLike> {
+    spend: T;
+    status: PendingWithdrawalStatus;
+    /** Human-readable, single-sentence explanation of the classification. */
+    reason: string;
+    /** Real value of the referenced outpoint, when the funding tx is known. */
+    onChainOutputValue?: number;
+    /** The verified spending tx, for EXECUTED / SPENT_MISMATCH. */
+    spendingTxid?: string;
+    /** Sats the verified spending tx pays to `targetAddress` (EXECUTED only). */
+    paidToTargetSats?: number;
+}
+/**
+ * HTTP seam: GET `url`, resolve `{ status, body }` (body null on non-JSON).
+ * Injectable for tests; the default uses global `fetch` (node ≥18 + browsers).
+ * Transport failures throw — reconciliation must fail LOUD, never classify on
+ * missing data.
+ */
+export type HttpGetJson = (url: string) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+export declare const defaultHttpGetJson: HttpGetJson;
+/** Classify one authorized spend against the esplora at `esploraBaseUrl`. */
+export declare function reconcileAuthorizedSpend<T extends AuthorizedSpendLike>(spend: T, esploraBaseUrl: string, httpGetJson?: HttpGetJson): Promise<ReconciledWithdrawal<T>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.306",
+  "version": "0.0.307",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",