Lightning

Methods for working with the Lightning Network

Selected Projects using Lightning

• bitpay.com crypto-rpc - https://github.com/bitpay/crypto-rpc
• channel.ninja - https://github.com/channelninja/channel.ninja
• coinos.io - https://github.com/coinos/coinos-server
• Galoy - https://github.com/GaloyMoney/galoy
• Lightning Poker - https://github.com/igreshev/lightning-poker
• Lightning Roulette - https://github.com/igreshev/lightning-roulette
• Lightning Shell - https://github.com/ibz/lightning-shell
• LNMarkets - https://github.com/lnmarkets/umbrel
• LNPingBot - https://github.com/swissrouting/lnpingbot
• MutinyWallet faucet - https://www.mutinywallet.com/
• p2plnbot - https://github.com/grunch/p2plnbot
• rekr - https://github.com/ryan-lingle/rekr
• stackernews - https://github.com/stackernews/stacker.news
• Suredbits API - https://github.com/Suredbits/sb-api-lnd
• Synonym Blocktank server - https://github.com/synonymdev/blocktank-server/
• Tarnhelm - https://github.com/bkiac/tarnhelm
• tbtcswaps - https://github.com/keep-community/tbtcswaps
• Thunderhub - https://github.com/apotdevin/thunderhub

LND Authentication

To connect to an LND node, authentication details are required.

Export credentials via CLI: balanceofsatoshis: npm install -g balanceofsatoshis and export via bos credentials --cleartext

Or 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 -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 {authenticatedLndGrpc} = require('lightning');

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

To access unauthenticated methods like the wallet unlocker, use unauthenticatedLndGrpc instead.

Debugging

If you encounter any issues connecting and wish to view detailed information about the underlying grpc calls, you can run Node with these environment variables set:

GRPC_VERBOSITY=DEBUG GRPC_TRACE=all node YOURSCRIPTNAME.js

Methods

• addExternalSocket: Add a new LN p2p network socket to node advertisement
• addPeer: Connect to a new peer
• authenticatedLndGrpc: Instantiate connection to authenticated lnd methods.
• beginGroupSigningSession: Start a new MuSig2 signing session
• broadcastChainTransaction: Publish an on-chain transaction to the network.
• cancelHodlInvoice: Cancel an open invoice.
• cancelPendingChannel: Cancel a pending channel.
• closeChannel: Close a channel out to the chain.
• changePassword: Update the wallet encryption passphrase.
• connectWatchtower: Connect a new watchtower.
• createChainAddress: Generate a chain address to receive on-chain funds.
• createHodlInvoice: Make a new off-chain invoice that will not automatically accept payment.
• createInvoice: Make a new off-chain invoice.
• createSeed: Generate a random wallet HD seed.
• createWallet: Make a new wallet.
• decodePaymentRequest: Get parsed details for a payment request.
• deleteFailedPayAttempts Remove failed payment paths from database.
• deleteFailedPayments Remove failed payments from the database.
• deleteForwardingReputations Clear pathfinding reputations of routing nodes and channels.
• deletePayment: Remove a past payment record.
• deletePayments: Remove all past payment records.
• diffieHellmanComputeSecret: Calculate a shared secret to enable symmetric encryption of data to another node.
• disableChannel: Signal disabled forwarding to a peer
• disconnectWatchtower: Remove a connected watchtower
• enableChannel: Signal forwarding enabled towards a peer.
• endGroupSigningSession: End a MuSig2 signing session
• fundPendingChannels: Provide a signed funding source for opening channels.
• fundPsbt: Make a PSBT with funds and change to setup a future on-chain spend.
• getAccessIds: List the access tokens granted permission to access the node.
• getAutopilot: Retrieve channel open autopilot configuration.
• getBackup: Get recovery details for a specific channel.
• getBackups: Get recovery details for all channels.
• getBlock: Get a block
• getChainAddresses: Get a list of created chain addresses
• getChainBalance: Get the amount of on-chain funds.
• getChainFeeEstimate: Estimate a chain fee to send funds to an address.
• getChainFeeRate: Get an estimate for an on-chain fee rate.
• getChainTransactions: List past on-chain transactions.
• getChannel: Lookup network graph details about a channel.
• getChannelBalance: Calculate the total off-chain balance on the node.
• getChannels: List open channels on the node.
• getClosedChannels: List closed channels on the node.
• getConnectedWatchtowers: List watchtowers that were added
• getEphemeralChannelIds: List other channel ids for channels
• getFailedPayments: List out past payments that failed.
• getFeeRates: List routing fee rates and routing policies of channels on the node.
• getForwardingConfidence: Calculate the pathfinding confidence score for routing a payment.
• getForwardingReputations: List the pathfinding reputations for payment routing.
• getForwards: List past forwards routed through the node.
• getHeight: Lookup the current best chain height.
• getIdentity: Derive the identity public key of the node.
• getInvoice: Lookup the status of an invoice.
• getInvoices: List details of all past open invoices and received payments.
• getLockedUtxos: List the UTXOs that are currently reserved and unavailable to coin selection.
• getMasterPublicKeys: List out master seed derived extended public keys and derivation paths.
• getMethods: List RPC methods and permissions required to use them.
• getNetworkCentrality: Calculate the graph centrality score of a node.
• getNetworkGraph: List all graph routing nodes and all channels.
• getNetworkInfo: Calculate network graph statistics.
• getNode: Retrieve graph details for a node and optionally list its channels.
• getPathfindingSettings: List out configuration options set for routing.
• getPayment: Lookup details about a past payment.
• getPayments: List details about past payment attempts and paid payment requests.
• getPeers: List details of connected nodes.
• getPendingChainBalance: Calculate the unconfirmed on-chain balance.
• getPendingChannels: List details of opening or closing channels.
• getPendingPayments: List out past pending payments.
• getPublicKey: Derive a public key at a given index.
• getRouteConfidence: Check a route to see the pathfinding confidence score that a payment would succeed.
• getRouteThroughHops: Calculate a route through specified nodes.
• getRouteToDestination: Calculate a route through the graph to a destination.
• getSettlementStatus: Lookup the status of a received payment output
• getSweepTransactions: List transactions that are sweeping funds on-chain.
• getTowerServerInfo: General information about a watchtower server running.
• getUtxos: List unspent transaction outputs in the on-chain wallet.
• getWalletInfo: Lookup general details about the node.
• getWalletStatus: Fetch the current state of the wallet.
• getWalletVersion: Retrieve the version and build tags of the node.
• grantAccess: Create an access credential macaroon to access the API.
• isDestinationPayable: Check if a destination can be paid
• lockUtxo: Lease a UTXO so it cannot be chosen to be spent.
• openChannel: Create a new channel to another node.
• openChannels: Open multiple channels in a single on-chain transaction batch.
• partiallySignPsbt: Add a partial signature to a PSBT
• pay: Make an off-chain payment.
• payViaPaymentDetails: Pay off-chain using details about a destination invoice.
• payViaPaymentRequest: Pay a payment request off-chain.
• payViaRoutes: Pay to a destination using a specified route or routes.
• prepareForChannelProposal: Prepare to receive a custom channel proposal.
• probeForRoute: Run a probe to find a route to pay to a destination.
• proposeChannel: Propose a new channel to a peer who has prepared for the channel proposal.
• recoverFundsFromChannel: Attempt to recover channel funds from a specific channel backup.
• recoverFundsFromChannels: Attempt to recover funds from multiple channels using a multiple channel backup.
• removeExternalSocket: Remove a LN p2p network socket from the node advertisement
• removePeer: Disconnect from a connected peer.
• requestChainFeeIncrease: Ask for a CPFP chain fee rate increase on a pending confirm UTXO.
• revokeAccess: Remove the access privileges of a previously issued access token macaroon credential.
• sendMessageToPeer: Send message to a connected peer.
• sendToChainAddress: Send funds on-chain to an address.
• sendToChainAddresses: Send funds on-chain to multiple chain addresses.
• sendToChainOutputScripts: Send funds on-chain to multiple chain destinations, specifying outputs scripts, not addresses.
• setAutopilot: Set the open channel autopilot configuration settings.
• settleHodlInvoice: Take incoming off-chain funds when an invoice has held funds from an incoming payment.
• signBytes: Use node keys to sign over an arbitrary set of bytes.
• signChainAddressMessage: Sign a message using the public key behind a chain address with ECDSA
• signMessage: Use the node identity key to generate a signed message that represents the public graph node identity.
• signPsbt: Sign inputs and finalize a partially signed transaction in the PSBT format to prepare it for broadcast.
• signTransaction: Generate signatures required for inputs on a transaction.
• stopDaemon: Send a shutdown request to cleanly kill the daemon.
• subscribeToBackups: Get notified on channel funds recovery backup file updates.
• subscribeToBlocks: Get notified when the Blockchain is updated.
• subscribeToChainAddress: Get notified when funds are sent to an on-chain address.
• subscribeToChainSpend: Get notified when a UTXO is spent.
• subscribeToChannels: Get notified when the set of active channels is updated.
• subscribeToForwardRequests: Get notified on requests to begin forward flows and interactively accept or reject or settle them.
• subscribeToForwards: Get notified on off-chain routed payment events.
• subscribeToGraph: Get notified of changes to the public routing graph nodes and channels.
• subscribeToInvoice: Get notified of status updates for incoming payments.
• subscribeToInvoices: Get notified of status updates on past created invoices.
• subscribeToOpenRequests: Get notified on requests to open an inbound channel and interactively accept or reject them.
• subscribeToPastPayment: Get notified of the current and ongoing status of a past off-chain payment.
• subscribeToPastPayments: Get notified of successful outgoing payments.
• subscribeToPayViaDetails: Make an off-chain payment using payment details and subscribe to the status of that payment.
• subscribeToPayViaRequest: Make an off-chain payment using a payment request and subscribe to the payment status.
• subscribeToPayViaRoutes: Start an off-chain payment using specific payment routes and subscribe to the payment result.
• subscribeToPayments: Subscribe to off-chain payments going out and being resolved
• subscribeToPeerMessages: Listen for incoming peer messages.
• subscribeToPeers: Listen to peer disconnect and connect events.
• subscribeToProbeForRoute: Start an off-chain probe to find a payable route and get notified on the status of the probe.
• subscribeToRpcRequests: Intercept all incoming and outgoing traffic to the RPC
• subscribeToTransactions: Get notified on on-chain transaction activity.
• subscribeToWalletStatus: Listen to updates to wallet state
• unauthenticatedLndGrpc: Create an lnd object for use with methods that do not require authentication credentials.
• unlockUtxo: Release a lease on a wallet UTXO to allow it to be selected for spending again.
• unlockWallet: Decrypt the wallet and start the daemon
• updateAlias: Update the advertised node alias
• updateChainTransaction: Edit the metadata of an on-chain transaction record.
• updateColor: Update the advertised node color
• updateConnectedWatchtower: Edit the settings on an added watchtower
• updateGroupSigningSession: Update a MuSig2 signing session with nonces and get a partial signature
• updatePathfindingSettings: Edit the configuration for routing calculations
• updateRoutingFees: Set the forwarding fees or other routing policies for a channel or all channels.
• verifyAccess: Confirm a macaroon has permission to access a given resource.
• verifyBackup: Check if a channel fund recovery backup file is valid.
• verifyBackups: Check if multiple channel fund recovery backups are valid.
• verifyBytesSignature: Check that a signature over arbitrary bytes is valid.
• verifyChainAddressMessage: Verify that a chain address message has a valid ECDSA signature
• verifyMessage: Check that a message from a node in the graph has a valid signature.