Describe a resource

Reading time: 11 min

Now that you know what a DID and a Verifiable Credential are, and what they mean for the Axone 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 Axone protocol).

Here are the 4 steps involved:

Steps to describe a resource in the Dataverse

We'll take 2 examples in this tutorial:

The dataset Crime Data from 2020 to Present
The storage service IPFS

info

Prerequisite:

Install the Axone CLI to interact with the protocol
Ensure you have npm installed on your system. You can follow the installation guide here.
Install the json-cli with the following command:

npm install -g jsonld-cli

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 Axone 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 Axone 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. The --keyring-backend test command parameter is intended for use in testing environments. However, it is not recommended for production applications where the security of private keys is a highest priority.

For secure keyring setup in production environments, refer to the Cosmos SDK doc. This documentation provides a comprehensive guide to establishing a secure keyring configuration suitable for production use.

Avoid using the --keyring-backend test option in production, as it leaves private keys unencrypted on the file system, posing a potential security risk.

​​# 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:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5.

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.

# Replace "crime-data-lapd" with your wallet name
okp4d keys show crime-data-lapd --keyring-backend test
- address: okp413e4exyqr5chxz5qlg2wpqr5ehmq90q2dgy753z
  name: crime-data-lapd
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"Aj8dI0OJWxTGM4gYd89cB8Qzi95DNxR/3F9DAPaNU0Mg"}'
  type: local

Reiterate the command to create a wallet to store the IPFS and Issuer's identities.

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 according to the nature of the resource you describe.

For the dataset, instantiate the template credential-dataset-description.
For the service, instantiate the template credential-digital-service-description.

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:

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.

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/"
    ],
    "type": ["VerifiableCredential","DatasetDescriptionCredential"],
    "id": "https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/5d29ea71-003f-46e7-a74d-d8d598629ed8",
    "credentialSubject": {
        "id": "did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5",
        "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/v3/thesaurus/media-type/text_csv",
        "hasGeoCoverage": "https://w3id.org/okp4/ontology/v3/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/v3/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.
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. Put the URI of the selected format in the jsonld.
hasGeoCoverage: select the geographical zone concerned by your dataset in the Thesaurus Area-code. 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. 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.

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/

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/okp4/ontology/v3/schema/credential/digital-service/description/"
    ],
    "type": ["VerifiableCredential","DigitalServiceDescriptionCredential"],
    "id": "https://w3id.org/okp4/ontology/v3/schema/credential/digital-service/description/5a3bd610-3a5d-4a41-bc90-0e437d453220",
    "credentialSubject": {
        "id": "did:key:zQ3shhb4SvzBRLbBonsvKb3WX6WoDeKWHpsXXXMhAJETqXAfB",
        "hasCategory": "https://w3id.org/okp4/ontology/v3/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.
id: copy the did:key of the digital service
hasCategory: select the cateogry of your service in the Thesaurus Digital Service Category. 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 VCs, 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 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:

okp4d credential sign $/MY-DIRECTORY/MY-DATASET.jsonld 
    --keyring-backend test 
    --from $MY_ADDR | jsonld toRdf -q - > $MY-DATASET.nq

With:

/MY-DIRECTORY/MY-DATASET.jsonld : credential file address
MY_ADDR : issuer address
MY-DATASET.nq : name of the file with the signed credential in RDF format

Example:

okp4d credential sign ipfs-digital-service-description.jsonld 
    --keyring-backend test 
    --from issuer-okp4 | jsonld toRdf -q - > ipfs-digital-service-description.nq

You can see that there is new fields in the jsonld with the cryptographic proof.

did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/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." .
did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/hasFormat https://w3id.org/okp4/ontology/v3/thesaurus/media-type/text_csv .
did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/hasGeoCoverage https://w3id.org/okp4/ontology/v3/thesaurus/area-code/840 .
did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/hasTag "Crime" .
did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/hasTag "Los Angeles" .
did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/hasTag "Police" .
did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/hasTitle "Crime Data from 2020 to Present" .
did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/hasTopic https://w3id.org/okp4/ontology/v3/thesaurus/topic/security .
https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/5d29ea71-003f-46e7-a74d-d8d598629ed8 http://www.w3.org/1999/02/22-rdf-syntax-ns#type https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/DatasetDescriptionCredential .
https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/5d29ea71-003f-46e7-a74d-d8d598629ed8 http://www.w3.org/1999/02/22-rdf-syntax-ns#type https://www.w3.org/2018/credentials#VerifiableCredential .
https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/5d29ea71-003f-46e7-a74d-d8d598629ed8 https://w3id.org/security#proof _:b0 .
https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/5d29ea71-003f-46e7-a74d-d8d598629ed8 https://www.w3.org/2018/credentials#credentialSubject did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5 .
https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/5d29ea71-003f-46e7-a74d-d8d598629ed8 https://www.w3.org/2018/credentials#issuanceDate "2024-02-02T09:45:43.475304+01:00"^^http://www.w3.org/2001/XMLSchema#dateTime .
https://w3id.org/okp4/ontology/v3/schema/credential/dataset/description/5d29ea71-003f-46e7-a74d-d8d598629ed8 https://www.w3.org/2018/credentials#issuer did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3 .
_:b1 http://purl.org/dc/terms/created "2024-04-03T09:19:27.543122+02:00"^^http://www.w3.org/2001/XMLSchema#dateTime _:b0 .
_:b1 http://www.w3.org/1999/02/22-rdf-syntax-ns#type https://w3id.org/security#EcdsaSecp256k1Signature2019 _:b0 .
_:b1 https://w3id.org/security#jws "eyJhbGciOiJ1bmtub3duIiwiYjY0IjpmYWxzZSwiY3JpdCI6WyJiNjQiXX0..8L1rZp9tfVh-cp0RXBx-IboTqmX7My6w5W4rKI3c1HxA82unFSdAdwKBXE4sBrYYHFCcTdnM13-WKpjbCVYqhw" _:b0 .
_:b1 https://w3id.org/security#proofPurpose https://w3id.org/security#assertionMethod _:b0 .
_:b1 https://w3id.org/security#verificationMethod did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3#zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3 _:b0 .

The VC is now in the hands of the Holder. Note that it is possible that the Issuer is also the Holder.

The Axone blockchain can only register VCs in N-Quads format.

Step 4: Register the credentials in the blockchain

The final step is to register the VCs in the Axone 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 Axone blockchain, you must pay fees in $AXONE at each transaction.

okp4d tx wasm execute $CONTRACT_ADDR \ 
    --node "https://api.drunemeton.okp4.network:443/rpc" \
    --chain-id okp4-drunemeton-1 \ 
    --from $MY_ADDR \ 
    --keyring-backend test
    --gas 10000000 \ "{\"submit_claims\":{\"metadata\": \"$(cat $MY-DATASET.nq | base64)\"}}"

With:

CONTRACT_ADDR : dataverse contract address (always the same) - For the Drunemeton testnet use okp418cszlvm6pze0x9sz32qnjq4vtd45xehqs8dq7cwy8yhq35wfnn3qvya8du
node "https://api.drunemeton.okp4.network:443/rpc" : name of the node for the Drunemeton testnet
MY_ADDR : registrant okp4 address
$MY-DATASET.nq : name of the file with the signed credential in RDF format

Example:

okp4d tx wasm execute okp418cszlvm6pze0x9sz32qnjq4vtd45xehqs8dq7cwy8yhq35wfnn3qvya8du \
    --node "https://api.drunemeton.okp4.network:443/rpc" \
    --chain-id okp4-drunemeton-1 \
    --from issuer-okp4 \
    --keyring-backend test 
    --gas 10000000 "{\"submit_claims\":{\"metadata\": \"$(cat ipfs-digital-service-description.nq | base64)\"}}"

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. Select the network (Currently Drunemeton-Testnet), click on the Search icon, and paste the transaction hash.

Example: Hash: 766627052AA0A56F56702038E54EC69491386D35E0D76A47F9D5B2321DD56C3E

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.

Describe a resource

Step 1: Create keys​

Step 2: Create the credentials​

Description of the dataset​

Description of the service​

Step 3: Sign the credentials​

Step 4: Register the credentials in the blockchain​

Step 1: Create keys

Step 2: Create the credentials

Description of the dataset

Description of the service

Step 3: Sign the credentials

Step 4: Register the credentials in the blockchain