> # RFC 0028 - Enabling Resource Discovery using the Introduction Protocol

## Purpose of this document
This document describes how SSI Agents can request introductions to parties that satisfy criteria of their own choosing. Specifically, the aim is to extend the [`Introduce Protocol`](https://github.com/hyperledger/aries-rfcs/blob/master/features/0028-introduce/README.md) to support selection criteria in a *machine-readable* way to enable resource discovery.

This document springs forth from the discussion started in https://github.com/hyperledger/aries-rfcs/issues/99.

## Motivation
The `Introduce Protocol` ([RFC-0028](https://github.com/hyperledger/aries-rfcs/blob/master/features/0028-introduce/README.md)) connects together two parties with no prior knowledge of each other. One of those ways involves an Introducee requesting another party (the eventual Introducer) for an introduction to a third party who as-of-yet remains unknown to the Introducee.

This is a classic case of *resource discovery* in an [unstructured peer-to-peer network](https://en.wikipedia.org/wiki/Peer-to-peer#Routing_and_resource_discovery). Extending the Introduce Protocol to support resource discovery in a way that can be readily understood by machines increases efficiency and greatly improves the user's experience. Both aspects lead to greater user retention and higher network throughputs.

There are many reasons why the User's Agent may not hold the credentials being requested for:

* The User might be acting as representative of another entity
* The User might be storing their credentials elsewhere (no honeypot)
* The User's credentials evolve periodically, requiring a direct query to the source (eg. credit score)
* The Relying Party requires a third party to "vouch" for the User and the vetting process consists of several challenges (reference in a resume)

... and many more.

## The Selection Criteria

A technical specification for the structure of the criteria is out of scope of this document. At this early stage of the Agent ecosystem we would rather adopt the "generic attachment with implementation-specific payload" pattern used in other RFCs. See examples [`request-presentation`](https://github.com/hyperledger/aries-rfcs/tree/master/features/0037-present-proof#request-presentation) and [`request-credential`](https://github.com/hyperledger/aries-rfcs/tree/master/features/0036-issue-credential#request-credential).

This is the proposed structure for the `request` message of the `Introduce Protocol`:

{
  "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/introduce/1.0/request",
  "@id": "df3b699d-3aa9-4fd0-bb67-49594da545bd",
  "please_introduce_to": {
    "description": "To process your credit card application.",
    "criteria~attach": {
      "mime-type": "application/json",
      "data": {
        "base64": "base64 encoding" 
      }
    }
  },
}

This is an example of what a network-specific payload for criteria would look like when base64-decoded:

{
  "queryExpression": {
    "type": "select",
    "name": "drivers_license",
    "fields": [
      "given_name",
      "family_name"
    ]
  }
}

#### A note on the variety of formats

DIDComm is intended to be interoperable among all SSI Agents operating across all identity networks. Providing a technical specification for expressing the criteria is challenging considering that the nascent SSI Agent ecosystem is fairly young, with most implementations being merely proofs of concepts and sandboxes.

Here are some ways in which selection criteria are being structured:

* [Credentials Requests](https://jolocom-lib.readthedocs.io/en/latest/interactionFlows.html#credential-requests) (Jolocom)
* [Requesting Specific Credentials](https://developer.uport.me/guides/requestcredentials#requesting-specific-credentials) (uPort)
* `indy_prover_create_credential_req` and `indy_prover_search_credentials_for_proof_req` in [Hyperledger Indy SDK](https://hyperledger-indy.readthedocs.io/projects/sdk/en/latest/docs/design/002-anoncreds/README.html#anoncreds-workflow)

## Protocol States

Having the Introducee include selection criteria in their request now places additional burden on the Introducer:

1. The Introducer must honor the request and search for matching candidates.
2. Because there are now certain expectations on the outcome, the Introducer must inform the Introducee of any subset of the criteria that cannot be satisfied for any reason.
3. Since the criteria may be satisfied by a group of candidates in aggregate - as opposed to a single party satisfying all criteria - then this would result in multiple rounds of introductions.

### 1. Introducer searches for matching candidates

Exactly _how_ the Introducer performs the search for matching candidates remains out of scope of this document. The Introducer's Agent may maintain a database with the necessary information, or it may query its connections to see which can provide the requested credentials or proofs (the DIF's Storage&Compute WG is currently exploring the concept of "credential manifests").

### 2. Introducer responds with "counter proposal"

_(This is step may be skipped if all criteria are met.)_

The Introducer may not be able to find matching candidates for all criteria - he/she may only have a partial match. In this case, the Introducer responds with a counter proposal to the Introducee:

{
  "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/introduce/1.0/candidates-proposal",
  "@id": "283e15b5-a3f7-43e7-bac8-b75e4e7a0a25",
  "~thread": {"thid": "df3b699d-3aa9-4fd0-bb67-49594da545bd"},
  "candidates~attach": {
    "mime-type": "application/json",
    "data": {
      "base64": "base64 encoding"
    }
  }
}

Notice again the "generic attachment with implementation-specific" pattern again here.

### 3. Introducee accepts or rejects counter proposal

_(This step is skipped if the previous step was also skipped)._

The Introducee either accepts or rejects the counter proposal. The protocol ends here if they reject, otherwise it continues onto the next step.

Response message:

{
  "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/introduce/1.0/candidates-response",
  "@id": "281523b5-a3f7-43e7-bac8-b7294n7a0a25",
  "~thread": {"thid": "df3b699d-3aa9-4fd0-bb67-49594da545bd"},
  "approve": true
}

### 4. Introducer forwards candidate `connection-invitation`s to Introducee

Once the Introducee has accepted, the familiar flow of the `Introduce Protocol` resumes, starting at the [`proposal`](https://github.com/hyperledger/aries-rfcs/blob/master/features/0028-introduce/README.md#proposal) stage with each of the candidates and then forwarding their [`invitation`](https://github.com/hyperledger/aries-rfcs/tree/master/features/0023-did-exchange#0-invitation-to-exchange)s to the Introducee.

The [`invitation`](https://github.com/hyperledger/aries-rfcs/tree/master/features/0023-did-exchange#0-invitation-to-exchange) message needs to be extended to include the subset of criteria matched by this candidate. (TODO)