Skip to content

Instantly share code, notes, and snippets.

@t-bast
Last active April 13, 2023 06:39
Show Gist options
  • Save t-bast/f4f5e6ba491b8e2bbe2f9c1d6c2bc0b5 to your computer and use it in GitHub Desktop.
Save t-bast/f4f5e6ba491b8e2bbe2f9c1d6c2bc0b5 to your computer and use it in GitHub Desktop.
Proposal to describe lightning protocol flows

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
@ddustin
Copy link

ddustin commented Apr 7, 2023

I like the clarity that labeling messages (node + msg index) brings.

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

@Roasbeef
Copy link

Twiddled a bit and got this:

  Alice                   Bob
    |                     |
    |                     |
    |                     |
    |                     |
    |-----\         /-----|
    |      \       /      |
    |       \     /       |
    |        \   /        |
    |         x           |
    |        /   \        |
    |       /     \       |
    |      /       \      |
    |-----/         \-----|
    |                     |
    |                     |

@Roasbeef
Copy link

Updated version, the label isn't quite right tho:
Screenshot 2023-04-10 at 2 31 21 PM

I think if I give it something like the above as a starting point (few shot example), then it would be able to use that as a template and take in as input a description. Then we can save that prompt template and use it for other stuff

@t-bast
Copy link
Author

t-bast commented Apr 11, 2023

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

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

Twiddled a bit and got this:

@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 😄

@ddustin
Copy link

ddustin commented Apr 12, 2023

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

image

@t-bast
Copy link
Author

t-bast commented Apr 13, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment