diff --git a/docs/decisions/20221005-using-tapir-library-as-a-dsl-for-openapi-specification.md b/docs/decisions/20221005-using-tapir-library-as-a-dsl-for-openapi-specification.md index b0d5f5b5ee..7ef2a38465 100644 --- a/docs/decisions/20221005-using-tapir-library-as-a-dsl-for-openapi-specification.md +++ b/docs/decisions/20221005-using-tapir-library-as-a-dsl-for-openapi-specification.md @@ -8,14 +8,14 @@ Related ADR/AIP: [Introduce REST HTTP for existing Node services](https://input-output.atlassian.net/wiki/spaces/AV2/pages/3454500948/AIP+-+001) ## Context and Problem Statement -Prism Platform v2 will contain the REST API. The decision was made by team consensus during the first AOH meeting to follow "OpenAPI specification first" approach and generate stubs, server side and client side code based on OAS. +PRISM Platform v2 will contain the REST API. The decision was made by team consensus during the first AOH meeting to follow "OpenAPI specification first" approach and generate stubs, server side and client side code based on OAS. Following this strategy we currently have 4-5 OAS files (Castor, Pollux, Mercury, Configuration). The following tool was selected for code generation: [OpenAPI Tools](https://github.com/OpenAPITools/openapi-generator) Instead of using the yaml file as OpenAPI specification and openapi-generator for server and client stub generation - this ADR proposes to use [Tapir](https://tapir.softwaremill.com/en/latest/index.html) Scala library as DSL for OpenAPI specification, `interpret` the endpoint defitions as Scala server and client stub, generate the yaml file, and use openapi-generator for client stubs. -Technology stack that is going to be used in Prism v2 backend: Scala 3 + ZIO ecosystem +Technology stack that is going to be used in PRISM v2 backend: Scala 3 + ZIO ecosystem Akka framework after version 2.6.x cannot be used because [Lightbend changed the license type to BSL 1.1](https://www.lightbend.com/blog/why-we-are-changing-the-license-for-akka). diff --git a/docs/decisions/20221006-store-private-keys-of-issuers-inside-prism-agent.md b/docs/decisions/20221006-store-private-keys-of-issuers-inside-prism-agent.md index 719aa01c8a..9ef15b8b15 100644 --- a/docs/decisions/20221006-store-private-keys-of-issuers-inside-prism-agent.md +++ b/docs/decisions/20221006-store-private-keys-of-issuers-inside-prism-agent.md @@ -6,7 +6,7 @@ ## Context and Problem Statement -While each holder has its own wallet application on the phone (edge agent) to store private keys, contacts and credentials that have been issued to them, prism 2.0 will provide a custodial solution to Issuers and Verifiers, thus they won't be having their own wallets and won't be storing/managing keys on their side, There needs to be a storage for private keys of issuers nad Verifiers on Prism side. +While each holder has a wallet application on the phone (edge agent) to store private keys, contacts, and credentials, PRISM 2.0 will provide a custodial solution to Issuers and Verifiers. Thus they won't have their wallets or store/manage keys. There needs to be storage for the private keys of issuers and Verifiers on the PRISM side. ## Considered Options diff --git a/docs/decisions/20230118-quill-library-for-sql-statement-generation.md b/docs/decisions/20230118-quill-library-for-sql-statement-generation.md index f8bc662338..4053963e56 100644 --- a/docs/decisions/20230118-quill-library-for-sql-statement-generation.md +++ b/docs/decisions/20230118-quill-library-for-sql-statement-generation.md @@ -7,11 +7,11 @@ ## Context and Problem Statement -PostgreSQL is essential to the Atala Prism technology stack, where most entities are stored. +PostgreSQL is essential to the Atala PRISM technology stack, where most entities are stored. -Backend services: Prism Agent, Prism Mediator, and Prism Node use PostgreSQL. +Backend services: PRISM Agent, PRISM Mediator, and PRISM Node use PostgreSQL. -[Doobie](https://tpolecat.github.io/doobie/index.html) llibrary is currently used in Scala code to communicate with Postgresql. Quotes from the website +[Doobie](https://tpolecat.github.io/doobie/index.html) library is currently used in Scala code to communicate with Postgresql. Quotes from the website ``` Doobie is a pure functional JDBC layer for Scala and Cats. It is not an ORM, nor is it a relational algebra; diff --git a/docs/docusaurus/connections/connection.md b/docs/docusaurus/connections/connection.md index 75fb48cde2..7d5cc1f6f0 100644 --- a/docs/docusaurus/connections/connection.md +++ b/docs/docusaurus/connections/connection.md @@ -2,21 +2,19 @@ A connection is a stateful relationship between two parties that enables secure communication. -The **Connection protocol** is required to establish secure connections between agents, +The [Connection protocol](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#connection-protocol) is required to establish secure connections between agents, allowing them to exchange information and interact. -The protocol provides endpoints for creating and managing connections, as well as for accepting invitations. - ## Roles The connection protocol has two roles: -1. **Inviter**: A subject that initiates a connection request by sending a *connection invitation*. -2. **Invitee**: A subject that receives a connection invitation and accepts it by sending a *connection request*. +1. [Inviter](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#inviter): A subject that initiates a connection request by sending a [connection invitation](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#connection-invitation). +2. [Invitee](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#invitee): A subject that receives a connection invitation and accepts it by sending a [connection request](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#connection-request). ## Prerequisites -1. **Inviter** and **Invitee** PRISM Agents up and running +1. Inviter and Invitee PRISM Agents up and running ## PRISM Agent endpoints overview @@ -29,17 +27,17 @@ The protocol uses the following REST API endpoints: 3. [`POST /connection-invitations`](/agent-api/#tag/Connections-Management/operation/acceptConnectionInvitation): Accepts an externally received invitation :::info -For more detailed information, please, check the full **[PRISM Agent API](/agent-api).** +Please check the full [PRISM Agent API](/agent-api) specification for more detailed information. ::: ## Inviter Flow -1. Generate and share a new Out-of-Band (OOB) invitation (connection is created in `InvitationGenerated` state) -2. Receive a connection request from the **Invitee** (connection is moved to `ConnectionRequestReceived` state) -3. Accept the connection request (connection is moved to `ConnectionResponsePending` state) +1. Generate and share a new Out-of-Band (OOB) invitation (connection gets created in `InvitationGenerated` state) +2. Receive a connection request from the Invitee (connection moves to `ConnectionRequestReceived` state) +3. Accept the connection request (connection moves to `ConnectionResponsePending` state) 4. Send the connection response via the DIDComm Agent (connection achieves `ConnectionResponseSent` state) -The **Inviter**'s state transitions are represented by the following Mermaid diagram: +The following diagram represents the Inviter's Connection state transitions: ```mermaid --- title: Inviter Connection State @@ -57,10 +55,10 @@ ConnectionResponseSent --> [*] 1. Receive the OOB invitation (`InvitationReceived` state) 2. Accept the invitation (connection is created in `ConnectionRequestPending` state) -3. Send the connection request via DIDComm (connection achieves `ConnectionRequestSent` state) +3. Send the connection request via [DIDComm](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#didcomm) (connection achieves `ConnectionRequestSent` state) 4. Receive the connection response (connection achieves `ConnectionResponseReceived` state) -The **Invitee**'s state transitions are represented by the following Mermaid diagram: +The following diagram represents the Invitee's Connection state transitions: ```mermaid --- title: Invitee Connection State @@ -81,14 +79,15 @@ The following diagram shows the end-to-end flow for establishing a connection be ## Command line example -The following example demonstrates on how you could use two PRISM Agents API to set up connection between them. +The following example demonstrates how you could use two PRISM Agent APIs to set up a connection between them. -### **Inviter** creates an invitation +### Inviter creates an invitation ```shell curl -X 'POST' \ 'http://localhost:8080/prism-agent/connections' \ -H 'Content-Type: application/json' \ + -H "apiKey: $API_KEY" \ -d '{ "label": "Connect with Alice" }' | jq ``` @@ -117,6 +116,7 @@ Replace `{RAW_INVITATION}` with the value of the '_oob' query string parameter f curl -X 'POST' \ 'http://localhost:8090/prism-agent/connection-invitations' \ -H 'Content-Type: application/json' \ + -H "apiKey: $API_KEY" \ -d '{ "invitation": "{RAW_INVITATION}" }' | jq ``` @@ -140,10 +140,11 @@ Example response: } ``` -### **Invitee** retrieves the list of connections +### Invitee retrieves the list of connections ```shell -curl -X 'GET' 'http://localhost:8090/prism-agent/connections' | jq +curl -X 'GET' 'http://localhost:8090/prism-agent/connections' \ + -H "apiKey: $API_KEY" | jq ``` Example output: @@ -172,10 +173,11 @@ Example output: } ``` -### **Inviter** retrieves the list of connections +### Inviter retrieves the list of connections ```shell -curl -X 'GET' 'http://localhost:8080/prism-agent/connections' | jq +curl -X 'GET' 'http://localhost:8080/prism-agent/connections' \ + -H "apiKey: $API_KEY" | jq ``` Example response: @@ -206,5 +208,5 @@ Example response: ``` :::info -For more detailed information, please, check the full **[PRISM Agent API](/agent-api).** +Please check the full [PRISM Agent API](/agent-api) specification for more detailed information. ::: diff --git a/docs/docusaurus/credentials/issue.md b/docs/docusaurus/credentials/issue.md index e238ba9598..c9617ae686 100644 --- a/docs/docusaurus/credentials/issue.md +++ b/docs/docusaurus/credentials/issue.md @@ -1,41 +1,41 @@ # Issue Credentials -In Atala PRISM, the **Issue Credentials Protocol** allows you to create, retrieve, and manage issued verifiable credentials (VCs) between a VC issuer and a VC holder. +In Atala PRISM, the [Issue Credentials Protocol](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#issue-credentials-protocol) allows you to create, retrieve, and manage issued [verifiable credentials (VCs)](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifiable-credentials) between a VC issuer and a VC holder. ## Roles -In the **Issue Credentials Protocol**, there are two roles: +In the Issue Credentials Protocol, there are two roles: -1. **Issuer** is responsible for creating a new credential offer, sending it to a **Holder**, and issuing the VC once the offer is accepted. -2. **Holder** is responsible for accepting a credential offer from an issuer and receiving the VC. +1. The [Issuer](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#issuer) is responsible for creating a new credential offer, sending it to a Holder, and issuing the VC once the offer is accepted. +2. The [Holder](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#holder) is responsible for accepting a credential offer from an issuer and receiving the VC. -The **Issuer** and **Holder** interact with the **PRISM Agent API** to perform the operations defined in the protocol. +The Issuer and Holder interact with the PRISM Agent API to perform the operations defined in the protocol. ## Prerequisites -Before using the **Issuing Credentials protocol**, the following conditions must be present: +Before using the Issuing Credentials protocol, the following conditions must be present: -1. **Issuer** and **Holder** PRISM Agents up and running -2. A connection must be established between the **Issuer** and **Holder** PRISM Agents (see [Connections](../connections/connection.md)) -3. The **Issuer** must have a published PRISM DID and the DID document must have at least one `assertionMethod` key for issuing credendials (see [Create DID](../dids/create.md) and [Publish DID](../dids/publish.md)) -4. The **Holder** must have a PRISM DID and the DID document must have at least one `authentication` key for presenting the proof +1. Issuer and Holder PRISM Agents up and running +2. A connection must be established between the Issuer and Holder PRISM Agents (see [Connections](../connections/connection.md)) +3. The Issuer must have a published PRISM DID, and the [DID document](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-document) must have at least one `assertionMethod` key for issuing credentials (see [Create DID](../dids/create.md) and [Publish DID](../dids/publish.md)) +4. The Holder must have a PRISM DID, and the DID document must have at least one `authentication` key for presenting the proof. ## Overview -The protocol described is a VC issuance process between two Atala PRISM Agents, the **Issuer** and the **Holder**. +The protocol described is a VC issuance process between two Atala PRISM Agents, the Issuer and the Holder. The protocol consists of the following main parts: -1. The **Issuer** creates a new credential offer using the [`/issue-credentials/credential-offers`](/agent-api/#tag/Issue-Credentials-Protocol/operation/createCredentialOffer) endpoint, which includes information such as the schema identifier and claims. -2. The **Holder** can then retrieve the offer using the [`/issue-credentials/records`](/agent-api/#tag/Issue-Credentials-Protocol/operation/getCredentialRecords) endpoint and accept the offer using the [`/issue-credentials/records/{recordId}/accept-offer`](/agent-api/#tag/Issue-Credentials-Protocol/operation/acceptCredentialOffer) endpoint. -3. The **Issuer** then uses the [`/issue-credentials/records/{recordId}/issue-credential`](/agent-api/#tag/Issue-Credentials-Protocol/operation/issueCredential) endpoint to issue the credential, which gets sent to the Holder via DIDComm. The Holder receives the credential, and the protocol is complete. +1. The Issuer creates a new credential offer using the [`/issue-credentials/credential-offers`](/agent-api/#tag/Issue-Credentials-Protocol/operation/createCredentialOffer) endpoint, which includes information such as the schema identifier and claims. +2. The Holder can then retrieve the offer using the [`/issue-credentials/records`](/agent-api/#tag/Issue-Credentials-Protocol/operation/getCredentialRecords) endpoint and accept the offer using the [`/issue-credentials/records/{recordId}/accept-offer`](/agent-api/#tag/Issue-Credentials-Protocol/operation/acceptCredentialOffer) endpoint. +3. The Issuer then uses the [`/issue-credentials/records/{recordId}/issue-credential`](/agent-api/#tag/Issue-Credentials-Protocol/operation/issueCredential) endpoint to issue the credential, which gets sent to the Holder via [DIDComm](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#didcomm). The Holder receives the credential, and the protocol is complete. The schema identifier defines the structure and the credential type issued, while the claims provide specific information about the individual, such as their name or qualifications. -This protocol is applicable in various real-life scenarios, such as educational credentialing, employment verification, and more. -In these scenarios, the **Issuer** could be a school, an employer, etc., and the **Holder** could be a student or an employee. +This protocol applies in various real-life scenarios, such as educational credentialing, employment verification, etc. +In these scenarios, the Issuer could be a school, an employer, etc., and the Holder could be a student or an employee. The VCs issued during this protocol could represent a diploma, a certificate of employment, etc. ## Endpoints @@ -50,7 +50,7 @@ The VCs issued during this protocol could represent a diploma, a certificate of :::info -For more detailed information, please, check the full **[PRISM Agent API](/agent-api).** +Please check the full [PRISM Agent API](/agent-api) specification for more detailed information. ::: ## Issuer interactions @@ -63,7 +63,7 @@ To start the process, the issuer needs to create a credential offer. To do this, make a `POST` request to the [`/issue-credentials/credential-offers`](/agent-api/#tag/Issue-Credentials-Protocol/operation/createCredentialOffer) endpoint with a JSON payload that includes the following information: 1. `schemaId`: This is an identifier for a schema, which defines the structure and format of the data in a verifiable credential. The schema identifier must be unique and typically a URL or a URN. -2. `claims`: The data stored in a verifiable credential. Claims get expressed in a key-value format and must conform to the structure and format defined in the schema. The claims contain the data that the issuer attests to, such as name, address, date of birth, and so on. +2. `claims`: are the data stored in a verifiable credential. Claims get expressed in a key-value format and must conform to the structure and format defined in the schema. Claims contain the data that the issuer attests to, such as name, address, date of birth, etc. Once the request initiates, a new credential record for the issuer gets created with a unique ID. The state of this record is now `OfferPending`. @@ -73,6 +73,7 @@ curl -X 'POST' \ 'http://localhost:8080/prism-agent/issue-credentials/credential-offers' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ + -H "apiKey: $API_KEY" \ -d '{ "schemaId": "schema:1234", "subjectId": "did:prism:subjectIdentifier", @@ -86,16 +87,16 @@ curl -X 'POST' \ ### Sending the Offer to the Holder -The next step for the **Issuer** is to send the offer to the holder using DIDComm. -To do this, the **Issuer** agent will process the offer and send it to the holder agent. -This process is automatic. The state of the **Issuer**'s record will change to `OfferSent`. +The next step for the Issuer is to send the offer to the holder using DIDComm. +To do this, the Issuer agent will process the offer and send it to the holder agent. +This process is automatic. The state of the Issuer's record will change to `OfferSent`. ### Issuing the Credential -Once the holder has approved the offer and sent a request to the **Issuer**, -the **Issuer** will receive the request via DIDComm and update the state of the record to `RequestReceived.` +Once the holder has approved the offer and sent a request to the Issuer, +the Issuer will receive the request via DIDComm and update the record state to `RequestReceived.` -The **Issuer** can then use the [`/issue-credentials/records/{recordId}/issue-credential`](/agent-api/#tag/Issue-Credentials-Protocol/operation/issueCredential) endpoint to issue the credential to the holder. +The Issuer can then use the [`/issue-credentials/records/{recordId}/issue-credential`](/agent-api/#tag/Issue-Credentials-Protocol/operation/issueCredential) endpoint to issue the credential to the holder. ```shell # Issuer POST request to issue the credential @@ -103,14 +104,15 @@ The **Issuer** can then use the [`/issue-credentials/records/{recordId}/issue-cr # and the record achieved `RequestReceived` state curl -X POST \ "http://localhost:8080/prism-agent/issue-credentials/records/$issuer_record_id/issue-credential" \ - -H "Content-Type: application/json" + -H "Content-Type: application/json" \ + -H "apiKey: $API_KEY" ``` When this endpoint gets called, the state of the record will change to `CredentialPending,` and after processing, it will change to `CredentialGenerated.` -Finally, the **Issuer** agent will send the credential to the holder via DIDComm, +Finally, the Issuer agent will send the credential to the holder via DIDComm, and the state of the record will change to `CredentialSent`. -At this point, the **Issuer**'s interactions with the holder are complete. +At this point, the Issuer's interactions with the holder are complete. ```mermaid --- @@ -131,8 +133,8 @@ This section describes the Holder role's available interactions with the PRISM A ### Receiving the VC Offer -The **Holder** will receive the offer from the **Issuer** via DIDComm, -and a new credential record with a unique ID will be created in the `OfferReceived` state. +The Holder will receive the offer from the Issuer via DIDComm, +and a new credential record with a unique ID gets created in the `OfferReceived` state. This process is automatic for the PRISM Agent. @@ -140,22 +142,24 @@ You could check if a new credential offer is available using [`/issue-credential ```shell # Holder GET request to retrieve credential records curl "http://localhost:8090/prism-agent/issue-credentials/records" \ - -H "Content-Type: application/json" + -H "Content-Type: application/json" \ + -H "apiKey: $API_KEY" ``` ### Approving the VC Offer -To accept the offer, the **Holder** can make a `POST` request to the [`/issue-credentials/records/{recordId}/accept-offer`](/agent-api/#tag/Issue-Credentials-Protocol/operation/acceptCredentialOffer) endpoint with a JSON payload that includes the following information: +To accept the offer, the Holder can make a `POST` request to the [`/issue-credentials/records/{recordId}/accept-offer`](/agent-api/#tag/Issue-Credentials-Protocol/operation/acceptCredentialOffer) endpoint with a JSON payload that includes the following information: 1. `holder_record_id`: The unique identifier of the issue credential record known by the holder PRISM Agent. -2. `subjectId`: This field represents the unique identifier for the subject of the verifiable credential. It is a short-form PRISM DID (Decentralized Identifier) string, such as `did:prism:subjectIdentifier`. +2. `subjectId`: This field represents the unique identifier for the subject of the verifiable credential. It is a short-form PRISM [DID](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifier) string, such as `did:prism:subjectIdentifier`. ```shell # Holder POST request to accept the credential offer curl -X POST "http://localhost:8090/prism-agent/issue-credentials/records/$holder_record_id/accept-offer" \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ + -H "apiKey: $API_KEY" \ -d '{ "subjectId": "did:prism:subjectIdentifier" }' @@ -165,13 +169,13 @@ This request will change the state of the record to `RequestPending`. ### Receiving the VC Credential -Once the **Holder** has approved the offer and sent a request to the **Issuer**, the **Holder** agent will process the request and send it to the **Issuer** agent. -The state of the **Holder**'s record will change to `RequestSent`. +Once the Holder has approved the offer and sent a request to the Issuer, the Holder agent will process the request and send it to the Issuer agent. +The state of the Holder's record will change to `RequestSent`. -After the **Issuer** has issued the credential, the **Holder** will receive the credential via DIDComm, and the state of the **Holder**'s record will change to `CredentialReceived`. +After the Issuer has issued the credential, the Holder will receive the credential via DIDComm, and the state of the Holder's record will change to `CredentialReceived`. This process is automatic for the PRISM Agent. -**Holder** can check the achieved credential using a GET request to [`/issue-credentials/records/{recordId}/`](/agent-api/#tag/Issue-Credentials-Protocol/operation/getCredentialRecord) endpoint. +The Holder can check the achieved credential using a GET request to [`/issue-credentials/records/{recordId}/`](/agent-api/#tag/Issue-Credentials-Protocol/operation/getCredentialRecord) endpoint. ```mermaid --- diff --git a/docs/docusaurus/credentials/present-proof.md b/docs/docusaurus/credentials/present-proof.md index ffef353e61..9665743a3e 100644 --- a/docs/docusaurus/credentials/present-proof.md +++ b/docs/docusaurus/credentials/present-proof.md @@ -1,66 +1,67 @@ # Present proof -The **Present Proof Protocol** allows: -- a **Verifier** to request a verifiable credential presentation from a **Prover** -- a **Prover** to respond by presenting a proof to the **Verifier** +The [Present Proof Protocol](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#present-proof-protocol) allows: +- a [Verifier](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifier) to request a verifiable credential presentation from a Holder/Prover +- a [Holder/Prover](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#holder) responds by presenting a cryptographic proof to the Verifier -The protocol provides endpoints for a **Verifier** to request new proof presentations from provers, and for a **Prover** to respond to the presentation request using a specific verifiable credential he owns. +The protocol provides endpoints for a Verifier to request new proof presentations from Holder/Provers and for a Holder/Prover to respond to the presentation request using a specific verifiable credential they own. ## Roles The present proof protocol has two roles: -1. **Verifier**: A subject that requests the presentation of a proof by sending a *request presentation* message, and then verifies the presentation. -2. **Prover**: A subject that receives a proof presentation request, prepares a proof and sends it to the verifier by sending a *proof presentation* message. +1. Verifier: A subject requesting a proof presentation by sending a request presentation message, then verifying the presentation. +2. Holder/Prover: A [subject](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#subject) that receives a [proof presentation](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#proof-presentation) request, prepares a proof, and sends it to the verifier by sending a proof presentation message. ## Prerequisites -Before using the **Proof Presentation protocol**, the following conditions must be present: +Before using the Proof Presentation protocol, the following conditions must be present: -1. **Prover** and **Verifier** PRISM Agents must be up and running -2. A connection must be established between the **Prover** and **Verifier** PRISM Agents (see [Connections](../connections/connection.md)) -3. The **Prover** should hold a verifiable credential (VC) received from an **Issuer** (see [Issue](./issue.md)) +1. Holder/Prover and Verifier PRISM Agents must be up and running +2. A connection must be established between the Holder/Prover and Verifier PRISM Agents (see [Connections](../connections/connection.md)) +3. The Holder/Prover should hold a [verifiable credential (VC)](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifiable-credential) received from an [Issuer](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#issuer) see [Issue](./issue.md). ## Overview -This protocol supports the presentation of verifiable claims between two Atala PRISM Agents, the **Prover** and the **Verifier**. +This protocol supports the presentation of verifiable claims between two Atala PRISM Agents, the Holder/Prover and the Verifier. The protocol consists of the following main parts: -1. The **Verifier** creates a new proof presentation request using the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/requestPresentation) endpoint. It includes the identifier of an existing `connection` between both parties as well as a `domain` and `challenge` to protect from potential replay attacks. -2. The **Prover** receives the presentation request from the **Verifier** and can retrieve the list of existing requests using the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint. -3. The **Prover** can then review and accept a specific request using the [`/present-proof/presentations/{presentationId}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint, providing the identifier of the `credential` record to use in the proof presentation. -4. The **Verifier** receives the proof presentation from the **Prover** and can accept it using the [`/present-proof/presentations/{presentationId}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint, specifying `presentation-accept` as action type. +1. The Verifier creates a new proof presentation request using the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/requestPresentation) endpoint. It includes the identifier of an existing `connection` between both parties, `domain`, and a `challenge` to protect from potential replay attacks. +2. The Holder/Prover receives the presentation request from the Verifier and can retrieve the list of existing requests using the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint. +3. The Holder/Prover can then review and accept a specific request using the [`/present-proof/presentations/{presentationId}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint, providing the identifier of the `credential` record to use in the proof presentation. +4. The Verifier receives the proof presentation from the Holder/Prover and can accept it using the [`/present-proof/presentations/{presentationId}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint, specifying `presentation-accept` as the action type. ## Endpoints | Endpoint | Method | Description | Role | | --- | --- | --- | --- | | [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/requestPresentation) | POST | Creates and sends a new proof presentation request. | Verifier | -| [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) | GET | Retrieves the collection of all the existing presentation proof records - sent or received. | Verifier, Prover | -| [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/getPresentation) | GET | Retrieves a specific presentation proof record by `id`. | Verifier, Prover | -| [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) | PATCH | Updates an existing presentation proof record to e.g. accept the request on **Prover** side, or accept the presentation on **Verifier** side. | Verifier, Prover | +| [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) | GET | Retrieves the collection of all the existing presentation proof records - sent or received. | Verifier, Holder/Prover | +| [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/getPresentation) | GET | Retrieves a specific presentation proof record by `id`. | Verifier, Holder/Prover | +| [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) | PATCH | Updates an existing presentation proof record to, e.g., accept the request on the Holder/Prover side or accept the presentation on the Verifier side. | Verifier, Holder/Prover | :::info -For more detailed information, please, check the full **[PRISM Agent API](/agent-api).** +For more detailed information, please, check the full [PRISM Agent API](/agent-api). ::: ## Verifier interactions -This section describes the interactions available to the **Verifier** with his PRISM Agent. +This section describes the interactions available to the Verifier with the PRISM Agent. ### Creating and sending a Presentation Request -To start the process, the verifier needs to create a proof presentation request. +The Verifier needs to create a proof presentation request to start the process. To do this, he makes a `POST` request to the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/requestPresentation) endpoint with a JSON payload that includes the following information: -1. `connectionId`: This field represents the unique identifier of an existing connection between the verifier and the prover. This connection will be used to exchange messages related to the protocol flow execution. -2. `challenge` and `domain`: The random seed challenge and operational domain are provided by the **Verifier** and must be signed by the **Prover** in the generated proof in order to protect from replay attacks. +1. `connectionId`: This field represents the unique identifier of an existing connection between the verifier and the Holder/prover. It is for exchanging messages related to the protocol flow execution. +2. `challenge` and `domain`: The Verifier provides the random seed challenge and operational domain, and the Holder/Prover must sign the generated proof to protect from replay attacks. ```bash curl -X 'POST' 'http://localhost:8070/prism-agent/present-proof/presentations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ + -H "apiKey: $API_KEY" \ -d '{ "connectionId": "872ddfa9-4115-46c2-8a1b-22c24c7431d7", "proofs":[], @@ -71,22 +72,24 @@ curl -X 'POST' 'http://localhost:8070/prism-agent/present-proof/presentations' \ }' ``` -Upon execution, a new presentation request record will be created with an initial state of `RequestPending`. The **Verifier** PRISM Agent will take care of sending the presentation request message to the PRISM Agent of the **Prover** through the specified DIDComm connection. The record state will then be moved to `RequestSent`. +Upon execution, a new presentation request record gets created with an initial state of `RequestPending`. The Verifier PRISM Agent will send the presentation request message to the PRISM Agent of the Holder/Prover through the specified DIDComm connection. The record state then is updated to `RequestSent`. -The **Verifier** can retrieve the list of presentation records making a `GET` request to the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint: +The Verifier can retrieve the list of presentation records by making a `GET` request to the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint: ```bash curl -X 'GET' 'http://localhost:8070/prism-agent/present-proof/presentations' \ - -H 'accept: application/json' + -H 'accept: application/json' \ + -H "apiKey: $API_KEY" ``` -### Accept presentation proof received from the prover -Once the **Prover** has received a proof presentation request, he can accept it using an appropriate verifiable credential. The PRISM Agent of the **Verifier** will receive that proof and verify it. Upon successful verification, the presentation record state will be moved to `PresentationVerified`. +### Accept presentation proof received from the Holder/prover +Once the Holder/Prover has received a proof presentation request, he can accept it using an appropriate verifiable credential. The PRISM Agent of the Verifier will receive that proof and verify it. Upon successful verification, the presentation record state gets updated to `PresentationVerified`. -The **Verifier** can then explicitly accept the specific verified proof presentation to move the record state to `PresentationAccepted`. This can be achieved by making a `PATCH` request to the [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint: +The Verifier can then explicitly accept the specific verified proof presentation to change the record state to `PresentationAccepted` by making a `PATCH` request to the [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint: ```bash curl -X 'PATCH' 'http://localhost:8070/prism-agent/present-proof/presentations/{PRESENTATION_ID}' \ -H 'Content-Type: application/json' \ + -H "apiKey: $API_KEY" \ -d '{ "action": "presentation-accept" }' @@ -98,53 +101,55 @@ title: Verifier Flow --- stateDiagram-v2 [*] --> RequestPending: new presentation request created by the Verifier - RequestPending --> RequestSent: presentation request sent to the Prover PRISM Agent - RequestSent --> PresentationReceived: presentation proof received from the Prover + RequestPending --> RequestSent: presentation request sent to the Holder/Prover PRISM Agent + RequestSent --> PresentationReceived: presentation proof received from the Holder/Prover PresentationReceived --> PresentationVerified: presentation proof verified by the Verifier PRISM Agent PresentationVerified --> PresentationAccepted: verified presentation proof explicitly accepted by the Verifier ``` -## Prover -This section describes the interactions available to the **Prover** with his PRISM Agent. +## Holder/Prover +This section describes the interactions available to the Holder/Prover with his PRISM Agent. ### Reviewing and accepting a received presentation request -The **Prover** can retrieve the list of presentation requests received by its PRISM Agent from different **Verifiers** making a `GET` request to the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint: +The Holder/Prover can retrieve the list of presentation requests received by its PRISM Agent from different Verifiers making a `GET` request to the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint: ```bash curl -X 'GET' 'http://localhost:8090/prism-agent/present-proof/presentations' \ - -H 'accept: application/json' + -H 'accept: application/json' \ + -H "apiKey: $API_KEY" ``` -The **Prover** can then accept a specific request, generate the proof, and send it to the **Verifier** PRISM Agent by making a `PATCH` request to the [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint: +The Holder/Prover can then accept a specific request, generate the proof, and send it to the Verifier PRISM Agent by making a `PATCH` request to the [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint: ```bash curl -X 'PATCH' 'http://localhost:8090/prism-agent/present-proof/presentations/{PRESENTATION_ID}' \ -H 'Content-Type: application/json' \ + -H "apiKey: $API_KEY" \ -d '{ "action": "request-accept", "proofId": ["{CRED_RECORD_ID}"] }' ``` -He will have to provide the following information: +The Holder/Prover will have to provide the following information: 1. `presentationId`: The unique identifier of the presentation record to accept. 2. `proofId`: The unique identifier of the verifiable credential record to use as proof. -Doing so, the record state will be moved to `PresentationPending` and processed by the Prover PRISM Agent. The agent will automatically generate the proof presentation - and move the state to `PresentationGenerated` - and will eventually send it to the Verifier Agent - and move the state to `PresentationSent`. +The record state is updated to `PresentationPending` and processed by the Holder/Prover PRISM Agent. The agent will automatically generate the proof presentation, change the state to `PresentationGenerated`, and will eventually send it to the Verifier Agent, and change the state to `PresentationSent`. ```mermaid --- -title: Prover Flow +title: Holder/Prover Flow --- stateDiagram-v2 [*] --> RequestReceived: presentation request received by the PRISM Agent - RequestReceived --> PresentationPending: request accepted by the Prover + RequestReceived --> PresentationPending: request accepted by the Holder/Prover PresentationPending --> PresentationGenerated: presentation proof generated by the PRISM Agent PresentationGenerated --> PresentationSent: generated proof sent to the Verifier PRISM Agent ``` ## Sequence diagram -The following diagram shows the end-to-end flow for a verifier to request and verify a proof presentation from a prover. +The following diagram shows the end-to-end flow for a verifier to request and verify a proof presentation from a Holder/prover. ![](present-proof-flow.png) \ No newline at end of file diff --git a/docs/docusaurus/dids/create.md b/docs/docusaurus/dids/create.md index e91ae056e8..244bb40fbf 100644 --- a/docs/docusaurus/dids/create.md +++ b/docs/docusaurus/dids/create.md @@ -1,20 +1,20 @@ # Create DID -PRISM DIDs are a type of _decentralized identifier_ used across Atala PRISM product suites. +PRISM DIDs are a type of [decentralized identifier (DID)](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifier) used across the Atala PRISM product suite. -It is a variation of a [_sidetree protocol_](https://identity.foundation/sidetree/spec/) and uses the Cardano blockchain as the underlying ledger for DID resolution and operation publication. -Please refere to [PRISM method specification](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md) for more detailed explanation of how it works. +It is a variation of a [sidetree protocol](https://identity.foundation/sidetree/spec/) and uses the Cardano blockchain as the underlying ledger for [DID resolution](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-resolution) and operation publication. +Please refer to the [PRISM method specification](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md) for a more detailed explanation of how it works. -A PRISM DID can be created entirely offline without interacting with the blockchain by constructing a DID create-operation, a protobuf message with a set of public keys and services. +PRISM DIDs can be created entirely offline without interacting with the blockchain by constructing a DID create-operation, a [protocol buffer (protobuf)](/documentation/docs/concepts/glossary.md#protocol-buffer) message with a set of public keys and services. Once the create-operation gets constructed, deriving a DID from this operation is possible, which is well-defined by the [PRISM DID method](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md). ## Roles -1. **DID Controller** is the organization or individual who has control of the DID. +1. [DID Controller](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-controller) is the organization or individual who has control of the DID. ## Prerequisites -1. **DID Controller** PRISM Agent up and running +1. DID Controller PRISM Agent up and running ## Overview @@ -24,7 +24,7 @@ The Agent will keep track of private keys used for the create-operation and the PRISM Agent provides two endpoint groups to facilitate PRISM DID usage. - `/dids/*` -are facilitators of low-level interactions between DID operations and the blockchain. +facilitate of low-level interactions between DID operations and the blockchain. The DID controllers will handle key management independently and use these endpoints for blockchain interaction. - `/did-registrar/*` @@ -46,20 +46,22 @@ The example uses the following endpoints ```bash curl --location --request GET 'http://localhost:8080/prism-agent/did-registrar/dids' \ + --header "apiKey: $API_KEY" \ --header 'Accept: application/json' ``` The result should show an empty list, as no DIDs exist on this PRISM Agent instance. ### 2. Create a PRISM Agent managed DID using DID registrar endpoint -The DID controller can create a new DID by sending a DID document template to the Agent. +The DID controller can create a new DID by sending a [DID document](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-document) template to the Agent. Since key pairs are generated and managed by PRISM Agent, DID controller only has to specify the key `id` and its purpose (e.g., `authentication`, `assertionMethod`, etc.). -The current PRISM DID method supports a key with a single purpose, but it may be extended to support a key with multiple purposes in the future. +The current PRISM DID method supports a key with a single purpose, but it is extendible to support a key with multiple purposes in the future. ```bash curl --location --request POST 'http://localhost:8080/prism-agent/did-registrar/dids' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ + --header "apiKey: $API_KEY" \ --data-raw '{ "documentTemplate": { "publicKeys": [ @@ -83,7 +85,7 @@ The response should look like ### 3. List the created DID -Checking the `GET /did-registrar/dids` endpoint, the response should return a list containing one DID. +Check the `GET /did-registrar/dids` endpoint. The response should return a list containing one DID. ```json { @@ -105,14 +107,15 @@ Checking the `GET /did-registrar/dids` endpoint, the response should return a li To check that the DID document is correctly populated, test the created DID against the resolution endpoint. Replacing the `{didRef}` with the long-form DID, and the response should return the DID document. -Replacing the `{didRef}` with the short-form DID, and the resolution should fail since the DID is not yet published. +Replacing the `{didRef}` with the short-form DID, and the resolution should fail since the DID still needs to be published. ```bash curl --location --request GET 'http://localhost:8080/prism-agent/dids/{didRef}' \ +--header "apiKey: $API_KEY" \ --header 'Accept: */*' ``` -Example DID document response (some fields are omitted for readability) +Example DID document response (some fields omitted for readability) ```json { diff --git a/docs/docusaurus/dids/deactivate.md b/docs/docusaurus/dids/deactivate.md index 3c1c6dfca5..aaffb66a4a 100644 --- a/docs/docusaurus/dids/deactivate.md +++ b/docs/docusaurus/dids/deactivate.md @@ -1,32 +1,31 @@ # Deactivate DID -DID deactivation is an important feature of SSI systems that gives greater control for managing digital identity. -DID deactivation can come in handy if the DID is compromised or no longer used. -This is crucial for the security and risk management of identity owners. +DID deactivation is an important feature that provides greater control for managing digital identity. +DID deactivation can be helpful if the [DID](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifier) is compromised or unused. +This feature is crucial for the security and risk management of identity owners. -Similar to [DID update](./update.md), the deactivation of a PRISM DID is a process of putting deactivate-operation on the blockchain so that other participants know that the DID is no longer active. +Similar to [DID update](./update.md), deactivating a PRISM DID is a process of putting deactivate-operation on the blockchain so that other participants know that the DID is no longer active. The PRISM DID method only allows published DID to be deactivated. ## Roles -1. **DID Controller** is the organization or individual who has control of the DID. +1. DID Controller is the organization or individual who has control of the DID. ## Prerequisites -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)) +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 -DID deactivation operates similarly to the DID update where deactivate-operation is published to the blockchain -and some confirmation blocks must be created before it is considered deactivated by other participants. -Once the DID is deactivated, all content in the DID document is emptied and no operation will have any effect on the DID afterward. -The same concept also holds for PRISM DID deactivation in that if any subsequent operation is made before the operation is confirmed, the fork can occur. +DID deactivation operates similarly to the DID update, where deactivate-operation publishes to the blockchain, and confirmation blocks must be created before participants consider it deactivated. +Once the DID is deactivated, all content in the [DID document](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-document) gets deleted, and no operation will affect the DID afterward. +The same concept also holds for PRISM DID deactivation in that the fork can occur if any subsequent operation occurs before the operation is confirmed. 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. -PRISM Agent allows DID deactivation to be easily performed. +DID deactivation is easily performed with the PRISM Agent. Under the hood, PRISM Agent uses the `MASTER` keys to sign the intended operation and automatically post the operation to the blockchain. This example shows the DID deactivation and steps to observe the changes to the DID using PRISM Agent. @@ -43,14 +42,15 @@ 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}' \ +--header "apiKey: $API_KEY" \ --header 'Accept: */*' ``` -Example DID document response (some fields are omitted for readability) +Example DID document response (some fields omitted for readability) ```json { @@ -63,30 +63,31 @@ Example DID document response (some fields are omitted for readability) "didResolutionMetadata": {...} } ``` -The DID metadata shows the `deactivation` status as `false` meaning that this DID is still active. +The DID metadata shows the `deactivation` status as `false`, meaning that this DID is still active. ### 2. Requesting the DID deactivation to PRSIM Agent -The active status is observed from the last step. +The active status comes from the last step. The DID deactivation can be performed by calling `POST /did-registrar/dids/{didRef}/deactivations` and replacing `{didRef}` with the DID to deactivate. ```bash curl --location --request POST 'http://localhost:8080/prism-agent/did-registrar/dids/{didRef}/deactivations' \ +--header "apiKey: $API_KEY" \ --header 'Accept: application/json' ``` -Under the hood, PRISM Agent constructs the DID deactivate-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. +Under the hood, PRISM Agent constructs the DID deactivate-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. If this deactivate-operation gets confirmed on the blockchain and not discarded as a fork, the DID becomes deactivated. -### 3. Wait for the confirmation and observe the change on the DID metadata +### 3. Wait for the confirmation and observe the change in the DID metadata -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. +When the DID Controller tries to resolve the DID again using the example in Step 1, +the content might remain the same because the operation still needs to be confirmed and applied. -The **DID Controller** keeps polling this endpoint until the `deactivated` status in DID document metadata is changed to `true`. +The DID Controller keeps polling this endpoint until the `deactivated` status in DID document metadata changes to `true`. -Example response of deactivated DID document (some fields are omitted for readability) +Example response of deactivated DID document (some fields omitted for readability) ```json { @@ -99,4 +100,4 @@ Example response of deactivated DID document (some fields are omitted for readab } ``` -The DID metadata indicates that the DID is now deactivated and the `didDocument` is now empty. +The DID metadata indicates that the DID is deactivated and the `didDocument` is empty. diff --git a/docs/docusaurus/dids/publish.md b/docs/docusaurus/dids/publish.md index d5b501bb00..46b4cc731f 100644 --- a/docs/docusaurus/dids/publish.md +++ b/docs/docusaurus/dids/publish.md @@ -1,33 +1,33 @@ # Publish DID -PRISM DID creation involves generating key pairs and some additional data (e.g. services) to construct a create-operation. -The create-operation allows **DID Controller** to derive two types of DID: +PRISM DID creation involves generating key pairs and additional data (e.g., services) to construct a create-operation. +The create-operation allows [DID Controller](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-controller) to derive two types of [DIDs](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifiers): 1. [Long-form DID](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md#long-form-dids-unpublished-dids). It has the following format `did:prism::` 2. Short-form DID. It has the following format `did:prism:` -The difference is the long-form DID contains the encoded create-operation in the DID itself while the short-form DID doesn't have this information. +The difference is the long-form DID contains the encoded create-operation in the DID itself while, the short-form DID doesn't have this information. As a result, when resolving the short-form DID, the resolver must look for additional data from the blockchain. On the other hand, resolving long-form DID is self-contained. Even if the data is not on the blockchain, the resolver can still work out the DID document of the long-form DID. -Enabling the resolution of short-form DID can be done by DID publication which is a process of putting the create-operation on the blockchain. +The resolution of short-form DID is achievable by DID publication, which is a process of putting the create-operation on the blockchain. ## Roles -1. **DID Controller** is the organization or individual who has control of the DID. +1. DID Controller is the organization or individual who has control of the DID. ## 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)) ## Overview -Publishing a DID requires the DID create-operation and the DID `MASTER` key pairs which PRISM Agent already created under the hood. -When the **DID Controller** requests a publication of their DID, PRISM Agent uses the DID `MASTER` key to sign the operation and submit the signed operation to the blockchain. -Once the operation is submitted to the blockchain, a specific number of confirmation blocks must be created before the DID operation is processed and considered published. +Publishing a DID requires the DID create-operation and the DID `MASTER` key pairs, which PRISM Agent already created under the hood. +When the DID Controller requests a publication of their DID, PRISM Agent uses the DID `MASTER` key to sign the operation and submit the signed operation to the blockchain. +After the operation submission to the blockchain, a specific number of confirmation blocks must get created before the DID operation is processed and published. (see [PRISM DID method - Processing of DID operation](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md#processing-of-operations)) ## Endpoints @@ -44,12 +44,13 @@ The example uses the following endpoints ### 1. Check the status of an unpublished DID -**DID Controller** checks the status by replacing the `{didRef}` with the unpublished DID on the Agent. +DID Controller checks the status by replacing the `{didRef}` with the unpublished DID on the Agent. The `{didRef}` path segment can be either short-form or long-form DID. -When a DID is created and not yet published, it has the status of `CREATED`. +When a DID gets created and not published, it has the status of `CREATED`. ```bash curl --location --request GET 'http://localhost:8080/prism-agent/did-registrar/dids/{didRef}' \ +--header "apiKey: $API_KEY" \ --header 'Accept: application/json' ``` @@ -64,16 +65,17 @@ Example response ``` ### 2. Request a publication of a DID -To publish a DID, **DID Controller** `POST` a request to `/did-registrar/dids/{didRef}/publications` endpoint. +To publish a DID, use DID Controller `POST` a request to `/did-registrar/dids/{didRef}/publications` endpoint. ```bash curl --location --request POST 'http://localhost:8080/prism-agent/did-registrar/dids/{didRef}/publications' \ +--header "apiKey: $API_KEY" \ --header 'Accept: application/json' ``` PRISM Agent will retrieve a DID `MASTER` key and sign the operation before submitting it to the blockchain. -The process is asynchronous and it takes time until the operation is confirmed. -The **DID Controller** receives a scheduled operation as a response. +The process is asynchronous, and it takes time until the operation is confirmed. +The DID Controller receives a scheduled operation as a response. ```json { @@ -84,15 +86,15 @@ The **DID Controller** receives a scheduled operation as a response. } ``` -The response contains `scheduledOperation` property which describes a scheduled operation. +The response contains the `scheduledOperation` property, which describes a scheduled operation. The submitted DID operations are batched together along with other operations to reduce the transaction cost when interacting with the blockchain. -*PRISM Agent will eventually expose an endpoint to check the status of a scheduled operation.* -*For now, checking the publishing status can be done by an example in step 3.* +PRISM Agent will eventually expose an endpoint to check the status of a scheduled operation. +Checking the publishing status is possible by following Step 3. ### 3. Wait until the DID operation is confirmed -The **DID Controller** checks the DID status same as in step 1, the status of the DID has changed to `PUBLICATION_PENDING`. +The DID Controller checks the DID status the same as in Step 1. The status of the DID has changed to `PUBLICATION_PENDING`. Example response with status `PUBLICATION_PENDING` @@ -115,19 +117,17 @@ Example response with status `PUBLISHED` } ``` -**NOTE:** -The `status` here is the internal status of the DID on the PRISM Agent (`PUBLISHED`, `CREATED`, `PUBLICAION_PENDING`). -It does not indicate the lifecycle of the DID observed on the blockchain (e.g. deactivated, etc). -The DID resolution metadata is used for that purpose. +> **Note:** The `status` here is the internal status of the DID on the PRISM Agent (`PUBLISHED`, `CREATED`, `PUBLICAION_PENDING`). It does not indicate the lifecycle of the DID observed on the blockchain (e.g., deactivated, etc.). The [DID resolution](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-resolution) metadata is for that purpose. ### 4. Resolve a short-form DID Only published DID can be resolved using short-form. To confirm that the short-form DID is resolvable, test the DID against the resolution endpoint. -Replace `{didRef}` with the short-form DID and the response should return a DID document. +Replace `{didRef}` with the short-form DID; the response should return a DID document. ```bash curl --location --request GET 'http://localhost:8080/prism-agent/dids/{didRef}' \ +--header "apiKey: $API_KEY" \ --header 'Accept: */*' ``` diff --git a/docs/docusaurus/dids/update.md b/docs/docusaurus/dids/update.md index 692493f87c..abd93fbea1 100644 --- a/docs/docusaurus/dids/update.md +++ b/docs/docusaurus/dids/update.md @@ -1,36 +1,35 @@ # Update DID -PRISM DID method allows **DID Controller** to update the content of the DID document by constructing a DID update-operation. +PRISM DID method allows [DID Controller](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#did-controller) to update the content of the [DID document(https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#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 only allows published DID to be updated. +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 [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](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifier) to be updated. -Each DID update-operation is cryptographically linked creating a lineage of DID operations. +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. +The data on the DID document is updated only from the operations on the valid lineage, and the operations on the fork get 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.* +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. +1. DID Controller is the organization or individual who has control of the DID. ## Prerequisites -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)) +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 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. +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. -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. 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. @@ -49,14 +48,15 @@ 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}' \ +--header "apiKey: $API_KEY" \ --header 'Accept: */*' ``` -Example DID document response (some fields are omitted for readability) +Example DID document response (some fields omitted for readability) ```json { @@ -88,14 +88,15 @@ The `verificationMethod` in the DID document only shows one public key called `k ### 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 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`. +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' \ +--header "apiKey: $API_KEY" \ --data-raw '{ "actions": [ { @@ -114,8 +115,8 @@ 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 at that time. -The **DID Controller** should receive a response about the operation that has been scheduled, waiting for confirmation 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. ```json @@ -129,12 +130,12 @@ The **DID Controller** should receive a response about the operation that has be ### 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. +When the DID Controller tries to resolve the DID again using the example in Step 1, +the content might remain the same because the operation still needs to be confirmed and applied. -The **DID Controller** keeps polling this endpoint until the new key `key-2` is observed. +The DID Controller keeps polling this endpoint until the new key, `key-2`, gets observed. -Example response of updated DID document (some fields are omitted for readability) +Example response of updated DID document (some fields omitted for readability) ```json { @@ -162,9 +163,9 @@ Example response of updated DID document (some fields are omitted for readabilit } ``` -A new key call `key-2` is observed and `key-1` which was removed has disappeared from the `verificationMethod`. +A new key, called `key-2`, gets observed, and `key-1`, now 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. +In case of failure, PRISM Agent will provide the capability to retrieve the low-level operation status and failure detail in the future. diff --git a/docs/docusaurus/index.md b/docs/docusaurus/index.md index 2d501368a4..1ac30a8c06 100644 --- a/docs/docusaurus/index.md +++ b/docs/docusaurus/index.md @@ -1,14 +1,22 @@ # Tutorials -Welcome to the **Atala PRISM Ecosystem** Tutorials! +Welcome to the Atala PRISM Tutorials! -These tutorials will help you get started with Self-Sovereign Identity (SSI) and using Atala PRISM. -The tutorials will guide you through setting up a connection, working with Decentralized Identifiers (DIDs), and using verifiable credentials. +These tutorials will help you get started with using Atala PRISM. +The tutorials will guide you through setting up a connection, working with [Decentralized Identifiers (DIDs)](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifer), and using [verifiable credentials](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifiable-credentials). -Whether you are new to SSI or have some prior experience, these tutorials will provide you with the necessary information and skills to build and use SSI-based applications. +Whether you are new to [self-sovereign identity (SSI)](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#self-sovereign-identity) or have prior experience, these tutorials will provide the necessary information and skills to build and use SSI-based applications. Throughout all code examples in tutorials, the following conventions are in use: * Issuer Agent is hosted at `http://localhost:8080/prism-agent/` * Holder Agent is hosted at `http://localhost:8090/prism-agent/` * Verifier Agent is hosted at `http://localhost:8100/prism-agent/` + +:::info To use the PRISM Cloud Agents, you must include an `apiKey` header in your requests. You can configure the key, and in some instances, it will be provided to you, so make sure to create an environment variable with the proper value. +```shell +export API_KEY= +``` +Alternatively, replace `$API_KEY` with your key in the CURL commands supplied throughout this tutorial. ::: + + diff --git a/docs/docusaurus/schemas/create.md b/docs/docusaurus/schemas/create.md index cba93d00be..9c7bd0f462 100644 --- a/docs/docusaurus/schemas/create.md +++ b/docs/docusaurus/schemas/create.md @@ -1,8 +1,8 @@ # Create the credential schema -The PRISM platform v2.0 exposes REST API for creation, fetching, and searching the credential schema records. +The PRISM platform v2.0 exposes REST API for creation, fetching, and searching the [credential schema](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#credential-schema) records. -The OpenAPI specification and redoc documentation describe the endpoint. +The OpenAPI specification and ReDoc documentation describe the endpoint. In this document, you can find step-by-step instructions for creating the credential schema. @@ -12,7 +12,7 @@ The following guide demonstrates how to create a driving license credential sche ### 1. Define the JSON Schema for the Verifiable Credential -Assume that you need a credential schema for the driving license, and the verifiable credential must have the following +Assume that you need a credential schema for the driving license, and the [verifiable credential](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifiable-credential) must have the following fields: - emailAddress - the email address of the driver @@ -23,7 +23,7 @@ fields: - drivingClass - driving class that denotes which types of vehicles the driver is allowed to go. Also, let's assume that the driving license might have additional optional claims. -First of all, the JSON Schema for the given fields must be defined as: +For the above fields, the JSON Schema definition must be: ```json { @@ -68,7 +68,7 @@ First of all, the JSON Schema for the given fields must be defined as: } ``` -Fields `$id` and `$schema` must be set to corresponding values which describe +The fields `$id` and `$schema` must correspond values that describe - the identity of the given JSON Schema `driving-license-1.0.0` and - the meta schema `https://json-schema.org/draft/2020-12/schema` @@ -76,7 +76,7 @@ Fields `$id` and `$schema` must be set to corresponding values which describe All the claims are listed under the `properties` object with corresponding `type`s and `format`s according to JSON Specification. -`additionalProperties` is set to true, meaning other fields can also be added to the verifiable credential.. +`additionalProperties` is set to true, meaning adding other fields to the verifiable credential is possible. ### 2. Create the credential schema record @@ -141,13 +141,13 @@ Specification. 3. Send the POST request to create the new schema. The response should contain a GUID that uniquely identifies the new schema. - Curl example for the `k8s-dev.atalaprism.io` environment is the following: + Curl example is the following: ```shell curl -X 'POST' \ - 'https://k8s-dev.atalaprism.io/prism-agent/schema-registry/schemas' \ + 'http://localhost:8080/prism-agent/schema-registry/schemas' \ -H 'accept: application/json' \ - -H 'apikey: $APIKEY' \ + -H "apikey: $API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "name": "driving-license", @@ -271,9 +271,9 @@ Send the GET request to retrieve the schema. Curl example is the following: ```shell curl -X 'GET' \ - 'https://k8s-dev.atalaprism.io/prism-agent/schema-registry/schemas/3f86a73f-5b78-39c7-af77-0c16123fa9c2' \ + 'http://localhost:8080/prism-agent/schema-registry/schemas/3f86a73f-5b78-39c7-af77-0c16123fa9c2' \ -H 'accept: application/json' \ - -H 'apikey: $APIKEY' + -H "apiKey: $API_KEY" ``` The response should contain the JSON object representing the schema you just created. @@ -339,14 +339,14 @@ The response should contain the JSON object representing the schema you just cre ``` -The triple `author`, `id`, and `version` are unique for the PRISM Agent instance. -So, having a single DID reference that the author uses, creating the credential schema with the same `id` and `version` +The PRISM Agent instance's triple `author`, `id`, and `version` are unique. +So, having a single [DID](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifier) reference that the author uses, creating the credential schema with the same `id` and `version` is impossible. ### 4. Update the credential schema -In order to upgrade the credential schema you need to perform the following steps: +To upgrade the credential schema, you need to perform the following steps: -1. start from the first step and change the JSON Schema -2. change the `version` according to the nature of your change -3. create a new credential schema record with a higher version \ No newline at end of file +1. Start from the first step and change the JSON Schema +2. Change the `version` according to the nature of your change +3. Create a new credential schema record with a higher version \ No newline at end of file diff --git a/docs/docusaurus/schemas/credential-schema.md b/docs/docusaurus/schemas/credential-schema.md index d5592b3d40..3a9c3fab48 100644 --- a/docs/docusaurus/schemas/credential-schema.md +++ b/docs/docusaurus/schemas/credential-schema.md @@ -7,8 +7,8 @@ the Atala PRISM Platform. ## 1. Introduction -Credential Schema is a data template for the Verifiable Credentials. -It contains claims (attributes) of the Verifiable Credentials, credential schema author, type, name, version, and proof +[Credential Schema](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#credential-schema) is a data template for [Verifiable Credentials](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifiable-credential). +It contains [claims](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#claims) (attributes) of the Verifiable Credentials, credential schema author, type, name, version, and proof of authorship. By putting schema definitions on a public blockchain, they are available for all verifiers to examine to determine the semantic interoperability of the Credential. @@ -38,7 +38,7 @@ Limitations and constraints of the PRISM Platform v2.0: ### Credential Schema -The Credential Schema is a template that defines a set of attributes the Issuer uses to issue the Verifiable Credential. +The Credential Schema is a template that defines a set of attributes the [Issuer](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#issuer) uses to issue the Verifiable Credential. ### Schema Registry @@ -46,7 +46,7 @@ The registry is where the Credential Schema is published and available for parti ### Issuer, Holder, Verifier -These are well-known roles in the SSI domain. +These are well-known roles in the [SSI](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#self-sovereign-identity) domain. ## 2. Credential Schema Attributes @@ -61,18 +61,12 @@ The locally unique identifier of the schema. ### longId (String) -Resource identifier of the given credential schema composed from the author's DID reference, id, and version fields. -Example: `{author}/{id}?version={version}` +Resource identifier of the given credential schema composed from the author's [DID]((https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#decentralized-identifier) reference, id, and version fields. +**Example:** `{author}/{id}?version={version}` -**_NOTE:_** -According to the [W3C specification](https://w3c-ccg.github.io/vc-json-schemas/#id), this field is locally unique and is -a combination of the Issuer `DID`, `uuid`, and `version`. +> **Note:** According to the [W3C specification](https://w3c-ccg.github.io/vc-json-schemas/#id), this field is locally unique and combines the Issuer `DID`, `uuid`, and `version`. +**For **example:** `did:example:MDP8AsFhHzhwUvGNuYkX7T/06e126d1-fa44-4882-a243-1e326fbe21db?version=1.0` -For example: - -`did:example:MDP8AsFhHzhwUvGNuYkX7T/06e126d1-fa44-4882-a243-1e326fbe21db?version=1.0` - -`longId`, `id` might be reconsidered in a new versions of the PRISM Platform. --- @@ -80,7 +74,7 @@ For example: It is a type of the supported JSON Schema of the credential schema. It describes the JSON Schema of the Credential Schema described in this document. -In the current implementation, this field must always be set to the value in the following example: +In the current implementation, this field must always be the value in the following example: ```json { @@ -93,7 +87,7 @@ In the current implementation, this field must always be set to the value in the ### name (String) It is a human-readable name for the schema. -Example: +**Example:** ```json { @@ -109,8 +103,7 @@ Example: It is a human-readable description of the schema. -**NOTE:** this field might be removed later as it's not a part of W3C specification but rather the internal field of the -JSON schema. +> **Note:** This field may get removed later as it's not a part of W3C specification but rather the internal field of the JSON schema. --- @@ -118,7 +111,7 @@ JSON schema. It is a version of the schema that contains the revision of the credential schema in [SemVer](https://semver.org/) format. -Example: +**Example:** ```json { @@ -126,10 +119,10 @@ Example: } ``` -The version field must be used for the schema evolution and describe the impact of the changes. -For the breaking changes, the `major` version must be increased. +The version field must be the schema evolution and describe the impact of the changes. +For the breaking changes, the `major` version must get increased. In the current implementation, the PRISM Platform doesn't validate whether the new version is backward compatible. -This logic might be implemented later, so the Issuer is responsible for correctly setting the credential schema's next +This logic may get implemented later, so the Issuer is responsible for correctly setting the credential schema's next version. --- @@ -137,7 +130,7 @@ version. ### author (DID) DID of the identity which authored the credential schema. -Example: +**Example:** ```json { @@ -149,8 +142,8 @@ Example: ### authored (DateTime) -[RFC3339](https://www.rfc-editor.org/rfc/rfc3339) date on which the credential schema was created. A piece of Metadata. -Example: +[RFC3339](https://www.rfc-editor.org/rfc/rfc3339) date of when the credential schema creation. A piece of Metadata. +**Example:** ```json { @@ -162,9 +155,9 @@ Example: ### schema (JSON Schema) -A valid [JSON-SCHEMA](https://json-schema.org/) where the credential schema semantic is defined. +A valid [JSON-SCHEMA](https://json-schema.org/) where the credential schema semantic gets defined. JSON Schema must be composed according to schema. -Example: +**Example:** ```json { @@ -214,8 +207,8 @@ Example: ### tags (String[]) It is a set of tokens that allow one to look up and filter the credential schema records. -This field is not a part of W3C specification and is used by the PRISM Platform for filtering the records. -Example: +This field is not a part of the W3C specification. Its usage by the PRISM platform for filtering the records. +**Example:** ```json { @@ -228,8 +221,7 @@ Example: ### proof (object) -The proof field is a JOSE object containing the credential schema's signature. -The following fields are used: +The proof field is a JOSE object containing the credential schema's signature, including the following fields: - type - created @@ -239,7 +231,7 @@ The following fields are used: - domain - jws -Example: +**Example:** ```json { diff --git a/docs/docusaurus/schemas/delete.md b/docs/docusaurus/schemas/delete.md index 2fe6c0be33..6244eaf82a 100644 --- a/docs/docusaurus/schemas/delete.md +++ b/docs/docusaurus/schemas/delete.md @@ -1,13 +1,11 @@ # Delete the credential schema -Unfortunately, after publishing (especially in the Verifiable Data Registry) the credential schema cannot be deleted. +Unfortunately, after publishing (especially in the [Verifiable Data Registry (VDR)](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifiable-data-registry), deleting the credential schema is impossible. -PRISM Platform v2.0 doesn't publish the credential schema in the VDR, this capability will be implemented in the later -version of the platform. -That's the reason why the platform does not expose the REST API for deletion. +PRISM Platform v2.0 doesn't publish the credential schema in the VDR. This capability will get implemented in the later version of the platform. That's why the platform does not expose the REST API for deletion. -If you really need to `delete` the credential schema, you can ask the database administrator or delete it from the -Posrgres instance by `guid`. +If you need to `delete` the credential schema, you can ask the database administrator or delete it from the +Postgres instance by `guid`. For example: diff --git a/docs/docusaurus/schemas/update.md b/docs/docusaurus/schemas/update.md index eff09d5fad..0e42ea4220 100644 --- a/docs/docusaurus/schemas/update.md +++ b/docs/docusaurus/schemas/update.md @@ -2,13 +2,12 @@ The PRISM platform v2.0 exposes REST API for creation, fetching, and searching the credential schema records. -The OpenAPI specification and redoc documentation describe the endpoint. +The OpenAPI specification and ReDoc documentation describe the endpoint. In this document, you can find step-by-step instructions for updating the credential schema. -After creation, the credential schema record cannot be updated. -If you need to create a similar schema but with the additional fields or different description, or metadata, -you need to create the credential schema record with the same `id` and higher `version`. +After creation, updating the credential schema record is not possible. +If you need to create a similar schema but with additional fields or a different description, or metadata, you need to create the credential schema record with the same `id` and a higher `version`. ## Step-by-step guide @@ -17,22 +16,21 @@ The following guide demonstrates how to update a driving license credential sche ### 1. Define the updated JSON Schema for the Verifiable Credential Assume that you need to update the credential schema from the previous tutorial. -So, there is an existing driving license, and the verifiable credential must additionally include two fields: +So, there is an existing driving license, and the [verifiable credential](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#verifiable-credential) must additionally include two fields: - bloodType - the blood type of the driver - organDonor - indicates whether or not the person is an organ donor -The blood type on a driver's license is typically represented using the ABO blood group system, and -may be represented as A+, A-, B+, B-, AB+, AB-, O+, or O-. -So, assume that these set of values must be enforced by the schema definition using the following regex: +The blood type on a driver's license is represented using the ABO blood group system, and +potentially represented as A+, A-, B+, B-, AB+, AB-, O+, or O-. +So, assume that this set of values must be enforced by the schema definition using the following regex: ```regexp ^(A|B|AB|O)[+-]?$ ``` -At the same time, organ donor must be represented as a binary value: `true`/`false`, `yes`/`no`, depending on the -jurisdiction, and it also might be `unknown`. -This also must be enforced by the schema definition using the `enum` keyword: +At the same time, the organ donor must represent a binary value: `true`/`false`, `yes`/`no`, depending on the +jurisdiction, and it also might be `unknown` and must be enforced by the schema definition using the `enum` keyword: ```yaml enum: @@ -43,16 +41,13 @@ This also must be enforced by the schema definition using the `enum` keyword: - unknown ``` -**NOTE**: +> **Note**: As the original credential schema allows `additionalProperties` to be defined, we assume that two additional claims must get added to the `required` attributes. -as the original credential schema allows `additionalProperties` to be defined, we assume, that two additional claims -must be added to the `required` attributes. - -as the change to the credential schema is a backward compatible, the next version can be `1.1.0` +As the change to the credential schema is backward compatible, the next version can be `1.1.0` --- -The JSON Schema for the given changes must be defined as: +The JSON Schema changes must be defined as follows: ```json { @@ -193,9 +188,9 @@ The curl example might be the following: ```shell curl -X 'PUT' \ - 'https://k8s-dev.atalaprism.io/prism-agent/schema-registry/schemas/f2bfbf78-8bd6-4cc6-8b39-b3a25e01e8ea' \ + 'http://localhost:8080/prism-agent/schema-registry/schemas/f2bfbf78-8bd6-4cc6-8b39-b3a25e01e8ea' \ -H 'accept: application/json' \ - -H 'apikey: $APIKEY' \ + -H "apiKey: $API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "name": "driving-license", diff --git a/docs/general/interdependencies.md b/docs/general/interdependencies.md index 8bca17418d..0eec0dda20 100644 --- a/docs/general/interdependencies.md +++ b/docs/general/interdependencies.md @@ -77,7 +77,7 @@ test ``` **Note:** -- The **Mercury Libraries** are the collection of dependencies with the single cross version. -We will represent as a single box here. But the real dependencies can of a subset of the Mercury Libraries. -For more information about the Mercury Modules Interdependencies see [HERE](./mercury/mercury-library/README.md). -- The **Pollux Libraries** are the collection of dependencies with the single cross version. \ No newline at end of file +- The **Mercury Libraries** collect all dependencies with the single cross version. +We will represent it as a single box here. But the actual dependencies can be of a subset of the Mercury Libraries. +For more information about the Mercury Modules Interdependencies, see [HERE](./mercury/mercury-library/README.md). +- The **Pollux Libraries** collect all dependencies with the single cross version. \ No newline at end of file diff --git a/docs/general/repositories_relationships.md b/docs/general/repositories_relationships.md index 1d01d68dfb..2b351981ae 100644 --- a/docs/general/repositories_relationships.md +++ b/docs/general/repositories_relationships.md @@ -1,14 +1,10 @@ # Repositories & Relationships -The building blocks are the separation of the projects by capabilities that work together. -That makes the Atala PRISM framework. +The building blocks separate the modules by capabilities that work together that make up the Atala PRISM framework. There are dependencies with Atala PRISM v1. -This is the main repository for the Atala PRISM V2. +This repo is the main repository for the Atala PRISM V2. -However the BB are separated into several repositories. -And there are dependencies with the Atala PRISM V1. - -So here we have a simplified view of all Atala repositories and how are they related together: +So here we have a simplified view of all Atala repositories and how they are related: ```mermaid flowchart diff --git a/docs/guides/linting.md b/docs/guides/linting.md index 79f0b68500..99e57a8a05 100644 --- a/docs/guides/linting.md +++ b/docs/guides/linting.md @@ -1,20 +1,20 @@ # Linting -Megalinter is used as the default linter and is run at the point of creating a PR by Github Actions. It is also included as a pre-commit hook. +Megalinter is the default linter and runs at the point of creating a Pull Request (PR) by GitHub Actions. It gets included as a pre-commit hook. ## Configuration -The default configuration for megalinter is found at the root of the repository in `.mega-linter.yml`. +The default configuration for Megalinter is at the repository's root in `.mega-linter.yml`. -This configuration forms the base and additional properties are overridden in the Github Action workflow file `./github/workflows/lint.yml`. +This configuration forms the base. To override additional properties, do so in the GitHub Action workflow file `./github/workflows/lint.yml`. -The Github Action workflow file only impacts the configuration at the point it runs within the continuous integration (CI) environment. +The GitHub Action workflow file only impacts the configuration when it runs within the continuous integration (CI) environment. -This means that megalinter will behave differently when run locally as part of the pre-commit hook [or enacted manually] compared to when run in an automated way in Github Actions as part of CI. +Megalinter's behavior will differ when run locally as part of the pre-commit hook [or enacted manually] compared to when run in an automated way in Github Actions as part of CI. -**Linting is currently in an early adoption phase and due to adoption of Scala 3, it only runs in a mode which does not fail PR checks if errors are found for various linters.** +> **Note:** Linting is currently in an early adoption phase and due to the adoption of Scala 3, it only runs in a mode that does not fail PR checks. -> At the end of this markdown document is a section for changelog, please leave feedback in this section so that we can enable and refine the linting configuration over time +> **Note:** At the end of this markdown document is a section for the changelog. Please leave feedback in this section so that we can enable and refine the linting configuration over time ### Base @@ -50,13 +50,13 @@ This means that megalinter will behave differently when run locally as part of t ## Linting Feedback -Please add any changes made to the linting rules in the below changelog section. This allows us to capture changes to linters over time which allows us to understand the good and the bad with respect to linting. +Please add any changes to the linting rules in the below changelog section. It will allow us to capture changes to linters over time, allowing us to understand the good and the bad concerning linting. -The objective with this feedback is to strike the balance of linting being useful for improving quality but not at the cost of developer velocity [it should not cause pain] +This feedback aims to strike the balance of linting helping improve quality but not at the cost of developer velocity. -The initial configuration has been created by disabling linters which were previously disabled and then changing linters which seem incompatible with our current work to "Enabled but pass even with error" +The initial configuration disables linters which were previously disabled and then changing linters which seem incompatible with our current work to "Enabled but pass even with error" -Please use the following format +Please use the following format: ```text ---