Present Credentials for Verification

Use the agent's stored credentials to present a cryptographic proof to a Verifier

The ProofExchangeModule provides the functionality needed to easily walk through the Decentralized Identity protocol flow for handling credential presentation requests and responding with the desired credentials & proofs. This module contains support for both Aries/DIDComm-based proof exchanges (e.g., after establishing an E2EE DIDComm connection with a verifier), and for OpenID4VC-based proof exchanges.

The functionality of the ProofExchangeModule is accessed via the agent's fields: agent.proofs.exchange. The functionality provided is described below.

Receive a Presentation Request

A ProofExchange (a pending presentation / proof in exchange) is created in the agent's wallet once a presentation request is received. Like CredentialExchange (see Accepting New Credentials), a ProofExchange can represent either an Aries or OpenID4VC protocol, this distinction is made via the variant of the ProofExchange (ProofExchange.Aries or ProofExchange.OpenId4Vc). Each of these variants contain further data specific to the protocol being used.

How a ProofExchange is initially received by the Edge Agent depends on the protocol being used (see below).

However regardless of the protocol, after a request is processed by the agent, a ProofExchange is created in the agent's wallet and can be accessed and used by the APIs mentioned below. If the agent is subscribed to agent events (see here), a new ProofExchange will invoke a proof update event.

Receiving an Aries Presentation Request

The agent receives Aries presentation requests as encrypted DIDComm messages, either through the receiveMessage API, or via the MessageSource of the agent's run loop. The presentation request must come from an established connection, and the ProofExchange.Aries will contain information about which connection the request came from.

Aries Proof Exchange Formats

Similar to Credential Exchanges, the ProofExchange.Aries object can represent different Aries proof exchange formats (see Standards and Protocols). ProofExchange.Aries contains a formatData field, which is a AriesProofExchangeFormatData data structure with variants for the different supported formats. Currently these format variants include:

• .Anoncred: contains the details of an Aries presentation exchange being performed with Aries Anoncreds or Indy Attachments. This format is used to exchange Anoncreds presentation requests & presentations. When the Edge Agent receives a ProofExchange request of this format, the SDK can select and present it's AnoncredV1 Credentials in response.

• .Dif: contains the details of an Aries presentation exchange being performed with a DIF Presentation Exchange. When the Edge Agent receives a ProofExchange request of this format, the SDK can select and present it's suitable Credentials in response.

The inner contents of these formatData objects particularly contains important details about what presentation items (requirements) which are being requested. In the case of Anoncreds, this may include groups of attributes and/or predicates that the verifier wishes to be presented (each with their own requirements). Or in the case of DIF, it will be a Presentation Definition, including several Input Descriptors that the verifier wishes to be presented (each with their own requirements).

In all cases, the inner data is structured in line with the relevant specifications. SDK consumers should make themselves familiar with these standard formats to understand how the presentation request data should be processed and/or displayed to the end application user.

Check out our sample apps for a reference on how these data formats can be processed in an application.

Receiving an OpenID4VC Presentation Request

The agent is capable of receiving OpenID4VP requests via the openid:// and openid4vp:// URL scheme through the receiveUrl API. The ProofExchange.OpenId4Vc will importantly contain details of; the verifier's ID (e.g. their DID), and the presentationRequest.

The presentationRequest contains the full DIF Presentation Definition describing the details of what the verifier wishes to be presented. This request very closely matches the Aries .Dif format variant discussed above, however OpenID4VP uses DIF Presentation Exchange V2 instead of V1, which contains a few minor breaking changes.

Finding Credentials for a Presentation

After receiving a ProofExchange in the REQUEST state, the consumer should query the agent to discover which credentials the agent has that will satisfy each item.

The retrieveCredentialsForProofRequest API, can be used for this. This API returns a RetrievedPresentationCredentials data structure to represent this.

RetrievedPresentationCredentials has variants depending on the ProofExchange presentation format that is being requested (DIF or Anoncred/Indy). Generally, the inner data of each variant maps the identifiers of the requested items to the IDs of Credentials that are suitable for presenting the requested item.

Protocol	Format	RetrievedPresentationCredentials
Aries	Anoncred	Anoncred
Aries	DIF (v1)	DIF
OpenID4VC	DIF (v2)	DIF

Credentials for an Anoncreds Presentation

When the retrieveCredentialsForProofRequest API is used on an .Anoncred formatted ProofExchange.Aries, it will return a RetrievedPresentationCredentials.Anoncred data object. This object contains:

• credentialsForRequestedAttributes: a map of requested attribute group referents/IDs, to the list of Credential IDs which may be used for presenting the attribute group. Attribute group IDs correspond to the referents in the AnoncredProofRequestInfo object of formatData.

• credentialsForRequestedPredicates: similar to above, this contains a map of requested predicate referents/IDs, to the list of Credential IDs which may be used for presenting the predicate.

• selfAttestableAttributes: a list of attribute referents/IDs which were requested for self-attestation. Unlike credentialsForRequestedAttributes, these requested attributes are to be self-attested by the agent; meaning any string value can be presented for these attributes. Attribute IDs correspond to the referents in the AnoncredProofRequestInfo object of formatData.

Swift

let agent: SudoDIEdgeAgent
let proofExchange: ProofExchange.Aries

do {
    guard case .anoncred(let anoncredsProofRequest) = proofExchange.formatData else {
        return
    }
    
    let suitableCreds = try await agent.proofs.exchange.retrieveCredentialsForProofRequest(
        proofExchangeId: proofExchange.proofExchangeId
    )
    guard case .anoncred(
        let credentialsForRequestedAttributes,
        let credentialsForRequestedPredicates,
        let selfAttestableAttributes
    ) = suitableCreds else {
        return
    }

    credentialsForRequestedAttributes.forEach { groupIdentifier, creds in
        let groupInfo = anoncredsProofRequest.requestedAttributes[groupIdentifier]!
        print("Attribute group \(groupInfo) can be presented with the following creds: \(creds)")
    }
    
    credentialsForRequestedPredicates.forEach { predicateId, creds in
        let predicateInfo = anoncredsProofRequest.requestedPredicates[predicateId]!
        print("predicate \(predicateInfo) can be presented with the following creds: \(creds)")
    }
    
    selfAttestableAttributes.forEach { attributeIdentifier in 
        let info = anoncredsProofRequest.requestedAttributes[attributeIdentifier]!
        print("Attribute \(info) should be self attested")
    }
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent
val proofExchange: ProofExchange.Aries

try {
    val anoncredData = proofExchange.formatData as? ProofExchangeFormatData.Anoncred ?: return
    val anoncredsProofRequest = anoncredData.proofRequest

    val suitableCreds = agent.proofs.exchange.retrieveCredentialsForProofRequest(
        proofExchange.proofExchangeId
    ) as RetrievedPresentationCredentials.Anoncred

    suitableCreds.credentialsForRequestedAttributes.forEach { (groupIdentifier, creds) ->
        val groupInfo = anoncredsProofRequest.requestedAttributes[groupIdentifier]!!
        println(
            "Attribute group '$groupInfo' can be presented with the following creds: $creds"
        )
    }
    suitableCreds.credentialsForRequestedPredicates.forEach { (predicateId, creds) ->
        val predicateInfo = anoncredsProofRequest.requestedPredicates[predicateId]!!
        println(
            "Predicate '$predicateInfo' can be presented with the following creds: $creds"
        )
    }
    suitableCreds.selfAttestableAttributes.forEach { (attributeIdentifier) ->
        val info = anoncredsProofRequest.requestedAttributes[attributeIdentifier]!!
        println(
            "Attribute '$info' should be self attested"
        )
    }
} catch (e: Exception) {
    // Handle exception
}

In the case where an agent holds no Credentials that are appropriate for a requested attribute group or predicate, a mapping to the referent will still be present, but will be mapped to an empty list.

Credentials for a DIF Presentation

When the retrieveCredentialsForProofRequest API is used on any ProofExchange.OpenId4Vc or on a .Dif formatted ProofExchange.Aries, it will return a RetrievedPresentationCredentials.Dif data object. This object contains:

• credentialsForRequestedDescriptors: a map of requested DIF Input Descriptor IDs, to the list of Credential IDs which may be used for presenting the input descriptor. Descriptor IDs correspond to the InputDescriptors within formatData.

Swift

let agent: SudoDIEdgeAgent
let proofExchange: ProofExchange.OpenId4Vc

do {
    let presentationDefinition = proofExchange.presentationRequest
    
    let suitableCreds = try await agent.proofs.exchange.retrieveCredentialsForProofRequest(
        proofExchangeId: proofExchange.proofExchangeId
    )
    guard case .dif(let credentialsForRequestedDescriptors) = suitableCreds else {
        return
    }

    credentialsForRequestedDescriptors.forEach { descriptorId, creds in
        let inputDescriptor = presentationDefinition.inputDescriptors.first { $0.id == descriptorId }!
        print("Input Descriptor \(inputDescriptor) can be presented with the following creds: \(creds)")
    }
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent
val proofExchange: ProofExchange.OpenId4Vc

try {
    val presentationDefinition = proofExchange.presentationRequest

    val suitableCreds = agent.proofs.exchange.retrieveCredentialsForProofRequest(
        proofExchange.proofExchangeId
    ) as RetrievedPresentationCredentials.Dif

    suitableCreds.credentialsForRequestedDescriptors.forEach { (descriptorId, creds) ->
        val inputDescriptor = presentationDefinition.inputDescriptors.first { it.id == descriptorId }
        println(
            "Input Descriptor '$inputDescriptor' can be presented with the following creds: $creds"
        )
    }
} catch (e: Exception) {
    // Handle exception
}

In the case where an agent holds no Credentials that are appropriate for a requested Input Descriptor, a mapping to the descriptor will still be present, but will be mapped to an empty list.

Presenting Credentials

After identifying credentials that are appropriate for presenting a proof exchange (see above section), the consumer must select a Credential to use for each requested presentation item. This selection is done by constructing a PresentationCredentials data object before passing it to the presentProof API where credential proofs will then be created and sent to the Verifier.

However, as before, the PresentationCredentials object has variants depending on the presentation exchange format being presented. The chosen variant should match the RetrievedPresentationCredentials variant.

Presenting for an Anoncreds Presentation

Like other APIs, if presenting an Anoncreds presentation, then the .Anoncred variant should be used. In this case, a PresentationCredentials.Anoncred data object should be constructed with the following data:

• credentialsForRequestedAttributes: a map of requested attribute group referents/IDs, to an AnoncredPresentationAttributeGroup object. This object contains the credentialId of the credential to present for the attribute group, and a revealed boolean flag. "revealed" is an Anoncreds zero-knowledge-proof feature: if revealed is set to false, the Verifier will receive proof of the Credential, without seeing any of the credential's attribute values.

• credentialsForRequestedPredicates: a map of requested predicate referents/IDs, to an AnoncredPresentationPredicate object. This object simply contains the credentialId of the credential to present for this predicate.

• selfAttestedAttributes: a map of self-attestable attribute referents/IDs, to a chosen string value (self attested value).

Swift

let agent: SudoDIEdgeAgent
let id: String // the id of the [ProofExchange]

do {
    let suitableCreds = try await agent.proofs.exchange.retrieveCredentialsForProofRequest(
        proofExchangeId: id
    )
    guard case .anoncred(
        let credentialsForRequestedAttributes,
        let credentialsForRequestedPredicates,
        let selfAttestableAttributes
    ) = suitableCreds else {
        return
    }
    
    let selectedCredsForRequestedAttributes = credentialsForRequestedAttributes.mapValues { creds in
        // auto-select the first credential for presentation
        AnoncredPresentationAttributeGroup(credentialId: creds[0], revealed: true)
    }
    
    let selectedCredsForRequestedPredicates = credentialsForRequestedPredicates.mapValues { creds in
        // auto-select the first credential for presentation
        AnoncredPresentationPredicate(credentialId: creds[0])
    }
    
    let selfAttestedAttributes = selfAttestableAttributes.reduce(into: [String: String]()) { map, referent in
        // auto-select a value
        map[referent] = "my attested value"
    }
    
    try await agent.proofs.exchange.presentProof(
        proofExchangeId: id,
        presentationCredentials: .anoncred(
            credentialsForRequestedAttributes: selectedCredsForRequestedAttributes,
            credentialsForRequestedPredicates: selectedCredsForRequestedPredicates,
            selfAttestedAttributes: selfAttestedAttributes
        )
    )
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent
val id: String // the id of the [ProofExchange]

try {
    val suitableCreds = agent.proofs.exchange.retrieveCredentialsForProofRequest(
        id
    ) as RetrievedPresentationCredentials.Anoncred

    val selectedCredsForRequestedAttributes =
        suitableCreds.credentialsForRequestedAttributes.mapValues { (_, creds) ->
            // auto-select the first credential for presentation
            AnoncredPresentationAttributeGroup(creds[0], revealed = true)
        }

    val selectedCredsForRequestedPredicates =
        suitableCreds.credentialsForRequestedPredicates.mapValues { (_, creds) ->
            // auto-select the first credential for presentation
            AnoncredPresentationPredicate(creds[0])
        }
    
    val selfAttestedAttributes =
        suitableCreds.selfAttestableAttributes.associateWith { referent -> "my attested value" }

    agent.proofs.exchange.presentProof(
        proofExchangeId = id,
        presentationCredentials = PresentationCredentials.Anoncred(
            credentialsForRequestedAttributes = selectedCredsForRequestedAttributes,
            credentialsForRequestedPredicates = selectedCredsForRequestedPredicates,
            selfAttestedAttributes = selfAttestedAttributes
        )
    )
} catch (e: Exception) {
    // Handle exception
}

For simplicity, this example assumes that there is at least 1 suitable credential for each attribute group and predicate. Additionally this example implements "auto-select", apps may wish to let their users manually select credentials. See our sample apps for a reference.

Presenting for a DIF Presentation

Like other APIs, if presenting a DIF presentation, then the .Dif variant should be used. In this case, a PresentationCredentials.Dif data object should be constructed with the following data:

• credentialsForDescriptors: a map of requested input descriptor IDs, to the ID of the Credential that should present the descriptor.

If possible, the Edge Agent SDK will automatically attempt to derive a selectively disclosed credential if the credential format and data allows (using BBS+ or SD-JWT). Meaning the agent will not present more data then necessary to the verifier; similar to Anoncreds.

See Aries RFC 0646 and Standards and Protocols.

Swift

let agent: SudoDIEdgeAgent
let id: String // the id of the [ProofExchange]

do {
    let suitableCreds = try await agent.proofs.exchange.retrieveCredentialsForProofRequest(
        proofExchangeId: id
    )
    guard case .dif(let credentialsForRequestedDescriptors) = suitableCreds else {
        return
    }
    
    let selectedCredsForDescriptors = credentialsForRequestedDescriptors.mapValues { creds in
        // auto-select the first credential for presentation
        creds[0]
    }
    
    try await agent.proofs.exchange.presentProof(
        proofExchangeId: id,
        presentationCredentials: .dif(
            credentialsForDescriptors: selectedCredsForDescriptors
        )
    )
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent
val id: String // the id of the [ProofExchange]

try {
    val suitableCreds = agent.proofs.exchange.retrieveCredentialsForProofRequest(
        id
    ) as RetrievedPresentationCredentials.Dif

    val selectedCredsForDescriptors =
        suitableCreds.credentialsForRequestedDescriptors.mapValues { (_, creds) ->
            // auto-select the first credential for presentation
            creds[0]
        }
    
    agent.proofs.exchange.presentProof(
        proofExchangeId = id,
        presentationCredentials = PresentationCredentials.Dif(
            credentialsForDescriptors = selectedCredsForDescriptors
        )
    )
} catch (e: Exception) {
    // Handle exception
}

For simplicity, this example assumes that there is at least 1 suitable credential for each input descriptor. Additionally this example implements "auto-select", apps may wish to let their users manually select credentials. See our sample apps for a reference.

Get a Pending Presentation by ID

As mentioned above, a pending presentation is represented by ProofExchange objects. To retrieve the current state of a specific ProofExchange in the agent's wallet, the getById API can be used. If a proof exchange cannot be found by the given ID, then null is returned:

Swift

let id: String // ID of the proof exchange to get ([ProofExchange.proofExchangeId])

do {
    let proofExchange = try await agent.proofs.exchange.getById(proofExchangeId: id)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the proof exchange to get ([ProofExchange.proofExchangeId])

launch {
    try {
        val proofExchange: ProofExchange? = agent.proofs.exchange.getById(id)
    } catch (e: ProofExchangeModule.GetException) {
        // Handle exception
    }
}

Delete a Pending Presentation by ID

Similarly, a ProofExchange in the wallet can be easily deleted via the deleteById API:

Swift

let id: String // ID of the proof exchange to delete ([ProofExchange.proofExchangeId])

do {
    try await agent.proofs.exchange.deleteById(proofExchangeId: id)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the proof exchange to delete ([ProofExchange.proofExchangeId])

launch {
    try {
        agent.proofs.exchange.deleteById(id)
    } catch (e: ProofExchangeModule.DeleteException) {
        // Handle exception
    }
}

Updating the Metadata of a Pending Presentation

ProofExchange objects contain some metadata that can be controlled by SDK consumers, allowing custom information to be attached to each ProofExchange, and allowing custom listing functionality to be leveraged.

Each ProofExchange contains a list of RecordTag (ProofExchange.tags) attached to it, where a RecordTag is simply a name-value pair stored with the record. By default, some tags are attached to new ProofExchanges, this includes:

• tag-name: ~started_timestamp, tag-value: The UNIX epoch seconds which this presentation began exchange

The tags on a ProofExchange can be replaced or updated by using the updateProofExchange API, and providing a new set to update. This will replace whatever the current set of tags is:

Swift

let id: String // ID of the proof exchange to update ([ProofExchange.proofExchangeId])

// add a 'category' of 'work' to this proof, and a 'priority' of '1'
let update = ProofExchangeUpdate(tags: [
    RecordTag(name: "category", value: "work"),
    RecordTag(name: "~priority", value: "1")
])

do {
    try await agent.proofs.exchange.updateProofExchange(proofExchangeId: id, proofExchangeUpdate: update)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the proof exchange to update ([ProofExchange.proofExchangeId])

// add a 'category' of 'work' to this proof, and a 'priority' of '1'
val update = ProofExchangeUpdate(
    tags = listOf(
         RecordTag("category", "work"),
         RecordTag("~priority", "1")   
    )
)

launch {
    try {
        agent.proofs.exchange.updateProofExchange(id, update)
    } catch (e: ProofExchangeModule.UpdateException) {
        // Handle exception
    }
}

Like most data in the wallet, RecordTag will be stored encrypted. Unless, the tag name is prefixed with ~, then the tag value will be stored unencrypted. Storing a tag value as unencrypted will allow some additional listing queries to be performed (see below).

Listing Pending Presentations

To list all pending presentations in the agent's wallet, the listAll API can be used:

Swift

do {
    let proofs = try await agent.proofs.exchange.listAll(options: nil)
} catch {
    // handle error
}

Kotlin

launch {
    try {
        val proofs: List<ProofExchange> = agent.proofs.exchange.listAll(null)
    } catch (e: ProofExchangeModule.ListException) {
        // Handle exception
    }
}

Filtered Listing

More complicated ProofExchange list queries can also be achieved by utilizing the ListProofExchangeFilters.

These filters allow for lists of ProofExchange to be filtered by; their state, by their tags, or filtered by both together.

Filtering by state can be achieved like so:

Swift

// get all the pending proofs which are waiting to be presented
let filters = ListProofExchangeFilters(state: ProofExchangeState.request)
let options = ListProofExchangeOptions(filters: filters)
    
do {
    let proofsPendingPresentation = try await agent.proofs.exchange.listAll(options: options)
} catch {
    // Handle error
}

Kotlin

// get all the pending proofs which are waiting to be presented
val filters = ListProofExchangeFilters(state = ProofExchangeState.Request)
val options = ListProofExchangeOptions(filters)
        
launch {
    try {
        val proofsPendingPresentation = agent.proofs.exchange.listAll(options)
    } catch (e: ProofExchangeModule.ListException) {
        // Handle exception
    }
}

To filter by tags applied to the ProofExchange (i.e. applied via the update API), the tagFilter field of ListProofExchangeFilters should be used. This field takes a String in compliance with a Wallet Query Language (WQL) Query.

Continuing from the example in the Update API section:

Swift

// WQL Query, filter for 'category' == 'work'
let wqlQuery = "{ \"category\": \"work\" }"
let filters = ListProofExchangeFilters(tagFilter: wqlQuery)
let options = ListProofExchangeOptions(filters: filters)
do {
    let pendingWorkProofs = try await agent.proofs.exchange.listAll(options: options)
} catch {
    // handle error
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
let wqlQuery = "{ \"~priority\": { \"$lt\": \"2\" } }"
let filters = ListProofExchangeFilters(tagFilter: wqlQuery)
let options = ListProofExchangeOptions(filters: filters)

do {
    let highPriorityPendingProofs = try await agent.proofs.exchange.listAll(options: options)
} catch {
    // Handle error
}

Kotlin

// WQL Query, filter for 'category' == 'work'
val wqlQuery = """{ "category": "work" }"""
val filters = ListProofExchangeFilters(tagFilter = wqlQuery)
val options = ListProofExchangeOptions(filters)

launch {
    try {
        val pendingWorkProofs = agent.proofs.exchange.listAll(options)
    } catch (e: ProofExchangeModule.ListException) {
        // Handle exception
    }
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
val wqlQuery = """{ "~priority": { "${"$"}lt": "2" } }"""
val filters = ListProofExchangeFilters(tagFilter = wqlQuery)
val options = ListProofExchangeOptions(filters)

launch {
    try {
        val highPriorityPendingProofs = agent.proofs.exchange.listAll(options)
    } catch (e: ProofExchangeModule.ListException) {
        // Handle exception
    }
}