@gvnrdao/dh-sdk 0.0.287 → 0.0.288

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

@@ -1,254 +0,0 @@
-/**
- * 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. Must be exactly
-     *  3 entries from the locked set: cryptocompare, coinmarketcap, coingecko. */
-    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("../cache/cache-manager.module").CacheStats | null;
-    /**
-     * Get address cache statistics
-     */
-    getAddressCacheStats(): import("../cache/cache-manager.module").CacheStats | null;
-    /**
-     * Get current network configuration
-     */
-    getNetwork(): BitcoinNetwork;
-    /**
-     * Check if consensus mode is enabled
-     */
-    isConsensusEnabled(): boolean;
-    /**
-     * Audit CRIT-2: verify a Phase-2 BTC withdrawal that the lit-ops-server
-     * claimed broadcast actually exists on chain and matches the user's
-     * authorization.
-     *
-     * Behavior:
-     *  - If we successfully fetch the tx AND it disagrees with what the user
-     *    authorized → throws (hard fail; server lied).
-     *  - If we fetch the tx and it matches → returns `{ verified: true }`.
-     *  - If no provider has the tx after `maxAttempts` retries → returns
-     *    `{ verified: false, reason: "not yet visible" }`. The caller decides
-     *    whether to log a warning and proceed (e.g., regtest without an
-     *    Esplora indexer, or extreme propagation delay) or to escalate.
-     *  - If no Bitcoin providers are configured → returns `{ verified: false,
-     *    reason: "no providers" }` immediately.
-     *
-     * The expected `value` is `targetAmount - networkFee` (what reaches the
-     * recipient after the fee), matching the Lit Action's
-     * `userReceivesAmount` computation.
-     */
-    verifyBroadcastTx(args: {
-        txid: string;
-        expectedInput: {
-            txid: string;
-            vout: number;
-        };
-        expectedOutput: {
-            address: string;
-            value: number;
-        };
-        maxAttempts?: number;
-        delayMs?: number;
-    }): Promise<{
-        verified: boolean;
-        reason?: string;
-        confirmed?: boolean;
-    }>;
-    /**
-     * Get current BTC price using LIT Protocol price oracle.
-     *
-     * Strict 3-of-3: all three configured providers must respond within 1% of
-     * each other, and the median is returned. The previous `mode: "fast" | "full"`
-     * parameter (with single-source and lenient-consensus variants) was removed
-     * in the H-2 audit fix — there is only one strict path now.
-     *
-     * @param sign - Whether to request PKP signature on the price
-     * @returns BTC price result with timestamp and source
-     */
-    getPrice(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

@@ -1,259 +0,0 @@
-/**
- * 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

@@ -1,152 +0,0 @@
-/**
- * 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>;