BOLT 0: Attempt shorter introduction as informal index.#432
Conversation
This was inspired by @shannona's lightning#415 Especially the title line :) Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
rustyrussell
requested review from
cdecker,
jimpo,
josephpoon,
shannona and
starkness
shannona
left a comment
shannona
left a comment
There was a problem hiding this comment.
Hey, @rustyrussell, glad that an introduction is going forward. I guess my draft was determined too long? I have some concern that this one ends up being too short, without strong context. I've added what context I could here, where I thought it was important (and made some other comments). Hopefully that'll be useful for this current effort.
Another possibility may be to create a draft somewhere between the two, if you found that useful.
| ## The Spark: A Short Introduction to Lightning | ||
|
|
||
| Lightning is a protocol for fast payments using Bitcoin, using a | ||
| network of channels. |
There was a problem hiding this comment.
Redundant use of using. Perhaps: "Lightning is a protocol for making fast payments with Bitcoin using a
+network of channels."
| custody of some bitcoin (e.g. 0.1 bitcoin), spendable only with both | ||
| their signatures. | ||
|
|
||
| Initially they each hold a bitcoin transaction which sends all the |
|
|
||
| Lightning works by establishing *channels*: two participants share | ||
| custody of some bitcoin (e.g. 0.1 bitcoin), spendable only with both | ||
| their signatures. |
There was a problem hiding this comment.
I feel like this doesn't fully describe what a channel actually is. Maybe: "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."
There was a problem hiding this comment.
Yes, I like that.
| their signatures. | ||
|
|
||
| Initially they each hold a bitcoin transaction which sends all the | ||
| bitcoin (e.g. 0.1) back to one party. They can sign a new bitcoin |
There was a problem hiding this comment.
0.1->0.1 bitcoin
They can sign->They can later sign
|
|
||
| Initially they each hold a bitcoin transaction which sends all the | ||
| bitcoin (e.g. 0.1) back to one party. They can sign a new bitcoin | ||
| transaction which splits these funds differently, e.g. 0.09 to one |
There was a problem hiding this comment.
which->that
0.09->0.09 bitcoin
| transaction so it won't be spent. | ||
|
|
||
| See [BOLT #2: Channel Establishment](02-peer-protocol.md#channel-establishment) for more on | ||
| channel establishment and [BOLT #3: Funding Transaction Output](03-transactions.md#funding-transaction-output) for the format of the bitcoin transaction which creates the channel. See [BOLT #5: Recommendations for On-chain Transaction Handling](05-onchain.md) for the requirements when peers disagree or fail, and the cross-signed bitcoin transaction must be spent. |
There was a problem hiding this comment.
which->that
And probably peers->participants since that's the language used in this section.
| 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. |
There was a problem hiding this comment.
This feels like it's missing a lot of context and dumps readers into the deep end without explaining why they're going there. Maybe if you lead with something like. "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, ..." [and then continue with line 49].
| ### Forwarding | ||
|
|
||
| Such a conditional payment can be safely forwarded to another | ||
| participant, e.g. "you get 0.01 bitcoin if you reveal the secret |
There was a problem hiding this comment.
You need to explicitly mention that you're decreasing the timeout else people might be confused by the e.g. Such as: "can be safely forwarded to another participant with a lower time limit, ..."
|
|
||
| Such a conditional payment can be safely forwarded to another | ||
| participant, e.g. "you get 0.01 bitcoin if you reveal the secret | ||
| within 5 hours". This allows channels to be chained for payments |
There was a problem hiding this comment.
Assuming you added the additional context I suggest above, you can now say "chained into a network"
| ### Payment Invoicing | ||
|
|
||
| To know what payments to make, [BOLT #11: Invoice Protocol for Lightning Payments](11-payment-encoding.md) presents the protocol for describing the destination and purpose of a payment such that the payer can later prove successful payment. | ||
|
|
There was a problem hiding this comment.
This isn't in the same format as the other sections. Maybe:
"A participant receives invoices that tell him what payments to make.
See [Bolt #11 ...]"
3 participants
This was inspired by @shannona's
#415
Especially the title line :)