# Aries RFC 0XXX: Transition to fully qualified dids for DIDComm

- Authors: [Timo Glastra (Animo Solutions)](mailto:[e-mail])
- Status: [PROPOSED](/README.md#proposed)
- Since: 2022-04-27
- Status Note: In step 1 - update all implementations to accept fully qualified dids. **Target Completion Date: xxxx-xx-xx**
- Supersedes:
- Start Date: 2022-04-21
- Tags: [community-update](/tags.md#community-update)

## Notes

- Define a process on how to go from unqualified peer dids to spec compliant peer dids
- Option 1. Party 1 transforms the did to a qualified did, sends it to Party 2.
- Option 2. Both parties transform the did to a qualified did, and use it from then on.
- Transition the unqalified peer did into a peer did numalgo 2, communicate it in that form
- Receive unqualified did, store it internally as a fully qualified did
- 2 Parts:
- Internally storing the did as fully qualified did
- Using the fully qualified did in communication
- Transform old did to new did
- Replace `publicKey` to `verificationMethod`
- Move all inline verification methods to the `verificationMethod` array and make them references (required by peer did spec)
- `did:sov` -> Each party decides for themselves which namespace they think the did belongs to
- This could lead to an inconsistency
- Advisory section on how this could be handled internally by software

## Summary

The Aries community has agreed to transition connections established using unqualified dids to fully qualified dids. This includes the transition from legacy peer dids as created by the indy-sdk (`example-did`) to `did:peer` dids as specified in the [Peer Did Method Specification](https://identity.foundation/peer-did-method-spec/), as well as the transition from unqualified indy dids to fully qualified and namespaced `did:indy` dids.

This community coordinated update only addresses the usage of unqualifed dids in didcomm protocols themselves, it doesn't address the usage of unqualified dids in the indy credential and presentation format.

This RFC follows the guidance in [RFC 0345](../../concepts/0345-community-coordinated-update/README.md) about
community-coordinated updates to (try to) ensure that independently deployed, interoperable agents remain interoperable throughout this transition.

The transition from unqualified dids to qualified dids will occur in four steps:

- **Pre-work**: Agent builders agree on the transition plan outlined in this RFC and the target date for completing Step 1.
- Any RFC updates related to this transition needed before starting the transition are completed.
- **Step 1**: Agent builders update all agent code bases and deployments to accept fully qualified `did:peer` and `did:indy` dids in addition to unqualified dids.
- During Step 1, all agents should continue to send dids in the format that is currently expected. For example, the connection protocol should use unqualified dids, while the DID Exchange protocol should use fully qualified dids.
- Each agent builder SHOULD notify the community they have completed Step 1 by submitting a PR to update their entry in the [implementations](#implementations) section of this RFC.
- **Step 2**: Agent builders update all agent code bases and deployments to send out fully qualified dids in all protocols.
- Each agent builder SHOULD notify the community they have completed Step 2 by submitting a PR to update their entry in the [implementations](#implementations) section.
- **Step 3**: Support for unqualified dids can be removed from all implementations and deployments.

### Step 1 - Accepting Qualified Dids

> TODO

### Qualifying indy dids registered to a network

This section describes how to qualify indy dids with both the method and namespace (`did:indy:<namespace>:<identifier>`). This includes fully unqualified dids without method and namespace (e.g. `BBPoJqRKatdcfLEAFL7exC`), and also dids using the `sov` method without without a namespace (e.g. `did:sov:BBPoJqRKatdcfLEAFL7exC`)

To qualify an indy did it's important to determine the network the did is registered on. Both unqualified indy dids and indy dids qualified with the the `sov` method are lacking the namespace identifier added to the `did:indy` method which allows to identify the network a did is registered on. It is up to the agent implementation to determine which network a did is registered on.

The following steps are needed to qualify an indy did:
1. Determine the network the indy did is registered on.
2. Map the network to the namespace identifier. A registry of indy networks can be found [here](https://github.com/idunion/indy-did-networks), however an agent is free to define their own network mapping, as long as other agents use the same mapping of network to namespace identifier.
3. Update the unqualified did to a fully qualified did by transforming it into the following format: `did:indy:<namespace>:<identifier>`. Some examples for a did registered on the sovrin staging network:
- `BBPoJqRKatdcfLEAFL7exC` becomes `did:indy:sovrin:staging:BBPoJqRKatdcfLEAFL7exC`
- `did:sov:BBPoJqRKatdcfLEAFL7exC` becomes `did:indy:sovrin:staging:BBPoJqRKatdcfLEAFL7exC`

#### Determining unqualified did based on qualified did

Determining the unqualified did based on a qualified did is a straightforward process:

1. Remove the `did:indy:<namespace>:` prefix from the fully qualified did, remaining will be the `<identifier>`.
2. The unqualifed did will be either `did:sov:<identifier>` or `<identifier>`.

### Qualifying peer dids

> TODO: If using method 1 it is almost impossible to deterministically generate the method specific identifier. The peer did method spec doesn't use something like JCS to deterministically get the bytes, meaning any differences in the did document (even though semantically the same) are problematic.
> This would mean we need to use `did:peer:2` dids, but that means static

This section describes how to qualify legacy peer peer dids not compliant with the [Peer Did Method Specification](https://identity.foundation/peer-did-method-spec/) into spec compliant `did:peer` dids.

The following steps are needed to qualify a peer did:
1. Update the did document to a did document following the [Peer Did Method Specification](https://identity.foundation/peer-did-method-spec/), keeping it semantically equal to the current did document. Examples include
- Update `publicKey` to `verificationMethod`
- Move all inline verification methods to the `verificationMethod` array and make them references
2. TODO: define the numAlgo to use for the peer did
3. Sam -> method 2 (I'd like to keep the door open for non static peer dids)
4. However, if there is an intent to support dynamic updates in the future, use of numalgo Method 1 is encouraged, as this allows static peer DIDs to acquire new state when dynamic support is added. (See next section.)
4. Calculate the `did:peer` did from the did document, following the peer did specification.

#### Determining unqualified did based on qualified did

> This is not possible with method 1 , but possible with method 2 but only if the did was generated using indy-sdk. Process for method 2:
> 1. Resolve the did to a did document
> 2. Extract all `Ed25519VerificationKey2018` authentication keys from the did document
> 3. For each verification method determine the did:
1. Decode the `publicKeyBase58` of the verification method into bytes
2. Take the first 16 bytes of the public key and base 58 encode this, this is the legacy indy did.

1. Extract all `Ed25519VerificationKey2018` entries

### Between Step Triggers

The community coordination triggers between the steps above will be as follows:

- **Pre-work to Step 1** - a PR to this RFC is merged that sets the RFC status to [ACCEPTED](/README.md#accepted).
- **Step 1 to Step 2** - the community agrees that the majority of the deployed agents have completed Step 1. A PR to this RFC is merged that sets the RFC status to [ADOPTED](/README.md#adopted).
- Agent builders indicate completion of Step 1 by updating the [Implementations](#implementations) section of this RFC.
- A PR to RFCs XXXX, XXXX (TODO: add RFCs that need updating?) that mentions the usage of unqualified dids is deprecated.
- The [ADOPTED](/README.md#adopted) version of this RFC is included in the then-current [Aries Interop Profile](/concepts/0302-aries-interop-profile/README.md) version.
- **Step 2 to Step 3** - the community agrees that the majority of the deployed agents have completed Step 2. A PR to this RFC is merged that sets the RFC status to [RETIRED](/README.md#retired).
- Agent builders indicate completion of Step 2 by updating the [Implementations](#implementations) section of this RFC.

## Motivation

To enable agent builders to independently update their code bases and deployed agents to move away from legacy usage of unqualified dids, while maintaining interoperability.

## Tutorial

The general mechanism for this type of transition is documented in [RFC 0345](../../concepts/0345-community-coordinated-update/README.md) about
community-coordinated updates.

The specific sequence of events to make this particular transition is outlined in the [summary](#summary) section of this RFC.

## Reference

See the [summary](#summary) section of this RFC for the details of this transition.

## Drawbacks

None identified.

## Rationale and alternatives

This approach balances the speed of adoption with the need for independent deployment and ongoing interoperability.

## Prior art

The approach outlined in [RFC
0345](../../concepts/0345-community-coordinated-update/README.md) about
community-coordinated updates is a well-known pattern for using deprecation to
make breaking changes in an ecosystem. Adjustments to the transition plan will be made as needed, and RFC 0345 will be updated based on lessons learned in executing this plan.

## Unresolved questions

- Where are unqualified dids actually used?
- Add inventory of places that are likely to be affected
- did:peer transformation
- Which numAlgo to use?
- How do we consistently derive the did:peer
- numAlgo 2: define order of purposes should be enough?
- numAlgo 1: harder because no canocalization scheme is used for peer dids
- Add note that removing the usage of unqualified dids in old protocols is not feasible (too much work), so this RFC focusses on updating unqualified dids to fully qualified dids.

## Implementations

The following table lists the status of various agent code bases and deployments with respect to **Step 1** of this transition. Agent builders MUST update this table as they complete steps of the transition.

Name / Link | Implementation Notes
--- | ---
|