c-lightning API

How to adapt c-lightning to do what you want to do.

The goals of c-lightning:

Fast & lightweight. For any device where you have a stable connection.

2. Flexible & customizable. Give you the tools to adapt it to your needs.

3. Optimize for powerusers. The server backend running big services, can be desktop/mobile wallet but not optimized for that.

Run it with log-level=debug. Don’t be scared if logs say something “died”, not necessarily bad. Use lightning-cli help to see all the different RPC commands. You can use one bitcoind node to serve a hundred c-lightning nodes.

Architecture

Special architecture. Multiple processes. Each channeld process takes care of one channel. Multi-daemon architecture allows easy swapping of parts. Lifecycle of processes is simple. The whole process is one state machine per channel. Separation of concerns. Channeld only has access to data relevant to it, more secure. hsmd is for private keys. gossipd only has access to what it needs. Could run on different machines. Separate into their own runtime with docker, selinux… The master daemon takes care of managing state across the channel processes. Gives a lot of flexibility. gossipd store information about network, local view of the network. Ask it for routing information. You could have multiple c-lightning nodes with one gossipd process, which uses the most memory. hsmd handles the private key encryption. It’s not an actual hardware security model *yet*. Plugins are tiny scripts that talk JSON-RPC over stdio. They get pushed notifications. Connectd is for incoming connections. Outbound data only comes from channeld processes.

JSON-RPC Interface

JSON is easy, human-readable. Unix socket, not exposed over the network. Use your preferred transport layer on top of the Unix socket for connecting remotely. lightning-cli is a small wrapper around socat. lightning-cli help and lightning-cli getinfo and there are man pages. pylightning is always up to date with c-lightning. lightning-charge has a JS client, can use REST or JSON-RPC. kugelblitz: out of date tiny golang wrapper. Bash: use socat but you’ll have to write valid JSON.

Invoicing/Receiving Payments

$ lightning-cli invoice [msatoshi] [unique label] [description]

Unique label can be the numeric ID of the shopping cart that matches an invoice. Enables later reconciliation. Description is what will end up in the payment request sent to the payer. Not necessary but be nice and help people.

$ lightning-cli listinvoices

$ lightning-cli waitinvoice [unique label]

$ lightning-cli waitanyinvoice [last-pay-index]

$ lightning-cli delexpiredinvoice [maxexpiry]

Delete unpaid expired invoices.

Sending Payments

$ lightning-cli pay [bolt 11 string]

Try a path, if it failed retry. Output is large, shows every path tried and the error message.

$ lightning-cli getroute [destination] [msatoshi] [riskfactor]

$ lightning-cli sendpay [route] [payment_hash]

$ lightning-cli waitsendpay [payment_hash]

Subdaemons

Tightly integrated with the master daemon, flexible but hard to code.

Pluggable Bitcoin backend (bitcoind, spruned, neutrino) Routing service and gossip store, externalize and centralize Replace HSMd with hardware wallet, mobile app, etcetera…

Plugins (tbd…)

Customization made simple, you just read JSON notifications. Read-only, for writing use the actual JSON-RPC API.