@gvnrdao/dh-sdk 0.0.166 → 0.0.205

package/dist/types/result.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Result type for standardized error handling across the SDK
+ *
+ * This is a discriminated union that provides type-safe error handling
+ * without throwing exceptions. Inspired by Rust's Result<T, E> type.
+ *
+ * @example
+ * ```typescript
+ * async function createLoan(request: CreateLoanRequest): Promise<Result<LoanData, SDKError>> {
+ *   try {
+ *     const loan = await performCreation(request);
+ *     return success(loan);
+ *   } catch (error) {
+ *     return failure(SDKError.from(error));
+ *   }
+ * }
+ *
+ * // Usage
+ * const result = await createLoan(request);
+ * if (result.success) {
+ *   console.log('Loan created:', result.value);
+ * } else {
+ *   console.error('Failed:', result.error);
+ * }
+ * ```
+ */
+/**
+ * Success variant of Result<T, E>
+ */
+export interface Success<T> {
+    success: true;
+    value: T;
+}
+/**
+ * Failure variant of Result<T, E>
+ */
+export interface Failure<E> {
+    success: false;
+    error: E;
+}
+/**
+ * Result type - either Success<T> or Failure<E>
+ */
+export type Result<T, E = Error> = Success<T> | Failure<E>;
+/**
+ * Creates a successful Result
+ */
+export declare function success<T>(value: T): Success<T>;
+/**
+ * Creates a failed Result
+ */
+export declare function failure<E>(error: E): Failure<E>;
+/**
+ * Type guard to check if Result is successful
+ */
+export declare function isSuccess<T, E>(result: Result<T, E>): result is Success<T>;
+/**
+ * Type guard to check if Result is a failure
+ */
+export declare function isFailure<T, E>(result: Result<T, E>): result is Failure<E>;
+/**
+ * Unwraps a Result, returning the value or throwing the error
+ */
+export declare function unwrap<T, E extends Error>(result: Result<T, E>): T;
+/**
+ * Unwraps a Result, returning the value or a default
+ */
+export declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+/**
+ * Maps a Result<T, E> to Result<U, E> by applying a function to the success value
+ */
+export declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/**
+ * Maps a Result<T, E> to Result<T, F> by applying a function to the error value
+ */
+export declare function mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/**
+ * Chains Result-returning operations together (flatMap)
+ */
+export declare function andThen<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+/**
+ * Returns the first successful Result, or the last error if all fail
+ */
+export declare function firstSuccess<T, E>(results: Result<T, E>[]): Result<T, E>;
+/**
+ * Collects all successful Results into an array
+ */
+export declare function collectSuccesses<T, E>(results: Result<T, E>[]): T[];
+/**
+ * Collects all failures into an array
+ */
+export declare function collectFailures<T, E>(results: Result<T, E>[]): E[];
+/**
+ * Combines multiple Results into a single Result containing an array
+ * If any Result fails, returns the first failure
+ */
+export declare function combine<T, E>(results: Result<T, E>[]): Result<T[], E>;
+/**
+ * Wraps an async function that may throw into one that returns a Result
+ */
+export declare function tryCatch<T, E = Error>(fn: () => T, errorHandler?: (error: unknown) => E): Result<T, E>;
+/**
+ * Async version of tryCatch
+ */
+export declare function tryCatchAsync<T, E = Error>(fn: () => Promise<T>, errorHandler?: (error: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Converts a Result to a Promise that rejects on failure
+ */
+export declare function toPromise<T, E extends Error>(result: Result<T, E>): Promise<T>;
+/**
+ * Converts a Promise to a Result (will never reject)
+ */
+export declare function fromPromise<T, E = Error>(promise: Promise<T>, errorHandler?: (error: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Utility to match on a Result and handle both cases
+ */
+export declare function match<T, E, U>(result: Result<T, E>, handlers: {
+    success: (value: T) => U;
+    failure: (error: E) => U;
+}): U;

package/dist/utils/bitcoin-address-cache.utils.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Bitcoin Address Derivation Cache Utility
+ * Implements LRU (Least Recently Used) caching for Bitcoin address derivation from PKP
+ * Avoids repeated SHA256+RIPEMD160 operations for the same PKP ID
+ */
+import type { BitcoinAddresses } from '../interfaces';
+/**
+ * Cache statistics
+ */
+export interface AddressCacheStats {
+    size: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+    hitRate: number;
+}
+/**
+ * Address cache configuration
+ */
+export interface AddressCacheConfig {
+    maxSize?: number;
+    ttlMs?: number;
+    debug?: boolean;
+}
+/**
+ * LRU Cache for Bitcoin address derivation
+ *
+ * Features:
+ * - TTL-based expiration
+ * - LRU eviction when max size reached
+ * - Hit/miss statistics tracking
+ * - Memory-efficient (stores only PKP ID and derived addresses)
+ */
+export declare class BitcoinAddressCache {
+    private cache;
+    private maxSize;
+    private ttlMs;
+    private debug;
+    private stats;
+    constructor(config?: AddressCacheConfig);
+    /**
+     * Get addresses from cache
+     * Returns null if not found or expired
+     */
+    get(pkpId: string): BitcoinAddresses | null;
+    /**
+     * Set addresses in cache
+     * Evicts LRU entry if cache is full
+     */
+    set(pkpId: string, value: BitcoinAddresses): void;
+    /**
+     * Check if entry is expired
+     */
+    private isExpired;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): AddressCacheStats;
+    /**
+     * Get cache size
+     */
+    size(): number;
+    /**
+     * Check if cache has entry
+     */
+    has(pkpId: string): boolean;
+    /**
+     * Delete specific entry
+     */
+    delete(pkpId: string): boolean;
+    /**
+     * Get all cached PKP IDs (for debugging)
+     */
+    getKeys(): string[];
+    /**
+     * Clean expired entries
+     */
+    cleanExpired(): number;
+}

package/dist/utils/bitcoin-provider.utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Bitcoin Provider Utilities
+ * Handles multi-provider consensus for Bitcoin blockchain queries
+ */
+import type { BitcoinProviderConfig } from '../interfaces/chunks/config.i';
+import type { BitcoinBalanceResult } from '../interfaces/chunks/position-query.i';
+/**
+ * Bitcoin Provider with consensus support
+ */
+export declare class BitcoinProvider {
+    private providers;
+    private consensusMode;
+    private debug;
+    constructor(configs: BitcoinProviderConfig[], consensusMode?: 'single' | 'majority', debug?: boolean);
+    /**
+     * Get UTXOs for a Bitcoin address with consensus
+     */
+    getUnspentsFor(address: string): Promise<BitcoinBalanceResult>;
+    /**
+     * Get UTXOs from a single provider
+     */
+    private getUnspentsSingle;
+    /**
+     * Check if a provider error is retryable
+     */
+    private isRetryableProviderError;
+    /**
+     * Get UTXOs with 2-of-3 consensus
+     */
+    private getUnspentsWithConsensus;
+    /**
+     * Find consensus among multiple provider results
+     */
+    private findConsensus;
+    /**
+     * Create a signature for a UTXO set (for comparison)
+     */
+    private getUTXOSetSignature;
+    private fetchUtxosFromProvider;
+    /**
+     * Get balance for an address (sum of UTXOs)
+     */
+    getBalance(address: string): Promise<bigint>;
+    /**
+     * Check if an address has received at least a specific amount
+     */
+    hasReceivedAmount(address: string, expectedAmount: bigint): Promise<boolean>;
+}

package/dist/utils/bitcoin-signature.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bitcoin Signature Utilities
+ *
+ * Converts Ethereum ECDSA signatures to Bitcoin DER format
+ *
+ * Trusted implementation from btc-always-signer.test.ts
+ */
+/**
+ * Convert Ethereum signature to Bitcoin DER format
+ *
+ * Handles BIP 62 normalization (low-s requirement) and DER encoding
+ *
+ * @param signature - Ethereum signature (hex string or {r, s, v} object)
+ * @returns DER-encoded signature as hex string
+ */
+export declare function convertEthereumSignatureToBitcoinDER(signature: string | {
+    r: string;
+    s: string;
+    v?: number;
+}): string;

package/dist/utils/chunks/bitcoin-utils.d.ts

@@ -0,0 +1,75 @@
+import { BitcoinAddressCache } from "../bitcoin-address-cache.utils";
+import type { BitcoinAddresses } from "../../interfaces";
+/**
+ * Initialize the global address cache with sensible defaults
+ */
+export declare function initializeAddressCache(config?: {
+    maxSize?: number;
+    ttlMs?: number;
+    debug?: boolean;
+}): void;
+/**
+ * Get the global address cache instance
+ */
+export declare function getAddressCache(): BitcoinAddressCache | null;
+/**
+ * Convert hex string to Uint8Array
+ * @param hexString Hex string
+ * @returns Uint8Array
+ */
+export declare const hexToUint8Array: (hexString: string) => Uint8Array;
+/**
+ * SHA256 hash using Node.js crypto module
+ * @param data Uint8Array
+ * @returns Uint8Array
+ */
+export declare const sha256: (data: Uint8Array) => Uint8Array;
+/**
+ * RIPEMD160 hash using native Web Crypto API
+ * @param data Uint8Array
+ * @returns Promise<Uint8Array>
+ */
+export declare const ripemd160: (data: Uint8Array) => Uint8Array;
+/**
+ * Convert CryptoJS WordArray to Uint8Array (fallback for RIPEMD160)
+ * @param wordArray CryptoJS WordArray
+ * @returns Uint8Array
+ */
+export declare const wordArrayToUint8Array: (wordArray: any) => Uint8Array;
+/**
+ * Generate a Bitcoin address from a PKP public key for regtest or mainnet.
+ * @param pkpPublicKey Hex string public key (with or without '0x' prefix)
+ * @param network "regtest" | "mainnet" | "testnet"
+ * @returns Bitcoin address (string)
+ */
+export declare function getBitcoinAddressFromPkp(pkpPublicKey: string, network?: "regtest" | "mainnet" | "testnet"): Promise<string>;
+/**
+ * Generate multiple Bitcoin addresses from a PKP public key for different networks.
+ * Uses caching to avoid repeated SHA256+RIPEMD160 operations for the same PKP ID.
+ * @param pkpPublicKey Hex string public key (with or without '0x' prefix)
+ * @returns Object containing addresses for different networks
+ */
+export declare function getBitcoinAddressesFromPkp(pkpPublicKey: string): Promise<BitcoinAddresses>;
+export declare class BitcoinUtils {
+    static validateAddress(address: string): boolean;
+    static formatTransaction(hash: string, amount: string, recipient: string): {
+        hash: string;
+        amount: string;
+        recipient: string;
+        timestamp: number;
+    };
+    static calculateFee(inputAmount: string, outputAmount: string): string;
+    /**
+     * Generate Bitcoin addresses from PKP public key
+     * @param pkpPublicKey PKP public key
+     * @param network Bitcoin network
+     * @returns Bitcoin address
+     */
+    static getBitcoinAddress(pkpPublicKey: string, network?: "regtest" | "mainnet" | "testnet"): Promise<string>;
+    /**
+     * Generate Bitcoin addresses for all networks
+     * @param pkpPublicKey PKP public key
+     * @returns Object with addresses for all networks
+     */
+    static getAllBitcoinAddresses(pkpPublicKey: string): Promise<BitcoinAddresses>;
+}

package/dist/utils/chunks/eip1559-broadcast.utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * EIP-1559 transaction broadcast helpers for paths that need explicit gas limits
+ * (e.g. large mintUCD) without manual signDigest / eth_sendRawTransaction.
+ */
+import { ethers as ethers5 } from "ethers";
+import type { BigNumber, providers, Signer } from "ethers";
+/** Observed mintUCD + LIT validation can exceed 7M gas; cap avoids block limit issues. */
+export declare const MINT_UCD_GAS_CEILING: ethers5.BigNumber;
+/** Headroom on eth_estimateGas (25%). */
+export declare const MINT_UCD_ESTIMATE_MARGIN_BPS = 2500;
+/**
+ * Returns gas limit with margin, capped, or null if estimateGas reverts/fails.
+ */
+export declare function estimateContractCallGasWithMargin(provider: providers.Provider, from: string, to: string, data: string, marginBps: number, ceiling: BigNumber): Promise<BigNumber | null>;
+export declare function resolveEip1559FeeFields(provider: providers.Provider): Promise<{
+    maxFeePerGas: BigNumber;
+    maxPriorityFeePerGas: BigNumber;
+}>;
+export declare function sendEip1559Transaction(params: {
+    signer: Signer;
+    to: string;
+    data: string;
+    gasLimit: BigNumber;
+}): Promise<ethers5.providers.TransactionResponse>;

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Production-Ready Error Handler for PKP Validation and Loan Creation
+ */
+/**
+ * Error categories for SDK operations
+ */
+export 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
+ */
+export declare enum ErrorSeverity {
+    LOW = "LOW",
+    MEDIUM = "MEDIUM",
+    HIGH = "HIGH",
+    CRITICAL = "CRITICAL"
+}
+/**
+ * Modern SDK Error class with structured error handling
+ */
+export declare class SDKError extends Error {
+    readonly code: string;
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly retryable: boolean;
+    readonly context?: Record<string, unknown>;
+    readonly originalError?: Error;
+    readonly cause?: unknown;
+    readonly timestamp: number;
+    constructor(params: {
+        code?: string;
+        message: string;
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        retryable?: boolean;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+        cause?: unknown;
+    });
+    /**
+     * Convert to JSON-serializable format
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        retryable: boolean;
+        context: Record<string, unknown> | undefined;
+        timestamp: number;
+        stack: string | undefined;
+    };
+}
+export interface ErrorContext {
+    operation: string;
+    network: string;
+    timestamp: number;
+    attemptNumber?: number;
+    duration?: number;
+    additionalInfo?: Record<string, any>;
+}
+export interface PKPValidationError {
+    code: string;
+    message: string;
+    context: ErrorContext;
+    severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    retryable: boolean;
+    userMessage?: string;
+}
+export declare class PKPErrorHandler {
+    static classifyError(error: any, context: ErrorContext): PKPValidationError;
+    static shouldRetry(error: PKPValidationError, attemptNumber: number, maxAttempts: number): boolean;
+    static getRetryDelay(error: PKPValidationError, attemptNumber: number): number;
+    static logError(error: PKPValidationError, context?: {
+        userId?: string;
+        sessionId?: string;
+    }): {
+        timestamp: string;
+        errorCode: string;
+        severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+        operation: string;
+        network: string;
+        attemptNumber: number | undefined;
+        duration: number | undefined;
+        retryable: boolean;
+        message: string;
+        userId: string | undefined;
+        sessionId: string | undefined;
+    };
+    static createUserFriendlyMessage(error: PKPValidationError, context?: {
+        isRetrying?: boolean;
+    }): string;
+}

package/dist/utils/ethers-interop.utils.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Ethers v5/v6 Interop Utilities
+ * Systematic normalization of BigNumber fields for cross-version compatibility
+ */
+/**
+ * Normalize a single BigNumberish value to string
+ * Handles ethers v5 BigNumber, native bigint, hex strings, and numbers
+ * @param value BigNumberish value to normalize
+ * @returns Normalized string representation
+ */
+export declare function normalizeBigNumberish(value: unknown): string;
+/**
+ * Normalize transaction receipt for cross-version compatibility
+ * Converts all BigNumber fields to strings
+ * @param receipt Transaction receipt to normalize
+ * @returns Normalized transaction receipt
+ */
+export declare function normalizeTransactionReceipt(receipt: unknown): Record<string, unknown> | null | undefined;
+/**
+ * Normalize transaction response for cross-version compatibility
+ * Converts all BigNumber fields to strings and preserves methods
+ * @param tx Transaction response to normalize
+ * @returns Normalized transaction response
+ */
+export declare function normalizeTransactionResponse(tx: unknown): Record<string, unknown> | null | undefined;
+/**
+ * Normalize contract method result for cross-version compatibility
+ * Recursively converts all BigNumber fields to strings
+ * @param result Contract method result to normalize
+ * @returns Normalized result
+ */
+export declare function normalizeContractResult(result: unknown): unknown;
+/**
+ * Normalize event logs for cross-version compatibility
+ * @param logs Array of event logs to normalize
+ * @returns Normalized logs
+ */
+export declare function normalizeLogs(logs: unknown): unknown[] | unknown;
+/**
+ * Normalize loan data for cross-version compatibility
+ * Specifically handles loan-related BigNumber fields
+ * @param loanData Loan data to normalize
+ * @returns Normalized loan data
+ */
+export declare function normalizeLoanData(loanData: unknown): Record<string, unknown> | null | undefined;
+/**
+ * Normalize position data for cross-version compatibility
+ * Specifically handles position-related BigNumber fields
+ * @param positionData Position data to normalize
+ * @returns Normalized position data
+ */
+export declare function normalizePositionData(positionData: unknown): Record<string, unknown> | null | undefined;
+/**
+ * Create a comprehensive normalizer for any data structure
+ * Automatically detects and normalizes BigNumber fields
+ * @param data Data to normalize
+ * @returns Normalized data
+ */
+export declare function normalizeForEthersInterop(data: unknown): unknown;
+/**
+ * BigInt Utility Functions for Ethers v6 Compatibility
+ * Native bigint doesn't have methods like BigNumber did in ethers v5
+ */
+/**
+ * Convert bigint to number (like BigNumber.toNumber())
+ * @param value bigint value
+ * @returns number representation
+ * @throws if value is too large for safe integer
+ */
+export declare function toNumber(value: bigint): number;
+/**
+ * Greater than comparison (like BigNumber.gt())
+ * @param a First value
+ * @param b Second value
+ * @returns true if a > b
+ */
+export declare function gt(a: bigint, b: bigint): boolean;
+/**
+ * Less than comparison (like BigNumber.lt())
+ * @param a First value
+ * @param b Second value
+ * @returns true if a < b
+ */
+export declare function lt(a: bigint, b: bigint): boolean;
+/**
+ * Addition (like BigNumber.add())
+ * @param a First value
+ * @param b Second value
+ * @returns Sum of a and b
+ */
+export declare function add(a: bigint, b: bigint): bigint;
+/**
+ * Subtraction (like BigNumber.sub())
+ * @param a First value
+ * @param b Second value
+ * @returns Difference of a and b
+ */
+export declare function sub(a: bigint, b: bigint): bigint;
+/**
+ * Multiplication (like BigNumber.mul())
+ * @param a First value
+ * @param b Second value
+ * @returns Product of a and b
+ */
+export declare function mul(a: bigint, b: bigint): bigint;
+/**
+ * Division (like BigNumber.div())
+ * @param a First value
+ * @param b Second value
+ * @returns Quotient of a and b
+ */
+export declare function div(a: bigint, b: bigint): bigint;
+/**
+ * Equals comparison (like BigNumber.eq())
+ * @param a First value
+ * @param b Second value
+ * @returns true if a equals b
+ */
+export declare function eq(a: bigint, b: bigint): boolean;
+/**
+ * Safe wait for transaction confirmation with ethers v5/v6 compatibility
+ *
+ * The issue: ethers v5 uses receipt.confirmations() as a function
+ * while ethers v6 uses receipt.confirmations as a property (number).
+ * When v5 and v6 are mixed in the dependency tree, the internal
+ * polling mechanism can fail with "receipt.confirmations is not a function".
+ *
+ * This wrapper provides a safe way to wait for transactions that handles
+ * the version incompatibility gracefully.
+ *
+ * @param tx Transaction response with wait() method
+ * @param confirmations Number of confirmations to wait for (default: 1)
+ * @param timeout Timeout in milliseconds (default: 60000)
+ * @returns Normalized transaction receipt
+ */
+export declare function safeWaitForTransaction(tx: {
+    wait?: (confirmations?: number) => Promise<unknown>;
+    hash?: string;
+    provider?: unknown;
+}, confirmations?: number, timeout?: number): Promise<Record<string, unknown>>;
+/**
+ * Check if an error is related to ethers v5/v6 compatibility issues
+ * @param error Error to check
+ * @returns true if this is an ethers compatibility error
+ */
+export declare function isEthersCompatibilityError(error: unknown): boolean;

package/dist/utils/extend-authorization.utils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Extend Position Authorization Utilities
+ *
+ * Generates authorization signatures for extend position requests
+ * that can be verified by the extend-position-validator LIT Action.
+ */
+import { ethers as ethers5 } from "ethers";
+/**
+ * Extend Owner Authorization Interface (matches lit-actions)
+ */
+export interface ExtendOwnerAuthorization {
+    positionId: string;
+    timestamp: number;
+    chainId: number;
+    newTerm: number;
+    action: string;
+    signature: string;
+    callerAddress: string;
+}
+/**
+ * Build the extend authorization message hash without signing.
+ *
+ * Use this when signing with a smart contract wallet (e.g. Safe) that
+ * needs to wrap the hash in its own domain before signing.
+ *
+ * @param positionId - Position identifier
+ * @param newTerm - Extension term in months (number)
+ * @param chainId - Chain ID for cross-chain replay protection
+ * @returns { hash, timestamp } — pass these to Safe for signing
+ */
+export declare function buildExtendAuthorizationHash(positionId: string, newTerm: number, chainId: number): {
+    hash: string;
+    timestamp: number;
+};
+/**
+ * Generate extend position authorization signature
+ *
+ * Creates a signature that matches the format expected by
+ * AuthorizationModule.verifyExtendAuthorization in lit-actions.
+ *
+ * Message structure:
+ * solidityKeccak256(
+ *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
+ *   [positionId, timestamp, chainId, newTerm, actionHash]
+ * )
+ *
+ * Where:
+ * - actionHash = keccak256("extend-position")
+ * - Signer address is recovered from signature by LIT Action
+ * - LIT Action validates recovered address === position owner
+ *
+ * @param positionId - Position identifier
+ * @param newTerm - Extension term in months (number)
+ * @param chainId - Chain ID for cross-chain replay protection
+ * @param signerOrPrecomputed - Either an ethers Wallet (EOA) or { timestamp, signature } for smart contract wallets
+ * @returns Authorization object with signature
+ */
+export declare function generateExtendAuthorization(positionId: string, newTerm: number, chainId: number, signerOrPrecomputed: ethers5.Wallet | {
+    timestamp: number;
+    signature: string;
+}): Promise<ExtendOwnerAuthorization>;