Skip to content

Commit 451c004

Browse files
Mr-LeshiyMr-Leshiy
committed
add catalyst signed document section
1 parent bafb9d8 commit 451c004

File tree

5 files changed

+232
-2
lines changed

5 files changed

+232
-2
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
title: Catalyst Documents

‎docs/src/architecture/08_concepts/catalyst_docs/index.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
Title: Catalyst Signed Documents
3+
Category: Catalyst
4+
Status: Proposed
5+
Authors:
6+
- Steven Johnson <[email protected]>
7+
- Alex Pozhylenkov <[email protected]>
8+
Implementors:
9+
- Catalyst Fund 14
10+
Discussions: []
11+
Created: 2024-12-29
12+
License: CC-BY-4.0
13+
---
14+
15+
## Abstract
16+
17+
Project Catalyst both produces and consumes documents of data (proposals, reviews, comments).
18+
To ensure the document is authoritative, all documents of this kind will be signed.
19+
In addition to the document contents, documents will also include metadata which describes
20+
what kind of document it is, and how the document relates to other documents.
21+
22+
## Motivation: why is this CIP necessary?
23+
24+
As we decentralize project catalyst, it will be required to unambiguously identify who produced a
25+
document, and the purpose of the document.
26+
27+
A signed document specification will detail the structure of a signed document, this specification
28+
is just the metadata that structure will carry for different kinds of documents.
29+
30+
## Specification
31+
32+
Catalyst signed document is a [signed object],
33+
so its fully follows the structure of the [signed object] specification.
34+
35+
* [`content type`](./../signed_object/index.md#content-type): `application/json`.
36+
[Signed object content](./../signed_object/index.md#signed-object-content) must be in [Json] format.
37+
```CDDL
38+
3 => 30
39+
```
40+
* [`content encoding`](./../signed_object/index.md#content-encoding-optional): `"br"`. [Signed object content](./../signed_object/index.md#signed-object-content) must be [Brotli] compressed.
41+
```CDDL
42+
"content encoding" => "br"
43+
```
44+
45+
### Document Type Definitions
46+
47+
#### Document Templates
48+
49+
Document Templates are themselves signed documents, the templates currently defined or planned are:
50+
51+
| [UUID] | [CBOR] | Type Description | Payload Type |
52+
| ------------------------------------ | ----------------------------------------- | ---------------------------- | --------------------------------- |
53+
| 0ce8ab38-9258-4fbc-a62e-7faa6e58318f | `37(h'0ce8ab3892584fbca62e7faa6e58318f')` | Proposal Template | [Brotli] Compressed [JSON Schema] |
54+
| 0b8424d4-ebfd-46e3-9577-1775a69d290c | `37(h'0b8424d4ebfd46e395771775a69d290c')` | Comment Template | [Brotli] Compressed [JSON Schema] |
55+
| ebe5d0bf-5d86-4577-af4d-008fddbe2edc | `37(h'ebe5d0bf5d864577af4d008fddbe2edc')` | Review Template | [Brotli] Compressed [JSON Schema] |
56+
| 65b1e8b0-51f1-46a5-9970-72cdf26884be | `37(h'65b1e8b051f146a5997072cdf26884be')` | Category Parameters Template | [Brotli] Compressed [JSON Schema] |
57+
| 7e8f5fa2-44ce-49c8-bfd5-02af42c179a3 | `37(h'7e8f5fa244ce49c8bfd502af42c179a3')` | Campaign Parameters Template | [Brotli] Compressed [JSON Schema] |
58+
| fd3c1735-80b1-4eea-8d63-5f436d97ea31 | `37(h'fd3c173580b14eea8d635f436d97ea31')` | Brand Parameters Template | [Brotli] Compressed [JSON Schema] |
59+
60+
#### Document Content Templates
61+
62+
Document Contents are signed documents, and are typically produced in accordance with a template document.
63+
64+
| [UUID] | [CBOR] | Type Description | Payload Type |
65+
| ------------------------------------ | ----------------------------------------- | ---------------------------- | -------------------------- |
66+
| 7808d2ba-d511-40af-84e8-c0d1625fdfdc | `37(h'7808d2bad51140af84e8c0d1625fdfdc')` | Proposal Document | [Brotli] Compressed [JSON] |
67+
| b679ded3-0e7c-41ba-89f8-da62a17898ea | `37(h'b679ded30e7c41ba89f8da62a17898ea')` | Comment Document | [Brotli] Compressed [JSON] |
68+
| e4caf5f0-098b-45fd-94f3-0702a4573db5 | `37(h'e4caf5f0098b45fd94f30702a4573db5')` | Review Document | [Brotli] Compressed [JSON] |
69+
| 48c20109-362a-4d32-9bba-e0a9cf8b45be | `37(h'48c20109362a4d329bbae0a9cf8b45be')` | Category Parameters Document | [Brotli] Compressed [JSON] |
70+
| 0110ea96-a555-47ce-8408-36efe6ed6f7c | `37(h'0110ea96a55547ce840836efe6ed6f7c')` | Campaign Parameters Document | [Brotli] Compressed [JSON] |
71+
| 3e4808cc-c86e-467b-9702-d60baa9d1fca | `37(h'3e4808ccc86e467b9702d60baa9d1fca')` | Brand Parameters Document | [Brotli] Compressed [JSON] |
72+
| 5e60e623-ad02-4a1b-a1ac-406db978ee48 | `37(h'5e60e623ad024a1ba1ac406db978ee48')` | Proposal Action Document | *TBD* |
73+
74+
### Document Metadata
75+
76+
Documents will contain metadata which allows the document to be categorized, versioned and linked.
77+
This data does not properly belong inside the document,
78+
but is critical to ensure the document is properly referenced and indexable.
79+
80+
```CDDL
81+
? "ref" => reference_type,
82+
? "template" => reference_type,
83+
? "reply" => reference_type,
84+
? "section" => text,
85+
? "collabs" => [+any],
86+
```
87+
88+
#### Document Reference : `ref` (optional)
89+
90+
This is a reference to another document.
91+
The purpose of the `ref` will vary depending on the document [`type`](#document-type--type).
92+
93+
The `ref` can be either a single [UUID] or a [CBOR] Array of Two [UUID].
94+
95+
If the `ref` is a single [UUID], it is a reference to the document of that [`id`](#document-id--id).
96+
If the `ref` is a [CBOR] array, it has the form `[<id>,<ver>]` where:
97+
98+
* `<id>` = the [UUID] of the referenced documents [`id`](#document-id--id)
99+
* `<ver>` = the [UUID] of the referenced documents [`ver`](#document-version--ver).
100+
101+
#### Template Reference : `template` (optional)
102+
103+
If the document was formed from a template, this is a reference to that template document.
104+
The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref).
105+
106+
It is invalid not to reference the template that formed a document.
107+
If this is missing from such documents, the document will itself be considered invalid.
108+
109+
Template references must explicitly reference both the Template Document ID, and Version.
110+
111+
#### Document Reference : `reply` (optional)
112+
113+
This is a reply to another document.
114+
The format is the same as the [CBOR] Array form of [`ref`](#document-reference--ref).
115+
116+
`reply` is always referencing a document of the same type, and that document must `ref` reference the same document `id`.
117+
However, depending on the document type, it may reference a different `ver` of that `id`.
118+
119+
#### Document Reference : `section` (optional)
120+
121+
This is a reference to a section of a document.
122+
It is a CBOR String, and contains a [JSON Path] identifying the section in question.
123+
124+
Because this metadata field uses [JSON Path], it can only be used to reference a document whose payload is [JSON].
125+
126+
#### Authorized Collaborators : `collabs` (optional)
127+
128+
This is a list of entities other than the original author that may also publish versions of this document.
129+
This may be updated by the original author, or any collaborator that is given "author" privileges.
130+
131+
The latest `collabs` list in the latest version, published by an authorized author is the definitive
132+
list of allowed collaborators after that point.
133+
134+
The `collabs` list is a [CBOR] Array.
135+
The contents of the array are TBD.
136+
137+
However, they will contain enough information such that each collaborator can be uniquely identified and validated.
138+
139+
*Note: An Author can unilaterally set the `collabs` list to any list of collaborators.
140+
It does NOT mean that the listed collaborators have agreed to collaborate, only that the Author
141+
gives them permission to.*
142+
143+
This list can impact actions that can be performed by the `Proposal Action Document`.
144+
145+
### Document Type Specifications
146+
147+
Note, not all document types are currently specified.
148+
149+
#### Proposal Template
150+
151+
This document provides the template structure which a Proposal must be formatted to, and validated against.
152+
153+
#### Comment Template
154+
155+
This document pr provides the template structure which a Comment must be formatted to, and validated against.
156+
157+
#### Proposal Document
158+
159+
This is a document, formatted against the referenced proposal template, which defines a proposal which may be submitted
160+
for consideration under one or more brand campaign categories.
161+
162+
The brand, campaign and category are not part of the document because the document can exist outside this boundary.
163+
They are defined when a specific document is submitted for consideration.
164+
165+
#### Comment Document
166+
167+
This is a document which provides a comment against a particular proposal.
168+
Because comments are informed by a particular proposals version, they *MUST* contain a [`ref`](#document-reference--ref)
169+
170+
They may *OPTIONALLY* also contain a [`reply`](#document-reference--reply) metadata field, which is a reference to another comment,
171+
where the comment is in reply to the referenced comment.
172+
173+
Comments may only [`reply`](#document-reference--reply) to a single other comment document.
174+
The referenced `comment` must be for the same proposal [`id`](#document-id--id),
175+
but can be for a different proposal [`ver`](#document-version--ver).
176+
177+
Comments may *OPTIONALLY* also contain a [`subsection`](#document-reference--section) field,
178+
when the comment only applies to a specific section to the document being commented upon,
179+
and not the entire document.
180+
181+
## Reference Implementation
182+
183+
The first implementation will be Catalyst Voices.
184+
185+
*TODO: Generate a set of test vectors which conform to this specification.*
186+
187+
## Rationale: how does this CIP achieve its goals?
188+
189+
By specifying metadata attached to signed documents and unambiguous document type identifiers, we allow
190+
documents to be broadcast over insecure means, and for their meaning and relationships to remain intact.
191+
192+
The Document itself is soft, but the metadata provides concrete relationships between documents.
193+
194+
## Path to Active
195+
196+
### Acceptance Criteria
197+
198+
Working Implementation before Fund 14.
199+
200+
### Implementation Plan
201+
202+
Fund 14 project catalyst will deploy this scheme for Key derivation.>
203+
204+
## Copyright
205+
206+
This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
207+
208+
[signed object]: ./../signed_object/index.md
209+
[JSON Schema]: https://json-schema.org/draft-07
210+
[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932
211+
[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
212+
[CBOR]: https://datatracker.ietf.org/doc/html/rfc8610
213+
[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html
214+
[JSON Path]: https://datatracker.ietf.org/doc/html/rfc9535

‎docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure
2626
Generalized vote transaction is a [signed object],
2727
so its fully follows the structure of the [signed object] specification.
2828

29-
* [`content type`](./../signed_object/index.md#content-type): `application/cbor`
29+
* [`content type`](./../signed_object/index.md#content-type): `application/cbor`.
30+
[Signed object content](./../signed_object/index.md#signed-object-content) must be a [CBOR] encoded.
3031
```CDDL
3132
3 => 50
3233
```

‎docs/src/architecture/08_concepts/catalyst_voting/v2.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,5 +99,6 @@ the following properties are used:
9999

100100
<!-- OPTIONAL SECTIONS: see CIP-0001 > Document > Structure table -->
101101

102+
[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html
102103
[BLAKE2b-512]: https://www.blake2.net/blake2.pdf
103104
[ristretto255]: https://ristretto.group

‎docs/src/architecture/08_concepts/signed_object/index.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,27 @@ Category: Catalyst
44
Status: Proposed
55
Authors:
66
- Steven Johnson <[email protected]>
7-
- Alex Pozhylenkov <[email protected]>
7+
- Alex Pozhylenkov <[email protected]>
88
Implementors:
99
- Catalyst Fund 14
1010
Discussions: []
1111
Created: 2024-12-27
1212
License: CC-BY-4.0
1313
---
1414

15+
* [Abstract](#abstract)
16+
* [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary)
17+
* [Specification](#specification)
18+
* [Signed Object fields](#signed-object-fields)
19+
* [`type`](#type)
20+
* [`id`](#id)
21+
* [`ver`](#ver)
22+
* [`alg`](#alg)
23+
* [`content type`](#content-type)
24+
* [`content encoding` (optional)](#content-encoding-optional)
25+
* [Signed Object content](#signed-object-content)
26+
* [COSE signature protected header](#cose-signature-protected-header)
27+
* [Copyright](#copyright)
1528

1629
## Abstract
1730

0 commit comments

Comments
 (0)