Thunderbolt Chain SDK

A TypeScript SDK for interacting with the Thunderbolt blockchain, providing seamless integration for Bitcoin operations, Boosting BTC functionality, and USD1 token operations.

Features

• 🔗 Blockchain Integration: Connect to Thunderbolt chain via RPC endpoints
• 💰 Boosting BTC Operations: Query balances, transfer, deposit, withdraw
• 💵 USD1 Token Operations: Complete USD1 token management functionality
• 🔐 Bitcoin Signing: Support for BIP322 message signing
• 📊 Account Management: Check activation status and account information
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions
• ⚙️ Configurable: Flexible configuration for different environments

Main Functions

| Function | Description | Parameters | Return Value | |----------|-------------|------------|-------------| | checkAddressActivation | Check address activation status | address: string | Promise | | queryBoostingBtcBalance | Query BTC balance | address: string | Promise | | queryBoostingBtcAllowance | Query BTC allowance amount | owner: string, spender: string | Promise | | transferBoostingBtc | Transfer BTC | sender, recipient, amount, signer | Promise | | increaseAllowance | Increase BTC allowance amount | sender, spender, amount, signer | Promise | | withdrawBoostingBtc | Withdraw BTC | sender, to, amount, signer | Promise | | depositBoostingBtc | Deposit BTC | sender, amount, signer | Promise | | queryUsd1Balance | Query USD1 balance | address: string | Promise | | queryUsd1Allowance | Query USD1 allowance amount | owner: string, spender: string | Promise | | transferUsd1 | Transfer USD1 | sender, recipient, amount, signer | Promise | | increaseUsd1Allowance | Increase USD1 allowance amount | sender, spender, amount, signer | Promise | | withdrawUsd1 | Withdraw USD1 | sender, to, amount, signer | Promise | | depositUsd1 | Deposit USD1 | sender, amount, signer | Promise | | createConfig | Create configuration | config: { chainId?: 'thunderbolt' | 'thunderbolt-devnet'; rpcEndpoint?: string } | void |

Installation

npm install @nubit/thunderbolt-chain-sdk

Quick Start

Basic Setup

import { 
  createConfig,
  checkAddressActivation,
  queryBoostingBtcBalance,
  transferBoostingBtc,
  queryUsd1Balance,
  transferUsd1
} from '@nubit/thunderbolt-chain-sdk';

// Optional: Configure for different environments
createConfig({
  chainId: 'thunderbolt-devnet',
  rpcEndpoint: 'https://dev-thunderbolt-gateway.nubit.network'
});

Checking Activation Status

async function checkUserActivation() {
  try {
    const isActivated = await checkAddressActivation('your-bitcoin-address');
    console.log('Address activated:', isActivated);
  } catch (error) {
    console.error('Failed to check activation:', error);
  }
}

Configuration

The SDK supports flexible configuration for different environments:

import { createConfig } from '@nubit/thunderbolt-chain-sdk';

// Configure for mainnet (default)
createConfig({
  chainId: 'thunderbolt',
  rpcEndpoint: 'https://gateway.thunderbolt.lt'
});

// Configure for devnet
createConfig({
  chainId: 'thunderbolt-devnet',
  rpcEndpoint: 'https://dev-thunderbolt-gateway.nubit.network'
});

// Use custom RPC endpoint with devnet
createConfig({
  chainId: 'thunderbolt-devnet',
  rpcEndpoint: 'https://your-custom-endpoint.com'
});

Note: For external developers, only chainId and rpcEndpoint parameters are supported. The chainId must be either 'thunderbolt' (mainnet) or 'thunderbolt-devnet' (devnet).

API Reference

User Operations checkAddressActivation(address: string): Promise

Check if a Bitcoin address is activated on the Thunderbolt chain.

const isActivated = await checkAddressActivation('bc1p...');

Boosting BTC Operations queryBoostingBtcBalance(address: string): Promise

Query the Boosting BTC balance of an address.

const balance = await queryBoostingBtcBalance('bc1p...');
console.log('Balance:', balance);

queryBoostingBtcAllowance(owner: string, spender: string): Promise

Query the allowance amount that a spender can use from an owner's account.

const allowance = await queryBoostingBtcAllowance(
  'owner-address',
  'spender-address'
);
console.log('Allowance:', allowance);

transferBoostingBtc(senderAddress: string, recipientAddress: string, amount: string, btcSigner: MessageSigner): Promise

Transfer Boosting BTC tokens between addresses.

const btcSigner = {
  signMessage: async (message: string, type?: string) => {
    // Implement your Bitcoin message signing logic
    return 'signature';
  },
  sendBitcoin: async (to: string, amount: number) => {
    // Implement your Bitcoin sending logic
    return 'txHash';
  }
};

const result = await transferBoostingBtc(
  'sender-address',
  'recipient-address',
  '1000000', // Amount in satoshis
  btcSigner
);

console.log('Transfer successful:', result.txHash);

increaseAllowance(senderAddress: string, spenderAddress: string, amount: string, btcSigner: MessageSigner): Promise

Increase the allowance for a spender.

const result = await increaseAllowance(
  'owner-address',
  'spender-address',
  '500000',
  btcSigner
);
console.log('Allowance increased:', result.txHash);

withdrawBoostingBtc(senderAddress: string, toAddress: string, amount: string, btcSigner: MessageSigner): Promise

Withdraw Boosting BTC tokens to a Bitcoin address.

const result = await withdrawBoostingBtc(
  'sender-address',
  'bitcoin-address',
  '1000000',
  btcSigner
);
console.log('Withdrawal successful:', result.txHash);

depositBoostingBtc(senderAddress: string, amount: string, btcSigner: MessageSigner): Promise

Deposit Bitcoin to get Boosting BTC tokens.

const result = await depositBoostingBtc(
  'sender-address',
  '1000000',
  btcSigner
);
console.log('Deposit successful:', result.txHash);

Advanced Usage

Custom Bitcoin Signer Implementation

import { MessageSigner } from '@nubit/thunderbolt-chain-sdk';

class CustomBitcoinSigner implements MessageSigner {
  async signMessage(message: string, type?: string): Promise<string> {
    // Implement BIP322 message signing
    // This should integrate with your wallet or signing service
    if (type === 'bip322-simple') {
      // Handle BIP322 simple signing
      return await this.signBip322Simple(message);
    }
    // Handle other signing types
    return await this.signDefault(message);
  }

  async sendBitcoin(to: string, amount: number): Promise<string> {
    // Implement Bitcoin transaction sending
    // Return transaction hash
    return 'transaction-hash';
  }

  private async signBip322Simple(message: string): Promise<string> {
    // Your BIP322 signing implementation
    return 'bip322-signature';
  }

  private async signDefault(message: string): Promise<string> {
    // Your default signing implementation
    return 'default-signature';
  }
}

const signer = new CustomBitcoinSigner();

Error Handling

import { BoostingBtcError } from '@nubit/thunderbolt-chain-sdk';

try {
  const result = await transferBoostingBtc(
    'sender',
    'recipient',
    'amount',
    signer
  );
} catch (error) {
  if (error instanceof BoostingBtcError) {
    console.error('Boosting BTC Error:', error.message, error.code);
  } else {
    console.error('Unknown error:', error);
  }
}

Transaction Broadcasting

import { broadcastTx } from '@nubit/thunderbolt-chain-sdk';

// Broadcast with different methods
const txBytes = new Uint8Array(/* your transaction bytes */);

// Synchronous broadcast (default)
const syncResult = await broadcastTx(txBytes, 'broadcast_tx_sync');

// Asynchronous broadcast
const asyncResult = await broadcastTx(txBytes, 'broadcast_tx_async');

// Commit broadcast (waits for inclusion in block)
const commitResult = await broadcastTx(txBytes, 'broadcast_tx_commit');

TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions:

import type {
  ThunderboltConfig,
  MessageSigner,
  TransferResponse,
  WithdrawResponse,
  DepositResponse,
  SendTxResponse,
  Response
} from '@nubit/thunderbolt-chain-sdk';

Examples

Complete Transfer Example

import { 
  createConfig,
  checkAddressActivation,
  queryBoostingBtcBalance,
  transferBoostingBtc,
  MessageSigner 
} from '@nubit/thunderbolt-chain-sdk';

async function performTransfer() {
  // Configure for devnet
  createConfig({
    chainId: 'thunderbolt-devnet',
    rpcEndpoint: 'https://dev-thunderbolt-gateway.nubit.network'
  });

  const senderAddress = 'bc1p...';
  const recipientAddress = 'bc1p...';
  const amount = '1000000'; // 0.01 BTC in satoshis

  try {
    // Check if addresses are activated
    const senderActivated = await checkAddressActivation(senderAddress);
    const recipientActivated = await checkAddressActivation(recipientAddress);
    
    if (!senderActivated || !recipientActivated) {
      throw new Error('Addresses must be activated first');
    }

    // Check balance
    const balance = await queryBoostingBtcBalance(senderAddress);
    if (parseInt(balance) < parseInt(amount)) {
      throw new Error('Insufficient balance');
    }

    // Perform transfer
    const signer: MessageSigner = {
      signMessage: async (message: string, type?: string) => {
        // Your signing implementation
        return 'signature';
      },
      sendBitcoin: async (to: string, amount: number) => {
        // Your Bitcoin sending implementation
        return 'txHash';
      }
    };

    const result = await transferBoostingBtc(
      senderAddress,
      recipientAddress,
      amount,
      signer
    );

    console.log('Transfer successful!', {
      txHash: result.txHash,
      success: result.success
    });

  } catch (error) {
    console.error('Transfer failed:', error);
  }
}

performTransfer();

License

This project is licensed under the ISC License - see the LICENSE file for details.