@gvnrdao/dh-sdk 0.0.166 → 0.0.205

package/dist/interfaces/chunks/btc.i.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bitcoin-related Types and Interfaces
+ */
+export interface IBTCProof {
+    transactionId: string;
+    blockHeight: number;
+    confirmations: number;
+    merkleProof: string[];
+    blockHeader: string;
+}
+export interface BTCTransaction {
+    txid: string;
+    txHash: string;
+    blockHeight: number;
+    confirmations: number;
+    value: string;
+    from: string;
+    to: string;
+    timestamp: number;
+}
+export interface BTCProof {
+    transaction: BTCTransaction;
+    proof: IBTCProof;
+    valid: boolean;
+    verified?: boolean;
+    merkleProof?: string[];
+}
+export interface MonitoringOptions {
+    confirmations: number;
+    minConfirmations?: number;
+    timeoutMs: number;
+    timeout?: number;
+    retryAttempts: number;
+    retryDelayMs: number;
+    onConfirmation?: (confirmations: number) => void;
+}

package/dist/interfaces/chunks/config.i.d.ts

@@ -0,0 +1,250 @@
+/**
+ * SDK Configuration Interfaces
+ */
+import { ethers as ethers5 } from "ethers";
+import { LitNetwork } from "@gvnrdao/dh-lit-ops";
+export type SDKMode = "standalone" | "service";
+/**
+ * Contract Addresses Configuration
+ */
+export interface ContractAddresses {
+    positionManager: string;
+    positionManagerCore?: string;
+    positionManagerViews?: string;
+    simplePsmV2?: string;
+    loanOperationsManager?: string;
+    termManager?: string;
+    collateralManager?: string;
+    ucdController?: string;
+    circuitBreaker?: string;
+    liquidationManager?: string;
+    ucdToken: string;
+    /** Optional when priceProviders is used (LIT actions fetch prices) */
+    priceFeedConsumer?: string;
+    operationAuthorizationRegistry?: string;
+    btcProofValidator?: string;
+    litActionValidator?: string;
+    /** BTCSpendAuthorizer proxy; required in dev for lit-actions `BtcSpendAuth` when passed via `contractAddresses`. */
+    btcSpendAuthorizer?: string;
+    /** BitcoinProviderRegistry proxy; required on non-hardhat chains when chain policy disallows arbitrary providers. */
+    bitcoinProviderRegistry?: string;
+    mockUsdcToken?: string;
+    mockUsdcOwner?: string;
+    mockUsdtToken?: string;
+    mockUsdtOwner?: string;
+}
+/**
+ * Base configuration shared by all SDK modes
+ */
+interface BaseSDKConfig {
+    litNetwork?: LitNetwork;
+    contractSigner?: ethers5.Wallet | ethers5.Signer;
+    ethRpcUrl?: string;
+    chainId?: number;
+    networkOverride?: {
+        chainId: number;
+        name: string;
+    };
+    provider?: ethers5.providers.Provider;
+    chain?: string;
+    litActionCid?: string;
+    litNodeConnectTimeoutMs?: number;
+    subgraphUrl?: string;
+    bitcoinRpcUrl?: string;
+    bitcoinProviders?: BitcoinProviderConfig[];
+    bitcoinConsensusMode?: "single" | "majority";
+    priceProviders?: PriceProviderConfig[];
+    /** PKP Ethereum address for signed price oracle (Lit jsParams pkpId); optional */
+    priceOraclePkpId?: string;
+    bitcoinFaucetUrl?: string;
+    contractAddresses?: ContractAddresses;
+    subgraphs?: {
+        tokenGvnrUrl?: string;
+        diamondHandsUrl?: string;
+    };
+    graphApiKey?: string;
+    graphOptions?: {
+        requestTimeoutMs?: number;
+        maxRetries?: number;
+        pageSize?: number;
+    };
+    mockUsdcTokenAddress?: string;
+    mockUsdcOwnerAddress?: string;
+    mockUsdcDecimals?: number;
+    mockUsdtTokenAddress?: string;
+    mockUsdtOwnerAddress?: string;
+    mockUsdtDecimals?: number;
+    ucdTokenAddress?: string;
+    sessionExpirationMinutes?: number;
+    transactionTimeoutMs?: number;
+    retryAttempts?: number;
+    debug?: boolean;
+    /**
+     * Optional: Override quantum timing buffer (in seconds)
+     * Default: Auto-detected based on network (10s for local, 50s for Sepolia, 35s for mainnet)
+     *
+     * Network-specific defaults:
+     * - Local networks (1337, 31337): 10s
+     * - Testnets (Sepolia 11155111, Goerli 5): 45-50s
+     * - Mainnet (1): 35s
+     *
+     * Only override if you have specific latency requirements.
+     * Recommended: Leave undefined to use automatic network detection.
+     */
+    quantumBufferSeconds?: number;
+    /**
+     * @deprecated No longer read. On Sepolia (11155111), when `eth_estimateGas` fails for
+     * `mintUCD` but a static `eth_call` succeeds, the SDK always broadcasts with a fixed
+     * gas ceiling (EIP-1559). Retained for backward-compatible configs.
+     */
+    skipGasEstimation?: boolean;
+    pkpServiceTimeoutMs?: number;
+    pkpServiceRetryCount?: number;
+    pkpServiceRetryDelayMs?: number;
+    balanceCacheOptions?: {
+        enabled?: boolean;
+        ttlMs?: number;
+        maxSize?: number;
+    };
+    addressCacheOptions?: {
+        enabled?: boolean;
+        ttlMs?: number;
+        maxSize?: number;
+        debug?: boolean;
+    };
+    concurrencyOptions?: {
+        enabled?: boolean;
+        concurrency?: number;
+        timeout?: number;
+        debug?: boolean;
+    };
+    loggingOptions?: {
+        enabled?: boolean;
+        level?: "debug" | "info" | "warn" | "error";
+        includeTimestamp?: boolean;
+        includeContext?: boolean;
+        maxContextKeys?: number;
+        verboseInProduction?: boolean;
+    };
+    validators?: {
+        /** Validator version for position creation (createPosition) - usually v1 for PKP security validation */
+        loanCreation: number;
+        /** Validator version for UCD minting (mintUCD) - usually v4 for business rules validation */
+        minting: number;
+        /** Validator version for partial payments (makePayment) - usually v1 for payment validation */
+        payment: number;
+        /** Validator version for loan extension/renewal (extendPosition) - usually v4 for extension validation */
+        extension: number;
+    };
+    defaultSelectedTermMonths?: number;
+    telegram?: {
+        chatId: string;
+        chatToken: string;
+        threadId?: number;
+    };
+    temperSignaturesTest?: boolean;
+}
+/**
+ * Service Mode Configuration
+ * Uses lit-ops-server for PKP operations
+ */
+export interface ServiceModeConfig extends BaseSDKConfig {
+    mode: "service";
+    serviceEndpoint: string;
+    serviceAuthToken?: string;
+    litOpsSigner?: never;
+}
+/**
+ * Standalone Mode Configuration
+ * User provides signer for direct LIT operations
+ */
+export interface StandaloneModeConfig extends BaseSDKConfig {
+    mode: "standalone";
+    litOpsSigner: ethers5.Wallet;
+    serviceEndpoint?: never;
+    serviceAuthToken?: never;
+}
+/**
+ * Main SDK Configuration - Discriminated Union
+ *
+ * Use ServiceModeConfig for production deployments with lit-ops-server
+ * Use StandaloneModeConfig for development/testing with direct LIT access
+ *
+ * @example Service Mode
+ * ```typescript
+ * const config: DiamondHandsSDKConfig = {
+ *   mode: 'service',
+ *   serviceEndpoint: 'https://lit-ops.example.com',
+ *   contractSigner: wallet
+ * };
+ * ```
+ *
+ * @example Standalone Mode
+ * ```typescript
+ * const config: DiamondHandsSDKConfig = {
+ *   mode: 'standalone',
+ *   litOpsSigner: wallet,
+ *   contractSigner: wallet
+ * };
+ * ```
+ */
+export type DiamondHandsSDKConfig = ServiceModeConfig | StandaloneModeConfig;
+/**
+ * Type guard to check if config is ServiceModeConfig
+ */
+export declare function isServiceModeConfig(config: DiamondHandsSDKConfig): config is ServiceModeConfig;
+/**
+ * Type guard to check if config is StandaloneModeConfig
+ */
+export declare function isStandaloneModeConfig(config: DiamondHandsSDKConfig): config is StandaloneModeConfig;
+/**
+ * Validates that ServiceModeConfig has required fields
+ */
+export declare function validateServiceModeConfig(config: ServiceModeConfig): string | null;
+/**
+ * Validates that StandaloneModeConfig has required fields
+ */
+export declare function validateStandaloneModeConfig(config: StandaloneModeConfig): string | null;
+/**
+ * Validates SDK configuration based on mode
+ */
+export declare function validateSDKConfig(config: DiamondHandsSDKConfig): string | null;
+/**
+ * SDK Initialization Options
+ */
+export interface SDKInitOptions {
+    overrideDefaults?: boolean;
+    customProvider?: ethers5.providers.Provider;
+    skipNetworkCheck?: boolean;
+}
+/**
+ * Network Configuration (basic)
+ */
+export interface BasicNetworkConfig {
+    name: string;
+    chainId: number;
+    rpcUrl: string;
+    blockExplorerUrl?: string;
+}
+/**
+ * Bitcoin Provider Configuration
+ */
+export interface BitcoinProviderConfig {
+    url: string;
+    network: "mainnet" | "regtest";
+    auth?: {
+        username: string;
+        password: string;
+    };
+    name?: string;
+    priority?: number;
+}
+/**
+ * Price Provider Configuration
+ */
+export interface PriceProviderConfig {
+    name: string;
+    apiKey?: string;
+    apiSecret?: string;
+}
+export {};

package/dist/interfaces/chunks/contract-interactions.i.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Smart Contract Interaction Interfaces
+ */
+import { ethers as ethers5 } from "ethers";
+/**
+ * Contract Call Options Interface
+ */
+export interface ContractCallOptions {
+    gasLimit?: number;
+    gasPrice?: string;
+    value?: string;
+    timeout?: number;
+}
+/**
+ * Contract Transaction Result Interface
+ */
+export interface ContractTransactionResult {
+    success: boolean;
+    error?: string;
+    transactionHash?: string;
+    receipt?: ethers5.providers.TransactionReceipt;
+    gasUsed?: string;
+    events?: any[];
+}
+/**
+ * Position Details Interface
+ */
+export interface PositionDetails {
+    positionId: string;
+    pkpId: string;
+    borrower: string;
+    ucdDebt: string;
+    createdAt: number;
+    lastUpdated: number;
+    collateralRatio: string;
+}
+/**
+ * Contract Query Options Interface
+ */
+export interface ContractQueryOptions {
+    blockTag?: number | "latest" | "pending";
+    contractAddress?: string;
+    abi?: string[];
+}
+/**
+ * Event Filter Interface
+ */
+export interface EventFilter {
+    address?: string;
+    topics?: (string | string[])[];
+    fromBlock?: number | "latest";
+    toBlock?: number | "latest";
+}
+/**
+ * Event Log Interface
+ */
+export interface EventLog {
+    address: string;
+    topics: string[];
+    data: string;
+    blockNumber: number;
+    transactionHash: string;
+    logIndex: number;
+}

package/dist/interfaces/chunks/contract-types.i.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Smart Contract Type Interfaces
+ *
+ * These interfaces define the TypeScript types for smart contracts used in the SDK.
+ * They are independent definitions - NOT imported from the contracts package.
+ * Based on Solidity interfaces from contracts/src/interfaces/
+ */
+import { ethers as ethers5 } from "ethers";
+import type { BigNumber } from "ethers";
+/**
+ * Position Manager Contract Interface
+ * Based on contracts/src/interfaces/IPositionManager.sol
+ */
+export interface PositionManager extends ethers5.Contract {
+    createPosition(pkpId: string, validatorSignature: string, mainnetVaultAddress: string, regtestVaultAddress: string, selectedTermMonths: number | BigNumber, validatorVersion: number | BigNumber): Promise<ethers5.ContractTransaction>;
+    mintUCD(positionId: string, mintAmount: BigNumber, mintFee: BigNumber, newDebt: BigNumber, newCollateral: BigNumber, btcPrice: BigNumber, authorizedSpendsHash: string, ucdDebtHash: string, contractHash: string, quantumTimestamp: BigNumber, mintValidatorSignature: string): Promise<ethers5.ContractTransaction>;
+    liquidatePosition(positionId: string, btcPrice: BigNumber, quantumTimestamp: BigNumber, liquidationValidatorSignature: string): Promise<ethers5.ContractTransaction>;
+    getPosition(positionId: string): Promise<{
+        positionId: string;
+        pkpId: string;
+        ucdDebt: BigNumber;
+        borrower: string;
+        createdAt: number;
+        lastUpdated: number;
+        selectedTerm: number;
+        expiryAt: number;
+        status: number;
+    }>;
+    pkpValidationRegistry(): Promise<string>;
+    updateBalance(positionId: string, newBtcBalance: string | number | BigNumber, btcPrice: string | number | BigNumber, quantumTimestamp: string | number | BigNumber, signature: string): Promise<ethers5.ContractTransaction>;
+}
+/**
+ * Loan Operations Manager Contract Interface
+ * Based on contracts/src/interfaces/ILoanOperationsManager.sol
+ */
+export interface ILoanOperationsManager extends ethers5.Contract {
+    mintUCD(positionId: string, mintAmount: BigNumber, mintFee: BigNumber, newDebt: BigNumber, newCollateral: BigNumber, btcPrice: BigNumber, authorizedSpendsHash: string, ucdDebtHash: string, quantumTimestamp: BigNumber): Promise<ethers5.ContractTransaction>;
+    processPayment(positionId: string, paymentAmount: BigNumber, quantumTimestamp: BigNumber, btcPrice: BigNumber): Promise<ethers5.ContractTransaction>;
+    updatePosition(positionId: string, newDebt: BigNumber, quantumTimestamp: BigNumber, btcPrice: BigNumber, updateValidatorSignature: string): Promise<ethers5.ContractTransaction>;
+    transferOriginationFee(recipient: string, amount: BigNumber): Promise<ethers5.ContractTransaction>;
+    mintExtensionFee(amount: BigNumber): Promise<ethers5.ContractTransaction>;
+    getOriginationFeeBalance(): Promise<BigNumber>;
+    authorizeBTCSpend(positionId: string, txid: string, vout: number, satoshis: BigNumber, targetAddress: string, targetAmount: BigNumber, litSignature: string): Promise<ethers5.ContractTransaction>;
+    liquidationThreshold(): Promise<BigNumber>;
+    minimumLoanValueWei(): Promise<BigNumber>;
+    ucdToken(): Promise<string>;
+    getUcdController(): Promise<string>;
+    getPKPActualCollateral(pkpId: string): Promise<BigNumber>;
+    isPriceFeedStale(): Promise<boolean>;
+    calculateCollateralRatio(positionId: string, btcPrice: BigNumber): Promise<BigNumber>;
+    getTotalAuthorizedSats(positionId: string): Promise<BigNumber>;
+    extendPosition(positionId: string, newTermMonths: BigNumber, extensionFee: BigNumber, quantumTimestamp: BigNumber, btcPrice: BigNumber, extendValidatorSignature: string): Promise<ethers5.ContractTransaction>;
+    withdrawBTC(positionId: string, btcTxid: string, btcVout: number, satoshis: BigNumber, destinationAddress: string, quantumTimestamp: BigNumber, btcPrice: BigNumber, btcWithdrawalSignature: string): Promise<ethers5.ContractTransaction>;
+}
+/**
+ * UCD Controller Contract Interface
+ * Based on contracts/src/interfaces/IUCDController.sol
+ */
+export interface IUCDController extends ethers5.Contract {
+    mintFromLoanOps(to: string, amount: BigNumber, positionId: string, debtAfterMint: BigNumber): Promise<ethers5.ContractTransaction>;
+    mintFromPsm(to: string, amount: BigNumber, stablecoin: string, amountIn: BigNumber): Promise<ethers5.ContractTransaction>;
+    burnTokens(from: string, amount: BigNumber): Promise<ethers5.ContractTransaction>;
+    setAdminModule(_adminModule: string): Promise<ethers5.ContractTransaction>;
+    setAuthorizedMinter(minter: string, authorized: boolean): Promise<ethers5.ContractTransaction>;
+    setAuthorizedBurner(burner: string, authorized: boolean): Promise<ethers5.ContractTransaction>;
+    setMaxSupply(newMaxSupply: BigNumber): Promise<ethers5.ContractTransaction>;
+    setDailyMintLimit(newLimit: BigNumber): Promise<ethers5.ContractTransaction>;
+    setDailyBurnLimit(newLimit: BigNumber): Promise<ethers5.ContractTransaction>;
+    setUCDToken(newToken: string): Promise<ethers5.ContractTransaction>;
+    getCurrentSupply(): Promise<BigNumber>;
+    getRemainingMintCapacity(): Promise<BigNumber>;
+    getRemainingBurnCapacity(): Promise<BigNumber>;
+    getRemainingPsmMintCapacity(): Promise<BigNumber>;
+    isAuthorizedMinter(account: string): Promise<boolean>;
+    isAuthorizedBurner(account: string): Promise<boolean>;
+    authorizedMinters(account: string): Promise<boolean>;
+    authorizedBurners(account: string): Promise<boolean>;
+    burnedPerAddress(account: string): Promise<BigNumber>;
+    totalMinted(): Promise<BigNumber>;
+    totalBurned(): Promise<BigNumber>;
+    maxSupply(): Promise<BigNumber>;
+    dailyMintLimit(): Promise<BigNumber>;
+    dailyBurnLimit(): Promise<BigNumber>;
+    lastMintReset(): Promise<BigNumber>;
+    lastBurnReset(): Promise<BigNumber>;
+    dailyMinted(): Promise<BigNumber>;
+    dailyBurned(): Promise<BigNumber>;
+    dailyPsmMinted(): Promise<BigNumber>;
+    psmDailyMintLimit(): Promise<BigNumber>;
+    circuitBreaker(): Promise<string>;
+    ucdToken(): Promise<string>;
+    adminModule(): Promise<string>;
+}
+/**
+ * Price Feed Consumer Contract Interface
+ */
+export interface IPriceFeedConsumer extends ethers5.Contract {
+    updatePrice(): Promise<ethers5.ContractTransaction>;
+    getCurrentPrice(): Promise<BigNumber>;
+    getPriceAge(): Promise<BigNumber>;
+    isPriceStale(): Promise<boolean>;
+    validatePriceFeed(): Promise<boolean>;
+    getLatestBTCPrice(): Promise<BigNumber>;
+    decimals(): Promise<number>;
+}
+/**
+ * Term Manager Contract Interface
+ * Based on contracts/src/interfaces/ITermManager.sol
+ */
+export interface ITermManager extends ethers5.Contract {
+    addTerm(termMonths: BigNumber, originationFee: BigNumber, extensionFee: BigNumber): Promise<ethers5.ContractTransaction>;
+    removeTerm(termMonths: BigNumber): Promise<ethers5.ContractTransaction>;
+    updateTermFees(termMonths: BigNumber, originationFee: BigNumber, extensionFee: BigNumber): Promise<ethers5.ContractTransaction>;
+    getTermFees(termMonths: BigNumber): Promise<{
+        originationFee: BigNumber;
+        extensionFee: BigNumber;
+    }>;
+    isValidTerm(termMonths: BigNumber): Promise<boolean>;
+    getValidTermsWithFees(): Promise<{
+        terms: BigNumber[];
+        originationFees: BigNumber[];
+        extensionFees: BigNumber[];
+    }>;
+    getTermDataById(termId: BigNumber): Promise<{
+        termMonths: BigNumber;
+        originationFee: BigNumber;
+        extensionFee: BigNumber;
+        isActive: boolean;
+    }>;
+    getAllTerms(): Promise<BigNumber[]>;
+    updateDependencies(newCore: string, newUcdController: string): Promise<ethers5.ContractTransaction>;
+    supportsInterface(interfaceId: string): Promise<boolean>;
+}
+/**
+ * Circuit Breaker Module Contract Interface
+ * Based on contracts/src/interfaces/ICircuitBreakerModule.sol
+ */
+export interface CircuitBreakerModule extends ethers5.Contract {
+    circuitBreakerCheck(ucdAmount: BigNumber, btcAmount: BigNumber): Promise<ethers5.ContractTransaction>;
+    proposeLimitUpdate(newMaxLoanValue: BigNumber, newMaxBtcPerPosition: BigNumber, newDailyLimit: BigNumber): Promise<ethers5.ContractTransaction>;
+    signLimitUpdate(proposalHash: string): Promise<ethers5.ContractTransaction>;
+    executeLimitUpdate(proposalHash: string, newMaxLoanValue: BigNumber, newMaxBtcPerPosition: BigNumber, newDailyLimit: BigNumber): Promise<ethers5.ContractTransaction>;
+    activateCircuitBreaker(): Promise<ethers5.ContractTransaction>;
+    deactivateCircuitBreaker(): Promise<ethers5.ContractTransaction>;
+    signCircuitBreakerDeactivation(): Promise<ethers5.ContractTransaction>;
+    maxSingleLoanValue(): Promise<BigNumber>;
+    maxBtcPerPosition(): Promise<BigNumber>;
+    dailyVolumeLimit(): Promise<BigNumber>;
+    circuitBreakerActive(): Promise<boolean>;
+    circuitBreakerActivatedAt(): Promise<BigNumber>;
+    dailyUcdVolume(day: BigNumber): Promise<BigNumber>;
+    dailyBtcVolume(day: BigNumber): Promise<BigNumber>;
+    supportsInterface(interfaceId: string): Promise<boolean>;
+}
+/**
+ * Liquidation Manager Contract Interface
+ * Based on contracts/src/interfaces/ILiquidationManager.sol
+ */
+export interface ILiquidationManager extends ethers5.Contract {
+    liquidatePosition(positionId: string, btcPrice: BigNumber, quantumTimestamp: BigNumber): Promise<ethers5.ContractTransaction>;
+    commitLiquidation(positionId: string, quantumTimestamp: BigNumber, btcPrice: BigNumber): Promise<ethers5.ContractTransaction>;
+    revealAndLiquidate(positionId: string, quantumTimestamp: BigNumber, btcPrice: BigNumber, liquidationValidatorSignature: string, deadline: BigNumber): Promise<ethers5.ContractTransaction>;
+    isLiquidatable(positionId: string, btcPrice: BigNumber, quantumTimestamp: BigNumber, liquidationValidatorSignature: string): Promise<boolean>;
+    supportsInterface(interfaceId: string): Promise<boolean>;
+}

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;