| Title | Category | Status | Authors | Implementors | Discussions | Created | License | ||
|---|---|---|---|---|---|---|---|---|---|
Signed Document Types and Metadata |
Catalyst |
Proposed |
|
|
2024-12-03 |
CC-BY-4.0 |
- Abstract
- Motivation: why is this CIP necessary?
- Specification
- Reference Implementation
- Rationale: how does this CIP achieve its goals?
- Path to Active
- Copyright
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.
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.
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 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 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 |
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.
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 ids 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.
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.
Subsequent versions will retain the same id and will create a new ver,
following best practice for creating a new UUID v7.
OPTIONAL, PROTECTED HEADER
This is a reference to another document.
The purpose of the ref will vary depending on the document 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.
If the ref is a CBOR array, it has the form [<id>,<ver>] where:
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.
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.
OPTIONAL, PROTECTED HEADER
This is a reply to another document.
The format is the same as the CBOR Array form of 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.
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.
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.
Note, not all document types are currently specified.
This document provides the template structure which a Proposal must be formatted to, and validated against.
This document pr provides the template structure which a Comment must be formatted to, and validated against.
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.
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
They may OPTIONALLY also contain a reply metadata field, which is 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,
but can be for a different proposal ver.
Comments may OPTIONALLY also contain a subsection field,
when the comment only applies to a specific section to the document being commented upon,
and not the entire document.
The first implementation will be Catalyst Voices.
TODO: Generate a set of test vectors which conform to this specification.
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.
Working Implementation before Fund 14.
Fund 14 project catalyst will deploy this scheme for Key derivation.>
This document is licensed under CC-BY-4.0.