@gvnrdao/dh-sdk 0.0.307 → 0.0.308

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

@@ -546,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;
@@ -564,11 +564,15 @@ export declare class DiamondHandsSDK {
      * 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.
+     * - 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); offer Cancel &
-     *                     re-request — Execute can only die at the signer guard.
+     *                     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
@@ -578,18 +582,6 @@ export declare class DiamondHandsSDK {
     reconcilePendingWithdrawals(positionId: string, opts?: {
         esploraBaseUrl?: string;
     }): Promise<Array<ReconciledWithdrawal<Awaited<ReturnType<DiamondHandsSDK["getPendingWithdrawals"]>>[number]>>>;
-    /**
-     * 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
-     */
     /**
      * Recover (clear) a stale BTC reservation via LIT-attested proof.
      *
@@ -639,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

@@ -16,10 +16,11 @@
  * - 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.
+ *                     nothing → unexecutable; recoverStaleSpend clears it.
  * - CORRUPT         — authorization contradicts the chain (declared value ≠
  *                     real output value, targetAmount > real value, or vout
- *                     out of range) → surface Cancel & re-request; never Execute.
+ *                     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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.307",
+  "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",