Proposal to describe lightning protocol flows

protocol-flows.md

Protocol flow representation

Representing message flows for lightning protocols is hard, because we're not using turn-based protocols: peers may be sending messages at the same time. It is very useful though to find a suitable way of representing protocol flows, to be able to discuss edge cases and implement the corresponding test cases.

The following diagram perfectly represents the fact that messages can be interleaved. There is no way to misinterpret it since Bolt 8 guarantees that messages are ordered. But it is hard for the reader to match a received message with the place where it was sent.

   Alice                                                    Bob
     |                                                       |
     |   commit_sig                          splice_locked   |
     |--------------------->           <---------------------|
     |   commit_sig                             commit_sig   |
     |--------------------->           --------------------->|
     |   splice_locked                      revoke_and_ack   |
     |<---------------------           <---------------------|
     |   revoke_and_ack                         commit_sig   |
     |<---------------------           --------------------->|

If we try to make continuous line from the sender to the receiver, it is unmanageable and impossible to read as well. But a simple trick is to number each message: that visual clue can be enough to help the reader. This is the same diagram with those numbers added:

   Alice                                                    Bob
     |                                                       |
     |   commit_sig (1a)                  splice_locked (1b) |
     |--------------------->           <---------------------|
     |   commit_sig (2a)                     commit_sig (1a) |
     |--------------------->           --------------------->|
     |   splice_locked (1b)              revoke_and_ack (2b) |
     |<---------------------           <---------------------|
     |   revoke_and_ack (2b)                 commit_sig (2a) |
     |<---------------------           --------------------->|

There are several advantages to this representation:

• it is easy to check for correctness, we simply need to look at the message numbers on both sides
  • they must be correctly ordered
  • no intermediate number can be missing
  • if that's not the case, the writer has made a mistake and can easily spot it and correct it
• it is easy to look at each side independently, and create test cases from the diagram
• it is easy to discuss specific steps (e.g. "when Bob receives (1a) he should do XXX")
• it is easy to automatically create variations:
  • for example, when looking at Alice's side, we could invert the order of (2a) and (1b) to make her receive splice_locked before sending her second commit_sig

How would Bob’s side be drawn next to Alice?

@ddustin I'm not sure what you mean, can you clarify?

Ah I was just viewing it on mobile. The right side appeared cut off -- I see it now

Hah ok that makes sense!
I haven't worked on the "optimized for mobile devices" experience yet 😆