Skip to content

Commit 0c2faf8

Browse files
saibatizokusaibatizoku
committed
feat(docs): add documentation for signed document metadata
1 parent 1440d0b commit 0c2faf8

File tree

2 files changed

+299
-0
lines changed

2 files changed

+299
-0
lines changed

‎docs/src/architecture/08_concepts/signed_document_metadata/.pages

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
title: Signed Document Metadata
2+
arrange:
3+
- metadata.md

‎docs/src/architecture/08_concepts/signed_document_metadata/metadata.md

+296
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
---
2+
Title: Signed Document Types and Metadata
3+
Category: Catalyst
4+
Status: Proposed
5+
Authors:
6+
- Steven Johnson <[email protected]>
7+
Implementors:
8+
- Catalyst Fund 14
9+
Discussions: []
10+
Created: 2024-12-03
11+
License: CC-BY-4.0
12+
---
13+
14+
* [Abstract](#abstract)
15+
* [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary)
16+
* [Specification](#specification)
17+
* [Document Type : `type`](#document-type--type)
18+
* [Document Type Definitions](#document-type-definitions)
19+
* [Document Templates](#document-templates)
20+
* [Document Content Templates](#document-content-templates)
21+
* [Document Metadata](#document-metadata)
22+
* [Document ID : `id`](#document-id--id)
23+
* [Document Version : `ver`](#document-version--ver)
24+
* [Document Reference : `ref`](#document-reference--ref)
25+
* [Template Reference : `template`](#template-reference--template)
26+
* [Document Reference : `reply`](#document-reference--reply)
27+
* [Document Reference : `section`](#document-reference--section)
28+
* [Authorized Collaborators : `collabs`](#authorized-collaborators--collabs)
29+
* [Document Type Specifications](#document-type-specifications)
30+
* [Proposal Template](#proposal-template)
31+
* [Comment Template](#comment-template)
32+
* [Proposal Document](#proposal-document)
33+
* [Comment Document](#comment-document)
34+
* [Reference Implementation](#reference-implementation)
35+
* [Rationale: how does this CIP achieve its goals?](#rationale-how-does-this-cip-achieve-its-goals)
36+
* [Path to Active](#path-to-active)
37+
* [Acceptance Criteria](#acceptance-criteria)
38+
* [Implementation Plan](#implementation-plan)
39+
* [Copyright](#copyright)
40+
41+
## Abstract
42+
43+
Project Catalyst both produces and consumes documents of data.
44+
To ensure the document is authoritative, all documents of this kind will be signed.
45+
In addition to the document contents, documents will also include metadata which describes
46+
what kind of document it is, and how the document relates to other documents.
47+
48+
## Motivation: why is this CIP necessary?
49+
50+
As we decentralize project catalyst, it will be required to unambiguously identify who produced a
51+
document, and the purpose of the document.
52+
53+
A signed document specification will detail the structure of a signed document, this specification
54+
is just the metadata that structure will carry for different kinds of documents.
55+
56+
## Specification
57+
58+
### Document Type : `type`
59+
60+
Each document will have a document type identifier called `type`.
61+
This identifier will be a [CBOR] Encoded [UUID Byte String].
62+
Only [UUID] V4 is supported and used.
63+
64+
The document types and their identifiers are listed here:
65+
66+
#### Document Type Definitions
67+
68+
##### Document Templates
69+
70+
Document Templates are themselves signed documents, the templates currently defined or planned are:
71+
72+
| [UUID] | [CBOR] | Type Description | Payload Type |
73+
| --- | --- | --- | --- |
74+
| 0ce8ab38-9258-4fbc-a62e-7faa6e58318f | `37(h'0ce8ab3892584fbca62e7faa6e58318f')` | Proposal Template | [Brotli] Compressed [JSON Schema] |
75+
| 0b8424d4-ebfd-46e3-9577-1775a69d290c | `37(h'0b8424d4ebfd46e395771775a69d290c')` | Comment Template | [Brotli] Compressed [JSON Schema] |
76+
| ebe5d0bf-5d86-4577-af4d-008fddbe2edc | `37(h'ebe5d0bf5d864577af4d008fddbe2edc')` | Review Template | [Brotli] Compressed [JSON Schema] |
77+
| 65b1e8b0-51f1-46a5-9970-72cdf26884be | `37(h'65b1e8b051f146a5997072cdf26884be')` | Category Parameters Template | [Brotli] Compressed [JSON Schema] |
78+
| 7e8f5fa2-44ce-49c8-bfd5-02af42c179a3 | `37(h'7e8f5fa244ce49c8bfd502af42c179a3')` | Campaign Parameters Template | [Brotli] Compressed [JSON Schema] |
79+
| fd3c1735-80b1-4eea-8d63-5f436d97ea31 | `37(h'fd3c173580b14eea8d635f436d97ea31')` | Brand Parameters Template | [Brotli] Compressed [JSON Schema] |
80+
81+
##### Document Content Templates
82+
83+
Document Contents are signed documents, and are typically produced in accordance with a template document.
84+
85+
| [UUID] | [CBOR] | Type Description | Payload Type |
86+
| --- | --- | --- | --- |
87+
| 7808d2ba-d511-40af-84e8-c0d1625fdfdc | `37(h'7808d2bad51140af84e8c0d1625fdfdc')` | Proposal Document | [Brotli] Compressed [JSON] |
88+
| b679ded3-0e7c-41ba-89f8-da62a17898ea | `37(h'b679ded30e7c41ba89f8da62a17898ea')` | Comment Document | [Brotli] Compressed [JSON] |
89+
| e4caf5f0-098b-45fd-94f3-0702a4573db5 | `37(h'e4caf5f0098b45fd94f30702a4573db5')` | Review Document | [Brotli] Compressed [JSON] |
90+
| 48c20109-362a-4d32-9bba-e0a9cf8b45be | `37(h'48c20109362a4d329bbae0a9cf8b45be')` | Category Parameters Document | [Brotli] Compressed [JSON] |
91+
| 0110ea96-a555-47ce-8408-36efe6ed6f7c | `37(h'0110ea96a55547ce840836efe6ed6f7c')` | Campaign Parameters Document | [Brotli] Compressed [JSON] |
92+
| 3e4808cc-c86e-467b-9702-d60baa9d1fca | `37(h'3e4808ccc86e467b9702d60baa9d1fca')` | Brand Parameters Document | [Brotli] Compressed [JSON] |
93+
| 5e60e623-ad02-4a1b-a1ac-406db978ee48 | `37(h'5e60e623ad024a1ba1ac406db978ee48')` | Proposal Action Document | *TBD* |
94+
95+
### Document Metadata
96+
97+
Documents will contain metadata which allows the document to be categorized, versioned and linked.
98+
This data does not properly belong inside the document,
99+
but is critical to ensure the document is properly referenced and indexable.
100+
101+
#### Document ID : `id`
102+
103+
<!-- markdownlint-disable MD036 -->
104+
**REQUIRED, PROTECTED HEADER**
105+
<!-- markdownlint-enable MD036 -->
106+
107+
Every document will have a unique document ID, this is to allow the same document to be referenced.
108+
All documents with the same `doc_id` are considered versions of the same document.
109+
However, `id` uniqueness is only guaranteed on first use.
110+
111+
If the same `id` is used, by unauthorized publishers, the document is invalid.
112+
113+
The `id` is a [UUID].
114+
This identifier will be a [CBOR] Encoded [UUID Byte String].
115+
Only [UUID] V7 is supported and used.
116+
117+
The first time a document is created, it will be assigned by the creator a new `id` which must
118+
be well constructed.
119+
120+
* The time must be the time the document was first created.
121+
* The random value must be truly random.
122+
123+
Creating `id` this way ensures there are no collisions, and they can be independently created without central co-ordination.
124+
125+
*Note: All documents are signed, the first creation of a `id` assigns that `id` to the creator and any assigned collaborators.
126+
A Signed Document that is not signed by the creator, or an assigned collaborator, is invalid.
127+
There is no reasonable way a `id` can collide accidentally.
128+
Therefore, detection of invalid `id`s published by unauthorized publishers, could result in anti-spam
129+
or system integrity mitigations being triggered.
130+
This could result in all actions in the system being blocked by the offending publisher,
131+
including all otherwise legitimate publications by the same author being marked as fraudulent.*
132+
133+
#### Document Version : `ver`
134+
135+
<!-- markdownlint-disable MD036 -->
136+
**REQUIRED, PROTECTED HEADER**
137+
<!-- markdownlint-enable MD036 -->
138+
139+
Every document in the system will be versioned.
140+
There can, and probably will, exist multiple versions of the same document.
141+
142+
The `ver` is a [UUID].
143+
This identifier will be a [CBOR] Encoded [UUID Byte String].
144+
Only [UUID] V7 is supported and used.
145+
146+
The initial `ver` assigned the first time a document is published will be identical to the [`id`](#document-id--id).
147+
Subsequent versions will retain the same [`id`](#document-id--id) and will create a new `ver`,
148+
following best practice for creating a new [UUID] v7.
149+
150+
#### Document Reference : `ref`
151+
152+
<!-- markdownlint-disable MD036 -->
153+
**OPTIONAL, PROTECTED HEADER**
154+
<!-- markdownlint-enable MD036 -->
155+
156+
This is a reference to another document.
157+
The purpose of the `ref` will vary depending on the document [`type`](#document-type--type).
158+
159+
The `ref` can be either a single [UUID] or a [CBOR] Array of Two [UUID].
160+
161+
If the `ref` is a single [UUID], it is a reference to the document of that [`id`](#document-id--id).
162+
If the `ref` is a [CBOR] array, it has the form `[<id>,<ver>]` where:
163+
164+
* `<id>` = the [UUID] of the referenced documents [`id`](#document-id--id)
165+
* `<ver>` = the [UUID] of the referenced documents [`ver`](#document-version--ver).
166+
167+
#### Template Reference : `template`
168+
169+
<!-- markdownlint-disable MD036 -->
170+
**REQUIRED, IF THE DOCUMENT WAS FORMED FROM A TEMPLATE, PROTECTED HEADER**
171+
<!-- markdownlint-enable MD036 -->
172+
173+
If the document was formed from a template, this is a reference to that template document.
174+
The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref).
175+
176+
It is invalid not to reference the template that formed a document.
177+
If this is missing from such documents, the document will itself be considered invalid.
178+
179+
Template references must explicitly reference both the Template Document ID, and Version.
180+
181+
#### Document Reference : `reply`
182+
183+
<!-- markdownlint-disable MD036 -->
184+
**OPTIONAL, PROTECTED HEADER**
185+
<!-- markdownlint-enable MD036 -->
186+
187+
This is a reply to another document.
188+
The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref).
189+
190+
`reply` is always referencing a document of the same type, and that document must `ref` reference the same document `id`.
191+
However, depending on the document type, it may reference a different `ver` of that `id`.
192+
193+
#### Document Reference : `section`
194+
195+
<!-- markdownlint-disable MD036 -->
196+
**OPTIONAL, PROTECTED HEADER**
197+
<!-- markdownlint-enable MD036 -->
198+
199+
This is a reference to a section of a document.
200+
It is a CBOR String, and contains a [JSON Path] identifying the section in question.
201+
202+
Because this metadata field uses [JSON Path], it can only be used to reference a document whose payload is [JSON].
203+
204+
#### Authorized Collaborators : `collabs`
205+
206+
<!-- markdownlint-disable MD036 -->
207+
**OPTIONAL, PROTECTED HEADER**
208+
<!-- markdownlint-enable MD036 -->
209+
210+
This is a list of entities other than the original author that may also publish versions of this document.
211+
This may be updated by the original author, or any collaborator that is given "author" privileges.
212+
213+
The latest `collabs` list in the latest version, published by an authorized author is the definitive
214+
list of allowed collaborators after that point.
215+
216+
The `collabs` list is a [CBOR] Array.
217+
The contents of the array are TBD.
218+
219+
However, they will contain enough information such that each collaborator can be uniquely identified and validated.
220+
221+
*Note: An Author can unilaterally set the `collabs` list to any list of collaborators.
222+
It does NOT mean that the listed collaborators have agreed to collaborate, only that the Author
223+
gives them permission to.*
224+
225+
This list can impact actions that can be performed by the `Proposal Action Document`.
226+
227+
### Document Type Specifications
228+
229+
Note, not all document types are currently specified.
230+
231+
#### Proposal Template
232+
233+
This document provides the template structure which a Proposal must be formatted to, and validated against.
234+
235+
#### Comment Template
236+
237+
This document pr provides the template structure which a Comment must be formatted to, and validated against.
238+
239+
#### Proposal Document
240+
241+
This is a document, formatted against the referenced proposal template, which defines a proposal which may be submitted
242+
for consideration under one or more brand campaign categories.
243+
244+
The brand, campaign and category are not part of the document because the document can exist outside this boundary.
245+
They are defined when a specific document is submitted for consideration.
246+
247+
#### Comment Document
248+
249+
This is a document which provides a comment against a particular proposal.
250+
Because comments are informed by a particular proposals version, they *MUST* contain a [`ref`](#document-reference--ref)
251+
252+
They may *OPTIONALLY* also contain a [`reply`](#document-reference--reply) metadata field, which is a reference to another comment,
253+
where the comment is in reply to the referenced comment.
254+
255+
Comments may only [`reply`](#document-reference--reply) to a single other comment document.
256+
The referenced `comment` must be for the same proposal [`id`](#document-id--id),
257+
but can be for a different proposal [`ver`](#document-version--ver).
258+
259+
Comments may *OPTIONALLY* also contain a [`subsection`](#document-reference--section) field,
260+
when the comment only applies to a specific section to the document being commented upon,
261+
and not the entire document.
262+
263+
## Reference Implementation
264+
265+
The first implementation will be Catalyst Voices.
266+
267+
*TODO: Generate a set of test vectors which conform to this specification.*
268+
269+
## Rationale: how does this CIP achieve its goals?
270+
271+
By specifying metadata attached to signed documents and unambiguous document type identifiers, we allow
272+
documents to be broadcast over insecure means, and for their meaning and relationships to remain intact.
273+
274+
The Document itself is soft, but the metadata provides concrete relationships between documents.
275+
276+
## Path to Active
277+
278+
### Acceptance Criteria
279+
280+
Working Implementation before Fund 14.
281+
282+
### Implementation Plan
283+
284+
Fund 14 project catalyst will deploy this scheme for Key derivation.>
285+
286+
## Copyright
287+
288+
This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
289+
290+
[UUID Byte String]: https://github.com/lucas-clemente/cbor-specs/blob/master/uuid.md
291+
[JSON Schema]: https://json-schema.org/draft-07
292+
[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932
293+
[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
294+
[CBOR]: https://datatracker.ietf.org/doc/html/rfc8610
295+
[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html
296+
[JSON Path]: https://datatracker.ietf.org/doc/html/rfc9535

0 commit comments

Comments
 (0)