Core Lightning v23.08: "Satoshi's Successor" Part II - Developer Experience

This is the second blog post in a series detailing the changes to CLN in the new v23.08 release, codenamed Satoshi’s Successor (courtesy of Matt Morehouse). The first post covers the improvements we made to user experience, and in the third and final post, we will delve into the experimental features enabled by v23.08, so you can carry on that reckless Lightning spirit!

In this installment, we focus on the new features and enhancements for developers. We know you all have been asking for several things of CLN, and this release we delivered!  

REST API and Ancient Runes

CLN finally has an official REST API (web API, if you are a pedant) through a new plugin called clnrest, which is installed by default.  You will need some Python packages installed to make it work, but it will produce an informative message in the logs about why it cannot run if it does not have them. It’s already a superset of the clightning-rest plugin, which the Ride the Lightning project has supported for some time, but has some neat additions and will be kept up-to-date from now on. This is not surprising when you find out the author is Shahana Farooqui herself (of RTL fame) who has also promised to write a detailed guide to using this API!

Runes are also now first-class citizens. Runes are bearer credentials, introduced in our commando plugin for controlling a node via the Lightning Network itself. The rune says exactly what commands you are allowed to run, and have proven popular for other uses, so now the functionality has been moved into the core of CLN for other projects to share them. They have proven extremely useful, and now you do not even have to implement them yourself: you can use our createrune and checkrune commands to do all the heavy lifting. At this point I will simply quote from the manual:

Oh, I almost forgot. Runes can also be invoked like in ancient times with the invokerune command. Feel the magical powers of a rune by invoking it.

Pay Command Upgrades

There are two main developer enhancements to the pay command. The first is that we now allow self-payment, where we used to reject that as… well, self-serving. The second is a little more embarrassing: because Bolt11 can legally contain the hash of the description, with the actual description elsewhere, there’s been debate over whether nodes should be given the actual description. The spec (and our users, not to mention the folks in accounting) are fairly clear that we should know the description of the purpose of the payment for us to sign off on it, but a change in 2019 eliminated this requirement, and I did not notice until 2022! So back in April 2022 (v0.11), we deprecated paying invoices if you did not supply the description. But it turns out that a bug in our parsing of the description meant that you could not always pass the description into the pay command, so we have had to undeprecate that again for now!

Other Commands

Long-awaited, we have added the first steps to a general wait and pagination API. The wait command simply waits until an entry is created, updated, or deleted, and works reliably across node and plugin restarts! It pairs with a list command, which for the moment is only supported on listinvoices. So every invoice has two numbers: a created_index and an optional updated_index. These start at 1, and are unique, and only ever increase: if you call the wait invoices created 1 command it will return once your first invoice has been created.

Paired with this, you can call listinvoices and specify index as either created or updated. You can specify start to indicate what index to start at, and an optional limit. So if the wait above returns created : 5, you know to listinvoices index=created start=1 will show you all the new invoices you missed. As a helpful addition, the wait command itself often returns some information about the invoice (label, Bolt11, and status): this is particularly convenient to save a call to listinvoices, but is not present if you actually missed the change (perhaps your plugin was slow, or offline for a while), so you will need to call listinvoices sometimes anyway.

Future releases will extend this API to the other list commands, allowing you to easily and reliably wait for almost any Core Lightning event, such as on-chain transactions or payment results.

Finally, we have added initial support for user-defined tracing on Linux, which allows you to profile what happens on your node at various key points. It is extremely useful for developers to analyze performance in live systems without interfering, and we have documented the process for you to get started.

Join the CLN Community

We want to thank the contributors (31 for the v23.08 release) who continue to help us improve CLN with every update. We are grateful for your support; your dedication and feedback made the new release possible.

As always, let us know what you like or what we could improve by starting a thread on Build On L2, where we have special developer and node runner pages to help facilitate long-form discussions. It is free to sign up, and nyms are more than welcome!

You can also reach us on our usual social channels: Twitter, Telegram, or Discord.