@gvnrdao/dh-sdk 0.0.303 → 0.0.304

package/dist/index.js

@@ -6602,6 +6602,14 @@ var ServerSession = class {
   fetchImpl;
   cached = null;
   inFlight = null;
+  /**
+   * Bumped by `clearPersisted()` (logout / disconnect). An in-flight
+   * `getOrRefresh()` captures this at start and refuses to write its freshly
+   * minted token back to `this.cached`/the store if the value changed
+   * meanwhile — so a refresh racing a sign-out can't silently "un-clear" the
+   * credential it was told to drop.
+   */
+  generation = 0;
   /**
    * Store key for the current signer, memoized on first use so the sync
    * `clear()` can drop the persisted token without an async address lookup.
@@ -6617,8 +6625,22 @@ var ServerSession = class {
     this.now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
     this.fetchImpl = opts.fetchImpl ?? ((...a) => fetch(...a));
   }
-  /** Returns a JWT good for at least `REFRESH_LEEWAY_SECONDS` more seconds. */
-  async getValidToken() {
+  /**
+   * Returns a JWT good for at least `REFRESH_LEEWAY_SECONDS` more seconds.
+   * Pass `{ silent: true }` to forbid a fresh wallet signature: it resolves ONLY
+   * from a live cached token or the persisted re-mint envelope, never prompting
+   * and never joining a prompt-capable in-flight refresh (used by `logout()`,
+   * which must never pop the wallet during sign-out). Rejects when only a fresh
+   * signature could produce a token.
+   */
+  async getValidToken(opts) {
+    if (opts?.silent) {
+      const session2 = await this.tryResolveSilently(this.generation);
+      if (!session2) {
+        throw new Error("ServerSession: no existing session to refresh");
+      }
+      return session2.token;
+    }
     const session = await this.getOrRefresh();
     return session.token;
   }
@@ -6651,20 +6673,24 @@ var ServerSession = class {
    * from storage).
    */
   async clearPersisted() {
+    this.generation += 1;
     this.cached = null;
     this.inFlight = null;
     if (!this.store)
       return;
-    if (this.lastStoreKey) {
-      this.store.clear(this.lastStoreKey);
-      return;
-    }
     try {
-      const address = (await this.signer.getAddress()).toLowerCase();
-      this.store.clear(
-        sessionStoreKey(address, this.chainId, this.serviceEndpoint)
-      );
+      if (this.lastStoreKey) {
+        this.store.clear(this.lastStoreKey);
+      } else {
+        const address = (await this.signer.getAddress()).toLowerCase();
+        this.store.clear(
+          sessionStoreKey(address, this.chainId, this.serviceEndpoint)
+        );
+      }
     } catch {
+    } finally {
+      this.generation += 1;
+      this.cached = null;
     }
   }
   /**
@@ -6674,7 +6700,8 @@ var ServerSession = class {
    * of server response so the client stops presenting the token.
    */
   async logout() {
-    const token = this.cached?.token ?? await this.getValidToken().catch(() => null);
+    const cached = this.cached;
+    const token = cached && cached.expiresAt > this.now() ? cached.token : await this.getValidToken({ silent: true }).catch(() => null);
     await this.clearPersisted();
     if (!token)
       return;
@@ -6689,6 +6716,50 @@ var ServerSession = class {
       );
     }
   }
+  /**
+   * Resolve a session WITHOUT ever prompting for a wallet signature: a live
+   * cached token, else the persisted JWT (adopted if still fresh, otherwise
+   * silently re-minted from the envelope). Returns `null` only when a fresh
+   * wallet signature would be required (dead/absent envelope). Never touches
+   * `this.inFlight`, so a silent caller (logout) can resolve independently
+   * instead of being dragged into a prompt-capable refresh already in flight.
+   *
+   * `gen` is the caller's clear-generation snapshot: writes to `this.cached`
+   * and the store are skipped if a `clearPersisted()` landed meanwhile.
+   */
+  async tryResolveSilently(gen) {
+    const nowSec = this.now();
+    if (this.cached && this.cached.expiresAt - REFRESH_LEEWAY_SECONDS > nowSec) {
+      return this.cached;
+    }
+    const persisted = await this.loadPersisted();
+    if (!persisted)
+      return null;
+    if (persisted.token && typeof persisted.tokenExpiresAt === "number" && persisted.tokenExpiresAt - REFRESH_LEEWAY_SECONDS > this.now()) {
+      const adopted = {
+        token: persisted.token,
+        expiresAt: persisted.tokenExpiresAt
+      };
+      if (gen === this.generation)
+        this.cached = adopted;
+      return adopted;
+    }
+    try {
+      const session = await this.login(persisted.payload);
+      if (gen === this.generation) {
+        this.persist(persisted.payload, session);
+        this.cached = session;
+      }
+      return session;
+    } catch (error) {
+      if (!isLoginRejection(error))
+        throw error;
+      if (gen === this.generation && this.store && this.lastStoreKey) {
+        this.store.clear(this.lastStoreKey);
+      }
+      return null;
+    }
+  }
   async getOrRefresh() {
     const nowSec = this.now();
     if (this.cached && this.cached.expiresAt - REFRESH_LEEWAY_SECONDS > nowSec) {
@@ -6696,30 +6767,13 @@ var ServerSession = class {
     }
     if (this.inFlight)
       return this.inFlight;
+    const gen = this.generation;
+    const notCleared = () => gen === this.generation;
     this.inFlight = (async () => {
       try {
-        const persisted = await this.loadPersisted();
-        if (persisted) {
-          if (persisted.token && typeof persisted.tokenExpiresAt === "number" && persisted.tokenExpiresAt - REFRESH_LEEWAY_SECONDS > this.now()) {
-            this.cached = {
-              token: persisted.token,
-              expiresAt: persisted.tokenExpiresAt
-            };
-            return this.cached;
-          }
-          try {
-            const session2 = await this.login(persisted.payload);
-            this.persist(persisted.payload, session2);
-            this.cached = session2;
-            return session2;
-          } catch (error) {
-            if (!isLoginRejection(error))
-              throw error;
-            if (this.store && this.lastStoreKey) {
-              this.store.clear(this.lastStoreKey);
-            }
-          }
-        }
+        const existing = await this.tryResolveSilently(gen);
+        if (existing)
+          return existing;
         this.onSignaturePrompt?.();
         const payload = await buildSignedLoginPayload(
           this.signer,
@@ -6727,11 +6781,14 @@ var ServerSession = class {
           this.serviceEndpoint
         );
         const session = await this.login(payload);
-        this.persist(payload, session);
-        this.cached = session;
+        if (notCleared()) {
+          this.persist(payload, session);
+          this.cached = session;
+        }
         return session;
       } finally {
-        this.inFlight = null;
+        if (notCleared())
+          this.inFlight = null;
       }
     })();
     return this.inFlight;
@@ -16104,13 +16161,25 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
     return this.serverSession.getAuthHeader();
   }
   /**
-   * Remove the persisted lit-ops-server session (the 24h re-mint envelope and
-   * its JWT) for the current auth signer. Call on wallet disconnect or
-   * explicit sign-out so the credential does not outlive the wallet
-   * connection. No-op in standalone mode.
+   * Sign out of the lit-ops-server session for the current auth signer. Call on
+   * wallet disconnect or explicit sign-out so the credential does not outlive
+   * the wallet connection. No-op in standalone mode.
+   *
+   * Attempts a server-side revocation first (`ServerSession.logout()` — which
+   * tombstones the envelope's 24h re-mint window and invalidates the JWT), then
+   * always removes the local credential. If the revocation call fails (offline,
+   * server down, wallet already disconnected) we still clear locally so the
+   * session cannot silently re-mint after sign-out; `logout()` is best-effort
+   * and never prompts the wallet.
    */
   async clearServerSession() {
-    await this.serverSession?.clearPersisted();
+    if (!this.serverSession)
+      return;
+    try {
+      await this.serverSession.logout();
+    } catch {
+      await this.serverSession.clearPersisted();
+    }
   }
   /**
    * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
@@ -20715,6 +20784,42 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       };
     }
   }
+  /**
+   * TEMPORARY (multi-UTXO withdrawal fix, Phase A): fetch the vault's confirmed
+   * UTXO set from lit-ops-server (`GET /api/lit/vault-utxos`) so the caller can
+   * assemble and sign the FULL input set for a multi-UTXO consolidation
+   * withdrawal. Phase 1 only returns ONE representative UTXO, so a vault whose
+   * balance is spread across several UTXOs otherwise fails the Phase-2 signer
+   * with "Insufficient UTXO value ... across 1 input(s)".
+   *
+   * Returns `[]` on any failure (non-service mode, network error, bad shape) so
+   * callers transparently fall back to the single authorized UTXO. Superseded
+   * by the btc-withdrawal Lit Action returning its own confirmedUTXOs (Phase B).
+   */
+  async fetchConfirmedVaultUtxos(positionId) {
+    if (this.config.mode !== "service" || !this.config.serviceEndpoint)
+      return [];
+    try {
+      const pid = positionId.startsWith("0x") ? positionId : `0x${positionId}`;
+      const resp = await fetch(
+        `${this.config.serviceEndpoint}/api/lit/vault-utxos?positionId=${encodeURIComponent(pid)}`,
+        { method: "GET", headers: { ...await this.getAuthHeader() } }
+      );
+      if (!resp.ok)
+        return [];
+      const json = await resp.json();
+      if (!json.success || !Array.isArray(json.data?.utxos))
+        return [];
+      return json.data.utxos.map((u) => ({
+        txid: String(u.txid),
+        vout: Number(u.vout),
+        value: Number(u.value),
+        confirmations: Number(u.confirmations ?? 0)
+      }));
+    } catch {
+      return [];
+    }
+  }
   /**
    * Execute Bitcoin withdrawal (Phase 2)
    *
@@ -21331,13 +21436,44 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       if (this.config.debug) {
         log.info("\u{1F50D} Found vault UTXO for execution", { utxoIdentifier });
       }
+      let executionUtxos;
+      const gatheredUtxos = await this.fetchConfirmedVaultUtxos(positionId);
+      if (gatheredUtxos.length > 0) {
+        const normTxid = (t) => String(t).toLowerCase().replace(/^0x/, "");
+        const byOutpoint = /* @__PURE__ */ new Map();
+        for (const u of gatheredUtxos) {
+          const txid = normTxid(u.txid);
+          byOutpoint.set(`${txid}:${u.vout}`, {
+            txid,
+            vout: Number(u.vout),
+            value: Number(u.value)
+          });
+        }
+        const repKey = `${normTxid(authResult.utxoTxid)}:${authResult.utxoVout}`;
+        if (!byOutpoint.has(repKey)) {
+          byOutpoint.set(repKey, {
+            txid: normTxid(authResult.utxoTxid),
+            vout: Number(authResult.utxoVout),
+            value: Number(authResult.utxoSatoshis)
+          });
+        }
+        if (byOutpoint.size > 1) {
+          executionUtxos = Array.from(byOutpoint.values());
+          if (this.config.debug) {
+            log.info("\u{1F9E9} Multi-UTXO withdrawal: signing full input set", {
+              inputs: executionUtxos.length
+            });
+          }
+        }
+      }
       const executionResult = await this.executeBTCWithdrawal({
         positionId,
         utxoIdentifier,
         utxoSatoshis: Number(authResult.utxoSatoshis),
         networkFee,
         destination: withdrawalAddress,
-        targetAmount: withdrawalAmount
+        targetAmount: withdrawalAmount,
+        ...executionUtxos ? { utxos: executionUtxos } : {}
       });
       if (this.config.debug) {
         log.info("\u2705 Phase 2 complete: Bitcoin transaction executed", {

package/dist/index.mjs

@@ -6526,6 +6526,14 @@ var ServerSession = class {
   fetchImpl;
   cached = null;
   inFlight = null;
+  /**
+   * Bumped by `clearPersisted()` (logout / disconnect). An in-flight
+   * `getOrRefresh()` captures this at start and refuses to write its freshly
+   * minted token back to `this.cached`/the store if the value changed
+   * meanwhile — so a refresh racing a sign-out can't silently "un-clear" the
+   * credential it was told to drop.
+   */
+  generation = 0;
   /**
    * Store key for the current signer, memoized on first use so the sync
    * `clear()` can drop the persisted token without an async address lookup.
@@ -6541,8 +6549,22 @@ var ServerSession = class {
     this.now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
     this.fetchImpl = opts.fetchImpl ?? ((...a) => fetch(...a));
   }
-  /** Returns a JWT good for at least `REFRESH_LEEWAY_SECONDS` more seconds. */
-  async getValidToken() {
+  /**
+   * Returns a JWT good for at least `REFRESH_LEEWAY_SECONDS` more seconds.
+   * Pass `{ silent: true }` to forbid a fresh wallet signature: it resolves ONLY
+   * from a live cached token or the persisted re-mint envelope, never prompting
+   * and never joining a prompt-capable in-flight refresh (used by `logout()`,
+   * which must never pop the wallet during sign-out). Rejects when only a fresh
+   * signature could produce a token.
+   */
+  async getValidToken(opts) {
+    if (opts?.silent) {
+      const session2 = await this.tryResolveSilently(this.generation);
+      if (!session2) {
+        throw new Error("ServerSession: no existing session to refresh");
+      }
+      return session2.token;
+    }
     const session = await this.getOrRefresh();
     return session.token;
   }
@@ -6575,20 +6597,24 @@ var ServerSession = class {
    * from storage).
    */
   async clearPersisted() {
+    this.generation += 1;
     this.cached = null;
     this.inFlight = null;
     if (!this.store)
       return;
-    if (this.lastStoreKey) {
-      this.store.clear(this.lastStoreKey);
-      return;
-    }
     try {
-      const address = (await this.signer.getAddress()).toLowerCase();
-      this.store.clear(
-        sessionStoreKey(address, this.chainId, this.serviceEndpoint)
-      );
+      if (this.lastStoreKey) {
+        this.store.clear(this.lastStoreKey);
+      } else {
+        const address = (await this.signer.getAddress()).toLowerCase();
+        this.store.clear(
+          sessionStoreKey(address, this.chainId, this.serviceEndpoint)
+        );
+      }
     } catch {
+    } finally {
+      this.generation += 1;
+      this.cached = null;
     }
   }
   /**
@@ -6598,7 +6624,8 @@ var ServerSession = class {
    * of server response so the client stops presenting the token.
    */
   async logout() {
-    const token = this.cached?.token ?? await this.getValidToken().catch(() => null);
+    const cached = this.cached;
+    const token = cached && cached.expiresAt > this.now() ? cached.token : await this.getValidToken({ silent: true }).catch(() => null);
     await this.clearPersisted();
     if (!token)
       return;
@@ -6613,6 +6640,50 @@ var ServerSession = class {
       );
     }
   }
+  /**
+   * Resolve a session WITHOUT ever prompting for a wallet signature: a live
+   * cached token, else the persisted JWT (adopted if still fresh, otherwise
+   * silently re-minted from the envelope). Returns `null` only when a fresh
+   * wallet signature would be required (dead/absent envelope). Never touches
+   * `this.inFlight`, so a silent caller (logout) can resolve independently
+   * instead of being dragged into a prompt-capable refresh already in flight.
+   *
+   * `gen` is the caller's clear-generation snapshot: writes to `this.cached`
+   * and the store are skipped if a `clearPersisted()` landed meanwhile.
+   */
+  async tryResolveSilently(gen) {
+    const nowSec = this.now();
+    if (this.cached && this.cached.expiresAt - REFRESH_LEEWAY_SECONDS > nowSec) {
+      return this.cached;
+    }
+    const persisted = await this.loadPersisted();
+    if (!persisted)
+      return null;
+    if (persisted.token && typeof persisted.tokenExpiresAt === "number" && persisted.tokenExpiresAt - REFRESH_LEEWAY_SECONDS > this.now()) {
+      const adopted = {
+        token: persisted.token,
+        expiresAt: persisted.tokenExpiresAt
+      };
+      if (gen === this.generation)
+        this.cached = adopted;
+      return adopted;
+    }
+    try {
+      const session = await this.login(persisted.payload);
+      if (gen === this.generation) {
+        this.persist(persisted.payload, session);
+        this.cached = session;
+      }
+      return session;
+    } catch (error) {
+      if (!isLoginRejection(error))
+        throw error;
+      if (gen === this.generation && this.store && this.lastStoreKey) {
+        this.store.clear(this.lastStoreKey);
+      }
+      return null;
+    }
+  }
   async getOrRefresh() {
     const nowSec = this.now();
     if (this.cached && this.cached.expiresAt - REFRESH_LEEWAY_SECONDS > nowSec) {
@@ -6620,30 +6691,13 @@ var ServerSession = class {
     }
     if (this.inFlight)
       return this.inFlight;
+    const gen = this.generation;
+    const notCleared = () => gen === this.generation;
     this.inFlight = (async () => {
       try {
-        const persisted = await this.loadPersisted();
-        if (persisted) {
-          if (persisted.token && typeof persisted.tokenExpiresAt === "number" && persisted.tokenExpiresAt - REFRESH_LEEWAY_SECONDS > this.now()) {
-            this.cached = {
-              token: persisted.token,
-              expiresAt: persisted.tokenExpiresAt
-            };
-            return this.cached;
-          }
-          try {
-            const session2 = await this.login(persisted.payload);
-            this.persist(persisted.payload, session2);
-            this.cached = session2;
-            return session2;
-          } catch (error) {
-            if (!isLoginRejection(error))
-              throw error;
-            if (this.store && this.lastStoreKey) {
-              this.store.clear(this.lastStoreKey);
-            }
-          }
-        }
+        const existing = await this.tryResolveSilently(gen);
+        if (existing)
+          return existing;
         this.onSignaturePrompt?.();
         const payload = await buildSignedLoginPayload(
           this.signer,
@@ -6651,11 +6705,14 @@ var ServerSession = class {
           this.serviceEndpoint
         );
         const session = await this.login(payload);
-        this.persist(payload, session);
-        this.cached = session;
+        if (notCleared()) {
+          this.persist(payload, session);
+          this.cached = session;
+        }
         return session;
       } finally {
-        this.inFlight = null;
+        if (notCleared())
+          this.inFlight = null;
       }
     })();
     return this.inFlight;
@@ -16032,13 +16089,25 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
     return this.serverSession.getAuthHeader();
   }
   /**
-   * Remove the persisted lit-ops-server session (the 24h re-mint envelope and
-   * its JWT) for the current auth signer. Call on wallet disconnect or
-   * explicit sign-out so the credential does not outlive the wallet
-   * connection. No-op in standalone mode.
+   * Sign out of the lit-ops-server session for the current auth signer. Call on
+   * wallet disconnect or explicit sign-out so the credential does not outlive
+   * the wallet connection. No-op in standalone mode.
+   *
+   * Attempts a server-side revocation first (`ServerSession.logout()` — which
+   * tombstones the envelope's 24h re-mint window and invalidates the JWT), then
+   * always removes the local credential. If the revocation call fails (offline,
+   * server down, wallet already disconnected) we still clear locally so the
+   * session cannot silently re-mint after sign-out; `logout()` is best-effort
+   * and never prompts the wallet.
    */
   async clearServerSession() {
-    await this.serverSession?.clearPersisted();
+    if (!this.serverSession)
+      return;
+    try {
+      await this.serverSession.logout();
+    } catch {
+      await this.serverSession.clearPersisted();
+    }
   }
   /**
    * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
@@ -20643,6 +20712,42 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       };
     }
   }
+  /**
+   * TEMPORARY (multi-UTXO withdrawal fix, Phase A): fetch the vault's confirmed
+   * UTXO set from lit-ops-server (`GET /api/lit/vault-utxos`) so the caller can
+   * assemble and sign the FULL input set for a multi-UTXO consolidation
+   * withdrawal. Phase 1 only returns ONE representative UTXO, so a vault whose
+   * balance is spread across several UTXOs otherwise fails the Phase-2 signer
+   * with "Insufficient UTXO value ... across 1 input(s)".
+   *
+   * Returns `[]` on any failure (non-service mode, network error, bad shape) so
+   * callers transparently fall back to the single authorized UTXO. Superseded
+   * by the btc-withdrawal Lit Action returning its own confirmedUTXOs (Phase B).
+   */
+  async fetchConfirmedVaultUtxos(positionId) {
+    if (this.config.mode !== "service" || !this.config.serviceEndpoint)
+      return [];
+    try {
+      const pid = positionId.startsWith("0x") ? positionId : `0x${positionId}`;
+      const resp = await fetch(
+        `${this.config.serviceEndpoint}/api/lit/vault-utxos?positionId=${encodeURIComponent(pid)}`,
+        { method: "GET", headers: { ...await this.getAuthHeader() } }
+      );
+      if (!resp.ok)
+        return [];
+      const json = await resp.json();
+      if (!json.success || !Array.isArray(json.data?.utxos))
+        return [];
+      return json.data.utxos.map((u) => ({
+        txid: String(u.txid),
+        vout: Number(u.vout),
+        value: Number(u.value),
+        confirmations: Number(u.confirmations ?? 0)
+      }));
+    } catch {
+      return [];
+    }
+  }
   /**
    * Execute Bitcoin withdrawal (Phase 2)
    *
@@ -21259,13 +21364,44 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       if (this.config.debug) {
         log.info("\u{1F50D} Found vault UTXO for execution", { utxoIdentifier });
       }
+      let executionUtxos;
+      const gatheredUtxos = await this.fetchConfirmedVaultUtxos(positionId);
+      if (gatheredUtxos.length > 0) {
+        const normTxid = (t) => String(t).toLowerCase().replace(/^0x/, "");
+        const byOutpoint = /* @__PURE__ */ new Map();
+        for (const u of gatheredUtxos) {
+          const txid = normTxid(u.txid);
+          byOutpoint.set(`${txid}:${u.vout}`, {
+            txid,
+            vout: Number(u.vout),
+            value: Number(u.value)
+          });
+        }
+        const repKey = `${normTxid(authResult.utxoTxid)}:${authResult.utxoVout}`;
+        if (!byOutpoint.has(repKey)) {
+          byOutpoint.set(repKey, {
+            txid: normTxid(authResult.utxoTxid),
+            vout: Number(authResult.utxoVout),
+            value: Number(authResult.utxoSatoshis)
+          });
+        }
+        if (byOutpoint.size > 1) {
+          executionUtxos = Array.from(byOutpoint.values());
+          if (this.config.debug) {
+            log.info("\u{1F9E9} Multi-UTXO withdrawal: signing full input set", {
+              inputs: executionUtxos.length
+            });
+          }
+        }
+      }
       const executionResult = await this.executeBTCWithdrawal({
         positionId,
         utxoIdentifier,
         utxoSatoshis: Number(authResult.utxoSatoshis),
         networkFee,
         destination: withdrawalAddress,
-        targetAmount: withdrawalAmount
+        targetAmount: withdrawalAmount,
+        ...executionUtxos ? { utxos: executionUtxos } : {}
       });
       if (this.config.debug) {
         log.info("\u2705 Phase 2 complete: Bitcoin transaction executed", {

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

@@ -112,10 +112,16 @@ export declare class DiamondHandsSDK {
      */
     private getAuthHeader;
     /**
-     * Remove the persisted lit-ops-server session (the 24h re-mint envelope and
-     * its JWT) for the current auth signer. Call on wallet disconnect or
-     * explicit sign-out so the credential does not outlive the wallet
-     * connection. No-op in standalone mode.
+     * Sign out of the lit-ops-server session for the current auth signer. Call on
+     * wallet disconnect or explicit sign-out so the credential does not outlive
+     * the wallet connection. No-op in standalone mode.
+     *
+     * Attempts a server-side revocation first (`ServerSession.logout()` — which
+     * tombstones the envelope's 24h re-mint window and invalidates the JWT), then
+     * always removes the local credential. If the revocation call fails (offline,
+     * server down, wallet already disconnected) we still clear locally so the
+     * session cannot silently re-mint after sign-out; `logout()` is best-effort
+     * and never prompts the wallet.
      */
     clearServerSession(): Promise<void>;
     /**
@@ -442,6 +448,24 @@ export declare class DiamondHandsSDK {
      * @returns Withdrawal result with transaction details
      */
     withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number): Promise<BTCWithdrawalResult>;
+    /**
+     * TEMPORARY (multi-UTXO withdrawal fix, Phase A): fetch the vault's confirmed
+     * UTXO set from lit-ops-server (`GET /api/lit/vault-utxos`) so the caller can
+     * assemble and sign the FULL input set for a multi-UTXO consolidation
+     * withdrawal. Phase 1 only returns ONE representative UTXO, so a vault whose
+     * balance is spread across several UTXOs otherwise fails the Phase-2 signer
+     * with "Insufficient UTXO value ... across 1 input(s)".
+     *
+     * Returns `[]` on any failure (non-service mode, network error, bad shape) so
+     * callers transparently fall back to the single authorized UTXO. Superseded
+     * by the btc-withdrawal Lit Action returning its own confirmedUTXOs (Phase B).
+     */
+    fetchConfirmedVaultUtxos(positionId: string): Promise<Array<{
+        txid: string;
+        vout: number;
+        value: number;
+        confirmations: number;
+    }>>;
     /**
      * Execute Bitcoin withdrawal (Phase 2)
      *