From 57124e80064b4b62a474af1861a9f135c00b82c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joaqu=C3=ADn=20Rosales?= Date: Wed, 18 Dec 2024 22:08:09 -0600 Subject: [PATCH 1/2] fix(docs): update signed document metadata to use UUIDv7 instead of ULID --- .../signed_document_metadata/metadata.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/src/architecture/08_concepts/signed_document_metadata/metadata.md b/docs/src/architecture/08_concepts/signed_document_metadata/metadata.md index 35976af3c8d..688349b25ae 100644 --- a/docs/src/architecture/08_concepts/signed_document_metadata/metadata.md +++ b/docs/src/architecture/08_concepts/signed_document_metadata/metadata.md @@ -110,8 +110,9 @@ 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 [ULID]. -It will be encoded using [ULID CBOR Encoding]. +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. @@ -138,12 +139,13 @@ including all otherwise legitimate publications by the same author being marked Every document in the system will be versioned. There can, and probably will, exist multiple versions of the same document. -The `ver` is a [ULID]. -It will be encoded using [ULID CBOR Encoding]. +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 [ULID]. +following best practice for creating a new [UUID] v7. #### Document Reference : `ref` @@ -154,13 +156,13 @@ following best practice for creating a new [ULID]. 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 [ULID] or a [CBOR] Array of Two [ULID]. +The `ref` can be either a single [UUID] or a [CBOR] Array of Two [UUID]. -If the `ref` is a single [ULID], 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`](#document-id--id). If the `ref` is a [CBOR] array, it has the form `[,]` where: -* `` = the [ULID] of the referenced documents [`id`](#document-id--id) -* `` = the [ULID] of the referenced documents [`ver`](#document-version--ver). +* `` = the [UUID] of the referenced documents [`id`](#document-id--id) +* `` = the [UUID] of the referenced documents [`ver`](#document-version--ver). #### Template Reference : `template` @@ -289,8 +291,6 @@ This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses [JSON Schema]: https://json-schema.org/draft-07 [Brotli]: https://datatracker.ietf.org/doc/html/rfc7932 [JSON]: https://datatracker.ietf.org/doc/html/rfc7159 -[ULID]: https://github.com/ulid/spec -[ULID CBOR Encoding]: https://github.com/input-output-hk/catalyst-voices/blob/main/docs/src/catalyst-standards/cbor_tags/ulid.md [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 c28da80d14b4c9f74a0ffd3be4aa7aa4c49982b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joaqu=C3=ADn=20Rosales?= Date: Wed, 18 Dec 2024 22:26:09 -0600 Subject: [PATCH 2/2] fix(docs): move signed doc metadata docs to catalyst-libs --- .../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 418ac0f62d5..00000000000 --- 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 688349b25ae..00000000000 --- 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 a `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 a `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