Day 1 of the Chaincode Labs Lightning Residency

This week I’m at the Chaincode Labs Lightning residency to learn from the experts and build my C# Microsoft Excel plugin for communicating with the LND gRPC API. This allows business professionals to easily interact with their node’s data and send payments. Here are notes I jotted down from day one’s morning presentations…

All mistakes are my own! Shout at me if something is wrong.

History of the Lightning Network with Christian Decker

“Off-chain” to not imply a hierarchy of layers.

What are off-chain protocols?

Systems in which you have users using data on a blockchain and managing it without touching the blockchain itself. Off-chain contract is also called a payment channel. We need a way to make sure older states are not used, an update mechanism is necessary. The core issue is how the last agreed upon state is enforceable on the blockchain.

The first Bitcoin update mechanism was created Satoshi Nakamoto in the initial release of Bitcoin in 2009. This was called nSequence transaction update. The problem is that miners can be incentivized to choose old transactions. nSequence numbers don’t work. This field has been repurposed since.

The first working update mechanism was Spilman’s simple micropayment channel. Setup transaction sends to a multisig 2-of-2 output. Settlement transaction spends to two outputs. Half-signed settlement transaction can be held off-chain to keep the channel open or committed to the blockchain to close the channel. A refund transaction is created when the channel is opened in case the participant who hasn’t signed the 2-of-2 disappears. This refund transaction has a timelock. The problem is that this update mechanism is unilateral. One party will always be incentivized to broadcast the state that gives them the most funds. “Replacement by incentive”, one party is incentivized. It’s like a prepaid debit card that you throwaway after use.

Duplex micropayment channels, Decker and Wattenhofer 2015, the initial settlement transaction has a timelock on it so that time must pass before settlement can happen. Replacement transactions have a slightly shorter timelock so that the old state is replaced. This can be done repeatedly and the timelock counts down. In the case of a unilateral close, the entire timelock needs to elapse. In a collaborative close, a new settlement transaction without a timelock is created, both participants sign it, and it is broadcasted.

The Lightning Penalty mechanism has the two parties each create their own settlement transaction. They are identical except for the conditions placed on the outputs. Old settlement transactions are revoked by telling the other party a secret. The advantage over duplex micropayment channels is that there is not a limited lifespan. The problem is if you accidentally broadcast an old state and get punished by losing all your funds. Backups are hard. It becomes a complex state machine that is more likely to have edge case bugs. Can’t share states among multiple nodes.

The eltoo update mechanism has a timelocked 2-of-2 setup transactions. The first settlement transaction reflects the same setup state. Each update extends the timelock and revokes the previous update by double-spending the same output. Depends on sighashnoinput softfork. No penalty. Backups are safe. State management is easier as we have symmetric state. You keep far fewer states. Disadvantage is implementation may have a bigger footprint, with 3 transactions instead of 2, and base layer protocol needs an update.

Bootstrapping and Maintaining a Lightning Node by Elaine Ou

How Routing Works (In Theory)

You want to send a payment when you do not have a channel open directly with the recipient. It is on the sender to find a route. The LN uses onion routing so that intermediate nodes do not know what is the starting or final destination. Keeps payments private and anonymous. Every node has their own local view of the network. The sender wants to find the shortest path that has enough channel capacity, taking into account fees and the time lock penalty. Clightning takes into account negative fees, which can be used by nodes to rebalance a channel. The sender tries different paths until one works. In practice there have been a lot of payment routing failure errors. Goal is to have this happen as infrequently as possible.

LN nodes use a DNS seed server for bootstrapping its view of the network.

Revocation punishment transaction is done by combining the commitment_secret which A sent to B, with the revocation_basepoint_secret that only B as.

Autopilot does not currently take into account factors like channel capacity vs channel balance, reliability/uptime, path diversity and redundancy (single points of failure), fewest hops to favorite destinations.

Incoming capacity allows us to receive payments in the future, your node has to convince other nodes to open channels to it. Otherwise you can only send payments. Being a good routing node is a chicken and egg problem. Build a store that people like so you get paid, not easy either. If you go out and spend on LN, you now have incoming capacity. You could buy bitcoins on an exchange and withdraw your funds to your LN wallet. Atomic swaps from altcoins or Bitcoin.

Why Payments Fail

Can’t find a route at all because not enough channels to well connected nodes. The payment may be too large, better off on-chain. Large transactions shorten channel lifetime. Zombie nodes made public channels then went offline. General problem is not enough information for the sender.

Information is spread with the gossip protocol. Not all channels are public. Some nodes only want private channels because they may not be available to route payments. For most users they don’t need public channels. Many users will be on mobile devices so reliability should not be expected. Division of labor: different nodes are going to be better at different things. There will be specialized routing nodes with public channels and mobile payment nodes with private channels.

You can provide routing hints when creating an invoice so that the payer can find a path to you even if you only have private channels open.

Be a good node: keep public channels balanced, use negative fees if you have to. Shutdown gracefully: close your channels before going offline. Punish bad nodes by closing inactive and offline channels.

Future Work In Progress

Atomic multi-path transactions (AMP). Splicing for resizing open channels. Channel factories. More information about peer node history, routing success and failure metrics, know if node’s channel closes where cooperative or unilateral.

The Lightning Protocol An Application Design Perspective with Alex Bosworth

Parts of the BOLTs that you as an app developer would care about.

  • HTLC is the atom of the app-building universe. Channels and the channel graph would ideally not be thought about by an app developer. Only HTLCs.


HTLC Lifecycle for Sending a Payment

  1. Funds locked to peer
  2. Wait for peer response up to timeout
  3. Peer notification of failure: good because you can stop waiting and try a different peer
  4. Peer notification of success
  5. What happens if we wait to timeout? We need to go on-chain.


The Lightning protocol is designed to change a lot. Assumption is that you stay online, especially for an app or service. There is no constraint that the underlying chain be Bitcoin. The same node and network could handle multiple different coins.


To have HTLCs be flowing you need channels. Channels can close at any time, so you need redundancy and channels open to different parts of the network. You never know where an HTLC came from, may be from outside the LN network.


You want to avoid the HTLC resolution state on-chain. Very small payments are actually disadvantaged as on-chain resolution isn’t worth it. Time-locked funds are going to become a fact of life, some portion of your wallet will always be time-locked due to channels being unexpectedly closed. LND currently uses 2 weeks as a maximum, scaled down to 1 day for the lowest amounts. Will become shorter as tools improve.


The onion messages could have more information in it than is currently implemented. This currently is possible by overloading failure messages. Failure messages could become useful, which is a problem as they don’t pay fees. Success messages should also have a payload and failure messages should start paying fees. This will allow API developers to use LN’s sphinx onion routing for both payment and data.


As an app developer don’t worry about breaches. There are easier ways to for attackers to abuse.

Do worry about chain fees (be choosy about peers). You can end up with dust. You can lose money to UTXO consolidation cost.

Backups — only éclair has backup support. LND and clightning do not have backup support. Ideally we would have a distributed database (replication). Static backups are a simple copy of commitment transactions. Non-evil peers could remind you of where state is.

Bolt 6: IRC bootstrapping no longer exists, so here’s what goes left unsaid…

A payment either resolves very quickly OR very slowly. Worrying case for app developers. In early days, payments can cost more on LN than on the chain, especially for large payments that are exhausting channels. Comprehensive backups and sharing are a ways off. Apps can game fees by hiding behind routing nodes.

Bolt 7: The Grid

The graph is like your ISP. Merchants (servers), consumers (clients), and routing nodes. In the future, ideally, all public channels would only be routing nodes, merchants and consumers would have private channels to routing nodes. 90% of the current graph is bad, for example public channel nodes that are offline. In the future it’s not a given that you would ever directly connect with a merchant.

Bolt 8: Public Key

Merchants and consumers can use their node key as a decentralized identity.

Bolt 9: Features so Far

Reducing channel graph sync requirements with small nodes. We haven’t had a global upgrade yet.

Bolt 10: DNS Bootstrap

You can be judgmental about your actual peers with LN, for Bitcoin network DNS is non-judgmental.

Bolt 11: Give Me Money

Invoices have lots of features, great for app developers. Downside is that it is a long string you have to copy/paste. Invoices can expire, have a description, have a fallback Bitcoin on-chain address, it’s extensible so you can add your own fields.

Lapp Monetization Models and Building with Éclair with Chris Stewart

Blockchains are bad: slow, inefficient, high fees, hard to maintain privacy. Only good for final settlement!

How to make BTC as a lapp dev?

  1. Lightning Network
  2. ???
  3. Profit!

What does lightning network enable us to do that wasn’t possible before?

Monetization strategies for APIs

  • Rate limiting: ration the service to prevent abuse
  • Crypto-exchanges for example
  • Pay per call APIs
  • Idea has been around for a while, 21co tried with old Spilman unidirectional channels
  • Suredbits is using LN
  • You can use preimages to encrypt payloads, if payment is successful the user receives the preimage needed to decrypt the data.
  • Use async to abstract away endpoint interaction complexity

Websocket subscriptions and LN

  • Subscribe to a websocket for a unit of time of streaming, for example pay 60 satoshis for 1 minute of data from the websocket
  • LN allows for easy refills of the subscription, cancellation with refunds

Day 2:

Day 3: