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_lockedbefore sending her secondcommit_sig
- for example, when looking at Alice's side, we could invert the order of (2a) and (1b) to make her receive
@ddustin I'm not sure what you mean, can you clarify?
@Roasbeef I don't find that very easy to read...
It's also useful to include the message name (which we can't write in diagonal) and a message number.
Also, if you have many messages in your protocol flow, there is a ton of wasted vertical space :/
I'm a bit skeptical that this is the right way forward, I still like my proposal better 😄