From 5defb6da86c187f57cab1c9085395ebf4becbad4 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 23 Nov 2023 17:20:26 +0000 Subject: [PATCH 01/19] init governance action metadata --- CIP-governance-metadata-actions/README.md | 98 +++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 CIP-governance-metadata-actions/README.md diff --git a/CIP-governance-metadata-actions/README.md b/CIP-governance-metadata-actions/README.md new file mode 100644 index 000000000..433fe0d95 --- /dev/null +++ b/CIP-governance-metadata-actions/README.md @@ -0,0 +1,98 @@ +--- +CIP: ? +Title: Governance Metadata - Governance Actions +Category: Metadata +Status: Proposed +Authors: + - Ryan Williams +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2023-11-23 +License: CC-BY-4.0 +--- + +## Abstract +The conway ledger era ushers in on-chain governance for Cardano via [CIP-1694 | A First Step Towards On-Chain Decentralized Governance](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md), with the addition of many new on-chain governance artifacts. +Some of these artifacts support the linking off-chain metadata, as a way to provide context. + +The [CIP-100 | Governance Metadata](https://github.com/cardano-foundation/CIPs/pull/556) standard provides a base framework for how all governance metadata should be formed and handled. +But this is intentionally limited in scope, so that it can be expanded upon by more specific subsequent CIPs. + +This proposal aims to provided a specification for off-chain metadata which gives context to governance actions, building on from the CIP-100 framework. +Without a sufficiently detailed standard for governance actions we introduce the possibility to undermine voters ability to adequately assess governance actions. +Furthermore a lack of such standards risks preventing interoperability between tools, to the detriment of user experiences. + +## Motivation: why is this CIP necessary? +Motivation for voters: +- The onchain information for GAs is very limited, it is the WHAT/HOW and not the WHY. +- Possible undermine governance is WHY is not supplied +- Provides an onchain history to attach to GAs (how should this be hosted?) +- We aim to provide base requirements for ALL GAs, more specific standards can follow.w + +Motivation for tooling: +By standardizing off-chain metadata formats we facilitate interoperability for tooling which creates and/or renders metadata attached to governance actions. +This intern promotes the user experience between tooling. + +The stake holders for this proposal are all of those users who intend to participate within governance via voting directly. +Furthermore, governance related indexing and submission based tooling providers. + +## Specification +Although there are seven types of governance action defined via CIP-1694, we focus this proposal on defining core properties which must be attached to all types. +We leave room for future standards to refine and specialize further to cater more specific for each type of governance action. + +### Extended Vocabulary +The following properties extend the vocably of CIP-100. + +#### Title +- This should be a sentence which should act as a human readable identifier for the GA +- It should briefly introduce the GA + - i.e; Increase K protocol parameter to 100,000 to increase decentralization of Cardano. +- The intention for this field is to act as a quick and clear differentiator between governance actions + +#### Abstract +- This should be a short amount of free flow text, limited to ~200 words. +- This should a short description of the reason behind the GA, so if a problem is being addressed, what why and how +- This should summarizes the problem and how GA fixes the problem - to help voters gain an understanding the context behind the GA + +#### Motivation +- This should be longer free form text encapsulating context around the problem that the GA is addressing. +- The content should also include mention of the use cases and stakeholders +- This field is an opportunity for the author to provide full context to the problem being addressed. + +#### Rationale +- This should be longer free form text discussing how the GA addresses the problem identified in the motivation +- i.e "by increasing X parameter we increase rewards for SPOs thus encouraging new SPOs to join the network +- This section should fully justify the changes being made to Cardano +- This should include what led to particular design decisions +- It should describe alternate designs considered and related work. +- The rationale should provide evidence of consensus within the community and discuss significant objections or concerns raised during the discussion. +- For some GAs this section SHOULD to be very long. + +### Versioning +This proposal should not be versioned, to update this standard a new CIP should be proposed. + +## Rationale: how does this CIP achieve its goals? +- base standard, good for MVP, makes this more straight forward to implement and support for all +- want to start simple with this proposal - MVG +- fields based on the CIP process with the specification and most of the header removed + +### Open Questions +- Should fields be optional or compulsory? + +## Path to Active + +### Acceptance Criteria +- [ ] This standard is supported by two different tooling providers used to submit governance actions to chain. +- [ ] This standard is supported by two different chain indexing tools, used to read and render metadata + +### Implementation Plan +Solicitation of feedback +- [ ] Run X online workshops to gather insights from stakeholders +- [ ] Seek community answers on all [Open Questions](#open-questions) +Implementation +- [ ] Author to provide reference implementation in a dApp form. +- [ ] Author to provide example metadata. + +## 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 918d842c22af08ee139c4ec5e949f2d05282f966 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 1 Dec 2023 17:45:49 +0000 Subject: [PATCH 02/19] details --- CIP-governance-metadata-actions/README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/CIP-governance-metadata-actions/README.md b/CIP-governance-metadata-actions/README.md index 433fe0d95..6b1d5cd73 100644 --- a/CIP-governance-metadata-actions/README.md +++ b/CIP-governance-metadata-actions/README.md @@ -16,7 +16,7 @@ License: CC-BY-4.0 The conway ledger era ushers in on-chain governance for Cardano via [CIP-1694 | A First Step Towards On-Chain Decentralized Governance](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md), with the addition of many new on-chain governance artifacts. Some of these artifacts support the linking off-chain metadata, as a way to provide context. -The [CIP-100 | Governance Metadata](https://github.com/cardano-foundation/CIPs/pull/556) standard provides a base framework for how all governance metadata should be formed and handled. +The [CIP-100 | Governance Metadata](https://github.com/cardano-foundation/CIPs/pull/556) standard provides a base framework for how all off-chain governance metadata should be formed and handled. But this is intentionally limited in scope, so that it can be expanded upon by more specific subsequent CIPs. This proposal aims to provided a specification for off-chain metadata which gives context to governance actions, building on from the CIP-100 framework. @@ -24,6 +24,12 @@ Without a sufficiently detailed standard for governance actions we introduce the Furthermore a lack of such standards risks preventing interoperability between tools, to the detriment of user experiences. ## Motivation: why is this CIP necessary? +Blockchains are poor choices to act as content databases. +This is why governance metadata anchors were chosen to provide a way to attach long form metadata content to on-chain events. +By only supplying an onchain hash of the off-chain we ensure correctness of data whilst minimizing the amount of data posted to the chain. + +When observing from the chain level, tooling can only observe the content of the governance action and it's anchor. + Motivation for voters: - The onchain information for GAs is very limited, it is the WHAT/HOW and not the WHY. - Possible undermine governance is WHY is not supplied @@ -79,6 +85,7 @@ This proposal should not be versioned, to update this standard a new CIP should ### Open Questions - Should fields be optional or compulsory? +- How do the above fields relate to the CIP-100 justification field? ## Path to Active @@ -88,8 +95,8 @@ This proposal should not be versioned, to update this standard a new CIP should ### Implementation Plan Solicitation of feedback -- [ ] Run X online workshops to gather insights from stakeholders -- [ ] Seek community answers on all [Open Questions](#open-questions) +- [ ] Run X online workshops to gather insights from stakeholders. +- [ ] Seek community answers on all [Open Questions](#open-questions). Implementation - [ ] Author to provide reference implementation in a dApp form. - [ ] Author to provide example metadata. From 21b467d1a2bf5d16c5db7b80adee98116278eda1 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Mon, 4 Dec 2023 23:08:16 +0000 Subject: [PATCH 03/19] add details from first workshop and general clean up --- CIP-governance-metadata-actions/README.md | 85 +++++++++++++++-------- 1 file changed, 56 insertions(+), 29 deletions(-) diff --git a/CIP-governance-metadata-actions/README.md b/CIP-governance-metadata-actions/README.md index 6b1d5cd73..a52c5c059 100644 --- a/CIP-governance-metadata-actions/README.md +++ b/CIP-governance-metadata-actions/README.md @@ -4,10 +4,10 @@ Title: Governance Metadata - Governance Actions Category: Metadata Status: Proposed Authors: - - Ryan Williams + - Ryan Williams Implementors: [] Discussions: - - https://github.com/cardano-foundation/cips/pulls/? + - https://github.com/cardano-foundation/cips/pulls/632 Created: 2023-11-23 License: CC-BY-4.0 --- @@ -23,65 +23,92 @@ This proposal aims to provided a specification for off-chain metadata which give Without a sufficiently detailed standard for governance actions we introduce the possibility to undermine voters ability to adequately assess governance actions. Furthermore a lack of such standards risks preventing interoperability between tools, to the detriment of user experiences. +### Acknowledgments + +
+ Governance Metadata Working Group - Workshop #1 2023-12-04 + + I would like to thank those that contributed to the Governance Metadata Working Group Workshop #1 hosted by Ryan Williams ([see presentation slides with notes](https://docs.google.com/presentation/d/18OK3vXexCc8ZXq-dC00RDPPKcy2Zu4DiMo8PeIZ47_4/)). + + Thank you to the co-hosts: + - Adam Dean + - Thomas Upfield + + Thank you to the participants: + - Carlos Lopez de Lara + - Igor Veličković + - Johnny Kelly + - Kenric Nelson + - Kevin Hammond + - Lorenzo Bruno + - Rhys Morgan + - Eric Alton + - Samuel Leathers + - Vladimir Kalnitsky + +
+ ## Motivation: why is this CIP necessary? Blockchains are poor choices to act as content databases. This is why governance metadata anchors were chosen to provide a way to attach long form metadata content to on-chain events. By only supplying an onchain hash of the off-chain we ensure correctness of data whilst minimizing the amount of data posted to the chain. -When observing from the chain level, tooling can only observe the content of the governance action and it's anchor. - -Motivation for voters: -- The onchain information for GAs is very limited, it is the WHAT/HOW and not the WHY. -- Possible undermine governance is WHY is not supplied -- Provides an onchain history to attach to GAs (how should this be hosted?) -- We aim to provide base requirements for ALL GAs, more specific standards can follow.w +### For voters +When observing from the chain level, tooling can only see the content of the governance action and it's anchor. +These on-chain components do not give give any context to the motivation nor off-chain discussion of an governance action. +Although this information would likely be desired context for voters. +By providing rich contextual metadata we enable voters to make well informed decisions. -Motivation for tooling: +### For all participants By standardizing off-chain metadata formats we facilitate interoperability for tooling which creates and/or renders metadata attached to governance actions. -This intern promotes the user experience between tooling. - -The stake holders for this proposal are all of those users who intend to participate within governance via voting directly. -Furthermore, governance related indexing and submission based tooling providers. +This intern promotes a rich user experience between tooling. +This is good for all governance participants. ## Specification Although there are seven types of governance action defined via CIP-1694, we focus this proposal on defining core properties which must be attached to all types. We leave room for future standards to refine and specialize further to cater more specific for each type of governance action. ### Extended Vocabulary -The following properties extend the vocably of CIP-100. +The following properties extend the vocably of [CIP-100's body field](https://github.com/Quantumplation/CIPs/blob/2382cf0c69a11ee1bd53c48a2dbb19c5759515f5/CIP-0100/README.md?plain=1#L171C1-L181C116). #### Title -- This should be a sentence which should act as a human readable identifier for the GA -- It should briefly introduce the GA +- This should be a sentence which should act as a human readable identifier for the GA. +- It should briefly introduce the GA so at a glance users can differentiate actions. - i.e; Increase K protocol parameter to 100,000 to increase decentralization of Cardano. -- The intention for this field is to act as a quick and clear differentiator between governance actions +- The intention for this field is to act as a quick and clear differentiator between governance actions. #### Abstract - This should be a short amount of free flow text, limited to ~200 words. -- This should a short description of the reason behind the GA, so if a problem is being addressed, what why and how -- This should summarizes the problem and how GA fixes the problem - to help voters gain an understanding the context behind the GA +- This should a short description of the reason behind the GA, so if a problem is being addressed: what, why and how. +- This should summarizes the problem and how GA fixes the problem - to help voters gain an understanding the context behind the GA without having to dig in too deep. +- This could help a user differentiate two actions which are having the same onchain effect, with similar titles. #### Motivation - This should be longer free form text encapsulating context around the problem that the GA is addressing. -- The content should also include mention of the use cases and stakeholders +- The content should also include mention of the use cases and stakeholders. - This field is an opportunity for the author to provide full context to the problem being addressed. #### Rationale -- This should be longer free form text discussing how the GA addresses the problem identified in the motivation -- i.e "by increasing X parameter we increase rewards for SPOs thus encouraging new SPOs to join the network -- This section should fully justify the changes being made to Cardano -- This should include what led to particular design decisions +- This should be longer free form text discussing how the GA addresses the problem identified in the motivation. +- i.e "by increasing X parameter we increase rewards for SPOs thus encouraging new SPOs to join the network. +- This section should fully justify the changes being made to Cardano. +- This should include what led to particular design decisions. - It should describe alternate designs considered and related work. - The rationale should provide evidence of consensus within the community and discuss significant objections or concerns raised during the discussion. - For some GAs this section SHOULD to be very long. +- This should include any recommendations made by relevant organizations or committees. ### Versioning This proposal should not be versioned, to update this standard a new CIP should be proposed. +Although through the JSON-LD mechanism further CIPs can add to the fields defined here. ## Rationale: how does this CIP achieve its goals? -- base standard, good for MVP, makes this more straight forward to implement and support for all -- want to start simple with this proposal - MVG -- fields based on the CIP process with the specification and most of the header removed + +// todo + +- base standard, good for MVP, makes this more straight forward to implement and support for all. +- want to start simple with this proposal - MVG. +- fields based on the CIP process with the specification and most of the header removed. ### Open Questions - Should fields be optional or compulsory? @@ -95,7 +122,7 @@ This proposal should not be versioned, to update this standard a new CIP should ### Implementation Plan Solicitation of feedback -- [ ] Run X online workshops to gather insights from stakeholders. +- [ ] Run X number of online workshops to gather insights from stakeholders. - [ ] Seek community answers on all [Open Questions](#open-questions). Implementation - [ ] Author to provide reference implementation in a dApp form. From 0f94e980cf9cce8c2c0f70292988a4161dc7b5db Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Mon, 4 Dec 2023 23:17:59 +0000 Subject: [PATCH 04/19] added missing participant from workshop 1 --- CIP-governance-metadata-actions/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CIP-governance-metadata-actions/README.md b/CIP-governance-metadata-actions/README.md index a52c5c059..13c6bee23 100644 --- a/CIP-governance-metadata-actions/README.md +++ b/CIP-governance-metadata-actions/README.md @@ -41,6 +41,7 @@ Furthermore a lack of such standards risks preventing interoperability between t - Kenric Nelson - Kevin Hammond - Lorenzo Bruno + - Mike Susko - Rhys Morgan - Eric Alton - Samuel Leathers From c3440c819b55cdfc0122b26a01cd9dd894a35c5d Mon Sep 17 00:00:00 2001 From: Ryan Williams <44342099+Ryun1@users.noreply.github.com> Date: Wed, 13 Dec 2023 16:24:28 +0000 Subject: [PATCH 05/19] Update CIP-governance-metadata-actions/README.md Co-authored-by: Robert Phair --- CIP-governance-metadata-actions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-actions/README.md b/CIP-governance-metadata-actions/README.md index 13c6bee23..a14e800ac 100644 --- a/CIP-governance-metadata-actions/README.md +++ b/CIP-governance-metadata-actions/README.md @@ -1,5 +1,5 @@ --- -CIP: ? +CIP: 108 Title: Governance Metadata - Governance Actions Category: Metadata Status: Proposed From 20f2fa86aa8cc70fc268ec573dfe1b49af788c3b Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Wed, 13 Dec 2023 16:38:40 +0000 Subject: [PATCH 06/19] align folder name with 108 numbering --- {CIP-governance-metadata-actions => CIP-0108}/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {CIP-governance-metadata-actions => CIP-0108}/README.md (100%) diff --git a/CIP-governance-metadata-actions/README.md b/CIP-0108/README.md similarity index 100% rename from CIP-governance-metadata-actions/README.md rename to CIP-0108/README.md From 16f15c66a1537f40aa8a31d8ed9f115fbf2f45bc Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 14 Dec 2023 21:07:00 +0000 Subject: [PATCH 07/19] add notes from workshop 2 --- CIP-0108/README.md | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index a14e800ac..e04c2c66a 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -16,10 +16,10 @@ License: CC-BY-4.0 The conway ledger era ushers in on-chain governance for Cardano via [CIP-1694 | A First Step Towards On-Chain Decentralized Governance](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md), with the addition of many new on-chain governance artifacts. Some of these artifacts support the linking off-chain metadata, as a way to provide context. -The [CIP-100 | Governance Metadata](https://github.com/cardano-foundation/CIPs/pull/556) standard provides a base framework for how all off-chain governance metadata should be formed and handled. +The [CIP-100 | Governance Metadata](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100) standard provides a base framework for how all off-chain governance metadata should be formed and handled. But this is intentionally limited in scope, so that it can be expanded upon by more specific subsequent CIPs. -This proposal aims to provided a specification for off-chain metadata which gives context to governance actions, building on from the CIP-100 framework. +This proposal aims to provide a specification for off-chain metadata vocabulary can be used to give context to governance actions, CIP-100. Without a sufficiently detailed standard for governance actions we introduce the possibility to undermine voters ability to adequately assess governance actions. Furthermore a lack of such standards risks preventing interoperability between tools, to the detriment of user experiences. @@ -49,6 +49,22 @@ Furthermore a lack of such standards risks preventing interoperability between t +
+ Governance Metadata Working Group - Workshop #2 2023-12-14 + + I would like to thank those that contributed to the Governance Metadata Working Group Workshop #2 hosted by Ryan Williams ([see presentation slides with notes](https://docs.google.com/presentation/d/1tFsyQnONjwyTm7zKrnxxedzWsoonO6-8vXw5vYzB3qs)). + + Thank you to the co-host: + - Adam Dean + + Thank you to the participants: + - Mark Byers + - Nils Codes + + Thank you to the bots that joined also. + +
+ ## Motivation: why is this CIP necessary? Blockchains are poor choices to act as content databases. This is why governance metadata anchors were chosen to provide a way to attach long form metadata content to on-chain events. @@ -70,7 +86,7 @@ Although there are seven types of governance action defined via CIP-1694, we foc We leave room for future standards to refine and specialize further to cater more specific for each type of governance action. ### Extended Vocabulary -The following properties extend the vocably of [CIP-100's body field](https://github.com/Quantumplation/CIPs/blob/2382cf0c69a11ee1bd53c48a2dbb19c5759515f5/CIP-0100/README.md?plain=1#L171C1-L181C116). +The following properties extend the potential vocabulary of [CIP-100](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100). #### Title - This should be a sentence which should act as a human readable identifier for the GA. @@ -99,21 +115,26 @@ The following properties extend the vocably of [CIP-100's body field](https://gi - For some GAs this section SHOULD to be very long. - This should include any recommendations made by relevant organizations or committees. +#### References +- set of: index, title, URI, hash (optional nice-to-have) +- Can link to Intersect working groups discussions +- Ability to add more verifiably correct information. + ### Versioning This proposal should not be versioned, to update this standard a new CIP should be proposed. -Although through the JSON-LD mechanism further CIPs can add to the fields defined here. +Although through the JSON-LD mechanism further CIPs can add to the common governance metadata vocabulary, ## Rationale: how does this CIP achieve its goals? - -// todo - - base standard, good for MVP, makes this more straight forward to implement and support for all. - want to start simple with this proposal - MVG. - fields based on the CIP process with the specification and most of the header removed. +- want to build in "layers of investigation" for voters, enforced via character limit on fields. ### Open Questions -- Should fields be optional or compulsory? -- How do the above fields relate to the CIP-100 justification field? +- Should fields be optional or compulsory? + - Title, abstract, motivation and rationale should be compulsory as they should be very important to the ability +- How much vocabulary can be extended to other onchain events? +- How to integrate custom set of HTML tags? to allow formatting of longer text fields. ## Path to Active From a0da8460a89f7c8e97a3da0df6fc5a421a6c7334 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Mon, 22 Jan 2024 14:59:09 +0000 Subject: [PATCH 08/19] turn notes to text --- CIP-0108/README.md | 139 ++++++++++++++++++++++++++++------------ CIP-0108/test-vector.md | 47 ++++++++++++++ 2 files changed, 144 insertions(+), 42 deletions(-) create mode 100644 CIP-0108/test-vector.md diff --git a/CIP-0108/README.md b/CIP-0108/README.md index e04c2c66a..42805b996 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -5,7 +5,8 @@ Category: Metadata Status: Proposed Authors: - Ryan Williams -Implementors: [] +Implementors: + - Ryan Williams Discussions: - https://github.com/cardano-foundation/cips/pulls/632 Created: 2023-11-23 @@ -86,65 +87,119 @@ Although there are seven types of governance action defined via CIP-1694, we foc We leave room for future standards to refine and specialize further to cater more specific for each type of governance action. ### Extended Vocabulary -The following properties extend the potential vocabulary of [CIP-100](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100). - -#### Title -- This should be a sentence which should act as a human readable identifier for the GA. -- It should briefly introduce the GA so at a glance users can differentiate actions. - - i.e; Increase K protocol parameter to 100,000 to increase decentralization of Cardano. -- The intention for this field is to act as a quick and clear differentiator between governance actions. - -#### Abstract -- This should be a short amount of free flow text, limited to ~200 words. -- This should a short description of the reason behind the GA, so if a problem is being addressed: what, why and how. -- This should summarizes the problem and how GA fixes the problem - to help voters gain an understanding the context behind the GA without having to dig in too deep. -- This could help a user differentiate two actions which are having the same onchain effect, with similar titles. - -#### Motivation -- This should be longer free form text encapsulating context around the problem that the GA is addressing. -- The content should also include mention of the use cases and stakeholders. -- This field is an opportunity for the author to provide full context to the problem being addressed. - -#### Rationale -- This should be longer free form text discussing how the GA addresses the problem identified in the motivation. -- i.e "by increasing X parameter we increase rewards for SPOs thus encouraging new SPOs to join the network. -- This section should fully justify the changes being made to Cardano. -- This should include what led to particular design decisions. -- It should describe alternate designs considered and related work. -- The rationale should provide evidence of consensus within the community and discuss significant objections or concerns raised during the discussion. -- For some GAs this section SHOULD to be very long. -- This should include any recommendations made by relevant organizations or committees. - -#### References -- set of: index, title, URI, hash (optional nice-to-have) -- Can link to Intersect working groups discussions -- Ability to add more verifiably correct information. +The following properties extend the potential vocabulary of [CIP-100](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100)'s `body` property. + +#### `title` +- A very short freefrom text field. Limited to 20 words. +- Authors SHOULD use this field to succinctly describe the governance action and its motivation. +- Authors SHOULD attempt to make this field unique whilst also avoiding hyperbolic language. +- i.e; Increase K protocol parameter to `100,000` to increase decentralization of Cardano. + +#### `abstract` +- A short freefrom text field. Limited to 300 words. +- Authors SHOULD use this field to expand upon their `title` by describing the contents of the governance action, its motivation and rationale. + +#### `motivation` +- A freeform text field. +- This SHOULD be used by the author to encapsulate all context around the problem that is being solved by the on-chain action. +- This SHOULD be used to outline the related stakeholders and use cases. + +#### `rationale` +- A freeform text field. +- This SHOULD be used by the author to discuss how the content of the governance action addresses the problem outlined within the `motivation`. +- This field SHOULD justify the changes being made to Cardano. +- i.e "by decreasing X parameter by Y we increase Ada earned by SPOs, thus incentivising more people to become SPOs, leading to a more diverse network" +- This SHOULD provide evidence of consensus within the community and discuss significant objections or concerns raised during the discussion. +- This SHOULD include discussion of alternative solutions and related topics/ governance actions. +- This SHOULD include any recommendations made by relevant organizations or committees. + +#### `references` +- An OPTIONAL array of objects. +- Each object MUST have a unique integer `index` field value which increases without gaps from `0`. This is to act as a unique referable ID. +- Each object MUST have a `title` field to describe the reference, such as; "blog - Why we must continue to fund Catalyst". +- Each object MUST have a `URI` field. +- Each object MAY have a OPTIONAL `URIHash` object. + - Each object MUST have a `hash` field. + - Each object MUST have a `hashAlgo` field. +- This should be used by the author to link related or supporting work via the URI, and reference this via the index within their freefrom text fields. + +### Application +Governance action metadata must include all compulsory fields to be considered CIP-0108 compliant. +Unlike with CIP-0100, here we prescribe that authors MUST include all fields. + +### Test Vector +See [test-vector.md](./test-vector.md) for examples. ### Versioning This proposal should not be versioned, to update this standard a new CIP should be proposed. Although through the JSON-LD mechanism further CIPs can add to the common governance metadata vocabulary, ## Rationale: how does this CIP achieve its goals? -- base standard, good for MVP, makes this more straight forward to implement and support for all. -- want to start simple with this proposal - MVG. -- fields based on the CIP process with the specification and most of the header removed. -- want to build in "layers of investigation" for voters, enforced via character limit on fields. +We intentionally have kept this proposal brief and uncomplicated. +This was to reduce the time to develop and deploy this standard. +We think it is better to have a base standard which can be improved, rather than meticulously craft a perfect single standard. +This way we enable tooling which depends on this standard to start development. +Furthermore, it is very difficult to predict future wants/needs now, so by allowing upgrades we build in the ability to improve the standard as new wants/needs arrive. + +The fields which have been chosen for this standard heavily inspired to those used for CIPs. +We did this for two reasons; familiarity and competency. +Those who are involved in Cardano are familiar with the CIP format, meaning they will be intuitively understand these fields being reused here. +These fields in combination have also been fairly battle tested via the CIPs process and thus act as a good standard to describe problems and their solutions. + +### Character Limits + +With this design, we wanted to allow for quick and easy differentiation between governance actions. +We achieve this by facilitating users "layers of investigation", where some fields are limited in size. +This encourages tooling providers to show users the small fields before allowing deep investigation of the larger fields. +By allowing this we aim to improve the experience of prospective voters, when sorting though many governance actions. + +The downside of highlighting some fields over others is that we incentivize hyperbolic and eye catching phrases. +Where authors want their governance action to standout in tooling so use overly dramatic phrasing. +This creates an environment where there is a race to the bottom on voter's attention. +Overall this could decrease the perceived legitimacy of the system. +The counter argument is that tooling providers should not use metadata to solely highlight proposals, rather other means such as cryptographically verified submitters. + +### `title` +This should be used by voters to quickly and easily differentiate between two governance actions which may be having the same or similar on-chain effects. +This is why we have chosen a short character limit, as longer titles would reduce the ability for quick reading. + +### `abstract` +This gives voters one step more detail beyond the `title`. +This allows for a compact description of the what, why and how without the voter having to read the larger fields. + +### `motivation` +The `motivation` is a chance for the author to fully describe the problem that is being solved by the governance action. +This is important as all governance actions are a solution to a problem and thus this is a universal field. +By showing relation to stakeholders the author is able to show that they have performed adequate research on the problem. +Voters can use this field to determine if the problem is sizable enough to warrant voting on. + +### `rationale` +This field gives the author the opportunity to explain how the onchain action is addressing the problem outlined in the motivation. +This gives the author a place to discuss any alternative designs or completing governance actions. +Voters should be able to use this field to evaluate the applicability of the solution to the problem. + +### `references` +References give the author ability to point to supporting research or related work. +These should be used by voters to verify the content of supporting research. +The inclusion of a hash allows for the supporting documentation to be cryptographically verified. ### Open Questions - Should fields be optional or compulsory? - Title, abstract, motivation and rationale should be compulsory as they should be very important to the ability -- How much vocabulary can be extended to other onchain events? -- How to integrate custom set of HTML tags? to allow formatting of longer text fields. +- How much vocabulary can be extended to other onchain governance events? + - It is hard to predict how the scope of future standards before they have been developed. +- How to integrate custom set of HTML tags? to allow formatting of longer text fields. + - Author to make a pull request against CIP-0100, to add this support. ## Path to Active ### Acceptance Criteria - [ ] This standard is supported by two different tooling providers used to submit governance actions to chain. -- [ ] This standard is supported by two different chain indexing tools, used to read and render metadata +- [ ] This standard is supported by two different chain indexing tools, used to read and render metadata. ### Implementation Plan Solicitation of feedback -- [ ] Run X number of online workshops to gather insights from stakeholders. +- [x] Run two online workshops to gather insights from stakeholders. - [ ] Seek community answers on all [Open Questions](#open-questions). Implementation - [ ] Author to provide reference implementation in a dApp form. diff --git a/CIP-0108/test-vector.md b/CIP-0108/test-vector.md new file mode 100644 index 000000000..b84242137 --- /dev/null +++ b/CIP-0108/test-vector.md @@ -0,0 +1,47 @@ +# Test Vector for CIP-0108 + +Here we create some useful definitions and some example metadata. + +## Common Context + +### Common Fields +The context fields which could be added to CIP-108 compliant jsonld files. +See [cip-0108.common.jsonld](./cip-0108.common.jsonld). + +```json + +``` + +### Common Fields Schema +A json schema for the common context fields. +See [cip-0108.common.schema.json](./cip-0108.common.schema.json). + +```json + +``` + +## Examples + +### Treasury Withdrawal +Hash: `` +See [example-treasury-withdrawal.jsonld](./example-treasury-withdrawal.jsonld). + +```json + +``` + +### Motion of No-Confidence +Hash: `` +See [example-no-confidence.jsonld](./example-no-confidence.jsonld). + +```json + +``` + +### Update Protocol Parameters +Hash: `` +See [example-protocol-parameter.jsonld](./example-protocol-parameter.jsonld). + +```json + +``` \ No newline at end of file From 2dc2c01a7cfbab8fb99d9eaa15051038d80a9210 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Tue, 23 Jan 2024 12:28:48 +0000 Subject: [PATCH 09/19] added markdown text formatting --- CIP-0108/README.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index 42805b996..8e51edd56 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -5,8 +5,7 @@ Category: Metadata Status: Proposed Authors: - Ryan Williams -Implementors: - - Ryan Williams +Implementors: [ ] Discussions: - https://github.com/cardano-foundation/cips/pulls/632 Created: 2023-11-23 @@ -86,26 +85,33 @@ This is good for all governance participants. Although there are seven types of governance action defined via CIP-1694, we focus this proposal on defining core properties which must be attached to all types. We leave room for future standards to refine and specialize further to cater more specific for each type of governance action. +### Markdown Text Styling +This standard introduces the possibility of using [Github markdown text styling](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#styling-text) within fields. + ### Extended Vocabulary The following properties extend the potential vocabulary of [CIP-100](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100)'s `body` property. #### `title` -- A very short freefrom text field. Limited to 20 words. +- A very short freefrom text field. Limited to `80` characters. +- This SHOULD NOT support markdown text styling. - Authors SHOULD use this field to succinctly describe the governance action and its motivation. - Authors SHOULD attempt to make this field unique whilst also avoiding hyperbolic language. - i.e; Increase K protocol parameter to `100,000` to increase decentralization of Cardano. #### `abstract` -- A short freefrom text field. Limited to 300 words. +- A short freefrom text field. Limited to `2500` characters. +- This SHOULD support markdown text styling. - Authors SHOULD use this field to expand upon their `title` by describing the contents of the governance action, its motivation and rationale. #### `motivation` - A freeform text field. +- This SHOULD support markdown text styling. - This SHOULD be used by the author to encapsulate all context around the problem that is being solved by the on-chain action. - This SHOULD be used to outline the related stakeholders and use cases. #### `rationale` - A freeform text field. +- This SHOULD support markdown text styling. - This SHOULD be used by the author to discuss how the content of the governance action addresses the problem outlined within the `motivation`. - This field SHOULD justify the changes being made to Cardano. - i.e "by decreasing X parameter by Y we increase Ada earned by SPOs, thus incentivising more people to become SPOs, leading to a more diverse network" @@ -114,10 +120,11 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - This SHOULD include any recommendations made by relevant organizations or committees. #### `references` -- An OPTIONAL array of objects. -- Each object MUST have a unique integer `index` field value which increases without gaps from `0`. This is to act as a unique referable ID. +- We extend CIP-100's references field. +- This SHOULD NOT support markdown text styling. +- To be an OPTIONAL set of objects, using the `@set` property. - Each object MUST have a `title` field to describe the reference, such as; "blog - Why we must continue to fund Catalyst". -- Each object MUST have a `URI` field. +- Each object MUST have a `uri` field. - Each object MAY have a OPTIONAL `URIHash` object. - Each object MUST have a `hash` field. - Each object MUST have a `hashAlgo` field. @@ -147,7 +154,6 @@ Those who are involved in Cardano are familiar with the CIP format, meaning they These fields in combination have also been fairly battle tested via the CIPs process and thus act as a good standard to describe problems and their solutions. ### Character Limits - With this design, we wanted to allow for quick and easy differentiation between governance actions. We achieve this by facilitating users "layers of investigation", where some fields are limited in size. This encourages tooling providers to show users the small fields before allowing deep investigation of the larger fields. @@ -189,7 +195,7 @@ The inclusion of a hash allows for the supporting documentation to be cryptograp - How much vocabulary can be extended to other onchain governance events? - It is hard to predict how the scope of future standards before they have been developed. - How to integrate custom set of HTML tags? to allow formatting of longer text fields. - - Author to make a pull request against CIP-0100, to add this support. + - Since CIP-100 does not intend to support rich text fields such an inclusion would not fit, so we have included such format here. ## Path to Active @@ -202,8 +208,7 @@ Solicitation of feedback - [x] Run two online workshops to gather insights from stakeholders. - [ ] Seek community answers on all [Open Questions](#open-questions). Implementation -- [ ] Author to provide reference implementation in a dApp form. -- [ ] Author to provide example metadata. +- [ ] Author to provide example metadata and schema files. ## 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 81975b0c436b811d5a62aa2208ed1105f7a8fb11 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 1 Feb 2024 13:20:25 +0000 Subject: [PATCH 10/19] add schema and example --- CIP-0108/README.md | 8 +- CIP-0108/cip-0108.common.jsonld | 49 ++++++++ CIP-0108/cip-0108.common.schema.json | 122 ++++++++++++++++++++ CIP-0108/example-treasury-withdrawal.jsonld | 74 ++++++++++++ CIP-0108/test-vector.md | 13 +-- 5 files changed, 250 insertions(+), 16 deletions(-) create mode 100644 CIP-0108/cip-0108.common.jsonld create mode 100644 CIP-0108/cip-0108.common.schema.json create mode 100644 CIP-0108/example-treasury-withdrawal.jsonld diff --git a/CIP-0108/README.md b/CIP-0108/README.md index 8e51edd56..82736e39b 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -125,14 +125,14 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - To be an OPTIONAL set of objects, using the `@set` property. - Each object MUST have a `title` field to describe the reference, such as; "blog - Why we must continue to fund Catalyst". - Each object MUST have a `uri` field. -- Each object MAY have a OPTIONAL `URIHash` object. - - Each object MUST have a `hash` field. - - Each object MUST have a `hashAlgo` field. +- Each object MAY have a OPTIONAL `referenceHash` object. + - Each object MUST have a `hashDigest` field. + - Each object MUST have a `hashAlgorithm` field, which is inherited from CIP-100. - This should be used by the author to link related or supporting work via the URI, and reference this via the index within their freefrom text fields. ### Application Governance action metadata must include all compulsory fields to be considered CIP-0108 compliant. -Unlike with CIP-0100, here we prescribe that authors MUST include all fields. +As this is an extension to CIP-100, all CIP-100 fields can be included within CIP-108 compliant metadata. ### Test Vector See [test-vector.md](./test-vector.md) for examples. diff --git a/CIP-0108/cip-0108.common.jsonld b/CIP-0108/cip-0108.common.jsonld new file mode 100644 index 000000000..f0b2dcc1b --- /dev/null +++ b/CIP-0108/cip-0108.common.jsonld @@ -0,0 +1,49 @@ +{ + "@context": { + "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", + "CIP108": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md#", + "hashAlgorithm": "CIP100:hashAlgorithm", + "body": { + "@id": "CIP108:body", + "@context": { + "references": { + "@id": "CIP108:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri", + "referenceHash": { + "@id": "CIP108:referenceHash", + "@context": { + "hashDigest": "CIP108:hashDigest", + "hashAlgorithm": "CIP100:hashAlgorithm" + } + } + } + }, + "title": "CIP108:title", + "abstract": "CIP108:abstract", + "motivation": "CIP108:motivation", + "rationale": "CIP108:rationale" + } + }, + "authors": { + "@id": "CIP100:authors", + "@container": "@set", + "@context": { + "did": "@id", + "name": "http://xmlns.com/foaf/0.1/name", + "witness": { + "@id": "CIP100:witness", + "@context": { + "witnessAlgorithm": "CIP100:witnessAlgorithm", + "publicKey": "CIP100:publicKey", + "signature": "CIP100:signature" + } + } + } + } + } +} \ No newline at end of file diff --git a/CIP-0108/cip-0108.common.schema.json b/CIP-0108/cip-0108.common.schema.json new file mode 100644 index 000000000..1f6c7b7dd --- /dev/null +++ b/CIP-0108/cip-0108.common.schema.json @@ -0,0 +1,122 @@ +{ + "title": "CIP-108 Common", + "description": "Metadata document for Cardano governance actions, extending CIP-100", + "type": "object", + "required": ["hashAlgorithm", "authors", "body"], + "properties": { + "hashAlgorithm": { + "$ref": "#/definitions/hashAlgorithm" + }, + "authors": { + "$ref": "#/definitions/authors" + }, + "body": { + "$ref": "#/definitions/body" + } + }, + "definitions": { + "hashAlgorithm": { + "type": "string", + "enum": ["blake2b-256"], + "title": "Hash Algorithm", + "description": "The algorithm used to authenticate this document externally (CIP-100)" + }, + "authors": { + "title": "Authors", + "description": "The authors of this governance metadata (CIP-100)", + "type": "array", + "items": { + "$ref": "#/definitions/author" + } + }, + "author": { + "title": "Author", + "description": "An author endorsing the content of a metadata document (CIP-100)", + "type": "object", + "required": ["name", "witness"], + "properties": { + "name": { + "type": "string", + "title": "Name" + }, + "witness": { + "$ref": "#/definitions/witness" + } + } + }, + "body": { + "title": "Body", + "description": "The body of the metadata document that is hashed to produce a signature (CIP-100)", + "type": "object", + "required": ["title", "abstract", "motivation", "rationale"], + "properties": { + "title": { + "type": "string", + "title": "Title", + "description": "A brief introduction to the motivation for the governance action" + }, + "abstract": { + "type": "string", + "title": "Abstract", + "description": "A concise summary of the motivation and rationale for the governance action" + }, + "motivation": { + "type": "string", + "title": "Motivation", + "description": "Context around the problem being addressed by the on-chain action" + }, + "rationale": { + "type": "string", + "title": "Rationale", + "description": "Explanation of how the governance action addresses the problem outlined in 'motivation'" + }, + "references": { + "type": "array", + "title": "References", + "items": { + "$ref": "#/definitions/reference" + } + } + } + }, + "reference": { + "title": "Reference", + "description": "A reference to a document", + "type": "object", + "required": ["type", "label", "uri"], + "properties": { + "type": { + "type": "string", + "enum": ["GovernanceMetadata", "Other"], + "title": "Type" + }, + "label": { + "type": "string", + "title": "Label" + }, + "uri": { + "type": "string", + "title": "URI" + }, + "referenceHash": { + "$ref": "#/definitions/referenceHash" + } + } + }, + "referenceHash": { + "title": "Reference Hash", + "description": "A hash of a reference document", + "type": "object", + "required": ["hashDigest", "hashAlgorithm"], + "properties": { + "hashDigest": { + "type": "string", + "title": "Hash" + }, + "hashAlgorithm": { + "$ref": "#/definitions/hashAlgorithm" + } + } + } + } +} \ No newline at end of file diff --git a/CIP-0108/example-treasury-withdrawal.jsonld b/CIP-0108/example-treasury-withdrawal.jsonld new file mode 100644 index 000000000..3a1569c67 --- /dev/null +++ b/CIP-0108/example-treasury-withdrawal.jsonld @@ -0,0 +1,74 @@ +{ + "@context": { + "@language": "en-us", + "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", + "CIP108": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md#", + "hashAlgorithm": "CIP100:hashAlgorithm", + "body": { + "@id": "CIP108:body", + "@context": { + "references": { + "@id": "CIP108:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri", + "referenceHash": { + "@id": "CIP108:referenceHash", + "@context": { + "hashDigest": "CIP108:hashDigest", + "hashAlgorithm": "CIP100:hashAlgorithm" + } + } + } + }, + "title": "CIP108:title", + "abstract": "CIP108:abstract", + "motivation": "CIP108:motivation", + "rationale": "CIP108:rationale" + } + }, + "authors": { + "@id": "CIP100:authors", + "@container": "@set", + "@context": { + "name": "http://xmlns.com/foaf/0.1/name", + "witness": { + "@id": "CIP100:witness", + "@context": { + "witnessAlgorithm": "CIP100:witnessAlgorithm", + "publicKey": "CIP100:publicKey", + "signature": "CIP100:signature" + } + } + } + } + }, + "hashAlgorithm": "blake2b-256", + "body": { + "title": "Buy Ryan a island", + "abstract": "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island.", + "motivation": "The current problem is that Ryan does not have an island, but he would really like an island.", + "rationale": "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references.", + "references": [ + { + "@type": "Other", + "label": "A cool island for Ryan", + "uri": "https://www.google.com/maps/place/World's+only+5th+order+recursive+island/@62.6511465,-97.7946829,15.75z/data=!4m14!1m7!3m6!1s0x5216a167810cee39:0x11431abdfe4c7421!2sWorld's+only+5th+order+recursive+island!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n!3m5!1s0x5216a167810cee39:0x11431abdfe4c7421!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n?authuser=0&entry=ttu" + } + ] + }, + "authors": [ + { + "name": "Ryan Williams", + "witness": { + "witnessAlgorithm": "ed25519", + "publicKey": "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb", + "signature": "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408" + } + } + ] +} + \ No newline at end of file diff --git a/CIP-0108/test-vector.md b/CIP-0108/test-vector.md index b84242137..9b6690f5b 100644 --- a/CIP-0108/test-vector.md +++ b/CIP-0108/test-vector.md @@ -8,27 +8,16 @@ Here we create some useful definitions and some example metadata. The context fields which could be added to CIP-108 compliant jsonld files. See [cip-0108.common.jsonld](./cip-0108.common.jsonld). -```json - -``` - ### Common Fields Schema A json schema for the common context fields. See [cip-0108.common.schema.json](./cip-0108.common.schema.json). -```json - -``` - ## Examples ### Treasury Withdrawal -Hash: `` +Hash (to go onchain): `` See [example-treasury-withdrawal.jsonld](./example-treasury-withdrawal.jsonld). -```json - -``` ### Motion of No-Confidence Hash: `` From 653f9eacc50298411fe3ac09f2b106f2dc247fb3 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 2 Feb 2024 22:56:07 +0000 Subject: [PATCH 11/19] add CIP-05 message signing --- CIP-0108/README.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index 82736e39b..92b380d70 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -7,13 +7,15 @@ Authors: - Ryan Williams Implementors: [ ] Discussions: - - https://github.com/cardano-foundation/cips/pulls/632 + - https://github.com/cardano-foundation/CIPs/pull/632 + - https://github.com/cardano-foundation/CIPs/pull/748 + - https://github.com/cardano-foundation/CIPs/issues/757 Created: 2023-11-23 License: CC-BY-4.0 --- ## Abstract -The conway ledger era ushers in on-chain governance for Cardano via [CIP-1694 | A First Step Towards On-Chain Decentralized Governance](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md), with the addition of many new on-chain governance artifacts. +The Conway ledger era ushers in on-chain governance for Cardano via [CIP-1694 | A First Step Towards On-Chain Decentralized Governance](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md), with the addition of many new on-chain governance artifacts. Some of these artifacts support the linking off-chain metadata, as a way to provide context. The [CIP-100 | Governance Metadata](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100) standard provides a base framework for how all off-chain governance metadata should be formed and handled. @@ -85,6 +87,16 @@ This is good for all governance participants. Although there are seven types of governance action defined via CIP-1694, we focus this proposal on defining core properties which must be attached to all types. We leave room for future standards to refine and specialize further to cater more specific for each type of governance action. +## New `witness` Type +Here we extend the potential witnesses, with a `witnessAlgorithm` that can be set to include support for [CIP-08 | Message Signing](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0008) standard, indicated by `CIP-0008`. +When `CIP-0008` algorithm is chosen a `publicKey` (set to a base-16 encoded ed25519 public key) property must be present along with a `cip8SignedMessage` property. +Where the `cip8SignedMessage` is produced by (blake2b-256) hash digest of the canonicalized of the `body` inside of a COSE envelope. +Where the key will be used to sign the `COSE_Sign1`'s `Sig_structure` with the following headers set: +* `alg` (1) - must be set to `EdDSA` (-8) + + +from [CIP-30](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0030/README.md#apisigndataaddr-address-payload-bytes-promisedatasignature). + ### Markdown Text Styling This standard introduces the possibility of using [Github markdown text styling](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#styling-text) within fields. @@ -153,6 +165,15 @@ We did this for two reasons; familiarity and competency. Those who are involved in Cardano are familiar with the CIP format, meaning they will be intuitively understand these fields being reused here. These fields in combination have also been fairly battle tested via the CIPs process and thus act as a good standard to describe problems and their solutions. +### New `witness` type +We introduce a new witness type to be able to reuse existing dApp-Wallet infrastructure. +The type as described allows for reuse of the CIP-30 signData standard, which means that governance dApps are able to implement this without needing any alterations to existing wallets. + +### Markdown Text Styling +We choose to introduce rich text standard here because we see significant value in supporting it. +Rich text styling improves the ability for the author to express themselves. +Furthermore, most potential voters are use to such standards when reviewing metadata. + ### Character Limits With this design, we wanted to allow for quick and easy differentiation between governance actions. We achieve this by facilitating users "layers of investigation", where some fields are limited in size. From 01ed8100cb865585e168499873a1389007832a23 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Sun, 4 Feb 2024 17:05:46 +0000 Subject: [PATCH 12/19] add note --- CIP-0108/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index 92b380d70..4ea64d41b 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -97,6 +97,8 @@ Where the key will be used to sign the `COSE_Sign1`'s `Sig_structure` with the f from [CIP-30](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0030/README.md#apisigndataaddr-address-payload-bytes-promisedatasignature). +//todo: clean up + ### Markdown Text Styling This standard introduces the possibility of using [Github markdown text styling](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#styling-text) within fields. From eccc0ef4afbdb18d482caf457a6f95148b8da852 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Sun, 4 Feb 2024 23:21:02 +0000 Subject: [PATCH 13/19] add examples --- .../examples/no-confidence.body.canonical | 12 +++ CIP-0108/examples/no-confidence.canonical | 18 +++++ .../no-confidence.jsonld} | 19 +++-- .../treasury-withdrawal.body.canonical | 9 +++ .../examples/treasury-withdrawal.canonical | 16 ++++ CIP-0108/examples/treasury-withdrawal.jsonld | 73 +++++++++++++++++++ CIP-0108/test-vector.md | 25 +++---- 7 files changed, 150 insertions(+), 22 deletions(-) create mode 100644 CIP-0108/examples/no-confidence.body.canonical create mode 100644 CIP-0108/examples/no-confidence.canonical rename CIP-0108/{example-treasury-withdrawal.jsonld => examples/no-confidence.jsonld} (67%) create mode 100644 CIP-0108/examples/treasury-withdrawal.body.canonical create mode 100644 CIP-0108/examples/treasury-withdrawal.canonical create mode 100644 CIP-0108/examples/treasury-withdrawal.jsonld diff --git a/CIP-0108/examples/no-confidence.body.canonical b/CIP-0108/examples/no-confidence.body.canonical new file mode 100644 index 000000000..7925c6551 --- /dev/null +++ b/CIP-0108/examples/no-confidence.body.canonical @@ -0,0 +1,12 @@ +_:c14n0 "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed."@en-us . +_:c14n0 "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed."@en-us . +_:c14n0 "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee."@en-us . +_:c14n0 _:c14n3 . +_:c14n0 "We must remove the ineffective Constitutional Committee"@en-us . +_:c14n1 "blake2b-256"@en-us . +_:c14n1 "931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5"@en-us . +_:c14n2 _:c14n0 . +_:c14n3 . +_:c14n3 "A governance action that has been unable to pass"@en-us . +_:c14n3 "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld"@en-us . +_:c14n3 _:c14n1 . diff --git a/CIP-0108/examples/no-confidence.canonical b/CIP-0108/examples/no-confidence.canonical new file mode 100644 index 000000000..d69b4559a --- /dev/null +++ b/CIP-0108/examples/no-confidence.canonical @@ -0,0 +1,18 @@ +_:c14n0 "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed."@en-us . +_:c14n0 "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed."@en-us . +_:c14n0 "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee."@en-us . +_:c14n0 _:c14n5 . +_:c14n0 "We must remove the ineffective Constitutional Committee"@en-us . +_:c14n1 _:c14n4 . +_:c14n1 "blake2b-256"@en-us . +_:c14n1 _:c14n0 . +_:c14n2 "blake2b-256"@en-us . +_:c14n2 "931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5"@en-us . +_:c14n3 "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb"@en-us . +_:c14n3 "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408"@en-us . +_:c14n3 "cip-0005"@en-us . +_:c14n4 _:c14n3 . +_:c14n5 . +_:c14n5 "A governance action that has been unable to pass"@en-us . +_:c14n5 "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld"@en-us . +_:c14n5 _:c14n2 . diff --git a/CIP-0108/example-treasury-withdrawal.jsonld b/CIP-0108/examples/no-confidence.jsonld similarity index 67% rename from CIP-0108/example-treasury-withdrawal.jsonld rename to CIP-0108/examples/no-confidence.jsonld index 3a1569c67..2c52c5317 100644 --- a/CIP-0108/example-treasury-withdrawal.jsonld +++ b/CIP-0108/examples/no-confidence.jsonld @@ -48,23 +48,26 @@ }, "hashAlgorithm": "blake2b-256", "body": { - "title": "Buy Ryan a island", - "abstract": "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island.", - "motivation": "The current problem is that Ryan does not have an island, but he would really like an island.", - "rationale": "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references.", + "title": "We must remove the ineffective Constitutional Committee", + "abstract": "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed.", + "motivation": "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed.", + "rationale": "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee.", "references": [ { "@type": "Other", - "label": "A cool island for Ryan", - "uri": "https://www.google.com/maps/place/World's+only+5th+order+recursive+island/@62.6511465,-97.7946829,15.75z/data=!4m14!1m7!3m6!1s0x5216a167810cee39:0x11431abdfe4c7421!2sWorld's+only+5th+order+recursive+island!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n!3m5!1s0x5216a167810cee39:0x11431abdfe4c7421!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n?authuser=0&entry=ttu" + "label": "A governance action that has been unable to pass", + "uri": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld", + "referenceHash": { + "hashDigest": "931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5", + "hashAlgorithm": "blake2b-256" + } } ] }, "authors": [ { - "name": "Ryan Williams", "witness": { - "witnessAlgorithm": "ed25519", + "witnessAlgorithm": "cip-0005", "publicKey": "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb", "signature": "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408" } diff --git a/CIP-0108/examples/treasury-withdrawal.body.canonical b/CIP-0108/examples/treasury-withdrawal.body.canonical new file mode 100644 index 000000000..55f3ec84c --- /dev/null +++ b/CIP-0108/examples/treasury-withdrawal.body.canonical @@ -0,0 +1,9 @@ +_:c14n0 "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island."@en-us . +_:c14n0 "The current problem is that Ryan does not have an island, but he would really like an island."@en-us . +_:c14n0 "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references."@en-us . +_:c14n0 _:c14n2 . +_:c14n0 "Buy Ryan a island"@en-us . +_:c14n1 _:c14n0 . +_:c14n2 . +_:c14n2 "A cool island for Ryan"@en-us . +_:c14n2 "https://www.google.com/maps/place/World's+only+5th+order+recursive+island/@62.6511465,-97.7946829,15.75z/data=!4m14!1m7!3m6!1s0x5216a167810cee39:0x11431abdfe4c7421!2sWorld's+only+5th+order+recursive+island!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n!3m5!1s0x5216a167810cee39:0x11431abdfe4c7421!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n?authuser=0&entry=ttu"@en-us . diff --git a/CIP-0108/examples/treasury-withdrawal.canonical b/CIP-0108/examples/treasury-withdrawal.canonical new file mode 100644 index 000000000..bc679841c --- /dev/null +++ b/CIP-0108/examples/treasury-withdrawal.canonical @@ -0,0 +1,16 @@ +_:c14n0 _:c14n3 . +_:c14n0 "blake2b-256"@en-us . +_:c14n0 _:c14n2 . +_:c14n1 "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb"@en-us . +_:c14n1 "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408"@en-us . +_:c14n1 "ed25519"@en-us . +_:c14n2 "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island."@en-us . +_:c14n2 "The current problem is that Ryan does not have an island, but he would really like an island."@en-us . +_:c14n2 "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references."@en-us . +_:c14n2 _:c14n4 . +_:c14n2 "Buy Ryan a island"@en-us . +_:c14n3 "Ryan Williams"@en-us . +_:c14n3 _:c14n1 . +_:c14n4 . +_:c14n4 "A cool island for Ryan"@en-us . +_:c14n4 "https://www.google.com/maps/place/World's+only+5th+order+recursive+island/@62.6511465,-97.7946829,15.75z/data=!4m14!1m7!3m6!1s0x5216a167810cee39:0x11431abdfe4c7421!2sWorld's+only+5th+order+recursive+island!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n!3m5!1s0x5216a167810cee39:0x11431abdfe4c7421!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n?authuser=0&entry=ttu"@en-us . diff --git a/CIP-0108/examples/treasury-withdrawal.jsonld b/CIP-0108/examples/treasury-withdrawal.jsonld new file mode 100644 index 000000000..9bc8edfe5 --- /dev/null +++ b/CIP-0108/examples/treasury-withdrawal.jsonld @@ -0,0 +1,73 @@ +{ + "@context": { + "@language": "en-us", + "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", + "CIP108": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md#", + "hashAlgorithm": "CIP100:hashAlgorithm", + "body": { + "@id": "CIP108:body", + "@context": { + "references": { + "@id": "CIP108:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri", + "referenceHash": { + "@id": "CIP108:referenceHash", + "@context": { + "hashDigest": "CIP108:hashDigest", + "hashAlgorithm": "CIP100:hashAlgorithm" + } + } + } + }, + "title": "CIP108:title", + "abstract": "CIP108:abstract", + "motivation": "CIP108:motivation", + "rationale": "CIP108:rationale" + } + }, + "authors": { + "@id": "CIP100:authors", + "@container": "@set", + "@context": { + "name": "http://xmlns.com/foaf/0.1/name", + "witness": { + "@id": "CIP100:witness", + "@context": { + "witnessAlgorithm": "CIP100:witnessAlgorithm", + "publicKey": "CIP100:publicKey", + "signature": "CIP100:signature" + } + } + } + } + }, + "hashAlgorithm": "blake2b-256", + "body": { + "title": "Buy Ryan a island", + "abstract": "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island.", + "motivation": "The current problem is that Ryan does not have an island, but he would really like an island.", + "rationale": "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references.", + "references": [ + { + "@type": "Other", + "label": "A cool island for Ryan", + "uri": "https://www.google.com/maps/place/World's+only+5th+order+recursive+island/@62.6511465,-97.7946829,15.75z/data=!4m14!1m7!3m6!1s0x5216a167810cee39:0x11431abdfe4c7421!2sWorld's+only+5th+order+recursive+island!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n!3m5!1s0x5216a167810cee39:0x11431abdfe4c7421!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n?authuser=0&entry=ttu" + } + ] + }, + "authors": [ + { + "name": "Ryan Williams", + "witness": { + "witnessAlgorithm": "ed25519", + "publicKey": "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb", + "signature": "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408" + } + } + ] +} diff --git a/CIP-0108/test-vector.md b/CIP-0108/test-vector.md index 9b6690f5b..6d48d394c 100644 --- a/CIP-0108/test-vector.md +++ b/CIP-0108/test-vector.md @@ -15,22 +15,19 @@ See [cip-0108.common.schema.json](./cip-0108.common.schema.json). ## Examples ### Treasury Withdrawal -Hash (to go onchain): `` -See [example-treasury-withdrawal.jsonld](./example-treasury-withdrawal.jsonld). +Blake2b-256 of the canonicalized document (to go onchain): `931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5` -### Motion of No-Confidence -Hash: `` -See [example-no-confidence.jsonld](./example-no-confidence.jsonld). - -```json +See: +- [treasury-withdrawal.jsonld](./examples/treasury-withdrawal.jsonld). +- [treasury-withdrawal.body.canonical](./examples/treasury-withdrawal.body.canonical). +- [treasury-withdrawal.canonical](./examples/treasury-withdrawal.canonical). -``` - -### Update Protocol Parameters -Hash: `` -See [example-protocol-parameter.jsonld](./example-protocol-parameter.jsonld). +### Motion of No-Confidence -```json +Blake2b-256 of the canonicalized document (to go onchain): `f5da6b55e1b24e657984a99b1155c307b24284472d409ab3ea8871f8ca1d3194` -``` \ No newline at end of file +See: +- [no-confidence.jsonld](./examples/no-confidence.jsonld). +- [no-confidence.body.canonical](./examples/no-confidence.body.canonical). +- [no-confidence.canonical](./examples/no-confidence.canonical). \ No newline at end of file From 1f4c5e2ea74f4d9b22a590cd959a8adc77a194c1 Mon Sep 17 00:00:00 2001 From: Ryan Williams <44342099+Ryun1@users.noreply.github.com> Date: Thu, 7 Mar 2024 15:26:28 +0000 Subject: [PATCH 14/19] Update CIP-0108/README.md --- CIP-0108/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index 4ea64d41b..d5307d9e9 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -137,7 +137,7 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - We extend CIP-100's references field. - This SHOULD NOT support markdown text styling. - To be an OPTIONAL set of objects, using the `@set` property. -- Each object MUST have a `title` field to describe the reference, such as; "blog - Why we must continue to fund Catalyst". +- Each object MUST have a `label` field to describe the reference, such as; "blog - Why we must continue to fund Catalyst". - Each object MUST have a `uri` field. - Each object MAY have a OPTIONAL `referenceHash` object. - Each object MUST have a `hashDigest` field. From 8494ba71a9ddd5bf5b0f7c82f9ff1020138d406c Mon Sep 17 00:00:00 2001 From: Ryan Williams <44342099+Ryun1@users.noreply.github.com> Date: Sun, 10 Mar 2024 22:41:15 +0000 Subject: [PATCH 15/19] Update CIP-0108/README.md --- CIP-0108/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index d5307d9e9..c2621fb77 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -21,7 +21,7 @@ Some of these artifacts support the linking off-chain metadata, as a way to prov The [CIP-100 | Governance Metadata](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100) standard provides a base framework for how all off-chain governance metadata should be formed and handled. But this is intentionally limited in scope, so that it can be expanded upon by more specific subsequent CIPs. -This proposal aims to provide a specification for off-chain metadata vocabulary can be used to give context to governance actions, CIP-100. +This proposal aims to provide a specification for off-chain metadata vocabulary that can be used to give context to governance actions. Without a sufficiently detailed standard for governance actions we introduce the possibility to undermine voters ability to adequately assess governance actions. Furthermore a lack of such standards risks preventing interoperability between tools, to the detriment of user experiences. From e002a87132b7cadd7317894939c64b6bb01ec54c Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Sun, 10 Mar 2024 21:54:11 -0100 Subject: [PATCH 16/19] general tidy throughout --- CIP-0108/README.md | 100 +++++++++++++++++++++------------------------ 1 file changed, 47 insertions(+), 53 deletions(-) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index c2621fb77..dd512d48a 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -25,47 +25,7 @@ This proposal aims to provide a specification for off-chain metadata vocabulary Without a sufficiently detailed standard for governance actions we introduce the possibility to undermine voters ability to adequately assess governance actions. Furthermore a lack of such standards risks preventing interoperability between tools, to the detriment of user experiences. -### Acknowledgments - -
- Governance Metadata Working Group - Workshop #1 2023-12-04 - - I would like to thank those that contributed to the Governance Metadata Working Group Workshop #1 hosted by Ryan Williams ([see presentation slides with notes](https://docs.google.com/presentation/d/18OK3vXexCc8ZXq-dC00RDPPKcy2Zu4DiMo8PeIZ47_4/)). - - Thank you to the co-hosts: - - Adam Dean - - Thomas Upfield - - Thank you to the participants: - - Carlos Lopez de Lara - - Igor Veličković - - Johnny Kelly - - Kenric Nelson - - Kevin Hammond - - Lorenzo Bruno - - Mike Susko - - Rhys Morgan - - Eric Alton - - Samuel Leathers - - Vladimir Kalnitsky - -
- -
- Governance Metadata Working Group - Workshop #2 2023-12-14 - - I would like to thank those that contributed to the Governance Metadata Working Group Workshop #2 hosted by Ryan Williams ([see presentation slides with notes](https://docs.google.com/presentation/d/1tFsyQnONjwyTm7zKrnxxedzWsoonO6-8vXw5vYzB3qs)). - - Thank you to the co-host: - - Adam Dean - - Thank you to the participants: - - Mark Byers - - Nils Codes - - Thank you to the bots that joined also. - -
+For the many contributors to this proposal, see [Acknowledgements](#acknowledgements). ## Motivation: why is this CIP necessary? Blockchains are poor choices to act as content databases. @@ -87,17 +47,9 @@ This is good for all governance participants. Although there are seven types of governance action defined via CIP-1694, we focus this proposal on defining core properties which must be attached to all types. We leave room for future standards to refine and specialize further to cater more specific for each type of governance action. -## New `witness` Type +### New `witness` Type Here we extend the potential witnesses, with a `witnessAlgorithm` that can be set to include support for [CIP-08 | Message Signing](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0008) standard, indicated by `CIP-0008`. -When `CIP-0008` algorithm is chosen a `publicKey` (set to a base-16 encoded ed25519 public key) property must be present along with a `cip8SignedMessage` property. -Where the `cip8SignedMessage` is produced by (blake2b-256) hash digest of the canonicalized of the `body` inside of a COSE envelope. -Where the key will be used to sign the `COSE_Sign1`'s `Sig_structure` with the following headers set: -* `alg` (1) - must be set to `EdDSA` (-8) - - -from [CIP-30](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0030/README.md#apisigndataaddr-address-payload-bytes-promisedatasignature). - -//todo: clean up +Here we mimic the restrictions as imposed over the CIP-30's implementation in [.signData()](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0030#apisigndataaddr-address-payload-bytes-promisedatasignature). ### Markdown Text Styling This standard introduces the possibility of using [Github markdown text styling](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#styling-text) within fields. @@ -229,9 +181,51 @@ The inclusion of a hash allows for the supporting documentation to be cryptograp ### Implementation Plan Solicitation of feedback - [x] Run two online workshops to gather insights from stakeholders. -- [ ] Seek community answers on all [Open Questions](#open-questions). +- [x] Seek community answers on all [Open Questions](#open-questions). Implementation -- [ ] Author to provide example metadata and schema files. +- [x] Author to provide example metadata and schema files. + +## Acknowledgments + +
+ Governance Metadata Working Group - Workshop #1 2023-12-04 + + I would like to thank those that contributed to the Governance Metadata Working Group Workshop #1 hosted by Ryan Williams ([see presentation slides with notes](https://docs.google.com/presentation/d/18OK3vXexCc8ZXq-dC00RDPPKcy2Zu4DiMo8PeIZ47_4/)). + + Thank you to the co-hosts: + - Adam Dean + - Thomas Upfield + + Thank you to the participants: + - Carlos Lopez de Lara + - Igor Veličković + - Johnny Kelly + - Kenric Nelson + - Kevin Hammond + - Lorenzo Bruno + - Mike Susko + - Rhys Morgan + - Eric Alton + - Samuel Leathers + - Vladimir Kalnitsky + +
+ +
+ Governance Metadata Working Group - Workshop #2 2023-12-14 + + I would like to thank those that contributed to the Governance Metadata Working Group Workshop #2 hosted by Ryan Williams ([see presentation slides with notes](https://docs.google.com/presentation/d/1tFsyQnONjwyTm7zKrnxxedzWsoonO6-8vXw5vYzB3qs)). + + Thank you to the co-host: + - Adam Dean + + Thank you to the participants: + - Mark Byers + - Nils Codes + + Thank you to the bots that joined also. + +
## 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 9c8fdcc27bc8a6cd85e7f5193c1e5495a9d2de41 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Tue, 2 Apr 2024 20:51:43 +0100 Subject: [PATCH 17/19] feat: Refactor test vector and examples --- .../examples/no-confidence.body.canonical | 20 +-- CIP-0108/examples/no-confidence.body.jsonld | 67 ++++++++++ CIP-0108/examples/no-confidence.canonical | 30 ++--- CIP-0108/examples/no-confidence.jsonld | 11 +- .../examples/treasury-withdrawal.body.jsonld | 62 +++++++++ .../examples/treasury-withdrawal.canonical | 24 ++-- CIP-0108/examples/treasury-withdrawal.jsonld | 4 +- CIP-0108/test-vector.md | 120 ++++++++++++++++-- 8 files changed, 283 insertions(+), 55 deletions(-) create mode 100644 CIP-0108/examples/no-confidence.body.jsonld create mode 100644 CIP-0108/examples/treasury-withdrawal.body.jsonld diff --git a/CIP-0108/examples/no-confidence.body.canonical b/CIP-0108/examples/no-confidence.body.canonical index 7925c6551..d30d16631 100644 --- a/CIP-0108/examples/no-confidence.body.canonical +++ b/CIP-0108/examples/no-confidence.body.canonical @@ -1,12 +1,12 @@ -_:c14n0 "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed."@en-us . -_:c14n0 "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed."@en-us . -_:c14n0 "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee."@en-us . -_:c14n0 _:c14n3 . -_:c14n0 "We must remove the ineffective Constitutional Committee"@en-us . -_:c14n1 "blake2b-256"@en-us . -_:c14n1 "931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5"@en-us . -_:c14n2 _:c14n0 . +_:c14n0 "blake2b-256"@en-us . +_:c14n0 "70e79c1f12ff3c8c955bc2178a542b5994a21be163dd7655af2c5308d2643323"@en-us . +_:c14n1 "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed."@en-us . +_:c14n1 "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed."@en-us . +_:c14n1 "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee."@en-us . +_:c14n1 _:c14n3 . +_:c14n1 "We must remove the ineffective Constitutional Committee"@en-us . +_:c14n2 _:c14n1 . _:c14n3 . _:c14n3 "A governance action that has been unable to pass"@en-us . -_:c14n3 "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld"@en-us . -_:c14n3 _:c14n1 . +_:c14n3 "https://raw.githubusercontent.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld"@en-us . +_:c14n3 _:c14n0 . diff --git a/CIP-0108/examples/no-confidence.body.jsonld b/CIP-0108/examples/no-confidence.body.jsonld new file mode 100644 index 000000000..755555029 --- /dev/null +++ b/CIP-0108/examples/no-confidence.body.jsonld @@ -0,0 +1,67 @@ +{ + "@context": { + "@language": "en-us", + "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", + "CIP108": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md#", + "hashAlgorithm": "CIP100:hashAlgorithm", + "body": { + "@id": "CIP108:body", + "@context": { + "references": { + "@id": "CIP108:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri", + "referenceHash": { + "@id": "CIP108:referenceHash", + "@context": { + "hashDigest": "CIP108:hashDigest", + "hashAlgorithm": "CIP100:hashAlgorithm" + } + } + } + }, + "title": "CIP108:title", + "abstract": "CIP108:abstract", + "motivation": "CIP108:motivation", + "rationale": "CIP108:rationale" + } + }, + "authors": { + "@id": "CIP100:authors", + "@container": "@set", + "@context": { + "name": "http://xmlns.com/foaf/0.1/name", + "witness": { + "@id": "CIP100:witness", + "@context": { + "witnessAlgorithm": "CIP100:witnessAlgorithm", + "publicKey": "CIP100:publicKey", + "signature": "CIP100:signature" + } + } + } + } + }, + "body": { + "title": "We must remove the ineffective Constitutional Committee", + "abstract": "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed.", + "motivation": "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed.", + "rationale": "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee.", + "references": [ + { + "@type": "Other", + "label": "A governance action that has been unable to pass", + "uri": "https://raw.githubusercontent.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld", + "referenceHash": { + "hashDigest": "70e79c1f12ff3c8c955bc2178a542b5994a21be163dd7655af2c5308d2643323", + "hashAlgorithm": "blake2b-256" + } + } + ] + } +} + \ No newline at end of file diff --git a/CIP-0108/examples/no-confidence.canonical b/CIP-0108/examples/no-confidence.canonical index d69b4559a..cfc8fe202 100644 --- a/CIP-0108/examples/no-confidence.canonical +++ b/CIP-0108/examples/no-confidence.canonical @@ -1,18 +1,18 @@ -_:c14n0 "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed."@en-us . -_:c14n0 "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed."@en-us . -_:c14n0 "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee."@en-us . -_:c14n0 _:c14n5 . -_:c14n0 "We must remove the ineffective Constitutional Committee"@en-us . -_:c14n1 _:c14n4 . -_:c14n1 "blake2b-256"@en-us . -_:c14n1 _:c14n0 . +_:c14n0 "blake2b-256"@en-us . +_:c14n0 "70e79c1f12ff3c8c955bc2178a542b5994a21be163dd7655af2c5308d2643323"@en-us . +_:c14n1 "The current constitutional committee have not voted for the last 100 epochs, causing an inability to pass any proposals. This is a waste of resources and must be removed."@en-us . +_:c14n1 "In order for governance to work an __active__ constitutional committee is required, without them the system grinds to a halt and important governance actions cannot be passed."@en-us . +_:c14n1 "By moving into a state of no confidence, **we** the DReps are able to vote in a new constitutional committee."@en-us . +_:c14n1 _:c14n5 . +_:c14n1 "We must remove the ineffective Constitutional Committee"@en-us . +_:c14n2 _:c14n3 . _:c14n2 "blake2b-256"@en-us . -_:c14n2 "931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5"@en-us . -_:c14n3 "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb"@en-us . -_:c14n3 "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408"@en-us . -_:c14n3 "cip-0005"@en-us . -_:c14n4 _:c14n3 . +_:c14n2 _:c14n1 . +_:c14n3 _:c14n4 . +_:c14n4 "7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a"@en-us . +_:c14n4 "84582aa201276761646472657373581d610fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42a166686173686564f458204a7ecc544559df67ece3f7f90f76c4e3e7e329a274c79a06dcfbf28351db600e5840a5dc881ddabdec69e0e4dabdd43a922ef474f7be1029facdbb9106429e17ec61deda22f2778eda21005127f0c6d10f8a4b0210b8177d03d2ae4618d2423d0807"@en-us . +_:c14n4 "cip-0008"@en-us . _:c14n5 . _:c14n5 "A governance action that has been unable to pass"@en-us . -_:c14n5 "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld"@en-us . -_:c14n5 _:c14n2 . +_:c14n5 "https://raw.githubusercontent.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld"@en-us . +_:c14n5 _:c14n0 . diff --git a/CIP-0108/examples/no-confidence.jsonld b/CIP-0108/examples/no-confidence.jsonld index 2c52c5317..89e18705b 100644 --- a/CIP-0108/examples/no-confidence.jsonld +++ b/CIP-0108/examples/no-confidence.jsonld @@ -56,9 +56,9 @@ { "@type": "Other", "label": "A governance action that has been unable to pass", - "uri": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld", + "uri": "https://raw.githubusercontent.com/cardano-foundation/CIPs/blob/master/CIP-0108/examples/treasury-withdrawal.jsonld", "referenceHash": { - "hashDigest": "931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5", + "hashDigest": "70e79c1f12ff3c8c955bc2178a542b5994a21be163dd7655af2c5308d2643323", "hashAlgorithm": "blake2b-256" } } @@ -67,11 +67,10 @@ "authors": [ { "witness": { - "witnessAlgorithm": "cip-0005", - "publicKey": "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb", - "signature": "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408" + "witnessAlgorithm": "cip-0008", + "publicKey": "7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a", + "signature": "84582aa201276761646472657373581d610fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42a166686173686564f458204a7ecc544559df67ece3f7f90f76c4e3e7e329a274c79a06dcfbf28351db600e5840a5dc881ddabdec69e0e4dabdd43a922ef474f7be1029facdbb9106429e17ec61deda22f2778eda21005127f0c6d10f8a4b0210b8177d03d2ae4618d2423d0807" } } ] } - \ No newline at end of file diff --git a/CIP-0108/examples/treasury-withdrawal.body.jsonld b/CIP-0108/examples/treasury-withdrawal.body.jsonld new file mode 100644 index 000000000..e5b0cda78 --- /dev/null +++ b/CIP-0108/examples/treasury-withdrawal.body.jsonld @@ -0,0 +1,62 @@ +{ + "@context": { + "@language": "en-us", + "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", + "CIP108": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md#", + "hashAlgorithm": "CIP100:hashAlgorithm", + "body": { + "@id": "CIP108:body", + "@context": { + "references": { + "@id": "CIP108:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri", + "referenceHash": { + "@id": "CIP108:referenceHash", + "@context": { + "hashDigest": "CIP108:hashDigest", + "hashAlgorithm": "CIP100:hashAlgorithm" + } + } + } + }, + "title": "CIP108:title", + "abstract": "CIP108:abstract", + "motivation": "CIP108:motivation", + "rationale": "CIP108:rationale" + } + }, + "authors": { + "@id": "CIP100:authors", + "@container": "@set", + "@context": { + "name": "http://xmlns.com/foaf/0.1/name", + "witness": { + "@id": "CIP100:witness", + "@context": { + "witnessAlgorithm": "CIP100:witnessAlgorithm", + "publicKey": "CIP100:publicKey", + "signature": "CIP100:signature" + } + } + } + } + }, + "body": { + "title": "Buy Ryan a island", + "abstract": "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island.", + "motivation": "The current problem is that Ryan does not have an island, but he would really like an island.", + "rationale": "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references.", + "references": [ + { + "@type": "Other", + "label": "A cool island for Ryan", + "uri": "https://www.google.com/maps/place/World's+only+5th+order+recursive+island/@62.6511465,-97.7946829,15.75z/data=!4m14!1m7!3m6!1s0x5216a167810cee39:0x11431abdfe4c7421!2sWorld's+only+5th+order+recursive+island!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n!3m5!1s0x5216a167810cee39:0x11431abdfe4c7421!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n?authuser=0&entry=ttu" + } + ] + } +} diff --git a/CIP-0108/examples/treasury-withdrawal.canonical b/CIP-0108/examples/treasury-withdrawal.canonical index bc679841c..f12c0673e 100644 --- a/CIP-0108/examples/treasury-withdrawal.canonical +++ b/CIP-0108/examples/treasury-withdrawal.canonical @@ -1,16 +1,16 @@ -_:c14n0 _:c14n3 . +_:c14n0 _:c14n2 . _:c14n0 "blake2b-256"@en-us . -_:c14n0 _:c14n2 . -_:c14n1 "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb"@en-us . -_:c14n1 "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408"@en-us . -_:c14n1 "ed25519"@en-us . -_:c14n2 "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island."@en-us . -_:c14n2 "The current problem is that Ryan does not have an island, but he would really like an island."@en-us . -_:c14n2 "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references."@en-us . -_:c14n2 _:c14n4 . -_:c14n2 "Buy Ryan a island"@en-us . -_:c14n3 "Ryan Williams"@en-us . -_:c14n3 _:c14n1 . +_:c14n0 _:c14n1 . +_:c14n1 "Withdraw 200000000000 ADA from the treasury so Ryan can buy an island."@en-us . +_:c14n1 "The current problem is that Ryan does not have an island, but he would really like an island."@en-us . +_:c14n1 "With these funds from the treasury will be sold for **cold hard cash**, this cash can then be used to purchase an island for Ryan. An example of this island is provided in the references."@en-us . +_:c14n1 _:c14n4 . +_:c14n1 "Buy Ryan a island"@en-us . +_:c14n2 "Ryan Williams"@en-us . +_:c14n2 _:c14n3 . +_:c14n3 "7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a"@en-us . +_:c14n3 "a476985b4cc0d457f247797611799a6f6a80fc8cb7ec9dcb5a8223888d0618e30de165f3d869c4a0d9107d8a5b612ad7c5e42441907f5b91796f0d7187d64a01"@en-us . +_:c14n3 "ed25519"@en-us . _:c14n4 . _:c14n4 "A cool island for Ryan"@en-us . _:c14n4 "https://www.google.com/maps/place/World's+only+5th+order+recursive+island/@62.6511465,-97.7946829,15.75z/data=!4m14!1m7!3m6!1s0x5216a167810cee39:0x11431abdfe4c7421!2sWorld's+only+5th+order+recursive+island!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n!3m5!1s0x5216a167810cee39:0x11431abdfe4c7421!8m2!3d62.651114!4d-97.7872244!16s%2Fg%2F11spwk2b6n?authuser=0&entry=ttu"@en-us . diff --git a/CIP-0108/examples/treasury-withdrawal.jsonld b/CIP-0108/examples/treasury-withdrawal.jsonld index 9bc8edfe5..594a48287 100644 --- a/CIP-0108/examples/treasury-withdrawal.jsonld +++ b/CIP-0108/examples/treasury-withdrawal.jsonld @@ -65,8 +65,8 @@ "name": "Ryan Williams", "witness": { "witnessAlgorithm": "ed25519", - "publicKey": "d34f36659e28a8343bd552b898ea77733f4057800d5a1e137453abfa7569caeb", - "signature": "cbb96ba1596fafc18eec84e306feea3067ba1c6ace95b11af820bcbd53837ef32bdcf28176749061e1f2a1300d4df98c80582722786e40cf330072d0b78a7408" + "publicKey": "7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a", + "signature": "a476985b4cc0d457f247797611799a6f6a80fc8cb7ec9dcb5a8223888d0618e30de165f3d869c4a0d9107d8a5b612ad7c5e42441907f5b91796f0d7187d64a01" } } ] diff --git a/CIP-0108/test-vector.md b/CIP-0108/test-vector.md index 6d48d394c..ab1444726 100644 --- a/CIP-0108/test-vector.md +++ b/CIP-0108/test-vector.md @@ -16,18 +16,118 @@ See [cip-0108.common.schema.json](./cip-0108.common.schema.json). ### Treasury Withdrawal -Blake2b-256 of the canonicalized document (to go onchain): `931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5` +Example metadata document file: [treasury-withdrawal.jsonld](./examples/treasury-withdrawal.jsonld). +Blake2b-256 of the canonicalized document (to go onchain): `6685960f5884922e135a951f8acb581ff7202fc111ec405a7e014ae725927aae` -See: -- [treasury-withdrawal.jsonld](./examples/treasury-withdrawal.jsonld). -- [treasury-withdrawal.body.canonical](./examples/treasury-withdrawal.body.canonical). -- [treasury-withdrawal.canonical](./examples/treasury-withdrawal.canonical). +#### Intermediate files + +Body files, used to correctly generate author's witness: +- [treasury-withdrawal.body.jsonld](./examples/treasury-withdrawal.body.jsonld) +- [treasury-withdrawal.body.canonical](./examples/treasury-withdrawal.body.canonical) + +Blake2b-256 hash digest of canonicalized body: `68d6fe27087457acf0164e65414238c43573192c99f30341926d1524924d71ca` + +Whole document canonical representation, used to generate final hash: +- [treasury-withdrawal.canonical](./examples/treasury-withdrawal.canonical) ### Motion of No-Confidence -Blake2b-256 of the canonicalized document (to go onchain): `f5da6b55e1b24e657984a99b1155c307b24284472d409ab3ea8871f8ca1d3194` +Example metadata document file: [no-confidence.jsonld](./examples/no-confidence.jsonld). +Blake2b-256 of the canonicalized document (to go onchain): `c382be96dd98c4bbd6d3afe81f0c8143e70fbb6b8855303e69a6606991a4e909` + +#### Intermediate files + +Body files, used to correctly generate author's witness: +- [no-confidence.body.jsonld](./examples/no-confidence.body.jsonld) +- [no-confidence.body.canonical](./examples/no-confidence.body.canonical) + +Blake2b-256 hash digest of canonicalized body: `4a7ecc544559df67ece3f7f90f76c4e3e7e329a274c79a06dcfbf28351db600e` + +Whole document canonical representation, used to generate final hash: +- [no-confidence.canonical](./examples/no-confidence.canonical) + +## How-to Recreate Examples + +### Author + +Keys used for author property, provided here for convenience. + +Private extended signing key (hex): +``` +105d2ef2192150655a926bca9cccf5e2f6e496efa9580508192e1f4a790e6f53de06529129511d1cacb0664bcf04853fdc0055a47cc6d2c6d205127020760652 +``` + +Public verification key (hex): +``` +7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a +``` + +Public verification key hash (hex): +``` +0fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42 +``` + +Mainnet public enterprize address (hex): +``` +610fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42 +``` + +### 1. Create the example.jsonld's `body` + +Create a `example.body.jsonld` and copy in all content from [cip-0108.common.jsonld](./cip-0108.common.jsonld) then fill in the body property with example data. + +If recreating the [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-withdrawal.body.jsonld](./examples/treasury-withdrawal.body.jsonld). + +### 2. Canonicalize the `body` + +Using a tool which complies with the [RDF Dataset Canonicalization](https://w3c-ccg.github.io/rdf-dataset-canonicalization/spec/), create a canonicalized representation of `example.body.jsonld`. +One such tool is the [JSON-LD Playground](https://json-ld.org/playground/). +Ensure the results ends in a newline. + +This creates `example.body.canonical`. + +For [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-withdrawal.body.canonical](./examples/treasury-withdrawal.body.canonical). + +### 3. Hash the canonicalized `body` + +Using a tool create a Blake2b-256 hash of the canonicalized `example.body.canonical`. +One such tool is the [ToolKit Bay](https://toolkitbay.com/tkb/tool/BLAKE2b_256). + +For [Treasury Withdrawal](#treasury-withdrawal), this will result in: `68d6fe27087457acf0164e65414238c43573192c99f30341926d1524924d71ca`. + +### 4. Authors witness over the hash of canonicalized `body` + +Use the hash produced in [3.](#3-hash-the-canonicalized-body) as the payload for the witnessing. For a `witnessAlgorithm` of `ed25519` refer to [CIP-100 Hashing and Signatures](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#hashing-and-signatures), for `cip-0008` refer to [CIP-108 New Witness Type](./README.md#new-witness-type). + +For [Treasury Withdrawal](#treasury-withdrawal), we use the keys described in [Author](#author) resulting in: `a476985b4cc0d457f247797611799a6f6a80fc8cb7ec9dcb5a8223888d0618e30de165f3d869c4a0d9107d8a5b612ad7c5e42441907f5b91796f0d7187d64a01`. + +### 5. Add other properties to example.jsonld + +We can go back to our `example.body.jsonld` and now add in all missing properties, from outside of `body`. +- Adding the `hashAlgorithm` of `blake2b-256`. +- Adding the `authors` with a single entry, including information of our `witness` goes into the `signature`. + +By adding this information we create our `example.jsonld`. + +For [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-withdrawal.jsonld](./examples/treasury-withdrawal.jsonld). + +### 6. Canonicalize example.jsonld + +To be able to create a final metadata hash which can be attached on-chain we must first canonicalize the `example.jsonld`. +Ensure the results ends in a newline. + +This creates `example.canonical`. + +For [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-withdrawal.canonical](./examples/treasury-withdrawal.canonical). + +### 7. Hash the canonicalized example.jsonld + +We then use the specified `hashAlgorithm` on `example.canonical`. + +For [Treasury Withdrawal](#treasury-withdrawal), this will result in `6685960f5884922e135a951f8acb581ff7202fc111ec405a7e014ae725927aae`. + +### 8. Submit to chain + +We can then host `example.jsonld` somewhere easily accessible following [CIP-100 Best Practices](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#best-practices). -See: -- [no-confidence.jsonld](./examples/no-confidence.jsonld). -- [no-confidence.body.canonical](./examples/no-confidence.body.canonical). -- [no-confidence.canonical](./examples/no-confidence.canonical). \ No newline at end of file +Then at submission time of the governance metadata anchor we can provide the on-chain transaction both the URI to the hosted `example.jsonld` but also the hash generated via [7.](#7-hash-the-canonicalized-examplejsonld). \ No newline at end of file From fc2fe1de6431ce4db341019e14b029151d4be466 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Wed, 3 Apr 2024 10:24:27 +0100 Subject: [PATCH 18/19] improve wording in test vectors --- CIP-0108/test-vector.md | 54 ++++++++++++++++++++--------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/CIP-0108/test-vector.md b/CIP-0108/test-vector.md index ab1444726..c09b608cf 100644 --- a/CIP-0108/test-vector.md +++ b/CIP-0108/test-vector.md @@ -1,14 +1,16 @@ # Test Vector for CIP-0108 -Here we create some useful definitions and some example metadata. +Here we create some useful definitions and some examples. ## Common Context ### Common Fields + The context fields which could be added to CIP-108 compliant jsonld files. See [cip-0108.common.jsonld](./cip-0108.common.jsonld). ### Common Fields Schema + A json schema for the common context fields. See [cip-0108.common.schema.json](./cip-0108.common.schema.json). @@ -21,14 +23,16 @@ Blake2b-256 of the canonicalized document (to go onchain): `6685960f5884922e135a #### Intermediate files +Files produced to articulate process, these are not necessary in implementations. + Body files, used to correctly generate author's witness: - [treasury-withdrawal.body.jsonld](./examples/treasury-withdrawal.body.jsonld) -- [treasury-withdrawal.body.canonical](./examples/treasury-withdrawal.body.canonical) +- [treasury-withdrawal.body.nq](./examples/treasury-withdrawal.body.nq) Blake2b-256 hash digest of canonicalized body: `68d6fe27087457acf0164e65414238c43573192c99f30341926d1524924d71ca` Whole document canonical representation, used to generate final hash: -- [treasury-withdrawal.canonical](./examples/treasury-withdrawal.canonical) +- [treasury-withdrawal.nq](./examples/treasury-withdrawal.nq) ### Motion of No-Confidence @@ -37,46 +41,42 @@ Blake2b-256 of the canonicalized document (to go onchain): `c382be96dd98c4bbd6d3 #### Intermediate files +Files produced to articulate process, these are not necessary in implementations. + Body files, used to correctly generate author's witness: - [no-confidence.body.jsonld](./examples/no-confidence.body.jsonld) -- [no-confidence.body.canonical](./examples/no-confidence.body.canonical) +- [no-confidence.body.nq](./examples/no-confidence.body.nq) Blake2b-256 hash digest of canonicalized body: `4a7ecc544559df67ece3f7f90f76c4e3e7e329a274c79a06dcfbf28351db600e` Whole document canonical representation, used to generate final hash: -- [no-confidence.canonical](./examples/no-confidence.canonical) +- [no-confidence.nq](./examples/no-confidence.nq) ## How-to Recreate Examples +This tutorial creates additional intermediate files, these are not required in implementations but are shown here to articulate the process. + ### Author Keys used for author property, provided here for convenience. -Private extended signing key (hex): -``` -105d2ef2192150655a926bca9cccf5e2f6e496efa9580508192e1f4a790e6f53de06529129511d1cacb0664bcf04853fdc0055a47cc6d2c6d205127020760652 -``` +Private extended signing key (hex): `105d2ef2192150655a926bca9cccf5e2f6e496efa9580508192e1f4a790e6f53de06529129511d1cacb0664bcf04853fdc0055a47cc6d2c6d205127020760652` Public verification key (hex): -``` -7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a -``` +`7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a` + -Public verification key hash (hex): -``` -0fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42 -``` +Public verification key hash (hex): `0fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42` Mainnet public enterprize address (hex): -``` -610fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42 -``` +`610fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42` ### 1. Create the example.jsonld's `body` -Create a `example.body.jsonld` and copy in all content from [cip-0108.common.jsonld](./cip-0108.common.jsonld) then fill in the body property with example data. +Create the `example.jsonld` file adding in all available values. +Then remove from this document any top-level field that is not `@context` or `body`. -If recreating the [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-withdrawal.body.jsonld](./examples/treasury-withdrawal.body.jsonld). +If recreating the [Treasury Withdrawal](#treasury-withdrawal), this will result in the intermediate file of [treasury-withdrawal.body.jsonld](./examples/treasury-withdrawal.body.jsonld). ### 2. Canonicalize the `body` @@ -84,13 +84,13 @@ Using a tool which complies with the [RDF Dataset Canonicalization](https://w3c- One such tool is the [JSON-LD Playground](https://json-ld.org/playground/). Ensure the results ends in a newline. -This creates `example.body.canonical`. +This creates `example.body.nq`. -For [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-withdrawal.body.canonical](./examples/treasury-withdrawal.body.canonical). +For [Treasury Withdrawal](#treasury-withdrawal), this will result in the intermediate file of [treasury-withdrawal.body.nq](./examples/treasury-withdrawal.body.nq). ### 3. Hash the canonicalized `body` -Using a tool create a Blake2b-256 hash of the canonicalized `example.body.canonical`. +Using a tool create a Blake2b-256 hash of the canonicalized `example.body.nq`. One such tool is the [ToolKit Bay](https://toolkitbay.com/tkb/tool/BLAKE2b_256). For [Treasury Withdrawal](#treasury-withdrawal), this will result in: `68d6fe27087457acf0164e65414238c43573192c99f30341926d1524924d71ca`. @@ -116,13 +116,13 @@ For [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-w To be able to create a final metadata hash which can be attached on-chain we must first canonicalize the `example.jsonld`. Ensure the results ends in a newline. -This creates `example.canonical`. +This creates `example.nq`. -For [Treasury Withdrawal](#treasury-withdrawal), this will result in [treasury-withdrawal.canonical](./examples/treasury-withdrawal.canonical). +For [Treasury Withdrawal](#treasury-withdrawal), this will result in the intermediate file of [treasury-withdrawal.nq](./examples/treasury-withdrawal.nq). ### 7. Hash the canonicalized example.jsonld -We then use the specified `hashAlgorithm` on `example.canonical`. +We then use the specified `hashAlgorithm` on `example.nq`. For [Treasury Withdrawal](#treasury-withdrawal), this will result in `6685960f5884922e135a951f8acb581ff7202fc111ec405a7e014ae725927aae`. From 5b8c1678e413ef9b3ef6aa56507daa17f3d3ab7d Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Tue, 16 Apr 2024 17:22:55 +0100 Subject: [PATCH 19/19] Update CIP-0108/README.md --- CIP-0108/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CIP-0108/README.md b/CIP-0108/README.md index dd512d48a..6f09d44f6 100644 --- a/CIP-0108/README.md +++ b/CIP-0108/README.md @@ -177,6 +177,7 @@ The inclusion of a hash allows for the supporting documentation to be cryptograp ### Acceptance Criteria - [ ] This standard is supported by two different tooling providers used to submit governance actions to chain. - [ ] This standard is supported by two different chain indexing tools, used to read and render metadata. + - DB-Sync via [db-sync-sancho-4.1.0](https://github.com/IntersectMBO/cardano-db-sync/releases/tag/sancho-4.1.0) ### Implementation Plan Solicitation of feedback