@gvnrdao/dh-sdk 0.0.205 → 0.0.206

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

@@ -137,11 +137,6 @@ interface BaseSDKConfig {
         extension: number;
     };
     defaultSelectedTermMonths?: number;
-    telegram?: {
-        chatId: string;
-        chatToken: string;
-        threadId?: number;
-    };
     temperSignaturesTest?: boolean;
 }
 /**

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("../..").CacheStats | null;
     /**
      * Get address cache statistics
      */
-    getAddressCacheStats(): {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    } | null;
+    getAddressCacheStats(): import("../..").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

@@ -143,6 +143,7 @@ export declare class DiamondHandsSDK {
     /**
      * Check if SDK is ready for operations
      */
+    private _relayNotification;
     private checkInitialized;
     private toSDKError;
     /**
@@ -427,7 +428,7 @@ export declare class DiamondHandsSDK {
     getLoansByBorrower(borrower: string, pagination?: {
         page: number;
         pageSize: number;
-    }): Promise<Result<import("../interfaces/chunks/loan-operations.i").PaginatedLoansResponse, SDKError>>;
+    }): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
     /**
      * Get all active loans
      *
@@ -437,7 +438,7 @@ export declare class DiamondHandsSDK {
     getActiveLoans(pagination?: {
         page: number;
         pageSize: number;
-    }): Promise<Result<import("../interfaces/chunks/loan-operations.i").PaginatedLoansResponse, SDKError>>;
+    }): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
     /**
      * Get loans by state/status
      *
@@ -448,7 +449,7 @@ export declare class DiamondHandsSDK {
     getLoansByState(state: string, pagination?: {
         page: number;
         pageSize: number;
-    }): Promise<Result<import("../interfaces/chunks/loan-operations.i").PaginatedLoansResponse, SDKError>>;
+    }): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
     /**
      * Get all loans with pagination
      *
@@ -462,11 +463,11 @@ export declare class DiamondHandsSDK {
         maxRows?: number;
         orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt";
         orderDirection?: "asc" | "desc";
-    }, source?: "subgraph" | "contract"): Promise<Result<import("../interfaces/chunks/loan-operations.i").PaginatedLoansResponse, SDKError>>;
+    }, source?: "subgraph" | "contract"): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
     /**
      * 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>>;
+    getLoanEvents(positionId: string, filter?: import("../types/event-types").LoanEventsFilter): Promise<Result<import("..").LoanEvents, SDKError>>;
     /**
      * Wait for the subgraph to index up to (and including) the given block number.
      * Call after on-chain actions (createLoan, mintUCD, etc.) before querying the subgraph.
@@ -481,7 +482,7 @@ export declare class DiamondHandsSDK {
      * @param address - Bitcoin address
      * @returns Balance in satoshis
      */
-    getBitcoinBalance(address: string): Promise<Result<import("./bitcoin/bitcoin-operations.module").EnrichedBitcoinBalance, SDKError>>;
+    getBitcoinBalance(address: string): Promise<Result<import("..").EnrichedBitcoinBalance, SDKError>>;
     /**
      * Get the current Bitcoin price
      *
@@ -501,7 +502,7 @@ export declare class DiamondHandsSDK {
      * @param publicKey - PKP public key
      * @returns Bitcoin addresses for all networks
      */
-    deriveBitcoinAddresses(publicKey: string): Promise<Result<import("../interfaces/chunks/loan-operations.i").BitcoinAddresses, SDKError>>;
+    deriveBitcoinAddresses(publicKey: string): Promise<Result<import("..").BitcoinAddresses, SDKError>>;
     /**
      * Get PKP data by token ID
      *
@@ -542,7 +543,7 @@ export declare class DiamondHandsSDK {
      * @param recipient - Recipient address
      * @returns Transaction result
      */
-    mintMockBTC(amount: Satoshis, recipient: string): Promise<Result<import("./mock/mock-token-manager.module").MockTokenTransactionResult, SDKError>>;
+    mintMockBTC(amount: Satoshis, recipient: string): Promise<Result<import("..").MockTokenTransactionResult, SDKError>>;
     /**
      * Approve mock BTC spending (test networks only)
      *
@@ -550,7 +551,7 @@ export declare class DiamondHandsSDK {
      * @param amount - Amount in satoshis
      * @returns Transaction result
      */
-    approveMockBTC(spender: string, amount: Satoshis): Promise<Result<import("./mock/mock-token-manager.module").MockTokenTransactionResult, SDKError>>;
+    approveMockBTC(spender: string, amount: Satoshis): Promise<Result<import("..").MockTokenTransactionResult, SDKError>>;
     /**
      * Get SDK configuration
      */
@@ -562,11 +563,7 @@ export declare class DiamondHandsSDK {
     /**
      * Get cache statistics
      */
-    getCacheStats(): Record<string, {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    }>;
+    getCacheStats(): Record<string, import("..").CacheStats>;
     /**
      * Get contract manager (for advanced usage)
      */

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

@@ -53,6 +53,8 @@ export interface LoanQueryConfig {
     bitcoinOperations: BitcoinOperations;
     /** Ethereum provider for PKP public key retrieval */
     provider?: providers.Provider;
+    /** PositionManagerCoreModule address — used as fallback vault address source for Chipotle loans */
+    positionManagerCoreAddress?: string;
     /** Cache for loan query results (keyed by PKP ID) */
     cache?: Cache<LoanData>;
     /** Enable debug logging */
@@ -194,11 +196,7 @@ export declare class LoanQuery {
     /**
      * Get cache statistics
      */
-    getCacheStats(): {
-        size: number;
-        maxSize: number;
-        ttlMs: number;
-    } | null;
+    getCacheStats(): import("../..").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("../..").CacheStats | null;
 }
 /**
  * Factory function to create a PKPManager instance

package/dist/utils/mint-authorization.utils.d.ts

@@ -133,13 +133,20 @@ export declare function generatePaymentAuthorization(positionId: string, amount:
  */
 export declare function generateExtendAuthorization(positionId: string, selectedTerm: number, chainId: number, signer: ethers5.Signer): Promise<ExtendOwnerAuthorization>;
 /**
- * Get PKP public key from PKP token ID
+ * Get PKP public key from PKP token ID.
  *
- * Queries the PKP NFT contract on the Chipotle LIT chain (Chronicle Yellowstone, chainId 175188).
+ * 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.
+ *
+ * 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.
  *
  * @param pkpTokenId - PKP token ID (bytes32 hex string)
- * @param provider - Ethereum provider (optional; reused if already on the correct LIT chain)
- * @param pkpNftContractAddress - PKP NFT contract address (required)
+ * @param provider - Ethereum provider connected to the PKP NFT chain
+ * @param pkpNftContractAddress - PKP NFT contract address on that chain (required)
  * @returns PKP public key as hex string with '0x' prefix
  */
 export declare function getPKPPublicKeyFromTokenId(pkpTokenId: string, provider?: ethers5.providers.Provider, pkpNftContractAddress?: string): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.205",
+  "version": "0.0.206",
   "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",
@@ -37,7 +37,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:strict": "tsc --noEmit -p tsconfig.strict.json",
     "test:types": "tsc --noEmit -p tsconfig.types.json",
-    "prepublishOnly": "npm run sync:deployments && npm run validate:contracts && npm run build:node && npm run build:browser",
+    "prepublishOnly": "npm run sync:deployments && npm run validate:contracts && npm run build:node",
     "test": "jest",
     "test:unit": "jest tests/shared/unit",
     "test:integration": "jest tests/shared/integration",