To help you get started, we've collected the most common ways that ln-service is being used within popular public projects.

Lightning Network Service

Overview

The core of this project is a gRPC interface for node.js projects, available through npm.

Supported LND versions:

• v0.17.0-beta to v0.17.4-beta
• v0.16.0-beta to v0.16.4-beta
• v0.15.2-beta to v0.15.5-beta
• v0.14.4-beta to v0.14.5-beta

For typescript-ready methods, check out https://github.com/alexbosworth/lightning#readme

Installing LND

There is a guide to installing LND on the LND repository: https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md

Example LND configuration options (~/.lnd/lnd.conf)

[Application Options]
externalip=IP
rpclisten=0.0.0.0:10009

[Bitcoin]
bitcoin.active=1
bitcoin.mainnet=1
bitcoin.node=bitcoind

If you are interacting with your node remotely, make sure to set (in [Application Options])

tlsextradomain=YOURDOMAIN

If you're adding TLS settings, regenerate the cert and key by stopping lnd, deleting the tls.cert and tls.key - then restart lnd to regenerate.

If you're going to use extended gRPC APIs, make sure to add the APIs to make tags.

make && make install tags="autopilotrpc chainrpc invoicesrpc peersrpc routerrpc signrpc walletrpc watchtowerrpc wtclientrpc"

Using gRPC

You can install ln-service service via npm

npm install ln-service

To use authenticated methods you will need to provide LND credentials.

To export the credentials via a command, you can install balanceofsatoshis: npm install -g balanceofsatoshis and export via bos credentials --cleartext

Or you can export them manually:

Run base64 on the tls.cert and admin.macaroon files to get the encoded authentication data to create the LND connection. You can find these files in the LND directory. (~/.lnd or ~/Library/Application Support/Lnd)

base64 tls.cert
base64 data/chain/bitcoin/mainnet/admin.macaroon

Be careful to avoid copying any newline characters in creds. To exclude them:

base64 -w0 ~/.lnd/tls.cert
base64 -w0 ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

You can then use these to interact with your LND node directly:

const lnService = require('ln-service');

const {lnd} = lnService.authenticatedLndGrpc({
  cert: 'base64 encoded tls.cert',
  macaroon: 'base64 encoded admin.macaroon',
  socket: '127.0.0.1:10009',
});

// Callback syntax
lnService.getWalletInfo({lnd}, (err, result) => {
  const nodeKey = result.public_key;
});

// Promise syntax
const nodePublicKey = (await lnService.getWalletInfo({lnd})).public_key;

An unauthenticatedLndGrpc function is also available for unlocker methods.

Subscriptions

• Besides the events listed in this documentation, all EventEmitter objects returned by any of the subscribeTo... methods also offer an error event. This event is triggered e.g. when LND is shut down. So, in order to detect and correctly handle such a situation, robust client code should generally also add a listener for the error event. For example, a function that will wait for and return the next forward but throw an exception when LND is either not reachable or shuts down while waiting for the forward would look something like this:

  const getNextForward = async (lnd) => {
      const emitter = subscribeToForwards({ lnd });
  
      try {
          return await new Promise((resolve, reject) => {
              emitter.on("forward", resolve);
              // Without the following line, the function will never throw
              // when the connection is lost after calling subscribeToForwards
              emitter.on("error", reject);
          });
      } finally {
          emitter.removeAllListeners();
      }
  };
  

• After the last listener has been removed from an EventEmitter object, the subscription is released and subsequent attempts to add a listener will result in an error. Call subscribeTo... again and add new listeners to the new EventEmitter object.

All Methods

• addAdvertisedFeature - Advertise a supported feature
• addExternalSocket - Advertise a new p2p host:ip address
• addPeer - Connect to a peer
• authenticatedLndGrpc - LND API Object
• beginGroupSigningSession - Start MuSig2 session
• broadcastChainTransaction - Push a chain tx
• cancelHodlInvoice - Cancel a held or any open invoice
• cancelPendingChannel - Cancel a pending open channel
• changePassword - Change the wallet unlock password
• closeChannel - Terminate an open channel
• connectWatchtower - Connect a watchtower
• createChainAddress - Get a chain address to receive at
• createHodlInvoice - Make a HODL HTLC invoice
• createInvoice - Make a regular invoice
• createSeed - Generate a wallet seed for a new wallet
• createSignedRequest - create a signed payment request
• createUnsignedRequest - create an unsigned invoice
• createWallet - Make a new wallet
• decodePaymentRequest - Decode a Lightning invoice
• deleteChainTransaction - Remove chain transaction
• deleteFailedPayAttempts - Remove records of failed pay attempts
• deleteFailedPayments - Remove records of payments that failed
• deleteForwardingReputations - Wipe node reps
• deletePayment - Delete the record of a single past payment
• deletePayments - Delete entire history of past payments
• deletePendingChannel - Delete a pending channel that will never confirm due to a conflicting confirmed transaction
• diffieHellmanComputeSecret - Get DH shared key
• disableChannel - Disable a channel for outgoing payments
• disconnectWatchtower - Disconnect a watchtower
• enableChannel - Enable a channel for outgoing payments
• endGroupSigningSession - Complete MuSig2 session
• fundPendingChannels - Fund pending open channels
• fundPsbt - Create an unsigned PSBT with funding inputs and spending outputs
• getAccessIds - Get granted macaroon root access ids
• getAutopilot - Get autopilot status or node scores
• getBackup - Get a backup of a channel
• getBackups - Get a backup for all channels
• getBlock - Get the raw block data given a block id in the chain
• getBlockHeader - Get the raw block header for a block
• getChainAddresses - Get created chain addresses
• getChainBalance - Get the confirmed chain balance
• getChainFeeEstimate - Get a chain fee estimate
• getChainFeeRate - Get the fee rate for a conf target
• getChainTransaction - Get single wallet transaction
• getChainTransactions - Get all chain transactions
• getChannel - Get graph information about a channel
• getChannelBalance - Get the balance of channel funds
• getChannels - Get all open channels
• getClosedChannels - Get previously open channels
• getConfiguration - Get configuration information
• getConnectedWatchtowers - Get connected towers
• getEphemeralChannelIds - Get other channel ids
• getFailedPayments - Get payments that were failed back
• getFeeRates - Get current routing fee rates
• getForwardingConfidence - Get pairwise confidence
• getForwardingReputations - Get graph reputations
• getForwards - Get forwarded routed payments
• getHeight - Get the current best chain height and block hash
• getIdentity - Get the node's identity key
• getInvoice - Get a previously created invoice
• getInvoices - Get all previously created invoices
• getLockedUtxos - Get all previously locked UTXOs
• getMasterPublicKeys - Get a list of master pub keys
• getMethods - Get available methods and associated permissions
• getNetworkCentrality - Get centrality score for nodes
• getNetworkGraph - Get the channels and nodes of the graph
• getNetworkInfo - Get high-level graph info
• getNode - Get graph info about a single node and its channels
• getPathfindingSettings - Get pathfinding system settings
• getPayment - Get a past payment
• getPayments - Get all past payments
• getPeers - Get all connected peers
• getPendingChainBalance - Get pending chain balance
• getPendingChannels - Get channels in pending states
• getPendingPayments - Get in-flight outgoing payments
• getPublicKey - Get a public key out of the seed
• getRouteConfidence - Get confidence in a route
• getRouteThroughHops - Get a route through nodes
• getRouteToDestination - Get a route to a destination
• getSettlementStatus - Get status of a received HTLC
• getSweepTransactions - Get transactions sweeping to self
• getTowerServerInfo - Get information about tower server
• getUtxos - Get on-chain unspent outputs
• getWalletInfo - Get general wallet info
• getWalletStatus - Get the status of the wallet
• getWalletVersion - Get the build and version of the LND
• grantAccess - Grant an access credential macaroon
• grpcProxyServer - REST proxy server for calling to gRPC
• isDestinationPayable - Check can pay to destination
• lockUtxo - Lock a UTXO temporarily to prevent it being used
• openChannel - Open a new channel
• openChannels - Open channels with external funding
• parsePaymentRequest - Parse a BOLT11 Payment Request
• partiallySignPsbt - Sign a PSBT without finalizing it
• pay - Send a payment
• payViaPaymentDetails - Pay using decomposed details
• payViaPaymentRequest - Pay using a payment request
• payViaRoutes - Make a payment over specified routes
• prepareForChannelProposal - setup for a channel proposal
• probeForRoute - Actively probe to find a payable route
• proposeChannel - Offer a channel proposal to a peer
• recoverFundsFromChannel - Restore a channel
• recoverFundsFromChannels - Restore all channels
• removeAdvertisedFeature - Remove feature from ad
• removeExternalSocket - Remove a p2p host:ip announce
• removePeer - Disconnect from a connected peer
• requestChainFeeIncrease - Request a CPFP spend on a UTXO
• restrictMacaroon - Add limitations to a macaroon
• revokeAccess - Revoke all access macaroons given to an id
• routeFromChannels - Convert channel series to a route
• sendMessageToPeer - Send a custom message to a peer
• sendToChainAddress - Send on-chain to an address
• sendToChainAddresses - Send on-chain to addresses
• sendToChainOutputScripts - Send to on-chain script outputs
• setAutopilot - Turn autopilot on and set autopilot scores
• settleHodlInvoice - Accept a HODL HTLC invoice
• signBytes - Sign over arbitrary bytes with node keys
• signChainAddressMessage - Sign with chain address
• signMessage - Sign a message with the node identity key
• signPsbt - Sign and finalize an unsigned PSBT using internal keys
• signTransaction - Sign an on-chain transaction
• stopDaemon - Stop lnd
• subscribeToBackups - Subscribe to channel backups
• subscribeToBlocks - Subscribe to on-chain blocks
• subscribeToChainAddress - Subscribe to receives
• subscribeToChainSpend - Subscribe to chain spends
• subscribeToChannels - Subscribe to channel statuses
• subscribeToForwardRequests - Interactively route
• subscribeToForwards - Subscribe to HTLC events
• subscribeToGraph - Subscribe to network graph updates
• subscribeToInvoice - Subscribe to invoice updates
• subscribeToInvoices - Subscribe to all invoices
• subscribeToOpenRequests - Approve open requests
• subscribeToPastPayment - Subscribe to a payment
• subscribeToPastPayments - Subscribe to all sent payments
• subscribeToPayViaDetails - Pay using details
• subscribeToPayViaRequest - Pay using a request
• subscribeToPayViaRoutes - Pay using routes
• subscribeToPayments - Subscribe to outgoing payments
• subscribeToPeerMessages - Listen to incoming custom messages
• subscribeToPeers - Subscribe to peers connectivity
• subscribeToProbe - Subscribe to a probe for a route
• subscribeToProbeForRoute - Probe for a route
• subscribeToRpcRequests - Subscribe to rpc requests
• subscribeToTransactions - Subscribe to chain tx
• subscribeToWalletStatus - Subscribe to node state
• unauthenticatedLndGrpc - LND for locked lnd APIs
• unlockUtxo - Release a locked UTXO so that it can be used again
• unlockWallet - Unlock a locked lnd
• updateAlias - Update node graph identity alias
• updateChainTransaction - Update a chain transaction
• updateColor - Update node graph color value
• updateConnectedWatchtower - Update watchtower
• updateGroupSigningSession - Sign with MuSig2
• updatePathfindingSettings - Update pathfinding configuration
• updateRoutingFees - Change routing fees
• verifyAccess - Verify a macaroon has access
• verifyBackup - Verify a channel backup
• verifyBackups - Verify a set of channel backups
• verifyBytesSignature - Verify a signature over bytes
• verifyChainAddressMessage - Check chain message
• verifyMessage - Verify a message signed by a node identity

Additional Libraries

• bolt01 - bolt01 messaging utilities
• bolt03 - bolt03 transaction utilities
• bolt07 - bolt07 channel gossip utilities
• bolt09 - bolt09 feature flag utilities
• invoices - bolt11 request utilities
• lightning - methods with typescript typing support
• ln-accounting - accounting records
• ln-docker-daemons - run regtest integration tests
• ln-pathfinding - pathfinding utilities
• ln-sync - metadata helper methods
• probing - payment probing utilities
• psbt - BIP 174 PSBT utilities

addAdvertisedFeature

Add an advertised feature to the graph node announcement

Note: this method is not supported in LND versions 0.14.5 and below

Requires LND built with peersrpc build tag

Requires peers:write permissions

{
  feature: 
  lnd: 
}

@returns via cbk or Promise

Example:

const {addAdvertisedFeature} = require('ln-service');

// Add a new supported feature to the graph node announcement
await addAdvertisedFeature({lnd, feature: 12345});

addExternalSocket

Add a new advertised p2p socket address

Note: this method is not supported in LND versions 0.14.5 and below

Requires LND built with peersrpc build tag

Requires peers:write permissions

{
  lnd: 
  socket: 
}

@returns via cbk or Promise

Example:

const {addExternalSocket} = require('ln-service');

// Add a new address to advertise on the graph via gossip
await addExternalSocket({lnd, socket: '192.168.0.1:9735'});

addPeer

Add a peer if possible (not self, or already connected)

Requires peers:write permission

timeout is not supported in LND 0.11.1 and below

{
  [is_temporary]:  // Default: false
  lnd: 
  public_key: 
  [retry_count]: 
  [retry_delay]: 
  socket:  // ip:port
  [timeout]: 
}

@returns via cbk or Promise

Example:

const {addPeer} = require('ln-service');
const socket = hostIp + ':' + portNumber;
await addPeer({lnd, socket, public_key: publicKeyHexString});

authenticatedLndGrpc

Initiate a gRPC API Methods Object for authenticated methods

Both the cert and macaroon expect the entire serialized LND generated file

{
  [cert]: 
  [macaroon]: 
  [socket]: 
}

@throws


@returns
{
  lnd: {
    autopilot: 
    chain: 
    default: 
    invoices: 
    router: 
    signer: 
    tower_client: 
    tower_server: 
    wallet: 
    version: 
  }
}

Example:

const lnService = require('ln-service');
const {lnd} = lnService.authenticatedLndGrpc({
  cert: 'base64 encoded tls.cert',
  macaroon: 'base64 encoded admin.macaroon',
  socket: '127.0.0.1:10009',
});
const wallet = await lnService.getWalletInfo({lnd});

beginGroupSigningSession

Start a MuSig2 group signing session

Requires LND built with signrpc, walletrpc build tags

Requires address:read, signer:generate permissions

This method is not supported in LND 0.14.5 and below

{
  lnd: 
  [is_key_spend]: 
  key_family: 
  key_index: 
  public_keys: []
  [root_hash]: 
}

@returns via cbk or Promise
{
  external_key: 
  id: 
  [internal_key]: 
  nonce: 
}

Example:

const {beginGroupSigningSession} = require('ln-service');

const session = await beginGroupSigningSession({
  lnd,
  key_family: 0,
  key_index: 0,
  public_keys: [externalPublicKey],
});

broadcastChainTransaction

Publish a raw blockchain transaction to Blockchain network peers

Requires LND built with walletrpc tag

{
  [description]: 
  lnd: 
  transaction: 
}

@returns via cbk or Promise
{
  id: 
}

Example:

const {broadcastChainTransaction} = require('ln-service');
const transaction = hexEncodedTransactionString;

// Broadcast transaction to the p2p network
const {id} = await broadcastChainTransaction({lnd, transaction});

cancelHodlInvoice

Cancel an invoice

This call can cancel both HODL invoices and also void regular invoices

Requires LND built with invoicesrpc

Requires invoices:write permission

{
  id: 
  lnd: 
}

Example:

const {cancelHodlInvoice} = require('ln-service');
const id = paymentRequestPreimageHashHexString;
await cancelHodlInvoice({id, lnd});

cancelPendingChannel

Cancel an external funding pending channel

{
  id: 
  lnd: 
}

@returns via cbk or Promise

Example:

const {cancelPendingChannel, openChannels} = require('ln-service');

const channelsToOpen = [{capacity: 1e6, partner_public_key: publicKey}];

const {pending} = await openChannels({lnd, channels: channelsToOpen});

const [id] = pending;

// Cancel the pending channel open request
await cancelPendingChannel({id, lnd});

changePassword

Change wallet password

Requires locked LND and unauthenticated LND connection

{
  current_password: 
  lnd: 
  new_password: 
}

@returns via cbk or Promise

Example:

const {changePassword} = require('ln-service');
await changePassword({lnd, current_password: pass, new_password: newPass});

closeChannel

Close a channel.

Either an id or a transaction id / transaction output index is required

If cooperatively closing, pass a public key and socket to connect

max_tokens_per_vbyte will be ignored when closing a peer initiated channel

Requires info:read, offchain:write, onchain:write, peers:write permissions

max_tokens_per_vbyte is not supported in LND 0.15.0 and below

{
  [address]: 
  [id]: 
  [is_force_close]: 
  lnd: 
  [max_tokens_per_vbyte]: 
  [public_key]: 
  [socket]: 
  [target_confirmations]: 
  [tokens_per_vbyte]: 
  [transaction_id]: 
  [transaction_vout]: 
}

@returns via cbk or Promise
{
  transaction_id: 
  transaction_vout: 
}

Example:

const {closeChannel} = require('ln-service');
const closing = await closeChannel({id, lnd});

connectWatchtower

Connect to a watchtower

This method requires LND built with wtclientrpc build tag

Requires offchain:write permission

{
  lnd: 
  public_key: 
  socket: 
}

Example:

const {connectWatchtower, getTowerServerInfo} = require('ln-service');

const {tower} = await getTowerServerInfo({lnd: towerServerLnd});

const [socket] = tower.sockets;

await connectWatchtower({lnd, socket, public_key: tower.public_key});

createChainAddress

Create a new receive address.

Requires address:write permission

LND 0.14.5 and below do not support p2tr addresses

{
  [format]:  // "np2wpkh" || "p2tr" || "p2wpkh"
  [is_unused]: 
  lnd: 
}

@returns via cbk or Promise
{
  address: 
}

Example:

const {createChainAddress} = require('ln-service');
const format = 'p2wpkh';
const {address} = await createChainAddress({format, lnd});

createHodlInvoice

Create HODL invoice. This invoice will not settle automatically when an HTLC arrives. It must be settled separately with the secret preimage.

Warning: make sure to cancel the created invoice before its CLTV timeout.

Requires LND built with invoicesrpc tag

Requires address:write, invoices:write permission

{
  [cltv_delta]: 
  [description]: 
  [description_hash]: 
  [expires_at]: 
  [id]: 
  [is_fallback_included]: 
  [is_fallback_nested]: 
  [is_including_private_channels]: 
  lnd: 
  [mtokens]: 
  [routes]: [[{
    [base_fee_mtokens]: 
    [channel]: 
    [cltv_delta]: 
    [fee_rate]: 
    public_key: 
  }]]
  [tokens]: 
}

@returns via cbk or Promise
{
  [chain_address]: 
  created_at: 
  description: 
  id: 
  mtokens: 
  request: 
  [secret]: 
  tokens: 
}

Example:

const {createHash, randomBytes} = require('crypto');
const {createHodlInvoice, settleHodlInvoice} = require('ln-service');
const {subscribeToInvoice} = require('ln-service');

const randomSecret = () => randomBytes(32);
const sha256 = buffer => createHash('sha256').update(buffer).digest('hex');

// Choose an r_hash for this invoice, a single sha256, on say randomBytes(32)
const secret = randomSecret();

const id = sha256(secret);

// Supply an authenticatedLndGrpc object for an lnd built with invoicesrpc tag
const {request} = await createHodlInvoice({id, lnd});

// Share the request with the payer and wait for a payment
const sub = subscribeToInvoice({id, lnd});

sub.on('invoice_updated', async invoice => {
  // Only actively held invoices can be settled
  if (!invoice.is_held) {
    return;
  }

  // Use the secret to claim the funds
  await settleHodlInvoice({lnd, secret: secret.toString('hex')});
});

createInvoice

Create a Lightning invoice.

Requires address:write, invoices:write permission

payment is not supported on LND 0.11.1 and below

{
  [cltv_delta]: 
  [description]: 
  [description_hash]: 
  [expires_at]: 
  [is_fallback_included]: 
  [is_fallback_nested]: 
  [is_including_private_channels]: 
  lnd: 
  [secret]: 
  [mtokens]: 
  [routes]: [[{
    [base_fee_mtokens]: 
    [channel]: 
    [cltv_delta]: 
    [fee_rate]: 
    public_key: 
  }]]
  [tokens]: 
}

@returns via cbk or Promise
{
  [chain_address]: 
  created_at: 
  [description]: 
  id: 
  [mtokens]: 
  [payment]: 
  request: 
  secret: 
  [tokens]: 
}

Example:

const {createInvoice} = require('ln-service');

// Create a zero value invoice
const invoice = await createInvoice({lnd});

createSeed

Create a wallet seed

Requires unlocked lnd and unauthenticated LND API Object

{
  lnd: 
  [passphrase]: 
}

@returns via cbk or Promise
{
  seed: 
}

Example:

const {createSeed, createWallet} = require('ln-service');
const {seed} = await createSeed({lnd});

// Use the seed to create a wallet
await createWallet({lnd, seed, password: '123456'});

createSignedRequest

Assemble a signed payment request

{
  destination: 
  hrp: 
  signature: 
  tags: []
}

@throws


@returns
{
  request: 
}

Example:

const {createSignedRequest} = require('ln-service');

// Get hrp and signature from createUnsignedRequest
// Get signature via standard private key signing, or LND signBytes
const {request} = createSignedRequest({
  destination: nodePublicKey,
  hrp: amountAndNetworkHrp,
  signature: signedPreimageHash,
  tags: paymentRequestTags,
});

createUnsignedRequest

Create an unsigned payment request

{
  [chain_addresses]: []
  [cltv_delta]: 
  [created_at]: 
  [description]: 
  [description_hash]: 
  destination: 
  [expires_at]: 
  features: [{
    bit: 
  }]
  id: 
  [mtokens]:  (can exceed Number limit)
  network: 
  [payment]: 
  [routes]: [[{
    [base_fee_mtokens]: 
    [channel]: 
    [cltv_delta]: 
    [fee_rate]: 
    public_key: 
  }]]
  [tokens]:  (note: can differ from mtokens)
}

@returns
{
  hash: 
  hrp: 
  preimage: 
  tags: [<data>]
}

Example:

const {createUnsignedRequest} = require('ln-service');

const unsignedComponents = createUnsignedRequest({
  destination: nodePublicKey,
  id: rHashHexString,
  network: 'bitcoin',
});
// Use createSignedRequest and a signature to create a complete request

createWallet

Create a wallet

Requires unlocked lnd and unauthenticated LND API Object

{
  lnd: 
  [passphrase]: 
  password: 
  seed: 
}

@returns via cbk or Promise
{
  macaroon: 
}

Example:

const {createWallet} = require('ln-service');
const {seed} = await createSeed({lnd});
await createWallet({lnd, seed, password: 'password'});

decodePaymentRequest

Get decoded payment request

Requires offchain:read permission

{
  lnd: 
  request: 
}

@returns via cbk or Promise
{
  chain_address: 
  [cltv_delta]: 
  created_at: 
  description: 
  description_hash: 
  destination: 
  expires_at: 
  features: [{
    bit: 
    is_known: 
    is_required: 
    type: 
  }]
  id: 
  is_expired: 
  mtokens: 
  [payment]: 
  routes: [[{
    [base_fee_mtokens]: 
    [channel]: 
    [cltv_delta]: 
    [fee_rate]: 
    public_key: 
  }]]
  safe_tokens: 
  tokens: 
}

Example:

const {decodePaymentRequest} = require('ln-service');
const request = 'bolt11EncodedPaymentRequestString';
const details = await decodePaymentRequest({lnd, request});

deleteChainTransaction

Remove a chain transaction.

Requires onchain:write permission

This method is not supported on LND 0.17.4 and below

{
  id: 
  lnd: 
}

@returns via cbk or Promise

Example:

const {deleteChainTransaction} = require('ln-service');

// Eliminate past broadcast chain transaction
await deleteChainTransaction({id, lnd});

deleteFailedPayAttempts

Delete failed payment attempt records

Requires offchain:write permission

Method not supported on LND 0.12.1 or below

id is not supported on LND 0.13.4 or below

{
  [id]: 
  lnd: 
}

@returns via cbk or Promise

Example:

const {deleteFailedPayAttempts} = require('ln-service');

// Eliminate all the records of past failed payment attempts
await deleteFailedPayAttempts({lnd});

deleteFailedPayments

Delete failed payment records

Requires offchain:write permission

Method not supported on LND 0.12.1 or below

{
  lnd: 
}

@returns via cbk or Promise

Example:

const {deleteFailedPayments} = require('ln-service');

// Eliminate all the records of past failed payments
await deleteFailedPayments({lnd});

deleteForwardingReputations

Delete all forwarding reputations

Requires offchain:write permission

{
  lnd: 
}

@returns via cbk or Promise

Example:

const {deleteForwardingReputations} = require('ln-service');

// Delete all routing reputations to clear pathfinding memory
await deleteForwardingReputations({});

deletePayment

Delete a payment record

Requires offchain:write permission

Note: this method is not supported on LND 0.13.4 and below

{
  id: 
  lnd: 
}

@returns via cbk or Promise

Example:

const {deletePayment} = require('ln-service');

// Eliminate the records of a payment
await deletePayment({id, lnd});

deletePayments

Delete all records of payments

Requires offchain:write permission

{
  lnd: 
}

@returns via cbk or Promise

Example:

const {deletePayments} = require('ln-service');

// Eliminate all the records of past payments
await deletePayments({lnd});

deletePendingChannel

Delete a pending channel

Pass the confirmed conflicting transaction that spends the same input to make sure that no funds are being deleted.

This method is not supported on LND 0.13.3 and below

{
  confirmed_transaction: 
  lnd: 
  pending_transaction: 
  pending_transaction_vout: 
}

@returns via cbk or Promise

const {deletePendingChannel} = require('ln-service');

// Delete a stuck pending channel
await deletePendingChannel({
  lnd,
  confirmed_transaction: confirmedTransactionHex,
  pending_transaction: stuckPendingChannelOpenTxHex,
  pending_transaction_vout: pendingChannelOutputIndexNumber,
});

diffieHellmanComputeSecret

Derive a shared secret

Key family and key index default to 6 and 0, which is the node identity key

Requires LND built with signerrpc build tag

Requires signer:generate permission

{
  [key_family]: 
  [key_index]: 
  lnd: 
  partner_public_key: 
}

@returns via cbk or Promise
{
  secret: 
}

disableChannel

Mark a channel as temporarily disabled for outbound payments and forwards

Note: this method is not supported in LND versions 0.12.1 and below

Requires offchain:write permission

{
  lnd: 
  transaction_id: 
  transaction_vout: 
}

@returns via cbk or Promise

Example:

const {disableChannel} = await require('ln-service');

const [channel] = (await getChannels({lnd})).channels;

// Disable outgoing traffic via the channel
await disableChannel({
  lnd,
  transaction_id: channel.transaction_id,
  transaction_vout: channel.transaction_vout,
});

disconnectWatchtower

Disconnect a watchtower

Requires LND built with wtclientrpc build tag

Requires offchain:write permission

{
  lnd: 
  public_key: 
}

@returns via cbk or Promise

const {disconnectWatchtower, getConnectedWatchtowers} = require('ln-service');

const [tower] = (await getConnectedWatchtowers({lnd})).towers;

await disconnectWatchtower({lnd, public_key: tower.public_key});

enableChannel

Mark a channel as enabled for outbound payments and forwards

Setting is_force_enable will prevent future automated disabling/enabling

Note: this method is not supported in LND versions 0.12.1 and below

Requires offchain:write permission

{
  [is_force_enable]: 
  lnd: 
  transaction_id: 
  transaction_vout: 
}

@returns via cbk or Promise

Example:

const {enableChannel} = await require('ln-service');

const [channel] = (await getChannels({lnd})).channels;

// Enable outgoing traffic via the channel
await enableChannel({
  lnd,
  transaction_id: channel.transaction_id,
  transaction_vout: channel.transaction_vout,
});

endGroupSigningSession

Complete a MuSig2 signing session

Requires LND built with signrpc build tag

Requires signer:generate permission

This method is not supported in LND 0.14.5 and below

{
  id: 
  lnd: 
  [signatures]: []
}

@returns via cbk or Promise
{
  [signature]: 
}

Example:

const {endGroupSigningSession} = require('ln-service');

// Cancel a group signing session
await endGroupSigningSession({id, lnd});

fundPendingChannels

Fund pending channels

Requires offchain:write, onchain:write permissions

{
  channels: []
  funding: 
  lnd: 
}

@returns via cbk or Promise

const {fundPendingChannels, openChannels} = require('ln-service');

const channelsToOpen = [{capacity: 1e6, partner_public_key: publicKey}];

const {pending} = await openChannels({lnd, channel: channelsToOpen});

const channels = pending.map(n => n.id);

// Fund the pending open channels request
await fundPendingChannels({channels, lnd, funding: psbt});

fundPsbt

Lock and optionally select inputs to a partially signed transaction

Specify outputs or PSBT with the outputs encoded

If there are no inputs passed, internal UTXOs will be selected and locked

utxo_selection methods: 'largest', 'random'

Requires onchain:write permission

Requires LND built with walletrpc tag

This method is not supported in LND 0.11.1 and below

Specifying 0 for min_confirmations is not supported in LND 0.13.0 and below

utxo_selection is not supported in LND 0.17.4 and below

{
  [fee_tokens_per_vbyte]: 
  [inputs]: [{
    transaction_id: 
    transaction_vout: 
  }]
  lnd: 
  [min_confirmations]: 
  [outputs]: [{
    address: 
    tokens: 
  }]
  [target_confirmations]: 
  [psbt]: 
  [utxo_selection]: <select method="">
}

@returns via cbk or Promise
{
  inputs: [{
    [lock_expires_at]: 
    [lock_id]: 
    transaction_id: 
    transaction_vout: 
  }]
  outputs: [{
    is_change: 
    output_script: 
    tokens: 
  }]
  psbt: 
}

Example:

const {fundPsbt} = require('ln-service');

const address = 'chainAddress';
const tokens = 1000000;

// Create an unsigned PSBT that sends 1mm to a chain address
const {psbt} = await fundPsbt({lnd, outputs: [{address, tokens}]});

// This PSBT can be used with signPsbt to sign and finalize for broadcast

getAccessIds

Get outstanding access ids given out

Note: this method is not supported in LND versions 0.11.1 and below

Requires macaroon:read permission

{
  lnd: 
}

@returns via cbk or Promise
{
  ids: []
}

Example:

const {getAccessIds, grantAccess} = require('ln-service');

// Create a macaroon that can be used to make off-chain payments
const {macaroon} = await grantAccess({lnd, id: '1', is_ok_to_pay: true});

// Get outstanding ids
const {ids} = await getAccessIds({lnd});

// The specified id '1' will appear in the ids array

getAutopilot

Get Autopilot status

Optionally, get the score of nodes as considered by the autopilot. Local scores reflect an internal scoring that includes local channel info

Permission info:read is required

{
  lnd: 
  [node_scores]: []
}

@returns via cbk or Promise
{
  is_enabled: 
  nodes: [{
    local_preferential_score: 
    local_score: 
    preferential_score: 
    public_key: 
    score: 
    weighted_local_score: 
    weighted_score: 
  }]
}

Example:

const {getAutopilot} = require('ln-service');
const isAutopilotEnabled = (await getAutopilot({lnd})).is_enabled;

getBackup

Get the static channel backup for a channel

Requires offchain:read permission

{
  lnd: 
  transaction_id: 
  transaction_vout: 
}

@returns via cbk or Promise
{
  backup: 
}

Example:

const {getBackup, getChannels} = require('ln-service');
const [channel] = (await getChannels({lnd})).channels;
const {backup} = await getBackup({
  lnd,
  transaction_id: channel.transaction_id,
  transaction_vout: channel.transaction_vout,
});

getBackups

Get all channel backups

Requires offchain:read permission

{
  lnd: 
}

@returns via cbk or Promise
{
  backup: 
  channels: [{
    backup: 
    transaction_id: 
    transaction_vout: 
  }]
}

Example:

const {getBackups} = require('ln-service');
const {backup} = await getBackups({lnd});

getBlock

Get a block in the chain

This method requires LND built with chainrpc build tag

Requires onchain:read permission

This method is not supported on LND 0.15.5 and below

{
  [height]: 
  [id]: 
  lnd: 
}

@returns via cbk or Promise
{
  block: 
}

Example:

const {getBlock, getHeight} = require('ln-service');

const chain = await getHeight({lnd});

const {block} = await getBlock({lnd, id: chain.current_block_hash});

const lastBlockSize = Buffer.from(block, 'hex').byteLength();

getBlockHeader

Get a block header in the best chain

This method requires LND built with chainrpc build tag

Requires onchain:read permission

This method is not supported on LND 0.17.0 and below

{
  [height]: 
  [id]: 
  lnd: 
}

@returns via cbk or Promise
{
  header: 
}

Example:

const {getBlockHeader, getHeight} = require('ln-service');

const chain = await getHeight({lnd});

const {header} = await getBlockHeader({lnd, id: chain.current_block_hash});

const lastBlockHeader = Buffer.from(header, 'hex');

getChainAddresses

Get the wallet chain addresses

Requires onchain:read permission

This method is not supported on LND 0.15.5 and below

{
  lnd: 
}

@returns via cbk or Promise
{
  addresses: [{
    address: 
    is_change: 
    tokens: 
  }]
}

const {getChainAddresses} = require('ln-service');

// How many chain addresses have been created
const numberOfChainAddresses = (await getChainAddresses({lnd})).addresses;

getChainBalance

Get balance on the chain.

Requires onchain:read permission

{
  lnd: 
}

@returns via cbk or Promise
{
  chain_balance: 
}

Example:

const {getChainBalance} = require('ln-service');
const chainBalance = (await getChainBalance({lnd})).chain_balance;

getChainFeeEstimate

Get a chain fee estimate for a prospective chain send

utxo_selection methods: 'largest', 'random'

Requires onchain:read permission

Specifying 0 for utxo_confirmations is not supported in LND 0.13.0 or below

utxo_selection is not supported in LND 0.17.4 and below

{
  lnd: 
  send_to: [{
    address: 
    tokens: 
  }]
  [target_confirmations]: 
  [utxo_confirmations]: 
  [utxo_selection]: </select>
}

@returns via cbk or Promise
{
  fee: 
  tokens_per_vbyte: 
}

Example:

const {getChainFeeEstimate} = require('ln-service');
const sendTo = [{address: 'chainAddressString', tokens: 100000000}];
const {fee} = await getChainFeeEstimate({lnd, send_to: sendTo});

getChainFeeRate

Get chain fee rate estimate

Requires LND built with walletrpc tag

Requires onchain:read permission

{
  [confirmation_target]: 
  lnd: 
}

@returns via cbk or Promise
{
  tokens_per_vbyte: 
}

Example:

const {getChainFeeRate} = require('ln-service');
const fee = (await getChainFeeRate({lnd, confirmation_target: 6})).tokens_per_vbyte;

getChainTransaction

Get a chain transaction.

Requires onchain:read permission

This method is not supported on LND 0.17.4 and below

{
  id: 
  lnd: 
}

@returns via cbk or Promise
{
  [block_id]: 
  [confirmation_count]: 
  [confirmation_height]: 
  created_at: 
  [description]: 
  [fee]: 
  id: 
  inputs: [{
    is_local: 
    transaction_id: 
    transaction_vout: 
  }]
  is_confirmed: 
  is_outgoing: 
  output_addresses: [<address>]
  tokens: 
  [transaction]: 
}

Example:

const {getChainTransaction} = require('ln-service');
const txIsConfirmed = (await getChainTransaction({id, lnd})).is_confirmed;

getChainTransactions

Get chain transactions.

Requires onchain:read permission

inputs are not supported on LND 0.15.0 and below

{
  [after]: 
  [before]: 
  lnd: 
}

@returns via cbk or Promise
{
  transactions: [{
    [block_id]: 
    [confirmation_count]: 
    [confirmation_height]: 
    created_at: 
    [description]: 
    [fee]: 
    id: 
    inputs: [{
      is_local: 
      transaction_id: 
      transaction_vout: 
    }]
    is_confirmed: 
    is_outgoing: 
    output_addresses: [<address>]
    tokens: 
    [transaction]: 
  }]
}

Example:

const {getChainTransactions} = require('ln-service');
const {transactions} = await getChainTransactions({lnd});

getChannelBalance

Get balance across channels.

Requires offchain:read permission

channel_balance_mtokens is not supported on LND 0.11.1 and below

inbound and inbound_mtokens are not supported on LND 0.11.1 and below

pending_inbound is not supported on LND 0.11.1 and below

unsettled_balance is not supported on LND 0.11.1 and below

unsettled_balance_mtokens is not supported on LND 0.11.1 and below

{
  lnd: 
}

@returns via cbk or Promise
{
  channel_balance: 
  [channel_balance_mtokens]: 
  [inbound]: 
  [inbound_mtokens]: 
  pending_balance: 
  [pending_inbound]: 
  [unsettled_balance]: 
  [unsettled_balance_mtokens]: 
}

Example:

const {getChannelBalance} = require('ln-service');
const balanceInChannels = (await getChannelBalance({lnd})).channel_balance;

getChannel

Get graph information about a channel on the network

Requires info:read permission

{
  id: 
  lnd: 
}

@returns via cbk or Promise
{
  capacity: 
  id: 
  policies: [{
    [base_fee_mtokens]: 
    [cltv_delta]: 
    [fee_rate]: 
    [is_disabled]: 
    [max_htlc_mtokens]: 
    [min_htlc_mtokens]: 
    public_key: 
    [updated_at]: 
  }]
  transaction_id: 
  transaction_vout: 
  [updated_at]: 
}

Example:

const {getChannel} = await require('ln-service');
const id = '0x0x0';
const channelDetails = await getChannel({id, lnd});

getChannels

Get channels

Requires offchain:read permission

in_channel, in_payment, is_forward, out_channel, out_payment, payment are not supported on LND 0.11.1 and below

is_trusted_funding is not supported on LND 0.15.0 and below

description is not supported on LND 0.16.4 and below

{
  [is_active]:  // false
  [is_offline]:  // false
  [is_private]:  // false
  [is_public]:  // false
  lnd: 
  [partner_public_key]: 
}

@returns via cbk or Promise
{
  channels: [{
    capacity: 
    commit_transaction_fee: 
    commit_transaction_weight: 
    [cooperative_close_address]: 
    [cooperative_close_delay_height]: 
    [description]: 
    id: 
    is_active: 
    is_closing: 
    is_opening: 
    is_partner_initiated: 
    is_private: 
    [is_trusted_funding]: 
    local_balance: 
    [local_csv]: 
    [local_dust]: 
    [local_given]: 
    [local_max_htlcs]: 
    [local_max_pending_mtokens]: 
    [local_min_htlc_mtokens]: 
    local_reserve: 
    other_ids: []
    partner_public_key: 
    past_states: 
    pending_payments: [{
      id: 
      [in_channel]: 
      [in_payment]: 
      [is_forward]: 
      is_outgoing: 
      [out_channel]: 
      [out_payment]: 
      [payment]: 
      timeout: 
      tokens: 
    }]
    received: 
    remote_balance: 
    [remote_csv]: 
    [remote_dust]: 
    [remote_given]: 
    [remote_max_htlcs]: 
    [remote_max_pending_mtokens]: 
    [remote_min_htlc_mtokens]: 
    remote_reserve: 
    sent: 
    [time_offline]: 
    [time_online]: 
    transaction_id: 
    transaction_vout: 
    [type]: 
    unsettled_balance: 
  }]
}

Example:

const {getChannels} = require('ln-service');

// Get the channels and count how many there are
const channelsCount = (await getChannels({lnd})).length;

getClosedChannels

Get closed out channels

Multiple close type flags are supported.

Requires offchain:read permission

`other_ids is not supported on LND 0.15.0 and below

{
  [is_breach_close]: 
  [is_cooperative_close]: 
  [is_funding_cancel]: 
  [is_local_force_close]: 
  [is_remote_force_close]: 
  lnd: 
}

@returns via cbk or Promise
{
  channels: [{
    capacity: 
    [close_balance_spent_by]: 
    [close_balance_vout]: 
    close_payments: [{
      is_outgoing: 
      is_paid: 
      is_pending: 
      is_refunded: 
      [spent_by]: 
      tokens: 
      transaction_id: 
      transaction_vout: 
    }]
    [close_confirm_height]: 
    [close_transaction_id]: 
    final_local_balance: 
    final_time_locked_balance: 
    [id]: 
    is_breach_close: 
    is_cooperative_close: 
    is_funding_cancel: 
    is_local_force_close: 
    [is_partner_closed]: 
    [is_partner_initiated]: 
    is_remote_force_close: 
    other_ids: []
    partner_public_key: 
    transaction_id: 
    transaction_vout: 
  }]
}

Example:

const {getClosedChannels} = require('ln-service');
const breachCount = await getClosedChannels({lnd, is_breach_close: true});

getConfiguration

Get the current configuration file settings and the output log

Requires info:read, offchain:read, onchain:read, peers:read permissions

This method is not supported on LND 0.17.4 and below

{
  lnd: 
}

@returns via cbk or Promise
{
  log: []
  options: [{
    type: <option type="">
    value: </option><option value="">
  }]
}

Example:

const {getConfiguration} = require('ln-service');
const {log, options} = await getConfiguration({});
const minimumChannelSize = options.find(n => n.type === 'minchansize').value;

getConnectedWatchtowers

Get a list of connected watchtowers and watchtower info

Requires LND built with wtclientrpc build tag

Requires offchain:read permission

Includes previously connected watchtowers

is_anchor flag is not supported on LND 0.11.1 and below

is_taproot flag is not supported on LND 0.17.4 and below

{
  [is_anchor]: 
  [is_taproot]: 
  lnd: 
}

@returns via cbk or Promise
{
  max_session_update_count: 
  sweep_tokens_per_vbyte: 
  backups_count: 
  failed_backups_count: 
  finished_sessions_count: 
  pending_backups_count: 
  sessions_count: 
  towers: [{
    is_active: 
    public_key: 
    sessions: [{
      backups_count: 
      max_backups_count: 
      pending_backups_count: 
      sweep_tokens_per_vbyte: 
    }]
    sockets: []
  }]
}

Example:

const {getConnectedWatchtowers} = require('ln-service');

const {towers} = (await getConnectedWatchtowers({lnd}));

getEphemeralChannelIds

Get ephemeral channel ids

Requires offchain:read permission

This method is not supported on LND 0.15.0 and below

{
  lnd: 
}

@returns via cbk or Promise
{
  channels: [{
    other_ids: []
    reference_id: 
  }]
}

Example:

const {getEphemeralChannelIds} = require('ln-service');

// Get the list of ephemeral ids related to channels
const {channels} = await getEphemeralChannelIds({lnd});

getFailedPayments

Get failed payments made through channels.

Requires offchain:read permission

created_after is not supported on LND 0.15.5 and below created_before is not supported on LND 0.15.5 and below

{
  [created_after]: 
  [created_before]:</option></address></address></data>