Subscribe to connect notifications with pyln-client

connect notifications are JSON-RPC requests we receive (if we've subscribed to) from lightningd each time we connect to another peer. They have no id field and its params field contains the information about the node we just connected to. Here is an example:

{
  "jsonrpc": "2.0",
  "method": "connect",
  "params": {
    "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
    "direction": "out",
    "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
    }
  }
}

invoice_creation notifications are JSON-RPC requests we receive (if we've subscribed to) from lightningd each time we create an invoice. They have no id field and the params field contains the invoice details. Here is an example:

{
  "jsonrpc": "2.0",
  "method": "invoice_creation",
  "params": {
    "invoice_creation": {
      "msat": "100000000msat",
      "preimage": "88042f007f02283571abbc40aca8b4302643415e85c71413177ef139b4276970",
      "label": "inv"
    }
  }
}

When the plugin is started, it receives a getmanifest request from lightningd like this one

{
  "jsonrpc": "2.0",
  "id": 187,
  "method": "getmanifest",
  "params": {
    "allow-deprecated-apis": false
  }
}

and if the plugin wants to subscribe to connect and invoice_creation notifications topics, it just have to reply to that request with a response that sets the subscriptions field of the result member to the array ["connect", "invoice_creation"] like this:

{
  "jsonrpc": "2.0",
  "id": 187,
  "result": {
    "dynamic": True,
    "options": [],
    "rpcmethods": [],
    "subscriptions": ["connect", "invoice_creation"]
  }
}

This is what we are going to do with pyln-client Python package.

Let's install pyln-client in .venv Python virtual environment:

◉ tony@tony:~/lnroom:
$ python -m venv .venv
◉ tony@tony:~/lnroom:
$ source .venv/bin/activate
(.venv) ◉ tony@tony:~/lnroom:
$ pip install pyln-client
...

Our setup for this episode is:

(.venv) ◉ tony@tony:~/lnroom:
$ ./setup.sh
Ubuntu 22.04.2 LTS
Python 3.10.6
lightningd v23.02.2
pyln-client  23.5

Let's start two Lightning nodes running on the Bitcoin regtest chain by sourcing the script lightning/contrib/startup_regtest.sh provided in CLN repository and by running the command start_ln:

(.venv) ◉ tony@tony:~/lnroom:
$ source lightning/contrib/startup_regtest.sh
lightning-cli is /usr/local/bin/lightning-cli
lightningd is /usr/local/bin/lightningd
Useful commands:
  start_ln 3: start three nodes, l1, l2, l3
  connect 1 2: connect l1 and l2
  fund_nodes: connect all nodes with channels, in a row
  stop_ln: shutdown
  destroy_ln: remove ln directories
(.venv) ◉ tony@tony:~/lnroom:
$ start_ln
Bitcoin Core starting
awaiting bitcoind...
Making "default" bitcoind wallet.
[1] 1460972
[2] 1461006
WARNING: eatmydata not found: instal it for faster testing
Commands:
        l1-cli, l1-log,
        l2-cli, l2-log,
        bt-cli, stop_ln, fund_nodes

We can check that l1-cli is just an alias for lightning-cli with the base directory being /tmp/l1-regtest:

(.venv) ◉ tony@tony:~/lnroom:
$ alias l1-cli
alias l1-cli='lightning-cli --lightning-dir=/tmp/l1-regtest'

In the file myplugin.py we have a working plugin written with pyln-client (thought it does nothing so far):

#!/usr/bin/env python

from pyln.client import Plugin
import json

plugin = Plugin()

plugin.run()

We use the line @plugin.subscribe("connect") to tell pyln-client that we want to subscribe to connect notification topic. And the function defined after that line will be used to handle connect notifications received from lightningd. In our case we write the params of the connect notification (which are the function arguments id, direction and address) that we receive in the file /tmp/plugin:

So our plugin is now:

#!/usr/bin/env python

from pyln.client import Plugin
import json

plugin = Plugin()

@plugin.subscribe("connect")
def connect_func(plugin,id, direction, address, **kwargs):
    params = {
        "id": id,
        "direction": direction,
        "address": address
    }
    with open("/tmp/myplugin", "a") as myplugin:
        myplugin.write("connect params: " + json.dumps(params) + "\n")

plugin.run()

Let's start our pyln-client plugin and connect the node l1 and l2:

(.venv) ◉ tony@tony:~/lnroom:
$ l1-cli plugin start $(pwd)/myplugin.py
{
   "command": "start",
   "plugins": [...]
}
(.venv) ◉ tony@tony:~/lnroom:
$ l2-cli -F getinfo | rg 'id|binding'
id=039b780a84d36584ac0d7c84d10a962a1c5b35d2775650454c2a843368970932b0
binding[0].type=ipv4
binding[0].address=127.0.0.1
binding[0].port=7272
(.venv) ◉ tony@tony:~/lnroom:
$ l1-cli connect 039b780a84d36584ac0d7c84d10a962a1c5b35d2775650454c2a843368970932b0@127.0.0.1:7272
{
   "id": "039b780a84d36584ac0d7c84d10a962a1c5b35d2775650454c2a843368970932b0",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}

We check that the file /tmp/plugin contains

connect params: {"id": "039b780a84d36584ac0d7c84d10a962a1c5b35d2775650454c2a843368970932b0", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}

indicating that we've successfully subscribed to connect notification topic.

Let's modify our plugin to subscribe to invoice_creation notification topic:

#!/usr/bin/env python

from pyln.client import Plugin
import json

plugin = Plugin()

@plugin.subscribe("connect")
def connect_func(plugin,id, direction, address, **kwargs):
    params = {
        "id": id,
        "direction": direction,
        "address": address
    }
    with open("/tmp/myplugin", "a") as myplugin:
        myplugin.write("connect params: " + json.dumps(params) + "\n")

@plugin.subscribe("invoice_creation")
def invoice_creation_func(plugin, invoice_creation, **kwargs):
    params = {
        "invoice_creation": invoice_creation
    }
    with open("/tmp/myplugin", "a") as myplugin:
        myplugin.write("invoice_creation params: " + json.dumps(params) + "\n")

plugin.run()

Back to our terminal, we restart the plugin and create an invoice with the node l1:

(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli plugin start $(pwd)/myplugin-pyln.py
{
   "command": "start",
   "plugins": [...]
}
(.venv) ◉ tony@tony:~/lnroom:
$ l1-cli invoice 0.001btc inv pizza
{
   "payment_hash": "fde8a7df1924d00e96312d765117088d97bd1886b310b14a93a342902f6a7482",
   "expires_at": 1684848791,
   "bolt11": "lnbcrt1m1pjx8pshsp5wx6c04s24ak9yj2f90ph4j7wlsu460x0xqt5e6d2sgknh6u23skqpp5lh520hceyngqa93394m9z9cg3ktm6xyxkvgtzj5n5dpfqtm2wjpqdqgwp5h57npxqyjw5qcqp29qyysgq3ewslg3tc38uexd0dy7mm5nqzhml85sap777scpynudjvxkamkv5srr343y8uvzsyjy4lc0ff3t3uxgxly0l4msyr9yk5kskuplqewspglvvs9",
   "payment_secret": "71b587d60aaf6c5249492bc37acbcefc395d3ccf30174ce9aa822d3beb8a8c2c",
   "warning_capacity": "Insufficient incoming channel capacity to pay invoice"
}

The file /tmp/plugin is now:

connect params: {"id": "039b780a84d36584ac0d7c84d10a962a1c5b35d2775650454c2a843368970932b0", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}
invoice_creation params: {"invoice_creation": {"msat": "100000000msat", "preimage": "4ec62babb7d48f494d9945cdfdbd942f387467da6b804d84c0428b49bbdf0844", "label": "inv"}}

We are done!

#!/usr/bin/env python

from pyln.client import Plugin
import json

plugin = Plugin()

@plugin.subscribe("connect")
def connect_func(plugin,id, direction, address, **kwargs):
    params = {
        "id": id,
        "direction": direction,
        "address": address
    }
    with open("/tmp/myplugin", "a") as myplugin:
        myplugin.write("connect params: " + json.dumps(params) + "\n")

@plugin.subscribe("invoice_creation")
def invoice_creation_func(plugin, invoice_creation, **kwargs):
    params = {
        "invoice_creation": invoice_creation
    }
    with open("/tmp/myplugin", "a") as myplugin:
        myplugin.write("invoice_creation params: " + json.dumps(params) + "\n")

plugin.run()

#!/usr/bin/env bash

ubuntu=$(lsb_release -ds)
lightningd=$(lightningd --version | xargs printf "lightningd %s\n")
python=$(python --version)
pyln_client=$(pip list | rg pyln-client)

printf "%s\n%s\n%s\n%s\n" "$ubuntu" "$python" "$lightningd" "$pyln_client"

{
  "jsonrpc": "2.0",
  "method": "connect",
  "params": {
    "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
    "direction": "out",
    "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "invoice_creation",
  "params": {
    "invoice_creation": {
      "msat": "100000000msat",
      "preimage": "88042f007f02283571abbc40aca8b4302643415e85c71413177ef139b4276970",
      "label": "inv"
    }
  }
}

connect params: {"id": "039b780a84d36584ac0d7c84d10a962a1c5b35d2775650454c2a843368970932b0", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}
invoice_creation params: {"invoice_creation": {"msat": "100000000msat", "preimage": "4ec62babb7d48f494d9945cdfdbd942f387467da6b804d84c0428b49bbdf0844", "label": "inv"}}