@gvnrdao/dh-sdk 0.0.166 → 0.0.205

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,223 @@
+/**
+ * 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(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | null;
+    /**
+     * Get address cache statistics
+     */
+    getAddressCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | 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,92 @@
+/**
+ * Cache Manager Module
+ *
+ * Provides a simple cache factory for SDK modules.
+ * Each cache is an independent LRU cache with TTL support.
+ */
+export interface CacheConfig {
+    maxSize: number;
+    ttlMs: number;
+}
+export interface CacheStats {
+    size: number;
+    maxSize: number;
+    ttlMs: number;
+}
+/**
+ * Simple LRU Cache with TTL support
+ */
+export declare class Cache<T = any> {
+    private cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(config: CacheConfig);
+    /**
+     * Get value from cache
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set value in cache
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Check if key exists in cache
+     */
+    has(key: string): boolean;
+    /**
+     * Delete key from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Clean expired entries
+     */
+    cleanExpired(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    };
+}
+/**
+ * Cache Manager
+ *
+ * Factory for creating named caches with specific configurations
+ */
+export declare class CacheManager {
+    private caches;
+    private readonly debug;
+    constructor(config?: {
+        debug?: boolean;
+    });
+    /**
+     * Get or create a cache instance
+     */
+    getCache<T = any>(name: string, config: CacheConfig): Cache<T>;
+    /**
+     * Clear all caches
+     */
+    clearAll(): void;
+    /**
+     * Clean expired entries from all caches
+     */
+    cleanAllExpired(): number;
+    /**
+     * Get statistics for all caches
+     */
+    getAllStats(): Record<string, ReturnType<Cache["getStats"]>>;
+    /**
+     * Destroy cache manager
+     */
+    destroy(): void;
+}
+export { Cache as LRUCache };
+export declare function createCacheManager(config?: {
+    debug?: boolean;
+}): CacheManager;

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>;