Quantumplation/CIP-????.md Secret

## CIP-????.md

      
    Raw
  

              CIP-????.md
            
          
    CIP-????: Governance Metadata Standard

Abstract

This Cardano Improvement Proposal (CIP) introduces a standardized and flexible metadata format for governance actions in the Cardano ecosystem. While the ledger does not enforce the structure of metadata, providing a standard for metadata will enable better tooling, improved interoperability, and more consistent display across wallets, blockchain explorers, and other tools. This CIP aims to strike a balance between flexibility and structure to facilitate high-quality tooling, without limiting expressivity with regards to user expression.
Acknowledgements


CHIL Pool
Alex Djuric
Cody Butz
Felix Weber
Leo Pienasola
Markus Gufler
Michael Madoff
Mohamed Mahmoud
Thomas Upfield
William Ryan
Santiago

Motivation

With the advent of the Voltaire era, Cardano is moving towards a decentralized governance model. CIP-1694 addresses a potential technical implementation of ledger rules for creating, voting on, and ratifying proposals. However, the ledger requires minimal information, and thus does not enforce the structure of metadata associated with governance actions.
However, to maximize the effectiveness of the experiences that tool and ecosystem developers can create, we put forth a common standard for this metadata to follow.  This will allow things like DRep explorers, deep wallet integration, automatic translation, etc.
While this specification is written with CIP-1694 in mind, many of the ideas should be equally suitable for any other governance proposal, provided that proposal has a mechanism for attaching metadata to a governance action.
Specification

Here we outline the high level format and requirements of this standard.
  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
  "OPTIONAL" in this document are to be interpreted as described in
  [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).


On chain metadata actions in CIP-1694 have the notion of an "Anchor"; this is the URL and a hash for additional, non-ledger metadata about the action.
Tools which publish governance related transactions MAY publish metadata via these fields.
While that content MAY be in any format, following any standard or non-standard, for the remainder of this document we will assume the intention is for that content to follow this standard.
The content hosted at the anchor URL MUST be a JSON document.
The JSON document SHOULD be formatted for human readability, for the sake of anyone who is manually perusing the metadata.
That content SHOULD be hosted on a content addressable storage medium, such as IPFS or Arweave, to ensure immutability and long term archival.
The hash included in the anchor MUST be the SHA256 hash of the content found at that URL

Notes from workshop:

Compared to transaction metadata / json-to-cbor etc.
Thomas expected it to be blake2b; this makes since, since throughout the ledger blake2b is used very often; but SHA256 is also more "ubiquitous", and the ledger isn't validating these hashes; should get more community input on which hash
sha256:blah or blake2b:blah to allow extensible hashing
Aleksandar suggested using / allowing YAML instead of / in addition to JSON; CIP-1694 maybe specifies JSON
Had a discussion about storing things on-chain, probably still needs more discussion in the open on twitter

Versioning

This CIP adopts a compositional approach to versioning, rather than an incremental one, inspired by recent changes to CIP-0030. Rather than forcing competing standards to compete for what the "next" version number will include, we instead encourage a variety of standards, and allow tool authors to support those which are the most beneficial. This creates an organic, collaborative evolution of the standard.

A metadata document SHOULD include an extensions field.
This field MUST be an array of objects

Each object MUST have a single field, cip, which is a string specifying the CIP that standardized the interpretation of the extension.
Each extension specifies some change or addition to the interpretation of the metadata document


If the metadata document is missing the extensions field, it will be assumed to be an array containing only this CIP.
These future extensions SHOULD endeavor, to the best of their ability, to avoid conflicts, such as overlapping field names.
If a conflict is unavoidable or only noticed after the standard is widely deployed, it SHOULD be updated to specify how the conflict is resolved.
Until a clear conflict resolution is specified in the CIP, the latter CIP in the array MUST take precedence over previous ones.
Tool authors MAY choose which extensions to support, but MUST make a best effort to display the metadata in the presence of unrecognized extensions, up to and including gracefully falling back to a raw data display.

Notes from the workshop:

Santiago commented that this section could be implemented via JSON-LD
Markus emphasized that using industry-standard mechanisms is super helpful for tooling authors, rather than reinventing our own standard
Alex emphasized how he liked the compositional nature of it, where CIPs can add entire blocks of functionality in one go and this meshes nicely with other parallel proposals

Governance Transaction Types

For each governance transaction (proposing a governance action, registering as a DRep (Voter), DRep retirement, Casting a vote, delegating ta a DRep, and voting as a Constitutional Committee Member), a specific set of fields should be included in the metadata. This allows for consistent display and interaction with these actions across tools and platforms.
NOTE: These actions are based on CIP-1694, but could be repurposed for any other CIP that gained community traction.
Common properties


Author + Signature + optional DIDs
Language (English / Spanish / etc)

ISO language code


Endorsements

Timestamp, Public Key, Signature, DID
Usually for proposal creation, but maybe your vote / registration / retirement has endorsements for example


Justification

Freeform or structured text that explains why the proposal is a good or bad idea
External errata for more explanation, videos, lectures, etc. justifying XYZ


Reference material

Similar proposals from other blockchains
Research papers / specifications for a hard fork
Publications on a cryptographic primitive


Where to find addendums / updates

We can't update this document because of the hash, but here's a URL / label / whatever to find potentially new information that has come to light


Governance Action Creation


Authorship history


First draft written timestamp


Other drafts / timestamps (reference)


Final draft timestamp


Time and materials budget


Time limit / sensitivity information

Urgent hardfork to fix a bug
Payout deadline


Proposal-type specific proposals

No Confidence
New CC
Constitution
Protocol Parameters
Simulation data
Treasury Payout
category
payment target information (if different from author)
(Including signature)
Info

Content


DRep Registration


Platform / Values
DID / Social Media / Website
Group / Organization
Stake Pool information?

DRep Retirement


Recommended Replacement

Who do you suggest your delegators delegate to in your stead?


Press release? (is this just justification?)
"I'll come back if ___"
"This is in protest of {governance action}"

Vote Casting


Vote Delegation


Cast Constitutional Committee Vote


Best Practices

In this section, we outline a number of best practices for tools and user experiences built on top of this standard.

If the hash in the anchor doesn't match the computed hash of the content, it is imperative to make that obvious to the user.

Without this being obvious, there are severe and dramatic attack vectors for manipulating user votes, delegators, etc.
NOTE: We don't use "MUST" in the RFC-2119 sense because it's unenforcable anyway, but if you don't check these hashes, you SHOULD inform the user that you are not checking the integrity of the data.
You MAY do this by displaying a prominent warning, or potentially fully barring access to the content.


You SHOULD provide a way to access the raw underlying data for advanced or diligent users.

This MAY be in the form of a JSON viewer, or a simple link to the content.


You SHOULD gracefully degrade to a simple raw content view if the metadata is malformed in some way.
You SHOULD provide links and cross references whenever the metadata refers to another object in some way

For example, a proposal may link to the sponsoring DReps, which may have their own view within the tool you're building


If you are hosting the content for the user, you SHOULD use a content-addressable hosting platform such as IPFS or Arweave
If the content is self-hosted, you SHOULD take care to warn the user about changing the content

For example, you CAN detect well-known content-addressable file storage platforms, and display an extra warning if the content is not hosted on one of those


Notes from workshop:

Markus wants to think deeply about pool metadata, and the notion of extended metadata and if there are lessons we can learn from that
Should we have a notion of where to find "addendums", which might change / be added; we can't update this metadata because it will change the hash, but we can have a type of data that is "less permanent" for example revisions, new information that comes to light, a DRep has their mind changed on a vote, etc.