Progress pill
Introduction to Securing Bitcoin Keys

BTCPay Server Lightning Wallet

Mastering BTC Pay Server

BTCPay Server Lightning Wallet

  • Connect internal node (server administrator)
  • Connect external node (server user/store owner)
  • Managing internal Lightning node LND (Server administrator)
  • Lightning wallet
  • Example 1
  • Example 2
  • Skill Summary
  • Knowledge assessment Practical Review
When a server administrator provisions a new BTCPay Server instance, they can set up a Lightning Network implementation, such as LND, Core Lightning, or Eclair; see Part Configuring BTCPay Server for more detailed installation instructions.
If followed along by a classroom, connecting a Lightning node to your BTCPay Server works through a Custom node. A user who is not a server administrator on BTCPay Server will not be able to use the internal Lightning node by default. This is to protect the server owner from losing their funds. Server administrators may install a plugin to grant access to their Lightning node through LNBank; this is outside the scope of this book. For more information on LNBank, refer to the official plugin page.

Connect internal node (server administrator)

The Server Administrator can use BTCPay Server's internal Lightning Node. Regardless of the Lightning implementation, connecting to the internal Lightning node is the same.
Go to a previous setup store, and click on the "Lightning" wallet in the left menu. BTCPay Server gives two setup possibilities: using the Internal node (Server admin only by default) or a custom node (external connection). Server administrators can click on the "Use internal node" option. There is no need for any more configuration. Click the "save" button and notice the notification stating, "BTC Lightning node updated". The store has now successfully got Lightning network capabilities.

Connect external node (server user/store owner)

By default, store owners are not allowed to use the server administrator Lightning Node. The connection needs to be made to an external node, either a node owned by the store owner before setting up a BTCPay Server, an LNBank plugin if made available by the server administrator, or a custodian solution like Alby.
Go to a previous setup store, and click "Lightning" underneath wallets in the left menu. As store owners are not allowed to use the internal node by default, this option is grayed out. Using a custom node is the only option available by default for store owners.
BTCPay Server requires connection information; the pre-made (or custodian solution) will deliver this information specifically tailored to a Lightning implementation. Within the BTCPay Server, Store owners can use the following connections;
  • C-lightning via TCPorUnixdomainsocketconnection.
  • Lightning Charge via HTTPS
  • Eclair via HTTPS
  • LND via the REST proxy
  • LNDhub via the REST API
Click "test connection" to ensure you correctly entered the connection details. After the connection is confirmed to be good, click 'Save', and BTCPay Server shows that the store is updated with a Lightning Node.

Managing internal Lightning node LND (Server administrator)

After connecting the internal Lightning Node, server administrators will notice new tiles on the Dashboard specifically for Lightning information.
  • Lightning Balance
  • BTC in channels
    • BTC opening channels
    • BTC local Balance
    • BTC remote balance
    • BTC closing channels
  • BTC On-chain
    • BTC confirmed
    • BTC unconfirmed
    • BTC reserved
  • Lightning Services
    • Ride the Lightning (RTL).
By clicking either on the Ride the Lightning Logo in the "Lightning services" tile or "Lightning" underneath wallets in the left menu, server administrators can reach RTL for Lightning node management.
Note!
Connecting the internal Lightning Node fails - If the internal connection fails, confirm:
  1. The Bitcoin on-chain node is fully synchronized
  2. The Internal lightning node is "Enabled" under "Lightning" > "Settings" > "BTC Lightning Settings"
If you are unable to connect to your Lightning node, you can try restarting your server, or read more details on BTCPay Server official documentation; https://docs.btcpayserver.org/Troubleshooting/. You cannot accept lightning payments in your store until your Lightning node appears "Online". Try to test your Lightning connection by clicking the "Public Node Info" link.

Lightning wallet

Within the Lightning wallet option in the left menu bar, server administrators will find easy access to RTL, their Public node Info, and Lightning settings specific to their BTCPay Server store.

Internal node info

Server administrators can click on the internal node info to view their server status (Online/Offline) and connection string for Clearnet or Tor.

Change connection

To change the external Lightning node, go to "Lightning Settings" and click "Change connection" (next to "Public Node info"). This resets the existing setup. Enter the new node details, click Save, and the store will update accordingly.

Services

If the server administrator decides to install multiple services for the Lightning implementation, they will be listed here. With a standard LND implementation, administrators will have Ride The Lightning (RTL) as a standard tool for node management.

BTC Lightning wallet settings

After adding the Lightning node to the store in a previous step, store owners can still choose to deactivate it for their store by using the Toggle at the top of the Lightning settings.

Lightning Payment options

Store owners can set the following parameters to enhance the Lightning experience for their customers.
  • Display Lightning payment amounts in Satoshis.
  • Add hop hints for private channels to the Lightning invoice.
  • Unify on-chain and Lightning payment URL/QR codes at checkout.
  • Set a description template for lightning invoices.

LNURL

Store owners can choose to either use or not use LNURL. A Lightning Network URL, or LNURL, is a proposed standard for interactions between Lightning Payer and payee. In short, an LNURL is a bech32 encoded URL prefixed with LNURL. The Lightning wallet is expected to decode the URL, contact the URL, and await a JSON object with further instructions, most notably a tag that defines the behavior of the LNURL.
  • Enable LNURL
  • LNURL Classic Mode
    • For wallet compatibility, Bech32 encoded (classic) vs cleartext URL (upcoming)
  • Allow the payee to pass a comment.

Example 1

Connect to Lightning with the internal node (Administrator)

This option is only available if you are the Administrator of this instance or if the Administrator has changed the default settings so that users can use the internal lightning node.
As an administrator, click on the Lightning Wallet in the left menu bar. BTCPay Server will ask you to select one of two options for connecting a Lightning Node: an Internal node or a custom external node. Click on "Use internal node" and then click "Save."

Managing your Lightning node (RTL)

After connecting to the internal Lightning node, BTCPay Server will update and show a notification "BTC Lightning node updated", confirming you have now connected Lightning to your store.
Managing the lightning node is a task for the server administrator. This involves the following:
  • Manage transaction
  • Managing liquidity
    • Inbound liquidity
    • Outbound liquidity
  • Managing peers and channels
    • Connected peers
    • Channel fees
    • Channel status
  • Making frequent backups of the channel states.
  • Checking routing reports
  • Alternatively, use services such as Loop.
All lightning node management is done as standard with RTL (assuming you are running on an LND implementation). Administrators can click on their Lightning Wallet in BTCPay Server and find a button to open RTL. The main Dashboard of BTCPay Server is now updated with the Lightning Network Tiles, including quick access to RTL.

Example 2

Connect to lightning with Alby

When connecting with a custodian like Alby, store owners should first create an account and visit https://getalby.com/
After creating the Alby account, go to your BTCPay Server store.
Step 1: Click 'Set up a Lightning node' on the Dashboard or 'Lightning' underneath wallets.
Step 2: Insert your Wallet connection credentials provided by Alby. On the Dashboard of Alby, click on Wallet. Here you will find "Wallet Connection Credentials". Copy these credentials. Paste the credentials from Alby into the Connection configuration field in BTCPay Server.
Step 3: After providing BTCPay Server with the Connection details, click the "Test Connection" button to ensure the connection is working properly. Notice the "Connection to lightning node successful" message at the top of your screen. This confirms that everything is working as expected.
Step 4: Click "Save," and your store is now connected to a Lightning node by Alby.
!Note!
Never trust a custodian Lightning solution with more value than you are willing to lose.

Skill Summary

In this section, you learned:
  • How to connect an internal or external Lightning node
  • The contents and function of various Lightning-related tiles in the Dashboard
  • How to configure Lightning wallet using Voltage Surge or Alby

Knowledge assessment Practical Review

Describe some of the various options for connecting a Lightning wallet to your store.