@gvnrdao/dh-sdk 0.0.288 → 0.0.289

package/dist/interfaces/chunks/position-query.i.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Position Query Interfaces
+ */
+import { LoanStatus } from "../../types/loanStatus";
+/**
+ * Position data structure (from contract)
+ */
+export interface Position {
+    positionId: string;
+    pkpId: string;
+    borrower: string;
+    vaultAddress: string;
+    vaultAddressRegtest?: string;
+    ucdDebt: bigint;
+    createdAt: number;
+    lastUpdated: number;
+    expiryAt: number;
+    status: LoanStatus;
+    collateralRatio?: number;
+    requestedCollateralRatio?: number;
+    selectedTerm: number;
+}
+/**
+ * Bitcoin UTXO (Unspent Transaction Output)
+ */
+export interface BitcoinUTXO {
+    txId: string;
+    vout: number;
+    value: number;
+    confirmations: number;
+    scriptPubKey?: string;
+    address?: string;
+}
+/**
+ * Position with Bitcoin status
+ */
+export interface PositionWithBTCStatus extends Position {
+    btcStatus: {
+        actualAmount: bigint;
+        confirmations: number;
+        utxos: BitcoinUTXO[];
+        lastCheckedAt: number;
+    };
+}
+/**
+ * Position query options
+ */
+export interface PositionQueryOptions {
+    borrower?: string;
+    status?: LoanStatus | LoanStatus[];
+    verifyBTC?: boolean;
+    offset?: number;
+    limit?: number;
+    sortBy?: 'createdAt' | 'lastUpdated' | 'ucdDebt';
+    sortDirection?: 'asc' | 'desc';
+}
+/**
+ * Position query result
+ */
+export interface PositionQueryResult {
+    positions: Position[] | PositionWithBTCStatus[];
+    total: number;
+    hasMore: boolean;
+    executionTimeMs: number;
+}
+/**
+ * Bitcoin balance check result
+ */
+export interface BitcoinBalanceResult {
+    address: string;
+    balance: bigint;
+    utxos: BitcoinUTXO[];
+    confirmations: number;
+    provider: string;
+    timestamp: number;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * General Request/Response Types and Interfaces
+ */
+import { AuthorizationParams } from '../../types/authorization-params';
+/**
+ * Authorization request with type-safe parameters
+ */
+export interface AuthorizationRequest {
+    /** PKP token ID */
+    pkpId: string;
+    /** Action being authorized (derived from params.type) */
+    action: string;
+    /** Type-safe authorization parameters (discriminated union) */
+    params: AuthorizationParams;
+    /** Authorization signature */
+    signature: string;
+    /** Request timestamp */
+    timestamp: number;
+}
+/**
+ * Result of an authorization check
+ */
+export interface AuthorizationResult {
+    /** Whether the authorization was successful */
+    authorized: boolean;
+    /** PKP token ID that was checked */
+    pkpId: string;
+    /** Error message if authorization failed */
+    error?: string;
+    /** Additional details about the authorization (type-safe per action) */
+    details?: unknown;
+}
+export interface ValidationRequest {
+    data: any;
+    rules: string[];
+    context?: Record<string, any>;
+}
+export interface ConfirmationResult {
+    confirmed: boolean;
+    confirmations: number;
+    blockHeight?: number;
+    txHash?: string;
+    error?: string;
+}
+export interface BTCDepositRequest {
+    positionId: string;
+}
+export interface BTCDepositResult {
+    success: boolean;
+    positionId?: string;
+    vaultBalance?: string;
+    hasBalance?: boolean;
+    validationResponse?: any;
+    error?: string;
+}

package/dist/interfaces/chunks/ucd-minting.i.d.ts

@@ -0,0 +1,34 @@
+/**
+ * UCD Minting Types and Interfaces
+ */
+export interface IUCDMinting {
+    mint(params: MintingParams): Promise<MintingResult>;
+    calculateRewards(amount: string): Promise<RewardDistribution>;
+    validateMinting(params: MintingParams): Promise<boolean>;
+}
+export interface MintingParams {
+    amount: string;
+    recipient: string;
+    collateralType: string;
+    collateralAmount: string;
+    oracleData?: any;
+}
+export interface MintingResult {
+    success: boolean;
+    txHash?: string;
+    mintedAmount?: string;
+    fees?: string;
+    rewards?: RewardDistribution;
+    error?: string;
+}
+export interface RewardDistribution {
+    totalRewards: string;
+    operatorReward: string;
+    protocolReward: string;
+    liquidityProviderReward: string;
+    distribution: {
+        operator: string;
+        protocol: string;
+        liquidityProvider: string;
+    };
+}

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,254 @@
+/**
+ * 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>;