@gvnrdao/dh-sdk 0.0.300 → 0.0.303

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,13 @@ export declare class DiamondHandsSDK {
      * reject the call with 401, which is the correct outcome.
      */
     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.
+     */
+    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
@@ -456,6 +463,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 +676,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 +864,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/chunks/eip1559-broadcast.utils.d.ts

@@ -4,27 +4,24 @@
  */
 import { type Provider, type Signer, type TransactionResponse } from "ethers";
 /**
- * Cap on mintUCD's gasLimit. mintUCD dynamically sizes gasLimit via
- * estimateContractCallGasWithMargin() (real eth_estimateGas + 25% margin) on
- * mainnet, so this value is NOT normally what gets submitted -- it only
- * becomes the literal gasLimit if (a) the estimate comes back anomalously
- * high, or (b) eth_estimateGas itself fails (some RPCs return bare 0x even
- * for valid txs), in which case — after a static call proves the tx valid —
- * this raw value is used as the gasLimit on any chain.
- * Previously 10,000,000 with a comment claiming "mintUCD + LIT validation
- * can exceed 7M gas" -- no evidence of that was found across 16 real mint
- * transactions checked (1 mainnet, 15 recent Sepolia, 2026-07-02): the
- * dynamically-computed gasLimit actually submitted ranged 388,620-886,988.
- * Lowered to 2,000,000 (~2.25x headroom over the highest real value seen)
- * for consistency with MAKE_PAYMENT_GAS_CEILING/EXTEND_POSITION_GAS_CEILING's
- * ~1.5-2x-headroom convention -- a smaller margin than those because this
- * ceiling is a rarely-hit fallback/cap, not the everyday operating value, so
- * a little extra buffer for cold-storage variance is cheap insurance.
+ * Fixed-gas ceiling for mintUCD's broadcast. Since the gold-standard refactor
+ * (2026-07-08) this IS the everyday submitted gasLimit: mintUCD no longer runs
+ * eth_estimateGas (its round-trip latency re-introduced the quantum-boundary
+ * race the submission gate exists to prevent), matching makePayment /
+ * withdrawBTC / extendPosition. Grounded in 16 real mint transactions
+ * (1 mainnet, 15 recent Sepolia, 2026-07-02): the estimate-derived gasLimit
+ * actually submitted ranged 388,620-886,988, and those limits all succeeded —
+ * so 886,988 is a KNOWN-SUFFICIENT limit, not a bare gasUsed figure.
+ * 1,300,000 gives ~1.47x headroom over it, matching MAKE_PAYMENT_GAS_CEILING's
+ * ~1.5x convention. Deliberately NOT higher: wallets (MetaMask) reject a tx
+ * when balance < gasLimit × maxFeePerGas, so an oversized fixed ceiling
+ * (previously 2M as a rarely-hit cap) would block low-ETH users from an
+ * affordable mint.
  */
 export declare const MINT_UCD_GAS_CEILING: bigint;
 /**
- * Fixed-gas ceiling for the withdrawBTC raw-tx fallback (used when estimateGas
- * is unavailable on the RPC). The on-chain flow now spans PositionManager →
+ * Fixed-gas ceiling for withdrawBTC's broadcast (the everyday submitted
+ * gasLimit — no estimateGas runs on this path). The on-chain flow now spans PositionManager →
  * CollateralManager → LoanOperationsManager → BTCSpendAuthorizer plus the audit
  * #3 Chainlink feed-staleness gate and the BitcoinWithdrawalAddressRegistry
  * allowlist STATICCALL; observed end-to-end cost is ~1.0–1.3M gas, so the prior
@@ -89,12 +86,6 @@ export declare const LIQUIDATION_COMMIT_GAS_CEILING: bigint;
  * provisional until re-measured against a real liquidation.
  */
 export declare const LIQUIDATION_REVEAL_GAS_CEILING: bigint;
-/** Headroom on eth_estimateGas (25%). */
-export declare const MINT_UCD_ESTIMATE_MARGIN_BPS = 2500;
-/**
- * Returns gas limit with margin, capped, or null if estimateGas reverts/fails.
- */
-export declare function estimateContractCallGasWithMargin(provider: Provider, from: string, to: string, data: string, marginBps: number, ceiling: bigint): Promise<bigint | null>;
 export declare function resolveEip1559FeeFields(provider: Provider): Promise<{
     maxFeePerGas: bigint;
     maxPriorityFeePerGas: bigint;

package/dist/utils/quantum-revert.utils.d.ts

@@ -10,6 +10,10 @@
  */
 /** `DeadZoneViolation()` selector — the stale-latest-block artifact we tolerate. */
 export declare const DEAD_ZONE_VIOLATION_SELECTOR = "0xbe4b82c1";
+/** Solidity `Error(string)` (require/revert with a message). */
+export declare const ERROR_STRING_SELECTOR = "0x08c379a0";
+/** Solidity `Panic(uint256)` (assert failures, overflow, div-by-zero, …). */
+export declare const PANIC_SELECTOR = "0x4e487b71";
 /**
  * Union of the custom-error selectors the mint/payment/quantum paths decode. Keep in
  * sync with OperationAuthorizationRegistry / PositionManager / LoanOperationsManager.
@@ -26,6 +30,11 @@ export interface DecodedRevert {
 /**
  * Extract the revert data / custom-error selector / known name from an ethers error,
  * probing every provider nesting (JsonRpc, Browser/MetaMask, wrapped `error.error`).
+ *
+ * Besides the custom-error selector map, decodes the two standard Solidity revert
+ * shapes so require-message reverts stay actionable when call sites rely solely on
+ * this decoder: `Error(string)` yields `name = 'Error("<message>")'` and
+ * `Panic(uint256)` yields `name = "Panic(0x<code>)"`.
  */
 export declare function decodeQuantumRevert(e: any): DecodedRevert;
 /** True iff the error decodes to `DeadZoneViolation()` from any provider nesting. */

package/dist/utils/quantum-submission.utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared submission-time safety for quantum-signed broadcasts
+ * (makePayment / mintUCD / withdrawBTC / extendPosition).
+ *
+ * One helper owns the dead-zone gate AND the pre-send simulate/re-simulate loop
+ * that used to exist as three subtly different inline copies in
+ * diamond-hands-sdk.ts. Callers encode calldata, call
+ * `assertSafeQuantumSubmission`, then broadcast ONCE with a fixed gas ceiling
+ * (`sendEip1559Transaction`) — never `estimateGas`, whose latency re-introduces
+ * the boundary race the gate exists to prevent, and never a re-broadcast.
+ *
+ * See docs/sdk-quantum-goldstandard-refactor-plan-2026-07-08.md.
+ */
+/** Default cap on dead-zone-triggered re-simulations (mirrors old makePayment). */
+export declare const MAX_DEADZONE_RESIMULATIONS = 3;
+/**
+ * Thrown when the pre-send simulation proves the transaction would revert.
+ * Carries everything a caller needs to enrich the failure without re-probing
+ * the provider error itself:
+ *
+ * - `errorName`  — decoded name, e.g. `"QuantumExpired()"` or `Error("msg")`
+ *                  (named to avoid shadowing `Error.name`).
+ * - `selector`   — 4-byte selector, e.g. `"0x131d9a21"`.
+ * - `data`       — FULL revert data (mintUCD decodes
+ *                  `DebtUpdateVerificationFailedDetailed` args from it).
+ * - `cause`      — the original provider error (`reason` / `shortMessage`
+ *                  fallbacks, empty-data detection → `diagnoseMintUCD`).
+ *
+ * Only thrown for DECODABLE reverts (revert data present). Transport-level
+ * `eth_call` failures never raise this — see `assertSafeQuantumSubmission`.
+ */
+export declare class QuantumRevertError extends Error {
+    readonly errorName: string | null;
+    readonly selector: string | null;
+    readonly data: string | null;
+    readonly cause: unknown;
+    constructor(errorName: string | null, selector: string | null, data: string | null, cause: unknown);
+}
+export interface SafeQuantumSubmissionOpts {
+    /** Provider used for the `eth_call` simulation (only `.call` is needed). */
+    provider: {
+        call(tx: {
+            to: string;
+            from: string;
+            data: string;
+        }): Promise<string>;
+    };
+    /** Target contract address. */
+    to: string;
+    /** Sender address — `eth_call` must run as the real sender (auth checks). */
+    from: string;
+    /** Encoded calldata; broadcast MUST send these exact bytes. */
+    data: string;
+    /** The quantum timestamp embedded in the LIT-signed payload. */
+    quantumTimestamp: number;
+    /** Cap on dead-zone re-simulations (default {@link MAX_DEADZONE_RESIMULATIONS}). */
+    maxResimulations?: number;
+    /** Clock seam (whole seconds). Drives BOTH the gate and the artifact test. */
+    now?: () => number;
+    /** Sleep seam, forwarded to the gate. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Debug sink; called with human-readable progress lines. */
+    onDebug?: (msg: string) => void;
+}
+/**
+ * Gate + pre-send simulation loop. Resolves when it is safe to broadcast;
+ * throws {@link QuantumRevertError} on a real (non-artifact) decodable revert.
+ * Never broadcasts anything itself.
+ *
+ * Sequence:
+ * 1. **Gate** (`awaitSafeSubmissionWindow`): a NEXT-quantum signature mined in
+ *    the last DEAD_ZONE_SECONDS of the current quantum reverts
+ *    `DeadZoneViolation()` on-chain, so defer the send across the boundary
+ *    when inclusion could land there.
+ * 2. **Simulate** (`eth_call`) and route the outcome:
+ *    - success → safe to broadcast.
+ *    - `DeadZoneViolation()` → `eth_call` runs against the LATEST block's
+ *      (slightly stale) timestamp while the on-chain rule uses MINE time. If
+ *      the signature is already the CURRENT quantum in real time it can never
+ *      be dead-zoned on-chain — stale-block artifact, proceed. Otherwise the
+ *      signature is still NEXT near the boundary: re-gate across it and
+ *      re-simulate (bounded by `maxResimulations`).
+ *    - any other DECODABLE revert → throw `QuantumRevertError` (fail fast: no
+ *      broadcast, no gas burned on a doomed tx).
+ *    - UNDECODABLE failure (no revert data: RPC timeout, rate limit, provider
+ *      quirk) → log and proceed. The fixed-ceiling broadcast degrades to the
+ *      pre-refactor blind-broadcast behavior instead of letting a flaky RPC
+ *      block a valid money-path operation.
+ * 3. **Final re-gate**: the sim loop adds RPC round-trips after step 1; this
+ *    closes the drift with pure clock math (no RPC). If it waits, the
+ *    signature is CURRENT afterward and needs no further simulation.
+ */
+export declare function assertSafeQuantumSubmission(opts: SafeQuantumSubmissionOpts): Promise<void>;

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,103 @@
 /**
- * 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;
+    /**
+     * 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>;
     /** 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>;
     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.300",
+  "version": "0.0.303",
   "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.312",
-    "@gvnrdao/dh-lit-ops": "^0.0.302",
+    "@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",