blocktank-lsp-http-client

Client to interact with the blocktank-lsp-http service.

Usage

Pay and open channel

import { BlocktankClient } from '@synonymdev/blocktank-lsp-http-client';

const client = new BlocktankClient();
const lspBalanceSat = 100*1000
const leaseDurationWeeks = 10
const order = await client.createOrder(lspBalanceSat, leaseDurationWeeks)
console.log(`Order expires at ${order.expiresAt}. Pay and open before this date.`)

// Pay either ln invoice or onchain. Ln invoice is automatically refunded if the channel is not opened before the order expires.
console.log(`Either pay ${order.feeSat}sat to bolt11 invoice ${order.payment.bolt11Invoice.request} or to onchain to ${order.payment.onchain.address}.`)

const expected0ConfFee = await client.getMin0ConfTxFee(order.id)
console.log(`Onchain payments that should be accepted as 0conf need to have a minimal fee of ${expected0ConfFee.satVByte}sat/vbyte.`)

// Check order status
const updatedOrder = await client.getOrder(order.id)
console.log(`Payment status: ${updatedOrder.payment.state}.`)
console.log(`Establish a peer connection to ${updatedOrder.lspNode.connectionStrings} in case you do not have a public address.`)

// Open channel
const announceChannel = true
// If only a pubkey is provided here, the client MUST establish a peer connection to the LSP node before opening the channel.
const connectionStringOrPubkey = '03775370500b8c8642617bced873e7914eaec4f6a79c9ca99043224a1b28677082@172.19.0.7:9735'
const openOrder = await client.openChannel(connectionStringOrPubkey, announceChannel)
console.log(`Funding tx outpoint: ${order.channel.fundingTx.id}:${order.channel.fundingTx.vout}.`)

Advanced Order Options

These options can be used to customize the order.

import { BlocktankClient } from '@synonymdev/blocktank-lsp-http-client';

const client = new BlocktankClient();
const lspBalanceSat = 100*1000
const leaseDurationWeeks = 10
const order = await client.createOrder(lspBalanceSat, leaseDurationWeeks, {
    clientBalanceSat: 20*2000, // How much initial spending balance client like to have. Max the same as lspBalanceSat.
    couponCode: 'SATOSHI_20PERCENT',
    lspNodeId: '0296b2db342fcf87ea94d981757fdf4d3e545bd5cef4919f58b5d38dfdd73bf5c9', // Choose the LSP node to open the channel with. MUST be from the list in `client.getInfo()`. If not set, the LSP will choose the best node for you.
})

General Info and Order Boundaries

LSP node list + order boundaries. These values are used to validate the order.

import { BlocktankClient } from '@synonymdev/blocktank-lsp-http-client';

const client = new BlocktankClient();
const info = await client.getInfo()

console.log(`Blocktank info`, info)
{
    version: 2,
    nodes: [ // Blocktank LSP nodes
      {
         alias: "Blocktank",
         pubkey: "0296b2db342fcf87ea94d981757fdf4d3e545bd5cef4919f58b5d38dfdd73bf5c9",
         connectionStrings: [
           "0296b2db342fcf87ea94d981757fdf4d3e545bd5cef4919f58b5d38dfdd73bf5c9@146.148.127.140:9735"
         ]
       }    
    ],
    options: {
        minChannelSizeSat: 1000, // Min channel size in satoshi. lspBalanceSat + clientBalanceSat MUST be >= minChannelSizeSat.
        maxChannelSizeSat: 3170000, // Max channel size in satoshi. lspBalanceSat + clientBalanceSat MUST be <= minChannelSizeSat.
        minExpiryWeeks: 1, // How long the channel MUST be leased for min.
        maxExpiryWeeks: 53, // How long the channel may be leased for max.
        minPaymentConfirmations: 0, // Minimum onchain payment confirmations required for the order.
        minHighRiskPaymentConfirmations: 1, // Minimum onchain payment confirmations required for orders with clientBalance.
        max0ConfClientBalanceSat: 317000, // Max clientBalanceSat for orders with 0 payment confirmations.
}

Channel Open error handling

import { BtChannelOrderErrorType } from '@synonymdev/blocktank-lsp-http-client';

try {
    await client.openChannel(connectionStringOrPubkey, announceChannel)
} catch (e) {
    if (e.data?.name === 'ChannelOpenError') {
        const errorType: BtChannelOrderErrorType = e.data.type

        if (errorType === BtChannelOrderErrorType.PEER_NOT_REACHABLE) {
            // LSP could not establish a peer connection to the client.
        } else if (errorType === BtChannelOrderErrorType.WRONG_ORDER_STATE) {
            // Order is not in the right state to open the channel. Order must be paid and not expired.
        } else if (errorType === BtChannelOrderErrorType.CHANNEL_REJECTED_BY_DESTINATION) {
            // Client rejected the channel opening.
        } else if (errorType === BtChannelOrderErrorType.CHANNEL_REJECTED_BY_LSP) {
            // LSP rejected the channel or node.
        } else if (errorType === BtChannelOrderErrorType.BLOCKTANK_NOT_READY) {
            // Blocktank is not ready.
        }
    }
    // Other error
    throw e
}

Versioning

1. Increase version in package.json.
2. Add changes to CHANGELOG.md.
3. Commit changes.
4. Tag new version: git tag v0.1.0.
5. Push tag git push origin v0.1.0.
6. Publish to npm: npm publish.