@gvnrdao/dh-lit-actions 0.0.60 → 0.0.63

package/pkg-dist/src/modules/bitcoin-data-provider.module.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Bitcoin Data Provider Module
+ *
+ * Provides Bitcoin network data with support for future consensus mechanisms.
+ * Current implementation: Single provider with fallback support
+ * Future implementation: 2-of-3 provider consensus
+ *
+ * This module centralizes all Bitcoin data queries to maintain a consistent
+ * interface that won't break when upgrading to multi-provider consensus.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BitcoinDataProvider = void 0;
+exports.createBitcoinDataProvider = createBitcoinDataProvider;
+/**
+ * Bitcoin Data Provider
+ *
+ * Fetches UTXO data from Bitcoin network.
+ * Interface designed to remain stable when adding multi-provider consensus.
+ */
+class BitcoinDataProvider {
+    constructor(config) {
+        this.config = config;
+        this.timeout = config.timeout || 10000; // Default 10 seconds
+    }
+    /**
+     * Fetch all UTXOs for a Bitcoin address
+     *
+     * @param address - Bitcoin address (legacy, segwit, or taproot)
+     * @returns Array of UTXOs
+     */
+    async getUTXOs(address) {
+        console.log(`[Bitcoin Data] Original address: "${address}"`);
+        // Strip network prefix if present (e.g., "REGTEST_address" -> "address")
+        const cleanAddress = this.stripNetworkPrefix(address);
+        console.log(`[Bitcoin Data] Cleaned address: "${cleanAddress}"`);
+        // If RPC helper is provided (for regtest/testing), use it directly
+        if (this.config.rpcHelper) {
+            return await this.fetchUTXOsFromRPC(cleanAddress);
+        }
+        // Try primary provider first
+        try {
+            return await this.fetchUTXOsFromProvider(this.config.providerUrl, cleanAddress);
+        }
+        catch (error) {
+            console.warn(`[Bitcoin Data] Primary provider failed: ${error.message}`);
+            // Try fallback providers if available
+            if (this.config.fallbackProviders &&
+                this.config.fallbackProviders.length > 0) {
+                const sortedFallbacks = [...this.config.fallbackProviders].sort((a, b) => a.priority - b.priority);
+                for (const fallback of sortedFallbacks) {
+                    try {
+                        console.log(`[Bitcoin Data] Trying fallback: ${fallback.name} (${fallback.url})`);
+                        return await this.fetchUTXOsFromProvider(fallback.url, cleanAddress);
+                    }
+                    catch (fallbackError) {
+                        console.warn(`[Bitcoin Data] Fallback ${fallback.name} failed: ${fallbackError.message}`);
+                        continue;
+                    }
+                }
+            }
+            throw new Error(`Failed to fetch UTXOs: ${error.message}`);
+        }
+    }
+    /**
+     * Strip network prefix from Bitcoin address
+     *
+     * Addresses may be stored with network prefix (e.g., "REGTEST_address")
+     * but APIs expect clean addresses without prefix.
+     *
+     * @param address - Address with optional prefix
+     * @returns Clean address without prefix
+     */
+    stripNetworkPrefix(address) {
+        const prefixPattern = /^(REGTEST_|TESTNET_|MAINNET_)/;
+        return address.replace(prefixPattern, "");
+    }
+    /**
+     * Fetch UTXOs using Bitcoin RPC (for regtest/testing)
+     */
+    async fetchUTXOsFromRPC(address) {
+        if (!this.config.rpcHelper) {
+            throw new Error("RPC helper not configured");
+        }
+        const wallet = this.config.rpcWallet || "";
+        const unspentOutputs = await this.config.rpcHelper.listUnspent(wallet, address);
+        const utxos = unspentOutputs.map((utxo) => ({
+            txid: utxo.txid,
+            vout: utxo.vout,
+            satoshis: BigInt(Math.round(utxo.amount * 100000000)), // BTC to satoshis as bigint
+            confirmations: utxo.confirmations,
+        }));
+        return utxos;
+    }
+    /**
+     * Parse Esplora/Blockstream/Mempool.space UTXO response
+     *
+     * Expected format: Array of {txid, vout, value, confirmations}
+     *
+     * @param data Raw response from provider API
+     * @returns Array of normalized UTXOs
+     */
+    parseBlockstreamUTXOs(data) {
+        if (!Array.isArray(data)) {
+            throw new Error("Invalid Blockstream response format: expected an array");
+        }
+        // Normalize UTXO format (different providers may have different field names)
+        const utxos = data.map((utxo) => ({
+            txid: utxo.txid,
+            vout: utxo.vout !== undefined ? utxo.vout : utxo.n,
+            satoshis: BigInt(utxo.value !== undefined ? utxo.value : utxo.satoshis),
+            confirmations: utxo.confirmations || 0,
+        }));
+        return utxos;
+    }
+    /**
+     * Internal method to fetch UTXOs from a specific provider
+     *
+     * Supports standard Esplora API format:
+     * - Standard format: {providerUrl}/address/{address}/utxos
+     * - providerUrl must include full base path (e.g., "http://localhost:3002/api/esplora")
+     */
+    async fetchUTXOsFromProvider(providerUrl, address) {
+        // Standard Esplora API format only
+        // providerUrl must include full base path (e.g., "http://localhost:3002/api/esplora")
+        const endpoint = `${providerUrl}/address/${address}/utxos`;
+        console.log(`Fetching UTXOs from ${endpoint}`);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(endpoint, {
+                signal: controller.signal,
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "User-Agent": "Mozilla/5.0 (compatible; DiamondHandsValidator/1.0)",
+                    "ngrok-skip-browser-warning": "true", // Skip ngrok browser warning page
+                },
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new Error(`Bitcoin provider error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            // Log the parsed data
+            console.log(`[Bitcoin Data] Raw API Response:`, JSON.stringify(data, null, 2));
+            // Parse standard Esplora/Blockstream format
+            return this.parseBlockstreamUTXOs(data);
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === "AbortError") {
+                throw new Error(`Request timeout after ${this.timeout}ms`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get complete UTXO set with balance summary
+     *
+     * This is the SINGLE method that vault-balance module should call.
+     * Returns everything needed to know about Bitcoin network state for an address.
+     *
+     * @param address - Bitcoin address
+     * @param minConfirmations - Minimum confirmations for "confirmed" status (REQUIRED - caller must specify)
+     * @returns Complete UTXO set with balance breakdown
+     */
+    async getUTXOSet(address, minConfirmations) {
+        const utxos = await this.getUTXOs(address);
+        const totalBalance = utxos.reduce((sum, utxo) => sum + utxo.satoshis, 0n);
+        const confirmedBalance = utxos
+            .filter((utxo) => utxo.confirmations >= minConfirmations)
+            .reduce((sum, utxo) => sum + utxo.satoshis, 0n);
+        const unconfirmedBalance = totalBalance - confirmedBalance;
+        return {
+            utxos,
+            totalBalance,
+            totalUTXOs: utxos.length,
+            confirmedBalance,
+            unconfirmedBalance,
+        };
+    }
+    /**
+     * Get transaction with confirmation count
+     *
+     * Checks if transaction exists on Bitcoin network and returns confirmation count.
+     * Used to validate authorized spends have been broadcasted.
+     *
+     * @param txid - Transaction ID to check
+     * @returns Transaction with confirmation count, or null if not found
+     */
+    async getTransaction(txid) {
+        // If RPC helper is provided (for regtest/testing), use it directly
+        if (this.config.rpcHelper) {
+            try {
+                const wallet = this.config.rpcWallet || "";
+                const tx = await this.config.rpcHelper.getTransaction(wallet, txid);
+                return {
+                    txid: tx.txid,
+                    confirmations: tx.confirmations || 0,
+                };
+            }
+            catch (error) {
+                // Transaction not found
+                if (error.message?.includes("Invalid or non-wallet transaction") ||
+                    error.code === -5) {
+                    return null;
+                }
+                throw error;
+            }
+        }
+        // Try provider API
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(`${this.config.providerUrl}/api/tx/${txid}`, {
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                if (response.status === 404) {
+                    return null; // Transaction not found
+                }
+                throw new Error(`Bitcoin provider error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            // Blockstream API format
+            if (data.status) {
+                return {
+                    txid: data.txid,
+                    confirmations: data.status.confirmed
+                        ? data.status.block_height
+                            ? 1
+                            : 0
+                        : 0,
+                };
+            }
+            return null;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === "AbortError") {
+                throw new Error(`Request timeout after ${this.timeout}ms`);
+            }
+            // 404 means transaction not found
+            if (error.message?.includes("404")) {
+                return null;
+            }
+            throw error;
+        }
+    }
+}
+exports.BitcoinDataProvider = BitcoinDataProvider;
+/**
+ * Factory function for creating Bitcoin Data Provider
+ * Useful for dependency injection and testing
+ */
+function createBitcoinDataProvider(config) {
+    return new BitcoinDataProvider(config);
+}
+//# sourceMappingURL=bitcoin-data-provider.module.js.map

package/pkg-dist/src/modules/bitcoin-data-provider.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitcoin-data-provider.module.js","sourceRoot":"","sources":["../../../src/modules/bitcoin-data-provider.module.ts"],"names":[],"mappings":"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"}

package/pkg-dist/src/modules/business-rules-math.module.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Business Rules Math Module
+ *
+ * Pure calculation functions for Diamond Hands Protocol business logic.
+ * These functions contain no side effects - they only perform calculations.
+ *
+ * Used by vault-snapshot and other modules for consistent math across the system.
+ */
+/**
+ * Calculate term start timestamp from expiry timestamp and term length
+ *
+ * Contract stores expiryAt but not termStartTimestamp.
+ * We derive it: termStart = expiry - (termLength * 30 days)
+ *
+ * Uses constants to avoid magic numbers and ensure accuracy.
+ *
+ * @param expiryTimestamp - Unix timestamp when term expires (0 if no term)
+ * @param termLengthMonths - Term length in months
+ * @returns Unix timestamp when term started (0 if no term)
+ */
+export declare function calculateTermStartFromExpiry(expiryTimestamp: number, termLengthMonths: number): number;
+/**
+ * Calculate term status from timestamps
+ *
+ * Determines:
+ * - How long into the term we are
+ * - Whether term is expired
+ * - Days until expiry or days into grace period
+ *
+ * @param termStartTimestamp - Unix timestamp when term started (0 if not started)
+ * @param selectedTermMonths - Term length in months
+ * @returns Complete term status metrics
+ */
+export declare function calculateTermStatus(termStartTimestamp: number, selectedTermMonths: number): {
+    termDurationDays: number;
+    termLengthDays: number;
+    isExpired: boolean;
+    daysUntilExpiry: number;
+    daysIntoGracePeriod: number;
+};
+/**
+ * Calculate current liquidation threshold with grace period escalation
+ *
+ * Active loan: 130% (13000 bps)
+ * Expired:
+ *   Day 0: 110% (11000 bps)
+ *   Day 30: 200% (20000 bps)
+ *   Quadratic escalation between
+ *
+ * Uses integer-only math for deterministic results across all platforms.
+ *
+ * @param isExpired - Whether loan is expired
+ * @param daysIntoGracePeriod - Days past expiry (0 if not expired)
+ * @returns Liquidation threshold in basis points
+ */
+export declare function calculateLiquidationThreshold(isExpired: boolean, daysIntoGracePeriod: number): number;
+/**
+ * Calculate collateral metrics from BTC balance and debt
+ *
+ * Converts BTC balance to USD value and calculates collateral ratio.
+ * Uses BigInt for all calculations to avoid JavaScript number precision issues.
+ *
+ * @param availableBTCSats - Available BTC balance in satoshis
+ * @param btcPriceUsd - BTC price with 8 decimals (e.g., 10000000000000 = $100,000)
+ * @param ucdDebt - UCD debt in wei (18 decimals)
+ * @returns Collateral value in USD and ratio in basis points
+ */
+export declare function calculateCollateralMetrics(availableBTCSats: bigint, btcPriceUsd: bigint, ucdDebt: bigint): {
+    collateralValueUsd: bigint;
+    collateralRatioBps: number;
+};
+/**
+ * Check if adding additional debt would maintain required collateral ratio
+ *
+ * Used by minting authorization to validate new mints.
+ *
+ * @param collateralValueUsd - Current collateral value in USD (whole dollars)
+ * @param currentDebt - Current UCD debt in wei (18 decimals)
+ * @param additionalDebt - Additional UCD debt to add in wei (18 decimals)
+ * @param requiredRatioBps - Required collateral ratio in basis points (e.g., 13000 for 130%)
+ * @returns True if sufficient collateral exists after adding debt
+ */
+export declare function hasSufficientCollateralForDebt(collateralValueUsd: bigint, currentDebt: bigint, additionalDebt: bigint, requiredRatioBps: number): boolean;
+/**
+ * Calculate fee from amount using basis points
+ *
+ * Bulletproof fee calculation with validation.
+ * Multiply before divide to maintain precision.
+ *
+ * @param amount - Principal amount (in wei or sats)
+ * @param feeBps - Fee in basis points (e.g., 50 = 0.5%)
+ * @returns Fee amount in same units as input
+ *
+ * @example
+ * calculateFeeBps(1000000000000000000n, 50) // 0.5% of 1 ETH
+ * // Returns: 5000000000000000n (0.005 ETH)
+ */
+export declare function calculateFeeBps(amount: bigint, feeBps: number): bigint;
+/**
+ * Calculate USD value of BTC amount
+ *
+ * Converts satoshis to USD using price with 8 decimals.
+ * Result maintains 8 decimal precision.
+ *
+ * @param btcSats - Bitcoin amount in satoshis
+ * @param btcPriceUsd8Decimals - BTC price with 8 decimals (e.g., 9800000000000n = $98,000)
+ * @returns USD value with 8 decimals
+ *
+ * @example
+ * calculateBtcValueUsd(100000000n, 9800000000000n) // 1 BTC at $98,000
+ * // Returns: 9800000000000n ($98,000 with 8 decimals)
+ */
+export declare function calculateBtcValueUsd(btcSats: bigint, btcPriceUsd8Decimals: bigint): bigint;
+/**
+ * Calculate collateral ratio in basis points (with 8-decimal collateral and 18-decimal debt)
+ *
+ * Used for UCD mint validation where collateral is in USD (8 decimals)
+ * and debt is in UCD wei (18 decimals).
+ *
+ * @param collateralValueUsd8Decimals - Collateral value in USD with 8 decimals
+ * @param debtUsd18Decimals - Debt amount in USD with 18 decimals (UCD wei)
+ * @returns Collateral ratio in basis points (e.g., 20000 = 200%)
+ *
+ * @example
+ * calculateCollateralRatioBps(9800000000000n, 4000000000000000000000n)
+ * // $98,000 collateral / $4,000 debt = 24.5 = 2450% = 24500 bps
+ * // Returns: 24500
+ */
+export declare function calculateCollateralRatioBps(collateralValueUsd8Decimals: bigint, debtUsd18Decimals: bigint): number;
+/**
+ * Check if collateral ratio meets minimum requirement
+ *
+ * @param collateralValueUsd8Decimals - Collateral value in USD with 8 decimals
+ * @param debtUsd18Decimals - Debt amount in USD with 18 decimals
+ * @param minimumRatioBps - Minimum required ratio in basis points (e.g., 20000 = 200%)
+ * @returns True if collateral is sufficient
+ *
+ * @example
+ * isCollateralSufficient(20000000000000n, 10000000000000000000000n, 20000)
+ * // $200,000 collateral / $10,000 debt = 2000% >= 200%
+ * // Returns: true
+ */
+export declare function isCollateralSufficient(collateralValueUsd8Decimals: bigint, debtUsd18Decimals: bigint, minimumRatioBps: number): boolean;
+/**
+ * Convert basis points to percentage (for display)
+ *
+ * @param basisPoints - Value in basis points
+ * @returns Percentage as number (e.g., 20000 bps => 200)
+ *
+ * @example
+ * bpsToPercent(20000) // Returns: 200
+ * bpsToPercent(50) // Returns: 0.5
+ */
+export declare function bpsToPercent(basisPoints: number): number;
+//# sourceMappingURL=business-rules-math.module.d.ts.map

package/pkg-dist/src/modules/business-rules-math.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"business-rules-math.module.d.ts","sourceRoot":"","sources":["../../../src/modules/business-rules-math.module.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,eAAe,EAAE,MAAM,EACvB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAgBR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,GACzB;IACD,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,CA4BA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,OAAO,EAClB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,CAwBR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd;IACD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAyCA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAC5C,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAgBT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAatE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,oBAAoB,EAAE,MAAM,GAC3B,MAAM,CAcR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,2BAA2B,EAAE,MAAM,EACnC,iBAAiB,EAAE,MAAM,GACxB,MAAM,CA4BR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,2BAA2B,EAAE,MAAM,EACnC,iBAAiB,EAAE,MAAM,EACzB,eAAe,EAAE,MAAM,GACtB,OAAO,CAaT;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAExD"}