Docs Audit: top level concepts sections

code_examples/sdk_examples/src/core_features/getting_started/03_fetch_did.ts

@@ -4,13 +4,13 @@ import * as Kilt from '@kiltprotocol/sdk-js'
 export async function main(): Promise<Kilt.DidUri | null> {
   let apiConfig = Kilt.ConfigService.get('api')
   const encodedJohnDoeDetails =
-    await apiConfig.call.did.queryByWeb3Name('john_doe')
+    await apiConfig.call.did.queryByWeb3Name('kiltnerd123')
 
   // This function will throw if johnDoeOwner does not exist
   const {
     document: { uri }
   } = Kilt.Did.linkedInfoFromChain(encodedJohnDoeDetails)
-  console.log(`My name is john_doe and this is my DID: "${uri}"`)
+  console.log(`My name is kiltnerd123 and this is my DID: "${uri}"`)
 
   return uri
 }

code_examples/sdk_examples/src/core_features/getting_started/index.ts

@@ -12,7 +12,7 @@ import { main as verifyCredential } from './06_verify_credential'
 async function fetchDidAndCredential() {
   const johnDoeDid = await fetchJohnDoeDid()
   if (!johnDoeDid)
-    throw new Error('"john_doe" is not associated to any DID on Spiritnet')
+    throw new Error('"kiltnerd123" is not associated to any DID on Spiritnet')
   const endpoints = await fetchJohnDoeEndpoints(johnDoeDid)
   if (!endpoints || !endpoints.length)
     throw new Error(`DID doesn't include services`)

code_examples/sdk_examples/src/core_features/web3names/index.ts

@@ -45,13 +45,13 @@ export async function runAll(
     throw new Error('web3name is registered for a wrong DID')
   }
 
-  console.log('3 w3n) Query credentials for "john_doe" web3name')
+  console.log('3 w3n) Query credentials for "kiltnerd123" web3name')
   try {
-    await queryPublishedCredentials('john_doe')
+    await queryPublishedCredentials('kiltnerd123')
   } catch (e) {
     if (e instanceof FetchError) {
       console.log(
-        'Query credentials for "john_doe" web3name failed because of bad IPFS gateway. Ignoring this.'
+        'Query credentials for "kiltnerd123" web3name failed because of bad IPFS gateway. Ignoring this.'
       )
     } else {
       // This one should not have happened.

docs/concepts/01_what_is_kilt.md

@@ -10,12 +10,12 @@ The core component of KILT is a digital identity protocol for:
 1. Generating and managing [**decentralized identifiers (DIDs)**](./10_glossary.md#Decentralized-Identifiers-(DID))
 2. Issuing and presenting digital [**verifiable credentials (VCs)**](./10_glossary.md#verifiable-credentials).
 
-In contrast to other centralized alternatives, KILT features self-sovereign data as well as revocable [credentials](./10_glossary.md#credential) anchored to the KILT blockchain.
+In contrast to other centralized alternatives, KILT features self-sovereign data and revocable [credentials](./10_glossary.md#credential) anchored to the KILT blockchain.
 
 KILT was built to be a business enabler, not only for the software industry but also for any entity.
 Such entities can establish a business model based on the trust infrastructure KILT provides, which is an essential building block of Web 3.0.
 
-## What KILT Provides
+## What KILT provides
 
 In particular, KILT provides:
 
@@ -26,22 +26,22 @@ In particular, KILT provides:
 KILT's main goal is to generate a level playing field for companies to explore new business models related to trust relationships and data sovereignty.
 KILT enables businesses and governments to rely on a common standard owned by everyone participating and not by a single company or set thereof.
 
-## The Problem
+## The problem
 
 In the beginning, identity and trust between entities were organized in a fully decentralized way.
 Individuals created trust relationships directly between them based on their observations.
 Of course, this had major drawbacks:
 
 * The size of the personal social network is limited
-* It is not trivial to judge the trustworthiness of an individual
-* It is hard to prove one's own identity to outsiders
+* It's not trivial to judge the trustworthiness of an individual
+* It's hard to prove one's own identity to outsiders
 
 When people started to organize themselves in bigger groups, founding villages and cities, those drawbacks were amplified and people needed to address them.
 People introduced mechanisms to create trust relationships between groups by issuing some form of attestation.
-In this way, people who do not know the individual directly but who trusted the group that gave the attestation, for example, a carpenter's guild, a monastery or a Scottish clan, could verify certain properties about another individual.
+In this way, people who don't know the individual directly but who trusted the group that gave the attestation. For example, a carpenter's guild, a monastery or a Scottish clan could verify certain properties about another individual.
 When the organizational structures grew further and large bureaucratic nations emerged, the authorities issuing those attestations and the scope of the trust relationships also grew.
 
-Though we can now see a more and more centralized way of organizing trust, the actual information that makes up an identity is still handed out directly to the individual, who is still responsible for their data.
+While there is now a more centralized way of organizing trust, the actual information that makes up an identity is still handed out directly to the individual, who is still responsible for their data.
 Take official personal documents like passports as an example.
 Trusted entities issue them and hand them out to the holder.
 That holder then has full control of their credential (their passport) and can use it wherever needed.
@@ -54,10 +54,10 @@ Every time users log into any service, they generate new data points which are t
 
 KILT Protocol aims to change that and give users back control over their data.
 
-## The Solution
+## The solution
 
 KILT provides a protocol and the tools for people to manage their own data, and to build a [digital identity](./10_glossary.md#digital-identity) by collecting credentials issued by trusted entities.
-Such credentials are not publicly available but stay within the user's control.
+Such credentials aren't publicly available but stay within the user's control.
 This is similar to the approach used for centuries before big corporations monetized our data.
 
 The core ideas are:

docs/concepts/02_did.md

@@ -4,12 +4,18 @@ title: KILT Decentralized Identifiers (DIDs)
 ---
 
 A KILT decentralized identifier (DID) is a string of letters and numbers uniquely identifying each KILT user.
-A DID can be thought of as a container of different keys that are all under the control of the same DID subject.
-For the official W3C DID spec, please visit the [DID Core spec page](https://www.w3.org/TR/did-core/); for the official KILT DID method specification, see the [KILT DID spec page](https://github.com/KILTprotocol/spec-kilt-did).
 
-The simplest type of KILT DID is called a **light DID**, because it can be generated and used offline without any internet connection (hence any connection with the KILT blockchain at all).
-Although very cheap, light DIDs are not very flexible and are only suitable for low-security use cases.
-In more complex use cases, an on-chain **full DID** is required, which allows the subject to store several different keys (and key types) and replace them over time, with the support of the KILT blockchain.
+Think of a DID as a container of different keys all under the control of the same DID subject.
+
+:::info DID spec
+
+For the official W3C DID spec, read the [DID Core spec page](https://www.w3.org/TR/did-core/); for the official KILT DID method specification, read the [KILT DID spec page](https://github.com/KILTprotocol/spec-kilt-did).
+
+:::
+
+The simplest type of KILT DID is a **[light DID](#light-dids)**, because you can generate and use it offline and no connection with the KILT blockchain.
+Although cheap, light DIDs aren't flexible and are only suitable for low-security use cases.
+In more complex use cases, you need an on-chain **[full DID](#full-dids)**, which allow the subject to store different keys and key types and replace them over time by using the KILT blockchain.
 
 ## Light DIDs
 
@@ -19,48 +25,63 @@ The following is an example of a light KILT DID:
 did:kilt:light:014nv4phaKc4EcwENdRERuMF79ZSSB5xvnAk3zNySSbVbXhSwS
 ```
 
-Beyond the standard prefix `did:kilt:`, the `light:` component indicates that this DID is a light DID, hence it can be resolved and utilized offline.
+Beyond the standard prefix `did:kilt:`, the `light:` component indicates that this DID is a light DID, hence it can be resolved and used offline.
+
+<!-- TODO: What is a service? -->
 
-Light DIDs optionally support the specification of an **encryption key** (of one of the supported key types) and services, which are both serialized, encoded and added at the end of the DID, like the following:
+Light DIDs optionally support the specification of an **encryption key** (of one of the supported key types) and services, which are both serialized, encoded, and added at the end of the DID, like the following:
 
 ```
 did:kilt:light:014nv4phaKc4EcwENdRERuMF79ZSSB5xvnAk3zNySSbVbXhSwS:z1ERkVVjngcarMbJn6YssB1PYULescQneSSEfCTJwYbzT2aK8fzH5WPsp3G4UVuLWWfsTayketnFV74YCnyboHBUvqEs6J8jdYY5dK2XeqCCs653Sf9XVH4RN2WvPrDFZXzzKf3KigvcaE7kkaEwLZvcas3U1M2ZDZCajDG71winwaRNrDtcqkJL9V6Q5yKNWRacw7hJ58d
 ```
 
 ## Full DIDs
 
-As mentioned above, the creation of a full DID requires interaction with the KILT blockchain.
-Therefore, the DID creation operation must be submitted by a KILT address with enough funds to pay the transaction fees and the required deposit.
+The creation of a full DID requires interaction with the KILT blockchain.
+Therefore, a KILT address with enough funds to pay the transaction fees and the required deposit must submit the DID creation operation.
 
 The following is an example of a full KILT DID:
 
 ```
 did:kilt:4rp4rcDHP71YrBNvDhcH5iRoM3YzVoQVnCZvQPwPom9bjo2e
 ```
 
-Here, there is no `light:` component, which indicates that the DID is a full DID and that the keys associated with it must not be derived from the DID identifier, but must be retrieved from the KILT blockchain.
+Above, there is no `light:` component.
+This indicates that the DID is a full DID and that you can't derive the keys associated with it from the DID identifier, but retrieve them from the KILT blockchain.
 
-Along with an authentication key, an encryption key, and services, a full DID also supports an **attestation key**, which must be used to write CTypes and attestations on the blockchain, and a **delegation key**, which must be used to write delegations on the blockchain.
+Along with an authentication key, encryption key, and services, a full DID also supports an **attestation key**, which you must use to write CTypes and attestations on the blockchain, and a **delegation key** to write delegations on the blockchain.
 
-## Migrating a Light DID to a Full DID
+## Migrating a light DID to a full DID
 
 The **migration** of a DID means that a light, off-chain DID is anchored to the KILT blockchain, supporting all the features that full DIDs provide.
 In the current version (v1) of the KILT DID protocol, a light DID of the form `did:kilt:light:014nv4phaKc4EcwENdRERuMF79ZSSB5xvnAk3zNySSbVbXhSwS` would become a full DID of the form `did:kilt:4nv4phaKc4EcwENdRERuMF79ZSSB5xvnAk3zNySSbVbXhSwS`.
-Note that the identifier of the two DIDs, apart from the initial `01` sequence of the light DID, are the same since both DIDs are derived from the same seed.
 
-**Once a light DID is migrated, all the credentials collected by the light DID can only be presented using the migrated on-chain DID.**
-This is by design, as it is assumed that the user had valid reasons to migrate the DID, and as on-chain DIDs offer greater security guarantees.
-KILT will thus reject light DID signatures even if the original claim in the credential was generated with that off-chain DID.
+:::note
+
+The identifier of the two DIDs, apart from the initial `01` sequence of the light DID, are the same since both DIDs are derived from the same seed.
 
-For a detailed developer-oriented guide to KILT DIDs, see our [DID Cookbook section](../develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md).
+:::
+
+**Once you migrate a light DID, you can only present all the credentials collected by the light DID using the migrated on-chain full DID.**
+
+This restriction is by design, as it's assumed that the user had valid reasons to migrate the DID, as on-chain DIDs offer greater security guarantees.
+KILT thus rejects light DID signatures even if the original claim in the credential was generated with that off-chain DID.
+
+:::tip
+
+For a detailed developer-oriented guide to KILT DIDs, read the [DID Cookbook section](../develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md).
+
+:::
 
 ## Storing a DID
 
-Storing a DID in the blockchain requires a deposit, consisting of a base deposit and an additional fee. The base deposit is a fixed amount of 4 KILT, while the additional fee is 0.05 KILT.
+Storing a DID on the KILT blockchain requires a deposit, consisting of a base deposit and an additional fee. The base deposit is a fixed amount of 4 KILT, while the additional fee is 0.05 KILT.
 
 In addition to the base deposit and fee, the total deposit increases based on the storage space used by the DID. Each byte of storage occupied by the DID requires a deposit of 50 micro KILT (0.000005 KILT).
-The overall size of the DID is determined by the inclusion of services and keys. The more services and keys in the DID, the larger the storage space required and, consequently, the higher the additional deposit.
+
+The inclusion of services and keys determines the overall size of the DID.
+The more services and keys in the DID, the larger the storage space required and, consequently, the higher the additional deposit.
 
 When updating the DID, the deposit is automatically adjusted to match the updated size. This ensures that the deposit accurately reflects the current storage requirements of the DID, whether they increase or decrease.
 
-The deposit can be reclaimed when the DID is deleted from the blockchain, allowing users to retrieve the deposited amount. However, please note that the additional fee cannot be refunded once it has been paid.
+You can reclaim the deposit when the DID is deleted from the blockchain, allowing users to retrieve the deposited amount. However, the additional fee can't be refunded once paid.