Docs audit for credentials section

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.
 
 <center>
 <ThemedImage
@@ -17,22 +17,26 @@ import ThemedImage from '@theme/ThemedImage';
 />
 </center>
 
-To get a credential, a Claimer needs to go through following process:
+To get a credential, a Claimer needs to take the following process:
 
-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. Optionally request and receive **Terms** and agree on a **Quote** with the potential Attester.
 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.
 
 To verify a credential, a Claimer can generate a presentation of it to a Verifier, with the following process:
 
-1. The Verifier may request a **credential** as the first step, along with with properties to reveal from such Credential.
+1. The Verifier may request a **credential** as the first step, along with with properties to reveal from the 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.
 
-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).
+
+:::

docs/concepts/05_credentials/02_ctypes.md

@@ -2,124 +2,131 @@
 id: ctypes
 title: CTypes
 ---
+
 import CodeBlock from '@theme/CodeBlock';
 
 <!-- Taken from https://github.com/webpack-contrib/raw-loader/issues/91#issuecomment-648830498 -->
+
 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.
+<!-- TODO: Since when? -->
+-   `additionalProperties`: A boolean added since version x 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#"`
+<CodeBlock className="language-json" title="CType schema example">
+  {ctypeSchema}
+</CodeBlock>
 
-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:** 
+<CodeBlock className="language-json" title="Full CType example">
+  {ctype}
+</CodeBlock>
 
-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')
-```
+<!-- TODO: Add example of CType metadata -->
 
-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.
 
-### 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, 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:
 
-<CodeBlock className="language-json" title="CType schema example">
-  {ctypeSchema}
-</CodeBlock>
+-   `$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`.
 
-<CodeBlock className="language-json" title="Full CType example">
-  {ctype}
-</CodeBlock>
+## 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.
 
-<!-- TODO: Add example of CType metadata -->
+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`
+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:
+<!-- TODO: Do we still need this? -->
 
-- `$schema`
-- `properties`
-  - `key`
-  - `$ref`
-  - `type`
-  - `format`
-- `title`
-- `type`
+:::danger Deprecation Warning: CType metaschema draft-01
 
-A typical CType ID would look like this: `kilt:ctype:0xda3861a45e0197f3ca145c2c209f9126e5053fas503e459af4255cf8011d5101`.
+CTypes based on the [Draft 01](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 when creating new CTypes.
+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/%60).
 
-## Storing and Querying CTypes
+This also means you should update existing CTypes.
 
-As of the [KILT runtime 1.9.0][kilt-runtime-1.9.0], CTypes can be queried directly from any KILT archive node!
+While existing CTypes continue to work in the short term, we advise to upgrade to the latest metaschema at your earliest convenience.
 
-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.
+Old Property Value: `"$schema": "http://kilt-protocol.org/draft-01/ctype#"`
+New Property Value: `"$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/"`
 
-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.
+## Migration instructions
 
-For adding a CType, a constant fee of 0.001 KILT is required.
+Attesters should transition to issuing credentials using upgraded versions of CTypes currently in use.
 
-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).
+Using sdk version `0.33.0` or later, you can produce a copy of an existing CType `oldCType` as follows:
 
-[kilt-runtime-1.9.0]: https://github.com/KILTprotocol/kilt-node/releases/tag/1.9.0
+```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.
+:::

docs/concepts/05_credentials/03_claiming.md

@@ -4,29 +4,31 @@ title: Claims
 ---
 
 import CodeBlock from '@theme/CodeBlock';
-
-<!-- Taken from https://github.com/webpack-contrib/raw-loader/issues/91#issuecomment-648830498 -->
 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.
+An entity can only trust a claim (as in the real world) if another trusted entity (called Attesters) *certifies* this claim.
+<!-- TODO: But what's a verifier? -->
 Therefore, Verifiers might trust different Attesters for distinct scenarios.
 
-## 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.
+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).
 
 <CodeBlock className="language-json" title="Claim example">
   {Claim}
 </CodeBlock>
 
-## Requesting a Credential
+## Requesting a credential
+
+Once the Claimer has created a claim, and Attester needs to certify it and the resulting `Credential` sent to the chosen Attester using any messaging system.
+
+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).
+:::