@hermetica/sdk 1.0.0

package/README.md

@@ -0,0 +1,294 @@
+# @hermetica/transactions
+
+A TypeScript library for creating and managing stake, unstake, and claim transactions on the Hermetica protocol. This library supports both Stacks and Bitcoin blockchains.
+
+## Features
+
+- Generate transaction hex for staking, unstaking, and claiming rewards
+- Support for both Stacks and Bitcoin blockchains
+- USDh/sUSDh supported on Stacks and Bitcoin; hBTC supported on Stacks only
+- Claims data retrieval for both chains
+- sUSDh and hBTC rate, price, and APY information retrieval
+- Configurable API host and affiliate code support
+
+## Installation
+
+```bash
+npm install @hermetica/transactions
+```
+
+## Configuration
+
+The library can be configured with the following options:
+
+```typescript
+const config = {
+  // Optional: Custom API host (defaults to https://app.hermetica.fi)
+  HOST: string;
+  // Optional: Your Hermetica affiliate code
+  AFFILIATE_CODE: string;
+};
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import { TransactionBuilder } from '@hermetica/transactions';
+
+const transactionBuilder = new TransactionBuilder({
+  HOST: 'CUSTOM_HERMETICA_API', // optional
+  AFFILIATE_CODE: 'YOUR_AFFILIATE_CODE' // optional
+});
+```
+
+### Generating Transactions
+
+#### For Stacks (USDh or hBTC)
+
+```typescript
+const stakeResult = await transactionBuilder.generateTransactionHex({
+  amount: '94.2', // Amount to stake
+  type: 'stake', // 'stake' | 'unstake' | 'withdraw'
+  chain: 'stacks',
+  protocol: 'USDh', // 'USDh' | 'hBTC'
+  public_key: '923xcv2...' // Your Stacks public key
+});
+
+// Response format
+{
+  status: 'success' | 'failed';
+  message: string;
+  data: {
+    tx_hex: string; // The transaction hex to be signed
+    type: 'stake' | 'unstake' | 'withdraw';
+    chain: 'stacks';
+  }
+}
+```
+
+#### Multisig Transactions (Stacks only)
+
+For multisig wallets (e.g., Asigna), pass comma-separated public keys and the signing threshold:
+
+```typescript
+const stakeResult = await transactionBuilder.generateTransactionHex({
+  amount: '100',
+  type: 'stake',
+  chain: 'stacks',
+  protocol: 'USDh',
+  public_key: 'pubKey1,pubKey2,pubKey3', // Comma-separated signer public keys
+  threshold: 2 // 2-of-3 multisig (required signatures)
+});
+```
+
+| Parameter    | Type     | Required | Description                                                                                      |
+| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `public_key` | `string` | Yes      | Single key for standard wallets, or comma-separated keys for multisig                            |
+| `threshold`  | `number` | No       | Number of required signatures. Defaults to 1. Only used when `public_key` contains multiple keys |
+
+> **Note:** Multisig is only supported on **Stacks**. Bitcoin USDh/sUSDh transactions do not support multisig.
+
+#### For Bitcoin (USDh only)
+
+```typescript
+const stakeResult = await transactionBuilder.generateTransactionHex({
+  amount: '94.2', // Amount to stake in BTC
+  type: 'stake', // 'stake' | 'unstake' | 'withdraw'
+  chain: 'bitcoin',
+  protocol: 'USDh', // Only USDh is supported on Bitcoin
+  addresses: {
+    payment_btc_address: {
+      address: '38byQL...', // Your Bitcoin payment address
+      pubKey: '0000231...', // Public key for the payment address
+      type: 'p2sh' // Address type: p2wpkh, p2sh, etc.
+    },
+    taproot_btc_address: {
+      address: 'bc1pkd...', // Your Taproot address
+      pubKey: '023xc0...', // Public key for the Taproot address
+      type: 'p2tr'
+    }
+  },
+  satvBFee: 5 // Optional: Fee rate in sat/vB (defaults to highest from mempool)
+});
+
+// Response format
+{
+  status: 'success' | 'failed';
+  message: string;
+  data: {
+    tx_hex: string; // The transaction hex to be signed
+    type: 'stake' | 'unstake' | 'withdraw';
+    chain: 'bitcoin';
+    inputs_to_sign?: {
+      [address: string]: number[]; // Input indices that need to be signed
+    }
+  }
+}
+```
+
+### Retrieving Claims Data
+
+#### For Stacks (USDh or hBTC)
+
+```typescript
+const withdrawalsData = await transactionBuilder.getWithdrawalsData({
+  chain: 'stacks',
+  protocol: 'USDh', // 'USDh' | 'hBTC'
+  public_key: '923xcv2...' // Your Stacks public key
+});
+
+// Response formats
+{
+  total_to_claim: number; // Total amount of tokens currently available to claim
+  next_amount_to_unlock: number; // Amount of tokens that will be unlocked in the next unlock period
+  next_claim_timestamp: number; // The timestamp in ms at which the next amount will become claimable
+  last_claim_timestamp: number; // The timestamp in ms at which the last unstake request will be fully unlocked
+}
+```
+
+#### For Bitcoin (USDh only)
+
+```typescript
+const withdrawalsData = await transactionBuilder.getWithdrawalsData({
+  chain: 'bitcoin',
+  protocol: 'USDh', // Only USDh is supported on Bitcoin
+  addresses: {
+    payment_btc_address: {
+      address: '38byQL...',
+      pubKey: '0000231...',
+      type: 'p2sh'
+    },
+    taproot_btc_address: {
+      address: 'bc1pkd...',
+      pubKey: '023xc0...',
+      type: 'p2tr'
+    }
+  }
+});
+
+// Response format
+{
+  total_to_claim: number; // Total amount of tokens currently available to claim
+  next_amount_to_unlock: number; // Amount of tokens that will be unlocked in the next unlock period
+  next_claim_timestamp: number; // The timestamp in ms at which the next amount will become claimable
+  last_claim_timestamp: number; // The timestamp in ms at which the last unstake request will be fully unlocked
+}
+```
+
+The claims data response provides information about:
+
+- Currently claimable amounts
+- Future unlock amounts
+- Timestamps for tracking unlock periods
+- This information is useful for displaying countdown timers, progress bars, or other UI elements related to the staking lifecycle
+
+### Retrieving hBTC Rate
+
+Get the current hBTC share price rate:
+
+```typescript
+const hbtcRate = await transactionBuilder.gethBTCRate();
+
+// Returns: number — The hBTC share price rate
+```
+
+### Retrieving hBTC Price
+
+Get the current hBTC price in USD:
+
+```typescript
+const hbtcPrice = await transactionBuilder.gethBTCPrice();
+
+// Returns: number — The hBTC price in USD
+```
+
+### Retrieving hBTC APY
+
+Get the current hBTC APY (Annual Percentage Yield):
+
+```typescript
+const hbtcApy = await transactionBuilder.gethBTCApy({
+  range: '7d' // Optional: Time range for APY calculation ('7d', '30d' or '365d')
+});
+
+// Returns: number — The current hBTC APY percentage
+```
+
+### Retrieving hBTC Remaining Capacity
+
+Get the remaining BTC deposit capacity for the hBTC vault:
+
+```typescript
+const remainingCapacity = await transactionBuilder.gethBTCRemainingCapacity();
+
+// Returns: number — The remaining BTC room available for deposits into the hBTC vault
+```
+
+### Retrieving sUSDh Rate
+
+Get the current sUSDh rate:
+
+```typescript
+const susdhRate = await transactionBuilder.getsUSDhRate();
+
+// Returns: number — The rate of USDh per sUSDh
+```
+
+### Retrieving sUSDh APY
+
+Get the current sUSDh APY (Annual Percentage Yield):
+
+```typescript
+const susdhApy = await transactionBuilder.getsUSDhApy({
+  range: '7d' // Optional: Time range for APY calculation ('7d', '30d' or '365d')
+});
+
+// Returns: number — The current sUSDh APY percentage
+```
+
+The APY functions support different time ranges to get historical or current yield data.
+
+## Supported Blockchains
+
+- **Stacks**: Full support for USDh and hBTC staking, unstaking, and claiming rewards
+- **Bitcoin**: Support for USDh staking, unstaking, and claiming rewards with:
+  - Payment address (p2sh, p2wpkh)
+  - Taproot address (p2tr)
+
+> **Note:** hBTC transactions are only supported on Stacks. Bitcoin chain support is limited to USDh/sUSDh.
+>
+> **Note:** Multisig transactions are only supported on **Stacks**. Bitcoin USDh/sUSDh transactions do not support multisig.
+
+## Transaction Types
+
+- **stake**: Lock your tokens in the protocol to start earning rewards
+- **unstake**: Initiate the withdrawal process for your staked tokens (requires waiting period)
+- **withdraw**: Collect your available rewards and/or unlocked tokens after the waiting period
+
+## Error Handling
+
+The library throws errors in the following cases:
+
+- Invalid configuration
+- Insufficient funds
+- Invalid address format
+- Network errors
+- Invalid transaction parameters
+
+Example error handling:
+
+```typescript
+try {
+  const result = await transactionBuilder.generateTransactionHex({
+    // ... transaction parameters
+  });
+} catch (error) {
+  console.error('Transaction generation failed:', error.message);
+}
+```
+
+## License
+
+GPL-3.0

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { TransactionResult, TransactionBuilderConfig, BitcoinTransactionParams, StacksTransactionParams, ClaimsData, GetApyParams } from './types';
+export declare class TransactionBuilder {
+    private config;
+    private axiosInstance;
+    constructor({ HOST, AFFILIATE_CODE }: TransactionBuilderConfig);
+    generateTransactionHex(params: BitcoinTransactionParams | StacksTransactionParams): Promise<TransactionResult>;
+    getWithdrawalsData(params: BitcoinTransactionParams | StacksTransactionParams): Promise<ClaimsData>;
+    private parseNumericResponse;
+    getsUSDhRate(): Promise<number>;
+    gethBTCRate(): Promise<number>;
+    gethBTCPrice(): Promise<number>;
+    getsUSDhApy(params?: GetApyParams): Promise<number>;
+    gethBTCApy(params?: GetApyParams): Promise<number>;
+    gethBTCRemainingCapacity(): Promise<number>;
+}

package/dist/index.js

@@ -0,0 +1,86 @@
+import axios from 'axios';
+// Main class
+export class TransactionBuilder {
+    constructor({ HOST, AFFILIATE_CODE }) {
+        this.config = {
+            HOST: HOST || 'https://app.hermetica.fi',
+            AFFILIATE_CODE: AFFILIATE_CODE || undefined
+        };
+        this.axiosInstance = axios.create({
+            baseURL: this.config.HOST,
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+    async generateTransactionHex(params) {
+        const { amount, chain, type, protocol } = params;
+        const requestBody = {
+            token_symbol: protocol,
+            amount,
+            chain,
+            affiliate_code: this.config.AFFILIATE_CODE,
+            ...(chain === 'bitcoin'
+                ? {
+                    addresses: params?.addresses,
+                    satvb_fee: params?.satvBFee
+                }
+                : {
+                    public_key: params?.public_key,
+                    threshold: params?.threshold
+                })
+        };
+        const response = await this.axiosInstance.post(`/api/v2/transactions/${type}`, requestBody);
+        return response.data;
+    }
+    async getWithdrawalsData(params) {
+        const { chain, protocol } = params;
+        const requestBody = {
+            chain,
+            public_key: params?.public_key,
+            addresses: params?.addresses,
+            token_symbol: protocol
+        };
+        const response = await this.axiosInstance.post(`/api/v2/transactions/claims_data`, requestBody);
+        return response.data;
+    }
+    parseNumericResponse(value, endpoint) {
+        const parsed = Number(value);
+        if (isNaN(parsed)) {
+            throw new Error(`Invalid numeric response from ${endpoint}: ${value}`);
+        }
+        return parsed;
+    }
+    async getsUSDhRate() {
+        const response = await this.axiosInstance.get(`/api/v2c/info/susdh_rate`);
+        return this.parseNumericResponse(response.data.rate, '/api/v2c/info/susdh_rate');
+    }
+    async gethBTCRate() {
+        const response = await this.axiosInstance.get(`/api/v2c/info/hbtc_rate`);
+        return this.parseNumericResponse(response.data.rate, '/api/v2c/info/hbtc_rate');
+    }
+    async gethBTCPrice() {
+        const response = await this.axiosInstance.get(`/api/v2/hbtc/price`);
+        return this.parseNumericResponse(response.data.price, '/api/v2/hbtc/price');
+    }
+    async getsUSDhApy(params) {
+        const response = await this.axiosInstance.get(`/api/v2/info/apy/susdh`, {
+            params: {
+                range: params?.range || '7d'
+            }
+        });
+        return this.parseNumericResponse(response.data.apy, '/api/v2/info/apy/susdh');
+    }
+    async gethBTCApy(params) {
+        const response = await this.axiosInstance.get(`/api/v2/info/apy/hbtc`, {
+            params: {
+                range: params?.range || '7d'
+            }
+        });
+        return this.parseNumericResponse(response.data.apy, '/api/v2/info/apy/hbtc');
+    }
+    async gethBTCRemainingCapacity() {
+        const response = await this.axiosInstance.get(`/api/v2/hbtc/vault-capacity`);
+        return this.parseNumericResponse(response.data.vault_capacity, '/api/v2/hbtc/vault-capacity');
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,64 @@
+export type TransactionType = 'stake' | 'unstake' | 'withdraw';
+export type BlockchainType = 'stacks' | 'bitcoin';
+export interface AddressData {
+    address: string;
+    pubKey: string;
+    type?: string;
+    threshold?: number;
+}
+export interface BtcAddresses {
+    payment_btc_address: AddressData;
+    taproot_btc_address: AddressData;
+}
+export interface BaseTransactionParams {
+    amount: string;
+    type: TransactionType;
+    chain: BlockchainType;
+    protocol: 'USDh' | 'hBTC';
+}
+export interface BitcoinTransactionParams extends BaseTransactionParams {
+    chain: 'bitcoin';
+    addresses: BtcAddresses;
+    satvBFee?: number;
+}
+export interface StacksTransactionParams extends BaseTransactionParams {
+    chain: 'stacks';
+    public_key: string;
+    threshold?: number;
+}
+export interface GetApyParams {
+    range?: '7d' | '30d' | '365d';
+}
+export type TransactionParams = BitcoinTransactionParams | StacksTransactionParams;
+export interface TransactionResult {
+    status: 'success' | 'failed';
+    message: string;
+    data: {
+        tx_hex: string;
+        type: TransactionType;
+        chain: BlockchainType;
+        inputs_to_sign?: {
+            [address: string]: number[];
+        };
+    };
+}
+export interface TransactionBuilderConfig {
+    HOST?: string;
+    AFFILIATE_CODE?: string;
+}
+export interface ClaimsData {
+    total_to_claim: number;
+    next_amount_to_unlock: number;
+    next_claim_timestamp: number;
+    last_claim_timestamp: number;
+}
+export interface RateData {
+    rate: number;
+}
+export interface sUSdhApyData {
+    apy: string;
+}
+export interface hBTCApyData {
+    apy: string;
+    last_update: number;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hermetica/sdk",
+  "version": "1.0.0",
+  "description": "Hermetica Transactions Library",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "jest",
+    "test:info": "npx tsx tests/test-info.ts",
+    "test:transactions": "npx tsx tests/test-transactions.ts",
+    "test:live": "npx tsx tests/test-info.ts && npx tsx tests/test-transactions.ts",
+    "test:live:local": "npx tsx tests/test-info.ts --local && npx tsx tests/test-transactions.ts --local",
+    "publish": "./publish.sh"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "axios": "^1.9.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.2.2",
+    "@types/node": "^20.11.22"
+  }
+}