From 8b342179337adec0eac8a775cb789419172cd55a Mon Sep 17 00:00:00 2001 From: patlo-iog <108713642+patlo-iog@users.noreply.github.com> Date: Fri, 3 Mar 2023 20:01:02 +0700 Subject: [PATCH] docs: add docusaurus DID update guide (#417) --- docs/docusaurus/dids/update.md | 162 ++++++++++++++++++++++++++++++++- 1 file changed, 161 insertions(+), 1 deletion(-) diff --git a/docs/docusaurus/dids/update.md b/docs/docusaurus/dids/update.md index 1ab042d60a..4bff676848 100644 --- a/docs/docusaurus/dids/update.md +++ b/docs/docusaurus/dids/update.md @@ -1 +1,161 @@ -# Update DID \ No newline at end of file +# Update DID + +PRISM DID method allows **DID Controller** to update the content of the DID document by constructing a DID update-operation. +The update-operation describes the update action on the DID document. +For example, **DID Controller** can add a new key to the DID document by constructing an update-operation containing the `AddKeyAction`. +It is also possible for **DID Controller** to compose multiple actions in the same update-operation. +The full list of supported update actions can be found in 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). +The PRISM DID method currently only allows published DID 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 are discarded. + +*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.* + +## Roles + +1. **DID Controller** is the organization or individual who has control of the DID. + +## Prerequisites + +1. **DID Controller** PRISM Agents 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 easily update the DID. +This update mechanism is implementation specific and it 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. + +This example shows the DID update capability on PRISM Agent and the steps to verify that the update has been confirmed and applied. + +## Endpoints + +The example uses the following endpoints + +| Endpoint | Description | Role | +|---------------------------------------------------------------------------------------------------------|-------------------------------|----------------| +| [`POST /did-registrar/dids/{didRef}/updates`](/agent-api/#tag/DID-Registrar/operation/updateManagedDid) | Update a PRISM DID | DID Controller | +| [`GET /dids/{didRef}`](/agent-api/#tag/DID/operation/getDid) | Resolve a DID to DID document | DID Controller | + +## DID Controller interactions + +### 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. + +```bash +curl --location --request GET 'http://localhost:8080/prism-agent/dids/{didRef}' \ +--header 'Accept: application/json' +``` + +Example DID document response (some fields are omitted for readability) + +```json +{ + "did": { + ... + "verificationMethod": [ + { + "controller": "did:prism:4262377859267f308a06ec6acf211fbe4d6745aa9e637e04548771169616fb86", + "id": "did:prism:4262377859267f308a06ec6acf211fbe4d6745aa9e637e04548771169616fb86#key-1", + "publicKeyJwk": { + "crv": "secp256k1", + "kty": "EC", + "x": "biEpgXMrmKMghF8LsXbIR0VDyIO31mnPkbJBpGDYH1g", + "y": "0YLIMfxY0_3J8Db6W0I1wcHZG3vRCRndNEnVn4h2V7Y" + }, + "type": "EcdsaSecp256k1VerificationKey2019" + } + ] + ... + }, + ... +} +``` +The `verificationMethod` in the DID document only shows one public key called `key-1`. + +### 2. Add a new key and remove the existing key + +The current DID document contains a key called `key-1`. +The **DID Controller** wishes to remove that key and add a new key called `key-2` + +The **DID Controller** submits a DID update request to `POST /did-registrar/dids/{didRef}/updates`. + +```bash +curl --location --request POST 'http://localhost:8080/prism-agent/did-registrar/dids/did:prism:4262377859267f308a06ec6acf211fbe4d6745aa9e637e04548771169616fb86/updates' \ +--header 'Content-Type: application/json' \ +--header 'Accept: application/json' \ +--data-raw '{ + "actions": [ + { + "actionType": "REMOVE_KEY", + "removeKey": { + "id": "key-1" + } + }, + { + "actionType": "ADD_KEY", + "addKey": { + "id": "key-2", + "purpose": "authentication" + } + } + ] +}' +``` +Under the hood, PRISM Agent constructs the DID update-operation from the *last confirmed operation* observed on the blockchain at that time. +The **DID Controller** should receive a response about the operation that has been scheduled, waiting for confirmation on the blockchain. + + +```json +{ + "scheduledOperation": { + "didRef": "did:prism:4262377859267f308a06ec6acf211fbe4d6745aa9e637e04548771169616fb86", + "id": "cb61cff083e27e2f8bc35b0e561780dc027c4f0072d2a2e478b2e0f26e3783b0" + } +} +``` + +### 3. Wait for the confirmation and observe the change on the DID document + +When the **DID Controller** tries to resolve the DID again using the example in step 1, +the content might still be the same because the operation is not yet confirmed and applied. + +The **DID Controller** keeps polling this endpoint until the new key `key-2` is observed. + +Example response of updated DID document (some fields are omitted for readability) + +```json +{ + "did": { + ... + "verificationMethod": [ + { + "controller": "did:prism:4262377859267f308a06ec6acf211fbe4d6745aa9e637e04548771169616fb86", + "id": "did:prism:4262377859267f308a06ec6acf211fbe4d6745aa9e637e04548771169616fb86#key-2", + "publicKeyJwk": { + "crv": "secp256k1", + "kty": "EC", + "x": "sg5X06yRDNaW2YcuMuOPwrDPp_vqOtKng0hMHxaME10", + "y": "uAKJanSsNoC_bcL4YS93qIqu_Qwdsr_80DzRTzI8RLU" + }, + "type": "EcdsaSecp256k1VerificationKey2019" + } + ] + }, + ... +} +``` + +A new key call `key-2` is observed and `key-1` which was removed has disappeared from the `verificationMethod`. + +## Future work + +The example only shows the case of a successful update. +In case of failure, PRISM Agent will be providing the capability to retrieve the low-level operation status and failure detail in the future.