@gvnrdao/dh-sdk 0.0.166 → 0.0.205

package/dist/interfaces/chunks/lit-actions.i.d.ts

@@ -0,0 +1,98 @@
+/**
+ * LIT Action Types and Interfaces (SDK boundary)
+ *
+ * This file provides the strongly-typed SDK view of LIT Actions and
+ * re-exports the action registry interfaces from the @gvnrdao/dh-lit-actions
+ * package so that action names and configs stay in sync across packages.
+ */
+import type { DiamondHandsLitActions, LitActionName } from "@gvnrdao/dh-lit-actions";
+import type { UcdMintValidatorResult, BtcWithdrawalValidatorResult, LiquidationValidatorResult, ExtendPositionValidatorResult, ProcessPaymentValidatorResult, LoanVaultBtcBalanceValidatorResult } from "./lit-actions-results.i";
+/**
+ * Re-export registry types so SDK consumers can use the same action name space.
+ */
+export type { DiamondHandsLitActions, LitActionName };
+/**
+ * Core LIT Action execution description.
+ *
+ * TParams describes the jsParams structure, TAuth describes the authSig shape.
+ * Both default to safe, unknown-based records instead of `any`.
+ */
+export interface ILitAction<TParams extends Record<string, unknown> = Record<string, unknown>, TAuth = LitActionAuth> {
+    code: string;
+    ipfsId?: string;
+    jsParams: TParams;
+    authSig: TAuth;
+}
+/**
+ * Parameters passed to lit-node-client.executeJs.
+ *
+ * This mirrors ILitAction but is named for historic reasons.
+ */
+export interface LitActionParams<TParams extends Record<string, unknown> = Record<string, unknown>, TAuth = LitActionAuth> {
+    code: string;
+    jsParams: TParams;
+    authSig: TAuth;
+    debug?: boolean;
+    pkpId?: string;
+    userAddress?: string;
+    /**
+     * Collateral amount used by some actions (e.g. mint flows).
+     * Replaces legacy btcAmount naming.
+     */
+    collateralAmount?: string;
+}
+/**
+ * Raw result returned from LIT Action execution.
+ *
+ * Callers are encouraged to wrap this in action-specific result
+ * types instead of accessing the generic `data` bag directly.
+ */
+export interface LitActionResult<TData = unknown> {
+    success: boolean;
+    signedData?: unknown;
+    decryptedData?: unknown;
+    claimedKeyId?: string;
+    signatures?: unknown;
+    /**
+     * Alias for signatures used by some helpers.
+     */
+    signature?: string;
+    decryptions?: unknown;
+    claims?: unknown;
+    response?: string;
+    logs?: string;
+    /**
+     * Action-specific payload. Prefer narrowing this via generics.
+     */
+    data?: TData;
+    /**
+     * Human-readable error (if any).
+     */
+    error?: string;
+}
+/**
+ * Discriminated union of typed results for the core Diamond Hands actions.
+ *
+ * This can be used by higher-level SDK helpers to express that a given
+ * execution is expected to return a particular validator payload.
+ */
+export type DiamondHandsLitActionResult = LitActionResult<UcdMintValidatorResult> | LitActionResult<BtcWithdrawalValidatorResult> | LitActionResult<LiquidationValidatorResult> | LitActionResult<ExtendPositionValidatorResult> | LitActionResult<ProcessPaymentValidatorResult> | LitActionResult<LoanVaultBtcBalanceValidatorResult>;
+/**
+ * Standard EIP-191 style authorization signature used by LIT.
+ */
+export interface LitActionAuth {
+    sig: string;
+    derivedVia: string;
+    signedMessage: string;
+    address: string;
+}
+/**
+ * Generic validation result used by some helper actions.
+ *
+ * Callers should prefer action-specific result types where available.
+ */
+export interface LitActionValidationResult<TDetails = unknown> {
+    valid: boolean;
+    error?: string;
+    details?: TDetails;
+}

package/dist/interfaces/chunks/loan-operations.i.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Loan Operations Interfaces
+ */
+import { LoanStatus } from "../../types/loanStatus";
+export type BitcoinAddresses = {
+    mainnet: string;
+    testnet: string;
+    regtest: string;
+};
+/**
+ * Create Loan Request Interface
+ */
+export interface CreateLoanRequest {
+    selectedTerm: number;
+}
+/**
+ * PKP Validation Data Interface
+ */
+export interface PKPValidationData {
+    tokenId: string;
+    publicKey: string;
+    ethAddress: string;
+    validationSignature: string;
+    btcAddresses: {
+        mainnet: string;
+        testnet: string;
+        regtest: string;
+    };
+}
+/**
+ * Create Loan Result Interface
+ */
+export interface CreateLoanResult {
+    success: boolean;
+    error?: string;
+    transactionHash?: string;
+    positionId?: string;
+    pkpData?: PKPValidationData;
+    vaultAddress?: string;
+    auditTrail?: {
+        pkpCreation: any;
+        validation: any;
+        contractCall: any;
+    };
+}
+/**
+ * Loan Data Interface (Graph/SDK simplified shape)
+ */
+export interface LoanData {
+    id: string;
+    pkpId: string;
+    borrower: {
+        createdAt: number;
+        id: string;
+    };
+    createdAt: number;
+    lastUpdatedAt: number;
+    loan: {
+        ucdMinted: number;
+        ucdPaid: number;
+        ucdDebt: number;
+        selectedTerm: number;
+        status: LoanStatus;
+        expiryAt: number;
+    };
+    collateral: {
+        vaultAddress: string | BitcoinAddresses;
+    };
+}
+/**
+ * Paginated Loans Response Interface
+ * Used by loan query methods that support pagination
+ */
+export interface PaginatedLoansResponse {
+    loans: LoanData[];
+    page: number;
+    maxRows: number;
+    totalLoans: number;
+}
+/**
+ * Detailed Loan Data Interface (used by getLoanById / PKP)
+ */
+export interface LoanDataDetail {
+    id: string;
+    pkpId: string;
+    borrower: {
+        id: string;
+        createdAt: number;
+    };
+    createdAt: number;
+    createdAtBlock: number;
+    lastUpdatedAt: number;
+    lastUpdatedAtBlock: number;
+    expiryAt: number;
+    loan: {
+        ucdMinted: number;
+        ucdPaid: number;
+        ucdDebt: number;
+        status: LoanStatus;
+        expiryAt: number;
+        currentTerm: {
+            id: string;
+            createdAt: number;
+            selectedTerm: number;
+            extensionFeeRate: number;
+            extensionFeeUCD: number;
+        };
+        extensions: {
+            extendedAt: number;
+            expiredAt: number;
+            term: number;
+            extensionFeeRate: number;
+            extensionFeeUCD: number;
+        };
+        totalExtensions: number;
+        payments: Array<{
+            amount: number;
+            blockNumber: number;
+            id: string;
+            newCollateralRatio: number;
+            newDebt: number;
+            payer: {
+                id: string;
+            };
+            createdAt: number;
+            transactionHash: string;
+            type: string;
+        }>;
+        totalPayments: number;
+        totalPaid: number;
+    };
+    collateral: {
+        vaultAddress: string | BitcoinAddresses;
+    };
+    liquidation: {
+        blockNumber: number;
+        collateralSeized: number;
+        commitHash: string;
+        commitTimestamp: string;
+        id: string;
+        liquidatedAmount: number;
+        liquidator: string;
+        revealDelay: string;
+        timestamp: number;
+        transactionHash: string;
+    };
+}
+/**
+ * Loans Query Interface
+ */
+export interface LoansQuery {
+    ownerWalletAddress?: string;
+    status?: LoanStatus;
+    expiryRange?: {
+        from: number;
+        to: number;
+    };
+    creationRange?: {
+        from: number;
+        to: number;
+    };
+}
+/**
+ * UCD Mint Request Interface
+ */
+export interface UCDMintRequest {
+    positionId: string;
+    amount: number;
+    selectedTerm?: number;
+    skipValidation?: boolean;
+    rpcUrl?: string;
+    customBitcoinRpcUrl?: string;
+    testBtcPrice?: number;
+    debugOverrides?: {
+        useStubbedBtcData?: boolean;
+        stubbedBtcPriceUsd?: string;
+        stubbedAvailableBtcSats?: string;
+        stubbedAuthorizedSpendsHash?: string;
+    };
+}
+/**
+ * UCD Mint Result Interface
+ */
+export interface UCDMintResult {
+    success: boolean;
+    transactionHash?: string;
+    blockNumber?: number;
+    blockHash?: string;
+    gasUsed?: string;
+    effectiveGasPrice?: string;
+    positionId?: string;
+    amountMinted?: string;
+    amountMintedUCD?: number;
+    error?: string;
+}
+/**
+ * Renew Position Result Interface
+ */
+export interface RenewPositionResult {
+    success: boolean;
+    transactionHash?: string;
+    blockNumber?: number;
+    blockHash?: string;
+    gasUsed?: string;
+    effectiveGasPrice?: string;
+    positionId?: string;
+    extensionTerm?: number;
+    newExpiryAt?: number;
+    error?: string;
+}
+/**
+ * Renew Position Request Interface
+ */
+export interface RenewPositionRequest {
+    positionId: string;
+    selectedTerm: number;
+}
+/**
+ * BTC Withdrawal Result Interface
+ */
+export interface BTCWithdrawalResult {
+    success: boolean;
+    evmTransactionHash?: string;
+    blockNumber?: number;
+    blockHash?: string;
+    gasUsed?: string;
+    effectiveGasPrice?: string;
+    positionId?: string;
+    withdrawalAddress?: string;
+    networkFee?: number;
+    amountWithdrawn?: string;
+    bitcoinTransactionHash?: string;
+    utxoTxid?: string;
+    utxoVout?: number;
+    error?: string;
+}
+/**
+ * Liquidation Request Interface
+ */
+export interface LiquidationRequest {
+    positionId: string;
+    forceContractCall?: boolean;
+    /**
+     * When true, the SDK will not send a UCD `approve(UCDController, …)` transaction.
+     * Use when the liquidator wallet has already approved UCDController (e.g. multisig flow).
+     * If allowance is insufficient, liquidation returns an error instead of approving.
+     */
+    skipUcdApproval?: boolean;
+    rpcUrl?: string;
+    customBitcoinRpcUrl?: string;
+}
+/**
+ * Liquidation Result Interface
+ */
+export interface LiquidationResult {
+    success: boolean;
+    error?: string;
+    transactionHash?: string;
+    blockNumber?: number;
+    positionId?: string;
+    debtAmount?: string;
+    collateralAmount?: string;
+    wasLiquidated?: boolean;
+    notLiquidatedReason?: string;
+    btcPrice?: string;
+    btcVaultBalance?: string;
+}
+/**
+ * Partial Payment Request Interface
+ */
+export interface PartialPaymentRequest {
+    positionId: string;
+    paymentAmount: number;
+    rpcUrl?: string;
+    customBitcoinRpcUrl?: string;
+}
+/**
+ * Confirm Balance Result Interface
+ */
+export interface ConfirmBalanceResult {
+    success: boolean;
+    transactionHash?: string;
+    blockNumber?: number;
+    blockHash?: string;
+    gasUsed?: string;
+    effectiveGasPrice?: string;
+    positionId?: string;
+    confirmedBalance?: string;
+    btcPrice?: string;
+    newStatus?: LoanStatus;
+    error?: string;
+}
+/**
+ * Confirm Balance Request Interface
+ */
+export interface ConfirmBalanceRequest {
+    positionId: string;
+}
+/**
+ * Partial Payment Result Interface
+ */
+export interface PartialPaymentResult {
+    success: boolean;
+    transactionHash?: string;
+    blockNumber?: number;
+    blockHash?: string;
+    gasUsed?: string;
+    effectiveGasPrice?: string;
+    positionId?: string;
+    paymentAmountUCD?: number;
+    error?: string;
+}
+/**
+ * Term with Fees Interface
+ */
+export interface TermWithFees {
+    termMonths: number;
+    originationFeeBps: number;
+    extensionFeeBps: number;
+}
+/**
+ * Terms with Fees Result Interface
+ */
+export interface TermsWithFeesResult {
+    terms: TermWithFees[];
+}
+/**
+ * Configuration for Loan Operations Manager
+ */
+export interface LoanManagerConfig {
+    debug?: boolean;
+}

package/dist/interfaces/chunks/pkp-integration.i.d.ts

@@ -0,0 +1,87 @@
+/**
+ * PKP Integration Interfaces
+ */
+/**
+ * PKP Manager Interface
+ */
+export interface IPKPManager {
+    issuePKP(request: PKPIssuanceRequest): Promise<PKPData>;
+    validatePKP(pkpId: string): Promise<PKPValidationResult>;
+    getPKPData(pkpId: string): Promise<PKPData | null>;
+}
+/**
+ * PKP Data Interface
+ */
+export interface PKPData {
+    tokenId: string;
+    publicKey: string;
+    ethAddress: string;
+    litActionCid?: string;
+}
+/**
+ * PKP Issuance Request Interface
+ */
+export interface PKPIssuanceRequest {
+    userId: string;
+    metadata?: {
+        name?: string;
+        description?: string;
+    };
+}
+/**
+ * PKP Creation Request Interface
+ */
+export interface PKPCreationRequest {
+    userId: string;
+    litActionCid: string;
+    metadata?: {
+        name?: string;
+        description?: string;
+        attributes?: Record<string, any>;
+    };
+}
+/**
+ * PKP Creation Result Interface
+ */
+export interface PKPCreationResult {
+    success: boolean;
+    error?: string;
+    tokenId?: string;
+    publicKey?: string;
+    ethAddress?: string;
+    transactionHash?: string;
+}
+/**
+ * PKP Validation Request Interface
+ */
+export interface PKPValidationRequest {
+    pkpId: string;
+    message: string;
+    signature: string;
+}
+/**
+ * PKP Validation Result Interface
+ */
+export interface PKPValidationResult {
+    valid: boolean;
+    error?: string;
+    validatorAddress?: string;
+    signature?: string;
+}
+/**
+ * PKP Signing Request Interface
+ */
+export interface PKPSigningRequest {
+    pkpId: string;
+    messageHash: string;
+    params?: Record<string, any>;
+}
+/**
+ * PKP Signing Result Interface
+ */
+export interface PKPSigningResult {
+    success: boolean;
+    error?: string;
+    signature?: string;
+    publicKey?: string;
+}

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;
+    };
+}