Skip to content

Commit cb475a6

Browse files
Mr-Leshiystevenj
Mr-Leshiy
and
stevenj
authored
feat(docs): Signed object design spec. (#126)
* add signed object design specs, update gen vote tx and vote v2 spec * add catalyst signed document section * add table of contents * fix markdown check * fix spelling * fix earthfile * rename catalyst signed object * update kid def * update content encoding * wip * wip * add meta.md doc * add ref hash defintion * Add a table of available document types * add proposal.md doc * add comment document * add review document * wip * update v2 tx spec * fix spelling * fix mkdocs * update metadata fields * wip * remove redundant section * fix ref_hash field * fix mk check * update immutable ledger spec * add earthly cddl check * fix ledger.md * try * fix * cleanup documents * fix comments --------- Co-authored-by: Steven Johnson <[email protected]>
1 parent 6a00a8b commit cb475a6

25 files changed

+852
-469
lines changed

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

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
title: Catalyst Documents
2+
arrange:
3+
- proposal.md
4+
- review.md
5+
- comment.md

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

+119
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
Title: Catalyst Comment Document
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-29
11+
License: CC-BY-4.0
12+
---
13+
14+
## Abstract
15+
16+
## Comment Document
17+
18+
This is a document which provides a comment against a particular [Proposal Document].
19+
20+
### Specification
21+
22+
Catalyst Comment document is a [Catalyst Signed Document],
23+
so its fully follows the structure of the [Catalyst Signed Document] specification.
24+
25+
#### Metadata Fields
26+
27+
A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields).
28+
29+
* [`type`](./../signed_doc/spec.md#type): `b679ded3-0e7c-41ba-89f8-da62a17898ea` [UUID] value.
30+
31+
```CDDL
32+
"type" => 37(h'b679ded30e7c41ba89f8da62a17898ea')
33+
```
34+
35+
* [`content type`](./../signed_doc/spec.md#content-type): `application/json`.
36+
[Catalyst Signed Document content] must be in [JSON] format.
37+
38+
```CDDL
39+
3 => 30
40+
```
41+
42+
* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional):
43+
[Catalyst Signed Document content] must be [Brotli] compressed.
44+
45+
```CDDL
46+
"content-type" => "br"
47+
```
48+
49+
* [`ref`](./../signed_doc/meta.md#ref-document-reference).
50+
Reference to a related [Proposal Document].
51+
* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0b8424d4-ebfd-46e3-9577-1775a69d290c` value,
52+
[comment template type](#comment-template).
53+
54+
```CDDL
55+
"template" => 37(h'0b8424d4ebfd46e395771775a69d290c')
56+
```
57+
58+
* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional).
59+
A reference to another comment,
60+
where the comment is in reply to the referenced comment.
61+
Comments may only reply to a single other comment document.
62+
The referenced `comment` must be for the same proposal [`id`](./../signed_doc/spec.md#id),
63+
but can be for a different proposal [`ver`](./../signed_doc/spec.md#ver).
64+
65+
* [`section`](./../signed_doc/meta.md#section-section-reference) (optional).
66+
Used when the comment only applies to a specific section to the document being commented upon,
67+
and not the entire document.
68+
69+
#### Content format
70+
71+
TODO
72+
73+
## Comment Template
74+
75+
This document pr provides the template structure which a Comment must be formatted to, and validated against.
76+
77+
### Specification
78+
79+
Catalyst Comment Template document is a [Catalyst Signed Document],
80+
so its fully follows the structure of the [Catalyst Signed Document] specification.
81+
82+
#### Metadata Fields
83+
84+
A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields).
85+
86+
* [`type`](./../signed_doc/spec.md#type): `0b8424d4-ebfd-46e3-9577-1775a69d290c` [UUID] value.
87+
88+
```CDDL
89+
"type" => 37(h'0b8424d4ebfd46e395771775a69d290c')
90+
```
91+
92+
* [`content type`](./../signed_doc/spec.md#content-type): `application/json`.
93+
[Catalyst Signed Document content] must be in [JSON] format.
94+
95+
```CDDL
96+
3 => 30
97+
```
98+
99+
* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional):
100+
[Catalyst Signed Document content] must be [Brotli] compressed.
101+
102+
```CDDL
103+
"content-type" => "br"
104+
```
105+
106+
#### Content format
107+
108+
TODO
109+
110+
## Copyright
111+
112+
This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
113+
114+
[Catalyst Signed Document]: ./../signed_doc/spec.md
115+
[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content
116+
[Proposal Document]: ./proposal.md
117+
[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932
118+
[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
119+
[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html

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

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
Title: Catalyst Proposal Document
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-29
11+
License: CC-BY-4.0
12+
---
13+
14+
## Abstract
15+
16+
## Proposal Document
17+
18+
This is a document, formatted against the referenced proposal template, which defines a proposal which may be submitted
19+
for consideration under one or more brand campaign categories.
20+
21+
The brand, campaign and category are not part of the document because the document can exist outside this boundary.
22+
They are defined when a specific document is submitted for consideration.
23+
24+
### Specification
25+
26+
Catalyst Proposal document is a [Catalyst Signed Document],
27+
so its fully follows the structure of the [Catalyst Signed Document] specification.
28+
29+
#### Metadata Fields
30+
31+
A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields).
32+
33+
* [`type`](./../signed_doc/spec.md#type): `7808d2ba-d511-40af-84e8-c0d1625fdfdc` [UUID] value.
34+
35+
```CDDL
36+
"type" => 37(h'7808d2bad51140af84e8c0d1625fdfdc')
37+
```
38+
39+
* [`content type`](./../signed_doc/spec.md#content-type): `application/json`.
40+
[Catalyst Signed Document content] must be in [JSON] format.
41+
42+
```CDDL
43+
3 => 30
44+
```
45+
46+
* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional):
47+
[Catalyst Signed Document content] must be [Brotli] compressed.
48+
49+
```CDDL
50+
"content-type" => "br"
51+
```
52+
53+
* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `0ce8ab38-9258-4fbc-a62e-7faa6e58318f` value,
54+
[proposal template type](#proposal-template).
55+
56+
```CDDL
57+
"template" => 37(h'0ce8ab3892584fbca62e7faa6e58318f')
58+
```
59+
60+
#### Content format
61+
62+
TODO
63+
64+
## Proposal Template
65+
66+
This document provides the template structure which a Proposal must be formatted to, and validated against.
67+
68+
### Specification
69+
70+
Catalyst Proposal Template document is a [Catalyst Signed Document],
71+
so its fully follows the structure of the [Catalyst Signed Document] specification.
72+
73+
#### Metadata Fields
74+
75+
A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields).
76+
77+
* [`type`](./../signed_doc/spec.md#type): `0ce8ab38-9258-4fbc-a62e-7faa6e58318f` [UUID] value.
78+
79+
```CDDL
80+
"type" => 37(h'0ce8ab3892584fbca62e7faa6e58318f')
81+
```
82+
83+
* [`content type`](./../signed_doc/spec.md#content-type): `application/json`.
84+
[Catalyst Signed Document content] must be in [JSON] format.
85+
86+
```CDDL
87+
3 => 30
88+
```
89+
90+
* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional):
91+
[Catalyst Signed Document content] must be [Brotli] compressed.
92+
93+
```CDDL
94+
"content-type" => "br"
95+
```
96+
97+
#### Content format
98+
99+
TODO
100+
101+
## Copyright
102+
103+
This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
104+
105+
[Catalyst Signed Document]: ./../signed_doc/spec.md
106+
[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content
107+
[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932
108+
[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
109+
[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html

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

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
Title: Catalyst Review Document
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-29
11+
License: CC-BY-4.0
12+
---
13+
14+
## Abstract
15+
16+
## Review Document
17+
18+
TODO
19+
20+
### Specification
21+
22+
Catalyst Review document is a [Catalyst Signed Document],
23+
so its fully follows the structure of the [Catalyst Signed Document] specification.
24+
25+
#### Metadata Fields
26+
27+
A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields).
28+
29+
* [`type`](./../signed_doc/spec.md#type): `e4caf5f0-098b-45fd-94f3-0702a4573db5` [UUID] value.
30+
31+
```CDDL
32+
"type" => 37(h'e4caf5f0098b45fd94f30702a4573db5')
33+
```
34+
35+
* [`content type`](./../signed_doc/spec.md#content-type): `application/json`.
36+
[Catalyst Signed Document content] must be in [JSON] format.
37+
38+
```CDDL
39+
3 => 30
40+
```
41+
42+
* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional):
43+
[Catalyst Signed Document content] must be [Brotli] compressed.
44+
45+
```CDDL
46+
"content-type" => "br"
47+
```
48+
49+
* [`template`](./../signed_doc/meta.md#ref-document-reference) must be equal to `ebe5d0bf-5d86-4577-af4d-008fddbe2edc` value,
50+
[review template type](#review-template).
51+
52+
```CDDL
53+
"template" => 37(h'ebe5d0bf5d864577af4d008fddbe2edc')
54+
```
55+
56+
#### Content format
57+
58+
TODO
59+
60+
## Review Template
61+
62+
TODO
63+
64+
### Specification
65+
66+
Catalyst Review Template document is a [Catalyst Signed Document],
67+
so its fully follows the structure of the [Catalyst Signed Document] specification.
68+
69+
#### Metadata Fields
70+
71+
A list of used [Catalyst Signed Document protected header fields](./../signed_doc/spec.md#signed-object-fields).
72+
73+
* [`type`](./../signed_doc/spec.md#type): `ebe5d0bf-5d86-4577-af4d-008fddbe2edc` [UUID] value.
74+
75+
```CDDL
76+
"type" => 37(h'ebe5d0bf5d864577af4d008fddbe2edc')
77+
```
78+
79+
* [`content type`](./../signed_doc/spec.md#content-type): `application/json`.
80+
[Catalyst Signed Document content] must be in [JSON] format.
81+
82+
```CDDL
83+
3 => 30
84+
```
85+
86+
* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional):
87+
[Catalyst Signed Document content] must be [Brotli] compressed.
88+
89+
```CDDL
90+
"content-type" => "br"
91+
```
92+
93+
#### Content format
94+
95+
TODO
96+
97+
## Copyright
98+
99+
This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
100+
101+
[Catalyst Signed Document]: ./../signed_doc/spec.md
102+
[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content
103+
[Brotli]: https://datatracker.ietf.org/doc/html/rfc7932
104+
[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
105+
[UUID]: https://www.rfc-editor.org/rfc/rfc9562.html

‎docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile

-2
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,8 @@ check-cddl:
1010
COPY ./gen_vote_tx.cddl \
1111
./vote_tx_v2_public.cddl \
1212
./vote_tx_v2_private.cddl \
13-
./gen_vote_tx_cose_payload.cddl \
1413
.
1514

16-
RUN cddlc -2 gen_vote_tx_cose_payload.cddl
1715
RUN cddlc -2 gen_vote_tx.cddl
1816
RUN cddlc -2 vote_tx_v2_public.cddl
1917
RUN cddlc -2 vote_tx_v2_private.cddl

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

-17
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,10 @@
22
; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06
33

44
gen-vote-tx<choice-t, proof-t, prop-id-t, voter-data-t> = [
5-
tx-body<choice-t, proof-t, prop-id-t, voter-data-t>,
6-
signature
7-
]
8-
9-
tx-body<choice-t, proof-t, prop-id-t, voter-data-t> = [
10-
vote-type,
11-
event,
125
votes<choice-t, proof-t, prop-id-t>,
136
voter-data<voter-data-t>,
147
]
158

16-
vote-type = UUID ; e.g. Public or Private vote
17-
event = { * event-key => event-value }
18-
event-key = int / text
19-
event-value = any
20-
219
votes<choice-t, proof-t, prop-id-t> = [+ vote<choice-t, proof-t, prop-id-t>]
2210
vote<choice-t, proof-t, prop-id-t> = [
2311
choices<choice-t>,
@@ -30,8 +18,3 @@ proof<proof-t> = #6.24(bytes .cbor proof-t) ; encoded-cbor
3018
prop-id<prop-id-t> = #6.24(bytes .cbor prop-id-t) ; encoded-cbor
3119

3220
voter-data<voter-data-t> = #6.24(bytes .cbor voter-data-t) ; encoded-cbor
33-
34-
UUID = #6.37(bytes) ; UUID type
35-
signature = #6.98(cose.COSE_Sign) ; COSE signature
36-
37-
;# import rfc9052 as cose

0 commit comments

Comments
 (0)