WDK logoWDK documentation

Configuration

Configuration options and settings for @tetherto/wdk-wallet-btc

Wallet Configuration

import WalletManagerBtc from '@tetherto/wdk-wallet-btc'

const wallet = new WalletManagerBtc(seedPhrase, {
  client: {
    type: 'electrum',
    clientConfig: {
      host: 'electrum.blockstream.info',
      port: 50002,
      protocol: 'tls'
    }
  },
  network: 'bitcoin'
})

Account Creation

// WalletAccountBtc is created by the WalletManagerBtc
// It takes the same configuration as the manager
const account = await wallet.getAccount(0) // Get account at index 0
const customAccount = await wallet.getAccountByPath("0'/0/5") // Custom path

Configuration Options

Client

The client option specifies how the wallet connects to Bitcoin network data. It accepts a pre-built IBtcClient, a client descriptor, or an ordered array of clients and descriptors for automatic failover.

Type: IBtcClient | BtcClientDescriptor | Array<IBtcClient | BtcClientDescriptor>

Default: Uses an Electrum descriptor for electrum.blockstream.info:50001.

Example:

const config = {
  client: {
    type: 'electrum',
    clientConfig: {
      host: 'fulcrum.frznode.com',
      port: 50002,
      protocol: 'tls'
    }
  }
}

BtcClientDescriptor supports:

TypeDescription
electrumCreates a TCP, TLS, or SSL Electrum client from clientConfig.
electrum-wsCreates a WebSocket Electrum client from clientConfig.
blockbook-httpCreates a stateless Blockbook HTTP client from clientConfig.

Built-in Transport Clients

The package still exports built-in transport clients when you want to instantiate the client yourself:

import {
  ElectrumTcp,   // TCP transport (default, port 50001)
  ElectrumTls,   // TLS transport (port 50002)
  ElectrumSsl,   // SSL transport (port 50002)
  ElectrumWs     // WebSocket transport
} from '@tetherto/wdk-wallet-btc'

// TCP (default)
const tcpClient = new ElectrumTcp({ host: 'electrum.blockstream.info', port: 50001 })

// TLS
const tlsClient = new ElectrumTls({ host: 'electrum.blockstream.info', port: 50002 })

// SSL
const sslClient = new ElectrumSsl({ host: 'electrum.blockstream.info', port: 50002 })

// WebSocket
const wsClient = new ElectrumWs({ url: 'wss://electrum.example.com:50004' })

Custom Bitcoin Client

You can implement your own client by implementing IBtcClient:

import { IBtcClient } from '@tetherto/wdk-wallet-btc'

class MyCustomBitcoinClient implements IBtcClient {
  // Implement the required interface methods
}

const wallet = new WalletManagerBtc(seedPhrase, {
  client: new MyCustomBitcoinClient(params),
  network: 'bitcoin'
})

Client Failover

Pass an ordered client array to retry connection failures against fallback clients. Set retries to control how many additional attempts can happen after the first failed call.

const wallet = new WalletManagerBtc(seedPhrase, {
  client: [
    {
      type: 'electrum',
      clientConfig: {
        host: 'primary-electrum.example',
        port: 50002,
        protocol: 'tls'
      }
    },
    {
      type: 'electrum',
      clientConfig: {
        host: 'secondary-electrum.example',
        port: 50002,
        protocol: 'tls'
      }
    }
  ],
  retries: 1,
  network: 'bitcoin'
})

Host

The host value belongs inside an electrum descriptor's clientConfig or an Electrum* client constructor. It is not a top-level wallet config option.

Type: string

Default: "electrum.blockstream.info"

Recommended: Configure your own Electrum server for production use. Public servers can be 10-300x slower and may fail for addresses with many transactions.

Example:

const config = {
  client: {
    type: 'electrum',
    clientConfig: {
      host: 'fulcrum.frznode.com',
      port: 50002,
      protocol: 'tls'
    }
  }
}

Port

The port value belongs inside an electrum descriptor's clientConfig or an Electrum* client constructor. It is not a top-level wallet config option.

Type: number

Default: 50001

Common Ports:

  • 50001 - TCP (default)
  • 50002 - TLS/SSL
  • 50003 - WebSocket

Example:

const config = {
  client: {
    type: 'electrum',
    clientConfig: {
      host: 'electrum.blockstream.info',
      port: 50002,
      protocol: 'tls'
    }
  }
}

Protocol

The protocol value belongs inside an electrum descriptor's clientConfig. It is not a top-level wallet config option.

Type: string

Values:

  • "tcp" - TCP transport (default)
  • "tls" - TLS transport
  • "ssl" - SSL transport

Default: "tcp"

Example:

const config = {
  client: {
    type: 'electrum',
    clientConfig: {
      host: 'electrum.blockstream.info',
      port: 50002,
      protocol: 'tls'
    }
  }
}

Retries

The retries option controls failover retry attempts when client is an array.

Type: number (optional)

Example:

const config = {
  client: [
    { type: 'electrum', clientConfig: { host: 'primary.example', port: 50002, protocol: 'tls' } },
    { type: 'electrum', clientConfig: { host: 'secondary.example', port: 50002, protocol: 'tls' } }
  ],
  retries: 2
}

Network

The network option specifies which Bitcoin network to use.

Type: string

Values:

  • "bitcoin" - Bitcoin mainnet (production)
  • "testnet" - Bitcoin testnet (development)
  • "regtest" - Bitcoin regtest (local testing)

Default: "bitcoin"

Example:

const config = {
  network: 'testnet' // Use testnet for development
}

BIP

The bip option specifies the address type derivation standard to use.

Type: number

Values:

  • 84 - BIP-84 (P2WPKH / Native SegWit) - addresses start with bc1 (mainnet) or tb1 (testnet)
  • 44 - BIP-44 (P2PKH / Legacy) - addresses start with 1 (mainnet) or m/n (testnet)

Default: 84

Example:

// Use legacy addresses
const config = {
  bip: 44
}

Electrum Server Configuration

Important: While the package defaults to electrum.blockstream.info:50001 for convenience, we strongly recommend configuring your own Electrum server for production use.

For Production:

  • Set up your own Fulcrum server for optimal performance and reliability
  • Use recent Fulcrum versions that support pagination for high-transaction addresses

For Development/Testing:

  • fulcrum.frznode.com:50001 - Generally faster than default
  • electrum.blockstream.info:50001 - Default fallback

Configuration Examples

import { ElectrumTcp, ElectrumTls } from '@tetherto/wdk-wallet-btc'

// Production with custom Fulcrum server
const productionClient = new ElectrumTls({
  host: 'your-fulcrum-server.com',
  port: 50002
})

const productionWallet = new WalletManagerBtc(seedPhrase, {
  client: productionClient,
  network: 'bitcoin'
})

// Development with alternative public server
const developmentClient = new ElectrumTcp({
  host: 'fulcrum.frznode.com',
  port: 50001
})

const developmentWallet = new WalletManagerBtc(seedPhrase, {
  client: developmentClient,
  network: 'bitcoin'
})

Network-Specific Configuration

Bitcoin Mainnet

import { ElectrumTcp } from '@tetherto/wdk-wallet-btc'

const client = new ElectrumTcp({
  host: 'electrum.blockstream.info', // Or your own server
  port: 50001
})

const wallet = new WalletManagerBtc(seedPhrase, {
  client,
  network: 'bitcoin'
})

Bitcoin Testnet

import { ElectrumTcp } from '@tetherto/wdk-wallet-btc'

const client = new ElectrumTcp({
  host: 'testnet.hsmiths.com', // Example testnet server
  port: 53011
})

const wallet = new WalletManagerBtc(seedPhrase, {
  client,
  network: 'testnet'
})

Bitcoin Regtest

import { ElectrumTcp } from '@tetherto/wdk-wallet-btc'

const client = new ElectrumTcp({
  host: 'localhost', // Local regtest node
  port: 50001
})

const wallet = new WalletManagerBtc(seedPhrase, {
  client,
  network: 'regtest'
})

Derivation Paths

Bitcoin wallet addresses are derived using BIP-32 hierarchical deterministic paths:

BIP-84 (Native SegWit) - Default

  • m/84'/0'/0'/0/0 for mainnet account 0, address 0
  • m/84'/1'/0'/0/0 for testnet/regtest account 0, address 0

Addresses start with bc1 (mainnet) or tb1 (testnet).

BIP-44 (Legacy)

  • m/44'/0'/0'/0/0 for mainnet account 0, address 0
  • m/44'/1'/0'/0/0 for testnet/regtest account 0, address 0

Addresses start with 1 (mainnet) or m/n (testnet).

Default Derivation Path Change in v1.0.0-beta.4+

The default derivation path was updated in v1.0.0-beta.4 to use BIP-84 (Native SegWit) instead of BIP-44 (Legacy):

  • Previous path (up to v1.0.0-beta.3): m/44'/0'/0'/0/{index} (Legacy addresses)
  • Current path (v1.0.0-beta.4+): m/84'/0'/0'/0/{index} (Native SegWit addresses)

If you're upgrading from an earlier version, existing wallets created with the old path will generate different addresses. Make sure to migrate any existing wallets or use the old path explicitly if needed for compatibility.

Use getAccountByPath to supply an explicit derivation path when importing or recreating legacy wallets.

Complete Configuration Example

import WalletManagerBtc, { ElectrumTls } from '@tetherto/wdk-wallet-btc'

// Create Electrum client
const client = new ElectrumTls({
  host: 'your-electrum-server.com', // Replace with your server
  port: 50002
})

// Create wallet manager with configuration
const wallet = new WalletManagerBtc(seedPhrase, {
  client,
  network: 'bitcoin',
  bip: 84 // Native SegWit (default)
})

// Get accounts (inherit configuration from manager)
const account0 = await wallet.getAccount(0)
const account1 = await wallet.getAccount(1)
const customAccount = await wallet.getAccountByPath("0'/0/5")

// Clean up when done
wallet.dispose()

Performance Considerations

Electrum Server Performance:

  • Public servers like Blockstream's can be significantly slower
  • Addresses with many transactions may cause timeouts
  • Custom Fulcrum servers provide better performance and reliability
  • Consider server location and network latency

Configuration Tips:

  • Use fulcrum.frznode.com for better development performance
  • Set up your own Fulcrum server for production
  • Monitor connection stability and implement retry logic
  • Consider using multiple backup servers

Need Help?

On this page