# Indy DID Method Implementation Plan

## Authors
- Daniel Bluhm <[e-mail]>
- [Adam Burdett](mailto:[e-mail]) <[e-mail]>
- Colton Wolkins <[e-mail]>
- Char Howland <[e-mail]>

## Introduction

Add support for W3C DID Specification compliant identifiers and documents on Indy Ledgers.

## Context

See the [DID Indy Method Specification](https://hyperledger.github.io/indy-did-method/) for the full context and an overview of the desired end state upon completion of this work.

### Pseudo DID Doc Support in Indy Networks

Previous to the definition of the Indy DID Method specification, DID Documents from Indy Nyms were constructed following convention only. This convention used nym and attrib transactions to construct rudimentary DID Documents. See [Resolving DID Documents in a single transaction](https://hyperledger.github.io/indy-did-method/#resolving-a-diddoc-in-a-single-transaction) for more details on why this approach was sub-optimal.

### Additional Links

See also the meeting notes and recordings of the following Indy Contributor calls for more discussion on the the Indy Method Specification:

- [2021-12-07 Indy Contributors](https://wiki.hyperledger.org/display/indy/2021-12-07+Indy+Contributors+Call)
- [2022-01-18 Indy Contributors](https://wiki.hyperledger.org/display/indy/2022-01-18+Indy+Contributors+Call)

## User stories

As a Holder/Prover, I want to be able to receive credentials from issuers from different Indy networks and be able to construct a single AnonCreds verifiable presentation that uses all of those credentials.

As an issuer, I want to be able to publish a DID Doc on an Indy ledger containing a BLS Key so that I can issue W3C Standard Verifiable JSON-LD Credentials using BBS+ Signatures.

## Goals

- Full DID Doc Support
- AnonCreds Object resolution by DID URL

## Non-Goals

- Per a discussion within the `did:indy` DID Method Working Group, referencing a SCHEMA object on another ledger is out of scope for this implementation of `did:indy`. Consideration will be given to how that will be done in the future, but for now, that capability is out of scope.

## Proposed Solution

### DID Doc Support

As discussed in [Indy DID Method 10.1: Creation](https://hyperledger.github.io/indy-did-method/#creation), to support writing full W3C compliant DID Documents to Indy Ledgers, a new attribute will be added to NYM transactions.

> Additionally, all newly created NYM transactions (meaning a NYM transaction writing a new identifier as opposed to updating an old one) MUST meet the self-certification requirements outlined in [Indy DID Method 10.1: Creation](https://hyperledger.github.io/indy-did-method/#creation). Nyms written prior to the creation of the Indy DID Method will be not be modified and MUST continue to be usable. As a result, the burden of determining self-certification will be delegated to the nym resolver.
>
> **(The above text is no longer in effect but left in for context; see [self-certification investigation below](#Self-certifying-Nym-transaction-transition))**

#### `diddocContent` Attribute

- This attribute will be a `JsonField` (JSON encoded string) with some length limit imposed (See [Storage of DID Doc Content](#Storage-of-DID-Doc-Content)).
- This attribute will be optional.
- The contents of this field will be validated according to the rules in [Validating DID Doc Content](#Validating-DID-Doc-Content).

#### Storage of DID Doc Content

`diddocContent` will be stored directly in the domain ledger state and will not require an additional store (as is the case for ATTRIB transaction data).

While investigating options for storage, it was determined that ATTRIB data was stored separately due to being arbitrary data not strictly required to represent the identity identified by the associated Nym. The size of the ATTRIB data, while significant when compared to the size of the typical NYM transaction, is dwarfed by the potential size of CLAIM_DEF and SCHEMA transactions. ATTRIBs are capped at 5KiB of raw data (size limit is imposed by transaction operation schema). CLAIM_DEF and SCHEMA transactions have no size limits and are bounded only by the maximum permitted message size of the secure transport layer of 128KiB. Therefore, it was determined that reasonable size limits should be imposed on DID Documents but any size up to the 128KiB message size cap is unlikely to negatively impact the performance of the network.

On inspection of old issues relating to the size limit on ATTRIB data, the 5KiB limit was chosen to enable batching of more ATTRIB transactions into a single 128KiB max message. This use case appears to only arise in testing scenarios.

The proposed (but still somewhat arbitrary) `diddocContent` size cap is 10KiB. In future iterations, this (and other size limits) should be network configurable through the config ledger.

> 1KiB == 1024 bytes

#### Validating DID Doc Content

Validation of the DID Document Content should be as minimal as possible. Minimal validation of the document content should ensure basic construction of a full DID Document while enabling usage of DID Document features not yet standardized or conceived. Overly strict validation would require code and network updates to allow such new features to be used on Indy Networks.

DID Doc Content should be validated as follows:

- Content is a JSON string (enforced by transaction operation schema)
- Content must not include `id` at root of the object
- Content must not include any nested objects with an `id` ending in `<nym>#verkey`

### Self-Certification of DIDs

Previously, NYM transactions did not require any link between its identifier and verification key. This makes proving ownership of Indy DIDs more difficult as arbitrary values (including "vanity DIDs") could be used. The Indy DID Method Specification accounts for this by introducing an explicit mechanism for self-certification.

However, this mechanism causes problems with backwards compatibility (See [the self-certification investigation below](#Self-certifying-Nym-transaction-transition) for more details on reasoning and alternatives). If implemented, the following rules would be met:

- Since the self-certification requirement is imposed only on newly created DIDs, validation of whether the identifier submitted in the nym transaction must be performed during `additional_dynamic_validation` and cannot be performed statically.
- NYM transactions failing to meet this requirement are rejected with appropriate error text.

**This requirement will not be enforced in implementation.**

### Resolving by `versionId` and `versionTime`

As described in [Indy DID Method 10.3.1 DID Versions](https://hyperledger.github.io/indy-did-method/#did-versions), it should be possible to resolve a particular version of a DID based on `versionId` (corresponding to a transaction sequence number) or on `versionTime`.

Indy natively supports retrieving transactions by sequence number using `GET_TXN`. Indy also supports retrieving the state of a nym at a particular point in time; however, this is not exposed directly in any read transactions but `GET_TAA` where it is used to check the value of the TAA at a given point in time.

To support resolving by `versionId` and `versionTime`, two new attributes will be added to the `GET_NYM` transaction:

- `seqNo` (equivalent to `versionId`) - sequence number of the transaction resulting in the state we wish to retrieve
- `timestamp` (equivalent to `versionTime`) - retrieve state at this timestamp (state exactly at the time or before). This value is a POSIX timestamp.

`seqNo` and `timestamp` are mutually exclusive; if both are present, inform the client of invalid request.

It will be the responsibility of the Resolver to transform a DID URL with these query parameters into the expected transaction format.

#### Resolving by `versionId`

[As pointed out by Dominic in this issue](https://github.com/hyperledger/indy-did-method/issues/19), there is some nuance to the retrieval of the state of a nym at a version that merits further discussion.

A sequence number refers to a specific transaction on Indy Networks. This means that, by retrieving a transaction, we are retrieving the operation data or the specific action that took place in that transaction. In other words (in the context of nyms, at least), a sequence number refers to a change to a nym and not the state of the nym after the change represented by the sequence number is applied. When retrieving by `versionId`, we are interested in the state of the nym and not the change taking place at that version.

To obtain the state of the nym at a particular sequence number, Dominic proposed a number of options in the issue he raised. After further investigation, it was determined that the option Dominic presented as 3b is the best balance between backwards compatibility, minimizing required changes, and implementing the spec as currently defined.

To resolve a DID Document by `versionId`, the `GetNymHandler` will:

1. Retrieve the transaction identified by the `versionId` (sequence number)
2. Extract timestamp from the transaction
3. Retrieve the root hash at (or nearest previous root hash to) that timestamp from the timestamp store
4. Retrieve value of nym as contained in state at root hash

### AnonCreds Object Resolution By DID URL

In general, most of the responsibility of resolving an AnonCreds object will be on the resolver. Further updates to Indy Node to accommodate the URLs defined in the spec should not be necessary.

### Deviations from the Method Specification

- Validation rules for DID Document
- Spec states that the ledger must construct the document and validate it; document construction should be delegated to resolver and sufficient validation will be performed by the node but full document construction will not be performed.
- ~~Spec states that if `@context` is included in `diddocContent`, the `@context` must include the DID Core JSON-LD context; this context should be included when the Resolver constructs the document and should not be required in `diddocContent`.~~ Corrected.
- Read rules for a DID
- When resolving with `versionId`, the spec states that `GET_TXN` will be used; as discussed in [Resolving by `versionId`](#Resolving-by-versionId), `GET_NYM` will be used instead.

### Open Questions

- When using multiple ledgers, how do we handle multiple versions/feature sets of the ledger?
- Multiple ledger questions have been deemed as out of scope.
- Should DID Document validation be more strict?

## Investigations

The following are results from investigations into features that will not necessarily be implemented at this time.

### Self-certifying Nym transaction transition

After discussions with the community, it has become clear that the self-certification requirement proposed in the Method Specification would be a significant breaking change for users of Indy Networks. Indy SDK users (which form a majority of the user base) would be unable to write new nyms without implementing workarounds as the SDK produces DIDs according to conventions incompatible with the self-certification requirement. As such, self-certification will not be enforced at this time.

However, in anticipation of enabling enforcement of self-certification at some future date, we have conducted some investigation of how this feature could be activated by networks.

#### Static Configuration

Using a static variable to trigger this similar to features being configured during testing was considered. This idea has been passed over because of the complexity of consensus in a pool and having each node in the pool turn on or off the static configuration at the same time.

#### Dynamic Configuration via Config Ledger

Our findings indicate that the config ledger is a preferable solution for nym self-certification configuration. To achieve this, we will need to add two handlers for the config ledger:

- A transaction for updating the config and
- a transaction for reading the state of the configuration.

With a new variable stored in the config ledger, the nym transaction handler will be able to access the config ledger in determining if self certification should be enforced.

If there is a bottleneck in accessing the config from the Patricia trie, we propose adding a flat "config cache" storage for a quick retrieval during nym transaction validation.

#### Optional new field for self-certification

Another potential option is to add a new field that indicates to the handler whether the submitted nym is self-certifying. This could provide an opportunity to enable progressive enforcement of nym requirements.

Rather than enforce self-certification and damage backwards compatibility, we could allow users to update their implementations and opt in to self-certification. This is an opportunity to work on implementation before eventually enforcing self-certification. Non-self-certifying nym transactions still have the minimum level of security because all transactions need to be signed; self-certifying nym transactions provide a level up in security.

This change could be specified using an incrementing integer: the original version without an option to disclose self-certification would be represented by 0; the updated version with the option to disclose self-certification would be represented by 1. The self-certification parameter would be stored as additional metadata and equal to true or false, but during this interim opt-in period, the transaction would not fail if self-certification evaluates to false. Each node would not have to be updated as outlined in the [static configuration investigation](https://hackmd.io/hjnCnMCjRcKzvoQY6_2-3A?view#Static-Configuration), but each node would need to be able to handle the new transaction field.

Linked transactions as a means to prove self-certification is under investigation. This would entail providing the last transaction that modified the retrieved nym.