Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve explanation on DID update lineage #587

Merged
merged 4 commits into from
Jul 14, 2023
Merged

docs: improve explanation on DID update lineage #587

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
783c21e
docs: update ambiguous explanation on DID update operation
Jul 7, 2023
d5d3ba8
docs: no ci [skip-ci]
Jul 7, 2023
bad4069
docs: expand on operation rejection and forks [skip-ci]
Jul 7, 2023
ef5ceca
doc: pr review [skip ci]
Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 22 additions & 11 deletions docs/docusaurus/dids/update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,12 @@ It is also possible for DID Controller to compose multiple actions in the same u
The [PRISM DID method - Update DID section](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md#update-did) includes a complete list of supported update actions.
The PRISM DID method only allows published [DID](/docs/concepts/glossary#decentralized-identifier) to be updated.

Each DID update-operation is cryptographically linked, creating a lineage of DID operations.
The lineage is not allowed to contain forks.
The data on the DID document is updated only from the operations on the valid lineage, and the operations on the fork get discarded.
When updating a DID, each operation is connected through cryptography,
forming a sequence of operations known as the lineage.
It's important to note that the lineage should not have any forks,
meaning that the operations should follow a single, uninterrupted path.
Only the operations within the valid lineage are considered when updating the data on
the DID document, while any operations on a forked lineage are disregarded and discarded by the protocol.

Please refer to [PRISM DID method - processing of update operation](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md#processing-of-updatedidoperations) for more detail about how a DID update-operation is processed.
It has an important implication on how the operation lineage is determined.
Expand All @@ -20,20 +23,28 @@ It has an important implication on how the operation lineage is determined.

## Prerequisites

1. DID Controller PRISM Agent up and running
2. DID Controller has a DID created on PRISM Agent (see [Create DID](./create.md))
1. DID Controller PRISM agent up and running
2. DID Controller has a DID created on PRISM agent (see [Create DID](./create.md))
3. DID Controller has a DID published to the blockchain (see [Publish DID](./publish.md))

## Overview

PRISM Agent allows the DID Controller to update the DID easily. This update mechanism is implementation specific and links the DID update-operation from the last confirmed operation observed on the blockchain.
PRISM agent allows the DID Controller to update the DID easily. This update mechanism is implementation specific and links the DID update-operation from the last confirmed operation observed on the blockchain.

Updating the DID will take some time until the update-operation gets confirmed on the blockchain. By updating the DID on PRISM Agent without waiting for the previous update-operation to be confirmed, the DID Controller is creating a fork on the DID lineage and risking having the subsequent operation discarded.
When updating a DID, there is a waiting period for the update to be confirmed on the blockchain.
If the DID Controller updates the DID before the previous update is confirmed,
it can create a situation where the sequence of updates splits into two separate paths,
which is not allowed according to the protocol. This happens because the PRISM agent connects
the update operation to the latest confirmed update. Once the pending update operation is confirmed,
any other pending operation that does not link to the latest confirmed operation will be discarded.
The subsequent updates continuing from that operation will also be discarded.
However, the PRISM agent has a safeguard in place to prevent this issue by rejecting
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would Agent know if update operation has been confirmed and applied already? are you polling node for the status of the operation? or are you checking the status of previous update operations before accepting a new one from every DID?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the agent is polling Node for all pending operations it submitted.

multiple updates submitted by the same agent while previous updates are still being processed.
patlo-iog marked this conversation as resolved.
Show resolved Hide resolved

Please refer to the `SECURE_DEPTH` parameter in [PRISM method - protocol parameters](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md#versioning-and-protocol-parameters) for the number of confirmation blocks.
At the time of writing, this number is 112 blocks.

This example shows the DID update capability on PRISM Agent and the steps to verify that the update has been confirmed and applied.
This example shows the DID update capability on PRISM agent and the steps to verify that the update has been confirmed and applied.

## Endpoints

Expand All @@ -48,7 +59,7 @@ The example uses the following endpoints

### 1. Check the current state of the DID document

Given the DID Controller has a DID on PRISM Agent and that DID is published, he can resolve the DID document using short-form DID.
Given the DID Controller has a DID on PRISM agent and that DID is published, he can resolve the DID document using short-form DID.

```bash
curl --location --request GET 'http://localhost:8080/prism-agent/dids/{didRef}' \
Expand Down Expand Up @@ -115,7 +126,7 @@ curl --location --request POST 'http://localhost:8080/prism-agent/did-registrar/
]
}'
```
Under the hood, PRISM Agent constructs the DID update-operation from the last confirmed operation observed on the blockchain.
Under the hood, PRISM agent constructs the DID update-operation from the last confirmed operation observed on the blockchain.
The DID Controller should receive a response about the scheduled operation, waiting for confirmation on the blockchain.


Expand Down Expand Up @@ -168,4 +179,4 @@ A new key, called `key-2`, gets observed, and `key-1`, now removed, has disappea
## Future work

The example only shows the case of a successful update.
In case of failure, PRISM Agent will provide the capability to retrieve the low-level operation status and failure detail in the future.
In case of failure, PRISM agent will provide the capability to retrieve the low-level operation status and failure detail in the future.