Draft

Signed-off-by: Chris Chinchilla <[email protected]>

docs/concepts/05_credentials/05_verification.md

@@ -22,66 +22,78 @@ During the verification process the Claimer wants to prove three things to the V
 
 ## Requesting a credential from a Claimer
 
-<!-- TODO: Code example? -->
 The Verifier may request a credential from a Claimer, providing the following data:
 
--   `CTypes`: Which CTypes the Verifier can work with for the use case. They can provide multiple options, to regard as alternatives.
--   **TrustedAttesters**: Which Attesters are considered trusted for each specified CType.
--   **requiredProperties**: Which properties for each specified CType must at least be revealed for the presentation to be considered sufficient.
+-   `cTypeHash`: Which CType hashes the Verifier can work with for the use case. They can provide multiple options, to regard as alternatives.
+-   `trustedAttesters`: Which Attesters to consider trusted for each specified CType.
+-   `requiredProperties`: Which properties for each specified CType must at least be revealed for the Verifier to consider the presentation sufficient.
 
     :::info
 
     [Read more on selective disclosure](#presenting-a-credential-with-selective-disclosure).
 
     :::
+<!-- TODO: Only example I can find that shows this has it outside of the CTypes -->
+-   `challenge`: A nonce, which the Verifier can use to ensure that the presentation generated by the Claimer is fresh and not replayed by some other older interactions.
 
--   **Challenge**: A nonce, which the Verifier can use to ensure that the presentation generated by the Claimer is fresh and not replayed by some other older interactions.
+### Example
+
+```json
+  "requirements": [{
+    "cTypeHash":"0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac",
+    "trustedAttesters":["did:kilt:4pehddkhEanexVTTzWAtrrfo2R7xPnePpuiJLC7shQU894aY"],
+    "requiredProperties": ["Email"]
+  }],
+```
 
 ## Presenting a credential with selective disclosure
 
 Given the `requiredProperties` specified by the Verifier, the Claimer can decide how much of the information they wish to reveal before they generate the presentation and send it to the Verifier.
 If supported by the Verifier, they can choose to hide attributes and thus only disclose a subset of the original claim data.
 
+:::caution
+The presentations can still be correlated, since the hash of the credential always stays the same, even when creating new presentations and selecting different attributes to show.
+:::
+
 For example, verifying a driving license only requires the verification of the driver's name and picture. A Claimer can decide to hide additional information such as age and place of residence.
-This increases the privacy of the Claimer since they only need to show attributes that are required in the specific context.
+This increases the privacy of the Claimer since they only need to show attributes required in the specific context.
 
-For a detailed developer-oriented guide to KILT presentation creation, see our [Presentation Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md).
+:::info
+
+For a detailed developer-oriented guide to KILT presentation creation, read the [presentation creation cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md).
 
-:::caution
-The presentations can still be correlated, since the hash of the credential always stays the same, even when creating new presentations and selecting different attributes to show.
 :::
 
 ## Verifying a presentation
 
 The Verifier receives the presentation from the Claimer, re-calculates the root hash of the credential from which the presentation was generated, and queries the KILT blockchain to obtain the associated attestation information, including the revocation status of the credential.
 
 If the Claimer tampered with the credential, the re-calculated root hash won't match any attestation on the chain.
-On the other hand, if an attestation with the calculated hash can be found on the chain and hasn't been revoked, the credential is valid.
+On the other hand, if the Verifier can find an attestation with the calculated hash on the chain and hasn't been revoked, the credential is valid.
 
 However, this doesn't give the Verifier the guarantee that the Claimer is the rightful/legitimate owner of the credential presented.
-That problem is addressed in the next section.
 
 ### Verifying the owner of the presented credential
 
 When issued, a credential is linked to the KILT decentralized identifier (DID) of the original Claimer.
-The DID can be resolved to the public key of the Claimer according to the [KILT DID specification](https://github.com/KILTprotocol/spec-kilt-did).
+The Verifier can resolve the DID to the public key of the Claimer according to the [KILT DID specification](https://github.com/KILTprotocol/spec-kilt-did).
 
 The Verifier assumes that the private key for the DID public key is only known to the owner of the credential, and isn't shared across users.
 Therefore, when requesting the Claimer to generate a presentation, the Verifier challenges the Claimer to sign a nonce (a random number used once) that the Verifier sends together with their request.
 
-If the Claimer can sign both the nonce and the presentation with the private key that only the credential's owner should have knowledge of, the Verifier won't be sure that the Claimer is indeed the legitimate owner of the credential.
+If the Claimer can sign both the nonce and the presentation with the private key that only the credential's owner should have knowledge of, the Verifier won't be sure that the Claimer is the legitimate owner of the credential.
 
 ### Verifying the content of the presented credential
 
 After the Verifier has checked that the credential is valid and belongs to the presenting Claimer, they need to verify that they have received all the required information.
 This is to verify that the presentation received contains the right values **and** the right semantics.
 
-For example, the _age_ property could have different meanings depending on whether it's defined for a passport CType or a Whisky certificate CType.
+For example, the `age` property could have different meanings depending on whether it's defined for a passport CType or a Whisky certificate CType.
 Therefore, the Verifier has to check if the CType matches one of the requested CTypes, and that the properties disclosed in the presentation includes all the properties requested for that CType presentation.
 
 :::info
 
-For a detailed developer-oriented guide to KILT credential verification, read the [Verification Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md).
+For a detailed developer-oriented guide to KILT credential verification, read the [verification cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md).
 
 :::