WIP: 18 Create the draft data flow presentation document

[JensJelitto]

Issue: https://github.com/AnonCreds-WG/anoncreds-spec/issues/18

Not yet ready for review.

[JensJelitto]

@swcurran, @ArPhil : I have tried to semi-complete the presentation part and would like you to do a first review. There are several open questions that I have:

• Overall style: Does my approach match your style expectations?
• Nomenclature: should we use proof vs. presentation vs. verifiable presentation?
• Style: Should we use only examples in JSON format vs. "pseudo-code" where the "value" part describes the type (I have currently chosen the second approach).
• Detail: How much algorithmic detail / explanation needs to be added?

Since I'll be out next week I send the pull request now such that you have a chance to react to my high-level questions.

[JensJelitto]

@swcurran : I can't assign any reviewers, so please feel free to do so.

[swcurran]

Thanks, Jens -- looking forward to going through this. Sorry you can't make it Monday -- we'll talk about you. :-)

[swcurran]

Awesome work -- this is great. I'd be happy to merge it in the current state, with the understanding that there will be more details to come. Some of things that I found that will either need work, or discussion:

Editorial Details

• Need to add references to definition where appropriate throughout -- e.g. [[ref: SCHEMA]]. That's an easy pass after the content is nailed down.
• Need to identify definitions to be added to the terminology section, such as WQL.
• Need to see about the format of internal links that cross markdown files to make sure that they render correctly in the file spec. I'm not sure if they are right or wrong in this PR -- just that they have to be checked.
• I'd like to see some cleanup/consistency on acronyms, but that's just me being picky :-) - e.g. WQL, JSON and the like.

Discussion Points

• We need to decide on where the terms "presentation" and "proof" should be used. Historically, AnonCreds has used "proof" for the complete "verifiable presentation" (the entire data structure), whereas in the W3C world, there is a (capitalized) Verifiable Presentation data model, and the "proof" is the item in both the VC and VP data models that holds the signature(s) and signature(s) metadata.
• We need to decide where "AnonCreds" stops and the Indy implementation begins in this section. For example, is the collection of credentials that satisfy a proof request a part of the AnonCreds spec, or something that should be called out needs to be done, and left as an exercise for an implementer. We'll discuss this on the next AnonCreds meeting.
• I do think we need to include details about how one goes from a Proof Request and the credentials that will be used to satisfy the Proof Request to generate the Proof itself. I'm not sure if we do that by including the details in the specification or by pointing to the algorithms. Again, a point of discussion.

[ArPhil]

Thanks @JensJelitto, that looks really great!

I go along with what stephen commented. Since I noticed, that the names of functions and methods of the INDY (SDK) code were mentioned and shown explicitly, and also because I am currently working on the issuance part, I would like to raise the question (to you all and myself):

How much of these details do we want to have within the AnonCreds (1.0) spec?

I understand, that the AnonCreds 1.0 spec shows the "current as is" state of AnonCreds with INDY. Later versions of the spec shall be INDY agnostic. Nevertheless, I struggle to see the clear benefit / value for us in providing this level of detail to the reader, because

• I believe it is rather important what is happening in the flows, rather than where exactily (in the code) it is happening (although this is important for us while creating the spec in order to understand it)
• different tools use different kind of entry points for the INDY SDK. Some could use the rust code directly, some could use any kind of wrapper, which is available in different languages with slightly different method interfaces. Do we provide all variations to the reader?
• The (rust) method interfaces / signatures also contain very deep INDY specifics like command_handle or wallet_handle parameters.

Happy to hear / read what you think!

[swcurran]

@JensJelitto -- figured out what happened with the rendering. There is a file that lists the source (md) files in the spec, and since you removed one, the list of files contains a non-existent reference. I'm not the best at making a change to a PR (but I really should learn...), but in the meantime, this is what you need to do.

Please add the following edit to your PR:

• Open the file specs.json in the root folder
• Find the line with "data_flow_presentation.md", and replace it with:

        "data_flow_presentation_overview.md",
        "data_flow_presentation_create_request.md",
        "data_flow_presentation_create_presentation.md",
        "data_flow_presentation_verify.md",

I tested that with the instructions in the EditingThe Spec document and it again renders.

[JensJelitto]

@swcurran I have fixed spec.json and the links.