Minor issues in documentation

[jnewbery]

Hi Rusty,

I decided to finally lock myself away with your Reaching the Ground with Lightning paper and your earlier blog post series last night and spent some time digging into the details of Lightning. I love the work you're doing on this, and I'm happy that I'm finally beginning to get my head around lightning.

I have a few minor comments about the paper:

1. in Figure 1: Figure 1 from the Lightning Network Draft 0.5

   • Commitment Close Tx 1A (CC1b) -- should be CC1a

   • Commitment Close Tx 1b (CC1a) -- should be CC1b

     (both of these are carried over from the Lightning Paper 0.5 and fixed in 0.5.9)

2. in Figure 2: Figure 2 from the Lightning Network Draft 0.5

   • "Commitment Refund Tx1a (CR2a)" should be "Commitment Refund Tx2a (CR2a)"

   • The settlement/timeout transactions are named S1a/SD1a/T1a/TR1a. I believe these should be called S2a/SD2a/T2a/TR2a (since they're descendants of Commitment transaction 2a)

     (carried over from the Lightning Paper 0.5 and still in 0.5.9)

3. Section 3.2: "These can be later balanced by the lightning network itself, or an atomic-swap an on-chain bitcoin transaction" should be "These can be later balanced by the lightning network itself, or an on-chain atomic-swap transaction."
4. Section 3.2: "implementation splits fees where possible< and never allows either side" has an errant < character inserted (which doesn't appear in the .lyx file)
5. The references seem to have been broken between v0.1 and v0.2. References are mis-numbered and in the wrong order.
6. References to the Appendixes are broken ('The scripts for this can be found in 4' rather than 'The scripts for this can be found in appendix A' and 'as the commitment transaction in 4' instead of 'as the commitment transaction in appendix B')
7. In v0.2, the conclusion can be updated: 'By using a dual anchor and escape transactions, channel establishment can also avoid new CHECKSIG flags, though it loses the important ability to outsoure the enforcement of channel contract terms.' to 'By using a rebalanced single anchor, channel establishment can also avoid new CHECKSIG flags, while retaining the important ability to outsource the enforcement of channel contract terms.'
8. I'd recommend that the 'Escape transactions' and 'Fast escape transactions' in appendix A get moved to appendix B now that dual anchors are not part of the current design.

I'll open a pull request for 3 and 7. The others are either:

• changes to .eps files. I'm afraid I don't know how to modify those.
• errors in whatever tool you used to generate the .pdf from the source files.

I've also been following along on the Lightning-dev mailing list, and see that there's been a lot of movement on state machines and routing since v0.2 of the documentation. Are there plans to update the paper to include information on those aspects? I'm happy to lend a hand if you think that'd be useful.

Thanks,
John

[rustyrussell]

John Newbery [email protected] writes:

Hi Rusty,

I decided to finally lock myself away with your Reaching the Ground with Lightning paper and your earlier blog post series last night and spent some time digging into the details of Lightning. I love the work you're doing on this, and I'm happy that I'm finally beginning to get my head around lightning.

Thanks for the proofreading, I'm sure others have spotted my mistakes
and not been so charitable with their time :)

I have a few minor comments about the paper:

1. in Figure 1: Figure 1 from the Lightning Network Draft 0.5

   • Commitment Close Tx 1A (CC1b) -- should be CC1a

   • Commitment Close Tx 1b (CC1a) -- should be CC1b

     (both of these are carried over from the Lightning Paper 0.5 and fixed in 0.5.9)

Thanks! Yes, I have an eps of those figures only, so it'd be a PITA
to fix. But I've put in a note.

1. in Figure 2: Figure 2 from the Lightning Network Draft 0.5

   • The settlement/timeout transactions are named S1a/SD1a/T1a/TR1a. I believe these should be called S2a/SD2a/T2a/TR2a (since they're descendants of Commitment transaction 2a)

     (carried over from the Lightning Paper 0.5 and still in 0.5.9)

Hmm, good point, but I don't refer to them anywhere. I've CC'd Joseph.

1. Section 3.2: "These can be later balanced by the lightning network itself, or an atomic-swap an on-chain bitcoin transaction" should be "These can be later balanced by the lightning network itself, or an on-chain atomic-swap transaction."

OK, "an atomic swap to an onchain bitcoin transaction".

1. Section 3.2: "implementation splits fees where possible< and never allows either side" has an errant < character inserted (which doesn't appear in the .lyx file)

Weird, that's not in the source. Fixed.

1. The references seem to have been broken between v0.1 and v0.2. References are mis-numbered and in the wrong order.

Hmm, regenerated. They look better now.

1. References to the Appendixes are broken ('The scripts for this can be found in 4' rather than 'The scripts for this can be found in appendix A' and 'as the commitment transaction in 4' instead of 'as the commitment transaction in appendix B')

Yep, fixed. Plus.

1. In v0.2, the conclusion can be updated: 'By using a dual anchor and escape transactions, channel establishment can also avoid new CHECKSIG flags, though it loses the important ability to outsoure the enforcement of channel contract terms.' to 'By using a rebalanced single anchor, channel establishment can also avoid new CHECKSIG flags, while retaining the important ability to outsource the enforcement of channel contract terms.'

The first half is correct, the second half is incorrect: we still need
new CHECKSIG flags to outsource contract terms.

1. I'd recommend that the 'Escape transactions' and 'Fast escape transactions' in appendix A get moved to appendix B now that dual anchors are not part of the current design.

Excellent point. Done.

I'll open a pull request for 3 and 7. The others are either:

• changes to .eps files. I'm afraid I don't know how to modify those.
• errors in whatever tool you used to generate the .pdf from the source files.

Oops, I should have applied that first, but I edited as I read this bug
report.

I've also been following along on the Lightning-dev mailing list, and see that there's been a lot of movement on state machines and routing since v0.2 of the documentation. Are there plans to update the paper to include information on those aspects? I'm happy to lend a hand if you think that'd be useful.

I think that the paper stands alone; there are many more areas to
document outside its scope however:

1. The protocol used for onion routing.
2. The cryptography used for inter-node communications.
3. The protocol and state machine used for inter-node communications.
4. The routing and fee protocols.

These are all in different stage of development though. The first two
should be getting some serious crypto review in the next few weeks. The
inter-node comms protocol seems fairly stable, but no doubt will change
as we actually try to interoperate. And the routing and fee protocols
are still being actively discussed.

But if you wanted to flesh out the very bare wiki, at least with ML
references, that would be a definite start!

Thanks,
Rusty.