Create the zone's governance

info

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

Zone Rules establish the boundaries of a specific area in the Dataverse, termed a zone, within which governance is enforced. Each zone is governed by its unique set of Rules tailored to its particular function or purpose.

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

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

The zone Governance is contractual, defining the terms of use of the zone. 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 zone within the dataverse.
• Governance as Code is represented by a program written in Prolog. This program details and encodes the specific rules governing zone management.

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

We'll take one simple example in this tutorial for the Collaborative AI zone.

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 zone

First, you need to define the governance rules of your zone. 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 Collaborative AI zone:

Division	Ordinal number	Title
Chapter	1	Collaborative AI zone
Section	1.1	Zone Governance
Article	1.1.1	Conditions to amend the rules
Paragraph	1.1.1.1	Governance can only be amended by the identity did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3
Article	1.1.2	Conditions on authorized services
Paragraph	1.1.1.1	Only services of type 'Storage' or 'Machine Learning'

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).

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 terms

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

Legal order

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 governance of Collaborative AI zone:

:- discontiguous([title/2,partOf/2,chapter/1,section/1,article/1,paragraph/2]).
chapter('chap1').
     title('chap1', 'Collaborative AI zone governance').
     section('sec1.1').
         partOf('sec1.1', 'chap1').
         title('sec1.1', 'Zone Governance').
             article('art1.1.1').
                 partOf('art1.1.1', 'sec1.1').
                 title('art1.1.1', 'Conditions to amend the rules').
                 paragraph('para1.1.1.1', permitted) :- action(A), A=='governance:amend', S == 'did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3'.
                    partOf('para1.1.1.1', 'art1.1.1').
                     description('para1.1.1.1', 'Governance can only be amended by the identity `did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3`').

Step 3: Submit the Prolog program in the Dataverse

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

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 4e2e5526-5ce0-41b9-b1ea-a4a3b595a0ae \
    --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 collab-ai-zone-governance.pl | base64)\", \"storage_address\": \"okp41suhgf5svhu4usrurvxzlgn54ksxmn8gljarjtxqnapv8kjnp4nrscr7uaj\"}"

txhash: 19DA088BC86BFCFAB34846D44024464BDADF71B74EEB1C68AC7634DE393B043B

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 19DA088BC86BFCFAB34846D44024464BDADF71B74EEB1C68AC7634DE393B043B

Find the contract address in the transactions information:

Example:

- attributes:
  - index: true
    key: _contract_address
    value: okp4182nff4ttmvshn6yjlqj5czapfcav9434l2qzz8aahf5pxnyd33ts6jynpl
  - 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 zone, whether it is a Dataset, a Service, or a Zone. This VP addresses two key dimensions:

• Association with Codified Governance: It associates the zone 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 zone 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:okp4182nff4ttmvshn6yjlqj5czapfcav9434l2qzz8aahf5pxnyd33ts6jynpl> 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/5f2e5526-5ce0-41b9-b1ea-a4a3b595a0ae",
  "credentialSubject": {
    "id": "did:key:zQ3shunN7us5oKNYKKzprW8nP5HAoTf4t2Fxyudho5zMAR1PQ",
    "isGovernedBy": {
      "type": "GovernanceText",
      "fromGovernance": "cosmwasm:law-stone:okp4182nff4ttmvshn6yjlqj5czapfcav9434l2qzz8aahf5pxnyd33ts6jynpl?query=%22program_code%22",
      "hasChapter": {
        "type": "Chapter",
        "hasTitle": "Collaborative AI governance",
        "hasOrdinalNumber": "1",
        "hasSection": {
          "type": "Section",
          "hasTitle": "Zone Governance",
          "hasOrdinalNumber": "1.1",
          "hasArticle": {
            "type": "Article",
            "hasTitle": "Conditions to amend the rules",
            "hasOrdinalNumber": "1.1.1",
            "hasParagraph": {
              "type": "Paragraph",
              "hasTitle": "Governance can only be amended by the identity `did:key:0x04d1j1x8f8a7a28f9a5a254c326a963a22f5a5b5d5f5e5d5c5b5a5958575758`",
              "hasOrdinalNumber": "1.1.1.1"
            }
          },
          "hasArticle": {
            "type": "Article",
            "hasTitle": "Conditions on authorized services",
            "hasOrdinalNumber": "1.1.2",
            "hasParagraph": {
              "type": "Paragraph",
              "hasTitle": "Only services of type 'Storage' or 'Machine Learning'",
              "hasOrdinalNumber": "1.1.2.1"
            }
          }
        },
        "hasSection": {
          "type": "Section",
          "hasTitle": "Zone Business Model",
          "hasOrdinalNumber": "1.2",
          "hasArticle": {
            "type": "Article",
            "hasTitle": "XXXX",
            "hasOrdinalNumber": "1.2.1",
            "hasParagraph": {
              "type": "Paragraph",
              "hasTitle": "XXXX",
              "hasOrdinalNumber": "1.2.1.1"
            }
          },
          "hasArticle": {
            "type": "Article",
            "hasTitle": "XXXX",
            "hasOrdinalNumber": "1.2.2",
            "hasParagraph": {
              "type": "Paragraph",
              "hasTitle": "XXXX",
              "hasOrdinalNumber": "1.2.2.1"
            }
          }
        }
      }
    }
  },
  "issuanceDate": "2024-06-06T15:45: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 collab-ai-zone-governance.jsonld
    --from issuer-okp4
    --keyring-backend test | jsonld toRdf -q - > collab-ai-zone-governance.nq

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

<did:key:zQ3shunN7us5oKNYKKzprW8nP5HAoTf4t2Fxyudho5zMAR1PQ> <https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/isGovernedBy> _:b2 .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/5f2e5526-5ce0-41b9-b1ea-a4a3b595a0ae> <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/5f2e5526-5ce0-41b9-b1ea-a4a3b595a0ae> <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/5f2e5526-5ce0-41b9-b1ea-a4a3b595a0ae> <https://w3id.org/security#proof> _:b0 .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/5f2e5526-5ce0-41b9-b1ea-a4a3b595a0ae> <https://www.w3.org/2018/credentials#credentialSubject> <did:key:zQ3shunN7us5oKNYKKzprW8nP5HAoTf4t2Fxyudho5zMAR1PQ> .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/5f2e5526-5ce0-41b9-b1ea-a4a3b595a0ae> <https://www.w3.org/2018/credentials#issuanceDate> "2024-06-06T15:45:00.475304+01:00"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://w3id.org/okp4/ontology/v3/schema/credential/governance/text/5f2e5526-5ce0-41b9-b1ea-a4a3b595a0ae> <https://www.w3.org/2018/credentials#issuer> <did:key:zQ3shs7auhJSmVJpiUbQWco6bxxEhSqWnVEPvaBHBRvBKw6Q3> .
_:b1 <http://purl.org/dc/terms/created> "2024-04-03T11:34:29.724958+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..WHnc8--Jo7GjhuN2HhO1bKE0EkfG8qVyl-M2k34hzmJsH6M4SfwtmocFPagvzFUu6upKM8mvt40Y2Hxz0cMKGg" _: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:okp4182nff4ttmvshn6yjlqj5czapfcav9434l2qzz8aahf5pxnyd33ts6jynpl?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> "Collaborative AI 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> "Zone Governance" .

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 collab-ai-zone-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](https://explore.okp4.network/). Select the network (Currently Drunemeton-Testnet), click on the Search icon, and paste the transaction hash.

Example:
Hash: E6D18D38D5A54BC0C73084A047448216A238C69930908B16F11509E7877E0CF9

<div style={{ display: "flex", justifyContent: "center" }}>
  <img src="/img/content/academy/transaction-explorer-4.webp" alt="Axone explorer" style={{ maxHeight: "340px" }}></img>
</div>

## Delete a zone in the Dataverse

The deletion of a zone in the Axone Dataverse is carried out exclusively by deleting the governance VP associated with this zone. This deletion action can only be initiated following the rules established by the governance of the zone.
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 zone 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 zones.