@gvnrdao/dh-sdk 0.0.293 → 0.0.294

package/dist/modules/bitcoin/bitcoin-operations.module.d.ts

@@ -185,19 +185,11 @@ export declare class BitcoinOperations {
     /**
      * Get balance cache statistics
      */
-    getBalanceCacheStats(): {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    } | null;
+    getBalanceCacheStats(): import("../cache/cache-manager.module").CacheStats | null;
     /**
      * Get address cache statistics
      */
-    getAddressCacheStats(): {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    } | null;
+    getAddressCacheStats(): import("../cache/cache-manager.module").CacheStats | null;
     /**
      * Get current network configuration
      */

package/dist/modules/cache/cache-manager.module.d.ts

@@ -1,74 +1,236 @@
 /**
- * Cache Manager Module
+ * Generic Cache Manager Module
  *
- * Provides a simple cache factory for SDK modules.
- * Each cache is an independent LRU cache with TTL support.
+ * Provides a type-safe, generic LRU cache with TTL support.
+ * Can be used for any data type (Bitcoin balances, addresses, query results, etc.)
+ *
+ * Features:
+ * - Generic type support
+ * - TTL-based expiration
+ * - LRU eviction policy
+ * - Hit/miss statistics
+ * - Memory-efficient
+ * - Thread-safe operations
  */
-export interface CacheConfig {
-    maxSize: number;
-    ttlMs: number;
+import { Result } from '../../types/result';
+import { SDKError } from '../../utils/error-handler';
+/**
+ * Cache entry with metadata
+ */
+interface CacheEntry<T> {
+    /** Cached value */
+    value: T;
+    /** Unix timestamp when entry was created (ms) */
+    timestamp: number;
+    /** Number of times this entry was accessed */
+    hits: number;
+    /** Unix timestamp of last access (ms) */
+    lastAccessed: number;
 }
+/**
+ * Cache statistics
+ */
 export interface CacheStats {
+    /** Current number of entries in cache */
     size: number;
-    maxSize: number;
-    ttlMs: number;
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Total evictions performed */
+    evictions: number;
+    /** Timestamp of oldest entry (ms) */
+    oldestEntry: number;
+    /** Timestamp of newest entry (ms) */
+    newestEntry: number;
+    /** Hit rate as percentage (0-100) */
+    hitRate: number;
 }
 /**
- * Simple LRU Cache with TTL support
+ * Cache configuration
+ */
+export interface CacheConfig {
+    /** Maximum number of entries (default: 1000) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (default: 60000 = 1 minute) */
+    ttlMs?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Cache name for logging (default: 'Cache') */
+    name?: string;
+}
+/**
+ * Generic LRU Cache with TTL support
+ *
+ * @template K - Key type (usually string)
+ * @template V - Value type
+ *
+ * @example
+ * ```typescript
+ * // Create a cache for Bitcoin balances
+ * const balanceCache = new LRUCache<string, BitcoinBalance>({
+ *   maxSize: 500,
+ *   ttlMs: 60000,
+ *   name: 'BitcoinBalance'
+ * });
+ *
+ * // Set value
+ * balanceCache.set('bc1q...', { balance: Satoshis(50000000n) });
+ *
+ * // Get value
+ * const balance = balanceCache.get('bc1q...');
+ * if (balance) {
+ *   console.log('Cached balance:', balance.balance);
+ * }
+ * ```
  */
-export declare class Cache<T = any> {
+export declare class LRUCache<K, V> {
     private cache;
+    /**
+     * Audit M-J: singleflight registry for `getOrCompute` / `getOrComputeResult`.
+     * Concurrent cache-miss callers for the same key share one inflight promise
+     * instead of each running `compute()` independently — important when the
+     * compute spends a paid LIT capacity credit or hits a rate-limited upstream.
+     */
+    private inflight;
+    private inflightResult;
     private readonly maxSize;
     private readonly ttlMs;
-    constructor(config: CacheConfig);
+    private readonly debug;
+    private readonly name;
+    private stats;
+    constructor(config?: CacheConfig);
     /**
      * Get value from cache
+     *
+     * Returns null if:
+     * - Key not found
+     * - Entry has expired
+     *
+     * @param key - Cache key
+     * @returns Cached value or null
      */
-    get(key: string): T | undefined;
+    get(key: K): V | null;
+    /**
+     * Get value from cache with Result wrapper
+     *
+     * Useful when you want to distinguish between "not found" and "expired"
+     */
+    getResult(key: K): Result<V, SDKError>;
     /**
      * Set value in cache
+     *
+     * If cache is full, evicts the least recently used entry
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Optional custom TTL for this entry (ms)
      */
-    set(key: string, value: T, ttl?: number): void;
+    set(key: K, value: V, ttl?: number): void;
     /**
-     * Check if key exists in cache
+     * Set value in cache with Result wrapper
      */
-    has(key: string): boolean;
+    setResult(key: K, value: V, ttl?: number): Result<void, SDKError>;
     /**
-     * Delete key from cache
+     * Check if key exists in cache (without affecting stats)
      */
-    delete(key: string): boolean;
+    has(key: K): boolean;
     /**
-     * Clear all cache entries
+     * Delete specific key from cache
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear entire cache
      */
     clear(): void;
     /**
-     * Clean expired entries
+     * Get current cache size
      */
-    cleanExpired(): number;
+    size(): number;
     /**
      * Get cache statistics
      */
-    getStats(): {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    };
+    getStats(): CacheStats;
+    /**
+     * Get hit rate percentage
+     */
+    getHitRate(): number;
+    /**
+     * Get all cached keys (for debugging)
+     */
+    getKeys(): K[];
+    /**
+     * Get all cached values (for debugging)
+     */
+    getValues(): V[];
+    /**
+     * Get all cache entries with metadata (for debugging)
+     */
+    getEntries(): Array<{
+        key: K;
+        value: V;
+        metadata: Omit<CacheEntry<V>, 'value'>;
+    }>;
+    /**
+     * Clean up expired entries
+     *
+     * Useful for periodic maintenance
+     *
+     * @returns Number of entries cleaned
+     */
+    cleanExpired(): number;
+    /**
+     * Check if cache entry is expired
+     */
+    private isExpired;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Get or compute value
+     *
+     * If key exists in cache, returns cached value.
+     * Otherwise, computes value using provided function and caches it.
+     *
+     * @param key - Cache key
+     * @param compute - Function to compute value if not in cache
+     * @param ttl - Optional custom TTL for this entry
+     * @returns Cached or computed value
+     */
+    getOrCompute(key: K, compute: () => Promise<V>, ttl?: number): Promise<V>;
+    /**
+     * Get or compute value with Result wrapper
+     */
+    getOrComputeResult(key: K, compute: () => Promise<Result<V, SDKError>>, ttl?: number): Promise<Result<V, SDKError>>;
 }
 /**
- * Cache Manager
- *
- * Factory for creating named caches with specific configurations
+ * Generic cache interface for type safety
+ */
+export interface Cache<T> {
+    get(key: string): T | null | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): boolean;
+    clear(): void;
+    has(key: string): boolean;
+    size(): number;
+    getStats(): CacheStats;
+}
+/**
+ * Cache Manager - Factory for creating specialized caches
  */
 export declare class CacheManager {
     private caches;
-    private readonly debug;
-    constructor(config?: {
-        debug?: boolean;
-    });
+    private readonly globalConfig;
+    constructor(globalConfig?: CacheConfig);
     /**
-     * Get or create a cache instance
+     * Create or get a named cache
+     *
+     * @param name - Unique cache name
+     * @param config - Optional cache-specific configuration
+     * @returns LRU cache instance
      */
-    getCache<K extends string = string, V = any>(name: K, config: CacheConfig): Cache<V>;
+    getCache<K, V>(name: string, config?: CacheConfig): LRUCache<K, V>;
     /**
      * Clear all caches
      */
@@ -80,13 +242,18 @@ export declare class CacheManager {
     /**
      * Get statistics for all caches
      */
-    getAllStats(): Record<string, ReturnType<Cache["getStats"]>>;
+    getAllStats(): Record<string, CacheStats>;
+    /**
+     * Get list of all cache names
+     */
+    getCacheNames(): string[];
     /**
-     * Destroy cache manager
+     * Delete a named cache
      */
-    destroy(): void;
+    deleteCache(name: string): boolean;
 }
-export { Cache as LRUCache };
-export declare function createCacheManager(config?: {
-    debug?: boolean;
-}): CacheManager;
+/**
+ * Factory function to create a CacheManager instance
+ */
+export declare function createCacheManager(config?: CacheConfig): CacheManager;
+export {};

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

@@ -373,6 +373,25 @@ export declare class DiamondHandsSDK {
      * @returns Payment result with transaction details
      */
     makePayment(request: PartialPaymentRequest): Promise<PartialPaymentResult>;
+    /**
+     * Whether a failed payment attempt is a quantum-timing failure that a fresh
+     * re-sign can fix (safe to retry), versus a terminal failure.
+     *
+     * Retryable: pre-send simulation quantum errors, or an atomic mined revert
+     * (status 0) — no funds moved and the quantum was not recorded on-chain, so a
+     * fresh signature + resubmit is safe.
+     *
+     * NOT retryable: a confirmation timeout — the original tx may still be pending, so
+     * a resubmit could double-pay. It is surfaced (with its tx hash) instead.
+     */
+    private isRetryablePaymentQuantumFailure;
+    /**
+     * One payment attempt: user auth → Lit Action authorization → dead-zone gate →
+     * pre-send simulation → broadcast → confirmation. Always resolves to a
+     * PartialPaymentResult (never throws to the caller); the makePayment wrapper owns
+     * the write lock, the pause pre-check, and the bounded re-sign retry loop.
+     */
+    private _makePaymentAttempt;
     /**
      * Access the approved-withdrawal-address allowlist module (self-service
      * add/remove + reads). The connected wallet manages its OWN addresses; a
@@ -847,11 +866,7 @@ export declare class DiamondHandsSDK {
     /**
      * Get cache statistics
      */
-    getCacheStats(): Record<string, {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    }>;
+    getCacheStats(): Record<string, import("./cache/cache-manager.module").CacheStats>;
     /**
      * Get contract manager (for advanced usage)
      */

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

@@ -196,11 +196,7 @@ export declare class LoanQuery {
     /**
      * Get cache statistics
      */
-    getCacheStats(): {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    } | null;
+    getCacheStats(): import("../cache/cache-manager.module").CacheStats | null;
 }
 /**
  * Factory function to create a LoanQuery instance

package/dist/modules/pkp/pkp-manager.module.d.ts

@@ -128,11 +128,7 @@ export declare class PKPManager {
     /**
      * Get cache statistics
      */
-    getCacheStats(): {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    } | null;
+    getCacheStats(): import("../cache/cache-manager.module").CacheStats | null;
 }
 /**
  * Factory function to create a PKPManager instance

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

@@ -7,14 +7,40 @@
  * - SDK signs for NEXT quantum immediately (no waiting)
  * - 60-second quantum windows
  * - 3-quantum validation (past, current, next) = 180s total validity
- * - Dead zones: first 8s and last 8s of each quantum
  * - Users can operate once per 60 seconds per position
  *
+ * DEAD ZONE — the subtle part (see OperationAuthorizationRegistry._validateQuantum):
+ * The 3-quantum window widens *acceptance*, but it does NOT make dead zones
+ * irrelevant. A signature whose quantum is NOT the on-chain CURRENT quantum
+ * (i.e. a NEXT or PAST signature) is REJECTED with `DeadZoneViolation()` when the
+ * transaction is mined in the last DEAD_ZONE_SECONDS of the current quantum
+ * (`block.timestamp >= currentQuantum + 60 - 8`). A CURRENT-quantum signature is
+ * never dead-zoned. Because the SDK signs NEXT and submits immediately, a send that
+ * lands in that trailing window reverts — so the submission path MUST gate on it via
+ * `awaitSafeSubmissionWindow` (defer across the boundary, at which point the signed
+ * NEXT quantum becomes CURRENT and can never be dead-zoned).
+ *
  * Architecture:
  * - SDK uses this to calculate NEXT quantum immediately
+ * - SDK gates every on-chain submission through `awaitSafeSubmissionWindow`
  * - Tests use this to generate valid timestamps
  * - LIT Actions validate 3-quantum window with dead zone protection
  */
+export declare const QUANTUM_WINDOW_SECONDS = 60;
+export declare const DEAD_ZONE_SECONDS = 8;
+/**
+ * Seconds of mainnet inclusion latency we insure against BEFORE the quantum
+ * boundary. ~1.3 of Ethereum's 12s slots. A NEXT/PAST-quantum send within
+ * `DEAD_ZONE_SECONDS + INCLUSION_LATENCY_BUDGET` of the boundary is deferred so it
+ * cannot be mined in the trailing dead zone `[boundary - 8, boundary)`.
+ */
+export declare const INCLUSION_LATENCY_BUDGET = 16;
+/**
+ * Seconds of client-clock-vs-chain skew guard we add AFTER the boundary when
+ * deferring. A CURRENT-quantum signature is never dead-zoned, so this only needs to
+ * cover modest clock skew — small on top of the boundary crossing.
+ */
+export declare const POST_BOUNDARY_SKEW_MARGIN = 3;
 /**
  * Calculate a valid quantum timestamp for NEXT quantum (NO WAITING)
  *
@@ -73,3 +99,44 @@ export declare function waitUntilTimestamp(targetTimestamp: number): Promise<voi
  * @throws Error if timestamp is invalid
  */
 export declare function validateQuantumTiming(signedTimestamp: number, _bufferSeconds?: number): void;
+/**
+ * Injectable clock/sleep seam for `awaitSafeSubmissionWindow` so unit tests can
+ * drive the decision deterministically. Defaults use the real clock and timer.
+ */
+export interface SafeSubmissionOptions {
+    /** Returns the current time in whole seconds. Defaults to `Date.now()/1000`. */
+    now?: () => number;
+    /** Sleeps for `ms` milliseconds. Defaults to `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface SafeSubmissionResult {
+    /** Whether the send was deferred across the quantum boundary. */
+    waited: boolean;
+    /** Seconds slept (0 when not deferred). */
+    waitedSeconds: number;
+}
+/**
+ * Submission-time dead-zone gate.
+ *
+ * Call this IMMEDIATELY before broadcasting any on-chain operation that carries a
+ * quantum-signed authorization (makePayment / mintUCD / withdrawBTC / extendPosition).
+ *
+ * Mirrors the on-chain `_validateQuantum` predicate exactly (do NOT substitute
+ * `isInSafeWorkZone`/`isInDeadZone`, which disagree with enforcement at second 52):
+ * the contract reverts `DeadZoneViolation()` iff the signature's quantum is not the
+ * CURRENT quantum AND `block.timestamp >= currentQuantum + 60 - DEAD_ZONE_SECONDS`.
+ *
+ * Strategy: the SDK signs the NEXT quantum. If we are close enough to the trailing
+ * boundary that realistic inclusion latency could land the mine in
+ * `[boundary - 8, boundary)`, wait until just past the boundary. After the boundary
+ * the signed NEXT quantum IS the new CURRENT quantum, so the dead-zone branch can
+ * never be entered — regardless of inclusion latency.
+ *
+ * PAST-quantum signatures are NOT deferred: waiting forward would age them out of the
+ * acceptance window (`QuantumOutsideWindow`). They must be handled by re-signing
+ * upstream. In practice the SDK only ever signs CURRENT/NEXT.
+ *
+ * @param quantumTimestamp The quantum timestamp embedded in the LIT-signed payload.
+ * @returns whether it waited, and for how long.
+ */
+export declare function awaitSafeSubmissionWindow(quantumTimestamp: number, opts?: SafeSubmissionOptions): Promise<SafeSubmissionResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.293",
+  "version": "0.0.294",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -82,7 +82,7 @@
   "sideEffects": false,
   "dependencies": {
     "@gvnrdao/dh-lit-actions": "^0.0.311",
-    "@gvnrdao/dh-lit-ops": "^0.0.299",
+    "@gvnrdao/dh-lit-ops": "^0.0.301",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",