Helios TypeScript SDK

The Helios SDK is a TypeScript library for building Bitcoin applications with support for the Helios Gateway, a hybrid L2/L3 platform for multi-asset transactions and state transitions.

Installation

npm install helios-sdk

Quick Start

Get started with the Helios SDK in 5 minutes:

1. Install and Import

import { HeliosWallet } from 'helios-sdk'

2. Create Wallet

const wallet = await HeliosWallet.create({
  gatewayUrl: 'https://gateway-mainnet.postfun.xyz'
})

3. Login

await wallet.login('your_nostr_secret_key')

4. Check Balance

const balance = await wallet.getBalance()
console.log('Balance:', balance)

5. Make a Transfer

const txId = await wallet.transfer({
  toAddress: 'recipient_address',
  amount: 1000,
  asset: 'BTC'
})

That's it! You're now ready to build Bitcoin applications with Helios. See the sections below for advanced features like swaps, Lightning ramps, and custom intents.

Examples

The SDK includes comprehensive example scripts in the examples/ directory that demonstrate real-world usage patterns:

🚀 Basic Wallet Setup

node examples/basic-wallet.js

Learn wallet creation, authentication, and balance checking.

💸 Transfers and Payments

node examples/transfers.js btc

Explore BTC transfers, multi-asset payments, and VTXO consolidation.

🔄 Swaps and Intents

node examples/swaps.js simple-swap

Master asset swaps, IntentBuilder, and complex multi-operation transactions.

⚡ Lightning Ramps

node examples/lightning-ramps.js onboard

Discover Lightning onboarding/offboarding and real-time monitoring.

🛡️ Error Handling

node examples/error-handling.js validation

Implement robust error handling, retry logic, and input validation.

For complete examples documentation, see examples/README.md.

Usage

Creating a Helios Wallet

import { SingleKey, HeliosWallet } from 'helios-sdk'

// Create a Helios wallet connected to the gateway
const wallet = await HeliosWallet.create({
  gatewayUrl: 'https://gateway-mainnet.postfun.xyz',
})

// Login with your Nostr secret key
await wallet.login('your_nsec_here')

Checking Balance and State

// Get multi-asset balance information
const balance = await wallet.getBalance()
console.log('Total Balance:', balance)
// Example balance structure:
// {
//   "BTC": { available: 100000, total: 150000 },
//   "ArkUSD": { available: 5000, total: 5000 },
//   "tBTC": { available: 0, total: 0 }
// }

// Get VTXOs with multi-asset holdings
const vtxos = await wallet.getVtxos()
console.log('VTXOs:', vtxos)
// Example VTXO structure:
// [{
//   id: "vtxo_123",
//   value: 100000,
//   status: "settled",
//   holdings: { "BTC": 100000, "ArkUSD": 5000 }
// }]

// Get transaction history
const history = await wallet.getHistory()
console.log('History:', history)

Onboarding and Offboarding

import { HeliosRamps } from 'helios-sdk'

const ramps = new HeliosRamps(wallet)

// Onboard funds via Lightning
const onboarding = await ramps.onboardWithLightning('BTC', 100000)
console.log('Pay invoice:', onboarding.invoice)

// Monitor onboarding completion
ramps.waitForOnboardingCompletion(onboarding.invoice, (completed) => {
  if (completed) {
    console.log('Onboarding completed!')
  }
})

// Offboard funds via Lightning
const offboarding = await ramps.offboardWithLightning('lnbc1...')
console.log('Offboard success:', offboarding.success)

Building State Transition Intents

import { IntentBuilder } from 'helios-sdk'

// Build a complex swap operation
const builder = new IntentBuilder(wallet)

const intentPayload = await builder
  .addSwap({
    fromAsset: 'ArkUSD',
    fromAmount: 2000,
    toAsset: 'tBTC',
    toAmount: 2000000,
    fromVtxo: 'vtxo_id_user_1',
    poolVtxo: 'vtxo_id_amm_pool_1',
  })
  .addFee() // Automatically adds fee payment
  .build()

// Submit the intent
const txId = await wallet.submitIntent(intentPayload)
console.log('Transaction ID:', txId)

// Simple transfer
const transferTxId = await wallet.transfer({
  toAddress: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx',
  amount: 50000,
  asset: 'BTC'
})

// VTXO consolidation
const consolidateTxId = await wallet.consolidateVtxos(['vtxo_1', 'vtxo_2'])

Gateway Information

// Get gateway configuration
const gatewayInfo = wallet.getGatewayInfo()
console.log('Gateway Info:', gatewayInfo)
// Example:
// {
//   arkdUrl: 'https://arkd.helios.sh',
//   esploraUrl: 'https://esplora.helios.sh',
//   feeAsset: 'BTC',
//   feeAmount: 10,
//   network: 'testnet',
//   unilateralExitDelay: 1008
// }

// Get wallet addresses
const arkAddress = await wallet.getArkAddress()
const boardingAddress = await wallet.getBoardingAddress()
console.log('Ark Address:', arkAddress)
console.log('Boarding Address:', boardingAddress)

Unilateral Exit

The Helios SDK preserves the original Arkade SDK's unilateral exit functionality:

import { Unroll, OnchainWallet } from 'helios-sdk'

// Create an onchain wallet for exit fees
const onchainWallet = new OnchainWallet(wallet.identity, 'testnet')

// Unroll a specific VTXO
const vtxo = { txid: 'your_vtxo_txid', vout: 0 }
const session = await Unroll.Session.create(
  vtxo,
  onchainWallet,
  onchainWallet.provider,
  wallet.indexerProvider
)

// Process unrolling steps
for await (const step of session) {
  switch (step.type) {
    case Unroll.StepType.WAIT:
      console.log(`Waiting for transaction ${step.txid} to be confirmed`)
      break
    case Unroll.StepType.UNROLL:
      console.log(`Broadcasting transaction ${step.tx.id}`)
      break
    case Unroll.StepType.DONE:
      console.log(`Unrolling complete for VTXO ${step.vtxoTxid}`)
      break
  }
}

// Complete the exit after timelock expires
await Unroll.completeUnroll(
  wallet,
  [vtxo.txid],
  onchainWallet.address
)

Development

Requirements

• pnpm - Package manager
• nigiri - For running integration tests with a local Bitcoin regtest network

Setup

1. Install dependencies:

pnpm install
pnpm format
pnpm lint

2. Install nigiri for integration tests:

curl https://getnigiri.vulpem.com | bash

Running the wallet in a service worker

1. Create a service worker file

// service-worker.ts
import { Worker } from 'helios-sdk'

// Worker handles communication between the main thread and service worker
new Worker().start()

2. Instantiate the ServiceWorkerWallet

// specify the path to the service worker file
// this will automatically register the service worker
const serviceWorker = await setupServiceWorker('/service-worker.js')
const wallet = new ServiceWorkerWallet(serviceWorker)

// Initialize the wallet
await wallet.init({
  privateKey: 'your_private_key_hex',
  // Esplora API, can be left empty mempool.space API will be used
  esploraUrl: 'https://mutinynet.com/api', 
  // OPTIONAL Helios Gateway connection information
  gatewayUrl: 'https://gateway-mainnet.postfun.xyz',
})

// check service worker status
const status = await wallet.getStatus()
console.log('Service worker status:', status.walletInitialized)

// clear wallet data stored in the service worker memory
await wallet.clear()

For complete API documentation, visit our TypeScript documentation.

Development

Requirements

• pnpm - Package manager
• nigiri - For running integration tests with a local Bitcoin regtest network

Setup

1. Install dependencies:

pnpm install
pnpm format
pnpm lint

2. Install nigiri for integration tests:

curl https://getnigiri.vulpem.com | bash

Running Tests

# Run all tests
pnpm test

# Run unit tests only
pnpm test:unit

# Run integration tests with Helios Gateway
nigiri start --ark
pnpm test:setup # Run setup script for integration tests
pnpm test:integration
nigiri stop --delete

# Run integration tests with Helios Gateway via Docker (requires nigiri)
nigiri start
pnpm test:up-docker
pnpm test:setup-docker # Run setup script for integration tests
pnpm test:integration-docker
pnpm test:down-docker
nigiri stop --delete

# Watch mode for development
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

Building the documentation

# Build the TS doc
pnpm docs:build
# open the docs in the browser
pnpm docs:open

Releasing

# Release new version (will prompt for version patch, minor, major)
pnpm release

# You can test release process without making changes
pnpm release:dry-run

# Cleanup: checkout version commit and remove release branch
pnpm release:cleanup

Helios SDK Features

The Helios SDK provides:

• Gateway Integration: Connect to Helios Gateway for state transitions
• Multi-Asset Support: Handle BTC, Taproot Assets, and IOUs
• IntentBuilder: Fluent interface for building complex transactions
• Session Management: Secure Nostr-based session handling
• Lightning Ramps: Onboard/offboard via Lightning Network
• Unilateral Exit: Trust-minimized exit mechanism preserved from Arkade
• Service Worker Support: Browser-based wallet functionality
• TypeScript Support: Full type safety and IntelliSense

Key Differences from Arkade SDK

• Uses Helios Gateway instead of direct Ark server connections
• Supports multi-asset transactions and IOUs
• Intent-based transaction building via IntentBuilder
• Session-based authentication with Nostr keys
• Gateway-discovered backend URLs and configuration
• Enhanced balance and state management for complex assets

License

MIT