@gvnrdao/dh-sdk 0.0.288 → 0.0.289

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,270 @@
+/**
+ * SDK Configuration Interfaces
+ */
+import type { Wallet, Signer, Provider } 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;
+    /** ContractVersionRegistry proxy; used for cross-contract version pinning. */
+    contractVersionRegistry?: string;
+    /** FeeRecipientRegistry proxy; M-8 fix — allowlist consulted by LoanOperationsManager.transferFee and SimplePSMV2.transferFee. */
+    feeRecipientRegistry?: string;
+    /** PositionDelegateRegistry proxy; consumed by LIT Action authorization verifier as the third recovery arm for Safe-as-borrower flows. */
+    positionDelegateRegistry?: string;
+    /** BitcoinWithdrawalAddressRegistry proxy; per-wallet allowlist that gates borrower-initiated BTC withdrawal destinations (24h time-lock). */
+    bitcoinWithdrawalAddressRegistry?: string;
+    mockUsdcToken?: string;
+    mockUsdcOwner?: string;
+    mockUsdtToken?: string;
+    mockUsdtOwner?: string;
+}
+/**
+ * Base configuration shared by all SDK modes
+ */
+interface BaseSDKConfig {
+    litNetwork?: LitNetwork;
+    contractSigner?: Wallet | Signer;
+    /**
+     * Optional signer used exclusively for EIP-712 server-session login.
+     * When provided, `ServerSession` uses this instead of `contractSigner` so
+     * the two concerns (auth identity vs on-chain msg.sender) can differ. In
+     * Safe mode the CLI passes the raw agent EOA here while `contractSigner`
+     * is a SafeModuleSignerAdapter that routes transactions through the module.
+     */
+    authSigner?: Wallet | Signer;
+    ethRpcUrl?: string;
+    chainId?: number;
+    networkOverride?: {
+        chainId: number;
+        name: string;
+    };
+    provider?: Provider;
+    chain?: string;
+    bitcoinNetwork?: "mainnet" | "testnet" | "regtest";
+    litActionCid?: string;
+    litNodeConnectTimeoutMs?: number;
+    subgraphUrl?: string;
+    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;
+    /** Notification label for server Telegram notifications. Default: "DH SDK". Set "DH APP" in the web app. */
+    callerLabel?: string;
+    /**
+     * 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;
+    temperSignaturesTest?: boolean;
+    /**
+     * Optional in-process notification sink invoked alongside the existing service-mode
+     * HTTP relay. Fires in BOTH `standalone` and `service` mode so consumers can observe
+     * lifecycle events (e.g. loan renewal, mint, payment, withdrawal) without depending
+     * on `lit-ops-server`. The SDK already emits messages via `formatLoan*Message` helpers
+     * — this hook just exposes them locally. Errors thrown by the handler are swallowed
+     * so notification failures cannot break business operations.
+     *
+     * @example
+     *   const notifications: string[] = [];
+     *   sdkConfig.notificationHandler = (msg) => { notifications.push(msg); };
+     */
+    notificationHandler?: (message: string) => void | Promise<void>;
+}
+/**
+ * Service Mode Configuration
+ * Uses lit-ops-server for PKP operations
+ */
+export interface ServiceModeConfig extends BaseSDKConfig {
+    mode: "service";
+    serviceEndpoint: string;
+    litOpsSigner?: never;
+}
+/**
+ * Standalone Mode Configuration
+ * User provides signer for direct LIT operations
+ */
+export interface StandaloneModeConfig extends BaseSDKConfig {
+    mode: "standalone";
+    litOpsSigner: Wallet;
+    serviceEndpoint?: 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;
+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?: 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;
+    pkpId?: string;
+    apiKey?: string;
+    apiSecret?: string;
+}
+export {};

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

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