GlcoinCore/cln-plugins
1
0
Fork 0
mirror of https://github.com/lightningd/plugins.git synced 2026-08-13 12:33:19 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
cln-plugins/cl-zmq
History
Exact
dependabot[bot] e3fa7b0eb7 build(deps): bump cryptography from 48.0.1 to 50.0.0 in /cl-zmq 
Bumps [cryptography](https://github.com/pyca/cryptography) from 48.0.1 to 50.0.0.
- [Changelog](https://github.com/pyca/cryptography/blob/main/CHANGELOG.rst)
- [Commits](https://github.com/pyca/cryptography/compare/48.0.1...50.0.0)

---
updated-dependencies:
- dependency-name: cryptography
  dependency-version: 50.0.0
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-08-06 12:09:09 +02:00
..
cl-zmq.py cl-zmq: update shebang dependency versions 2026-05-12 22:29:00 +02:00
example-subscriber.py zmq: rename to cl-zmq for reckless 2025-12-06 10:39:40 +01:00
manifest.json cl-zmq: add reckless manifest 2026-07-24 15:18:49 +02:00
pyproject.toml build(deps): bump the all-dependencies group across 3 directories with 7 updates 2026-05-12 22:29:00 +02:00
README.md cl-zmq: add reckless manifest 2026-07-24 15:18:49 +02:00
test_zmq.py zmq: rename to cl-zmq for reckless 2025-12-06 10:39:40 +01:00
uv.lock build(deps): bump cryptography from 48.0.1 to 50.0.0 in /cl-zmq 2026-08-06 12:09:09 +02:00

README.md

ZeroMQ Publisher Plugin

This module forwards notifications to ZeroMQ endpoints depending on configuration.

The usage and setup mimics similar functionality in bitcoind for opting-in to notifications and selecting high water mark (ZMQ_HWM) preferences.

Installation

You need uv to run this plugin like a binary. After uv is installed you can simply run

lightning-cli plugin start /path/to/cl-zmq.py

If you use systemd to start CLN, you must have uv in the PATH that systemd uses, which is likely different than the PATH from your shell. Most uv installation methods install uv into your user's home directory (~/.local/bin or ~/.cargo/bin), which systemd cannot access.

You can either:

Option 1: Install uv system-wide (recommended):

curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR="/usr/local/bin" sh

Option 2: Copy your existing user installation:

sudo cp "$(command -v uv)" /usr/local/bin/uv

Option 3: Configure your systemd service to use a custom PATH (see systemd documentation).

To verify uv is accessible to systemd:

sudo systemd-run --user --wait command -v uv

This should output /usr/local/bin/uv.

For general plugin installation instructions see the repos main README.md

Usage

The plugin registeres CLI options for opting in to notifications at given endpoints. Eg running with:

 $ lightningd --zmq-pub-connect=ipc:///tmp/cl-zmq  \
              --zmq-pub-disconnect=tcp://127.0.0.1:5555

will publish connect and disconnect notifications to the specified endpoints. The default high water mark is 1000, which is the same as bitcoind's default.

This plugin does not interpret the content of the data, merely passes it on.

The ZMQ tag used for subscribing is the UTF-8 encoded string of the notification type name string. Eg. for the invoice_payment notification, the tag for subscribers will be b'invoice_payment'. The data published will be UTF-8 encoded JSON which comes from lightningd.

Example

example-subscriber.py is provided as an example subscriber to mirror the publishing code.

Tips and Tricks

  • The plugin subscribes to all notifications under in the NOTIFICATION_TYPE_NAMES regardless of whether they are connected to ZMQ endpoints via CLI launch. For avoiding that performance overhead, entries can be dropped from the list to avoid subscribing to them.
  • Unless there are changes to the plugin interfaces, notification types that are added in the future should be easy to include by adding the value to the NOTIFICATION_TYPE_NAMES list.