diff --git a/docs/src/architecture/08_concepts/catalyst_docs/.pages b/docs/src/architecture/08_concepts/catalyst_docs/.pages new file mode 100644 index 0000000000..15986adb3b --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/.pages @@ -0,0 +1,5 @@ +title: Catalyst Documents +arrange: +- proposal.md +- review.md +- comment.md \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_docs/comment.md b/docs/src/architecture/08_concepts/catalyst_docs/comment.md new file mode 100644 index 0000000000..b146c2e028 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/comment.md @@ -0,0 +1,119 @@ +--- +Title: Catalyst Comment Document +Category: Catalyst +Status: Proposed +Authors: + - Steven Johnson +Implementors: + - Catalyst Fund 14 +Discussions: [] +Created: 2024-12-29 +License: CC-BY-4.0 +--- + +## Abstract + +## Comment Document + +This is a document which provides a comment against a particular [Proposal Document]. + +### Specification + +Catalyst Comment document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`type`](./../signed_doc/spec.md#type): `b679ded3-0e7c-41ba-89f8-da62a17898ea` [UUID] value. + + ```CDDL + "type" => 37(h'b679ded30e7c41ba89f8da62a17898ea') + ``` + +* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. + [Catalyst Signed Document content] must be in [JSON] format. + + ```CDDL + 3 => 30 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +* [`ref`](./../signed_doc/meta.md#ref-document-reference). + Reference to a related [Proposal Document]. +* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0b8424d4-ebfd-46e3-9577-1775a69d290c` value, + [comment template type](#comment-template). + + ```CDDL + "template" => 37(h'0b8424d4ebfd46e395771775a69d290c') + ``` + +* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional). + A reference to another comment, + where the comment is in reply to the referenced comment. + Comments may only reply to a single other comment document. + The referenced `comment` must be for the same proposal [`id`](./../signed_doc/spec.md#id), + but can be for a different proposal [`ver`](./../signed_doc/spec.md#ver). + +* [`section`](./../signed_doc/meta.md#section-section-reference) (optional). + Used when the comment only applies to a specific section to the document being commented upon, + and not the entire document. + +#### Content format + +TODO + +## Comment Template + +This document pr provides the template structure which a Comment must be formatted to, and validated against. + +### Specification + +Catalyst Comment Template document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`type`](./../signed_doc/spec.md#type): `0b8424d4-ebfd-46e3-9577-1775a69d290c` [UUID] value. + + ```CDDL + "type" => 37(h'0b8424d4ebfd46e395771775a69d290c') + ``` + +* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. + [Catalyst Signed Document content] must be in [JSON] format. + + ```CDDL + 3 => 30 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +#### Content format + +TODO + +## Copyright + +This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +[Catalyst Signed Document]: ./../signed_doc/spec.md +[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content +[Proposal Document]: ./proposal.md +[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 +[JSON]: https://datatracker.ietf.org/doc/html/rfc7159 +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md new file mode 100644 index 0000000000..f9639cc64d --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -0,0 +1,109 @@ +--- +Title: Catalyst Proposal Document +Category: Catalyst +Status: Proposed +Authors: + - Steven Johnson +Implementors: + - Catalyst Fund 14 +Discussions: [] +Created: 2024-12-29 +License: CC-BY-4.0 +--- + +## Abstract + +## Proposal Document + +This is a document, formatted against the referenced proposal template, which defines a proposal which may be submitted +for consideration under one or more brand campaign categories. + +The brand, campaign and category are not part of the document because the document can exist outside this boundary. +They are defined when a specific document is submitted for consideration. + +### Specification + +Catalyst Proposal document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`type`](./../signed_doc/spec.md#type): `7808d2ba-d511-40af-84e8-c0d1625fdfdc` [UUID] value. + + ```CDDL + "type" => 37(h'7808d2bad51140af84e8c0d1625fdfdc') + ``` + +* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. + [Catalyst Signed Document content] must be in [JSON] format. + + ```CDDL + 3 => 30 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0ce8ab38-9258-4fbc-a62e-7faa6e58318f` value, + [proposal template type](#proposal-template). + + ```CDDL + "template" => 37(h'0ce8ab3892584fbca62e7faa6e58318f') + ``` + +#### Content format + +TODO + +## Proposal Template + +This document provides the template structure which a Proposal must be formatted to, and validated against. + +### Specification + +Catalyst Proposal Template document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`type`](./../signed_doc/spec.md#type): `0ce8ab38-9258-4fbc-a62e-7faa6e58318f` [UUID] value. + + ```CDDL + "type" => 37(h'0ce8ab3892584fbca62e7faa6e58318f') + ``` + +* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. + [Catalyst Signed Document content] must be in [JSON] format. + + ```CDDL + 3 => 30 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +#### Content format + +TODO + +## Copyright + +This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +[Catalyst Signed Document]: ./../signed_doc/spec.md +[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content +[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 +[JSON]: https://datatracker.ietf.org/doc/html/rfc7159 +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html diff --git a/docs/src/architecture/08_concepts/catalyst_docs/review.md b/docs/src/architecture/08_concepts/catalyst_docs/review.md new file mode 100644 index 0000000000..456bd3d69c --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/review.md @@ -0,0 +1,105 @@ +--- +Title: Catalyst Review Document +Category: Catalyst +Status: Proposed +Authors: + - Steven Johnson +Implementors: + - Catalyst Fund 14 +Discussions: [] +Created: 2024-12-29 +License: CC-BY-4.0 +--- + +## Abstract + +## Review Document + +TODO + +### Specification + +Catalyst Review document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`type`](./../signed_doc/spec.md#type): `e4caf5f0-098b-45fd-94f3-0702a4573db5` [UUID] value. + + ```CDDL + "type" => 37(h'e4caf5f0098b45fd94f30702a4573db5') + ``` + +* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. + [Catalyst Signed Document content] must be in [JSON] format. + + ```CDDL + 3 => 30 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `ebe5d0bf-5d86-4577-af4d-008fddbe2edc` value, + [review template type](#review-template). + + ```CDDL + "template" => 37(h'ebe5d0bf5d864577af4d008fddbe2edc') + ``` + +#### Content format + +TODO + +## Review Template + +TODO + +### Specification + +Catalyst Review Template document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`type`](./../signed_doc/spec.md#type): `ebe5d0bf-5d86-4577-af4d-008fddbe2edc` [UUID] value. + + ```CDDL + "type" => 37(h'ebe5d0bf5d864577af4d008fddbe2edc') + ``` + +* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. + [Catalyst Signed Document content] must be in [JSON] format. + + ```CDDL + 3 => 30 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +#### Content format + +TODO + +## Copyright + +This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +[Catalyst Signed Document]: ./../signed_doc/spec.md +[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content +[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 +[JSON]: https://datatracker.ietf.org/doc/html/rfc7159 +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile index db9c8d6863..b484de1990 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile @@ -10,10 +10,8 @@ check-cddl: COPY ./gen_vote_tx.cddl \ ./vote_tx_v2_public.cddl \ ./vote_tx_v2_private.cddl \ - ./gen_vote_tx_cose_payload.cddl \ . - RUN cddlc -2 gen_vote_tx_cose_payload.cddl RUN cddlc -2 gen_vote_tx.cddl RUN cddlc -2 vote_tx_v2_public.cddl RUN cddlc -2 vote_tx_v2_private.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl index c343b5658b..ef18b5a635 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl @@ -2,22 +2,10 @@ ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 gen-vote-tx = [ - tx-body, - signature -] - -tx-body = [ - vote-type, - event, votes, voter-data, ] -vote-type = UUID ; e.g. Public or Private vote -event = { * event-key => event-value } -event-key = int / text -event-value = any - votes = [+ vote] vote = [ choices, @@ -30,8 +18,3 @@ proof = #6.24(bytes .cbor proof-t) ; encoded-cbor prop-id = #6.24(bytes .cbor prop-id-t) ; encoded-cbor voter-data = #6.24(bytes .cbor voter-data-t) ; encoded-cbor - -UUID = #6.37(bytes) ; UUID type -signature = #6.98(cose.COSE_Sign) ; COSE signature - -;# import rfc9052 as cose diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl index 8499c7ddf0..f80efcb091 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl @@ -6,7 +6,7 @@ vote-tx-v2 = gen-vote-tx = gen-vote-tx -`event` - a set of different identifiers which is uniquely define a particular voting event. - Vote: * `choices` - a collection of voter choices for the proposal. @@ -44,32 +42,6 @@ Vote: `voter-data` - an any additional voter's specific data. -### Transaction signing - -[COSE] is used to define a transaction's signature structure. -[COSE] is a flexible security protocol that supports various types of security messages. -However, only `COSE Signed Data Object` or `COSE_Sign` type is used. - -The following header must be included in the [COSE] signature. - -`protected`: - -* `content type`: `application/cbor` - (this parameter is used to indicate the content type of the data in the payload or ciphertext fields). - -Any other headers as `alg`, `kid` etc. could be specified of any kind and not defined by this spec. - -#### Signature payload - -As mentioned earlier, the content type of the [COSE] signature payload is `application/cbor`. -In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: - - -```CDDL -{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl') }} -``` - - ## Rationale ## Path to Active @@ -82,6 +54,4 @@ In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: -[BLAKE2b-256]: https://www.blake2.net/blake2.pdf -[COSE]: https://datatracker.ietf.org/doc/rfc9052/ -[CBOR]: https://datatracker.ietf.org/doc/rfc8949/ +[CDDL]: https://datatracker.ietf.org/doc/html/rfc8610 diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 53a583d45c..45c1192581 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -1,16 +1,9 @@ -# V2 - --- - Title: Catalyst V2 Voting Transaction - Status: Proposed - Authors: - Alex Pozhylenkov - Created: 2024-10-24 - --- ## Abstract @@ -21,33 +14,47 @@ This document describes a Catalyst V2 vote transaction structure. ## Specification -It is a Catalyst v2 voting transaction -defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specification) structure. +Catalyst v2 voting transaction is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. -Following that spec need to define a `choice`, `proof` and `prop-id`. +### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`content type`](./../signed_doc/spec.md#content-type): `application/cbor`. + [Catalyst Signed Document content] must be a [CBOR] encoded. + + ```CDDL + 3 => 50 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +* [`brand_id`](./../signed_doc/meta.md#brand_id). +* [`campaign_id`](./../signed_doc/meta.md#campaign_id). +* [`election_id`](./../signed_doc/meta.md#election_id). +* [`category_id`](./../signed_doc/meta.md#category_id). + +#### Public vote -Also needed to define an `event` field, -so for both public and private transaction it must be the following: - -```CDDL -event = { - "brand_id": UUID, - "campaign_id": UUID, - "election_id": UUID, - "category_id": UUID, -} -``` - -* `brand_id` - a unique identifier which represents a "brand" who is running the voting, - e.g. Catalyst, Midnight. -* `campaign_id` - a unique identifier which defines a "campaign" of voting, - e.g. "treasury campaign". -* `election_id` - a unique identifier which defines an election, - e.g. "Catalyst Fund 1", "Catalyst Fund 2". -* `category_id` - a unique identifier which defines a voting category as a collection of proposals, - e.g. "Development & Infrastructure", "Products & Integrations". - -### Public vote +For the public vote [`type`](./../signed_doc/spec.md#type) value defined as follows: + +* [`type`](./../signed_doc/spec.md#type): `8de5586c-e998-4b95-8742-7be3c8592803` [UUID] value. + + ```CDDL + "type" => 37(h'8DE5586CE9984B9587427BE3C8592803') + ``` + +##### Content format + +The public vote transaction [Catalyst Signed Document content] format is based on the [Generalized Vote Transaction Structure]. + +Following that spec need to define a `choice`, `proof` and `prop-id`. ??? note "Public vote transaction v2 definition: `vote_tx_v2_public.cddl`" @@ -57,13 +64,21 @@ event = { ``` -For the public vote `vote-type` value defined as follows: +#### Private vote + +For the private vote [`type`](./../signed_doc/spec.md#type) value defined as follows: -```CDDL -vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803 -``` +* [`type`](./../signed_doc/spec.md#type): `e78ee18d-f380-44c1-a852-80aa6ecb07fe` [UUID] value. -### Private vote + ```CDDL + "type" => 37(h'E78EE18DF38044C1A85280AA6ECB07FE') + ``` + +##### Content format + +The private vote transaction [Catalyst Signed Document content] format is based on the [Generalized Vote Transaction Structure]. + +Following that spec need to define a `choice`, `proof` and `prop-id`. ??? note "Private vote transaction v2 definition: `vote_tx_v2_private.cddl`" @@ -73,13 +88,7 @@ vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742 ``` -For the private vote `vote-type` value defined as follows: - -```CDDL -vote-type = #6.37(h'E78EE18DF38044C1A85280AA6ECB07FE') ; e78ee18d-f380-44c1-a852-80aa6ecb07fe -``` - -#### Vote and Proof generation +##### Vote and Proof generation To generate a cryptographically secured `choice-data` and `zk_proof` parts you can follow this [spec](./crypto.md#vote). Important to note, @@ -102,7 +111,11 @@ the following properties are used: +[Catalyst Signed Document]: ./../signed_doc/spec.md +[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content +[Generalized Vote Transaction Structure]: ./gen_vote_tx.md [BLAKE2b-512]: https://www.blake2.net/blake2.pdf [ristretto255]: https://ristretto.group - - +[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html +[CBOR]: https://datatracker.ietf.org/doc/rfc8949/ diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile index 84fa4e9a54..d98629da5d 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile @@ -7,8 +7,7 @@ check-cddl: WORKDIR /cddl - COPY ./block.cddl ./genesis_to_prev_hash.cddl ./hash.cddl . + COPY ./block.cddl ./hash.cddl . RUN cddlc -2 hash.cddl RUN cddlc -2 block.cddl - RUN cddlc -2 genesis_to_prev_hash.cddl diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl index 1dfc20a029..3749ecf809 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl @@ -4,18 +4,13 @@ block = [ block-header, block-data, - validator-signature, ] block-header = [ - chain-id: UUID, ; UUID v7 height: int, - timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time - prev-block-id: hash-bytes, ; hash of the previous block ?ledger-type: UUID, ; UUID v4 ?purpose-id: UUID, ; UUID v7 - ?validator, - ~metadata, + ~extra-header-data, ] block-data = encoded-cbor @@ -24,9 +19,6 @@ UUID = #6.37(bytes) ; UUID type kid = hash-bytes ; hash of the x509/c509 certificate -validator = (kid / [2* kid]) -metadata = [ *any ] - -validator-signature = (bytes / [2* bytes]) +extra-header-data = [ *any ] ;# include hash diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl deleted file mode 100644 index 740d0234e5..0000000000 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl +++ /dev/null @@ -1,17 +0,0 @@ -; All encoders/decoders of this specification must follow deterministic cbor encoding rules -; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 - -genesis-to-prev-hash = [ - chain-id: UUID, ; UUID v7 - timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time - ledger-type: UUID, ; UUID v4 - purpose-id: UUID, ; UUID v7 - validator, -] - -UUID = #6.37(bytes) ; UUID type - -validator = (kid / [2* kid]) -kid = hash-bytes ; hash of the x509/c509 certificate - -;# include hash diff --git a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md index af4cb2c95b..f3731abdad 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md +++ b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md @@ -72,6 +72,47 @@ Which is well suited where it comes to process some temporary event e.g. voting. ### Block structure +Immutable ledger block is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +### Metadata Fields + +* [`id`](./../signed_doc/spec.md#id). + Used as a unique identifier of the chain. + So all blocks from the same chain must have the same + [`id`](./../signed_doc/spec.md#id) field value. +* [`ver`](./../signed_doc/spec.md#ver). + Used as a unique identifier of the block itself. + Also the block's creation `timestamp` value is determined from the + [`ver`](./../signed_doc/spec.md#ver) field. +* [`content type`](./../signed_doc/spec.md#content-type): `application/cbor`. + [Catalyst Signed Document content] must be a [CBOR] encoded. + + ```CDDL + 3 => 50 + ``` + +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. + + ```CDDL + "content-type" => "br" + ``` + +* [`type`](./../signed_doc/spec.md#type): `d9e7e6ce-2401-4d7d-9492-f4f7c64241c3` [UUID] value. + + ```CDDL + "type" => 37(h'D9E7E6CE24014D7D9492F4F7C64241C3') + ``` + +* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference). + Previous block reference. + A [`ref`](./../signed_doc/meta.md#ref-document-reference) part **must** be a pair of + [`id`](./../signed_doc/spec.md#id) and + [`ver`](./../signed_doc/spec.md#ver). + +### Content format + ??? note "Block CDDL definition: `block.cddl`" @@ -82,12 +123,9 @@ Which is well suited where it comes to process some temporary event e.g. voting. Header: -* `chain-id` - unique identifier of the chain. * `height` - block's height. Also is used to identify the block type: *genesis*, *regular*, *final* (in more details described in [validation section](#block-validation-rules)). -* `timestamp` - block's timestamp. -* `prev-block-id` - previous block hash. * `ledger-type` - unique identifier of the ledger type. In general, this is the way to strictly bound and specify `block-data` of the ledger for the specific `ledger-type`. But such rules will be a part of the specific ledger type definition, @@ -97,63 +135,42 @@ Header: each Ledger instance will have a strict time boundaries, so each of them will run for different purposes. This is the way to distinguish them. -* `validator` - identifier or identifiers of the entity who was produced and processed a block. -* `metadata` - fully optional field, to add some arbitrary metadata to the block. +* `extra-header-data` - fully optional field, to add some arbitrary data to the block header. Block: * `block-header` - block header described above, * `block-data` - an array of some CBOR encoded data -* `validator-signature` - a signature or signatures of the validator's. ### Block validation rules -* `chain-id` **MUST** be the same as for the previous block (except for genesis). +* [`id`](./../signed_doc/spec.md#id) + **MUST** be the same as for the previous block (except for genesis). * `height` **MUST** be incremented by `1` from the previous block height value (except for genesis and final block). *Genesis* block **MUST** have `0` value. *Final* block **MUST** hash be incremented by `1` from the previous block height and changed the sign to negative. E.g. previous block height is `9` and the *Final* block height is `-10`. * *Final* block is the last one for the specific chain and any other block could not be referenced to the *Final* one. -* `timestamp` **MUST** be greater or equals than the `timestamp` of the previous block (except for genesis). -* `prev-block-id` **MUST** be a hash of the previous block bytes (except for genesis). - +* [`ver`](./../signed_doc/spec.md#ver) + timestamp value **MUST** be greater or equals than the corresponding `timestamp` + of the previous block (except for genesis). +* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference) + **MUST** be a reference to the previous block (except for genesis). * `ledger-type` **MUST** be the same as for the previous block if present (except for genesis). **MANDATORY** field for *Genesis* and *Final* blocks. * `purpose-id` **MUST** be the same as for the previous block if present (except for genesis). **MANDATORY** field for *Genesis* and *Final* blocks. -* `validator` **MUST** be the same as for the previous block if present (except for genesis). - **MANDATORY** field for *Genesis* and *Final* blocks. -* `prev-block-id`'s CBOR tag value and `bstr` size **MUST** be the same as for the previous block (except for genesis). +* [`kid`](./../signed_doc/spec.md#cose-signature-protected-header) field + **MUST** be the same as for the previous block (except for genesis). +* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference)'s + `hash-bytes` CBOR tag value and `bytes` size + **MUST** be the same as for the previous block (except for genesis). Means that the hash function type and hash size itself must be the same. -* `prev-block-id` and `validator-signature` **MUST** use the same hash function, defined with the - `hash-bytes`. - -* `prev-block-id` for the *Genesis* block **MUST** be a hash of the `genesis-to-prev-hash` bytes. - +* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference) + field for the *Genesis* block **MUST** be omitted. * `block-data` **MUST** be a [deterministically][CBOR-deterministically-encoded] encoded CBOR. - -??? note "Genesis to previous block hash CDDL definition: `genesis-to-prev-hash.cddl`" - - ```CDDL - {{ include_file('src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl',indent=4) }} - ``` - - -#### Signature rules - -`validator-signature` -**MUST** be a signature of the hashed `block-header` bytes and the `block-data` bytes -(with the order the same as defined for `block`). -Signed by the validator's keys defined in the corresponding certificates referenced by the `validator`. -Signature algorithm is defined by the certificate. -The format and size of this field **MUST** be totally the same as `validator` field: - -* if `validator` is only one id => `validator-signature` contains only 1 signature; -* if `validator` is array => `validator-signature` contains an array with the same length; -* order of signatures from the `validator-signature`'s array corresponds to the validators order of `validator`'s array. - ## Rationale ## Path to Active @@ -166,4 +183,8 @@ The format and size of this field **MUST** be totally the same as `validator` fi +[Catalyst Signed Document]: ./../signed_doc/spec.md +[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content [CBOR-deterministically-encoded]: https://datatracker.ietf.org/doc/html/rfc8949#name-deterministically-encoded-c +[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 +[CBOR]: https://datatracker.ietf.org/doc/rfc8949/ diff --git a/docs/src/architecture/08_concepts/signed_doc/.pages b/docs/src/architecture/08_concepts/signed_doc/.pages new file mode 100644 index 0000000000..ffda03396a --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/.pages @@ -0,0 +1,5 @@ +title: Catalyst Signed Document +nav: + - Specification: spec.md + - Metadata Fields: meta.md + - Document Types: types.md diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile b/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile new file mode 100644 index 0000000000..dbfe99684b --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile @@ -0,0 +1,14 @@ +VERSION 0.8 + +IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.2.27 AS cddl-ci + +check-cddl: + FROM cddl-ci+cddl-base + + WORKDIR /cddl + + COPY ./additional_meta.cddl ./hash.cddl ./signed_doc_meta.cddl . + + RUN cddlc -2 hash.cddl + RUN cddlc -2 additional_meta.cddl + RUN cddlc -2 signed_doc_meta.cddl diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl new file mode 100644 index 0000000000..71a7ce9adc --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl @@ -0,0 +1,19 @@ +additional_fields = { + ? "ref" => ref_type, + ? "ref_hash" => ref_hash_type, + ? "template" => ref_type, + ? "reply" => ref_type, + ? "section" => text, + ? "collabs" => [+any], + ? "brand_id" => UUID, ; UUID v4 + ? "campaign_id" => UUID, ; UUID v4 + ? "election_id" => UUID, ; UUID v4 + ? "category_id" => UUID, ; UUID v4 +} + +ref_type = UUID / [UUID, UUID] ; UUIDs v7 +ref_hash_type = [ref_type, hash-bytes] + +UUID = #6.37(bytes) + +;# include hash diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/blueprint.cue b/docs/src/architecture/08_concepts/signed_doc/cddl/blueprint.cue new file mode 100644 index 0000000000..1624838699 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/blueprint.cue @@ -0,0 +1,2 @@ +version: "1.0.0" +project: name: "docs-signed-doc-cddl" diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/hash.cddl similarity index 56% rename from docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl rename to docs/src/architecture/08_concepts/signed_doc/cddl/hash.cddl index e0a996f19c..18c0d6e4a1 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/hash.cddl @@ -1,5 +1,8 @@ ; All encoders/decoders of this specification must follow deterministic cbor encoding rules ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 -cose-payload = blake2b-256 -blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes +hash-bytes = ( + #6.32781(bytes) / ; Blake3 hash + #6.32782(bytes) / ; Blake2b hash + #6.32783(bytes) ; Blake2s hash +) diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl new file mode 100644 index 0000000000..212ca843bd --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl @@ -0,0 +1,25 @@ +; All encoders/decoders of this specification must follow deterministic cbor encoding rules +; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 + +signed_doc_meta = { + "type" => UUID, ; UUID v4 + "id" => UUID, ; UUID v7 + "ver" => UUID, ; UUID v7 + + 1 => -8, ; "alg": EdDSA + 3 => text / int, ; "content type" + ? content-encoding-key => "br", ; payload content encoding + + ~meta.additional_fields, + + * metadata-key => metadata-value +} + +content-encoding-key = "Content-Encoding" / "content-encoding" + +metadata-key = int / text +metadata-value = any + +UUID = #6.37(bytes) + +;# include additional_meta as meta diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md new file mode 100644 index 0000000000..8088cd2b0b --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -0,0 +1,111 @@ +# Metadata Fields List + + +??? note "Additional Metadata fields: `additional_meta.cddl`" + + ```CDDL + {{ include_file('src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl', indent=4) }} + ``` + + +* [Metadata Fields List](#metadata-fields-list) + * [`ref` Document Reference](#ref-document-reference) + * [`ref_hash` Secured Document Reference](#ref_hash-secured-document-reference) + * [`template` Template Reference](#template-template-reference) + * [`reply` Reply Reference](#reply-reply-reference) + * [`section` Section Reference](#section-section-reference) + * [`collabs` Authorized Collaborators](#collabs-authorized-collaborators) + * [`brand_id`](#brand_id) + * [`campaign_id`](#campaign_id) + * [`election_id`](#election_id) + * [`category_id`](#category_id) + +## `ref` Document Reference + +This is a reference to another document. +The purpose of the `ref` will vary depending on the document [`type`](./spec.md#type). + +The `ref` can be either a single [UUID] or a [CBOR] Array of Two [UUID]. + +If the `ref` is a single [UUID] v7, it is a reference to the document of that [`id`](./spec.md#id). +If the `ref` is a [CBOR] array, it has the form `[,]` where: + +* `` - the [UUID] v7 of the referenced documents [`id`](./spec.md#id). +* `` - the [UUID] v7 of the referenced documents [`ver`](./spec.md#ver). + +## `ref_hash` Secured Document Reference + +This is a cryptographically secured reference to another document. + +It consists of two fields: + +* [`ref`](#ref-document-reference) - simple reference to the document. +* `hash` - hash of the referenced document [CBOR] bytes. + +## `template` Template Reference + +If the document was formed from a template, this is a reference to that template document. +The format is the same as the [CBOR] Array form of [`ref`](#ref-document-reference). + +It is invalid not to reference the template that formed a document. +If this is missing from such documents, the document will itself be considered invalid. + +Template references must explicitly reference both the Template Document ID, and Version. + +## `reply` Reply Reference + +This is a reply to another document. +The format is the same as the [CBOR] Array form of [`ref`](#ref-document-reference). + +`reply` is always referencing a document of the same type, and that document must `ref` reference the same document `id`. +However, depending on the document type, it may reference a different `ver` of that `id`. + +## `section` Section Reference + +This is a reference to a section of a document. +It is a CBOR String, and contains a [JSON Path] identifying the section in question. + +Because this metadata field uses [JSON Path], it can only be used to reference a document whose payload is [JSON]. + +## `collabs` Authorized Collaborators + +This is a list of entities other than the original author that may also publish versions of this document. +This may be updated by the original author, or any collaborator that is given "author" privileges. + +The latest `collabs` list in the latest version, published by an authorized author is the definitive +list of allowed collaborators after that point. + +The `collabs` list is a [CBOR] Array. +The contents of the array are TBD. + +However, they will contain enough information such that each collaborator can be uniquely identified and validated. + +*Note: An Author can unilaterally set the `collabs` list to any list of collaborators. +It does NOT mean that the listed collaborators have agreed to collaborate, only that the Author +gives them permission to.* + +This list can impact actions that can be performed by the `Proposal Action Document`. + +## `brand_id` + +Unique identifier [UUID] v4, which represents a "brand" who is running the voting, +e.g. Catalyst, Midnight. + +## `campaign_id` + +Unique identifier [UUID] v4, which defines a "campaign" of voting, +e.g. "treasury campaign". + +## `election_id` + +Unique identifier [UUID] v4, which defines an election, +e.g. "Catalyst Fund 1", "Catalyst Fund 2". + +## `category_id` + +Unique identifier [UUID] v4 which defines a voting category as a collection of proposals, +e.g. "Development & Infrastructure", "Products & Integrations". + +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html +[CBOR]: https://datatracker.ietf.org/doc/rfc8949/ +[JSON Path]: https://datatracker.ietf.org/doc/html/rfc9535 diff --git a/docs/src/architecture/08_concepts/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md new file mode 100644 index 0000000000..11752acd42 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/spec.md @@ -0,0 +1,176 @@ +--- +Title: Catalyst Signed Document +Category: Catalyst +Status: Proposed +Authors: + - Steven Johnson + - Alex Pozhylenkov +Implementors: + - Catalyst Fund 14 +Discussions: [] +Created: 2024-12-27 +License: CC-BY-4.0 +--- + +* [Abstract](#abstract) +* [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary) +* [Specification](#specification) + * [Catalyst Signed Document metadata fields](#catalyst-signed-document-metadata-fields) + * [`type`](#type) + * [`id`](#id) + * [`ver`](#ver) + * [`alg`](#alg) + * [`content type`](#content-type) + * [`content encoding` (optional)](#content-encoding-optional) + * [Catalyst Signed Document content](#catalyst-signed-document-content) + * [COSE signature protected header](#cose-signature-protected-header) +* [Copyright](#copyright) + +## Abstract + +Project Catalyst both produces and consumes a lot of different data objects, +in different places of the system. +To ensure the data object is authoritative, it must be signed. +In addition to the data object content and the signature, metadata is also included +to describe different kind of Catalyst Signed Document properties. + +## Motivation: why is this CIP necessary? + +As we decentralize project catalyst, it will be required to unambiguously identify who produced some +data object, and the purpose of it. + +## Specification + +Catalyst Signed Document is [COSE] based structure, particularly `COSE Signed Data Object` [COSE] type. +It fully inherits an original [COSE] design and specifies the details of different [COSE] header's fields. + +### Catalyst Signed Document metadata fields + +To uniquely specify a Catalyst Signed Document `id`, `type`, `version` etc., +a list of different metadata fields is specified. + +Also as you can see from the specification, +it is allowed to add any number of additional metadata fields, which could be specified for each `type` of document. + +[A full list of considered additional metadata fields](./meta.md). + +All these fields will be encoded as the [COSE] `protected` header + + +??? note "Catalyst Signed Document metadata fields: `signed_doc_meta.cddl`" + + ```CDDL + {{ include_file('src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl', indent=4) }} + ``` + + +#### `type` + +Each Catalyst Signed Document will have a type identifier called `type`. + +The `type` is a [UUID] v4. + +[A full list of Catalyst supported document types](./types.md) + +#### `id` + +Every Catalyst Signed Document will have a unique ID. +All Catalyst Signed Document with the same `id` are considered different versions of the same Catalyst Signed Document +(read about [`ver`](#ver)). +However, `id` uniqueness is only guaranteed on first use. + +If the same `id` is used, by unauthorized publishers, the Catalyst Signed Document is invalid. + +The `id` is a [UUID] v7. + +The first time a Catalyst Signed Document is created, it will be assigned by the creator a new `id` which must +be well constructed. + +* The time must be the time the Catalyst Signed Document was first created. +* The random value must be truly random. + +Creating `id` this way ensures there are no collisions, and they can be independently created without central co-ordination. + +*Note: All Catalyst Signed Documents are signed, +the first creation of an `id` assigns that `id` to the creator and any assigned collaborators. +A Catalyst Signed Document that is not signed by the creator, or an assigned collaborator, is invalid. +There is no reasonable way an `id` can collide accidentally. +Therefore, detection of invalid `id`s published by unauthorized publishers, could result in anti-spam +or system integrity mitigations being triggered. +This could result in all actions in the system being blocked by the offending publisher, +including all otherwise legitimate publications by the same author being marked as fraudulent.* + +#### `ver` + +Every Catalyst Signed Document in the system will be versioned. +There can, and probably will, exist multiple versions of the same document. + +The `ver` is a [UUID] v7. + +The initial `ver` assigned the first time a Catalyst Signed Document is published will be identical to the [`id`](#id). +Subsequent versions will retain the same [`id`](#id) and will create a new `ver`, +following best practice for creating a new [UUID] v7. + +#### `alg` + +This is an original [COSE] header field, +which indicates the cryptography algorithm used for the security processing. + + +!!! warning "" + + It must be equal to `EdDSA` value + + +Only `ed25119` considered at this moment as the only option to be supported for signed objects. + +#### [`content type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) + +This is an original [COSE] header field, +which indicates the [`content type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) +of the [content](#catalyst-signed-document-content) ([COSE] `payload`) data. + +#### [`content encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) (optional) + +This field is used to indicate the [`content encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) +algorithm of the [content](#catalyst-signed-document-content) data. + +Supported encodings: + +* `br` - [Brotli] compressed data. + +### Catalyst Signed Document content + +The Catalyst Signed Document content data is encoded (and could be additionally compressed, +read [`content encoding`](#content-encoding-optional)) as [COSE] `payload`. + +### [COSE] signature protected header + +As it mentioned earlier, Catalyst Signed Document utilizes `COSE Signed Data Object` format, +which allows to provide multi-signature functionality. +In that regard, +each Catalyst Signed Document [COSE] signature **must** include the following `protected` header field: + + +```CDDL +; All encoders/decoders of this specification must follow deterministic cbor encoding rules +; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 + +signature_protected_header = { + 4 => bytes ; "kid", UTF-8 encoded URI string +} +``` + + +* `kid`: A unique identifier of the signer. + A [UTF-8] encoded [URI] string. + +## Copyright + +This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 +[UTF-8]: https://datatracker.ietf.org/doc/html/rfc3629 +[URI]: https://datatracker.ietf.org/doc/html/rfc3986 +[COSE]: https://datatracker.ietf.org/doc/html/rfc9052 +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html diff --git a/docs/src/architecture/08_concepts/signed_doc/types.md b/docs/src/architecture/08_concepts/signed_doc/types.md new file mode 100644 index 0000000000..eb3469f241 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/types.md @@ -0,0 +1,26 @@ +# Document Types Table + +| [UUID] | [CBOR] | Type Description | Payload Type | Specification Link | +| ------------------------------------ | ----------------------------------------- | ---------------------------- | --------------------------------- | ------------------------------------------------------------------------------ | +| 7808d2ba-d511-40af-84e8-c0d1625fdfdc | `37(h'7808d2bad51140af84e8c0d1625fdfdc')` | Proposal Document | [Brotli] Compressed [JSON] | [Proposal Spec](./../catalyst_docs/proposal.md#proposal-document) | +| 0ce8ab38-9258-4fbc-a62e-7faa6e58318f | `37(h'0ce8ab3892584fbca62e7faa6e58318f')` | Proposal Template | [Brotli] Compressed [JSON Schema] | [Proposal Template Spec](./../catalyst_docs/proposal.md#proposal-template) | +| b679ded3-0e7c-41ba-89f8-da62a17898ea | `37(h'b679ded30e7c41ba89f8da62a17898ea')` | Comment Document | [Brotli] Compressed [JSON] | [Comment Spec](./../catalyst_docs/comment.md#comment-document) | +| 0b8424d4-ebfd-46e3-9577-1775a69d290c | `37(h'0b8424d4ebfd46e395771775a69d290c')` | Comment Template | [Brotli] Compressed [JSON Schema] | [Comment Template Spec](./../catalyst_docs/comment.md#comment-template) | +| e4caf5f0-098b-45fd-94f3-0702a4573db5 | `37(h'e4caf5f0098b45fd94f30702a4573db5')` | Review Document | [Brotli] Compressed [JSON] | [Review Spec](./../catalyst_docs/review.md#review-document) | +| ebe5d0bf-5d86-4577-af4d-008fddbe2edc | `37(h'ebe5d0bf5d864577af4d008fddbe2edc')` | Review Template | [Brotli] Compressed [JSON Schema] | [Review Template Spec](./../catalyst_docs/review.md#review-template) | +| 48c20109-362a-4d32-9bba-e0a9cf8b45be | `37(h'48c20109362a4d329bbae0a9cf8b45be')` | Category Parameters Document | [Brotli] Compressed [JSON] | *TBD* | +| 65b1e8b0-51f1-46a5-9970-72cdf26884be | `37(h'65b1e8b051f146a5997072cdf26884be')` | Category Parameters Template | [Brotli] Compressed [JSON Schema] | *TBD* | +| 0110ea96-a555-47ce-8408-36efe6ed6f7c | `37(h'0110ea96a55547ce840836efe6ed6f7c')` | Campaign Parameters Document | [Brotli] Compressed [JSON] | *TBD* | +| 7e8f5fa2-44ce-49c8-bfd5-02af42c179a3 | `37(h'7e8f5fa244ce49c8bfd502af42c179a3')` | Campaign Parameters Template | [Brotli] Compressed [JSON Schema] | *TBD* | +| 3e4808cc-c86e-467b-9702-d60baa9d1fca | `37(h'3e4808ccc86e467b9702d60baa9d1fca')` | Brand Parameters Document | [Brotli] Compressed [JSON] | *TBD* | +| fd3c1735-80b1-4eea-8d63-5f436d97ea31 | `37(h'fd3c173580b14eea8d635f436d97ea31')` | Brand Parameters Template | [Brotli] Compressed [JSON Schema] | *TBD* | +| 5e60e623-ad02-4a1b-a1ac-406db978ee48 | `37(h'5e60e623ad024a1ba1ac406db978ee48')` | Proposal Action Document | *TBD* | *TBD* | +| 8de5586c-e998-4b95-8742-7be3c8592803 | `37(h'8DE5586CE9984B9587427BE3C8592803')` | Public Vote Tx V2 | [Brotli] Compressed [CBOR] | [Public Vote Tx V2 Spec](./../catalyst_voting/v2.md#public-vote) | +| e78ee18d-f380-44c1-a852-80aa6ecb07fe | `37(h'E78EE18DF38044C1A85280AA6ECB07FE')` | Private Vote Tx V2 | [Brotli] Compressed [CBOR] | [Private Vote Tx V2 Spec](./../catalyst_voting/v2.md#private-vote) | +| d9e7e6ce-2401-4d7d-9492-f4f7c64241c3 | `37(h'D9E7E6CE24014D7D9492F4F7C64241C3')` | Immutable Ledger Block | [Brotli] Compressed [CBOR] | [Immutable Ledger Block Spec](./../immutable_ledger/ledger.md#block-structure) | + +[JSON Schema]: https://json-schema.org/draft-07 +[JSON]: https://datatracker.ietf.org/doc/html/rfc7159 +[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 +[CBOR]: https://datatracker.ietf.org/doc/html/rfc8610 +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html diff --git a/docs/src/architecture/08_concepts/signed_document_metadata/.pages b/docs/src/architecture/08_concepts/signed_document_metadata/.pages deleted file mode 100644 index 418ac0f62d..0000000000 --- a/docs/src/architecture/08_concepts/signed_document_metadata/.pages +++ /dev/null @@ -1,3 +0,0 @@ -title: Signed Document Metadata -arrange: - - metadata.md diff --git a/docs/src/architecture/08_concepts/signed_document_metadata/metadata.md b/docs/src/architecture/08_concepts/signed_document_metadata/metadata.md deleted file mode 100644 index 0240f68942..0000000000 --- a/docs/src/architecture/08_concepts/signed_document_metadata/metadata.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -Title: Signed Document Types and Metadata -Category: Catalyst -Status: Proposed -Authors: - - Steven Johnson -Implementors: - - Catalyst Fund 14 -Discussions: [] -Created: 2024-12-03 -License: CC-BY-4.0 ---- - -* [Abstract](#abstract) -* [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary) -* [Specification](#specification) - * [Document Type : `type`](#document-type--type) - * [Document Type Definitions](#document-type-definitions) - * [Document Templates](#document-templates) - * [Document Content Templates](#document-content-templates) - * [Document Metadata](#document-metadata) - * [Document ID : `id`](#document-id--id) - * [Document Version : `ver`](#document-version--ver) - * [Document Reference : `ref`](#document-reference--ref) - * [Template Reference : `template`](#template-reference--template) - * [Document Reference : `reply`](#document-reference--reply) - * [Document Reference : `section`](#document-reference--section) - * [Authorized Collaborators : `collabs`](#authorized-collaborators--collabs) - * [Document Type Specifications](#document-type-specifications) - * [Proposal Template](#proposal-template) - * [Comment Template](#comment-template) - * [Proposal Document](#proposal-document) - * [Comment Document](#comment-document) -* [Reference Implementation](#reference-implementation) -* [Rationale: how does this CIP achieve its goals?](#rationale-how-does-this-cip-achieve-its-goals) -* [Path to Active](#path-to-active) - * [Acceptance Criteria](#acceptance-criteria) - * [Implementation Plan](#implementation-plan) -* [Copyright](#copyright) - -## Abstract - -Project Catalyst both produces and consumes documents of data. -To ensure the document is authoritative, all documents of this kind will be signed. -In addition to the document contents, documents will also include metadata which describes -what kind of document it is, and how the document relates to other documents. - -## Motivation: why is this CIP necessary? - -As we decentralize project catalyst, it will be required to unambiguously identify who produced a -document, and the purpose of the document. - -A signed document specification will detail the structure of a signed document, this specification -is just the metadata that structure will carry for different kinds of documents. - -## Specification - -### Document Type : `type` - -Each document will have a document type identifier called `type`. -This identifier will be a [CBOR] Encoded [UUID Byte String]. -Only [UUID] V4 is supported and used. - -The document types and their identifiers are listed here: - -#### Document Type Definitions - -##### Document Templates - -Document Templates are themselves signed documents, the templates currently defined or planned are: - -| [UUID] | [CBOR] | Type Description | Payload Type | -| --- | --- | --- | --- | -| 0ce8ab38-9258-4fbc-a62e-7faa6e58318f | `37(h'0ce8ab3892584fbca62e7faa6e58318f')` | Proposal Template | [Brotli] Compressed [JSON Schema] | -| 0b8424d4-ebfd-46e3-9577-1775a69d290c | `37(h'0b8424d4ebfd46e395771775a69d290c')` | Comment Template | [Brotli] Compressed [JSON Schema] | -| ebe5d0bf-5d86-4577-af4d-008fddbe2edc | `37(h'ebe5d0bf5d864577af4d008fddbe2edc')` | Review Template | [Brotli] Compressed [JSON Schema] | -| 65b1e8b0-51f1-46a5-9970-72cdf26884be | `37(h'65b1e8b051f146a5997072cdf26884be')` | Category Parameters Template | [Brotli] Compressed [JSON Schema] | -| 7e8f5fa2-44ce-49c8-bfd5-02af42c179a3 | `37(h'7e8f5fa244ce49c8bfd502af42c179a3')` | Campaign Parameters Template | [Brotli] Compressed [JSON Schema] | -| fd3c1735-80b1-4eea-8d63-5f436d97ea31 | `37(h'fd3c173580b14eea8d635f436d97ea31')` | Brand Parameters Template | [Brotli] Compressed [JSON Schema] | - -##### Document Content Templates - -Document Contents are signed documents, and are typically produced in accordance with a template document. - -| [UUID] | [CBOR] | Type Description | Payload Type | -| --- | --- | --- | --- | -| 7808d2ba-d511-40af-84e8-c0d1625fdfdc | `37(h'7808d2bad51140af84e8c0d1625fdfdc')` | Proposal Document | [Brotli] Compressed [JSON] | -| b679ded3-0e7c-41ba-89f8-da62a17898ea | `37(h'b679ded30e7c41ba89f8da62a17898ea')` | Comment Document | [Brotli] Compressed [JSON] | -| e4caf5f0-098b-45fd-94f3-0702a4573db5 | `37(h'e4caf5f0098b45fd94f30702a4573db5')` | Review Document | [Brotli] Compressed [JSON] | -| 48c20109-362a-4d32-9bba-e0a9cf8b45be | `37(h'48c20109362a4d329bbae0a9cf8b45be')` | Category Parameters Document | [Brotli] Compressed [JSON] | -| 0110ea96-a555-47ce-8408-36efe6ed6f7c | `37(h'0110ea96a55547ce840836efe6ed6f7c')` | Campaign Parameters Document | [Brotli] Compressed [JSON] | -| 3e4808cc-c86e-467b-9702-d60baa9d1fca | `37(h'3e4808ccc86e467b9702d60baa9d1fca')` | Brand Parameters Document | [Brotli] Compressed [JSON] | -| 5e60e623-ad02-4a1b-a1ac-406db978ee48 | `37(h'5e60e623ad024a1ba1ac406db978ee48')` | Proposal Action Document | *TBD* | - -### Document Metadata - -Documents will contain metadata which allows the document to be categorized, versioned and linked. -This data does not properly belong inside the document, -but is critical to ensure the document is properly referenced and indexable. - -#### Document ID : `id` - - -**REQUIRED, PROTECTED HEADER** - - -Every document will have a unique document ID, this is to allow the same document to be referenced. -All documents with the same `doc_id` are considered versions of the same document. -However, `id` uniqueness is only guaranteed on first use. - -If the same `id` is used, by unauthorized publishers, the document is invalid. - -The `id` is a [UUID]. -This identifier will be a [CBOR] Encoded [UUID Byte String]. -Only [UUID] V7 is supported and used. - -The first time a document is created, it will be assigned by the creator a new `id` which must -be well constructed. - -* The time must be the time the document was first created. -* The random value must be truly random. - -Creating `id` this way ensures there are no collisions, and they can be independently created without central co-ordination. - -*Note: All documents are signed, the first creation of an `id` assigns that `id` to the creator and any assigned collaborators. -A Signed Document that is not signed by the creator, or an assigned collaborator, is invalid. -There is no reasonable way an `id` can collide accidentally. -Therefore, detection of invalid `id`s published by unauthorized publishers, could result in anti-spam -or system integrity mitigations being triggered. -This could result in all actions in the system being blocked by the offending publisher, -including all otherwise legitimate publications by the same author being marked as fraudulent.* - -#### Document Version : `ver` - - -**REQUIRED, PROTECTED HEADER** - - -Every document in the system will be versioned. -There can, and probably will, exist multiple versions of the same document. - -The `ver` is a [UUID]. -This identifier will be a [CBOR] Encoded [UUID Byte String]. -Only [UUID] V7 is supported and used. - -The initial `ver` assigned the first time a document is published will be identical to the [`id`](#document-id--id). -Subsequent versions will retain the same [`id`](#document-id--id) and will create a new `ver`, -following best practice for creating a new [UUID] v7. - -#### Document Reference : `ref` - - -**OPTIONAL, PROTECTED HEADER** - - -This is a reference to another document. -The purpose of the `ref` will vary depending on the document [`type`](#document-type--type). - -The `ref` can be either a single [UUID] or a [CBOR] Array of Two [UUID]. - -If the `ref` is a single [UUID], it is a reference to the document of that [`id`](#document-id--id). -If the `ref` is a [CBOR] array, it has the form `[,]` where: - -* `` = the [UUID] of the referenced documents [`id`](#document-id--id) -* `` = the [UUID] of the referenced documents [`ver`](#document-version--ver). - -#### Template Reference : `template` - - -**REQUIRED, IF THE DOCUMENT WAS FORMED FROM A TEMPLATE, PROTECTED HEADER** - - -If the document was formed from a template, this is a reference to that template document. -The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref). - -It is invalid not to reference the template that formed a document. -If this is missing from such documents, the document will itself be considered invalid. - -Template references must explicitly reference both the Template Document ID, and Version. - -#### Document Reference : `reply` - - -**OPTIONAL, PROTECTED HEADER** - - -This is a reply to another document. -The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref). - -`reply` is always referencing a document of the same type, and that document must `ref` reference the same document `id`. -However, depending on the document type, it may reference a different `ver` of that `id`. - -#### Document Reference : `section` - - -**OPTIONAL, PROTECTED HEADER** - - -This is a reference to a section of a document. -It is a CBOR String, and contains a [JSON Path] identifying the section in question. - -Because this metadata field uses [JSON Path], it can only be used to reference a document whose payload is [JSON]. - -#### Authorized Collaborators : `collabs` - - -**OPTIONAL, PROTECTED HEADER** - - -This is a list of entities other than the original author that may also publish versions of this document. -This may be updated by the original author, or any collaborator that is given "author" privileges. - -The latest `collabs` list in the latest version, published by an authorized author is the definitive -list of allowed collaborators after that point. - -The `collabs` list is a [CBOR] Array. -The contents of the array are TBD. - -However, they will contain enough information such that each collaborator can be uniquely identified and validated. - -*Note: An Author can unilaterally set the `collabs` list to any list of collaborators. -It does NOT mean that the listed collaborators have agreed to collaborate, only that the Author -gives them permission to.* - -This list can impact actions that can be performed by the `Proposal Action Document`. - -### Document Type Specifications - -Note, not all document types are currently specified. - -#### Proposal Template - -This document provides the template structure which a Proposal must be formatted to, and validated against. - -#### Comment Template - -This document pr provides the template structure which a Comment must be formatted to, and validated against. - -#### Proposal Document - -This is a document, formatted against the referenced proposal template, which defines a proposal which may be submitted -for consideration under one or more brand campaign categories. - -The brand, campaign and category are not part of the document because the document can exist outside this boundary. -They are defined when a specific document is submitted for consideration. - -#### Comment Document - -This is a document which provides a comment against a particular proposal. -Because comments are informed by a particular proposals version, they *MUST* contain a [`ref`](#document-reference--ref) - -They may *OPTIONALLY* also contain a [`reply`](#document-reference--reply) metadata field, which is a reference to another comment, -where the comment is in reply to the referenced comment. - -Comments may only [`reply`](#document-reference--reply) to a single other comment document. -The referenced `comment` must be for the same proposal [`id`](#document-id--id), -but can be for a different proposal [`ver`](#document-version--ver). - -Comments may *OPTIONALLY* also contain a [`subsection`](#document-reference--section) field, -when the comment only applies to a specific section to the document being commented upon, -and not the entire document. - -## Reference Implementation - -The first implementation will be Catalyst Voices. - -*TODO: Generate a set of test vectors which conform to this specification.* - -## Rationale: how does this CIP achieve its goals? - -By specifying metadata attached to signed documents and unambiguous document type identifiers, we allow -documents to be broadcast over insecure means, and for their meaning and relationships to remain intact. - -The Document itself is soft, but the metadata provides concrete relationships between documents. - -## Path to Active - -### Acceptance Criteria - -Working Implementation before Fund 14. - -### Implementation Plan - -Fund 14 project catalyst will deploy this scheme for Key derivation.> - -## Copyright - -This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -[UUID Byte String]: https://github.com/lucas-clemente/cbor-specs/blob/master/uuid.md -[JSON Schema]: https://json-schema.org/draft-07 -[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 -[JSON]: https://datatracker.ietf.org/doc/html/rfc7159 -[CBOR]: https://datatracker.ietf.org/doc/html/rfc8610 -[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html -[JSON Path]: https://datatracker.ietf.org/doc/html/rfc9535