@synonymdev/blocktank-lsp-btc-client

blocktank-lsp-btc-client

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

Usage

Watched Address

Watched Addresses are onchain addresses that you get notified about in case of a incoming transaction.

Create WatchedAddress

import { LspBtcClient, IWatchedAddress } from '@synonymdev/blocktank-lsp-btc-client';

const daysToWatch = 1 // How long in time this address is watched for. Default: 1
const maxWatchedBlockConfirmations = 6 // How many blockConfirmations you want to receive events for. Default: 6.
const client = new LspBtcClient()
const watched: IWatchedAddress = await client.createAddress(daysToWatch, maxWatchedBlockConfirmations)
console.log('Newly created address', watched.address)

Listen for updates

Update events are sent when a tx gets added/removed to the watched address or the tx confirmation state changes.

• Enters mempool (also due to reorg).
• Leaves mempool (rbf).
• Every block confirmations until maxWatchedBlockConfirmations.

Important: Due to reorgs, the number of block confirmations can go backward!

import {LspBtcClient, IWatchedAddress, LspBtcEventListener, IAddressUpdateEvent, SuspiciousZeroConfReason } from "@synonymdev/blocktank-lsp-btc-client";

const listener = new LspBtcEventListener()
await listener.init()
const client = new LspBtcClient()
await listener.listenToAddressUpdates(async message => {
    const event: IAddressUpdateEvent = message.content

    // Pull the latest invoice
    const watched = await client.getAddress(event.id)

    if (watched.isBlacklisted) {
        // DO NOT TOUCH! Address received a tx from a blacklisted address.
        return;
    }

    const _1ConfirmationTxs = watched.transactions.filter(tx => {
        // Do your own risk analysis here.
        // Block confirmations are great. 
        // 0conf is always risky.
        // Do NOT use 0conf for high value txs or high value products.
        return tx.blockConfirmationCount >= 1 || tx.suspicious0ConfReason === SuspiciousZeroConfReason.NONE;
    })

    const amountSat = _1ConfirmationTxs.reduce((acc, tx) => acc + tx.amountSat, 0)
    console.log(`Received ${amountSat} satoshis on address ${watched.address}`)
})

Important blockConfirmationCount may be higher than maxWatchedBlockConfirmations. blockConfirmationCount may also jump suddendly from 0 to 6. So always check blockConfirmationCount with >=.

Info Always close your event listener with await listener.close() when you are done listening to events.

Regtest methods

For regtest, the client exposes some methods:

• regtestMineBlocks
• regtestSendPayment

Checkout the types to see how to use them. They are very simple.

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. Build: npm run build.
7. Publish to npm: npm publish.