ln-service

v57.9.1

Published

a day ago

Interaction helper for your Lightning Network daemon

Downloads

13,834

0High
0Medium
0Low

alexbosworth

bitcoin grpc lightning lightning-network lnd

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.5-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: <BOLT 09 Feature Bit Number>
  lnd: <Authenticated LND API Object>
}

@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: <Authenticated LND API Object>
  socket: <Add Socket Address String>
}

@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]: <Add Peer as Temporary Peer Bool> // Default: false
  lnd: <Authenticated LND API Object>
  public_key: <Public Key Hex String>
  [retry_count]: <Retry Count Number>
  [retry_delay]: <Delay Retry By Milliseconds Number>
  socket: <Host Network Address And Optional Port String> // ip:port
  [timeout]: <Connection Attempt Timeout Milliseconds Number>
}

@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]: <Base64 or Hex Serialized LND TLS Cert>
  [macaroon]: <Base64 or Hex Serialized Macaroon String>
  [socket]: <Host:Port String>
}

@throws
<Error>

@returns
{
  lnd: {
    autopilot: <Autopilot API Methods Object>
    chain: <ChainNotifier API Methods Object>
    default: <Default API Methods Object>
    invoices: <Invoices API Methods Object>
    router: <Router API Methods Object>
    signer: <Signer Methods API Object>
    tower_client: <Watchtower Client Methods Object>
    tower_server: <Watchtower Server Methods API Object>
    wallet: <WalletKit gRPC Methods API Object>
    version: <Version Methods API Object>
  }
}

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: <Authenticated LND API Object>
  [is_key_spend]: <Key Is BIP 86 Key Spend Key Bool>
  key_family: <HD Seed Key Family Number>
  key_index: <Key Index Number>
  public_keys: [<External Public Key Hex String>]
  [root_hash]: <Taproot Script Root Hash Hex String>
}

@returns via cbk or Promise
{
  external_key: <Final Script or Top Level Public Key Hex String>
  id: <Session Id Hex String>
  [internal_key]: <Internal Top Level Public Key Hex String>
  nonce: <Session Compound Nonces Hex String>
}

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]: <Transaction Label String>
  lnd: <Authenticated LND API Object>
  transaction: <Transaction Hex String>
}

@returns via cbk or Promise
{
  id: <Transaction Id Hex String>
}

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: <Payment Preimage Hash Hex String>
  lnd: <Authenticated RPC LND API Object>
}

Example:

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

cancelPendingChannel

Cancel an external funding pending channel

{
  id: <Pending Channel Id Hex String>
  lnd: <Authenticated LND API Object>
}

@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: <Current Password String>
  lnd: <Unauthenticated LND API Object>
  new_password: <New Password String>
}

@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]: <Request Sending Local Channel Funds To Address String>
  [id]: <Standard Format Channel Id String>
  [is_force_close]: <Is Force Close Bool>
  lnd: <Authenticated LND API Object>
  [max_tokens_per_vbyte]: <Fail Cooperative Close Above Fee Rate Number>
  [public_key]: <Peer Public Key String>
  [socket]: <Peer Socket String>
  [target_confirmations]: <Confirmation Target Number>
  [tokens_per_vbyte]: <Target Tokens Per Virtual Byte Number>
  [transaction_id]: <Transaction Id Hex String>
  [transaction_vout]: <Transaction Output Index Number>
}

@returns via cbk or Promise
{
  transaction_id: <Closing Transaction Id Hex String>
  transaction_vout: <Closing Transaction Vout Number>
}

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: <Authenticated LND API Object>
  public_key: <Watchtower Public Key Hex String>
  socket: <Network Socket Address IP:PORT String>
}

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]: <Receive Address Type String> // "np2wpkh" || "p2tr" || "p2wpkh"
  [is_unused]: <Get As-Yet Unused Address Bool>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  address: <Chain Address String>
}

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]: <Final CLTV Delta Number>
  [description]: <Invoice Description String>
  [description_hash]: <Hashed Description of Payment Hex String>
  [expires_at]: <Expires At ISO 8601 Date String>
  [id]: <Payment Hash Hex String>
  [is_fallback_included]: <Is Fallback Address Included Bool>
  [is_fallback_nested]: <Is Fallback Address Nested Bool>
  [is_including_private_channels]: <Invoice Includes Private Channels Bool>
  lnd: <Authenticated LND API Object>
  [mtokens]: <Millitokens String>
  [routes]: [[{
    [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
    [channel]: <Standard Format Channel Id String>
    [cltv_delta]: <CLTV Blocks Delta Number>
    [fee_rate]: <Fee Rate In Millitokens Per Million Number>
    public_key: <Forward Edge Public Key Hex String>
  }]]
  [tokens]: <Tokens Number>
}

@returns via cbk or Promise
{
  [chain_address]: <Backup Address String>
  created_at: <ISO 8601 Date String>
  description: <Description String>
  id: <Payment Hash Hex String>
  mtokens: <Millitokens String>
  request: <BOLT 11 Encoded Payment Request String>
  [secret]: <Hex Encoded Payment Secret String>
  tokens: <Tokens Number>
}

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]: <CLTV Delta Number>
  [description]: <Invoice Description String>
  [description_hash]: <Hashed Description of Payment Hex String>
  [expires_at]: <Expires At ISO 8601 Date String>
  [is_fallback_included]: <Is Fallback Address Included Bool>
  [is_fallback_nested]: <Is Fallback Address Nested Bool>
  [is_including_private_channels]: <Invoice Includes Private Channels Bool>
  lnd: <Authenticated LND API Object>
  [secret]: <Payment Preimage Hex String>
  [mtokens]: <Millitokens String>
  [routes]: [[{
    [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
    [channel]: <Standard Format Channel Id String>
    [cltv_delta]: <CLTV Blocks Delta Number>
    [fee_rate]: <Fee Rate In Millitokens Per Million Number>
    public_key: <Forward Edge Public Key Hex String>
  }]]
  [tokens]: <Tokens Number>
}

@returns via cbk or Promise
{
  [chain_address]: <Backup Address String>
  created_at: <ISO 8601 Date String>
  [description]: <Description String>
  id: <Payment Hash Hex String>
  [mtokens]: <Millitokens String>
  [payment]: <Payment Identifying Secret Hex String>
  request: <BOLT 11 Encoded Payment Request String>
  secret: <Hex Encoded Payment Secret String>
  [tokens]: <Tokens Number>
}

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: <Unauthenticated LND API Object>
  [passphrase]: <Seed Passphrase String>
}

@returns via cbk or Promise
{
  seed: <Cipher Seed Mnemonic String>
}

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: <Destination Public Key Hex String>
  hrp: <Request Human Readable Part String>
  signature: <Request Hash Signature Hex String>
  tags: [<Request Tag Word Number>]
}

@throws
<Error>

@returns
{
  request: <BOLT 11 Encoded Payment Request String>
}

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]: [<Chain Address String>]
  [cltv_delta]: <CLTV Delta Number>
  [created_at]: <Invoice Creation Date ISO 8601 String>
  [description]: <Description String>
  [description_hash]: <Description Hash Hex String>
  destination: <Public Key String>
  [expires_at]: <ISO 8601 Date String>
  features: [{
    bit: <BOLT 09 Feature Bit Number>
  }]
  id: <Preimage SHA256 Hash Hex String>
  [mtokens]: <Requested Milli-Tokens Value String> (can exceed Number limit)
  network: <Network Name String>
  [payment]: <Payment Identifier Hex String>
  [routes]: [[{
    [base_fee_mtokens]: <Base Fee Millitokens String>
    [channel]: <Standard Format Channel Id String>
    [cltv_delta]: <Final CLTV Expiration Blocks Delta Number>
    [fee_rate]: <Fees Charged in Millitokens Per Million Number>
    public_key: <Forward Edge Public Key Hex String>
  }]]
  [tokens]: <Requested Chain Tokens Number> (note: can differ from mtokens)
}

@returns
{
  hash: <Payment Request Signature Hash Hex String>
  hrp: <Human Readable Part of Payment Request String>
  preimage: <Signature Hash Preimage Hex String>
  tags: [<Data Tag Number>]
}

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: <Unauthenticated LND API Object>
  [passphrase]: <AEZSeed Encryption Passphrase String>
  password: <Wallet Password String>
  seed: <Seed Mnemonic String>
}

@returns via cbk or Promise
{
  macaroon: <Base64 Encoded Admin Macaroon String>
}

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: <Authenticated LND API Object>
  request: <BOLT 11 Payment Request String>
}

@returns via cbk or Promise
{
  chain_address: <Fallback Chain Address String>
  [cltv_delta]: <Final CLTV Delta Number>
  created_at: <Payment Request Created At ISO 8601 Date String>
  description: <Payment Description String>
  description_hash: <Payment Longer Description Hash Hex String>
  destination: <Public Key Hex String>
  expires_at: <ISO 8601 Date String>
  features: [{
    bit: <BOLT 09 Feature Bit Number>
    is_known: <Feature is Known Bool>
    is_required: <Feature Support is Required To Pay Bool>
    type: <Feature Type String>
  }]
  id: <Payment Hash Hex String>
  is_expired: <Invoice is Expired Bool>
  mtokens: <Requested Millitokens String>
  [payment]: <Payment Identifier Hex Encoded String>
  routes: [[{
    [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
    [channel]: <Standard Format Channel Id String>
    [cltv_delta]: <CLTV Blocks Delta Number>
    [fee_rate]: <Fee Rate In Millitokens Per Million Number>
    public_key: <Forward Edge Public Key Hex String>
  }]]
  safe_tokens: <Requested Tokens Rounded Up Number>
  tokens: <Requested Tokens Rounded Down Number>
}

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.5 and below

{
  id: <Transaction Id Hex String>
  lnd: <Authenticated LND API Object>
}

@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]: <Delete Only Failed Attempt Records For Payment With Hash Hex String>
  lnd: <Authenticated LND API Object>
}

@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: <Authenticated LND API Object>
}

@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: <Authenticated LND API Object>
}

@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: <Payment Preimage Hash Hex String>
  lnd: <Authenticated LND API Object>
}

@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: <Authenticated LND API Object>
}

@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: <Hex Encoded Conflicting Transaction String>
  lnd: <Authenticated LND API Object>
  pending_transaction: <Hex Encoded Pending Transaction String>
  pending_transaction_vout: <Pending Channel Output Index Number>
}

@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 Family Number>
  [key_index]: <Key Index Number>
  lnd: <Authenticated LND API Object>
  partner_public_key: <Public Key Hex String>
}

@returns via cbk or Promise
{
  secret: <Shared Secret Hex String>
}

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: <Authenticated LND API Object>
  transaction_id: <Channel Funding Transaction Id Hex String>
  transaction_vout: <Channel Funding Transaction Output Index Number>
}

@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: <Authenticated LND API Object>
  public_key: <Watchtower Public Key Hex String>
}

@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]: <Force Channel Enabled Bool>
  lnd: <Authenticated LND API Object>
  transaction_id: <Channel Funding Transaction Id Hex String>
  transaction_vout: <Channel Funding Transaction Output Index Number>
}

@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: <Session Id Hex String>
  lnd: <Authenticated LND API Object>
  [signatures]: [<Combine External Partial Signature Hex String>]
}

@returns via cbk or Promise
{
  [signature]: <Combined Signature Hex String>
}

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: [<Pending Channel Id Hex String>]
  funding: <Signed Funding Transaction PSBT Hex String>
  lnd: <Authenticated LND API Object>
}

@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.5 and below

{
  [fee_tokens_per_vbyte]: <Chain Fee Tokens Per Virtual Byte Number>
  [inputs]: [{
    transaction_id: <Unspent Transaction Id Hex String>
    transaction_vout: <Unspent Transaction Output Index Number>
  }]
  lnd: <Authenticated LND API Object>
  [min_confirmations]: <Spend UTXOs With Minimum Confirmations Number>
  [outputs]: [{
    address: <Chain Address String>
    tokens: <Send Tokens Tokens Number>
  }]
  [target_confirmations]: <Confirmations To Wait Number>
  [psbt]: <Existing PSBT Hex String>
  [utxo_selection]: <Select UTXOs Using Method String>
}

@returns via cbk or Promise
{
  inputs: [{
    [lock_expires_at]: <UTXO Lock Expires At ISO 8601 Date String>
    [lock_id]: <UTXO Lock Id Hex String>
    transaction_id: <Unspent Transaction Id Hex String>
    transaction_vout: <Unspent Transaction Output Index Number>
  }]
  outputs: [{
    is_change: <Spends To a Generated Change Output Bool>
    output_script: <Output Script Hex String>
    tokens: <Send Tokens Tokens Number>
  }]
  psbt: <Unsigned PSBT Hex String>
}

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: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  ids: [<Root Access Id Number>]
}

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: <Authenticated LND Object>
  [node_scores]: [<Get Score For Public Key Hex String>]
}

@returns via cbk or Promise
{
  is_enabled: <Autopilot is Enabled Bool>
  nodes: [{
    local_preferential_score: <Local-adjusted Pref Attachment Score Number>
    local_score: <Local-adjusted Externally Set Score Number>
    preferential_score: <Preferential Attachment Score Number>
    public_key: <Node Public Key Hex String>
    score: <Externally Set Score Number>
    weighted_local_score: <Combined Weighted Locally-Adjusted Score Number>
    weighted_score: <Combined Weighted Score Number>
  }]
}

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: <Authenticated LND API Object>
  transaction_id: <Funding Transaction Id Hex String>
  transaction_vout: <Funding Transaction Output Index Number>
}

@returns via cbk or Promise
{
  backup: <Channel Backup Hex String>
}

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: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  backup: <All Channels Backup Hex String>
  channels: [{
    backup: <Individualized Channel Backup Hex String>
    transaction_id: <Channel Funding Transaction Id Hex String>
    transaction_vout: <Channel Funding Transaction Output Index Number>
  }]
}

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]: <Block Height Number>
  [id]: <Block Hash Hex String>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  block: <Raw Block Bytes Hex String>
}

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]: <Block Height Number>
  [id]: <Block Hash Hex String>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  header: <Raw Block Header Bytes Hex String>
}

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: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  addresses: [{
    address: <Chain Address String>
    is_change: <Is Internal Change Address Bool>
    tokens: <Balance of Funds Controlled by Output Script Tokens Number>
  }]
}

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: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  chain_balance: <Confirmed Chain Balance Tokens Number>
}

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.5 and below

{
  lnd: <Authenticated LND API Object>
  send_to: [{
    address: <Address String>
    tokens: <Tokens Number>
  }]
  [target_confirmations]: <Target Confirmations Number>
  [utxo_confirmations]: <Minimum Confirmations for UTXO Selection Number>
  [utxo_selection]: <Select UTXOs Using Method String>
}

@returns via cbk or Promise
{
  fee: <Total Fee Tokens Number>
  tokens_per_vbyte: <Fee Tokens Per VByte Number>
}

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]: <Future Blocks Confirmation Number>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  tokens_per_vbyte: <Tokens Per Virtual Byte Number>
}

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.5 and below

{
  id: <Transaction Id Hex String>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  [block_id]: <Block Hash String>
  [confirmation_count]: <Confirmation Count Number>
  [confirmation_height]: <Confirmation Block Height Number>
  created_at: <Created ISO 8601 Date String>
  [description]: <Transaction Label String>
  [fee]: <Fees Paid Tokens Number>
  id: <Transaction Id String>
  inputs: [{
    is_local: <Spent Outpoint is Local Bool>
    transaction_id: <Transaction Id Hex String>
    transaction_vout: <Transaction Output Index Number>
  }]
  is_confirmed: <Is Confirmed Bool>
  is_outgoing: <Transaction Outbound Bool>
  output_addresses: [<Address String>]
  tokens: <Tokens Including Fee Number>
  [transaction]: <Raw Transaction Hex String>
}

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]: <Confirmed After Current Best Chain Block Height Number>
  [before]: <Confirmed Before Current Best Chain Block Height Number>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  transactions: [{
    [block_id]: <Block Hash String>
    [confirmation_count]: <Confirmation Count Number>
    [confirmation_height]: <Confirmation Block Height Number>
    created_at: <Created ISO 8601 Date String>
    [description]: <Transaction Label String>
    [fee]: <Fees Paid Tokens Number>
    id: <Transaction Id String>
    inputs: [{
      is_local: <Spent Outpoint is Local Bool>
      transaction_id: <Transaction Id Hex String>
      transaction_vout: <Transaction Output Index Number>
    }]
    is_confirmed: <Is Confirmed Bool>
    is_outgoing: <Transaction Outbound Bool>
    output_addresses: [<Address String>]
    tokens: <Tokens Including Fee Number>
    [transaction]: <Raw Transaction Hex String>
  }]
}

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: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  channel_balance: <Channels Balance Tokens Number>
  [channel_balance_mtokens]: <Channels Balance Millitokens String>
  [inbound]: <Inbound Liquidity Tokens Number>
  [inbound_mtokens]: <Inbound Liquidity Millitokens String>
  pending_balance: <Pending On-Chain Channels Balance Tokens Number>
  [pending_inbound]: <Pending On-Chain Inbound Liquidity Tokens Number>
  [unsettled_balance]: <In-Flight Tokens Number>
  [unsettled_balance_mtokens]: <In-Flight Millitokens String>
}

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: <Standard Format Channel Id String>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  capacity: <Maximum Tokens Number>
  id: <Standard Format Channel Id String>
  policies: [{
    [base_fee_mtokens]: <Base Fee Millitokens String>
    [cltv_delta]: <Locktime Delta Number>
    [fee_rate]: <Fees Charged Per Million Millitokens Number>
    [is_disabled]: <Channel Is Disabled Bool>
    [max_htlc_mtokens]: <Maximum HTLC Millitokens Value String>
    [min_htlc_mtokens]: <Minimum HTLC Millitokens Value String>
    public_key: <Node Public Key String>
    [updated_at]: <Policy Last Updated At ISO 8601 Date String>
  }]
  transaction_id: <Transaction Id Hex String>
  transaction_vout: <Transaction Output Index Number>
  [updated_at]: <Last Update Epoch ISO 8601 Date String>
}

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]: <Limit Results To Only Active Channels Bool> // false
  [is_offline]: <Limit Results To Only Offline Channels Bool> // false
  [is_private]: <Limit Results To Only Private Channels Bool> // false
  [is_public]: <Limit Results To Only Public Channels Bool> // false
  lnd: <Authenticated LND gRPC API Object>
  [partner_public_key]: <Only Channels With Public Key Hex String>
}

@returns via cbk or Promise
{
  channels: [{
    capacity: <Channel Token Capacity Number>
    commit_transaction_fee: <Commit Transaction Fee Number>
    commit_transaction_weight: <Commit Transaction Weight Number>
    [cooperative_close_address]: <Coop Close Restricted to Address String>
    [cooperative_close_delay_height]: <Prevent Coop Close Until Height Number>
    [description]: <Channel Description String>
    id: <Standard Format Channel Id String>
    is_active: <Channel Active Bool>
    is_closing: <Channel Is Closing Bool>
    is_opening: <Channel Is Opening Bool>
    is_partner_initiated: <Channel Partner Opened Channel Bool>
    is_private: <Channel Is Private Bool>
    [is_trusted_funding]: <Funding Output is Trusted Bool>
    local_balance: <Local Balance Tokens Number>
    [local_csv]: <Local CSV Blocks Delay Number>
    [local_dust]: <Local Non-Enforceable Amount Tokens Number>
    [local_given]: <Local Initially Pushed Tokens Number>
    [local_max_htlcs]: <Local Maximum Attached HTLCs Number>
    [local_max_pending_mtokens]: <Local Maximum Pending Millitokens String>
    [local_min_htlc_mtokens]: <Local Minimum HTLC Millitokens String>
    local_reserve: <Local Reserved Tokens Number>
    other_ids: [<Other Channel Id String>]
    partner_public_key: <Channel Partner Public Key String>
    past_states: <Total Count of Past Channel States Number>
    pending_payments: [{
      id: <Payment Preimage Hash Hex String>
      [in_channel]: <Forward Inbound From Channel Id String>
      [in_payment]: <Payment Index on Inbound Channel Number>
      [is_forward]: <Payment is a Forward Bool>
      is_outgoing: <Payment Is Outgoing Bool>
      [out_channel]: <Forward Outbound To Channel Id String>
      [out_payment]: <Payment Index on Outbound Channel Number>
      [payment]: <Payment Attempt Id Number>
      timeout: <Chain Height Expiration Number>
      tokens: <Payment Tokens Number>
    }]
    received: <Received Tokens Number>
    remote_balance: <Remote Balance Tokens Number>
    [remote_csv]: <Remote CSV Blocks Delay Number>
    [remote_dust]: <Remote Non-Enforceable Amount Tokens Number>
    [remote_given]: <Remote Initially Pushed Tokens Number>
    [remote_max_htlcs]: <Remote Maximum Attached HTLCs Number>
    [remote_max_pending_mtokens]: <Remote Maximum Pending Millitokens String>
    [remote_min_htlc_mtokens]: <Remote Minimum HTLC Millitokens String>
    remote_reserve: <Remote Reserved Tokens Number>
    sent: <Sent Tokens Number>
    [time_offline]: <Monitoring Uptime Channel Down Milliseconds Number>
    [time_online]: <Monitoring Uptime Channel Up Milliseconds Number>
    transaction_id: <Blockchain Transaction Id String>
    transaction_vout: <Blockchain Transaction Vout Number>
    [type]: <Channel Commitment Transaction Type String>
    unsettled_balance: <Unsettled Balance Tokens Number>
  }]
}

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]: <Only Return Breach Close Channels Bool>
  [is_cooperative_close]: <Only Return Cooperative Close Channels Bool>
  [is_funding_cancel]: <Only Return Funding Canceled Channels Bool>
  [is_local_force_close]: <Only Return Local Force Close Channels Bool>
  [is_remote_force_close]: <Only Return Remote Force Close Channels Bool>
  lnd: <Authenticated LND gRPC API Object>
}

@returns via cbk or Promise
{
  channels: [{
    capacity: <Closed Channel Capacity Tokens Number>
    [close_balance_spent_by]: <Channel Balance Output Spent By Tx Id String>
    [close_balance_vout]: <Channel Balance Close Tx Output Index Number>
    close_payments: [{
      is_outgoing: <Payment Is Outgoing Bool>
      is_paid: <Payment Is Claimed With Preimage Bool>
      is_pending: <Payment Resolution Is Pending Bool>
      is_refunded: <Payment Timed Out And Went Back To Payer Bool>
      [spent_by]: <Close Transaction Spent By Transaction Id Hex String>
      tokens: <Associated Tokens Number>
      transaction_id: <Transaction Id Hex String>
      transaction_vout: <Transaction Output Index Number>
    }]
    [close_confirm_height]: <Channel Close Confirmation Height Number>
    [close_transaction_id]: <Closing Transaction Id Hex String>
    final_local_balance: <Channel Close Final Local Balance Tokens Number>
    final_time_locked_balance: <Closed Channel Timelocked Tokens Number>
    [id]: <Closed Standard Format Channel Id String>
    is_breach_close: <Is Breach Close Bool>
    is_cooperative_close: <Is Cooperative Close Bool>
    is_funding_cancel: <Is Funding Cancelled Close Bool>
    is_local_force_close: <Is Local Force Close Bool>
    [is_partner_closed]: <Channel Was Closed By Channel Peer Bool>
    [is_partner_initiated]: <Channel Was Initiated By Channel Peer Bool>
    is_remote_force_close: <Is Remote Force Close Bool>
    other_ids: [<Other Channel Id String>]
    partner_public_key: <Partner Public Key Hex String>
    transaction_id: <Channel Funding Transaction Id Hex String>
    transaction_vout: <Channel Funding Output Index Number>
  }]
}

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.5 and below

{
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  log: [<Log Line String>]
  options: [{
    type: <Option Type String>
    value: <Option Value String>
  }]
}

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.5 and below

{
  [is_anchor]: <Get Anchor Type Tower Info Bool>
  [is_taproot]: <Get Taproot Type Tower Info Bool>
  lnd: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  max_session_update_count: <Maximum Updates Per Session Number>
  sweep_tokens_per_vbyte: <Sweep Tokens per Virtual Byte Number>
  backups_count: <Total Backups Made Count Number>
  failed_backups_count: <Total Backup Failures Count Number>
  finished_sessions_count: <Finished Updated Sessions Count Number>
  pending_backups_count: <As Yet Unacknowledged Backup Requests Count Number>
  sessions_count: <Total Backup Sessions Starts Count Number>
  towers: [{
    is_active: <Tower Can Be Used For New Sessions Bool>
    public_key: <Identity Public Key Hex String>
    sessions: [{
      backups_count: <Total Successful Backups Made Count Number>
      max_backups_count: <Backups Limit Number>
      pending_backups_count: <Backups Pending Acknowledgement Count Number>
      sweep_tokens_per_vbyte: <Fee Rate in Tokens Per Virtual Byte Number>
    }]
    sockets: [<Tower Network Address IP:Port String>]
  }]
}

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: <Authenticated LND API Object>
}

@returns via cbk or Promise
{
  channels: [{
    other_ids: [<Channel Identifier String>]
    reference_id: <Top Level Channel Identifier String>
  }]
}

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]: <Creation Date After or Equal to ISO 8601 Date String>
  [created_before]:

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Lightning Network Service

Overview

Installing LND

Using gRPC

Subscriptions

All Methods

Additional Libraries

addAdvertisedFeature

addExternalSocket

addPeer

authenticatedLndGrpc

beginGroupSigningSession

broadcastChainTransaction

cancelHodlInvoice

cancelPendingChannel

changePassword

closeChannel

connectWatchtower

createChainAddress

createHodlInvoice

createInvoice

createSeed

createSignedRequest

createUnsignedRequest

createWallet

decodePaymentRequest

deleteChainTransaction

deleteFailedPayAttempts

deleteFailedPayments

deleteForwardingReputations

deletePayment

deletePayments

deletePendingChannel

diffieHellmanComputeSecret

disableChannel

disconnectWatchtower

enableChannel

endGroupSigningSession

fundPendingChannels

fundPsbt

getAccessIds

getAutopilot

getBackup

getBackups

getBlock

getBlockHeader

getChainAddresses

getChainBalance

getChainFeeEstimate

getChainFeeRate

getChainTransaction

getChainTransactions

getChannelBalance

getChannel

getChannels

getClosedChannels

getConfiguration

getConnectedWatchtowers

getEphemeralChannelIds

getFailedPayments