Skip to main content

Create the resource's governance

Reading time: 17 min
info

We recommend you first read the Technical documentation of Governance before delving into practice in the Academy.

Resource Consent is an agreement associated with the use of Resources within Zones. By resources, we mean Digital Resources (e.g., datasets) or Digital Services. It goes beyond simple approval and encompasses the permissions and restrictions on resource owners' access, usage, sharing, management, and handling of their resources. It allows parties to define boundaries and establish terms for others to interact with their digital resources. This is crucial for governance, ensuring resources are used appropriately per the relevant parties' expressed will and intentions.

The materialization of a resource in the dataverse requires the creation of a Governance VP. According to a principle of self-determination, the resource itself must generate this VP, i.e., the issuer and the resource have the same identity.

The impact of this VP of Governance is constitutional. Its implementation transfers authority from the issuer (i.e., the resource) to an autonomous governance system associated with the resource. This system is equipped with its own mechanisms and manages changes and revisions relating to the governance of the resource in an independent, self-regulated, and decentralized manner.

The governance of a Dataset or Service Governance is contractual, defining the terms of access and use of the resource. For example, it can specify the conditions of access to a dataset for certain services with specific claims.

In the protocol, governance structures are made up of two key elements:

  • A VP serves as proof of the existence of a governance by referencing the Codified Governance. This document plays a fundamental role in creating a resource within the dataverse.
  • Governance as Code is represented by a program written in Prolog. This program details and encodes the specific rules governing resource management.
Governance elements for Resources in Axone Protocol

Here are the five steps to create the governance of a resource in the Dataverse:

Steps to create a resource's governance

We'll take 2 simple examples in this tutorial:

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: Define the governance of your resource

First, you need to define the governance rules of your resource. The governance content is systematically arranged into a hierarchical text structure comprising sections, articles, and paragraphs.

  • chapter: This term represents a major division in structuring rules, similar to a chapter in a legislative text. It is used to group together articles dealing with related subjects or falling within the same thematic area.
  • section: A section is a subdivision of a chapter. It allows articles to be organized into thematic subgroups, making the structure of the rules more readable and easier to navigate.
  • article: The article is the basic unit in the formulation of rules. Each article sets out a specific rule or set of rules and is identified by a unique number or title for ease of reference.
  • paragraph: The paragraph is the element that contains the text of the rule itself. This translates into a clause defining a specific condition or rule in Prolog.

You can use a template (coming soon) or begin from scratch.

Governance rules of the dataset Crime Data from 2020 to Present:

DivisionOrdinal numberTitle
Chapter1Crime data dataset governance
Section1.1Usage of the dataset
Article1.1.1Conditions on consumers
Paragraph1.1.1.1Everyone can use the dataset
Article1.1.2Conditions on services that consume the dataset
Paragraph1.1.2.1Only services of type "Storage" or "Data Processing"
Section1.2Conditions of usages
Article1.2.1Price
Paragraph1.2.1.1Free
Article1.2.2Rate limiting
Paragraph1.2.2.1The rate limit is 2 months maximum

Governance rules of the service IPFS:

DivisionOrdinal numberTitle
Chapter1IPFS governance
Section1.1Usage of the dataset
Article1.1.1Conditions on consumers
Paragraph1.1.1.1Everyone can use the dataset
Section1.2Conditions of usages
Article1.2.1Price
Paragraph1.2.1.1Free
info

The Axone Community will provide more and more templates over time.

Step 2: Create the Prolog program

Introduction

Codified Governance is based on the principles of Rules as Code (RaC), a powerful and innovative approach that reinvents a fundamental aspect of governance: the formulation of rules. This concept suggests that governance bodies implement official versions of rules (such as regulations) in a format that can be interpreted by both machines and humans.

This method facilitates computer systems' understanding and automated application of rules, guaranteeing consistent and deterministic execution. On the other hand, the ability of rules to be interpreted by humans facilitates their verification and encourages the informed and responsible involvement of stakeholders.

In the context of the protocol, it enables autonomous and decentralized interpretation and execution of the rules, thanks to the use of Smart Contracts.

The elements of law

Several terminological elements are essential when expressing legal terms in Prolog for the construction of governance rules. These elements provide a structured framework, mirroring traditional legal documents, and facilitate the precise encoding of legal concepts and rules in the Prolog programming environment.

Hierarchical elements

To articulate the hierarchy of the various elements that make up governance, hierarchy levels are introduced into the system to improve structuring and enhance understanding of the content.

These elements are translated into the following Prolog predicates:

chapter(ChapterId).
section(SectionId).
article(ArticleId).
paragraph(ParagraphId, ...).

To maintain the link between the different hierarchical elements, the binary predicate partOf/2 is added to the system.

For example:

% Definition of instances
chapter(chap1).
section(sec1).
article(art1).
paragraph(para1, ...).
paragraph(para2, ...).

% Definition of relationships
partOf(para1, art1).
partOf(para2, art1).
partOf(art1, sec1).
partOf(sec1, chap1).
Governance elements for Resources in Axone Protocol

Elements of description

To enable the textual description of the different parts of governance, 2 predicates are introduced into the system:

  • title: The title of a hierarchy element
  • description: The description of a hierarchy element
title(ElementId, Text).
description(ElementId, Text).

Where ElementId is an instance of a hierarchical element as defined above.

Legal reasoning is based on expressing what is permitted and what is prohibited. Unconditional or conditional paragraph/2 clauses encode this expression.

The paragraph/2 predicate is defined as follows:

paragraph(ParagraphId, Modality)

where

  • ParagraphId is the unique identifier of the paragraph.
  • Modality designates the modality, the interpretation under which the rule is to be considered. The possible values are:
    • permitted: This modality expresses formal permission relating to the specified action, depending on the particular conditions or context taken into account. It is relevant to conditional clauses, highlighting situations where the action is explicitly permitted.
    • prohibited: This modality expresses an explicit prohibition linked to the action mentioned, applicable in the specific context considered. It is also relevant for conditional clauses, marking circumstances where the action is formally prohibited.

Elements of context

The paragraph/2 predicate allows the expression of (unitary) governance rules by asserting the modality with which to interpret the rule. However, contextual elements such as the action performed, the object of the action, or the subject at the origin of the action are not explicitly specified in the signature of the predicate. For this reason, predicate clauses can incorporate references to contextual elements, establishing conditions for satisfying the rule. As part of the interpretation of a rule, contextual elements are introduced as facts and exploited in the rules to define the conditions under which the modality expressed in the rule is true.

The subjectId/1 predicate unifies the decentralized identifier (DID) of the subject of an action with the supplied argument.

The resourceId/1 predicate unifies the resource's decentralized identifier (DID), which is the object of the action with the supplied argument.

The action/1 predicate unifies the action initiated by the subject on the object with the supplied argument. The action is a term (a prolog fact) defined by an extensible control vocabulary, which refers to all possible actions. By convention, actions are designated by a domain and an action separated by ':'.

Examples of action:

  • resource:download
  • governance:amend

The legal order is the framework that enables the resolution of interactions between rules derived from different, possibly conflicting, norms, such as the rules governing the consent of resources and those defining the governance of an area.

To interpret these rules without conflict, it is essential to use strict principles that define an unambiguous and consistent logical framework that makes it possible to establish the resulting modality when several norms express different modalities.

First of all, it should be remembered that the modalities are: permitted and prohibited, plus unregulated, which corresponds to the absence of a verdict for evaluating a rule.

Principle of Non-Contradiction
For a given standard (i.e., governance), no action can be both permitted and prohibited by the applicable rules. If such a contradiction occurs, the action is considered to be unregulated. In Prolog, this means that for a given rule, there cannot be several possible modality solutions that satisfy it.

Principle of Non-Regulation
For a given standard, if an action is neither prohibited nor permitted by any rule, the action is considered to be unregulated.

Priority principle
For two standards under consideration, providing 2 different verdicts, the following priority principle is applied:

  • prohibited over permitted: If an action is both prohibited by one rule and permitted by another, the prohibition rule prevails.
  • prohibited over unregulated: If a rule prohibits an action, the prohibition prevails, regardless of whether other rules are neutral in this respect.
  • permitted over unregulated: If an action is explicitly permitted by a rule, this permission prevails over the absence of any indication (unregulated) in other rules.

Examples

Here is an example of the consent attached to the Crime dataset:

:- discontiguous([title/2,partOf/2,chapter/1,section/1,article/1,paragraph/2]).
chapter('chap1').
title('chap1', 'Crime data governance').
section('sec1.1').
partOf('sec1.1', 'chap1').
title('sec1.1', 'Usage of the dataset').
article('art1.1.1').
partOf('art1.1.1', 'sec1.1').
title('art1.1.1', 'Conditions on consumers').
paragraph('para1.1.1.1', permitted) :- action(A), A=='workflow:consume'.
partOf('para1.1.1.1', 'art1.1.1').
description('para1.1.1.1', 'Everyone can use the dataset').

Step 3: Submit the Prolog program in the Dataverse

Create a Prolog file my-resource-governance.pl with the governance of your resource.

Create a specific smart contrat Law Stone for your governance.

okp4d tx wasm instantiate 2 --label $UNIQUE_LABEL \
--node "https://api.drunemeton.okp4.network:443/rpc" \
--chain-id okp4-drunemeton-1 \
--keyring-backend test \
--from $WALLET \
--admin $WALLET \
--gas 20000000 \
"{\"program\":\"$(cat $MY-GOVERNANCE.pl | base64)\", \"storage_address\": \"CONTRACT_ADDR\"}"

With:

  • $UNIQUE_LABEL : name of the smart contract. It must be unique. You can use a UUID.
  • CONTRACT_ADDR : Cognitarium contract address (always the same) okp41suhgf5svhu4usrurvxzlgn54ksxmn8gljarjtxqnapv8kjnp4nrscr7uaj
  • from $WALLET : registrant okp4 address
  • admin $WALLET : okp4 address which is allowed to update the contract
  • $MY-GOVERNANCE.pl : Prolog file of the governance

Example:

okp4d tx wasm instantiate 2 --label fea0312a-f4bb-449c-a736-7a16e7cc94c1 \
--node "https://api.drunemeton.okp4.network:443/rpc" \
--chain-id okp4-drunemeton-1 \
--keyring-backend test \
--from issuer-okp4 \
--admin issuer-okp4 \
--gas 20000000 \
"{\"program\":\"$(cat crime-dataset-governance.pl | base64)\", \"storage_address\": \"okp41suhgf5svhu4usrurvxzlgn54ksxmn8gljarjtxqnapv8kjnp4nrscr7uaj\"}"

txhash: 59AB4A2A7AD238AD55F75D5CB9B576FF92DDE39F1509442A74E6556A612591A6

Then you need to find the contract address which is necessary for the next step. You can use the following command:

okp4d --node "https://api.drunemeton.okp4.network:443/rpc" query tx $TX_HASH

With:

  • $TX_HASH: The hash of the transaction which instantiates the smart contract

Example:

okp4d --node "https://api.drunemeton.okp4.network:443/rpc" query tx 59AB4A2A7AD238AD55F75D5CB9B576FF92DDE39F1509442A74E6556A612591A6

Find the contract address in the transactions information:

Example:

- attributes:
- index: true
key: _contract_address
value: okp41z7asfxkwv0t863rllul570eh5pf2zk07k3d86ag4vtghaue37l5sa62rrk
- index: true
key: code_id
value: "2"

Step 4: Create the Governance VC

The Governance VP is a specific type of VP that details the governance rules applicable to a given resource, whether it is a Dataset, a Service, or a Zone. This VP addresses two key dimensions:

  • Association with Codified Governance: It associates the resource with a URI that refers to the codified governance rules (governance as code). This URI points to a program in Prolog language that explicitly defines the governance rules.
  • Textual Description of the Rules: In addition to the link to the codified rules, the VP provides a structured and hierarchical textual explanation of the governance rules, as set out in the Prolog program.

This bimodal approach not only guarantees the clarity and accessibility of the governance rules for human users but also ensures their direct and functional on-chain integration. The VP of Governance therefore plays a crucial role in clarifying and implementing governance guidelines for resources within the Axone dataverse.

Governance VPs play an essential role in the dataverse, applying universally to various categories of resources, such as datasets, services, and zones.

Instantiate the template credential-governance-text.

Fill in the template with the elements you precedently defined.

The following code specifies that the Crime Dataset whose DID is <did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5> has a governance system that is described by the prolog program <cosmwasm:okp4-objectarium:okp41z7asfxkwv0t863rllul570eh5pf2zk07k3d86ag4vtghaue37l5sa62rrk> for which a text description is also provided.

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/"
],
"type": ["VerifiableCredential","GovernanceTextCredential"],
"id": "https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hfk0312a-f4bb-449c-a736-7a16e7cc94c1",
"credentialSubject": {
"id": "did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5",
"isGovernedBy": {
"type": "GovernanceText",
"fromGovernance": "cosmwasm:law-stone:okp41z7asfxkwv0t863rllul570eh5pf2zk07k3d86ag4vtghaue37l5sa62rrk?query=%22program_code%22",
"hasChapter": {
"type": "Chapter",
"hasTitle": "Crime data dataset governance",
"hasOrdinalNumber": "1",
"hasSection": {
"type": "Section",
"hasTitle": "Usage of the dataset",
"hasOrdinalNumber": "1.1",
"hasArticle": {
"type": "Article",
"hasTitle": "Conditions on consumers",
"hasOrdinalNumber": "1.1.1",
"hasParagraph": {
"type": "Paragraph",
"hasTitle": "Everyone can use the dataset",
"hasOrdinalNumber": "1.1.1.1"
}
},
"hasArticle": {
"type": "Article",
"hasTitle": "Conditions on services that consume the dataset",
"hasOrdinalNumber": "1.1.2",
"hasParagraph": {
"type": "Paragraph",
"hasTitle": "Only services of type 'Storage' or 'Data Processing'",
"hasOrdinalNumber": "1.1.2.1"
}
}
},
"hasSection": {
"type": "Section",
"hasTitle": "Conditions of usages",
"hasOrdinalNumber": "1.2",
"hasArticle": {
"type": "Article",
"hasTitle": "Price",
"hasOrdinalNumber": "1.2.1",
"hasParagraph": {
"type": "Paragraph",
"hasTitle": "Free",
"hasOrdinalNumber": "1.2.1.1"
}
},
"hasArticle": {
"type": "Article",
"hasTitle": "Rate limiting",
"hasOrdinalNumber": "1.2.2",
"hasParagraph": {
"type": "Paragraph",
"hasTitle": "The rate limit is 2 months maximum",
"hasOrdinalNumber": "1.2.2.1"
}
}
}
}
}
},
"issuanceDate": "2024-02-06T13:29:00.475304+01:00",
"issuer": {
"id": "did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3",
"name": "OKP4"
}
}

Step 5: Sign and register in the Blockchain

Now that you have created the VC, you will sign it.

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:

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 crime-dataset-governance.jsonld 
--from issuer-okp4
--keyring-backend test | jsonld toRdf -q - > crime-dataset-governance.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/governance/text/isGovernedBy> _:b2 .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hfk0312a-f4bb-449c-a736-7a16e7cc94c1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/GovernanceTextCredential> .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hfk0312a-f4bb-449c-a736-7a16e7cc94c1> <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/governance/text/hfk0312a-f4bb-449c-a736-7a16e7cc94c1> <https://w3id.org/security#proof> _:b0 .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hfk0312a-f4bb-449c-a736-7a16e7cc94c1> <https://www.w3.org/2018/credentials#credentialSubject> <did:key:zQ3shRfADCmegmmKotqCjzDc9BHWDpbEzp9yMiN5RkJx88oP5> .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hfk0312a-f4bb-449c-a736-7a16e7cc94c1> <https://www.w3.org/2018/credentials#issuanceDate> "2024-02-06T13:29:00.475304+01:00"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hfk0312a-f4bb-449c-a736-7a16e7cc94c1> <https://www.w3.org/2018/credentials#issuer> <did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3> .
_:b1 <http://purl.org/dc/terms/created> "2024-04-03T10:45:45.644839+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..VJ_c0Hn4N-Wlcdvqk5fHdWPFtUM3bxmPW_qM_9hUOsYxs5ucoB3S3y2837VgXO51Urv84Pv0o5wM0SNng7KPZQ" _:b0 .
_:b1 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> _:b0 .
_:b1 <https://w3id.org/security#verificationMethod> <did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3#zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3> _:b0 .
_:b2 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/GovernanceText> .
_:b2 <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/fromGovernance> <cosmwasm:law-stone:okp41z7asfxkwv0t863rllul570eh5pf2zk07k3d86ag4vtghaue37l5sa62rrk?query=%22program_code%22> .
_:b2 <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hasChapter> _:b3 .
_:b3 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/Chapter> .
_:b3 <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hasOrdinalNumber> "1" .
_:b3 <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hasSection> _:b4 .
_:b3 <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hasTitle> "Crime data dataset governance" .
_:b4 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/Section> .
_:b4 <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hasOrdinalNumber> "1.1" .
_:b4 <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/hasTitle> "Usage of the dataset" .

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.

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 crime-dataset-governance.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: 4192587E13FF1A1530B0FFE88A80EACE4954374AE9A2789462E0372CC49E1A47

Axone explorer

Delete a resource in the Dataverse

The deletion of a resource in the Axone Dataverse is carried out exclusively by deleting the governance VP associated with this resource. This deletion action can only be initiated following the rules established by the governance of the resource. It is essential to stress the primacy of governance in this context. Suppose the established governance system does not designate a specific authority empowered to revoke the VP of Governance (or, more generally, the conditions that must be satisfied for its realization). In that case, the result is that the resource remains irrevocably integrated into the dataverse. This provision highlights the crucial importance of a systematic design of governance rules, particularly concerning the mechanisms for modifying and revoking resources.

Extinction of a resource in the Dataverse

VPs can be issued with predefined validity periods. When these durations expire, the VPs concerned are automatically revoked, rendering them null and void. This feature is crucial for managing situations where a resource becomes obsolete or loses relevance. When the governance VP expires, the resource concerned is nullified in the dataverse. As a result, the resource loses its recognition and validity within the system, rendering it unusable and unreferenced. In this context, it is essential to highlight the principle that governance does not have absolute primacy: governance regulations cannot prevent resource revocation. Indeed, the decision to revoke a resource falls exclusively within the authority of the entity that issued the resource's initial governance VP. However, extending these expirations through a governance amendment process is possible following the terms established by the governance itself.