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

edeykholt commented 7 months ago

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 KERI IPEX Protocol .

m00sey commented 6 months ago

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

edeykholt commented 6 months ago

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

Is the diagram consistent with the spec IPEX section?
Does each role really need to know the initial intention (mapping to 3 start states) upon instantiation of a protocol instance?
For guiding interoperability testing discussions, is it helpful to name the states?
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 commented 5 months ago

Pending open discussion in weekly call.

edeykholt commented 5 months ago

Updated diagram and table for discussion. IPEX 20240401a

Discloser state-transition table

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 commented 5 months ago

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

edeykholt commented 5 months ago

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 commented 4 months ago

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.