REST APIs for Core Lightning written with node.js
REST APIs for Core Lightning written in Node.js
Docker image: https://hub.docker.com/repository/docker/saubyk/c-lightning-rest
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
The below run time configuration are available, which can be configured either via library specific config file or C-Lightning config
file:
https
and http
(unencrypted and insecure communication between API server and the app)test
and production
lightning-rpc
file is located. It will default to standard lightning path if not configured/rpc
endpointcl-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:
3001
)4001
)https
)production
)
)["*"]
)localhost
)::
)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:
rest-port
rest-docport
rest-protocol
rest-execmode
rest-lnrpcpath
rest-rpc
rest-domain
rest-bind
Defaults are the same as in option # 1 with the exception that rest-rpc
is a comma separated string.
You can choose from the below options to run the API server
$ node cl-rest.js
Access the APIs on the default port 3001 or the port configured in the config file.
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
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
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.
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:
macaroon
set as the macaroon coverted to base64 string.var abc = fs.readFileSync (macaroonFile);
var macaroon = Buffer.from(abc).toString("base64");
macaroon
set as the macaroon coverted to hex string and encodingtype
with value set as 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.
Sample url for Swagger documentation of APIs: http://localhost:4001/api-docs/
C-Lightning commands covered by this API suite is here
GET
: Get node informationGET
: Returns on-chain funds and channel funds informationGET
: Returns total, confirmed and unconfirmed on-chain balancesGET
: Returns the routing fee collected by the nodePOST
: Creates a digital signature of the message using node's secret keyGET
: Verifies a signature and the pubkey of the node which signed the messageGET
: Decodes various invoice strings including BOLT12GET
: List all the configuration optionsGET
: Generate address for recieving on-chain fundsPOST
: Withdraw on-chain funds to an addressPOST
: Connect with a network peerGET
: Returns the list of peers connected with the nodeDEL
: Disconnect from a connected network peerPOST
: Open channel with a connected peer nodeGET
: Get the list of channels that are known to the node.POST
: Update the fee policy for a channelDEL
: Close channelGET
: Get the list of forwarded htlcs by the nodeGET
: Summarizes local and remote channel balances on the nodePOST
: Pay a bolt11 invoiceGET
: List result of payment {bolt11}, or allGET
: List outgoing payments {bolt11}, or all. This api has more detailed output than listpaysGET
: Decode the bolt11 invoicePOST
: Send funds to a node without an invoicePOST
: Generates a bolt11 invoice provided amount in msat, label, description, expiry in seconds (optional)GET
: Lists the invoice on the node, for a {label} or all.DEL
: Delete expired invoices.DEL
: Delete a particular invoice with a label and status.GET
: List the best route for the payment of [msatoshi] to a lightning node [id]GET
: Lookup node info from the network graph, for a given [pubkey]GET
: Lookup channel info from the network graph, for a given [short_channel_id]GET
: Lookup fee rates on the network, for a given rate style (perkb
or perkw
)GET
: Get the urgent, normal and slow Bitcoin feerates as sat/kVB.POST
: Create an offerGET
: Returns a list of all the offers on the nodePOST
: Fetch an invoice for an offerDEL
: Disables an existing offer, so that it cannot be used for future paymentsGET
: Reload the policy fileGET
: Returns swap by swapidGET
: List swapsGET
: Returns active swapsGET
: Returns unhandled swaps requested by peer nodesGET
: Lists peers supporting the peerswap pluginGET
: Sets peerswap to allow or deny incoming swap requestsGET
: Adds peer with specified pubkey to allowlistGET
: Removes peer with specified pubkey from allowlistGET
: Resends last swap message to specified swap idPOST
: Initiates a swap inPOST
: Initiates a swap outPOST
: additional access to RPC comands. Examples of body param for rpc:{"method": "getinfo"}
{"method":"signmessage", "params": ["message"]}
{"method":"mymethod", "params: {"key1": "value1"...}}
PRs are welcome! :-)