@gvnrdao/dh-sdk 0.0.288 → 0.0.289

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

@@ -0,0 +1,259 @@
+/**
+ * Generic Cache Manager Module
+ *
+ * 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
+ */
+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;
+    /** 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;
+}
+/**
+ * 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 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;
+    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"
+     */
+    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: K, value: V, ttl?: number): void;
+    /**
+     * Set value in cache with Result wrapper
+     */
+    setResult(key: K, value: V, ttl?: number): Result<void, SDKError>;
+    /**
+     * Check if key exists in cache (without affecting stats)
+     */
+    has(key: K): boolean;
+    /**
+     * Delete specific key from cache
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear entire cache
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     */
+    size(): number;
+    /**
+     * Get cache statistics
+     */
+    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>>;
+}
+/**
+ * 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 globalConfig;
+    constructor(globalConfig?: CacheConfig);
+    /**
+     * Create or get a named cache
+     *
+     * @param name - Unique cache name
+     * @param config - Optional cache-specific configuration
+     * @returns LRU cache instance
+     */
+    getCache<K, V>(name: string, config?: CacheConfig): LRUCache<K, V>;
+    /**
+     * Clear all caches
+     */
+    clearAll(): void;
+    /**
+     * Clean expired entries from all caches
+     */
+    cleanAllExpired(): number;
+    /**
+     * Get statistics for all caches
+     */
+    getAllStats(): Record<string, CacheStats>;
+    /**
+     * Get list of all cache names
+     */
+    getCacheNames(): string[];
+    /**
+     * Delete a named cache
+     */
+    deleteCache(name: string): boolean;
+}
+/**
+ * Factory function to create a CacheManager instance
+ */
+export declare function createCacheManager(config?: CacheConfig): CacheManager;
+export {};

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

@@ -0,0 +1,152 @@
+/**
+ * Contract Manager Module
+ *
+ * Responsible for:
+ * - Managing contract instances and their lifecycle
+ * - Providing typed contract interfaces
+ * - Handling contract address resolution
+ * - Managing provider/signer connections
+ *
+ * This module centralizes all contract interaction setup and provides
+ * a clean interface for other modules to access contracts.
+ */
+import { Contract, type Provider, type Signer } from "ethers";
+import type { ContractAddresses } from "../../interfaces/chunks/config.i";
+import { type DeploymentContracts } from "../../constants/chunks/deployment-addresses";
+import { Result } from "../../types/result";
+import { SDKError } from "../../utils/error-handler";
+import type { PositionManager, ILoanOperationsManager, IUCDController, IPriceFeedConsumer, ITermManager, CircuitBreakerModule, ILiquidationManager } from "../../interfaces/chunks/contract-types.i";
+/**
+ * Type alias for ethers v6 provider (used throughout SDK)
+ */
+export type { Provider };
+/**
+ * Type alias for ethers v6 signer
+ */
+export type { Signer };
+/**
+ * Type alias for contract runner (provider or signer)
+ */
+export type ContractRunner = Provider | Signer;
+/**
+ * Configuration for Contract Manager
+ */
+export interface ContractManagerConfig {
+    /** Ethers v5 provider for reading blockchain data */
+    provider: Provider;
+    /** Ethers v5 signer for writing transactions (optional) */
+    signer?: Signer;
+    /** Contract addresses for the target network */
+    contractAddresses: ContractAddresses;
+    /** SDK mode: 'service' or 'standalone' */
+    mode?: "service" | "standalone";
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Network name (e.g. "sepolia", "localhost") for deployment address lookup */
+    networkName?: string;
+}
+/**
+ * Managed contract instances with proper typing
+ */
+export interface ManagedContracts {
+    positionManager: PositionManager;
+    loanOperationsManager: ILoanOperationsManager;
+    ucdController: IUCDController;
+    priceFeed: IPriceFeedConsumer;
+    termManager: ITermManager;
+    circuitBreaker: CircuitBreakerModule;
+    liquidationManager: ILiquidationManager;
+    /** Per-wallet approved-withdrawal-address allowlist. Untyped ethers Contract — methods accessed via WithdrawalAddressModule. */
+    bitcoinWithdrawalAddressRegistry: Contract;
+}
+/**
+ * Contract Manager Module
+ *
+ * Centralized contract instance management with proper typing
+ */
+export declare class ContractManager {
+    private readonly config;
+    private contracts;
+    constructor(config: ContractManagerConfig);
+    /**
+     * Initialize all contract instances
+     *
+     * This is called lazily on first access to any contract
+     */
+    private initializeContracts;
+    /**
+     * Validate that all required contract addresses are present and valid
+     */
+    private validateContractAddresses;
+    /**
+     * Get all managed contract instances
+     */
+    getContracts(): Result<ManagedContracts, SDKError>;
+    /**
+     * Get Position Manager contract
+     */
+    getPositionManager(): Result<PositionManager, SDKError>;
+    /**
+     * Get Loan Operations Manager contract
+     */
+    getLoanOperationsManager(): Result<ILoanOperationsManager, SDKError>;
+    /**
+     * Get UCD Controller contract
+     */
+    getUCDController(): Result<IUCDController, SDKError>;
+    /**
+     * Get Price Feed contract
+     */
+    getPriceFeed(): Result<IPriceFeedConsumer, SDKError>;
+    /**
+     * Get Term Manager contract
+     */
+    getTermManager(): Result<ITermManager, SDKError>;
+    /**
+     * Get Circuit Breaker contract
+     */
+    getCircuitBreaker(): Result<CircuitBreakerModule, SDKError>;
+    /**
+     * Get Liquidation Manager contract
+     */
+    getLiquidationManager(): Result<ILiquidationManager, SDKError>;
+    /**
+     * Get the BitcoinWithdrawalAddressRegistry contract (per-wallet approved-address allowlist).
+     */
+    getBitcoinWithdrawalAddressRegistry(): Result<Contract, SDKError>;
+    /**
+     * Get the provider instance
+     */
+    getProvider(): Provider;
+    /**
+     * Get the signer instance (if available)
+     */
+    getSigner(): Result<Signer, SDKError>;
+    /**
+     * Check if a signer is available for write operations
+     */
+    hasSigner(): boolean;
+    /**
+     * Get contract addresses
+     */
+    getContractAddresses(): ContractAddresses;
+    /**
+     * Get the full deployment map for the configured network.
+     * Returns all deployed contracts (including admin-surface ones not needed at runtime),
+     * keyed by PascalCase contract name matching the deployment JSON.
+     * Returns null if the network name is unknown.
+     */
+    getDeploymentAddresses(): DeploymentContracts | null;
+    /**
+     * Get the network chain ID from the provider
+     */
+    getChainId(): Promise<Result<number, SDKError>>;
+    /**
+     * Verify that the provider is connected and responsive
+     */
+    verifyConnection(): Promise<Result<boolean, SDKError>>;
+}
+/**
+ * Factory function to create a ContractManager instance
+ */
+export declare function createContractManager(config: ContractManagerConfig): Result<ContractManager, SDKError>;