@gvnrdao/dh-sdk 0.0.288 → 0.0.289

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

@@ -0,0 +1,248 @@
+/**
+ * UCD Mint Authorization Utilities
+ *
+ * Generates authorization signatures for UCD mint requests
+ * that can be verified by the ucd-mint-validator LIT Action.
+ * Also includes withdrawal authorization utilities.
+ */
+import { type Provider, type Signer } from "ethers";
+/**
+ * Owner Authorization Interface (matches lit-actions)
+ */
+export interface MintOwnerAuthorization {
+    positionId: string;
+    timestamp: number;
+    chainId: number;
+    amount: string;
+    action: string;
+    signature: string;
+}
+/**
+ * Build the mint 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.
+ *
+ * Returns the raw hash AND the timestamp so both can be passed to
+ * generateMintAuthorization via the pre-computed signature overload.
+ *
+ * @param positionId - Position identifier
+ * @param amount - Amount to mint in wei (bigint)
+ * @param chainId - Chain ID for cross-chain replay protection
+ * @returns { hash, timestamp } — pass these to Safe for signing
+ */
+export declare function buildMintAuthorizationHash(positionId: string, amount: bigint, chainId: number): {
+    hash: string;
+    timestamp: number;
+};
+/**
+ * Generate mint authorization signature
+ *
+ * Creates a signature that matches the format expected by
+ * AuthorizationModule.verifyMintAuthorization in lit-actions.
+ *
+ * Message structure:
+ * solidityKeccak256(
+ *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
+ *   [positionId, timestamp, chainId, amount, actionHash]
+ * )
+ *
+ * Where:
+ * - actionHash = keccak256("mint-ucd")
+ * - Signer address is recovered from signature by LIT Action
+ * - LIT Action validates recovered address === position owner
+ *
+ * @param positionId - Position identifier
+ * @param amount - Amount to mint in wei (bigint)
+ * @param chainId - Chain ID for cross-chain replay protection
+ * @param signerOrPrecomputed - Either an ethers Signer (EOA) or { timestamp, signature } for smart contract wallets
+ * @returns Authorization object with signature
+ */
+export declare function generateMintAuthorization(positionId: string, amount: bigint, chainId: number, signerOrPrecomputed: Signer | {
+    timestamp: number;
+    signature: string;
+}): Promise<MintOwnerAuthorization>;
+/**
+ * Payment Authorization Interface (matches lit-actions)
+ */
+export interface PaymentOwnerAuthorization {
+    positionId: string;
+    timestamp: number;
+    chainId: number;
+    amount: string;
+    action: string;
+    signature: string;
+}
+/**
+ * Extend Position Authorization Interface (matches lit-actions)
+ */
+export interface ExtendOwnerAuthorization {
+    positionId: string;
+    timestamp: number;
+    chainId: number;
+    selectedTerm: number;
+    action: string;
+    signature: string;
+}
+/**
+ * Balance Confirmation Authorization Interface
+ * For permissionless balance confirmation with quantum security
+ */
+export interface BalanceConfirmationAuthorization {
+    positionId: string;
+    timestamp: number;
+    chainId: number;
+    caller: string;
+    action: string;
+    signature: string;
+}
+/**
+ * Generate payment authorization signature
+ *
+ * Creates a signature that matches the format expected by
+ * process-payment-validator LIT Action.
+ *
+ * Message structure:
+ * solidityKeccak256(
+ *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
+ *   [positionId, timestamp, chainId, amount, actionHash]
+ * )
+ *
+ * Where:
+ * - actionHash = keccak256("make-payment")
+ * - Signer address is recovered from signature by LIT Action
+ * - LIT Action validates recovered address === position owner
+ */
+export declare function generatePaymentAuthorization(positionId: string, amount: bigint, chainId: number, signer: Signer): Promise<PaymentOwnerAuthorization>;
+/**
+ * Generate extend position authorization signature
+ *
+ * Creates a signature that matches the format expected by
+ * extend-position-validator LIT Action.
+ *
+ * Message structure:
+ * solidityKeccak256(
+ *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
+ *   [positionId, timestamp, chainId, selectedTerm, actionHash]
+ * )
+ *
+ * Where:
+ * - actionHash = keccak256("extend-position")
+ * - Signer address is recovered from signature by LIT Action
+ * - LIT Action validates recovered address === position owner
+ */
+export declare function generateExtendAuthorization(positionId: string, selectedTerm: number, chainId: number, signer: Signer): Promise<ExtendOwnerAuthorization>;
+/**
+ * Optional Chipotle service fallback for `getPKPPublicKeyFromTokenId`.
+ *
+ * Chipotle PKPs have no on-chain `getPubkey(tokenId)` lookup, so when the
+ * SDK's in-memory `pkp-data` cache is empty (page reload, new device, cleared
+ * browser data) we recover the public key by re-running pkp-validator via the
+ * lit-ops-server `/api/lit/pkp/derive-public-key` endpoint. Chipotle key
+ * derivation is deterministic from `pkpId`, so this returns the same key.
+ */
+export interface ChipotleServiceFallback {
+    serviceEndpoint: string;
+    /** Returns `Authorization`-style headers for the lit-ops-server request. */
+    getAuthHeader?: () => Promise<Record<string, string>>;
+    borrowerAddress?: string;
+    timeoutMs?: number;
+    debug?: boolean;
+}
+/**
+ * Get PKP public key from PKP token ID.
+ *
+ * For legacy PKPs minted as NFTs on Chronicle Yellowstone: looks up
+ * via `getPubkey(tokenId)` on the supplied PKP NFT contract.
+ *
+ * For Chipotle PKPs (ABI-encoded ETH address): there is no on-chain lookup, so
+ * if `chipotleFallback.serviceEndpoint` is configured, the public key is
+ * derived by calling lit-ops-server. If the fallback is not configured, this
+ * throws with a clear diagnostic.
+ *
+ * @param pkpTokenId - PKP token ID (bytes32 hex string)
+ * @param provider - Ethereum provider connected to the PKP NFT chain (legacy PKPs only)
+ * @param pkpNftContractAddress - PKP NFT contract address on that chain (legacy PKPs only)
+ * @param chipotleFallback - Service-mode fallback used when pkpTokenId is a Chipotle id
+ * @returns PKP public key as hex string with '0x' prefix
+ */
+export declare function getPKPPublicKeyFromTokenId(pkpTokenId: string, provider?: Provider, pkpNftContractAddress?: string, chipotleFallback?: ChipotleServiceFallback): Promise<string>;
+/**
+ * Withdraw Owner Authorization Interface (matches lit-actions)
+ */
+export interface WithdrawOwnerAuthorization {
+    positionId: string;
+    timestamp: number;
+    chainId: number;
+    amount: string;
+    action: string;
+    signature: string;
+}
+/**
+ * Build the withdraw 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 amount - Amount to withdraw in satoshis (bigint)
+ * @param chainId - Chain ID for cross-chain replay protection
+ * @param destinationAddress - Bitcoin destination address
+ * @returns { hash, timestamp } — pass these to Safe for signing
+ */
+export declare function buildWithdrawAuthorizationHash(positionId: string, amount: bigint, chainId: number, destinationAddress: string): {
+    hash: string;
+    timestamp: number;
+};
+/**
+ * Generate withdrawal authorization signature
+ *
+ * Creates a signature that matches the format expected by
+ * AuthorizationModule.verifyWithdrawAuthorization in lit-actions.
+ *
+ * Message structure:
+ * solidityKeccak256(
+ *   ["bytes32", "uint256", "uint256", "uint256", "string", "bytes32"],
+ *   [positionId, timestamp, chainId, amount, destinationAddress, actionHash]
+ * )
+ *
+ * Where:
+ * - actionHash = keccak256("withdraw-btc")
+ * - Signer address is recovered from signature by LIT Action
+ * - LIT Action validates recovered address === position owner
+ *
+ * @param positionId - Position identifier
+ * @param amount - Amount to withdraw in satoshis (bigint)
+ * @param chainId - Chain ID for cross-chain replay protection
+ * @param signerOrPrecomputed - Either an ethers Signer (EOA) or { timestamp, signature } for smart contract wallets
+ * @param destinationAddress - Bitcoin address for withdrawal
+ * @returns Authorization object with signature
+ */
+export declare function generateWithdrawAuthorization(positionId: string, amount: bigint, // satoshis
+chainId: number, signerOrPrecomputed: Signer | {
+    timestamp: number;
+    signature: string;
+}, destinationAddress: string): Promise<WithdrawOwnerAuthorization>;
+/**
+ * Generate balance confirmation authorization signature
+ *
+ * Creates a signature for permissionless balance confirmation with quantum security.
+ * Unlike mint/payment (owner-signed), this is signed by the caller (anyone).
+ *
+ * Message structure:
+ * solidityKeccak256(
+ *   ["bytes32", "uint256", "uint256", "address", "bytes32"],
+ *   [positionId, timestamp, chainId, caller, actionHash]
+ * )
+ *
+ * Where:
+ * - actionHash = keccak256("confirm-balance")
+ * - Signer is the caller (anyone can call permissionlessly)
+ * - Quantum timestamp validates timing security
+ *
+ * @param positionId - Position identifier
+ * @param chainId - Chain ID for cross-chain replay protection
+ * @param signer - Ethereum signer to sign with (the caller)
+ * @returns Authorization object with signature
+ */
+export declare function generateBalanceConfirmationAuthorization(positionId: string, chainId: number, signer: Signer): Promise<BalanceConfirmationAuthorization>;

package/dist/utils/position-delegate.utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Position Delegate Utilities
+ *
+ * Helpers for registering an off-chain authorization delegate on a position.
+ * The delegate lets a Safe-as-borrower delegate LIT Action auth signing to a
+ * hot agent EOA without making that EOA a Safe owner. The delegate is read by
+ * the LIT Action authorization verifier as a third recovery arm after the
+ * EOA `position.borrower` check and the EIP-1271 smart-account fallback.
+ *
+ * State lives on `PositionDelegateRegistry` (a standalone contract), not on
+ * PositionManager — PositionManager is at the 24 KiB Spurious Dragon limit
+ * and cannot carry the additional storage + setter without going over.
+ */
+import { type Signer, type Provider, type TransactionResponse } from "ethers";
+/**
+ * Register (or revoke) the off-chain authorization delegate for a position.
+ *
+ * Must be called by the position's current `borrower` — for Safe-as-borrower
+ * setups, that means the call must go through `safe.execTransaction(...)` or
+ * `agentModule.execute(...)` so that `msg.sender` at the registry equals the
+ * Safe. Pass `ethers.constants.AddressZero` as `delegate` to revoke.
+ *
+ * @param positionId Position identifier (bytes32).
+ * @param delegate New delegate EOA, or zero address to clear.
+ * @param signer Ethers signer that will be `msg.sender` at the registry.
+ * @param registryAddress Deployed `PositionDelegateRegistry` address for the chain.
+ * @returns The submitted transaction response.
+ */
+export declare function setPositionDelegate(positionId: string, delegate: string, signer: Signer, registryAddress: string): Promise<TransactionResponse>;
+/**
+ * Read the currently registered delegate for a position.
+ *
+ * Returns the zero address when no delegate has been registered. Pure view;
+ * any provider works (signer not required).
+ *
+ * @param positionId Position identifier (bytes32).
+ * @param provider Ethers provider or signer.
+ * @param registryAddress Deployed `PositionDelegateRegistry` address.
+ * @returns The delegate EOA, or zero address if none.
+ */
+export declare function getPositionDelegate(positionId: string, provider: Provider | Signer, registryAddress: string): Promise<string>;

package/dist/utils/quantum-timing.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Quantum Timing Utility
+ *
+ * Shared utility for calculating valid quantum timestamps across SDK, tests, and lit-ops.
+ *
+ * NEW QUANTUM PROTOCOL (60-second 3-window system):
+ * - SDK signs for NEXT quantum immediately (no waiting)
+ * - 60-second quantum windows
+ * - 3-quantum validation (past, current, next) = 180s total validity
+ * - Dead zones: first 8s and last 8s of each quantum
+ * - Users can operate once per 60 seconds per position
+ *
+ * Architecture:
+ * - SDK uses this to calculate NEXT quantum immediately
+ * - Tests use this to generate valid timestamps
+ * - LIT Actions validate 3-quantum window with dead zone protection
+ */
+/**
+ * Calculate a valid quantum timestamp for NEXT quantum (NO WAITING)
+ *
+ * NEW 60-second quantum system:
+ * - Returns NEXT quantum boundary immediately
+ * - No waiting for optimal moment
+ * - Signature valid for 180 seconds (3 quantums: PAST, CURRENT, NEXT)
+ * - User can sign immediately, operation executes within 3-quantum window
+ *
+ * @returns Promise<number> - Next quantum boundary timestamp
+ */
+export declare function calculateValidQuantumTimestamp(): Promise<number>;
+/**
+ * Check if a timestamp is in the safe work zone (outside dead zones)
+ *
+ * @param timestamp - Unix timestamp to check
+ * @returns boolean - True if in safe zone (8-52s of any quantum)
+ */
+export declare function isInSafeWorkZone(timestamp: number): boolean;
+/**
+ * Get current quantum without waiting
+ *
+ * @returns number - Current quantum timestamp
+ */
+export declare function getCurrentQuantum(): number;
+/**
+ * Get seconds remaining in current quantum
+ *
+ * @returns number - Seconds until quantum expires
+ */
+export declare function getSecondsUntilQuantumExpiry(): number;
+/**
+ * Calculate next quantum timestamp WITHOUT waiting (60-second system)
+ *
+ * Returns NEXT quantum boundary immediately.
+ * No waiting, no optimal moment calculation.
+ * Signature valid for 180 seconds (3 quantums).
+ *
+ * @returns number - Next quantum boundary timestamp
+ */
+export declare function calculateNextQuantumTimestamp(): number;
+/**
+ * Wait until specific timestamp is reached
+ *
+ * @param targetTimestamp - Unix timestamp to wait for
+ */
+export declare function waitUntilTimestamp(targetTimestamp: number): Promise<void>;
+/**
+ * Validate quantum timing (60-second 3-quantum system)
+ *
+ * Validates that a signed timestamp falls within valid 3-quantum window.
+ * With 60-second quantums, signatures are valid for 180 seconds (PAST, CURRENT, NEXT).
+ *
+ * @param signedTimestamp - Timestamp that was signed by user
+ * @param bufferSeconds - Unused in new system (kept for API compatibility)
+ * @throws Error if timestamp is invalid
+ */
+export declare function validateQuantumTiming(signedTimestamp: number, _bufferSeconds?: number): void;

package/dist/utils/server-session.d.ts

@@ -0,0 +1,50 @@
+/**
+ * In-memory session JWT manager for lit-ops-server.
+ *
+ * The server's `POST /api/auth/login` route accepts an EIP-712-signed
+ * `DhServerLogin` envelope and returns an HS256 JWT with a 15-minute TTL.
+ * This helper:
+ *
+ *   - caches the JWT until ~30s before expiry,
+ *   - coalesces concurrent callers behind a single in-flight Promise so we
+ *     don't spam `/api/auth/login` on parallel SDK calls,
+ *   - exposes `getValidToken()` returning the live token and
+ *     `getAuthHeader()` returning a ready-to-spread `{ Authorization: ... }`
+ *     object.
+ *
+ * Browser-safe — no filesystem touches. The CLI mirrors this shape but
+ * persists to `~/.diamond-hands/session.json` for cross-invocation reuse.
+ */
+import type { Signer } from "ethers";
+export interface ServerSessionOptions {
+    signer: Signer;
+    serviceEndpoint: string;
+    chainId: number;
+    /** Override for tests. */
+    now?: () => number;
+    /** Override for tests. */
+    fetchImpl?: typeof fetch;
+}
+export declare class ServerSession {
+    private readonly signer;
+    private readonly serviceEndpoint;
+    private readonly chainId;
+    private readonly now;
+    private readonly fetchImpl;
+    private cached;
+    private inFlight;
+    constructor(opts: ServerSessionOptions);
+    /** Returns a JWT good for at least `REFRESH_LEEWAY_SECONDS` more seconds. */
+    getValidToken(): Promise<string>;
+    /** Convenience for fetch: spread directly into `headers`. */
+    getAuthHeader(): Promise<Record<string, string>>;
+    /** Drop the cached token (e.g. on 401 from server). Next call re-logs in. */
+    clear(): void;
+    /**
+     * Revoke the current session JWT on lit-ops-server (`POST /api/auth/logout`).
+     * Clears the local cache regardless of server response so the client stops
+     * presenting the token.
+     */
+    logout(): Promise<void>;
+    private getOrRefresh;
+}

package/dist/utils/service-endpoint-policy.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Refuses to send session JWTs or signed auth payloads over plaintext HTTP
+ * unless the endpoint is loopback. https://* is always allowed; http://localhost,
+ * http://127.0.0.1 (and the 127.0.0.0/8 range), and http://[::1] are allowed for
+ * local development; everything else throws.
+ *
+ * Audit L-10: the previous `*.localhost` wildcard was dropped. `.localhost` is reserved to
+ * loopback by RFC 6761, but not every resolver honours it strictly — a hostile or misconfigured
+ * DNS could resolve `foo.localhost` to an off-host IP and exfiltrate the cleartext token. Exact
+ * loopback literals + the numeric 127.0.0.0/8 range can't be DNS-hijacked.
+ *
+ * IPv4-mapped IPv6 loopback (e.g. `http://[::ffff:127.0.0.1]`) is intentionally NOT accepted: the
+ * URL parser normalises it to a hex form (`[::ffff:7f00:1]`) that is fragile to match safely. Use
+ * `127.0.0.1`, `::1`, or `localhost` for local development.
+ */
+export declare function assertSafeServiceEndpoint(endpoint: string): void;

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

@@ -0,0 +1,34 @@
+/**
+ * Signature Tempering Utility
+ *
+ * Security testing tool to intentionally corrupt signatures so tests can prove
+ * the on-chain validator rejects invalid signatures.
+ *
+ * WARNING: TESTING ONLY. `maybeTemperSignature` refuses to corrupt signatures
+ * when `NODE_ENV === "production"`, regardless of the config flag. The previous
+ * behavior (any caller could flip `temperSignaturesTest: true` to corrupt every
+ * signature) was an audit finding — the function is now defense-in-depth.
+ */
+/**
+ * Tempers a signature by modifying the 3rd character with a random valid hex character
+ * that differs from the original.
+ *
+ * @param signature - Original signature (0x prefixed hex string)
+ * @returns Tempered signature with 3rd character modified
+ *
+ * @example
+ * const original = "0x1234567890abcdef...";
+ * const tempered = temperSignature(original);
+ * // tempered = "0x12X4567890abcdef..." where X != 3
+ */
+export declare function temperSignature(signature: string): string;
+/**
+ * Conditionally tempers a signature based on config flag.
+ * Returns original signature if tempering is disabled.
+ *
+ * @param signature - Original signature
+ * @param shouldTemper - Whether to apply tempering
+ * @param operationName - Name of operation for logging (optional)
+ * @returns Original or tempered signature
+ */
+export declare function maybeTemperSignature(signature: string, shouldTemper: boolean | undefined, operationName?: string): string;

package/dist/utils/telegram-messaging.utils.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Telegram Messaging Utilities
+ *
+ * Provides functionality to send messages to Telegram chats using the node-telegram-bot-api package
+ */
+/**
+ * Send a message to a Telegram chat
+ *
+ * @param chatId - Telegram chat ID
+ * @param chatToken - Telegram bot token
+ * @param message - Message to send
+ * @param threadId - Optional thread ID for message threads in groups
+ * @returns Promise that resolves when message is sent, or rejects on error
+ */
+export declare function sendTelegramMessage(chatId: string, chatToken: string, message: string, threadId?: number): Promise<void>;
+/**
+ * Format a mint notification message
+ *
+ * @param mintAmount - Amount minted in UCD
+ * @param loanId - Position/loan ID
+ * @param txHash - Transaction hash
+ * @returns Formatted message string
+ */
+export declare function formatMintMessage(mintAmount: number | string, loanId: string, txHash: string): string;
+/**
+ * Format a partial payment notification message
+ *
+ * @param paymentAmount - Amount repaid in UCD
+ * @param loanId - Position/loan ID
+ * @param txHash - Transaction hash
+ * @returns Formatted message string
+ */
+export declare function formatPartialPaymentMessage(paymentAmount: number | string, loanId: string, txHash: string): string;
+/**
+ * Format a BTC withdrawal notification message
+ *
+ * @param withdrawalAmount - Amount withdrawn in BTC
+ * @param vaultAddress - Bitcoin vault address
+ * @param loanId - Position/loan ID
+ * @param destinationAddress - Bitcoin destination address
+ * @returns Formatted message string
+ */
+export declare function formatWithdrawalMessage(withdrawalAmount: number | string, vaultAddress: string, loanId: string, destinationAddress: string): string;
+/**
+ * Format a mint failure notification message
+ *
+ * @param mintAmount - Amount that failed to be minted in UCD
+ * @param loanId - Position/loan ID
+ * @returns Formatted message string
+ */
+export declare function formatMintFailureMessage(mintAmount: number | string, loanId: string): string;
+/**
+ * Format a partial payment failure notification message
+ *
+ * @param paymentAmount - Amount that failed to be repaid in UCD
+ * @param loanId - Position/loan ID
+ * @param txHash - Optional transaction hash if available
+ * @returns Formatted message string
+ */
+export declare function formatPartialPaymentFailureMessage(paymentAmount: number | string, loanId: string, txHash?: string): string;
+/**
+ * Format a loan creation notification message
+ *
+ * @param positionId - Position/loan ID
+ * @param pkpId - PKP token ID
+ * @param vaultAddress - Regtest BTC vault address
+ * @returns Formatted message string
+ */
+export declare function formatLoanCreationMessage(positionId: string, pkpId: string, vaultAddress?: string): string;
+/**
+ * Format a loan creation failure notification message
+ *
+ * @param error - Error description
+ * @returns Formatted message string
+ */
+export declare function formatLoanCreationFailureMessage(error: string): string;
+/**
+ * Format a BTC withdrawal notification message
+ *
+ * @param withdrawalAmount - Amount withdrawn in BTC
+ * @param loanId - Position/loan ID
+ * @param btcTxHash - Bitcoin transaction hash
+ * @returns Formatted message string
+ */
+export declare function formatBTCWithdrawalMessage(withdrawalAmount: number | string, loanId: string, btcTxHash: string): string;
+/**
+ * Format a BTC withdrawal failure notification message
+ *
+ * @param withdrawalAmount - Amount that failed to be withdrawn in BTC
+ * @param btcVault - Bitcoin vault address
+ * @param btcDestinationAddress - Bitcoin destination address
+ * @param loanId - Position/loan ID
+ * @returns Formatted message string
+ */
+export declare function formatBTCWithdrawalFailureMessage(withdrawalAmount: number | string, btcVault: string, btcDestinationAddress: string, loanId: string): string;
+/**
+ * Format a loan renewal success notification message
+ *
+ * @param positionId - Position/loan ID
+ * @param txHash - Transaction hash
+ * @returns Formatted message string
+ */
+export declare function formatLoanRenewalMessage(positionId: string, txHash: string): string;
+/**
+ * Format a loan renewal failure notification message
+ *
+ * @param loanId - Position/loan ID
+ * @param error - Error description
+ * @returns Formatted message string
+ */
+export declare function formatLoanRenewalFailureMessage(loanId: string, error: string): string;
+/**
+ * Format a balance confirmation success notification message
+ *
+ * @param loanId - Position/loan ID
+ * @returns Formatted message string
+ */
+export declare function formatBalanceConfirmationMessage(loanId: string): string;
+/**
+ * Format a balance confirmation failure notification message
+ *
+ * @param loanId - Position/loan ID
+ * @returns Formatted message string
+ */
+export declare function formatBalanceConfirmationFailureMessage(loanId: string): string;
+/**
+ * Format a BTC withdrawal success notification message
+ *
+ * @param withdrawalAmount - Amount withdrawn in BTC
+ * @param btcVault - Bitcoin vault address
+ * @param btcDestinationAddress - Bitcoin destination address
+ * @param loanId - Position/loan ID
+ * @returns Formatted message string
+ */
+export declare function formatBTCWithdrawalSuccessMessage(withdrawalAmount: number | string, btcVault: string, btcDestinationAddress: string, loanId: string, btcTxId?: string): string;
+/**
+ * Format a liquidation skipped notification message
+ *
+ * @param loanId - Position/loan ID
+ * @param ratio - Current collateral ratio (as percentage)
+ * @param threshold - Liquidation threshold (as percentage)
+ * @param btcVault - Bitcoin vault address
+ * @param btcVaultBalance - BTC vault balance
+ * @param ucdDebt - UCD debt amount
+ * @param btcPrice - Current BTC price
+ * @returns Formatted message string
+ */
+export declare function formatLiquidationSkippedMessage(loanId: string, ratio: number | string, threshold: number | string, btcVault: string, btcVaultBalance: string, ucdDebt: string, btcPrice: string): string;
+/**
+ * Format a liquidation success notification message
+ *
+ * @param loanId - Position/loan ID
+ * @param ratio - Current collateral ratio (as percentage)
+ * @param threshold - Liquidation threshold (as percentage)
+ * @param btcVault - Bitcoin vault address
+ * @param btcVaultBalance - BTC vault balance
+ * @param ucdDebt - UCD debt amount
+ * @param btcPrice - Current BTC price
+ * @returns Formatted message string
+ */
+export declare function formatLiquidationSuccessMessage(loanId: string, ratio: number | string, threshold: number | string, btcVault: string, btcVaultBalance: string, ucdDebt: string, btcPrice: string): string;
+/**
+ * Format BTC price from satoshi value to readable USD format
+ *
+ * @param btcPriceSats - BTC price in satoshis (8 decimals)
+ * @returns Formatted BTC price string
+ */
+export declare function formatBTCPrice(btcPriceSats: string | number): string;
+/**
+ * Format BTC amount to readable BTC format
+ * Accepts either satoshi values (converts to BTC) or already formatted BTC values
+ *
+ * @param btcAmount - BTC amount in satoshis or already in BTC format
+ * @returns Formatted BTC amount string
+ */
+export declare function formatBTCAmount(btcAmount: string | number): string;
+/**
+ * Format a liquidation failure notification message
+ *
+ * @param loanId - Position/loan ID
+ * @param errorMessage - Error message describing the failure
+ * @param btcVault - Bitcoin vault address
+ * @param btcVaultBalance - BTC vault balance
+ * @param ucdDebt - UCD debt amount
+ * @param btcPrice - Current BTC price
+ * @returns Formatted message string
+ */
+export declare function formatLiquidationFailureMessage(loanId: string, errorMessage: string, btcVault: string, btcVaultBalance: string, ucdDebt: string, btcPrice: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.288",
+  "version": "0.0.289",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",