Proof Exchanges

Manage proof exchanges, also known as presentation exchanges, using Aries protocols

A proof exchange, represented by AIPProofExchange, is an encapsulation of the cloud agent's progress in either sending or receiving a credential presentation over an established DIDComm connection.

Proof Exchange Roles & States

An AIPProofExchange has a role (known as myRole) and a state associated with it.

Role

The role indicates which role the cloud agent plays in the proof exchange protocol. The role is fixed for the lifetime of the proof exchange.

Role is either:

VERIFIER or PROVER

State

The state indicates the current state of the cloud agent in the proof exchange protocol. The state transitions over time in a forward direction and cannot transition to previous states.

State transitions to success:

REQUEST -> PRESENTED -> DONE

PROPOSAL -> REQUEST -> PRESENTED -> DONE

Summary

The following table provides a description of each role and each role+state combination.

Role	State	Description
VERIFIER		The cloud agent is acting as the verifier of the credential presentation.
	PROPOSAL	The connection proposed that it send a presentation to the cloud agent for verification.
	REQUEST	The cloud agent sent a proof request (also known as a presentation request) to the connection. If this state was preceded by PROPOSAL, then the request may be based on the connection's proposal.
	PRESENTED	The cloud agent received the presentation from the connection.
	DONE	Terminal state for a successful proof exchange. The received presentation has undergone verification. Note that this state does not indicate the result of the verification. To check the verification result, see verificationResult on the AIPProofPresentation message which is embedded within the AIPProofExchange.
	ABANDONED	Terminal state for an unsuccessful proof exchange. The cloud agent did not receive a presentation from the connection.
PROVER		The cloud agent is acting as the prover (also known as the holder or the presenter). The cloud agent will generate and send a verifiable presentation using one or more of its held credentials as a base.
	PROPOSAL	The cloud agent proposed that it send a presentation to a connection for verification.
	REQUEST	The cloud agent received a proof request (also known as a presentation request) from the connection. If this state was preceded by PROPOSAL, then the request may be based on the cloud agent's proposal.
	PRESENTED	The cloud agent sent the presentation to the connection.
	DONE	Terminal state for a successful proof exchange. Note that the cloud agent with the role of PROVER does not receive any indication of the verification result.
	ABANDONED	Terminal state for an unsuccessful proof exchange. The cloud agent did not send a presentation to the connection.

Supported credential presentation formats

The cloud agent supports proof exchanges for both Anoncreds Verifiable Presentations and W3C Verifiable Presentations. The credential presentation format for the specific proof exchange is specified using the format nested object.

Request proof

The cloud agent creates a new AIPProofExchange with role VERIFIER and send a proof request to the specified connectionId. The format input object must be filled with the details of the presentation to request.

A referent must be included for each set of attributes requested. The referent acts as an identifier for a set of attributes, and the prover must reference it in their subsequent presentation. If more than one referent appears in the same proof request, the prover will be able to present a different credential per referent.

mutation MyMutation {
  sendAipProofRequest(
    connectionId: "001fe530-3562-41d6-a631-3df9c7ae1f38"
    request: {
      format: {
        # INSERT DETAILS OF THE PRESENTATION TO REQUEST
      }
    }
  ) {
    id
    myRole
    state
    connectionId
  }
}

If instead the cloud agent receives a proof request, a new AIPProofExchange is created with role PROVER.

View received proof requests

View proof exchanges in any state, with pagination and filtering options. Returns a nextToken which can be passed into the same query in order to fetch subsequent pages.

As an example, the filter options can be used to find received proof requests, even from a specific connection.

query MyQuery {
  aipProofExchanges(
    page: {
      nextToken: null
    }
    filter: {
      myProofExRole: PROVER
      proofExStates: [REQUEST]
      connectionIds: ["001fe530-3562-41d6-a631-3df9c7ae1f38"]
    }
  ) {
    items {
      id
      myRole
      state
      messages {
        request {
          comment
          format {
            __typename
            ... on AnoncredsProofRequest {
              attributeGroups {
                referent
                attributeNames
                restrictions {
                  schemaId
                  schemaIssuerId
                  schemaName
                  schemaVersion
                  credDefId
                  issuerId
                  attributeNames
                  attributeValues {
                    name
                    value
                  }
                  nonRevoked {
                    from
                    to
                  }
                  predicate {
                    operator
                    threshold
                  }
                }
              }
            }
            ... on W3CProofNegotiation {
              attributeGroups {
                referent
                attributes {
                  attributePaths
                  valueRestrictions {
                    dataFormat
                    pattern
                    inSet
                    notInSet
                    equal
                    notEqual
                    minLength
                    maxLength
                    lessThan
                    lessThanOrEqual
                    greaterThan
                    greaterThanOrEqual
                  }
                  isHolderSubject
                  presentationType
                }
              }
              submissionRequirementJsons
            }
          }
        }
      }
      connectionId
    }
    nextToken
  }
}

Alternatively, view a single proof exchange, referenced by its unique ID.

query MyQuery {
  aipProofExchange(
    proofExId: "44269eb7-0288-46ad-ab59-e646ad010202"
  ) {
    id
    myRole
    state
    connectionId
  }
}

Accept a proof request

Before accepting the proof request, the cloud agent must select which credentials to use in the presentation. The following call can be used to quickly identify held credentials which are valid for selection. The returned referent maps each set of credential IDs to a referent in the proof request. The array of returned credentialIds will be empty if the cloud agent does not possess any valid credential for that referent.

mutation MyMutation {
  credentialsForAipProofExchange(
    proofExId: "44269eb7-0288-46ad-ab59-e646ad010202"
  ) {
    credentialsForReferents {
      referent
      credentialIds
    }
  }
}

The cloud agent accepts the request by generating the presentation and sending it to the connection. The input param proofExId must match the ID of an AIPProofExchange which has the PROVER role and is in the REQUEST state. Once the cloud agent with PROVER role has accepted a proof request, there is nothing left for it to do in the exchange.

mutation MyMutation {
  acceptAipProofRequest(
    proofExId: "44269eb7-0288-46ad-ab59-e646ad010202"
    presentation: {
      format: {
        # INSERT DETAILS OF THE PRESENTATION TO SEND
      }
    }
  ) {
    id
    myRole
    state
    connectionId
  }
}

Delete a proof exchange

Delete a proof exchange. This will send a "problem report" to the associated connection to inform them that the cloud agent has abandoned the proof exchange.

mutation MyMutation {
  deleteAipProofExchange(
    credExId: "44269eb7-0288-46ad-ab59-e646ad010202"
  )
}