Home

Awesome

C-Lightning-REST

REST APIs for Core Lightning written in Node.js

Docker image: https://hub.docker.com/repository/docker/saubyk/c-lightning-rest

<a name="setup"></a>Setup

<a name="prereq"></a>Pre-requisite

<a name="install"></a>Installation

Download a specific version by following the instructions on the release page

Download from master (not recommended), by following the below steps:

$ git clone https://github.com/saubyk/c-lightning-REST
$ cd c-lightning-REST
$ npm install

<a name="config"></a>Configuration parameters

The below run time configuration are available, which can be configured either via library specific config file or C-Lightning config file:

Option 1: Via Config file cl-rest-config.json

For running the server, rename the file sample-cl-rest-config.json to cl-rest-config.json. Following parameters can be configured in the config file:

Option 2: With the plugin configuration, if used as a plugin

NOTE: Node.js plugins might not work with lightningd.service setting MemoryDenyWriteExecute=true as it denies the creation of writable and executable memory mappings. Ref: https://github.com/Ride-The-Lightning/c-lightning-REST/issues/116

If running as a plugin, configure the below options in your core lightning config file:

Defaults are the same as in option # 1 with the exception that rest-rpc is a comma separated string.

<a name="exec"></a>Execute Server

You can choose from the below options to run the API server

Option 1: Run as an API server

$ node cl-rest.js

Access the APIs on the default port 3001 or the port configured in the config file.

Option 2: Run as a core lightning plugin

Pass arguments when launching lightningd:

$ lightningd --plugin=PATH_TO_PLUGIN [--rest-port=N] [--rest-protocol=http|https] [--rest-execmode=MODE]

E.g. $ lightningd --plugin=/Users/<user>/c-lightning-REST/clrest.js --rest-port=3003

OR

Set plugin, [rest-port], [rest-docport], [rest-protocol], and [rest-execmode] in lightningd config

E.g. add below to the config file in .lightning folder

plugin=/Users/<user>/c-lightning-REST/clrest.js
rest-port=3002
rest-docport=4001
rest-protocol=https

Option 3: Running c-lightning-REST as a service (Rpi or Linux platform users)

In case you are running a headless Rpi or a Linux node, you can configure c-lightning-REST as a service.

# Raspibolt c-lightning-REST: systemd unit for c-lightning-REST
# /etc/systemd/system/c-lightning-REST.service

[Unit]
Description=c-lightning-REST daemon
Wants=lightningd.service
After=lightningd.service

[Service]
ExecStart=/usr/bin/node <Full path of the c-lightning-REST folder>/cl-rest.js
User=<user>
Restart=always
TimeoutSec=120
RestartSec=30

[Install]
WantedBy=multi-user.target

$ sudo systemctl enable c-lightning-REST
$ sudo systemctl start c-lightning-REST

$ sudo journalctl -f -u c-lightning-REST

<a name="sec"></a>Security

With the default config, APIs will be served over https (a self signed certificate and key will be generated in the certs folder with openssl).

Sample url: https://localhost:3001/v1/getinfo/

Providing a DOMAIN to the c-lightning-REST configuration will add the domain as a subjectAltName to the openssl certificate, permitting successful certificate validation by users and applications, e.g. Zeus, when connecting to the server at via that domain.

If you are upgrading a server which is already configured, you should first backup and your entire ./certs directory in case you need to restore it later. Following this you should delete only the .certs/certificate.pem and .certs/key.pem files, so that new SSL certificates can be generated which take the subjectAltName into consideration.

WARNING: Do not delete access.macaroon or rootKey.key. If you do then your connection to remote applications will be lost, and need to be re-configured.

New certificates will be automatically generated as usual next time the program is started up.

<a name="auth"></a>Authentication

Authentication has been implemented with macaroons. Macaroons are bearer tokens, which will be verified by the server. Two files, access.macaroon and rootKey.key, will be generated in the certs folder in the application root. The access.macaroon has to be read by the requesting application, converted to base64 or hex, and passed in the header with key value macaroon.

Encoding Options for passing macaroon in the header:

Option 1 - base64

var abc = fs.readFileSync (macaroonFile);
var macaroon = Buffer.from(abc).toString("base64");

Option 2 - hex

var abc = fs.readFileSync (macaroonFile);
var macaroon = Buffer.from(abc).toString("hex");

If you need help converting your macaroon to hex format you can use the Node.js script from the Zeus project, found here. Alternatively, if you're running a Unix-based operating system (eg. macOS, Linux) you can run xxd -ps -u -c 1000 /path/to/access.macaroon to generate your macaroon in hex format.

<a name="apis"></a>API Documentation

Sample url for Swagger documentation of APIs: http://localhost:4001/api-docs/

C-Lightning commands covered by this API suite is here

General Node info

On-Chain fund management

Peer management

Channel management

Payments

Invoice

Network

Offers

Peerswap

RPC

No param

{"method": "getinfo"}

One param

{"method":"signmessage", "params": ["message"]}

Multiple params

{"method":"mymethod", "params: {"key1": "value1"...}}

PRs are welcome! :-)