Describe a resource
Welcome to the Axone Quickstart Guide. In this guide, you'll learn how to interact with the Axone Protocol and harness its powerful features to manage and share AI resources effectively.
If you have never interacted with a Cosmos SDK world, you might want to check out these guides first to get familiar with Keplr and CLI before getting started with Axone.
We'll start by describing a resource—a fundamental step that allows you to define and register any digital asset within the Axone ecosystem. This process sets the foundation for resource governance, collaboration, and seamless integration into AI workflows. Let's begin by understanding how to describe a resource accurately to unlock the full potential of Axone Protocol.
Here are the 4 steps involved:
We'll take 2 examples in this tutorial:
- The dataset Crime Data from 2020 to Present
- The storage service IPFS
Prerequisite:
- Install the Axone CLI to interact with the protocol
- Ensure you have
npminstalled 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.
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
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 |
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.
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 datasethasDescription: fill in the description of the datasethasFormat: 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 datasethasTopic: 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 Todayid(issuer): copy the did:key of the issuername: 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 servicehasCategory: 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 tagshasTitle: fill in the title of the servicehasWebpage: fill in the URL of the service's webpageid(issuer): copy the did:key of the issuername: 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 addressMY_ADDR: issuer addressMY-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).
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 okp418cszlvm6pze0x9sz32qnjq4vtd45xehqs8dq7cwy8yhq35wfnn3qvya8dunode "https://api.drunemeton.okp4.network:443/rpc": name of the node for the Drunemeton testnetMY_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](https://explore.okp4.network/). Select the network (Currently Drunemeton-Testnet), click on the Search icon, and paste the transaction hash.
Example:
Hash: 766627052AA0A56F56702038E54EC69491386D35E0D76A47F9D5B2321DD56C3E
<div style={{ display: "flex", justifyContent: "center" }}>
<img src="/img/content/academy/transaction-explorer.webp" alt="Axone explorer" style={{ maxHeight: "340px" }}></img>
</div>
<br>
</br>
:::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.
:::