@gvnrdao/dh-sdk 0.0.301 → 0.0.304

package/dist/interfaces/chunks/config.i.d.ts

@@ -3,6 +3,7 @@
  */
 import type { Wallet, Signer, Provider } from "ethers";
 import { LitNetwork } from "@gvnrdao/dh-lit-ops";
+import type { ServerSessionStore } from "../../utils/server-session-store";
 export type SDKMode = "standalone" | "service";
 /**
  * Contract Addresses Configuration
@@ -55,6 +56,27 @@ interface BaseSDKConfig {
      * is a SafeModuleSignerAdapter that routes transactions through the module.
      */
     authSigner?: Wallet | Signer;
+    /**
+     * Persistence for the lit-ops-server session (service mode). The signed
+     * EIP-712 login envelope silently re-mints 15-minute JWTs for up to 24h, so
+     * persisting it means at most one wallet signature per day per device
+     * instead of one per 15 minutes / page reload. Defaults to enabled with
+     * `localStorage` in browsers; degrades to per-instance memory elsewhere.
+     * Note the persisted envelope is a re-mint credential for its window —
+     * call `clearServerSession()` on wallet disconnect.
+     */
+    sessionPersistence?: {
+        /** Default true. Set false for a fresh signature per instance + expiry. */
+        enabled?: boolean;
+        /** Custom store (e.g. a file-backed store for CLI daemons). */
+        store?: ServerSessionStore;
+    };
+    /**
+     * Fires immediately before the server-session login requests a wallet
+     * signature — never on the silent re-mint paths. Lets UIs show a
+     * "check your wallet" prompt.
+     */
+    onSessionSignaturePrompt?: () => void;
     ethRpcUrl?: string;
     chainId?: number;
     networkOverride?: {

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

@@ -111,6 +111,19 @@ export declare class DiamondHandsSDK {
      * reject the call with 401, which is the correct outcome.
      */
     private getAuthHeader;
+    /**
+     * 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>;
     /**
      * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
      * the post-write state. We clear the entire loan-query cache (not just
@@ -435,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)
      *
@@ -456,6 +487,17 @@ export declare class DiamondHandsSDK {
          * Action can cross-check against the on-chain authorizer record.
          */
         targetAmount: number;
+        /**
+         * FULL input set the phase-2 signer may spend (P6/#8 — bound into the
+         * signature via a canonical set hash). Omit for the common single-UTXO
+         * withdrawal; multi-UTXO consolidation withdrawals MUST list every input
+         * (each with its full sat value), including the authorized UTXO.
+         */
+        utxos?: Array<{
+            txid: string;
+            vout: number;
+            value: number;
+        }>;
     }): Promise<{
         success: boolean;
         txid?: string;
@@ -658,6 +700,13 @@ export declare class DiamondHandsSDK {
      * Get all events for a loan position from the subgraph
      */
     getLoanEvents(positionId: string, filter?: import("../types/event-types").LoanEventsFilter): Promise<Result<import("../types/event-types").LoanEvents, SDKError>>;
+    /**
+     * Get loan-event history for every position owned by a wallet.
+     * Composes getUserPositions + getLoanEvents; returns one LoanEvents per
+     * position (each carrying its own positionId). Bitcoin deposits are not on the
+     * subgraph — merge those in from an Esplora source on the consumer side.
+     */
+    getWalletLoanEvents(userAddress: string, filter?: import("../types/event-types").LoanEventsFilter): Promise<Result<import("../types/event-types").LoanEvents[], SDKError>>;
     /**
      * Get protocol-wide events across all indexed entity types.
      * Returns a merged, sorted discriminated-union timeline.
@@ -839,6 +888,22 @@ export declare class DiamondHandsSDK {
         signature: string;
         validatorPkp: string;
     }, SDKError>>;
+    /**
+     * List a vault address's PENDING (not-yet-confirmed) incoming BTC deposits.
+     *
+     * A deposit is "pending" until it reaches the protocol's minimum confirmation
+     * depth (6) — the confirmed balance endpoints (`getVaultBalance` /
+     * `getAddressBalance`) omit anything shallower, so this surfaces in-flight
+     * deposits (0–5 confirmations). Server-delegated: lit-ops-server queries its
+     * configured premium Esplora provider (`/api/lit/pending-deposits`). Requires
+     * service mode.
+     */
+    getPendingDeposits(vaultAddress: string): Promise<Array<{
+        txid: string;
+        sats: number;
+        confirmations: number;
+        minConfirmations: number;
+    }>>;
     /**
      * Mint mock BTC tokens (test networks only)
      *

package/dist/modules/loan/loan-query.module.d.ts

@@ -187,6 +187,29 @@ export declare class LoanQuery {
      * ```
      */
     getLoanEvents(positionId: string, filter?: LoanEventsFilter): Promise<Result<LoanEvents, SDKError>>;
+    /**
+     * Get loan-event history for every position owned by a wallet.
+     *
+     * Composes getUserPositions + getLoanEvents (the subgraph has no wallet-scoped
+     * event collection). Each returned LoanEvents carries its own positionId, so
+     * callers can flatten and merge into a single per-wallet timeline.
+     *
+     * Bitcoin deposits never appear in the subgraph — merge those in from an
+     * Esplora source on the consumer side.
+     *
+     * @param userAddress - Loan-owner wallet address.
+     * @param filter - Optional per-position event filter (same semantics as getLoanEvents).
+     * @returns One LoanEvents object per position (empty array if the wallet has none).
+     *
+     * @example
+     * ```typescript
+     * const result = await loanQuery.getWalletLoanEvents('0x830b...');
+     * if (result.success) {
+     *   const allEvents = result.value; // LoanEvents[] — one per position
+     * }
+     * ```
+     */
+    getWalletLoanEvents(userAddress: string, filter?: LoanEventsFilter): Promise<Result<LoanEvents[], SDKError>>;
     /**
      * Clear loan cache
      *

package/dist/types/authorization-params.d.ts

@@ -40,8 +40,6 @@ export interface MintUCDAuthParams extends BaseAuthParams {
     amount: UCD;
     /** PKP public key (optional - validator PKP is passed separately to authorizeMintUCD) */
     publicKey?: string;
-    /** Bitcoin provider URL for balance verification */
-    bitcoinProviderUrl?: string;
     /** Selected term in months (override when contract state is zero) */
     selectedTerm?: number;
 }

package/dist/utils/btc-withdrawal-message.d.ts

@@ -14,6 +14,24 @@ export interface BtcExecuteSignParams {
     chainId: number;
     signer: Signer;
 }
+/** One Bitcoin input the borrower authorizes the phase-2 signer to spend. */
+export interface BtcExecuteInput {
+    txid: string;
+    vout: number;
+    /** Full output value in sats (feeds the BIP143 sighash). */
+    value: number;
+}
+/**
+ * Canonical hash of a Bitcoin input set (remediation P6/#8).
+ *
+ * CANONICALIZATION MUST MATCH
+ * `lit-actions/src/modules/bitcoin/utxo-set-hash.ts` byte-for-byte: entries
+ * normalized to `${txidLowercase}:${vout}:${value}`, sorted by (txid asc,
+ * vout asc), joined with "|", then keccak256 over the UTF-8 bytes. The Lit
+ * Action recomputes this over the `utxos[]` it actually signs, so an operator
+ * cannot spend inputs beyond the set hashed here.
+ */
+export declare function hashBtcInputSet(utxos: BtcExecuteInput[]): string;
 export interface BtcExecuteSignedEnvelope {
     positionId: string;
     txid: string;
@@ -31,6 +49,12 @@ export interface BtcExecuteSignedEnvelope {
     userSignature: string;
     /** Address recovered from the signer (borrower). */
     borrowerAddress: string;
+    /**
+     * The FULL input set bound into the signature (P6/#8). The server must
+     * forward exactly this set to the phase-2 signer — any other set fails
+     * signature verification in the Lit Action.
+     */
+    utxos: BtcExecuteInput[];
 }
 /**
  * Build the quantum-aligned timestamp + EIP-191 signature the
@@ -57,4 +81,11 @@ export declare function buildBtcExecuteEnvelope(params: BtcExecuteSignParams & {
     satoshis: number;
     targetAddress: string;
     targetAmount: number;
+    /**
+     * FULL input set the phase-2 signer may spend (P6/#8). Omit for the
+     * common single-UTXO withdrawal — it defaults to exactly the authorized
+     * UTXO, the most restrictive set. Multi-UTXO consolidation withdrawals
+     * MUST list every input here; the authorized UTXO must be among them.
+     */
+    utxos?: BtcExecuteInput[];
 }): Promise<BtcExecuteSignedEnvelope>;

package/dist/utils/server-session-store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Client-side persistence for the lit-ops-server session.
+ *
+ * The server accepts re-mints of the SAME signed login envelope until
+ * `issuedAt + REAUTH_WINDOW_SECONDS` (see lit-ops-server `login-handler.ts`),
+ * so caching the signed payload means an expired 15-minute JWT — or a full
+ * page reload — costs one silent API call instead of another wallet popup.
+ * Mirrors the frontend's `wallet-login-cache.ts` pattern for the Firebase
+ * `DhWebLogin` flow.
+ *
+ * Browser-safe: the default store auto-detects `localStorage` and degrades to
+ * a per-instance in-memory map elsewhere (Node, blocked storage), which keeps
+ * exactly the pre-persistence behavior.
+ */
+import type { DhServerLoginPayload } from "./eip712-login";
+/** Must match lit-ops-server's REAUTH_WINDOW_SECONDS (`eip712-digest.ts`). */
+export declare const REAUTH_WINDOW_SECONDS: number;
+/** Stop using a cached payload this long before the server would reject it. */
+export declare const SAFETY_MARGIN_SECONDS: number;
+/** One persisted session: the 24h re-mint credential plus the current JWT. */
+export interface PersistedServerSession {
+    version: 1;
+    /** Lowercased signer address the payload authenticates. */
+    address: string;
+    chainId: number;
+    /** Normalized service endpoint (trailing slashes stripped) — the signed audience. */
+    endpoint: string;
+    payload: DhServerLoginPayload;
+    /** Current JWT, if still live — lets a reload skip even the silent re-mint call. */
+    token?: string;
+    /** JWT expiry, unix seconds. */
+    tokenExpiresAt?: number;
+}
+/**
+ * Pluggable persistence. Implementations must be best-effort and never throw
+ * out of `save`/`clear`; `load` returns null for absent or malformed entries.
+ */
+export interface ServerSessionStore {
+    load(key: string): PersistedServerSession | null;
+    save(key: string, session: PersistedServerSession): void;
+    clear(key: string): void;
+}
+export declare function sessionStoreKey(address: string, chainId: number, endpoint: string): string;
+export declare class LocalStorageSessionStore implements ServerSessionStore {
+    load(key: string): PersistedServerSession | null;
+    save(key: string, session: PersistedServerSession): void;
+    clear(key: string): void;
+}
+export declare class MemorySessionStore implements ServerSessionStore {
+    private readonly entries;
+    load(key: string): PersistedServerSession | null;
+    save(key: string, session: PersistedServerSession): void;
+    clear(key: string): void;
+}
+/** `localStorage` when usable (browser, not blocked), else per-instance memory. */
+export declare function createDefaultSessionStore(): ServerSessionStore;

package/dist/utils/server-session.d.ts

@@ -1,50 +1,132 @@
 /**
- * In-memory session JWT manager for lit-ops-server.
+ * Session JWT manager for lit-ops-server.
  *
  * The server's `POST /api/auth/login` route accepts an EIP-712-signed
- * `DhServerLogin` envelope and returns an HS256 JWT with a 15-minute TTL.
- * This helper:
+ * `DiamondHands` envelope and returns an HS256 JWT with a 15-minute TTL. The
+ * same signed envelope may silently re-mint fresh JWTs until
+ * `issuedAt + REAUTH_WINDOW_SECONDS` (24h), so a wallet signature is only
+ * needed once per window. This helper:
  *
  *   - caches the JWT until ~30s before expiry,
+ *   - persists the signed envelope (+ current JWT) via a pluggable store —
+ *     `localStorage` in browsers by default — so page reloads and expired
+ *     JWTs recover WITHOUT another wallet popup,
  *   - coalesces concurrent callers behind a single in-flight Promise so we
  *     don't spam `/api/auth/login` on parallel SDK calls,
  *   - exposes `getValidToken()` returning the live token and
  *     `getAuthHeader()` returning a ready-to-spread `{ Authorization: ... }`
  *     object.
  *
- * Browser-safe — no filesystem touches. The CLI mirrors this shape but
- * persists to `~/.diamond-hands/session.json` for cross-invocation reuse.
+ * Browser-safe — no filesystem touches; outside browsers the store degrades
+ * to per-instance memory. The CLI mirrors this shape but persists to
+ * `~/.diamond-hands/session.json` for cross-invocation reuse.
  */
 import type { Signer } from "ethers";
+import { type ServerSessionStore } from "./server-session-store";
 export interface ServerSessionOptions {
     signer: Signer;
     serviceEndpoint: string;
     chainId: number;
+    /**
+     * Persistence for the signed login envelope + JWT. Defaults to
+     * `localStorage` in browsers and per-instance memory elsewhere.
+     */
+    sessionStore?: ServerSessionStore;
+    /** Set false to disable persistence entirely (fresh signature per instance + expiry). */
+    persistSession?: boolean;
+    /**
+     * Fires immediately before a wallet signature is requested — i.e. only when
+     * neither the cached JWT nor the persisted envelope could renew the session,
+     * never on the silent paths. Lets UIs show a "check your wallet" prompt.
+     */
+    onSignaturePrompt?: () => void;
     /** Override for tests. */
     now?: () => number;
     /** Override for tests. */
     fetchImpl?: typeof fetch;
 }
+/** Login failure carrying the HTTP status so callers can tell rejection from outage. */
+export declare class ServerLoginError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
 export declare class ServerSession {
     private readonly signer;
     private readonly serviceEndpoint;
     private readonly chainId;
+    private readonly store;
+    private readonly onSignaturePrompt?;
     private readonly now;
     private readonly fetchImpl;
     private cached;
     private inFlight;
+    /**
+     * 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.
+     */
+    private generation;
+    /**
+     * Store key for the current signer, memoized on first use so the sync
+     * `clear()` can drop the persisted token without an async address lookup.
+     */
+    private lastStoreKey;
     constructor(opts: ServerSessionOptions);
-    /** Returns a JWT good for at least `REFRESH_LEEWAY_SECONDS` more seconds. */
-    getValidToken(): Promise<string>;
+    /**
+     * 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.
+     */
+    getValidToken(opts?: {
+        silent?: boolean;
+    }): Promise<string>;
     /** Convenience for fetch: spread directly into `headers`. */
     getAuthHeader(): Promise<Record<string, string>>;
-    /** Drop the cached token (e.g. on 401 from server). Next call re-logs in. */
+    /**
+     * Drop the cached token (e.g. on 401 from server). The persisted envelope is
+     * kept — the next call re-mints silently — but its stored token copy is
+     * dropped too so a dead JWT can't be re-adopted from the store.
+     */
     clear(): void;
     /**
-     * Revoke the current session JWT on lit-ops-server (`POST /api/auth/logout`).
-     * Clears the local cache regardless of server response so the client stops
-     * presenting the token.
+     * Drop the session AND the persisted re-mint envelope (wallet disconnect /
+     * explicit sign-out paths — anything that must remove the 24h credential
+     * from storage).
+     */
+    clearPersisted(): Promise<void>;
+    /**
+     * Revoke the current session JWT on lit-ops-server (`POST /api/auth/logout`)
+     * — which also tombstones the envelope's re-mint window server-side — and
+     * remove the persisted credential locally. Clears the local cache regardless
+     * of server response so the client stops presenting the token.
      */
     logout(): Promise<void>;
+    /**
+     * 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.
+     */
+    private tryResolveSilently;
     private getOrRefresh;
+    private login;
+    /**
+     * Load the persisted session for the current signer, validating that it
+     * belongs to this address/chain/endpoint and that the envelope is still
+     * inside the re-auth window (with a safety margin). Invalid or expired
+     * entries are evicted.
+     */
+    private loadPersisted;
+    /** Best-effort save of the envelope + live JWT for silent recovery. */
+    private persist;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.301",
+  "version": "0.0.304",
   "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.313",
-    "@gvnrdao/dh-lit-ops": "^0.0.303",
+    "@gvnrdao/dh-lit-actions": "^0.0.314",
+    "@gvnrdao/dh-lit-ops": "^0.0.304",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",