From bafb9d8d1d3a893cf7521082fe753e0dc38e4204 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sat, 28 Dec 2024 16:48:28 +0200 Subject: [PATCH 01/33] add signed object design specs, update gen vote tx and vote v2 spec --- .../catalyst_voting/cddl/gen_vote_tx.cddl | 17 -- .../cddl/gen_vote_tx_cose_payload.cddl | 5 - .../cddl/vote_tx_v2_private.cddl | 4 +- .../cddl/vote_tx_v2_public.cddl | 4 +- .../catalyst_voting/gen_vote_tx.md | 44 ++---- .../08_concepts/catalyst_voting/v2.md | 19 +-- .../08_concepts/signed_object/.pages | 1 + .../cddl/signed_object_meta.cddl | 17 ++ .../08_concepts/signed_object/index.md | 145 ++++++++++++++++++ 9 files changed, 191 insertions(+), 65 deletions(-) delete mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl create mode 100644 docs/src/architecture/08_concepts/signed_object/.pages create mode 100644 docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl create mode 100644 docs/src/architecture/08_concepts/signed_object/index.md 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/gen_vote_tx_cose_payload.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl deleted file mode 100644 index e0a996f19c..0000000000 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl +++ /dev/null @@ -1,5 +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 - -cose-payload = blake2b-256 -blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes 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 50 + ``` +* [`content encoding`](./../signed_object/index.md#content-encoding-optional): is missing + +### Content format + +The generalized vote transaction [content format](./../signed_object/index.md#signed-object-content) + ??? note "vote transaction definition: `gen_vote_tx.cddl`" @@ -31,8 +44,6 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure ``` -`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 +55,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 +67,7 @@ In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: +[signed object]: ./../signed_object/index.md [BLAKE2b-256]: https://www.blake2.net/blake2.pdf [COSE]: https://datatracker.ietf.org/doc/rfc9052/ [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 53a583d45c..623e0affc5 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -26,16 +26,13 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec need to define a `choice`, `proof` and `prop-id`. -Also needed to define an `event` field, -so for both public and private transaction it must be the following: +Also additional [signed object protected header fields](./../signed_object/index.md#signed-object-fields) are defined, ```CDDL -event = { - "brand_id": UUID, - "campaign_id": UUID, - "election_id": UUID, - "category_id": UUID, -} +"brand_id" => UUID, ; UUID v4 +"campaign_id" => UUID, ; UUID v4 +"election_id" => UUID, ; UUID v4 +"category_id" => UUID, ; UUID v4 ``` * `brand_id` - a unique identifier which represents a "brand" who is running the voting, @@ -57,7 +54,7 @@ event = { ``` -For the public vote `vote-type` value defined as follows: +For the public vote [`type`](./../signed_object/index.md#type) value defined as follows: ```CDDL vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803 @@ -73,7 +70,7 @@ vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742 ``` -For the private vote `vote-type` value defined as follows: +For the private vote [`type`](./../signed_object/index.md#type) value defined as follows: ```CDDL vote-type = #6.37(h'E78EE18DF38044C1A85280AA6ECB07FE') ; e78ee18d-f380-44c1-a852-80aa6ecb07fe @@ -104,5 +101,3 @@ the following properties are used: [BLAKE2b-512]: https://www.blake2.net/blake2.pdf [ristretto255]: https://ristretto.group - - diff --git a/docs/src/architecture/08_concepts/signed_object/.pages b/docs/src/architecture/08_concepts/signed_object/.pages new file mode 100644 index 0000000000..a6e0c31069 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_object/.pages @@ -0,0 +1 @@ +title: Catalyst Signed Object diff --git a/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl b/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl new file mode 100644 index 0000000000..1aa7d74963 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl @@ -0,0 +1,17 @@ +; All encoders/decoders of this specification must follow deterministic cbor encoding rules +; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 + +signed_object_fields = { + "type" => UUID, ; UUID v4 + "id" => UUID, ; UUID v7 + "ver" => UUID, ; UUID v7 + + 1 => -8, ; "alg": EdDSA + 3 => tstr / int, ; "content type" + ? "content encoding" => tstr / int, ; payload content encoding + + * metadata-key => metadata-value +} +metadata-key = int / text +metadata-value = any +UUID = #6.37(bytes) \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/signed_object/index.md b/docs/src/architecture/08_concepts/signed_object/index.md new file mode 100644 index 0000000000..90b628676c --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_object/index.md @@ -0,0 +1,145 @@ +--- +Title: Catalyst Signed Object +Category: Catalyst +Status: Proposed +Authors: + - Steven Johnson + - Alex Pozhylenkov +Implementors: + - Catalyst Fund 14 +Discussions: [] +Created: 2024-12-27 +License: CC-BY-4.0 +--- + + +## 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. +Id addition to the data object content and the signature, metadata is also included +to describe different kind of signed object 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 object 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. + +### Signed Object fields + +To uniquely specify a signed object type, version etc., as it was mentioned before, +a list of different 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 signed object. + +All these fields will be encoded as the [COSE] `protected` header + + +??? note "Catalyst signed object fields: `signed_object_meta.cddl`" + + ```CDDL + {{ include_file('src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl', indent=4) }} + ``` + + +#### `type` + +Each signed object will have a type identifier called `type`. + +The `type` is a [UUID] V4. + +#### `id` + +Every signed object will have a unique ID. +All signed object with the same `id` are considered versions of the same signed object +(read about [`ver`](#ver)). +However, `id` uniqueness is only guaranteed on first use. + +If the same `id` is used, by unauthorized publishers, the signed object is invalid. + +The `id` is a [UUID] V7. + +The first time a signed object is created, it will be assigned by the creator a new `id` which must +be well constructed. + +* The time must be the time the signed object 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 signed objects are signed, the first creation of an `id` assigns that `id` to the creator and any assigned collaborators. +A Signed Object 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 signed object 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 signed object is published will be identical to the [`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. + +#### `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` + +This is an original [COSE] header field, +which indicates the `content type` of the [content](#signed-object-content) ([COSE] `pyaload`) data. + +#### `content encoding` (optional) + +This field is used to indicate the content encodings algorithm of the [content](#signed-object-content) data. + +### Signed Object content + +The signed object content data is encoded (and could be additionaly 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 object [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" +} +``` + +* `kid`: A unique identifier of the signer. + + +## Copyright + +This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +[COSE]: https://datatracker.ietf.org/doc/html/rfc9052 +[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 From 451c004ee7fe4540f28bfacaf4757a6624672085 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 29 Dec 2024 16:01:24 +0200 Subject: [PATCH 02/33] add catalyst signed document section --- .../08_concepts/catalyst_docs/.pages | 1 + .../08_concepts/catalyst_docs/index.md | 214 ++++++++++++++++++ .../catalyst_voting/gen_vote_tx.md | 3 +- .../08_concepts/catalyst_voting/v2.md | 1 + .../08_concepts/signed_object/index.md | 15 +- 5 files changed, 232 insertions(+), 2 deletions(-) create mode 100644 docs/src/architecture/08_concepts/catalyst_docs/.pages create mode 100644 docs/src/architecture/08_concepts/catalyst_docs/index.md 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..6aa2eb82e4 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/.pages @@ -0,0 +1 @@ +title: Catalyst Documents \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_docs/index.md b/docs/src/architecture/08_concepts/catalyst_docs/index.md new file mode 100644 index 0000000000..01a70c28db --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/index.md @@ -0,0 +1,214 @@ +--- +Title: Catalyst Signed Documents +Category: Catalyst +Status: Proposed +Authors: + - Steven Johnson + - Alex Pozhylenkov +Implementors: + - Catalyst Fund 14 +Discussions: [] +Created: 2024-12-29 +License: CC-BY-4.0 +--- + +## Abstract + +Project Catalyst both produces and consumes documents of data (proposals, reviews, comments). +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 + +Catalyst signed document is a [signed object], +so its fully follows the structure of the [signed object] specification. + +* [`content type`](./../signed_object/index.md#content-type): `application/json`. + [Signed object content](./../signed_object/index.md#signed-object-content) must be in [Json] format. + ```CDDL + 3 => 30 + ``` +* [`content encoding`](./../signed_object/index.md#content-encoding-optional): `"br"`. [Signed object content](./../signed_object/index.md#signed-object-content) must be [Brotli] compressed. + ```CDDL + "content encoding" => "br" + ``` + +### 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. + +```CDDL +? "ref" => reference_type, +? "template" => reference_type, +? "reply" => reference_type, +? "section" => text, +? "collabs" => [+any], +``` + +#### Document Reference : `ref` (optional) + +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` (optional) + +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) + +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) + +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) + +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). + +[signed object]: ./../signed_object/index.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 diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index c81cdef59a..97bcb4d384 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -26,7 +26,8 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure Generalized vote transaction is a [signed object], so its fully follows the structure of the [signed object] specification. -* [`content type`](./../signed_object/index.md#content-type): `application/cbor` +* [`content type`](./../signed_object/index.md#content-type): `application/cbor`. + [Signed object content](./../signed_object/index.md#signed-object-content) must be a [CBOR] encoded. ```CDDL 3 => 50 ``` diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 623e0affc5..12194b57a2 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -99,5 +99,6 @@ the following properties are used: +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html [BLAKE2b-512]: https://www.blake2.net/blake2.pdf [ristretto255]: https://ristretto.group diff --git a/docs/src/architecture/08_concepts/signed_object/index.md b/docs/src/architecture/08_concepts/signed_object/index.md index 90b628676c..0c97a32e9d 100644 --- a/docs/src/architecture/08_concepts/signed_object/index.md +++ b/docs/src/architecture/08_concepts/signed_object/index.md @@ -4,7 +4,7 @@ Category: Catalyst Status: Proposed Authors: - Steven Johnson - - Alex Pozhylenkov + - Alex Pozhylenkov Implementors: - Catalyst Fund 14 Discussions: [] @@ -12,6 +12,19 @@ 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) + * [Signed Object fields](#signed-object-fields) + * [`type`](#type) + * [`id`](#id) + * [`ver`](#ver) + * [`alg`](#alg) + * [`content type`](#content-type) + * [`content encoding` (optional)](#content-encoding-optional) + * [Signed Object content](#signed-object-content) + * [COSE signature protected header](#cose-signature-protected-header) +* [Copyright](#copyright) ## Abstract From 3017e51555d15c1771877a1cdb75b9b167791f17 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 29 Dec 2024 16:02:16 +0200 Subject: [PATCH 03/33] add table of contents --- .../08_concepts/catalyst_docs/index.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/index.md b/docs/src/architecture/08_concepts/catalyst_docs/index.md index 01a70c28db..0872c4ba39 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/index.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/index.md @@ -12,6 +12,31 @@ Created: 2024-12-29 License: CC-BY-4.0 --- +* [Abstract](#abstract) +* [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary) +* [Specification](#specification) + * [Document Type Definitions](#document-type-definitions) + * [Document Templates](#document-templates) + * [Document Content Templates](#document-content-templates) + * [Document Metadata](#document-metadata) + * [Document Reference : `ref` (optional)](#document-reference--ref-optional) + * [Template Reference : `template` (optional)](#template-reference--template-optional) + * [Document Reference : `reply` (optional)](#document-reference--reply-optional) + * [Document Reference : `section` (optional)](#document-reference--section-optional) + * [Authorized Collaborators : `collabs` (optional)](#authorized-collaborators--collabs-optional) + * [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 (proposals, reviews, comments). @@ -76,6 +101,7 @@ Document Contents are signed documents, and are typically produced in accordance 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. +It is defined and specified as [signed object protected header fields](./../signed_object/index.md#signed-object-fields). ```CDDL ? "ref" => reference_type, From 0dfc4b62fa839a1b0abecc383ed9f1a67e596a07 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 29 Dec 2024 16:35:12 +0200 Subject: [PATCH 04/33] fix markdown check --- .../08_concepts/catalyst_docs/index.md | 32 +++++++++++-------- .../catalyst_voting/gen_vote_tx.md | 4 +-- .../08_concepts/catalyst_voting/v2.md | 1 - .../08_concepts/signed_object/index.md | 14 ++++---- 4 files changed, 28 insertions(+), 23 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/index.md b/docs/src/architecture/08_concepts/catalyst_docs/index.md index 0872c4ba39..3d51f2c04a 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/index.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/index.md @@ -36,7 +36,6 @@ License: CC-BY-4.0 * [Implementation Plan](#implementation-plan) * [Copyright](#copyright) - ## Abstract Project Catalyst both produces and consumes documents of data (proposals, reviews, comments). @@ -59,10 +58,14 @@ so its fully follows the structure of the [signed object] specification. * [`content type`](./../signed_object/index.md#content-type): `application/json`. [Signed object content](./../signed_object/index.md#signed-object-content) must be in [Json] format. + ```CDDL 3 => 30 ``` -* [`content encoding`](./../signed_object/index.md#content-encoding-optional): `"br"`. [Signed object content](./../signed_object/index.md#signed-object-content) must be [Brotli] compressed. + +* [`content encoding`](./../signed_object/index.md#content-encoding-optional): `"br"`. + [Signed object content](./../signed_object/index.md#signed-object-content) must be [Brotli] compressed. + ```CDDL "content encoding" => "br" ``` @@ -114,20 +117,20 @@ It is defined and specified as [signed object protected header fields](./../sign #### Document Reference : `ref` (optional) This is a reference to another document. -The purpose of the `ref` will vary depending on the document [`type`](#document-type--type). +The purpose of the `ref` will vary depending on the document [`type`](./../signed_object/index.md#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 single [UUID], it is a reference to the document of that [`id`](./../signed_object/index.md#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). +* `` = the [UUID] of the referenced documents [`id`](./../signed_object/index.md#id) +* `` = the [UUID] of the referenced documents [`ver`](./../signed_object/index.md#ver). #### Template Reference : `template` (optional) 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). +The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref-optional). 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. @@ -137,7 +140,7 @@ Template references must explicitly reference both the Template Document ID, and #### Document Reference : `reply` (optional) This is a reply to another document. -The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref). +The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref-optional). `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`. @@ -191,16 +194,17 @@ 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) +Because comments are informed by a particular proposals version, they *MUST* contain a [`ref`](#document-reference--ref-optional) -They may *OPTIONALLY* also contain a [`reply`](#document-reference--reply) metadata field, which is a reference to another comment, +They may *OPTIONALLY* also contain a [`reply`](#document-reference--reply-optional) 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 only [`reply`](#document-reference--reply-optional) to a single other comment document. +The referenced `comment` must be for the same proposal [`id`](./../signed_object/index.md#id), +but can be for a different proposal [`ver`](./../signed_object/index.md#ver). -Comments may *OPTIONALLY* also contain a [`subsection`](#document-reference--section) field, +Comments may *OPTIONALLY* also contain a [`section`](#document-reference--section-optional) field, when the comment only applies to a specific section to the document being commented upon, and not the entire document. diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index 97bcb4d384..2081be5923 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -28,9 +28,11 @@ so its fully follows the structure of the [signed object] specification. * [`content type`](./../signed_object/index.md#content-type): `application/cbor`. [Signed object content](./../signed_object/index.md#signed-object-content) must be a [CBOR] encoded. + ```CDDL 3 => 50 ``` + * [`content encoding`](./../signed_object/index.md#content-encoding-optional): is missing ### Content format @@ -69,6 +71,4 @@ Vote: [signed object]: ./../signed_object/index.md -[BLAKE2b-256]: https://www.blake2.net/blake2.pdf -[COSE]: https://datatracker.ietf.org/doc/rfc9052/ [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 12194b57a2..623e0affc5 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -99,6 +99,5 @@ the following properties are used: -[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html [BLAKE2b-512]: https://www.blake2.net/blake2.pdf [ristretto255]: https://ristretto.group diff --git a/docs/src/architecture/08_concepts/signed_object/index.md b/docs/src/architecture/08_concepts/signed_object/index.md index 0c97a32e9d..b537d083e8 100644 --- a/docs/src/architecture/08_concepts/signed_object/index.md +++ b/docs/src/architecture/08_concepts/signed_object/index.md @@ -102,7 +102,7 @@ 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 signed object is published will be identical to the [`id`](#id). -Subsequent versions will retain the same [`id`](#document-id--id) and will create a new `ver`, +Subsequent versions will retain the same [`id`](#id) and will create a new `ver`, following best practice for creating a new [UUID] v7. #### `alg` @@ -110,9 +110,11 @@ following best practice for creating a new [UUID] v7. 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. @@ -127,7 +129,8 @@ This field is used to indicate the content encodings algorithm of the [content]( ### Signed Object content -The signed object content data is encoded (and could be additionaly compressed, read [`content encoding`](#content-encoding-optional)) as [COSE] `payload`. +The signed object content data is encoded (and could be additionaly compressed, +read [`content encoding`](#content-encoding-optional)) as [COSE] `payload`. ### [COSE] signature protected header @@ -136,7 +139,8 @@ which allows to provide multi-signature functionality. In that regard, each Catalyst signed object [COSE] signature **must** include the following `protected` header field: -```cddl + +```CDDL ; All encoders/decoders of this specification must follow deterministic cbor encoding rules ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 @@ -144,15 +148,13 @@ signature_protected_header = { 4 => bytes ; "kid" } ``` + * `kid`: A unique identifier of the signer. - ## Copyright This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). [COSE]: https://datatracker.ietf.org/doc/html/rfc9052 -[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 From 0c4717f6c909bbd766f4f57757ffd858838e8f2d Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 29 Dec 2024 16:40:48 +0200 Subject: [PATCH 05/33] fix spelling --- .../08_concepts/signed_object/cddl/signed_object_meta.cddl | 4 ++-- docs/src/architecture/08_concepts/signed_object/index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl b/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl index 1aa7d74963..c3ecfd50ce 100644 --- a/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl +++ b/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl @@ -7,8 +7,8 @@ signed_object_fields = { "ver" => UUID, ; UUID v7 1 => -8, ; "alg": EdDSA - 3 => tstr / int, ; "content type" - ? "content encoding" => tstr / int, ; payload content encoding + 3 => text / int, ; "content type" + ? "content encoding" => text / int, ; payload content encoding * metadata-key => metadata-value } diff --git a/docs/src/architecture/08_concepts/signed_object/index.md b/docs/src/architecture/08_concepts/signed_object/index.md index b537d083e8..72e471451a 100644 --- a/docs/src/architecture/08_concepts/signed_object/index.md +++ b/docs/src/architecture/08_concepts/signed_object/index.md @@ -121,7 +121,7 @@ Only `ed25119` considered at this moment as the only option to be supported for #### `content type` This is an original [COSE] header field, -which indicates the `content type` of the [content](#signed-object-content) ([COSE] `pyaload`) data. +which indicates the `content type` of the [content](#signed-object-content) ([COSE] `payload`) data. #### `content encoding` (optional) @@ -129,7 +129,7 @@ This field is used to indicate the content encodings algorithm of the [content]( ### Signed Object content -The signed object content data is encoded (and could be additionaly compressed, +The signed object content data is encoded (and could be additionally compressed, read [`content encoding`](#content-encoding-optional)) as [COSE] `payload`. ### [COSE] signature protected header From 144612f590c18f151457e131939bc2db60992338 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 29 Dec 2024 16:42:11 +0200 Subject: [PATCH 06/33] fix earthfile --- .../src/architecture/08_concepts/catalyst_voting/cddl/Earthfile | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile index 0fe8c1b435..db149db0e2 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 From 2acf8414dbf2de24415437ede02a039ad9491875 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Fri, 3 Jan 2025 15:10:48 +0200 Subject: [PATCH 07/33] rename catalyst signed object --- .../08_concepts/catalyst_docs/index.md | 28 +++++++++---------- .../catalyst_voting/gen_vote_tx.md | 14 +++++----- .../08_concepts/catalyst_voting/v2.md | 6 ++-- .../08_concepts/signed_doc/.pages | 3 ++ .../cddl/signed_doc_meta.cddl} | 4 ++- .../{signed_object => signed_doc}/index.md | 18 ++++++------ .../08_concepts/signed_object/.pages | 1 - 7 files changed, 39 insertions(+), 35 deletions(-) create mode 100644 docs/src/architecture/08_concepts/signed_doc/.pages rename docs/src/architecture/08_concepts/{signed_object/cddl/signed_object_meta.cddl => signed_doc/cddl/signed_doc_meta.cddl} (94%) rename docs/src/architecture/08_concepts/{signed_object => signed_doc}/index.md (90%) delete mode 100644 docs/src/architecture/08_concepts/signed_object/.pages diff --git a/docs/src/architecture/08_concepts/catalyst_docs/index.md b/docs/src/architecture/08_concepts/catalyst_docs/index.md index 3d51f2c04a..fb7d5f0985 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/index.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/index.md @@ -53,18 +53,18 @@ is just the metadata that structure will carry for different kinds of documents. ## Specification -Catalyst signed document is a [signed object], -so its fully follows the structure of the [signed object] specification. +Catalyst signed document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. -* [`content type`](./../signed_object/index.md#content-type): `application/json`. - [Signed object content](./../signed_object/index.md#signed-object-content) must be in [Json] format. +* [`content type`](./../signed_doc/index.md#content-type): `application/json`. + [Catalyst Signed Document content](./../signed_doc/index.md#signed-object-content) must be in [Json] format. ```CDDL 3 => 30 ``` -* [`content encoding`](./../signed_object/index.md#content-encoding-optional): `"br"`. - [Signed object content](./../signed_object/index.md#signed-object-content) must be [Brotli] compressed. +* [`content encoding`](./../signed_doc/index.md#content-encoding-optional): `"br"`. + [Catalyst Signed Document content](./../signed_doc/index.md#signed-object-content) must be [Brotli] compressed. ```CDDL "content encoding" => "br" @@ -104,7 +104,7 @@ Document Contents are signed documents, and are typically produced in accordance 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. -It is defined and specified as [signed object protected header fields](./../signed_object/index.md#signed-object-fields). +It is defined and specified as [Catalyst Signed Document protected header fields](./../signed_doc/index.md#signed-object-fields). ```CDDL ? "ref" => reference_type, @@ -117,15 +117,15 @@ It is defined and specified as [signed object protected header fields](./../sign #### Document Reference : `ref` (optional) This is a reference to another document. -The purpose of the `ref` will vary depending on the document [`type`](./../signed_object/index.md#type). +The purpose of the `ref` will vary depending on the document [`type`](./../signed_doc/index.md#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`](./../signed_object/index.md#id). +If the `ref` is a single [UUID], it is a reference to the document of that [`id`](./../signed_doc/index.md#id). If the `ref` is a [CBOR] array, it has the form `[,]` where: -* `` = the [UUID] of the referenced documents [`id`](./../signed_object/index.md#id) -* `` = the [UUID] of the referenced documents [`ver`](./../signed_object/index.md#ver). +* `` = the [UUID] of the referenced documents [`id`](./../signed_doc/index.md#id) +* `` = the [UUID] of the referenced documents [`ver`](./../signed_doc/index.md#ver). #### Template Reference : `template` (optional) @@ -201,8 +201,8 @@ which is a reference to another comment, where the comment is in reply to the referenced comment. Comments may only [`reply`](#document-reference--reply-optional) to a single other comment document. -The referenced `comment` must be for the same proposal [`id`](./../signed_object/index.md#id), -but can be for a different proposal [`ver`](./../signed_object/index.md#ver). +The referenced `comment` must be for the same proposal [`id`](./../signed_doc/index.md#id), +but can be for a different proposal [`ver`](./../signed_doc/index.md#ver). Comments may *OPTIONALLY* also contain a [`section`](#document-reference--section-optional) field, when the comment only applies to a specific section to the document being commented upon, @@ -235,7 +235,7 @@ Fund 14 project catalyst will deploy this scheme for Key derivation.> This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). -[signed object]: ./../signed_object/index.md +[Catalyst Signed Document]: ./../signed_doc/index.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 diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index 2081be5923..5122b71c66 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -23,21 +23,21 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure ## Specification -Generalized vote transaction is a [signed object], -so its fully follows the structure of the [signed object] specification. +Generalized vote transaction is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. -* [`content type`](./../signed_object/index.md#content-type): `application/cbor`. - [Signed object content](./../signed_object/index.md#signed-object-content) must be a [CBOR] encoded. +* [`content type`](./../signed_doc/index.md#content-type): `application/cbor`. + [Catalyst Signed Document content](./../signed_doc/index.md#signed-object-content) must be a [CBOR] encoded. ```CDDL 3 => 50 ``` -* [`content encoding`](./../signed_object/index.md#content-encoding-optional): is missing +* [`content encoding`](./../signed_doc/index.md#content-encoding-optional): is missing ### Content format -The generalized vote transaction [content format](./../signed_object/index.md#signed-object-content) +The generalized vote transaction [content format](./../signed_doc/index.md#signed-object-content) ??? note "vote transaction definition: `gen_vote_tx.cddl`" @@ -70,5 +70,5 @@ Vote: -[signed object]: ./../signed_object/index.md +[Catalyst Signed Document]: ./../signed_doc/index.md [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 623e0affc5..402cb7ef1e 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -26,7 +26,7 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec need to define a `choice`, `proof` and `prop-id`. -Also additional [signed object protected header fields](./../signed_object/index.md#signed-object-fields) are defined, +Also additional [Catalyst Signed Document protected header fields](./../signed_doc/index.md#catalyst-signed-document-fields) are defined, ```CDDL "brand_id" => UUID, ; UUID v4 @@ -54,7 +54,7 @@ Also additional [signed object protected header fields](./../signed_object/index ``` -For the public vote [`type`](./../signed_object/index.md#type) value defined as follows: +For the public vote [`type`](./../signed_doc/index.md#type) value defined as follows: ```CDDL vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803 @@ -70,7 +70,7 @@ vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742 ``` -For the private vote [`type`](./../signed_object/index.md#type) value defined as follows: +For the private vote [`type`](./../signed_doc/index.md#type) value defined as follows: ```CDDL vote-type = #6.37(h'E78EE18DF38044C1A85280AA6ECB07FE') ; e78ee18d-f380-44c1-a852-80aa6ecb07fe 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..5343b80fd2 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/.pages @@ -0,0 +1,3 @@ +title: Catalyst Signed Document +arrange: +- index.md diff --git a/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl similarity index 94% rename from docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl rename to docs/src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl index c3ecfd50ce..57ce2056ed 100644 --- a/docs/src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl @@ -1,7 +1,7 @@ ; All encoders/decoders of this specification must follow deterministic cbor encoding rules ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 -signed_object_fields = { +signed_doc_meta = { "type" => UUID, ; UUID v4 "id" => UUID, ; UUID v7 "ver" => UUID, ; UUID v7 @@ -12,6 +12,8 @@ signed_object_fields = { * metadata-key => metadata-value } + metadata-key = int / text metadata-value = any + UUID = #6.37(bytes) \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/signed_object/index.md b/docs/src/architecture/08_concepts/signed_doc/index.md similarity index 90% rename from docs/src/architecture/08_concepts/signed_object/index.md rename to docs/src/architecture/08_concepts/signed_doc/index.md index 72e471451a..7444faea9f 100644 --- a/docs/src/architecture/08_concepts/signed_object/index.md +++ b/docs/src/architecture/08_concepts/signed_doc/index.md @@ -1,5 +1,5 @@ --- -Title: Catalyst Signed Object +Title: Catalyst Signed Document Category: Catalyst Status: Proposed Authors: @@ -15,14 +15,14 @@ License: CC-BY-4.0 * [Abstract](#abstract) * [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary) * [Specification](#specification) - * [Signed Object fields](#signed-object-fields) + * [Catalyst Signed Document fields](#catalyst-signed-document-fields) * [`type`](#type) * [`id`](#id) * [`ver`](#ver) * [`alg`](#alg) * [`content type`](#content-type) * [`content encoding` (optional)](#content-encoding-optional) - * [Signed Object content](#signed-object-content) + * [Catalyst Signed Document content](#catalyst-signed-document-content) * [COSE signature protected header](#cose-signature-protected-header) * [Copyright](#copyright) @@ -44,20 +44,20 @@ data object, and the purpose of it. Catalyst signed object 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. -### Signed Object fields +### Catalyst Signed Document fields -To uniquely specify a signed object type, version etc., as it was mentioned before, +To uniquely specify a Catalyst Signed Document type, version etc., as it was mentioned before, a list of different 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 signed object. +it is allowed to add any number of additional metadata fields, which could be specified for each `type` of document. All these fields will be encoded as the [COSE] `protected` header -??? note "Catalyst signed object fields: `signed_object_meta.cddl`" +??? note "Catalyst Signed Document fields: `signed_doc_meta.cddl`" ```CDDL - {{ include_file('src/architecture/08_concepts/signed_object/cddl/signed_object_meta.cddl', indent=4) }} + {{ include_file('src/architecture/08_concepts/signed_doc/cddl/signed_doc_meta.cddl', indent=4) }} ``` @@ -127,7 +127,7 @@ which indicates the `content type` of the [content](#signed-object-content) ([CO This field is used to indicate the content encodings algorithm of the [content](#signed-object-content) data. -### Signed Object content +### Catalyst Signed Document content The signed object content data is encoded (and could be additionally compressed, read [`content encoding`](#content-encoding-optional)) as [COSE] `payload`. diff --git a/docs/src/architecture/08_concepts/signed_object/.pages b/docs/src/architecture/08_concepts/signed_object/.pages deleted file mode 100644 index a6e0c31069..0000000000 --- a/docs/src/architecture/08_concepts/signed_object/.pages +++ /dev/null @@ -1 +0,0 @@ -title: Catalyst Signed Object From c8dca62e34ad4bbbc08786849bd61ca66a7b09b3 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Fri, 3 Jan 2025 15:12:22 +0200 Subject: [PATCH 08/33] update kid def --- docs/src/architecture/08_concepts/signed_doc/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_doc/index.md b/docs/src/architecture/08_concepts/signed_doc/index.md index 7444faea9f..2e05e5ca3e 100644 --- a/docs/src/architecture/08_concepts/signed_doc/index.md +++ b/docs/src/architecture/08_concepts/signed_doc/index.md @@ -145,16 +145,18 @@ each Catalyst signed object [COSE] signature **must** include the following `pro ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 signature_protected_header = { - 4 => bytes ; "kid" + 4 => bytes ; "kid", UTF-8 encoded URI string } ``` -* `kid`: A unique identifier of the signer. +* `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). +[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 From d1a44280d665f8154818c4148debda2d6808da60 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Fri, 3 Jan 2025 15:27:50 +0200 Subject: [PATCH 09/33] update content encoding --- .../08_concepts/catalyst_docs/index.md | 7 --- .../signed_doc/cddl/signed_doc_meta.cddl | 2 +- .../08_concepts/signed_doc/index.md | 54 +++++++++++-------- 3 files changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/index.md b/docs/src/architecture/08_concepts/catalyst_docs/index.md index fb7d5f0985..d983eff6ae 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/index.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/index.md @@ -63,13 +63,6 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati 3 => 30 ``` -* [`content encoding`](./../signed_doc/index.md#content-encoding-optional): `"br"`. - [Catalyst Signed Document content](./../signed_doc/index.md#signed-object-content) must be [Brotli] compressed. - - ```CDDL - "content encoding" => "br" - ``` - ### Document Type Definitions #### Document Templates 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 index 57ce2056ed..06479d9a27 100644 --- 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 @@ -8,7 +8,7 @@ signed_doc_meta = { 1 => -8, ; "alg": EdDSA 3 => text / int, ; "content type" - ? "content encoding" => text / int, ; payload content encoding + ? "Content-Encoding" / "content-encoding" => "br", ; payload content encoding * metadata-key => metadata-value } diff --git a/docs/src/architecture/08_concepts/signed_doc/index.md b/docs/src/architecture/08_concepts/signed_doc/index.md index 2e05e5ca3e..1b4da920af 100644 --- a/docs/src/architecture/08_concepts/signed_doc/index.md +++ b/docs/src/architecture/08_concepts/signed_doc/index.md @@ -15,7 +15,7 @@ License: CC-BY-4.0 * [Abstract](#abstract) * [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary) * [Specification](#specification) - * [Catalyst Signed Document fields](#catalyst-signed-document-fields) + * [Catalyst Signed Document metadata fields](#catalyst-signed-document-metadata-fields) * [`type`](#type) * [`id`](#id) * [`ver`](#ver) @@ -32,7 +32,7 @@ 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. Id addition to the data object content and the signature, metadata is also included -to describe different kind of signed object properties. +to describe different kind of Catalyst Signed Document properties. ## Motivation: why is this CIP necessary? @@ -41,20 +41,20 @@ data object, and the purpose of it. ## Specification -Catalyst signed object is [COSE] based structure, particularly `COSE Signed Data Object` [COSE] type. +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 fields +### Catalyst Signed Document metadata fields To uniquely specify a Catalyst Signed Document type, version etc., as it was mentioned before, -a list of different fields is specified. +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. All these fields will be encoded as the [COSE] `protected` header -??? note "Catalyst Signed Document fields: `signed_doc_meta.cddl`" +??? 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) }} @@ -63,31 +63,31 @@ All these fields will be encoded as the [COSE] `protected` header #### `type` -Each signed object will have a type identifier called `type`. +Each Catalyst Signed Document will have a type identifier called `type`. The `type` is a [UUID] V4. #### `id` -Every signed object will have a unique ID. -All signed object with the same `id` are considered versions of the same signed object +Every Catalyst Signed Document will have a unique ID. +All Catalyst Signed Document with the same `id` are considered 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 signed object is invalid. +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 signed object is created, it will be assigned by the creator a new `id` which must +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 signed object was first created. +* 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 signed objects are signed, the first creation of an `id` assigns that `id` to the creator and any assigned collaborators. -A Signed Object that is not signed by the creator, or an assigned collaborator, is invalid. +*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. @@ -96,12 +96,12 @@ including all otherwise legitimate publications by the same author being marked #### `ver` -Every signed object in the system will be versioned. +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 signed object is published will be identical to the [`id`](#id). +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. @@ -118,26 +118,30 @@ which indicates the cryptography algorithm used for the security processing. Only `ed25119` considered at this moment as the only option to be supported for signed objects. -#### `content type` +#### [`content type`] This is an original [COSE] header field, -which indicates the `content type` of the [content](#signed-object-content) ([COSE] `payload`) data. +which indicates the [`content type`] of the [content](#catalyst-signed-document-content) ([COSE] `payload`) data. -#### `content encoding` (optional) +#### [`content encoding`] (optional) -This field is used to indicate the content encodings algorithm of the [content](#signed-object-content) data. +This field is used to indicate the [`content encoding`] algorithm of the [content](#catalyst-signed-document-content) data. + +Supported encodings: + +* `br` - [Brotli] compressed data. ### Catalyst Signed Document content -The signed object content data is encoded (and could be additionally compressed, +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, +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 object [COSE] signature **must** include the following `protected` header field: +each Catalyst Signed Document [COSE] signature **must** include the following `protected` header field: ```CDDL @@ -156,6 +160,10 @@ signature_protected_header = { This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +[`content type`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type +[`content encoding`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding +[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 From 45bedde112ef82003d20adada25a4b4f9d2ad1a8 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Fri, 3 Jan 2025 15:35:39 +0200 Subject: [PATCH 10/33] wip --- docs/src/architecture/08_concepts/signed_doc/.pages | 4 ++-- .../src/architecture/08_concepts/signed_doc/index.md | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_doc/.pages b/docs/src/architecture/08_concepts/signed_doc/.pages index 5343b80fd2..50c5718fbc 100644 --- a/docs/src/architecture/08_concepts/signed_doc/.pages +++ b/docs/src/architecture/08_concepts/signed_doc/.pages @@ -1,3 +1,3 @@ title: Catalyst Signed Document -arrange: -- index.md +nav: +- Catalyst Signed Document Specification: index.md diff --git a/docs/src/architecture/08_concepts/signed_doc/index.md b/docs/src/architecture/08_concepts/signed_doc/index.md index 1b4da920af..102758a981 100644 --- a/docs/src/architecture/08_concepts/signed_doc/index.md +++ b/docs/src/architecture/08_concepts/signed_doc/index.md @@ -118,14 +118,16 @@ which indicates the cryptography algorithm used for the security processing. Only `ed25119` considered at this moment as the only option to be supported for signed objects. -#### [`content type`] +#### [`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`] of the [content](#catalyst-signed-document-content) ([COSE] `payload`) data. +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`] (optional) +#### [`content encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) (optional) -This field is used to indicate the [`content encoding`] algorithm of the [content](#catalyst-signed-document-content) data. +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: @@ -161,8 +163,6 @@ signature_protected_header = { This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). -[`content type`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type -[`content encoding`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding [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 From 4c7f92b0921419f6e04c0f7bce1d0fc92bc5f477 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Fri, 3 Jan 2025 15:46:54 +0200 Subject: [PATCH 11/33] wip --- .../08_concepts/catalyst_docs/index.md | 20 +++++++++---------- .../catalyst_voting/gen_vote_tx.md | 10 +++++----- .../08_concepts/catalyst_voting/v2.md | 6 +++--- .../08_concepts/signed_doc/.pages | 3 ++- .../08_concepts/signed_doc/meta.md | 1 + .../signed_doc/{index.md => spec.md} | 0 6 files changed, 21 insertions(+), 19 deletions(-) create mode 100644 docs/src/architecture/08_concepts/signed_doc/meta.md rename docs/src/architecture/08_concepts/signed_doc/{index.md => spec.md} (100%) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/index.md b/docs/src/architecture/08_concepts/catalyst_docs/index.md index d983eff6ae..c4cbe0d2eb 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/index.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/index.md @@ -56,8 +56,8 @@ is just the metadata that structure will carry for different kinds of documents. Catalyst signed document is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. -* [`content type`](./../signed_doc/index.md#content-type): `application/json`. - [Catalyst Signed Document content](./../signed_doc/index.md#signed-object-content) must be in [Json] format. +* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. + [Catalyst Signed Document content](./../signed_doc/spec.md#signed-object-content) must be in [Json] format. ```CDDL 3 => 30 @@ -97,7 +97,7 @@ Document Contents are signed documents, and are typically produced in accordance 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. -It is defined and specified as [Catalyst Signed Document protected header fields](./../signed_doc/index.md#signed-object-fields). +It is defined and specified as [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). ```CDDL ? "ref" => reference_type, @@ -110,15 +110,15 @@ It is defined and specified as [Catalyst Signed Document protected header fields #### Document Reference : `ref` (optional) This is a reference to another document. -The purpose of the `ref` will vary depending on the document [`type`](./../signed_doc/index.md#type). +The purpose of the `ref` will vary depending on the document [`type`](./../signed_doc/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], it is a reference to the document of that [`id`](./../signed_doc/index.md#id). +If the `ref` is a single [UUID], it is a reference to the document of that [`id`](./../signed_doc/spec.md#id). If the `ref` is a [CBOR] array, it has the form `[,]` where: -* `` = the [UUID] of the referenced documents [`id`](./../signed_doc/index.md#id) -* `` = the [UUID] of the referenced documents [`ver`](./../signed_doc/index.md#ver). +* `` = the [UUID] of the referenced documents [`id`](./../signed_doc/spec.md#id) +* `` = the [UUID] of the referenced documents [`ver`](./../signed_doc/spec.md#ver). #### Template Reference : `template` (optional) @@ -194,8 +194,8 @@ which is a reference to another comment, where the comment is in reply to the referenced comment. Comments may only [`reply`](#document-reference--reply-optional) to a single other comment document. -The referenced `comment` must be for the same proposal [`id`](./../signed_doc/index.md#id), -but can be for a different proposal [`ver`](./../signed_doc/index.md#ver). +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). Comments may *OPTIONALLY* also contain a [`section`](#document-reference--section-optional) field, when the comment only applies to a specific section to the document being commented upon, @@ -228,7 +228,7 @@ Fund 14 project catalyst will deploy this scheme for Key derivation.> This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). -[Catalyst Signed Document]: ./../signed_doc/index.md +[Catalyst Signed Document]: ./../signed_doc/spec.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 diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index 5122b71c66..52baf9f645 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -26,18 +26,18 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure Generalized vote transaction is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. -* [`content type`](./../signed_doc/index.md#content-type): `application/cbor`. - [Catalyst Signed Document content](./../signed_doc/index.md#signed-object-content) must be a [CBOR] encoded. +* [`content type`](./../signed_doc/spec.md#content-type): `application/cbor`. + [Catalyst Signed Document content](./../signed_doc/spec.md#signed-object-content) must be a [CBOR] encoded. ```CDDL 3 => 50 ``` -* [`content encoding`](./../signed_doc/index.md#content-encoding-optional): is missing +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): is missing ### Content format -The generalized vote transaction [content format](./../signed_doc/index.md#signed-object-content) +The generalized vote transaction [content format](./../signed_doc/spec.md#signed-object-content) ??? note "vote transaction definition: `gen_vote_tx.cddl`" @@ -70,5 +70,5 @@ Vote: -[Catalyst Signed Document]: ./../signed_doc/index.md +[Catalyst Signed Document]: ./../signed_doc/spec.md [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 402cb7ef1e..dd0ea1f4a6 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -26,7 +26,7 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec need to define a `choice`, `proof` and `prop-id`. -Also additional [Catalyst Signed Document protected header fields](./../signed_doc/index.md#catalyst-signed-document-fields) are defined, +Also additional [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#catalyst-signed-document-fields) are defined, ```CDDL "brand_id" => UUID, ; UUID v4 @@ -54,7 +54,7 @@ Also additional [Catalyst Signed Document protected header fields](./../signed_d ``` -For the public vote [`type`](./../signed_doc/index.md#type) value defined as follows: +For the public vote [`type`](./../signed_doc/spec.md#type) value defined as follows: ```CDDL vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803 @@ -70,7 +70,7 @@ vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742 ``` -For the private vote [`type`](./../signed_doc/index.md#type) value defined as follows: +For the private vote [`type`](./../signed_doc/spec.md#type) value defined as follows: ```CDDL vote-type = #6.37(h'E78EE18DF38044C1A85280AA6ECB07FE') ; e78ee18d-f380-44c1-a852-80aa6ecb07fe diff --git a/docs/src/architecture/08_concepts/signed_doc/.pages b/docs/src/architecture/08_concepts/signed_doc/.pages index 50c5718fbc..6bc6e3f0b4 100644 --- a/docs/src/architecture/08_concepts/signed_doc/.pages +++ b/docs/src/architecture/08_concepts/signed_doc/.pages @@ -1,3 +1,4 @@ title: Catalyst Signed Document nav: -- Catalyst Signed Document Specification: index.md +- Specification: spec.md +- Metadata Fields List: meta.md 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..cbf11fc474 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -0,0 +1 @@ +Something \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/signed_doc/index.md b/docs/src/architecture/08_concepts/signed_doc/spec.md similarity index 100% rename from docs/src/architecture/08_concepts/signed_doc/index.md rename to docs/src/architecture/08_concepts/signed_doc/spec.md From b247fe7d3f8fdbd9e6274e76a1975df183bfaae2 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Fri, 3 Jan 2025 17:18:33 +0200 Subject: [PATCH 12/33] add meta.md doc --- .../signed_doc/cddl/additional_meta.cddl | 11 ++++ .../signed_doc/cddl/signed_doc_meta.cddl | 6 +- .../08_concepts/signed_doc/meta.md | 66 ++++++++++++++++++- .../08_concepts/signed_doc/spec.md | 2 + 4 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 docs/src/architecture/08_concepts/signed_doc/cddl/additional_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..703255ca8a --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl @@ -0,0 +1,11 @@ +additional_fields = { + ? "ref" => reference_type, + ? "template" => reference_type, + ? "reply" => reference_type, + ? "section" => text, + ? "collabs" => [+any], +} + +reference_type = UUID / [UUID, UUID] + +UUID = #6.37(bytes) 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 index 06479d9a27..b122c69510 100644 --- 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 @@ -10,10 +10,14 @@ signed_doc_meta = { 3 => text / int, ; "content type" ? "Content-Encoding" / "content-encoding" => "br", ; payload content encoding + ~meta.additional_fields, + * metadata-key => metadata-value } metadata-key = int / text metadata-value = any -UUID = #6.37(bytes) \ No newline at end of file +UUID = #6.37(bytes) + +;# include additional_meta as meta \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index cbf11fc474..ab29e086a9 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -1 +1,65 @@ -Something \ No newline at end of file + + +??? note "Additional Metadata fields: `additional_meta.cddl`" + + ```CDDL + {{ include_file('src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl', indent=4) }} + ``` + + +## `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], 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] of the referenced documents [`id`](./spec.md#id) +* `` = the [UUID] of the referenced documents [`ver`](./spec.md#ver). + +## `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`. \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md index 102758a981..84b3b07d9a 100644 --- a/docs/src/architecture/08_concepts/signed_doc/spec.md +++ b/docs/src/architecture/08_concepts/signed_doc/spec.md @@ -48,8 +48,10 @@ It fully inherits an original [COSE] design and specifies the details of differe To uniquely specify a Catalyst Signed Document type, version etc., as it was mentioned before, 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 defined [here](./meta.md). All these fields will be encoded as the [COSE] `protected` header From aa2e48f4148fbcac4af7d2accbab866d605df22e Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 14:11:08 +0200 Subject: [PATCH 13/33] add ref hash defintion --- .../cddl/genesis_to_prev_hash.cddl | 7 +++--- .../signed_doc/cddl/additional_meta.cddl | 12 ++++++---- .../08_concepts/signed_doc/cddl/hash.cddl | 8 +++++++ .../08_concepts/signed_doc/meta.md | 23 ++++++++++++++++--- 4 files changed, 40 insertions(+), 10 deletions(-) create mode 100644 docs/src/architecture/08_concepts/signed_doc/cddl/hash.cddl 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 index 740d0234e5..7d0d525063 100644 --- 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 @@ -2,14 +2,15 @@ ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06 genesis-to-prev-hash = [ - chain-id: UUID, ; UUID v7 + chain-id: ULID, timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time - ledger-type: UUID, ; UUID v4 - purpose-id: UUID, ; UUID v7 + ledger-type: UUID, + purpose-id: ULID / UUID, validator, ] UUID = #6.37(bytes) ; UUID type +ULID = #6.32780(bytes) ; ULID type validator = (kid / [2* kid]) kid = hash-bytes ; hash of the x509/c509 certificate 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 index 703255ca8a..a6cad9c181 100644 --- a/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl @@ -1,11 +1,15 @@ additional_fields = { - ? "ref" => reference_type, - ? "template" => reference_type, - ? "reply" => reference_type, + ? "ref" => ref_type, + ? "rev-hash" => ref_hash_type, + ? "template" => ref_type, + ? "reply" => ref_type, ? "section" => text, ? "collabs" => [+any], } -reference_type = UUID / [UUID, UUID] +ref_type = UUID / [UUID, UUID] +ref_hash_type = [ref_type, hash-bytes] UUID = #6.37(bytes) + +;# include hash diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/hash.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/hash.cddl new file mode 100644 index 0000000000..18c0d6e4a1 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/hash.cddl @@ -0,0 +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 + +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/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index ab29e086a9..6f021a5d70 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -7,6 +7,13 @@ ``` +* [`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) + ## `ref` Document Reference This is a reference to another document. @@ -17,8 +24,17 @@ 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`](./spec.md#id). If the `ref` is a [CBOR] array, it has the form `[,]` where: -* `` = the [UUID] of the referenced documents [`id`](./spec.md#id) -* `` = the [UUID] of the referenced documents [`ver`](./spec.md#ver). +* `` - the [UUID] of the referenced documents [`id`](./spec.md#id). +* `` - the [UUID] 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 @@ -62,4 +78,5 @@ However, they will contain enough information such that each collaborator can be 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`. \ No newline at end of file +This list can impact actions that can be performed by the `Proposal Action Document`. + From 98f82db470cdf8de2696a4774789cb5487950f57 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 14:22:48 +0200 Subject: [PATCH 14/33] Add a table of available document types --- .../08_concepts/signed_doc/.pages | 1 + .../08_concepts/signed_doc/spec.md | 5 +++- .../08_concepts/signed_doc/types.md | 23 +++++++++++++++++++ 3 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 docs/src/architecture/08_concepts/signed_doc/types.md diff --git a/docs/src/architecture/08_concepts/signed_doc/.pages b/docs/src/architecture/08_concepts/signed_doc/.pages index 6bc6e3f0b4..db7a381818 100644 --- a/docs/src/architecture/08_concepts/signed_doc/.pages +++ b/docs/src/architecture/08_concepts/signed_doc/.pages @@ -2,3 +2,4 @@ title: Catalyst Signed Document nav: - Specification: spec.md - Metadata Fields List: meta.md +- Document Types: types.md diff --git a/docs/src/architecture/08_concepts/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md index 84b3b07d9a..258f1eb7e9 100644 --- a/docs/src/architecture/08_concepts/signed_doc/spec.md +++ b/docs/src/architecture/08_concepts/signed_doc/spec.md @@ -51,7 +51,8 @@ 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 defined [here](./meta.md). + +[A full list of considered additional metadata fields](./meta.md). All these fields will be encoded as the [COSE] `protected` header @@ -69,6 +70,8 @@ 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] + #### `id` Every Catalyst Signed Document will have a unique ID. 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..7d5e94aec5 --- /dev/null +++ b/docs/src/architecture/08_concepts/signed_doc/types.md @@ -0,0 +1,23 @@ + +| [UUID] | [CBOR] | Type Description | Payload Type | +| ------------------------------------ | ----------------------------------------- | ---------------------------- | --------------------------------- | +| 7808d2ba-d511-40af-84e8-c0d1625fdfdc | `37(h'7808d2bad51140af84e8c0d1625fdfdc')` | Proposal Document | [Brotli] Compressed [JSON] | +| 0ce8ab38-9258-4fbc-a62e-7faa6e58318f | `37(h'0ce8ab3892584fbca62e7faa6e58318f')` | Proposal Template | [Brotli] Compressed [JSON Schema] | +| b679ded3-0e7c-41ba-89f8-da62a17898ea | `37(h'b679ded30e7c41ba89f8da62a17898ea')` | Comment Document | [Brotli] Compressed [JSON] | +| 0b8424d4-ebfd-46e3-9577-1775a69d290c | `37(h'0b8424d4ebfd46e395771775a69d290c')` | Comment Template | [Brotli] Compressed [JSON Schema] | +| e4caf5f0-098b-45fd-94f3-0702a4573db5 | `37(h'e4caf5f0098b45fd94f30702a4573db5')` | Review Document | [Brotli] Compressed [JSON] | +| ebe5d0bf-5d86-4577-af4d-008fddbe2edc | `37(h'ebe5d0bf5d864577af4d008fddbe2edc')` | Review Template | [Brotli] Compressed [JSON Schema] | +| 48c20109-362a-4d32-9bba-e0a9cf8b45be | `37(h'48c20109362a4d329bbae0a9cf8b45be')` | Category Parameters Document | [Brotli] Compressed [JSON] | +| 65b1e8b0-51f1-46a5-9970-72cdf26884be | `37(h'65b1e8b051f146a5997072cdf26884be')` | Category Parameters Template | [Brotli] Compressed [JSON Schema] | +| 0110ea96-a555-47ce-8408-36efe6ed6f7c | `37(h'0110ea96a55547ce840836efe6ed6f7c')` | Campaign Parameters Document | [Brotli] Compressed [JSON] | +| 7e8f5fa2-44ce-49c8-bfd5-02af42c179a3 | `37(h'7e8f5fa244ce49c8bfd502af42c179a3')` | Campaign Parameters Template | [Brotli] Compressed [JSON Schema] | +| 3e4808cc-c86e-467b-9702-d60baa9d1fca | `37(h'3e4808ccc86e467b9702d60baa9d1fca')` | Brand Parameters Document | [Brotli] Compressed [JSON] | +| fd3c1735-80b1-4eea-8d63-5f436d97ea31 | `37(h'fd3c173580b14eea8d635f436d97ea31')` | Brand Parameters Template | [Brotli] Compressed [JSON Schema] | +| 5e60e623-ad02-4a1b-a1ac-406db978ee48 | `37(h'5e60e623ad024a1ba1ac406db978ee48')` | Proposal Action Document | *TBD* | + + +[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 \ No newline at end of file From 811c4b41fb3d8be741a65c62c3f5c16ffa56d7a5 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 15:13:56 +0200 Subject: [PATCH 15/33] add proposal.md doc --- .../08_concepts/catalyst_docs/.pages | 4 +- .../08_concepts/catalyst_docs/proposal.md | 89 +++++++++++++++++++ 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/src/architecture/08_concepts/catalyst_docs/proposal.md diff --git a/docs/src/architecture/08_concepts/catalyst_docs/.pages b/docs/src/architecture/08_concepts/catalyst_docs/.pages index 6aa2eb82e4..f03788f51e 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/.pages +++ b/docs/src/architecture/08_concepts/catalyst_docs/.pages @@ -1 +1,3 @@ -title: Catalyst Documents \ No newline at end of file +title: Catalyst Documents +arrage: +- proposal.md \ No newline at end of file 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..8c46b01be8 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -0,0 +1,89 @@ +--- +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 + +Catalysyt Proposal document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +* [`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): `"br"`. + [Catalyst Signed Document content] must be [Brotli] compressed. + +#### Proposal Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) +* [`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') + ``` + +* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) +* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) +* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) + +## Proposal Template + +This document provides the template structure which a Proposal must be formatted to, and validated against. + +### Specification + +Catalysyt Proposal Template document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +* [`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): `"br"`. + [Catalyst Signed Document content] must be [Brotli] compressed. + +#### Proposal Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) +* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) +* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) +* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) + +## 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 \ No newline at end of file From 12215340946a1bec2148da5eab5bb8fd9072ee12 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 15:24:15 +0200 Subject: [PATCH 16/33] add comment document --- .../08_concepts/catalyst_docs/comment.md | 95 +++++++++++++++++++ .../08_concepts/catalyst_docs/proposal.md | 12 +-- 2 files changed, 101 insertions(+), 6 deletions(-) create mode 100644 docs/src/architecture/08_concepts/catalyst_docs/comment.md 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..25c47a5d39 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/comment.md @@ -0,0 +1,95 @@ +--- +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 + +Catalysyt Comment document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +* [`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): `"br"`. + [Catalyst Signed Document content] must be [Brotli] compressed. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`ref`](./../signed_doc/meta.md#ref-document-reference). Refence to a related [Proposal Document]. +* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0b8424d4-ebfd-46e3-9577-1775a69d290c` value, [commemt 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. + +* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional). + +## Comment Template + +This document pr provides the template structure which a Comment must be formatted to, and validated against. + +### Specification + +Catalysyt Comment Template document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +* [`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): `"br"`. + [Catalyst Signed Document content] must be [Brotli] compressed. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) +* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) +* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) +* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) + +## 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 \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md index 8c46b01be8..c367053cbb 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -36,20 +36,20 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati * [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. [Catalyst Signed Document content] must be [Brotli] compressed. -#### Proposal Metadata Fields +#### Metadata Fields A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). -* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) +* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional). * [`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') ``` -* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) -* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) -* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) +* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional). +* [`section`](./../signed_doc/meta.md#section-section-reference) (optional). +* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional). ## Proposal Template @@ -70,7 +70,7 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati * [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. [Catalyst Signed Document content] must be [Brotli] compressed. -#### Proposal Metadata Fields +#### Metadata Fields A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). From 49a029f2ede729b383b8292cba0a05fa51140b15 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 15:28:41 +0200 Subject: [PATCH 17/33] add review document --- .../08_concepts/catalyst_docs/.pages | 4 +- .../08_concepts/catalyst_docs/review.md | 80 +++++++++++++++++++ 2 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 docs/src/architecture/08_concepts/catalyst_docs/review.md diff --git a/docs/src/architecture/08_concepts/catalyst_docs/.pages b/docs/src/architecture/08_concepts/catalyst_docs/.pages index f03788f51e..426fd4d1e4 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/.pages +++ b/docs/src/architecture/08_concepts/catalyst_docs/.pages @@ -1,3 +1,5 @@ title: Catalyst Documents arrage: -- proposal.md \ No newline at end of file +- proposal.md +- review.md +- comment.md \ No newline at end of file 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..130b9a2022 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_docs/review.md @@ -0,0 +1,80 @@ +--- +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 + +Catalysyt Review document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +* [`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): `"br"`. + [Catalyst Signed Document content] must be [Brotli] compressed. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`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') + ``` + +## Review Template + +TODO + +### Specification + +Catalysyt Review Template document is a [Catalyst Signed Document], +so its fully follows the structure of the [Catalyst Signed Document] specification. + +* [`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): `"br"`. + [Catalyst Signed Document content] must be [Brotli] compressed. + +#### Metadata Fields + +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + +* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) +* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) +* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) +* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) + +## 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 \ No newline at end of file From 9defe3c0779544e22996c6af265a623bb50dc1f5 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 15:44:01 +0200 Subject: [PATCH 18/33] wip --- .../08_concepts/catalyst_docs/comment.md | 41 ++- .../08_concepts/catalyst_docs/index.md | 237 ------------------ .../08_concepts/catalyst_docs/proposal.md | 41 ++- .../08_concepts/catalyst_docs/review.md | 41 ++- .../08_concepts/signed_doc/spec.md | 2 +- .../08_concepts/signed_doc/types.md | 30 +-- 6 files changed, 106 insertions(+), 286 deletions(-) delete mode 100644 docs/src/architecture/08_concepts/catalyst_docs/index.md diff --git a/docs/src/architecture/08_concepts/catalyst_docs/comment.md b/docs/src/architecture/08_concepts/catalyst_docs/comment.md index 25c47a5d39..fc83bae51a 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/comment.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/comment.md @@ -22,6 +22,16 @@ This is a document which provides a comment against a particular [Proposal Docum Catalysyt 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. @@ -29,12 +39,11 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. - [Catalyst Signed Document content] must be [Brotli] compressed. - -#### Metadata Fields +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. -A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + ```CDDL + "content-type" => "br" + ``` * [`ref`](./../signed_doc/meta.md#ref-document-reference). Refence to a related [Proposal Document]. * [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0b8424d4-ebfd-46e3-9577-1775a69d290c` value, [commemt template type](#comment-template). @@ -65,6 +74,16 @@ This document pr provides the template structure which a Comment must be formatt Catalysyt 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. @@ -72,12 +91,11 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. - [Catalyst Signed Document content] must be [Brotli] compressed. - -#### Metadata Fields +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. -A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + ```CDDL + "content-type" => "br" + ``` * [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) * [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) @@ -92,4 +110,5 @@ This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses [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 \ No newline at end of file +[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/index.md b/docs/src/architecture/08_concepts/catalyst_docs/index.md deleted file mode 100644 index c4cbe0d2eb..0000000000 --- a/docs/src/architecture/08_concepts/catalyst_docs/index.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -Title: Catalyst Signed Documents -Category: Catalyst -Status: Proposed -Authors: - - Steven Johnson - - Alex Pozhylenkov -Implementors: - - Catalyst Fund 14 -Discussions: [] -Created: 2024-12-29 -License: CC-BY-4.0 ---- - -* [Abstract](#abstract) -* [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary) -* [Specification](#specification) - * [Document Type Definitions](#document-type-definitions) - * [Document Templates](#document-templates) - * [Document Content Templates](#document-content-templates) - * [Document Metadata](#document-metadata) - * [Document Reference : `ref` (optional)](#document-reference--ref-optional) - * [Template Reference : `template` (optional)](#template-reference--template-optional) - * [Document Reference : `reply` (optional)](#document-reference--reply-optional) - * [Document Reference : `section` (optional)](#document-reference--section-optional) - * [Authorized Collaborators : `collabs` (optional)](#authorized-collaborators--collabs-optional) - * [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 (proposals, reviews, comments). -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 - -Catalyst signed document is a [Catalyst Signed Document], -so its fully follows the structure of the [Catalyst Signed Document] specification. - -* [`content type`](./../signed_doc/spec.md#content-type): `application/json`. - [Catalyst Signed Document content](./../signed_doc/spec.md#signed-object-content) must be in [Json] format. - - ```CDDL - 3 => 30 - ``` - -### 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. -It is defined and specified as [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). - -```CDDL -? "ref" => reference_type, -? "template" => reference_type, -? "reply" => reference_type, -? "section" => text, -? "collabs" => [+any], -``` - -#### Document Reference : `ref` (optional) - -This is a reference to another document. -The purpose of the `ref` will vary depending on the document [`type`](./../signed_doc/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], it is a reference to the document of that [`id`](./../signed_doc/spec.md#id). -If the `ref` is a [CBOR] array, it has the form `[,]` where: - -* `` = the [UUID] of the referenced documents [`id`](./../signed_doc/spec.md#id) -* `` = the [UUID] of the referenced documents [`ver`](./../signed_doc/spec.md#ver). - -#### Template Reference : `template` (optional) - -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-optional). - -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) - -This is a reply to another document. -The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref-optional). - -`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) - -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) - -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-optional) - -They may *OPTIONALLY* also contain a [`reply`](#document-reference--reply-optional) 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-optional) 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). - -Comments may *OPTIONALLY* also contain a [`section`](#document-reference--section-optional) 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). - -[Catalyst Signed Document]: ./../signed_doc/spec.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 diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md index c367053cbb..18b49a863a 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -26,6 +26,16 @@ They are defined when a specific document is submitted for consideration. Catalysyt 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. @@ -33,12 +43,11 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. - [Catalyst Signed Document content] must be [Brotli] compressed. - -#### Metadata Fields +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. -A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + ```CDDL + "content-type" => "br" + ``` * [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional). * [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0ce8ab38-9258-4fbc-a62e-7faa6e58318f` value, [proposal template type](#proposal-template). @@ -60,6 +69,16 @@ This document provides the template structure which a Proposal must be formatted Catalysyt 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. @@ -67,12 +86,11 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. - [Catalyst Signed Document content] must be [Brotli] compressed. - -#### Metadata Fields +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. -A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + ```CDDL + "content-type" => "br" + ``` * [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) * [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) @@ -86,4 +104,5 @@ This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses [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 \ No newline at end of file +[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 index 130b9a2022..6143d9965a 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/review.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/review.md @@ -22,6 +22,16 @@ TODO Catalysyt 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. @@ -29,12 +39,11 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. - [Catalyst Signed Document content] must be [Brotli] compressed. - -#### Metadata Fields +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. -A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + ```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). @@ -51,6 +60,16 @@ TODO Catalysyt 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. @@ -58,12 +77,11 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): `"br"`. - [Catalyst Signed Document content] must be [Brotli] compressed. - -#### Metadata Fields +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. -A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). + ```CDDL + "content-type" => "br" + ``` * [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) * [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) @@ -77,4 +95,5 @@ This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses [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 \ No newline at end of file +[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/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md index 258f1eb7e9..c96d2639ec 100644 --- a/docs/src/architecture/08_concepts/signed_doc/spec.md +++ b/docs/src/architecture/08_concepts/signed_doc/spec.md @@ -70,7 +70,7 @@ 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] +[A full list of Catalyst supported document types](./types.md) #### `id` diff --git a/docs/src/architecture/08_concepts/signed_doc/types.md b/docs/src/architecture/08_concepts/signed_doc/types.md index 7d5e94aec5..c2297bc560 100644 --- a/docs/src/architecture/08_concepts/signed_doc/types.md +++ b/docs/src/architecture/08_concepts/signed_doc/types.md @@ -1,19 +1,19 @@ -| [UUID] | [CBOR] | Type Description | Payload Type | -| ------------------------------------ | ----------------------------------------- | ---------------------------- | --------------------------------- | -| 7808d2ba-d511-40af-84e8-c0d1625fdfdc | `37(h'7808d2bad51140af84e8c0d1625fdfdc')` | Proposal Document | [Brotli] Compressed [JSON] | -| 0ce8ab38-9258-4fbc-a62e-7faa6e58318f | `37(h'0ce8ab3892584fbca62e7faa6e58318f')` | Proposal Template | [Brotli] Compressed [JSON Schema] | -| b679ded3-0e7c-41ba-89f8-da62a17898ea | `37(h'b679ded30e7c41ba89f8da62a17898ea')` | Comment Document | [Brotli] Compressed [JSON] | -| 0b8424d4-ebfd-46e3-9577-1775a69d290c | `37(h'0b8424d4ebfd46e395771775a69d290c')` | Comment Template | [Brotli] Compressed [JSON Schema] | -| e4caf5f0-098b-45fd-94f3-0702a4573db5 | `37(h'e4caf5f0098b45fd94f30702a4573db5')` | Review Document | [Brotli] Compressed [JSON] | -| ebe5d0bf-5d86-4577-af4d-008fddbe2edc | `37(h'ebe5d0bf5d864577af4d008fddbe2edc')` | Review Template | [Brotli] Compressed [JSON Schema] | -| 48c20109-362a-4d32-9bba-e0a9cf8b45be | `37(h'48c20109362a4d329bbae0a9cf8b45be')` | Category Parameters Document | [Brotli] Compressed [JSON] | -| 65b1e8b0-51f1-46a5-9970-72cdf26884be | `37(h'65b1e8b051f146a5997072cdf26884be')` | Category Parameters Template | [Brotli] Compressed [JSON Schema] | -| 0110ea96-a555-47ce-8408-36efe6ed6f7c | `37(h'0110ea96a55547ce840836efe6ed6f7c')` | Campaign Parameters Document | [Brotli] Compressed [JSON] | -| 7e8f5fa2-44ce-49c8-bfd5-02af42c179a3 | `37(h'7e8f5fa244ce49c8bfd502af42c179a3')` | Campaign Parameters Template | [Brotli] Compressed [JSON Schema] | -| 3e4808cc-c86e-467b-9702-d60baa9d1fca | `37(h'3e4808ccc86e467b9702d60baa9d1fca')` | Brand Parameters Document | [Brotli] Compressed [JSON] | -| fd3c1735-80b1-4eea-8d63-5f436d97ea31 | `37(h'fd3c173580b14eea8d635f436d97ea31')` | Brand Parameters Template | [Brotli] Compressed [JSON Schema] | -| 5e60e623-ad02-4a1b-a1ac-406db978ee48 | `37(h'5e60e623ad024a1ba1ac406db978ee48')` | Proposal Action Document | *TBD* | +| [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* | [JSON Schema]: https://json-schema.org/draft-07 From b989ea4d5a15bb7924f31b54a35b322dbbdbf167 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 16:14:23 +0200 Subject: [PATCH 19/33] update v2 tx spec --- .../catalyst_voting/gen_vote_tx.md | 21 +---- .../08_concepts/catalyst_voting/v2.md | 77 +++++++++++++------ .../08_concepts/signed_doc/types.md | 2 + 3 files changed, 57 insertions(+), 43 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index 52baf9f645..0c80a2549e 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -15,7 +15,7 @@ Created: 2024-09-04 ## Abstract -This document defines a generalized view of the "Catalyst" voting transaction. +This document defines a generalized voting transaction [CDDL] structure. ## Motivation @@ -23,22 +23,6 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure ## Specification -Generalized vote transaction is a [Catalyst Signed Document], -so its fully follows the structure of the [Catalyst Signed Document] specification. - -* [`content type`](./../signed_doc/spec.md#content-type): `application/cbor`. - [Catalyst Signed Document content](./../signed_doc/spec.md#signed-object-content) must be a [CBOR] encoded. - - ```CDDL - 3 => 50 - ``` - -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): is missing - -### Content format - -The generalized vote transaction [content format](./../signed_doc/spec.md#signed-object-content) - ??? note "vote transaction definition: `gen_vote_tx.cddl`" @@ -70,5 +54,4 @@ Vote: -[Catalyst Signed Document]: ./../signed_doc/spec.md -[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 dd0ea1f4a6..9d85b108b9 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,12 +14,12 @@ 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 -Also additional [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#catalyst-signed-document-fields) are defined, +A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). ```CDDL "brand_id" => UUID, ; UUID v4 @@ -44,7 +37,35 @@ Also additional [Catalyst Signed Document protected header fields](./../signed_d * `category_id` - a unique identifier which defines a voting category as a collection of proposals, e.g. "Development & Infrastructure", "Products & Integrations". -### Public vote +* [`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" + ``` + + +##### 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`" @@ -54,13 +75,21 @@ Also additional [Catalyst Signed Document protected header fields](./../signed_d ``` -For the public vote [`type`](./../signed_doc/spec.md#type) value defined as follows: +##### Private vote -```CDDL -vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803 -``` +For the private vote [`type`](./../signed_doc/spec.md#type) value defined as follows: + +* [`type`](./../signed_doc/spec.md#type): `e78ee18d-f380-44c1-a852-80aa6ecb07fe` [UUID] value. + + ```CDDL + "type" => 37(h'E78EE18DF38044C1A85280AA6ECB07FE') + ``` -### Private vote +###### 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`" @@ -70,13 +99,7 @@ vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742 ``` -For the private vote [`type`](./../signed_doc/spec.md#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, @@ -99,5 +122,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/ \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/signed_doc/types.md b/docs/src/architecture/08_concepts/signed_doc/types.md index c2297bc560..6cb2ae6c33 100644 --- a/docs/src/architecture/08_concepts/signed_doc/types.md +++ b/docs/src/architecture/08_concepts/signed_doc/types.md @@ -14,6 +14,8 @@ | 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) | [JSON Schema]: https://json-schema.org/draft-07 From 6b90ad4885feefdff9eddbbfaaa69dce309030b7 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 16:22:48 +0200 Subject: [PATCH 20/33] fix spelling --- docs/src/architecture/08_concepts/catalyst_docs/.pages | 2 +- .../src/architecture/08_concepts/catalyst_docs/comment.md | 8 ++++---- .../architecture/08_concepts/catalyst_docs/proposal.md | 4 ++-- docs/src/architecture/08_concepts/catalyst_docs/review.md | 4 ++-- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/.pages b/docs/src/architecture/08_concepts/catalyst_docs/.pages index 426fd4d1e4..15986adb3b 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/.pages +++ b/docs/src/architecture/08_concepts/catalyst_docs/.pages @@ -1,5 +1,5 @@ title: Catalyst Documents -arrage: +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 index fc83bae51a..4d8e4bbcb3 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/comment.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/comment.md @@ -19,7 +19,7 @@ This is a document which provides a comment against a particular [Proposal Docum ### Specification -Catalysyt Comment document is a [Catalyst Signed Document], +Catalyst Comment document is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. #### Metadata Fields @@ -45,8 +45,8 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "content-type" => "br" ``` -* [`ref`](./../signed_doc/meta.md#ref-document-reference). Refence to a related [Proposal Document]. -* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0b8424d4-ebfd-46e3-9577-1775a69d290c` value, [commemt template type](#comment-template). +* [`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') @@ -71,7 +71,7 @@ This document pr provides the template structure which a Comment must be formatt ### Specification -Catalysyt Comment Template document is a [Catalyst Signed Document], +Catalyst Comment Template document is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. #### Metadata Fields diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md index 18b49a863a..818bee07e5 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -23,7 +23,7 @@ They are defined when a specific document is submitted for consideration. ### Specification -Catalysyt Proposal document is a [Catalyst Signed Document], +Catalyst Proposal document is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. #### Metadata Fields @@ -66,7 +66,7 @@ This document provides the template structure which a Proposal must be formatted ### Specification -Catalysyt Proposal Template document is a [Catalyst Signed Document], +Catalyst Proposal Template document is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. #### Metadata Fields diff --git a/docs/src/architecture/08_concepts/catalyst_docs/review.md b/docs/src/architecture/08_concepts/catalyst_docs/review.md index 6143d9965a..7a6cdfc83b 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/review.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/review.md @@ -19,7 +19,7 @@ TODO ### Specification -Catalysyt Review document is a [Catalyst Signed Document], +Catalyst Review document is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. #### Metadata Fields @@ -57,7 +57,7 @@ TODO ### Specification -Catalysyt Review Template document is a [Catalyst Signed Document], +Catalyst Review Template document is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. #### Metadata Fields From 080b53f895e5a960d237b01c925a57fe12d3ed2f Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 5 Jan 2025 17:04:53 +0200 Subject: [PATCH 21/33] fix mkdocs --- .../08_concepts/catalyst_docs/comment.md | 12 ++++++++---- .../08_concepts/catalyst_docs/proposal.md | 9 ++++++--- .../08_concepts/catalyst_docs/review.md | 9 ++++++--- .../08_concepts/catalyst_voting/v2.md | 18 +++++++++--------- .../architecture/08_concepts/signed_doc/.pages | 6 +++--- .../08_concepts/signed_doc/meta.md | 2 +- .../08_concepts/signed_doc/spec.md | 7 ++++--- .../08_concepts/signed_doc/types.md | 4 ++-- 8 files changed, 39 insertions(+), 28 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/comment.md b/docs/src/architecture/08_concepts/catalyst_docs/comment.md index 4d8e4bbcb3..11bdaef00f 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/comment.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/comment.md @@ -39,14 +39,17 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. +* [`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). +* [`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') @@ -91,7 +94,8 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. ```CDDL "content-type" => "br" diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md index 818bee07e5..68ed436eb1 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -43,14 +43,16 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. +* [`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) (optional). -* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0ce8ab38-9258-4fbc-a62e-7faa6e58318f` value, [proposal template type](#proposal-template). +* [`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') @@ -86,7 +88,8 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. ```CDDL "content-type" => "br" diff --git a/docs/src/architecture/08_concepts/catalyst_docs/review.md b/docs/src/architecture/08_concepts/catalyst_docs/review.md index 7a6cdfc83b..e75e407bf3 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/review.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/review.md @@ -39,13 +39,15 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. +* [`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). +* [`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') @@ -77,7 +79,8 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do 3 => 30 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. ```CDDL "content-type" => "br" diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 9d85b108b9..425adf5c2f 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -17,7 +17,7 @@ This document describes a Catalyst V2 vote transaction structure. Catalyst v2 voting transaction is a [Catalyst Signed Document], so its fully follows the structure of the [Catalyst Signed Document] specification. -#### Metadata Fields +### Metadata Fields A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). @@ -44,14 +44,14 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do 3 => 50 ``` -* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): [Catalyst Signed Document content] must be [Brotli] compressed. +* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional): + [Catalyst Signed Document content] must be [Brotli] compressed. ```CDDL "content-type" => "br" ``` - -##### Public vote +#### Public vote For the public vote [`type`](./../signed_doc/spec.md#type) value defined as follows: @@ -61,7 +61,7 @@ For the public vote [`type`](./../signed_doc/spec.md#type) value defined as foll "type" => 37(h'8DE5586CE9984B9587427BE3C8592803') ``` -###### Content format +##### Content format The public vote transaction [Catalyst Signed Document content] format is based on the [Generalized Vote Transaction Structure]. @@ -75,7 +75,7 @@ Following that spec need to define a `choice`, `proof` and `prop-id`. ``` -##### Private vote +#### Private vote For the private vote [`type`](./../signed_doc/spec.md#type) value defined as follows: @@ -85,7 +85,7 @@ For the private vote [`type`](./../signed_doc/spec.md#type) value defined as fol "type" => 37(h'E78EE18DF38044C1A85280AA6ECB07FE') ``` -###### Content format +##### Content format The private vote transaction [Catalyst Signed Document content] format is based on the [Generalized Vote Transaction Structure]. @@ -99,7 +99,7 @@ Following that spec need to define a `choice`, `proof` and `prop-id`. ``` -###### 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, @@ -129,4 +129,4 @@ the following properties are used: [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/ \ No newline at end of file +[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 index db7a381818..ffda03396a 100644 --- a/docs/src/architecture/08_concepts/signed_doc/.pages +++ b/docs/src/architecture/08_concepts/signed_doc/.pages @@ -1,5 +1,5 @@ title: Catalyst Signed Document nav: -- Specification: spec.md -- Metadata Fields List: meta.md -- Document Types: types.md + - Specification: spec.md + - Metadata Fields: meta.md + - Document Types: types.md diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index 6f021a5d70..b6b27477c8 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -1,3 +1,4 @@ +# Metadata Fields List ??? note "Additional Metadata fields: `additional_meta.cddl`" @@ -79,4 +80,3 @@ It does NOT mean that the listed collaborators have agreed to collaborate, only gives them permission to.* This list can impact actions that can be performed by the `Proposal Action Document`. - diff --git a/docs/src/architecture/08_concepts/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md index c96d2639ec..5d2411761c 100644 --- a/docs/src/architecture/08_concepts/signed_doc/spec.md +++ b/docs/src/architecture/08_concepts/signed_doc/spec.md @@ -91,7 +91,8 @@ be well constructed. 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. +*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 @@ -161,13 +162,13 @@ signature_protected_header = { ``` -* `kid`: A unique identifier of the signer. A [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 diff --git a/docs/src/architecture/08_concepts/signed_doc/types.md b/docs/src/architecture/08_concepts/signed_doc/types.md index 6cb2ae6c33..ce38e19d6a 100644 --- a/docs/src/architecture/08_concepts/signed_doc/types.md +++ b/docs/src/architecture/08_concepts/signed_doc/types.md @@ -1,3 +1,4 @@ +# Document Types Table | [UUID] | [CBOR] | Type Description | Payload Type | Specification Link | | ------------------------------------ | ----------------------------------------- | ---------------------------- | --------------------------------- | -------------------------------------------------------------------------- | @@ -17,9 +18,8 @@ | 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) | - [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 \ No newline at end of file +[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html From 9c23bd62bf567295b083cc2251ed379751a1be14 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 11:33:58 +0200 Subject: [PATCH 22/33] update metadata fields --- .../08_concepts/catalyst_voting/v2.md | 21 +++------- .../signed_doc/cddl/additional_meta.cddl | 6 ++- .../08_concepts/signed_doc/meta.md | 39 ++++++++++++++----- .../08_concepts/signed_doc/spec.md | 6 +-- 4 files changed, 43 insertions(+), 29 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 425adf5c2f..45c1192581 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -21,22 +21,6 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields). -```CDDL -"brand_id" => UUID, ; UUID v4 -"campaign_id" => UUID, ; UUID v4 -"election_id" => UUID, ; UUID v4 -"category_id" => UUID, ; UUID v4 -``` - -* `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". - * [`content type`](./../signed_doc/spec.md#content-type): `application/cbor`. [Catalyst Signed Document content] must be a [CBOR] encoded. @@ -51,6 +35,11 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "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 For the public vote [`type`](./../signed_doc/spec.md#type) value defined as follows: 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 index a6cad9c181..b45ae22e15 100644 --- a/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl @@ -5,9 +5,13 @@ additional_fields = { ? "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] +ref_type = UUID / [UUID, UUID] ; UUIDs v7 ref_hash_type = [ref_type, hash-bytes] UUID = #6.37(bytes) diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index b6b27477c8..8a4d487f66 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -8,12 +8,17 @@ ``` -* [`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) +* [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 @@ -22,11 +27,11 @@ The purpose of the `ref` will vary depending on the document [`type`](./spec.md# 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`](./spec.md#id). +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] of the referenced documents [`id`](./spec.md#id). -* `` - the [UUID] of the referenced documents [`ver`](./spec.md#ver). +* `` - 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 @@ -80,3 +85,19 @@ It does NOT mean that the listed collaborators have agreed to collaborate, only 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". \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md index 5d2411761c..19706bc161 100644 --- a/docs/src/architecture/08_concepts/signed_doc/spec.md +++ b/docs/src/architecture/08_concepts/signed_doc/spec.md @@ -68,7 +68,7 @@ All these fields will be encoded as the [COSE] `protected` header Each Catalyst Signed Document will have a type identifier called `type`. -The `type` is a [UUID] V4. +The `type` is a [UUID] v4. [A full list of Catalyst supported document types](./types.md) @@ -81,7 +81,7 @@ 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 `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. @@ -105,7 +105,7 @@ including all otherwise legitimate publications by the same author being marked 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 `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`, From 76b248a64a3a309cd5a3972f01fbe33ee9bcc0ce Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 11:37:28 +0200 Subject: [PATCH 23/33] wip --- .../src/architecture/08_concepts/catalyst_docs/comment.md | 8 ++++++++ .../architecture/08_concepts/catalyst_docs/proposal.md | 8 ++++++++ docs/src/architecture/08_concepts/catalyst_docs/review.md | 8 ++++++++ 3 files changed, 24 insertions(+) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/comment.md b/docs/src/architecture/08_concepts/catalyst_docs/comment.md index 11bdaef00f..76a06da449 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/comment.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/comment.md @@ -68,6 +68,10 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do * [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional). +#### Content format + +TODO + ## Comment Template This document pr provides the template structure which a Comment must be formatted to, and validated against. @@ -106,6 +110,10 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do * [`section`](./../signed_doc/meta.md#section-section-reference) (optional) * [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) +#### Content format + +TODO + ## Copyright This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md index 68ed436eb1..f701838286 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -62,6 +62,10 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do * [`section`](./../signed_doc/meta.md#section-section-reference) (optional). * [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional). +#### Content format + +TODO + ## Proposal Template This document provides the template structure which a Proposal must be formatted to, and validated against. @@ -100,6 +104,10 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do * [`section`](./../signed_doc/meta.md#section-section-reference) (optional) * [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) +#### Content format + +TODO + ## Copyright This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). diff --git a/docs/src/architecture/08_concepts/catalyst_docs/review.md b/docs/src/architecture/08_concepts/catalyst_docs/review.md index e75e407bf3..1bdbbb76a2 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/review.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/review.md @@ -53,6 +53,10 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "template" => 37(h'ebe5d0bf5d864577af4d008fddbe2edc') ``` +#### Content format + +TODO + ## Review Template TODO @@ -91,6 +95,10 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do * [`section`](./../signed_doc/meta.md#section-section-reference) (optional) * [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) +#### Content format + +TODO + ## Copyright This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). From 15ce4bc9c7a2da14bb9f496ca3bd4c9a4789222b Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 11:49:01 +0200 Subject: [PATCH 24/33] remove redundant section --- .../signed_document_metadata/.pages | 3 - .../signed_document_metadata/metadata.md | 296 ------------------ 2 files changed, 299 deletions(-) delete mode 100644 docs/src/architecture/08_concepts/signed_document_metadata/.pages delete mode 100644 docs/src/architecture/08_concepts/signed_document_metadata/metadata.md 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 From d765971c7f7cee9d0c0e338fe29fd49b5f9f6b94 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 13:05:29 +0200 Subject: [PATCH 25/33] fix ref_hash field --- .../08_concepts/signed_doc/cddl/additional_meta.cddl | 2 +- docs/src/architecture/08_concepts/signed_doc/meta.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) 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 index b45ae22e15..71a7ce9adc 100644 --- a/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/additional_meta.cddl @@ -1,6 +1,6 @@ additional_fields = { ? "ref" => ref_type, - ? "rev-hash" => ref_hash_type, + ? "ref_hash" => ref_hash_type, ? "template" => ref_type, ? "reply" => ref_type, ? "section" => text, diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index 8a4d487f66..1df6353dab 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -10,7 +10,7 @@ * [Metadata Fields List](#metadata-fields-list) * [`ref` Document Reference](#ref-document-reference) - * [`ref-hash` Secured Document Reference](#ref-hash-secured-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) @@ -33,14 +33,14 @@ 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 +## `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. +* `hash` - hash of the referenced document [CBOR] bytes. ## `template` Template Reference From ba32dd506b6322048ea65b456c7e0a7a4af3779d Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 14:44:05 +0200 Subject: [PATCH 26/33] fix mk check --- .../architecture/08_concepts/signed_doc/meta.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index 1df6353dab..5604f8a501 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -10,7 +10,7 @@ * [Metadata Fields List](#metadata-fields-list) * [`ref` Document Reference](#ref-document-reference) - * [`ref_hash` Secured Document Reference](#ref-hash-secured-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) @@ -88,16 +88,20 @@ This list can impact actions that can be performed by the `Proposal Action Docum ## `brand_id` -Unique identifier [UUID] v4, which represents a "brand" who is running the voting, e.g. Catalyst, Midnight. +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". +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". +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". \ No newline at end of file +Unique identifier [UUID] v4 which defines a voting category as a collection of proposals, +e.g. "Development & Infrastructure", "Products & Integrations". From 2e716557e757ca785d365120e343d256f0f8b433 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 15:45:52 +0200 Subject: [PATCH 27/33] update immutable ledger spec --- .../immutable_ledger/cddl/Earthfile | 3 +- .../immutable_ledger/cddl/block.cddl | 12 +-- .../cddl/genesis_to_prev_hash.cddl | 18 ---- .../08_concepts/immutable_ledger/ledger.md | 96 +++++++++++-------- .../08_concepts/signed_doc/meta.md | 3 + .../08_concepts/signed_doc/types.md | 35 +++---- 6 files changed, 81 insertions(+), 86 deletions(-) delete mode 100644 docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl 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 7d0d525063..0000000000 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl +++ /dev/null @@ -1,18 +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: ULID, - timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time - ledger-type: UUID, - purpose-id: ULID / UUID, - validator, -] - -UUID = #6.37(bytes) ; UUID type -ULID = #6.32780(bytes) ; ULID 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..67c29b32ce 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,5 @@ The format and size of this field **MUST** be totally the same as `validator` fi +[Catalyst Signed Document]: ./../signed_doc/spec.md [CBOR-deterministically-encoded]: https://datatracker.ietf.org/doc/html/rfc8949#name-deterministically-encoded-c diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index 5604f8a501..67a2fe8180 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -105,3 +105,6 @@ e.g. "Catalyst Fund 1", "Catalyst Fund 2". 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/ diff --git a/docs/src/architecture/08_concepts/signed_doc/types.md b/docs/src/architecture/08_concepts/signed_doc/types.md index ce38e19d6a..eb3469f241 100644 --- a/docs/src/architecture/08_concepts/signed_doc/types.md +++ b/docs/src/architecture/08_concepts/signed_doc/types.md @@ -1,22 +1,23 @@ # 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) | +| [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 From 3900978b75e95ab5fd0b55ef963bc2340dd59fb6 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 15:54:25 +0200 Subject: [PATCH 28/33] add earthly cddl check --- .../08_concepts/signed_doc/cddl/Earthfile | 14 ++++++++++++++ .../08_concepts/signed_doc/cddl/blueprint.cue | 2 ++ 2 files changed, 16 insertions(+) create mode 100644 docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile create mode 100644 docs/src/architecture/08_concepts/signed_doc/cddl/blueprint.cue 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/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" From 217da88f6e778ec89243e28b113fbada46efba26 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 16:01:00 +0200 Subject: [PATCH 29/33] fix ledger.md --- docs/src/architecture/08_concepts/immutable_ledger/ledger.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md index 67c29b32ce..f3731abdad 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md +++ b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md @@ -184,4 +184,7 @@ Block: [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/ From a15421334bd1e8bd293659ff582b56737810a6df Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 16:01:26 +0200 Subject: [PATCH 30/33] try --- docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile b/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile index dbfe99684b..f94ef962f8 100644 --- a/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile @@ -10,5 +10,5 @@ check-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 + # RUN cddlc -2 additional_meta.cddl + # RUN cddlc -2 signed_doc_meta.cddl From 712323d567e99dec1909a855e95a8d78de15d008 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 17:11:49 +0200 Subject: [PATCH 31/33] fix --- docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile | 4 ++-- .../08_concepts/signed_doc/cddl/signed_doc_meta.cddl | 6 ++++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile b/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile index f94ef962f8..dbfe99684b 100644 --- a/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile @@ -10,5 +10,5 @@ check-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 + RUN cddlc -2 additional_meta.cddl + RUN cddlc -2 signed_doc_meta.cddl 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 index b122c69510..212ca843bd 100644 --- 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 @@ -8,16 +8,18 @@ signed_doc_meta = { 1 => -8, ; "alg": EdDSA 3 => text / int, ; "content type" - ? "Content-Encoding" / "content-encoding" => "br", ; payload content encoding + ? 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 \ No newline at end of file +;# include additional_meta as meta From ba67c28291e29d7fccfcb52cd3dd8e0874b0f630 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 6 Jan 2025 17:13:28 +0200 Subject: [PATCH 32/33] cleanup documents --- .../architecture/08_concepts/catalyst_docs/comment.md | 7 ------- .../architecture/08_concepts/catalyst_docs/proposal.md | 10 ---------- .../architecture/08_concepts/catalyst_docs/review.md | 5 ----- 3 files changed, 22 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_docs/comment.md b/docs/src/architecture/08_concepts/catalyst_docs/comment.md index 76a06da449..b146c2e028 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/comment.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/comment.md @@ -66,8 +66,6 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do Used when the comment only applies to a specific section to the document being commented upon, and not the entire document. -* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional). - #### Content format TODO @@ -105,11 +103,6 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "content-type" => "br" ``` -* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) -* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) -* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) -* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) - #### Content format TODO diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md index f701838286..f9639cc64d 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md @@ -50,7 +50,6 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "content-type" => "br" ``` -* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional). * [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0ce8ab38-9258-4fbc-a62e-7faa6e58318f` value, [proposal template type](#proposal-template). @@ -58,10 +57,6 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "template" => 37(h'0ce8ab3892584fbca62e7faa6e58318f') ``` -* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional). -* [`section`](./../signed_doc/meta.md#section-section-reference) (optional). -* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional). - #### Content format TODO @@ -99,11 +94,6 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "content-type" => "br" ``` -* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) -* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) -* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) -* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) - #### Content format TODO diff --git a/docs/src/architecture/08_concepts/catalyst_docs/review.md b/docs/src/architecture/08_concepts/catalyst_docs/review.md index 1bdbbb76a2..456bd3d69c 100644 --- a/docs/src/architecture/08_concepts/catalyst_docs/review.md +++ b/docs/src/architecture/08_concepts/catalyst_docs/review.md @@ -90,11 +90,6 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do "content-type" => "br" ``` -* [`ref`](./../signed_doc/meta.md#ref-document-reference) (optional) -* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional) -* [`section`](./../signed_doc/meta.md#section-section-reference) (optional) -* [`collabs`](./../signed_doc/meta.md#collabs-authorized-collaborators) (optional) - #### Content format TODO From 84d29564308ad4a9dce5fe3bf2a5669e785d0fb6 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Wed, 8 Jan 2025 17:20:55 +0200 Subject: [PATCH 33/33] fix comments --- docs/src/architecture/08_concepts/signed_doc/meta.md | 1 + docs/src/architecture/08_concepts/signed_doc/spec.md | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_doc/meta.md b/docs/src/architecture/08_concepts/signed_doc/meta.md index 67a2fe8180..8088cd2b0b 100644 --- a/docs/src/architecture/08_concepts/signed_doc/meta.md +++ b/docs/src/architecture/08_concepts/signed_doc/meta.md @@ -108,3 +108,4 @@ 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 index 19706bc161..11752acd42 100644 --- a/docs/src/architecture/08_concepts/signed_doc/spec.md +++ b/docs/src/architecture/08_concepts/signed_doc/spec.md @@ -31,7 +31,7 @@ License: CC-BY-4.0 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. -Id addition to the data object content and the signature, metadata is also included +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? @@ -46,7 +46,7 @@ It fully inherits an original [COSE] design and specifies the details of differe ### Catalyst Signed Document metadata fields -To uniquely specify a Catalyst Signed Document type, version etc., as it was mentioned before, +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, @@ -75,7 +75,7 @@ The `type` is a [UUID] v4. #### `id` Every Catalyst Signed Document will have a unique ID. -All Catalyst Signed Document with the same `id` are considered versions of the same Catalyst Signed Document +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.