add a state protocol diagram after table introduction, early in Exchange Protocol section

[edeykholt]

Suggested content to add early in the Exchange Protocol section:
`

State Protocol Diagram

The following depicts the two roles for this protocol, the interactions between them, and UML state diagrams for each role. Note for a given instantiation of the protocol, each role may select one from multiple start states, and thus expecting certain interactions from the other role.`

https://lucid.app/lucidchart/747aee2b-120e-4d7e-971c-df8954874ce1/edit?viewport_loc=-150%2C-91%2C2304%2C1167%2C0_0&invitationId=inv_eb70ac41-ad96-48a8-98e8-02eff2bccd84

If that link doesn't work, use this: https://lucid.app/lucidchart/747aee2b-120e-4d7e-971c-df8954874ce1/view?invitationId=inv_eb70ac41-ad96-48a8-98e8-02eff2bccd84&page=0_0#

A PNG and an SVG Export of this from lucid.app are attached

.

[m00sey]

This would be better in mermaid so everyone can maintain/contribute and track changes to it.

[edeykholt]

@m00sey Mermaid can't draw multiple state machines on a single diagram, plus doesn't have the ability to show "send events" or messages between the two as arrows. There might be other text-to-diagram tools that would work.

The information in this diagram could alternately be presented as two state-transition type of tables (discloser and disclosee), perhaps expanding on the existing table in the IPEX section https://trustoverip.github.io/tswg-acdc-specification/#issuance-and-presentation-exchange-ipex.
When I drew this choreography diagram over two months ago, my initial motivation was to understand what was written at that time. It raised questions such as:

1. Is the diagram consistent with the spec IPEX section?
2. Does each role really need to know the initial intention (mapping to 3 start states) upon instantiation of a protocol instance?
3. For guiding interoperability testing discussions, is it helpful to name the states?
4. What about timeouts when one role waits too long in a state?

Addressing these types of questions can wait until there are two implementations of the IPEX protocol that need to be tested for interoperability. This could be in a interop testing guide, or they could be addressed upfront in a design discussion. I'd rather see that design discussion happen versus solving how to get this particular diagram (or table) into the spec.

[pfeairheller]

Pending open discussion in weekly call.

[edeykholt]

Updated diagram and table for discussion.

There would also be a similar Disclosee table.
Alternatively, there could be separate State and Transition tables for each, but this protocol is simple enough to combine into one per role.

The existing table in the spec would stay to specify the messages and content.

[pfeairheller]

Discussed on KERI/ACDC Call on 4/2/2024. Tabled for now.

[edeykholt]

The key insight for me during the call was that the intention for IPEX's interactions is to be more general-purpose than I previously understood and not intended to solve all the particulars of business problem such as the lifecycle of a credential (offer, create, exchange, present, ...). Perhaps reverse-engineering the reference implementation for vLEI credential issuance and modeling this would set up for future interoperability specifications.

Also having sequence diagrams of the IPEX protocol interactions (and vLEI credentials) would help visualize and confirm the common interactions.

[edeykholt]

I analyzed this some more. Additional thoughts:

• Phil suggested a few weeks ago the state names might be simpler and clearer with just the message verb (e.g. apply) being put in its past tense form (applied). Will consider that, and the fact that when an exchange message is received it often will need to go through a verification step, as well.
• Looked at the tests at https://github.com/WebOfTrust/keripy/blob/main/tests/vc/test_protocoling.py and believe there are some missing paths on this diagram not checked. Numbering the exchanges on the diagram might help future discussion.
• The latest diagram above is wrong in that it shows an ongoing service; however, the protocol states should be per-conversation, so closer to the diagram early in this conversation that has multiple start and end states.
• Adding tables for states and transitions is still a good idea. Then, the diagram could be optional and not even in the spec.
• I'd welcome help on any of this.

[edeykholt]

@kentbull and I had a working session to reconcile the keripy test with my understanding of the IPEX Exchange protocol table in the spec. He created a keripy branch with comments, here: https://github.com/kentbull/keripy/pull/2/files and will work issues with that test.
I'll continue working on the spec issues mentioned above.

[edeykholt]

[edeykholt]

Preparing a pull request... 95ec77d

[edeykholt]

Notes:
Rendered markdown (current at the moment, 2024-05-09, but not a stable link):
https://github.com/edeykholt/tswg-acdc-specification/blob/revised-format/spec/spec.md#exchange-protocol

2024-05-09 link to lucidchart as reference (not to be in spec):
https://lucid.app/lucidchart/747aee2b-120e-4d7e-971c-df8954874ce1/edit?invitationId=inv_eb70ac41-ad96-48a8-98e8-02eff2bccd84

[edeykholt]

Discussed on 5/14/2024 spec call. The work above documents the flow for contractually protected disclosure for the vLEI ecosystem as implemented in Keripy. See #103 for next steps.