@gvnrdao/dh-sdk 0.0.219 → 0.0.221

package/dist/interfaces/chunks/contract-types.i.d.ts

@@ -12,7 +12,7 @@ import type { BigNumber } from "ethers";
  * Based on contracts/src/interfaces/IPositionManager.sol
  */
 export interface PositionManager extends ethers5.Contract {
-    createPosition(pkpId: string, validatorSignature: string, mainnetVaultAddress: string, regtestVaultAddress: string, selectedTermMonths: number | BigNumber, validatorVersion: number | BigNumber): Promise<ethers5.ContractTransaction>;
+    createPosition(pkpId: string, validatorSignature: string, mainnetVaultAddress: string, regtestVaultAddress: string, selectedTermMonths: number | BigNumber, validatorVersion: number | BigNumber, pkpPublicKey: string): Promise<ethers5.ContractTransaction>;
     mintUCD(positionId: string, mintAmount: BigNumber, mintFee: BigNumber, newDebt: BigNumber, newCollateral: BigNumber, btcPrice: BigNumber, authorizedSpendsHash: string, ucdDebtHash: string, contractHash: string, quantumTimestamp: BigNumber, mintValidatorSignature: string): Promise<ethers5.ContractTransaction>;
     liquidatePosition(positionId: string, btcPrice: BigNumber, quantumTimestamp: BigNumber, liquidationValidatorSignature: string): Promise<ethers5.ContractTransaction>;
     getPosition(positionId: string): Promise<{

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

@@ -184,19 +184,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,228 @@
 /**
- * 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;
+}
+/**
+ * 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;
 }
 /**
- * Simple LRU Cache with TTL support
+ * 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;
     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: K): V | null;
+    /**
+     * Get value from cache with Result wrapper
+     *
+     * Useful when you want to distinguish between "not found" and "expired"
      */
-    get(key: string): T | undefined;
+    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;
+    /**
+     * Delete specific key from cache
+     */
+    delete(key: K): boolean;
     /**
-     * Clear all cache entries
+     * 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<T = any>(name: string, config: CacheConfig): Cache<T>;
+    getCache<K, V>(name: string, config?: CacheConfig): LRUCache<K, V>;
     /**
      * Clear all caches
      */
@@ -80,13 +234,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

@@ -563,11 +563,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)
      */
@@ -593,6 +589,11 @@ export declare class DiamondHandsSDK {
      *          Will be integrated into core methods in Round 2
      */
     private extractLitActionError;
+    /**
+     * Build the Chipotle service-mode fallback config for getPKPPublicKeyFromTokenId.
+     * Returns undefined in standalone mode so the helper falls back to throwing.
+     */
+    private getChipotlePublicKeyFallback;
     /**
      * Get provider or throw error
      */

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

@@ -124,11 +124,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/mint-authorization.utils.d.ts

@@ -132,24 +132,40 @@ export declare function generatePaymentAuthorization(positionId: string, amount:
  * - LIT Action validates recovered address === position owner
  */
 export declare function generateExtendAuthorization(positionId: string, selectedTerm: number, chainId: number, signer: ethers5.Signer): Promise<ExtendOwnerAuthorization>;
+/**
+ * Optional Chipotle service fallback for `getPKPPublicKeyFromTokenId`.
+ *
+ * Chipotle PKPs have no on-chain `getPubkey(tokenId)` lookup, so when the
+ * SDK's in-memory `pkp-data` cache is empty (page reload, new device, cleared
+ * browser data) we recover the public key by re-running pkp-validator via the
+ * lit-ops-server `/api/lit/pkp/derive-public-key` endpoint. Chipotle key
+ * derivation is deterministic from `pkpId`, so this returns the same key.
+ */
+export interface ChipotleServiceFallback {
+    serviceEndpoint: string;
+    serviceAuthToken?: string;
+    borrowerAddress?: string;
+    timeoutMs?: number;
+    debug?: boolean;
+}
 /**
  * Get PKP public key from PKP token ID.
  *
- * Only valid for datil/naga-era PKPs minted as NFTs on Chronicle Yellowstone.
- * The caller must supply both the provider (connected to the PKP NFT's chain)
- * and the PKP NFT contract address for that chain.
+ * For datil/naga-era PKPs minted as NFTs on Chronicle Yellowstone: looks up
+ * via `getPubkey(tokenId)` on the supplied PKP NFT contract.
  *
- * Chipotle PKPs are wallet addresses returned by the Chipotle REST API — they
- * are not NFTs and cannot be looked up via this function. Passing a Chipotle
- * pkpId (ABI-encoded ETH address, e.g. 0x000...00<20-byte-addr>) throws an
- * explicit error so callers surface a clear diagnostic.
+ * For Chipotle PKPs (ABI-encoded ETH address): there is no on-chain lookup, so
+ * if `chipotleFallback.serviceEndpoint` is configured, the public key is
+ * derived by calling lit-ops-server. If the fallback is not configured, this
+ * throws with a clear diagnostic.
  *
  * @param pkpTokenId - PKP token ID (bytes32 hex string)
- * @param provider - Ethereum provider connected to the PKP NFT chain
- * @param pkpNftContractAddress - PKP NFT contract address on that chain (required)
+ * @param provider - Ethereum provider connected to the PKP NFT chain (datil/naga only)
+ * @param pkpNftContractAddress - PKP NFT contract address on that chain (datil/naga only)
+ * @param chipotleFallback - Service-mode fallback used when pkpTokenId is a Chipotle id
  * @returns PKP public key as hex string with '0x' prefix
  */
-export declare function getPKPPublicKeyFromTokenId(pkpTokenId: string, provider?: ethers5.providers.Provider, pkpNftContractAddress?: string): Promise<string>;
+export declare function getPKPPublicKeyFromTokenId(pkpTokenId: string, provider?: ethers5.providers.Provider, pkpNftContractAddress?: string, chipotleFallback?: ChipotleServiceFallback): Promise<string>;
 /**
  * Withdraw Owner Authorization Interface (matches lit-actions)
  */

package/dist/utils/telegram-messaging.utils.d.ts

@@ -132,7 +132,7 @@ export declare function formatBalanceConfirmationFailureMessage(loanId: string):
  * @param loanId - Position/loan ID
  * @returns Formatted message string
  */
-export declare function formatBTCWithdrawalSuccessMessage(withdrawalAmount: number | string, btcVault: string, btcDestinationAddress: string, loanId: string): string;
+export declare function formatBTCWithdrawalSuccessMessage(withdrawalAmount: number | string, btcVault: string, btcDestinationAddress: string, loanId: string, btcTxId?: string): string;
 /**
  * Format a liquidation skipped notification message
  *

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.219",
+  "version": "0.0.221",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
-  "types": "dist/sdk/src/index.d.ts",
+  "types": "dist/index.d.ts",
   "module": "dist/index.mjs",
   "exports": {
     ".": {
-      "types": "./dist/sdk/src/index.d.ts",
+      "types": "./dist/index.d.ts",
       "browser": "./dist/index.mjs",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
     },
     "./server": {
-      "types": "./dist/sdk/src/server.d.ts",
+      "types": "./dist/server.d.ts",
       "import": "./dist/server.mjs",
       "require": "./dist/server.js"
     }
@@ -70,8 +70,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@gvnrdao/dh-lit-actions": "^0.0.283",
-    "@gvnrdao/dh-lit-ops": "^0.0.256",
+    "@gvnrdao/dh-lit-actions": "^0.0.285",
+    "@gvnrdao/dh-lit-ops": "^0.0.258",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.15.2",
     "bech32": "^2.0.0",