diff --git a/docs/concepts/01_what_is_kilt.md b/concepts/01_what_is_kilt.md similarity index 100% rename from docs/concepts/01_what_is_kilt.md rename to concepts/01_what_is_kilt.md diff --git a/docs/concepts/02_did.md b/concepts/02_did.md similarity index 98% rename from docs/concepts/02_did.md rename to concepts/02_did.md index 7c1164c6c..b132ef34c 100644 --- a/docs/concepts/02_did.md +++ b/concepts/02_did.md @@ -69,7 +69,7 @@ KILT thus rejects light DID signatures even if the original claim in the credent :::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). +For a detailed developer-oriented guide to KILT DIDs, read the [DID Cookbook section](/develop/sdk/cookbook/dids/light-did-creation). ::: diff --git a/docs/concepts/03_web3names.md b/concepts/03_web3names.md similarity index 94% rename from docs/concepts/03_web3names.md rename to concepts/03_web3names.md index b2f54a1cc..b4230b511 100644 --- a/docs/concepts/03_web3names.md +++ b/concepts/03_web3names.md @@ -46,7 +46,7 @@ For example, showing the web3name of a collator's account on the [KILT Stakeboar }} /> -For a detailed developer-oriented guide to web3names and account linking, read the [web3name Cookbook section](../develop/01_sdk/02_cookbook/02_web3names/01_claim.md) and the [account linking Cookbook section](../develop/01_sdk/02_cookbook/03_account_linking/01_link.md). +For a detailed developer-oriented guide to web3names and account linking, read the [web3name Cookbook section](/develop/sdk/cookbook/web3names/claim) and the [account linking Cookbook section](/develop/sdk/cookbook/account_linking/link). ## KILT DIDs vs. KILT accounts diff --git a/docs/concepts/04_asset_dids.md b/concepts/04_asset_dids.md similarity index 100% rename from docs/concepts/04_asset_dids.md rename to concepts/04_asset_dids.md diff --git a/docs/concepts/05_credentials/01_overview.md b/concepts/05_credentials/01_overview.md similarity index 100% rename from docs/concepts/05_credentials/01_overview.md rename to concepts/05_credentials/01_overview.md diff --git a/docs/concepts/05_credentials/02_ctypes.md b/concepts/05_credentials/02_ctypes.md similarity index 95% rename from docs/concepts/05_credentials/02_ctypes.md rename to concepts/05_credentials/02_ctypes.md index f902ba161..cde2c79d0 100644 --- a/docs/concepts/05_credentials/02_ctypes.md +++ b/concepts/05_credentials/02_ctypes.md @@ -93,7 +93,7 @@ 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). +For a detailed developer-oriented guide to KILT CTypes, read the [CType Cookbook section](/develop/sdk/cookbook/claiming/ctype-creation). [kilt-runtime-1.9.0]: https://github.com/KILTprotocol/kilt-node/releases/tag/1.9.0 @@ -124,7 +124,7 @@ 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. +After [registering the new CType on the KILT blockchain](/develop/sdk/claiming/ctype-creation), 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/concepts/05_credentials/03_claiming.md similarity index 95% rename from docs/concepts/05_credentials/03_claiming.md rename to concepts/05_credentials/03_claiming.md index 1779099f6..6c7ac7899 100644 --- a/docs/concepts/05_credentials/03_claiming.md +++ b/concepts/05_credentials/03_claiming.md @@ -35,6 +35,6 @@ The to-be-attested `Credential` contains the original claim, data needed for fut :::info -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, read the [Claim Cookbook section](/develop/sdk/cookbook/claiming/attestation-request). ::: diff --git a/docs/concepts/05_credentials/04_attestation.md b/concepts/05_credentials/04_attestation.md similarity index 94% rename from docs/concepts/05_credentials/04_attestation.md rename to concepts/05_credentials/04_attestation.md index 33c9c2aae..4c3d1a452 100644 --- a/docs/concepts/05_credentials/04_attestation.md +++ b/concepts/05_credentials/04_attestation.md @@ -15,7 +15,7 @@ After the credential has been attested, the Claimer can store it in their wallet :::info -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). +For a detailed developer-oriented guide to KILT attestations, read the [Attestation cookbook section](/develop/sdk/cookbook/claiming/attestation-creation). ::: diff --git a/docs/concepts/05_credentials/05_verification.md b/concepts/05_credentials/05_verification.md similarity index 95% rename from docs/concepts/05_credentials/05_verification.md rename to concepts/05_credentials/05_verification.md index 0c50f9dcb..7f5cee881 100644 --- a/docs/concepts/05_credentials/05_verification.md +++ b/concepts/05_credentials/05_verification.md @@ -74,7 +74,7 @@ This increases the privacy of the Claimer since they only need to show attribute :::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). +For a detailed developer-oriented guide to KILT presentation creation, read the [presentation creation cookbook section](/develop/sdk/cookbook/claiming/presentation-creation). ::: @@ -107,7 +107,7 @@ Therefore, the Verifier has to check if the CType matches one of the requested C :::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/sdk/cookbook/claiming/presentation-verification). ::: diff --git a/docs/concepts/05_credentials/06_public_credentials.md b/concepts/05_credentials/06_public_credentials.md similarity index 100% rename from docs/concepts/05_credentials/06_public_credentials.md rename to concepts/05_credentials/06_public_credentials.md diff --git a/docs/concepts/05_credentials/_category_.json b/concepts/05_credentials/_category_.json similarity index 100% rename from docs/concepts/05_credentials/_category_.json rename to concepts/05_credentials/_category_.json diff --git a/docs/concepts/06_distributed_trust.md b/concepts/06_distributed_trust.md similarity index 100% rename from docs/concepts/06_distributed_trust.md rename to concepts/06_distributed_trust.md diff --git a/docs/concepts/07_dip/01_overview.md b/concepts/07_dip/01_overview.md similarity index 100% rename from docs/concepts/07_dip/01_overview.md rename to concepts/07_dip/01_overview.md diff --git a/docs/concepts/07_dip/02_provider.md b/concepts/07_dip/02_provider.md similarity index 100% rename from docs/concepts/07_dip/02_provider.md rename to concepts/07_dip/02_provider.md diff --git a/docs/concepts/07_dip/03_consumer.md b/concepts/07_dip/03_consumer.md similarity index 100% rename from docs/concepts/07_dip/03_consumer.md rename to concepts/07_dip/03_consumer.md diff --git a/docs/concepts/07_dip/04_user_account_kilt.md b/concepts/07_dip/04_user_account_kilt.md similarity index 100% rename from docs/concepts/07_dip/04_user_account_kilt.md rename to concepts/07_dip/04_user_account_kilt.md diff --git a/docs/concepts/07_dip/05_dapp_developer.md b/concepts/07_dip/05_dapp_developer.md similarity index 94% rename from docs/concepts/07_dip/05_dapp_developer.md rename to concepts/07_dip/05_dapp_developer.md index 7409dc288..09857fb2f 100644 --- a/docs/concepts/07_dip/05_dapp_developer.md +++ b/concepts/07_dip/05_dapp_developer.md @@ -51,8 +51,8 @@ For example, `did:kilt:4q4QzFTs9hKh4QizLB3B7zuGYCG3QPamiBFEgwM6gTM7gK3g` Currently only supports version 1. - `blockNumber`: The block number of the relay chain to use for the generation of the DIP proof. If not provided, uses the last finalized block. -- `linkedAccounts`: An array of [account addresses linked to the DID](../../develop/01_sdk/02_cookbook/03_account_linking/01_link.md##linking-an-account-to-a-did) to reveal in the generated proof. -- `web3Name`: Whether to reveal [the web3name of the DID subject](../../develop/01_sdk/02_cookbook/02_web3names/01_claim.md) in the generated proof. +- `linkedAccounts`: An array of [account addresses linked to the DID](/develop/sdk/cookbook/account_linking/account-link#linking-an-account-to-a-did) to reveal in the generated proof. +- `web3Name`: Whether to reveal [the web3name of the DID subject](/develop/sdk/cookbook/web3names/claim) in the generated proof. In the example code, the configuration also has extra parameters for the time-bound DID signature extension [mentioned below](#creating-extensions-for-specific-proofs). @@ -108,7 +108,7 @@ await signAndSubmitTx(consumerApi, dipSubmittable, submitterKeypair) Linked accounts let you specify which accounts you want to prove that you control when you make the cross-chain proof. As part of the proof provided, you can also include other values, such as the web3name. -For all the accounts you want to link, use the `associateAccountToChainArgs` method, [as detailed in this guide](../../develop/01_sdk/02_cookbook/03_account_linking/01_link.md##linking-an-account-to-a-did). +For all the accounts you want to link, use the `associateAccountToChainArgs` method, [as detailed in this guide](/develop/sdk/cookbook/account_linking/account-link#linking-an-account-to-a-did). You can then batch all the linked account transactions and authorize them using the `authorizeTx` method. diff --git a/docs/concepts/07_dip/_category_.json b/concepts/07_dip/_category_.json similarity index 100% rename from docs/concepts/07_dip/_category_.json rename to concepts/07_dip/_category_.json diff --git a/docs/concepts/08_messaging.md b/concepts/08_messaging.md similarity index 98% rename from docs/concepts/08_messaging.md rename to concepts/08_messaging.md index 1070ed633..7d4597544 100644 --- a/docs/concepts/08_messaging.md +++ b/concepts/08_messaging.md @@ -40,5 +40,5 @@ Therefore, this scheme still works if a DID should expose multiple encryption ke :::caution While no one can read or change what's inside an encrypted message even if they intercept it while traveling on the network, a sophisticated attacker may try to guess what's inside and trick either side of the channel by resubmitting a copy of that message later. -For a detailed developer-oriented guide about how to protect against *replay attacks*, read the [Replay Protection Cookbook section](../develop/01_sdk/02_cookbook/06_messaging/02_replay_protection.md). +For a detailed developer-oriented guide about how to protect against *replay attacks*, read the [Replay Protection Cookbook section](/develop/sdk/cookbook/messaging/replay-protection). ::: diff --git a/docs/concepts/09_advanced_concepts/01_terms_and_quote.md b/concepts/09_advanced_concepts/01_terms_and_quote.md similarity index 100% rename from docs/concepts/09_advanced_concepts/01_terms_and_quote.md rename to concepts/09_advanced_concepts/01_terms_and_quote.md diff --git a/docs/concepts/09_advanced_concepts/02_nested_ctypes.md b/concepts/09_advanced_concepts/02_nested_ctypes.md similarity index 100% rename from docs/concepts/09_advanced_concepts/02_nested_ctypes.md rename to concepts/09_advanced_concepts/02_nested_ctypes.md diff --git a/docs/concepts/09_advanced_concepts/_category_.json b/concepts/09_advanced_concepts/_category_.json similarity index 100% rename from docs/concepts/09_advanced_concepts/_category_.json rename to concepts/09_advanced_concepts/_category_.json diff --git a/docs/concepts/10_glossary.md b/concepts/10_glossary.md similarity index 100% rename from docs/concepts/10_glossary.md rename to concepts/10_glossary.md diff --git a/develop/01_sdk/01_quickstart.md b/develop/01_sdk/01_quickstart.md new file mode 100644 index 000000000..cd4fb924f --- /dev/null +++ b/develop/01_sdk/01_quickstart.md @@ -0,0 +1,227 @@ +--- +id: quickstart +title: Quickstart +--- + +import CodeBlock from '@theme/CodeBlock'; +import SnippetBlock from '@site/src/components/SnippetBlock'; +import TsJsSnippet from '@site/src/components/TsJsSnippet'; +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import PrintHelloWorld from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/01_print_hello_world.ts'; +import ConnectSpirit from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/02_connect_spirit.ts'; +import ConnectPere from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/02_connect_pere.ts'; +import FetchDid from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/03_fetch_did.ts'; +import FetchEndpoints from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/04_fetch_endpoints.ts'; +import FetchEndpointData from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/05_fetch_endpoint_data.ts'; +import VerifyCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/06_verify_credential.ts'; +import Disconnect from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/07_disconnect.ts'; + +Get started with KILT by following this guide, which teaches you to: + +1. Import the **KILT SDK** into your project +2. Connect to the **KILT blockchain** +3. Query a **web3name** to retrieve its **DID** +4. Verify a **credential** using a **DID service** + +:::info Prerequisites + +This quickstart guide provides hands-on experience to enhance your understanding of KILT. +Basic knowledge of JavaScript and command-line tools is recommended. + +::: + +## Setup + +Create a new project and directory and move into the directory by running `mkdir kilt-rocks && cd kilt-rocks`. + + + + +Inside the `kilt-rocks` project directory, install the **KILT SDK**, **Typescript**, **ts-node**, and **Axios** dependencies: + +```bash npm2yarn +npm init -y +npm install @kiltprotocol/sdk-js ts-node typescript axios +``` + +With the required dependencies installed, create a TypeScript file with `touch quickstart.ts`. + + + + +From inside the `kilt-rocks` project directory, install the **KILT SDK**, **Node**, and **Axios** dependencies: + +```bash npm2yarn +npm init -y +npm install @kiltprotocol/sdk-js node axios +``` + +With the required dependencies installed, create a JavaScript file with `touch quickstart.js`. + +To enable ES modules in your project, add `"type": "module"` to the `package.json` file. + + + + +Declare an `async main` function in the `quickstart.ts` file that executes the rest of the code in this quickstart and call the `main()` function by default: + +{/* TODO: Do we need to test this or provide JS/TS equivalent? */} + +```js +async function main() { +} + +main() +``` + +**With the setup completed, let's get started! 🔥** + +### Import the KILT SDK + +Begin by importing the **KILT SDK** and **Axios** at the top of the file: + +```js +import * as Kilt from '@kiltprotocol/sdk-js' +import axios from 'axios' +``` + +Now, you can access the SDK and all its functionality. +The next step is connecting to the **KILT blockchain**. + +### Connect to the KILT Blockchain + +To perform operations that rely on the **KILT blockchain**, such as querying and verifying a credential, you must first connect to the **KILT blockchain**. + +Within the `main` function, configure the SDK to connect to a KILT node using the `Kilt.connect()` method: + + + +

Peregrine is the development blockchain. + Connect to this network for testing and development purposes.

+ + {ConnectPere} + + + +

Spiritnet is the production blockchain. + When you are ready to publish your DApp, connect to the Spiritnet network for production purposes.

+ + {ConnectSpirit} + + + + +To ensure proper cleanup, call the `Kilt.disconnect()` function at the bottom of the `main()` function. +You should add all other code before this function call: + + +{Disconnect} + + +By adding `await Kilt.disconnect()`, you ensure that the connection to the blockchain node is properly closed when the script finishes executing, which helps maintain the integrity of your application and is a good practice to follow. + +Run the code by calling the name of the file. +If you set up everything correctly, you should see no output showing that your code connected to the **KILT blockchain**. + + + + +```bash +yarn ts-node quickstart.ts +``` + + + + +```bash +node quickstart.js +``` + + + + +As you add to the code in this file, you can always run it with the same command. + +**Congratulations! 🔥** + +You have connected to a KILT blockchain node. +The next step is to start querying data from the blockchain. + +## Query a KILT Identity + +The following code queries information related to a **web3name** (`kiltnerd123`) and uses it to retrieve the **KILT DID** linked to it. + +Between the `Kilt.connect()` and `Kilt.disconnect()` lines, add the following code: + + +{FetchDid} + + +Try running the code and check the result. + +Did you get the DID? You now have `kiltnerd123`'s DID. +The next step is to see if `kiltnerd123` has any publicly linked KILT credentials to retrieve and verify. + +## Retrieve and Verify a Credential + +A **KILT DID** can expose services that allow external resources to be linked to the DID. +**KILT credentials** represent one type of external resource. + +You can retrieve the **services** attached to kiltnerd123's DID and see if they link to any public credentials to **query** and **verify**. + +Add the following code after the code you added in the previous step but before the `await Kilt.disconnect()`. +It retrieves the services exposed by the DID found for `kiltnerd123`: + + +{FetchEndpoints} + + +The code should print endpoints as JSON. + +The next step is to see if you can find a credential among them. +You do this by selecting one of the endpoints and querying the URL to see if it returns a KILT credential collection as described in the [KiltPublishedCredentialCollectionV1 specification](https://github.com/KILTprotocol/spec-KiltPublishedCredentialCollectionV1). + +Add the following code after the code you added in the previous step but before `await Kilt.disconnect()`: + + + {FetchEndpointData} + + +If the script completes without errors, you retrieved the published credential using the URL specified in the service. + +The next step is to make sure the credential is **valid** and has a valid **structure**. + +The following code outputs a string depending on whether the credential is valid, revoked, or not valid. +Add it before `await Kilt.disconnect()`: + + +{VerifyCredential} + + +Run the code and wait to see if you can retrieve **and** verify one of kiltnerd123's credentials! + +:::info Next steps + +- If you want to explore more of KILT's features, read our [Concepts section](/concepts/what-is-kilt). +- If you want to dive deeper into the SDK, read the next section, [the KILT Cookbook](./02_dids/01_light_did_creation.md). + +::: diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/00_generate_keys.md b/develop/01_sdk/02_dids/00_generate_keys.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/00_generate_keys.md rename to develop/01_sdk/02_dids/00_generate_keys.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md b/develop/01_sdk/02_dids/01_light_did_creation.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md rename to develop/01_sdk/02_dids/01_light_did_creation.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/02_full_did_creation.md b/develop/01_sdk/02_dids/02_full_did_creation.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/02_full_did_creation.md rename to develop/01_sdk/02_dids/02_full_did_creation.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/03_full_did_update.md b/develop/01_sdk/02_dids/03_full_did_update.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/03_full_did_update.md rename to develop/01_sdk/02_dids/03_full_did_update.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/04_did_query.md b/develop/01_sdk/02_dids/04_did_query.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/04_did_query.md rename to develop/01_sdk/02_dids/04_did_query.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/05_full_did_delete.md b/develop/01_sdk/02_dids/05_full_did_delete.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/05_full_did_delete.md rename to develop/01_sdk/02_dids/05_full_did_delete.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/06_full_did_tx.md b/develop/01_sdk/02_dids/06_full_did_tx.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/06_full_did_tx.md rename to develop/01_sdk/02_dids/06_full_did_tx.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/07_did_signature.md b/develop/01_sdk/02_dids/07_did_signature.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/07_did_signature.md rename to develop/01_sdk/02_dids/07_did_signature.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/08_did_export.md b/develop/01_sdk/02_dids/08_did_export.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/08_did_export.md rename to develop/01_sdk/02_dids/08_did_export.md diff --git a/docs/develop/01_sdk/02_cookbook/01_dids/_category_.json b/develop/01_sdk/02_dids/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/01_dids/_category_.json rename to develop/01_sdk/02_dids/_category_.json diff --git a/docs/develop/01_sdk/02_cookbook/03_account_linking/01_link.md b/develop/01_sdk/03_account_linking/01_link.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/03_account_linking/01_link.md rename to develop/01_sdk/03_account_linking/01_link.md diff --git a/docs/develop/01_sdk/02_cookbook/03_account_linking/02_account_name.md b/develop/01_sdk/03_account_linking/02_account_name.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/03_account_linking/02_account_name.md rename to develop/01_sdk/03_account_linking/02_account_name.md diff --git a/docs/develop/01_sdk/02_cookbook/03_account_linking/03_unlink.md b/develop/01_sdk/03_account_linking/03_unlink.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/03_account_linking/03_unlink.md rename to develop/01_sdk/03_account_linking/03_unlink.md diff --git a/docs/develop/01_sdk/02_cookbook/03_account_linking/_category_.json b/develop/01_sdk/03_account_linking/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/03_account_linking/_category_.json rename to develop/01_sdk/03_account_linking/_category_.json diff --git a/docs/develop/01_sdk/03_chain_setup/01_standalone_setup.md b/develop/01_sdk/03_chain_setup/01_standalone_setup.md similarity index 100% rename from docs/develop/01_sdk/03_chain_setup/01_standalone_setup.md rename to develop/01_sdk/03_chain_setup/01_standalone_setup.md diff --git a/docs/develop/01_sdk/03_chain_setup/02_peregrine_setup.md b/develop/01_sdk/03_chain_setup/02_peregrine_setup.md similarity index 100% rename from docs/develop/01_sdk/03_chain_setup/02_peregrine_setup.md rename to develop/01_sdk/03_chain_setup/02_peregrine_setup.md diff --git a/docs/develop/01_sdk/03_chain_setup/03_prod_chain_setup.md b/develop/01_sdk/03_chain_setup/03_prod_chain_setup.md similarity index 100% rename from docs/develop/01_sdk/03_chain_setup/03_prod_chain_setup.md rename to develop/01_sdk/03_chain_setup/03_prod_chain_setup.md diff --git a/docs/develop/01_sdk/03_chain_setup/_category_.json b/develop/01_sdk/03_chain_setup/_category_.json similarity index 100% rename from docs/develop/01_sdk/03_chain_setup/_category_.json rename to develop/01_sdk/03_chain_setup/_category_.json diff --git a/docs/develop/01_sdk/03_chain_setup/index.md b/develop/01_sdk/03_chain_setup/index.md similarity index 100% rename from docs/develop/01_sdk/03_chain_setup/index.md rename to develop/01_sdk/03_chain_setup/index.md diff --git a/develop/01_sdk/04_claiming/01_ctype_creation.md b/develop/01_sdk/04_claiming/01_ctype_creation.md new file mode 100644 index 000000000..5fd55c436 --- /dev/null +++ b/develop/01_sdk/04_claiming/01_ctype_creation.md @@ -0,0 +1,44 @@ +--- +id: ctype-creation +title: Create a CType +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import CreateCType from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/01_create_ctype.ts'; +import FetchCType from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/02_fetch_ctype.ts'; + +Every KILT credential has to conform to a CType. +A CType describes which properties a credential has and what type these properties have. +CTypes must be registered on the Spiritnet blockchain. +To learn more about CTypes, see the [CType concept section](/concepts/credentials/ctypes). + +The creation of a CType in KILT involves two steps: the definition of a CType and the anchoring of its hash on the KILT blockchain. + +:::info DID required +The creator of a CType is required to have a full DID with an attestation key. +To see how to manage DIDs, please refer to the [DID section](../02_dids/03_full_did_update.md). +::: + +:::info CTypes are unique +The creation of a new CType requires the CType hash to be unique. +Before writing a new CType, Attesters should check whether there is already an existing CType which matches their requirements. + +Visit our [CType index repository](https://github.com/KILTprotocol/ctype-index) for a non-exhaustive list of existing CTypes. +::: + +The following snippets show how to create a CType: + + + {CreateCType} + + + +## Retrieve a CType from its ID + +CTypes can be queried directly from any KILT archive nodes. +The following example shows how to query a CType using the SDK: + + + {FetchCType} + diff --git a/docs/develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md b/develop/01_sdk/04_claiming/02_attestation_request.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md rename to develop/01_sdk/04_claiming/02_attestation_request.md diff --git a/develop/01_sdk/04_claiming/03_attestation_creation.md b/develop/01_sdk/04_claiming/03_attestation_creation.md new file mode 100644 index 000000000..1546a8681 --- /dev/null +++ b/develop/01_sdk/04_claiming/03_attestation_creation.md @@ -0,0 +1,21 @@ +--- +id: attestation-creation +title: Attest a Claim (Issue a Credential) +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import CreateAttestation from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/04_create_attestation.ts'; + +Once an Attester has received a to-be-attested `Credential` from a Claimer, they will typically verify the information in the claim. +If the claims correspond to truth, the Attester will proceed by attesting the root hash of the credential on the KILT blockchain, timestamping the attestation operation. +A deposit is reserved from the balance of the KILT account submitting the creation transaction, which is returned if and when the attestation is removed from the chain. + +:::info +An Attester is required to have a full DID with an attestation key. +To see how to manage DIDs, please refer to the [DID section](../02_dids/03_full_did_update.md). +::: + + + {CreateAttestation} + \ No newline at end of file diff --git a/docs/develop/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md b/develop/01_sdk/04_claiming/04_presentation_creation.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md rename to develop/01_sdk/04_claiming/04_presentation_creation.md diff --git a/docs/develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md b/develop/01_sdk/04_claiming/05_presentation_verification.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md rename to develop/01_sdk/04_claiming/05_presentation_verification.md diff --git a/docs/develop/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md b/develop/01_sdk/04_claiming/06_credential_revocation.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md rename to develop/01_sdk/04_claiming/06_credential_revocation.md diff --git a/docs/develop/01_sdk/02_cookbook/04_claiming/_category_.json b/develop/01_sdk/04_claiming/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/04_claiming/_category_.json rename to develop/01_sdk/04_claiming/_category_.json diff --git a/docs/develop/01_sdk/04_integrate/01_nodejs.md b/develop/01_sdk/04_integrate/01_nodejs.md similarity index 100% rename from docs/develop/01_sdk/04_integrate/01_nodejs.md rename to develop/01_sdk/04_integrate/01_nodejs.md diff --git a/docs/develop/01_sdk/04_integrate/02_browser.md b/develop/01_sdk/04_integrate/02_browser.md similarity index 100% rename from docs/develop/01_sdk/04_integrate/02_browser.md rename to develop/01_sdk/04_integrate/02_browser.md diff --git a/docs/develop/01_sdk/04_integrate/03_distillery.md b/develop/01_sdk/04_integrate/03_distillery.md similarity index 100% rename from docs/develop/01_sdk/04_integrate/03_distillery.md rename to develop/01_sdk/04_integrate/03_distillery.md diff --git a/docs/develop/01_sdk/04_integrate/_category_.json b/develop/01_sdk/04_integrate/_category_.json similarity index 100% rename from docs/develop/01_sdk/04_integrate/_category_.json rename to develop/01_sdk/04_integrate/_category_.json diff --git a/docs/develop/01_sdk/04_integrate/index.md b/develop/01_sdk/04_integrate/index.md similarity index 100% rename from docs/develop/01_sdk/04_integrate/index.md rename to develop/01_sdk/04_integrate/index.md diff --git a/docs/develop/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md b/develop/01_sdk/05_public_credentials/01_credential_issuance.md similarity index 97% rename from docs/develop/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md rename to develop/01_sdk/05_public_credentials/01_credential_issuance.md index 2bd743f12..651723e4d 100644 --- a/docs/develop/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md +++ b/develop/01_sdk/05_public_credentials/01_credential_issuance.md @@ -41,4 +41,4 @@ This is to save space on credentials that actually benefit from CBOR compression Hence, creating public credentials without the SDK requires the credential to be CBOR-encoded! ::: -[ctypes-link]: ../../../../concepts/05_credentials/02_ctypes.md +[ctypes-link]: /concepts/credentials/ctypes diff --git a/docs/develop/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md b/develop/01_sdk/05_public_credentials/02_credential_retrieval.md similarity index 98% rename from docs/develop/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md rename to develop/01_sdk/05_public_credentials/02_credential_retrieval.md index b2514585a..40a63e6c3 100644 --- a/docs/develop/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md +++ b/develop/01_sdk/05_public_credentials/02_credential_retrieval.md @@ -65,4 +65,4 @@ Rather, the block number in which the extrinsic is submitted is stored inside th This represents a very good tradeoff between **security** - because the blockchain itself dictates what the creation block number is for any given public credential - and **storage efficiency** - since the full credential is stored off-chain, accessible via any KILT archive node or indexing service. ::: -[asset-did-concept]: ../../../../concepts/04_asset_dids.md \ No newline at end of file +[asset-did-concept]: /concepts/asset-dids \ No newline at end of file diff --git a/docs/develop/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md b/develop/01_sdk/05_public_credentials/03_credential_revocation.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md rename to develop/01_sdk/05_public_credentials/03_credential_revocation.md diff --git a/docs/develop/01_sdk/02_cookbook/05_public_credentials/_category_.json b/develop/01_sdk/05_public_credentials/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/05_public_credentials/_category_.json rename to develop/01_sdk/05_public_credentials/_category_.json diff --git a/docs/develop/01_sdk/02_cookbook/06_messaging/01_messaging.md b/develop/01_sdk/06_messaging/01_messaging.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/06_messaging/01_messaging.md rename to develop/01_sdk/06_messaging/01_messaging.md diff --git a/docs/develop/01_sdk/02_cookbook/06_messaging/02_replay_protection.md b/develop/01_sdk/06_messaging/02_replay_protection.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/06_messaging/02_replay_protection.md rename to develop/01_sdk/06_messaging/02_replay_protection.md diff --git a/docs/develop/01_sdk/02_cookbook/06_messaging/_category_.json b/develop/01_sdk/06_messaging/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/06_messaging/_category_.json rename to develop/01_sdk/06_messaging/_category_.json diff --git a/docs/develop/01_sdk/02_cookbook/07_signCallback.md b/develop/01_sdk/07_signCallback.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/07_signCallback.md rename to develop/01_sdk/07_signCallback.md diff --git a/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md b/develop/01_sdk/08_upgrading_to_v0_29/01_backward_compatibility.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md rename to develop/01_sdk/08_upgrading_to_v0_29/01_backward_compatibility.md diff --git a/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json b/develop/01_sdk/08_upgrading_to_v0_29/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json rename to develop/01_sdk/08_upgrading_to_v0_29/_category_.json diff --git a/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md b/develop/01_sdk/08_upgrading_to_v0_29/index.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md rename to develop/01_sdk/08_upgrading_to_v0_29/index.md diff --git a/docs/develop/01_sdk/02_cookbook/02_web3names/01_claim.md b/develop/01_sdk/09_web3names/01_claim.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/02_web3names/01_claim.md rename to develop/01_sdk/09_web3names/01_claim.md diff --git a/docs/develop/01_sdk/02_cookbook/02_web3names/02_credential_query.md b/develop/01_sdk/09_web3names/02_credential_query.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/02_web3names/02_credential_query.md rename to develop/01_sdk/09_web3names/02_credential_query.md diff --git a/docs/develop/01_sdk/02_cookbook/02_web3names/03_release.md b/develop/01_sdk/09_web3names/03_release.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/02_web3names/03_release.md rename to develop/01_sdk/09_web3names/03_release.md diff --git a/develop/01_sdk/09_web3names/04_query.md b/develop/01_sdk/09_web3names/04_query.md new file mode 100644 index 000000000..70c01926b --- /dev/null +++ b/develop/01_sdk/09_web3names/04_query.md @@ -0,0 +1,24 @@ +--- +id: web3name-query +title: Resolve a web3name +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import QueryDid from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/web3names/02_query_did_name.ts'; + + +A web3name can be resolved in a similar manner to [how a DID is resolved](../02_dids/04_did_query.md). +Resolving the web3name will provide the same information as resolving a DID does. + +To query and retrieve the DID document associated with a web3name, you can use the following code example: + + + + {QueryDid} + + +In the code example above, the `queryDidDocument` function takes a web3Name parameter, which represents the web3name to be resolved. +It internally uses the `api.call.did.queryByWeb3Name` method to query the information of the provided web3name from the blockchain. + +The function then decodes the result using `Kilt.Did.linkedInfoFromChain` to extract the associated DID document and any other linked blockchain accounts. Finally, it returns the resolved DID document. diff --git a/docs/develop/01_sdk/02_cookbook/02_web3names/_category_.json b/develop/01_sdk/09_web3names/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/02_web3names/_category_.json rename to develop/01_sdk/09_web3names/_category_.json diff --git a/docs/develop/01_sdk/05_troubleshoot.md b/develop/01_sdk/10_troubleshoot.md similarity index 100% rename from docs/develop/01_sdk/05_troubleshoot.md rename to develop/01_sdk/10_troubleshoot.md diff --git a/docs/develop/01_sdk/_category_.json b/develop/01_sdk/_category_.json similarity index 100% rename from docs/develop/01_sdk/_category_.json rename to develop/01_sdk/_category_.json diff --git a/docs/develop/02_chain/01_introduction.md b/develop/02_chain/01_introduction.md similarity index 100% rename from docs/develop/02_chain/01_introduction.md rename to develop/02_chain/01_introduction.md diff --git a/docs/develop/02_chain/02_pallets/01_did.md b/develop/02_chain/02_pallets/01_did.md similarity index 100% rename from docs/develop/02_chain/02_pallets/01_did.md rename to develop/02_chain/02_pallets/01_did.md diff --git a/docs/develop/02_chain/02_pallets/_category_.json b/develop/02_chain/02_pallets/_category_.json similarity index 100% rename from docs/develop/02_chain/02_pallets/_category_.json rename to develop/02_chain/02_pallets/_category_.json diff --git a/docs/develop/02_chain/03_deployments.md b/develop/02_chain/03_deployments.md similarity index 100% rename from docs/develop/02_chain/03_deployments.md rename to develop/02_chain/03_deployments.md diff --git a/docs/develop/02_chain/04_fullnode.md b/develop/02_chain/04_fullnode.md similarity index 98% rename from docs/develop/02_chain/04_fullnode.md rename to develop/02_chain/04_fullnode.md index d056efcc4..10a2237f7 100644 --- a/docs/develop/02_chain/04_fullnode.md +++ b/develop/02_chain/04_fullnode.md @@ -7,7 +7,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; We will guide you through the process of setting up and connecting to a KILT full node. -In contrast [to a collator](../../participate/01_staking/01_become_a_collator/03_setup_node.md), full nodes do not author blocks. +In contrast [to a collator](/participate/staking/become_a_collator/setup-node), full nodes do not author blocks. They act as a backend for websites and help to verify new blocks or validate extrinsics (e.g., coin transfers and other transactions) directly on the network without relying on a centralized infrastructure provider. ## Setup diff --git a/docs/develop/02_chain/_category_.json b/develop/02_chain/_category_.json similarity index 100% rename from docs/develop/02_chain/_category_.json rename to develop/02_chain/_category_.json diff --git a/docs/develop/03_workshop/01_welcome.md b/develop/03_workshop/01_welcome.md similarity index 100% rename from docs/develop/03_workshop/01_welcome.md rename to develop/03_workshop/01_welcome.md diff --git a/docs/develop/03_workshop/02_setup.md b/develop/03_workshop/02_setup.md similarity index 100% rename from docs/develop/03_workshop/02_setup.md rename to develop/03_workshop/02_setup.md diff --git a/develop/03_workshop/03_overview.md b/develop/03_workshop/03_overview.md new file mode 100644 index 000000000..3bfb9ca58 --- /dev/null +++ b/develop/03_workshop/03_overview.md @@ -0,0 +1,96 @@ +--- +id: overview +title: 👓 Overview +--- + +This tutorial runs through the full story of a claim. + +It involves three actors which work together to create **distributed trust**: + +- A Claimer is an actor who claims to possess certain credentials, abilities, or other attributes. +- An Attester is an actor that verifies the claims of a Claimer. +- A Verifier is an actor that asks for proof of a claim. + +For the workshop, you play all three roles. + +In a real-world use case, these actors would be different people and services, which this workshop simulates using different folders for each service. +Each actor typically performs different roles: + +- Both the Verifier and the Attester have to interact with the KILT blockchain. +- But only the Attester is required to own KILTs since they have to pay for storing the attestation on chain. +- The Verifier only needs to query the KILT blockchain to ensure that the attestation is still valid and was not revoked. +- The Claimer is not required to query the blockchain, but they might do so to check whether their credential is still valid or if the Attester has revoked it in the meantime. + +## Request an Attestation + +Before the Claimer can attest a credential, they need to generate a [light DID](../01_sdk//02_dids/01_light_did_creation.md), which can happen off-chain. + +The Attester has to register their DID on chain and needs KILT coins. + +After both the Attester and the Claimer have set up their identities, the Claimer can start the attestation process by requesting an attestation from the Attester. + +```mermaid +sequenceDiagram +actor C as Claimer +actor A as Attester +participant B as KILT Blockchain + C->>+C: Create credential from provided claims + C->>+A: Transmit credential to request attestation + A->>A: Validate received attributes + A->>+B: Store attestation + B-->>-A: Attestation hash + A-->>-C: Attestation Hash +``` + +1. The Claimer prepares the Credential to attest, along with some proof, for example, a bank statement and ID. +2. They send the document to the Attester for attestation. +3. Upon receiving the credential, the Attester decides whether the claim is valid by examining the proofs. If the Attester trusts the claim, they store the attestation document's hash value on the chain, which is a non-functional copy of the document. +4. The Attester sends this hash value to the Claimer, which represents verification of a document. + +## Verify an Attestation + +The Verifier requests a presentation from the Claimer for a specific required CType. Without a specific CType, the presentation is meaningless. + + + +A presentation is derived from a credential and does not need to contain all attributes. + +After the request, the Claimer can choose to hide elements of their credentials that aren't relevant to the claim. +For example, hide their address from their ID if the Verifier is only interested in their age. + +:::info + +A later step in the workshop [explains CTypes in more detail](./04_attester/03_ctype.md). + +::: + +```mermaid +sequenceDiagram +actor C as Claimer +actor V as Verifier +participant B as KILT Blockchain + V->>+C: Request presentation for CType + C->>C: Derive a presentation from a credential + C-->>-V: submit presentation + V->>B: check validity of presentation +``` + +### Example: Requesting a travel visa + +To take an example of applying for a travel visa: + +1. The Embassy (analogous to the Verifier) asks a traveler (analogous to the Claimer) for a specific document or CType. For example, it could be a bank statement. The Embassy asks, "Provide proof of financial stability, and we'll grant you a visa." The traveler gets the bank statement from their bank, gets it attested by the bank (The Attester), and prepares the document. +2. The document is ready, but the Embassy doesn't need all the information in the document. The embassy wants to know if a traveler has sufficient funds, but they don't need to know any transaction details. The traveler redacts or hides these details while presenting. +3. The traveler presents the document to the embassy. +4. The embassy verified the document's authenticity by comparing its hash value with the one on their internal system or a decentralized ledger. +5. Since they trust the Attester (in this case, the bank that attested the bank statement), they approved the visa application. + +:::tip Summary + +As you can see, the Embassy didn't need to trust the Claimer directly in this system. +They trust the Attester, whom they had previously worked with, or respect due to their position. +And with that trust, they grant the visa with no knowledge of what the Claimer has used the credential for. +Even though this process emerged due to the trust in the Attester, the Attester was not involved in the second stage, so they were unaware of it. +Privacy was achieved with distributed trust. + +::: \ No newline at end of file diff --git a/docs/develop/03_workshop/04_attester/01_account.md b/develop/03_workshop/04_attester/01_account.md similarity index 100% rename from docs/develop/03_workshop/04_attester/01_account.md rename to develop/03_workshop/04_attester/01_account.md diff --git a/docs/develop/03_workshop/04_attester/02_did.md b/develop/03_workshop/04_attester/02_did.md similarity index 96% rename from docs/develop/03_workshop/04_attester/02_did.md rename to develop/03_workshop/04_attester/02_did.md index fa4bc03cd..47d0796f1 100644 --- a/docs/develop/03_workshop/04_attester/02_did.md +++ b/develop/03_workshop/04_attester/02_did.md @@ -28,7 +28,7 @@ Other users can now encrypt messages using your public encryption key and send a Kilt supports two DID types: **light** and **full**. There are differences between the two types, but the most crucial is that you can use a light DID offline, but a full DID needs access to the blockchain to work. -Read the [DID documentation](../../../develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md) to learn more about the difference between the light and full types. +Read the [DID documentation](/develop/sdk/cookbook/dids/light-did-creation) to learn more about the difference between the light and full types. :::info KILT DID diff --git a/docs/develop/03_workshop/04_attester/03_ctype.md b/develop/03_workshop/04_attester/03_ctype.md similarity index 99% rename from docs/develop/03_workshop/04_attester/03_ctype.md rename to develop/03_workshop/04_attester/03_ctype.md index 417885275..55eac6f69 100644 --- a/docs/develop/03_workshop/04_attester/03_ctype.md +++ b/develop/03_workshop/04_attester/03_ctype.md @@ -23,7 +23,7 @@ A CType ensures that a credential contains all required attributes, e.g., a driv The CType is important since a Verifier requests credentials for a specific CType. For example, the traffic police want to see your driver's license, not your gym membership. -To learn more about CTypes, read the [in-depth CType documentation](../../../concepts/05_credentials/02_ctypes.md). +To learn more about CTypes, read the [in-depth CType documentation](/concepts/credentials/ctypes). You can also [read through existing CTypes in the CType-index](https://github.com/KILTprotocol/ctype-index). ::: diff --git a/docs/develop/03_workshop/04_attester/_category_.json b/develop/03_workshop/04_attester/_category_.json similarity index 100% rename from docs/develop/03_workshop/04_attester/_category_.json rename to develop/03_workshop/04_attester/_category_.json diff --git a/docs/develop/03_workshop/04_attester/index.md b/develop/03_workshop/04_attester/index.md similarity index 100% rename from docs/develop/03_workshop/04_attester/index.md rename to develop/03_workshop/04_attester/index.md diff --git a/docs/develop/03_workshop/05_claimer/01_did.md b/develop/03_workshop/05_claimer/01_did.md similarity index 92% rename from docs/develop/03_workshop/05_claimer/01_did.md rename to develop/03_workshop/05_claimer/01_did.md index e6abbde43..b434df3f9 100644 --- a/docs/develop/03_workshop/05_claimer/01_did.md +++ b/develop/03_workshop/05_claimer/01_did.md @@ -22,7 +22,7 @@ Remember, light DIDs can do the following: - Sign attestation requests and presentation with the authentication keys - Encrypt messages with the encryption keys -Read the [DID documentation](../../../develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md) to learn more about DIDs and the difference between their light and full versions. +Read the [DID documentation](/develop/sdk/cookbook/dids/light-did-creation) to learn more about DIDs and the difference between their light and full versions. ::: diff --git a/docs/develop/03_workshop/05_claimer/02_request.md b/develop/03_workshop/05_claimer/02_request.md similarity index 100% rename from docs/develop/03_workshop/05_claimer/02_request.md rename to develop/03_workshop/05_claimer/02_request.md diff --git a/docs/develop/03_workshop/05_claimer/_category_.json b/develop/03_workshop/05_claimer/_category_.json similarity index 100% rename from docs/develop/03_workshop/05_claimer/_category_.json rename to develop/03_workshop/05_claimer/_category_.json diff --git a/docs/develop/03_workshop/05_claimer/index.md b/develop/03_workshop/05_claimer/index.md similarity index 100% rename from docs/develop/03_workshop/05_claimer/index.md rename to develop/03_workshop/05_claimer/index.md diff --git a/docs/develop/03_workshop/06_attestation.md b/develop/03_workshop/06_attestation.md similarity index 100% rename from docs/develop/03_workshop/06_attestation.md rename to develop/03_workshop/06_attestation.md diff --git a/docs/develop/03_workshop/07_verification.md b/develop/03_workshop/07_verification.md similarity index 100% rename from docs/develop/03_workshop/07_verification.md rename to develop/03_workshop/07_verification.md diff --git a/docs/develop/03_workshop/08_done.md b/develop/03_workshop/08_done.md similarity index 100% rename from docs/develop/03_workshop/08_done.md rename to develop/03_workshop/08_done.md diff --git a/docs/develop/03_workshop/_category_.json b/develop/03_workshop/_category_.json similarity index 100% rename from docs/develop/03_workshop/_category_.json rename to develop/03_workshop/_category_.json diff --git a/docs/develop/04_specifications.md b/develop/04_specifications.md similarity index 100% rename from docs/develop/04_specifications.md rename to develop/04_specifications.md diff --git a/develop/05_builtonkilt.md b/develop/05_builtonkilt.md new file mode 100644 index 000000000..278dda115 --- /dev/null +++ b/develop/05_builtonkilt.md @@ -0,0 +1,78 @@ +--- +id: builtonkilt +title: Built on KILT +--- + +import ThemedImage from '@theme/ThemedImage'; +import LogoText from '@site/src/components/LogoText'; + +This section contains a non-exhaustive list of apps, wallets and websites that are built on KILT. +If you are not on the list and want to be added, you are welcome to [open a PR](https://github.com/KILTprotocol/docs/edit/master/docs/develop/05_builtonkilt.md). + +## Wallets + +Wallets are the gateway to Web3. +They store private information like secret keys for KILT DIDs and credentials. +Each time a website needs to access some information about the visitor, the wallet first asks its owner’s permission to share the requested information. + + + + Sporran is the first wallet to support the KILT protocol. + It is maintained by _BOTLabs Trusted Entity B.T.E GmbH_ and it is [open source](https://github.com/BTE-Trusted-Entity/sporran-extension). + + +## Web Apps + +Decentralized applications have already been built that use the functions of the wallet. + + + Help secure the KILT Spiritnet! + On Stakeboard you can influence who is allowed to build blocks on Spiritnet by delegating KILT tokens to a collator you trust. + + +--- + + + w3n.id is a website that helps you claim and search web3names. + Learn more about KILT web3names in our [concepts section](/concepts/web3names). + + +--- + + + DIDsign provides a decentralized way to sign any file directly in your browser using your KILT DID. + Your data stays locally on your device and is never transferred or held in a centralized place. + + +--- + + + Get your first KILT credential today! + SocialKYC issues credentials that prove ownership of several social profiles, including email addresses, and Telegram, Twitter and GitHub accounts, with more being continuously added. + It's free to use, and credentials expire after one year. + diff --git a/docs/develop/06_contribute.md b/develop/06_contribute.md similarity index 98% rename from docs/develop/06_contribute.md rename to develop/06_contribute.md index 63430b580..e5f45a340 100644 --- a/docs/develop/06_contribute.md +++ b/develop/06_contribute.md @@ -49,7 +49,7 @@ In addition you should: The proposal should then be discussed with the community (including, for example, the KILT Technical Committee, governance, or relevant project team) using community channels such as [Discord](https://discord.gg/7uyfMXh6AT) or [Polkassembly](https://kilt.polkassembly.network/discussions). If the community is not in agreement with the proposal, it is unlikely that it would be approved by governance. -See the [guide to creating a proposal](../participate/03_treasury_proposal.md) for additional details. +See the [guide to creating a proposal](/participate/treasury-proposal) for additional details. ## Tips diff --git a/docs/develop/07_dApp/01_welcome.md b/develop/07_dApp/01_welcome.md similarity index 100% rename from docs/develop/07_dApp/01_welcome.md rename to develop/07_dApp/01_welcome.md diff --git a/develop/07_dApp/02_well-known-did-config.md b/develop/07_dApp/02_well-known-did-config.md new file mode 100644 index 000000000..71c8edf3e --- /dev/null +++ b/develop/07_dApp/02_well-known-did-config.md @@ -0,0 +1,110 @@ +--- +id: well-known-did-config +title: Well-Known DID Configuration +--- + + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import DomainLinkageCtype from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/dapp/01_domain_linkage_ctype.ts'; +import DomainLinkageClaim from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/dapp/02_domain_linkage_claim.ts'; +import SignPresentation from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/dapp/03_sign_presentation.ts'; +import AttestCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/dapp/04_attest_credential.ts'; +import FormatCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/dapp/05_format_credential.ts'; + +:::danger This is a working draft + +The KILT support of the *Well-Known DID Configuration* uses unpublished specifications and will change in the future. + +::: + +The *Well-Known DID Configuration* is implemented as a security measure when setting up the communication session between the dapp and extension. +It ensures that the DID the browser extension is communicating to is linked to the domain that is visited by the browser. +This rule is currently enforced by the KILT Wallet reference implementation (Sporran Extension), but might be relaxed in the future. +The implementation is based on the [*Well-Known DID Configuration*][well-known-spec] specified by the Decentralized Identity Foundation. + +Once a communication session between a dapp and an extension is opened, the extension will query `/.well-known/did-configuration.json`. +This JSON-file must contain a credential presentation that conforms to the [Domain Linkage CType][CType-Domain-Linkage]. + +## Set up the Well-Known DID Configuration + +For the *Well-Known DID Configuration* you need to go through the following steps: + +0. Create a full DID + * You will need the `assertionMethodKey` a.k.a. `attestationKey` for signing the credential + * The `authenticationKey` is required for signing the transaction +1. Create a claim +2. Attest the claim +3. Create a presentation +4. Host the presentation on your website at `https:///.well-known/did-configuration.json` + +### Create a DID + +Your dapp needs a DID to identify itself to the extension. +If your dapp does not have a DID yet, follow the [*create a full DID* guide][create-full-did]. +Make sure to create the DID with an `assertionMethodKey` so that you are able to issue attestations. + +### Making the claim + +After you get a DID, you can make a claim about that DID. +The claim has to be based on the [Domain Linkage CType][CType-Domain-Linkage], whose definition you can get from the linked GitHub repository, or fetch from the blockchain using the CType's id: + + + {DomainLinkageCtype} + + +The credential is built from the CType, claim contents, and your dapp's unique DID: + + + {DomainLinkageClaim} + + +The credential isn't attested yet and is therefore not valid yet. + +### Self-attesting the credential + +A valid credential requires an attestation. +Since the website wants to link itself to the DID just created, it has to self-attest the domain linkage credential, i.e., write the credential attestation on chain using the same DID it is trying to link to. + +In order to attest the credential we go through the following steps: + +1. calculating the claim hash +2. creating the attest transaction +3. authorizing the transaction with your DID +4. paying for the transaction with a KILT account and submitting it to the chain + + + {AttestCredential} + + +If you want to learn more about attestations you can refer to our [concept guide][concept-attestations] or the [cookbook][cookbook-attestations]. + +### Presenting the credential + +To use the newly attested credential, we need to derive a presentation from it to host on the dapp website. + + + {SignPresentation} + + +The Well-Known DID Configuration specification requires a verifiable credential. +For now we have to manually convert our KILT credential into the required format. + + + {FormatCredential} + + +### Host the Presentation + +Now that you generated a presentation, you need to host it in your web app, so that the extension can query the presentation. +The extension will make an HTTP GET request to the following URI, and your dapp must respond with the presentation. + +`/.well-known/did-configuration.json` + +How the file is hosted depends on your project setup and is out of scope for this guide. + +[concept-attestations]: /concepts/credentials/attestation +[cookbook-attestations]: ../01_sdk//04_claiming/03_attestation_creation.md +[create-full-did]: ../01_sdk//02_dids/02_full_did_creation.md +[well-known-spec]: https://identity.foundation/specs/did-configuration/ +[CType-Domain-Linkage]: https://github.com/KILTprotocol/ctype-index/tree/main/ctypes/0x9d271c790775ee831352291f01c5d04c7979713a5896dcf5e81708184cc5c643 diff --git a/docs/develop/07_dApp/03_session.md b/develop/07_dApp/03_session.md similarity index 100% rename from docs/develop/07_dApp/03_session.md rename to develop/07_dApp/03_session.md diff --git a/docs/develop/07_dApp/04_verifier.md b/develop/07_dApp/04_verifier.md similarity index 98% rename from docs/develop/07_dApp/04_verifier.md rename to develop/07_dApp/04_verifier.md index 1f44af1c6..fe362f81a 100644 --- a/docs/develop/07_dApp/04_verifier.md +++ b/develop/07_dApp/04_verifier.md @@ -20,7 +20,7 @@ After the browser extension verified the Well-Known DID Configuration and the en This is a two step process. First the server sends a message to the extension that request the presentation of a credential. -Since we don't want to see just any credential, but expect specific content, we also require that the credential conforms to a specific [CType](../../concepts/05_credentials/02_ctypes.md). +Since we don't want to see just any credential, but expect specific content, we also require that the credential conforms to a specific [CType](/concepts/credentials/ctypes). When the extension receives the request, it will prompt the user to select a credential that should be presented to the server. The user can also choose to reject this request and not to show any presentation. diff --git a/docs/develop/07_dApp/_category_.json b/develop/07_dApp/_category_.json similarity index 100% rename from docs/develop/07_dApp/_category_.json rename to develop/07_dApp/_category_.json diff --git a/docs/develop/08_opendid/01_overview.md b/develop/08_opendid/01_overview.md similarity index 95% rename from docs/develop/08_opendid/01_overview.md rename to develop/08_opendid/01_overview.md index 235e4223d..e42a82d1b 100644 --- a/docs/develop/08_opendid/01_overview.md +++ b/develop/08_opendid/01_overview.md @@ -3,7 +3,7 @@ id: what-is-opendid title: Overview --- -[OpenDID](https://github.com/KILTprotocol/opendid) is an OpenID Provider implementation capable of authenticating users through their [Decentralized Identifier (DID)](../../concepts/02_did.md) and Verifiable Credentials. +[OpenDID](https://github.com/KILTprotocol/opendid) is an OpenID Provider implementation capable of authenticating users through their [Decentralized Identifier (DID)](/concepts/did) and Verifiable Credentials. It follows the [OpenID Connect 1.0 Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and acts as a bridge between the decentralized identity world and the centralized authentication world supporting both the implicit and Authorization Code Flow. diff --git a/docs/develop/08_opendid/02_opendid_flow.md b/develop/08_opendid/02_opendid_flow.md similarity index 100% rename from docs/develop/08_opendid/02_opendid_flow.md rename to develop/08_opendid/02_opendid_flow.md diff --git a/docs/develop/08_opendid/03_opendid_service.md b/develop/08_opendid/03_opendid_service.md similarity index 100% rename from docs/develop/08_opendid/03_opendid_service.md rename to develop/08_opendid/03_opendid_service.md diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/develop/08_opendid/04_integrate_opendid.md similarity index 100% rename from docs/develop/08_opendid/04_integrate_opendid.md rename to develop/08_opendid/04_integrate_opendid.md diff --git a/docs/develop/08_opendid/05_demo_project.md b/develop/08_opendid/05_demo_project.md similarity index 100% rename from docs/develop/08_opendid/05_demo_project.md rename to develop/08_opendid/05_demo_project.md diff --git a/docs/develop/08_opendid/06_advanced.md b/develop/08_opendid/06_advanced.md similarity index 100% rename from docs/develop/08_opendid/06_advanced.md rename to develop/08_opendid/06_advanced.md diff --git a/docs/develop/08_opendid/_category_.json b/develop/08_opendid/_category_.json similarity index 100% rename from docs/develop/08_opendid/_category_.json rename to develop/08_opendid/_category_.json diff --git a/docs/develop/_category_.json b/develop/_category_.json similarity index 100% rename from docs/develop/_category_.json rename to develop/_category_.json diff --git a/docusaurus.config.js b/docusaurus.config.js index 26bab7d0b..567873b5a 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -40,9 +40,8 @@ module.exports = { image: 'img/expert_dark_preview.png', announcementBar: { id: 'dip-announcement', - // Use absolute links proceeded by '/docs' content: - 'DIP enables OpenID inspired cross-chain identity, help us test this new feature!', + 'DIP enables OpenID inspired cross-chain identity, help us test this new feature!', backgroundColor: '#2db528', textColor: '#fff', isCloseable: true, @@ -56,8 +55,12 @@ module.exports = { }, items: [ { - type: 'doc', - docId: 'concepts/what-is-kilt', + type: 'docsVersionDropdown', + position: 'right', + dropdownActiveClassDisabled: true, + }, + { + to: '/concepts/what-is-kilt', label: 'What is KILT?', }, { @@ -66,42 +69,42 @@ module.exports = { items: [ { type: 'doc', - docId: 'develop/sdk/quickstart', + docId: 'sdk/quickstart', label: 'SDK Documentation', }, { type: 'doc', - docId: 'develop/chain/introduction', + docId: 'chain/introduction', label: 'Blockchain Documentation', }, { type: 'doc', - docId: 'develop/workshop/welcome', + docId: 'workshop/welcome', label: 'Workshop', }, { type: 'doc', - docId: 'develop/contribute', + docId: 'contribute', label: 'Contribute', }, { type: 'doc', - docId: 'develop/specifications', + docId: 'specifications', label: 'Technical Specifications', }, { type: 'doc', - docId: 'develop/builtonkilt', + docId: 'builtonkilt', label: 'Built on KILT', }, { type: 'doc', - docId: 'develop/dApp/welcome', + docId: 'dApp/welcome', label: 'DApp Documentation', }, { type: 'doc', - docId: 'develop/opendid/what-is-opendid', + docId: 'opendid/what-is-opendid', label: 'OpenDID Documentation', }, ], @@ -111,28 +114,23 @@ module.exports = { label: 'Participate', items: [ { - type: 'doc', - docId: 'participate/staking/become_a_collator/overview', + to: 'participate/staking/become_a_collator/overview', label: 'Staking', }, { - type: 'doc', - docId: 'participate/governance/vote', + to: 'participate/governance/vote', label: 'Voting', }, { - type: 'doc', - docId: 'participate/treasury-proposal', + to: 'participate/treasury-proposal', label: 'Treasury Proposals', }, { - type: 'doc', - docId: 'participate/content-creation-guidelines', + to: 'participate/content-creation-guidelines', label: 'Content Creation Guidelines', }, { - type: 'doc', - docId: 'participate/treasury-tip', + to: 'participate/treasury-tip', label: 'Treasury Tips', }, ], @@ -204,16 +202,24 @@ module.exports = { '@docusaurus/preset-classic', { docs: { + path: 'develop', + lastVersion: 'current', + versions: { + current: { + label: '1.0.x', + }, + 0.3: { + label: '0.3.x', + path: '0.3', + }, + }, + routeBasePath: 'develop', + sidebarPath: './sidebarsDevelop.js', remarkPlugins: [ [require('@docusaurus/remark-plugin-npm2yarn'), { sync: true }], ], - sidebarPath: require.resolve('./sidebars.js'), editUrl: 'https://github.com/KILTprotocol/docs/edit/master/', showLastUpdateTime: true, - admonitions: { - keywords: ['version-label'], - extendDefaults: true, - }, }, theme: { customCss: require.resolve('./src/css/custom.css'), @@ -234,6 +240,40 @@ module.exports = { }, }, plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + id: 'concepts', + path: 'concepts', + routeBasePath: 'concepts', + sidebarPath: './sidebarsConcepts.js', + admonitions: { + keywords: ['version-label'], + extendDefaults: true, + }, + remarkPlugins: [ + [require('@docusaurus/remark-plugin-npm2yarn'), { sync: true }], + ], + editUrl: 'https://github.com/KILTprotocol/docs/edit/master/', + showLastUpdateTime: true, + // ... other options + }, + ], + [ + '@docusaurus/plugin-content-docs', + { + id: 'participate', + path: 'participate', + routeBasePath: 'participate', + sidebarPath: './sidebarsParticipate.js', + remarkPlugins: [ + [require('@docusaurus/remark-plugin-npm2yarn'), { sync: true }], + ], + editUrl: 'https://github.com/KILTprotocol/docs/edit/master/', + showLastUpdateTime: true, + // ... other options + }, + ], // Pulls external files and adds them as files in the Docusaurus folder, rewriting the title and the file name [ 'docusaurus-plugin-remote-content', @@ -241,7 +281,7 @@ module.exports = { name: 'dip-provider-docs', sourceBaseUrl: 'https://raw.githubusercontent.com/KILTprotocol/kilt-node/1.13.0/pallets/pallet-dip-provider/', - outDir: 'docs/concepts/07_dip', + outDir: 'concepts/07_dip', documents: ['README.md'], modifyContent(filename, content) { if (filename.includes('README')) { @@ -265,7 +305,7 @@ module.exports = { name: 'dip-consumer-docs', sourceBaseUrl: 'https://raw.githubusercontent.com/KILTprotocol/kilt-node/1.13.0/pallets/pallet-dip-consumer/', - outDir: 'docs/concepts/07_dip', + outDir: 'concepts/07_dip', documents: ['README.md'], modifyContent(filename, content) { if (filename.includes('README')) { diff --git a/markdown-link-check.config.json b/markdown-link-check.config.json index a00c94747..6480ea436 100644 --- a/markdown-link-check.config.json +++ b/markdown-link-check.config.json @@ -19,6 +19,15 @@ }, { "pattern": "/(localhost)." + }, + { + "pattern": "^/develop/" + }, + { + "pattern": "^/participate/" + }, + { + "pattern": "^/concepts/" } ] } \ No newline at end of file diff --git a/package.json b/package.json index 9a7c5918b..b5b9c524f 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ }, "scripts": { "build": "yarn check-ts && yarn check-links && yarn generate-examples && docusaurus build", - "check-links": "yarn markdown-link-check -c markdown-link-check.config.json -q $(find docs -name '*.md')", + "check-links": "yarn markdown-link-check -c markdown-link-check.config.json -q $(find participate concepts develop -name '*.md')", "check-ts": "concurrently -m 1 yarn:check-ts:*", "check-ts:scripts": "cd scripts && yarn install && yarn check-ts", "check-ts:examples": "cd code_examples/sdk_examples && yarn install && yarn check-ts", @@ -33,22 +33,22 @@ "concurrently": "^8.2.2" }, "dependencies": { - "@babel/parser": "^7.23.6", - "@babel/standalone": "^7.23.8", - "@docusaurus/core": "^3.1.0", - "@docusaurus/preset-classic": "^3.1.0", - "@docusaurus/remark-plugin-npm2yarn": "^3.1.0", - "@docusaurus/theme-mermaid": "^3.1.0", - "@mdx-js/react": "^3.0.0", - "archiver": "^6.0.1", - "clsx": "^2.1.0", + "@babel/parser": "^7.25.3", + "@babel/standalone": "^7.25.3", + "@docusaurus/core": "^3.4.0", + "@docusaurus/preset-classic": "^3.4.0", + "@docusaurus/remark-plugin-npm2yarn": "^3.4.0", + "@docusaurus/theme-mermaid": "^3.4.0", + "@mdx-js/react": "^3.0.1", + "archiver": "^7.0.1", + "clsx": "^2.1.1", "docusaurus-plugin-remote-content": "^4.0.0", - "markdown-link-check": "^3.11.2", + "markdown-link-check": "^3.12.2", "node-args": "^2.1.8", - "prettier": "^3.2.4", + "prettier": "^3.3.3", "raw-loader": "^4.0.2", - "react": "^18.2.0", - "react-dom": "^18.2.0", + "react": "^18.3.1", + "react-dom": "^18.3.1", "react-markdown": "^9.0.1" }, "browserslist": { diff --git a/docs/participate/01_staking/01_become_a_collator/01_overview.md b/participate/01_staking/01_become_a_collator/01_overview.md similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/01_overview.md rename to participate/01_staking/01_become_a_collator/01_overview.md diff --git a/docs/participate/01_staking/01_become_a_collator/02_hardware_requirements.md b/participate/01_staking/01_become_a_collator/02_hardware_requirements.md similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/02_hardware_requirements.md rename to participate/01_staking/01_become_a_collator/02_hardware_requirements.md diff --git a/docs/participate/01_staking/01_become_a_collator/03_setup_node.md b/participate/01_staking/01_become_a_collator/03_setup_node.md similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/03_setup_node.md rename to participate/01_staking/01_become_a_collator/03_setup_node.md diff --git a/docs/participate/01_staking/01_become_a_collator/04_session_keys.md b/participate/01_staking/01_become_a_collator/04_session_keys.md similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/04_session_keys.md rename to participate/01_staking/01_become_a_collator/04_session_keys.md diff --git a/docs/participate/01_staking/01_become_a_collator/05_join_collators.md b/participate/01_staking/01_become_a_collator/05_join_collators.md similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/05_join_collators.md rename to participate/01_staking/01_become_a_collator/05_join_collators.md diff --git a/docs/participate/01_staking/01_become_a_collator/_03_start_node_binary.mdx b/participate/01_staking/01_become_a_collator/_03_start_node_binary.mdx similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/_03_start_node_binary.mdx rename to participate/01_staking/01_become_a_collator/_03_start_node_binary.mdx diff --git a/docs/participate/01_staking/01_become_a_collator/_03_start_node_docker.mdx b/participate/01_staking/01_become_a_collator/_03_start_node_docker.mdx similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/_03_start_node_docker.mdx rename to participate/01_staking/01_become_a_collator/_03_start_node_docker.mdx diff --git a/docs/participate/01_staking/01_become_a_collator/_category_.json b/participate/01_staking/01_become_a_collator/_category_.json similarity index 100% rename from docs/participate/01_staking/01_become_a_collator/_category_.json rename to participate/01_staking/01_become_a_collator/_category_.json diff --git a/docs/participate/01_staking/02_advanced_collator_section/01_adjust_stake.md b/participate/01_staking/02_advanced_collator_section/01_adjust_stake.md similarity index 100% rename from docs/participate/01_staking/02_advanced_collator_section/01_adjust_stake.md rename to participate/01_staking/02_advanced_collator_section/01_adjust_stake.md diff --git a/docs/participate/01_staking/02_advanced_collator_section/02_exit.md b/participate/01_staking/02_advanced_collator_section/02_exit.md similarity index 100% rename from docs/participate/01_staking/02_advanced_collator_section/02_exit.md rename to participate/01_staking/02_advanced_collator_section/02_exit.md diff --git a/docs/participate/01_staking/02_advanced_collator_section/03_collator_lifecycle.md b/participate/01_staking/02_advanced_collator_section/03_collator_lifecycle.md similarity index 100% rename from docs/participate/01_staking/02_advanced_collator_section/03_collator_lifecycle.md rename to participate/01_staking/02_advanced_collator_section/03_collator_lifecycle.md diff --git a/docs/participate/01_staking/02_advanced_collator_section/04_monitoring.md b/participate/01_staking/02_advanced_collator_section/04_monitoring.md similarity index 100% rename from docs/participate/01_staking/02_advanced_collator_section/04_monitoring.md rename to participate/01_staking/02_advanced_collator_section/04_monitoring.md diff --git a/docs/participate/01_staking/02_advanced_collator_section/05_bootnodes.md b/participate/01_staking/02_advanced_collator_section/05_bootnodes.md similarity index 100% rename from docs/participate/01_staking/02_advanced_collator_section/05_bootnodes.md rename to participate/01_staking/02_advanced_collator_section/05_bootnodes.md diff --git a/docs/participate/01_staking/02_advanced_collator_section/06_benchmarking.md b/participate/01_staking/02_advanced_collator_section/06_benchmarking.md similarity index 100% rename from docs/participate/01_staking/02_advanced_collator_section/06_benchmarking.md rename to participate/01_staking/02_advanced_collator_section/06_benchmarking.md diff --git a/docs/participate/01_staking/02_advanced_collator_section/_category_.json b/participate/01_staking/02_advanced_collator_section/_category_.json similarity index 100% rename from docs/participate/01_staking/02_advanced_collator_section/_category_.json rename to participate/01_staking/02_advanced_collator_section/_category_.json diff --git a/docs/participate/01_staking/03_delegate/01_overview.md b/participate/01_staking/03_delegate/01_overview.md similarity index 100% rename from docs/participate/01_staking/03_delegate/01_overview.md rename to participate/01_staking/03_delegate/01_overview.md diff --git a/docs/participate/01_staking/03_delegate/02_become.md b/participate/01_staking/03_delegate/02_become.md similarity index 100% rename from docs/participate/01_staking/03_delegate/02_become.md rename to participate/01_staking/03_delegate/02_become.md diff --git a/docs/participate/01_staking/03_delegate/03_adjust_stake.md b/participate/01_staking/03_delegate/03_adjust_stake.md similarity index 100% rename from docs/participate/01_staking/03_delegate/03_adjust_stake.md rename to participate/01_staking/03_delegate/03_adjust_stake.md diff --git a/docs/participate/01_staking/03_delegate/04_exit.md b/participate/01_staking/03_delegate/04_exit.md similarity index 100% rename from docs/participate/01_staking/03_delegate/04_exit.md rename to participate/01_staking/03_delegate/04_exit.md diff --git a/docs/participate/01_staking/03_delegate/05_delegator_lifecycle.md b/participate/01_staking/03_delegate/05_delegator_lifecycle.md similarity index 100% rename from docs/participate/01_staking/03_delegate/05_delegator_lifecycle.md rename to participate/01_staking/03_delegate/05_delegator_lifecycle.md diff --git a/docs/participate/01_staking/03_delegate/_category_.json b/participate/01_staking/03_delegate/_category_.json similarity index 100% rename from docs/participate/01_staking/03_delegate/_category_.json rename to participate/01_staking/03_delegate/_category_.json diff --git a/docs/participate/01_staking/04_claim_rewards.md b/participate/01_staking/04_claim_rewards.md similarity index 100% rename from docs/participate/01_staking/04_claim_rewards.md rename to participate/01_staking/04_claim_rewards.md diff --git a/docs/participate/01_staking/05_unlock_unstaked.md b/participate/01_staking/05_unlock_unstaked.md similarity index 100% rename from docs/participate/01_staking/05_unlock_unstaked.md rename to participate/01_staking/05_unlock_unstaked.md diff --git a/docs/participate/01_staking/06_troubleshooting.md b/participate/01_staking/06_troubleshooting.md similarity index 100% rename from docs/participate/01_staking/06_troubleshooting.md rename to participate/01_staking/06_troubleshooting.md diff --git a/docs/participate/01_staking/_04_claim_rewards_collator.mdx b/participate/01_staking/_04_claim_rewards_collator.mdx similarity index 100% rename from docs/participate/01_staking/_04_claim_rewards_collator.mdx rename to participate/01_staking/_04_claim_rewards_collator.mdx diff --git a/docs/participate/01_staking/_04_claim_rewards_delegator.mdx b/participate/01_staking/_04_claim_rewards_delegator.mdx similarity index 100% rename from docs/participate/01_staking/_04_claim_rewards_delegator.mdx rename to participate/01_staking/_04_claim_rewards_delegator.mdx diff --git a/docs/participate/01_staking/_category_.json b/participate/01_staking/_category_.json similarity index 100% rename from docs/participate/01_staking/_category_.json rename to participate/01_staking/_category_.json diff --git a/docs/participate/01_staking/_disclaimer_staking_tx.md b/participate/01_staking/_disclaimer_staking_tx.md similarity index 79% rename from docs/participate/01_staking/_disclaimer_staking_tx.md rename to participate/01_staking/_disclaimer_staking_tx.md index 524d9fef3..299d39747 100644 --- a/docs/participate/01_staking/_disclaimer_staking_tx.md +++ b/participate/01_staking/_disclaimer_staking_tx.md @@ -1,5 +1,5 @@ :::info -You can either execute this transaction in Polkadot JS Apps or the [**KILT Stakeboard**](../../develop/05_builtonkilt.md#web-apps), which serves as an in-house developed Frontend for all KILT staking activity. +You can either execute this transaction in Polkadot JS Apps or the [**KILT Stakeboard**](/develop/builtonkilt#web-apps), which serves as an in-house developed Frontend for all KILT staking activity. Below, we outline the steps for Polkadot JS Apps. The process for KILT Stakeboard is described in detail in the [**BOTLabs Trusted Entity support hub**](https://support.kilt.io/support/solutions/80000442174). ::: diff --git a/docs/participate/02_governance/01_vote.md b/participate/02_governance/01_vote.md similarity index 100% rename from docs/participate/02_governance/01_vote.md rename to participate/02_governance/01_vote.md diff --git a/docs/participate/02_governance/02_remove_vote.md b/participate/02_governance/02_remove_vote.md similarity index 100% rename from docs/participate/02_governance/02_remove_vote.md rename to participate/02_governance/02_remove_vote.md diff --git a/docs/participate/02_governance/03_unlock_coins.md b/participate/02_governance/03_unlock_coins.md similarity index 100% rename from docs/participate/02_governance/03_unlock_coins.md rename to participate/02_governance/03_unlock_coins.md diff --git a/docs/participate/02_governance/_category_.json b/participate/02_governance/_category_.json similarity index 100% rename from docs/participate/02_governance/_category_.json rename to participate/02_governance/_category_.json diff --git a/docs/participate/03_treasury_proposal.md b/participate/03_treasury_proposal.md similarity index 100% rename from docs/participate/03_treasury_proposal.md rename to participate/03_treasury_proposal.md diff --git a/docs/participate/04_content_creation_guidelines.md b/participate/04_content_creation_guidelines.md similarity index 100% rename from docs/participate/04_content_creation_guidelines.md rename to participate/04_content_creation_guidelines.md diff --git a/docs/participate/05_propose_tip.md b/participate/05_propose_tip.md similarity index 97% rename from docs/participate/05_propose_tip.md rename to participate/05_propose_tip.md index 84196c2c7..8d5ec07c8 100644 --- a/docs/participate/05_propose_tip.md +++ b/participate/05_propose_tip.md @@ -6,7 +6,7 @@ title: Treasury Tips Similar to [opening a Treasury proposal](./03_treasury_proposal.md), anyone can start a tipping process. You can expect success if the tip is based on a meaningful contribution. -The variety of potential contributions is vast, read the [KILT Contribution guide](../develop/06_contribute.md) for a high level description of tips and the differences to Treasury proposals. +The variety of potential contributions is vast, read the [KILT Contribution guide](/develop/contribute) for a high level description of tips and the differences to Treasury proposals. This document covers the necessary steps from requesting a tip to receiving it. diff --git a/docs/participate/_category_.json b/participate/_category_.json similarity index 100% rename from docs/participate/_category_.json rename to participate/_category_.json diff --git a/sidebars.js b/sidebars.js index 96e4b1ee0..d4bdb951f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,22 +1,4 @@ module.exports = { - concepts: [ - { - type: 'autogenerated', - dirName: 'concepts', - }, - ], - staking: [ - { - type: 'autogenerated', - dirName: 'participate/01_staking', - }, - ], - governance: [ - { - type: 'autogenerated', - dirName: 'participate/02_governance', - }, - ], chain: [ { type: 'autogenerated', diff --git a/sidebarsConcepts.js b/sidebarsConcepts.js new file mode 100644 index 000000000..eed7746e2 --- /dev/null +++ b/sidebarsConcepts.js @@ -0,0 +1,7 @@ +module.exports = { + concepts: [ + { + type: 'autogenerated', + dirName: '.', + }] +} diff --git a/sidebarsDevelop.js b/sidebarsDevelop.js new file mode 100644 index 000000000..1ddb257ca --- /dev/null +++ b/sidebarsDevelop.js @@ -0,0 +1,7 @@ +module.exports = { + develop: [ + { + type: 'autogenerated', + dirName: '.', + }] +} diff --git a/sidebarsParticipate.js b/sidebarsParticipate.js new file mode 100644 index 000000000..bcca441e3 --- /dev/null +++ b/sidebarsParticipate.js @@ -0,0 +1,7 @@ +module.exports = { + participate: [ + { + type: 'autogenerated', + dirName: '.', + }] +} diff --git a/docs/develop/01_sdk/01_quickstart.md b/versioned_docs/version-0.3/01_sdk/01_quickstart.md similarity index 99% rename from docs/develop/01_sdk/01_quickstart.md rename to versioned_docs/version-0.3/01_sdk/01_quickstart.md index 02bd1c8f5..a01df120a 100644 --- a/docs/develop/01_sdk/01_quickstart.md +++ b/versioned_docs/version-0.3/01_sdk/01_quickstart.md @@ -221,7 +221,7 @@ Run the code and wait to see if you can retrieve **and** verify one of kiltnerd1 :::info Next steps -- If you want to explore more of KILT's features, read our [Concepts section](../../concepts/01_what_is_kilt.md). +- If you want to explore more of KILT's features, read our [Concepts section](/concepts/what-is-kilt). - If you want to dive deeper into the SDK, read the next section, [the KILT Cookbook](./02_cookbook/01_dids/01_light_did_creation.md). ::: diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/00_generate_keys.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/00_generate_keys.md new file mode 100644 index 000000000..1553de1f2 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/00_generate_keys.md @@ -0,0 +1,63 @@ +--- +id: key-generation +title: Generate DID keys +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import GenerateKeys from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/00_generate_did_keys.ts'; + +Creating a Decentralized Identifier (DID) on the KILT network involves generating keying material for authentication and encryption. +This guide shows how to create a set of key pairs suitable for generating a KILT DID. + +Before proceeding, it's important to note that this example assumes the usage of the `@kiltprotocol/sdk-js` library along with the `@polkadot/util-crypto` library for cryptographic operations. + +Additionally, it's important to securely store keys and the mnemonic seed phrase. +For production use, ensure that private keys are encrypted and stored safely, while also creating a backup of the mnemonic seed phrase. + +## Derivation paths + +The code example below derives different types of keys from a single account using derivation paths. + +A derivation path is a way to derive a new key from a parent key and is a sequence of indices separated by a delimiter. +The most common delimiter is `/` (forward slash). + +KILT uses the same derivation paths as the underlying Polkadot libraries, using soft and hard key derivation. + +## Soft derivation + +A soft derivation allows someone to potentially figure out the initial account's private key if they know the derived account's private key. +It is also possible to determine that different accounts generated from the same seed are linked to that seed. + +A `/` (single slash) indicates a soft derivation path. +For example, `deal rice sunny now boss cluster team use wreck electric wing deliver/0` is a soft derivation path. + +## Hard derivation + +A hard derivation path does not allow someone to do either of these. +Even if you know a derived private key, it's not possible to figure out the private key of the root address, and it's impossible to prove that the first account is linked with the second. + +A `//` (double slash) indicates a hard derivation path. +For example, `deal rice sunny now boss cluster team use wreck electric wing deliver//0` is a hard derivation path. + +## Creating new accounts from a seed + +This approach allows you to generate various key pairs for authentication, key agreement, assertion methods, and capability delegation from one mnemonic seed phrase. + +To create another account using the same seed, change the number at the end of the string. For example, `/1`, `/2`, and `/3` create different derived accounts. + +Using derivation paths simplifies key management, ensuring that a single mnemonic seed serves as the basis for multiple keys associated with a DID. +This method improves efficiency while maintaining security. +However, it's essential to handle and store private keys securely to prevent unauthorized access and ensure the overall integrity and privacy of the decentralized identity system. + +Below is an example code snippet illustrating the key pair generation for a KILT DID: + + + {GenerateKeys} + + +:::info +This example doesn't show how to store the keys. +It is recommended to store the keys in a secure manner, e.g. only storing the private keys encrypted on disk. +The mnemonic seed phrase can be used to regenerate the keys, so it is recommended to also store the mnemonic in a secure manner and create a backup of it. +::: diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/01_light_did_creation.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/01_light_did_creation.md new file mode 100644 index 000000000..01c59ac8b --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/01_light_did_creation.md @@ -0,0 +1,36 @@ +--- +id: light-did-creation +title: Create a Light DID +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import LightDidSimple from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/01_light_did_simple.ts'; +import LightDidComplete from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/02_light_did_complete.ts'; + +The creation of a light DID requires the generation of some keying material for keys that are to be used for authentication and encryption. +For the sake of ease of use, the example snippets below show how to use keys generated with a `Keyring`, provided also by the `@polkadot/api` library, to generate key pairs that are kept in memory and disappear at the end of the program execution, unless saved to some persistent storage. + +The following is an example of how to create a light DID after creating an authentication keypair. + + + {LightDidSimple} + + +For cases in which an encryption key and some services also need to be added to a light DID: + + + {LightDidComplete} + + +:::info +In KILT, light DIDs are meant to be used in one of two cases: + +1. As *ephemeral, one-time identifiers* when establishing new communication channels with untrusted parties. +2. As an *entrypoint into the KILT ecosystem*, i.e., to obtain one's first credentials and get acquainted with KILT. + +As such, light DIDs do not support updates of any sort, but they retain the same identifier until they are upgraded to full DIDs. +They are not intended for use in complex and/or high-security use cases. +In those situations, a full DID should be used. +Visit the [next section](./02_full_did_creation.md) to see how to create and manage full DIDs. +::: diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/02_full_did_creation.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/02_full_did_creation.md new file mode 100644 index 000000000..389e8e940 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/02_full_did_creation.md @@ -0,0 +1,34 @@ +--- +id: full-did-creation +title: Create a Full DID +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import FullDidSimple from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/04_full_did_simple.ts'; +import FullDidComplete from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/05_full_did_complete.ts'; +import LightDidMigrate from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/03_light_did_migrate.ts'; + +The following is an example of how to create and write on the blockchain a full DID that specifies only an authentication key. + + + {FullDidSimple} + + +If additional keys or services are to be specified, they can be passed as parameters to the creation transaction. + + + {FullDidComplete} + + +## Upgrade a Light DID to a Full DID + +Another way to obtain a full DID is by upgrading a previously-created light DID. +KILT supports this operation in a way that does not invalidate any credentials that had been issued to the light DID before being upgraded. + +The following code shows how to migrate a light DID to a full DID. +Credentials, presentations, and verifications remain unchanged and remain valid. + + + {LightDidMigrate} + diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/03_full_did_update.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/03_full_did_update.md new file mode 100644 index 000000000..688385841 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/03_full_did_update.md @@ -0,0 +1,15 @@ +--- +id: full-did-update +title: Update a Full DID keys and service endpoints +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import FullDidUpdate from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/07_full_did_update.ts'; + +Once anchored to the KILT blockchain, a full DID can be updated. +For instance, the following snippet shows how to use the `authorizeBatch` function to update the authentication key, remove an old service *and* add a new one for a full DID in the same transaction. + + + {FullDidUpdate} + diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/04_did_query.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/04_did_query.md new file mode 100644 index 000000000..99f68590b --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/04_did_query.md @@ -0,0 +1,22 @@ +--- +id: did-query +title: Resolve a DID +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import DidQuery from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/06_did_query.ts'; + +Querying the state of a DID is called **resolution**. +The entity that queries the DID Document for a given DID, i.e., resolves it, is called a **resolver**. + +The KILT SDK provides such a resolver to use with KILT DIDs, as the snippet below shows: + + + {DidQuery} + + +:::note +The DID resolver can resolve both light and full DIDs. +For a more in-depth explanation about the KILT DID method and resolution, refer to our [specification](https://github.com/KILTprotocol/spec-kilt-did). +::: diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/05_full_did_delete.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/05_full_did_delete.md new file mode 100644 index 000000000..4e4232956 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/05_full_did_delete.md @@ -0,0 +1,29 @@ +--- +id: full-did-delete +title: Delete a Full DID +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import FullDidDelete from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/11_full_did_delete.ts'; +import FullDidDepositReclaim from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/13_full_did_deposit_reclaim.ts'; + +Once a DID is no longer needed, it is recommended to deactivate it by removing it from the KILT blockchain. +The following snippet shows how to do it: + + + {FullDidDelete} + + +:::warning +Please note that once deleted, a full DID becomes unusable and cannot be re-created anymore. +This means that all credentials obtained with that DID are no longer valid and must be obtained with a different DID if needed. +::: + +## Claim back a DID deposit + +Claiming back the deposit of a DID is semantically equivalent to deactivating and deleting the DID, with the difference that the extrinsic to claim the deposit can only be called by the deposit owner and does not require a signature by the DID subject: + + + {FullDidDepositReclaim} + \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/06_full_did_tx.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/06_full_did_tx.md new file mode 100644 index 000000000..ace83349e --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/06_full_did_tx.md @@ -0,0 +1,57 @@ +--- +id: full-did-batch +title: Build DID Extrinsics +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import FullDidSignTx from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/09_full_did_tx.ts'; +import FullDidBatch from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/08_full_did_batch.ts'; + +DID keys can be used to sign extrinsic. +But not every extrinsic can be signed using a DID. +The Spiritnet blockchain offers two types of extrinsics. + +The first type can only be called using an account. +We call them account extrinsic. +The second callable type are DID extrinsics. +They must be used for all KILT features like creating CTypes, issue attestations, etc. +Since every extrinsic requires fees to be paid, this type needs to be wrapped inside an account extrinsic. +Accounts hold balances and can therefore pay fees and provide deposits. + +This document describes how to sign the DID extrinsics. +The KILT SDK provides two functions for signing DID extrinsics. +The first function signs a single extrinsic while the second one batches multiple extrinsics together. + +## Single extrinsics + +To sign a single extrinsic, you need to provide: + +* the DID that wants to sign the extrinsic (also called *origin* of the extrinsic) + * refer to the [full did creation guide](02_full_did_creation.md) to learn how to create a DID +* [a `SignCallback` that signs the extrinsic](../07_signCallback.md) +* the extrinsic that should be signed and submitted +* and the address of the account that pays for the fees. + + + {FullDidSignTx} + + + +## Batch multiple extrinsics + +Full DIDs can also be used to batch multiple extrinsics that require the signature of the DID. +For instance, a batch could create multiple services with a single submission to the blockchain. +This would save the user the time of generating one additional signature, as multiple extrinsics are batched and signed at once. +The extrinsics are also submitted and executed in the same block. +For more information, see the [official Substrate documentation](https://paritytech.github.io/substrate/master/pallet_utility/pallet/struct.Pallet.html). + +An example of a batch using the `authorizeBatch` is provided below. + + + {FullDidBatch} + + +DIDs have different keys that posses different capabilities. +Each key can only be used to authorize a specific subset of extrinsics. +If extrinsics are batched together that require different DID keys, the `authorizeBatch` function will call the sign callback multiple times. diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/07_did_signature.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/07_did_signature.md new file mode 100644 index 000000000..7c6659fb4 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/07_did_signature.md @@ -0,0 +1,25 @@ +--- +id: did-signature +title: Generate and Verify a DID Signature +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import DidSignature from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/10_did_signature.ts'; + +In addition to being used to authorize chain operations, both light and full DIDs have off-chain applications. + +One such applications is generating digital signatures. +As a DID can have multiple keys, in addition to the signature data itself, a DID signature contains information about the signer's DID and key used, so that Verifiers have all the information needed to resolve the DID from the KILT blockchain and use the right key to verify the generated signature. + +The snippet below shows how to generate and verify a DID signature using the KILT SDK. + + + {DidSignature} + + +:::note +Notice that the snippet above takes a `DidDocument` instance to generate the signature. +A `DidDocument` can represent either a light or a full DID. +This means that both light and full DIDs can generate signatures, and the KILT SDK implements the right verification logic depending on whether the signer is a light or a full DID. +::: diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/08_did_export.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/08_did_export.md new file mode 100644 index 000000000..8b53f209d --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/08_did_export.md @@ -0,0 +1,21 @@ +--- +id: did-export +title: Exporting a KILT DID +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import DidExport from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/12_did_export.ts'; + +The DID Document exporter provides the functionality needed to convert an instance of an SDK `DidDocument` object into a document that is compliant with the [W3C specification](https://www.w3.org/TR/did-core/). +This component is required for the KILT plugin for the [DIF Universal Resolver](https://dev.uniresolver.io/). + +## How to use the exporter + +The exporter interface and used types are part of the `@kiltprotocol/types` package, while the actual `DidDocumentExporter` is part of the `@kiltprotocol/did` package. +Both types and DID packages are accessible via the top-level `@kiltprotocol/sdk-js` import. +The following shows how to use the exporter to generate a W3C-compliant DID Document from a given `DidDocument`, which can represent either a light or a full DID. + + + {DidExport} + \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/_category_.json new file mode 100644 index 000000000..cd4de73d6 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/01_dids/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "KILT DIDs", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/01_claim.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/01_claim.md new file mode 100644 index 000000000..88f687ba8 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/01_claim.md @@ -0,0 +1,19 @@ +--- +id: web3name-claim +title: Claim a web3name +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import Claim from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/web3names/01_claim.ts'; + +A web3name can be claimed if it currently has no owner, using the following snippet as reference. + + + {Claim} + + +The claiming process requires the reservation of a deposit that is freed upon web3name release. + +Once claimed, the web3name will start appearing whenever the DID of its owner is resolved, for instance via the [Universal Resolver](https://dev.uniresolver.io/#did:kilt:4pZGzLSybfMsxB1DcpFNYmnqFv5QihbFb1zuSuuATqjRQv2g). +For more information about web3names and DIDs, see the official [KILT DID Specification](https://github.com/KILTprotocol/spec-kilt-did/blob/main/README.md). diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/02_credential_query.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/02_credential_query.md new file mode 100644 index 000000000..9213f6810 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/02_credential_query.md @@ -0,0 +1,21 @@ +--- +id: credential-query +title: Query Public Credentials for a web3name +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import QueryNameCredentials from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/web3names/03_query_name_credentials.ts'; + +web3names are linked to KILT DIDs, and KILT DIDs can define services to expose additional service/information. +One of the possible endpoint types is the [`KiltPublishedCredentialCollectionV1`][kilt-published-credential-collection-v1-type] type. +The type defines the structure to make KILT credentials public and accessible to anyone. + +Because of the relationship between web3names and DIDs, it is possible, given a certain web3name, to retrieve all public credentials that the DID subject identified by that web3name has made available. +Below is a code snippet showing how to do that using the KILT SDK, and how to perform the needed security checks/validation as recommended by the [specification][kilt-published-credential-collection-v1-type]. + + + {QueryNameCredentials} + + +[kilt-published-credential-collection-v1-type]: https://github.com/KILTprotocol/spec-KiltPublishedCredentialCollectionV1/blob/main/README.md diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/03_release.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/03_release.md new file mode 100644 index 000000000..a22050964 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/03_release.md @@ -0,0 +1,48 @@ +--- +id: web3name-release +title: Release a web3name +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import Release from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/web3names/04_release.ts'; +import ReclaimDeposit from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/web3names/05_reclaim_deposit.ts'; + +If a web3name is no longer needed, either the DID owner or the deposit payer can release it, with deposit being released and returned to the original payer. + +## Releasing a Web3name by the DID Owner + +In the case of the DID owner willing to release the web3name, the following snippet provides a reference implementation on how to achieve that. + + + {Release} + + +In the code above, the `releaseWeb3Name` function takes the following parameters: + +* **did**: The DID URI of the owner. +* **submitterAccount**: The keyring pair of the submitter. +* **signCallback**: The sign extrinsic callback function. This function is used to sign the extrinsic, read more that in [the SignCallback section](../07_signCallback.md). + +The function `releaseWeb3Name` uses the KILT SDK to create a *web3name release transaction* using `api.tx.web3Names.releaseByOwner`. +It then authorizes the transaction using the `Kilt.Did.authorizeTx` method and submits the authorized transaction to the blockchain using `Kilt.Blockchain.signAndSubmitTx`. +This process ensures that the release transaction is signed by the DID owner. + + +## Reclaiming a Web3name Deposit by the Deposit Payer + +If the web3name is being released by the deposit payer, the signature of the DID owner is not required; a regular signed extrinsic can be submitted to the KILT blockchain, as shown below. + + + {ReclaimDeposit} + + +In the code above, the `reclaimWeb3NameDeposit` function takes the following parameters: + +* **submitterAddress**: The keyring pair of the submitter. +* **web3Name**: The web3name for which the deposit is to be reclaimed. + +The function creates a web3name deposit reclaim transaction using `api.tx.web3Names.reclaimDeposit` and submits the signed transaction to the blockchain using `Kilt.Blockchain.signAndSubmitTx`. +Since the web3name is being released by the deposit payer, the signature of the DID owner is not required. + +By using these code examples, you can easily release or reclaim the deposit of a web3name, depending on the scenario and the role of the entity initiating the release. diff --git a/docs/develop/01_sdk/02_cookbook/02_web3names/04_query.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/04_query.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/02_web3names/04_query.md rename to versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/04_query.md diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/_category_.json new file mode 100644 index 000000000..6dab303b4 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/02_web3names/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "web3names", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/01_link.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/01_link.md new file mode 100644 index 000000000..db6735186 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/01_link.md @@ -0,0 +1,87 @@ +--- +id: account-link +title: Link an Account to a KILT DID +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import SubAccLink from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/01_sub_link.ts'; +import EthAccLink from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/01_eth_link.ts'; +import EthWeb3AccLink from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/01_eth_link_web3js.ts'; +import EthMetamaskAccLink from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/01_eth_link_metamask.ts'; +import SenderLink from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/02_sender_link.ts'; + +Sometimes there is the need to link a DID to an account publicly. +The link makes it possible to lookup a DID for an account. +The other directions is also possible. +With a DID you can lookup a list of linked account. + +Linking accounts can be useful when your account should have an identity. +E.g. as a collator, you might want to provide some public information so that delegator can better decide who earned their stake. + +An account can be linked to a DID in one of two ways. +Either the account that sends the transaction links itself to the DID, or the sender is unrelated to the DID and a third account is linked. +In the latter case, a challenge needs to be signed using the third account, to prove ownership. + +The second option is useful in cases where the account that should be linked doesn't own KILT tokens and the transaction is paid for by a third party. +This option also allows to link account schemes that are not native to the Spiritnet Blockchain. +Right now the only other address scheme supported are ethereum accounts. + +:::warning Don't use linked accounts for asset transfers + +Don't use these linked accounts for asset transfers. +Since these accounts are not limited to KILT accounts, but can be used on any chain, the recipient might not be able to access the transferred asset on other chains. +When a link to an account on a different Polkadot chain is created, this account might only be usable on this specific chain. + +If you want transfer assets to a DID have a look at [the asset transfer service](https://github.com/KILTprotocol/spec-KiltTransferAssetRecipientV1). + +::: + +## Linking the sender to a DID + +Link the sender of the transaction to the DID. +The sender will provide the deposit and pay the fees. +They will also be linked to the DID. + + + {SenderLink} + + +## Linking an account to a DID + +Link another account to the DID. +The sender will provide the deposit and pay the fees, but will not be linked to the DID in any way. +The account that should be linked must sign a challenge to prove that the account agrees to be linked. + +The proof contains the DID that the account will be linked to and an expiration date (in terms of blocks), to prevent replay attacks. +The proof will only be valid up until the blocknumber is reached. + +With this option you can link addresses that are supported by the Spiritnet blockchain (Sr25519, Ed25519, Ecdsa), but also ethereum addresses. + + + + + {SubAccLink} + + + + + {EthAccLink} + + + + + {EthWeb3AccLink} + + + + Refer to the Metamask documentation for further information. + + {EthMetamaskAccLink} + + + diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/02_account_name.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/02_account_name.md new file mode 100644 index 000000000..ed7357fb6 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/02_account_name.md @@ -0,0 +1,27 @@ +--- +id: account-name +title: Query the web3name of an Account +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import AccountWeb3NameQuery from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/03_account_web3name_query.ts'; +import AccountWeb3NameQueryNoSDK from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/04_account_web3name_query_no_sdk.ts'; + +For accounts that have been linked to DIDs that have claimed a web3name, the linking feature opens the way to a host of possibilities, e.g., showing the web3name of a collator's account on the [KILT Stakeboard][kilt-stakeboard]. + +This section shows how to perform the `account -> web3name` querying both with and without the support of the KILT SDK. + +## Query an Account's web3name with the KILT SDK + + + {AccountWeb3NameQuery} + + +## Query an Account's web3name without the KILT SDK + + + {AccountWeb3NameQueryNoSDK} + + +[kilt-stakeboard]: https://stakeboard.kilt.io/ diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/03_unlink.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/03_unlink.md new file mode 100644 index 000000000..08711f178 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/03_unlink.md @@ -0,0 +1,30 @@ +--- +id: account-unlink +title: Unlink an Account From a KILT DID +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import DidUnlink from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/05_did_unlink.ts'; +import AccountUnlink from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/06_account_unlink.ts'; +import ReclaimDeposit from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/07_reclaim_deposit.ts'; + +Similar to the way a new account to DID link is created, removing a link can happen in one of three ways: + +1. The DID owner submits a transaction indicating which account to unlink: + + + {DidUnlink} + + +2. The linked account submits a transaction indicating that the link with the DID should be removed: + + + {AccountUnlink} + + +3. The deposit payer submits a transaction indicating that they want to reclaim their deposit, which in turn removes the existing link between the specified account and DID: + + + {ReclaimDeposit} + \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/_category_.json new file mode 100644 index 000000000..ac71ff896 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/03_account_linking/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Account <-> KILT DID Relationship", + "collapsible": true, + "collapsed": true +} diff --git a/docs/develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md similarity index 93% rename from docs/develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md rename to versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md index 12d3aba54..74a17cac6 100644 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md @@ -11,7 +11,7 @@ import FetchCType from '!!raw-loader!@site/code_examples/sdk_examples/src/core_f Every KILT credential has to conform to a CType. A CType describes which properties a credential has and what type these properties have. CTypes must be registered on the Spiritnet blockchain. -To learn more about CTypes, see the [CType concept section](../../../../concepts/05_credentials/02_ctypes.md). +To learn more about CTypes, see the [CType concept section](/concepts/credentials/ctypes). The creation of a CType in KILT involves two steps: the definition of a CType and the anchoring of its hash on the KILT blockchain. diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/02_attestation_request.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/02_attestation_request.md new file mode 100644 index 000000000..bd602126f --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/02_attestation_request.md @@ -0,0 +1,21 @@ +--- +id: attestation-request +title: Request an Attestation +--- +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import RequestAttestation from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/03_request_attestation.ts'; + +To obtain credentials, Claimers have to request an attestation for a set of claims from an Attester. +The resulting object is a `Credential`, which can be created following the snippet below. + +This process does not involve any interaction with the KILT blockchain, but is simply a communication channel where the Claimer and the Attester can communicate. + + + {RequestAttestation} + + +:::note +The structure of the claims must respect the schema defined in the specified CType. +Attesters (and Verifiers) will reject claims that fail to verify correctly. +::: \ No newline at end of file diff --git a/docs/develop/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md similarity index 100% rename from docs/develop/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md rename to versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md new file mode 100644 index 000000000..facd14d49 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md @@ -0,0 +1,26 @@ +--- +id: presentation-creation +title: Present a Credential +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import CreatePresentation from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/05_create_presentation.ts'; + +With a valid credential, Claimers can now go to Verifiers to request some service upon providing proof of validity of a certain credential. +The process of presenting one or more credentials to a Verifier is called `Presentation`. + +This step, similar to the [attestation request](./02_attestation_request.md), requires that a communication channel exist between the Claimer and the Verifier so that information about the presentation can be shared. +To verify the revocation status of the presented credential(s), a Verifier must be able to interact with a KILT full node. + +:::info +KILT supports selective disclosure of claims when creating presentations. +This means that given a credential, it is possible for the Claimer to reveal only a subset of its claims, depending on the requirements set by the Verifier. +Check the snippet below to see how that is done using the KILT SDK. +::: + +The Claimer can generate a presentation starting from a credential, optionally specifying the fields to reveal and a presentation challenge, which is useful to prove freshness of the generated presentation. + + + {CreatePresentation} + \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md new file mode 100644 index 000000000..480cc236d --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md @@ -0,0 +1,27 @@ +--- +id: presentation-verification +title: Verify a Credential or a Presentation +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import VerifyPresentation from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/06_verify_presentation.ts'; + +Whether a presentation involves selective disclosure or a whole credential is not technically relevant to Verifiers. +This is because in KILT a presentation **is** a credential. +This means that the logic for Verifiers does not change depending on the case, thus verifying a presentation is as easy as calling one SDK function, like the following code snippet: + + + {VerifyPresentation} + + +:::warning Check if the presenter is the credential subject +Verifying a presentation provides proof that all the information is correct and authentic, and that the credential has not been revoked. +Verifiers still need to match the subject of the credential to the entity that is presenting it. +One way of achieving this is by asking the Claimer to include a challenge in the presentation signature, as shown in the snippet above. +Without a challenge, Verifiers must implement other measures to be certain about the identity of the presenter. +::: + +:::warning Evaluation of the attester's trust is up to the Verifiers +Verifiers must also have a registry of attesters they trust, and verify that the issuer of the credential they are verifying belongs to such list and, where necessary, whether it is still in operation or not, i.e., whether its DID still exists or has been deleted. +::: \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md new file mode 100644 index 000000000..da6ff398b --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md @@ -0,0 +1,26 @@ +--- +id: attestation-removal +title: Revoke a Credential +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import RevokeCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/07_revoke_credential.ts'; +import ReclaimDeposit from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/claiming/08_reclaim_attestation_deposit.ts'; + +If the conditions that make a credential valid cease to exist, an Attester can revoke and optionally remove their attestation from the KILT blockchain. +This does not automatically delete the credential from the Claimer's wallet, of course, but it makes it impossible for the Claimer to use the credential in the future. + +Since the attestation creation reserved some KILT tokens from the submitter's balance, removing an attestation would return those funds into the payer's pockets. + + + {RevokeCredential} + + +## Claim Back an Attestation Deposit + +Claiming back the deposit of an attestation is semantically equivalent to revoking and removing the attestation, with the difference that the extrinsic to claim the deposit can only be called by the deposit owner and does not require the Attester's signature: + + + {ReclaimDeposit} + \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/_category_.json new file mode 100644 index 000000000..21073c229 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/04_claiming/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "KILT Credentials", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md new file mode 100644 index 000000000..651723e4d --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md @@ -0,0 +1,44 @@ +--- +id: public-credential-issuance +title: Credential Issuance +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import CreateCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/01_create_credential.ts'; +import IssueCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/02_issue_credential.ts'; + +As for traditional KILT credentials, public credentials also have their structure defined by a [CType][ctypes-link], although CTypes that can be used to represent information about assets would probably differ from the ones used to represent information about people. + +As mentioned in the section about credentials, the creation of a CType in KILT involves two steps: the definition of a CType and the anchoring of its hash on the KILT blockchain. + +We will not cover the creation of a CType, please refer to the [CType creation](../04_claiming/01_ctype_creation.md) + +## Create and Issue the Credential + +Using the existing CType, the new public credential object can be created with the actual content, and then written to the chain for the rest of the KILT users (and beyond) to consume. + +Creating a public credential is as simple as creating an object that conforms to the required structure of the CType: + + + {CreateCredential} + + +:::note +The creation of the credential object does not require any interaction with the blockchain per se. +This also means that, until the object is written to the blockchain (see below), it cannot be used/retrieved/verified by anyone else, so it is, by all means, not existing. +::: + +Once the credential object is created, it must be written to the blockchain for other people to be able to use it. + + + {IssueCredential} + + +:::info Credential has to be CBOR-encoded! +Given a public credential object, the SDK internally CBOR-encodes it before firing the extrinsic to the blockchain! +This is to save space on credentials that actually benefit from CBOR compression (e.g., if they contain a lot of binary information). +Hence, creating public credentials without the SDK requires the credential to be CBOR-encoded! +::: + +[ctypes-link]: /concepts/credentials/ctypes diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md new file mode 100644 index 000000000..40a63e6c3 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md @@ -0,0 +1,68 @@ +--- +id: public-credential-retrieval +title: Retrieve Public Credentials +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import RetrieveCredentialbyId from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/03_retrieve_credential_by_id.ts'; +import RetrieveCredentialsbySubject from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/04_retrieve_credentials_by_subject.ts'; +import VerifyCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/05_verify_credential.ts'; + +Public credentials have their best capability in the fact that they are, indeed, public by design. +This means that once issued, anyone who has access to an archive or full node for the KILT blockchain can retrieve them, making them very decentralized in nature. + +The KILT SDK exposes different ways to fetch public credentials. + +## Retrieve a Credential by its Identifier + +Some use cases might involve the communication of just the ID of one or more public credentials, e.g., to offload the retrieval of the full credential to the receiver, and save some communication bandwidth. + +The KILT SDK accounts for this use case, and makes it very easy to query a public credential given its ID: + + + {RetrieveCredentialbyId} + + +If a credential with the provided ID cannot be found, then the ID is invalid and should be treated as such by the received. + +## Retrieve All Credentials for an Asset + +Other use cases might work differently: given an asset identified by an [AssetDID][asset-did-concept], a user might want to retrieve all the credentials that have been issued to that asset. + +The KILT SDK makes also this use case very easy: + + + {RetrieveCredentialsbySubject} + + +## Verify a Public Credential + +A third class of use cases might involve users exchanging whole public credentials, for instance when showing some sort of proof. + +This case is also supported by the KILT SDK, and relies on an important feature of public credentials: **the identifier (ID) of a public credential is generated from its content and from the KILT DID of its attester**. +This means that even a minimal change in the content of a public credential object before being shared with other parties, will result in those parties deriving a different identifier from the credential, which will then lead to an error during the verification process. + +Verifying a public credential is shown in the following snippet: + + + {VerifyCredential} + + +What the `verifyCredential` function does internally is the following: + +1. Derive the credential identifier from the provided content and attester information. +2. Fetch the actual credential from the blockchain, as shown in the [section above](#retrieve-a-credential-by-id), failing if the credential does not exist. +3. [OPTIONAL] Verify that the credential structure matches what the optionally-provided CType defines. +4. Verify that the rest of the fields in the provided credential (i.e., revocation status, identifier, creation block number) match the retrieved credential. + +If all the tests above pass, the credential is considered valid! ✅ + +:::info How are public credentials stored on the blockchain? +Because public credentials need to be public and accessible by everyone, their full content needs to be somehow stored on the blockchain. +Nevertheless, the credential itself is not stored as part of the blockchain database. +Rather, the block number in which the extrinsic is submitted is stored inside the blockchain database, and serves as a "pointer" to the block containing the whole information, that clients (including the SDK) can use. +This represents a very good tradeoff between **security** - because the blockchain itself dictates what the creation block number is for any given public credential - and **storage efficiency** - since the full credential is stored off-chain, accessible via any KILT archive node or indexing service. +::: + +[asset-did-concept]: /concepts/asset-dids \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md new file mode 100644 index 000000000..23f9a79f9 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md @@ -0,0 +1,63 @@ +--- +id: public-credential-revocation +title: Revoke (and remove) Public Credentials +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import RevokeRemoveCredentialById from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/06_revoke_remove_credential_by_id.ts'; +import RevokeCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/07_revoke_remove_credential_by_content.ts'; +import UnrevokeCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/08_unrevoke_credential.ts'; +import ReclaimDeposit from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/public_credentials/09_reclaim_deposit.ts'; + +Depending on the use cases, some credentials, as with any other type of credential, might need to be temporarily or permanently revoked. + +The KILT SDK provides different features depending on the needs of the use case. + +## Revoke and Remove a Credential + +As we have seen for [public credential retrieval][credential-retrieval], a credential identifier is sufficient to perform most operations on public credentials. +This is true also for revocation and removal. + +Some use cases might need a revoked credential to remain on chain and marked as revoked, while other use cases might combine together revocation and removal, removing a credential whenever it is to be marked as revoked, fulfilling the same goal of marking the credential as invalid. + +In the former case, the deposit taken at the time when the credential is created is not returned, since the credential is still on chain. +In the latter case, all information about the information is cleared, hence the deposit is returned to its original payer. + + + {RevokeRemoveCredentialById} + + +Because a credential identifier can also be calculated starting from the credential itself and the information about its attester, it is also possible to revoke (and optionally remove) a credential given the credential itself. + + + {RevokeCredential} + + +## Unrevoke a Credential + +For public credentials that have been revoked but not removed from chain, it is possible to un-revoke them, making them valid again. + +For instance, a driving license can be marked as "suspended" for three years, without being completely invalidated. +At the end of the suspension period, it is enabled again by being unrevoked. + +As for revocation, both the credential ID and the whole credential can be used, since the SDK provides the primitives to always obtain the former from the latter, but here we show how the whole credential can be used to generate and submit an un-revocation transaction. + + + {UnrevokeCredential} + + +## Reclaim the Deposit for a Credential + +All the operations mentioned so far, always require the participation of the public credential attester, who must use their assertion key to sign all operations before they are submitted to the KILT blockchain. + +The only operation that can be submitted directly by someone else, as with other places in the SDK, is the transaction to remove a credential and obtain the initial deposit. + +This is, technically speaking, a different operation compared to the one to remove a credential, albeit the two yield the same result: all traces of the credential are removed from the chain and the deposit is returned to its payer. +The difference between the two is about who is authorized to perform the operation: while credential removal requires a DID signature by the original credential creator (a.k.a. issuer), the deposit claiming operation requires a regular transaction signature by the KILT account that paid the original deposit, with no involvement of the original attester. + + + {ReclaimDeposit} + + +[credential-retrieval]: ./02_credential_retrieval.md \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/_category_.json new file mode 100644 index 000000000..ddf9ba6eb --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/05_public_credentials/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Public Credentials and AssetDIDs", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/01_messaging.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/01_messaging.md new file mode 100644 index 000000000..406b53343 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/01_messaging.md @@ -0,0 +1,55 @@ +--- +id: messaging_book +title: Generate a Message +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import GenerateRequestCredentialMessage from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/messaging/01_generate_request_credential_message.ts'; +import EncryptMessage from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/messaging/02_encrypt_message.ts'; +import DecryptMessage from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/messaging/03_decrypt_message.ts'; + +KILT defines a [unicast](https://en.wikipedia.org/wiki/Unicast) messaging protocol + +Each of the messages sent is encrypted using the [DID key agreement key](https://www.w3.org/TR/did-core/#key-agreement). +A message consists of the sender's DID URI, the receiver's DID URI, the message type and the body. +There are multiple different message types, each of them with a different structure and containing different information. +In this example we are going to build a `request-credential` message. +The message structure is checked and validated on by the KILT SDK to ensure the users are sending correctly structured messages. + +The following example here will generate a message by constructing the message content. +The message content includes a valid `cTypeHash` and a list of `trusted attesters`. +The message requires a `messageBody`, sender and receiver uri. + + + {GenerateRequestCredentialMessage} + + +## Encryption + +The messages data are encrypted and decrypted using [nacl's](https://github.com/dchest/tweetnacl-js) 'x25519-xsalsa20-poly1305' algorithm, which provides repudiable authenticated encryption based on an x25519 key agreement protocol. +The DID holds keys for the encryption and decryption. +The key is called `KeyAgreement` keys. +They may also be known as encryption keys. + +The content of the object is converted from a serialized string to a byte array, which is passed into the callback function along with the sender's DID and key agreement public key of the receiver. + +The following example here will take a generated message and encrypt the message for the receiver to decrypt later. + + + {EncryptMessage} + + +The encrypted data is converted into a hex string which is known as the ciphertext along with the nonce that was generated during encryption. + +## Decryption + +The decryption takes the encrypted message and decyphers its content. +The following example here will take a encrypted message and decrypt using the private key of the receiver. +Once decrypted, it checks the content is a valid message. +The decrypted data can be used for additional steps. +After decrypting, the receiver may wish to present a credential from the trusted attester list with a given CType. + + + {DecryptMessage} + diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/02_replay_protection.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/02_replay_protection.md new file mode 100644 index 000000000..4c5d93b87 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/02_replay_protection.md @@ -0,0 +1,43 @@ +--- +id: replay_protection +title: Protect Against Replay Attacks +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import DefineRange from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/messaging/_replay_protection_01.ts'; +import EvaluateMessageTime from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/messaging/_replay_protection_02.ts'; +import PurgeTimeout from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/messaging/_replay_protection_03.ts'; + +Whenever data travels on a public network, even when encrypted or signed, the communicating parties need to make sure they never accept and process a message more than once to protect against exploits by malicious third parties (so-called replay attacks). +When requesting and submitting credential presentations, vulnerabilities for replay attacks can be prevented by requesting that the Claimer sign a unique piece of data as part of the presentation, as shown in the [Verification Cookbook section](../04_claiming/04_presentation_creation.md). + +However, protection against replay attacks can also happen on the message layer. +To help prevent these types of attacks, KILT messages are timestamped and expose a unique identifier as part of their encrypted content, which therefore cannot be tampered with. +It is good practice to impose limits on an acceptable range for timestamps on incoming messages and to keep a record of the ids of previous submissions, which can be purged after their acceptance range has run out. +This way, any resubmission is either rejected because its id is known to the recipient, or because its timestamp is too old. +Below you can find example code of how this could be implemented. + +1. Define acceptance range and set up a record of past submissions: + + + {DefineRange} + + +2. Check record for each incoming message and update if accepted: + + + {EvaluateMessageTime} + + +3. Purge at regular intervals: + + + {PurgeTimeout} + diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/_category_.json new file mode 100644 index 000000000..2c3437f16 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/06_messaging/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Messaging", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/07_signCallback.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/07_signCallback.md new file mode 100644 index 000000000..e704093ab --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/07_signCallback.md @@ -0,0 +1,83 @@ +--- +id: signCallback +title: SignCallback +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import SignCallback from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/signCallback/useSignCallback.ts'; +import SignExtrinsicCallback from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/signCallback/useExtrinsicCallback.ts'; +import GetStoreTxSignCallback from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/signCallback/useStoreTxSignCallback.ts'; + +Signing data involves using the private key and therefore needs to be secure. +There are many different options how data could be signed. +You might have the private key stored in memory and are therefore able to simply sign the data. +This is the easiest option but also comes with higher security risk. +Storing the private key on a separate device or inside a sandboxed application can increase security. +But to enable these security options, we need a generic interface to talk to the signer. +This is what the `SignCallback` does. + +The `SignCallback` defines an interface between the SDK and an arbitrary signing strategy. +May it be a ledger, an air gapped phone or your browser extension. +The interface is generic enough to support implementations for all these security measures. + +## The SignCallback Family + +There are three types of signing callbacks: +1. The `SignCallback` is the most general and can be used in almost all cases, except when signing a full DID creation transaction. +2. The `SignExtrinsicCallback` is a special `SignCallback` which can only be used to sign extrinsics. + Thus, every `SignCallback` can also be used as a `SignExtrinsicCallback`. +3. The `GetStoreTxSignCallback` can only be used to sign the creation of a new DID. + +### SignCallback + +The plain `SignCallback` signs arbitrary data. +It is called with `SignRequestData` which contains + +* the `data` as `UInt8Array` that should be signed +* the `keyRelationship` which specifies which DID key must be used +* and the `did` (`DidUri`) which specifies the DID that must sign the data + +The callback is expected to return a `SignResponseData` which contains + +* the `signature` as an `UInt8Array` +* the `keyUri` which identifies the key that was used for signing +* and the `keyType` which specifies the signature scheme that was used (either `sr25519`, `ed25519` or `ecdsa`) + +The signed callback can be used as a closure. +If you already have the private key of the DID stored in the surrounding scope, you can just use this key. + + + {SignCallback} + + +### SignExtrinsicCallback + +The `SignExtrinsicCallback` is a special case of the `SignCallback`. +Signing an extrinsic doesn't require the `keyUri` as a return value since the chain will pick the appropriate key using information from the extrinsic. +The extrinsic that is submitted has a specific `VerificationKeyRelationship`, which defines which key must be used to sign the extrinsic. +Using this relation between extrinsic and key, the chain looks up the public key and verifies the signature. + +The `SignExtrinsicCallback` is called with the same `SignRequestData`, but can return a `SignResponseData` that doesn't contain the `keyUri` but only + +* the `signature` as an `UInt8Array` +* and the `keyType` which specifies the signature scheme that was used (either `sr25519`, `ed25519` or `ecdsa`). + + + {SignExtrinsicCallback} + + +### GetStoreTxSignCallback + +The `GetStoreTxSignCallback` is only used to sign the data that is submitted to the blockchain when a DID is being created. +Because there is no DID identifier before the DID is registered on chain, this callback doesn't receive the DID as a parameter. +There is also no DID document and no public key stored if the DID hasn't yet been created. +Therefore the `keyUri` cannot point to a valid DID key and is not included in the return data. + + + {GetStoreTxSignCallback} + + +## Signing using an extension + +🚧 This section is work in progress 🚧 diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md new file mode 100644 index 000000000..5cd11e026 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md @@ -0,0 +1,93 @@ +--- +id: v29-backward-compatibility +title: Backward Compatibility with Pre-0.29.x Versions +--- + +Depending on how exactly your application interacts with other applications, changes to some data formats and interfaces might mean that conversions are required for them to remain compatible. + +To align with breaking changes to data structures in messaging, credentials, and CTypes, we published version 3.0 of the [Credentials API specification](https://github.com/KILTprotocol/spec-ext-credential-api) that specifies how browser extensions like the [Sporran credential wallet](https://github.com/BTE-Trusted-Entity/sporran-extension) interact with web applications that produce or consume credentials. + +When upgrading to a 0.29.x version of the SDK and to the Credentials API version 3.0, we recommend backward support of Credentials API version 2.0, as supporting only the latest version may result in poor user experience. In what follows, we outline an upgrade strategy for implementers of the Credentials API specification. + +These instructions will also help with translating from and to data types of pre-0.29 SDK versions in other scenarios, such as when sending messages between clients, or when importing older data (e.g. credentials). + +## General Strategy + +Since version 3.0, the specification requires conformant web apps as well as extensions to announce the versions of the API they use, allowing for version negotiation. +Because extensions inject themselves into web pages that signal support for kilt features via the `window.kilt` property, the recommended strategy is to handle backward compatibility on the extension side. +This way, extensions can be upgraded ahead of time, and implement a fallback to a version 2.0 compatible interface if a web application does not signal version 3.0 support. +Following this strategy, backward compatibility on the application side is not strictly necessary. +We recommend notifying users of web apps that have upgraded to version 3.0 if they try to connect with an older extension, pointing them to the need to upgrade their extension to use this app. + +## Message Conversion + +Breaking changes introduced with version 3.0 of the Credential Api exclusively affect selected data types of messages passed between the application backend and extension. +In the attester (credential issuance) flow the message types `submit-terms` and `request-attestation` have changed. +In the verifier (presentation exchange) flow the message type `submit-credential` message is affected. + +Version 3.0 extensions can achieve backward compatibility by translating messages received from and sent to the application which implements an earlier version of the specification. +Below you can find brief descriptions of how these conversions can be implemented. + + + +### `submit-terms` + +When receiving a `submit-terms` message from the old web app, replace the items of the `cTypes` content property with the values of their `schema` properties: + +```ts +interface Old { + cTypes: Array<{ + schema: ICTypeSchema + hash: HexString // duplicates `schema.$id` + owner: DidUri | null // apparently unused + }> + ... +} + +interface New { + cTypes: Array // Note that 0.29 renames ICTypeSchema to ICType + ... +} +``` + + + +### `request-attestation` + +Before encrypting a `request-attestation` type message destined for an older web app, rename `credential` to `requestForAttestation`: + +```ts +interface New { + credential: { claim, ... } + quote?: IQuoteAgreement +} + +interface Old { + requestForAttestation: { claim, ... } + quote?: IQuoteAgreement +} +``` + +:::info +The old `IRequestForAttestation` interface optionally allowed claimers to attach a signature for authentication. +There is no property intended for this purpose on the new interface, as the message encryption scheme already takes care of authentication. +What has changed is that this form of authentication is __not publicly verifiable__. +Attesters can instead require claimers to sign a quote agreement for the purpose of bookkeeping, which contains the credential hash and thus represents a commitment to any claims made. +::: + +### `submit-credential` + +Before encrypting a `submit-credential` message for the older application, replace every item with an object having the property `request` with the value of item itself, and the property `attestation` with the attestation for this credential. + +```ts +interface New extends Array<{ claim, ..., claimerSignature }> {} + +interface Old extends Array<{ + attestation: { claimHash, owner, ... } + request: { claim, ..., claimerSignature } +}> {} +``` diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json new file mode 100644 index 000000000..a58847a1c --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Upgrading to v0.29", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md b/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md new file mode 100644 index 000000000..810b3c4c0 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md @@ -0,0 +1,15 @@ +--- +id: howto-upgrade-v29-index +title: Upgrading to v0.29 +--- + +Version 0.29.0 is the result of our efforts to make the SDK easier to understand and to use. + +As a consequence, quite a few things have changed relative to previous versions. +These pages serve as a reference point for what to consider when upgrading to make your transition as smooth as possible. + + + +Find out what has changed and how to upgrade in the [release notes](https://github.com/KILTprotocol/sdk-js/releases/tag/0.29.0). + +Also make sure to read up on [how to remain interoperable](./01_backward_compatibility.md) with previous versions of the SDK. diff --git a/docs/develop/01_sdk/02_cookbook/_category_.json b/versioned_docs/version-0.3/01_sdk/02_cookbook/_category_.json similarity index 100% rename from docs/develop/01_sdk/02_cookbook/_category_.json rename to versioned_docs/version-0.3/01_sdk/02_cookbook/_category_.json diff --git a/versioned_docs/version-0.3/01_sdk/03_chain_setup/01_standalone_setup.md b/versioned_docs/version-0.3/01_sdk/03_chain_setup/01_standalone_setup.md new file mode 100644 index 000000000..5ba705d44 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/03_chain_setup/01_standalone_setup.md @@ -0,0 +1,113 @@ +--- +id: standalone-chain-setup +title: BYOB - Bring Your Own Blockchain +--- + +If you want to have full control over your blockchain deployment, e.g., if you want to reset the state repeatedly or need more funds than a faucet can provide for a single account, you will need to run your own blockchain. +For this purpose, we provide a Docker image which runs in standalone mode. +This means that the blockchain doesn't act as a parachain but as an independent chain. +There is no need to run a Relay Chain and register the KILT chain as a parachain. +This greatly simplifies the setup. + +You only need to start the Docker image: + +```bash +docker run --rm -it -p 9944:9944 -p 9933:9933 kiltprotocol/standalone-node:latest --dev --ws-external --rpc-external +``` + +You should see output similar to the following: + +``` +2022-05-05 13:25:12 KILT Node +2022-05-05 13:25:12 ✌️ version 1.6.2 +2022-05-05 13:25:12 ❤️ by KILT , 2019-2022 +2022-05-05 13:25:12 📋 Chain specification: Development +2022-05-05 13:25:12 🏷 Node name: subdued-chair-0035 +2022-05-05 13:25:12 👤 Role: AUTHORITY +2022-05-05 13:25:12 💾 Database: RocksDb at /tmp/substrateufCNUV/chains/development/db/full +2022-05-05 13:25:12 ⛓ Native runtime: kilt-kestrel (kilt-kestrel-0.tx3.au4) +2022-05-05 13:25:13 🔨 Initializing Genesis block/state (state: 0xb4a2…94b3, header-hash: 0x09fc…3a2b) +2022-05-05 13:25:13 👴 Loading GRANDPA authority set from genesis on what appears to be first startup. +2022-05-05 13:25:14 Using default protocol ID "sup" because none is configured in the chain specs +2022-05-05 13:25:14 🏷 Local node identity is: 12D3KooWMCqWaxXTQbmG9feCe4cMzjCzUKfm5T6VvGDmh8X5QHe9 +2022-05-05 13:25:14 📦 Highest known block at #0 +2022-05-05 13:25:14 〽️ Prometheus exporter started at 127.0.0.1:9615 +2022-05-05 13:25:14 Listening for new connections on 0.0.0.0:9944. +2022-05-05 13:25:19 💤 Idle (0 peers), best: #0 (0x09fc…3a2b), finalized #0 (0x09fc…3a2b), ⬇ 0 ⬆ 0 +2022-05-05 13:25:20 Accepted a new tcp connection from 172.17.0.1:56636. +2022-05-05 13:25:23 🙌 Starting consensus session on top of parent 0x... +2022-05-05 13:25:23 🎁 Prepared block for proposing at 1 (3 ms) [hash: 0x...; parent_hash: 0x09fc…3a2b; extrinsics (1): [0xae1a…0701]] +2022-05-05 13:25:23 🔖 Pre-sealed block for proposal at 1. Hash now 0x..., previously 0x.... +``` + +Congratulations! +You are running your own KILT blockchain. 🎉 + +The blockchain exposes a RPC endpoint on port `9944`. +You can test that by calling an RPC endpoint using curl. + +```bash +curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "system_name", "params":[]}' http://127.0.0.1:9944/ +``` + +This should give you `{"jsonrpc":"2.0","result":"KILT Node","id":1}` as a response. + +The `--dev` parameter provides a pre-funded account which you can use as a faucet, and that has the following mnemonic: `receive clutch item involve chaos clutch furnace arrest claw isolate okay together`. + +You can create the account with the following SDK function: + +```ts +// Creates an ed25519 key by default which is required to access the funds. +const devFaucet = Crypto.makeKeypairFromUri(faucetSeed) +``` + +With the new `devFaucet`, you can transfer funds to other accounts and test all the KILT features that require tx fee payment. + +## Standalone vs. Parachain (Peregrine/Spiritnet) + +The standalone chain is close in functionality to Kilt parachains but there are a few fundamental differences between them. + + + +### Governance + +While governance is an important part of Kilt parachains, it's not used in the standalone version and the **Sudo** pallet replaces it. +None of the following pallets are part of the standalone chain, but they are all part of the parachain runtime: + +* Democracy +* Council +* TechnicalCommittee +* TechnicalMembership +* Treasury +* Scheduler + +### Staking + +Staking is part of the consensus protocol and is used to elect who is allowed to produce blocks. +Parachains need to have this election process as decentralized as possible. +On the other hand, for a standalone development chain, it's not necessary since all nodes are probably controlled by you or your organization. + +### Deployment Complexity + +Deploying a parachain is more complex than deploying a standalone chain. +For the standalone node, a single Docker command is enough. +In contrast, the task of spinning up a parachain is split into three steps. + +1. Setup a Relay Chain with 4 validators. +2. Start and connect your parachain node to the Relay Chain. +3. Register your parachain using the runtime WASM and the genesis state. + +Since these steps are not trivial to execute and take some time to do manually, you can use this [Docker-based setup script](https://github.com/KILTprotocol/local-parachain-setup) to automate the steps. + +### Transaction Encoding + +Before transactions are sent to the chain, they are encoded and signed. +The encoding depends on the runtime and can differ from chain to chain. +Even the same call in the same pallet can have a different encoding for different chains, for instance, the `vest`()` call of the `vesting` pallet: + +| Chain | Encoding of Vesting.vest() | +| ---------- | -------------------------- | +| Spiritnet | `0x2900` | +| Standalone | `0x2100` | diff --git a/versioned_docs/version-0.3/01_sdk/03_chain_setup/02_peregrine_setup.md b/versioned_docs/version-0.3/01_sdk/03_chain_setup/02_peregrine_setup.md new file mode 100644 index 000000000..175032ba8 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/03_chain_setup/02_peregrine_setup.md @@ -0,0 +1,22 @@ +--- +id: peregrine-chain-setup +title: Connect to Peregrine +--- + +Before connecting to the production Spiritnet, it is recommended to test applications using its canary network _Peregrine_. +In contrast to [running your own blockchain](./01_standalone_setup.md), you will neither have control over the blockchain, nor have any initial funds. + +In this section we will guide you through the process of receiving funds on Peregrine and connecting to one of the network nodes. +Additionally, we explain the difference between the Standalone and Parachain runtimes. + +## Receive Funds + +Since the native token of Peregrine, the _PILT_, does not have any economic value, you can request 100 PILT from the [Peregrine faucet](https://faucet.peregrine.kilt.io). + +## Connect to the Network + +Replace the WebSocket address of [your script](./index.md#set-up-your-project) or application with `wss://peregrine.kilt.io`. + +You can either use your own frontend or the [Polkadot JS Apps](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fperegrine.kilt.io%2Fparachain-public-ws#/explorer) to interact with the chain. +Moreover, you can use [Subscan](https://kilt-testnet.subscan.io/) as a chain explorer. +For a full list of deployments and services, take a look [here](../../02_chain/03_deployments.md). \ No newline at end of file diff --git a/versioned_docs/version-0.3/01_sdk/03_chain_setup/03_prod_chain_setup.md b/versioned_docs/version-0.3/01_sdk/03_chain_setup/03_prod_chain_setup.md new file mode 100644 index 000000000..121c34335 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/03_chain_setup/03_prod_chain_setup.md @@ -0,0 +1,25 @@ +--- +id: prod-chain-setup +title: Connect to Spiritnet +--- + +For production setups it is important to run your own full node. +Running your own full node has several advantages over relying on a public full node. + +The most important advantage is security. +You rely on the full node to provide you with correct data. +When using a public full node, you rely on a third party: there is no 100% guarantee that the information returned is correct. + +Another important aspect when hosting a full node is availability. +Public full nodes typically do not come with a Service Level Agreement (SLA) and might go down for maintenance or are simply too slow. +With your own full node infrastructure, you can ensure that there is always enough capacity to serve your needs and your customers. + +In our [blockchain section](../../02_chain/01_introduction.md), you can find a [tutorial on how to run your own full node](../../02_chain/04_fullnode.md). + +## Connect to the Network + +Replace the WebSocket address of [your script](./index.md#set-up-your-project) or application with `wss://kilt-rpc.dwellir.com`. + +You can either use your own frontend or the [Polkadot JS Apps](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkilt-rpc.dwellir.com/explorer) to interact with the chain. +Moreover, you can use [Subscan](https://spiritnet.subscan.io/) as a chain explorer. +For a full list of deployments and services, see [here](../../02_chain/03_deployments.md). diff --git a/versioned_docs/version-0.3/01_sdk/03_chain_setup/_category_.json b/versioned_docs/version-0.3/01_sdk/03_chain_setup/_category_.json new file mode 100644 index 000000000..88da89b23 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/03_chain_setup/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Chain Setup for Development", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/03_chain_setup/index.md b/versioned_docs/version-0.3/01_sdk/03_chain_setup/index.md new file mode 100644 index 000000000..84c89539e --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/03_chain_setup/index.md @@ -0,0 +1,24 @@ +--- +id: dev-chain-setup +title: Chain Setup for Development +--- + +If you want to develop solutions that integrate KILT, such as a dapp, a wallet, or a Web3 login, you will need a blockchain environment that can be used for development and testing without requiring you to buy actual KILT tokens. +For that purpose, you can either use the public KILT Peregrine testnet or run your own development blockchain. + +The **Peregrine** network is a parachain that is similar to Spiritnet (our mainnet) in functionality, but its coin, the PILT, doesn't hold any monetary value. +Any new features that we plan to add to our Spiritnet runtime will first undergo a testing period on Peregrine. +This gives developers like you the chance to test your software with any new features before they are available on Spiritnet. + +Nevertheless, there are a scenarios where a public network (that everyone else is also using) is not ideal. +For instance, if you need more funds than the faucet can provide, or if you need to reset the state of the blockchain at any time, you will need to setup your own little KILT blockchain. + +In this section, we will guide you through the process of +1. [Running your own KILT blockchain](./01_standalone_setup.md) +2. [Connecting to the Peregrine test network](./02_peregrine_setup.md) +3. [Connecting to the Spiritnet production network](./03_prod_chain_setup.md) + +## Set up your Project + +We expect you to already have a small project which can connect and potentially interact with a KILT blockchain given the WebSocket address of a KILT node. +If that is not the case, please take a look at our [Quickstart section](../01_quickstart.md#connecting-to-kilt-blockchain) which will provide you with all necessary means to create and run a basic script. diff --git a/versioned_docs/version-0.3/01_sdk/04_integrate/01_nodejs.md b/versioned_docs/version-0.3/01_sdk/04_integrate/01_nodejs.md new file mode 100644 index 000000000..57a4acf2e --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/04_integrate/01_nodejs.md @@ -0,0 +1,29 @@ +--- +id: howto-integrate-nodejs +title: NodeJS +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import QueryAccountName from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/linking/03_account_web3name_query.ts'; + +NodeJS is natively supported and doesn't require any additional setup. + +Have a look at these example `package.json` and `index.js` files for reference: + +```json +{ + "name": "kilt-sdk-node-test", + "type": "module", + "version": "1.0.0", + "main": "index.js", + "license": "MIT", + "dependencies": { + "@kiltprotocol/sdk-js": "0.35.0" + } +} +``` + + + {QueryAccountName} + diff --git a/versioned_docs/version-0.3/01_sdk/04_integrate/02_browser.md b/versioned_docs/version-0.3/01_sdk/04_integrate/02_browser.md new file mode 100644 index 000000000..b0a291ec4 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/04_integrate/02_browser.md @@ -0,0 +1,45 @@ +--- +id: howto-integrate-browser +title: Browser +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Our JavaScript SDK (`@kiltprotocol/sdk-js`) is ready to be used in a browser context. For rapid prototyping of simple web apps, we provide a code bundle of the entire SDK which you can embed in a site by adding the following script tag: + +```html + +``` + +The SDK's functions then become available via a new `kilt` property on the global `window` object. + +To get started with your first **React application** using KILT, we recommend using either the [KILT Distillery](./03_distillery.md) CLI tool for bootstrapping or a framework like [Vite](https://vitejs.dev) or [Next.js](https://nextjs.org) that takes away some of the complexity in building and testing a React application. You can find a broader selection of popular React-powered frameworks on the [React project's homepage](https://react.dev/learn/start-a-new-react-project). + +After completing the respective tool's recommended steps to initialize your project, simply add the SDK to your dependencies and you are ready to hack away! + +:::info + +You should of course familiarize yourself with the tool of your choice, but these commands have served us well in the past: + + + +```bash +yarn create vite my-kilt-app --template react-ts +cd my-kilt-app +yarn add @kiltprotocol/sdk-js +``` + + + + +```bash +yarn create next-app my-kilt-app +cd my-kilt-app +yarn add @kiltprotocol/sdk-js +``` + + + + +::: diff --git a/versioned_docs/version-0.3/01_sdk/04_integrate/03_distillery.md b/versioned_docs/version-0.3/01_sdk/04_integrate/03_distillery.md new file mode 100644 index 000000000..f61dd9fb2 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/04_integrate/03_distillery.md @@ -0,0 +1,12 @@ +--- +id: howto-integrate-distillery +title: KILT Distillery +--- + +Different types of projects can be bootstrapped using our [KILT distillery CLI](https://github.com/KILTprotocol/kilt-distillery-cli). + +Please read the README.md file for more information, but if you are impatient you can execute this command and follow the instructions: + +```bash +npx git+https://github.com/KILTprotocol/kilt-distillery-cli +``` diff --git a/versioned_docs/version-0.3/01_sdk/04_integrate/_category_.json b/versioned_docs/version-0.3/01_sdk/04_integrate/_category_.json new file mode 100644 index 000000000..6ca72770c --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/04_integrate/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Integrate the KILT SDK", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/01_sdk/04_integrate/index.md b/versioned_docs/version-0.3/01_sdk/04_integrate/index.md new file mode 100644 index 000000000..bac181a29 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/04_integrate/index.md @@ -0,0 +1,11 @@ +--- +id: howto-integrate-index +title: How to Integrate +--- + +Integrating with KILT is easy. +If your project needs to integrate KILT in a frontend and/or a backend application, we've got you covered! + +These pages are dedicated to helping you set up a [NodeJS application](./01_nodejs.md) or [web app](./02_browser.md). + +We also introduce the [KILT distillery CLI tool](./03_distillery.md) which helps you quickly spin up your first KILT-based project. diff --git a/versioned_docs/version-0.3/01_sdk/05_troubleshoot.md b/versioned_docs/version-0.3/01_sdk/05_troubleshoot.md new file mode 100644 index 000000000..369a3e616 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/05_troubleshoot.md @@ -0,0 +1,36 @@ +--- +id: troubleshoot-sdk +title: Troubleshoot +--- + +Solutions and workarounds for common or unresolved issues. + +## Webpack < 5 used to include polyfills + +``` +ERROR in ./node_modules/cbor/lib/commented.js 3:15-32 +Module not found: Error: Can't resolve 'stream' in 'node_modules/cbor/lib' + +BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default. +This is no longer the case. +Verify if you need this module and configure a polyfill for it. +``` + +### Solution + +The problem occurs because one of the dependecies you are using in your project (or used by a library you depend on) relies on NodeJS built-ins which are not available in a browser context. +You should aim to identify and replace these dependencies with browser-compatible alternatives. + +You might see the above error when using older versions of the KILT SDK with `create-react-app`. Make sure that you are using `@kiltprotocol/sdk-js` version 0.33.0 and above, which work in a browser context out-of-the-box. + +If the affected dependencies cannot be removed or replaced, you may need to look into setting up polyfills for the required NodeJS built-ins. + +## `redeclaration of import Buffer` + +``` +Uncaught SyntaxError: redeclaration of import Buffer +``` + +### Solution + +Your project might be using polyfills for the NodeJS built-in `Buffer`, which can cause conflicts with some polkadot-js libraries such as `@polkadot/react-identicon`. You can try upgrading the SDK and its dependencies to their latest versions. It's possible that upgrading will allow you to drop these polyfills from your configuration. diff --git a/versioned_docs/version-0.3/01_sdk/_category_.json b/versioned_docs/version-0.3/01_sdk/_category_.json new file mode 100644 index 000000000..13d35e4e8 --- /dev/null +++ b/versioned_docs/version-0.3/01_sdk/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "SDK", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/02_chain/01_introduction.md b/versioned_docs/version-0.3/02_chain/01_introduction.md new file mode 100644 index 000000000..20b625490 --- /dev/null +++ b/versioned_docs/version-0.3/02_chain/01_introduction.md @@ -0,0 +1,10 @@ +--- +id: introduction +title: Introduction +--- + +The section covers KILT chain specific topics. + +* Learn about the different [KILT pallets](./02_pallets/01_did.md) (still a WIP) +* Learn about the different [KILT deployments](./03_deployments.md) +* Learn how to run a [KILT full node](./04_fullnode.md) diff --git a/versioned_docs/version-0.3/02_chain/02_pallets/01_did.md b/versioned_docs/version-0.3/02_chain/02_pallets/01_did.md new file mode 100644 index 000000000..d0e8c3385 --- /dev/null +++ b/versioned_docs/version-0.3/02_chain/02_pallets/01_did.md @@ -0,0 +1,115 @@ +--- +id: pallet-did +title: DID pallet +--- + +In KILT a DID is a decentralized identifier that the user owns and controls. +It consists of a unique set of keys that can be used for different operations on the blockchain. +For an in-depth explanation see the [KILT DID spec](https://github.com/KILTprotocol/kilt-did-driver/blob/master/docs/did-spec/spec.md). + +A DID may be a "light" DID, which is not stored on-chain, or a "full" on-chain DID. +A light DID is issued by default, with the keys stored locally on your device. +By upgrading this to a full DID registered on the blockchain, all the keys associated with it can be retrieved from the KILT blockchain storage. + +A full DID can then be used to perform certain on-chain actions which include: + +* Writing CTypes to the chain +* Writing attestations to the chain +* Setting delegations +* Doing key rotations on the DID keys + +## Register a Full DID + +A full DID is needed if the user wants to become an Attester or wants to setup delegations. +A full DID also allows the user to embed a list of URLs, known as services, into the DID document so that they can be retrieved from the chain as part of the DID document. +To create a full DID the user first has to create some keys, and optionally some services: + +* one authentication key for signing extrinsics from your DID +* zero or more key agreement keys for encrypting messages that are sent to you +* (optional) one attestation key for signing attestations +* (optional) one delegation key for authorizing delegations +* (optional) service that point to external hostings for others to find + +After the relevant components have been created, they are ready to write the DID to the KILT blockchain. +The user then has to create the `did::create` extrinsic and sign it with any KILT account that has enough funding to pay both the transaction fees and the DID deposit. +The extrinsic consists of + +* The `DidCreationDetails` object containing keys, services and the account id of the submitter for the creation +* The `DidSignature` which is a signature using your authentication key over the scale encoded `DidCreationDetails` from above +* A regular signature authenticating the sender of the extrinsic + +The DID owner and the submitter can be two different parties. +This allows the creation of a DID without having to pay any fees or deposits. +Beware that this also means that the DID creator gives up some power over the DID: The submitter who pays the deposit will be able to delete the DID from the blockchain and claim back its deposit. +Once the `did::create` extrinsic is submitted and executed, the DID is written to the chain. + +## Use a Full DID + +Once the DID is successfully registered on chain, it can be used to perform certain on-chain actions that are not possible to do with a regular account. +This includes the handling of attestations and CTypes, setting up trust hierarchies through delegations, managing web3names and much more. + +Those actions need to be signed by the DID before they can be submitted to chain by any account that the DID owner specifies when signing. +We are naming those actions "DID-Calls". +To submit those there is a special extrinsic called `submit_did_call`. + +The process of doing any DID-Call is always the same: + +* Construct the actual call you want to execute including all arguments of that extrinsic. +* Wrap the call in a `DidAuthorizedCallOperation` together with the + * Senders DID to indicate who wants this operation to happen + * Senders DID tx_counter + 1 to prevent replay attacks + * Current block number to prevent the operation being submitted too far in the future + * Account of the submitter to allow the DID owner to specify who is allowed to submit +* Create a signature over the `DidAuthorizedCallOperation` by scale-encoding it and signing it using the appropriate key + * Most operations require the authentication key of the DID to be used + * Managing Attestations requires the attestation key + * Managing Delegations requires the delegation key +* Construct the `submit_did_call` extrinsic consisting of + * The `DidAuthorizedCallOperation` + * The DID signature +* Pass the call over to the submitter who can now sign and submit it to the chain + * The submitter will have to pay for all fees and deposits that result from the operation + * In general the submitter will have the power to delete all on-chain objects to reclaim their deposit +* The chain now checks that + * The submitter's signature is correct + * The submitter is the one specified in the `DidAuthorizedCallOperation` + * The DID signature is correct + * The tx_counter is valid (current tx_counter + 1) + * The blocknumber is not older than an hour (given 12s block time) +* After that the actual call gets dispatched with a special `DidOrigin` + * This allows the executer of the actual call to get the DID and the account of the submitter + +## Update a Full DID + +There is a set of extrinsics available to update a full DID. +These are: + +* `set_authentication_key` +* `set_delegation_key` +* `remove_delegation_key` +* `set_attestation_key` +* `remove_attestation_key` +* `add_key_agreement_key` +* `remove_key_agreement_key` +* `add_service_endpoint` +* `remove_service_endpoint` +* `delete` + +All of them have to be authenticated using the DID that is updated following the process described above. + +## What About the Deposit? + +When writing a DID to the chain the submitter of the extrinsic has to pay a deposit. +The base deposit is currently 2 KILT. +For additional used storage, for example by adding more services, more tokens are taken as deposit, depending on the amount of additional storage taken. +Freeing up storage reduces the deposit. +This is to incentivize deleting unused DIDs or keys to reduce the total storage of the chain. +The deposit is always bound to the account that submitted the extrinsic to create the DID, and not to the DID itself. +Consequently there are also two ways of reclaiming the deposit: + +1) The DID owner decides to delete the DID using the `did::delete` extrinsic. + This call needs to be authorized by the DID and can therefore be submitted by any account. + Despite the fact that this account can differ from the deposit owner, the deposit will always be reimbursed to the account that paid for it. +2) The deposit owner can decide to claim their deposit back using the `did::reclaim_deposit` extrinsic. + This will also cause the DID to be fully deleted but it doesn't require a signature from the DID. + Only the signature of the account that created the DID is needed for this. diff --git a/versioned_docs/version-0.3/02_chain/02_pallets/_category_.json b/versioned_docs/version-0.3/02_chain/02_pallets/_category_.json new file mode 100644 index 000000000..fd547d13d --- /dev/null +++ b/versioned_docs/version-0.3/02_chain/02_pallets/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "KILT Pallets", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/02_chain/03_deployments.md b/versioned_docs/version-0.3/02_chain/03_deployments.md new file mode 100644 index 000000000..37d93ea14 --- /dev/null +++ b/versioned_docs/version-0.3/02_chain/03_deployments.md @@ -0,0 +1,32 @@ +--- +id: deployments +title: Deployments and Services +--- + +KILT has two public deployments: a production one, called **Spiritnet**, and a test/dev one, called **Peregrine**. +To learn more about how to set up a node for either environment, please check our [fullnode set up guide](./04_fullnode.md). + +**Spiritnet** is the production blockchain, and has been live since September 2021. + +**Peregrine** is the public testnet, which can be used to build and test products that use the KILT blockchain, before switching to Spiritnet. + +| Service | Spiritnet | Peregrine | +|:----------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------:| +| Faucet | - | [Peregrine Faucet][pere-faucet] | +| Public Endpoints | [BOTLabs: wss://spiritnet.kilt.io][spirit-wss-kilt]
[OnFinality: wss://spiritnet.api.onfinality.io/public-ws][spirit-wss-onfinality]
[Dwellir: wss://kilt-rpc.dwellir.com][spirit-wss-dwellir] | [BOTLabs: wss://peregrine.kilt.io][pere-wss-kilt] | +| Wallet | [Sporran](https://www.sporran.org/) | [GitHub](https://github.com/BTE-Trusted-Entity/sporran-extension/releases) (manual loading into the browser) | +| Staking UI | Collators' performance (view only): [Stakekilt](https://stakekilt.com/)
Delegation staking platform: [Stakeboard](https://stakeboard.kilt.io) | - | +| Governance UI | [Polkassembly][spirit-polkassembly] | - | +| Chain Explorer | [Subscan](https://spiritnet.subscan.io) | [Subscan](https://kilt-testnet.subscan.io) | +| w3n Service | [w3n.id](https://w3n.id) | [test.w3n.id](https://test.w3n.id/) | +| Link Accounts | [linking.trusted-entity.io](https://linking.trusted-entity.io/) | [test.linking.trusted-entity.io](https://test.linking.trusted-entity.io/) | +| DIDsign | [didsign.io](https://didsign.io/) | [test.didsign.io](https://test.didsign.io/) | +| SocialKYC | [socialkyc.io](https://socialkyc.io/) | [test.socialkyc.io](https://test.socialkyc.io/) | + + +[spirit-polkassembly]: https://kilt.polkassembly.network +[spirit-wss-kilt]: https://polkadot.js.org/apps/?rpc=wss://spiritnet.kilt.io +[spirit-wss-onfinality]: https://polkadot.js.org/apps/?rpc=wss://spiritnet.api.onfinality.io/public-ws +[spirit-wss-dwellir]: https://polkadot.js.org/apps/?rpc=wss://kilt-rpc.dwellir.com +[pere-faucet]: https://faucet.peregrine.kilt.io +[pere-wss-kilt]: https://polkadot.js.org/apps/?rpc=wss://peregrine.kilt.io diff --git a/versioned_docs/version-0.3/02_chain/04_fullnode.md b/versioned_docs/version-0.3/02_chain/04_fullnode.md new file mode 100644 index 000000000..10a2237f7 --- /dev/null +++ b/versioned_docs/version-0.3/02_chain/04_fullnode.md @@ -0,0 +1,227 @@ +--- +id: fullnode-setup +title: Set Up a KILT Full Node +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +We will guide you through the process of setting up and connecting to a KILT full node. +In contrast [to a collator](/participate/staking/become_a_collator/setup-node), full nodes do not author blocks. +They act as a backend for websites and help to verify new blocks or validate extrinsics (e.g., coin transfers and other transactions) directly on the network without relying on a centralized infrastructure provider. + +## Setup + +There are currently two different runtimes (i.e., two different parachain environments) that a KILT full node can be part of: + +- **Spiritnet**: the official public network, which contains only stable and thoroughly-tested features +- **Peregrine**: the public test network whose runtime is as close to that of Spiritnet as possible. It can be used to test applications that use KILT before connecting them to the production Spiritnet chain, which requires tokens that have real monetary value + +Each runtime has its own benchmark measurements. + +:::info +The remainder of this guide will focus on the official **Spiritnet**. +Nevertheless, we recommend trying out the setup on our Peregrine testnet first. +Hence, at each step where it is applicable, we indicate what differs between the Peregrine and Spiritnet configuration for the full node to join either network. +::: + +### WASM Runtime Execution + +A KILT full node should use the `--execution=wasm` parameter for both the Relay Chain and parachain collation. +The alternative to WASM runtime execution is native runtime execution, which might be faster but can, in some cases, deviate from the WASM execution logic and result in a different state. +When this happens, the full node will crash and will stop synchronizing with the network. +Since the WASM runtime logic is part of the blockchain state itself and hence represents the single source of truth, all nodes should execute the WASM version of the runtime logic. + +### Specify the Right Chainspec + +The `--chain` parameter indicates which blockchain the KILT full node will join. +This parameter must be specified for both the parachain **and** the Relay Chain, since both chains are, as a matter of fact, separate blockchains. +The KILT parachain accepts an additional parameter to select the environment to use for the WASM runtime execution. +This can either be `peregrine` or `spiritnet`. + +Hence, to start a full node for the Spiritnet network, the parameter would be `--chain=spiritnet`. +Unfortunately, there is no hardcoded chain spec for the Peregrine network, so the full path of the chainspec file must be provided `--chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json`. +Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/master/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. + +### Specify the Blockchain Storage Path + +The `--base-path` parameter specifies where all the persistent files must be stored. +By default, the session keys will also be stored in the *base path*, but we recommend separating them from the other files. +This makes sure that the keyfiles are not accidentally lost or published when the blockchain database is either backed up or restored. +You can configure where to store the session keys using the `--keystore-path` option. +Since the collator will collate only for the parachain, there is no need to add this to the Relay Chain part of the command. + +## Join the Network + + + + + +### Build the Full Node + +In order to build the KILT full node executable, you need to have [rustup and Rust installed](https://www.rust-lang.org/tools/install). +After cloning the repository, you can build the executable by running the `cargo build` command below from the root directory. + +```bash +# Clone the repository +git clone https://github.com/KILTprotocol/kilt-node.git +# Check out master branch +git checkout master +# Build the executable from source enabling all the optimizations with --release. +cargo build --release -p kilt-parachain +``` + +:::info +You must not use the default `develop` branch to build the executable. +Instead, the [latest release](https://github.com/KILTprotocol/kilt-node/releases) from `master` should be used. +::: + +The compiled executable can be found in `./target/release/kilt-parachain` after the build process completes successfully. + +### Run an Archive Node + +To run an Archive full node, add the option `--pruning archive` to the command. + + + + + +```bash +./target/release/kilt-parachain \ + --chain=spiritnet \ + --runtime=spiritnet \ + --rpc-port=9944 \ + --rpc-cors=all \ + --rpc-external \ + --name="name of full node" \ + --execution=wasm \ + --pruning archive \ + -- \ + --chain=polkadot \ + --execution=wasm +``` + + + + +```bash +./target/release/kilt-parachain \ + --chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json \ + --runtime=peregrine \ + --rpc-port=9944 \ + --rpc-cors=all \ + --rpc-external \ + --name="name of full node" \ + --execution=wasm \ + --pruning archive \ + -- \ + --chain=/node/dev-specs/kilt-parachain/peregrine-relay.json \ + --execution=wasm +``` + + + + + + + +### Run an Archive Node + +The full node can also be started as a Docker container. +To expose the WebSockets ensure that the `--rpc-external` flags is set. + +To run an Archive full node add the option `--pruning archive` to the command. + +First, you can fetch the latest pre-built image: + +```bash +docker pull kiltprotocol/kilt-node:latest +``` + +Once you have the image, you can spin up the container. +Make sure to choose whether you want to start a full node for Peregrine or Spiritnet by selecting the correct runtime and chain. + + + + + +```bash +docker run -v kilt-node-data:/data kiltprotocol/kilt-node:latest \ + --base-path=/data/para \ + --chain=spiritnet \ + --runtime=spiritnet \ + --rpc-port=9944 \ + --rpc-cors=all \ + --rpc-external \ + --name="name of full node" \ + --execution=wasm \ + --pruning archive \ + -- \ + --base-path=/data/relay \ + --chain=polkadot \ + --execution=wasm +``` + + + + +```bash +docker run -v kilt-node-data:/data kiltprotocol/kilt-node:latest \ + --base-path=/data/para \ + --chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json \ + --runtime=peregrine \ + --rpc-port=9944 \ + --rpc-cors=all \ + --rpc-external \ + --name="name of full node" \ + --execution=wasm \ + --pruning archive \ + -- \ + --base-path=/data/relay \ + --chain=/node/dev-specs/kilt-parachain/peregrine-relay.json \ + --execution=wasm +``` + + + + + + + +## Sync the Blockchain State + +Once started, the full node needs to fully sync up with both the parachain and the Relay Chain states. +Depending on the size of both blockchain states and the node hardware specs, it may take from a number of hours to a few days for the node to fully synchronize. +More details can be found in the [Polkadot network documentation](https://wiki.polkadot.network/docs/maintain-guides-how-to-validate-polkadot#synchronize-chain-data). + +:::note Example of node sync + +```Example of node sync +2021-06-17 02:34:34 🔍 Discovered new external address for our node: /ip4/100.102.231.64/tcp/30333/ws/p2p/12D3KooWLE7ivpuXJQpFVP4fuuutAqEsk8nrNEpuR3tddqnXgLPB +2021-06-17 02:34:36 ⚙️ Syncing 409.2 bps, target=#8062689 (5 peers), best: #3477 (0x63ad…e046), finalized #3072 (0x0e4c…f587), ⬇ 153.2kiB/s ⬆ 12.9kiB/s +2021-06-17 02:34:37 🔍 Discovered new external address for our node: /ip4/100.111.175.0/tcp/30333/ws/p2p/12D3KooWLE7ivpuXJQpFVP4fuuutAqEsk8nrNEpuR3tddqnXgLPB +2021-06-17 02:34:38 🔍 Discovered new external address for our node: /ip4/100.100.176.0/tcp/30333/ws/p2p/12D3KooWLE7ivpuXJQpFVP4fuuutAqEsk8nrNEpuR3tddqnXgLPB +2021-06-17 02:34:41 ⚙️ Syncing 386.2 bps, target=#8062690 (7 peers), best: #5409 (0x1d76…8c3d), finalized #5121 (0x8ad1…b6dc), ⬇ 96.1kiB/s ⬆ 10.9kiB/s +2021-06-17 02:34:46 ⚙️ Syncing 394.8 bps, target=#8062691 (11 peers), best: #7383 (0x0689…6f1e), finalized #7168 (0x72a9…8d8c), ⬇ 352.9kiB/s ⬆ 5.1kiB/s +2021-06-17 02:34:51 ⚙️ Syncing 347.0 bps, target=#8062692 (12 peers), best: #9118 (0x66fc…cce3), finalized #8704 (0x14c9…705e), ⬇ 62.7kiB/s ⬆ 1.7kiB/s +``` + +::: diff --git a/versioned_docs/version-0.3/02_chain/_category_.json b/versioned_docs/version-0.3/02_chain/_category_.json new file mode 100644 index 000000000..1b41abda0 --- /dev/null +++ b/versioned_docs/version-0.3/02_chain/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Chain", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/03_workshop/01_welcome.md b/versioned_docs/version-0.3/03_workshop/01_welcome.md new file mode 100644 index 000000000..6ed35f2f3 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/01_welcome.md @@ -0,0 +1,38 @@ +--- +id: welcome +title: 👋🏻 Welcome +--- + + + + +SDK version **0.35.0**. + +:::info What you can expect to learn + +📦 **Topics**: [KILT SDK](https://github.com/KILTprotocol/sdk-js) essentials, basic credential workflow. +This includes creating a CType and a claim, attesting a claim, and finally verifying the credential. + +⏳ **Duration**: 15-45 minutes. + +🤓 **Prerequisites**: + +- Basic JavaScript or TypeScript knowledge. +- [Node.js](https://nodejs.org/) installed. Any stable LTS version >= 16.0. + +❓ **Questions?** Join our [developer community channel](https://discord.gg/hX4pc8rdHS)! + +::: + +## Welcome, curious mind! + +In this tutorial, you will: + +✔ Get familiar with the essential concepts in KILT: accounts, DIDs, CTypes, claims, credentials, and more. + +✔ Use the KILT SDK to implement the basic flow of a KILT claim, from creation until verification. +You'll create a claim as a Claimer, attest it as an Attester and verify it as a Verifier. + +✔ Use the KILT SDK to write onto and read from the KILT blockchain. + +Ready? Let's go! \ No newline at end of file diff --git a/versioned_docs/version-0.3/03_workshop/02_setup.md b/versioned_docs/version-0.3/03_workshop/02_setup.md new file mode 100644 index 000000000..c63d7c19e --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/02_setup.md @@ -0,0 +1,108 @@ +--- +id: setup +title: 🎒 Setup +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Project setup + +Create a new project in a fresh directory and navigate into it by running `mkdir kilt-rocks && cd kilt-rocks`. + + + +The dependencies needed are the following: + +- [KILT SDK-JS](https://github.com/KILTprotocol/sdk-js#readme) - for KILT functionality +- [dotenv](https://github.com/motdotla/dotenv#readme) - to load environment variables +- If you use Typescript and not JavaScript [ts-node](https://www.npmjs.com/package/ts-node) and [Typescript](https://www.typescriptlang.org/) - to execute TS code + + + + + Initialize the project and install dependencies. + + ```bash npm2yarn + npm init -y + npm install @kiltprotocol/sdk-js dotenv ts-node typescript + ``` + + + + + Initialize the project and install dependencies. + + ```bash npm2yarn + npm init -y + npm install @kiltprotocol/sdk-js dotenv + ``` + + + + +## Project Folder + + + + + Create the following remaining files and folders to end up with the folder structure below: + + ``` + └─ kilt-rocks/ # project + ├─ attester/ # all attester code + ├─ claimer/ # all claimer code + ├─ verify.ts # all verifier code + └─ .env # environment variables + ``` + ``` + mkdir attester claimer && touch verify.ts .env + ``` + + + + + + Create the following remaining files and folders to end up with the folder structure below: + + ``` + └─ kilt-rocks/ # project + ├─ attester/ # all attester code + ├─ claimer/ # all claimer code + ├─ verify.js # all verifier code + └─ .env # environment variables + ``` + ``` + mkdir attester claimer && touch verify.js .env + ``` + + + + +## PILT Tokens + +This workshop interacts with the Peregrine test blockchain, which requires you to pay for each transaction with Peregrine Kilt (PILT) tokens. + +But don't worry. PILT tokens have no value, and you can request them from the [faucet](https://faucet.peregrine.kilt.io). + +## Blockchain Connection + +Before using any SDK functionality, you must initialize and configure the Kilt SDK. + +As this workshop uses the [Peregrine Testnet](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fperegrine.kilt.io%2Fparachain-public-ws%2F#/explorer) you use its address whenever using the SDK to interact with the Kilt blockchain. + +You do this by calling the following function: + +```JavaScript +await Kilt.connect({address}) +``` + +Where `address` is the address of the full node you want to connect to, which for this workshop, is `wss://peregrine.kilt.io`. + +For convenience, add the address to the `.env` file. + +```env title=".env" +WSS_ADDRESS=wss://peregrine.kilt.io +``` + +That's it for the basic setup - You're good to go! \ No newline at end of file diff --git a/docs/develop/03_workshop/03_overview.md b/versioned_docs/version-0.3/03_workshop/03_overview.md similarity index 100% rename from docs/develop/03_workshop/03_overview.md rename to versioned_docs/version-0.3/03_workshop/03_overview.md diff --git a/versioned_docs/version-0.3/03_workshop/04_attester/01_account.md b/versioned_docs/version-0.3/03_workshop/04_attester/01_account.md new file mode 100644 index 000000000..e2710f623 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/04_attester/01_account.md @@ -0,0 +1,111 @@ +--- +id: account +title: Account +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import GenerateAccount from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/attester/generateAccount.ts'; + +With the [project structure setup](./) in the last step, you can create your Attester account. + +With KILT, an account is an object that interacts with the blockchain. + +:::info KILT Account + +A KILT account is a set of cryptographic elements: + +- The address, generated from the public key, is the entity's unique and public on-chain identifier, used to pay fees and deposits. +- A signing key pair to write transactions on-chain + +::: + +To create an account, you need a mnemonic. + +:::info Mnemonic + +In cryptography, a mnemonic consists of a series of 12 or 24 random words. + +For example, `waste frown beach save hidden bar inmate oil mind member junk famous` is a mnemonic. + +You use a mnemonic to generate signing key pairs. +What's great about a mnemonic is that it's **human-readable**, and a person could memorize it to later re-generate their key pairs and address. +A mnemonic is critical for security, so it's crucial to keep it safe! + +::: + +## Create the Account + +To generate an account, use the `addFromMnemonic()` function on the [`KiltKeyringPair`](https://kiltprotocol.github.io/sdk-js/interfaces/types_src.KiltKeyringPair.html) interface of the SDK. +The function uses the underlying polkadot `mnemonicGenerate()` function to generate a 12-word mnemonic. + +:::info polkadot.js + +The KILT SDK is built on top of the [polkadot.js](https://polkadot.js.org/) library, so this workshop uses several functions from the library. + +The library provides tools to interact with the KILT blockchain and other Substrate-based blockchains. + +In addition, the polkadot.js library offers cryptographic primitives and a serialization framework to encode/decode data sent to and received from the blockchain. +Read the [API documentation](https://polkadot.js.org/docs/) to learn more about the functions available. + +::: + +Add the following code to the `generateAccount` file. + + + {GenerateAccount} + + +The `generateAccount` method returns an object with the following two properties: + +- A key `account` with the type `Kilt.KiltKeyringPair`. +- A key `mnemonic` with the type `string`. + +Generating these values takes two steps: + +1. Create the `mnemonic` value using the `mnemonicGenerate()` method from the `Utils.Crypto` package. +2. The `account` value first needs a `keyring` value defined, which is a data structure for defining the key pair type. This example uses `ed25519`, but `sr25519` or `ecdsa` are also valid. + +The function then returns the value using the `makeKeypairFromUri()` method to create a key pair for the address using the given mnemonic. + +The rest of the code runs the `generateAccount` function and logs the results to the console. + +## Run code + +Run the code above to receive your Attester `
` and ``. + + + + +```bash +yarn ts-node ./attester/generateAccount.ts +``` + + + + +```bash +node ./attester/generateAccount.js +``` + + + + +The output provides you with an `ATTESTER_ACCOUNT_MNEMONIC` and `ATTESTER_ACCOUNT_ADDRESS`. +Save both values in your `.env` file, which should look similar to the below. + +```env title=".env" +WSS_ADDRESS=wss://peregrine.kilt.io + +ATTESTER_ACCOUNT_MNEMONIC="warrior icon use cry..." +ATTESTER_ACCOUNT_ADDRESS="4ohMvUHsyeDhMVZF..." +``` + +:::warning Get PILT coins! + +You now have a blockchain account to use to pay fees and deposits. +If you haven't already requested PILT, go to the [faucet](https://faucet.peregrine.kilt.io) and request tokens for your `
`. + +::: diff --git a/versioned_docs/version-0.3/03_workshop/04_attester/02_did.md b/versioned_docs/version-0.3/03_workshop/04_attester/02_did.md new file mode 100644 index 000000000..1dab87d08 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/04_attester/02_did.md @@ -0,0 +1,139 @@ +--- +id: did +title: DID +--- + +import CodeBlock from '@theme/CodeBlock'; +import TsJsBlock from '@site/src/components/TsJsBlock'; +import SnippetBlock from '@site/src/components/SnippetBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import GenerateKeypairs from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/attester/generateKeypairs.ts'; +import GenerateDid from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/attester/generateDid.ts'; + +The next step is to generate a KILT decentralized identifier (DID) using the account you created for the Attester in [the previous step](./01_account.md). + +A DID may represent any entity, such as a person, an organization, or a machine. + +A DID is a string uniquely identifying each KILT user. +You can store information about a DID on the KILT chain, which is useful for different use cases. + +One use case is messaging. +You could store a public encryption key and a service on chain, and a user can query both using a DID. +Other users can now encrypt messages using your public encryption key and send a message to your service. + +## Light and full DIDs + +Kilt supports two DID types: **light** and **full**. + +There are differences between the two types, but the most crucial is that you can use a light DID offline, but a full DID needs access to the blockchain to work. +Read the [DID documentation](../../01_sdk/02_cookbook/01_dids/01_light_did_creation.md) to learn more about the difference between the light and full types. + +:::info KILT DID + +A DID supports four different key types: + +- An _authentication key pair_, used to sign claims and present authenticated credentials +- A _key-agreement key pair_, used to encrypt/decrypt messages +- An _assertion-method key pair_, used to write CTypes and attestations on chain +- A _capability-delegation key pair_, used to write delegations on chain + +You can replace keys over time, e.g., if a key becomes compromised. + +::: + +## What's the difference between a DID and an account? + +A DID and an account sound quite similar, but there are some differences: + +- You record both to chain +- You can have a DID without an account +- You can have an account without a DID +- Only an account can pay deposits and fees and attest claims +- DIDs don't hold any coins + +In summary, you register a DID on the blockchain by an account submitting the DID creation transaction and paying the fees. + +## Create a DID + +As an Attester needs to interact with the chain, you must create a full DID. + +### Write DID to chain + +The KILT SDK provides multiple methods to create DIDs, this workshop highlights the `createFromAccount` method, that creates a DID from any pre-existing substrate-compatible account. + + + + +:::info Bring your own account + +This workshop assumes you followed the [create account step](./01_account.md), but if you have a pre-existing account, you can use that instead. + +::: + +Create and submit the extrinsic (aka transaction) that registers the DID. + + + {GenerateDid} + + +The `publicKeyToChain` helper method returns a public key of the correct type. + +The `txs` array holds the two transactions containing the extrinsics needed to submit to the chain for the Attester's DID creation. + +The `createFromAccount` method takes the authenticated key of the account to attach the DID to, and the `setAttestationKey` method takes the same parameter to set the attestation key the DID needs and uses. + +An Attester account needs to have an attestation key to write CTypes and attestations on chain. Use the `setAttestationKey` method to set this. For this example transaction, the Attester account uses the `dispatchAs` proxy method to assign the attestation key to the same account. However, you can also use this method to assign the attestation key to another account. + +The `signAndSubmitTx` method then takes those transactions and submits them as a batch to the chain. + +## Run the code + +Now run the code with: + + + + + ```bash + yarn ts-node ./attester/generateDid.ts + ``` + + + + + ```bash + node ./attester/generateDid.js + ``` + + + + +Once you have run the script, the output should provide you with the `ATTESTER_DID_URI`. + +The output should look like the following, but not identical since the code creates the DIDs from your account: + +``` +ATTESTER_DID_URI="did:kilt:4ohMvUHsyeD…" +``` + +Save the values in the `.env` file, which should now look like the following: + +```env title=".env" +WSS_ADDRESS=wss://peregrine.kilt.io + +ATTESTER_ACCOUNT_MNEMONIC="warrior icon use cry... +ATTESTER_ACCOUNT_ADDRESS=4ohMvUHsyeDhMVZF... +ATTESTER_DID_URI="did:kilt:4ohMvUHsyeD..." +``` + +Well done - You've generated a full DID! The next step is to create a CType! + +## Generate Keys + +Add the following code to the `generateKeypairs` file. + + + {GenerateKeypairs} + + diff --git a/versioned_docs/version-0.3/03_workshop/04_attester/03_ctype.md b/versioned_docs/version-0.3/03_workshop/04_attester/03_ctype.md new file mode 100644 index 000000000..55eac6f69 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/04_attester/03_ctype.md @@ -0,0 +1,120 @@ +--- +id: ctype +title: CType +--- + +import CodeBlock from '@theme/CodeBlock'; +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import CtypeSchema from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/attester/ctypeSchema.ts'; +import GenerateCtype from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/attester/generateCtype.ts'; + + +import Ctype from '@site/scripts/out/ctype.json.raw!=!raw-loader!@site/scripts/out/ctype.json'; + +A claim type (CType) is a KILT-specific term, but the concept is simple: +A CType is a JSON schema that defines the structure of a claim, and you can think of it as the data model for your claim. + +:::info CType + +A CType ensures that a credential contains all required attributes, e.g., a driver's license has to contain a name, date of birth, and the vehicle types that the claimer can drive. +The CType is important since a Verifier requests credentials for a specific CType. +For example, the traffic police want to see your driver's license, not your gym membership. + +To learn more about CTypes, read the [in-depth CType documentation](/concepts/credentials/ctypes). +You can also [read through existing CTypes in the CType-index](https://github.com/KILTprotocol/ctype-index). +::: + +Before the Attester can attest credentials, they must decide which CType they support. +For example, a traffic authority only issues driver's licenses (A CType for driver's license), not a university diploma. + +Since CTypes enable interoperability between Attesters, using existing CTypes rather than creating new ones is highly recommended. +However, this workshop creates a new CType to show the process. + +Creating CTypes requires an account and a full DID. +Make sure your account holds KILT tokens so that you can pay the fees for creating a CType. + +For example, a basic CType for a driver's license could look like this: + + + {Ctype} + + +The CType has the following attributes: + +| Key | Value | +| -------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `$id` | The KILT id of this CType. It's the most important property as it represents the **digital footprint** of the CType. | +| `$schema` | A reference to the meta-schema describing what a CType may look like. There are two versions. | +| `title` | The title of the CType. | +| `properties` | The properties that a claim conforming to this CType may have. | +| `type` | Type is an object for all CTypes. | +| `additionalProperties` | The default is false. This restricts unwanted properties in a claim. | + +A CType is stored on the KILT blockchain. + +In a real-world situation, a user would retrieve an existing CType from the chain or a CType registry. +For example, via a Credential Registry's REST API. + +In this tutorial, the Attester creates and attempts to store a CType on the KILT test blockchain. + +## Create CType + +Copy the following to define a `CType` with a given schema: + + + {CtypeSchema} + + +:::warning + +As many people follow this workshop, using the CType schema defined above will result in a duplicate error when you run the code later. +To avoid this, change the value of `fromProperties` to something unique, such as adding your name to the "Drivers License" string. + +::: + +## Get CType + +Copy the following to create a `CType` on the chain: + + + {GenerateCtype} + + +The `ensureStoredCType` function takes the Attester's account, DID, and a callback to sign the function and checks if the CType is already on chain. +It uses the `verifyStored` method to pass the CType to the KILT blockchain and make the check. +If it does not exist, it stores it on chain, using the `toChain` method to encode the CType into a unique hash and the `add` method to create a new CType from the given unique hash and associate it with the Attester. +The function then uses the `authorizeTx` to authorize the transaction and `signAndSubmitTx` to sign and submit the transaction containing the new CType. + +:::warning + +Remember, an account must have the required amount of tokens to pay the transaction fee and deposit. + +::: + +## Run + + + + + Run the `attester/generateCtype.ts` file. + + ```bash + yarn ts-node attester/generateCtype.ts + ``` + + + + + Run the `attester/generateCtype.js` file. + + ```bash + node attester/generateCtype.js + ``` + + + + +Before you can attest Credentials, you need a Claimer to request it diff --git a/versioned_docs/version-0.3/03_workshop/04_attester/_category_.json b/versioned_docs/version-0.3/03_workshop/04_attester/_category_.json new file mode 100644 index 000000000..6c31a6f8e --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/04_attester/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "🏢 Attester", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/03_workshop/04_attester/index.md b/versioned_docs/version-0.3/03_workshop/04_attester/index.md new file mode 100644 index 000000000..5da9f6d70 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/04_attester/index.md @@ -0,0 +1,59 @@ +--- +id: attester +title: 🏢 Attester +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This section of the workshop covers creating the Attester code. The steps are the following: + +1. [Create an account](./01_account.md) to pay for all transactions and storage deposits. +2. [Create a DID](./02_did.md), which is the identity used to create attestations. + + While you can always switch the KILT account and pay deposits and fees with any account you like, your DID stays the same and is the way Claimers identify and trust you. + +1. Before you can attest claims, [you need a CType](./03_ctype.md) that describes and gives context to what you attest. +2. Once you have a way to pay fees and deposits, have an identity, and a CType, [you can create attestations](../06_attestation.md). + +## Folder Structure + +Create the following files in the `attester` folder. +These folders mimic an Attester service. + + + + + ```bash + └─ kilt-rocks/ # project + └─ attester/ # all attester code + ├─ attestCredential.ts # issues attestations + ├─ ctypeSchema.ts # create a local CType definition + ├─ generateAccount.ts # functions for setting up and loading the attester's account + ├─ generateCtype.ts # register the CType on chain + ├─ generateDid.ts # registers the attester's on-chain DID + └─ generateKeypairs.ts # setup the keys for the attester's DID + ``` + ```bash + cd attester && touch attestCredential.ts ctypeSchema.ts generateAccount.ts generateCtype.ts generateDid.ts generateKeypairs.ts && cd .. + ``` + + + + ```bash + └─ kilt-rocks/ # project + └─ attester/ # all attester code + ├─ attestCredential.js # issues attestations + ├─ ctypeSchema.js # create a local CType definition + ├─ generateAccount.js # functions for setting up and loading the attester's account + ├─ generateCtype.js # register the CType on chain + ├─ generateDid.js # registers the attester's on-chain DID + └─ generateKeypairs.js # setup the keys for the attester's DID + ``` + + ```bash + cd attester && touch attestCredential.js ctypeSchema.js generateAccount.js generateCtype.js generateDid.js generateKeypairs.js && cd .. + ``` + + + diff --git a/versioned_docs/version-0.3/03_workshop/05_claimer/01_did.md b/versioned_docs/version-0.3/03_workshop/05_claimer/01_did.md new file mode 100644 index 000000000..202548c17 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/05_claimer/01_did.md @@ -0,0 +1,75 @@ +--- +id: did +title: DID +--- + +import CodeBlock from '@theme/CodeBlock'; +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import GenerateKeypairs from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/claimer/generateKeypairs.ts'; +import GenerateLightDid from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/claimer/generateLightDid.ts'; + +This section covers creating a light DID using the account you created for the Claimer. + +Since a light DID is not registered on the blockchain, you don't need funds to create one. + +:::info + +Remember, light DIDs can do the following: + +- Sign attestation requests and presentation with the authentication keys +- Encrypt messages with the encryption keys + +Read the [DID documentation](../../01_sdk/02_cookbook/01_dids/01_light_did_creation.md) to learn more about DIDs and the difference between their light and full versions. + +::: + +## Generate Keys + +Like the Attester, the Claimer must also set up the DID keys. + + + {GenerateKeypairs} + + +The code above is similar to the `generateKeyAgreement` function used in the Attester section but simpler, as the Claimer only needs an authentication key and an encryption key. + +Both the keys are derived from the same seed, but they could also have two different seeds. + +## Generate Light DID + +With the `keypairs` generated, you can create the light DID. +Because it's off-chain you can create the DID object every time, but you still need to save the mnemonic to the `.env` file with a different variable name. + + + {GenerateLightDid} + + +The Claimer doesn't have an `account`, as the Claimer doesn't need to hold funds. + +The `generateKeypairs` function takes the `mnemonic` value and generates the `authentication` and `keyAgreement` keys. + +The `createLightDidDocument` method takes these two values and generates the light DID. + +## Run + + + + + ```bash + yarn ts-node ./claimer/generateLightDid.ts + ``` + + + + + ```bash + node ./claimer/generateLightDid.js + ``` + + + + +Well done - You successfully generated a light DID! diff --git a/versioned_docs/version-0.3/03_workshop/05_claimer/02_request.md b/versioned_docs/version-0.3/03_workshop/05_claimer/02_request.md new file mode 100644 index 000000000..8dbc992ff --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/05_claimer/02_request.md @@ -0,0 +1,73 @@ +--- +id: request +title: Request an Attestation +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import CreateClaim from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/claimer/createClaim.ts'; +import GenerateCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/claimer/generateCredential.ts'; + +This section covers creating a `Claim` and a `Credential`. + +KILT is a premissionless system. +Anyone or anything can claim something and attest to it. +But an attested credential only has value if the Verifier of the credential _trusts_ the Attester of the credential. + + +## Create Credential + +Use the previously created `light DID`, `ctype`, and Claimer provided `content` to generate the `Claim` object. + +A claim consists of attributes that we claim to be true about us. + + + {CreateClaim} + + +The `fromCTypeAndClaimContents` function takes the `lightDid`, `ctype`, and `content` values and generates a `Claim` object. + +## Receive attestation for claim + +Since you want to receive an attestation for those claims, build a `Credential` in the `generateCredential` function below. + +The credential contains all necessary information so the Attester can attest it. + + + {GenerateCredential} + + + +The `main` function takes the Claimer mnemonic and generates the light DID following the steps outlined in the [DID section](./01_did.md). +It then calls the `generateCredential` function using the supplied claim attributes. +It then uses the `createClaim` method from the previous step to create the `Claim` object and the `Kilt.Credential.fromClaim` method takes the claim and returns the `Credential` object. + +When Attesters issue `Attestations`, they are written to the chain, which requires a deposit. +Each new `Credential` is unique. +During testing, you can store and reuse credentials into `./claimer/_credential.json` to avoid multiple attestations. + +You can share this credential with others following the workshop to see how they get denied from fraudulent senders. + +## Run + + + + + ```bash + yarn ts-node claimer/generateCredential.ts + ``` + + + + + ```bash + node claimer/generateCredential.js + ``` + + + + +OK, you've made a claim as a Claimer and created a credential from it. +The next step is to finish the Attester and get the credential attested! diff --git a/versioned_docs/version-0.3/03_workshop/05_claimer/_category_.json b/versioned_docs/version-0.3/03_workshop/05_claimer/_category_.json new file mode 100644 index 000000000..5656d275e --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/05_claimer/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "👤 Claimer", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/03_workshop/05_claimer/index.md b/versioned_docs/version-0.3/03_workshop/05_claimer/index.md new file mode 100644 index 000000000..0c9431ac7 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/05_claimer/index.md @@ -0,0 +1,76 @@ +--- +id: claimer +title: 👤 Claimer +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This section covers the steps undertaken by the Claimer. + +Here's an overview: + +1. [Create a DID](./01_did.md), which is the identity used to interact with Attesters and Verifiers. +2. Create a claim, request an attestation, and generate a credential using the attestation for our claim. +3. Present the claim to a Verifier. + +## What is a Claimer? + +Claimers are a crucial part of the Self-Sovereign Identity system. + +A Claimer is an individual or institution that makes a claim or statement about their identity or abilities. +They can use their identity credentials to prove these claims, and third-party institutions verify them. + +Anyone can be a Claimer. +All you need to do is complete a CType and create a claim. +Then, you can send these claims to Attesters for verification. + +They store their identity credentials in their digital wallets, so they decide which information to provide to which service. +They have full control over their data and decide which data to share, where, and how. + +You don't need to create a DID on the chain, meaning you are entirely independent! + +Claimers can use their accounts without needing a chain connection. + + +## Folder Structure + +Create the following files in the Claimer folder. +This folders serves to mimic a Claimer's perspective. + + + + + ```bash + └─ kilt-rocks/ # project + └─ claimer/ # all claimer code + ├─ createClaim.ts # creates a claim + ├─ createPresentation.ts # creates a presentation for verifiers + ├─ generateCredential.ts # create the credential object that is sent to the attester for attestation + ├─ generateKeypairs.ts # create keypairs for the light DID + └─ generateLightDid.ts # create the light DID for the claimer + ``` + + ```bash + cd claimer && touch createClaim.ts createPresentation.ts generateCredential.ts generateKeypairs.ts generateLightDid.ts && cd .. + ``` + + + + + ```bash + └─ kilt-rocks/ # project + └─ claimer/ # all claimer code + ├─ createClaim.js # creates a claim + ├─ createPresentation.js # creates a presentation for verifiers + ├─ generateCredential.js # create the credential object that is sent to the attester for attestation + ├─ generateKeypairs.js # create keypairs for the light DID + └─ generateLightDid.js # create the light DID for the claimer + ``` + + ```bash + cd claimer && touch createClaim.js createPresentation.js generateCredential.js generateKeypairs.js generateLightDid.js && cd .. + ``` + + + diff --git a/versioned_docs/version-0.3/03_workshop/06_attestation.md b/versioned_docs/version-0.3/03_workshop/06_attestation.md new file mode 100644 index 000000000..a433f6110 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/06_attestation.md @@ -0,0 +1,55 @@ +--- +id: attestation +title: 🧾 Attestation +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import AttestCredential from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/attester/attestCredential.ts'; + +This section covers how the Attester receives and processes a `Credential` and how you can: + +- Attest or deny it +- Store the attestation information on the chain + +## Attest a Credential + + + {AttestCredential} + + +The `attestCredential` function loads the account and DID of the Attester and issues an attestation for the credential received from the Claimer. +The credential is valid from the time an Attester attests it on chain until the time it is revoked. + +In the `attestingFlow` function, the Claimer generates the demo credential and sends it to the Attester. +The Attester checks the attributes and either attests or denies the attestation if the attributes are invalid. +Once the attestation is written on the chain, the Attester can share all or part of the attested credentials with verifiers. + +## Run + +Run the code from the command line: + + + + + ```bash + yarn ts-node attester/attestCredential.ts + ``` + + + + + ```bash + node attester/attestCredential.js + ``` + + + + +## Summary + +Your job as an Attester is complete. You've attested a credential and written the attestation hash onto the chain. + +Let's move on to set up the Verifier! diff --git a/versioned_docs/version-0.3/03_workshop/07_verification.md b/versioned_docs/version-0.3/03_workshop/07_verification.md new file mode 100644 index 000000000..e0a154733 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/07_verification.md @@ -0,0 +1,72 @@ +--- +id: verification +title: 🤝 Verification +--- + +import CodeBlock from '@theme/CodeBlock'; +import TsJsBlock from '@site/src/components/TsJsBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import Verify from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/verify.ts'; +import CreatePresentation from '!!raw-loader!@site/code_examples/sdk_examples/src/workshop/claimer/createPresentation.ts'; + +In this section, you play the role of a Verifier that does the following: + +1. Take a `Presentation` object supplied by a Claimer +2. Verify that its data is correct +3. Verify that the attestation is valid, i.e., its hash exists on-chain and the attestation has not been revoked +4. Verify that the Claimer sending the `Credential` owns it + +:::info Presentation object + +The Claimer uses a Credential to create the `Presentation` object. +Unlike the credential, a `Presentation` can hide some attributes that are not required by the Verifier and can contain a claimer-signed challenge. +A `Presentation` also contains a proof that the Claimer owns the credential. + +::: + +## Create Presentation + +A Claimer needs to send more than a credential, as they also need to prove ownership of the credential. +A Claimer does this by creating a presentation and signing the Verifier's challenge. + + + {CreatePresentation} + + +The `createPresentation` method returns a presentation, taking the credential, a callback to sign data, and the Verifier's challenge as input. + +## Verify + +The verification code exposes the `getChallenge` method which returns a random and unique challenge for the Claimer to sign. +This unique challenge is used to prove ownership. + + + {Verify} + + +The `verifyPresentation` method performs the actual verification, taking a presentation and the Claimer's challenge as input. + +## Run + +Run the code from the command line: + + + + + ```bash + yarn ts-node verify.ts + ``` + + + + + ```bash + node verify.js + ``` + + + + +That's it! All done :-) \ No newline at end of file diff --git a/versioned_docs/version-0.3/03_workshop/08_done.md b/versioned_docs/version-0.3/03_workshop/08_done.md new file mode 100644 index 000000000..ff6558e53 --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/08_done.md @@ -0,0 +1,25 @@ +--- +id: done +title: 🚀 Done +--- + +## Congrats! + +Well done! +You now understand the main actors in KILT, the `Claimers`, `Attesters` and `Verifiers`. + +You have also learned how to: + +- create accounts +- create light and full DIDs +- create claims and attestation requests +- process requests and attest credentials +- generate and sign credential presentations +- receive and verify presentations + +## Resources + +Here are some resources to help you continue your journey in the KILT ecosystem: + +- [Discord](https://discord.gg/5VZnPdTZMy) - DAO-inspired, outcome-focused community +- [Element](https://matrix.to/#/%23kilt-general:matrix.org) - Technical, Governance, Treasury discussion diff --git a/versioned_docs/version-0.3/03_workshop/_category_.json b/versioned_docs/version-0.3/03_workshop/_category_.json new file mode 100644 index 000000000..65d6b088b --- /dev/null +++ b/versioned_docs/version-0.3/03_workshop/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Workshop", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/04_specifications.md b/versioned_docs/version-0.3/04_specifications.md new file mode 100644 index 000000000..b36bed2b5 --- /dev/null +++ b/versioned_docs/version-0.3/04_specifications.md @@ -0,0 +1,28 @@ +--- +id: specifications +title: Technical Specifications +--- + +:::note +This section is a WIP. +The end goal is for it to host all KILT specifications. +::: + +List of core specifications KILT has defined in an effort to standardize APIs and data structures across applications: + +- [KILT DID Method (GitHub repo)][kilt-did-method] +- [KiltPublishedCredentialCollectionV1 Service Type (GitHub repo)][kilt-published-credential-collection-v1] +- [Asset DID Method (GitHub repo)][asset-did-method] +- [KiltTransferAssetRecipientV1 Service Type (GitHub repo)][kilt-transfer-asset-receipient-v1] + +List of extensions to the core KILT protocol that standardize communication with the core KILT components (e.g., API for wallets to present credentials): + +- [Wallet Credential API (GitHub repo)][kilt-wallet-credential-api] +- [Wallet DIDSign API (GitHub repo)][kilt-wallet-didsign-api] + +[kilt-did-method]: https://github.com/KILTprotocol/spec-kilt-did +[kilt-published-credential-collection-v1]: https://github.com/KILTprotocol/spec-KiltPublishedCredentialCollectionV1 +[asset-did-method]: https://github.com/KILTprotocol/spec-asset-did +[kilt-transfer-asset-receipient-v1]: https://github.com/KILTprotocol/spec-KiltTransferAssetRecipientV1 +[kilt-wallet-credential-api]: https://github.com/KILTprotocol/spec-ext-credential-api +[kilt-wallet-didsign-api]: https://github.com/KILTprotocol/spec-ext-didsign-api diff --git a/docs/develop/05_builtonkilt.md b/versioned_docs/version-0.3/05_builtonkilt.md similarity index 96% rename from docs/develop/05_builtonkilt.md rename to versioned_docs/version-0.3/05_builtonkilt.md index e03487106..5a3f814f9 100644 --- a/docs/develop/05_builtonkilt.md +++ b/versioned_docs/version-0.3/05_builtonkilt.md @@ -49,7 +49,7 @@ Decentralized applications have already been built that use the functions of the width='80' alt='bte-w3n-id-logo'> w3n.id is a website that helps you claim and search web3names. - Learn more about KILT web3names in our [concepts section](../concepts/03_web3names.md). + Learn more about KILT web3names in our [concepts section](/concepts/web3names). --- diff --git a/versioned_docs/version-0.3/06_contribute.md b/versioned_docs/version-0.3/06_contribute.md new file mode 100644 index 000000000..e5f45a340 --- /dev/null +++ b/versioned_docs/version-0.3/06_contribute.md @@ -0,0 +1,101 @@ +--- +id: contribute +title: Contribution Guidelines +--- + +As a decentralized network, KILT depends on the support of its community. +There are many ways to contribute to KILT Protocol and the products and services built on it. +The following guide is to **help builders and contributors** find the resources needed to take action and work under the guidance of the core developers. + +If you are interested in contributing but unsure how to begin, start in our [Clan KILT Discord](https://discord.gg/7uyfMXh6AT) channel. +The developers active there, which include the team that originally developed KILT and the wider KILT community, can: + +- Provide feedback on proposals or ideas +- Discuss possible use cases and feature requests +- Make suggestions for non-technical contributions, including events, writing, or business models +- Answer questions about the protocol, services and products + + +## Feature Requests + +A feature request may be used to change the KILT Protocol and its services by adding new features or changing/removing existing ones. + + +A feature request is a meaningful way for anyone to contribute following the guidelines below: + + - Begin a discussion with the community to ensure most see that the proposed feature adds real and meaningful value to KILT Protocol, supporting its goals + - Open an Issue on the corresponding repository + - Give your Pull Request a clear title + - Provide a written outline of the feature request for discussion + +After discussion, if the community agrees that the change should be implemented, the proposer may also submit a Treasury proposal to support the work. +The guidelines of how to do that are presented in the next section. + +## Treasury Proposals + +A Treasury proposal is a request to receive funds from the Treasury pool. +The proposal should begin with a clear title, a written outline of the idea, and a discussion about implementation or deliverables as outlined above for feature requests. +The proposal should be for something that changes or adds value to KILT in a meaningful way. + +:::info +In general, a Treasury proposal spend occurs after completing all outlined deliverables and not before. +Thus, it is recommended to open multiple consecutive milestone-based proposals rather than one large proposal to fund contributions. +::: + +In addition you should: + +- Explain any milestones that have already been achieved +- Outline what needs to be done for the proposal to be completed + +The proposal should then be discussed with the community (including, for example, the KILT Technical Committee, governance, or relevant project team) using community channels such as [Discord](https://discord.gg/7uyfMXh6AT) or [Polkassembly](https://kilt.polkassembly.network/discussions). +If the community is not in agreement with the proposal, it is unlikely that it would be approved by governance. +See the [guide to creating a proposal](/participate/treasury-proposal) for additional details. + +## Tips + +Tips are a more agile and lightweight process to receive rewards for contributing to the KILT Protocol. +Even though the funds also come from the Treasury, the procedure is more straightforward. +The major difference compared to Treasury proposals is that for tips, determining the bounty amount is part of the course of tipping. +In other words, the final tip amount is not clear beforehand and the group of pre-determined stakeholders comes to consensus on how much should be paid. +Eventually, the median of proposed tips will be awarded from the Treasury. +Currently, the tippers include all Council members and other core code contributors. + +Both proposals and tips are similar in the sense that there must be someone (called the _Finder_) to open the tipping process by providing a reason in the form of a URL or an explanation on [Polkassembly](https://kilt.polkassembly.network/). +In contrast to proposals, tips do not require an extensive document; a URL to the pull request or the blog post suffices. +If the Finder is part of the group that decides about the bounty award, no deposit needs to be made. +Moreover, the beneficiary will receive the entire tip without any deductions. +Otherwise, a small deposit, which depends on the length of the message explaining the reason for the tip, needs to be reserved. +The deposit will be released after the tipping process has finished. +Additionally, the Finder also receives a minor Finder's fee of 20% which is subtracted from the final tip amount. + +Therefore, **even if you are not a contributor, you can open a tipping process for someone else and receive a smaller portion of their potential reward**. +Of course, you can also suggest potential tip candidates to the Council, which would then tip if they are deemed worthy. + +## Bug Reports + +We try our best, but bugs are an everyday reality with all software and are bound to happen. +We can't fix bugs we don't notice, so your potential findings give us the best possibility of keeping the project running smoothly and securely. + +If you are unsure if a bug is a bug, it is best to open an issue and report it anyway. +The active developers will evaluate it and help to figure out the issue. + +It is helpful to check if a report has already been filed in the related project. +Search the issues board for possible phrases that match the description of the bug. +It's possible you may not find an issue, but it's better to file a duplicated bug than not report one. + +Once you begin reporting the bug, write a descriptive title so that if others find the same issue they can either add to your findings or know that the bug has already been reported. +A bug report should be as detailed as possible, including steps to reproduce, screenshots, error reports, or code snippets. +The more details you provide, the easier it is to fix the issue. + +## Pull Requests + +Pull Requests (PR) are an integral part of contributions to evolve KILT. +GitHub itself has some [excellent documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests) on using the Pull Request feature. +KILT uses the "[fork and pull](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)" model, where contributors push changes to their personal fork and create Pull Requests to bring those changes into the original source repository. + +Before starting a PR, it’s best to contact other active developers and discuss the proposed changes. +Open an issue or directly contact some of the developers on [Discord](https://discord.gg/7uyfMXh6AT) to kick off the discussion and present the proposal. +Once approved, contributors can open a PR for review. +The PR will be reviewed and, if accepted, merged into the corresponding repository. + +The following section is inspired by the Rust Programming Language [Bug Report](https://rustc-dev-guide.rust-lang.org/contributing.html) contribution guide. diff --git a/versioned_docs/version-0.3/07_dApp/01_welcome.md b/versioned_docs/version-0.3/07_dApp/01_welcome.md new file mode 100644 index 000000000..8f04305cc --- /dev/null +++ b/versioned_docs/version-0.3/07_dApp/01_welcome.md @@ -0,0 +1,13 @@ +--- +id: welcome +title: Overview +--- + +This section expands on the [Credential API Specification](https://github.com/KILTprotocol/spec-ext-credential-api) and includes code examples to help you build a decentralized application (dapp). + +This documentation assumes that you already have a browser extension capable of exposing the credential API to your dapp. +We suggest using Sporran: + +- [Sporran Full Version](https://github.com/BTE-Trusted-Entity/sporran-extension) +- [Sporran Test Version for Peregrine](https://github.com/BTE-Trusted-Entity/sporran-extension/releases) +- [Sporran Lite (Credentials only)](https://github.com/BTE-Trusted-Entity/sporran-extension/tree/sporran-lite) diff --git a/docs/develop/07_dApp/02_well-known-did-config.md b/versioned_docs/version-0.3/07_dApp/02_well-known-did-config.md similarity index 98% rename from docs/develop/07_dApp/02_well-known-did-config.md rename to versioned_docs/version-0.3/07_dApp/02_well-known-did-config.md index 825387701..9f15351d2 100644 --- a/docs/develop/07_dApp/02_well-known-did-config.md +++ b/versioned_docs/version-0.3/07_dApp/02_well-known-did-config.md @@ -103,7 +103,7 @@ The extension will make an HTTP GET request to the following URI, and your dapp How the file is hosted depends on your project setup and is out of scope for this guide. -[concept-attestations]: ../../concepts/05_credentials/04_attestation.md +[concept-attestations]: /concepts/credentials/attestation [cookbook-attestations]: ../01_sdk/02_cookbook/04_claiming/03_attestation_creation.md [create-full-did]: ../01_sdk/02_cookbook/01_dids/02_full_did_creation.md [well-known-spec]: https://identity.foundation/specs/did-configuration/ diff --git a/versioned_docs/version-0.3/07_dApp/03_session.md b/versioned_docs/version-0.3/07_dApp/03_session.md new file mode 100644 index 000000000..12b04afce --- /dev/null +++ b/versioned_docs/version-0.3/07_dApp/03_session.md @@ -0,0 +1,59 @@ +--- +id: session +title: Setting Up the Communication Session +--- + +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import DappIntroduction from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/dapp/06_dapp_introduction.ts'; +import SessionCheck from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/dapp/07_session_check.ts'; + +The first step in creating your dapp is to set up the communication session. +The purpose of the session is to pass encrypted messages back and forth between your dapp and the extension. + +## Dapp Indicates Credential API Support + +In order to indicate its support of the extension's API, the dapp creates the `window.kilt` object as soon as possible. +To indicate the API version that the dapp supports, we also create the properties `window.kilt.meta.versions.credentials`. +Since `meta` is not an extension, this property is not enumerable. +For example: + +```html + + + +``` + +## Dapp Introduces Itself + +The dapp introduces itself to the extension with its name, encryption key URI, and a challenge. +A copy of the challenge should be stored on the server side. +For example: + + + {DappIntroduction} + + +At this point the extension has received the introduction of the dapp and returned a new session along with the encrypted challenge. + +## Dapp checks the session values + +The extension has provided the session along with an encrypted challenge. +The dapp decrypts the challenge and verifies that it matches the original challenge. +This should happen on the server side: + + + {SessionCheck} + + +That's it! The communication session has been securely established and you're ready to start sending and receiving messages. diff --git a/versioned_docs/version-0.3/07_dApp/04_verifier.md b/versioned_docs/version-0.3/07_dApp/04_verifier.md new file mode 100644 index 000000000..fe362f81a --- /dev/null +++ b/versioned_docs/version-0.3/07_dApp/04_verifier.md @@ -0,0 +1,84 @@ +--- +id: dapp-verifier +title: Verifying a Credential +--- + +import TsJsSnippet from '@site/src/components/TsJsSnippet'; +import TsJsBlock from '@site/src/components/TsJsBlock'; + +import EmailCtype from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/verifier/01_email_ctype.ts'; +import GenerateChallenge from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/verifier/02_generate_challenge.ts'; +import CreateRequestCredentialMessage from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/verifier/03_create_request_credential_message.ts'; +import EncryptRequestCredentialMessage from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/verifier/04_encrypt_request_credential_message.ts'; +import DecryptCredentialMessage from '!!raw-loader!@site/code_examples/sdk_examples/src/dapp/verifier/05_verify_credential_message.ts'; + +This section demonstrates how to build a basic verifier according to the [Credential API Specification](https://github.com/KILTprotocol/spec-ext-credential-api). +Before continuing, please make sure you have already set up the [communication session](03_session.md) and [Well-Known DID Configuration](02_well-known-did-config.md). + +This guide explains specifically how a web server can request a credential presentation from one of its visitors (the claimer). +After the browser extension verified the Well-Known DID Configuration and the encrypted communication channel between the extension and the server was established, the web server can request the credential presentation. +This is a two step process. + +First the server sends a message to the extension that request the presentation of a credential. +Since we don't want to see just any credential, but expect specific content, we also require that the credential conforms to a specific [CType](/concepts/credentials/ctypes). +When the extension receives the request, it will prompt the user to select a credential that should be presented to the server. +The user can also choose to reject this request and not to show any presentation. + +The second step is to verify the received credential. +After the user chooses the credential, the extension will pass a response to the website which contains the credential presentation. +The server of that website needs to ensure that this presentation is actually valid. + +## Request a Credential Presentation + +Before the website can request a credential, it needs the type of credential (CType) that it wants to request. +In this guide the website requests an email address that is owned by the DID. +For that it uses the Email CType. +You can search through existing CTypes in the [CType Index](https://github.com/KILTprotocol/ctype-index). + + + {EmailCtype} + + +After settled on a CType, the server can build the request for the visitor. +Since we want to ensure that the presentation of the credential is fresh, the server first has to create a random challenge. +The presentation must include this challenge and since it's random, the presentation must be created and signed from scratch. +This ensures that it's not possible to record a presentation and just send this, pretending to be the owner of the DID. +The challenge can be generated using the polkadot crypto utilities: + + + {GenerateChallenge} + + +With the challenge the server can construct the `request-credential` message. +The request is sent to the light DID (`claimerSessionDid`) that is used to encrypt the messages (see [Session](03_session.md) for more information). + + + {CreateRequestCredentialMessage} + + +:::note Privacy + +The credential itself doesn't need to be issued to this DID since the light DID is only used to encrypt the messages. +We don't use the full DID of the claimer to establish the encrypted communication, so that the claimer first can ensure the origin of the `request-credential` message. + +::: + +After the server has built the message object, it must encrypt the message for the claimer. +Once the message is encrypted the server can pass on the message to the extension. + + + {EncryptRequestCredentialMessage} + + +## Verify the Presentation + +After sending the `request-credential` message to the extension, the verifier listens for a message of type `submit-credential` in response. + +After the response from the extension is received, forwarded to the server and decrypted, the verifier must check that it has the expected CType and that it contains a valid credential. +Since everyone can run an attestation service, you need to make sure that you also verify that the attester is trusted. + + + {DecryptCredentialMessage} + + +That's it! Your verifier has successfully requested and verified a credential. diff --git a/versioned_docs/version-0.3/07_dApp/_category_.json b/versioned_docs/version-0.3/07_dApp/_category_.json new file mode 100644 index 000000000..235e97018 --- /dev/null +++ b/versioned_docs/version-0.3/07_dApp/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "DApp", + "collapsible": true, + "collapsed": true +} diff --git a/versioned_docs/version-0.3/08_opendid/01_overview.md b/versioned_docs/version-0.3/08_opendid/01_overview.md new file mode 100644 index 000000000..e42a82d1b --- /dev/null +++ b/versioned_docs/version-0.3/08_opendid/01_overview.md @@ -0,0 +1,40 @@ +--- +id: what-is-opendid +title: Overview +--- + +[OpenDID](https://github.com/KILTprotocol/opendid) is an OpenID Provider implementation capable of authenticating users through their [Decentralized Identifier (DID)](/concepts/did) and Verifiable Credentials. + +It follows the [OpenID Connect 1.0 Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and acts as a bridge between the decentralized identity world and the centralized authentication world supporting both the implicit and Authorization Code Flow. + +A major use of OpenDID is Single Sign-On (SSO), which allows users to use the same DID and credentials to sign into multiple platforms and web services. For instance, by adding a "Sign in with KILT" button to a webpage. + +Although integrating that functionality into a webpage is relatively simple, configuring and running OpenDID is more involved. + +:::info + +To learn more about the flow of OpenDID, see the [OpenDID Flow](./02_opendid_flow.md) documentation. + +::: + +## Project container structure + +The project consist of multiple parts that supplement and interact with each other all shipped as Docker containers and released to Docker Hub. + +### opendid-setup container + +The OpenDID Service needs configuration to run, which you can apply using this +container. +For example, it requires a DID to establish a session with an identity wallet. +This container creates a DID and the necessary configuration by providing an account with enough funds. + +Learn more in the [run setup container documentation](./03_opendid_service.md#run-setup-container). + +### kiltprotocol/opendid container + +This container [runs the OpenDID Service](./03_opendid_service.md#run-the-service), both the OpenDID front and back end. +This container requires the configuration file created from the `opendid-setup` container. + +### kiltprotocol/opendid-demo + +This container is a [web app demo](./05_demo_project.md), including front and back end services to demonstrate the use of OpenDID. \ No newline at end of file diff --git a/versioned_docs/version-0.3/08_opendid/02_opendid_flow.md b/versioned_docs/version-0.3/08_opendid/02_opendid_flow.md new file mode 100644 index 000000000..5a1046ce7 --- /dev/null +++ b/versioned_docs/version-0.3/08_opendid/02_opendid_flow.md @@ -0,0 +1,74 @@ +--- +id: flow +title: OpenDID Flow +--- + +This guide explains the internal workings of OpenDID. +Understanding this flow is helpful for setting up and configuring an OpenDID Service but less important if you only need to integrate it in an application. + +OpenDID includes interactions between multiple apps to authenticate and authorize users. +Common use cases include the following: + +- Web app front end (app that includes the login button, for example, the demo app) +- Web app back end +- OpenDID front end +- OpenDID back end +- Identity wallet that follows [the Credential API spec](https://github.com/KILTprotocol/spec-ext-credential-api) (typically a browser extension, for example, [Sporran](https://www.sporran.org/)) + +The following steps outline the interactions necessary to implement [the implicit flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth): + +1. The user clicks the login button on the _web app front end_. +2. The _web app front end_ redirects the user to the _OpenDID front end_. +3. The user chooses what wallet to authenticate with. +4. The _OpenDID back end_ establishes a secure session with the _identity wallet_. +5. The _OpenDID back end_ optionally requests a credential that implements a specific CType. +6. The _identity wallet_ provides the _OpenDID back end_ with the requested credential, after authenticating the DID holder. +7. The _OpenDID back end_ returns a `id_token` as a JSON web token (JWT) to the _OpenDID front end_. +8. _OpenDID front end_ redirects the user back to a specific `redirect_url` on the _web app front end_ including the `id_token`. +9. The _web app front end_ detects the `id_token` and sends it to the _web app back end_. +10. The _web app back end_ verifies the `id_token` and ensures the validity of the credential. + +The following sequence diagram summarizes the flow: + +```mermaid +sequenceDiagram + +participant AB as WebApp Backend +participant AF as WebApp Frontend +participant OF as OpenDID Frontend +participant OB as OpenDID Backend +participant IW as Identity Wallet + +AF->>OF: (1, 2) Authorize (redirect_uri: /callback) +OF->>OF: (3) Pick Identity Wallet +critical (4) Key Exchange +OF->>OB: GET Challenge +OB-->>OF: Challenge +OF->>IW: Start Session +IW-->>OF: Encrypted Challenge +OF->>OB: POST Challenge +OB-->>OF: OK +end + +critical Authenticate +OF->>OB: (5) GET Credential Requirements +OB-->>OF: Credential Requirements +OF->>IW: (6) Request Credential +IW->>IW: Authenticate User +IW->>OF: Credential +OF->>OB: POST Credential +OB->>OB: Verify Credential +OB->>OF: (7) `id_token`) +end + +OF->>AF: redirect to /callback with `id_token` +AF->>AB: (8) `id_token` +AB->>AB: (9) verify `id_token` +AB->>AF: (10) Access granted. + +``` + +:::info +Although this example describes the implicit flow, [the authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) is similar. +Instead of returning an `id_token` directly, the OpenDID service instead returns a `code` to exchange for an `id_token` using the `token` endpoint. +::: diff --git a/versioned_docs/version-0.3/08_opendid/03_opendid_service.md b/versioned_docs/version-0.3/08_opendid/03_opendid_service.md new file mode 100644 index 000000000..311f3fc60 --- /dev/null +++ b/versioned_docs/version-0.3/08_opendid/03_opendid_service.md @@ -0,0 +1,115 @@ +--- +id: opendid_service +title: Run OpenDID Service +--- + +## Configuration + +Running the OpenDID service requires some configuration and a KILT DID. +The DID establishes a secure session with an identity wallet using a key agreement key of type `X25519KeyAgreementKey2019` included in the DID Document generated by the setup container. + +OpenDID serves a [well-known DID configuration](https://identity.foundation/.well-known/resources/did-configuration/), which the identity wallet uses to ensure that the domain is linked to the specified DID. + +### Run setup container + +Before running the `opendid-setup` container, set two environment variables: + +1. `SEED` to provide an account with funds (minimum of 3 KILT) for the DID generation. + + ```bash + export SEED="dont try this seed its completely made up for this nice example" + ``` + +2. `ENDPOINT` + + Set to "spiritnet" if the account is on the spiritnet production network. + + ```bash + export ENDPOINT="spiritnet" + ``` + + Set to "peregrine" if the account is on the peregrine test network. + + ```bash + export ENDPOINT="peregrine" + ``` + + Then run the setup with the following command: + + ```bash + docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data docker.io/kiltprotocol/opendid-setup:latest "${SEED}" + ``` + +The command generates a set of new mnemonics and then derives a DID from them and generates multiple files into the current directory: + +1. `config.yaml` The configuration file used by the OpenDID service. + + :::warning + You only need the `config.yaml` to run the OpenDID service. + This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access. + ::: + +2. `did-secrets.json` This file contains the public and secret keys in the DID Document. + + :::warning + Keep a secure backup of this file as it contains all the secret keys. + ::: + +3. `did-document.json` contains the DID Document generated by this setup. + +The container generates sensible defaults in the `config.yaml` file, but here are some values you might want to change: + +- Set `production` to true, this only allows secure connections. +- Set the `WellKnownDid` > `origin`, which should match the host running the OpenDID service. +- Set the keys used for JWT issuance in the `jwt` section. +- The `client` section, including: + + - The client ID as a key (The default is: `example-client`). + - The `requirements` section, including: + + - What CTypes are required for authentication. + - The trusted attesters as an address (The default is for the [SocialKYC attester](https://socialkyc.io/)). + + :::note info + + The generated default `config.yaml` requires an [email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by an attester. + + ::: + + - What `redirect_url`s the service accepts (The default is `http://localhost:1606/callback.html` for the demo project). + - The `clientSecret` is optional but recommended. If you use the authorization code flow, the `token` endpoint requires it. + +## Run the service + +When you've made changes to the `config.yaml` file, you can run the OpenDID service. + +1. Specify the runtime through the `RUNTIME` environment variable: + + Set to `"spiritnet"` for production KILT + + ```bash + export RUNTIME="spiritnet" + ``` + + Set to `"peregrine"` for the KILT test net. + + ```bash + export RUNTIME="peregrine" + ``` + +2. Run the `docker.io/kiltprotocol/opendid` docker image. + + ```bash + docker run -d --rm \ + -v $(pwd)/config.yaml:/app/config.yaml \ + -v $(pwd)/checks:/app/checks \ + -e "RUNTIME=${RUNTIME}" \ + -p 3001:3001 \ + docker.io/kiltprotocol/opendid:latest + ``` + +3. Open the login page at _http://localhost:3001_. + +## Next steps + +With configuration in place and a service running, next you need to [integrate OpenDID into an application](./04_integrate_opendid.md) so that a user can use the login page. diff --git a/versioned_docs/version-0.3/08_opendid/04_integrate_opendid.md b/versioned_docs/version-0.3/08_opendid/04_integrate_opendid.md new file mode 100644 index 000000000..a0518be0b --- /dev/null +++ b/versioned_docs/version-0.3/08_opendid/04_integrate_opendid.md @@ -0,0 +1,126 @@ +--- +id: integrate_opendid +title: Integrate OpenDID +--- + +OpenDID follows the [OpenID Connect 1.0 Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and implements both the [implicit flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowSteps) +and the [authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). +Read the [demo project guide](05_demo_project.md) for an example of integrating OpenDID. + +## Authorization code flow + +Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID service and setting the following query URL-encoded parameters: + +- `response_type`: set value to `code` to indicate Authorization Code Flow. +- `client_id`: The client ID set in the `config.yaml` file. +- `redirect_uri`: OpenDID redirects to this URL after authentication. +- `scope`: set value to `openid`. +- `state`: set to a secure random number. +- `nonce`: optional value, set to a secure random number. + +**Example**: + +``` +GET /api/v1/authorize? + response_type=code& + client_id=example-client& + redirect_uri=http://localhost:1606/callback.html& + scope=openid& + state=rkw49cbvd4azu5dsln1xbl& + nonce=vedur4om49ei8w91jt7wt HTTP/1.1 +``` + +After successful authentication, the OpenDID service redirects back to the provided `redirect_uri` with `code` and `state` query parameters. + +**Example**: + +``` +/callback.html? + code=lwDS1ZpQBwR4Vdm53_L8bWpUJ1mx9A0mA_-86dubTqzqzwGazx1RyLX4Z_qf& + state=rkw49cbvd4azu5dsln1xbl +``` + +You can retrieve the `id_token` by calling the **POST** `/api/v1/token` and providing the following values in the form serialization: + +- `code`: code value returned from `authorize`. +- `grant_type`: set value to `authorization_code`. +- `redirect_uri`: the same `redirect_uri` used in `authorize`. +- `client_id`: the client ID set in the `config.yaml` file. +- `client_secret`: the client secret value set in the `config.yaml` file. + +**Example**: + +``` +POST /api/v1/token HTTP/1.1 +Content-Type: application/x-www-form-urlencoded + +code=lwDS1ZpQBwR4Vdm53_L8bWpUJ1mx9A0mA_-86dubTqzqzwGazx1RyLX4Z_qf& +grant_type=authorization_code& +redirect_uri=http%3A%2F%2Flocalhost%3A1606%2Fcallback.html& +client_id=example-client& +client_secret=insecure_client_secret +``` + +The OpenDID service returns the `id_token` in the response body serialized as a JSON object. + +```json +{ + "access_token": "SsFhhSBMWsLeDMxVUVGreKARNwYxMZtGFfBr0-ZiH6iondSmwPRvQDqkG6Fh", + "token_type": "bearer", + "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTYwNjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXV0aGVudGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.yOmE_9jWKcAu8LpjVx7IsFyOOvlKbgo2oC4Imf-qrLY", + "id_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTU1MjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXBwbGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.YlRE9EGnSExQCb5m2iy4__58PZJlZdCZMsSvsuW4oj8" +} +``` + +:::note +In full-stack applications, calling the `token` endpoint is usually done through the back end to improve security. +::: + +The `id_token` is a bearer JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. +You must verify this using the JWT public key, for example, by the back end of the Web app. + +## Implicit flow + +Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query parameters: + +- `response_type`: set value to `id_token` to indicate Implicit Flow. +- `client_id`: The client ID set in the config.yaml file. +- `redirect_uri`: OpenDID redirects to this URL after authentication. +- `scope`: set value to `openid`. +- `state`: set to a secure random number. +- `nonce`: optional value, set to a secure random number. + +**Example**: + +``` +GET /api/v1/authorize? + response_type=id_token& + client_id=example-client& + redirect_uri=http://localhost:1606/callback.html& + scope=openid& + state=o0fl4c9gwylymzw5f4ik& + nonce=ia7sa06ungxdfzaqphk2 HTTP/1.1 +``` + +After successful authentication, OpenDID redirects back to the provided `redirect_uri` with `id_token` and `state` +**fragment components**. + +**Example**: + +``` +/callback.html# + id_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4ODQ5MDYsImlhdCI6MTcxNjg4NDg0NiwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXBwbGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoiOTFzN2ZnZDZvcjR3c2NkdGVtcXQifQ.xTy3Oyc5e-vlP10mGy0f9GqNU4LV97s77s-l7w5EwF0& + refresh_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4ODU0NDYsImlhdCI6MTcxNjg4NDg0NiwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXV0aGVudGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoiOTFzN2ZnZDZvcjR3c2NkdGVtcXQifQ.87UHGid3OotxO8Wpfuw-1sc5fsQJVt5gc2cqp9dVHiw& + state=nitctpl7nmqcpvob7xthrw& + token_type=bearer +``` + +## Self-Issued OpenID Provider v2 (SIOPv2) + +You can configure OpenDID to be compatible with [SIOPv2](https://openid.net/specs/openid-connect-self-issued-v2-1_0.html). +In this case, you only need a DID for the authorization, and no credentials. +To configure the OpenDID service to allow SIOPv2, it must have a `client` key with an empty requirements +value in the `config.yaml` file. + +Initiate the SIOPv2 flow the same way as the [Implicit Flow](#implicit-flow) with the exception that the `nonce` +value is required. diff --git a/versioned_docs/version-0.3/08_opendid/05_demo_project.md b/versioned_docs/version-0.3/08_opendid/05_demo_project.md new file mode 100644 index 000000000..a4a334d35 --- /dev/null +++ b/versioned_docs/version-0.3/08_opendid/05_demo_project.md @@ -0,0 +1,30 @@ +--- +id: demo_project +title: Demo Project +--- + +The example code at [demo-project](https://github.com/KILTprotocol/opendid/tree/main/demo-project) contains a minimal application that uses OpenDID. +It's an [express](https://expressjs.com) application that exposes three things: + +- A login page that handles the dispatching of the user to the OpenDID service. +- A callback page for one of the OpenID Connect flows supported to accept the token. +- A protected resource that only authenticated users can access. + +For the demo application to work you need a running OpenDID Service and an identity wallet that follows [the Credential API spec](https://github.com/KILTprotocol/spec-ext-credential-api) (e.g. [Sporran](https://www.sporran.org/)) with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). +If you follow the steps in this section in order, you have all the necessary components for the demo application to run. + +Run the pre-configured demo application with the following command: + +```bash +docker run -d -it --rm \ + --name demo-frontend \ + -p 1606:1606 \ + docker.io/kiltprotocol/opendid-demo +``` + +The demo page runs on _http://localhost:1606_. It pre-fills the Client ID value and offers login buttons to follow the implicit or authorization code flow. + +:::note +You can set the JSON web token (JWT) secret can with the `TOKEN_SECRET` environment variable inside the docker container. It must match +the one specified in the `config.yaml` file to correctly verify the `id_token`. The default is `super-secret-jwt-secret`. +::: diff --git a/versioned_docs/version-0.3/08_opendid/06_advanced.md b/versioned_docs/version-0.3/08_opendid/06_advanced.md new file mode 100644 index 000000000..ec36cb8bb --- /dev/null +++ b/versioned_docs/version-0.3/08_opendid/06_advanced.md @@ -0,0 +1,111 @@ +--- +id: advanced +title: Advanced Usage +--- + +## Use dynamic client management with etcd + +To dynamically create or remove OpenID Connect clients, configure the service to get its configuration from an [etcd cluster](https://etcd.io) by adding the connection parameters for the cluster in the `config.yaml` file. + +```yaml +etcd: + endpoints: ['localhost:2379'] + user: etcd-user + password: my-password + tlsDomainName: my.etcd.cluster.example.com + tlsCaCert: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tlsClientCert: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tlsClientKey: | + -----BEGIN RSA PRIVATE KEY----- + + -----END RSA PRIVATE KEY----- +``` + +All fields except `endpoints` are optional. +When everything is set up you can start adding client configurations into the etcd cluster. + +```bash +CLIENT_SPEC=$(cat <= 0.1.1" +event-target-shim@^5.0.0: + version "5.0.1" + resolved "https://registry.yarnpkg.com/event-target-shim/-/event-target-shim-5.0.1.tgz#5d4d3ebdf9583d63a5333ce2deb7480ab2b05789" + integrity sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ== + eventemitter3@^4.0.0: version "4.0.7" resolved "https://registry.yarnpkg.com/eventemitter3/-/eventemitter3-4.0.7.tgz#2de9b68f6528d5644ef5c59526a1b4a07306169f" integrity sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw== -events@^3.2.0: +events@^3.2.0, events@^3.3.0: version "3.3.0" resolved "https://registry.yarnpkg.com/events/-/events-3.3.0.tgz#31a95ad0a924e2d2c419a813aeb2c4e878ea7400" integrity sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q== @@ -4837,6 +4885,18 @@ glob-to-regexp@^0.4.1: resolved "https://registry.yarnpkg.com/glob-to-regexp/-/glob-to-regexp-0.4.1.tgz#c75297087c851b9a578bd217dd59a92f59fe546e" integrity sha512-lkX1HJXwyMcprw/5YUZc2s7DrpAiHB21/V+E1rHUrVNokkvB6bqMzT0VfV6/86ZNabt1k14YOIaT7nDvOX3Iiw== +glob@^10.0.0: + version "10.4.5" + resolved "https://registry.yarnpkg.com/glob/-/glob-10.4.5.tgz#f4d9f0b90ffdbab09c9d77f5f29b4262517b0956" + integrity sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg== + dependencies: + foreground-child "^3.1.0" + jackspeak "^3.1.2" + minimatch "^9.0.4" + minipass "^7.1.2" + package-json-from-dist "^1.0.0" + path-scurry "^1.11.1" + glob@^10.3.7: version "10.4.2" resolved "https://registry.yarnpkg.com/glob/-/glob-10.4.2.tgz#bed6b95dade5c1f80b4434daced233aee76160e5" @@ -4861,17 +4921,6 @@ glob@^7.0.0, glob@^7.1.3, glob@^7.1.6: once "^1.3.0" path-is-absolute "^1.0.0" -glob@^8.0.0: - version "8.1.0" - resolved "https://registry.yarnpkg.com/glob/-/glob-8.1.0.tgz#d388f656593ef708ee3e34640fdfb99a9fd1c33e" - integrity sha512-r8hpEjiQEYlF2QU0df3dS+nxxSIreXQS1qRhMJM0Q5NDdR386C7jb7Hwwod8Fgiuex+k0GFjgft18yvxm5XoCQ== - dependencies: - fs.realpath "^1.0.0" - inflight "^1.0.4" - inherits "2" - minimatch "^5.0.1" - once "^1.3.0" - global-dirs@^3.0.0: version "3.0.1" resolved "https://registry.yarnpkg.com/global-dirs/-/global-dirs-3.0.1.tgz#0c488971f066baceda21447aecb1a8b911d22485" @@ -5359,6 +5408,11 @@ icss-utils@^5.0.0, icss-utils@^5.1.0: resolved "https://registry.yarnpkg.com/icss-utils/-/icss-utils-5.1.0.tgz#c6be6858abd013d768e98366ae47e25d5887b1ae" integrity sha512-soFhflCVWLfRNOPU3iv5Z9VUdT44xFRbzjLsEzSr5AQmgqPMTHdU3PMT1Cf1ssx8fLNJDA1juftYl+PUcv3MqA== +ieee754@^1.2.1: + version "1.2.1" + resolved "https://registry.yarnpkg.com/ieee754/-/ieee754-1.2.1.tgz#8eb7a10a63fff25d15a57b001586d177d1b0d352" + integrity sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA== + ignore@^5.2.0, ignore@^5.2.4: version "5.3.1" resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.3.1.tgz#5073e554cd42c5b33b394375f538b8593e34d4ef" @@ -5642,7 +5696,7 @@ is-root@^2.1.0: resolved "https://registry.yarnpkg.com/is-root/-/is-root-2.1.0.tgz#809e18129cf1129644302a4f8544035d51984a9c" integrity sha512-AGOriNp96vNBd3HtU+RzFEc75FfR5ymiYv8E553I71SCeXBiMsVDUtdio1OEFvrPyLIQ9tVR5RxXIFe5PUFjMg== -is-stream@^2.0.0: +is-stream@^2.0.0, is-stream@^2.0.1: version "2.0.1" resolved "https://registry.yarnpkg.com/is-stream/-/is-stream-2.0.1.tgz#fac1e3d53b97ad5a9d0ae9cef2389f5810a5c077" integrity sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg== @@ -6015,7 +6069,7 @@ markdown-extensions@^2.0.0: resolved "https://registry.yarnpkg.com/markdown-extensions/-/markdown-extensions-2.0.0.tgz#34bebc83e9938cae16e0e017e4a9814a8330d3c4" integrity sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q== -markdown-link-check@^3.11.2: +markdown-link-check@^3.12.2: version "3.12.2" resolved "https://registry.yarnpkg.com/markdown-link-check/-/markdown-link-check-3.12.2.tgz#05606ccfdfc14e75d28a15cf31297aa273f1f754" integrity sha512-GWMwSvxuZn+uGGydi5yywnnDZy08SGps4I/63xqvWT7lxtH4cVLnhgZZYtEcPz/QvgPg9vbH2rvWpa29owMtHA== @@ -7014,7 +7068,7 @@ minimatch@3.1.2, minimatch@^3.0.4, minimatch@^3.0.5, minimatch@^3.1.1: dependencies: brace-expansion "^1.1.7" -minimatch@^5.0.1, minimatch@^5.1.0: +minimatch@^5.1.0: version "5.1.6" resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-5.1.6.tgz#1cfcb8cf5522ea69952cd2af95ae09477f122a96" integrity sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g== @@ -7814,10 +7868,10 @@ postcss@^8.4.21, postcss@^8.4.24, postcss@^8.4.26, postcss@^8.4.33, postcss@^8.4 picocolors "^1.0.1" source-map-js "^1.2.0" -prettier@^3.2.4: - version "3.3.2" - resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.3.2.tgz#03ff86dc7c835f2d2559ee76876a3914cec4a90a" - integrity sha512-rAVeHYMcv8ATV5d508CFdn+8/pHPpXeIid1DdrPwXnaAdH7cqjVbpJaT5eq4yRAFU/lsbwYwSF/n5iNrdJHPQA== +prettier@^3.3.3: + version "3.3.3" + resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.3.3.tgz#30c54fe0be0d8d12e6ae61dbb10109ea00d53105" + integrity sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew== pretty-error@^4.0.0: version "4.0.0" @@ -7857,6 +7911,11 @@ process-nextick-args@~2.0.0: resolved "https://registry.yarnpkg.com/process-nextick-args/-/process-nextick-args-2.0.1.tgz#7820d9b16120cc55ca9ae7792680ae7dba6d7fe2" integrity sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag== +process@^0.11.10: + version "0.11.10" + resolved "https://registry.yarnpkg.com/process/-/process-0.11.10.tgz#7332300e840161bda3e69a1d1d91a7d4bc16f182" + integrity sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A== + progress@^2.0.3: version "2.0.3" resolved "https://registry.yarnpkg.com/progress/-/progress-2.0.3.tgz#7e8cf8d8f5b8f239c1bc68beb4eb78567d572ef8" @@ -8037,7 +8096,7 @@ react-dev-utils@^12.0.1: strip-ansi "^6.0.1" text-table "^0.2.0" -react-dom@^18.2.0: +react-dom@^18.3.1: version "18.3.1" resolved "https://registry.yarnpkg.com/react-dom/-/react-dom-18.3.1.tgz#c2265d79511b57d479b3dd3fdfa51536494c5cb4" integrity sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw== @@ -8150,7 +8209,7 @@ react-router@5.3.4, react-router@^5.3.4: tiny-invariant "^1.0.2" tiny-warning "^1.0.0" -react@^18.2.0: +react@^18.3.1: version "18.3.1" resolved "https://registry.yarnpkg.com/react/-/react-18.3.1.tgz#49ab892009c53933625bd16b2533fc754cab2891" integrity sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ== @@ -8170,7 +8229,7 @@ readable-stream@^2.0.1, readable-stream@^2.0.5: string_decoder "~1.1.1" util-deprecate "~1.0.1" -readable-stream@^3.0.6, readable-stream@^3.4.0, readable-stream@^3.6.0: +readable-stream@^3.0.6: version "3.6.2" resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-3.6.2.tgz#56a9b36ea965c00c5a93ef31eb111a0f11056967" integrity sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA== @@ -8179,6 +8238,17 @@ readable-stream@^3.0.6, readable-stream@^3.4.0, readable-stream@^3.6.0: string_decoder "^1.1.1" util-deprecate "^1.0.1" +readable-stream@^4.0.0: + version "4.5.2" + resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-4.5.2.tgz#9e7fc4c45099baeed934bff6eb97ba6cf2729e09" + integrity sha512-yjavECdqeZ3GLXNgRXgeQEdz9fvDDkNKyHnbHRFtOr7/LcfgBcmct7t/ET+HaCTqfh06OzoAxrkN/IfjJBVe+g== + dependencies: + abort-controller "^3.0.0" + buffer "^6.0.3" + events "^3.3.0" + process "^0.11.10" + string_decoder "^1.3.0" + readdir-glob@^1.1.2: version "1.1.3" resolved "https://registry.yarnpkg.com/readdir-glob/-/readdir-glob-1.1.3.tgz#c3d831f51f5e7bfa62fa2ffbe4b508c640f09584" @@ -8941,7 +9011,7 @@ string-width@^5.0.1, string-width@^5.1.2: emoji-regex "^9.2.2" strip-ansi "^7.0.1" -string_decoder@^1.1.1: +string_decoder@^1.1.1, string_decoder@^1.3.0: version "1.3.0" resolved "https://registry.yarnpkg.com/string_decoder/-/string_decoder-1.3.0.tgz#42f114594a46cf1a8e30b0a84f56c78c3edac21e" integrity sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA== @@ -9747,14 +9817,14 @@ yocto-queue@^1.0.0: resolved "https://registry.yarnpkg.com/yocto-queue/-/yocto-queue-1.1.1.tgz#fef65ce3ac9f8a32ceac5a634f74e17e5b232110" integrity sha512-b4JR1PFR10y1mKjhHY9LaGo6tmrgjit7hxVIeAmyMw3jegXR4dhYqLaQF5zMXZxY7tLpMyJeLjr1C4rLmkVe8g== -zip-stream@^5.0.1: - version "5.0.2" - resolved "https://registry.yarnpkg.com/zip-stream/-/zip-stream-5.0.2.tgz#77b1dce7af291482d368a9203c9029f4eb52e12e" - integrity sha512-LfOdrUvPB8ZoXtvOBz6DlNClfvi//b5d56mSWyJi7XbH/HfhOHfUhOqxhT/rUiR7yiktlunqRo+jY6y/cWC/5g== +zip-stream@^6.0.1: + version "6.0.1" + resolved "https://registry.yarnpkg.com/zip-stream/-/zip-stream-6.0.1.tgz#e141b930ed60ccaf5d7fa9c8260e0d1748a2bbfb" + integrity sha512-zK7YHHz4ZXpW89AHXUPbQVGKI7uvkd3hzusTdotCg1UxyaVtg0zFJSTfW/Dq5f7OBBVnq6cZIaC8Ti4hb6dtCA== dependencies: - archiver-utils "^4.0.1" - compress-commons "^5.0.1" - readable-stream "^3.6.0" + archiver-utils "^5.0.0" + compress-commons "^6.0.2" + readable-stream "^4.0.0" zwitch@^2.0.0: version "2.0.4"