# DIDComm v2 Streamlined Presentation Exchange
> Note: I started from Stephen's work, then adapted it to DIDComm v2 and suggest some simplifications.

## Background

The PEx effort is focused on the process of a verifier sending a request for a presentation message to a prover, and the prover responding with a presentation that (crytopgraphically at least) satisfies the verifier's request. The request is a DIF Presentation Exchange presentation definition, and the response is a DIF Presentation Exchange presentation submission containing one or more verifiable presentations. Those are the only two messages allowed in the flow.

The WACI protocol specification's [Request/Share](https://identity.foundation/wallet-and-credential-interactions/#requestshare) section describes how that exchange is accomplished using that protocol with a challenge token (the request) and a callback to an HTTP endpoint for the response.

Within the set of protocols that make up Aries Interop Profile (AIP) 2.0 are two messages (Out of Band and Present Proof V2) that implement this same exchange on top of a DIDComm v1 connection using DIDComm v2 message envelopes. This document details the flow, including both the messages that are sent, a summary of the internal Aries agent processing that is occuring and the callouts to the business code (in Aries terms, the "controller" for the verfier and the prover). The internal processing notes are included to provide visibility into the message and protocol handling in the Aries frameworks to simplify the business processing layer. All of the cryptographic processing, identifier resolution, and message and protocol handling is handled by the Aries framework, and the business layer deals with send requests via an HTTP API to, and receiving events from, an Aries framework.

## Assumptions

- An out-of-band (non-Aries) communication channel is available between the verifier and the prover(s) sufficient to allow the verifier to provide a URL to the prover.
- Could be an email with a QR code to be scanned by a wallet and a link to be opened on a mobile device to be handled by a wallet
- Could be a web page displaying a QR code
- Could be a QR code printed by the verifier and posted
- The prover has a wallet app that is capable of executing Aries 2.0 protocols
- The prover has one or more credentials in an appropiate format needed to construct the presentation(s) to satisfy the request
- The verifier has an agent framework capable of executing Aries AIP 2.0 protocols
- The verifier can construct a DIF Presentation Exchange presentation definition and process a DIF Presentation Exchange presentation submission.

## Flow

### Summary

An Aries AIP 1.0 Connection-less presentation begins with a verifier creating an "out-of-band" invitiation message to be given to one or more provers. The invitiation is of the form that the specific presentation request (from [Aries RFC 0454 Present Proof V2](https://github.com/hyperledger/aries-rfcs/tree/master/features/0454-present-proof-v2)) in a message to the invitee is included (as an attachment or link to an attachment) in the invitation and the DIDComm service block to which the response is to be sent is either resolvable (from a DID) or inline in the invitation. The presentation request message itself includes an attachment that provides the details of the presentation requested based on the desired verifiable credentials format(s) (e.g. Indy and/or JSON-LD and/or BBS+).

The invitation may be created specifically for one invitee or to be shared with many invitees, perhaps by posting it in a public place. The invitation message is made available to the wallet via some "out-of-band" communication channel, a URL, a shortened-URL, a QR code of the URL/shortened-URL, etc.

The prover's wallet (somehow) receives the invitation, extracts/resolves the attached "Request Presentation" message and processes it. That involves searching the wallet secure storage to find the credentials that satisfy the request. The wallet might also check to see if any of the candidate credentials have been revoked. A user interface opens to offer the Prover (e.g. the person) the opportunity to review the submission, make any decisions about the credentials to share, and if the presentation should be sent to the verifier. "Decisions" in this case would be needed if the automated credential search determined more than one way to satisfy the request. The Prover adjusts as needed the response, and agrees to deliver the presentation. Again, an attachment to the message contains the presentation in a format that satisifies the presentation request.

The prover wallet uses the DIDComm information in (or resolved from) the invitation to prepare and send the message to the verifier. That includes at least the encryption key(s) to use for preparing the message and envelope(s), and a physical endpoint to which the message is to be delivered. The `id` field from the invitation is used as the parent thread ID (`pthid`) for the response message so that the verifier has some context for processing the message.

The verifier receives the response and uses the `pthid` to associate the response with the invitation to which it is related, and passes the message and context to a message handler. The presentation is processed and the verifiable presentation(s) is/are verified.

Since no DIDComm connection is established between the prover and verifier, a response from the verifier cannot be sent back to the prover. As such, the verifier's action following the verification is communicated in some other way -- for example, as a message to a person monitoring the verifications at a point of entry, who can allow the Prover to continue or not.

### DID and DID Document Requirements
DIDs can by any method that supports the required key types and a service block of the following format:

"service": [{
    "id": "#someid",
    "type": "didcommmessaging",
    "serviceEndpoint": "https://example.com/endpoint",
    "routingKeys": ["did:example:somemediator#somekey"]
  }]

If ledger reliance is an issue, [Peer DIDs](https://identity.foundation/peer-did-method-spec/#generation-method) (particularly method 2) may be used.

### Verifier: Create Out-of-Band "Request Presentation Message" Invitation

An out of band invitation is created by the verifier that includes a presentation request message. The layers of this message are defined in this section.

#### Invitation JSON and Notes

{
  "type": "https://didcomm.org/out-of-band/2.0/invitation",
  "id": "<id used for context as pthid>",
  "body": {
      "goal_code": "streamlined-vp",
      "accept": ["didcomm/v2"],
      "services": ["did:example:verifier"]
  }
}

- The message is sent as plaintext, so there is no DIDComm encryption envelope involved in the message.
- The `streamlined-vp` signals to the Prover what is desired.
- Items of the `services` array are DIDs. Peer DIDs may be used to avoid the need of recording anything on a ledger.

> Note: For the purpose of the streamlined flow, a maximum of 1 mediator will be used in the service block.

Upon receipt (scanning) of this message, the Prover knows that the Verifier desires a credential. The actual credential request is large, and so retrieved as part of the flow.

### Verifier: Display QR Code

The invitation must be conveyed (somehow) to the Prover. Often this is done by converting the invitation into an HTTP URL, possibly shortened, and then into a QR code for display or printing. The encoding into URL and QR code is defined [here](https://github.com/hyperledger/aries-rfcs/tree/master/features/0434-outofband#standard-out-of-band-message-encoding) in Aries RFC 0434 Out-of-Band. In the same RFC, the URL shortening is formalized [here](https://github.com/hyperledger/aries-rfcs/tree/master/features/0434-outofband#url-shortening).

Notes:

- The generation of the invitation may be deferred to shortened URL resolution, allowing a common QR code to be used, but a uniquely identified message sent to each wallet scanning the QR code.
- The encoded HTTP URL could be displayed as a link in an email.
- Things get tricky if the user is browsing on their smartphone when trying to consume the invitation. A convention of using a `didcomm` protocol has been used to have the mobile OS launch a wallet to handle the link. #helpwanted!!

### Prover: Receive Invitation

The prover receives the invitation message and processes it. Generally, an Aries framework will have a message dispatcher to handle the common elements of processing a message.

- Unpacking the envelope (not needed in this case because the message is plaintext).
- Detecting the thread and finding the protocol state (not needed in this case because this is the first message of the thread).
- Finding and processing any high-level decorators (may be used with this message to do the attachment handling -- resolving links, decoding base64 -- as needed).
- Detecting the message type and dispatching it to the appropriate message handler. In this case, it would go to the Out-of-Band "Invitation" handler, which in turn would do some processing and pass the attached `request-presentation` message to the Present Proof "request-presentation" message handler.

In processing the invitation, the out-of-band handler, a connection object would be created for holding the verifier's DIDComm invitation. As needed, the `services` DID would be resolved, and the DIDComm service block persisted, with the ID for the connection included with protocol state information passed to the `request-presentation` message handler.

### Prover: Propose Presentation

prover reaches out to verifier to see what they want, and receive nonce info {**<--s/ nonce info /challenge for signing a VP/? __jc**}.

{
    "type": "https://didcomm.org/present-proof/3.0/propose-presentation",
    "id": "<message unique id>",
    "pthid": "<id present in invitation>",
    "from": "did:example:prover",
    "to": "did:example:verifier"
}

The verifier can tell which link or QR code this came from by correlating the `pthid` of this message with the `id` of the invitation message.

> The propose-presentation message often contains details about what the prover thinks they should present, but it can also be blank to indicate just that they want to start that conversation

### Verifier: Request Presentation

verifier returns what the presentation defintion they want.

{
  "type": "https://didcomm.org/present-proof/3.0/request-presentation",
  "id": "0ac534c8-98ed-4fe3-8a41-3600775e1e92",
  "from": "did:example:verifier",
  "to": "did:example:prover",
  "body": {},
  "attachments": [
    {
      "id": "ed7d9b1f-9eed-4bde-b81c-3aa7485cf947",
      "mime_type": "application/json",
      "format": "dif/presentation-exchange/definitions@v1.0",
      "data": {
        "json": {
          "dif": {
            "options": {
              "challenge": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
              "domain": "4jt78h47fh47"
            },
            "presentation_definition": {

            }
          }
        }
      }
    }
  ]
}

Notes:

- The attachment payload contains a DIF Presentation Exchange document, per [Aries RFC 0510 DIF Presentation Exchange](https://github.com/hyperledger/aries-rfcs/tree/master/features/0510-dif-pres-exch-attach), which in turn points to version 1.0.0 of the [DIF Presentation Exchange specification](https://identity.foundation/presentation-exchange/).

### Prover: Prepare Presentation

Within the "request-presentation" message handler, the message would be processed, as (more or less) follows.

- Process the header of the message, extract the per request format type attachments and decide on which to process, based on the capabilities of the wallet--notably the verifiable credential formats supported.
- In this case, the DIF PE attachment is presumed to be supported and processed.
- Process the DIF PE and search in wallet storage for the credential(s) that satisfies the request.
- Determine what options are available to the wallet owner in sending the response.
- At minimum, there is the question "Do you want to respond?"
- As well there may be multiple ways of responding to the presentation, e.g. multiple credentials in the wallet storage that satisfy the request.
- If the presentation is to be sent, the [RFC 0454 Present Proof `presentation` message](https://github.com/hyperledger/aries-rfcs/tree/master/features/0454-present-proof-v2#presentation) is prepared and sent.

A generalized Aries message handler may serialize and persist an in-flight protocol state object as part of sending the request to a User Interface for a response from the wallet owner. The response would be received back as an event to the general dispatcher, much as described in the [section above](#Prover-Receive-Invitation) when the invitation was received and processed.

#### Presentation Message JSON and Notes

The following is an example of a full `presentation` message. This JSON shows an Aries messsage, with an attachment of a presentation using DIF Presentation Exchange document with the an array of (one, in this example) Verifiable Presentations and a `presentation_submission` item that describes what is being provided.

{
  "type": "https://didcomm.org/present-proof/3.0/presentation",
  "id": "f1ca8245-ab2d-4d9c-8d7d-94bf310314ef",
  "from": "did:example:verifier",
  "to": "did:example:prover",
  "body": {},
  "attachments": [
    {
      "@id": "2a3f1c4c-623c-44e6-b159-179048c51260",
      "mime-type": "application/ld+json",
      "format": "dif/presentation-exchange/submission@v1.0",
      "data": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1"
        ],
        "type": [
          "VerifiablePresentation"
        ],
        "verifiableCredential": [
          {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://w3id.org/citizenship/v1",
              "https://w3id.org/security/bbs/v1"
            ],
            "id": "https://issuer.oidp.uscis.gov/credentials/83627465",
            "type": [
              "PermanentResidentCard",
              "VerifiableCredential"
            ],
            "credentialSubject": {
              "id": "did:sov:4QxzWk3ajdnEA37NdNU5Kt",
              "type": [
                "Person",
                "PermanentResident"
              ],
              "givenName": "JOHN"
            },
            "issuanceDate": "2010-01-01T19:53:24Z",
            "issuer": "did:key:zUC72DsuZqSbiiLLydyssCW82PMjn25VNNXguv6irxuB4LNAu145PE9iG2qbYgzPuGTwhbSmDwmcTDu677VKH7w9PkcRxZPtGD2RgZ9ACQEPCs1bZyrk8RRDpuCTUr4F6ETeQQP",
            "proof": {
              "type": "BbsBlsSignatureProof2020",
              "nonce": "W0HJw8OvyFonxWDnz1npXVn1u4JWqkVoS1493CDQFVVOChGKuVaxOzAahX7v5r6MzS0=",
              "proofValue": "ABkBuAaPsfObokMu/zsmoRpoBhiQdpRNm3Q9dzm6Nj6wpnIfosYhkDHyIdkmC8D3YUFe6CvvkAvUauxu1jMpA2A1haPHu2D4/BqoNseCIEE6Fqmuy1BFkbdTYqC9g+KTx5tnPnvngG7RrYiMvHX9xcci8vmM6sMlZD6hJGpJoVVGgg0wHFP+IIQDi+B20T6QaJwSSMzWAAAAdIlPi49Usfp2/9ycjA9WFLhALC7G2R/vgUk/taRMRNDVIROXNzCIJuqAeZvoBX9xKAAAAAI0Obo9NqWhCCkJHEyaezmwnuZ52yKKPcHM6uISt2zrV17Mvc2nqLN+I1JjIHoTlNQ4F5WwBxxBmaCrrrhAtyDylje7JwQNQWoIVRUb3i7LFcg6ZYGG50Rap8FXHX7yO5ryGVUxjiPaz+qqE5njmYrzAAAAD3J10bdmab+ASYKM9RoJJ8YwAQmgsnfwuZv4GYm4xzaTV0FlTvqOzqc9Fa5zW0amz4r5ozvZY94mXksKQilUVFEQr4uUKH5dFlagmOjCelrlVGmMXOzEWkPzH7OH70GxET5e3qqf3pec3ny541jMj/8+8FwHwnTR4gdHDrweqZnBUQNblPY3cHxekXgE2H+xUTq0fZxGO0ghrVQE/prqka1DpiZpou3FwIYftP8ecLJ0k8DCCKcDlT6Y7hO0NW4tQz2KM72BnzOR+hdBoRI28uZKNv4OkI522LtaI2RYSnvWMBA/jXieR+wsUwxp9GOEo0/rJ0IVgwrEATdg+IDNp2McmZaVmF9BM2IScpzEpKbZlO3aY8NcCvfxkl6615JrLDqOBxLXX4RbKxIw22Fy4tFkjlyKRCilPvb0/vXRRnDaJhoQWmzEcsvMFtuJUSLNcX0Yktg9AC5JYPUqyPVMbV0qCtFWKAb4kwZRlJF4WBm5alvY37hLa/DTFymmwo7EsxlkNrHxjPyvM4OpzUA5DP1T9nETNGvwoYX7Ovl+na6ucZ1HF6MxE54EppLfFZHCulvU2OsSmsZ6XV7NCTJ4+QozNpvyqHS93oAiIabt20oRR6i9d4N8N0iRtB+ffNBV0Q==",
              "verificationMethod": "did:key:zUC72DsuZqSbiiLLydyssCW82PMjn25VNNXguv6irxuB4LNAu145PE9iG2qbYgzPuGTwhbSmDwmcTDu677VKH7w9PkcRxZPtGD2RgZ9ACQEPCs1bZyrk8RRDpuCTUr4F6ETeQQP#zUC72DsuZqSbiiLLydyssCW82PMjn25VNNXguv6irxuB4LNAu145PE9iG2qbYgzPuGTwhbSmDwmcTDu677VKH7w9PkcRxZPtGD2RgZ9ACQEPCs1bZyrk8RRDpuCTUr4F6ETeQQP",
              "proofPurpose": "assertionMethod",
              "created": "2021-05-14T20:16:05.457334"
            }
          }
        ],
        "presentation_submission": {
          "id": "1d257c50-454f-4c96-a273-c5368e01fe63",
          "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0654",
          "descriptor_map": [
            {
              "id": "citizenship_input_1",
              "format": "ldp_vp",
              "path": "$.verifiableCredential[0]"
            }
          ]
        },
        "proof": {
          "type": "Ed25519Signature2018",
          "verificationMethod": "did:sov:4QxzWk3ajdnEA37NdNU5Kt#key-1",
          "created": "2021-05-14T20:16:29.565377",
          "proofPurpose": "authentication",
          "challenge": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
          "jws": "eyJhbGciOiAiRWREU0EiLCAiYjY0IjogZmFsc2UsICJjcml0IjogWyJiNjQiXX0..7M9LwdJR1_SQayHIWVHF5eSSRhbVsrjQHKUrfRhRRrlbuKlggm8mm_4EI_kTPeBpalQWiGiyCb_0OWFPtn2wAQ"
        }
      }
    }
  ]
}

Notes:

- Everything up to `presentations~attach` is an [Aries RFC 0454 Present Proof V2 `presentation`](https://github.com/hyperledger/aries-rfcs/tree/master/features/0454-present-proof-v2#presentation) message. Check the RFC for the details about the items in the JSON, optional fields and so on.
- Everything after `presentations~attach` is a standard Aries RFC 0017 Attachment, with the payload (the `json` item value) the presentation (see next bullet item). As with the invitation attachment, this attachment could be `json`, `base64` or (extremely unlikely) `links` to HTTP(S) URLs.
- The attachment payload contains a DIF Presentation Exchange presentation document, per [Aries RFC 0510 DIF Presentation Exchange](https://github.com/hyperledger/aries-rfcs/tree/master/features/0510-dif-pres-exch-attach), which in turn points to version 1.0.0 of the [DIF Presentation Exchange specification](https://identity.foundation/presentation-exchange/).
- There is one `verifiable presentation` in the document, a signature over the array of (one) presentations, and the `presentation_submission` that relates to the requested `presentation_definition` that shows how the request was satisfied. While this example is a very simple version of a Presentation Exchange, they can get significantly more complicated.

### Prover: Send Presentation

The prepared `presentation` message is included in the protocol state object and passed to an outbound message dispatcher. The outbound message dispatcher takes the message, gets the required connection object, prepares and sends the message in the necessary DIDComm envelope(s). Once prepared the message would be sent to the requested endpoint over the requested transport protocol--as defined in the verifier's DIDComm service block.

#### Send Presentation Envelope JSON and Notes

The DIDComm envelope is prepared, encrypting and wrapping the payload (the `presentation` message) for the verifier. The DIDComm service block provided by the verifier is used to prepare the envelope(s).

@TelegramSam -- can you add the JSON and notes in the style above.

### Verifier: Receive Presentation

The verifier receives the DIDcomm message and processes it. This is the same process with different data as described in the [Receive Invitation](#) section above.

- Unpack the envelope.
- Detect the thread and finding the protocol state object. Within the thread, the `pthid` (parent thread ID) should match an invitation ID previously prepared by the verfier. That ID should provide sufficient state for the remainder of the flow.
- Find and process any high-level decorators (may be used with this message to do the attachment handling -- e.g. decoding base64 -- as needed).
- Detect the message type and dispatch the message and protocol state object to the appropriate message handler. In this case, it would go to the Present Proof V2 "presentation" handler.

### Verifier: Verify Presentation

The "presentation" message handler would use the protocol state object to provide access to the presentation request data, and process the message to extract the DIF Presentation Exchange (PE) data. This includes verifying each of the verifiable presentations (as required) and verifying the PE proof. The verification statuses (true, false) and the presentation is then passed to the verifier business logic to act on the statues and claims data as needed.

Note that since there was no DIDComm connection established with the prover, the verifier has no way to back the result of the processing -- success or failure.

## References

- RFC 434 Out of Band
- Invitation
- Presentation Request attachment
- URL Shortening
- RFC 454 Present Proof V2
- Presentation Request Message
- Presentation Message