From 6afc72825c8899238a26dc2df71131fcaf1a9a45 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Thu, 30 May 2024 16:51:30 +0200 Subject: [PATCH] DIP SDK Docs (#312) * Change web3name Signed-off-by: Chris Chinchilla * Draft Signed-off-by: Chris Chinchilla * Draft Signed-off-by: Chris Chinchilla * Draft Signed-off-by: Chris Chinchilla * Revert "Change web3name" This reverts commit a5351da92420a39828771d622e4c567a57aff7ee. * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * review Signed-off-by: Chris Chinchilla * Changes from review Signed-off-by: Chris Chinchilla * Review Signed-off-by: Chris Chinchilla * Add config details Signed-off-by: Chris Chinchilla * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * Update docs/concepts/07_dip/05_dapp_developer.md Co-authored-by: Antonio * Changes from revview Signed-off-by: Chris Chinchilla * Temp fix docs links Signed-off-by: Chris Chinchilla --------- Signed-off-by: Chris Chinchilla Co-authored-by: Antonio --- docs/concepts/07_dip/05_dapp_developer.md | 121 +++++++++++++++++- docs/develop/02_chain/04_fullnode.md | 2 +- .../01_become_a_collator/03_setup_node.md | 2 +- 3 files changed, 122 insertions(+), 3 deletions(-) diff --git a/docs/concepts/07_dip/05_dapp_developer.md b/docs/concepts/07_dip/05_dapp_developer.md index 54e840a37..7409dc288 100644 --- a/docs/concepts/07_dip/05_dapp_developer.md +++ b/docs/concepts/07_dip/05_dapp_developer.md @@ -26,8 +26,127 @@ Import the SDK into your code: import { * } from '@kiltprotocol/dip-sdk' ``` +## Example application + +This example application walks through the code you can find in the tests for the DIP SDK. + +### 1. Generate a base proof + +Start by generating the base proof for the DIP using the `[generateDipSiblingBaseProof](https://kiltprotocol.github.io/dip-sdk/functions/generateDipSiblingBaseProof.html)` method and passing the desired configuration: + +```typescript +const baseDipProof = await DipSdk.generateDipSiblingBaseProof(config) +``` + +:::info What's a base proof? +A base proof is a cross-chain state proof, revealing the parts of a DID Document stored on the KILT blockchain. +::: + +The configuration for the base proof takes the following parameters: + +- `didUri`: (Required) The DID URI of the DIP subject performing the cross-chain operation. +For example, `did:kilt:4q4QzFTs9hKh4QizLB3B7zuGYCG3QPamiBFEgwM6gTM7gK3g` +- `keyIds`: (Required) An array of verification method IDs of the DID revealed in the cross-chain operation. +- `proofVersion`: (Required) The version of the DIP proof to generate. +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). + +The configuration also has details of the provider, which in this case uses a value populated from an environment variable: + +```typescript +const providerAddress = `ws://127.0.0.1:${process.env['PROVIDER_ALICE_RPC']}` +``` + +### 2. Generate a submittable extrinsic + +The method returns the DID base proof. +You have to call a second method, the `[generateDipSubmittableExtrinsic](https://kiltprotocol.github.io/dip-sdk/functions/generateDipSubmittableExtrinsic.html)` method to generate a submittable extrinsic that includes the generated proof. + +You need to pass the following parameters: + +- The API of the consumer chain. +- The base proof. +- The call to the consumer chain. +- The DID URI. + +:::info Submittable extrinsics + +A transaction that originates from an external account and affects the state of the blockchain. +An extrinisc executes actions on the network, such as transferring funds, making governance decisions, using functionality of the parachain, or interacting with smart contracts. + +::: + +```typescript +const dipSubmittable = DipSdk.generateDipSubmittableExtrinsic({ + api: consumerApi, + baseDipProof, + call, + didUri: did.uri, +}) +``` + +The method returns the different components of the proof, [which you can see in the example code](https://github.com/KILTprotocol/dip-sdk/blob/9ad141b3757e076744ab8b2d29bcf10bbeaddd9f/tests/dip-provider-template-dip-consumer-template/develop.test.ts#L219): + +- The provider head proof, which is proof of the provider parachain header on the relay chain. +- 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 +await signAndSubmitTx(consumerApi, dipSubmittable, submitterKeypair) +``` + +### 3. Linking accounts (optional) + +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. + +```typescript +const signedLinkedAccounts = await Kilt.Did.authorizeTx( + newFullDidUri, + providerApi.tx.utility.batchAll(linkAccountTxs), + signCallback, + newSubmitterKeypair.address as KiltAddress, + { txCounter: new BN(4) } +) +``` + +## Creating extensions for specific proofs + +If you need a specific proof type for a consumer chain, then a chain developer needs to submit a PR to the SDK repository in the `src > dipProof > extensions` folder. +The extension included with the SDK adds support for a time-bound DID signature, i.e., a signature which is valid only until a certain block number on the consumer chain. + +The extension can take any form, but must return [a SCALE encoded](https://docs.substrate.io/reference/scale-codec/) object. +There's an example of how the extension does this [on GitHub](https://github.com/KILTprotocol/dip-sdk/blob/9ad141b3757e076744ab8b2d29bcf10bbeaddd9f/src/dipProof/extensions/timeBoundDidSignature.ts#L113). + +To add the extension, use the `generateDipSubmittableExtrinsic` method and pass the additional proof elements along with consumer chain specific components. + +```typescript +const dipSubmittable = DipSdk.generateDipSubmittableExtrinsic({ + additionalProofElements: + DipSdk.dipProof.extensions.timeBoundDidSignature.toChain( + crossChainDidSignature + ), + api: consumerApi, + baseDipProof, + call, + didUri: did.uri, +}) +``` + :::info Read the auto-generated [API documentation](https://kiltprotocol.github.io/dip-sdk) for more details on the methods the SDK provides. -::: \ No newline at end of file +::: diff --git a/docs/develop/02_chain/04_fullnode.md b/docs/develop/02_chain/04_fullnode.md index 39810ced4..083e32de7 100644 --- a/docs/develop/02_chain/04_fullnode.md +++ b/docs/develop/02_chain/04_fullnode.md @@ -41,7 +41,7 @@ This can either be `peregrine` or `spiritnet`. Hence, to start a full node for the Spiritnet network, the parameter would be `--chain=spiritnet`. Unfortunately, there is no hardcoded chain spec for the Peregrine network, so the full path of the chainspec file must be provided `--chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json`. -Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/develop/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. +Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/develop/chainspecs/peregrine/peregrine-paseo.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. ### Specify the Blockchain Storage Path diff --git a/docs/participate/01_staking/01_become_a_collator/03_setup_node.md b/docs/participate/01_staking/01_become_a_collator/03_setup_node.md index 42e979570..16d623a2a 100644 --- a/docs/participate/01_staking/01_become_a_collator/03_setup_node.md +++ b/docs/participate/01_staking/01_become_a_collator/03_setup_node.md @@ -74,7 +74,7 @@ This can either be `peregrine` or `spiritnet`. Hence, to start a collator node for the Spiritnet network, the parameter would be `--chain=spiritnet`. Unfortunately, there is no hardcoded chain spec for the Peregrine network, so the full path of the chainspec file must be provided `--chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json`. -Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/develop/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. +Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/develop/chainspecs/peregrine/peregrine-paseo.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. ### Specify the Blockchain Storage Path