Awesome
holdinvoice
Core lightning (CLN) plugin to hold invoices. Supports rpc and grpc.
Installation
Release binaries for
- x86_64-linux
- armv7-linux (Raspberry Pi 32bit)
- aarch64-linux (Raspberry Pi 64bit)
can be found on the release page. If you are unsure about your architecture you can run uname -m
.
They require glibc>=2.31
, which you can check with ldd --version
.
In your cln config you must add:
important-plugin=<path/to/holdinvoice>
and if you want to use the plugin via grpc you must add:
grpc-hold-port=<port>
to run a separate grpc server for the plugins methods.
Building
You can build the plugin yourself instead of using the release binaries. First clone the repo:
git clone https://github.com/daywalker90/holdinvoice.git
Install a recent rust version (rustup is recommended).
Install protobuf-compiler
since we need protoc
:
apt install protobuf-compiler
Then in the holdinvoice
folder run:
cargo build --release
After that the binary will be here: target/release/holdinvoice
Note: Release binaries are built using cross
and the optimized
profile.
Documentation
There are four methods provided by this plugin:
holdinvoice
: amount_msat label description [expiry] [fallbacks] [preimage] cltv [deschashonly]- create an invoice where the HTLC's will be held by the plugin, it has almost the same options as cln's invoice, but cltv is required
holdinvoicesettle
: payment_hash- order plugin to settle a holdinvoice with enough HTLC's being held, does not wait for actual setllement of HTLC's
holdinvoicecancel
: payment_hash- order plugin to cancel a holdinvoice and return any pending HTLC's back, does not wait for actual return of HTLC's
holdinvoicelookup
: payment_hash- look up the holdstate of a holdinvoice and if it's in the ACCEPTED holdstate return the
htlc_expiry
- waits for actual settlement or return of HTLC's (with a timeout) and doublechecks holdstate with invoice state
- valid holdstates are:
- OPEN (no or not enough HTLC's pending)
- ACCEPTED (enough HTLC's to fulfill the invoice pending)
- SETTLED (invoice paid)
- CANCELED (invoice unpaid and will not accept any further HTLC's even if not yet expired)
- look up the holdstate of a holdinvoice and if it's in the ACCEPTED holdstate return the
The plugin will automatically cancel any invoice if it is either close to expiry (this is one major difference to the way lnd does it because cln can't settle with an expired invoice) or if a pending HTLC is close to expiry and would otherwise cause a force close of the channel. You can configure when this happens with the options below.
During a node restart invoices that were previously in the ACCEPTED state can temporarily be back in the OPEN state, because the HTLC's get replayed to the plugin during startup.
Options
You can set the following options in your cln config file:
holdinvoice-cancel-before-htlc-expiry
: number of blocks before HTLC's expiry where the plugin auto-cancels invoice and HTLC's, Default:6
holdinvoice-cancel-before-invoice-expiry
: number of seconds before invoice expiry where the plugin auto cancels any pending HTLC's and no longer accepts new HTLC's, Default:1800