@gvnrdao/dh-sdk 0.0.125 → 0.0.128

package/dist/index.d.mts

@@ -122,306 +122,6 @@ declare function match<T, E, U>(result: Result$1<T, E>, handlers: {
     failure: (error: E) => U;
 }): U;
 
-/**
- * Production-Ready Error Handler for PKP Validation and Loan Creation
- */
-/**
- * Error categories for SDK operations
- */
-declare enum ErrorCategory {
-    CONFIGURATION = "CONFIGURATION",
-    INITIALIZATION = "INITIALIZATION",
-    NETWORK = "NETWORK",
-    CONTRACT = "CONTRACT",
-    PKP = "PKP",
-    BITCOIN = "BITCOIN",
-    AUTHORIZATION = "AUTHORIZATION",
-    VALIDATION = "VALIDATION",
-    TRANSACTION = "TRANSACTION",
-    SUBGRAPH = "SUBGRAPH",
-    CACHE = "CACHE",
-    UNKNOWN = "UNKNOWN"
-}
-/**
- * Error severity levels
- */
-declare enum ErrorSeverity {
-    LOW = "LOW",
-    MEDIUM = "MEDIUM",
-    HIGH = "HIGH",
-    CRITICAL = "CRITICAL"
-}
-/**
- * Modern SDK Error class with structured error handling
- */
-declare class SDKError extends Error {
-    readonly category: ErrorCategory;
-    readonly severity: ErrorSeverity;
-    readonly retryable: boolean;
-    readonly context?: Record<string, any>;
-    readonly originalError?: Error;
-    readonly timestamp: number;
-    constructor(params: {
-        message: string;
-        category: ErrorCategory;
-        severity: ErrorSeverity;
-        retryable?: boolean;
-        context?: Record<string, any>;
-        originalError?: Error;
-    });
-    /**
-     * Convert to JSON-serializable format
-     */
-    toJSON(): {
-        name: string;
-        message: string;
-        category: ErrorCategory;
-        severity: ErrorSeverity;
-        retryable: boolean;
-        context: Record<string, any> | undefined;
-        timestamp: number;
-        stack: string | undefined;
-    };
-}
-
-/**
- * Generic Cache Manager Module
- *
- * Provides a type-safe, generic LRU cache with TTL support.
- * Can be used for any data type (Bitcoin balances, addresses, query results, etc.)
- *
- * Features:
- * - Generic type support
- * - TTL-based expiration
- * - LRU eviction policy
- * - Hit/miss statistics
- * - Memory-efficient
- * - Thread-safe operations
- */
-
-/**
- * Cache entry with metadata
- */
-interface CacheEntry<T> {
-    /** Cached value */
-    value: T;
-    /** Unix timestamp when entry was created (ms) */
-    timestamp: number;
-    /** Number of times this entry was accessed */
-    hits: number;
-    /** Unix timestamp of last access (ms) */
-    lastAccessed: number;
-}
-/**
- * Cache statistics
- */
-interface CacheStats {
-    /** Current number of entries in cache */
-    size: number;
-    /** Total cache hits */
-    hits: number;
-    /** Total cache misses */
-    misses: number;
-    /** Total evictions performed */
-    evictions: number;
-    /** Timestamp of oldest entry (ms) */
-    oldestEntry: number;
-    /** Timestamp of newest entry (ms) */
-    newestEntry: number;
-    /** Hit rate as percentage (0-100) */
-    hitRate: number;
-}
-/**
- * Cache configuration
- */
-interface CacheConfig {
-    /** Maximum number of entries (default: 1000) */
-    maxSize?: number;
-    /** Time-to-live in milliseconds (default: 60000 = 1 minute) */
-    ttlMs?: number;
-    /** Enable debug logging (default: false) */
-    debug?: boolean;
-    /** Cache name for logging (default: 'Cache') */
-    name?: string;
-}
-/**
- * Generic LRU Cache with TTL support
- *
- * @template K - Key type (usually string)
- * @template V - Value type
- *
- * @example
- * ```typescript
- * // Create a cache for Bitcoin balances
- * const balanceCache = new LRUCache<string, BitcoinBalance>({
- *   maxSize: 500,
- *   ttlMs: 60000,
- *   name: 'BitcoinBalance'
- * });
- *
- * // Set value
- * balanceCache.set('bc1q...', { balance: Satoshis(50000000n) });
- *
- * // Get value
- * const balance = balanceCache.get('bc1q...');
- * if (balance) {
- *   console.log('Cached balance:', balance.balance);
- * }
- * ```
- */
-declare class LRUCache<K, V> {
-    private cache;
-    private readonly maxSize;
-    private readonly ttlMs;
-    private readonly debug;
-    private readonly name;
-    private stats;
-    constructor(config?: CacheConfig);
-    /**
-     * Get value from cache
-     *
-     * Returns null if:
-     * - Key not found
-     * - Entry has expired
-     *
-     * @param key - Cache key
-     * @returns Cached value or null
-     */
-    get(key: K): V | null;
-    /**
-     * Get value from cache with Result wrapper
-     *
-     * Useful when you want to distinguish between "not found" and "expired"
-     */
-    getResult(key: K): Result$1<V, SDKError>;
-    /**
-     * Set value in cache
-     *
-     * If cache is full, evicts the least recently used entry
-     *
-     * @param key - Cache key
-     * @param value - Value to cache
-     * @param ttl - Optional custom TTL for this entry (ms)
-     */
-    set(key: K, value: V, ttl?: number): void;
-    /**
-     * Set value in cache with Result wrapper
-     */
-    setResult(key: K, value: V, ttl?: number): Result$1<void, SDKError>;
-    /**
-     * Check if key exists in cache (without affecting stats)
-     */
-    has(key: K): boolean;
-    /**
-     * Delete specific key from cache
-     */
-    delete(key: K): boolean;
-    /**
-     * Clear entire cache
-     */
-    clear(): void;
-    /**
-     * Get current cache size
-     */
-    size(): number;
-    /**
-     * Get cache statistics
-     */
-    getStats(): CacheStats;
-    /**
-     * Get hit rate percentage
-     */
-    getHitRate(): number;
-    /**
-     * Get all cached keys (for debugging)
-     */
-    getKeys(): K[];
-    /**
-     * Get all cached values (for debugging)
-     */
-    getValues(): V[];
-    /**
-     * Get all cache entries with metadata (for debugging)
-     */
-    getEntries(): Array<{
-        key: K;
-        value: V;
-        metadata: Omit<CacheEntry<V>, 'value'>;
-    }>;
-    /**
-     * Clean up expired entries
-     *
-     * Useful for periodic maintenance
-     *
-     * @returns Number of entries cleaned
-     */
-    cleanExpired(): number;
-    /**
-     * Check if cache entry is expired
-     */
-    private isExpired;
-    /**
-     * Evict least recently used entry
-     */
-    private evictLRU;
-    /**
-     * Get or compute value
-     *
-     * If key exists in cache, returns cached value.
-     * Otherwise, computes value using provided function and caches it.
-     *
-     * @param key - Cache key
-     * @param compute - Function to compute value if not in cache
-     * @param ttl - Optional custom TTL for this entry
-     * @returns Cached or computed value
-     */
-    getOrCompute(key: K, compute: () => Promise<V>, ttl?: number): Promise<V>;
-    /**
-     * Get or compute value with Result wrapper
-     */
-    getOrComputeResult(key: K, compute: () => Promise<Result$1<V, SDKError>>, ttl?: number): Promise<Result$1<V, SDKError>>;
-}
-/**
- * Cache Manager - Factory for creating specialized caches
- */
-declare class CacheManager {
-    private caches;
-    private readonly globalConfig;
-    constructor(globalConfig?: CacheConfig);
-    /**
-     * Create or get a named cache
-     *
-     * @param name - Unique cache name
-     * @param config - Optional cache-specific configuration
-     * @returns LRU cache instance
-     */
-    getCache<K, V>(name: string, config?: CacheConfig): LRUCache<K, V>;
-    /**
-     * Clear all caches
-     */
-    clearAll(): void;
-    /**
-     * Clean expired entries from all caches
-     */
-    cleanAllExpired(): number;
-    /**
-     * Get statistics for all caches
-     */
-    getAllStats(): Record<string, CacheStats>;
-    /**
-     * Get list of all cache names
-     */
-    getCacheNames(): string[];
-    /**
-     * Delete a named cache
-     */
-    deleteCache(name: string): boolean;
-}
-/**
- * Factory function to create a CacheManager instance
- */
-declare function createCacheManager(config?: CacheConfig): CacheManager;
-
 /**
  * Branded types for domain-specific values to prevent mixing incompatible units
  *
@@ -554,6 +254,68 @@ declare namespace BPSConversions {
     function format(bps: BPS): string;
 }
 
+/**
+ * Production-Ready Error Handler for PKP Validation and Loan Creation
+ */
+/**
+ * Error categories for SDK operations
+ */
+declare enum ErrorCategory {
+    CONFIGURATION = "CONFIGURATION",
+    INITIALIZATION = "INITIALIZATION",
+    NETWORK = "NETWORK",
+    CONTRACT = "CONTRACT",
+    PKP = "PKP",
+    BITCOIN = "BITCOIN",
+    AUTHORIZATION = "AUTHORIZATION",
+    VALIDATION = "VALIDATION",
+    TRANSACTION = "TRANSACTION",
+    SUBGRAPH = "SUBGRAPH",
+    CACHE = "CACHE",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Error severity levels
+ */
+declare enum ErrorSeverity {
+    LOW = "LOW",
+    MEDIUM = "MEDIUM",
+    HIGH = "HIGH",
+    CRITICAL = "CRITICAL"
+}
+/**
+ * Modern SDK Error class with structured error handling
+ */
+declare class SDKError extends Error {
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly retryable: boolean;
+    readonly context?: Record<string, any>;
+    readonly originalError?: Error;
+    readonly timestamp: number;
+    constructor(params: {
+        message: string;
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        retryable?: boolean;
+        context?: Record<string, any>;
+        originalError?: Error;
+    });
+    /**
+     * Convert to JSON-serializable format
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        retryable: boolean;
+        context: Record<string, any> | undefined;
+        timestamp: number;
+        stack: string | undefined;
+    };
+}
+
 /**
  * SDK Configuration Interfaces
  */
@@ -569,6 +331,7 @@ interface ContractAddresses {
     simplePsmV2?: string;
     loanOperationsManager?: string;
     termManager?: string;
+    collateralManager?: string;
     ucdController?: string;
     circuitBreaker?: string;
     communityManager?: string;
@@ -602,6 +365,7 @@ interface BaseSDKConfig {
     bitcoinRpcUrl?: string;
     bitcoinProviders?: BitcoinProviderConfig[];
     bitcoinConsensusMode?: "single" | "majority";
+    priceProviders?: PriceProviderConfig[];
     bitcoinFaucetUrl?: string;
     contractAddresses?: ContractAddresses;
     subgraphs?: {
@@ -654,16 +418,6 @@ interface BaseSDKConfig {
         verboseInProduction?: boolean;
     };
     validatorVersion?: number;
-    /**
-     * Lit Action execution mode (standalone mode only)
-     * In service mode, actions are always executed via the service endpoint
-     * - 'ipfs': Execute from IPFS CID (client-side, default for standalone)
-     * - 'code': Execute inline code via service
-     * @note This setting is ignored when mode === 'service'
-     */
-    litActionExecution?: 'ipfs' | 'code';
-    ucdMintValidatorCid?: string;
-    btcWithdrawalCid?: string;
     defaultSelectedTermMonths?: number;
     telegram?: {
         chatId: string;
@@ -766,6 +520,14 @@ interface BitcoinProviderConfig {
     name?: string;
     priority?: number;
 }
+/**
+ * Price Provider Configuration
+ */
+interface PriceProviderConfig {
+    name: string;
+    apiKey?: string;
+    apiSecret?: string;
+}
 
 interface TypedDeferredTopicFilter<_TCEvent extends TypedContractEvent> extends DeferredTopicFilter {
 }
@@ -876,7 +638,6 @@ declare namespace IPositionManager {
         positionId: BytesLike;
         pkpId: BytesLike;
         ucdDebt: BigNumberish;
-        vaultAddress: string;
         borrower: AddressLike;
         createdAt: BigNumberish;
         lastUpdated: BigNumberish;
@@ -888,7 +649,6 @@ declare namespace IPositionManager {
         positionId: string,
         pkpId: string,
         ucdDebt: bigint,
-        vaultAddress: string,
         borrower: string,
         createdAt: bigint,
         lastUpdated: bigint,
@@ -899,7 +659,6 @@ declare namespace IPositionManager {
         positionId: string;
         pkpId: string;
         ucdDebt: bigint;
-        vaultAddress: string;
         borrower: string;
         createdAt: bigint;
         lastUpdated: bigint;
@@ -908,9 +667,49 @@ declare namespace IPositionManager {
         status: bigint;
     };
 }
+declare namespace ICollateralManager {
+    type WithdrawalParamsStruct = {
+        positionId: BytesLike;
+        actionHash: BytesLike;
+        authorizedSpendsHash: BytesLike;
+        ucdDebtHash: BytesLike;
+        withdrawalAddress: string;
+        totalDeduction: BigNumberish;
+        newCollateral: BigNumberish;
+        quantumTimestamp: BigNumberish;
+        btcPrice: BigNumberish;
+        utxoTxid: string;
+        utxoVout: BigNumberish;
+    };
+    type WithdrawalParamsStructOutput = [
+        positionId: string,
+        actionHash: string,
+        authorizedSpendsHash: string,
+        ucdDebtHash: string,
+        withdrawalAddress: string,
+        totalDeduction: bigint,
+        newCollateral: bigint,
+        quantumTimestamp: bigint,
+        btcPrice: bigint,
+        utxoTxid: string,
+        utxoVout: bigint
+    ] & {
+        positionId: string;
+        actionHash: string;
+        authorizedSpendsHash: string;
+        ucdDebtHash: string;
+        withdrawalAddress: string;
+        totalDeduction: bigint;
+        newCollateral: bigint;
+        quantumTimestamp: bigint;
+        btcPrice: bigint;
+        utxoTxid: string;
+        utxoVout: bigint;
+    };
+}
 interface PositionManagerInterface extends Interface {
-    getFunction(nameOrSignature: "ADMIN_ROLE" | "COMMUNITY_FEE_DISTRIBUTOR_ROLE" | "COMMUNITY_MINTER_ROLE" | "DEFAULT_ADMIN_ROLE" | "EMERGENCY_PAUSE_ROLE" | "LIQUIDATOR_ROLE" | "ORACLE_UPDATER_ROLE" | "UPGRADE_INTERFACE_VERSION" | "VERSION" | "_performExtensionValidation" | "admin" | "authorizationRegistry" | "calculateCollateralRatio" | "circuitBreaker" | "collateral" | "commitLiquidation" | "communityManager" | "core" | "createPosition" | "extendPosition" | "getExpiredLoanLiquidationThreshold" | "getPKPLoanParams" | "getPKPPositionData" | "getPositionDetails" | "getPositionStatus" | "getRoleAdmin" | "grantRole" | "hasRole" | "initialize" | "isExpiredLoanLiquidatable" | "liquidatePosition" | "liquidation" | "loanOps" | "makePartialPayment" | "paused" | "pkpValidationRegistry" | "proxiableUUID" | "renounceRole" | "repayPosition" | "revealAndLiquidate" | "revokeRole" | "setAuthorizationRegistry" | "setPKPValidationRegistry" | "supportsInterface" | "termManager" | "updateDebtFromLoanOps" | "updateModules" | "updatePosition" | "updatePositionStatusFromLoanOps" | "upgradeToAndCall" | "validatePKPLogic" | "validateUpgrade" | "views" | "withdrawBTC"): FunctionFragment;
-    getEvent(nameOrSignatureOrTopic: "CollateralRatioUpdated" | "Initialized" | "IntegrityCheckFailed" | "ModulesUpdatedBatch" | "PKPLogicValidated" | "PKPValidationRegistryUpdated" | "PartialPaymentMade" | "Paused" | "PositionClosed" | "PositionCreated" | "PositionLiquidated" | "PositionRenewed" | "PositionRepaid" | "PositionStatusUpdated" | "PositionUpdated" | "RoleAdminChanged" | "RoleGranted" | "RoleRevoked" | "UCDMinted" | "Unpaused" | "Upgraded" | "WithdrawBTCSignatureDebug"): EventFragment;
+    getFunction(nameOrSignature: "ADMIN_ROLE" | "COMMUNITY_FEE_DISTRIBUTOR_ROLE" | "COMMUNITY_MINTER_ROLE" | "DEFAULT_ADMIN_ROLE" | "EMERGENCY_PAUSE_ROLE" | "LIQUIDATOR_ROLE" | "ORACLE_UPDATER_ROLE" | "UPGRADE_INTERFACE_VERSION" | "VERSION" | "_performExtensionValidation" | "admin" | "authorizationRegistry" | "calculateCollateralRatio" | "circuitBreaker" | "clearExtensionPending" | "collateral" | "commitLiquidation" | "communityManager" | "core" | "createPosition" | "extendPosition" | "getExpiredLoanLiquidationThreshold" | "getPKPLoanParams" | "getPKPPositionData" | "getPositionDetails" | "getPositionStatus" | "getRoleAdmin" | "grantRole" | "hasRole" | "initialize" | "isExpiredLoanLiquidatable" | "liquidatePosition" | "liquidation" | "loanOps" | "makePartialPayment" | "paused" | "pkpValidationRegistry" | "proxiableUUID" | "renounceRole" | "repayPosition" | "revealAndLiquidate" | "revokeRole" | "setAuthorizationRegistry" | "setPKPValidationRegistry" | "supportsInterface" | "termManager" | "updateDebtFromLoanOps" | "updateModules" | "updatePosition" | "updatePositionStatusFromLoanOps" | "upgradeToAndCall" | "validatePKPLogic" | "validateUpgrade" | "views" | "withdrawBTC"): FunctionFragment;
+    getEvent(nameOrSignatureOrTopic: "CollateralRatioUpdated" | "ExtensionPendingCleared" | "Initialized" | "IntegrityCheckFailed" | "ModulesUpdatedBatch" | "PKPLogicValidated" | "PKPValidationRegistryUpdated" | "PartialPaymentMade" | "Paused" | "PositionClosed" | "PositionCreated" | "PositionLiquidated" | "PositionRenewed" | "PositionRepaid" | "PositionStatusUpdated" | "PositionUpdated" | "RoleAdminChanged" | "RoleGranted" | "RoleRevoked" | "UCDMinted" | "Unpaused" | "Upgraded"): EventFragment;
     encodeFunctionData(functionFragment: "ADMIN_ROLE", values?: undefined): string;
     encodeFunctionData(functionFragment: "COMMUNITY_FEE_DISTRIBUTOR_ROLE", values?: undefined): string;
     encodeFunctionData(functionFragment: "COMMUNITY_MINTER_ROLE", values?: undefined): string;
@@ -920,17 +719,18 @@ interface PositionManagerInterface extends Interface {
     encodeFunctionData(functionFragment: "ORACLE_UPDATER_ROLE", values?: undefined): string;
     encodeFunctionData(functionFragment: "UPGRADE_INTERFACE_VERSION", values?: undefined): string;
     encodeFunctionData(functionFragment: "VERSION", values?: undefined): string;
-    encodeFunctionData(functionFragment: "_performExtensionValidation", values: [IPositionManagerCore.PositionStruct, BigNumberish]): string;
+    encodeFunctionData(functionFragment: "_performExtensionValidation", values: [IPositionManagerCore.PositionStruct, BigNumberish, BigNumberish]): string;
     encodeFunctionData(functionFragment: "admin", values?: undefined): string;
     encodeFunctionData(functionFragment: "authorizationRegistry", values?: undefined): string;
     encodeFunctionData(functionFragment: "calculateCollateralRatio", values: [BytesLike]): string;
     encodeFunctionData(functionFragment: "circuitBreaker", values?: undefined): string;
+    encodeFunctionData(functionFragment: "clearExtensionPending", values: [BytesLike]): string;
     encodeFunctionData(functionFragment: "collateral", values?: undefined): string;
     encodeFunctionData(functionFragment: "commitLiquidation", values: [BytesLike, BytesLike]): string;
     encodeFunctionData(functionFragment: "communityManager", values?: undefined): string;
     encodeFunctionData(functionFragment: "core", values?: undefined): string;
-    encodeFunctionData(functionFragment: "createPosition", values: [BytesLike, BytesLike, string, BigNumberish, BigNumberish]): string;
-    encodeFunctionData(functionFragment: "extendPosition", values: [BytesLike, BigNumberish]): string;
+    encodeFunctionData(functionFragment: "createPosition", values: [BytesLike, BytesLike, string, string, BigNumberish, BigNumberish]): string;
+    encodeFunctionData(functionFragment: "extendPosition", values: [BytesLike, BigNumberish, BigNumberish, BigNumberish, BytesLike]): string;
     encodeFunctionData(functionFragment: "getExpiredLoanLiquidationThreshold", values: [BytesLike]): string;
     encodeFunctionData(functionFragment: "getPKPLoanParams", values: [BytesLike]): string;
     encodeFunctionData(functionFragment: "getPKPPositionData", values: [BytesLike]): string;
@@ -983,14 +783,7 @@ interface PositionManagerInterface extends Interface {
     encodeFunctionData(functionFragment: "validatePKPLogic", values: [BytesLike]): string;
     encodeFunctionData(functionFragment: "validateUpgrade", values: [AddressLike]): string;
     encodeFunctionData(functionFragment: "views", values?: undefined): string;
-    encodeFunctionData(functionFragment: "withdrawBTC", values: [
-        BytesLike,
-        string,
-        BigNumberish,
-        BigNumberish,
-        BigNumberish,
-        BytesLike
-    ]): string;
+    encodeFunctionData(functionFragment: "withdrawBTC", values: [ICollateralManager.WithdrawalParamsStruct, BytesLike]): string;
     decodeFunctionResult(functionFragment: "ADMIN_ROLE", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "COMMUNITY_FEE_DISTRIBUTOR_ROLE", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "COMMUNITY_MINTER_ROLE", data: BytesLike): Result$2;
@@ -1005,6 +798,7 @@ interface PositionManagerInterface extends Interface {
     decodeFunctionResult(functionFragment: "authorizationRegistry", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "calculateCollateralRatio", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "circuitBreaker", data: BytesLike): Result$2;
+    decodeFunctionResult(functionFragment: "clearExtensionPending", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "collateral", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "commitLiquidation", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "communityManager", data: BytesLike): Result$2;
@@ -1067,6 +861,18 @@ declare namespace CollateralRatioUpdatedEvent {
     type Log = TypedEventLog<Event>;
     type LogDescription = TypedLogDescription<Event>;
 }
+declare namespace ExtensionPendingClearedEvent {
+    type InputTuple = [positionId: BytesLike, clearedBy: AddressLike];
+    type OutputTuple = [positionId: string, clearedBy: string];
+    interface OutputObject {
+        positionId: string;
+        clearedBy: string;
+    }
+    type Event = TypedContractEvent<InputTuple, OutputTuple, OutputObject>;
+    type Filter = TypedDeferredTopicFilter<Event>;
+    type Log = TypedEventLog<Event>;
+    type LogDescription = TypedLogDescription<Event>;
+}
 declare namespace InitializedEvent$1 {
     type InputTuple = [version: BigNumberish];
     type OutputTuple = [version: bigint];
@@ -1453,39 +1259,6 @@ declare namespace UpgradedEvent$1 {
     type Log = TypedEventLog<Event>;
     type LogDescription = TypedLogDescription<Event>;
 }
-declare namespace WithdrawBTCSignatureDebugEvent {
-    type InputTuple = [
-        positionId: BytesLike,
-        messageHash: BytesLike,
-        expectedPkp: AddressLike,
-        recoveredPkp: AddressLike,
-        isValid: boolean,
-        btcPrice: BigNumberish,
-        quantumTimestamp: BigNumberish
-    ];
-    type OutputTuple = [
-        positionId: string,
-        messageHash: string,
-        expectedPkp: string,
-        recoveredPkp: string,
-        isValid: boolean,
-        btcPrice: bigint,
-        quantumTimestamp: bigint
-    ];
-    interface OutputObject {
-        positionId: string;
-        messageHash: string;
-        expectedPkp: string;
-        recoveredPkp: string;
-        isValid: boolean;
-        btcPrice: bigint;
-        quantumTimestamp: bigint;
-    }
-    type Event = TypedContractEvent<InputTuple, OutputTuple, OutputObject>;
-    type Filter = TypedDeferredTopicFilter<Event>;
-    type Log = TypedEventLog<Event>;
-    type LogDescription = TypedLogDescription<Event>;
-}
 interface PositionManager extends BaseContract {
     connect(runner?: ContractRunner | null): PositionManager;
     waitForDeployment(): Promise<this>;
@@ -1510,7 +1283,8 @@ interface PositionManager extends BaseContract {
     VERSION: TypedContractMethod<[], [string], "view">;
     _performExtensionValidation: TypedContractMethod<[
         position: IPositionManagerCore.PositionStruct,
-        selectedTerm: BigNumberish
+        selectedTerm: BigNumberish,
+        btcPrice: BigNumberish
     ], [
         [
             bigint,
@@ -1532,6 +1306,11 @@ interface PositionManager extends BaseContract {
         bigint
     ], "view">;
     circuitBreaker: TypedContractMethod<[], [string], "view">;
+    clearExtensionPending: TypedContractMethod<[
+        positionId: BytesLike
+    ], [
+        void
+    ], "nonpayable">;
     collateral: TypedContractMethod<[], [string], "view">;
     commitLiquidation: TypedContractMethod<[
         positionId: BytesLike,
@@ -1544,7 +1323,8 @@ interface PositionManager extends BaseContract {
     createPosition: TypedContractMethod<[
         pkpId: BytesLike,
         validatorSignature: BytesLike,
-        vaultAddress: string,
+        mainnetVaultAddress: string,
+        regtestVaultAddress: string,
         selectedTermMonths: BigNumberish,
         validatorVersion: BigNumberish
     ], [
@@ -1552,7 +1332,10 @@ interface PositionManager extends BaseContract {
     ], "nonpayable">;
     extendPosition: TypedContractMethod<[
         positionId: BytesLike,
-        selectedTerm: BigNumberish
+        selectedTerm: BigNumberish,
+        quantumTimestamp: BigNumberish,
+        btcPrice: BigNumberish,
+        extensionValidatorSignature: BytesLike
     ], [
         boolean
     ], "nonpayable">;
@@ -1716,11 +1499,7 @@ interface PositionManager extends BaseContract {
     ], "view">;
     views: TypedContractMethod<[], [string], "view">;
     withdrawBTC: TypedContractMethod<[
-        positionId: BytesLike,
-        withdrawalAddress: string,
-        networkFee: BigNumberish,
-        quantumTimestamp: BigNumberish,
-        btcPrice: BigNumberish,
+        params: ICollateralManager.WithdrawalParamsStruct,
         withdrawalValidatorSignature: BytesLike
     ], [
         boolean
@@ -1737,7 +1516,8 @@ interface PositionManager extends BaseContract {
     getFunction(nameOrSignature: "VERSION"): TypedContractMethod<[], [string], "view">;
     getFunction(nameOrSignature: "_performExtensionValidation"): TypedContractMethod<[
         position: IPositionManagerCore.PositionStruct,
-        selectedTerm: BigNumberish
+        selectedTerm: BigNumberish,
+        btcPrice: BigNumberish
     ], [
         [
             bigint,
@@ -1755,6 +1535,7 @@ interface PositionManager extends BaseContract {
     getFunction(nameOrSignature: "authorizationRegistry"): TypedContractMethod<[], [string], "view">;
     getFunction(nameOrSignature: "calculateCollateralRatio"): TypedContractMethod<[positionId: BytesLike], [bigint], "view">;
     getFunction(nameOrSignature: "circuitBreaker"): TypedContractMethod<[], [string], "view">;
+    getFunction(nameOrSignature: "clearExtensionPending"): TypedContractMethod<[positionId: BytesLike], [void], "nonpayable">;
     getFunction(nameOrSignature: "collateral"): TypedContractMethod<[], [string], "view">;
     getFunction(nameOrSignature: "commitLiquidation"): TypedContractMethod<[
         positionId: BytesLike,
@@ -1767,7 +1548,8 @@ interface PositionManager extends BaseContract {
     getFunction(nameOrSignature: "createPosition"): TypedContractMethod<[
         pkpId: BytesLike,
         validatorSignature: BytesLike,
-        vaultAddress: string,
+        mainnetVaultAddress: string,
+        regtestVaultAddress: string,
         selectedTermMonths: BigNumberish,
         validatorVersion: BigNumberish
     ], [
@@ -1775,7 +1557,10 @@ interface PositionManager extends BaseContract {
     ], "nonpayable">;
     getFunction(nameOrSignature: "extendPosition"): TypedContractMethod<[
         positionId: BytesLike,
-        selectedTerm: BigNumberish
+        selectedTerm: BigNumberish,
+        quantumTimestamp: BigNumberish,
+        btcPrice: BigNumberish,
+        extensionValidatorSignature: BytesLike
     ], [
         boolean
     ], "nonpayable">;
@@ -1907,16 +1692,13 @@ interface PositionManager extends BaseContract {
     getFunction(nameOrSignature: "validateUpgrade"): TypedContractMethod<[newImplementation: AddressLike], [boolean], "view">;
     getFunction(nameOrSignature: "views"): TypedContractMethod<[], [string], "view">;
     getFunction(nameOrSignature: "withdrawBTC"): TypedContractMethod<[
-        positionId: BytesLike,
-        withdrawalAddress: string,
-        networkFee: BigNumberish,
-        quantumTimestamp: BigNumberish,
-        btcPrice: BigNumberish,
+        params: ICollateralManager.WithdrawalParamsStruct,
         withdrawalValidatorSignature: BytesLike
     ], [
         boolean
     ], "nonpayable">;
     getEvent(key: "CollateralRatioUpdated"): TypedContractEvent<CollateralRatioUpdatedEvent.InputTuple, CollateralRatioUpdatedEvent.OutputTuple, CollateralRatioUpdatedEvent.OutputObject>;
+    getEvent(key: "ExtensionPendingCleared"): TypedContractEvent<ExtensionPendingClearedEvent.InputTuple, ExtensionPendingClearedEvent.OutputTuple, ExtensionPendingClearedEvent.OutputObject>;
     getEvent(key: "Initialized"): TypedContractEvent<InitializedEvent$1.InputTuple, InitializedEvent$1.OutputTuple, InitializedEvent$1.OutputObject>;
     getEvent(key: "IntegrityCheckFailed"): TypedContractEvent<IntegrityCheckFailedEvent.InputTuple, IntegrityCheckFailedEvent.OutputTuple, IntegrityCheckFailedEvent.OutputObject>;
     getEvent(key: "ModulesUpdatedBatch"): TypedContractEvent<ModulesUpdatedBatchEvent.InputTuple, ModulesUpdatedBatchEvent.OutputTuple, ModulesUpdatedBatchEvent.OutputObject>;
@@ -1937,10 +1719,11 @@ interface PositionManager extends BaseContract {
     getEvent(key: "UCDMinted"): TypedContractEvent<UCDMintedEvent$1.InputTuple, UCDMintedEvent$1.OutputTuple, UCDMintedEvent$1.OutputObject>;
     getEvent(key: "Unpaused"): TypedContractEvent<UnpausedEvent$1.InputTuple, UnpausedEvent$1.OutputTuple, UnpausedEvent$1.OutputObject>;
     getEvent(key: "Upgraded"): TypedContractEvent<UpgradedEvent$1.InputTuple, UpgradedEvent$1.OutputTuple, UpgradedEvent$1.OutputObject>;
-    getEvent(key: "WithdrawBTCSignatureDebug"): TypedContractEvent<WithdrawBTCSignatureDebugEvent.InputTuple, WithdrawBTCSignatureDebugEvent.OutputTuple, WithdrawBTCSignatureDebugEvent.OutputObject>;
     filters: {
         "CollateralRatioUpdated(bytes32,uint256,uint256)": TypedContractEvent<CollateralRatioUpdatedEvent.InputTuple, CollateralRatioUpdatedEvent.OutputTuple, CollateralRatioUpdatedEvent.OutputObject>;
         CollateralRatioUpdated: TypedContractEvent<CollateralRatioUpdatedEvent.InputTuple, CollateralRatioUpdatedEvent.OutputTuple, CollateralRatioUpdatedEvent.OutputObject>;
+        "ExtensionPendingCleared(bytes32,address)": TypedContractEvent<ExtensionPendingClearedEvent.InputTuple, ExtensionPendingClearedEvent.OutputTuple, ExtensionPendingClearedEvent.OutputObject>;
+        ExtensionPendingCleared: TypedContractEvent<ExtensionPendingClearedEvent.InputTuple, ExtensionPendingClearedEvent.OutputTuple, ExtensionPendingClearedEvent.OutputObject>;
         "Initialized(uint64)": TypedContractEvent<InitializedEvent$1.InputTuple, InitializedEvent$1.OutputTuple, InitializedEvent$1.OutputObject>;
         Initialized: TypedContractEvent<InitializedEvent$1.InputTuple, InitializedEvent$1.OutputTuple, InitializedEvent$1.OutputObject>;
         "IntegrityCheckFailed(bytes32,string,string,uint256)": TypedContractEvent<IntegrityCheckFailedEvent.InputTuple, IntegrityCheckFailedEvent.OutputTuple, IntegrityCheckFailedEvent.OutputObject>;
@@ -1981,8 +1764,6 @@ interface PositionManager extends BaseContract {
         Unpaused: TypedContractEvent<UnpausedEvent$1.InputTuple, UnpausedEvent$1.OutputTuple, UnpausedEvent$1.OutputObject>;
         "Upgraded(address)": TypedContractEvent<UpgradedEvent$1.InputTuple, UpgradedEvent$1.OutputTuple, UpgradedEvent$1.OutputObject>;
         Upgraded: TypedContractEvent<UpgradedEvent$1.InputTuple, UpgradedEvent$1.OutputTuple, UpgradedEvent$1.OutputObject>;
-        "WithdrawBTCSignatureDebug(bytes32,bytes32,address,address,bool,uint256,uint256)": TypedContractEvent<WithdrawBTCSignatureDebugEvent.InputTuple, WithdrawBTCSignatureDebugEvent.OutputTuple, WithdrawBTCSignatureDebugEvent.OutputObject>;
-        WithdrawBTCSignatureDebug: TypedContractEvent<WithdrawBTCSignatureDebugEvent.InputTuple, WithdrawBTCSignatureDebugEvent.OutputTuple, WithdrawBTCSignatureDebugEvent.OutputObject>;
     };
 }
 
@@ -2465,8 +2246,17 @@ interface ILiquidationManager extends BaseContract {
 }
 
 interface ILoanOperationsManagerInterface extends Interface {
-    getFunction(nameOrSignature: "calculateCollateralRatio" | "getCurrentBTCPrice" | "getOriginationFeeBalance" | "getPKPActualCollateral" | "getUcdController" | "isPriceFeedStale" | "liquidationThreshold" | "maximumLtvRatio" | "minimumLoanValueWei" | "mintUCD" | "processPartialPayment" | "repayPosition" | "supportsInterface" | "transferOriginationFee" | "ucdToken" | "updatePosition"): FunctionFragment;
+    getFunction(nameOrSignature: "authorizeBTCSpend" | "calculateCollateralRatio" | "getCurrentBTCPrice" | "getOriginationFeeBalance" | "getPKPActualCollateral" | "getUcdController" | "isPriceFeedStale" | "liquidationThreshold" | "maximumLtvRatio" | "minimumLoanValueWei" | "mintUCD" | "processPartialPayment" | "repayPosition" | "supportsInterface" | "transferOriginationFee" | "ucdToken" | "updatePosition"): FunctionFragment;
     getEvent(nameOrSignatureOrTopic: "PositionRepaid" | "PositionUpdated" | "UCDMinted"): EventFragment;
+    encodeFunctionData(functionFragment: "authorizeBTCSpend", values: [
+        BytesLike,
+        string,
+        BigNumberish,
+        BigNumberish,
+        string,
+        BigNumberish,
+        BytesLike
+    ]): string;
     encodeFunctionData(functionFragment: "calculateCollateralRatio", values: [BytesLike]): string;
     encodeFunctionData(functionFragment: "getCurrentBTCPrice", values?: undefined): string;
     encodeFunctionData(functionFragment: "getOriginationFeeBalance", values?: undefined): string;
@@ -2493,6 +2283,7 @@ interface ILoanOperationsManagerInterface extends Interface {
     encodeFunctionData(functionFragment: "transferOriginationFee", values: [AddressLike, BigNumberish]): string;
     encodeFunctionData(functionFragment: "ucdToken", values?: undefined): string;
     encodeFunctionData(functionFragment: "updatePosition", values: [BytesLike, BigNumberish]): string;
+    decodeFunctionResult(functionFragment: "authorizeBTCSpend", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "calculateCollateralRatio", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "getCurrentBTCPrice", data: BytesLike): Result$2;
     decodeFunctionResult(functionFragment: "getOriginationFeeBalance", data: BytesLike): Result$2;
@@ -2586,6 +2377,17 @@ interface ILoanOperationsManager extends BaseContract {
     listeners<TCEvent extends TypedContractEvent>(event: TCEvent): Promise<Array<TypedListener<TCEvent>>>;
     listeners(eventName?: string): Promise<Array<Listener>>;
     removeAllListeners<TCEvent extends TypedContractEvent>(event?: TCEvent): Promise<this>;
+    authorizeBTCSpend: TypedContractMethod<[
+        positionId: BytesLike,
+        txid: string,
+        vout: BigNumberish,
+        satoshis: BigNumberish,
+        targetAddress: string,
+        targetAmount: BigNumberish,
+        litSignature: BytesLike
+    ], [
+        bigint
+    ], "nonpayable">;
     calculateCollateralRatio: TypedContractMethod<[
         positionId: BytesLike
     ], [
@@ -2647,6 +2449,17 @@ interface ILoanOperationsManager extends BaseContract {
         boolean
     ], "nonpayable">;
     getFunction<T extends ContractMethod = ContractMethod>(key: string | FunctionFragment): T;
+    getFunction(nameOrSignature: "authorizeBTCSpend"): TypedContractMethod<[
+        positionId: BytesLike,
+        txid: string,
+        vout: BigNumberish,
+        satoshis: BigNumberish,
+        targetAddress: string,
+        targetAmount: BigNumberish,
+        litSignature: BytesLike
+    ], [
+        bigint
+    ], "nonpayable">;
     getFunction(nameOrSignature: "calculateCollateralRatio"): TypedContractMethod<[positionId: BytesLike], [bigint], "view">;
     getFunction(nameOrSignature: "getCurrentBTCPrice"): TypedContractMethod<[], [bigint], "view">;
     getFunction(nameOrSignature: "getOriginationFeeBalance"): TypedContractMethod<[], [bigint], "view">;
@@ -4148,6 +3961,99 @@ declare class MockTokenManager {
  */
 declare function createMockTokenManager(config: MockTokenManagerConfig): Result$1<MockTokenManager, SDKError>;
 
+/**
+ * Cache Manager Module
+ *
+ * Provides a simple cache factory for SDK modules.
+ * Each cache is an independent LRU cache with TTL support.
+ */
+interface CacheConfig {
+    maxSize: number;
+    ttlMs: number;
+}
+interface CacheStats {
+    size: number;
+    maxSize: number;
+    ttlMs: number;
+}
+/**
+ * Simple LRU Cache with TTL support
+ */
+declare class Cache<T = any> {
+    private cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(config: CacheConfig);
+    /**
+     * Get value from cache
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set value in cache
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Check if key exists in cache
+     */
+    has(key: string): boolean;
+    /**
+     * Delete key from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Clean expired entries
+     */
+    cleanExpired(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    };
+}
+/**
+ * Cache Manager
+ *
+ * Factory for creating named caches with specific configurations
+ */
+declare class CacheManager {
+    private caches;
+    private readonly debug;
+    constructor(config?: {
+        debug?: boolean;
+    });
+    /**
+     * Get or create a cache instance
+     */
+    getCache<T = any>(name: string, config: CacheConfig): Cache<T>;
+    /**
+     * Clear all caches
+     */
+    clearAll(): void;
+    /**
+     * Clean expired entries from all caches
+     */
+    cleanAllExpired(): number;
+    /**
+     * Get statistics for all caches
+     */
+    getAllStats(): Record<string, ReturnType<Cache["getStats"]>>;
+    /**
+     * Destroy cache manager
+     */
+    destroy(): void;
+}
+
+declare function createCacheManager(config?: {
+    debug?: boolean;
+}): CacheManager;
+
 declare enum LoanStatus {
     PENDING_DEPOSIT = 0,
     PENDING_MINT = 1,
@@ -4363,6 +4269,8 @@ interface BTCWithdrawalResult {
     networkFee?: number;
     amountWithdrawn?: string;
     bitcoinTransactionHash?: string;
+    utxoTxid?: string;
+    utxoVout?: number;
     error?: string;
 }
 /**
@@ -4477,6 +4385,18 @@ interface BitcoinBalanceResult {
     timestamp: number;
 }
 
+/**
+ * Bitcoin Operations Module
+ *
+ * Responsible for:
+ * - Deriving Bitcoin addresses from PKP public keys
+ * - Querying Bitcoin balances (with multi-provider consensus)
+ * - Validating Bitcoin transactions
+ * - Caching Bitcoin data for performance
+ *
+ * Uses branded types (Satoshis) for type-safe Bitcoin amounts
+ */
+
 /**
  * Bitcoin network type
  */
@@ -4492,9 +4412,9 @@ interface BitcoinOperationsConfig {
     /** Consensus mode: single or majority */
     consensusMode?: "single" | "majority";
     /** Cache for balance results */
-    balanceCache?: LRUCache<string, BitcoinBalanceResult>;
+    balanceCache?: Cache<BitcoinBalanceResult>;
     /** Cache for address derivations */
-    addressCache?: LRUCache<string, BitcoinAddresses>;
+    addressCache?: Cache<BitcoinAddresses>;
     /** LitOps instance for price oracle queries (optional) */
     litOps?: any;
     /** Signer for LIT Protocol operations (required for getBTCPrice) */
@@ -4641,11 +4561,19 @@ declare class BitcoinOperations {
     /**
      * Get balance cache statistics
      */
-    getBalanceCacheStats(): CacheStats | null;
+    getBalanceCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | null;
     /**
      * Get address cache statistics
      */
-    getAddressCacheStats(): CacheStats | null;
+    getAddressCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | null;
     /**
      * Get current network configuration
      */
@@ -4946,13 +4874,11 @@ declare class DiamondHandsSDK {
     private readonly cacheManager;
     private readonly litOps;
     private readonly pkpManager;
-    private readonly pkpAuthorization;
     private readonly loanCreator;
     private readonly loanQuery;
     private readonly bitcoinOperations;
     private readonly mockTokenManager?;
     private readonly graphClient;
-    private readonly btcWithdrawalCid;
     private isInitialized;
     private isDisposed;
     /**
@@ -5027,64 +4953,6 @@ declare class DiamondHandsSDK {
      * Check if SDK is ready for operations
      */
     private checkInitialized;
-    /**
-     * Pre-validate quantum state before Lit Action execution
-     *
-     * Checks on-chain quantum state to prevent wasted Lit Action executions:
-     * 1. If quantum was already used for this position
-     * 2. Current quantum and safe zone status
-     * 3. Calculates wait time if quantum is already used
-     *
-     * @param positionIdBytes32 - Position ID in bytes32 format
-     * @returns Pre-validation result with canProceed flag and optional wait time
-     */
-    private preValidateQuantumState;
-    /**
-     * Wait for optimal quantum timing before starting LIT Action
-     *
-     * Goal: Start LIT Action execution early in a quantum window to maximize
-     * the chance that contract submission happens within safe window.
-     *
-     * Optimal window: 10-15 seconds into quantum (200s window)
-     * - Narrower window for more predictable timing
-     * - Avoids start dead zone (0-7s)
-     * - Leaves maximum time for LIT Action + submission (up to 185s with 200s window)
-     *
-     * MAX WAIT: 50 seconds to cover full quantum transition without landing in dead zone
-     */
-    private waitForOptimalQuantumTiming;
-    /**
-     * Validate quantum timestamp on-chain before contract call
-     *
-     * Checks:
-     * 1. If quantum was already used for this position
-     * 2. If quantum is in dead zone
-     * 3. If quantum matches current quantum
-     *
-     * @param positionIdBytes32 - Position ID in bytes32 format
-     * @param quantumTimestamp - Quantum timestamp to validate
-     * @returns Validation result with isValid flag and reason if invalid
-     */
-    private validateQuantumOnChain;
-    /**
-     * Ensure we're in a safe quantum window before submitting contract transaction
-     *
-     * Strategy: Be conservative and fail fast if we're too close to dead zones or quantum expired.
-     * This forces the caller to retry with a fresh signature rather than risk hitting dead zone
-     * during transaction submission.
-     *
-     * Safe submission window: 10-150 seconds into quantum (140s window with 200s quantum)
-     * - Avoids start dead zone: 0-9s (extra buffer for clock drift)
-     * - Avoids end dead zone: 192-199s
-     * - 42s buffer before end dead zone accounts for:
-     *   * Network latency to RPC node (1-5s)
-     *   * Clock drift between client and RPC node (up to 70s observed)
-     *   * Gas estimation time (1-3s)
-     *   * Safety margin (5-10s)
-     *
-     * @param targetTimestamp - Target timestamp (may have offset, e.g., quantum + 10)
-     */
-    private ensureSafeQuantum;
     /**
      * Get SDK initialization state
      */
@@ -5111,17 +4979,18 @@ declare class DiamondHandsSDK {
      */
     requestMintUCD(request: UCDMintRequest): Promise<UCDMintResult>;
     /**
-     * Execute UCD mint request (internal implementation)
-     * Separated to enable retry logic
+     * Extend position term
+     *
+     * @param positionId - Position identifier
+     * @param selectedTerm - Extension term in months
+     * @returns Transaction receipt
      */
-    private executeMintUCD;
     /**
      * Make a partial payment on a loan
      *
      * @param request - Partial payment request with position ID and amount
      * @returns Partial payment result with transaction details
      */
-    partPayment(request: PartialPaymentRequest): Promise<PartialPaymentResult>;
     /**
      * Withdraw Bitcoin from a position
      *
@@ -5131,7 +5000,94 @@ declare class DiamondHandsSDK {
      * @param networkFee - Network fee for Bitcoin transaction in satoshis (REQUIRED)
      * @returns Withdrawal result with transaction details
      */
-    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number, networkFee: number): Promise<BTCWithdrawalResult>;
+    /**
+     * Withdraw BTC from position vault
+     *
+     * IMPORTANT: withdrawalAmount is the TOTAL DEDUCTION from vault.
+     * The operator will deduct the actual network fee at execution time.
+     * User receives: withdrawalAmount - actualNetworkFee
+     *
+     * @param positionId - Position identifier
+     * @param withdrawalAddress - Bitcoin address to receive withdrawn funds
+     * @param withdrawalAmount - Total amount to deduct from vault in satoshis (includes fee)
+     * @param customRpcUrl - Optional custom RPC URL for LIT Action (for local testing)
+     * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
+     * @returns Withdrawal result with transaction details
+     */
+    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number, customRpcUrl?: string, customBitcoinRpcUrl?: string): Promise<BTCWithdrawalResult>;
+    /**
+     * Execute Bitcoin withdrawal (Phase 2)
+     *
+     * Signs and broadcasts the Bitcoin transaction for an authorized withdrawal.
+     * User must have previously authorized the withdrawal via withdrawBTC().
+     *
+     * @param request - Execution request with positionId, utxoIdentifier, and networkFee
+     * @returns Execution result with Bitcoin txid
+     */
+    executeBTCWithdrawal(request: {
+        positionId: string;
+        utxoIdentifier: string;
+        networkFee: number;
+        destination: string;
+        customRpcUrl?: string;
+        customBitcoinRpcUrl?: string;
+    }): Promise<{
+        success: boolean;
+        txid?: string;
+        amountSent?: number;
+        networkFee?: number;
+        destination?: string;
+        error?: string;
+    }>;
+    /**
+     * Execute pending Bitcoin transfers
+     *
+     * Queries authorized spends that haven't been broadcast to Bitcoin network yet
+     * and executes them by signing and broadcasting the transactions.
+     *
+     * @param positionId - Position identifier
+     * @param networkFee - Network fee for Bitcoin transaction in satoshis
+     * @param customRpcUrl - Optional custom RPC URL for LIT Action (for local testing)
+     * @returns Array of execution results for each pending transfer
+     */
+    executePendingBtcTransfers(positionId: string, networkFee: number, customRpcUrl?: string): Promise<Array<{
+        success: boolean;
+        utxoIdentifier?: string;
+        txid?: string;
+        amountSent?: number;
+        networkFee?: number;
+        destination?: string;
+        error?: string;
+    }>>;
+    /**
+     * Withdraw BTC and execute transfer (Complete Flow)
+     *
+     * Performs both Phase 1 (authorization) and Phase 2 (execution) in sequence:
+     * 1. Authorizes withdrawal on contract (withdrawBTC)
+     * 2. Executes pending Bitcoin transfers (signs and broadcasts)
+     *
+     * @param positionId - Position identifier
+     * @param withdrawalAddress - Bitcoin address to receive withdrawn funds
+     * @param withdrawalAmount - Total amount to deduct from vault in satoshis
+     * @param networkFee - Network fee for Bitcoin transaction in satoshis
+     * @param customRpcUrl - Optional custom RPC URL for LIT Action (for local testing)
+     * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
+     * @returns Complete withdrawal result with both authorization and execution details
+     */
+    withdrawBTCAndExecute(positionId: string, withdrawalAddress: string, withdrawalAmount: number, networkFee: number, customRpcUrl?: string, customBitcoinRpcUrl?: string): Promise<{
+        success: boolean;
+        authorization?: BTCWithdrawalResult;
+        transfers?: Array<{
+            success: boolean;
+            utxoIdentifier?: string;
+            txid?: string;
+            amountSent?: number;
+            networkFee?: number;
+            destination?: string;
+            error?: string;
+        }>;
+        error?: string;
+    }>;
     /**
      * Get loan data by position ID
      *
@@ -5266,7 +5222,11 @@ declare class DiamondHandsSDK {
     /**
      * Get cache statistics
      */
-    getCacheStats(): Record<string, CacheStats>;
+    getCacheStats(): Record<string, {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    }>;
     /**
      * Get contract manager (for advanced usage)
      */
@@ -5361,7 +5321,7 @@ interface BaseAuthParams {
  * Parameters for creating a new loan/position
  */
 interface CreateLoanAuthParams extends BaseAuthParams {
-    type: 'create';
+    type: "create";
     /** Selected loan term in months (e.g., 12, 24, 36) */
     selectedTerm: number;
     /** Borrower's Ethereum address */
@@ -5373,7 +5333,7 @@ interface CreateLoanAuthParams extends BaseAuthParams {
  * Parameters for minting UCD against existing collateral
  */
 interface MintUCDAuthParams extends BaseAuthParams {
-    type: 'mint';
+    type: "mint";
     /** Position/loan identifier */
     positionId: string;
     /** Amount of UCD to mint (in wei, 18 decimals) */
@@ -5389,15 +5349,13 @@ interface MintUCDAuthParams extends BaseAuthParams {
  * Parameters for withdrawing Bitcoin from vault
  */
 interface WithdrawBTCAuthParams extends BaseAuthParams {
-    type: 'withdraw';
+    type: "withdraw";
     /** Position/loan identifier */
     positionId: string;
     /** Destination Bitcoin address */
     destinationAddress: string;
     /** Amount to withdraw in satoshis */
     amount: Satoshis;
-    /** Network fee for Bitcoin transaction in satoshis */
-    networkFee: Satoshis;
     /** PKP public key */
     publicKey: string;
 }
@@ -5405,7 +5363,7 @@ interface WithdrawBTCAuthParams extends BaseAuthParams {
  * Parameters for repaying UCD debt
  */
 interface RepayDebtAuthParams extends BaseAuthParams {
-    type: 'repay';
+    type: "repay";
     /** Position/loan identifier */
     positionId: string;
     /** Amount of UCD to repay (in wei, 18 decimals) */
@@ -5417,7 +5375,7 @@ interface RepayDebtAuthParams extends BaseAuthParams {
  * Parameters for extending loan term
  */
 interface ExtendTermAuthParams extends BaseAuthParams {
-    type: 'extend';
+    type: "extend";
     /** Position/loan identifier */
     positionId: string;
     /** New term length in months */
@@ -5429,7 +5387,7 @@ interface ExtendTermAuthParams extends BaseAuthParams {
  * Parameters for closing a position
  */
 interface ClosePositionAuthParams extends BaseAuthParams {
-    type: 'close';
+    type: "close";
     /** Position/loan identifier */
     positionId: string;
     /** Final debt amount being repaid */
@@ -5584,6 +5542,20 @@ interface PKPSigningResult {
     publicKey?: string;
 }
 
+/**
+ * PKP Manager Module
+ *
+ * Responsible for:
+ * - Creating new PKPs (via service or direct)
+ * - Querying PKP data from contracts
+ * - Managing PKP lifecycle
+ * - Caching PKP data for performance
+ *
+ * Supports two modes:
+ * - Service mode: Uses lit-ops-server for PKP operations
+ * - Direct mode: Directly interacts with LIT Protocol
+ */
+
 /**
  * PKP Manager configuration
  */
@@ -5599,7 +5571,7 @@ interface PKPManagerConfig {
     /** Direct mode: wallet for PKP operations */
     litOpsWallet?: Wallet;
     /** Optional cache for PKP data */
-    cache?: LRUCache<string, PKPData>;
+    cache?: Cache<PKPData>;
     /** Enable debug logging */
     debug?: boolean;
     /** Timeout for service requests (ms) */
@@ -5691,7 +5663,11 @@ declare class PKPManager {
     /**
      * Get cache statistics
      */
-    getCacheStats(): CacheStats | null;
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | null;
 }
 /**
  * Factory function to create a PKPManager instance
@@ -5728,7 +5704,7 @@ interface LoanCreatorConfig {
     /** Wallet for LIT Protocol operations (Yellowstone signer, capacity credits owner) - standalone mode only */
     litOpsSigner?: Wallet;
     /** SDK mode: 'service' or 'standalone' */
-    mode?: 'service' | 'standalone';
+    mode?: "service" | "standalone";
     /** LIT Action CID for loan creation */
     litActionCid: string;
     /** User ID (typically wallet address) */
@@ -6412,6 +6388,18 @@ declare class DiamondHandsGraph {
 }
 type DiamondHandsGraphClient = DiamondHandsGraph;
 
+/**
+ * Loan Query Module
+ *
+ * Responsible for:
+ * - Querying loan data from subgraph
+ * - Enriching loans with Bitcoin balance data
+ * - Caching query results for performance
+ * - Supporting pagination for large result sets
+ *
+ * Uses the existing DiamondHandsGraphClient for subgraph queries
+ */
+
 /**
  * Loan query filters
  */
@@ -6449,7 +6437,7 @@ interface LoanQueryConfig {
     /** Ethereum provider for PKP public key retrieval */
     provider?: providers.Provider;
     /** Cache for loan query results */
-    cache?: LRUCache<string, LoanData>;
+    cache?: Cache<LoanData>;
     /** Enable debug logging */
     debug?: boolean;
     /** Default page size for pagination */
@@ -6578,7 +6566,11 @@ declare class LoanQuery {
     /**
      * Get cache statistics
      */
-    getCacheStats(): CacheStats | null;
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    } | null;
 }
 /**
  * Factory function to create a LoanQuery instance
@@ -6794,4 +6786,4 @@ declare const DEFAULT_BITCOIN_CONSENSUS_MODE: "majority";
  */
 declare const MIN_BITCOIN_PROVIDERS_FOR_CONSENSUS = 2;
 
-export { AuditTrail, AuthParamsValidation, AuthorizationParams, AuthorizationRequest, AuthorizationResult, BPS, BPSConversions, BTCDepositRequest, BTCDepositResult, BTCProof, BTCTransaction, BTCWithdrawalResult, BasicNetworkConfig, BitcoinAddresses, BitcoinBalanceResult, BitcoinNetwork, BitcoinOperations, BitcoinOperationsConfig, BitcoinProviderConfig, BitcoinUTXO, BlockNumber, CacheConfig, CacheManager, CacheStats, ClosePositionAuthParams, ConfirmationResult, ContractAddresses, ContractCallOptions, ContractManager, ContractManagerConfig, ContractQueryOptions, ContractTransactionResult, CreateLoanAuthParams, CreateLoanRequest, CreateLoanResult, DEFAULT_BALANCE_CACHE_SIZE, DEFAULT_BALANCE_CACHE_TTL_MS, DEFAULT_BITCOIN_CONSENSUS_MODE, DEFAULT_CACHE_CLEANUP_INTERVAL_MS, DEFAULT_CONCURRENCY_LIMIT, DEFAULT_LIT_NETWORKS, DEFAULT_MAX_RETRIES, DEFAULT_NETWORKS, DEFAULT_NETWORK_CONFIG, DEFAULT_OPERATION_TIMEOUT_MS, DEFAULT_PAGINATION_ROWS, DEFAULT_PKP_CACHE_SIZE, DEFAULT_PKP_CACHE_TTL_MS, DebugInfo, DiamondHandsSDK, DiamondHandsSDKConfig, EnrichedBitcoinBalance, EnvironmentName, ErrorCategory, ErrorSeverity, EventFilter, EventHelpers, EventLog, ExtendTermAuthParams, Failure, FeeDistributionEvent, IBTCProof, ILitAction, IPKPManager, IUCDMinting, LRUCache, LiquidationEvent, LiquidationRequest, LitActionAuth, LitActionParams, LitActionResult, LitActionValidationResult, LoanCreationAudit, LoanCreator, LoanCreatorConfig, LoanData, LoanDataDetail, LoanEvents, LoanEventsFilter, LoanManagerConfig, LoanQuery, LoanQueryConfig, LoanQueryFilters, LoanStatus, LoansQuery, MAX_PAGINATION_ROWS, MIN_BITCOIN_PROVIDERS_FOR_CONSENSUS, ManagedContracts, MintUCDAuthParams, MintingParams, MintingResult, MockTokenManager, MockTokenManagerConfig, MockTokenTransactionResult, MonitoringOptions, NETWORK_CONFIGS, NetworkConfig, PKPCreationRequest, PKPCreationResult, PKPData, PKPIssuanceRequest, PKPManager, PKPManagerConfig, PKPSigningRequest, PKPSigningResult, PKPValidationData, PKPValidationRequest, PKPValidationResult, POSITION_MANAGER_ABI, PRICE_FEED_CONSUMER_ABI, PSM_ABI, PSM_MAX_OPERATIONS_PER_WINDOW, PSM_RATE_LIMIT_RESET_BLOCKS, PaginatedLoansResponse, PaginatedResult, Pagination, PaginationParams, PartialPaymentRequest, PartialPaymentResult, PaymentEvent, PaymentType, Position, PositionDetails, PositionQueryOptions, PositionQueryResult, PositionStatus, PositionWithBTCStatus, RepayDebtAuthParams, Result$1 as Result, RetryConfig, RewardDistribution, SDKConfig, SDKError, SDKInitOptions, SDKMode, SDK_DEFAULTS, SDK_ERROR_MESSAGES, Satoshis, SatoshisConversions, ServiceModeConfig, StandaloneModeConfig, StatusUpdateEvent, Success, THE_GRAPH_MAX_BATCH_SIZE, UCD, UCDConversions, UCDMintEvent, UCDMintRequest, UCDMintResult, UCD_TOKEN_ABI, UnixTimestamp, ValidationRequest, Wei, WeiConversions, WithdrawBTCAuthParams, andThen, collectFailures, collectSuccesses, combine, createBitcoinOperations, createCacheManager, createContractManager, createLoanCreator, createLoanQuery, createMockTokenManager, createPKPManager, DiamondHandsSDK as default, envLog, failure, firstSuccess, fromPromise, getAllNetworkConfigs, getCurrentEnvironment, getLitNetworkConfig, getNetworkConfig, getNetworkConfigByName, isClosePositionAuth, isCreateLoanAuth, isExtendTermAuth, isFailure, isMintUCDAuth, isNetworkSupported, isRepayDebtAuth, isServiceModeConfig, isStandaloneModeConfig, isSuccess, isValidPaymentType, isValidPositionStatus, isWithdrawBTCAuth, loadSDKConfig, map, mapError, match, numericToPositionStatus, success, toPromise, tryCatch, tryCatchAsync, unwrap, unwrapOr, validateSDKConfig, validateSDKEnvironment, validateServiceModeConfig, validateStandaloneModeConfig };
+export { AuditTrail, AuthParamsValidation, AuthorizationParams, AuthorizationRequest, AuthorizationResult, BPS, BPSConversions, BTCDepositRequest, BTCDepositResult, BTCProof, BTCTransaction, BTCWithdrawalResult, BasicNetworkConfig, BitcoinAddresses, BitcoinBalanceResult, BitcoinNetwork, BitcoinOperations, BitcoinOperationsConfig, BitcoinProviderConfig, BitcoinUTXO, BlockNumber, CacheConfig, CacheManager, CacheStats, ClosePositionAuthParams, ConfirmationResult, ContractAddresses, ContractCallOptions, ContractManager, ContractManagerConfig, ContractQueryOptions, ContractTransactionResult, CreateLoanAuthParams, CreateLoanRequest, CreateLoanResult, DEFAULT_BALANCE_CACHE_SIZE, DEFAULT_BALANCE_CACHE_TTL_MS, DEFAULT_BITCOIN_CONSENSUS_MODE, DEFAULT_CACHE_CLEANUP_INTERVAL_MS, DEFAULT_CONCURRENCY_LIMIT, DEFAULT_LIT_NETWORKS, DEFAULT_MAX_RETRIES, DEFAULT_NETWORKS, DEFAULT_NETWORK_CONFIG, DEFAULT_OPERATION_TIMEOUT_MS, DEFAULT_PAGINATION_ROWS, DEFAULT_PKP_CACHE_SIZE, DEFAULT_PKP_CACHE_TTL_MS, DebugInfo, DiamondHandsSDK, DiamondHandsSDKConfig, EnrichedBitcoinBalance, EnvironmentName, ErrorCategory, ErrorSeverity, EventFilter, EventHelpers, EventLog, ExtendTermAuthParams, Failure, FeeDistributionEvent, IBTCProof, ILitAction, IPKPManager, IUCDMinting, Cache as LRUCache, LiquidationEvent, LiquidationRequest, LitActionAuth, LitActionParams, LitActionResult, LitActionValidationResult, LoanCreationAudit, LoanCreator, LoanCreatorConfig, LoanData, LoanDataDetail, LoanEvents, LoanEventsFilter, LoanManagerConfig, LoanQuery, LoanQueryConfig, LoanQueryFilters, LoanStatus, LoansQuery, MAX_PAGINATION_ROWS, MIN_BITCOIN_PROVIDERS_FOR_CONSENSUS, ManagedContracts, MintUCDAuthParams, MintingParams, MintingResult, MockTokenManager, MockTokenManagerConfig, MockTokenTransactionResult, MonitoringOptions, NETWORK_CONFIGS, NetworkConfig, PKPCreationRequest, PKPCreationResult, PKPData, PKPIssuanceRequest, PKPManager, PKPManagerConfig, PKPSigningRequest, PKPSigningResult, PKPValidationData, PKPValidationRequest, PKPValidationResult, POSITION_MANAGER_ABI, PRICE_FEED_CONSUMER_ABI, PSM_ABI, PSM_MAX_OPERATIONS_PER_WINDOW, PSM_RATE_LIMIT_RESET_BLOCKS, PaginatedLoansResponse, PaginatedResult, Pagination, PaginationParams, PartialPaymentRequest, PartialPaymentResult, PaymentEvent, PaymentType, Position, PositionDetails, PositionQueryOptions, PositionQueryResult, PositionStatus, PositionWithBTCStatus, PriceProviderConfig, RepayDebtAuthParams, Result$1 as Result, RetryConfig, RewardDistribution, SDKConfig, SDKError, SDKInitOptions, SDKMode, SDK_DEFAULTS, SDK_ERROR_MESSAGES, Satoshis, SatoshisConversions, ServiceModeConfig, StandaloneModeConfig, StatusUpdateEvent, Success, THE_GRAPH_MAX_BATCH_SIZE, UCD, UCDConversions, UCDMintEvent, UCDMintRequest, UCDMintResult, UCD_TOKEN_ABI, UnixTimestamp, ValidationRequest, Wei, WeiConversions, WithdrawBTCAuthParams, andThen, collectFailures, collectSuccesses, combine, createBitcoinOperations, createCacheManager, createContractManager, createLoanCreator, createLoanQuery, createMockTokenManager, createPKPManager, DiamondHandsSDK as default, envLog, failure, firstSuccess, fromPromise, getAllNetworkConfigs, getCurrentEnvironment, getLitNetworkConfig, getNetworkConfig, getNetworkConfigByName, isClosePositionAuth, isCreateLoanAuth, isExtendTermAuth, isFailure, isMintUCDAuth, isNetworkSupported, isRepayDebtAuth, isServiceModeConfig, isStandaloneModeConfig, isSuccess, isValidPaymentType, isValidPositionStatus, isWithdrawBTCAuth, loadSDKConfig, map, mapError, match, numericToPositionStatus, success, toPromise, tryCatch, tryCatchAsync, unwrap, unwrapOr, validateSDKConfig, validateSDKEnvironment, validateServiceModeConfig, validateStandaloneModeConfig };