@gvnrdao/dh-sdk 0.0.172 → 0.0.206

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

@@ -0,0 +1,64 @@
+/**
+ * Utility Type Interfaces
+ */
+/**
+ * Generic Result Interface
+ */
+export interface Result<T = any> {
+    success: boolean;
+    error?: string;
+    data?: T;
+}
+/**
+ * Pagination Interface
+ */
+export interface Pagination {
+    page: number;
+    limit: number;
+    total?: number;
+    hasNext?: boolean;
+    hasPrev?: boolean;
+}
+/**
+ * Paginated Result Interface
+ */
+export interface PaginatedResult<T = any> extends Result<T[]> {
+    pagination?: Pagination;
+}
+/**
+ * Audit Trail Interface
+ */
+export interface AuditTrail {
+    operation: string;
+    timestamp: number;
+    duration?: number;
+    success: boolean;
+    error?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Debug Information Interface
+ */
+export interface DebugInfo {
+    logs: string[];
+    metrics?: {
+        startTime: number;
+        endTime: number;
+        duration: number;
+    };
+    networkCalls?: {
+        url: string;
+        method: string;
+        duration: number;
+        success: boolean;
+    }[];
+}
+/**
+ * Retry Configuration Interface
+ */
+export interface RetryConfig {
+    maxAttempts: number;
+    delay: number;
+    backoffMultiplier?: number;
+    maxDelay?: number;
+}

package/dist/interfaces/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Diamond Hands SDK Interfaces
+ * All TypeScript interfaces and types used in the SDK package
+ *
+ * Following the golden source pattern with organized chunks
+ */
+export * from "./chunks/config.i";
+export * from "./chunks/contract-types.i";
+export * from "./chunks/loan-operations.i";
+export * from "./chunks/pkp-integration.i";
+export * from "./chunks/contract-interactions.i";
+export * from "./chunks/utility.i";
+export * from "./chunks/btc.i";
+export * from "./chunks/lit-actions.i";
+export * from "./chunks/ucd-minting.i";
+export * from "./chunks/requests.i";
+export * from "./chunks/position-query.i";

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

@@ -0,0 +1,215 @@
+/**
+ * Bitcoin Operations Module
+ *
+ * Responsible for:
+ * - Deriving Bitcoin addresses from PKP public keys
+ * - Querying Bitcoin balances (with multi-provider consensus)
+ * - Validating Bitcoin transactions
+ * - Caching Bitcoin data for performance
+ *
+ * Uses branded types (Satoshis) for type-safe Bitcoin amounts
+ */
+import { Result } from "../../types/result";
+import { Satoshis } from "../../types/branded/domain-values";
+import { SDKError } from "../../utils/error-handler";
+import type { Cache } from "../cache/cache-manager.module";
+import type { BitcoinAddresses } from "../../interfaces/chunks/loan-operations.i";
+import type { BitcoinBalanceResult, BitcoinUTXO } from "../../interfaces/chunks/position-query.i";
+import type { BitcoinProviderConfig, PriceProviderConfig } from "../../interfaces/chunks/config.i";
+/**
+ * Bitcoin network type
+ */
+export type BitcoinNetwork = "mainnet" | "testnet" | "regtest";
+/**
+ * Bitcoin Operations configuration
+ */
+export interface BitcoinOperationsConfig {
+    /** Bitcoin network to use */
+    network: BitcoinNetwork;
+    /** Bitcoin provider configurations (supports 1-3 for consensus) */
+    providers: BitcoinProviderConfig[];
+    /** Consensus mode: single or majority */
+    consensusMode?: "single" | "majority";
+    /** Cache for balance results (keyed by address) */
+    balanceCache?: Cache<BitcoinBalanceResult>;
+    /** Cache for address derivations (keyed by PKP public key) */
+    addressCache?: Cache<BitcoinAddresses>;
+    /** LitOps instance for price oracle queries (optional) */
+    litOps?: any;
+    /** Signer for LIT Protocol operations (required for getBTCPrice) */
+    signer?: any;
+    /** Optional PKP Ethereum address for signed price oracle (Lit jsParams pkpId) */
+    priceOraclePkpId?: string;
+    /** Price feed API credentials passed to the price-oracle Lit Action (needs 3 sources for getBTCPrice) */
+    priceProviders?: PriceProviderConfig[];
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Bitcoin balance with enhanced metadata
+ */
+export interface EnrichedBitcoinBalance {
+    /** Bitcoin address */
+    address: string;
+    /** Balance in satoshis (branded type) */
+    balance: Satoshis;
+    /** UTXOs for this address */
+    utxos: BitcoinUTXO[];
+    /** Minimum confirmations across UTXOs */
+    confirmations: number;
+    /** Provider name that returned this data */
+    provider: string;
+    /** Timestamp when fetched */
+    timestamp: number;
+    /** Whether this data came from cache */
+    cached: boolean;
+}
+/**
+ * Bitcoin price result from LIT Protocol price oracle
+ */
+export interface BTCPriceResult {
+    /** Price with 8 decimals (e.g., "10679200000000" for $106,792) */
+    priceE8: string;
+    /** Price in USD as a number */
+    price: number;
+    /** Unix timestamp when price was fetched */
+    timestamp: number;
+    /** Source: "fast" (single source), "consensus" (multiple sources), or "fast-fallback" */
+    source: string;
+    /** Optional PKP signature on the price data */
+    signature?: string;
+    /** Optional signer address */
+    signer?: string;
+}
+/**
+ * Bitcoin Operations Module
+ *
+ * Handles all Bitcoin-related operations with type safety and caching
+ */
+export declare class BitcoinOperations {
+    private readonly config;
+    private readonly provider;
+    private readonly litOps?;
+    constructor(config: BitcoinOperationsConfig);
+    /**
+     * Derive Bitcoin addresses from PKP public key
+     *
+     * Generates addresses for all networks (mainnet, testnet, regtest)
+     * and caches the result.
+     *
+     * @param publicKey - PKP public key (hex string)
+     * @returns Bitcoin addresses for all networks
+     */
+    deriveAddresses(publicKey: string): Promise<Result<BitcoinAddresses, SDKError>>;
+    /**
+     * Get Bitcoin address for current network
+     *
+     * Convenience method that returns only the address for the configured network.
+     *
+     * @param publicKey - PKP public key
+     * @returns Bitcoin address for current network
+     */
+    getAddressForNetwork(publicKey: string): Promise<Result<string, SDKError>>;
+    /**
+     * Get Bitcoin balance for an address
+     *
+     * Queries balance using configured providers with consensus if enabled.
+     * Results are cached for performance.
+     *
+     * @param address - Bitcoin address
+     * @param skipCache - Skip cache and force fresh query
+     * @returns Enriched balance information
+     */
+    getBalance(address: string, skipCache?: boolean): Promise<Result<EnrichedBitcoinBalance, SDKError>>;
+    /**
+     * Get balance with consensus across multiple providers
+     *
+     * Only available if multiple providers are configured.
+     *
+     * @param address - Bitcoin address
+     * @returns Consensus balance result
+     */
+    getBalanceWithConsensus(address: string): Promise<Result<EnrichedBitcoinBalance, SDKError>>;
+    /**
+     * Get balances for multiple addresses
+     *
+     * Efficiently queries balances for multiple addresses in parallel.
+     *
+     * @param addresses - Array of Bitcoin addresses
+     * @returns Array of balance results
+     */
+    getBalances(addresses: string[]): Promise<Result<EnrichedBitcoinBalance[], SDKError>>;
+    /**
+     * Get balance for a PKP public key
+     *
+     * Convenience method that derives address and queries balance.
+     *
+     * @param publicKey - PKP public key
+     * @returns Balance for the PKP's Bitcoin address
+     */
+    getBalanceForPKP(publicKey: string): Promise<Result<EnrichedBitcoinBalance, SDKError>>;
+    /**
+     * Validate a Bitcoin address
+     *
+     * Checks if an address has a valid format.
+     *
+     * @param address - Bitcoin address
+     * @returns Whether address is valid
+     */
+    validateAddress(address: string): boolean;
+    /**
+     * Clear balance cache for an address
+     *
+     * Forces next balance query to fetch fresh data.
+     *
+     * @param address - Bitcoin address
+     */
+    clearBalanceCache(address: string): void;
+    /**
+     * Clear all balance cache
+     */
+    clearAllBalanceCache(): void;
+    /**
+     * Clear address cache for a public key
+     *
+     * Forces next address derivation to compute fresh.
+     *
+     * @param publicKey - PKP public key
+     */
+    clearAddressCache(publicKey: string): void;
+    /**
+     * Clear all address cache
+     */
+    clearAllAddressCache(): void;
+    /**
+     * Get balance cache statistics
+     */
+    getBalanceCacheStats(): import("../..").CacheStats | null;
+    /**
+     * Get address cache statistics
+     */
+    getAddressCacheStats(): import("../..").CacheStats | null;
+    /**
+     * Get current network configuration
+     */
+    getNetwork(): BitcoinNetwork;
+    /**
+     * Check if consensus mode is enabled
+     */
+    isConsensusEnabled(): boolean;
+    /**
+     * Get current BTC price using LIT Protocol price oracle
+     *
+     * Queries the decentralized price oracle via LIT Actions.
+     * Supports fast mode (single source) and full mode (consensus).
+     *
+     * @param mode - Price fetch mode: "fast" (single source) or "full" (consensus)
+     * @param sign - Whether to request PKP signature on the price
+     * @returns BTC price result with timestamp and source
+     */
+    getPrice(mode?: "fast" | "full", sign?: boolean): Promise<Result<BTCPriceResult, SDKError>>;
+}
+/**
+ * Factory function to create a BitcoinOperations instance
+ */
+export declare function createBitcoinOperations(config: BitcoinOperationsConfig): Result<BitcoinOperations, SDKError>;

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

@@ -0,0 +1,251 @@
+/**
+ * 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;
+    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,136 @@
+/**
+ * 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 { ethers as ethers5 } from "ethers";
+import type { ContractAddresses } from "../../interfaces/chunks/config.i";
+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 v5 provider (used throughout SDK)
+ */
+export type Provider = ethers5.providers.Provider;
+/**
+ * Type alias for ethers v5 signer
+ */
+export type Signer = ethers5.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;
+}
+/**
+ * Managed contract instances with proper typing
+ */
+export interface ManagedContracts {
+    positionManager: PositionManager;
+    loanOperationsManager: ILoanOperationsManager;
+    ucdController: IUCDController;
+    priceFeed: IPriceFeedConsumer;
+    termManager: ITermManager;
+    circuitBreaker: CircuitBreakerModule;
+    liquidationManager: ILiquidationManager;
+}
+/**
+ * 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 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 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>;