feat: add Describe a resource

docs/academy/describe-resource.mdx

@@ -0,0 +1,276 @@
+---
+sidebar_position: 10
+sidebar_class_name: hidden
+---
+
+# Describe a resource
+
+<i>Reading time: {readingTime} min</i>
+
+Now that you know what a DID and a Verifiable Credential are, and what they mean for the OKP4 protocol, let's put them into practice! 
+
+You're a digital resource provider and you want to share a dataset or a service. First, you need to describe your resource and register it in the Dataverse (i.e. in the OKP4 protocol). 
+
+Here are the 4 steps involved: 
+
+<center>
+  <img src="/img/content/academy/describe-resource-1.webp" alt="Steps to describe a resource in the Dataverse" style={{ maxHeight: "340px" }}></img>
+</center>
+
+We'll take 2 examples in this tutorial: 
+
+- The dataset [Crime Data from 2020 to Present](https://data.lacity.org/Public-Safety/Crime-Data-from-2020-to-Present/2nrs-mtv8/about_data)
+- The storage service [IPFS](https://ipfs.tech)
+
+:::info
+Prerequisite: [Install the OKP4 CLI](https://docs.okp4.network/tutorials/cli-1#installing-the-okp4-cli) to interact with the protocol. 
+:::
+
+## Step 1: Create keys
+
+As we saw previously, all entities are identified by a DID in the Dataverse. The first step consists of creating keys and related DID for the issuer of the credentials and the resource itself. 
+
+The OKP4 Protocol can provide you keys (also called a wallet) and DID. A key pair is created to obtain a wallet to establish secure ownership and control over your assets on the OKP4 blockchain. The key pair consists of two cryptographic keys: public and private keys.
+When creating a wallet, you're typically provided with a mnemonic consisting of 12, 24, or sometimes more words. This mnemonic acts as a human-readable representation of the underlying cryptographic information. It is easier to remember and write down than the complex numbers and characters representing the private key.
+The mnemonic serves as a backup mechanism for the wallet. You can regenerate the key pair by inputting the mnemonic into any compatible wallet software to recover access to your funds.
+
+Here, we don’t create a wallet for cryptocurrency storage but for secure storage of identifiers: A wallet can securely store digital identifiers, such as proofs of identity, certificates, or other personal identification information. 
+
+:::danger
+A keyring is a secure software utility designed to store and manage credentials, such as passwords, cryptographic keys, and API tokens, in a centralized and encrypted form. `--keyring-backend test` is a command used to configure a keyring in test mode, which is helpful for development and testing but not for applications where private key security is a major concern. Be careful; this keyring is unsafe as the private keys are unencrypted on the file system.
+:::
+
+```bash
+​​# Create a new key. Replace "crime-data-lapd" with another name
+okp4d keys add crime-data-lapd --keyring-backend test
+```
+
+:::danger
+If you create a new key pair, the terminal displays a list of 24 words. Store this mnemonic phrase in a safe place.
+:::
+
+Get the list of all your keys stored locally especially the new one. You can see that the DID related to this key is `did:key:zQ3shcLHSPRYUJzAPzS5mrxVy8rpbfmu6S3x2J2gDWPAbRx92`.
+
+```bash
+okp4d keys list --keyring-backend test
+
+address: okp413e4exyqr5chxz5qlg2wpqr5ehmq90q2dgy753z
+  did: did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5
+  name: crime-data-lapd
+  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"Aj8dI0OJWxTGM4gYd89cB8Qzi95DNxR/3F9DAPaNU0Mg"}'
+  type: local
+```
+
+You can also use the command `okp4d show` to directly find information about a particular wallet. 
+
+```bash
+# Replace "issuer-okp4" with your wallet name
+okp4d keys show issuer-okp4 --keyring-backend test
+
+- address: okp41ysl9yllv40kfygcdfqj7c9n2a5c5zpmgku8ufg
+  name: issuer-okp4
+  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A7lWVpVRnv82dt3LDLsDkCas/rth0NXMp1N2yupOpf/8"}'
+  type: local
+```
+Reiterate the command to create a wallet to store the issuer's identity. 
+
+So now we have the following information: 
+
+|  | Crime dataset | 
+|--------------|------|
+| Name of the wallet | crime-data-lapd |
+| Public key  | okp413e4exyqr5chxz5qlg2wpqr5ehmq90q2dgy753z | 
+| DID  | did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 |
+
+|  | IPFS Storage | 
+|--------------|------|
+| Name of the wallet | digital-resource-ipfs |
+| Public key | okp41mlq7l9snuy9m0cznyrv3emn9wsndzle5v4j5q4 |
+| DID  | did:key:zQ3shhb4SvzBRLbBonsvKb3WX6WoDeKWHpsXXXMhAJETqXAfB | 
+
+|  | Issuer |
+|--------------|------|
+| Name of the wallet | issuer-okp4 |
+| Public key  | okp41ysl9yllv40kfygcdfqj7c9n2a5c5zpmgku8ufg |
+| DID  | did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3 |
+
+:::note
+In the future, you will be able to use any key provider, such as Cheqd.  
+:::
+
+## Step 2: Create the credentials
+
+Find the credential templates you need in the [Ontology documentation](https://docs.okp4.network/ontology/schemas) according to the nature of the resource you describe. 
+
+For the dataset, instantiate the template [credential-dataset-description](https://github.com/okp4/ontology/blob/main/src/example/dataset/crime-dataset-description.jsonld).  
+For the service, instantiate the template [credential-digital-service-description](https://github.com/okp4/ontology/blob/main/src/example/digital-service/ipfs-digital-service-description.jsonld).
+
+:::info
+Would you like to describe your dataset with other properties? You can create your template of credentials. Don’t directly add these properties in the DatasetDescriptionCredential as defined in the Ontology. 
+:::
+
+### Description of the dataset 
+
+Here are the following metadata of the dataset [Crime Data from 2020 to Present](https://data.lacity.org/Public-Safety/Crime-Data-from-2020-to-Present/2nrs-mtv8/about_data):
+
+| Title | Crime Data from 2020 to Present | 
+|--------------|------|
+| Description | This dataset reflects incidents of crime in the City of Los Angeles dating back to 2020. This data is transcribed from original crime reports that are typed on paper and therefore there may be some inaccuracies within the data. Some location fields with missing data are noted as (0°, 0°). Address fields are only provided to the nearest hundred block in order to maintain privacy. This data is as accurate as the data in the database. | 
+| Format  | CSV | 
+| Geographical coverage | USA | 
+| Image | NA |
+| Tags | Crime, Police, Los Angeles |
+| Temporal coverage | 2020 to Present |
+| Topic | Security |
+
+Let’s fill in the template.
+
+```bash
+{
+    "@context": [
+        "https://www.w3.org/2018/credentials/v1",
+        "https://w3id.org/okp4/ontology/v$major/schema/credential/dataset/description/"
+    ],
+    "type": "VerifiableCredential",
+    "id": "https://w3id.org/okp4/ontology/v$major/schema/credential/dataset/description/d1120529-3242-4fa8-ac7c-a99abc3fc73e",
+    "credentialSubject": {
+        "id": "did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5",
+        "type": "DatasetDescriptionCredential",
+        "hasDescription": "This dataset reflects incidents of crime in the City of Los Angeles dating back to 2020. This data is transcribed from original crime reports that are typed on paper and therefore there may be some inaccuracies within the data. Some location fields with missing data are noted as (0°, 0°). Address fields are only provided to the nearest hundred block in order to maintain privacy. This data is as accurate as the data in the database.",
+        "hasFormat": "https://w3id.org/okp4/ontology/v$major/thesaurus/media-type/text_csv",
+        "hasGeoCoverage": "https://w3id.org/okp4/ontology/v$major/thesaurus/area-code/840",
+        "hasTag": [
+            "Crime",
+            "Police",
+            "Los Angeles"
+        ],
+        "hasTemporalCoverage": "2020-01-01T00:00:00.0000+01:00/2024-02-02T00:00:00.00000+01:00",
+        "hasTitle": "Crime Data from 2020 to Present",
+        "hasTopic": "https://w3id.org/okp4/ontology/v$major/thesaurus/topic/security"
+    },
+    "issuanceDate": "2024-02-02T09:45:43.475304+01:00",
+    "issuer": {
+        "id": "did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3",
+        "name": "OKP4"
+    }
+}
+```
+
+Fields to modify:
+
+- `id` (in @context): change the UUID at the end of the URI. You can generate a new UUID with this [tool](https://www.uuidgenerator.net). 
+- `id`: copy the did:key of the dataset
+- `hasDescription`: fill in the description of the dataset
+- `hasFormat`: select the format of your dataset in the [Thesaurus Media Type](https://github.com/okp4/ontology/blob/main/src/thesaurus/media-type.ttl). Put the URI of the selected format in the jsonld. 
+- `hasGeoCoverage`: select the geographical zone concerned by your dataset in the [Thesaurus Area-code](https://github.com/okp4/ontology/blob/main/src/thesaurus/area-code.ttl). Put the URI of the selected zone in the jsonld. 
+- `hasTag`: fill in a list of tags
+- `hasTemporalCoverage': change the start and end date of the period concerned by your dataset
+- `hasTitle`: fill in the title of the dataset
+- `hasTopic`: select the topic concerned by your dataset in the [Thesaurus Topic](https://github.com/okp4/ontology/blob/main/src/thesaurus/topic.ttl). Put the URI of the selected topic in the jsonld. 
+- `issuanceDate`: update the date for Today
+- `id` (issuer): copy the did:key of the issuer
+- `name`: put the issuer's name (string). 
+
+You can remove some properties if they are not relevant to your dataset. 
+
+### Description of the service 
+
+Here are the following metadata of the service [IPFS](https://ipfs.tech).
+
+| Title | IPFS | 
+|--------------|------|
+| Description | IPFS is a decentralized protocol designed to facilitate the storage, sharing, and retrieval of files on a global scale. | 
+| Category | Storage | 
+| Image | NA |
+| Publisher | OKP4 |
+| Tags | Storage Cloud Peer-to-peer |
+| Webpage | https://docs.ipfs.tech/ |
+
+```bash
+{
+    "@context": [
+        "https://www.w3.org/2018/credentials/v1",
+        "https://w3id.org/okp4/ontology/v$major/schema/credential/digital-service/description/"
+    ],
+    "type": "VerifiableCredential",
+    "id": "https://w3id.org/okp4/ontology/v$major/schema/credential/digital-service/description/72cab400-5bd6-4eb4-8605-a5ee8c1a45c9",
+    "credentialSubject": {
+        "id": "did:key:zQ3shhb4SvzBRLbBonsvKb3WX6WoDeKWHpsXXXMhAJETqXAfB",
+        "type": "DigitalServiceDescriptionCredential",
+        "hasCategory": "https://w3id.org/okp4/ontology/v$major/thesaurus/digital-service-category/Storage",
+        "hasDescription": "IPFS is a decentralized protocol designed to facilitate the storage, sharing, and retrieval of files on a global scale",
+        "hasPublisher": "IPFS",
+        "hasTag": [
+            "Storage",
+            "Peer-to-peer",
+            "Cloud"
+        ],
+        "hasTitle": "IPFS",
+        "hasWebpage": "https://docs.ipfs.tech/"
+    },
+    "issuanceDate": "2024-01-22T09:28:43.475304+01:00",
+    "issuer": {
+        "id": "did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3",
+        "name": "OKP4"
+    }
+}
+```
+
+Fields to modify:
+
+- `id` (in @context): change the UUID at the end of the URI. You can generate a new UUID with this [tool](https://www.uuidgenerator.net). 
+- `id`: copy the did:key of the digital service
+- `hasCategory`: select the cateogry of your service in the [Thesaurus Digital Service Category](https://github.com/okp4/ontology/blob/main/src/thesaurus/digital-service-category.ttl). Put the URI of the selected format in the jsonld. 
+- `hasDescription`: fill in the description of the service
+- `hasPublisher': fill in the name of the entity primarily responsible for making the Digital Service available
+- `hasTag`: fill in a list of tags
+- `hasTitle`: fill in the title of the service
+- `hasWebpage`: fill in the URL of the service’s webpage
+- `id` (issuer): copy the did:key of the issuer
+- `name`: put the issuer's name (string). 
+
+## Step 3: Sign the credentials
+
+Now that you have created the VC, you will sign them. 
+
+Signing a verifiable credential involves creating a digital signature using cryptographic techniques. This signature is unique to both the document (in this case, the credential) and the signer's private key, making it nearly impossible to forge. The private key is kept secret by the signer, while the corresponding public key is made available for anyone wishing to verify the signature's authenticity.
+
+By signing the credential, any alteration to the credential's data after it has been signed will invalidate the signature. This ensures the data has not been tampered with and remains as it was when issued.
+
+To sign your VC, use this command: 
+
+COMMANDE A AJOUTER
+
+You can see that there is a new field in the jsonld with the cryptographic proof. 
+
+AJOUTER RESULTAT
+
+The VC is now in the hands of the Holder. Note that it is possible that the Issuer is also the Holder. 
+
+The OKP4 blockchain can only register VCs in N-Quads format. Then, you must convert the jsonld files in N-Quads. You can use this tool: https://transform.tools/jsonld-to-nquads .
+
+## Step 4: Register the credentials in the blockchain
+
+The final step is to register the VCs in the OKP4 blockchain by submitting them to the Dataverse smart contract. It’s the role of the Registrant (who can be the Holder or another entity). 
+
+:::info
+Note that as you interact with the OKP4 blockchain, you must pay fees in $KNOW at each transaction.
+::: 
+
+```bash
+# okp4d tx wasm execute $CONTRACT_ADDR \ --from $MY_ADDR \ --gas 10000000 \ "{\"submit_claims\":{\"metadata\": \"$(cat vc.nq | base64)\"}}"
+```
+
+With:
+
+- `CONTRACT_ADDR` : dataverse contract address (always the same)  
+- `MY_ADDR` : registrant okp4 address  
+- `vc.nq` : name of the verifiable credential signed in RDF in N-Quads format  
+
+The Protocol will check the signature and if the public key corresponds to the proof in the VC, the VC is registered in the smart contract (Cognitarium). 
+
+The command returns the hash of the transaction. You can find more details of this transaction in the [Explorer](https://explore.okp4.network/). Select the network (Currently Drunemeton-Testnet), click on the Search icon, and paste the transaction hash.  
+
+:::warning
+Remember, the Resource Governance VC ensures the existence of a resource in the protocol: a resource or zone exists in the protocol only if governance is attached to it. Let’s do it on the next page. 
+:::