@gvnrdao/dh-sdk

TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs

Description

The official TypeScript SDK for the Diamond Hands Protocol, enabling developers to interact with Bitcoin-backed lending smart contracts using LIT Protocol's Programmable Key Pairs (PKPs) for secure asset management.

Installation

npm install @gvnrdao/dh-sdk

Usage

Basic Setup

import { DiamondHandsSDK } from "@gvnrdao/dh-sdk";

// Initialize SDK
const sdk = new DiamondHandsSDK({
  mode: "service", // or 'standalone'
  serviceEndpoint: "http://localhost:3001",
  contractAddresses: {
    positionManager: "0x...",
    ucdToken: "0x...",
    // ... other contract addresses
  },
});

await sdk.initialize();

Creating a Loan

const loanRequest = {
  collateralAmount: 25000, // UCD equivalent
  collateralRatio: 150, // 150%
  selectedTerm: 3, // 3 months
};

const result = await sdk.createLoan(loanRequest);
if (result.success) {
  console.log("Loan created:", result.transactionHash);
  console.log("Position ID:", result.positionId);
  console.log("PKP Address:", result.pkpData.ethAddress);
}

Features

• ✅ Service & Standalone Modes: Flexible deployment options
• ✅ Browser & Node.js Support: Works in both environments
• ✅ TypeScript Support: Full type definitions included
• ✅ PKP Integration: Secure key management with LIT Protocol
• ✅ Smart Contract Integration: Direct interaction with Diamond Hands contracts
• ✅ Bitcoin Operations: Support for Bitcoin deposit verification
• ✅ Telegram Notifications: Optional event notifications (Node.js only)

API Reference

Core Methods

• initialize() - Initialize the SDK
• createLoan(request) - Create a new loan position
• repayLoan(positionId, amount) - Repay an existing loan
• liquidatePosition(positionId) - Liquidate an undercollateralized position

Configuration Options

See the full API documentation for detailed configuration options and method signatures.

Telegram Notifications

The SDK supports optional Telegram notifications for loan events (minting, payments, renewals, etc.). These notifications only work in Node.js environments due to browser security restrictions.

Enabling Telegram Notifications

Add the telegram configuration when initializing the SDK:

const sdk = new DiamondHandsSDK({
  mode: "service",
  serviceEndpoint: "http://localhost:3001",
  telegram: {
    chatId: "your-chat-id",
    chatToken: "your-bot-token",
    threadId: 123 // Optional: for group threads
  },
  // ... other config
});

Browser Behavior

Important: Telegram notifications are automatically disabled in browser environments to avoid CORS errors. The SDK detects browser environments and silently skips notification attempts without breaking your application flow.

• ✅ Node.js: Notifications sent via Telegram Bot API
• ✅ Browser: Notifications silently skipped (no errors)
• ✅ Development: Console logs in localhost for debugging

Supported Events

The SDK sends notifications for:

• Loan creation
• UCD minting
• Partial payments
• Loan renewals
• Balance confirmations
• BTC withdrawals
• Operation failures

Security Note

Never expose your Telegram bot token in frontend code. If you need notifications from browser applications, use a backend webhook endpoint instead.

License

MIT