Learn how to subscribe to lightningd event notifications with CLN plugins

Here is my setup:

◉ tony@tony:~/lnroom:
$ ./setup.sh
Ubuntu 22.04.2 LTS
Python 3.10.6
lightningd v23.02.2

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:

◉ tony@tony:~/clnlive:
$ 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
◉ tony@tony:~/clnlive:
$ start_ln
Bitcoin Core starting
awaiting bitcoind...
Making "default" bitcoind wallet.
[1] 108917
[2] 108952
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:

◉ tony@tony:~/clnlive:
$ alias l1-cli
alias l1-cli='lightning-cli --lightning-dir=/tmp/l1-regtest'

Instead of writing the plugin from scratch we use parts of the code we wrote during the first live which was about registering JSON-RPC methods to lightningd and understanding CLN plugin system.

This way we can focus on how to subscribe to notification topics and how to handle notifications.

So we start with the file myplugin.py containing the following:

#!/usr/bin/env python

import sys
import json

# getmanifest
request = sys.stdin.readline()
sys.stdin.readline() # "\n"
req_id = json.loads(request)["id"]

manifest = {
    "jsonrpc": "2.0",
    "id": req_id,
    "result": {
        "dynamic": True,
        "options": [],
        "rpcmethods": []
    }
}

sys.stdout.write(json.dumps(manifest))
sys.stdout.flush()

# init
request = sys.stdin.readline()
sys.stdin.readline() # "\n"
req_id = json.loads(request)["id"]

init = {
    "jsonrpc": "2.0",
    "id": req_id,
    "result": {}
}

sys.stdout.write(json.dumps(init))
sys.stdout.flush()

# io loop

for request in sys.stdin:
    sys.stdin.readline() # "\n"

In that script, we first receive the getmanifest request from lightningd in our stdin stream, we extract its id and we construct the getmanifest response (the plugin is dynamic, with no startup options and register no JSON-RPC methods) that we send back to lightningd by writing it to our stdout stream:

...
# getmanifest
request = sys.stdin.readline()
sys.stdin.readline() # "\n"
req_id = json.loads(request)["id"]

manifest = {
    "jsonrpc": "2.0",
    "id": req_id,
    "result": {
        "dynamic": True,
        "options": [],
        "rpcmethods": []
    }
}

sys.stdout.write(json.dumps(manifest))
sys.stdout.flush()
...

Then we handle the init request sent by lightningd in our stdin stream:

...
# init
request = sys.stdin.readline()
sys.stdin.readline() # "\n"
req_id = json.loads(request)["id"]

init = {
    "jsonrpc": "2.0",
    "id": req_id,
    "result": {}
}

sys.stdout.write(json.dumps(init))
sys.stdout.flush()
...

And finally we start an I/O loop waiting for incoming request from lightningd:

...
# io loop

for request in sys.stdin:
    sys.stdin.readline() # "\n"

Let's subscribe to connect notification topic by adding it to the array subscriptions part of the result field of the getmanifest response:

...
manifest = {
    "jsonrpc": "2.0",
    "id": req_id,
    "result": {
        "dynamic": True,
        "options": [],
        "rpcmethods": [],
        "subscriptions": ["connect"]
    }
}
...

And when we'll receive notifications for that topic, we'll write them into the file /tmp/myplugin like this:

for request in sys.stdin:
    sys.stdin.readline() # "\n"

    with open("/tmp/myplugin", "a") as myplugin:
        myplugin.write("connect notification: " + request + "\n")

Note that we don't need to write any logic for now because the only notifications we'll ever receive from lightningd are for connect topic (due to our getmanifest response).

Note also that since we are handling notifications, we don't send any responses to lightningd unlike what we did before with getmanifest and init requests.

In our terminal now we can start our plugin and connect l1 and l2 nodes using connect command provided by lightning/contrib/startup_regtest.sh script:

$ l1-cli plugin start $(pwd)/myplugin.py
{
   "command": "start",
   "plugins": [
      {
         "name": "/usr/local/libexec/c-lightning/plugins/autoclean",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/chanbackup",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/bcli",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/commando",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/funder",
         "active": true,
         "dynamic": true
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/topology",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/keysend",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/offers",
         "active": true,
         "dynamic": true
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/pay",
         "active": true,
         "dynamic": true
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/txprepare",
         "active": true,
         "dynamic": true
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/spenderp",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/sql",
         "active": true,
         "dynamic": true
      },
      {
         "name": "/usr/local/libexec/c-lightning/plugins/bookkeeper",
         "active": true,
         "dynamic": false
      },
      {
         "name": "/home/tony/clnlive/myplugin.py",
         "active": true,
         "dynamic": true
      }
   ]
}
◉ tony@tony:~/clnlive:
$ connect 1 2
{
   "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}

As the node l1 is running myplugin plugin which subscribes to connect notification topic and write them to the file /tmp/plugin each time l1 connects to another node, and that l1 has just connected to l2, the file /tmp/plugin contains the following connect notification:

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

We can prettify that notification like this:

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

Note that the request from lightningd being a notification has no id.

With that done, now we know how to subscribe to a notification topic in Core Lightning.

To summarize, in the getmanifest response we add the notification topics we want to subscribe too in the array subscriptions of the params field, then each time we receive a notification for one of those topics we handle them without relpying back to lightningd.

Let's subscribe to disconnect notification topic by adding it to the array subscriptions part of the result field of the getmanifest response:

...
manifest = {
    "jsonrpc": "2.0",
    "id": req_id,
    "result": {
        "dynamic": True,
        "options": [],
        "rpcmethods": [],
        "subscriptions": ["connect", "disconnect"]
    }
}
...

Now we add some logic in the I/O loop to dispatch on the notification topics. To do this we extract the method (the notification topic) of the notification we receive from lightningd and we dispatch on it like this:

for request in sys.stdin:
    sys.stdin.readline() # "\n"

    method = json.loads(request)["method"]
    if method == "connect":
        with open("/tmp/myplugin", "a") as myplugin:
            myplugin.write("connect notification: " + request + "\n")

    if method == "disconnect":
        with open("/tmp/myplugin", "a") as myplugin:
            myplugin.write("disconnect notification: " + request + "\n")

In our terminal, first we disconnect the nodes l1 and l2

◉ tony@tony:~/clnlive:
$ l1-cli disconnect 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
{}

then we restart the plugin

◉ tony@tony:~/clnlive:
$ l1-cli plugin start $(pwd)/myplugin.py
{
   "command": "start",
   "plugins": [...]
}

Note that since the checksum of our plugin script as change, using start subcommand of plugin command stops myplugin.py plugin that was running and restart it with the new modifications.

Then we connect again both nodes and disconnect them immediately:

◉ tony@tony:~/clnlive:
$ connect 1 2
{
   "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}

The plugin myplugin.py has been notified twice: once for connect notification topic and once for disconnect notification topic.

Therefore, the file /tmp/myplugin is now:

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

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

disconnect notification: {"jsonrpc":"2.0","method":"disconnect","params":{"id":"0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf"}}

We are done for that first part.

Let's stop the node l1, install pyln-client in .venv python environment and restart it after activating .venv environment:

◉ tony@tony:~/clnlive:
$ l1-cli stop
"Shutdown complete"
[1]-  Done                    test -f "/tmp/l$i-$network/lightningd-$network.pid" || $EATMYDATA "$LIGHTNINGD" "--lightning-dir=/tmp/l$i-$network"
◉ tony@tony:~/clnlive:
$ python -m venv .venv
◉ tony@tony:~/clnlive:
$ source .venv/bin/activate
(.venv) ◉ tony@tony:~/clnlive:
$ pip install pyln-client
...
(.venv) ◉ tony@tony:~/clnlive:
$ lightningd --lightning-dir=/tmp/l1-regtest --daemon

In the file myplugin-pyln.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 notification received from lightningd. In our case we write the id of the node we connect too 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):
    with open("/tmp/myplugin-pyln", "a") as myplugin:
        myplugin.write("connect notification: " + id + "\n")

plugin.run()

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

(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli plugin start $(pwd)/myplugin-pyln.py
{
   "command": "start",
   "plugins": [...]
}
(.venv) ◉ tony@tony:~/clnlive:
$ connect 1 2
{
   "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}

We check that the file /tmp/plugin-pyln contains

connect notification: 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf

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

Let's modify our plugin to return the params object of the connect notification:

#!/usr/bin/env python

from pyln.client import Plugin
import json

plugin = Plugin()

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

plugin.run()

Note how pyln-client passes the argument to connect_func. Each first fields in the params object of a notification request like the following connect request

{
  "jsonrpc": "2.0",
  "method": "connect",
  "params": {
    "id": "...",
    "direction": "...",
    "address": {...}
  }
}

are bound to their value and pass as argument to the function (connect_func in our case) defined below @plugin.subscribe("...").

Back to our terminal, we disconnect the nodes, restart the plugin and connect them again:

(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli disconnect 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
{}
(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli plugin start $(pwd)/myplugin-pyln.py
{
   "command": "start",
   "plugins": [...]
}
(.venv) ◉ tony@tony:~/clnlive:
$ connect 1 2
{
   "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}

The file /tmp/plugin-pyln is now:

connect notification: 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
connect notification: {"id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}

It is easier to debug our code when we have access to the traceback. And pyln-client makes it easy by logging in the node's log the Traceback when an error is caught during the notification handling.

Let's see that by introducing a type error in our plugin like this:

#!/usr/bin/env python

from pyln.client import Plugin
import json

plugin = Plugin()

@plugin.subscribe("connect")
def connect_func(plugin, id, direction, address , **kwargs):
    1 + "foo"

plugin.run()

Back to our terminal, we disconnect the nodes, restart the plugin and connect them again:

(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli disconnect 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
{}
(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli plugin start $(pwd)/myplugin-pyln.py
{
   "command": "start",
   "plugins": [...]
}
(.venv) ◉ tony@tony:~/clnlive:
$ connect 1 2
{
   "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}

If we were running a plugin that return an error due to the expression 1 + "foo", lightningd would have killed the plugin. But, pyln-client caches errors and logs them in the node's log. And so the plugin is not killed by lightningd as we can see looking for its process:

(.venv) ◉ tony@tony:~/clnlive:
$ ps -ax | rg myplugin
1207796 ?        S      0:00 python /home/tony/clnlive/myplugin-pyln.py
1207907 pts/0    S+     0:00 rg myplugin

And we can read the traceback in the log file /tmp/l1-regtest/log:

2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py: Traceback (most recent call last):
2023-05-11T14:41:22.629Z DEBUG   0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf-connectd: peer_out WIRE_GOSSIP_TIMESTAMP_FILTER
2023-05-11T14:41:22.629Z DEBUG   0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf-gossipd: seeker: starting gossip
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py:   File \"/home/tony/clnlive/.venv/lib/python3.10/site-packages/pyln/client/plugin.py\", line 668, in _dispatch_notification
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py:     self._exec_func(func, request)
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py:   File \"/home/tony/clnlive/.venv/lib/python3.10/site-packages/pyln/client/plugin.py\", line 619, in _exec_func
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py:     ret = func(*ba.args, **ba.kwargs)
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py:   File \"/home/tony/clnlive/myplugin-pyln.py\", line 10, in connect_func
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py:     1 + \"foo\"
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py: TypeError: unsupported operand type(s) for +: 'int' and 'str'
2023-05-11T14:41:22.629Z INFO    plugin-myplugin-pyln.py:

Let's modify our plugin to subscribe to disconnect 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):
    notif = {
        "id": id,
        "direction": direction,
        "address": address
    }
    with open("/tmp/myplugin-pyln", "a") as myplugin:
        myplugin.write("connect notification: " + json.dumps(notif) + "\n")

@plugin.subscribe("disconnect")
def disconnect_func(plugin, id, **kwargs):
    with open("/tmp/myplugin-pyln", "a") as myplugin:
        myplugin.write("disconnect notification: " + id + "\n")

plugin.run()

Back to our terminal, we disconnect the nodes, restart the plugin, connect them again and disconnect them immediately:

(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli disconnect 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
{}
(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli plugin start $(pwd)/myplugin-pyln.py
{
   "command": "start",
   "plugins": [...]
}
(.venv) ◉ tony@tony:~/clnlive:
$ connect 1 2
{
   "id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}
(.venv) ◉ tony@tony:~/clnlive:
$ l1-cli disconnect 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
{}

The file /tmp/plugin-pyln is now:

connect notification: 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
connect notification: {"id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}
connect notification: {"id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}
disconnect notification: 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf

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):
    notif = {
        "id": id,
        "direction": direction,
        "address": address
    }
    with open("/tmp/myplugin-pyln", "a") as myplugin:
        myplugin.write("connect notification: " + json.dumps(notif) + "\n")

@plugin.subscribe("disconnect")
def disconnect_func(plugin, id, **kwargs):
    with open("/tmp/myplugin-pyln", "a") as myplugin:
        myplugin.write("disconnect notification: " + id + "\n")

@plugin.subscribe("invoice_creation")
def invoice_creation_func(plugin, invoice_creation, **kwargs):
    with open("/tmp/myplugin-pyln", "a") as myplugin:
        myplugin.write("invoice_creation notification: " +
                       json.dumps(invoice_creation) + "\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:~/clnlive:
$ l1-cli invoice 0.001btc inv pizza
{
   "payment_hash": "cdc9e18d9bd7e8c9206f8a1ed085b433ee52c4f669fe2b769b249ea792fb13d0",
   "expires_at": 1684421489,
   "bolt11": "lnbcrt1m1pj96q83sp59lafyq9v75389rf7vw9naa98wgcjclqlhm0uv078x6x2dl55l3kqpp5ehy7rrvm6l5vjgr03g0dppd5x0h9938kd8lzka5myj020yhmz0gqdqgwp5h57npxqyjw5qcqp29qyysgqnj9sv2jnkvt8ggjwhtz66gqhgakpdux5addva5zpm2u86q7a60rzn8ravhg9wrfkum80sevcpr82gxqs3j7a9nmrwrx4scsdha6jnssq0hs8he",
   "payment_secret": "2ffa9200acf522728d3e638b3ef4a772312c7c1fbedfc63fc7368ca6fe94fc6c",
   "warning_capacity": "Insufficient incoming channel capacity to pay invoice"
}

The file /tmp/plugin-pyln is now:

connect notification: 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
connect notification: {"id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}
connect notification: {"id": "0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf", "direction": "out", "address": {"type": "ipv4", "address": "127.0.0.1", "port": 7272}}
disconnect notification: 0271aecf3075ce72f2df479b60fc1db98d4d780c66fa495013614054554e1bb2bf
invoice_creation notification: {"msat": "100000000msat", "preimage": "88042f007f02283571abbc40aca8b4302643415e85c71413177ef139b4276970", "label": "inv"}

In the directory tests/plugins of lightning repository we can find more examples of subscription to notification topics:

◉ tony@tony:~/clnlive/lightning/tests/plugins:[git»(HEAD detached at v23.02.2)]
$ rg '@plugin\.subscribe'
misc_notifications.py
17:@plugin.subscribe("channel_opened")
25:@plugin.subscribe("channel_state_changed")
30:@plugin.subscribe("shutdown")

pretend_badlog.py
14:@plugin.subscribe("warning")

forward_payment_status.py
14:@plugin.subscribe("forward_event")

block_added.py
11:@plugin.subscribe("block_added")

coin_movements.py
12:@plugin.subscribe("coin_movement")

sendpay_notifications.py
15:@plugin.subscribe("sendpay_success")
21:@plugin.subscribe("sendpay_failure")

balance_snaps.py
12:@plugin.subscribe("balance_snapshot")

custom_notifications.py
8:@plugin.subscribe("custom")
27:@plugin.subscribe("pay_success")
37:@plugin.subscribe("ididntannouncethis")

How does connect_func get called when the connect notification is received?

{
 'connect': <function connect_func at 0x7f801af9be20>,
 'disconnect': <function disconnect_func at 0x7f801afc0dc0>,
 'invoice_creation': <function invoice_creation_func at 0x7f801afc1870>
}

class Plugin(object):
    ...
    def run(self) -> None:
        # If we are not running inside lightningd we'll print usage
        # and some information about the plugin.
        if os.environ.get('LIGHTNINGD_PLUGIN', None) != '1':
            return self.print_usage()

        partial = b""
        for l in self.stdin.buffer:
            partial += l

            msgs = partial.split(b'\n\n')
            if len(msgs) < 2:
                continue

            partial = self._multi_dispatch(msgs)

class Plugin(object):
    ...
    def _multi_dispatch(self, msgs: List[bytes]) -> bytes:
        """We received a couple of messages, now try to dispatch them all.

        Returns the last partial message that was not complete yet.
        """
        for payload in msgs[:-1]:
            # Note that we use function annotations to do Millisatoshi
            # conversions in _exec_func, so we don't use LightningJSONDecoder
            # here.
            request = self._parse_request(json.loads(payload.decode('utf8')))

            # If this has an 'id'-field, it's a request and returns a
            # result. Otherwise it's a notification and it doesn't
            # return anything.
            if request.id is not None:
                self._dispatch_request(request)
            else:
                self._dispatch_notification(request)

        return msgs[-1]

class Plugin(object):
    ...
    def _dispatch_notification(self, request: Request) -> None:
        if request.method not in self.subscriptions:
            raise ValueError("No subscription for {name} found.".format(
                name=request.method))
        func = self.subscriptions[request.method]

        try:
            self._exec_func(func, request)
        except Exception:
            self.log(traceback.format_exc())