What is Coffee? and Why do we need it?

The Coffee plugin manager facilitates the use of the Core Lightning plugin architecture for both users and developers. It offers assistance to them while working with Core Lightning.

Problems

Core lightning has a very powerful plugin system that empowers everyone to write a plugin for core lightning to extend the functionality of it.

In fact, currently, we have many ways to write a plugin in core lightning with different languages, like Rust, Go, Java, Kotlin, Scala, Dart, Python and many others. This can lead to disarray in the community, as the user now has to follow a different procedure for installing a plugin and building it.

Despite allowing all users to write plugins in their own way, this can have a detrimental effect in fragmenting the ecosystem.

Solution

We are offering Coffee as a solution to help install and develop a plugin for Core Lightning, similar to how Cargo is used for Rust.

In fact, Coffee is implemented to be a modular plugin manager and supports all the user needs.

Currently, with Coffee it is possible to install a plugin from a GitHub repository and allow the user to manage it.

In fact, you can install a Java plugin that supports Coffee in a couple of commands after you install it

coffee --network testnet link /home/alice/.lightning
coffee --network testnet remote add lightningd https://github.com/lightningd/plugins.git
coffee --network testnet install btcli4j

Ideas

The idea that we have for Coffee is to be the de facto tool to install and build a plugin in Core Lightning, so we are planning to release it in different way, such as:

as a command line tool: empower the developers and the Linux hackers to play with Coffee from command line;
as a web server: empower the web and mobile applications to manage Core Lightning;
as a plugin: empower current systems like gRPC and REST to interact with with Coffee through the Core Lightning RPC commands.

Contribute

To empower everyone, we need the help and the vision of everyone, so if you want to contribute with ideas please submit an issue or if you want to contribute please read our hacking guide

In addition, consider subscribing to our mailing list

Install Coffee

Binary Installation

You can install coffee as a binary tool, but for now you need to install also Rust on your system.

When you had Rust up and running, to install Coffee you need just to do

git clone https://github.com/coffee-tools/coffee.git && cd coffee
make install
coffee --help

You can also install coffee_httpd binary to run coffee as a server. run:

cargo install --bin coffee_httpd

Using Coffee

Coffee is a plugin manager and development tool for core lightning nodes. It helps automate configuration and installation of plugins, and provides plugin templates for all the official languages.

Coffee is a command line utility that provides access to a wide range of tasks.

First Configuration

Coffee is able to manage the configuration of your core lightning and all the plugins connected with it, so in order to use Coffee, the user needs to point Coffee to the current root of core lightning.

By default the Core Lightning home is stored in the /home/<user>/.lightning, and you can do it with the following command

coffee link /home/alice/.lightning

If you want to unlink coffee from Core Lightning configuration at any time, you can do it with the following command

coffee unlink /home/alice/.lightning

Then you will find an include at the end of the config file at /home/alice/.lightning/bitcoin/config, in case this config file do not exist Coffee will create it.

include /home/alice/.coffee/testnet/coffee.conf

In addition there are the following additional option that you can specify:

--network: by default set to bitcoin, but if you want to specify the network that Core Lightning is using, you must ensure that the flag is set to the correct network.
--data-dir: by default set to /home/alice/.coffee, you may want to set this option if you are looking to specify a different directory for the Coffee home.
--skip-verify: Use this option to bypass coffee's validation process, which checks for conflicts between its configuration and the local storage.

Add a Plugin Repository

Coffee ensures a high-functioning and secure core by allowing users to select repositories from which to download plugins, and then authorizing the installation of only the desired plugins.

To add a plugin repository, simply run the following command.

coffee remote add <repository_name> <repository_url>

To remove a plugin repository, simply run the following command.

coffee remote rm <repository_name>

To list plugin repositories, simply run the following command.

coffee remote list

To list available plugins in a specific remote repository

coffee remote inspect <repository_name>

Install a Plugin

Congratulations! After adding a repository, Coffee will catalogue it, allowing you to explore all the plugins that can be installed via the CLI. Coffee offers multiple installation strategies that you can select based on your preferences, such as:

Dynamic installation

To install a plugin dynamically, you simply need to run.

coffee install -d <plugin_name>

Static installation

To install a plugin statically, you simply need to run.

coffee install <plugin_name>

Removing a Plugin

To remove an installed plugin, you simply have to run the following command.

coffee remove <plugin_name>

Disabling a Plugin

Disabling a plugin means that the plugin will not be loaded with CLN but it will still be installed and can be enabled at any time.

To disable a plugin, run:

coffee disable <plugin_name>

Enabling a Plugin

To enable a plugin, run:

coffee enable <plugin_name>

Upgrade a Plugin

Coffee tightly integrates with git, allowing you to easily upgrade your plugins through the command line interface (CLI). This eliminates the need for tedious tasks such as downloading the latest updates and creating new versions of plugins. To upgrade a plugin, all you need to do is run.

coffee upgrade <repo_name>

Listing all the plugins

coffee list

Showing the README file of the plugin

coffee show <plugin_name>

Searching for a plugin in remote repositories

coffee search <plugin_name>

To solve issues with coffee configuration and ensure its integrity on disk

coffee nurse

Additionally, if you wish to perform a verification of coffee without making any changes, you can use the --verify flag:

coffee nurse --verify

Tipping a plugin in Bitcoin

coffee tip <plugin_name> <millisatoshi>

Running coffee as a server

To run Coffee as a server, you can use the coffee_httpd binary.

Please note that the server runs on localhost with port 8080 where you can find a Swagger API documentation with all the available endpoints.

Starting the Coffee Server

To start the Coffee server, run the following command:

coffee_httpd --cln-path <core_lightning_path> --network <network>

Make sure the coffee_httpd binary is in your system PATH or in the current working directory.

How to support?

Core Lightning support many different ways to write a plugin, and if this is bad or good will not be discussed in this section. However, we must have a way to install automatically all the plugins that the ecosystem supports.

With Coffee, we choose to give this freedom to the developers of the plugin, in fact, coffee uses a manifest where it is possible to specify the install script and the runnable file/binary file.

Add a Manifest file

The coffee manifest is a yaml file with the name coffee.yml or coffee.yaml, where it is possible specify the install script an other meta information.

Coffee will heavily search this file in the root directory of the plugin, and it is not so different from what the other languages like nodejs, go, rust does.

An example of the coffee manifest that will install a Kotlin plugin is the following one:

---
plugin:
  name: btcli4j
  version: 0.0.1
  lang: java
  install: |
    sh -C ./gradlew createRunnableScript
  main: btcli4j-gen.sh

Where it is possible to specify the following options:

name: the official name of the plugin, that Coffee will referer to during the installation process;
version: the version of the plugin, that currently is not used;
lang: the language of the plugin, used to try to install a plugin when the install script is not specified;
install: a custom install script used by Coffee to compile the plugin;
main: the binary or runnable file that core lightning needs to run.
important: bool flag for plugins that must be run as important-plugin

In the future, the coffee will be also able to install binary other than a plugin, so coffee will be installed with coffee itself. With some craziness will be also possible to manage core lightning itself.

Please if you feel that additional meta information needs to be specified open an issue https://github.com/coffee-tools/coffee/issues

Tipping

While there are possibility to tipping anything on lightning, there is any solution to tipping a core lightning plugin developer. So with coffee as developer you can define a BOLT 12 invoice that allow the developer of the plugin to receive tips. So, the developer of the plugin should define a coffee manifest that specify the tipping info.

An example can be:

---
plugin:
  name: btcli4j
  version: 0.0.1
  lang: java
  install: |
    sh -C ./gradlew createRunnableScript
  main: btcli4j-gen.sh
tipping: 
  bolt12: <bolt12 invoice>

Contributing to Coffee

Table of Content

Introduction
Code Style
Commit Style
How to make the release

Introduction

Welcome to the HACKING guide and let's peek into how a day in the life of a Coffee plugin manager maintainer looks like.

After reading this, you should be prepared to contribute to the repository and be a potential maintainer in the future if you desire!

Before starting developing you can with make setup to configure all the necessary check before create a commit.

Code style

To ensure consistency throughout the source code, these rules are to be kept in mind:

All features or bug fixes must be tested by one or more specs (unit-tests).
All public API methods must be documented. (Details TBC).
Four spaces
Call make fmt before committing
If you can, GPG-sign at least your top commit when filing a PR

If You Don’t Know The Right Thing, Do The Simplest Thing

Sometimes the right way is unclear, so it’s best not to spend time on it. It’s far easier to rewrite simple code than complex code, too.

Use of `FIXME`

There are two cases in which you should use a /* FIXME: */ comment: one is where an optimization seems possible, but it’s unclear if it’s yet worthwhile, and the second one is in the case of an ugly corner case which could be improved (and may be in a following patch).

There are always compromises in code: eventually, it needs to ship. FIXME is grep-fodder for yourself and others, as well as useful warning signs if we later encounter an issue in some part of the code.

Write For Today: Unused Code Is Buggy Code

Don’t overdesign: complexity is a killer. If you need a fancy data structure, start with a brute force linked list. Once that’s working, perhaps consider your fancy structure, but don’t implement a generic thing. Use /* FIXME: ...*/ to salve your conscience.

Keep Your Patches Reviewable

Try to make a single change at a time. It’s tempting to do “drive-by” fixes as you see other things, and a minimal amount is unavoidable, but you can end up shaving infinite yaks. This is a good time to drop a /* FIXME: ...*/ comment and move on.

Commit Style

The commit style is one of the more important concepts when managing a monorepo like Coffee, and in particular, the commit style is used to generate the changelog for the next release.

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory while the scope of the header is optional.

All lines in a commit message should be at most 100 characters! This ensures better readability on GitHub as well as in various git tools.

The footer should contain a closing reference to an issue if any.

Some couple of examples are:

docs(changelog): update changelog to beta.5

fix(release): need to depend on the latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

Types

feat: A new feature
fix: A bug fix
deprecate: Deprecate a feature and start to the removing process (3 official release or 1 major release)
remove: End of life for the feature.

Scopes

core: Changes related to the main functions
cmd: Changes related to the cli package
docs: Changes related to the documentation of the crate
github: Changes related to the github interface
lib: Changes related to the core library package
storage: Changes related to the storage package

Subject

The subject contains a succinct description of the change:

use the imperative, present tense: "change" not "changed" nor "changes"
don't capitalize the first letter
no dot (.) at the end

Body

You are free to put all the content you want inside the body, but if you are fixing try to follow this indication and do not waste the body space, also it is preferable that if you fix an exception or some wrong behavior you must put the details or stacktrace inside the body ensure sure that the search engine indexes it.

An example of commit body is the following one

checker: fixes overloading operation when the type is optimized

The stacktrace is the following one

} expected `Foo` not `Foo` - both operands must be the same type for operator overloading
   11 | }
   12 |
   13 | fn (_ Foo) == (_ Foo) bool {
      |                  ~~~
   14 |     return true
   15 | }---
description: "`Rust core lightning Rust framework` HACKING guide"
---

How to make the release

TODO

N.B: Part of this document is stolen from core lightning docs made with from @rustyrussell 's experience.

Cheers!

Vincent

Coffee Plugin Manager