Image for post
Image for post

c-lightning API

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

The goals of c-lightning:

  1. 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.


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]


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

  1. Pluggable Bitcoin backend (bitcoind, spruned, neutrino)
  2. Routing service and gossip store, externalize and centralize
  3. 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.

  1. Autopilot
  2. Payment logic (hold HTLC until delivered, notify service, …)
  3. Short-circuit payments, if you have multiple c-lightning nodes you can have one virtual node that passes payments to the nodes.
  4. External continuations
  5. … whatever else you can come up with. Plugins open up flexibility.

Lightning UX — Building Lightning into Bitrefill

Lightning Invoices

They’re great. Bolt 11 format: simple, extendable QR-code-ready protocol for requesting payments over Lightning. Modification of an invoice will invalidate the invoice due to the checksum. Copy and paste the whole string, easy. The network and amount are human-readable. bc13370n for example. Never enter the amount manually with Lightning invoices, this avoids user errors that were common in Bitcoin. On-chain payments should use Lightning invoices too.

UX Improvements with Lightning

Goal of removing Partial Order failures. Funds are not sent after expiration. In practice we have seen issues with lightning invoices being paid after expiry off chain. No notification sent, payment not updated.

Proof of Payment

Proof of payment (preimage) allows verification of payment.

Easy to integrate lightning. Used the same payments flow as Bitcoin on-chain. Re-designed to do a bigger QR code to be easier to scan. User confusion by calling it “Bitcoin Lightning”. Renamed it to “Lightning (BTC)”. Bitrefill does not publish node info on the site. Info is already in the invoice. Supports LTC, a lot lower value due to no mobile wallets.

Upper case the letters in your Lightning invoice before converting to a QR code, it’ll be an easier to scan QR code.


  1. Mobile wallets in use
  2. Zap, Éclair

Lightning Deposits

  1. 0 amount invoices can be an option for deposits
  2. Possible use case being send all feature
  3. Can be used for tips and other use cases
  4. Submarine swaps allow Bitrefill to accept altcoins without setting up infrastructure for every altcoin.

Lightning Withdrawal

  1. Auto decode invoices for users
  2. Buda charges no fee, but should in practice
  3. Custodial wallets, have to start somewhere
  4. Make faucets great again
  5. Better error codes needed for lightning sending api with lnd needed
  6. Better handling and documentation of lifecycle of send

Improvements to the Lightning UX

  1. Routing failures
  2. Encode fallback addresses in the backup when routing has failed and order is > X value.

Lighting Refunds Future UX

Reserve can prevent sending payment back for a refund. Support for paying on-chain.

LN-Powered Games

I’m not a game developer, take it with a grain of salt. Ideas about how games might be an interesting application for Lightning. We’ve all played some kind of game at some point. Enormous variety of games on phone, laptop, console, desktop. Some are free, some are paid. Some make you gamble, others are for passing time.

Lighting as a Payment Method

Games use money:

  1. Pay to play. Arcade machine. Most direct monetization. Satoshi’s place is in this category. With Lightning you can have a lower price point.
  2. In-game purchases. Buy items, powerups, this is the main way that free games monetize themselves today.
  3. In-app currencies. Most games create their own virtual currency. Human psychology is manipulated by a virtual currency, abstracting away real value of money, makes them more likely to spend. Deposit $5 and get 1,000 jewels, you’ll forget the exchange rate. With Lightning you can use satoshis and outsource the tracking of balances.
  4. Trading in-game items between each other. In some cases they are used to gamble on matches (counter-strike). In some cases you can trade items for real money, including BTC. You can have a Lightning escrow to minimize risk of p2p item trading.
  5. Gambling. Games of chance. Against house odds or between players (online poker). Sports betting. Regulatory arbitrage using Lightning.
  6. Twitch / spectator donations. Streamers get donations while playing games. Lightning could provide a fun way for spectators to interact with players.

How do game developers and players benefit?

Three characteristics enabled by Bitcoin + LN:

  • Permission-less. Payment processors require you to be > 18 years old to sell your video game.
  • Low fees. Payment processors charge a large %
  • Microtransactions. Unlocks the ability to monetize little things. Might not be as great as people think. Mental accounting costs.

Why are games an interesting application for Lightning?

  1. Fun!
  2. Younger audience that “gets” it.
  3. Cutting edge.
  4. Digital.
  5. Huge industry.

Narrowing things down…

The type of lightning games I think are interesting.

  • Indie games. Not million dollar budgets. Benefits of lightning are more obvious for small developers.
  • Browser based. HTML5 > Flash. Good platform to build a game on.
  • Multiplayer. Use money in innovative ways.
  • Online, you have to be online because of LN.

The Anatomy of a Multiplayer Game

LAN parties. Host of the game is also a player. You have to trust they’re not running a modified version to pwn you. Doesn’t work in adversarial situations, need a referee to prevent cheating — the authoritative server. The de facto source of truth which all clients sync to. The server is not a player. Real time multiplayer gaming is hard. Turn based is easier.

Existing Lightning Games

Lightning Spin, Poketoshi (pay for each button press), Satoshis Game (steam-like platform to aggregate), Satoshi’s Place, Sarutobi, Lightning Roulette.

Experimental Stuff

Demo of tank battle game with nintendo switch controller, scanning QR code gives shield to tank. Lightning payments inside of minecraft for teleporting.

Tools and Plugins

Game engines: phaser, unity, playcanvas

Game servers: Nakama, colyseus, playfab

Lightning: plugins for unity or make something from scratch

Digital Assets and NFTs

Controversial. Immutable, transparent, scarce items tradable without intermediaries. Most attempts have been on-chain. Counterparty, rare pepes, cryptokitties. Already hard enough to have one token (BTC).

Explosive Innovation

It’s hard to imagine a world without Internet services. We’re at 1990 with LN, infrastructure is being built, what use cases and applications are going to be common?

Building Zap — UX, Design, and Product

Zap didn’t raise any capital, didn’t spend anything on marketing. It got featured on Bloomberg Business because of a tweet GIF showing a payment. How to keep your open source project alive?

“I only build products I am a user of.”

Unique ground-level relationship with the users and community that your project is targeting. If you’re building for Android buy an Android. Projects that survive have a real use case and the builder is the first user.

Pick an enemy when marketing. Be authentic and relatable. Contrast your solution against something familiar. Zap was contrasted with s2x, BCH nastiness. Videos of people actually using it.

Limit your scope. Ship it. You’ll never be finished 100%. You have to iterate quickly. Truth comes from the market. Make it real.

Don’t try and understand what a user “wants”. Understand what a user is trying to accomplish. When debugging ask users “tell me your story” so that you understand the context of how the app is being used.

Zap will eventually allow you to buy channel capacity within the app, with fiat.

Invest in things that will last. Channels won’t be relevant to the end user. Autopilot, splicing, AMP. Don’t invest in a channel UI.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store