@gvnrdao/dh-sdk 0.0.306 → 0.0.308

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";
@@ -545,7 +546,7 @@ export declare class DiamondHandsSDK {
      * been broadcast to the Bitcoin network. An empty array means no pending withdrawals.
      *
      * @param positionId - Position identifier
-     * @returns Array of pending withdrawals, each including a pre-computed utxoKey for use with cancelPendingWithdrawal
+     * @returns Array of pending withdrawals, each including a pre-computed utxoKey (the key recoverStaleSpend and the admin clearing path operate on)
      */
     getPendingWithdrawals(positionId: string): Promise<Array<{
         txid: string;
@@ -557,17 +558,30 @@ export declare class DiamondHandsSDK {
         utxoKey: string;
     }>>;
     /**
-     * Cancel a pending BTC withdrawal
-     *
-     * Removes a stale authorized spend from BTCSpendAuthorizer, unlocking the UTXO
-     * and allowing the borrower to retry the withdrawal from scratch.
-     * Only the position's borrower may call this — requires a connected signer.
-     *
-     * @param positionId - Position identifier
-     * @param txid - Bitcoin UTXO transaction ID (from getPendingWithdrawals)
-     * @param vout - Output index (from getPendingWithdrawals)
-     * @returns Transaction hash of the cancellation EVM transaction
-     */
+     * 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 —
+     *                     feed it to recoverStaleSpend to clear the reservation.
+     * - SPENT_MISMATCH  → unexecutable; recoverStaleSpend with the spending txid
+     *                     as invalidator clears the reservation.
+     * - CORRUPT         → authorization contradicts the chain (e.g. declared
+     *                     satoshis ≠ real output value); Execute can only die at
+     *                     the signer guard, and no borrower-side cancel exists
+     *                     (audit #62210) — clearing needs the AdminModule
+     *                     cancelStaleSpendByAdmin operator override.
+     * - 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]>>>;
     /**
      * Recover (clear) a stale BTC reservation via LIT-attested proof.
      *
@@ -617,6 +631,59 @@ export declare class DiamondHandsSDK {
         error?: string;
         failedStep?: "attestation" | "submit" | "config";
     }>;
+    /**
+     * Sign + broadcast the PKP vault→vault self-spend that invalidates one
+     * stuck authorized outpoint (btc-utxo-invalidator 1.0.0). Once the returned
+     * `invalidatorTxid` reaches >=6 Bitcoin confirmations, `recoverStaleSpend`
+     * clears the on-chain reservation — the trustless replacement for the
+     * AdminModule cancelStaleSpendByAdmin path on unspent stuck/corrupt
+     * reservations (incident 2026-07-22). Requires the borrower (or position
+     * delegate) signer; the signature is scoped to exactly this outpoint.
+     */
+    invalidateStaleSpend(params: {
+        positionId: string;
+        utxoTxid: string;
+        utxoVout: number;
+        rpcUrl?: string;
+    }): Promise<{
+        success: boolean;
+        alreadySpent?: {
+            spendingTxid: string;
+        };
+        invalidatorTxid?: string;
+        invalidatorAmount?: number;
+        networkFee?: number;
+        /** True when the on-chain record's declared value ≠ the real output (corrupt-record recovery). */
+        valueMismatch?: boolean;
+        error?: string;
+        failedStep?: string;
+    }>;
+    /**
+     * Resumable, stateless clearing state machine for one stuck reservation —
+     * Bitcoin itself is the state store, so every call either advances the flow
+     * one step or reports where it stands (survives reloads and the multi-day
+     * 6-confirmation wait; no internal polling).
+     *
+     *  (a) reservation gone            → phase "cleared"
+     *  (b) outpoint spent, >=6 confs   → recoverStaleSpend → "cleared"/"failed"
+     *      outpoint spent, <6 confs    → "awaiting-confirmations" (x/6)
+     *  (c) outpoint unspent            → invalidateStaleSpend → "invalidator-broadcast"
+     */
+    clearStuckReservation(params: {
+        positionId: string;
+        utxoTxid: string;
+        utxoVout: number;
+        esploraBaseUrl?: string;
+    }): Promise<{
+        phase: "cleared" | "awaiting-confirmations" | "invalidator-broadcast" | "failed";
+        invalidatorTxid?: string;
+        confirmations?: number;
+        required?: number;
+        transactionHash?: string;
+        classification?: string;
+        valueMismatch?: boolean;
+        error?: string;
+    }>;
     /**
      * Withdraw BTC and execute transfer (Complete Flow)
      *

package/dist/utils/stale-spend-invalidate-message.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Borrower authorization envelope for the btc-utxo-invalidator Lit Action —
+ * the SDK-side mirror of `AuthorizationModule.verifyRecoveryAuthorization`
+ * (lit-actions/src/modules/authorization.module.ts:539). Field order and
+ * types MUST match byte-for-byte; the action recomputes this hash and
+ * EIP-191-recovers the borrower/delegate from it.
+ *
+ * NOTE: the lit-actions side hashes with ethers v5 `solidityKeccak256`, this
+ * side with v6 `solidityPackedKeccak256` — identical packed encoding; the
+ * unit test asserts byte-equality of the preimages so drift cannot sneak in.
+ */
+import { type Signer } from "ethers";
+/** Must equal RECOVERY_INVALIDATE_ACTION_STRING in lit-actions constants. */
+export declare const RECOVERY_INVALIDATE_ACTION = "btc-utxo-invalidator";
+export interface InvalidateStaleSpendEnvelope {
+    positionId: string;
+    utxoTxid: string;
+    utxoVout: number;
+    /** Quantum-aligned unix seconds bound into the signature. */
+    timestamp: number;
+    chainId: number;
+    action: typeof RECOVERY_INVALIDATE_ACTION;
+    signature: string;
+    borrowerAddress: string;
+}
+/** The exact packed hash `verifyRecoveryAuthorization` recomputes in-TEE. */
+export declare function buildInvalidateMessageHash(params: {
+    positionId: string;
+    timestamp: number;
+    chainId: number;
+    utxoTxid: string;
+    utxoVout: number;
+}): string;
+/**
+ * Build + sign the invalidate envelope with a quantum-aligned timestamp.
+ * The signature is scoped to exactly one (positionId, utxoTxid, utxoVout)
+ * recovery on one chain and cannot be replayed as any other authorization
+ * (the action string is pinned into the hash).
+ */
+export declare function buildInvalidateStaleSpendEnvelope(params: {
+    positionId: string;
+    utxoTxid: string;
+    utxoVout: number;
+    chainId: number;
+    signer: Signer;
+}): Promise<InvalidateStaleSpendEnvelope>;

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

@@ -0,0 +1,65 @@
+/**
+ * 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; recoverStaleSpend clears it.
+ * - CORRUPT         — authorization contradicts the chain (declared value ≠
+ *                     real output value, targetAmount > real value, or vout
+ *                     out of range) → operator recovery (admin clearing path);
+ *                     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.308",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -82,8 +82,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@gvnrdao/dh-lit-actions": "0.0.315",
-    "@gvnrdao/dh-lit-ops": "0.0.306",
+    "@gvnrdao/dh-lit-actions": "^0.0.316",
+    "@gvnrdao/dh-lit-ops": "^0.0.307",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",