CIP-0185? | Governance Action Addendums - #1180
Conversation
|
|
||
| ## Motivation | ||
|
|
||
| Under the current CIP-1694 and CIP-0108 frameworks, proposers lack a standardized, on-chain mechanism to provide ongoing context or reactions to a governance action once it is submitted. Consequently, proposers often distribute additional information—such as answers to community questions, rationale refinements, or strategic adjustments—through public or private off-chain channels. |
There was a problem hiding this comment.
CIP-100 does give the externalUpdates field, for this purpose, but I don't think this has ever been used
https://github.com/cardano-foundation/CIPs/tree/master/CIP-0100
There was a problem hiding this comment.
thanks @thenic95 - CIP looks good & marking for Triage at CIP meeting in a week's time (https://hackmd.io/@cip-editors/133). Would be nice to see you there especially for an opportunity for an initial review with @Ryun1 of whether this CIP's goals can be met with existing CIP-0100 semantics as per #1180 (comment).
rphair
added
Category: Metadata
rphair
changed the title
There was a problem hiding this comment.
This proposal was well received and introduced by its author at the CIP meeting today: acknowledged as useful, timely, and with good writing on a sensible specification.
@thenic95 please update the containing directory to CIP-0183CIP-0185 and also the directory portion of your proposal link in the OP. 🎉 I expect some parallel review may happen with a concurrent proposal on a very similar subject (cc @Quantumplation):
... so please @thenic95 could you begin a more demanding review by explaining (in a way that would satisfy those not well-versed in governance metadata) the difference in scope or behaviour with this other proposal?
Also we noted @Ryun1's likely interest in both proposals & would especially look forward to his own initial assessment.
rphair
added
State: Confirmed
Quantumplation
left a comment
Quantumplation
left a comment
There was a problem hiding this comment.
Overall, this proposal is great and a long time coming. We submitted our proposals within a very short time window of ours, mostly because I got tired of waiting for someone else to do it 😅
| ### 2. Off-chain JSON-LD Schema | ||
| Any metadata document claiming to be a `GovernanceActionUpdate` MUST strictly adhere to the following schema structure, extending CIP-0100 and utilizing deep semantic mapping in the `@context`. | ||
|
|
||
| To prevent indexer Denial-of-Service (DoS), the hosted JSON-LD file MUST NOT exceed 50KB in size. Proposers are heavily encouraged to host this payload on decentralized storage (e.g., IPFS, Arweave) to prevent link rot. |
There was a problem hiding this comment.
IMO Size limits and hosting concerns are, IMO, not in the domain of a standard like this, except insomuch as we might suggest guidance to an implementor for how to handle / display large files and self-hosted documents.
An indexer should implement their own policy for how they integrate this into their tooling, and always provide access to the original document, for example.
| ### 5. On-chain Anchoring (Transaction Metadata) | ||
|
|
||
| Because the original governance action cannot be altered, the update MUST be anchored via a standard Cardano transaction. | ||
| To ensure efficient indexing by governance tooling, this standard requests the dedicated Transaction Metadata Label `1695` via the CIP-0010 registry. |
There was a problem hiding this comment.
In CIP-100 we reserved 1694 explicitly for all governance related metadata; the document itself indicates what it is (and, indeed, given the way json-ld works, can be mixed with other documents and standards), so a separate 1965 metadataum label isn't needed.
|
|
||
| 1. **Detection:** Governance tools MUST filter the blockchain for standard transactions containing label `1695`. | ||
| 2. **URI Reassembly & Fetching:** Indexers MUST concatenate the array of strings found in the `uri` field to reconstruct the full URL. To prevent DoS attacks, indexers MUST enforce a strict timeout (e.g., maximum 5 seconds) when attempting to fetch the off-chain payload. | ||
| 3. **Hash Verification:** Once fetched, indexers MUST hash the downloaded JSON-LD file using Blake2b-256 and verify it matches the `dataHash` provided in the on-chain metadata. If it does not match, the update MUST be discarded. |
There was a problem hiding this comment.
This deviates from CIP-100 recommendations; Tools are encouraged to always show the metadata, but to display an obvious warning to the user about the divergence. This is done to limit the impact that a bug in the indexer hides or censors voices at a critical time.
| 3. **Hash Verification:** Once fetched, indexers MUST hash the downloaded JSON-LD file using Blake2b-256 and verify it matches the `dataHash` provided in the on-chain metadata. If it does not match, the update MUST be discarded. | ||
| 4. **Cross-Referencing & Signature Validation:** * Utilizing the `txHash` from the on-chain metadata, resolve the original Governance Action and fetch its original off-chain JSON-LD metadata. | ||
| * Extract the `publicKey`(s) from the original proposal's `authors` array. | ||
| * Verify that the `publicKey` present in the Addendum's `witness` block exactly matches at least one of the original public keys. |
There was a problem hiding this comment.
"at least one of"; this allows one author to speak on behalf of all authors, which is likely dangerous.
| 4. **Cross-Referencing & Signature Validation:** * Utilizing the `txHash` from the on-chain metadata, resolve the original Governance Action and fetch its original off-chain JSON-LD metadata. | ||
| * Extract the `publicKey`(s) from the original proposal's `authors` array. | ||
| * Verify that the `publicKey` present in the Addendum's `witness` block exactly matches at least one of the original public keys. | ||
| * Perform standard CIP-0100 signature verification on the Addendum's `body`. If the keys do not match, or the signature is invalid, the Addendum MUST be discarded. |
There was a problem hiding this comment.
Again, CIP-100 recommendation is to surface anything, and make deviations obvious to users. It avoids censorship, and lets DReps make their own judgement call. Indeed, the fact that someone is trying to impersonate the author can also be useful voting signal.
| * Extract the `publicKey`(s) from the original proposal's `authors` array. | ||
| * Verify that the `publicKey` present in the Addendum's `witness` block exactly matches at least one of the original public keys. | ||
| * Perform standard CIP-0100 signature verification on the Addendum's `body`. If the keys do not match, or the signature is invalid, the Addendum MUST be discarded. | ||
| 5. **Conflict Resolution:** If multiple valid updates share the same `sequenceNumber`, indexers MUST prioritize the update contained in the transaction with the lower absolute slot number. If they share the same block, prioritize the lexicographically lower transaction hash. |
There was a problem hiding this comment.
Transactions in the block have an ordering; insisting on the lexographically lower transaction hash causes the processing order to deviate from how anything else would normally process transactions.
| * Verify that the `publicKey` present in the Addendum's `witness` block exactly matches at least one of the original public keys. | ||
| * Perform standard CIP-0100 signature verification on the Addendum's `body`. If the keys do not match, or the signature is invalid, the Addendum MUST be discarded. | ||
| 5. **Conflict Resolution:** If multiple valid updates share the same `sequenceNumber`, indexers MUST prioritize the update contained in the transaction with the lower absolute slot number. If they share the same block, prioritize the lexicographically lower transaction hash. | ||
| 6. **Terminal State:** Indexers SHOULD NOT render new updates submitted to the chain after the original governance action has reached a finalized state (Ratified, Expired, or Dropped). |
There was a problem hiding this comment.
Similar note here; IMO tools should show this, and make it clear that it was posted after the fact.
| ## Rationale | ||
|
|
||
| - **Preserving Immutability:** By using standard transactions to publish updates rather than attempting to alter the governance action itself, this design respects the fundamental immutability requirements of Cardano governance actions outlined in the Constitution. | ||
| - **Authentication via Auxiliary Metadata:** Unlike native CIP-1694 Governance Actions or Votes, which utilize ledger-enforced anchors signed directly by the actor's credential, these updates utilize standard transaction auxiliary metadata (Label 1695). Because any network participant can submit a transaction containing auxiliary metadata, on-chain transaction signatures cannot be used to prove provenance. Therefore, it is strictly mandatory that the off-chain JSON-LD document contains a valid `witness` signature from the original author to prevent malicious actors from broadcasting forged updates. |
There was a problem hiding this comment.
Note that this isn't strictly true; we could, for example, index and allow transactions submitted if they were signed by the same set of signatures that originally published the governance action.
| - **Authentication via Auxiliary Metadata:** Unlike native CIP-1694 Governance Actions or Votes, which utilize ledger-enforced anchors signed directly by the actor's credential, these updates utilize standard transaction auxiliary metadata (Label 1695). Because any network participant can submit a transaction containing auxiliary metadata, on-chain transaction signatures cannot be used to prove provenance. Therefore, it is strictly mandatory that the off-chain JSON-LD document contains a valid `witness` signature from the original author to prevent malicious actors from broadcasting forged updates. | ||
| - **Hardware Wallet Support:** While hardware wallets cannot natively generate CIP-0100 JSON-LD payloads in isolation, this standard relies on existing ecosystem tooling (such as CLI tools like `cardano-signer` or dedicated frontend DApps) to construct the payload, chunk the on-chain metadata, and request the signature via standard wallet derivation paths. | ||
| - **Separation of Concerns (Label 1695):** Requesting a distinct metadata label (`1695`) instead of overloading `1694` or `674` allows indexers to safely filter for governance updates without routing logic conflicts or having to parse standard transaction comments. | ||
| - **64-Byte Limit Compliance:** Explicitly separating the `txHash` and chunking the `uri` into an array ensures that standard indexers will not fail when attempting to read the on-chain pointer, respecting the hardcoded limits of the Cardano ledger. |
There was a problem hiding this comment.
In particular, it's not just about the indexers: the cardano ledger will reject transactions that do not.
rphair
changed the title
There was a problem hiding this comment.
@thenic95 with apologies I have to rename this from candidate CIP-0183 to 185 because of duplication with this slightly older proposal:
This renaming ensures your proposal is still numbered consecutively with @Quantumplation's proposal of nearly identical purpose:
Editors & reviewers might prefer a unification of these two governance metadata proposals if possible — based on a selection of details that satisfies both your objectives — and though only 1 of these proposals might be merged in the long run, it won't help now to give them both the same candidate CIP number 😅
(this also means, when you get around to updating based on editorial & review suggestions, that the containing directory must be renamed to CIP-0185)
|
Thank you for the heads-up, Robert. I plan to spend some more time on this CIP and potential consolidation efforts after the current budget season has somewhat concluded. I greatly appreciate the editors' and reviewers' feedback. |
- Rename directory to CIP-0185 as requested by editors - Conform to CIP-0001 template: single Category, full Motivation/Rationale headings, Copyright section, PR links in Discussions - Adopt CIP-0100 label 1694 instead of requesting a new label, with a typed anchor for cheap indexer filtering - Replace discard rules with CIP-0100 always-display-with-warnings philosophy; resolve conflicts by canonical chain order - Absorb from CIP-0184 (PR cardano-foundation#1182): update type taxonomy, binding statements, author-complete signing rule, no-widening constraints, and bootstrapping of update authority; add Pi Lanningham as co-author - Add JSON-LD context, JSON schema, and example document - Move fetch limits from normative spec to implementation guidance Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
@thenic95 your current plan to consolidate this with CIP-0184? / #1182 is very welcome, pending @Quantumplation's agreement. FYI reviewers: that plan is described, with a merged proposal linked, here: |
There was a problem hiding this comment.
It was resolved at the CIP meeting today that we'll continue commentary on this PR thread alone (vs. #1182 which we agreed to mark Draft to avoid duplication of effort) before & after @thenic95's proposed merger of the two proposals as outlined in #1182 (comment).
Once that consolidation is complete, we can definitively close the other one (cc @Quantumplation) and then we'll solicit general review on the resulting proposal here.
|
@rphair Thanks for the productive session on 21 July! As agreed, I've now pushed the consolidated proposal: c0054d1 Summary of what changed:
Ready for review whenever convenient, and happy to help close out #1182 once this lands, per the plan. |
rphair
left a comment
rphair
left a comment
There was a problem hiding this comment.
@thenic95 this all looks very well written, technically complete & workable to me. I have no practical experience with this data structure so I would follow the reviews from related stakeholders in certifying it.
Please tag whoever might have made the case for this in governance workshops & working groups — I'll try to get started with some who have contributed reviews & done work in this scope (e.g. #978): @Ryun1 @Crypto2099 @gitmachtl @gufmar @ptrdsh
... and especially after @Quantumplation's own review and/or acceptance of the merged changes we can mark this for Last Check review as soon as there seems nothing further to add or change (next meeting on biweekly schedule = https://hackmd.io/@cip-editors/141).
| Discussions: | ||
| - https://github.com/cardano-foundation/CIPs/pull/1180 | ||
| - https://github.com/cardano-foundation/CIPs/pull/1182 |
There was a problem hiding this comment.
| Discussions: | |
| - https://github.com/cardano-foundation/CIPs/pull/1180 | |
| - https://github.com/cardano-foundation/CIPs/pull/1182 | |
| Discussions: | |
| - Original PR: https://github.com/cardano-foundation/CIPs/pull/1180 | |
| - Concurrent PR (closed): https://github.com/cardano-foundation/CIPs/pull/1182 |
This will fix the validation problem currently reported here: https://github.com/cardano-foundation/CIPs/actions/runs/31160001114/job/92807938789?pr=1180
| [CIP-0010]: ../CIP-0010/README.md | ||
| [CIP-0100]: ../CIP-0100/README.md | ||
| [CIP-0108]: ../CIP-0108/README.md |
There was a problem hiding this comment.
| [CIP-0010]: ../CIP-0010/README.md | |
| [CIP-0100]: ../CIP-0100/README.md | |
| [CIP-0108]: ../CIP-0108/README.md | |
| [CIP-0010]: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0010/README.md | |
| [CIP-0100]: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md | |
| [CIP-0108]: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0108/README.md |
Relative links for CIPs have never been portable... they're used but they've been hit-or-miss and so authors are generally advised to use absolute URLs: i.e. GitHub URLs because their immutability makes them canonical.
See CIP-1852 to show how relative links in the GitHub source document are inadequate: the ../ works properly on GitHub (follow the relative link to CIP-0003 to confirm) but the different framework on cips.cardano.org makes that link fail on its version of CIP-1852.
Nobody has pressed for a relative linking format that works in both contexts & I believe I added something to CIP-0001 in years gone by that advises everyone to use absolute links. Relative links were added in the meantime but only to "assets" in the same CIP/CPS.
If you believe a universal relative linking format is necessary — which would refer to a different CIP or CPS in the same document archive (i.e. without your cips.cardano.org link opening on GitHub) — then you can leave this text alone but then:
- We would have to open an issue on cf-cip-frontend to ensure relative inter-CIP links are supported, hopefully by the time this is merged (cc @aldo555) which would also fix all the currently broken relative inter-CIP links in other CIPs (cc @Ryun1).
| - **64-byte limit compliance:** chunking the `uri` into an array ensures transactions are accepted by the ledger, which rejects metadata strings over 64 bytes, and that indexers can reliably reconstruct the pointer. | ||
| - **Always-display philosophy:** an earlier draft required indexers to discard updates that failed validation or arrived after a terminal state. This revision follows CIP-0100's guidance to surface content with prominent warnings instead, because silent suppression risks censoring legitimate voices via indexer bugs and hides impersonation attempts that are themselves relevant signal. | ||
| - **Publishing updates as new governance actions** was rejected: it is heavyweight, requires deposits and re-voting, and does not address the post-ratification case where an administrator needs a clarification of an action that has already passed. | ||
| - **Relationship to CIP-0184:** this proposal was drafted concurrently with [CIP-0184][] (Governance Proposal Feedback and Addenda), and this revision incorporates several of its ideas — the update taxonomy, the author-complete signing rule, the no-widening constraints, structured `bindingStatements`, and the explicit bootstrapping of authority — reflected in its co-authorship. This CIP deliberately retains a narrower scope: a single document type covering author-issued updates to *submitted* governance actions, with a fully-specified on-chain anchoring and indexing flow. Pre-submission draft proposals and third-party feedback documents (CIP-0184's `DraftProposal` and `ProposalFeedback`) are complementary concerns and remain out of scope here. |
There was a problem hiding this comment.
| - **Relationship to CIP-0184:** this proposal was drafted concurrently with [CIP-0184][] (Governance Proposal Feedback and Addenda), and this revision incorporates several of its ideas — the update taxonomy, the author-complete signing rule, the no-widening constraints, structured `bindingStatements`, and the explicit bootstrapping of authority — reflected in its co-authorship. This CIP deliberately retains a narrower scope: a single document type covering author-issued updates to *submitted* governance actions, with a fully-specified on-chain anchoring and indexing flow. Pre-submission draft proposals and third-party feedback documents (CIP-0184's `DraftProposal` and `ProposalFeedback`) are complementary concerns and remain out of scope here. | |
| - **Relationship to CIP-0184 candidate:** this proposal was drafted concurrently with [CIP-0184?][] (Governance Proposal Feedback and Addenda), and this revision incorporates several of its ideas — the update taxonomy, the author-complete signing rule, the no-widening constraints, structured `bindingStatements`, and the explicit bootstrapping of authority — reflected in its co-authorship. This CIP deliberately retains a narrower scope: a single document type covering author-issued updates to *submitted* governance actions, with a fully-specified on-chain anchoring and indexing flow. Pre-submission draft proposals and third-party feedback documents (the CIP-0184 candidate's `DraftProposal` and `ProposalFeedback`) are complementary concerns and remain out of scope here. |
Unless #1182 is reopened at @Quantumplation's discretion, there is not going to be a CIP-0184. There was not one at the time of that number assignment either: only when merged into the repository does that become a CIP. So to be accurate both now & in the future we need some changes to the wording.
Since the CIP editors sometimes have to retract widely publicised statements about drafts and other incomplete works being called "CIPs" as soon as they are posted — which defeats the purpose of a review process — please also try to pass along this request to others who are standardising their work & try to imagine the chaos there would be if drafts were considered CIPs (i.e. standards) as soon as they were posted as a pull request. 🙏
(note the shortcut reference link will also have to be changed below: #1180 (comment))
There was a problem hiding this comment.
(apologies for not getting to a deeper review yet, but)
I do think this policy is harmful... ontologically, as soon as they exist in someone's head, they are CIP's: cardano improvement proposals. They are someones Proposal to Improve Cardano. Just like an RFC is an RFC as soon as it is posted: it is a Request For Comments, whether it actually gets widely adopted or not.
What you're objecting to is more that people imbue them with authority before the review process; An ideal process would have a separate term for those that had gone through review and been merged, perhaps Cardano Standard.
That being said, we live in an imperfect world, so I doubt we're likely to upend the entrenched process and terminology based purely on that. Just know that I'm over here grumpily grumbling.
There was a problem hiding this comment.
thanks @Quantumplation - we've been consistently encouraging the community to continue with those proposed improvements as "candidates" (i.e. the ideation & initial expression) since that term carries the same enthusiasm without declaring finality.
After some problems in the past, I think this taking better hold in the community thanks to repetition in the Community Digest which focuses on what it means to be a "candidate" CIP and what is accomplished when a submission is "completed"; e.g. this recent column.
There was a problem hiding this comment.
grumble grumble ATM machine grumble lol
| [CIP-0010]: ../CIP-0010/README.md | ||
| [CIP-0100]: ../CIP-0100/README.md | ||
| [CIP-0108]: ../CIP-0108/README.md | ||
| [CIP-0184]: https://github.com/cardano-foundation/CIPs/pull/1182 |
There was a problem hiding this comment.
| [CIP-0184]: https://github.com/cardano-foundation/CIPs/pull/1182 | |
| [CIP-0184?]: https://github.com/cardano-foundation/CIPs/pull/1182 |
(continued from previous #1180 (comment): to show CIP candidate tag correctly)
4 participants
This PR introduces a new CIP for "Governance Action Addendums." Currently, proposers lack a standardized, on-chain mechanism to provide verifiable updates or clarifications to their active governance actions, leading to severe information asymmetry among voters (where only highly connected DReps receive off-chain context).
This standard solves this by allowing authors to publish append-only, cryptographically verified updates using a dedicated transaction metadata label (1695) and an extension of the CIP-0100 JSON-LD schema. This ensures all voters have equal access to proposal refinements and rationale updates while strictly preserving the immutability of the original governance action.
(Rendered latest version)