From 7920140e56c0fa5f44cb20e42e03c4ebf38b138b Mon Sep 17 00:00:00 2001 From: Pi Lanningham Date: Thu, 20 Jul 2023 14:46:26 -0400 Subject: [PATCH 1/8] Second draft of the governance metadata CIP --- CIP-0010/registry.json | 4 + CIP-?/README.md | 297 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 301 insertions(+) create mode 100644 CIP-?/README.md diff --git a/CIP-0010/registry.json b/CIP-0010/registry.json index 7a1a85b0b..92cfaf6e6 100644 --- a/CIP-0010/registry.json +++ b/CIP-0010/registry.json @@ -47,6 +47,10 @@ "transaction_metadatum_label": 1667, "description": "CIP-72: dApp registration & Discovery" }, + { + "transaction_metadataum_label": 1694, + "description": "Voltaire - additional metadata for governance, provided in a separate transaction" + }, { "transaction_metadatum_label": 1870, "description": "Open Badges v2.0 compliant metadata" diff --git a/CIP-?/README.md b/CIP-?/README.md new file mode 100644 index 000000000..dd49b48a6 --- /dev/null +++ b/CIP-?/README.md @@ -0,0 +1,297 @@ +--- +CIP: ? +Title: Governance Action Metadata Standard +Category: Metadata +Status: Proposed +Authors: + - Pi Lanningham +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2023-04-09 +License: CC-BY-4.0 +--- + +## 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 + +
+ First draft/workshop + + I would like to thank those that contributed to this first draft during the online workshop that was held on 2023-04-12. + + - CHIL Pool + - Alex Djuric + - Cody Butz + - Felix Weber + - Leo Pienasola + - Markus Gufler + - Michael Madoff + - Mohamed Mahmoud + - Thomas Upfield + - William Ryan + - Santiago Carmuega + +
+ +
+ Second draft + + The following people helped with the second draft, out of band at at the Edinburgh workshop on 2023-07-12. + + - Ryan Williams + - Matthias Bankort + - All Edinburgh Workshop attendees +
+ +## 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 proposed changes to the ledger. The ledger has no mechanism or desire to validate this metadata, and as a result, the official specification leaves the format of this metadata unspecified. + +To facilitate rich user experiences for the various governance actors, however, it would be beneficial to have a suggested universal format for this metadata, allowing deep and interconnected discovery and exploration of this metadata. This CIP seeks to provide that standard format, and a minimal set of fields for various governance actions, leavine the true depth of metadata to be defined later through the extensibility mechanism outlined below. + +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. + +Explicitly, here are the goals this CIP is trying to satisfy: + - Standardize a format for rich metadata related to cardano governance + - Standardize a minimal and uncontroversial set of fields to support "Minimal Viable Governance" + - Leave that format open to extension and experimentation + - Enable tooling and ecosystem developers to build the best user experiences possible + - Provide a set of best practices that tooling and ecosystem developers can rely on for the health and integrity of this data + +## Specification + +This section outlines 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 (and likely any alternative proposals) 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 SHOULD 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 SHOULD/MUST will refer to documents that are following this specification. +- The content hosted at the anchor URL MUST be a JSON-LD document according to the rest of this specification. +- This document SHOULD include `@context` and `@type` fields below to aid in interpretation of the 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 a tagged hash, such as `SHA256:{hash}` + + + +### Versioning + +[JSON-LD](https://json-ld.org/) is a standard for describing interconnected JSON documents that use a shared vocabulary. + +In a JSON-LD document, every field is uniquely tied to some globally unique identifier by means of an Internationalized Resource Identifier (IRI). Different machine-consumers can then know that they agree on the interpretation of these fields. + +The shared vocabulary of fields is standardized within the scope of a document via a `@context` field. This allows a compositional / extensible approach to versioning, similar to the recent changes to [CIP-0030](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0030/README.md). Rather than specifying a version number and forcing competing standards to compete for what the "next" version number will include, instead a wide variety of standards are allowed and encouraged. Tool authors MAY support those which are the most beneficial or common. This creates an organic, collaborative evolution of the standard. + + - A governance metadata document MAY include a `@context` field. + - A governance metadata document MAY include a `@type` field, referring to a specific type of document from the included `@context`s. + - The `@context` field, if included, MUST be a valid JSON-LD @context field; the basics are described below. + - It MAY be a string, in which case it MUST be the IRI of a jsonld document describing the shared vocabulary to assume when interpreting the document. + - It MAY be an object, where each key refers to a property name, and the value refers to the IRI describing how that field should be interpreted. + - It MAY be an array, including multiple contexts, which are processed in order. + - For a full understanding of the @context field, refer to the [JSON-LD specification](https://www.w3.org/TR/json-ld/). + - If the metadata document is missing the `@context` field, it will be assumed to refer to [./cip-?.common.jsonld] + - Future CIPs may standardize common contexts, and SHOULD attempt to reuse common terminology and SHOULD avoid naming collisions. + - Tool authors MAY choose which contexts to support, but MUST make a best effort to display the metadata in the presence of unrecognized context, up to and including gracefully falling back to a raw display of the JSON document. + +### Governance Transaction Types + +In CIP-1694 (and likely any alternative or future evolution of it), there are a number of certificates that can be attached to a transaction pertaining to governance; each of these is equipped with an "anchor", which can refer to an external document. This CIP provides the following JSON-LD schemas intended to represent a fairly minimal set of properties and types for each type of transaction: + + - [Common Definitions](./cip-?.common.jsonld) + - [Governance Action](./cip-?.action.jsonld) + - [DRep (Voter) Registration](./cip-?.registration.jsonld) + - [DRep (Voter) Retirement](./cip-?.retirement.jsonld) + - [DRep (Voter) Vote](./cip-?.vote.jsonld) + - [DRep (Voter) Delegation](./cip-?.delegation.jsonld) + - [Constitutional Committee Vote](./cip-?.cc-vote.jsonld) + + + +Additionally, someone may wish to augment a previous piece of metadata with new information, divorced from the transaction that initially published it; this may be useful, for example, to provide additional arguments in favor of or against a proposal, provide translations to other languages, provide a layman's explanation of a highly technical document, etc. + +To this end, this CIP reserves [metadatum label 1694](../CIP-0010/README.md) for publishing these kinds of augments on-chain. This CIP also provides a special JSON-LD schema specifically for these documents: + + - [Augmentation](./cip-?.augmentation.jsonld) + +NOTE: These actions are based on CIP-1694, but could be repurposed for any governance CIP with minimal changes. + +The rest of this document will provide a high level description of the properties described in each of the schemas above. + +#### Common properties + +The following properties are considered common to all types of transactions, and the minimal set needed for "minimum viable governance": + + - Authors: The primary contributors and authors for this metadata document + - An array of objects + - Each object may have an address, a display name, and optionally a WC3 DID + - Each address mentioned MUST sign the transaction + - Tooling authors SHOULD validate these signatures; if absent or invalid, tooling authors SHOULD make this clear in the UI + + - Language: the ISO 639-1 that any prose in this metadata is written in + - Tooling authors MAY provide automatic translation, but SHOULD make the original prose easily available + - Justification + - Freeform text that explains *why* this proposal / vote / registration / retirement is being proposed / made / etc. + - Tooling authors MAY emphasize that this justification represents the view of the authors only + - External updates + - A array of objects + - Each object may have a URL, and a type + - The purpose is to allow "additional updates", that aren't locked in by a hash + - Tooling authors MAY fetch and parse this metadata according to this standard, + - If so, Tooling authors MUST emphasize that this information is second-class, given that it might have changed + + +#### Specific fields + +This CIP currently doesn't standardize any fields specific to each type of transaction, beyond specifying a `@type` for each type of transaction. + + + +### Best Practices + +This section outlines a number of other best practices for tools and user experiences built on top of this standard, as brainstormed by the Cardano community. + + - 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: The term "MUST" in the RFC-2119 sense isn't used here because it's unenforcable anyway, but if these hashes *aren't* checked, 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, or not understood. + - 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 such as IPFS or Arweave, and display an extra warning if the content is not hosted on one of those + + + +## Rationale: how does this CIP achieve its goals? + +Here are the goals this CIP seeks to achieve, and the rationale for how this specific solution accomplishes them: + + - Standardize a format for rich metadata related to cardano governance + - Standardizing on JSON-LD provides an industry standard, yet highly flexible format for effectively arbitrary structured data + - Standardize a minimal and uncontroversial set of fields to support "Minimal Viable Governance" + - This CIP fully specifies the Authors, Language, Justification, and External Updates fields + - Each of these fields is essential for the global accessibility of this data, and enables tooling that promotes a well-informed voting populace + - Leave that format open to extension and experimentation + - JSON-LD has, built in, a mechanism for extending and experimenting with new field types + - Anyone can extend this metadata, even independent of the CIP process, with their own field definitions + - Tooling authors can, independently, choose which extensions to support natively, while also surfacing fields they don't recognize in more generic ways. + - Enable tooling and ecosystem developers to build the best user experiences possible + - The `@context` field of a JSON-LD document allows tooling authors to confidently and consistently interpret a known field within the metadata, with reduced risk of misinterpreting or misrepresenting the authors intent + - This metadata can also reference other objects and documents in the ecosystem, providing for rich exploration needed for an informed voting populace. + - Provide a set of best practices that tooling and ecosystem developers can rely on for the health and integrity of this data + - This CIP has an explicit section of best practices, brainstormed with attendees of a workshop dedicated to the purpose. + +The following alternatives were considered, and rejected: + - Plain JSON documents + - While ultimately flexible and simple, there is a risk that with no way to structure what is *officially* supported, and the interpretation of each field, tooling authors would have one hand tied behind their back, and would be limited to a minimum common denominator. + - A custom JSON format, with reference to CIPs + - An initial draft of this proposal had an `extensions` field that operated very similar to `@context` + - Instead, this CIP chose to go with an industry standard format to leverage the existing tooling and thought that went into JSON-LD + - CBOR or other machine encoding + - The metadata in question, despite being proliferous, is not expected to to be an undue storage burden; It's not, for example, video data, or storing billions of records. + - It is more important, then, that the metadata be human readable, so that tooling authors have the option to show this data in its raw format to a user, and for it to be loosely understandable even by non-technical users. + +## Path to Active + +The path for this proposal to be considered active within the community focuses on 4 key stages: Feedback, Implementation, Adoption, and Extension. + +### Acceptance Criteria + +In order for this standard to be active, the following should be true: + + - At least 1 month of feedback has been solicited, and any relevant changes with broad consensus to the proposal made + - At least 2 client libraries in existence that support reading an arbitrary JSON file, and returning strongly typed representations of these documents + - At least 1 widely used *producer* of governance metadata (such as a wallet, or the cardano-cli) + - At least 1 widely used *consumer* of governance metadata (such as a blockchain explorer, governance explorer, voting dashboard, etc) + - At least 1 CIP in the "Proposed" status that outlines additional fields to extend this metadata + +### Implementation Plan + +The key stages to get this proposal to active, and the motivation for why each stage is valuable, is outlined below: + +- Solicitation of feedback + - While this proposal represents the input of many prominent community members, it is by no means exhaustive + - This CIP should receive a moderate, but not egregious, amount of scrutiny and feedback within it's initial goals +- Implementation + - The effectiveness of this standard is greatly amplified if tools and SDKs are built which allow parsing arbitrary data according to this standard + - Sundae Labs has offered to build Rust and Golang libraries that capture the types outlined above, and implementations in other languages are welcome + +- Adoption + - This standard is most effective if it receives widespread adoption + - Therefore, a path to active includes engaging prominent members of the ecosystem, such as wallets and explorers, to begin producing and consuming documents in accordance with the standard. +- Extension + - Finally, this standard chooses to fully specify very little of the total surface area of what could be expressed in governance metadata + - Therefore, to prove the extensibility of the standard, at least one follow-up CIP should be drafted, extending the set of fields beyond "Minimum Viable Governance" + +## Copyright + +This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). \ No newline at end of file From 1d42b2a05835e3d413c0b47db6034e7529874f1b Mon Sep 17 00:00:00 2001 From: Pi Lanningham Date: Sat, 22 Jul 2023 16:26:27 -0400 Subject: [PATCH 2/8] Typo --- CIP-?/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-?/README.md b/CIP-?/README.md index dd49b48a6..a14a1119a 100644 --- a/CIP-?/README.md +++ b/CIP-?/README.md @@ -51,7 +51,7 @@ This Cardano Improvement Proposal (CIP) introduces a standardized and flexible m 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 proposed changes to the ledger. The ledger has no mechanism or desire to validate this metadata, and as a result, the official specification leaves the format of this metadata unspecified. -To facilitate rich user experiences for the various governance actors, however, it would be beneficial to have a suggested universal format for this metadata, allowing deep and interconnected discovery and exploration of this metadata. This CIP seeks to provide that standard format, and a minimal set of fields for various governance actions, leavine the true depth of metadata to be defined later through the extensibility mechanism outlined below. +To facilitate rich user experiences for the various governance actors, however, it would be beneficial to have a suggested universal format for this metadata, allowing deep and interconnected discovery and exploration of this metadata. This CIP seeks to provide that standard format, and a minimal set of fields for various governance actions, leaving the true depth of metadata to be defined later through the extensibility mechanism outlined below. 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. From a684e895749c19d60aa690a31c160ed38b22b8a3 Mon Sep 17 00:00:00 2001 From: Pi Lanningham Date: Sun, 23 Jul 2023 14:58:06 -0400 Subject: [PATCH 3/8] Small bits of feedback --- CIP-?/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-?/README.md b/CIP-?/README.md index a14a1119a..e0b4f60a2 100644 --- a/CIP-?/README.md +++ b/CIP-?/README.md @@ -1,13 +1,13 @@ --- CIP: ? -Title: Governance Action Metadata Standard +Title: Governance Metadata Category: Metadata Status: Proposed Authors: - Pi Lanningham Implementors: [] Discussions: - - https://github.com/cardano-foundation/cips/pulls/? + - https://github.com/cardano-foundation/cips/pulls/556 Created: 2023-04-09 License: CC-BY-4.0 --- From 788123cbe0afc2593643daf4dd5d0a0c5eff1020 Mon Sep 17 00:00:00 2001 From: Pi Lanningham Date: Thu, 27 Jul 2023 12:50:13 -0400 Subject: [PATCH 4/8] Make open questions more discoverable --- CIP-?/README.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/CIP-?/README.md b/CIP-?/README.md index e0b4f60a2..c7c804f6f 100644 --- a/CIP-?/README.md +++ b/CIP-?/README.md @@ -80,11 +80,10 @@ This section outlines the high level format and requirements of this standard. - 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 a tagged hash, such as `SHA256:{hash}` - + - [ ] Should we pick a specific hash, instead of using a tagged hash? + - [ ] what hashes are supported? ### Versioning @@ -117,7 +116,7 @@ In CIP-1694 (and likely any alternative or future evolution of it), there are a - [DRep (Voter) Delegation](./cip-?.delegation.jsonld) - [Constitutional Committee Vote](./cip-?.cc-vote.jsonld) - + Additionally, someone may wish to augment a previous piece of metadata with new information, divorced from the transaction that initially published it; this may be useful, for example, to provide additional arguments in favor of or against a proposal, provide translations to other languages, provide a layman's explanation of a highly technical document, etc. @@ -129,6 +128,9 @@ NOTE: These actions are based on CIP-1694, but could be repurposed for any gover The rest of this document will provide a high level description of the properties described in each of the schemas above. +TODO: + - [ ] The above schemas aren't written yet; this is one of the areas I could use some help in, and I didn't want that to be a further impediment to me getting this draft out the door, as it's taken me long enough as it is + #### Common properties The following properties are considered common to all types of transactions, and the minimal set needed for "minimum viable governance": @@ -138,7 +140,7 @@ The following properties are considered common to all types of transactions, and - Each object may have an address, a display name, and optionally a WC3 DID - Each address mentioned MUST sign the transaction - Tooling authors SHOULD validate these signatures; if absent or invalid, tooling authors SHOULD make this clear in the UI - + - Language: the ISO 639-1 that any prose in this metadata is written in - Tooling authors MAY provide automatic translation, but SHOULD make the original prose easily available - Justification @@ -150,13 +152,19 @@ The following properties are considered common to all types of transactions, and - The purpose is to allow "additional updates", that aren't locked in by a hash - Tooling authors MAY fetch and parse this metadata according to this standard, - If so, Tooling authors MUST emphasize that this information is second-class, given that it might have changed - + + +Open Questions: + - [ ] Open to other suggestions for how to securely prove authenticity / endorsement when capturing signatures / DIDs + - [ ] The 'type' of external updates is TBD; I was thinking something like "Blog", "Twitter Feed", "RSS", and "Metadata", (with the last one representing a document that can be consumed according to this spec) but it might not even be neccesary #### Specific fields This CIP currently doesn't standardize any fields specific to each type of transaction, beyond specifying a `@type` for each type of transaction. + + In a JSON-LD document, every field is uniquely tied to some globally unique identifier by means of an Internationalized Resource Identifier (IRI). Different machine-consumers can then know that they agree on the interpretation of these fields. The shared vocabulary of fields is standardized within the scope of a document via a `@context` field. This allows a compositional / extensible approach to versioning, similar to the recent changes to [CIP-0030](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0030/README.md). Rather than specifying a version number and forcing competing standards to compete for what the "next" version number will include, instead a wide variety of standards are allowed and encouraged. Tool authors MAY support those which are the most beneficial or common. This creates an organic, collaborative evolution of the standard. +Note: Any URI's in the @context field SHOULD be content-addressable and robustly hosted; losing access to the schema is less dangerous than losing access to the metadata itself, but should still prefer strong and immutable storage options for the preservation of context. + - A governance metadata document MAY include a `@context` field. - A governance metadata document MAY include a `@type` field, referring to a specific type of document from the included `@context`s. - The `@context` field, if included, MUST be a valid JSON-LD @context field; the basics are described below. - It MAY be a string, in which case it MUST be the IRI of a jsonld document describing the shared vocabulary to assume when interpreting the document. - - It MAY be an object, where each key refers to a property name, and the value refers to the IRI describing how that field should be interpreted. - - It MAY be an array, including multiple contexts, which are processed in order. + - It MAY be an object, where each key refers to a property name, and the value is either an IRI to a schema describing that field, or an object with that definition inlined. + - It MAY be an array, including multiple contexts, which are merged in order with a "most-recently-defined-wins" mechanism. - For a full understanding of the @context field, refer to the [JSON-LD specification](https://www.w3.org/TR/json-ld/). - - If the metadata document is missing the `@context` field, it will be assumed to refer to [./cip-?.common.jsonld] + - Each IRI in the `@context` field SHOULD refer to a schema hosted via a robust, content addressable, and immutable storage medium such as IPFS, Arweave, etc. + - If the metadata document is missing the `@context` field, it will be assumed to refer to [./cip-100.common.jsonld] - Future CIPs may standardize common contexts, and SHOULD attempt to reuse common terminology and SHOULD avoid naming collisions. - Tool authors MAY choose which contexts to support, but MUST make a best effort to display the metadata in the presence of unrecognized context, up to and including gracefully falling back to a raw display of the JSON document. -### Governance Transaction Types - -In CIP-1694 (and likely any alternative or future evolution of it), there are a number of certificates that can be attached to a transaction pertaining to governance; each of these is equipped with an "anchor", which can refer to an external document. This CIP provides the following JSON-LD schemas intended to represent a fairly minimal set of properties and types for each type of transaction: +**Extensions to the governance metadata standard can take one of two forms**: +- CIP-100 itself can be updated through the normal CIP process to provide additional clarity on any concepts that are giving people trouble with adoption, or to correct inaccuracies. +- A new CIP, defining a new vocabulary for a specific use case. - - [Common Definitions](./cip-?.common.jsonld) - - [Governance Action](./cip-?.action.jsonld) - - [DRep (Voter) Registration](./cip-?.registration.jsonld) - - [DRep (Voter) Retirement](./cip-?.retirement.jsonld) - - [DRep (Voter) Vote](./cip-?.vote.jsonld) - - [DRep (Voter) Delegation](./cip-?.delegation.jsonld) - - [Constitutional Committee Vote](./cip-?.cc-vote.jsonld) +### Governance Transaction Types +In CIP-1694 (and likely any alternative or future evolution of it), there are a number of certificates that can be attached to a transaction pertaining to governance; each of these is equipped with an "anchor", which can refer to an external document. This CIP provides the following JSON-LD schema intended to represent a fairly minimal vocabulary : + - [Common Definitions](./cip-100.common.jsonld) Additionally, someone may wish to augment a previous piece of metadata with new information, divorced from the transaction that initially published it; this may be useful, for example, to provide additional arguments in favor of or against a proposal, provide translations to other languages, provide a layman's explanation of a highly technical document, etc. -To this end, this CIP reserves [metadatum label 1694](../CIP-0010/README.md) for publishing these kinds of augments on-chain. This CIP also provides a special JSON-LD schema specifically for these documents: +These can, in theory, be published anywhere, but to aide in discoverability for indexing tools, we explicitly call out the Cardano blockchain as a convenient "public square" in which to publish this metadata. - - [Augmentation](./cip-?.augmentation.jsonld) +To this end, this CIP reserves [metadatum label 1694](../CIP-0010/README.md) for publishing these kinds of augments on-chain. This CIP also provides a minimal JSON-LD schema specifically for these documents, though the vocabulary may be extended in the same way that any other json-ld context can be extended: -NOTE: These actions are based on CIP-1694, but could be repurposed for any governance CIP with minimal changes. + - [Augmentation](./cip-100.augmentation.jsonld) The rest of this document will provide a high level description of the properties described in each of the schemas above. -TODO: - - [ ] The above schemas aren't written yet; this is one of the areas I could use some help in, and I didn't want that to be a further impediment to me getting this draft out the door, as it's taken me long enough as it is - #### Common properties The following properties are considered common to all types of transactions, and the minimal set needed for "minimum viable governance": - - Authors: The primary contributors and authors for this metadata document - - An array of objects - - Each object may have an address, a display name, and optionally a WC3 DID - - Each address mentioned MUST sign the transaction - - Tooling authors SHOULD validate these signatures; if absent or invalid, tooling authors SHOULD make this clear in the UI - - - Language: the ISO 639-1 that any prose in this metadata is written in - - Tooling authors MAY provide automatic translation, but SHOULD make the original prose easily available - - Justification - - Freeform text that explains *why* this proposal / vote / registration / retirement is being proposed / made / etc. - - Tooling authors MAY emphasize that this justification represents the view of the authors only - - External updates - - A array of objects - - Each object may have a URL, and a type - - The purpose is to allow "additional updates", that aren't locked in by a hash - - Tooling authors MAY fetch and parse this metadata according to this standard, - - If so, Tooling authors MUST emphasize that this information is second-class, given that it might have changed - +- hash-algorithm: The algorithm used to hash the document for the purposes of the on-chain anchor; currently only supports blake2b-256 +- authors: The primary contributors and authors for this metadata document + - An array of objects + - Each object MAY have a display name + - Each object MUST have one or more witnesses + - Each witness may define a context, describing the manner in which the document has been witnessed + - A default witness scheme is described in a later section + - Tooling authors SHOULD validate these witnesses; if absent or invalid, tooling authors SHOULD make this clear in the UI +- body: The material contents of the document, separate for the purposes of signing + - justification + - Freeform text that explains *why* this proposal / vote / registration / retirement is being proposed / made / etc. + - Tooling authors MAY emphasize that this justification represents the view of the authors only + - external-updates + - A array of objects + - Each object can have a context defining how to interpret it + - by default, assumed to just be a title and a URL + - The purpose is to allow "additional updates", that aren't written yet + - Tooling authors MAY fetch and parse this metadata according to this standard, + - If so, Tooling authors MUST emphasize that this information is second-class, given that it might have changed + +An example jsonld specification for the above context is specified in + - [cip-100.common.jsonld](./cip-100.common.jsonld) + +Additionally, we highlight the following concepts native to json-ld that are useful in the context of governance metadata: + - [@language](https://www.w3.org/TR/json-ld11/#string-internationalization) + - The `@context` field SHOULD specify a `@language` property, which is an ISO 639-1 language string, to define a default language for the whole document + - Specific sub-fields can specify different languages + - The `@context` field may specify a `@container` property set to `@language`, in which case the property becomes a map with different translations of the property + - Tooling authors MAY provide automatic translation, but SHOULD make the original prose easily available Open Questions: - - [ ] Open to other suggestions for how to securely prove authenticity / endorsement when capturing signatures / DIDs - - [ ] The 'type' of external updates is TBD; I was thinking something like "Blog", "Twitter Feed", "RSS", and "Metadata", (with the last one representing a document that can be consumed according to this spec) but it might not even be neccesary - -#### Specific fields - -This CIP currently doesn't standardize any fields specific to each type of transaction, beyond specifying a `@type` for each type of transaction. + - [ ] Investigate whether the activity-pub / activity-streams is appropriate for external updates @Nils + - [ ] @santicmaru and I are still working on the jsonld files - +Open Questions: + - [ ] Should we leverage https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.jsonld in any way, or other DID specifications? + - Frankly, the whole DID space seems to make things way more complicated than it needs to be heh + - [ ] What is the exact procedure for canonicalizing the body? + - We can't just pluck the body field from the JSON, unless we say it inherits the context from the original document + - There's not a clear way to extract the subset of an object from the canonical format ### Best Practices @@ -233,12 +232,6 @@ This section outlines a number of other best practices for tools and user experi - 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 such as IPFS or Arweave, and display an extra warning if the content is not hosted on one of those - - ## Rationale: how does this CIP achieve its goals? Here are the goals this CIP seeks to achieve, and the rationale for how this specific solution accomplishes them: @@ -246,7 +239,7 @@ Here are the goals this CIP seeks to achieve, and the rationale for how this spe - Standardize a format for rich metadata related to cardano governance - Standardizing on JSON-LD provides an industry standard, yet highly flexible format for effectively arbitrary structured data - Standardize a minimal and uncontroversial set of fields to support "Minimal Viable Governance" - - This CIP fully specifies the Authors, Language, Justification, and External Updates fields + - This CIP specifies a minimal number of fields: hash-algorithm, authors, justification, external-updates, and @language - Each of these fields is essential for the global accessibility of this data, and enables tooling that promotes a well-informed voting populace - Leave that format open to extension and experimentation - JSON-LD has, built in, a mechanism for extending and experimenting with new field types diff --git a/CIP-0100/cip-100.augmentation.jsonld b/CIP-0100/cip-100.augmentation.jsonld new file mode 100644 index 000000000..adfb1dafc --- /dev/null +++ b/CIP-0100/cip-100.augmentation.jsonld @@ -0,0 +1,5 @@ +{ + "@context": { + + } +} \ No newline at end of file diff --git a/CIP-0100/cip-100.common.jsonld b/CIP-0100/cip-100.common.jsonld new file mode 100644 index 000000000..fccd708c2 --- /dev/null +++ b/CIP-0100/cip-100.common.jsonld @@ -0,0 +1,18 @@ +{ + "@context": { + "hash-algorithm": "", + "authors": { + "@container": "@set", + "@type": "" + }, + "body": { + "@context": { + "justification": "", + "external-updates": { + "@container": "@set", + "@type": "" + }, + } + } + } +} \ No newline at end of file From 93999e0e436e6de962862190014d0363a2d327e0 Mon Sep 17 00:00:00 2001 From: Pi Lanningham Date: Sun, 10 Dec 2023 23:18:54 -0500 Subject: [PATCH 7/8] Final draft for CIP-0100 Provides a JSON-LD and JSON Schema file for the minimal features. Reworks the wording of many bits, especially to reference a parallel CIP to extend CIP-0013. Renames "justification" to "comment", to leave it more general so others can specify the rationale-related extensions. Provides example test vectors. Folds the "augmentation" concept into a simple "references" field. --- CIP-0100/README.md | 126 +++++++++++++---------- CIP-0100/cip-0100.common.jsonld | 45 +++++++++ CIP-0100/cip-0100.common.schema.json | 146 +++++++++++++++++++++++++++ CIP-0100/cip-100.augmentation.jsonld | 5 - CIP-0100/cip-100.common.jsonld | 18 ---- CIP-0100/example.body.canonical | 9 ++ CIP-0100/example.canonical | 10 ++ CIP-0100/example.json | 59 +++++++++++ 8 files changed, 339 insertions(+), 79 deletions(-) create mode 100644 CIP-0100/cip-0100.common.jsonld create mode 100644 CIP-0100/cip-0100.common.schema.json delete mode 100644 CIP-0100/cip-100.augmentation.jsonld delete mode 100644 CIP-0100/cip-100.common.jsonld create mode 100644 CIP-0100/example.body.canonical create mode 100644 CIP-0100/example.canonical create mode 100644 CIP-0100/example.json diff --git a/CIP-0100/README.md b/CIP-0100/README.md index ba11e9bfd..954314263 100644 --- a/CIP-0100/README.md +++ b/CIP-0100/README.md @@ -14,7 +14,7 @@ License: CC-BY-4.0 ## 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. +This Cardano Improvement Proposal (CIP) introduces a standardized and flexible metadata format for governance events 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 @@ -105,19 +105,13 @@ This section outlines the high level format and requirements of this standard. - This document SHOULD include `@context` and `@type` fields below to aid in interpretation of the 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. -- As per an update to CIP-1694, the hash included in the anchor MUST be a tagged hash, such as `blake2b-256:{hash}` +- The hash in the anchor MUST be the hash of the canonicalized form of the metadata document, using the hashing algorithm specified in the `hashAlgorithm` field. Currently only blake2b-256 is supported. - For the purposes of hashing and signature validation, we should use the [canonical RDF triplet representation](https://www.w3.org/TR/rdf-canon/), as outlined in the JSON-LD specification. -Open question: - - [ ] is rdf-canon sufficient for our needs? @Santiago - ### Versioning [JSON-LD](https://json-ld.org/) is a standard for describing interconnected JSON documents that use a shared vocabulary. - - - In a JSON-LD document, every field is uniquely tied to some globally unique identifier by means of an Internationalized Resource Identifier (IRI). Different machine-consumers can then know that they agree on the interpretation of these fields. The shared vocabulary of fields is standardized within the scope of a document via a `@context` field. This allows a compositional / extensible approach to versioning, similar to the recent changes to [CIP-0030](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0030/README.md). Rather than specifying a version number and forcing competing standards to compete for what the "next" version number will include, instead a wide variety of standards are allowed and encouraged. Tool authors MAY support those which are the most beneficial or common. This creates an organic, collaborative evolution of the standard. @@ -132,88 +126,100 @@ Note: Any URI's in the @context field SHOULD be content-addressable and robustly - It MAY be an array, including multiple contexts, which are merged in order with a "most-recently-defined-wins" mechanism. - For a full understanding of the @context field, refer to the [JSON-LD specification](https://www.w3.org/TR/json-ld/). - Each IRI in the `@context` field SHOULD refer to a schema hosted via a robust, content addressable, and immutable storage medium such as IPFS, Arweave, etc. - - If the metadata document is missing the `@context` field, it will be assumed to refer to [./cip-100.common.jsonld] + - If the metadata document is missing the `@context` field, it will be assumed to refer to [./cip-0100.common.jsonld] - Future CIPs may standardize common contexts, and SHOULD attempt to reuse common terminology and SHOULD avoid naming collisions. - Tool authors MAY choose which contexts to support, but MUST make a best effort to display the metadata in the presence of unrecognized context, up to and including gracefully falling back to a raw display of the JSON document. **Extensions to the governance metadata standard can take one of two forms**: -- CIP-100 itself can be updated through the normal CIP process to provide additional clarity on any concepts that are giving people trouble with adoption, or to correct inaccuracies. -- A new CIP, defining a new vocabulary for a specific use case. +- CIP-0100 itself can be updated through the normal CIP process to provide additional clarity on any concepts that are giving people trouble with adoption, or to correct inaccuracies. +- A new CIP, which defines new JSON-LD vocabulary to extend this one, which seeks broad adoption. +- A new context document, used in the wild, but not officially standardized, and which doesn't seek broad adoption. + +### Hosting + +In CIP-1694 (and likely any alternative or future evolution of it), there are a number of certificates that can be attached to a transaction pertaining to governance; each of these is equipped with an "anchor", which is a URI at which can be found additional metadata. + +While this metadata can be published anywhere, external hosting may be unavailable to some users. Therefore, we recognize the transaction metadata as an effective tool for a "common town square" for hosting and discoverability, and reserve [metadatum label 1694](../CIP-0010/README.md) for publishing governance related metadata on-chain. + +With the help of [CIP-?](https://github.com/cardano-foundation/CIPs/pull/635), the anchor can then refer to the metadata of another transaction, or even the metadata of the transaction being published itself. + +When published on-chain, the CBOR encoding of this metadata, when published on-chain, follows [the standard convention](https://developers.cardano.org/docs/get-started/cardano-serialization-lib/transaction-metadata/#json-conversion) used for converting JSON to CBOR in transaction metadata. -### Governance Transaction Types +### Augmentations -In CIP-1694 (and likely any alternative or future evolution of it), there are a number of certificates that can be attached to a transaction pertaining to governance; each of these is equipped with an "anchor", which can refer to an external document. This CIP provides the following JSON-LD schema intended to represent a fairly minimal vocabulary : +Additionally, someone may wish to augment a previous piece of metadata with new information, divorced from the transaction that initially published it; this may be useful, for example, provide additional arguments in favor of or against a proposal, provide translations to other languages, provide a layman's explanation of a highly technical document, etc. - - [Common Definitions](./cip-100.common.jsonld) +These use the same format, but leverage the `references` field to point to the documents that they wish to extend. -Additionally, someone may wish to augment a previous piece of metadata with new information, divorced from the transaction that initially published it; this may be useful, for example, to provide additional arguments in favor of or against a proposal, provide translations to other languages, provide a layman's explanation of a highly technical document, etc. +These can, in theory, be published anywhere, but the use of metadatum label 1694 mentioned above is particularly useful in this case. -These can, in theory, be published anywhere, but to aide in discoverability for indexing tools, we explicitly call out the Cardano blockchain as a convenient "public square" in which to publish this metadata. +### Context and Schema -To this end, this CIP reserves [metadatum label 1694](../CIP-0010/README.md) for publishing these kinds of augments on-chain. This CIP also provides a minimal JSON-LD schema specifically for these documents, though the vocabulary may be extended in the same way that any other json-ld context can be extended: +We expect a rich ecosystem of CIPs to emerge defining different extensions, so this CIP provides only an initial base-line MVP of fields, defined in the following JSON-LD and JSON Schema files: - - [Augmentation](./cip-100.augmentation.jsonld) + - [JSON-LD Context](./cip-0100.common.jsonld) + - [JSON Schema](./cip-0100.common.schema.json) -The rest of this document will provide a high level description of the properties described in each of the schemas above. +The rest of this document will provide a high level description of how these fields should be interpreted -#### Common properties +### High level description The following properties are considered common to all types of transactions, and the minimal set needed for "minimum viable governance": -- hash-algorithm: The algorithm used to hash the document for the purposes of the on-chain anchor; currently only supports blake2b-256 -- authors: The primary contributors and authors for this metadata document +- `hashAlgorithm`: The algorithm used to hash the document for the purposes of the on-chain anchor; currently only supports blake2b-256 +- `authors`: The primary contributors and authors for this metadata document - An array of objects - - Each object MAY have a display name - - Each object MUST have one or more witnesses - - Each witness may define a context, describing the manner in which the document has been witnessed - - A default witness scheme is described in a later section - - Tooling authors SHOULD validate these witnesses; if absent or invalid, tooling authors SHOULD make this clear in the UI -- body: The material contents of the document, separate for the purposes of signing - - justification - - Freeform text that explains *why* this proposal / vote / registration / retirement is being proposed / made / etc. - - Tooling authors MAY emphasize that this justification represents the view of the authors only - - external-updates + - Each object MAY have a `name` property, which serves as a display name + - Each object MUST have a `witness` field, which contains a signature of the `body` of the document + - The witness may define a `@context`, describing the manner in which the document has been witnessed + - A default witness scheme context is described in a later section + - Tooling authors SHOULD validate witnesses they understand + - If witnesses aren't validated, tooling authors SHOULD emphasize this to the user + - If absent or invalid, tooling authors SHOULD make this clear to the user +- `body`: The material contents of the document, separate for the purposes of signing + - `references` + - An array of objects + - Each object specifies a `@type`, which is either "GovernanceMetadata" or "Other" + - Each object specifies a `label`, which serves as a human readable display name + - Each object specifies a `uri`; when the type is set to "GovernanceMetadata", the URI should point to another CIP-0100 compliant document + - `comment` + - Freeform text attached to the metadata; richer structures for justifying the transaction this is attached to is left to future CIPs + - Tooling authors SHOULD emphasize that these comments represent the *authors* views, and may contain bias. + - `externalUpdates` - A array of objects - - Each object can have a context defining how to interpret it - - by default, assumed to just be a title and a URL - - The purpose is to allow "additional updates", that aren't written yet + - Each object can have a `@context` defining how to interpret it + - by default, assumed to just be an object with a `title` and `uri` field + - The purpose is to allow "additional updates", that aren't written yet, such as a blog or RSS feed - Tooling authors MAY fetch and parse this metadata according to this standard, - If so, Tooling authors MUST emphasize that this information is second-class, given that it might have changed -An example jsonld specification for the above context is specified in - - [cip-100.common.jsonld](./cip-100.common.jsonld) - Additionally, we highlight the following concepts native to json-ld that are useful in the context of governance metadata: - [@language](https://www.w3.org/TR/json-ld11/#string-internationalization) - - The `@context` field SHOULD specify a `@language` property, which is an ISO 639-1 language string, to define a default language for the whole document - - Specific sub-fields can specify different languages - - The `@context` field may specify a `@container` property set to `@language`, in which case the property becomes a map with different translations of the property - - Tooling authors MAY provide automatic translation, but SHOULD make the original prose easily available - -Open Questions: - - [ ] Investigate whether the activity-pub / activity-streams is appropriate for external updates @Nils - - [ ] @santicmaru and I are still working on the jsonld files + - The `@context` field SHOULD specify a `@language` property, which is an ISO 639-1 language string, to define a default language for the whole document + - Specific sub-fields can specify different languages + - The `@context` field may specify a `@container` property set to `@language`, in which case the property becomes a map with different translations of the property + - Tooling authors MAY provide automatic translation, but SHOULD make the original prose easily available ### Hashing and Signatures When publishing a governance action, the certificate has an "anchor", defined as a URI and a hash of the content at the URI. -For CIP-100 compliant metadata, the hash in the anchor should be the blake2b-256 hash of the "Canonized" form of the document. This canonicalization is to remove ambiguities in serialization format and ensure that all consumers arrive at the same hash. The canonicalization algorithm for JSON-LD is specified [here](https://w3c-ccg.github.io/rdf-dataset-canonicalization/spec/). +For CIP-0100 compliant metadata, the hash in the anchor should be the blake2b-256 hash of the "Canonized" form of the full document. This canonicalization is to remove ambiguities in serialization format and ensure that all consumers arrive at the same hash. The canonicalization algorithm for JSON-LD is specified [here](https://w3c-ccg.github.io/rdf-dataset-canonicalization/spec/). A metadata has a number of authors, each of which MUST authenticate their endorsement of the document in some way. -This is left extensible, through the use of a new context, but for the purposes of this CIP alone, a default scheme is defined. +This is left extensible, through the use of a new context, but for the purposes of this CIP, we provide a simple scheme. -Each author should have one or more witnesses. The witness will be an object with an algorithm (set to ed25519), a public key (set to an ed25519 public key), and a signature. +Each author should have a witness. The witness will be an object with an `witnessAlgorithm` (set to ed25519), a `publicKey` (set to a base-16 encoded ed25519 public key), and a `signature`, set to the base-16 encoded signature of the body field. -The signature is the ed5519 signature using the attached public key, of the hash of the canonical form of the `body` field of the document. This is to separate the certifiable material from the non-certifiable material. +Because the overall document may change, it is neccesary to hash a subset of the document that is known before any signatures are collected. This is the motivation behind the `body` field. -Open Questions: - - [ ] Should we leverage https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.jsonld in any way, or other DID specifications? - - Frankly, the whole DID space seems to make things way more complicated than it needs to be heh - - [ ] What is the exact procedure for canonicalizing the body? - - We can't just pluck the body field from the JSON, unless we say it inherits the context from the original document - - There's not a clear way to extract the subset of an object from the canonical format +The signature is an ed5519 signature using the attached public key, and the payload set to the blake2b-256 hash of the `body` field. Specifically, this field is canonicalized in the following way. +- Canonicalize the whole document according to [this](https://w3c-ccg.github.io/rdf-dataset-canonicalization/spec/) specification. +- Identify the node-ID of the `body` node +- Filter the canonicalized document to include the body node, and all its descendents +- Ensure the file ends in a newline +- Hash the resulting file with blake2b-256 ### Best Practices @@ -261,6 +267,14 @@ The following alternatives were considered, and rejected: - The metadata in question, despite being proliferous, is not expected to to be an undue storage burden; It's not, for example, video data, or storing billions of records. - It is more important, then, that the metadata be human readable, so that tooling authors have the option to show this data in its raw format to a user, and for it to be loosely understandable even by non-technical users. +## Test Vectors + +An example document with an inline context is provided in [this](./example.json) example JSON file. + +Canonicalization should produce the following blak2b-256 hash: + +34cbb91e044cbd1dbda9e5aa542a74e712d23d0bf151c436c52920dcac03629c + ## Path to Active The path for this proposal to be considered active within the community focuses on 4 key stages: Feedback, Implementation, Adoption, and Extension. diff --git a/CIP-0100/cip-0100.common.jsonld b/CIP-0100/cip-0100.common.jsonld new file mode 100644 index 000000000..931637922 --- /dev/null +++ b/CIP-0100/cip-0100.common.jsonld @@ -0,0 +1,45 @@ +{ + "@context": { + "Proposal": "https://cips.cardano.org/cip/CIP-0100#Proposal", + "hashAlgorithm": "https://cips.cardano.org/cip/CIP-0100#hashAlgorithm", + "body": { + "@id": "https://cips.cardano.org/cip/CIP-0100#body", + "@context": { + "references": { + "@id": "https://cips.cardano.org/cip/CIP-0100#references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "https://cips.cardano.org/cip/CIP-0100#GovernanceMetadataReference", + "Other": "https://cips.cardano.org/cip/CIP-0100#OtherReference", + "label": "https://cips.cardano.org/cip/CIP-0100#reference-label", + "uri": "https://cips.cardano.org/cip/CIP-0100#reference-uri" + } + }, + "comment": "https://cips.cardano.org/cip/CIP-0100#comment", + "externalUpdates": { + "@id": "https://cips.cardano.org/cip/CIP-0100#externalUpdates", + "@context": { + "title": "https://cips.cardano.org/cip/CIP-0100#update-title", + "uri": "https://cips.cardano.org/cip/CIP-0100#update-uri" + } + } + } + }, + "authors": { + "@id": "https://cips.cardano.org/cip/CIP-0100#authors", + "@container": "@set", + "@context": { + "did": "@id", + "name": "http://xmlns.com/foaf/0.1/name", + "witness": { + "@id": "https://cips.cardano.org/cip/CIP-0100#witness", + "@context": { + "witnessAlgorithm": "https://cips.cardano.org/cip/CIP-0100#witnessAlgorithm", + "publicKey": "https://cips.cardano.org/cip/CIP-0100#publicKey", + "signature": "https://cips.cardano.org/cip/CIP-0100#signature" + } + } + } + } + } +} \ No newline at end of file diff --git a/CIP-0100/cip-0100.common.schema.json b/CIP-0100/cip-0100.common.schema.json new file mode 100644 index 000000000..8cc15369e --- /dev/null +++ b/CIP-0100/cip-0100.common.schema.json @@ -0,0 +1,146 @@ +{ + "title": "CIP-100 Common", + "description": "A base-line CIP-100 governance metadata document", + "type": "object", + "required": [ + "hashAlgorithm", + "authors", + "body" + ], + "properties": { + "hashAlgorithm": { + "$ref": "#/definitions/hashAlgorithm" + }, + "authors": { + "title": "Authors", + "description": "The authors of this governance metadata", + "type": "array", + "items": { + "$ref": "#/definitions/Author" + } + }, + "body": { + "$ref": "#/definitions/Body" + } + }, + "definitions": { + "hashAlgorithm": { + "title": "Hash Algorithm", + "description": "The hash algorithm used to authenticate this document externally", + "type": "string", + "enum": [ + "blake2b-224" + ] + }, + "Author": { + "title": "Author", + "description": "An author endorsing the content of a metadata document", + "type": "object", + "required": [ + "witness" + ], + "properties": { + "name": { + "title": "Name", + "type": "string" + }, + "witness": { + "$ref": "#/definitions/Witness" + } + } + }, + "Witness": { + "title": "Witness", + "description": "A witness proving that the author endorses the content of the metadata", + "type": "object", + "properties": { + "witnessAlgorithm": { + "title": "WitnessAlgorithm", + "type": "string", + "enum": [ + "ed25519" + ] + }, + "publicKey": { + "title": "PublicKey", + "type": "string" + }, + "signature": { + "title": "Signature", + "type": "string" + } + } + }, + "Body": { + "title": "Body", + "description": "The body of the metadata document that is hashed to produce a signature", + "properties": { + "references": { + "title": "References", + "type": "array", + "items": { + "$ref": "#/definitions/Reference" + } + }, + "comment": { + "title": "Comment", + "type": "string" + }, + "externalUpdatess": { + "title": "ExternalUpdates", + "type": "array", + "items": { + "$ref": "#/definitions/ExternalUpdate" + } + } + } + }, + "Reference": { + "title": "Reference", + "description": "A reference to a document", + "type": "object", + "required": [ + "@type", + "label", + "uri" + ], + "properties": { + "@type": { + "title": "Type", + "type": "string", + "enum": [ + "GovernanceMetadata", + "Other" + ] + }, + "label": { + "title": "Label", + "type": "string" + }, + "uri": { + "title": "URI", + "type": "string" + } + } + }, + "ExternalUpdate": { + "title": "ExternalUpdate", + "type": "object", + "description": "An source for updates *after* the metadata is published", + "required": [ + "title", + "uri" + ], + "properties": { + "title": { + "title": "Title", + "type": "string" + }, + "uri": { + "title": "URI", + "type": "string" + } + } + } + } +} \ No newline at end of file diff --git a/CIP-0100/cip-100.augmentation.jsonld b/CIP-0100/cip-100.augmentation.jsonld deleted file mode 100644 index adfb1dafc..000000000 --- a/CIP-0100/cip-100.augmentation.jsonld +++ /dev/null @@ -1,5 +0,0 @@ -{ - "@context": { - - } -} \ No newline at end of file diff --git a/CIP-0100/cip-100.common.jsonld b/CIP-0100/cip-100.common.jsonld deleted file mode 100644 index fccd708c2..000000000 --- a/CIP-0100/cip-100.common.jsonld +++ /dev/null @@ -1,18 +0,0 @@ -{ - "@context": { - "hash-algorithm": "", - "authors": { - "@container": "@set", - "@type": "" - }, - "body": { - "@context": { - "justification": "", - "external-updates": { - "@container": "@set", - "@type": "" - }, - } - } - } -} \ No newline at end of file diff --git a/CIP-0100/example.body.canonical b/CIP-0100/example.body.canonical new file mode 100644 index 000000000..fda1165f3 --- /dev/null +++ b/CIP-0100/example.body.canonical @@ -0,0 +1,9 @@ +_:c14n0 "Blog"@en-us . +_:c14n0 "https://314pool.com"@en-us . +_:c14n2 _:c14n5 . +_:c14n3 . +_:c14n3 "CIP-100"@en-us . +_:c14n3 "https://cips.cardano.org/cip/CIP-0100"@en-us . +_:c14n5 "This is a test vector for CIP-100"@en-us . +_:c14n5 _:c14n0 . +_:c14n5 _:c14n3 . diff --git a/CIP-0100/example.canonical b/CIP-0100/example.canonical new file mode 100644 index 000000000..f0f95ac81 --- /dev/null +++ b/CIP-0100/example.canonical @@ -0,0 +1,10 @@ +_:c14n0 "Blog"@en-us . +_:c14n0 "https://314pool.com"@en-us . +_:c14n2 _:c14n5 . +_:c14n3 . +_:c14n3 "CIP-100"@en-us . +_:c14n3 "https://cips.cardano.org/cip/CIP-0100"@en-us . +_:c14n4 "Pi Lanningham"@en-us . +_:c14n5 "This is a test vector for CIP-100"@en-us . +_:c14n5 _:c14n0 . +_:c14n5 _:c14n3 . diff --git a/CIP-0100/example.json b/CIP-0100/example.json new file mode 100644 index 000000000..d0add95a6 --- /dev/null +++ b/CIP-0100/example.json @@ -0,0 +1,59 @@ +{ + "@context": { + "@language": "en-us", + "Proposal": "https://cips.cardano.org/cip/CIP-0100#Proposal", + "hashAlgorithm": "https://cips.cardano.org/cip/CIP-0100#hashAlgorithm", + "body": { + "@id": "https://cips.cardano.org/cip/CIP-0100#body", + "@context": { + "references": { + "@id": "https://cips.cardano.org/cip/CIP-0100#references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "https://cips.cardano.org/cip/CIP-0100#GovernanceMetadataReference", + "Other": "https://cips.cardano.org/cip/CIP-0100#OtherReference", + "label": "https://cips.cardano.org/cip/CIP-0100#reference-label", + "uri": "https://cips.cardano.org/cip/CIP-0100#reference-uri" + } + }, + "comment": "https://cips.cardano.org/cip/CIP-0100#comment", + "externalUpdates": { + "@id": "https://cips.cardano.org/cip/CIP-0100#externalUpdates", + "@context": { + "title": "https://cips.cardano.org/cip/CIP-0100#update-title", + "uri": "https://cips.cardano.org/cip/CIP-0100#update-uri" + } + } + } + }, + "authors": { + "@id": "https://cips.cardano.org/cip/CIP-0100#authors", + "@container": "@set", + "@context": { + "did": "@id", + "name": "http://xmlns.com/foaf/0.1/name", + "witness": { + "@id": "https://cips.cardano.org/cip/CIP-0100#witness", + "@context": { + "witnessAlgorithm": "https://cips.cardano.org/cip/CIP-0100#witnessAlgorithm", + "publicKey": "https://cips.cardano.org/cip/CIP-0100#publicKey", + "signature": "https://cips.cardano.org/cip/CIP-0100#signature" + } + } + } + } + }, + "hashAlgorithm": "blake2b-224", + "authors": [ + { "name": "Pi Lanningham", "witness": { "witnessAlgorithm": "ed25519", "publicKey": "46e4db7f87497ba232977ccd591b3d040316b155e8c60e3ea49176c03fa269de", "signature": "abcd"}} + ], + "body": { + "references": [ + { "@type": "Other", "label": "CIP-100", "uri": "https://cips.cardano.org/cip/CIP-0100" } + ], + "comment": "This is a test vector for CIP-100", + "externalUpdates": [ + { "title": "Blog", "uri": "https://314pool.com" } + ] + } + } \ No newline at end of file From badf723b7d0de401b4f1aa954faa4adcce7f1d06 Mon Sep 17 00:00:00 2001 From: Pi Lanningham Date: Tue, 12 Dec 2023 11:23:29 -0500 Subject: [PATCH 8/8] Update CIP-0100/README.md Co-authored-by: Ryan Williams <44342099+Ryun1@users.noreply.github.com> --- CIP-0100/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0100/README.md b/CIP-0100/README.md index 954314263..64d4c9b57 100644 --- a/CIP-0100/README.md +++ b/CIP-0100/README.md @@ -267,7 +267,7 @@ The following alternatives were considered, and rejected: - The metadata in question, despite being proliferous, is not expected to to be an undue storage burden; It's not, for example, video data, or storing billions of records. - It is more important, then, that the metadata be human readable, so that tooling authors have the option to show this data in its raw format to a user, and for it to be loosely understandable even by non-technical users. -## Test Vectors +### Test Vectors An example document with an inline context is provided in [this](./example.json) example JSON file.