@gvnrdao/dh-sdk 0.0.172 → 0.0.206

package/dist/modules/diamond-hands-sdk.d.ts

@@ -0,0 +1,666 @@
+/**
+ * Diamond Hands SDK - Main Entry Point
+ *
+ * This is the primary SDK class that orchestrates all modules.
+ * It provides a clean, high-level API for interacting with the Diamond Hands protocol.
+ *
+ * Architecture:
+ * - Thin orchestrator (< 500 lines)
+ * - Delegates to specialized modules
+ * - No business logic (all in modules)
+ * - Dependency injection pattern
+ * - Result-based error handling
+ */
+import { Result } from "../types/result";
+import { Satoshis } from "../types/branded/domain-values";
+import { SDKError } from "../utils/error-handler";
+import type { CreateLoanRequest, CreateLoanResult, LoanData, LoanDataDetail, UCDMintRequest, UCDMintResult, PartialPaymentRequest, PartialPaymentResult, BTCWithdrawalResult, RenewPositionRequest, RenewPositionResult, LiquidationRequest, LiquidationResult, ConfirmBalanceRequest, ConfirmBalanceResult, TermsWithFeesResult } from "../interfaces/chunks/loan-operations.i";
+import type { DiamondHandsSDKConfig } from "../interfaces/chunks/config.i";
+import type { PKPData } from "../interfaces/chunks/pkp-integration.i";
+import { ContractManager } from "./contract/contract-manager.module";
+import { BitcoinOperations } from "./bitcoin/bitcoin-operations.module";
+type PositionDetailsView = {
+    positionId: string;
+    pkpId: string;
+    ucdDebt: any;
+    debt?: any;
+    btcVault?: any;
+    btcVaultBalance?: any;
+    btcPrice?: any;
+    [key: string]: any;
+};
+/**
+ * Diamond Hands SDK
+ *
+ * Main SDK class providing high-level API for the Diamond Hands lending protocol.
+ *
+ * @example
+ * ```typescript
+ * const sdkResult = await DiamondHandsSDK.create({
+ *   mode: 'service',
+ *   serviceEndpoint: 'https://lit-ops.example.com',
+ *   contractSigner: wallet,
+ * });
+ *
+ * if (!sdkResult.success) {
+ *   console.error('Failed to initialize SDK:', sdkResult.error);
+ *   return;
+ * }
+ *
+ * const sdk = sdkResult.value;
+ *
+ * // Create a loan
+ * const result = await sdk.createLoan({ selectedTerm: 12 });
+ * if (result.success) {
+ *   console.log('Position created:', result.value.positionId);
+ * }
+ *
+ * // Clean up when done
+ * sdk.dispose();
+ * ```
+ */
+export declare class DiamondHandsSDK {
+    private readonly config;
+    private readonly contractManager;
+    private readonly cacheManager;
+    private readonly litOps;
+    private readonly pkpManager;
+    private readonly loanCreator;
+    private readonly loanQuery;
+    private readonly bitcoinOperations;
+    private readonly mockTokenManager?;
+    private readonly graphClient;
+    private isInitialized;
+    private isDisposed;
+    /**
+     * Private constructor - use DiamondHandsSDK.create() instead
+     *
+     * @param config - SDK configuration
+     */
+    private constructor();
+    /**
+     * Create and initialize a new Diamond Hands SDK instance
+     *
+     * This is the recommended way to create an SDK instance. It validates the
+     * configuration, initializes all modules, and verifies connectivity before
+     * returning the SDK instance.
+     *
+     * @param config - SDK configuration (discriminated union based on mode)
+     * @returns Result containing initialized SDK or error
+     *
+     * @example Service Mode
+     * ```typescript
+     * const result = await DiamondHandsSDK.create({
+     *   mode: 'service',
+     *   serviceEndpoint: 'https://lit-ops.example.com',
+     *   contractSigner: wallet,
+     * });
+     * ```
+     *
+     * @example Standalone Mode
+     * ```typescript
+     * const result = await DiamondHandsSDK.create({
+     *   mode: 'standalone',
+     *   litOpsSigner: wallet,
+     *   contractSigner: wallet,
+     * });
+     * ```
+     */
+    static create(config: DiamondHandsSDKConfig): Promise<Result<DiamondHandsSDK, SDKError>>;
+    /**
+     * Enrich configuration with network defaults from network-configs.ts
+     *
+     * If contractAddresses or subgraphs are not provided, attempt to load them
+     * from the network configuration based on the detected chainId.
+     */
+    private static enrichConfigWithNetworkDefaults;
+    /**
+     * Initialize the SDK and verify it's ready for use
+     *
+     * This method:
+     * 1. Marks the SDK as initialized
+     * 2. Verifies network connectivity
+     * 3. Validates contract addresses
+     *
+     * @returns Result indicating success or failure
+     */
+    private initialize;
+    /**
+     * Verify network connectivity and contract availability
+     */
+    private verifyConnection;
+    /**
+     * Dispose of the SDK and clean up resources
+     *
+     * This method:
+     * - Clears all caches
+     * - Removes event listeners
+     * - Marks the SDK as disposed
+     *
+     * After calling dispose(), the SDK instance cannot be reused.
+     */
+    dispose(): void;
+    /**
+     * Check if SDK is ready for operations
+     */
+    private _relayNotification;
+    private checkInitialized;
+    private toSDKError;
+    /**
+     * Get SDK initialization state
+     */
+    get initialized(): boolean;
+    /**
+     * Get SDK disposal state
+     */
+    get disposed(): boolean;
+    /**
+     * Create a new loan
+     *
+     * Complete flow: PKP creation → address derivation → authorization → contract call
+     *
+     * @param request - Loan creation request
+     * @returns Loan creation result with position ID and audit trail
+     * @example
+     * ```typescript
+     * const result = await sdk.createLoan({
+     *   collateralAmount: 25_000,
+     *   collateralRatio: 150,
+     *   selectedTerm: 3,
+     * });
+     * if (result.success) {
+     *   console.log(result.value.positionId);
+     * }
+     * ```
+     */
+    createLoan(request: CreateLoanRequest): Promise<Result<CreateLoanResult, SDKError>>;
+    /**
+     * Request UCD minting against existing collateral
+     * Performs LIT Action validation and calls contract
+     *
+     * @param request - Mint request with position ID and amount
+     * @returns Mint result with transaction details
+     * @example
+     * ```typescript
+     * const mint = await sdk.requestMintUCD({ positionId, amount: 100 });
+     * if (!mint.success) {
+     *   console.error(mint.error);
+     * }
+     * ```
+     */
+    requestMintUCD(request: UCDMintRequest): Promise<UCDMintResult>;
+    /**
+     * Request UCD minting using the SDK-wide `Result` contract.
+     *
+     * Use this in new integrations when you want a consistent error model that
+     * avoids thrown exceptions for routine operation failures.
+     *
+     * @param request - Mint request with position ID and amount.
+     * @returns `Result` containing mint transaction data or an `SDKError`.
+     * @example
+     * ```typescript
+     * const result = await sdk.requestMintUCDResult({ positionId, amount: 100 });
+     * if (!result.success) {
+     *   console.error(result.error.code, result.error.message);
+     *   return;
+     * }
+     * console.log(result.value.transactionHash);
+     * ```
+     */
+    requestMintUCDResult(request: UCDMintRequest): Promise<Result<UCDMintResult, SDKError>>;
+    private _requestMintUCDAttempt;
+    /**
+     * @notice Liquidate position using commit-reveal system with MEV protection
+     * @dev Executes liquidation with randomized delay to prevent MEV attacks using LIQUIDATOR_ROLE.
+     * On-chain liquidation burns the position debt in UCD from the liquidator via `UCDController`;
+     * `UCDToken` (M-4) requires an allowance from the liquidator to UCDController. Before
+     * `commitLiquidation`, the SDK checks UCD balance and allowance; if allowance is below debt
+     * it submits `approve(ucdController, debt)` unless `request.skipUcdApproval` is true.
+     * @param request - Liquidation request with position ID and options
+     * @returns Liquidation result with transaction details
+     * @example
+     * ```typescript
+     * const liq = await sdk.liquidatePosition({ positionId });
+     * if (!liq.success) {
+     *   console.error(liq.error);
+     * }
+     * ```
+     */
+    liquidatePosition(request: LiquidationRequest): Promise<LiquidationResult>;
+    /**
+     * Liquidate a position using the SDK-wide `Result` contract.
+     *
+     * @param request - Liquidation request payload.
+     * @returns `Result` containing liquidation details or an `SDKError`.
+     * @example
+     * ```typescript
+     * const result = await sdk.liquidatePositionResult({ positionId });
+     * if (result.success) {
+     *   console.log(result.value.transactionHash);
+     * }
+     * ```
+     */
+    liquidatePositionResult(request: LiquidationRequest): Promise<Result<LiquidationResult, SDKError>>;
+    /**
+     * Extend position term
+     *
+     * Follows main's security pattern: authorization → LIT validation → contract execution
+     * Same pattern as makePayment: generate user auth, call lit-ops for LIT Action, then call contract.
+     *
+     * @param _positionId - Position identifier
+     * @param _selectedTerm - Extension term in months
+     * @returns Transaction receipt
+     */
+    private extendPosition;
+    /**
+     * Renew (extend) position with consistent response structure
+     *
+     * This method provides a consistent API for position renewal that returns
+     * structured transaction details instead of raw TransactionReceipt.
+     *
+     * @param request - Renew position request with position ID and selected term
+     * @returns Structured renewal result with transaction details
+     * @example
+     * ```typescript
+     * const renewal = await sdk.renewPosition({ positionId, selectedTerm: 6 });
+     * if (renewal.success) {
+     *   console.log(renewal.transactionHash);
+     * }
+     * ```
+     */
+    renewPosition(request: RenewPositionRequest): Promise<RenewPositionResult>;
+    /**
+     * Renew a position using the SDK-wide `Result` contract.
+     *
+     * @param request - Renewal request with position and term.
+     * @returns `Result` containing renewal details or an `SDKError`.
+     * @example
+     * ```typescript
+     * const result = await sdk.renewPositionResult({ positionId, selectedTerm: 3 });
+     * if (!result.success) {
+     *   throw result.error;
+     * }
+     * ```
+     */
+    renewPositionResult(request: RenewPositionRequest): Promise<Result<RenewPositionResult, SDKError>>;
+    /**
+     * Confirm Bitcoin balance for a position
+     *
+     * This method:
+     * 1. Queries BTC balance via LIT Action
+     * 2. Gets PKP signature for the balance
+     * 3. Calls PositionManager.updateBalance() on-chain
+     * 4. Transitions position status to PENDING_MINT
+     *
+     * @param request - Confirm balance request with position ID
+     * @returns Confirmation result with transaction details
+     */
+    confirmBalance(request: ConfirmBalanceRequest): Promise<ConfirmBalanceResult>;
+    /**
+     * Make a payment on a loan position
+     *
+     * Follows main's security pattern: authorization → LIT validation → contract execution
+     *
+     * @param request - Payment request with position ID and amount
+     * @returns Payment result with transaction details
+     */
+    makePayment(request: PartialPaymentRequest): Promise<PartialPaymentResult>;
+    /**
+     * Withdraw Bitcoin from a position
+     *
+     * @param positionId - Position identifier
+     * @param withdrawalAddress - Bitcoin address to send BTC to
+     * @param withdrawalAmount - Amount to withdraw in satoshis (REQUIRED)
+     * @param networkFee - Network fee for Bitcoin transaction in satoshis (REQUIRED)
+     * @returns Withdrawal result with transaction details
+     */
+    /**
+     * Withdraw BTC from position vault
+     *
+     * IMPORTANT: withdrawalAmount is the TOTAL DEDUCTION from vault.
+     * The operator will deduct the actual network fee at execution time.
+     * User receives: withdrawalAmount - actualNetworkFee
+     *
+     * @param positionId - Position identifier
+     * @param withdrawalAddress - Bitcoin address to receive withdrawn funds
+     * @param withdrawalAmount - Total amount to deduct from vault in satoshis (includes fee)
+     * @param rpcUrl - Optional RPC URL override for LIT Action (for local testing)
+     * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
+     * @returns Withdrawal result with transaction details
+     */
+    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number, rpcUrl?: string, customBitcoinRpcUrl?: string): Promise<BTCWithdrawalResult>;
+    /**
+     * Execute Bitcoin withdrawal (Phase 2)
+     *
+     * Signs and broadcasts the Bitcoin transaction for an authorized withdrawal.
+     * User must have previously authorized the withdrawal via withdrawBTC().
+     *
+     * @param request - Execution request with positionId, utxoIdentifier, and networkFee
+     * @returns Execution result with Bitcoin txid
+     */
+    executeBTCWithdrawal(request: {
+        positionId: string;
+        utxoIdentifier: string;
+        networkFee: number;
+        destination: string;
+        rpcUrl?: string;
+        customBitcoinRpcUrl?: string;
+    }): Promise<{
+        success: boolean;
+        txid?: string;
+        amountSent?: number;
+        networkFee?: number;
+        destination?: string;
+        error?: string;
+    }>;
+    /**
+     * Execute pending Bitcoin transfers
+     *
+     * Queries authorized spends that haven't been broadcast to Bitcoin network yet
+     * and executes them by signing and broadcasting the transactions.
+     *
+     * @param positionId - Position identifier
+     * @param networkFee - Network fee for Bitcoin transaction in satoshis
+     * @param rpcUrl - Optional RPC URL override for LIT Action (for local testing)
+     * @returns Array of execution results for each pending transfer
+     */
+    executePendingBtcTransfers(positionId: string, networkFee: number, rpcUrl?: string): Promise<Array<{
+        success: boolean;
+        utxoIdentifier?: string;
+        txid?: string;
+        amountSent?: number;
+        networkFee?: number;
+        destination?: string;
+        error?: string;
+    }>>;
+    /**
+     * Withdraw BTC and execute transfer (Complete Flow)
+     *
+     * Performs both Phase 1 (authorization) and Phase 2 (execution) in sequence:
+     * 1. Authorizes withdrawal on contract (withdrawBTC)
+     * 2. Executes pending Bitcoin transfers (signs and broadcasts)
+     *
+     * @param positionId - Position identifier
+     * @param withdrawalAddress - Bitcoin address to receive withdrawn funds
+     * @param withdrawalAmount - Total amount to deduct from vault in satoshis
+     * @param networkFee - Network fee for Bitcoin transaction in satoshis
+     * @param rpcUrl - Optional RPC URL override for LIT Action (for local testing)
+     * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
+     * @returns Complete withdrawal result with both authorization and execution details
+     */
+    withdrawBTCAndExecute(positionId: string, withdrawalAddress: string, withdrawalAmount: number, networkFee: number, rpcUrl?: string, customBitcoinRpcUrl?: string): Promise<{
+        success: boolean;
+        authorization?: BTCWithdrawalResult;
+        transfers?: Array<{
+            success: boolean;
+            utxoIdentifier?: string;
+            txid?: string;
+            amountSent?: number;
+            networkFee?: number;
+            destination?: string;
+            error?: string;
+        }>;
+        error?: string;
+    }>;
+    /**
+     * Get loan data by position ID
+     *
+     * @param positionId - Position ID
+     * @param enrichBalance - Whether to enrich with current Bitcoin balance
+     * @returns Detailed loan data
+     */
+    getLoanById(positionId: string, enrichBalance?: boolean): Promise<Result<LoanDataDetail | null, SDKError>>;
+    /**
+     * Get loan data by PKP ID
+     *
+     * @param pkpId - PKP token ID
+     * @param enrichBalance - Whether to enrich with current Bitcoin balance
+     * @returns Loan data
+     */
+    getLoanByPkpId(pkpId: string, enrichBalance?: boolean): Promise<Result<LoanData | null, SDKError>>;
+    /**
+     * Get loans for a borrower
+     *
+     * @param borrower - Borrower address
+     * @param pagination - Optional pagination parameters (page, pageSize)
+     * @returns Paginated loans response with loans array, page info, and total count
+     */
+    getLoansByBorrower(borrower: string, pagination?: {
+        page: number;
+        pageSize: number;
+    }): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
+    /**
+     * Get all active loans
+     *
+     * @param pagination - Optional pagination parameters (page, pageSize)
+     * @returns Paginated loans response with loans array, page info, and total count
+     */
+    getActiveLoans(pagination?: {
+        page: number;
+        pageSize: number;
+    }): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
+    /**
+     * Get loans by state/status
+     *
+     * @param state - Loan state (PENDING_DEPOSIT, ACTIVE, EXPIRED, REPAID, LIQUIDATED, EXTENDED, CLOSED)
+     * @param pagination - Optional pagination parameters (page, pageSize)
+     * @returns Paginated loans response with loans array, page info, and total count
+     */
+    getLoansByState(state: string, pagination?: {
+        page: number;
+        pageSize: number;
+    }): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
+    /**
+     * Get all loans with pagination
+     *
+     * @param pagination - Pagination parameters (page, maxRows, orderBy, orderDirection)
+     * @param enrichBalance - Whether to enrich loans with Bitcoin balance (not used currently)
+     * @param source - Data source: "subgraph" (default) or "contract"
+     * @returns Paginated loans response with loans array, page info, and total count
+     */
+    getLoansAll(pagination?: {
+        page?: number;
+        maxRows?: number;
+        orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt";
+        orderDirection?: "asc" | "desc";
+    }, source?: "subgraph" | "contract"): Promise<Result<import("..").PaginatedLoansResponse, SDKError>>;
+    /**
+     * Get all events for a loan position from the subgraph
+     */
+    getLoanEvents(positionId: string, filter?: import("../types/event-types").LoanEventsFilter): Promise<Result<import("..").LoanEvents, SDKError>>;
+    /**
+     * Wait for the subgraph to index up to (and including) the given block number.
+     * Call after on-chain actions (createLoan, mintUCD, etc.) before querying the subgraph.
+     *
+     * @param targetBlock - Block number the subgraph must have indexed
+     * @param options - Override timeout/interval for this call
+     * @throws if timeout is reached before subgraph catches up
+     */
+    /**
+     * Get Bitcoin balance for an address
+     *
+     * @param address - Bitcoin address
+     * @returns Balance in satoshis
+     */
+    getBitcoinBalance(address: string): Promise<Result<import("..").EnrichedBitcoinBalance, SDKError>>;
+    /**
+     * Get the current Bitcoin price
+     *
+     * @returns the current Bitcoin price in USD
+     */
+    getBitcoinPrice(): Promise<{
+        price: number;
+        priceE8: string;
+        timestamp: number;
+        source: string;
+        signature: string | undefined;
+        signer: string | undefined;
+    }>;
+    /**
+     * Derive Bitcoin addresses from PKP public key
+     *
+     * @param publicKey - PKP public key
+     * @returns Bitcoin addresses for all networks
+     */
+    deriveBitcoinAddresses(publicKey: string): Promise<Result<import("..").BitcoinAddresses, SDKError>>;
+    /**
+     * Get PKP data by token ID
+     *
+     * @param tokenId - PKP token ID
+     * @returns PKP data
+     */
+    getPKPData(tokenId: string): Promise<Result<PKPData | null, SDKError>>;
+    /**
+     * Get PKP public key by token ID
+     *
+     * @param tokenId - PKP token ID
+     * @returns PKP public key
+     */
+    getPKPPublicKey(tokenId: string): Promise<Result<string, SDKError>>;
+    /**
+     * Get all available loan terms with their fees
+     *
+     * Retrieves all valid loan terms from the TermManager contract along with
+     * their origination fees and extension/renewal fees.
+     *
+     * @returns Result containing array of terms with fees
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.getTermsWithFees();
+     * if (result.success) {
+     *   result.value.terms.forEach(term => {
+     *     console.log(`${term.termMonths} months: ${term.originationFeeBps}bps origination, ${term.extensionFeeBps}bps renewal`);
+     *   });
+     * }
+     * ```
+     */
+    getTermsWithFees(): Promise<Result<TermsWithFeesResult, SDKError>>;
+    /**
+     * Mint mock BTC tokens (test networks only)
+     *
+     * @param amount - Amount in satoshis
+     * @param recipient - Recipient address
+     * @returns Transaction result
+     */
+    mintMockBTC(amount: Satoshis, recipient: string): Promise<Result<import("..").MockTokenTransactionResult, SDKError>>;
+    /**
+     * Approve mock BTC spending (test networks only)
+     *
+     * @param spender - Spender address
+     * @param amount - Amount in satoshis
+     * @returns Transaction result
+     */
+    approveMockBTC(spender: string, amount: Satoshis): Promise<Result<import("..").MockTokenTransactionResult, SDKError>>;
+    /**
+     * Get SDK configuration
+     */
+    getConfig(): DiamondHandsSDKConfig;
+    /**
+     * Clear all caches
+     */
+    clearAllCaches(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): Record<string, import("..").CacheStats>;
+    /**
+     * Get contract manager (for advanced usage)
+     */
+    getContractManager(): ContractManager;
+    /**
+     * Get Bitcoin operations module (for advanced usage)
+     */
+    getBitcoinOperations(): BitcoinOperations;
+    /**
+     * Check if running on production network
+     */
+    private isProductionNetwork;
+    /**
+     * Get Bitcoin network based on chain
+     */
+    private getBitcoinNetwork;
+    /**
+     * Extract error message from LIT Action response
+     * Checks both `error` and `reason` fields and parses nested error structures
+     *
+     * @private
+     * @remarks Production-ready error parser for LIT Protocol responses
+     *          Will be integrated into core methods in Round 2
+     */
+    private extractLitActionError;
+    /**
+     * Get provider or throw error
+     */
+    private getProviderOrThrow;
+    /**
+     * Get signer or throw error
+     */
+    private getSignerOrThrow;
+    /**
+     * Get contract addresses or throw error
+     */
+    private getContractAddressesOrThrow;
+    /**
+     * Ensure SDK is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Convert decimal position ID to bytes32 format
+     */
+    private toBytes32;
+    /**
+     * Check if an error indicates a technical failure vs business logic rejection
+     */
+    /**
+     * Get position details view from contract
+     * Queries PositionManagerCoreModule directly for reliability (subgraph listens to core module)
+     */
+    getPositionDetailsView(positionId: string): Promise<PositionDetailsView>;
+    /**
+     * Get position by ID (internal helper)
+     * Uses getPositionDetailsView which queries core module directly
+     */
+    private getPosition;
+    /**
+     * Verify position exists in core contract (PositionManagerCoreModule)
+     * This is critical because mint operations check the core contract, not PositionManager
+     *
+     * @param positionId - Position ID to verify
+     * @param retries - Number of retries with exponential backoff (default: 3)
+     * @param retryDelayMs - Initial retry delay in milliseconds (default: 1000)
+     * @returns Promise<boolean> - true if position exists, false otherwise
+     */
+    verifyPositionExistsInCore(positionId: string, retries?: number, retryDelayMs?: number): Promise<boolean>;
+    /**
+     * Get loan operations accessor
+     * Returns a helper object for interacting with loan operations contract
+     */
+    loanOps(): {
+        getProtocolConfig(): Promise<{
+            liquidationThreshold: any;
+            minimumLoanValueUcd: any;
+            minimumLoanValueWei: any;
+            maxSingleLoanValueUcd: any;
+        }>;
+    };
+    /**
+     * Calculate reveal delay for MEV protection in commit-reveal liquidation
+     * @param positionId Position identifier (for entropy)
+     * @param quantumTimestamp LIT quantum timestamp (for additional entropy)
+     * @returns Delay in seconds before reveal phase can execute
+     */
+    private calculateRevealDelay;
+    /**
+     * Calculate the exact reveal delay by replicating LiquidationManager._calculateRandomizedDelay.
+     * Reads vrfSeeds[positionId] from the contract and applies the same two-step keccak256 formula.
+     * Falls back to the local estimate if the contract read fails.
+     */
+    private calculateRevealDelayFromContract;
+    /**
+     * Wait for the specified delay period (MEV protection)
+     * @param delaySeconds Number of seconds to wait
+     */
+    private waitForRevealDelay;
+}
+export {};