RGB API JavaScript SDK

A JavaScript/TypeScript SDK for interacting with RGB Lightning Node APIs. This SDK provides a simple and intuitive interface for managing RGB assets, lightning network operations, and on-chain transactions.

Features

• Modular Architecture: Organized into logical modules (node, onchain, RGB, lightning, swaps)
• Full TypeScript Support: Complete type definitions for all APIs
• Promise-based: Modern async/await API
• Error Handling: Comprehensive error handling with meaningful messages
• Flexible Configuration: Support for custom headers, base URLs, and axios configurations

Installation

npm install @lnfi-network/rgb-api-js-sdk

or

yarn add @lnfi-network/rgb-api-js-sdk

Quick Start

import { RgbApiClient } from '@lnfi-network/rgb-api-js-sdk';

// Initialize the client
const client = new RgbApiClient({
  baseUrl: 'http://localhost:3001'
});

// Check node status
const nodeInfo = await client.node.getNodeInfo();
console.log('Node Info:', nodeInfo);

// List RGB assets
const assets = await client.rgb.listAssets();
console.log('Assets:', assets);

Configuration

Basic Configuration

const client = new RgbApiClient({
  baseUrl: 'http://localhost:3001'
});

Advanced Configuration

const client = new RgbApiClient({
  baseUrl: 'https://your-rgb-node.com',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Custom-Header': 'value'
  },
  axiosConfig: {
    timeout: 10000,
    proxy: false
  }
});

API Modules

Node Operations

// Get node information
const nodeInfo = await client.node.getNodeInfo();

// Check node state (0: NON_EXISTING, 1: LOCKED, 4: SERVER_ACTIVE)
const state = await client.node.getNodeState();

// Get network information
const networkInfo = await client.node.getNetworkInfo();

// Validate indexer URL
await client.node.checkIndexerUrl({ 
  indexer_url: 'electrs:50001' 
});

// Sign a message
const signature = await client.node.signMessage({ 
  message: 'Hello RGB' 
});

RGB Asset Operations

// List all assets
const assets = await client.rgb.listAssets();

// Get asset balance
const balance = await client.rgb.getAssetBalance({
  asset_id: 'rgb1qyfe883hey6jrgj2xvk5g3dfmfqfzm7a4wez4pd2krf7ltsxffd6u6nqcg'
});

// Get asset metadata
const metadata = await client.rgb.getAssetMetadata({
  asset_id: 'rgb1qyfe883hey6jrgj2xvk5g3dfmfqfzm7a4wez4pd2krf7ltsxffd6u6nqcg'
});

// Send assets
await client.rgb.sendAssets({
  recipient_map: {
    'asset_id': [{
      recipient: 'recipient_address',
      amount: 1000
    }]
  }
});

// Convert hex to RGB asset ID
const rgbId = await client.rgb.assetIdFromHexBytes({
  hex_bytes: '9266c8ffd37caee3809ebe465d9eb29666613eb47737f3f27444c56720b58d74'
});
console.log('RGB Asset ID:', rgbId.asset_id);
// Output: rgb:kmbI~9N8-ruOAnr5-GXZ6ylm-ZhPrR3N-~PydETF-ZyC1jXQ

// Convert RGB asset ID to hex
const hexBytes = await client.rgb.assetIdToHexBytes({
  asset_id: 'rgb:kmbI~9N8-ruOAnr5-GXZ6ylm-ZhPrR3N-_PydETF-ZyC1jXQ'
});
console.log('Hex Bytes:', hexBytes.hex_bytes);
// Output: 9266c8ffd37caee3809ebe465d9eb29666613eb47737e3f27444c56720b58d74

Lightning Network Operations

// List channels
const channels = await client.lightning.listChannels();

// Create invoice
const invoice = await client.lightning.createInvoice({
  amount_msat: 10000,
  description: 'Payment for services'
});

// Decode RGB Lightning invoice
const decoded = await client.lightning.decodeRGBLNInvoice(
  'lnbcrt30u1p5f9szd...'
);

// Pay invoice
await client.lightning.payInvoice({
  invoice: 'lnbcrt30u1p5f9szd...'
});

On-chain Operations

// Get new address
const address = await client.onchain.getAddress();

// List transactions
const transactions = await client.onchain.listTransactions();

// Send Bitcoin
await client.onchain.sendBtc({
  address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  amount: 100000 // satoshis
});

Swap Operations

// List swaps
const swaps = await client.swaps.listSwaps();

// Create swap
await client.swaps.createSwap({
  // swap parameters
});

TypeScript Support

The SDK includes comprehensive TypeScript definitions:

import { RgbApiClient, NodeState, AssetSchema } from '@lnfi-network/rgb-api-js-sdk';

const client = new RgbApiClient({ 
  baseUrl: 'http://localhost:3001' 
});

// Type-safe operations
const state: number = await client.node.getNodeState();
if (state === 4) { // SERVER_ACTIVE
  console.log('Node is active and ready');
}

// Filter assets by schema
const assets = await client.rgb.listAssets({
  filter_asset_schemas: [AssetSchema.NIA, AssetSchema.CFA]
});

Error Handling

The SDK provides structured error handling:

try {
  const nodeInfo = await client.node.getNodeInfo();
} catch (error) {
  if (error.message.includes('Network Error')) {
    console.error('Unable to connect to RGB node');
  } else if (error.message.includes('API Error')) {
    console.error('API returned an error:', error.message);
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Development

Building

npm run build

Testing

# Run all tests
npm test

# Run specific test file
npm test test/rgb.integration.test.js

Development Mode

npm run dev

Examples

Check the examples/ directory for complete usage examples:

• Node.js Example

API Reference

For detailed API documentation, refer to:

• Type definitions: src/types.d.ts
• Module implementations: src/modules/

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.