Core Lightning plugins in 2023

If I understand correctly, the plugin system has been introduced in release [0.6.3] - 2019-01-09: "The Smallblock Conspiracy".

And the most import plugin ever written (cowsay.sh) has been introduced with the following pull request: The most important contrib/ addition, ever. #2985.

◉ tony@tony:~/clnlive/lightning:[git»(HEAD detached at v23.05.2)]
$ git log --oneline --reverse --pretty=format:"%an" lightningd/plugin.c | sort | uniq
arowser
Christian Decker
Conor Scott
darosior
lisa neigut
Michael Schmoock
Richard Bondi
Rusty Russell
Simon Vrouwe
trueptolemy
Vasil Dimov
Vincenzo Palazzo
ZmnSCPxj
ZmnSCPxj jxPCSnmZ

Plugins can be written in any languages.

They are started by lightningd and live as subprocesses of lightningd master process. They read incoming requests from lightningd in their stdin stream and send responses/notifications to lightningd by writing to their stdout stream.

When started, plugins reply to a getmanifest request telling lightningd what they want to register, declare and subscribe to (startup options, JSON-RPC commands, notification topics and hooks).

Then they receive an init request from lightningd. At that moment, plugins have complete information about the node, therefore they can initialize themselves if necessary (starting a webserver for instance). When they are done they reply to that init request which tell lightningd that it can proceed.

Finally, plugins start an IO loop waiting for incoming request from lightningd.

Note that lightningd and plugins use JSON-RPC 2.0 to understand each other.

See lightning:doc/PLUGINS.md.

The following Bash script foo-plugin.bash implements a CLN plugin that registers foo-method JSON-RPC method to lightningd. When we call that method from any client with no argument, it returns the json {"foo":"bar"}. Note that this uses no specific CLN library and only depends only on jq command for convenience:

#!/usr/bin/bash

set -e

# getmanifest
read -r JSON
read -r _
id=$(echo "$JSON" | jq .id)
echo '{"jsonrpc": "2.0", "id": '"$id"', "result": {"dynamic": true, "options": [], "rpcmethods": [{"name": "foo-method", "usage": "", "description": "description"}]}}'

# init
read -r JSON
read -r _
id=$(echo "$JSON" | jq .id)
echo '{"jsonrpc": "2.0", "id": '"$id"', "result": {}}'

# i/o loop
while read -r JSON; do
    read -r _
    id=$(echo "$JSON" | jq .id)
    echo '{"jsonrpc": "2.0", "id": '"$id"', "result": {"foo": "bar"}}'
done

The plugin can be started like this

◉ tony@tony:~/clnlive:
$ lightning-cli plugin start $(pwd)/foo-plugin.bash

and foo-method command can be called using lightning-cli RPC client like this:

◉ tony@tony:~/clnlive:
$ lightning-cli foo-method
{
   "foo": "bar"
}

Now, if we use a plugin library to write plugins, all the plumbing goes away and we can focus on our use case. For instance the previous foo-plugin.bash plugin would be written in Python using pyln-client library like this:

#!/usr/bin/env python3
from pyln.client import Plugin

plugin = Plugin()

@plugin.method("foo-method")
def foo_method_func(plugin):
    return {"foo": "bar"}

plugin.run()

• plugins:backup/README.md: This plugin will maintain clean database backups to another location. It uses the `db_write` hook to make sure to always have a backup that is not missing any state updates and is not potentially harmful.

• clightning4j/esplora_clnd_plugin: Using @Blockstream Esplora web explorer to fetch bitcoin data for clightning.

• coffee-tools/folgore: Universal Bitcoin backend for core lightning with BIP 157 support full based on the btcli4j Kotlin plugin! Ah, yes it is written in Rust.

• clightning4j/btcli4j: It is a core lightning plugin to override Bitcoin backend plugin with esplora by Blockstream and give the possibility to make the running process with bitcoind in pruning mode more solid.

• plugins:sauron/README.md: A Bitcoin backend plugin relying on Esplora.

• nbd-wtf/trustedcoin: A lightningd plugin that replaces bitcoind with trusted public explorers.

• andrewtoth/rust-bcli: A CoreLightning bitcoin backend plugin written in rust to replace the built-in bcli.

• Start9Labs/c-lightning-pruning-plugin: This plugin manages pruning of bitcoind such that it can always sync.

• ElementsProject/peerswap: PeerSwap allows two different types of swaps: swap-in / swap-out.

• nbd-wtf/poncho: This is an early alpha software that turns your CLN node into a hosted channels provider.

• justinmoon/clhwi: C-Lightning Plugin to Fund Channels w/ Hardware Wallets.

• plugins:autopilot/README.md: This is a version of Rene Pickhardt's Autopilot library ported as a Core-Lightning plugin.

• renepickhardt/lightning-network-autopilot: A python library that uses data science and statistical methods to make recommendations for channel management of lightning network node operators.

• daywalker90/summars: A core lightning plugin to show a summary of your channels and optionally recent forwards.

• rsbondi/multifund: c-lightning plugin to fund multiple channels with a single transaction.

• kristapsk/lightning-channelbalance: channelbalance plugin for c-lightning.

• ZmnSCPxj/clboss: Automated Core Lightning Node Manager.

• ZmnSCPxj/cldcb: C-Lightning Dynamic Channel Backup.

• plugins:rebalance/README.md: This plugin moves liquidity between your channels using circular payments.

• plugins:persistent-channels/README.md: The persistent channels plugin allows you to describe a number of channels you'd like to have open at any time and the plugin will attempt to maintain that state.

• plugins:drain/README.md: This plugin drains or fills up the capacity of one of your channel using circular payments to yourself.

• plugins:jitrebalance/jitrebalance.py: JIT rebalancing of channels.

• plugins:feeadjuster/README.md: This plugin dynamically adjusts fees according to channel balances.

• fiatjaf/vhc: c-lightning hosted channels plugin in V.

• giovannizotta/circular: Core Lightning plugin that helps routing nodes rebalance their channels.

• plugins:monitor/README.md: Monitors the health of your peers and helps you to decide if you might want to close a channel.

• daywalker90/sling: A core lightning plugin to automatically rebalance multiple channels.

• toneloc/stable-channels: p2p stable channels on the Bitcoin Lightning Network.

• chrisguida/watchdescriptor: watchdescriptor is a Rust-based CLN plugin that allows CLN's bookkeeper plugin to track coin movements in external descriptor wallets, enabling businesses to obtain a complete picture of all bitcoin inflows and outflows.

• flitz-be/lightningd-redis-publisher: Publish C-Lightning events to redis.

• rbndg/c-lightning-events: Subscribe to C-Lightning events with websocket.

• yukibtc/cln-ntfy: CLN plugin for ntfy.

• vincenzopalazzo/crab.rs: Crab: a rust plugin for core lightning able to manage a notify system.

• fiatjaf/lightningd-webhook: A lightningd plugin that emits webhooks for each notification events.

• plugins:zmq/README.md: This module forwards notifications to ZeroMQ endpoints depending on configuration.

• rsbondi/clightning-rest: A rest plugin for clightning.

• Start9Labs/c-lightning-http-plugin: A plugin for c-lightning that proxies http rpc traffic to the unix domain socket.

• Ride-The-Lightning/c-lightning-REST: REST APIs for Core Lightning written with node.js.

• clightning4j/jrest: A Java plugin for c-lightning to expose the API over rest!

• willcl-ark/lightning-macaroons: c-lightning RPC macaroons.

• nettijoe96/c-lightning-graphql: graphql api plugin for c-lightning.

• nettijoe96/jwt-factory: Json Web Tokens (JWT) to provide auth for c-lightning plugins.

• vincenzopalazzo/cln-remote-api: Rust Remote API for core lightning provided as library and a plugin.

• jb55/cln-core-rpc: expose bitcoin-core rpcs as clightning rpcs.

• AutonomousOrganization/freeze: Hold invoices for core lightning.

• hodlinvoices (niftynei): How to hodlinvoices on @Core_LN?

• lnplay.live-plugin: Core Lighting plugin for https://lnplay.live. Developed for the tabconf2023 hackathon. The RPC method lnplaylive-createorder is called by the front end web app to get an invoice for a product and lnplaylive-invoicestatus rpc method returns the status of a BOLT11 invoice.

• endothermicdev/impscan: CLN plugin to scan for active implementations on the lightning network.

• plugins:probe/README.md: This plugin regularly performs a random probe of the network by sending a payment to a random node in the network, with a random `payment_hash`, and observing how the network reacts.

• niftynei/sitzprobe: sitzprobe is a c-lightning plugin that actively sends test payments through the lightning network.

• plugins:historian/README.org: The historian plugin aims to provide tools to archive the Lightning Network gossip messages and to work with the archived messages.

• AutonomousOrganization/fgln: Plugin and library that uses graph Library fgl to load lightning network into functional data structure and create some convenience functions (in progress).

• litch/spaz: This is a CLN plugin to make a fairly randomly spazzy node in a network.

• elsirion/clnurl: Core Lightning plugin for LNURL and LNAddress support.

• breez/lspd: lspd is a simple deamon that provides LSP services to Breez clients. This is a simple example of an lspd that works with an LND node or a CLN node. The CLN plugin is defined in the subdirectory cln_plugin.

• plugins:noise/README.org: The Noise plugin allows sending and receiving private messages through the Lightning Network.

• bitonic-cjp/lightning-message-demo: This software demonstrates how data can be sent along with Lightning payments, from payer to payee.

• LNOpenMetrics/go-lnmetrics.reporter: Reference implementation written in Go to collect and report of the lightning node metrics.

• plugins:prometheus/README.md: This plugin exposes some key metrics from c-lightning in the prometheus format so it can be scraped, plotted and alerts can be created on it.

• kristapsk/lightning-feereport: feereport plugin for c-lightning.

• AutonomousOrganization/summy: Summarize Core Lightning status with rpc calls and forward logs.

• 0xB10C/c-lightning-plugin-csvexportpays: A c-lightning plugin that exports all payments to a CSV file.

• plugins:summary/README.md: This plugin is a little hack to show a summary of your node, including fiat amounts.

• jb55/clightning-offer-summary: a clightning plugin that summarizes paid offer invoices.

• kristapsk/lightning-walletbalance: walletbalance plugin for c-lightning.

• munin-clightning: These plugins offer visualization for channels, CLN logs, feerates, fees, funds, invoices and payments.

• daywalker90/vitality: Core lightning (CLN) plugin to watch channel health, gossip health and ping amboss for online status.

• joelklabo/nostr-control: A CLN Plugin you can interact with over Nostr DM.

• joelklabo/nostrify: Core Lightning plugin that sends events to Nostr.

• thesimplekid/cln-nostr-wallet-connect: Core Lightning plugin for nostr wallet connect.

• thesimplekid/cln-zapper-rs: Core Lightning plugin for sending zap events.

• daGoodenough/bolt12-prism: CLN plugin for lightning prisms using BOLT 12.

• andrewtoth/paythrough: CoreLightning plugin to pay through a specific channel.

• plugins:paytest/README.org: A plugin to benchmark the performance of the pay plugin. It can generate mock invoices for remote nodes, and it can hold on to incoming test multi-part payments as if they were real payments.

• ZmnSCPxj/payz: Plugin for an alternative to the normal C-Lightning pay algorithm.

• fiatjaf/trampoline: Trampoline payments plugin for c-lightning.

• dart-lightning/kraken: Kraken is a plugin for Core Lightning that helps you analyze payment failure and try to procude a suggestion.

• darosior/lightning-qt: lightning-qt is a Python plugin for C-lightning, a Lightning Network daemon. It enables the use of a bitcoin-qt-like Graphical User Interface (actually, part of the icons and forms have been taken from bitcoin-qt and modified) via the RPC interface.

• talaia-labs/rust-teos: The Eye of Satoshi - Lightning Watchtower.

• plugins:currencyrate/README.md: This plugin provides Bitcoin currency conversion functions using various different backends and taking the median. It caches results for an hour.

• plugins:datastore/README.md: The next version of c-lightning (0.10.2?) has a built-in datastore. Until then, this plugin serves the same purpose, and has the same interface.

• rsbondi/clightning-dotnet-plugin: Hello world plugin in csharp

• plugins:donations/README.md: This plugin enables c-lightning nodes to start one or several small webserver via the command line on specified port. The webserver is based on flask and exposes the invoice API call.

• plugins:helpme/README.md: This plugin is designed to walk you through setting up a fresh Core-Lightning node, offering advice for common problems.

• clightning4j/LNQrcode: It is a plugin for c-lightning to display a QR code on a View!

• jb55/clightning-discovery: clightning dns-sd auto-discovery plugin

• andrewtoth/broadcast-over-tor: Privacy enhancing CoreLightning plugin which broadcasts all on-chain transactions to random nodes over tor.

• andrewtoth/listmempoolfunds: CoreLightning plugin to track unconfirmed funds.

• kristapsk/c-lightning-lnd-plugins: Plugins for c-lightning emulating some commands of LND (lncli).

• AI4ALL: Build an AI enabled 'helpme' Plugin for Core Lightning: Build an AI enabled version of the helpme plugin for the Core Lightning (a Bitcoin Lightning Network Node implementation) command line tool.

• Advanced c-lightning Node Customization: Dangerous Hooks:

  • how to ban a command,

  • how to extend the invoice command such that we can pass the amount in cents to the command,

  • how to require a password to run the JSON-RPC commands,

  • how to replace a command by another.

• Rusty Russell - JSON Interface with c-lightning and Writing Extensions:

  • plugin system with a shell example plugin,

  • pylightning Python library,

  • write plugin that create an invoice when we visit, http://localhost:5000 url and show the invoice in the browser.

• Rusty Russell | Getting Started with c-lightning Webinar | February 17 2021:

  • helpme.py plugin,

  • summary.py plugin,

  • currencyrate.py plugin.

• Protocol Development Using c-lightning:

  • how we can use Core Lightning and its exposed interfaces to build some prototypes for LN protocol,

  • sendcustommsg, createonion, sendonion RPC commands,

  • pyln-client, pyln-testing,

  • building a chat app,

  • plugins:noise/README.org.

• Christian Decker - the c-lightning API: plugin system.

• c-lightning 0.9.2: Notifications | Lisa Neigut | December 3 2020:

  • notifications,

  • writing a plugin with pyln-client,

  • tests/plugins/notify.py (in lightning).

• Core Lightning Plugin: Bookkeeper: builtin bookkeeper plugin.

• Core Lightning Plugin: Chanbackup: chanbackup plugin.

• Antoine Poinsot - c-lightning plugins:

  • Core Lightning design,

  • how plugins work,

  • Why plugins are great,

• Lightning Network Autopilot - lib_autopilot.py submission for bitcoin 2019 virtual hackathon:

  • https://github.com/renepickhardt/lightning-network-autopilot,

  • plugins:autopilot/README.md.

• DEVELOPER - How to create c-lightning plugins & personal announcement!:

  • pylightning Python library.

• Let's Build Sauron: Running a Lightning Node from a Repl:

  • bitcoin backend plugin Sauron,

  • Installing it and how does it works.

• #Ai4ALL / Let's Build Sauron: Running a Lightning Node from a Repl (condensed)

  • bounty for building an CLN plugin helpme using AI,

  • sauron bitcoin backend plugin,

  • helpme plugin,

  • pyln-client.

• Deploying an Eye of Satoshi Lightning Watchtower:

  • the deployement of a test network with two CLN nodes and a watchtower using Polar,

  • the installation of The Eye of Satoshi watchtower,

  • the installation of watchtower-client plugin for CLN and

  • some basic interactions between a node and the watchtower.

• CORE LIGHTNING - 2 Plugins:

  • summary plugin,

  • backup plugin and with file in another server using NFS file system.

• Fully Noded & C-Lightning Chat using the Noise plugin: plugins:noise/README.org.

• Highlight: Write a clever plugin manager written in rust for core lightning

  • Live coding writing a PR for a CLN plugin manager.

• clnrest Latest Features with Shahana: Become better at controlling your CLN node by using clnrest to its fullest potential. Join Blockstream Front-End Engineer Shahana Farooqi to find out more about recent improvements as well as:

  • clnrest usage in applications

  • rune validation

  • certificate generation

  • configuration options

  • automated tests

• Learn everything you need to add custom functionality to your node by writing plugins for CLN:

  • Plebdev Workshop - Developing Core Lightning Plugins (Part #1)

  • Plebdevs Workshop: Core Lightning Plugins #2

• Understand CLN Plugin mechanism with a Python example: In this live, we add the method myplugin to Core Lightning by writing a dynamic Python plugin called myplugin.py. Doing this, we try to understand: (1) how startup options are passed to the plugin, (2) how cli parameters are passed to the plugin and (3) how to communicate to the lightning node via JSON-RPC over unix sockets.

• Register a JSON-RPC method to Core Lightning using pyln-client Python package: In this live, we register a JSON-RPC method in Core Lightning using pyln-client Python package. As pyln-client uses Python decorators to declare JSON-RPC methods, in the second part we try to understand how they work by playing with 2 examples, the second one being very close to the way pyln-client uses them.

• How to write tests for CLN plugins: In this live, we use pyln-testing Python package to write a test for a simple Core Lightning plugin written with pyln-client Python package. We do it in a TDD style.

• Learn how to subscribe to lightningd event notifications with CLN plugins: In the first part of this live we write a Python plugin without pyln-client package which subscribes to the notification topics connect and disconnect. A benefit of doing it like this is that it allows us to understand how the system works. Another benefit is that the way we write the plugin can be applied to any other languages. In the second part we do it again with Python but this time using pyln-client package.

• How Core Lightning plugins can communicate with each other?: In this live we implement a plugin that emits custom notifications foo to lightningd and another plugin which subscribes to those custom notifications foo. We do it with Python only and also with pyln-client package.

• Core lightning rpc_command hook, pay command and BOLT11 invoice: In this live we write a plugin that limits the amount a node can send (using the builtin pay command) to a BOLT11 invoice. This is possible thanks to Core Lightning hook system and specifically the hook rpc_command.

• How does Core Lightning communicate with the Bitcoin network?: In this live we install trustedcoin plugin that replaces bitcoind with trusted public explorers. Then we look at lightningd/bitcoind.c file which defines a standardized interface for talking and gathering Bitcoin data using any Bitcoin backend plugin. Finally, we see how trustedcoin uses public Esplora instances to implement the JSON-RPC method getrawblockbyheight.

• Start writing Core Lightning plugins with pyln-client TODAY!: In this episode, we register a JSON-RPC method in Core Lightning using pyln-client Python package.

• Overview of pyln-client implementation - Plugin.run() - Part 1: In this episode, we look a pyln-client Python package implementation focusing specifically on the method run of the class Plugin.

• Overview of pyln-client implementation - @plugin.method() - Part 2: In this episode, we look a pyln-client Python package implementation focusing specifically on the method method of the class Plugin. We write a very simplified version of Method and Plugin classes to understand plugin.method().

• Overview of pyln-client implementation - LightningRpc - Part 3: In this episode, we look a pyln-client Python package implementation focusing specifically on LightningRpc class. This class implements a RPC client for the lightningd daemon. This RPC client connects to the lightningd daemon through a unix domain socket and passes calls through.

• Understand CLN Plugin mechanism with a Bash example: In this live, we add the method mymethod to Core Lightning by writing a dynamic Bash plugin called myplugin.bash. Doing this, we try to understand: (1) how startup options are passed to the plugin, (2) how cli parameters are passed to the plugin and (3) how to communicate to the lightning node via JSON-RPC over unix sockets.

• Subscribe to lightningd notification topics with a Python plugin: In this episode we write a Python plugin without pyln-client package which subscribes to the notification topics connect and disconnect. A benefit of doing it like this is that it allows us to understand how the system works.

• Subscribe to connect notifications with pyln-client: In this episode we write a Python plugin with pyln-client package which subscribes to the notification topics connect and invoice_creation.

• Write a Core Lightning plugin in Javascript: In this episode, we write a Core Lightning plugin in Javascript that registers a JSON-RPC method. To do so we use clightningjs Javascript package.

• Write a Core Lightning plugin in Go: In this episode, we write a Core Lightning plugin in go that registers a JSON-RPC method. To do so we use lightningd-gjson-rpc Go module.

• Write a Core Lightning plugin in Rust: In this episode, we write a Core Lightning plugin in Rust that registers a JSON-RPC method. To do so we use cln-plugin and cln-rpc Rust crates.

• Getting started with CLNRest plugin: In this live we see how to start and use the new builtin plugin CLNRest that transforms RPC calls into a REST service. We learn how to use the Swagger interface to generate/send http requests. Then we connect to the websocket offered by CLNRest that sends lightningd notification. Finally, we take a look at CLNRest implementation to show how plugin developers can take advantage of the new JSON RPC method checkrune.

• Get started with cln-grpc plugin: In this live we continue our tour about Core Lightning remote control with the builtin plugin cln-grpc. We write a Python application which generates invoices on our CLN node using the gRPC protocol.

• A foo/bar CLN plugin example written with pyln-client!: A foo/bar CLN plugin example written with pyln-client!

• pyln-client uses Python decorators

• wait_for_log is what you're looking for!: You want to test your CLN plugin and have to wait for something to be written in the node's log before continuing. wait_for_log is what you're looking for!

• Do you want to be notified by lightningd each time you connect to a peer?

• custom notifications: With custom notifications, CLN plugins can communicate with each other! BOOM!!!

• Pizzas can be really expensive: rpc_command hook

• How to mess up your Core Lightning node with class: rpc_command hook