BTCPayServer.Lightning.CLightning 1.6.0

dotnet add package BTCPayServer.Lightning.CLightning --version 1.6.0                
NuGet\Install-Package BTCPayServer.Lightning.CLightning -Version 1.6.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BTCPayServer.Lightning.CLightning" Version="1.6.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BTCPayServer.Lightning.CLightning --version 1.6.0                
#r "nuget: BTCPayServer.Lightning.CLightning, 1.6.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install BTCPayServer.Lightning.CLightning as a Cake Addin
#addin nuget:?package=BTCPayServer.Lightning.CLightning&version=1.6.0

// Install BTCPayServer.Lightning.CLightning as a Cake Tool
#tool nuget:?package=BTCPayServer.Lightning.CLightning&version=1.6.0                

CircleCI

A C# library for Lightning Network clients

Introduction

This library is meant to facilitate the development of Lightning Network based apps written in C#. Its main goal isn't to perfectly implement client API of all lightning node implementation, but to provide a common abstraction that can be used to support many implementations at once.

The most important packages are:

  • BTCPayServer.Lightning.Common contains the common abstractions shared between those implementation.
  • BTCPayServer.Lightning.All contains LightningClientFactory which can convert a connection string to an instance of ILightningClient.

If your app depends on ILightningClient directly, you will be able to support those different lightning implementations out of the box.

Here is a description of all packages:

  • BTCPayServer.Lightning.All super package which reference all the others NuGet
  • BTCPayServer.Lightning.Common exposes common classes and ILightningClient NuGet
  • BTCPayServer.Lightning.LND exposes easy to use LND clients NuGet
  • BTCPayServer.Lightning.CLightning exposes easy to use clightning clients NuGet
  • BTCPayServer.Lightning.Charge exposes easy to use Charge clients NuGet
  • BTCPayServer.Lightning.Eclair exposes easy to use Eclair clients NuGet
  • BTCPayServer.Lightning.LNbank exposes easy to use LNbank clients NuGet
  • BTCPayServer.Lightning.LNDhub exposes easy to use LNDhub clients NuGet

If you develop an app, we advise you to reference BTCPayServer.Lightning.All NuGet.

If you develop a library, we advise you to reference BTCPayServer.Lightning.Common NuGet.

You can also use our BOLT11PaymentRequest to parse BOLT11 invoices. (See example).

How to use

Click on the nuget button of the package interesting you, and follow the instruction to add it to your project. For .NET Core Apps, you need to enter this in your project's folder:

dotnet add package BTCPayServer.Lightning.All

You have two ways to use this library:

  • Either you want your code to works with all lightning implementation (right now LND, Charge, CLightning)
  • Or you want your code to work on a particular lightning implementation

Using the generic interface

This is done by using LightningClientFactory and the common interface ILightningClient.

string connectionString = "...";
ILightningClientFactory factory = new LightningClientFactory(Network.Main);
ILightningClient client = factory.Create(connectionString);
LightningInvoice invoice = await client.CreateInvoice(10000, "CanCreateInvoice", TimeSpan.FromMinutes(5));

ILightningClient is an interface which abstract the underlying implementation with a common interface.

The connectionString encapsulates the necessary information BTCPay needs to connect to your Lightning node, we currently support:

  • clightning via TCP or unix domain socket connection
  • lightning charge via HTTPS
  • LND via the REST proxy
  • Eclair via their new REST API
  • LNbank via REST API
  • LNDhub via their REST API
Examples
  • type=clightning;server=unix://root/.lightning/lightning-rpc
  • type=clightning;server=tcp://1.1.1.1:27743/
  • type=lnd-rest;server=http://mylnd:8080/;macaroonfilepath=/root/.lnd/invoice.macaroon;allowinsecure=true
  • type=lnd-rest;server=https://mylnd:8080/;macaroon=abef263adfe...
  • type=lnd-rest;server=https://mylnd:8080/;macaroon=abef263adfe...;certthumbprint=abef263adfe...
  • type=lnd-rest;server=https://mylnd:8080/;macaroonfilepath=/root/.lnd/invoice.macaroon;certfilepath=/var/lib/lnd/tls.cert
  • type=charge;server=https://charge:8080/;api-token=myapitoken...
  • type=charge;server=https://charge:8080/;cookiefilepath=/path/to/cookie...
  • type=eclair;server=http://127.0.0.1:4570;password=eclairpass
  • type=eclair;server=http://127.0.0.1:4570;password=eclairpass;bitcoin-host=bitcoin.host;bitcoin-auth=btcpass
  • type=lnbank;server=http://lnbank:5000;api-token=myapitoken;allowinsecure=true
  • type=lnbank;server=https://mybtcpay.com/lnbank;api-token=myapitoken
  • type=lndhub;server=https://login:password@lndhub.io
Eclair notes

Note that bitcoin-host and bitcoin-auth are optional, only useful if you want to call ILightningClient.GetDepositAddress on Eclair. We expect this won't be needed in the future.

LND notes

Unless the LND certificate is trusted by your machine you need to set the server authentication scheme for LND by specifying one of: certthumbprint, certfilepath, allowinsecure=true.

certfilepath and certthumbprint are equivalent in terms of security but differ in their practical usage. certfilepath reads a file on your file system so unless you set up some kind of file syncing you can not use it for remote connections. The advantage is that if the certificate is updated (and synced in case of a remote machine) no more reconfiguration is required for RPC connections to continue to work. It is therefore the recommended option if you can use it.

The certthumbprint to connect to your LND node can be obtained through this command line:

openssl x509 -noout -fingerprint -sha256 -in /root/.lnd/tls.cert | sed -e 's/.*=//;s/://g'

allowinsecure=true just blindly accepts any server connection and is therefore not secure unless used in tightly controlled environments. E.g. host is the same machine or is accessed over an encrypted tunnel, assuming no untrusted entities can bind the specified port.

LNDhub notes

You can also use the lndhub:// URL, which can be retrieved e.g. from the BlueWallet Export/Backup screen. The library turns it into the expected type=lndhub connection string format.

Using implementation specific class

If you want to leverage specific lightning network implementation, either instanciate directly ChargeClient, LndClient or CLightningClient, or cast the ILightningClient object returned by LightningClientFactory.

How to test

You first need to run all the dependencies with docker-compose:

cd tests
docker-compose up

Then you can run and debug the tests with Visual Studio or Visual Studio Code.

If you want to use command line:

cd tests
dotnet test

Licence

MIT

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on BTCPayServer.Lightning.CLightning:

Package Downloads
BTCPayServer.Lightning.All

Client library for lightning network implementations to build Lightning Network Apps in C#.

BTCPayServer.Lightning.Charge

Client library for lightning charge to build Lightning Network Apps in C#.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.6.0 5,956 4/10/2024
1.5.1 6,162 11/21/2023
1.5.0 263 10/19/2023
1.3.28 5,271 7/24/2023
1.3.27 3,469 5/12/2023
1.3.26 3,601 4/6/2023
1.3.25 4,764 2/2/2023
1.3.24 1,588 1/11/2023
1.3.23 630 1/10/2023
1.3.22 880 1/6/2023
1.3.21 1,212 12/23/2022
1.3.20 724 12/22/2022
1.3.19 1,059 12/7/2022
1.3.18 835 12/6/2022
1.3.17 755 12/5/2022
1.3.16 2,596 10/31/2022
1.3.15 979 10/26/2022
1.3.14 2,142 9/26/2022
1.3.13 1,072 9/15/2022
1.3.12 1,056 9/9/2022
1.3.11 952 9/9/2022
1.3.10 678 8/23/2022
1.3.9 5,168 7/8/2022
1.3.8 1,719 6/21/2022
1.3.7 5,617 6/8/2022
1.3.6 1,018 6/2/2022
1.3.5 2,005 5/19/2022
1.3.4 702 5/18/2022
1.3.3 1,104 5/14/2022
1.3.2 3,099 4/3/2022
1.3.1 3,253 2/16/2022
1.3.0 1,122 2/14/2022
1.2.11 984 2/13/2022
1.2.10 6,604 11/26/2021
1.2.9 3,329 10/21/2021
1.2.8 3,502 8/25/2021
1.2.7 733 8/18/2021
1.2.6 947 8/10/2021
1.2.5 1,210 7/29/2021
1.2.4 916 7/15/2021
1.2.3 33,303 1/27/2021
1.2.2 1,057 8/27/2020
1.2.1 6,729 8/17/2020
1.2.0 4,693 6/8/2020
1.1.8 1,841 5/19/2020
1.1.7 18,179 4/26/2020
1.1.6 4,910 3/10/2020
1.1.5 4,810 12/27/2019
1.1.4 769 12/27/2019
1.1.3 3,153 11/2/2019
1.1.2 925 11/1/2019
1.1.1 2,037 8/17/2019
1.1.0.17 1,334 7/13/2019
1.1.0.16 1,104 7/4/2019
1.1.0.15 937 7/1/2019
1.1.0.14 1,770 5/16/2019
1.1.0.13 1,377 5/7/2019
1.1.0.12 1,068 4/17/2019
1.1.0.11 1,363 4/10/2019
1.1.0.10 1,150 3/25/2019
1.1.0.9 1,154 3/17/2019
1.1.0.8 1,462 3/14/2019
1.1.0.7 1,411 3/2/2019
1.1.0.6 1,319 2/20/2019
1.1.0.5 1,310 2/17/2019
1.1.0.4 5,862 1/22/2019
1.1.0.3 1,877 12/19/2018
1.1.0.2 1,474 12/9/2018
1.1.0.1 1,629 11/6/2018
1.1.0 2,301 9/9/2018
1.0.0.2 1,093 8/30/2018
1.0.0.1 1,315 8/30/2018
1.0.0 1,324 8/29/2018