diff --git a/docs/concepts/05_credentials/01_overview.md b/docs/concepts/05_credentials/01_overview.md
index 051ec61bd..42ce07760 100644
--- a/docs/concepts/05_credentials/01_overview.md
+++ b/docs/concepts/05_credentials/01_overview.md
@@ -5,7 +5,7 @@ title: Overview
import ThemedImage from '@theme/ThemedImage';
-**Credentials** consist of a set of claims which belong to a **Claimer**, are attested by an **Attester** and can be verified by **Verifiers**.
+**Credentials** consist of a set of claims which belong to a **Claimer**, are attested by an **Attester**, and that a **Verifier** can verify.
-To get a credential, a Claimer needs to go through following process:
+To get a credential, a Claimer needs to take the following steps:
-1. Find a **CType** a claim should be based on. Potential Attesters and Verifiers might advertise this information themselves.
+1. Find a **CType** to base a claim on. Potential Attesters and Verifiers might advertise this information themselves.
2. Make a **claim** containing a set of properties about themselves.
-3. Potentially request and receive **Terms** and agree on a **Quote** with the potential Attester.
+3. Fulfil any requirement from your Attester. For example, accepting their **Terms** and paying a **Quote**.
4. **Request an attestation** from the Attester.
-5. Wait for the claims to be **attested** by the Attester.
+5. Wait for the Attester to **attest** claims.
-Once attested, the claims are considered to be a valid credential.
+Once attested, the wrapped claims are considered to be a valid credential.
-To verify a credential, a Claimer can generate a presentation of it to a Verifier, with the following process:
+To use a Credential, the Claimer can generate a Credential-Presentation for a Verifier.
+The verification would follow this process:
-1. The Verifier may request a **credential** as the first step, along with with properties to reveal from such Credential.
-2. The Claimer selectively **discloses** the requested properties and signs the generated presentation.
-3. The Verifier **checks** the presentation structure, content and signature, and decides whether they trust the Attester of the presented credential.
+1. The Verifier may request a **Credential** of a CType, along with with properties to reveal.
+He would also provide a **challenge** to ensure the presentations are not recycled.
+2. The Claimer selectively **discloses** the requested properties and signs them along with the challenge to generate a presentation.
+3. The Verifier **verify** the presentation structure, content and signature, and decides whether they trust the Attester of the presented credential.
-Each step is described in more detail in the next sections.
+The next sections describe each step in more detail.
-If you want to learn about how implement the above flow in a dapp that interacts with a browser extension, please refer to the [Credential API specification](https://github.com/KILTprotocol/spec-ext-credential-api).
+:::info
+
+To learn about how to implement the flow above in a dapp that interacts with a browser extension, read the [Credential API specification](https://github.com/KILTprotocol/spec-ext-credential-api).
+
+:::
diff --git a/docs/concepts/05_credentials/02_ctypes.md b/docs/concepts/05_credentials/02_ctypes.md
index aa7e05868..f902ba161 100644
--- a/docs/concepts/05_credentials/02_ctypes.md
+++ b/docs/concepts/05_credentials/02_ctypes.md
@@ -2,124 +2,130 @@
id: ctypes
title: CTypes
---
+
import CodeBlock from '@theme/CodeBlock';
+
import ctypeSchema from '@site/scripts/out/ctype-schema.json.raw!=!raw-loader!@site/scripts/out/ctype-schema.json';
import ctype from '@site/scripts/out/ctype.json.raw!=!raw-loader!@site/scripts/out/ctype.json';
-CTypes are data types specific to KILT that define the structure of a claim (i.e., its data model).
-CTypes are based on JSON Schema, a standard used to annotate and validate JSON documents.
+Claim types (CTypes) are data types specific to KILT that define the structure of a claim (i.e., its data model).
+CTypes are based on [JSON Schema](https://json-schema.org/), a standard used to annotate and validate JSON documents.
The schema defines which properties exist and what their type should be, e.g., a string, a number, an object, etc.
-## JSON Schema
+## CType model JSON schema
-KILT uses [JSON Schema](https://json-schema.org/) (currently draft-07) to validate and annotate data in a strict format.
-This data format is used to define [CType models](https://github.com/KILTprotocol/sdk-js/blob/master/packages/core/src/ctype/CType.schemas.ts).
-The following are all required properties of the schema:
+The following are all required properties of the JSON schema for [CType models](https://github.com/KILTprotocol/sdk-js/blob/master/packages/core/src/ctype/CType.schemas.ts):
-- **Identifier**: `$id` in the format `kilt:ctype:0x{cTypeHash}`.
-- **Reference to CType metaschema (`$schema`)**: Describes what a valid CType must looks like. The latest metaschema is accessible at [ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/).
-- **Title**: Defines a user-friendly name for the CType that makes it easier for users to contextualize.
-- **Properties**: Set of fields (e.g., name, birthdate) that the CType can contain, and hence that the Claimer can have attested.
-- **Type**: Is always `"object"`, instructing the JSON schema validator to expect an object (where each property is a claim about the Claimer in the credential).
-- **Additional properties**: In newer CTypes, *additionalProperties* must be present and must be set to `false`, restricting allowable claims in a credential to those listed in `properties`.
+- `$id`: An **identifier**: in the format `kilt:ctype:0x{cTypeHash}`.
+- `$schema`: A **reference to CType metaschema**: Describes what a valid CType must looks like. You can find the latest metaschema on IPFS at the following address [ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/).
+- `title`: A user-friendly name for the CType that makes it easier for users to contextualize.
+- `properties`: A set of fields (e.g., name, birth date) that the CType can contain, and that the Claimer can have attested. [Read more details about properties below](#properties).
+- `type`: An object containing properties for a claim about the Claimer in the credential.
+- `additionalProperties`: A boolean added since version 1 of CTypes, that must be set and allows or disallows any properties in addition to those in `properties`. If set to `false`, the CType validation will fail if there are any additional properties.
-:::warning
-Deprecation Warning: CType metaschema draft-01
+### Properties
-CTypes based on the `[http://kilt-protocol.org/draft-01/ctype#](http://kilt-protocol.org/draft-01/ctype%23%60)` metaschema are susceptible to faulty or malicious attester integrations that may introduce unexpected properties to a claim.
-Due to this vulnerability, this version of the metaschema is deprecated and its use is discouraged in the creation of new CTypes.
-For optimal security and functionality, it is recommended to use SDK version `0.33.0` or later for creating CTypes.
-This newer version defaults to using the updated metaschema available at [`ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/`](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/%60).
+When creating the accepted properties of a new CType schema, you define each property as a key-value pair.
+The **key** is the property name (such as "age") and the **value** is an object that has a "type" property whose property defines which type the credential property should have (e.g., "number") or a `$ref` property whose value is a reference to another CType or one of its properties. Using a `$ref` allows for nested CTypes
-This also means you should update existing CTypes.
+Each property must have:
-While existing CTypes will continue to work in the short term, we advise to upgrade to the latest metaschema at your earliest convenience.
+- One of the following fields: `type` or `$ref`
+- A type of `string`, `integer`, `number` or `boolean` to define the attribute
+- Reference nested JSON schemas from previously created CTypes with a `uri` using `$ref`.
+- The format field is optionally:
+ - _Date_ format e.g., 2012-04-23T18:25:43.511Z
+ - _Time_ format e.g., T18:25:43.511Z
+ - _URI_ format e.g., "https://www.example.com"
-Old Property Value: `"$schema": "http://kilt-protocol.org/draft-01/ctype#"`
+
+ {ctypeSchema}
+
-New Property Value: `"$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/"`
+When submitted, the CType schema is hashed to generate its own identifier, and it becomes the full CType object:
-**Migration instructions:**
+
+ {ctype}
+
-Attesters are recommended to transition to issuing credentials using upgraded versions of CTypes currently in use.
+## CType metadata
-Using sdk version `0.33.0` or later, you can produce a copy of an existing CType `oldCType` as follows:
+You can link CType Metadata to a given CType to provide title and descriptions in different languages for the whole CType and its properties.
-``` js
-const newCType = CType.fromProperties(oldCType.title, oldCType.properties, 'V1')
-```
+
-The new CType will have the same title and properties as the existing one, but will be based on the new metaschema, resulting in a different hash and id.
-After [registering the new CType on the Kilt blockchain](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md), you can use the new CType as a drop-in replacement in issuing credentials.
-Depending verifiers are recommended to accept both the old and new CType during a transition period.
-Test thoroughly to ensure the correct behaviour and functionality of the new CTypes in your application.
+## Hashing
-If you encounter any issues during the migration process or have questions, refer to the documentation or seek support from the relevant community.
-:::
+Use the hash of the CType to identify and anchor it to the KILT blockchain. Once this is done, it's no longer possible to change or delete the CType schema.
-### Properties
+### Constructing the `hash` for the `$id`
-When creating a new CType schema, the following properties are required:
+KILT uses the `blake2b256` hashing algorithm to compute the hash of CTypes, after sorting the CType object by a canonicalization algorithm to ensure that semantically equivalent CTypes with different orders of their properties result in the same final hash.
-- One of the following fields: `type` or `$ref`
-- A type of `string`, `integer`, `number` or `boolean` to define the attribute
-- Nested JSON schemas can be referenced by a `uri` using `$ref` (giving the advantage of being able to reference previously-created CTypes)
-- The format field is optionally:
- - *Date* format e.g., 2012-04-23T18:25:43.511Z
- - *Time* format e.g., T18:25:43.511Z
- - *URI* format e.g., "https://www.example.com"
+KILT computes the hash from the following fields of the CType schema:
-
- {ctypeSchema}
-
+- `$schema`
+- `properties`
+ - `key`
+ - `$ref`
+ - `type`
+ - `format`
+- `title`
+- `type`
-The CType schema is afterwards hashed to generate its own identifier, and it becomes the full CType object:
+A typical CType ID looks like this: `kilt:ctype:0xda3861a45e0197f3ca145c2c209f9126e5053fas503e459af4255cf8011d5101`.
-
- {ctype}
-
+## Storing and querying CTypes
-## CType Metadata
+As of the [KILT runtime 1.9.0][kilt-runtime-1.9.0], you can query CTypes directly from any KILT archive node.
-CType Metadata can be linked to a given CType to provide title and descriptions in different languages for the whole CType and its properties.
+After creating a CType, its full content is only included in the blockchain block history and its hash and creation block number anchored to the blockchain state.
-
+To query the full content of a CType, use its hash to look up the creation block number, and use that to query any KILT archive node for the extrinsic information about the CType.
-## Hashing
+The returned information includes the whole CType, which is now available for the user to, for example, verify credentials against it.
-The hash of the CType is used to identify and anchor it to the KILT blockchain.
+:::info CType creation cost
-### Constructing the `hash` for the `$id`
+Currently, it costs 0.001 KILT to create a CType on the KILT blockchain.
+
+:::
+
+For a detailed developer-oriented guide to KILT CTypes, read the [CType Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md).
-KILT uses the hashing algorithm `blake2b256` to compute the hash of CTypes.
-Before hashing, the CType object is sorted by a canonicalization algorithm to ensure that semantically equivalent CTypes with different order of their properties result in the same final hash.
+[kilt-runtime-1.9.0]: https://github.com/KILTprotocol/kilt-node/releases/tag/1.9.0
-The hash is computed from the following fields of the CType schema:
+:::danger Deprecation Warning: CType metaschema draft-01
-- `$schema`
-- `properties`
- - `key`
- - `$ref`
- - `type`
- - `format`
-- `title`
-- `type`
+CTypes based on the [Draft 01](http://kilt-protocol.org/draft-01/ctype) metaschema are subject to a vulnerability that could fool an **Attester** by introducing data they never checked.
-A typical CType ID would look like this: `kilt:ctype:0xda3861a45e0197f3ca145c2c209f9126e5053fas503e459af4255cf8011d5101`.
-## Storing and Querying CTypes
+Due to this vulnerability, this version of the metaschema is deprecated and its use is discouraged when creating new CTypes.
-As of the [KILT runtime 1.9.0][kilt-runtime-1.9.0], CTypes can be queried directly from any KILT archive node!
+For optimal security and functionality, use SDK version `0.33.0` or later for creating CTypes.
+This newer version defaults to using the updated metaschema available at [`ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/`](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq).
-After creating a CType, its full content is included only in the blockchain block history, while its hash and creation block number is anchored to the blockchain state.
+This also means you should update existing CTypes.
+While existing CTypes continue to work in the short term, we advise to upgrade to the latest metaschema at your earliest convenience.
-Querying the full content of a CType then becomes trivial, since the CType hash can be used to look up its creation block number, and then that information can be used to ask any KILT archive node for the extrinsic information about the CType creation.
-The information includes the whole CType, which is now available for the user to, e.g., verify credentials against it.
+Old Property Value: `"$schema": "http://kilt-protocol.org/draft-01/ctype"`
+New Property Value: `"$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/"`
-For adding a CType, a constant fee of 0.001 KILT is required.
+## Migration instructions
-For a detailed developer-oriented guide to KILT CTypes, see our [CType Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md).
+Attesters should transition to issuing credentials using upgraded versions of CTypes currently in use.
-[kilt-runtime-1.9.0]: https://github.com/KILTprotocol/kilt-node/releases/tag/1.9.0
+Using sdk version `0.33.0` or later, you can produce a copy of an existing CType `oldCType` as follows:
+
+```js
+const newCType = CType.fromProperties(oldCType.title, oldCType.properties, 'V1')
+```
+
+The new CType has the same title and properties as the existing one, but be based on the new metaschema, resulting in a different hash and id.
+After [registering the new CType on the KILT blockchain](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md), you can use the new CType as a drop-in replacement in issuing credentials.
+
+Verifiers depending on these CTypes should accept both the old and new CType during a transition period.
+Test thoroughly to ensure the correct behavior and functionality of the new CTypes in your application.
+:::
diff --git a/docs/concepts/05_credentials/03_claiming.md b/docs/concepts/05_credentials/03_claiming.md
index 7cda3b612..1779099f6 100644
--- a/docs/concepts/05_credentials/03_claiming.md
+++ b/docs/concepts/05_credentials/03_claiming.md
@@ -4,29 +4,37 @@ title: Claims
---
import CodeBlock from '@theme/CodeBlock';
-
-
import Claim from '@site/scripts/out/claim.json.raw!=!raw-loader!@site/scripts/out/claim.json';
As KILT is an open system, entities can make claims about any other entities, including themselves.
-A claim (as in the real world) can only be trusted if another trusted entity (we call them Attesters) *certifies* this claim.
-Therefore, Verifiers might trust different Attesters for distinct scenarios.
+An entity can only trust a claim (as in the real world) if another trusted entity (called **Attesters**) *certifies* this claim.
+Therefore, **Verifiers** might trust different **Attesters** for distinct scenarios.
+
+:::info Role recap
+- **Claimers** want information about themselves certified.
+They also issue credentials, but these remain invalid without an attestation.
+- **Attester** check the truthfulness of a claim and certify them.
+- **Verifiers** accept the credentials, only verifying that your certification are legitimate.
+:::
-## Creating a Claim
+## Creating a claim
In KILT, claims are based on claim types (CTypes).
-Hence, given a CType, a Claimer only needs to create a claim with the properties specified in the CType schema.
-The resulting claim contains a reference to the CType by its hash and includes the identity of the claim subject (identified by the `owner` property).
+Given a CType, a Claimer only needs to create a claim with the properties specified in the CType schema.
+The resulting claim contains a reference to the CType by its hash and includes the identity of the claim subject (identified by the `owner` property, which has the value of a KILT DID).
{Claim}
-## Requesting a Credential
+## Requesting a credential
+
+Once the Claimer has wrapped their claims into a `Credential`, they send it to the chosen Attester using any messaging system for **certification**, i.e. attested.
+
+The to-be-attested `Credential` contains the original claim, data needed for future selective disclosure of the claim contents (read more in the [Verification documentation](./05_verification.md)), and the legitimation and / or delegation ID of the Attester and the credential root hash, used to identify both the credential and its on-chain attestation.
-Once the Claimer has created a claim, they need to get it *certified*, i.e., attested, by an Attester.
-The resulting `Credential` must then be sent to the chosen Attester using any messaging system.
+:::info
-The to-be-attested `Credential` contains the original claim, data needed for future selective disclosure (more on that in the [Verification section](./05_verification.md)) of the claim contents, the legitimation and / or delegation ID of the Attester and the credential root hash, which is used to identify both the credential and its on-chain attestation.
+For a detailed developer-oriented guide to KILT claims, read the [Claim Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md).
-For a detailed developer-oriented guide to KILT claims, see our [Claim Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md).
+:::
diff --git a/docs/concepts/05_credentials/04_attestation.md b/docs/concepts/05_credentials/04_attestation.md
index 666b6ef3b..33c9c2aae 100644
--- a/docs/concepts/05_credentials/04_attestation.md
+++ b/docs/concepts/05_credentials/04_attestation.md
@@ -3,20 +3,26 @@ id: attestation
title: Attestations
---
-In KILT, the terms Attestation and Credential are often used interchangeably, albeit their meaning is slightly different.
-Precisely a *credential* includes the original claimer's data and all the information linked to it, while an *attestation* only refers to the on-chain proof that a given credential has been attested.
+KILT uses the terms Attestation and Credential interchangeably, but their meaning is different.
+A _Credential_ includes the original claimer's data and all the information linked to it, while an _Attestation_ only refers to the on-chain proof that a given credential has been attested.
-To write an attestation on the blockchain, the Attester checks the validity of the received to-be-attested `Credential`, ensuring that the data inside it match the requirements of the attestation (e.g., that the user's name is indeed Alice).
+To write an attestation on the KILT blockchain, the Attester checks the validity of the received to-be-attested `Credential` data, ensuring that the data inside it matches the requirements of the attestation. For example, that the user's name is indeed Alice.
-After that, the Attester writes the `Credential`'s root hash on the KILT blockchain, basically certifying that a credential with that root hash is valid.
-The Claimer can hence monitor the blockchain themselves to listen for the event resulting from the attestation process, marking the moment in which the credential is attested and hence becomes usable.
+After that, the Attester writes the `Credential`'s root hash on the KILT blockchain, certifying that a credential with that root hash is valid.
+The Claimer can monitor the blockchain to listen for the event resulting from the attestation process, marking when the credential is attested and usable.
-After the credential has been attested, the Claimer can store it in their own wallet and can now use it with Verifiers that trust credentials issued by that Attester.
+After the credential has been attested, the Claimer can store it in their wallet and can now use it with Verifiers that trust credentials issued by that Attester.
-For a detailed developer-oriented guide to KILT attestations, see our [Attestation Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md).
+:::info
-### Storing Attestations
+For a detailed developer-oriented guide to KILT attestations, read the [Attestation cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md).
+
+:::
+
+### Storing attestations
Storing a attestation in the blockchain requires providing a constant deposit, which is currently around 0.12 KILT. The deposit amount is calculated based on the worst-case scenario for a attestation, where the maximum storage for one attestation reaches 179 bytes.
-The deposit serves as a security measure to ensure the integrity of the blockchain and incentivize users to manage their attestation responsibly. By requiring a deposit, it discourages spamming or unnecessary creation of attestation.
-The deposit can be reclaimed by the attester by deleting their attestation. Revoking them is not sufficient.
+The deposit serves as a security measure to ensure the integrity of the blockchain and incentivize users to manage their attestation responsibly.
+By requiring a deposit, it discourages spamming or unnecessary creation of attestation.
+The attester can reclaim the deposit by deleting their attestation.
+Revoking them isn't sufficient as the deposit still shows in chain storage, but marked as invalid.
\ No newline at end of file
diff --git a/docs/concepts/05_credentials/05_verification.md b/docs/concepts/05_credentials/05_verification.md
index 17c9839a9..0c50f9dcb 100644
--- a/docs/concepts/05_credentials/05_verification.md
+++ b/docs/concepts/05_credentials/05_verification.md
@@ -3,68 +3,111 @@ id: verification
title: Verification
---
-KILT allows a Verifier to check if the information in a credential presented by a Claimer is correct and valid.
+KILT lets a Verifier check if the information in a credential presented by a Claimer is correct and valid.
With the presentation of the credential, the Claimer also presents evidence that a third party (i.e., an Attester) ensured the correctness of the Claimer’s attributes.
-The Verifier trusts this third party either because they trust their reputation directly or they trust a delegation structure that this Attester is part of (e.g., a State department issuing driving licenses).
+The Verifier trusts this third party either because they trust their reputation directly or they trust a delegation structure that this Attester is part of.
+For example, a State department issuing driving licenses.
For the verification process:
-- The Claimer needs their credential and the private key associated with their identifier
-- The Verifier needs the identifier of the trusted Attester
+- The Claimer needs their credential and the private key associated with their identifier
+- The Verifier needs the identifier of the trusted Attester
-During the verification process the Claimer wants to prove three things to the Verifier:
+During the verification process the Claimer wants to prove the following things to the Verifier:
-- The credential is valid (i.e., not revoked by its Attester)
-- The attributes in the credential actually refer to the Claimer
-- The credential contains information that is relevant for the Verifier in this use case
+- The credential is valid (i.e., not revoked by its Attester)
+- The attributes in the credential actually refer to it's Presenter
+- The credential contains information relevant for the Verifier for this use case
+- That an Attester ensured the correct and trustworthy-ness of the Claimer's attributes
-## Requesting a Credential from a Claimer
+## Requesting a credential from a Claimer
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, which have to be regarded 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. More on "selective disclosure" later.
-- **Challenge**: a nonce, which the Verifier can make use of to ensure that the presentation generated by the Claimer is fresh and is not being replayed by some other older interactions. More on that later.
-## 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.
+- `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).
+
+ :::
+- `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
+{
+ "body": {
+ "content": {
+ "cTypes": [
+ {
+ "cTypeHash": "0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac",
+ "trustedAttesters": [
+ "did:kilt:4pehddkhEanexVTTzWAtrrfo2R7xPnePpuiJLC7shQU894aY"
+ ],
+ "requiredProperties": [
+ "Email"
+ ]
+ }
+ ],
+ "challenge": "0x5a1a17eca9ddf6b4d14dffb2abd1411fe9235927975a246b3963db86dfb7de5f"
+ },
+ "type": "request-credential"
+ }
+}
+```
+
+## 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.
-For example, if 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.
-
-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).
-
:::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
+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 required in the specific context.
+
+:::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).
+
+:::
+
+## 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 will not match any attestation on the chain.
-On the other hand, if an attestation with the calculated hash can be found on the chain and has not been revoked, the credential is valid.
+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 the Verifier can find an attestation with the calculated hash on the chain and hasn't been revoked, the credential is valid.
-However, this does not 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.
+However, this doesn't give the Verifier the guarantee that the Claimer is the rightful/legitimate owner of the credential presented.
-### Verifying the Owner of the Presented Credential
+### 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 can be sure that the Claimer is the legitimate owner of the credential.
-The Verifier assumes that the private key for the DID public key is only known to the owner of the credential, and is not shared across users.
-Therefore, when requesting the Claimer to generate a presentation, the Verifier challenges the Claimer to sign a nonce (a random number that is used once) that the Verifier sends together with their request.
+### Verifying the content of the presented 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 can be sure that the Claimer is indeed the legitimate owner of the 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.
-### Verifying the Content of the Presented Credential
+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.
-After the Verifier has checked that the credential is valid and belongs to the presenting Claimer, they still need to verify that they have received all the required information as the presentation received could contain the right values, but not the right semantics.
-For example, the _age_ property could have different meanings depending on whether it is 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 include at least all of 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, see our [Verification Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md).
diff --git a/docs/concepts/05_credentials/06_public_credentials.md b/docs/concepts/05_credentials/06_public_credentials.md
index 56c082cee..e220b1962 100644
--- a/docs/concepts/05_credentials/06_public_credentials.md
+++ b/docs/concepts/05_credentials/06_public_credentials.md
@@ -7,19 +7,21 @@ import CodeBlock from '@theme/CodeBlock';
import PublicCredential from '@site/scripts/out/public-credential.json.raw!=!raw-loader!@site/scripts/out/public-credential.json';
-Given that with [AssetDIDs][asset-did-concepts] there is now a way to uniquely identify assets regardless of the chain they live on or their current owner, KILT also allows owners of an on-chain DID with an assertion key (a.k.a. attesters) to issue credentials to those assets.
+[AssetDIDs][asset-did-concepts] give a way to uniquely identify assets regardless of the blockchain they live on or their current owner.
+KILT allows owners of an on-chain DID with an assertion key (a.k.a. attesters) to issue credentials to those assets.
-Public credentials are not very different in their structure from traditional KILT credentials.
-The main difference is that, since they are public, public credentials do not have any selective disclosure capabilities, hence all the cryptographic information required to enable those is stripped away from the credential content.
-Everything else remains as for regular credentials, including the requirement for its structure to match a given CType, and optionally the presence of some delegation information.
+Public credentials aren't that different in their structure from traditional KILT credentials.
+The main difference is that, since they're public, they don't have selective disclosure capabilities.
+This is because the cryptographic information required to enable this is stripped away from the credential content.
{PublicCredential}
-:::info Anyone can be an attester!
-While traditional KILT credentials are held in the wallet of their owner, who then decides what credential to share with whom, public credentials are, as the name suggests, public by design.
-This means that when reading all the credentials issued for a given asset, consumers should be aware of the level of trust they have towards the issuer of each credential, as is the case for traditional KILT credentials.
+:::warning Anyone can be an attester!
+While the owner of normal KILT credentials holds them in their wallet and decides what credential to share with who, public credentials are, as the name suggests, public by design.
+
+This means that when reading the credentials issued for a given asset, consumers should be aware of the level of trust they have towards the issuer of each credential.
:::
[asset-did-concepts]: ../04_asset_dids.md
\ No newline at end of file