@gvnrdao/dh-sdk 0.0.288 → 0.0.289

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

@@ -0,0 +1,165 @@
+/**
+ * Typed responses for critical Diamond Hands LIT Actions.
+ *
+ * These mirror the JSON payloads passed to `Lit.Actions.setResponse(...)`
+ * in the lit-actions package and are intended to be used as the `TData`
+ * parameter on `LitActionResult<TData>`.
+ */
+import type { PositionId } from "../../types/branded/ids";
+/**
+ * Base shape for approval-style validator responses.
+ */
+export interface BaseValidatorResponse {
+    approved: boolean;
+    positionId?: PositionId | string;
+    reason?: string;
+    failedStep?: string;
+    timestamp: number | string;
+    /**
+     * Optional low-level execution error from lit-ops / LIT runtime.
+     */
+    error?: string;
+    /**
+     * Some flows attach the raw signature JSON here (service wrappers).
+     */
+    signature?: string;
+}
+/**
+ * UCD Mint Validator response (ucdMintValidator).
+ * Source: lit-actions/src/ucd-mint-validator.ts
+ */
+export interface UcdMintValidatorResponse extends BaseValidatorResponse {
+    approved: true;
+    mintAmount: string;
+    mintFee: string;
+    newDebt: string;
+    newCollateral: string;
+    newCollateralRatioBps: number;
+    btcPrice: string;
+    authorizedSpendsHash: string;
+    ucdDebtHash: string;
+    contractBundleHash: string;
+    signature: string;
+    validatorPkp: string;
+    /**
+     * Optional: Exact parameter values used for signing.
+     * If present, SDK should use these values instead of response values
+     * to ensure contract receives identical parameters that were signed.
+     */
+    signingParams?: {
+        positionId: string;
+        actionHash: string;
+        authorizedSpendsHash: string;
+        ucdDebtHash: string;
+        contractBundleHash: string;
+        btcPrice: string;
+        mintAmount: string;
+        mintFee: string;
+        newCollateral: string;
+        newDebt: string;
+        timestamp: string;
+    };
+}
+export interface UcdMintValidatorErrorResponse extends BaseValidatorResponse {
+    approved: false;
+}
+export type UcdMintValidatorResult = UcdMintValidatorResponse | UcdMintValidatorErrorResponse;
+/**
+ * BTC Withdrawal Validator response (btcWithdrawal).
+ * Source: lit-actions/src/btc-withdrawal.ts
+ */
+export interface BtcWithdrawalValidatorResponse extends BaseValidatorResponse {
+    approved: true;
+    actionHash: string;
+    authorizedSpendsHash: string;
+    ucdDebtHash: string;
+    totalDeduction: string;
+    remainingCollateral: string;
+    newCollateralRatioBps?: number;
+    destinationAddress: string;
+    signature: string;
+    btcPrice: string;
+    /**
+     * Optional UTXO fields used by enhanced BTC withdrawal flow.
+     * These are populated by the LIT Action when BIP-143 validation is enabled.
+     */
+    utxoTxid?: string;
+    utxoVout?: number;
+}
+export interface BtcWithdrawalValidatorErrorResponse extends BaseValidatorResponse {
+    approved: false;
+}
+export type BtcWithdrawalValidatorResult = BtcWithdrawalValidatorResponse | BtcWithdrawalValidatorErrorResponse;
+/**
+ * Liquidation Validator response (liquidationValidator).
+ * Source: lit-actions/src/liquidation-validator.ts
+ */
+export interface LiquidationValidatorResponse extends BaseValidatorResponse {
+    approved: true;
+    btcPrice: string;
+    btcAmountSats: string;
+    signature: string;
+    signatureBonus: string;
+    validatorPkp: string;
+}
+export interface LiquidationValidatorErrorResponse extends BaseValidatorResponse {
+    approved: false;
+}
+export type LiquidationValidatorResult = LiquidationValidatorResponse | LiquidationValidatorErrorResponse;
+/**
+ * Extend Position Validator response (extendPositionValidator).
+ * Source: lit-actions/src/extend-position-validator.ts
+ */
+export interface ExtendPositionValidatorResponse extends BaseValidatorResponse {
+    approved: true;
+    selectedTerm: number;
+    btcPrice: string;
+    availableBTCBalance: string;
+    extensionFee: string;
+    newTotalDebt: string;
+    newCollateralRatioBps: string;
+    signature: string;
+    timestamp: number;
+    quantumTimestamp: number;
+    validatorPkp: string;
+}
+export interface ExtendPositionValidatorErrorResponse extends BaseValidatorResponse {
+    approved: false;
+}
+export type ExtendPositionValidatorResult = ExtendPositionValidatorResponse | ExtendPositionValidatorErrorResponse;
+/**
+ * Process Payment Validator response (processPaymentValidator).
+ * Source: lit-actions/src/process-payment-validator.ts
+ */
+export interface ProcessPaymentValidatorResponse extends BaseValidatorResponse {
+    approved: true;
+    paymentAmount: string;
+    btcPrice: string;
+    btcAmountSats: string;
+    signature: string;
+    timestamp: number;
+    validatorPkp: string;
+}
+export interface ProcessPaymentValidatorErrorResponse extends BaseValidatorResponse {
+    approved: false;
+}
+export type ProcessPaymentValidatorResult = ProcessPaymentValidatorResponse | ProcessPaymentValidatorErrorResponse;
+/**
+ * Loan vault BTC balance / deposit validator response (loanVaultBtcBalance).
+ * Source: lit-actions/src/loan-vault-btc-balance.ts
+ */
+export interface LoanVaultBtcBalanceValidatorResponse {
+    vaultAddress: string;
+    vaultBalance: string;
+    positionId: PositionId | string;
+    btcPrice: string;
+    signature: string;
+    timestamp: number;
+    validatorPkp: string;
+}
+export interface LoanVaultBtcBalanceValidatorErrorResponse {
+    error: string;
+    positionId: PositionId | string | null;
+    timestamp: number;
+}
+export type LoanVaultBtcBalanceValidatorResult = LoanVaultBtcBalanceValidatorResponse | LoanVaultBtcBalanceValidatorErrorResponse;

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,331 @@
+/**
+ * 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;
+    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;
+    /** Full satoshi value of the authorized UTXO; needed by Phase 2 broadcast. */
+    utxoSatoshis?: string;
+    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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}