@gvnrdao/dh-sdk 0.0.166 → 0.0.205

package/dist/graphs/diamond-hands.d.ts

@@ -0,0 +1,248 @@
+import type { LoanData } from "../interfaces";
+import type { GraphPositionWithBorrowerDTO } from "../types/graph-dtos";
+import type { LoanEvents, LoanEventsFilter } from "../types/event-types";
+import type { BitcoinOperations, EnrichedBitcoinBalance } from "../modules/bitcoin/bitcoin-operations.module";
+export interface DiamondHandsGraphConfig {
+    endpoint: string;
+    requestTimeoutMs?: number;
+    maxRetries?: number;
+    defaultPageSize?: number;
+    headers?: Record<string, string>;
+}
+export interface UserData {
+    id: string;
+    positions: LoanData[];
+    totalBorrowed: string;
+    totalRepaid: string;
+    activePositions: string;
+    firstInteractionTimestamp: string;
+    lastInteractionTimestamp: string;
+}
+export interface LoanTermData {
+    id: string;
+    months: string;
+    mintFeeBps?: string;
+    extensionFeeBps?: string;
+    isValid?: boolean;
+    createdAt?: string;
+    createdAtBlock?: string;
+}
+export interface PSMConfigurationData {
+    id: string;
+    version: string;
+    redeemEnabled: boolean;
+    totalSwapVolume: string;
+    totalRedeemVolume: string;
+    supportedStablecoinsCount: string;
+    lastUpdated: string;
+}
+export interface SupportedStablecoinData {
+    id: string;
+    address: string;
+    isSupported: boolean;
+    exchangeRate: string;
+    entryFee: string;
+    exitFee: string;
+    reserves: string;
+    decimals: string;
+    totalSwapVolume: string;
+    totalRedeemVolume: string;
+    swapCount: string;
+    redeemCount: string;
+    addedAt: string;
+    lastUpdated: string;
+}
+export interface PSMTransactionData {
+    id: string;
+    type: string;
+    user: string;
+    stablecoin: SupportedStablecoinData;
+    stablecoinAmount: string;
+    ucdAmount: string;
+    fee: string;
+    effectiveRate: string;
+    timestamp: string;
+    blockNumber: string;
+    transactionHash: string;
+}
+export interface UserRateLimitData {
+    id: string;
+    user: string;
+    stablecoin: SupportedStablecoinData;
+    lastOperationBlock: string;
+    operationCount: string;
+    isCurrentlyLimited: boolean;
+    nextResetBlock: string;
+    lastUpdated: string;
+}
+export declare class DiamondHandsGraph {
+    private client;
+    private defaultPageSize;
+    private bitcoinOps?;
+    constructor(config: DiamondHandsGraphConfig, bitcoinOps?: BitcoinOperations);
+    /**
+     * Transform graph position data to LoanData interface
+     * Converts flat graph structure to nested LoanData structure
+     */
+    private transformGraphPositionToLoanData;
+    /**
+     * Helper: Get total count by paginating through all results
+     * The Graph has a hard limit of 1000 items per query, so we need to paginate
+     *
+     * NOTE: This implementation fetches minimal data (just IDs) for counting.
+     * The Graph protocol does not currently support count-only aggregation queries,
+     * so this batching approach is optimal for total count determination.
+     * Future optimization: If The Graph adds support for aggregate functions
+     * (e.g., `positions_aggregate { count }`), this should be updated.
+     *
+     * @param entityName The GraphQL entity name (e.g., "positions", "users")
+     * @param whereClause Optional GraphQL where clause (e.g., "{ borrower: $borrower }")
+     * @param variables Optional variables for the where clause
+     * @returns Total count of items
+     */
+    private getTotalCountPaginated;
+    /**
+     * Get user positions from subgraph
+     */
+    getUserPositions(userAddress: string, first?: number, skip?: number, orderBy?: string, orderDirection?: string): Promise<{
+        positions: LoanData[];
+        total: number;
+    }>;
+    /**
+     * Get user positions with enriched Bitcoin balance data
+     *
+     * Same as getUserPositions but queries actual BTC balance from Bitcoin network
+     * for each vault address in parallel.
+     *
+     * @param userAddress - User's Ethereum address
+     * @param first - Optional: max number of positions to return (default: 10)
+     * @param skip - Optional: number of positions to skip (default: 0)
+     * @param orderBy - Optional: field to order by (default: "createdAt")
+     * @param orderDirection - Optional: asc or desc (default: "desc" - most recent first)
+     * @returns Positions with actual BTC balances from Bitcoin network
+     */
+    getUserPositionsWithBtc(userAddress: string, first?: number, skip?: number, orderBy?: string, orderDirection?: "asc" | "desc"): Promise<{
+        positions: (LoanData & {
+            btcBalance?: EnrichedBitcoinBalance;
+        })[];
+        total: number;
+    }>;
+    /**
+     * Get position by PKP ID from subgraph
+     */
+    getPositionByPKP(pkpId: string): Promise<LoanData | null>;
+    /**
+     * Get detailed position data by PKP ID from subgraph
+     */
+    getDetailedPositionByPkpId(pkpId: string): Promise<any | null>;
+    /**
+     * Get detailed position data by position ID from subgraph
+     */
+    getDetailedPositionById(positionId: string): Promise<GraphPositionWithBorrowerDTO | null>;
+    /**
+     * Get all positions with pagination
+     */
+    getAllPositions(options?: {
+        pageSize?: number;
+        maxPages?: number;
+    }): Promise<LoanData[]>;
+    /**
+     * Get all positions directly (simple query with pagination support)
+     */
+    getPositions(first?: number, orderBy?: string, orderDirection?: "asc" | "desc", skip?: number, includeTotalCount?: boolean): Promise<{
+        positions: LoanData[];
+        total: number;
+    }>;
+    /**
+     * Get positions filtered by an array of statuses
+     */
+    getPositionsByStatus(statuses: string[], first?: number, orderBy?: string, orderDirection?: "asc" | "desc", skip?: number): Promise<{
+        positions: LoanData[];
+        total: number;
+    }>;
+    /**
+     * Get active positions only
+     */
+    getActivePositions(options?: {
+        pageSize?: number;
+        maxPages?: number;
+    }): Promise<LoanData[]>;
+    /**
+     * Get protocol statistics
+     */
+    getProtocolStats(): Promise<{
+        totalValueLocked: string;
+        totalBorrowed: string;
+        totalRepaid: string;
+        totalLiquidated: string;
+        totalPositions: string;
+        activePositions: string;
+        totalUsers: string;
+    } | null>;
+    /**
+     * Health check for subgraph
+     */
+    healthCheck(): Promise<{
+        isHealthy: boolean;
+        latestBlock?: string;
+    }>;
+    /**
+     * Get all configured loan terms (from subgraph)
+     * Note: If the subgraph does not seed default terms from the contract, this may return an empty array.
+     */
+    getLoanTerms(options?: {
+        first?: number;
+        skip?: number;
+    }): Promise<LoanTermData[]>;
+    /**
+     * Get a single loan term by months (from subgraph)
+     * Typical id is the months as string, e.g., "12".
+     */
+    getLoanTerm(months: number | string): Promise<LoanTermData | null>;
+    /**
+     * Get PSM configuration from subgraph
+     */
+    getPSMConfiguration(): Promise<PSMConfigurationData | null>;
+    /**
+     * Get all supported stablecoins from subgraph
+     */
+    getSupportedStablecoins(onlySupported?: boolean): Promise<SupportedStablecoinData[]>;
+    /**
+     * Get stablecoin details by address
+     */
+    getStablecoinDetails(address: string): Promise<SupportedStablecoinData | null>;
+    /**
+     * Get user rate limit status for a specific stablecoin
+     */
+    getUserRateLimit(userAddress: string, stablecoinAddress: string): Promise<UserRateLimitData | null>;
+    /**
+     * Get PSM transactions with filters
+     */
+    getPSMTransactions(filters?: {
+        user?: string;
+        stablecoin?: string;
+        type?: "SWAP" | "REDEEM";
+        first?: number;
+        skip?: number;
+    }): Promise<PSMTransactionData[]>;
+    /**
+     * Get PSM analytics for a date range
+     */
+    getPSMDailyMetrics(startDate?: string, endDate?: string, first?: number): Promise<any[]>;
+    /**
+     * Get all events for a specific loan position
+     *
+     * Returns a comprehensive 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 - The position ID to query events for
+     * @param filter - Optional filters to apply
+     * @returns Complete event history for the position
+     */
+    getLoanEvents(positionId: string, filter?: LoanEventsFilter): Promise<LoanEvents>;
+}
+export type DiamondHandsGraphClient = DiamondHandsGraph;