Skip to content

Commit

Permalink
Merge branch 'master' into 3558-create-v1-in-docusaurus-move-all-sdk-…
Browse files Browse the repository at this point in the history 
…related-docs-out-of-cookbook-section-and-one-level-up

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

# Conflicts:
#	concepts/05_credentials/02_ctypes.md
#	concepts/05_credentials/03_claiming.md
#	concepts/05_credentials/04_attestation.md
#	concepts/05_credentials/05_verification.md
  • Loading branch information
@ChrisChinchilla
ChrisChinchilla committed Aug 6, 2024
2 parents ff6c801 + a0bcaae commit da8a54d
Show file tree
Hide file tree
Showing 7 changed files with 226 additions and 155 deletions.
4 changes: 2 additions & 2 deletions concepts/02_did.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ For a detailed developer-oriented guide to KILT DIDs, read the [DID Cookbook sec

## Storing a DID

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.
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 2 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).

Expand All @@ -84,4 +84,4 @@ The more services and keys in the DID, the larger the storage space required and

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.

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.
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.
30 changes: 18 additions & 12 deletions concepts/05_credentials/01_overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -17,22 +17,28 @@ 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 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).

:::
158 changes: 82 additions & 76 deletions concepts/05_credentials/02_ctypes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,124 +2,130 @@
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.
- `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#"`
<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/sdk/cookbook/claiming/ctype-creation), 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:

<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`
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/sdk/cookbook/claiming/ctype-creation).

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/sdk/cookbook/claiming/ctype-creation).
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.
:::
Loading

0 comments on commit da8a54d

Please sign in to comment.