BOLT #0: Introduction and Index
Welcome, friend! These Basis of Lightning Technology (BOLT) documents describe a layer-2 protocol for off-chain bitcoin transfer by mutual cooperation, relying on on-chain transactions for enforcement if necessary.
Some requirements are subtle; we have tried to highlight motivations and reasoning behind the results you see here. I'm sure we've fallen short; if you find any part confusing or wrong, please contact us and help us improve.
This is version 0.
- BOLT #1: Base Protocol
- BOLT #2: Peer Protocol for Channel Management
- BOLT #3: Bitcoin Transaction and Script Formats
- BOLT #4: Onion Routing Protocol
- BOLT #5: Recommendations for On-chain Transaction Handling
- BOLT #7: P2P Node and Channel Discovery
- BOLT #8: Encrypted and Authenticated Transport
- BOLT #9: Assigned Feature Flags
- BOLT #10: DNS Bootstrap and Assisted Node Location
- BOLT #11: Invoice Protocol for Lightning Payments
The Spark: A Short Introduction to Lightning
Lightning is a protocol for making fast payments with Bitcoin using a network of channels.
Lightning works by establishing channels: two participants create a Lightning payment channel that contains some amount of bitcoin (e.g., 0.1 bitcoin) that they've locked up on the Bitcoin network. It is spendable only with both their signatures.
Initially they each hold a bitcoin transaction that sends all the bitcoin (e.g. 0.1 bitcoin) back to one party. They can later sign a new bitcoin transaction that splits these funds differently, e.g. 0.09 bitcoin to one party, 0.01 bitcoin to the other, and invalidate the previous bitcoin transaction so it won't be spent.
See BOLT #2: Channel Establishment for more on channel establishment and BOLT #3: Funding Transaction Output for the format of the bitcoin transaction that creates the channel. See BOLT #5: Recommendations for On-chain Transaction Handling for the requirements when participants disagree or fail, and the cross-signed bitcoin transaction must be spent.
A Lightning channel only allows payment between two participants, but channels can be connected together to form a network that allows payments between all members of the network. This requires the technology of a conditional payment, which can be added to a channel, e.g. "you get 0.01 bitcoin if you reveal the secret within 6 hours". Once the recipient presents the secret, that bitcoin transaction is replaced with one lacking the conditional payment and adding the funds to that recipient's output.
Such a conditional payment can be safely forwarded to another participant with a lower time limit, e.g. "you get 0.01 bitcoin if you reveal the secret within 5 hours". This allows channels to be chained into a network without trusting the intermediaries.
To make a payment, a participant needs to know what channels it can send through. Participants tell each other about channel and node creation, and updates.
See BOLT #7: P2P Node and Channel Discovery for details on the communication protocol, and BOLT #10: DNS Bootstrap and Assisted Node Location for initial network bootstrap.
A participant receives invoices that tell her what payments to make.
See BOLT #11: Invoice Protocol for Lightning Payments for the protocol describing the destination and purpose of a payment such that the payer can later prove successful payment.
Glossary and Terminology Guide
The uniquely identifying hash of the target blockchain (usually the genesis hash). This allows nodes to create and reference channels on several blockchains. Nodes are to ignore any messages that reference a
chain_hashthat are unknown to them. Unlike
bitcoin-cli, the hash is not reversed but is used directly.
For the main chain Bitcoin blockchain, the
chain_hashvalue MUST be (encoded in hex):
Commitment revocation private key:
- Every commitment transaction has a unique commitment revocation private-key value that allows the other peer to spend all outputs immediately: revealing this key is how old commitment transactions are revoked. To support revocation, each output of the commitment transaction refers to the commitment revocation public key.
- See container: commitment transaction
- See originator: per-commitment secret
- A transaction that spends the funding transaction. Each peer holds the other peer's signature for this transaction, so that each always has a commitment transaction that it can spend. After a new commitment transaction is negotiated, the old one is revoked.
- See parts: commitment number, commitment revocation private key, HTLC, per-commitment secret, outpoint
- See related: closing transaction, funding transaction, penalty transaction
- See types: revoked commitment transaction
HTLC: Hashed Time Locked Contract.
- A conditional payment between two peers: the recipient can spend the payment by presenting its signature and a payment preimage, otherwise the payer can cancel the contract by spending it after a given time. These are implemented as outputs from the commitment transaction.
- See container: commitment transaction
- See parts: Payment hash, Payment preimage
Invoice: A request for funds on the Lightning Network, possibly
including payment type, payment amount, expiry, and other information. This is how payments are made on the Lightning Network, rather than using Bitcoin-style addresses.
It's ok to be odd:
- A rule applied to some numeric fields that indicates either optional or compulsory support for features. Even numbers indicate that both endpoints MUST support the feature in question, while odd numbers indicate that the feature MAY be disregarded by the other endpoint.
- A millisatoshi, often used as a field name.
Revoked commitment transaction:
Revoked transaction close:
- An uncooperative close of a channel, accomplished by broadcasting a commitment transaction. This transaction is larger (i.e. less efficient) than a closing transaction, and the peer whose commitment is broadcast cannot access its own outputs for some previously-negotiated duration.
- See related: mutual close, revoked transaction close
Why this network could be democratic... Numismatic... Cryptographic! Why it could be released Lightning! (Release Lightning!) We'll have some timelocked contracts with hashed pubkeys, oh yeah. (Keep talking, whoa keep talkin') We'll segregate the witness for trustless starts, oh yeah. (I'll get the money, I've got to get the money) With dynamic onion routes, they'll be shakin' in their boots; You know that's just the truth, we'll be scaling through the roof. Release Lightning! (Go, go, go, go; go, go, go, go, go, go) [Chorus:] Oh released Lightning, it's better than a debit card.. (Release Lightning, go release Lightning!) With released Lightning, micropayments just ain't hard... (Release Lightning, go release Lightning!) Then kaboom: we'll hit the moon -- release Lightning! (Go, go, go, go; go, go, go, go, go, go) We'll have QR codes, and smartphone apps, oh yeah. (Ooo ooo ooo ooo ooo ooo ooo) P2P messaging, and passive incomes, oh yeah. (Ooo ooo ooo ooo ooo ooo ooo) Outsourced closure watch, gives me feelings in my crotch. You'll know it's not a brag when the repo gets a tag: Released Lightning. [Chorus] [Instrumental, ~1m10s] [Chorus] (Lightning! Lightning! Lightning! Lightning! Lightning! Lightning! Lightning! Lightning!) C'mon guys, let's get to work!
-- Anthony Towns email@example.com
[ FIXME: Insert Author List ]
This work is licensed under a Creative Commons Attribution 4.0 International License.