@gvnrdao/dh-sdk 0.0.166 → 0.0.205

package/dist/types/branded/domain-values.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Branded types for domain-specific values to prevent mixing incompatible units
+ *
+ * These types provide compile-time safety to ensure we don't accidentally
+ * use Bitcoin satoshis where UCD is expected, or vice versa.
+ *
+ * @example
+ * ```typescript
+ * const debt: UCD = UCD(1000000n);
+ * const balance: Satoshis = Satoshis(50000000n);
+ *
+ * // This will cause a TypeScript error:
+ * await mintUCD(balance); // Error: Cannot use Satoshis where UCD expected
+ * ```
+ */
+declare const __brand: unique symbol;
+/**
+ * UCD (USD Coin Diamond) - The stablecoin minted against Bitcoin collateral
+ * Base unit: 1 UCD = 10^18 wei (matches ERC20 decimals)
+ */
+export type UCD = bigint & {
+    readonly [__brand]: 'UCD';
+};
+/**
+ * Satoshis - Bitcoin base unit
+ * Base unit: 1 BTC = 100,000,000 satoshis
+ */
+export type Satoshis = bigint & {
+    readonly [__brand]: 'Satoshis';
+};
+/**
+ * Wei - Ethereum base unit for ETH and ERC20 tokens (18 decimals)
+ * Base unit: 1 token = 10^18 wei
+ */
+export type Wei = bigint & {
+    readonly [__brand]: 'Wei';
+};
+/**
+ * BPS - Basis Points for percentage calculations
+ * Base unit: 1% = 100 BPS, 100% = 10,000 BPS
+ */
+export type BPS = number & {
+    readonly [__brand]: 'BPS';
+};
+/**
+ * UnixTimestamp - Unix timestamp in seconds
+ */
+export type UnixTimestamp = number & {
+    readonly [__brand]: 'UnixTimestamp';
+};
+/**
+ * BlockNumber - Ethereum block number
+ */
+export type BlockNumber = number & {
+    readonly [__brand]: 'BlockNumber';
+};
+export declare const UCD: (value: bigint) => UCD;
+export declare const Satoshis: (value: bigint) => Satoshis;
+export declare const Wei: (value: bigint) => Wei;
+export declare const BPS: (value: number) => BPS;
+export declare const UnixTimestamp: (value: number) => UnixTimestamp;
+export declare const BlockNumber: (value: number) => BlockNumber;
+export declare function isUCD(value: unknown): value is UCD;
+export declare function isSatoshis(value: unknown): value is Satoshis;
+export declare function isWei(value: unknown): value is Wei;
+export declare function isBPS(value: unknown): value is BPS;
+export declare function isUnixTimestamp(value: unknown): value is UnixTimestamp;
+export declare function isBlockNumber(value: unknown): value is BlockNumber;
+export declare namespace UCDConversions {
+    function fromWhole(whole: number | string): UCD;
+    function toWhole(ucd: UCD): number;
+    function format(ucd: UCD, decimals?: number): string;
+    /**
+     * Convert UCD to JSON-serializable string
+     */
+    function toJSON(ucd: UCD): string;
+    /**
+     * Parse UCD from JSON string
+     */
+    function fromJSON(json: string): UCD;
+    /**
+     * Convert to structured serializable format with metadata
+     */
+    function toSerializable(ucd: UCD): {
+        value: string;
+        decimals: number;
+        type: 'UCD';
+    };
+}
+export declare namespace SatoshisConversions {
+    function fromBTC(btc: number | string): Satoshis;
+    function toBTC(satoshis: Satoshis): number;
+    function format(satoshis: Satoshis, unit?: 'BTC' | 'sats'): string;
+    /**
+     * Convert Satoshis to JSON-serializable string
+     */
+    function toJSON(satoshis: Satoshis): string;
+    /**
+     * Parse Satoshis from JSON string
+     */
+    function fromJSON(json: string): Satoshis;
+    /**
+     * Convert to structured serializable format with metadata
+     */
+    function toSerializable(satoshis: Satoshis): {
+        value: string;
+        unit: 'satoshis';
+        type: 'Satoshis';
+    };
+}
+export declare namespace WeiConversions {
+    function fromWhole(whole: number | string): Wei;
+    function toWhole(wei: Wei): number;
+    function format(wei: Wei, decimals?: number): string;
+    /**
+     * Convert Wei to JSON-serializable string
+     */
+    function toJSON(wei: Wei): string;
+    /**
+     * Parse Wei from JSON string
+     */
+    function fromJSON(json: string): Wei;
+    /**
+     * Convert to structured serializable format with metadata
+     */
+    function toSerializable(wei: Wei): {
+        value: string;
+        decimals: number;
+        type: 'Wei';
+    };
+}
+export declare namespace BPSConversions {
+    function fromPercent(percent: number): BPS;
+    function toPercent(bps: BPS): number;
+    function toDecimal(bps: BPS): number;
+    function format(bps: BPS): string;
+}
+export {};

package/dist/types/branded/ids.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Branded identifier types for PKP and Position IDs.
+ *
+ * These provide lightweight nominal typing so that internal helpers can
+ * distinguish between generic strings and protocol identifiers, while
+ * still being freely assignable to `string` where needed.
+ */
+declare const __idBrand: unique symbol;
+/**
+ * PKP token identifier (decimal string or hex string, depending on context).
+ */
+export type PkpId = string & {
+    readonly [__idBrand]: "PkpId";
+};
+/**
+ * Position identifier (on-chain bytes32, represented as hex string in SDK).
+ */
+export type PositionId = string & {
+    readonly [__idBrand]: "PositionId";
+};
+export declare const PkpId: (value: string) => PkpId;
+export declare const PositionId: (value: string) => PositionId;
+export {};

package/dist/types/event-types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Loan Event Types
+ *
+ * Type definitions for all loan-related events tracked by the Diamond Hands Protocol.
+ * These events are indexed by The Graph subgraph and can be queried via the SDK.
+ */
+/**
+ * Payment event type enum
+ */
+export declare enum PaymentType {
+    FULL_REPAYMENT = "FULL_REPAYMENT",
+    PARTIAL_PAYMENT = "PARTIAL_PAYMENT",
+    EXTENSION_FEE = "EXTENSION_FEE"
+}
+/**
+ * Position status enum
+ */
+export declare enum PositionStatus {
+    PENDING_DEPOSIT = "PENDING_DEPOSIT",
+    ACTIVE = "ACTIVE",
+    EXPIRED = "EXPIRED",
+    LIQUIDATED = "LIQUIDATED",
+    REPAID = "REPAID",
+    CLOSED = "CLOSED"
+}
+/**
+ * Payment event - tracks all payment activities for a position
+ */
+export interface PaymentEvent {
+    /** Unique event ID (transaction hash + log index) */
+    id: string;
+    /** Position ID this payment belongs to */
+    positionId: string;
+    /** Address of the payer */
+    payer: string;
+    /** Payment amount in UCD (wei) */
+    amount: string;
+    /** Type of payment */
+    type: PaymentType;
+    /** Transaction hash */
+    transactionHash: string;
+    /** Block timestamp */
+    timestamp: string;
+    /** Block number */
+    blockNumber: string;
+    /** Log index in the transaction */
+    logIndex: string;
+    /** Position debt after payment */
+    newDebt: string;
+    /** Position collateral ratio after payment (basis points) */
+    newCollateralRatio: string;
+}
+/**
+ * Status update event - tracks position status changes
+ */
+export interface StatusUpdateEvent {
+    /** Unique event ID (transaction hash + log index) */
+    id: string;
+    /** Position ID */
+    positionId: string;
+    /** Previous status */
+    oldStatus: PositionStatus;
+    /** New status */
+    newStatus: PositionStatus;
+    /** Reason for status change (optional) */
+    reason?: string;
+    /** Block timestamp */
+    timestamp: string;
+    /** Block number */
+    blockNumber: string;
+    /** Transaction hash */
+    transactionHash: string;
+}
+/**
+ * Liquidation event - tracks position liquidations
+ */
+export interface LiquidationEvent {
+    /** Unique event ID (transaction hash) */
+    id: string;
+    /** Position ID that was liquidated */
+    positionId: string;
+    /** Address of the liquidator */
+    liquidator: string;
+    /** Amount of debt liquidated (UCD wei) */
+    liquidatedAmount: string;
+    /** Amount of collateral seized (satoshis) */
+    collateralSeized: string;
+    /** Transaction hash */
+    transactionHash: string;
+    /** Block timestamp */
+    timestamp: string;
+    /** Block number */
+    blockNumber: string;
+    /** MEV protection: commit hash (if used) */
+    commitHash?: string;
+    /** MEV protection: commit timestamp (if used) */
+    commitTimestamp?: string;
+    /** MEV protection: reveal delay in seconds (if used) */
+    revealDelay?: string;
+}
+/**
+ * UCD mint event - tracks UCD minting for positions
+ */
+export interface UCDMintEvent {
+    /** Unique event ID (transaction hash + log index) */
+    id: string;
+    /** Position ID */
+    positionId: string;
+    /** Amount of UCD minted (wei) */
+    amount: string;
+    /** Proof bytes (for verification) */
+    proof: string;
+    /** Address that performed the mint */
+    minter: string;
+    /** Whether this was a community mint */
+    isCommunityMint: boolean;
+    /** Block timestamp */
+    timestamp: string;
+    /** Block number */
+    blockNumber: string;
+    /** Transaction hash */
+    transactionHash: string;
+}
+/**
+ * Community fee distribution event
+ */
+export interface FeeDistributionEvent {
+    /** Unique event ID (transaction hash + log index) */
+    id: string;
+    /** Position ID */
+    positionId: string;
+    /** Recipient address */
+    recipient: string;
+    /** Fee amount (UCD wei) */
+    amount: string;
+    /** Type of fee (e.g., "community", "extension") */
+    feeType: string;
+    /** Block timestamp */
+    timestamp: string;
+    /** Block number */
+    blockNumber: string;
+    /** Transaction hash */
+    transactionHash: string;
+}
+/**
+ * Aggregate container for all loan events
+ */
+export interface LoanEvents {
+    /** Position ID these events belong to */
+    positionId: string;
+    /** All payment events */
+    payments: PaymentEvent[];
+    /** All status update events */
+    statusUpdates: StatusUpdateEvent[];
+    /** Liquidation event (if position was liquidated) */
+    liquidation?: LiquidationEvent;
+    /** All UCD mint events */
+    mints: UCDMintEvent[];
+    /** All community fee distribution events */
+    feeDistributions: FeeDistributionEvent[];
+    /** Total number of events */
+    totalEvents: number;
+}
+/**
+ * Options for filtering loan events
+ */
+export interface LoanEventsFilter {
+    /** Filter by event types */
+    eventTypes?: Array<'payment' | 'status' | 'liquidation' | 'mint' | 'fee'>;
+    /** Filter by minimum timestamp */
+    fromTimestamp?: string;
+    /** Filter by maximum timestamp */
+    toTimestamp?: string;
+    /** Filter by minimum block number */
+    fromBlock?: string;
+    /** Filter by maximum block number */
+    toBlock?: string;
+    /** Limit number of events per type */
+    limit?: number;
+    /** Order direction */
+    orderDirection?: 'asc' | 'desc';
+}
+/**
+ * Type guard to check if status is valid
+ */
+export declare function isValidPositionStatus(status: string): status is PositionStatus;
+/**
+ * Type guard to check if payment type is valid
+ */
+export declare function isValidPaymentType(type: string): type is PaymentType;
+/**
+ * Convert numeric status to enum
+ */
+export declare function numericToPositionStatus(status: number): PositionStatus;
+/**
+ * Event helper functions
+ */
+export declare const EventHelpers: {
+    /**
+     * Sort events by timestamp (descending by default)
+     */
+    sortByTimestamp<T extends {
+        timestamp: string;
+    }>(events: T[], direction?: "asc" | "desc"): T[];
+    /**
+     * Filter events by timestamp range
+     */
+    filterByTimestamp<T extends {
+        timestamp: string;
+    }>(events: T[], fromTimestamp?: string, toTimestamp?: string): T[];
+    /**
+     * Filter events by block range
+     */
+    filterByBlock<T extends {
+        blockNumber: string;
+    }>(events: T[], fromBlock?: string, toBlock?: string): T[];
+    /**
+     * Get total count of all events
+     */
+    getTotalCount(events: LoanEvents): number;
+    /**
+     * Merge and sort all events by timestamp
+     */
+    getAllEventsSorted(events: LoanEvents, direction?: "asc" | "desc"): Array<(PaymentEvent & {
+        eventType: "payment";
+    }) | (StatusUpdateEvent & {
+        eventType: "status";
+    }) | (LiquidationEvent & {
+        eventType: "liquidation";
+    }) | (UCDMintEvent & {
+        eventType: "mint";
+    }) | (FeeDistributionEvent & {
+        eventType: "fee";
+    })>;
+};

package/dist/types/graph-dtos.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Graph Data Transfer Objects (DTOs)
+ * Strictly typed interfaces for GraphQL responses to replace any types
+ */
+export type BigIntString = string;
+export type TimestampString = string;
+export type AddressString = string;
+export interface GraphPositionDTO {
+    id: string;
+    pkpId: string;
+    borrower: string;
+    createdAt: TimestampString;
+    lastUpdated: TimestampString;
+    vaultAddress: string;
+    ucdMinted?: BigIntString;
+    ucdPaid?: BigIntString;
+    ucdDebt: BigIntString;
+    selectedTerm: string;
+    status: string;
+    expiryAt: TimestampString;
+    createdAtBlock?: string;
+    lastUpdatedAt?: TimestampString;
+    loanTerm?: {
+        id: string;
+        months: string;
+        extensionFeeRate: string;
+        extensionFeeUCD: string;
+        totalExtensions: string;
+        createdAt: string;
+    };
+    extensionFeesPaid?: string;
+    totalExtensions?: string;
+    payments?: Array<{
+        id: string;
+        amount: number;
+        blockNumber: number;
+        newCollateralRatio: number;
+        newDebt: number;
+        payer: {
+            id: string;
+        };
+        createdAt: number;
+        transactionHash: string;
+        type: string;
+    }>;
+    totalPaid?: string;
+    liquidation?: {
+        id: string;
+        liquidatedAt: string;
+        liquidatedBy: string;
+        reason: string;
+        collateralRecovered: string;
+        debtRecovered: string;
+        liquidationFee: string;
+        blockNumber: number;
+        collateralSeized: string;
+        commitHash: string;
+        commitTimestamp: string;
+        liquidatedAmount: string;
+        liquidator: string;
+        revealDelay: string;
+        timestamp: string;
+        transactionHash: string;
+    };
+}
+export interface GraphBorrowerDTO {
+    id: string;
+    createdAt: TimestampString;
+}
+export interface GraphPositionWithBorrowerDTO extends Omit<GraphPositionDTO, 'borrower'> {
+    borrower: GraphBorrowerDTO;
+}
+export interface GraphUserDataDTO {
+    id: string;
+    positions: GraphPositionDTO[];
+    totalBorrowed: BigIntString;
+    totalRepaid: BigIntString;
+    activePositions: string;
+    firstInteractionTimestamp: TimestampString;
+    lastInteractionTimestamp: TimestampString;
+}
+export interface GraphLoanTermDTO {
+    id: string;
+    months: string;
+    mintFeeBps?: string;
+    extensionFeeBps?: string;
+    isValid?: boolean;
+    createdAt?: TimestampString;
+    createdAtBlock?: string;
+}
+export interface GraphPSMConfigurationDTO {
+    id: string;
+    version: string;
+    redeemEnabled: boolean;
+    totalSwapVolume: BigIntString;
+    totalRedeemVolume: BigIntString;
+    supportedStablecoinsCount: string;
+    lastUpdated: TimestampString;
+}
+export interface GraphSupportedStablecoinDTO {
+    id: string;
+    address: AddressString;
+    isSupported: boolean;
+    exchangeRate: BigIntString;
+    entryFee: BigIntString;
+    exitFee: BigIntString;
+    reserves: BigIntString;
+    totalSupply: BigIntString;
+    lastUpdated: TimestampString;
+}
+export interface GraphPSMDailyMetricsDTO {
+    id: string;
+    date: string;
+    totalSwapVolume: BigIntString;
+    totalRedeemVolume: BigIntString;
+    averageExchangeRate: BigIntString;
+    uniqueUsers: string;
+    transactionCount: string;
+}
+export interface GraphTokenDTO {
+    id: string;
+    address: AddressString;
+    name: string;
+    symbol: string;
+    decimals: string;
+    totalSupply: BigIntString;
+    createdAtTimestamp: TimestampString;
+    createdAtBlock: string;
+}
+export interface GraphAccountDTO {
+    id: string;
+    address: AddressString;
+    balance: BigIntString;
+    token: string;
+    createdAtTimestamp: TimestampString;
+    createdAtBlock: string;
+}
+export interface GraphMetaDTO {
+    block: {
+        number: string;
+        hash: string;
+        timestamp: string;
+    };
+    deployment: {
+        network: string;
+        chainId: string;
+        subgraphName: string;
+        version: string;
+    };
+}
+export interface GraphPaginationDTO {
+    first: number;
+    skip: number;
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+}
+export interface GraphPaginatedResponseDTO<T> {
+    data: T[];
+    total: number;
+    page: number;
+    hasMore: boolean;
+}
+export interface GraphPositionsResponseDTO {
+    positions: GraphPositionWithBorrowerDTO[];
+    _meta: GraphMetaDTO;
+}
+export interface GraphUserPositionsResponseDTO {
+    positions: GraphPositionDTO[];
+    total: number;
+}
+export interface GraphPositionsByStatusResponseDTO {
+    positions: GraphPositionDTO[];
+    total: number;
+}
+export interface GraphPSMDailyMetricsResponseDTO {
+    psmDailyMetrics: GraphPSMDailyMetricsDTO[];
+}
+export interface GraphTokensResponseDTO {
+    tokens: GraphTokenDTO[];
+}
+export interface GraphTokenResponseDTO {
+    token: GraphTokenDTO;
+}
+export interface GraphAccountResponseDTO {
+    account: GraphAccountDTO;
+}
+export interface GraphAccountsResponseDTO {
+    accounts: GraphAccountDTO[];
+}
+export interface GraphPositionFilterDTO {
+    borrower?: string;
+    status?: string;
+    pkpId?: string;
+    createdAt_gte?: TimestampString;
+    createdAt_lte?: TimestampString;
+}
+export interface GraphAccountFilterDTO {
+    token?: string;
+    minBalance?: BigIntString;
+    address?: AddressString;
+}
+export interface GraphHealthCheckDTO {
+    _meta: GraphMetaDTO;
+    positionsCount: number;
+    lastIndexedBlock: string;
+    isHealthy: boolean;
+}
+export interface GraphErrorDTO {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: string[];
+    extensions?: {
+        code: string;
+        exception?: {
+            stacktrace: string[];
+        };
+    };
+}
+export interface GraphResponseDTO<T> {
+    data?: T;
+    errors?: GraphErrorDTO[];
+    extensions?: {
+        [key: string]: any;
+    };
+}

package/dist/types/loanStatus.d.ts

@@ -0,0 +1,10 @@
+export declare enum LoanStatus {
+    PENDING_DEPOSIT = 0,
+    PENDING_MINT = 1,
+    ACTIVE = 2,
+    EXPIRED = 3,
+    LIQUIDATABLE = 4,
+    LIQUIDATED = 5,
+    REPAID = 6,
+    CLOSED = 7
+}