npm package: @gvnrdao/dh-sdk
Description: TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs
Author: Diamond Hands Protocol
Latest version: 0.0.162

# @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

```bash
npm install @gvnrdao/dh-sdk
```

## Usage

### Basic Setup

```typescript
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

```typescript
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:

```typescript
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