From ccf875c43acb167c6211679336c2b4fdda339db9 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Tue, 16 Jul 2024 22:23:38 -0600 Subject: [PATCH 01/18] init cc vote rationale metadata cip --- .../README.md | 133 ++++++++++++++++++ .../ryans-island-is-unconstitutional.jsonld | 74 ++++++++++ 2 files changed, 207 insertions(+) create mode 100644 CIP-governance-metadata-cc-rationale/README.md create mode 100644 CIP-governance-metadata-cc-rationale/ryans-island-is-unconstitutional.jsonld diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md new file mode 100644 index 000000000..8ef8e3055 --- /dev/null +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -0,0 +1,133 @@ +--- +CIP: ? +Title: Governance metadata - Constitutional Committee vote rationale +Category: Metadata +Status: Proposed +Authors: + - Ryan Williams + - Eysteinh +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/CIPs/pull/? +Created: 2024-07-17 +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/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 that can be used to give context to Constitutional Committee votes. + +## Motivation: why is this CIP necessary? + +### For GA submitters +- Provide clarity to submitters - why their proposal is unconstitutional? + +### For voters +- Provide clarity to DReps/ada holders/SPOs + - to show that the CC is fair and reasonable + - so the CC don't get voted out OR "no confidenced" - this instability would risk the perceived legitimacy of the system + +## Specification + +We define an initial specification for fields which SHOULD be added to constitutional committee votes. + +### 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. + +#### `summary` + +- A short text field. Limited to `200` characters. +- Authors SHOULD use this field to clearly state their stance on the issue. +- Authors SHOULD use this field to succinctly describe their rationale. +- Authors SHOULD give a brief overview of the main arguments will support your position. +- This SHOULD NOT support markdown text styling. +- Compulsory + +#### `rationale-statement` + +- A long text field. +- Authors SHOULD use this field to fully describe their rationale. +- Authors SHOULD discuss their the arguments in full detail. +- This SHOULD support markdown text styling. +- Compulsory + +#### `precedent-discussion` + +- A long text field. +- The author SHOULD use this field to discuss what they feel is relevant precedent. +- directly passed similar proposals (history of proposals) +- (consider precedents can discarded when constitutions change?) +- This SHOULD support markdown text styling. +- Optional + +#### `counterarguments-discussion` + +- A long text field. +- The author SHOULD use this field to discuss significant counter arguments to the position taken. +- This SHOULD support markdown text styling. +- Optional + +#### `references` + +- We extend CIP-100's references field. +- We add to CIP-100's `@type`s, with a type of `relevant-articles`. +- Authors SHOULD use this field to list the relevant constitution articles to their argument. +- Optional + +### Application + +Constitutional committee must include all compulsory fields to be considered CIP-XXX compliant. +As this is an extension to CIP-100, all CIP-100 fields can be included within CIP-XXX compliant metadata. + +### Test Vector + +// todo + +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? + +// todo - fill in details + +### `summary` + +- useful for users to quickly see a preview of the whole rationale +- gives tooling the option to show a high level intro + +#### No `conclusion` + +- probably not needed + +## 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 two online workshops to gather insights from stakeholders. +- [ ] Seek community answers on all [Open Questions](#open-questions). + +#### Implementation + +- [ ] 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). diff --git a/CIP-governance-metadata-cc-rationale/ryans-island-is-unconstitutional.jsonld b/CIP-governance-metadata-cc-rationale/ryans-island-is-unconstitutional.jsonld new file mode 100644 index 000000000..9d9dc2aac --- /dev/null +++ b/CIP-governance-metadata-cc-rationale/ryans-island-is-unconstitutional.jsonld @@ -0,0 +1,74 @@ +{ + "@context": { + "@language": "en-us", + "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", + "CIPXXX": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md#", + "hashAlgorithm": "CIP100:hashAlgorithm", + "body": { + "@id": "CIPXXX:body", + "@context": { + "references": { + "@id": "CIPXXX:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri" + } + }, + "summary": "CIPXXX:summary", + "rationale-statement": "CIPXXX:rationale-statement", + "relevant-articles": "CIPXXX:relevant-articles", + "precedents": "CIPXXX:precedents", + "counterarguments": "CIPXXX:counterarguments", + "conclusion": "CIPXXX:conclusion" + } + }, + "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": { + "summary": "Ryan using treasury funds to buy an island is unconstitutional.", + "rationale-statement": "The Cardano treasury is not meant to be used for personal gain, it should be for the benefit of the community.", + "precedents": "No precedent", + "counterarguments": "It would be pretty cool.", + "conclusion": "In conclusion spending the treasury to benefit a single dude, bad.", + "references": [ + { + "@type": "Relevant Articles", + "label": "Article III section 8.", + "uri": "https://github.com/IntersectMBO/interim-constitution/blob/main/cardano-constitution-0.txt#L231" + }, + { + "@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": "7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a", + "signature": "a476985b4cc0d457f247797611799a6f6a80fc8cb7ec9dcb5a8223888d0618e30de165f3d869c4a0d9107d8a5b612ad7c5e42441907f5b91796f0d7187d64a01" + } + } + ] +} From 180c864ac4f807c0636f8739ca4f05889567b59b Mon Sep 17 00:00:00 2001 From: adanorthpool Date: Wed, 7 Aug 2024 14:10:34 +0200 Subject: [PATCH 02/18] Update CIP-governance-metadata-cc-rationale/README.md --- CIP-governance-metadata-cc-rationale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 8ef8e3055..dc9230bee 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -5,7 +5,7 @@ Category: Metadata Status: Proposed Authors: - Ryan Williams - - Eysteinh + - Eystein Magnus Hansen Implementors: [] Discussions: - https://github.com/cardano-foundation/CIPs/pull/? From 6150fb9d5cf6f803659ccfd5136822fecb6b036e Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Thu, 8 Aug 2024 09:54:05 +0100 Subject: [PATCH 03/18] Update CIP-governance-metadata-cc-rationale/README.md --- CIP-governance-metadata-cc-rationale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index dc9230bee..cabc39c23 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -25,7 +25,7 @@ This proposal aims to provide a specification for off-chain metadata vocabulary ## Motivation: why is this CIP necessary? -### For GA submitters +### For governance action authors - Provide clarity to submitters - why their proposal is unconstitutional? ### For voters From 85b202314be0d5aa374bb748ef0361940c9b73f2 Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Thu, 8 Aug 2024 12:58:12 +0100 Subject: [PATCH 04/18] update discussions link to PR --- CIP-governance-metadata-cc-rationale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index cabc39c23..c3d32ee90 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -8,7 +8,7 @@ Authors: - Eystein Magnus Hansen Implementors: [] Discussions: - - https://github.com/cardano-foundation/CIPs/pull/? + - https://github.com/cardano-foundation/CIPs/pull/878 Created: 2024-07-17 License: CC-BY-4.0 --- From 030e302aaaaa04e10260fdf104d97a0411fe6412 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Sun, 18 Aug 2024 21:49:25 -0700 Subject: [PATCH 05/18] flesh out notes in motivation --- .../README.md | 25 +++++++++++++------ .../ryans-island-is-unconstitutional.jsonld | 0 .../test-vector.md | 3 +++ 3 files changed, 21 insertions(+), 7 deletions(-) rename CIP-governance-metadata-cc-rationale/{ => examples}/ryans-island-is-unconstitutional.jsonld (100%) create mode 100644 CIP-governance-metadata-cc-rationale/test-vector.md diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index c3d32ee90..67edd81b9 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -16,23 +16,34 @@ 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. +Some of these artifacts support the linking of off-chain metadata, as a way to provide context to on-chain actions. -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. +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 can be formed and handled. +But this standard was 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 that can be used to give context to Constitutional Committee votes. +This proposal aims to provide a specification for the off-chain metadata vocabulary that can be used to give context to Constitutional Committee votes. ## Motivation: why is this CIP necessary? -### For governance action authors -- Provide clarity to submitters - why their proposal is unconstitutional? +The high-level motivation for this proposal is to provide a standard which improves legitimacy of Cardano's governance system. + +### Clarity for governance action authors + +Governance action authors are likely to have dedicated a significant amount of time to making their action meaningful and effective (as well as a significant deposit). +If this action is not able to be ratified by the Constitution Committee, it is fair for the author to expect a reasonable explanation from the committee. + +Without reasonable context being provided by the constitutional committee votes, authors may struggle to iterate upon their actions, until they are deemed constitutional. + +### Context for other voting bodies -### For voters - Provide clarity to DReps/ada holders/SPOs - to show that the CC is fair and reasonable - so the CC don't get voted out OR "no confidenced" - this instability would risk the perceived legitimacy of the system +### CC Votes are different to other types of vote +- little overlap between this and other types of vote, so we cant reuse standards as easily +- CIP100 comment field is fine, but not up to the requirements + ## Specification We define an initial specification for fields which SHOULD be added to constitutional committee votes. diff --git a/CIP-governance-metadata-cc-rationale/ryans-island-is-unconstitutional.jsonld b/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld similarity index 100% rename from CIP-governance-metadata-cc-rationale/ryans-island-is-unconstitutional.jsonld rename to CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld diff --git a/CIP-governance-metadata-cc-rationale/test-vector.md b/CIP-governance-metadata-cc-rationale/test-vector.md new file mode 100644 index 000000000..9c66e4fd2 --- /dev/null +++ b/CIP-governance-metadata-cc-rationale/test-vector.md @@ -0,0 +1,3 @@ + + +// todo \ No newline at end of file From ed09d0f40d69343a098a85b5c395819786b15310 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Tue, 20 Aug 2024 19:41:08 +0100 Subject: [PATCH 06/18] flesh out --- .../README.md | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 67edd81b9..b333fc57c 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -1,6 +1,6 @@ --- CIP: ? -Title: Governance metadata - Constitutional Committee vote rationale +Title: Governance metadata - Constitutional Committee votes Category: Metadata Status: Proposed Authors: @@ -21,7 +21,7 @@ Some of these artifacts support the linking of off-chain metadata, as a way to p 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 can be formed and handled. But this standard was intentionally limited in scope, so that it can be expanded upon by more specific subsequent CIPs. -This proposal aims to provide a specification for the off-chain metadata vocabulary that can be used to give context to Constitutional Committee votes. +This proposal aims to provide a specification for the off-chain metadata vocabulary that can be used to give context to Constitutional Committee (CC) votes. ## Motivation: why is this CIP necessary? @@ -29,16 +29,19 @@ The high-level motivation for this proposal is to provide a standard which impro ### Clarity for governance action authors -Governance action authors are likely to have dedicated a significant amount of time to making their action meaningful and effective (as well as a significant deposit). -If this action is not able to be ratified by the Constitution Committee, it is fair for the author to expect a reasonable explanation from the committee. +Governance action authors are likely to have dedicated a significant amount of time to making their action meaningful and effective (as well as locking a significant deposit). +If this action is not able to be ratified by the CC, it is fair for the author to expect a reasonable explanation from the CC. -Without reasonable context being provided by the constitutional committee votes, authors may struggle to iterate upon their actions, until they are deemed constitutional. +Without reasonable context being provided by the CC votes, authors may struggle to iterate upon their actions, until they are deemed constitutional. +This situation would could decrease perceived legitimacy in Cardano's governance. ### Context for other voting bodies -- Provide clarity to DReps/ada holders/SPOs - - to show that the CC is fair and reasonable - - so the CC don't get voted out OR "no confidenced" - this instability would risk the perceived legitimacy of the system +By producing a standard we hope to encourage all CC members to attach rich contextual metadata to their votes. +This context should show CC member's decision making is fair and reasonable. + +This context allows the other voting bodies to adequately check the power of the CC. +The on-chain technical checks of power for the ### CC Votes are different to other types of vote - little overlap between this and other types of vote, so we cant reuse standards as easily @@ -46,7 +49,7 @@ Without reasonable context being provided by the constitutional committee votes, ## Specification -We define an initial specification for fields which SHOULD be added to constitutional committee votes. +We define an initial specification for fields which SHOULD be added to CC votes. ### Extended Vocabulary @@ -94,7 +97,7 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi ### Application -Constitutional committee must include all compulsory fields to be considered CIP-XXX compliant. +CC must include all compulsory fields to be considered CIP-XXX compliant. As this is an extension to CIP-100, all CIP-100 fields can be included within CIP-XXX compliant metadata. ### Test Vector From bd4cd531d8020ffd676adbe1053e2e97ab65a781 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Tue, 20 Aug 2024 19:47:12 +0100 Subject: [PATCH 07/18] add notes from review --- CIP-governance-metadata-cc-rationale/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index b333fc57c..835d28089 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -47,6 +47,16 @@ The on-chain technical checks of power for the - little overlap between this and other types of vote, so we cant reuse standards as easily - CIP100 comment field is fine, but not up to the requirements +### Inclusion in interim constitution + +- Article VI Section 4 of the Interim Constitution + +### Tooling + +- Allows rationales to be machine-readable (e.g. AI training) +- Allows rationale sections to be queryable +- Provides a structured breakdown so it is easier to maintain contexts when translating rationales + ## Specification We define an initial specification for fields which SHOULD be added to CC votes. From e302f3897baef89cbe8448c11bcef2e83c18c3f4 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 13 Sep 2024 23:19:24 +0100 Subject: [PATCH 08/18] enhance and fix --- .../README.md | 25 ++++++++++----- .../ryans-island-is-unconstitutional.jsonld | 31 ++++++++++++++----- 2 files changed, 41 insertions(+), 15 deletions(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 835d28089..2492ed2a7 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -74,7 +74,7 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - This SHOULD NOT support markdown text styling. - Compulsory -#### `rationale-statement` +#### `rationaleStatement` - A long text field. - Authors SHOULD use this field to fully describe their rationale. @@ -82,7 +82,7 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - This SHOULD support markdown text styling. - Compulsory -#### `precedent-discussion` +#### `precedentDiscussion` - A long text field. - The author SHOULD use this field to discuss what they feel is relevant precedent. @@ -91,13 +91,28 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - This SHOULD support markdown text styling. - Optional -#### `counterarguments-discussion` +#### `counterargumentDiscussion` - A long text field. - The author SHOULD use this field to discuss significant counter arguments to the position taken. - This SHOULD support markdown text styling. - Optional +#### `conclusion` + +- A long text field. +- Optional + +#### `internalVote` +``` + "internalVote": { + "constitutional": 0, + "unconstitutional": 0, + "abstain": 0, + "didNotVote": 0 + } +`` + #### `references` - We extend CIP-100's references field. @@ -130,10 +145,6 @@ Although through the JSON-LD mechanism further CIPs can add to the common govern - useful for users to quickly see a preview of the whole rationale - gives tooling the option to show a high level intro -#### No `conclusion` - -- probably not needed - ## Path to Active ### Acceptance Criteria diff --git a/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld b/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld index 9d9dc2aac..5a1e2bd19 100644 --- a/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld +++ b/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld @@ -18,11 +18,20 @@ } }, "summary": "CIPXXX:summary", - "rationale-statement": "CIPXXX:rationale-statement", - "relevant-articles": "CIPXXX:relevant-articles", - "precedents": "CIPXXX:precedents", - "counterarguments": "CIPXXX:counterarguments", - "conclusion": "CIPXXX:conclusion" + "rationaleStatement": "CIPXXX:rationale-statement", + "precedentDiscussion": "CIPXXX:precedentDiscussion", + "counterargumentDiscussion": "CIPXXX:counterarguments", + "conclusion": "CIPXXX:conclusion", + "internalVote": { + "@id": "CIPXXX:internalVote", + "@context": { + "constitutional": "CIPXXX:constitutional", + "unconstitutional": "CIPXXX:unconstitutional", + "abstain": "CIPXXX:abstain", + "didNotVote": "CIPXXX:didNotVote" + } + } + } }, "authors": { @@ -44,10 +53,16 @@ "hashAlgorithm": "blake2b-256", "body": { "summary": "Ryan using treasury funds to buy an island is unconstitutional.", - "rationale-statement": "The Cardano treasury is not meant to be used for personal gain, it should be for the benefit of the community.", - "precedents": "No precedent", - "counterarguments": "It would be pretty cool.", + "rationaleStatement": "The Cardano treasury is not meant to be used for personal gain, it should be for the benefit of the community.", + "precedentDiscussion": "No precedent", + "counterargumentDiscussion": "It would be pretty cool.", "conclusion": "In conclusion spending the treasury to benefit a single dude, bad.", + "internalVote": { + "constitutional": 1, + "unconstitutional": 0, + "abstain": 0, + "didNotVote": 0 + }, "references": [ { "@type": "Relevant Articles", From 73e137a44cbb9d8e4d7e2e56b24ab17e81b62f9e Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 13 Sep 2024 23:22:53 +0100 Subject: [PATCH 09/18] fix formatting --- CIP-governance-metadata-cc-rationale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 2492ed2a7..380790467 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -111,7 +111,7 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi "abstain": 0, "didNotVote": 0 } -`` +``` #### `references` From 57483743e1dd731475e6e8e7e94c234a9b3d00f9 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 13 Sep 2024 23:49:53 +0100 Subject: [PATCH 10/18] fix relevantArticles --- CIP-governance-metadata-cc-rationale/README.md | 2 +- .../examples/ryans-island-is-unconstitutional.jsonld | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 380790467..9ac7e6576 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -116,7 +116,7 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi #### `references` - We extend CIP-100's references field. -- We add to CIP-100's `@type`s, with a type of `relevant-articles`. +- We add to CIP-100's `@type`s, with a type of `relevantArticles`. - Authors SHOULD use this field to list the relevant constitution articles to their argument. - Optional diff --git a/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld b/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld index 5a1e2bd19..3ef6df253 100644 --- a/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld +++ b/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld @@ -65,7 +65,7 @@ }, "references": [ { - "@type": "Relevant Articles", + "@type": "relevant-articles", "label": "Article III section 8.", "uri": "https://github.com/IntersectMBO/interim-constitution/blob/main/cardano-constitution-0.txt#L231" }, From 466baa7617963da811d997e0630e70b6fa8d6a18 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 13 Sep 2024 23:50:28 +0100 Subject: [PATCH 11/18] actually fix relevantArticles --- .../examples/ryans-island-is-unconstitutional.jsonld | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld b/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld index 3ef6df253..8f2c1f748 100644 --- a/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld +++ b/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld @@ -65,7 +65,7 @@ }, "references": [ { - "@type": "relevant-articles", + "@type": "relevantArticles", "label": "Article III section 8.", "uri": "https://github.com/IntersectMBO/interim-constitution/blob/main/cardano-constitution-0.txt#L231" }, From 2cd4d81f60223270cbf62f830d374e5ce79cf554 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Mon, 16 Sep 2024 14:09:57 +0100 Subject: [PATCH 12/18] flesh out and tidy --- .../README.md | 112 ++++++++++++------ 1 file changed, 77 insertions(+), 35 deletions(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 9ac7e6576..a8ab159bb 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -19,7 +19,7 @@ The Conway ledger era ushers in on-chain governance for Cardano via [CIP-1694 | Some of these artifacts support the linking of off-chain metadata, as a way to provide context to on-chain actions. 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 can be formed and handled. -But this standard was intentionally limited in scope, so that it can be expanded upon by more specific subsequent CIPs. +This standard was intentionally limited in scope, so that it can be expanded upon by more specific subsequent CIPs. This proposal aims to provide a specification for the off-chain metadata vocabulary that can be used to give context to Constitutional Committee (CC) votes. @@ -33,7 +33,7 @@ Governance action authors are likely to have dedicated a significant amount of t If this action is not able to be ratified by the CC, it is fair for the author to expect a reasonable explanation from the CC. Without reasonable context being provided by the CC votes, authors may struggle to iterate upon their actions, until they are deemed constitutional. -This situation would could decrease perceived legitimacy in Cardano's governance. +This situation could decrease perceived legitimacy in Cardano's governance. ### Context for other voting bodies @@ -41,27 +41,38 @@ By producing a standard we hope to encourage all CC members to attach rich conte This context should show CC member's decision making is fair and reasonable. This context allows the other voting bodies to adequately check the power of the CC. -The on-chain technical checks of power for the -### CC Votes are different to other types of vote -- little overlap between this and other types of vote, so we cant reuse standards as easily -- CIP100 comment field is fine, but not up to the requirements +### CC votes are different to other types of vote -### Inclusion in interim constitution +The CC and their votes are fundamentally very different from the other voting bodies. +This makes reusing standards from these voting bodies problematic. -- Article VI Section 4 of the Interim Constitution +### Inclusion within interim constitution + +Cardano's [Interim Constitution Article VI Section 4](https://github.com/IntersectMBO/interim-constitution/blob/75155526ce850118898bd5eacf460f5d68ceb083/cardano-constitution-0.txt#L330) states: + +```txt +Constitutional Committee processes shall be transparent. +The Constitutional Committee shall publish each decision. +When voting no on a proposal, the Committee shall set forth the basis +for its decision with reference to specific Articles of this Constitution +that are in conflict with a given proposal. +``` + +This mandates that the CC must provide rationale for at least `no` votes. +Specifying a structure and common vocabulary for this improves the efforts to be transparent. ### Tooling -- Allows rationales to be machine-readable (e.g. AI training) -- Allows rationale sections to be queryable -- Provides a structured breakdown so it is easier to maintain contexts when translating rationales +By creating and implementing these metadata standards we facilitate the creation of tooling that can read and write this data. +Such tooling greatly expands the reach and effectiveness of rationales as it allows for rich user interfaces to be created. +i.e. translation tools, rationale comparison tools, ## Specification -We define an initial specification for fields which SHOULD be added to CC votes. +We define a specification for fields which can be added to CC votes. -### Extended Vocabulary +### Extended Body Vocabulary The following properties extend the potential vocabulary of [CIP-100](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100)'s `body` property. @@ -72,53 +83,72 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - Authors SHOULD use this field to succinctly describe their rationale. - Authors SHOULD give a brief overview of the main arguments will support your position. - This SHOULD NOT support markdown text styling. -- Compulsory +- Compulsory. #### `rationaleStatement` - A long text field. - Authors SHOULD use this field to fully describe their rationale. -- Authors SHOULD discuss their the arguments in full detail. -- This SHOULD support markdown text styling. -- Compulsory +- Authors SHOULD discuss their arguments in full detail. +- This field SHOULD support markdown text styling. +- Compulsory. #### `precedentDiscussion` - A long text field. - The author SHOULD use this field to discuss what they feel is relevant precedent. -- directly passed similar proposals (history of proposals) -- (consider precedents can discarded when constitutions change?) -- This SHOULD support markdown text styling. -- Optional +- This field SHOULD support markdown text styling. +- Optional. #### `counterargumentDiscussion` - A long text field. - The author SHOULD use this field to discuss significant counter arguments to the position taken. -- This SHOULD support markdown text styling. -- Optional +- This field SHOULD support markdown text styling. +- Optional. #### `conclusion` - A long text field. -- Optional +- The author SHOULD use this field to conclude their rationale. +- This SHOULD NOT support markdown text styling. +- Optional. #### `internalVote` -``` - "internalVote": { - "constitutional": 0, - "unconstitutional": 0, - "abstain": 0, - "didNotVote": 0 - } -``` -#### `references` +- A custom object field. +- This field SHOULD be used to reflect any internal voting decisions within CC member. +- This field SHOULD be used by members who are constructed from organizations or consortiums. +- Optional. + +##### `constitutional` + +- A positive integer. +- The author SHOULD use this field to represent a number of internal votes for the constitutionality of the action. + +##### `unconstitutional` + +- A positive integer. +- The author SHOULD use this field to represent a number of internal votes against the constitutionality of the action. + +##### `abstain` + +- A positive integer. +- The author SHOULD use this field to represent a number of internal abstain votes for the action. + +##### `didNotVot` + +- A positive integer. +- The author SHOULD use this field to represent a number of unused internal votes. + +### Extended `references` Vocabulary + +Here we extend CIP-100's `references` field. + +#### `relevantArticles` -- We extend CIP-100's references field. - We add to CIP-100's `@type`s, with a type of `relevantArticles`. - Authors SHOULD use this field to list the relevant constitution articles to their argument. -- Optional ### Application @@ -145,6 +175,18 @@ Although through the JSON-LD mechanism further CIPs can add to the common govern - useful for users to quickly see a preview of the whole rationale - gives tooling the option to show a high level intro +### `rationaleStatement` + +### `precedentDiscussion` + +### `counterargumentDiscussion` + +### `conclusion` + +### `internalVote` + +### `relevantArticles` + ## Path to Active ### Acceptance Criteria From f752e9e5f5583e34a831e7f4cd5aab19788be6c5 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Tue, 17 Sep 2024 15:05:15 +0100 Subject: [PATCH 13/18] add supporting schema files --- .../README.md | 6 +- .../cip-xxxx.common.jsonld | 53 +++++++ .../cip-xxxx.common.schema.json | 148 ++++++++++++++++++ 3 files changed, 204 insertions(+), 3 deletions(-) create mode 100644 CIP-governance-metadata-cc-rationale/cip-xxxx.common.jsonld create mode 100644 CIP-governance-metadata-cc-rationale/cip-xxxx.common.schema.json diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index a8ab159bb..b0307af1e 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -5,7 +5,7 @@ Category: Metadata Status: Proposed Authors: - Ryan Williams - - Eystein Magnus Hansen + - Eysteinh Magnus Hansen Implementors: [] Discussions: - https://github.com/cardano-foundation/CIPs/pull/878 @@ -145,9 +145,9 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi Here we extend CIP-100's `references` field. -#### `relevantArticles` +#### `RelevantArticles` -- We add to CIP-100's `@type`s, with a type of `relevantArticles`. +- We add to CIP-100's `@type`s, with a type of `RelevantArticles`. - Authors SHOULD use this field to list the relevant constitution articles to their argument. ### Application diff --git a/CIP-governance-metadata-cc-rationale/cip-xxxx.common.jsonld b/CIP-governance-metadata-cc-rationale/cip-xxxx.common.jsonld new file mode 100644 index 000000000..d99ccd9a3 --- /dev/null +++ b/CIP-governance-metadata-cc-rationale/cip-xxxx.common.jsonld @@ -0,0 +1,53 @@ +{ + "@context": { + "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", + "CIPXXX": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0XXX/README.md#", + "hashAlgorithm": "CIP100:hashAlgorithm", + "body": { + "@id": "CIPXXX:body", + "@context": { + "references": { + "@id": "CIPXXX:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri", + "RelevantArticles": "CIPXXX:RelevantArticles" + } + }, + "summary": "CIPXXX:summary", + "rationaleStatement": "CIPXXX:rationaleStatement", + "precedentDiscussion": "CIPXXX:precedentDiscussion", + "counterargumentDiscussion": "CIPXXX:counterargumentDiscussion", + "conclusion": "CIPXXX:conclusion", + "internalVote": { + "@id": "CIPXXX:internalVote", + "@context": { + "constitutional": "CIPXXX:constitutional", + "unconstitutional": "CIPXXX:unconstitutional", + "abstain": "CIPXXX:abstain", + "didNotVote": "CIPXXX:didNotVote" + } + } + } + }, + "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-governance-metadata-cc-rationale/cip-xxxx.common.schema.json b/CIP-governance-metadata-cc-rationale/cip-xxxx.common.schema.json new file mode 100644 index 000000000..ab88028ca --- /dev/null +++ b/CIP-governance-metadata-cc-rationale/cip-xxxx.common.schema.json @@ -0,0 +1,148 @@ +{ + "title": "CIP-XXX Common", + "description": "Metadata document for Cardano Constitutional Committee vote rationales, 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" + } + } + }, + "Witness": { + "title": "Witness", + "description": "A witness proving that the author endorses the content of the metadata", + "type": "object", + "properties": { + "witnessAlgorithm": { + "title": "WitnessAlgorithm", + "type": "string", + "enum": [ + "ed25519" + ] + }, + "publicKey": { + "title": "PublicKey", + "type": "string" + }, + "signature": { + "title": "Signature", + "type": "string" + } + } + }, + "body": { + "title": "Body", + "description": "The body of the metadata document that is hashed to produce a signature (CIP-100)", + "type": "object", + "required": ["summary", "rationaleStatement"], + "properties": { + "summary": { + "type": "string", + "title": "Summary", + "description": "" + }, + "rationaleStatement": { + "type": "string", + "title": "Rationale Statement", + "description": "" + }, + "precedentDiscussion": { + "type": "string", + "title": "Precedent Discussion", + "description": "" + }, + "counterargumentDiscussion": { + "type": "string", + "title": "Counterargument Discussion", + "description": "" + }, + "conclusion": { + "type": "string", + "title": "conclusion", + "description": "" + } + } + }, + "reference": { + "title": "Reference", + "description": "A reference to a document", + "type": "object", + "required": ["type", "label", "uri"], + "properties": { + "type": { + "type": "string", + "enum": ["GovernanceMetadata", "Other", "RelevantArticles"], + "title": "Type" + }, + "label": { + "type": "string", + "title": "Label" + }, + "uri": { + "type": "string", + "title": "URI" + } + } + }, + "internalVote": { + "title": "Internal Vote", + "description": "", + "type": "object", + "required": ["constitutional", "unconstitutional", "abstain", "didNotVote"], + "properties": { + "constitutional": { + "type": "integer", + "title": "" + }, + "unconstitutional": { + "type": "integer", + "title": "" + }, + "abstain": { + "type": "integer", + "title": "" + }, + "didNotVote": { + "type": "integer", + "title": "" + } + } + } + } +} \ No newline at end of file From a0fbf9c95313f36ae049d8d3231b4f51338f9ed8 Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Tue, 17 Sep 2024 20:30:00 +0100 Subject: [PATCH 14/18] Update CIP-governance-metadata-cc-rationale/README.md Co-authored-by: Robert Phair --- CIP-governance-metadata-cc-rationale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index b0307af1e..82d8ecdd8 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -1,5 +1,5 @@ --- -CIP: ? +CIP: 136 Title: Governance metadata - Constitutional Committee votes Category: Metadata Status: Proposed From 313aba18299d66178da28053a558f9850af6c44d Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Tue, 17 Sep 2024 20:31:14 +0100 Subject: [PATCH 15/18] Update CIP-governance-metadata-cc-rationale/README.md Co-authored-by: Robert Phair --- CIP-governance-metadata-cc-rationale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 82d8ecdd8..195dd94b4 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -5,7 +5,7 @@ Category: Metadata Status: Proposed Authors: - Ryan Williams - - Eysteinh Magnus Hansen + - Eystein Magnus Hansen Implementors: [] Discussions: - https://github.com/cardano-foundation/CIPs/pull/878 From 4afc50fe25b96012371bc3a428b90153a8340d2b Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Tue, 17 Sep 2024 16:19:26 +0100 Subject: [PATCH 16/18] fix typo --- CIP-governance-metadata-cc-rationale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-governance-metadata-cc-rationale/README.md index 195dd94b4..9f3de4b33 100644 --- a/CIP-governance-metadata-cc-rationale/README.md +++ b/CIP-governance-metadata-cc-rationale/README.md @@ -136,7 +136,7 @@ The following properties extend the potential vocabulary of [CIP-100](https://gi - A positive integer. - The author SHOULD use this field to represent a number of internal abstain votes for the action. -##### `didNotVot` +##### `didNotVote` - A positive integer. - The author SHOULD use this field to represent a number of unused internal votes. From c97a80f1333af5101aaba2048d8353d7d3b109e1 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Wed, 18 Sep 2024 14:01:26 +0100 Subject: [PATCH 17/18] rename directory --- {CIP-governance-metadata-cc-rationale => CIP-0136}/README.md | 0 .../cip-xxxx.common.jsonld | 0 .../cip-xxxx.common.schema.json | 0 .../examples/ryans-island-is-unconstitutional.jsonld | 0 {CIP-governance-metadata-cc-rationale => CIP-0136}/test-vector.md | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename {CIP-governance-metadata-cc-rationale => CIP-0136}/README.md (100%) rename {CIP-governance-metadata-cc-rationale => CIP-0136}/cip-xxxx.common.jsonld (100%) rename {CIP-governance-metadata-cc-rationale => CIP-0136}/cip-xxxx.common.schema.json (100%) rename {CIP-governance-metadata-cc-rationale => CIP-0136}/examples/ryans-island-is-unconstitutional.jsonld (100%) rename {CIP-governance-metadata-cc-rationale => CIP-0136}/test-vector.md (100%) diff --git a/CIP-governance-metadata-cc-rationale/README.md b/CIP-0136/README.md similarity index 100% rename from CIP-governance-metadata-cc-rationale/README.md rename to CIP-0136/README.md diff --git a/CIP-governance-metadata-cc-rationale/cip-xxxx.common.jsonld b/CIP-0136/cip-xxxx.common.jsonld similarity index 100% rename from CIP-governance-metadata-cc-rationale/cip-xxxx.common.jsonld rename to CIP-0136/cip-xxxx.common.jsonld diff --git a/CIP-governance-metadata-cc-rationale/cip-xxxx.common.schema.json b/CIP-0136/cip-xxxx.common.schema.json similarity index 100% rename from CIP-governance-metadata-cc-rationale/cip-xxxx.common.schema.json rename to CIP-0136/cip-xxxx.common.schema.json diff --git a/CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld b/CIP-0136/examples/ryans-island-is-unconstitutional.jsonld similarity index 100% rename from CIP-governance-metadata-cc-rationale/examples/ryans-island-is-unconstitutional.jsonld rename to CIP-0136/examples/ryans-island-is-unconstitutional.jsonld diff --git a/CIP-governance-metadata-cc-rationale/test-vector.md b/CIP-0136/test-vector.md similarity index 100% rename from CIP-governance-metadata-cc-rationale/test-vector.md rename to CIP-0136/test-vector.md From 1369c977de9ed1f9b86680c2dfeddc56e10bb9d0 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Sun, 22 Sep 2024 21:14:07 +0100 Subject: [PATCH 18/18] init proper test vectors --- ...xx.common.jsonld => cip-136.common.jsonld} | 29 +++---- ...schema.json => cip-136.common.schema.json} | 9 +- ...easury-withdrawal-unconstitutional.jsonld} | 82 ++++++++++--------- CIP-0136/test-vector.md | 49 ++++++++++- 4 files changed, 113 insertions(+), 56 deletions(-) rename CIP-0136/{cip-xxxx.common.jsonld => cip-136.common.jsonld} (61%) rename CIP-0136/{cip-xxxx.common.schema.json => cip-136.common.schema.json} (94%) rename CIP-0136/examples/{ryans-island-is-unconstitutional.jsonld => treasury-withdrawal-unconstitutional.jsonld} (51%) diff --git a/CIP-0136/cip-xxxx.common.jsonld b/CIP-0136/cip-136.common.jsonld similarity index 61% rename from CIP-0136/cip-xxxx.common.jsonld rename to CIP-0136/cip-136.common.jsonld index d99ccd9a3..e3ab95906 100644 --- a/CIP-0136/cip-xxxx.common.jsonld +++ b/CIP-0136/cip-136.common.jsonld @@ -1,34 +1,35 @@ { "@context": { + "@language": "en-us", "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", - "CIPXXX": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0XXX/README.md#", + "CIP136": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0136/README.md#", "hashAlgorithm": "CIP100:hashAlgorithm", "body": { - "@id": "CIPXXX:body", + "@id": "CIP136:body", "@context": { "references": { - "@id": "CIPXXX:references", + "@id": "CIP100:references", "@container": "@set", "@context": { "GovernanceMetadata": "CIP100:GovernanceMetadataReference", "Other": "CIP100:OtherReference", "label": "CIP100:reference-label", "uri": "CIP100:reference-uri", - "RelevantArticles": "CIPXXX:RelevantArticles" + "RelevantArticles": "CIP136:RelevantArticles" } }, - "summary": "CIPXXX:summary", - "rationaleStatement": "CIPXXX:rationaleStatement", - "precedentDiscussion": "CIPXXX:precedentDiscussion", - "counterargumentDiscussion": "CIPXXX:counterargumentDiscussion", - "conclusion": "CIPXXX:conclusion", + "summary": "CIP136:summary", + "rationaleStatement": "CIP136:rationaleStatement", + "precedentDiscussion": "CIP136:precedentDiscussion", + "counterargumentDiscussion": "CIP136:counterargumentDiscussion", + "conclusion": "CIP136:conclusion", "internalVote": { - "@id": "CIPXXX:internalVote", + "@id": "CIP136:internalVote", "@context": { - "constitutional": "CIPXXX:constitutional", - "unconstitutional": "CIPXXX:unconstitutional", - "abstain": "CIPXXX:abstain", - "didNotVote": "CIPXXX:didNotVote" + "constitutional": "CIP136:constitutional", + "unconstitutional": "CIP136:unconstitutional", + "abstain": "CIP136:abstain", + "didNotVote": "CIP136:didNotVote" } } } diff --git a/CIP-0136/cip-xxxx.common.schema.json b/CIP-0136/cip-136.common.schema.json similarity index 94% rename from CIP-0136/cip-xxxx.common.schema.json rename to CIP-0136/cip-136.common.schema.json index ab88028ca..742bfc7ce 100644 --- a/CIP-0136/cip-xxxx.common.schema.json +++ b/CIP-0136/cip-136.common.schema.json @@ -1,5 +1,5 @@ { - "title": "CIP-XXX Common", + "title": "CIP-136 Common", "description": "Metadata document for Cardano Constitutional Committee vote rationales, extending CIP-100", "type": "object", "required": ["hashAlgorithm", "authors", "body"], @@ -72,6 +72,13 @@ "type": "object", "required": ["summary", "rationaleStatement"], "properties": { + "references": { + "title": "References", + "type": "array", + "items": { + "$ref": "#/definitions/Reference" + } + }, "summary": { "type": "string", "title": "Summary", diff --git a/CIP-0136/examples/ryans-island-is-unconstitutional.jsonld b/CIP-0136/examples/treasury-withdrawal-unconstitutional.jsonld similarity index 51% rename from CIP-0136/examples/ryans-island-is-unconstitutional.jsonld rename to CIP-0136/examples/treasury-withdrawal-unconstitutional.jsonld index 8f2c1f748..41e8aa6e8 100644 --- a/CIP-0136/examples/ryans-island-is-unconstitutional.jsonld +++ b/CIP-0136/examples/treasury-withdrawal-unconstitutional.jsonld @@ -2,52 +2,54 @@ "@context": { "@language": "en-us", "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#", - "CIPXXX": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md#", + "CIP136": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0136/README.md#", "hashAlgorithm": "CIP100:hashAlgorithm", "body": { - "@id": "CIPXXX:body", - "@context": { - "references": { - "@id": "CIPXXX:references", - "@container": "@set", - "@context": { - "GovernanceMetadata": "CIP100:GovernanceMetadataReference", - "Other": "CIP100:OtherReference", - "label": "CIP100:reference-label", - "uri": "CIP100:reference-uri" - } - }, - "summary": "CIPXXX:summary", - "rationaleStatement": "CIPXXX:rationale-statement", - "precedentDiscussion": "CIPXXX:precedentDiscussion", - "counterargumentDiscussion": "CIPXXX:counterarguments", - "conclusion": "CIPXXX:conclusion", - "internalVote": { - "@id": "CIPXXX:internalVote", - "@context": { - "constitutional": "CIPXXX:constitutional", - "unconstitutional": "CIPXXX:unconstitutional", - "abstain": "CIPXXX:abstain", - "didNotVote": "CIPXXX:didNotVote" - } + "@id": "CIP136:body", + "@context": { + "references": { + "@id": "CIP100:references", + "@container": "@set", + "@context": { + "GovernanceMetadata": "CIP100:GovernanceMetadataReference", + "Other": "CIP100:OtherReference", + "label": "CIP100:reference-label", + "uri": "CIP100:reference-uri", + "RelevantArticles": "CIP136:RelevantArticles" + } + }, + "summary": "CIP136:summary", + "rationaleStatement": "CIP136:rationaleStatement", + "precedentDiscussion": "CIP136:precedentDiscussion", + "counterargumentDiscussion": "CIP136:counterargumentDiscussion", + "conclusion": "CIP136:conclusion", + "internalVote": { + "@id": "CIP136:internalVote", + "@container": "@set", + "@context": { + "constitutional": "CIP136:constitutional", + "unconstitutional": "CIP136:unconstitutional", + "abstain": "CIP136:abstain", + "didNotVote": "CIP136:didNotVote" + } + } } - - } }, "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" - } + "@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" + } + } } - } } }, "hashAlgorithm": "blake2b-256", diff --git a/CIP-0136/test-vector.md b/CIP-0136/test-vector.md index 9c66e4fd2..d71054799 100644 --- a/CIP-0136/test-vector.md +++ b/CIP-0136/test-vector.md @@ -1,3 +1,50 @@ +# Test Vector for CIP-136 +Here we create some useful definitions and some examples. + +## Common Context + +### Common Fields + +The context fields which could be added to CIP-136 compliant jsonld files. +See [cip-0136.common.jsonld](./cip-0136.common.jsonld). + +### Common Fields Schema + +A json schema for the common context fields. +See [cip-0136.common.schema.json](./cip-0136.common.schema.json). + +## Examples + +### Treasury Withdrawal is Unconstitutional + +Example metadata document file: [treasury-withdrawal-unconstitutional.jsonld](./examples/treasury-withdrawal-unconstitutional.jsonld). +Blake2b-256 of the file content (to go onchain): `` + +#### Intermediate files + +Files produced to articulate process, these are not necessary in implementations. + +Body files, used to correctly generate author's witness: +- [treasury-withdrawal-unconstitutional.body.jsonld](./examples/treasury-withdrawal-unconstitutional.body.jsonld) +- [treasury-withdrawal-unconstitutional.body.nq](./examples/treasury-withdrawal-unconstitutional.body.nq) + +Blake2b-256 hash digest of canonicalized body: `` + +## 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` + +Public verification key (hex): +`7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a` + +Public verification key hash (hex): `0fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42` + +Mainnet public enterprize address (hex): `610fdc780023d8be7c9ff3a6bdc0d8d3b263bd0cc12448c40948efbf42` -// todo \ No newline at end of file