Closed edeykholt closed 3 months ago
This would be better in mermaid so everyone can maintain/contribute and track changes to it.
@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:
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.
Pending open discussion in weekly call.
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.
Discussed on KERI/ACDC Call on 4/2/2024. Tabled for now.
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.
I analyzed this some more. Additional thoughts:
@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.
Preparing a pull request... https://github.com/trustoverip/tswg-acdc-specification/commit/95ec77ddbe503c068cad507a6502a9282655c338
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
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.
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](https://github.com/trustoverip/tswg-acdc-specification/assets/8242469/2052271f-fb44-453a-baa0-8ace94b00adf)