@gvnrdao/dh-sdk 0.0.166 → 0.0.205

package/dist/modules/loan/loan-creator.module.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Loan Creator Module
+ *
+ * Responsible for:
+ * - Orchestrating the multi-step loan creation flow
+ * - Creating PKP for custody
+ * - Authorizing loan creation
+ * - Submitting loan creation transaction
+ * - Building comprehensive audit trail
+ *
+ * Flow: PKP Creation → Authorization → Contract Call → Verification
+ */
+import type { Wallet } from "ethers";
+import { Result } from "../../types/result";
+import { SDKError } from "../../utils/error-handler";
+import type { PKPManager } from "../pkp/pkp-manager.module";
+import type { ContractManager } from "../contract/contract-manager.module";
+import type { BitcoinOperations } from "../bitcoin/bitcoin-operations.module";
+import type { CreateLoanRequest, CreateLoanResult } from "../../interfaces/chunks/loan-operations.i";
+import type { LitOps } from "@gvnrdao/dh-lit-ops";
+/**
+ * Loan Creator configuration
+ */
+export interface LoanCreatorConfig {
+    /** LitOps instance for PKP operations */
+    litOps: LitOps;
+    /** PKP Manager for PKP operations */
+    pkpManager: PKPManager;
+    /** Contract Manager for contract interactions */
+    contractManager: ContractManager;
+    /** Bitcoin Operations for address derivation */
+    bitcoinOperations: BitcoinOperations;
+    /** Wallet for contract transactions (Ethereum mainnet/Sepolia) */
+    wallet: Wallet;
+    /** Wallet for LIT Protocol operations (Yellowstone signer, capacity credits owner) - standalone mode only */
+    litOpsSigner?: Wallet;
+    /** SDK mode: 'service' or 'standalone' */
+    mode?: "service" | "standalone";
+    /** LIT Action CID for loan creation */
+    litActionCid: string;
+    /** User ID (typically wallet address) */
+    userId: string;
+    /** Lit Protocol network (e.g. 'chipotle') */
+    litNetwork?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Transaction timeout (ms) */
+    transactionTimeoutMs?: number;
+    /** Validator version for loan creation (createPosition) - REQUIRED */
+    loanCreationValidatorVersion: number;
+    /** EVM JSON-RPC URL for service-mode PKP flow (forwards to lit-ops-server) */
+    ethRpcUrl?: string;
+    /** Security testing: Temper signatures to test contract validation */
+    temperSignaturesTest?: boolean;
+    /**
+     * Optional: Custom PKP creator.
+     * When provided, bypasses the default LitOps PKP flow and creates the PKP using
+     * this function.
+     */
+    nagaLoanPkpCreator?: () => Promise<{
+        tokenId: string;
+        publicKey: string;
+        ethAddress: string;
+        validatorSignature: string;
+    }>;
+}
+/**
+ * Loan creation audit trail
+ */
+export interface LoanCreationAudit {
+    /** PKP creation details */
+    pkpCreation: {
+        tokenId: string;
+        publicKey: string;
+        ethAddress: string;
+        timestamp: number;
+    };
+    /** Bitcoin addresses derived */
+    bitcoinAddresses: {
+        mainnet: string;
+        testnet: string;
+        regtest: string;
+    };
+    /** Authorization details */
+    authorization: {
+        signature: string;
+        timestamp: number;
+    };
+    /** Contract call details */
+    contractCall: {
+        transactionHash: string;
+        blockNumber: number;
+        gasUsed: string;
+        timestamp: number;
+    };
+}
+/**
+ * Loan Creator Module
+ *
+ * Orchestrates the complete loan creation flow with comprehensive error handling
+ */
+export declare class LoanCreator {
+    private readonly config;
+    private readonly transactionTimeoutMs;
+    private pkpValidationRegistryAddressCache;
+    constructor(config: LoanCreatorConfig);
+    /**
+     * Create a new loan
+     *
+     * Complete flow:
+     * 1. Create PKP for Bitcoin custody
+     * 2. Derive Bitcoin addresses
+     * 3. Build authorization signature
+     * 4. Authorize loan creation (LIT Action)
+     * 5. Submit loan creation transaction
+     * 6. Wait for confirmation
+     * 7. Build audit trail
+     *
+     * @param request - Loan creation request
+     * @returns Loan creation result with audit trail
+     */
+    createLoan(request: CreateLoanRequest): Promise<Result<CreateLoanResult, SDKError>>;
+    /**
+     * Step 2: Derive Bitcoin addresses from PKP public key
+     */
+    private deriveBitcoinAddresses;
+    /**
+     * Step 3: Submit loan creation transaction
+     */
+    private submitLoanCreation;
+    /**
+     * Extract position ID from transaction receipt
+     */
+    private extractPositionId;
+    /**
+     * Get vault address for current network
+     */
+    private getVaultAddressForNetwork;
+}
+/**
+ * Factory function to create a LoanCreator instance
+ */
+export declare function createLoanCreator(config: LoanCreatorConfig): Result<LoanCreator, SDKError>;

package/dist/modules/loan/loan-query.module.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Loan Query Module
+ *
+ * Responsible for:
+ * - Querying loan data from subgraph
+ * - Enriching loans with Bitcoin balance data
+ * - Caching query results for performance
+ * - Supporting pagination for large result sets
+ *
+ * Uses the existing DiamondHandsGraphClient for subgraph queries
+ */
+import { Result } from "../../types/result";
+import { SDKError } from "../../utils/error-handler";
+import type { BitcoinOperations } from "../bitcoin/bitcoin-operations.module";
+import type { Cache } from "../cache/cache-manager.module";
+import type { LoanData, LoanDataDetail, PaginatedLoansResponse } from "../../interfaces/chunks/loan-operations.i";
+import type { LoanEvents, LoanEventsFilter } from "../../types/event-types";
+import { DiamondHandsGraphClient } from "@graphs/diamond-hands";
+import type { providers } from "ethers";
+/**
+ * Loan query filters
+ */
+export interface LoanQueryFilters {
+    /** Filter by borrower address */
+    borrower?: string;
+    /** Filter by status */
+    status?: number;
+    /** Filter by minimum collateral ratio (BPS) */
+    minCollateralRatio?: number;
+    /** Filter by maximum collateral ratio (BPS) */
+    maxCollateralRatio?: number;
+    /** Order by field */
+    orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt";
+    /** Order direction */
+    orderDirection?: "asc" | "desc";
+}
+/**
+ * Pagination parameters
+ */
+export interface PaginationParams {
+    /** Page number (0-indexed) */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+}
+/**
+ * Loan Query configuration
+ */
+export interface LoanQueryConfig {
+    /** Subgraph client for queries */
+    graphClient: DiamondHandsGraphClient;
+    /** Bitcoin operations for balance enrichment */
+    bitcoinOperations: BitcoinOperations;
+    /** Ethereum provider for PKP public key retrieval */
+    provider?: providers.Provider;
+    /** Cache for loan query results (keyed by PKP ID) */
+    cache?: Cache<LoanData>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Default page size for pagination */
+    defaultPageSize?: number;
+}
+/**
+ * Loan Query Module
+ *
+ * Handles all loan data queries with caching and balance enrichment
+ */
+export declare class LoanQuery {
+    private readonly config;
+    private readonly defaultPageSize;
+    constructor(config: LoanQueryConfig);
+    /**
+     * Get loan by position ID
+     *
+     * @param positionId - Position ID
+     * @param enrichBalance - Whether to enrich with Bitcoin balance
+     * @returns Detailed loan data
+     */
+    getLoanById(positionId: string, enrichBalance?: boolean): Promise<Result<LoanDataDetail | null, SDKError>>;
+    /**
+     * Get loan by PKP ID
+     *
+     * @param pkpId - PKP token ID
+     * @param enrichBalance - Whether to enrich with Bitcoin balance
+     * @returns Loan data
+     */
+    getLoanByPkpId(pkpId: string, enrichBalance?: boolean): Promise<Result<LoanData | null, SDKError>>;
+    /**
+     * Get loans with filters and pagination
+     *
+     * @param filters - Query filters
+     * @param pagination - Pagination parameters
+     * @returns Paginated loans response
+     */
+    getLoans(filters?: LoanQueryFilters, pagination?: PaginationParams): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    /**
+     * Get loans with BTC balance data from Bitcoin network
+     *
+     * Same as getLoans but includes actual Bitcoin balance for each position's vault.
+     * Queries BTC balances in parallel for performance.
+     *
+     * @param filters - Query filters
+     * @param pagination - Pagination parameters
+     * @returns Paginated loans response with BTC balance data
+     */
+    getLoansWithBtc(filters?: LoanQueryFilters, pagination?: PaginationParams): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    /**
+     * Enrich loans with vault addresses derived from PKP public keys
+     *
+     * @param loans - Array of loans to enrich
+     * @returns Enriched loans with vault addresses for all networks
+     */
+    private enrichLoansWithVaultAddresses;
+    /**
+     * Map numeric status to string for subgraph queries
+     */
+    private mapStatusToString;
+    /**
+     * Map string status to numeric for filtering
+     */
+    private mapStringToStatus;
+    /**
+     * Validate if a string is a valid loan status
+     */
+    private isValidStatus;
+    /**
+     * Get loans for a borrower
+     *
+     * @param borrower - Borrower address
+     * @param pagination - Pagination parameters
+     * @returns Paginated loans for borrower
+     */
+    getLoansByBorrower(borrower: string, pagination?: PaginationParams): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    /**
+     * Get active loans (status = 0)
+     *
+     * @param pagination - Pagination parameters
+     * @returns Paginated active loans
+     */
+    getActiveLoans(pagination?: PaginationParams): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    /**
+     * Get loans by state/status
+     *
+     * @param state - Loan state (PENDING_DEPOSIT, ACTIVE, EXPIRED, REPAID, LIQUIDATED, EXTENDED, CLOSED)
+     * @param pagination - Pagination parameters
+     * @returns Paginated loans matching the specified state
+     */
+    getLoansByState(state: string, pagination?: PaginationParams): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    /**
+     * Enrich a loan with current Bitcoin balance
+     *
+     * Note: btcAmount field removed - balance is now queried on-chain via lit-actions with signature validation
+     * This method is kept for potential future use but no longer sets btcAmount
+     */
+    private enrichLoanWithBalance;
+    /**
+     * Get all events for a loan position
+     *
+     * Retrieves complete event history including:
+     * - Payments (full repayments, partial payments, extension fees)
+     * - Status updates with reasons
+     * - Liquidation event (if liquidated)
+     * - UCD mint events
+     * - Community fee distributions
+     *
+     * @param positionId - Position ID to query events for
+     * @param filter - Optional filters (date range, event types, etc.)
+     * @returns Complete event history for the position
+     *
+     * @example
+     * ```typescript
+     * // Get all events
+     * const result = await loanQuery.getLoanEvents('0x123...');
+     *
+     * // Get only payment events
+     * const paymentsOnly = await loanQuery.getLoanEvents('0x123...', {
+     *   eventTypes: ['payment']
+     * });
+     *
+     * // Get events in date range
+     * const recent = await loanQuery.getLoanEvents('0x123...', {
+     *   fromTimestamp: '1640000000',
+     *   toTimestamp: '1650000000'
+     * });
+     * ```
+     */
+    getLoanEvents(positionId: string, filter?: LoanEventsFilter): Promise<Result<LoanEvents, SDKError>>;
+    /**
+     * Clear loan cache
+     *
+     * @param pkpId - PKP ID to clear, or undefined to clear all
+     */
+    clearCache(pkpId?: string): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | null;
+}
+/**
+ * Factory function to create a LoanQuery instance
+ */
+export declare function createLoanQuery(config: LoanQueryConfig): Result<LoanQuery, SDKError>;

package/dist/modules/mock/mock-token-manager.module.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Mock Token Manager Module
+ *
+ * Responsible for:
+ * - Managing mock Bitcoin tokens for testing
+ * - Minting mock BTC tokens
+ * - Approving mock BTC spending
+ * - Querying mock BTC balances
+ *
+ * This module is for testing only and should not be used in production
+ */
+import { Result } from '../../types/result';
+import { Satoshis } from '../../types/branded/domain-values';
+import { SDKError } from '../../utils/error-handler';
+import type { ContractManager } from '../contract/contract-manager.module';
+/**
+ * Mock Token Manager configuration
+ */
+export interface MockTokenManagerConfig {
+    /** Contract manager for accessing mock token contracts */
+    contractManager: ContractManager;
+    /** Network identifier */
+    network: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Transaction timeout (ms) */
+    transactionTimeoutMs?: number;
+}
+/**
+ * Mock token transaction result
+ */
+export interface MockTokenTransactionResult {
+    /** Transaction hash */
+    transactionHash: string;
+    /** Block number */
+    blockNumber: number;
+    /** Gas used */
+    gasUsed: string;
+    /** Transaction was successful */
+    success: boolean;
+}
+/**
+ * Mock Token Manager Module
+ *
+ * Provides utilities for working with mock Bitcoin tokens in test environments
+ *
+ * ⚠️ WARNING: This module is for testing only. Do not use in production.
+ */
+export declare class MockTokenManager {
+    private readonly config;
+    constructor(config: MockTokenManagerConfig);
+    /**
+     * Mint mock BTC tokens
+     *
+     * @param amount - Amount to mint in satoshis
+     * @param recipient - Recipient address
+     * @returns Transaction result
+     */
+    mintMockBTC(amount: Satoshis, recipient: string): Promise<Result<MockTokenTransactionResult, SDKError>>;
+    /**
+     * Approve mock BTC spending
+     *
+     * @param spender - Spender address
+     * @param amount - Amount to approve in satoshis
+     * @returns Transaction result
+     */
+    approveMockBTC(spender: string, amount: Satoshis): Promise<Result<MockTokenTransactionResult, SDKError>>;
+    /**
+     * Get mock BTC balance
+     *
+     * @param address - Address to query
+     * @returns Balance in satoshis
+     */
+    getMockBTCBalance(address: string): Promise<Result<Satoshis, SDKError>>;
+    /**
+     * Check if current network is production (mainnet)
+     */
+    private isProductionNetwork;
+}
+/**
+ * Factory function to create a MockTokenManager instance
+ */
+export declare function createMockTokenManager(config: MockTokenManagerConfig): Result<MockTokenManager, SDKError>;

package/dist/modules/pkp/pkp-manager.module.d.ts

@@ -0,0 +1,136 @@
+/**
+ * PKP Manager Module
+ *
+ * Responsible for:
+ * - Creating new PKPs (via service or direct)
+ * - Querying PKP data from contracts
+ * - Managing PKP lifecycle
+ * - Caching PKP data for performance
+ *
+ * Supports two modes:
+ * - Service mode: Uses lit-ops-server for PKP operations
+ * - Direct mode: Directly interacts with LIT Protocol
+ */
+import type { Wallet } from "ethers";
+import { Result } from "../../types/result";
+import { SDKError } from "../../utils/error-handler";
+import type { Cache } from "../cache/cache-manager.module";
+import type { PKPData, PKPCreationRequest, PKPCreationResult, PKPValidationResult } from "../../interfaces/chunks/pkp-integration.i";
+import type { SDKMode } from "../../interfaces/chunks/config.i";
+/**
+ * PKP Manager configuration
+ */
+export interface PKPManagerConfig {
+    /** Operation mode: service (via lit-ops-server) or direct (LIT Protocol) */
+    mode: SDKMode;
+    /** LIT network (naga, naga-test, naga-dev, etc.) */
+    litNetwork: string;
+    /** Service mode: endpoint for lit-ops-server */
+    serviceEndpoint?: string;
+    /** Service mode: authentication token */
+    serviceAuthToken?: string;
+    /** Direct mode: wallet for PKP operations */
+    litOpsWallet?: Wallet;
+    /** Optional cache for PKP data */
+    cache?: Cache<PKPData>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Timeout for service requests (ms) */
+    serviceTimeoutMs?: number;
+    /** Max retries for failed operations */
+    maxRetries?: number;
+}
+/**
+ * PKP Manager Module
+ *
+ * Manages PKP creation, querying, and lifecycle with support for
+ * both service mode and direct mode operations.
+ */
+export declare class PKPManager {
+    private readonly config;
+    private readonly serviceTimeoutMs;
+    constructor(config: PKPManagerConfig);
+    /**
+     * Validate PKPManager configuration
+     */
+    private validateConfig;
+    /**
+     * Create a new PKP
+     *
+     * Routes to service mode or direct mode based on configuration.
+     *
+     * @param request - PKP creation request
+     * @returns PKP creation result
+     */
+    createPKP(request: PKPCreationRequest): Promise<Result<PKPCreationResult, SDKError>>;
+    /**
+     * Create PKP via lit-ops-server (service mode)
+     */
+    private createPKPViaService;
+    /**
+     * Create PKP directly via LIT Protocol (standalone mode)
+     *
+     * Note: This is a placeholder implementation. In production, this would
+     * use the LIT SDK directly to mint a PKP.
+     */
+    private createPKPDirect;
+    /**
+     * Get PKP data by token ID
+     *
+     * Checks cache first, then queries from service/contract if needed.
+     *
+     * @param tokenId - PKP token ID
+     * @returns PKP data or null if not found
+     */
+    getPKPData(tokenId: string): Promise<Result<PKPData | null, SDKError>>;
+    /**
+     * Get PKP data from service
+     */
+    private getPKPDataFromService;
+    /**
+     * Get PKP data from contract (direct mode)
+     *
+     * Note: This is a placeholder. In production, would query PKP registry contract.
+     */
+    private getPKPDataFromContract;
+    /**
+     * Get PKP public key from token ID
+     *
+     * Convenience method that extracts just the public key.
+     *
+     * @param tokenId - PKP token ID
+     * @returns PKP public key
+     */
+    getPKPPublicKey(tokenId: string): Promise<Result<string, SDKError>>;
+    /**
+     * Validate that a PKP exists and is active
+     *
+     * @param tokenId - PKP token ID
+     * @returns Validation result
+     */
+    validatePKP(tokenId: string): Promise<Result<PKPValidationResult, SDKError>>;
+    /**
+     * Clear PKP from cache
+     *
+     * Useful when PKP data may have changed.
+     *
+     * @param tokenId - PKP token ID
+     */
+    clearCache(tokenId: string): void;
+    /**
+     * Clear all cached PKP data
+     */
+    clearAllCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | null;
+}
+/**
+ * Factory function to create a PKPManager instance
+ */
+export declare function createPKPManager(config: PKPManagerConfig): Result<PKPManager, SDKError>;

package/dist/protocol/protocol-pause.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Helpers for `PositionManager.getProtocolPauseStatus()` (Lit Actions / client fast-fail).
+ */
+import { ethers } from 'ethers';
+export type ProtocolPauseStatus = {
+    positionManagerPaused: boolean;
+    positionManagerLiquidationsPaused: boolean;
+    positionManagerCorePaused: boolean;
+    loanOperationsPaused: boolean;
+    collateralManagerPaused: boolean;
+    liquidationManagerPaused: boolean;
+    circuitBreakerPaused: boolean;
+    ucdControllerPaused: boolean;
+    ucdTokenPaused: boolean;
+    simplePsmPaused: boolean;
+};
+export declare function fetchProtocolPauseStatus(provider: ethers.providers.Provider, positionManagerAddress: string): Promise<ProtocolPauseStatus>;
+export type ProtocolPauseKey = keyof ProtocolPauseStatus;
+export declare function assertProtocolNotPaused(status: ProtocolPauseStatus, requiredKeys: readonly ProtocolPauseKey[]): void;

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Node-only entry for the Diamond Hands SDK (PKP mint / server env).
+ *
+ * Use this subpath when you need {@link loadSDKConfig} with `.env` discovery
+ * (`environment.ts`) and optional `PKP_MINT_PRIVATE_KEY` for mint-wallet flows.
+ *
+ * The main package export (`@gvnrdao/dh-sdk`) re-exports browser-safe config from
+ * `environment.browser` — suitable for read-only and user-wallet flows in any runtime.
+ * Do **not** put `PKP_MINT_PRIVATE_KEY` in client bundles; import from here only in Node
+ * scripts, lit-ops-server, CI, or other trusted server contexts.
+ *
+ * @see {@link https://github.com/gvnrdao/diamond-hands/blob/main/docs/security/SECRETS-POLICY.md | SECRETS-POLICY.md}
+ * @module @gvnrdao/dh-sdk/server
+ */
+export { loadSDKConfig, validateSDKEnvironment, getCurrentEnvironment, resolveLitNetworkFromEnv, envLog, } from "./constants/chunks/environment";
+export { loadEncryptedProviderRegistry, getEncryptedPriceProviders, } from "./constants/chunks/encrypted-provider-params";
+export type { SDKConfig, EnvironmentName } from "./constants/chunks/environment";