diff --git a/docs/concepts/02_did.md b/docs/concepts/02_did.md index 7c1164c6c..1d63e7418 100644 --- a/docs/concepts/02_did.md +++ b/docs/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). + ::: diff --git a/docs/concepts/03_web3names.md b/docs/concepts/03_web3names.md index b2f54a1cc..c9a420d3d 100644 --- a/docs/concepts/03_web3names.md +++ b/docs/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). + ## KILT DIDs vs. KILT accounts diff --git a/docs/concepts/05_credentials/02_ctypes.md b/docs/concepts/05_credentials/02_ctypes.md index 11aa11918..15fed4e12 100644 --- a/docs/concepts/05_credentials/02_ctypes.md +++ b/docs/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). + [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. + Verifiers depending on these CTypes should accept both the old and new CType during a transition period. Test thoroughly to ensure the correct behavior and functionality of the new CTypes in your application. diff --git a/docs/concepts/05_credentials/03_claiming.md b/docs/concepts/05_credentials/03_claiming.md index 1779099f6..2709c58ab 100644 --- a/docs/concepts/05_credentials/03_claiming.md +++ b/docs/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). + ::: diff --git a/docs/concepts/05_credentials/04_attestation.md b/docs/concepts/05_credentials/04_attestation.md index 33c9c2aae..babf88837 100644 --- a/docs/concepts/05_credentials/04_attestation.md +++ b/docs/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). + ::: @@ -25,4 +25,4 @@ Storing a attestation in the blockchain requires providing a constant deposit, w The deposit serves as a security measure to ensure the integrity of the blockchain and incentivize users to manage their attestation responsibly. By requiring a deposit, it discourages spamming or unnecessary creation of attestation. The attester can reclaim the deposit by deleting their attestation. -Revoking them isn't sufficient as the deposit still shows in chain storage, but marked as invalid. \ No newline at end of file +Revoking them isn't sufficient as the deposit still shows in chain storage, but marked as invalid. diff --git a/docs/concepts/05_credentials/05_verification.md b/docs/concepts/05_credentials/05_verification.md index 0c50f9dcb..2be95fe1e 100644 --- a/docs/concepts/05_credentials/05_verification.md +++ b/docs/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). + ::: @@ -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). + ::: diff --git a/docs/concepts/07_dip/05_dapp_developer.md b/docs/concepts/07_dip/05_dapp_developer.md index 0083e33f7..49813f0ee 100644 --- a/docs/concepts/07_dip/05_dapp_developer.md +++ b/docs/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. + + In the example code, the configuration also has extra parameters for the time-bound DID signature extension [mentioned below](#creating-extensions-for-specific-proofs). @@ -96,7 +96,7 @@ The method returns the different components of the proof, [which you can see in - The commitment proof, which proves the DIP commitment for the subject of the action, which is the DID URI. - The DID proof, which reveals parts of the DID document as specified by key IDs, proof version, and whether to include the web3name and any of its linked accounts. -Behind the scenes, the method uses the `dispatchAs` method ([and corresponding chain method](https://github.com/KILTprotocol/kilt-node/blob/4ddb8a0ef6258873458f19d3ee9dcb6d7c24e645/pallets/did/src/lib.rs#L1152)) to pass the extrinsic following the consumer's type registry. + You can now sign and submit to the consumer chain. ```typescript @@ -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). + You can then batch all the linked account transactions and authorize them using the `authorizeTx` method. diff --git a/docs/concepts/08_messaging.md b/docs/concepts/08_messaging.md index 1070ed633..104e2cf1f 100644 --- a/docs/concepts/08_messaging.md +++ b/docs/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). + ::: diff --git a/docs/develop/01_sdk/01_quickstart.md b/docs/develop/01_sdk/01_quickstart.md deleted file mode 100644 index 02bd1c8f5..000000000 --- a/docs/develop/01_sdk/01_quickstart.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -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/01_what_is_kilt.md). -- 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/docs/develop/01_sdk/02_cookbook/01_dids/00_generate_keys.md b/docs/develop/01_sdk/02_cookbook/01_dids/00_generate_keys.md deleted file mode 100644 index 1553de1f2..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/00_generate_keys.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md b/docs/develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md deleted file mode 100644 index 01c59ac8b..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/01_light_did_creation.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/02_full_did_creation.md b/docs/develop/01_sdk/02_cookbook/01_dids/02_full_did_creation.md deleted file mode 100644 index 389e8e940..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/02_full_did_creation.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/03_full_did_update.md b/docs/develop/01_sdk/02_cookbook/01_dids/03_full_did_update.md deleted file mode 100644 index 688385841..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/03_full_did_update.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/04_did_query.md b/docs/develop/01_sdk/02_cookbook/01_dids/04_did_query.md deleted file mode 100644 index 99f68590b..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/04_did_query.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/05_full_did_delete.md b/docs/develop/01_sdk/02_cookbook/01_dids/05_full_did_delete.md deleted file mode 100644 index 4e4232956..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/05_full_did_delete.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/06_full_did_tx.md b/docs/develop/01_sdk/02_cookbook/01_dids/06_full_did_tx.md deleted file mode 100644 index ace83349e..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/06_full_did_tx.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/07_did_signature.md b/docs/develop/01_sdk/02_cookbook/01_dids/07_did_signature.md deleted file mode 100644 index 7c6659fb4..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/07_did_signature.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/08_did_export.md b/docs/develop/01_sdk/02_cookbook/01_dids/08_did_export.md deleted file mode 100644 index 8b53f209d..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/08_did_export.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/01_dids/_category_.json b/docs/develop/01_sdk/02_cookbook/01_dids/_category_.json deleted file mode 100644 index cd4de73d6..000000000 --- a/docs/develop/01_sdk/02_cookbook/01_dids/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "KILT DIDs", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/02_cookbook/02_web3names/01_claim.md b/docs/develop/01_sdk/02_cookbook/02_web3names/01_claim.md deleted file mode 100644 index 88f687ba8..000000000 --- a/docs/develop/01_sdk/02_cookbook/02_web3names/01_claim.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/02_web3names/02_credential_query.md b/docs/develop/01_sdk/02_cookbook/02_web3names/02_credential_query.md deleted file mode 100644 index 9213f6810..000000000 --- a/docs/develop/01_sdk/02_cookbook/02_web3names/02_credential_query.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/02_web3names/03_release.md b/docs/develop/01_sdk/02_cookbook/02_web3names/03_release.md deleted file mode 100644 index a22050964..000000000 --- a/docs/develop/01_sdk/02_cookbook/02_web3names/03_release.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/02_web3names/04_query.md deleted file mode 100644 index 8112e5886..000000000 --- a/docs/develop/01_sdk/02_cookbook/02_web3names/04_query.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -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](../01_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/docs/develop/01_sdk/02_cookbook/02_web3names/_category_.json deleted file mode 100644 index 6dab303b4..000000000 --- a/docs/develop/01_sdk/02_cookbook/02_web3names/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "web3names", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/02_cookbook/03_account_linking/01_link.md b/docs/develop/01_sdk/02_cookbook/03_account_linking/01_link.md deleted file mode 100644 index db6735186..000000000 --- a/docs/develop/01_sdk/02_cookbook/03_account_linking/01_link.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/03_account_linking/02_account_name.md b/docs/develop/01_sdk/02_cookbook/03_account_linking/02_account_name.md deleted file mode 100644 index ed7357fb6..000000000 --- a/docs/develop/01_sdk/02_cookbook/03_account_linking/02_account_name.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/03_account_linking/03_unlink.md b/docs/develop/01_sdk/02_cookbook/03_account_linking/03_unlink.md deleted file mode 100644 index 08711f178..000000000 --- a/docs/develop/01_sdk/02_cookbook/03_account_linking/03_unlink.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/03_account_linking/_category_.json b/docs/develop/01_sdk/02_cookbook/03_account_linking/_category_.json deleted file mode 100644 index ac71ff896..000000000 --- a/docs/develop/01_sdk/02_cookbook/03_account_linking/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "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/docs/develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md deleted file mode 100644 index 12d3aba54..000000000 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -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/05_credentials/02_ctypes.md). - -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](../01_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/docs/develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md deleted file mode 100644 index bd602126f..000000000 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md deleted file mode 100644 index 1a53d3755..000000000 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/03_attestation_creation.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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](../01_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/docs/develop/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md deleted file mode 100644 index facd14d49..000000000 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/04_presentation_creation.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md b/docs/develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md deleted file mode 100644 index 480cc236d..000000000 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/05_presentation_verification.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md b/docs/develop/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md deleted file mode 100644 index da6ff398b..000000000 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/06_credential_revocation.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/04_claiming/_category_.json b/docs/develop/01_sdk/02_cookbook/04_claiming/_category_.json deleted file mode 100644 index 21073c229..000000000 --- a/docs/develop/01_sdk/02_cookbook/04_claiming/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "KILT Credentials", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md b/docs/develop/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md deleted file mode 100644 index 2bd743f12..000000000 --- a/docs/develop/01_sdk/02_cookbook/05_public_credentials/01_credential_issuance.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -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/05_credentials/02_ctypes.md diff --git a/docs/develop/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md b/docs/develop/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md deleted file mode 100644 index 925becd7f..000000000 --- a/docs/develop/01_sdk/02_cookbook/05_public_credentials/02_credential_retrieval.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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-its-identifier), 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/04_asset_dids.md diff --git a/docs/develop/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md b/docs/develop/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md deleted file mode 100644 index 23f9a79f9..000000000 --- a/docs/develop/01_sdk/02_cookbook/05_public_credentials/03_credential_revocation.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/05_public_credentials/_category_.json b/docs/develop/01_sdk/02_cookbook/05_public_credentials/_category_.json deleted file mode 100644 index ddf9ba6eb..000000000 --- a/docs/develop/01_sdk/02_cookbook/05_public_credentials/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Public Credentials and AssetDIDs", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/02_cookbook/06_messaging/01_messaging.md b/docs/develop/01_sdk/02_cookbook/06_messaging/01_messaging.md deleted file mode 100644 index 406b53343..000000000 --- a/docs/develop/01_sdk/02_cookbook/06_messaging/01_messaging.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/06_messaging/02_replay_protection.md b/docs/develop/01_sdk/02_cookbook/06_messaging/02_replay_protection.md deleted file mode 100644 index 4c5d93b87..000000000 --- a/docs/develop/01_sdk/02_cookbook/06_messaging/02_replay_protection.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/06_messaging/_category_.json b/docs/develop/01_sdk/02_cookbook/06_messaging/_category_.json deleted file mode 100644 index 2c3437f16..000000000 --- a/docs/develop/01_sdk/02_cookbook/06_messaging/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Messaging", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/02_cookbook/07_signCallback.md b/docs/develop/01_sdk/02_cookbook/07_signCallback.md deleted file mode 100644 index e704093ab..000000000 --- a/docs/develop/01_sdk/02_cookbook/07_signCallback.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md b/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md deleted file mode 100644 index 7b44f9eee..000000000 --- a/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/01_backward_compatibility.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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/KILT-Foundation/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/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json b/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json deleted file mode 100644 index a58847a1c..000000000 --- a/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Upgrading to v0.29", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md b/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md deleted file mode 100644 index 810b3c4c0..000000000 --- a/docs/develop/01_sdk/02_cookbook/08_upgrading_to_v0_29/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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/docs/develop/01_sdk/02_cookbook/_category_.json deleted file mode 100644 index 3eda769a1..000000000 --- a/docs/develop/01_sdk/02_cookbook/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Cookbook", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/03_chain_setup/01_standalone_setup.md b/docs/develop/01_sdk/03_chain_setup/01_standalone_setup.md deleted file mode 100644 index 5ba705d44..000000000 --- a/docs/develop/01_sdk/03_chain_setup/01_standalone_setup.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -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/docs/develop/01_sdk/03_chain_setup/02_peregrine_setup.md b/docs/develop/01_sdk/03_chain_setup/02_peregrine_setup.md deleted file mode 100644 index 375b744eb..000000000 --- a/docs/develop/01_sdk/03_chain_setup/02_peregrine_setup.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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://substratefaucet.xyz/kilt). - -## 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. -For a full list of deployments and services, take a look [here](../../02_chain/03_deployments.md). diff --git a/docs/develop/01_sdk/03_chain_setup/03_prod_chain_setup.md b/docs/develop/01_sdk/03_chain_setup/03_prod_chain_setup.md deleted file mode 100644 index 121c34335..000000000 --- a/docs/develop/01_sdk/03_chain_setup/03_prod_chain_setup.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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/docs/develop/01_sdk/03_chain_setup/_category_.json b/docs/develop/01_sdk/03_chain_setup/_category_.json deleted file mode 100644 index 88da89b23..000000000 --- a/docs/develop/01_sdk/03_chain_setup/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Chain Setup for Development", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/03_chain_setup/index.md b/docs/develop/01_sdk/03_chain_setup/index.md deleted file mode 100644 index 76cb5d16e..000000000 --- a/docs/develop/01_sdk/03_chain_setup/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -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) which will provide you with all necessary means to create and run a basic script. diff --git a/docs/develop/01_sdk/04_integrate/01_nodejs.md b/docs/develop/01_sdk/04_integrate/01_nodejs.md deleted file mode 100644 index 57a4acf2e..000000000 --- a/docs/develop/01_sdk/04_integrate/01_nodejs.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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/docs/develop/01_sdk/04_integrate/02_browser.md b/docs/develop/01_sdk/04_integrate/02_browser.md deleted file mode 100644 index b0a291ec4..000000000 --- a/docs/develop/01_sdk/04_integrate/02_browser.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -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/docs/develop/01_sdk/04_integrate/03_distillery.md b/docs/develop/01_sdk/04_integrate/03_distillery.md deleted file mode 100644 index f61dd9fb2..000000000 --- a/docs/develop/01_sdk/04_integrate/03_distillery.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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/docs/develop/01_sdk/04_integrate/_category_.json b/docs/develop/01_sdk/04_integrate/_category_.json deleted file mode 100644 index 6ca72770c..000000000 --- a/docs/develop/01_sdk/04_integrate/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Integrate the KILT SDK", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/01_sdk/04_integrate/index.md b/docs/develop/01_sdk/04_integrate/index.md deleted file mode 100644 index bac181a29..000000000 --- a/docs/develop/01_sdk/04_integrate/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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/docs/develop/01_sdk/05_troubleshoot.md b/docs/develop/01_sdk/05_troubleshoot.md deleted file mode 100644 index 369a3e616..000000000 --- a/docs/develop/01_sdk/05_troubleshoot.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -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/docs/develop/01_sdk/_category_.json b/docs/develop/01_sdk/_category_.json deleted file mode 100644 index 13d35e4e8..000000000 --- a/docs/develop/01_sdk/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "SDK", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/02_browser.md b/docs/develop/02_browser.md new file mode 100644 index 000000000..b4f948d72 --- /dev/null +++ b/docs/develop/02_browser.md @@ -0,0 +1,4 @@ +--- +id: browser +title: Browser +--- diff --git a/docs/develop/03_chain_setup/01_standalone_setup.md b/docs/develop/03_chain_setup/01_standalone_setup.md new file mode 100644 index 000000000..d9b7be250 --- /dev/null +++ b/docs/develop/03_chain_setup/01_standalone_setup.md @@ -0,0 +1,4 @@ +--- +id: standalone-setup +title: Standalone Setup +--- diff --git a/docs/develop/03_chain_setup/02_peregrine_setup.md b/docs/develop/03_chain_setup/02_peregrine_setup.md new file mode 100644 index 000000000..b0b9c1d8d --- /dev/null +++ b/docs/develop/03_chain_setup/02_peregrine_setup.md @@ -0,0 +1,4 @@ +--- +id: peregrine-setup +title: Peregrine Setup +--- diff --git a/docs/develop/03_chain_setup/03_prod_chain_setup.md b/docs/develop/03_chain_setup/03_prod_chain_setup.md new file mode 100644 index 000000000..dde72e837 --- /dev/null +++ b/docs/develop/03_chain_setup/03_prod_chain_setup.md @@ -0,0 +1,4 @@ +--- +id: production-setup +title: Production Setup +--- diff --git a/docs/develop/03_chain_setup/_category_.json b/docs/develop/03_chain_setup/_category_.json new file mode 100644 index 000000000..e69de29bb diff --git a/docs/develop/03_chain_setup/index.md b/docs/develop/03_chain_setup/index.md new file mode 100644 index 000000000..030bed7d4 --- /dev/null +++ b/docs/develop/03_chain_setup/index.md @@ -0,0 +1,4 @@ +--- +id: title +title: dev-chain-setup +--- diff --git a/docs/develop/03_credentials.md b/docs/develop/03_credentials.md new file mode 100644 index 000000000..a460e2868 --- /dev/null +++ b/docs/develop/03_credentials.md @@ -0,0 +1,4 @@ +--- +id: credentials +title: Credentials +--- diff --git a/docs/develop/03_workshop/01_welcome.md b/docs/develop/03_workshop/01_welcome.md deleted file mode 100644 index 91c6cb0af..000000000 --- a/docs/develop/03_workshop/01_welcome.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -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! diff --git a/docs/develop/03_workshop/02_setup.md b/docs/develop/03_workshop/02_setup.md deleted file mode 100644 index 0aea51580..000000000 --- a/docs/develop/03_workshop/02_setup.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -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://substratefaucet.xyz/kilt). - -## 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! diff --git a/docs/develop/03_workshop/03_overview.md b/docs/develop/03_workshop/03_overview.md deleted file mode 100644 index bcb80e36d..000000000 --- a/docs/develop/03_workshop/03_overview.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -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_cookbook/01_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/docs/develop/03_workshop/04_attester/01_account.md deleted file mode 100644 index f4c1f30da..000000000 --- a/docs/develop/03_workshop/04_attester/01_account.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -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://substratefaucet.xyz/kilt) and request tokens for your `
`. - -::: diff --git a/docs/develop/03_workshop/04_attester/02_did.md b/docs/develop/03_workshop/04_attester/02_did.md deleted file mode 100644 index fa4bc03cd..000000000 --- a/docs/develop/03_workshop/04_attester/02_did.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -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](../../../develop/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/docs/develop/03_workshop/04_attester/03_ctype.md b/docs/develop/03_workshop/04_attester/03_ctype.md deleted file mode 100644 index 417885275..000000000 --- a/docs/develop/03_workshop/04_attester/03_ctype.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -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/05_credentials/02_ctypes.md). -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/docs/develop/03_workshop/04_attester/_category_.json b/docs/develop/03_workshop/04_attester/_category_.json deleted file mode 100644 index 6c31a6f8e..000000000 --- a/docs/develop/03_workshop/04_attester/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "🏒 Attester", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/03_workshop/04_attester/index.md b/docs/develop/03_workshop/04_attester/index.md deleted file mode 100644 index 5da9f6d70..000000000 --- a/docs/develop/03_workshop/04_attester/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -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/docs/develop/03_workshop/05_claimer/01_did.md b/docs/develop/03_workshop/05_claimer/01_did.md deleted file mode 100644 index e6abbde43..000000000 --- a/docs/develop/03_workshop/05_claimer/01_did.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -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](../../../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. - -::: - -## 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/docs/develop/03_workshop/05_claimer/02_request.md b/docs/develop/03_workshop/05_claimer/02_request.md deleted file mode 100644 index 8dbc992ff..000000000 --- a/docs/develop/03_workshop/05_claimer/02_request.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -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/docs/develop/03_workshop/05_claimer/_category_.json b/docs/develop/03_workshop/05_claimer/_category_.json deleted file mode 100644 index 5656d275e..000000000 --- a/docs/develop/03_workshop/05_claimer/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "πŸ‘€ Claimer", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/03_workshop/05_claimer/index.md b/docs/develop/03_workshop/05_claimer/index.md deleted file mode 100644 index 0c9431ac7..000000000 --- a/docs/develop/03_workshop/05_claimer/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -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/docs/develop/03_workshop/06_attestation.md b/docs/develop/03_workshop/06_attestation.md deleted file mode 100644 index a433f6110..000000000 --- a/docs/develop/03_workshop/06_attestation.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -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/docs/develop/03_workshop/07_verification.md b/docs/develop/03_workshop/07_verification.md deleted file mode 100644 index e0a154733..000000000 --- a/docs/develop/03_workshop/07_verification.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -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/docs/develop/03_workshop/08_done.md b/docs/develop/03_workshop/08_done.md deleted file mode 100644 index ff6558e53..000000000 --- a/docs/develop/03_workshop/08_done.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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/docs/develop/03_workshop/_category_.json b/docs/develop/03_workshop/_category_.json deleted file mode 100644 index 65d6b088b..000000000 --- a/docs/develop/03_workshop/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Workshop", - "collapsible": true, - "collapsed": true -} diff --git a/docs/develop/04_distillery.md b/docs/develop/04_distillery.md new file mode 100644 index 000000000..96c7318f4 --- /dev/null +++ b/docs/develop/04_distillery.md @@ -0,0 +1,4 @@ +--- +id: distillery +title: Distillery +--- diff --git a/docs/develop/07_dApp/02_well-known-did-config.md b/docs/develop/07_dApp/02_well-known-did-config.md index 825387701..63284055c 100644 --- a/docs/develop/07_dApp/02_well-known-did-config.md +++ b/docs/develop/07_dApp/02_well-known-did-config.md @@ -102,9 +102,9 @@ The extension will make an HTTP GET request to the following URI, and your dapp `/.well-known/did-configuration.json` How the file is hosted depends on your project setup and is out of scope for this guide. - + diff --git a/docs/sdk/01_quickstart.md b/docs/sdk/01_quickstart.md new file mode 100644 index 000000000..50476322c --- /dev/null +++ b/docs/sdk/01_quickstart.md @@ -0,0 +1,4 @@ +--- +id: quickstart +title: Quickstart +--- diff --git a/docs/sdk/02_tutorial/02_tutorial.md b/docs/sdk/02_tutorial/02_tutorial.md new file mode 100644 index 000000000..4603aec81 --- /dev/null +++ b/docs/sdk/02_tutorial/02_tutorial.md @@ -0,0 +1,4 @@ +--- +id: tutorial +title: Tutorial +--- diff --git a/docs/sdk/03_accounts.md b/docs/sdk/03_accounts.md new file mode 100644 index 000000000..6f337eba7 --- /dev/null +++ b/docs/sdk/03_accounts.md @@ -0,0 +1,4 @@ +--- +id: accounts +title: Accounts +--- diff --git a/docs/sdk/04_dids.md b/docs/sdk/04_dids.md new file mode 100644 index 000000000..fff66ad47 --- /dev/null +++ b/docs/sdk/04_dids.md @@ -0,0 +1,4 @@ +--- +id: dids +title: DID +--- diff --git a/docs/sdk/05_claiming/05_claiming.md b/docs/sdk/05_claiming/05_claiming.md new file mode 100644 index 000000000..add7c605f --- /dev/null +++ b/docs/sdk/05_claiming/05_claiming.md @@ -0,0 +1,4 @@ +--- +id: claiming +title: Claiming +--- diff --git a/docs/sdk/05_credentials.md b/docs/sdk/05_credentials.md new file mode 100644 index 000000000..aff1b32d4 --- /dev/null +++ b/docs/sdk/05_credentials.md @@ -0,0 +1,4 @@ +--- +id: credentials +title: credentials +--- diff --git a/docs/sdk/06_upgrading.md b/docs/sdk/06_upgrading.md new file mode 100644 index 000000000..45ad25026 --- /dev/null +++ b/docs/sdk/06_upgrading.md @@ -0,0 +1,4 @@ +--- +id: upgrading +title: Upgrading +--- diff --git a/docusaurus.config.js b/docusaurus.config.js index c605a9dc5..9b4345877 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -48,7 +48,7 @@ module.exports = { isCloseable: true, }, navbar: { - title: '', // no title since the Name is already in the logo + title: '', logo: { alt: 'KILT Logo', src: 'img/logo_light.svg', @@ -62,22 +62,53 @@ module.exports = { }, { type: 'dropdown', - label: 'Develop', + label: 'SDK', items: [ { type: 'doc', - docId: 'develop/sdk/quickstart', - label: 'SDK Documentation', + docId: 'sdk/quickstart', + label: 'SDK Quickstart', }, { type: 'doc', - docId: 'develop/chain/introduction', - label: 'Blockchain Documentation', + docId: 'sdk/tutorial/tutorial', + label: 'Tutorial', + }, + { + type: 'doc', + docId: 'sdk/accounts', + label: 'Accounts', + }, + { + type: 'doc', + docId: 'sdk/dids', + label: 'DIDs', + }, + { + type: 'doc', + docId: 'sdk/claiming/claiming', + label: 'Claiming', + }, + { + type: 'doc', + docId: 'sdk/credentials', + label: 'Credentials', + }, + { + type: 'doc', + docId: 'sdk/upgrading', + label: 'Upgrading', }, + ], + }, + { + type: 'dropdown', + label: 'Develop', + items: [ { type: 'doc', - docId: 'develop/workshop/welcome', - label: 'Workshop', + docId: 'develop/chain/introduction', + label: 'Blockchain', }, { type: 'doc', @@ -87,7 +118,7 @@ module.exports = { { type: 'doc', docId: 'develop/specifications', - label: 'Technical Specifications', + label: 'Specifications', }, { type: 'doc', @@ -97,7 +128,7 @@ module.exports = { { type: 'doc', docId: 'develop/dApp/welcome', - label: 'DApp Documentation', + label: 'DApp Docs', }, { type: 'doc',