Ok, you're ready to start building extra functionality into your Core Lightning node. The place to do that is Core Lighting Plugins. This post shows you how to set up a new plugin and get it working on your LNPlay CLN instance. The purpose of this basic plugin is to expose ONE RPC method htmx-getinfo that returns an HTMX snippet to the caller. Later, we use this RPC method to interact with the front-end widget.

Repo

First, create a Github repo for your new CLN plugin. The example in this post uses this repo. Your CLN node will pull the latest changes from the repo and load the associated CLN plugin.

htmx-getinfo

To help developers get started with plugin development, we developed a very simple CLN plugin template called htmx-getinfo to help people get started. This plugin has one RPC method: htmx-getinfo that when called, returns the output of the getinfo command but formatted for HTMX instead of JSON.

#!/usr/bin/env python3

from pyln.client import Plugin, RpcError

plugin = Plugin()

@plugin.init()  # this runs when the plugin starts.
def init(options, configuration, plugin, **kwargs):
    plugin.log("cln-htmx-getinfo boilerplate.")

@plugin.method("htmx-getinfo")
def htmx_getinfo(plugin):
    '''
    Returns the getinfo output as HTMX.
    '''

    get_info_response = plugin.rpc.getinfo()
    node_id = get_info_response["id"]
    node_color = get_info_response["color"]
    node_alias = get_info_response["alias"]
    block_height = get_info_response["blockheight"]

    html_content = f"<table><tr><th>Field</th><th>Value</th></tr><tr><td>Node ID:</td><td>{node_id}</td></tr><td>Alias</td><td>{node_alias}</td></tr><tr><td>Color</td><td>{node_color}</td></tr><tr><td>Block Height</td><td>{block_height}</td></tr></table>"

    return html_content

plugin.run()  # Run our plugin

Reckless

Reckless is a plugin manager for Core-Lightning. It manages the plugin lifecycle. Reckless is a python script that allows you to add and active new Core Lightning plugins on your node.

Reckless-Wrapper

To expose the reckless shell script to REST endpoint users, we created cln-reckless-wrapper. The plugin creates new RPC methods on each CLN node, allowing developers to add and update plugins to their node.

Using reckless-wrapper

Generally the first step you will take is running reckless-sourcelist. This returns a list of all the repos reckless is currently managing.

 ./lightning-cli reckless-sourcelist 

The output should list the Core Lightning public plugins repo by default:

{
   "sources": [
      "https://github.com/lightningd/plugins"
   ]
}

Add your plugin repo to reckless

To add your own CLN Plugin repo, you can run reckless-sourceadd. The example below adds a very basic plugin (discussed later).

 ./lightning-cli reckless-sourceadd -k repo_url=https://github.com/jrman28/cln-htmx-getinfo

Now run reckless-sourcelist again, your plugin repo should be listed:

{
   "sources": [
      "https://github.com/lightningd/plugins",
      "https://github.com/jrman28/cln-htmx-getinfo"
   ]
}

Install the plugin

To install your plugin and all its dependencies, run the following command, for example:

 ./lightning-cli reckless-install -k plugin_name=cln-htmx-getinfo

This downloads the plugin software to your core lightning node. It also activates the plugin by default. Here's some example output:

{
   "install_messages": [
      "Collecting pyln-client",
      "  Downloading asn1crypto-1.5.1-py2.py3-none-any.whl (105 kB)",
      "Collecting pycparser",
      "  Downloading pycparser-2.21-py2.py3-none-any.whl (118 kB)",
      "...",
      "dependencies installed successfully",
      "plugin installed: /reckless-plugins/cln-htmx-getinfo",
      "cln-htmx-getinfo enabled"
   ]
}

Verify your plugin

To verify that your plugin was activated successful, run the following command:

./lightning-cli plugin -k subcommand="list"

You see something like:

{
   "command": "list",
   "plugins": [
      ...
      {
         "name": "/reckless-plugins/cln-htmx-getinfo/cln-htmx-getinfo.py",
         "active": true,
         "dynamic": true
      }
   ]
}

Update your plugin

Need to push some updates to your LNPLay instance? Just run uninstall and install.

./lightning-cli reckless-uninstall -k plugin_name=cln-htmx-getinfo
./lightning-cli reckless-install -k plugin_name=cln-htmx-getinfo