Skip to content

Commit e6c5f48

Browse files
stevenjMr-Leshiy
stevenj
and
Mr-Leshiy
authored
feat(docs): Expanded Documentation for signed documents (#646)
* fix(docs): fix local builds with earthly and Just * fix(docs): Remove CDDL from checks until we actually have it * feat(docs): wip * fix(docs): wip, but should fix cue errors * fix(docs): spelling * fix(docs): format * fix(docs): markdown * fix(docs): regenerated * fix(docs): make the check target work properly after `cue vet` broke * fix(docs): markdown * fix(docs): fix format * feat(docs): wip * fix(docs): key derivation docs render * fix(docs): wip contest ballot/register generation * docs(docs): Voter Ballot seems finished * docs(docs): Add the ballot checkpoint design specification to the docs * fix(docs): cue formatting * fix(docs): Markdown format now indent changed * docs(docs): Generalize sub-section page creation WIP * docs(docs): Preserve historical jormungandr vote transaction information for context * docs(docs): remove obsoleted documentation to provide better clarity * docs(docs): doc cleanup wip * fix(docs): spelling * fix(docs): markdown and spelling issues * fix(docs): cue format * fix(docs): Fix markdown * fix(docs): More markdown fixes * fix(docs): more markdown fixes * fix(rust): add bulleting board operator to admin roles * fix(rust): Fix documentation on user and admin role types in rust * docs(docs): WIP Parameters heirarchy and discovery * docs(docs): wip * fix(docs): WIP * fix(general): Revert cat-ci bump which breaks the build * fix(docs): Further revert cat-ci to last actual working version. * fix(rust): revert deny.toml to match cat-ci * fix(general): Try patched cat-ci with python on top of debian * fix(general): Promote python base2 to just python-base * fix(general): Fix CI branch name * docs(docs): fix spelling * docs(docs): remove proposals info from specs for now * fix(rust): Don't validate the contents of the CDDL because we can't validate all valid CDDL * fix(rust): Stop broken test case from failing build * fix(rust): skip failing tests * fix(rust): remove unused cbork dependency for now * fix(docs): format * docs(docs): Add link to main branch documentation in the Readme.md * feat(rust/signed-doc): Set the tagged version of `catalyst-signed-doc-spec` (#629) * set the proper version for the `catalyst-signed-doc-macro` * wip * revert `build-info` version * docs(docs): WIP * docs(docs): wip * docs(docs): Proposals flow done * fix(rust): Latest standard configs * fix: python version comment * fix: Python fixes * fix(general): python lint issues * fix(rust): Make sure coverage files don't end up in git * fix(general): Bump to released cat-ci with python updates for docs * docs(docs): Further explain how submission actions and moderation interacts with co-proposers * docs(docs): Add high level query guidance for proposal submission actions * docs(docs): expand docs for submission signing * fix(docs): make spell checking faster by not copying useless data * fix(rust): Missing CI bump * docs(docs): Add diagram to help explain the document type sequence * fix(docs): link * docs(docs): Add WIP drafts of the drep and voting document guides * fix(docs): check validation * fix(docs): markdown format * fix(docs): spec check issues * fix(docs): Add drep registration and delegation process docs * feat(docs): wip * fix(docs): content-encoding must be optional * fix(rust): try and fix test cases for ci * docs(docs): Update collaborators specifications * docs(docs): regen docs * fix(docs): markdown lint issues --------- Co-authored-by: Alex Pozhylenkov <[email protected]>
1 parent 8afb686 commit e6c5f48

33 files changed

+1597
-318
lines changed

‎.config/dictionaries/project.dic‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ ciphertexts
5252
Coap
5353
codegen
5454
codepoints
55+
Collab
5556
connexa
5657
coti
5758
coverallsapp

‎.earthlyignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.git
2+
**/target

‎AGENTS.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# AGENTS – Guidelines for Automated Assistants
2+
3+
This file provides repo‑wide guidance for automated coding assistants working in
4+
`catalyst-libs`.
5+
It applies to the entire repository unless a more specific
6+
`AGENTS.md` exists in a subdirectory.
7+
8+
## General Principles
9+
10+
* Make **small, targeted changes** that directly address the user’s request.
11+
* Prefer **clarity and correctness** over cleverness; do not refactor broadly
12+
unless explicitly asked.
13+
* Keep existing project structure, naming, and file layout intact unless there
14+
is a strong reason to change it.
15+
* When in doubt about intent (spec vs implementation vs docs), **ask the user**
16+
rather than guessing.
17+
18+
## Documentation & Specs
19+
20+
* For architecture/spec docs under `docs/src/architecture` that have a matching
21+
Jinja source under `specs/generators/pages`, treat the **Jinja template as the
22+
source of truth**.
23+
* Example: if both
24+
`specs/generators/pages/signed_doc/voting_process/foo.md.jinja` and
25+
`docs/src/architecture/08_concepts/signed_doc/voting_process/foo.md`
26+
exist, edit the `.md.jinja` file, not the generated `.md`.
27+
* Follow existing Markdown style:
28+
* Respect the “one sentence per line” convention where it is used.
29+
* Keep headings, link styles, and admonitions consistent with nearby text.
30+
* When adding terminology that is likely to trigger the spell checker, add it
31+
to `.config/dictionaries/project.dic` in **sorted order**.
32+
* If the user asks for validation, suggest or run (with their consent):
33+
* `just check-markdown`
34+
* `just check-spelling`
35+
36+
## Python (spec generators and tooling)
37+
38+
* Python code lives primarily under `specs/generators` and is linted/formatted
39+
with `ruff` (see `ruff.toml`).
40+
* Conform to the existing style:
41+
* Use double quotes for strings.
42+
* Keep line length within the configured limit.
43+
* Do not introduce new global `ignore` rules in `ruff.toml` unless the user
44+
requests it.
45+
* Where sensible, keep functions small and focused; avoid introducing new
46+
dependencies without discussing with the user.
47+
* When the user wants checks run, prefer:
48+
* `just format-python-code`
49+
* `just lint-python`
50+
51+
## Rust Workspace
52+
53+
* The Rust workspace is in `rust/`.
54+
Follow the existing module layout and
55+
crate boundaries; do not split or merge crates without explicit direction.
56+
* Match the existing style and patterns:
57+
* Use `cargo fmt` / the configured `fmtfix` and lint commands indirectly
58+
via `rust/Justfile` where possible.
59+
* Avoid adding new crates to the workspace unless clearly justified.
60+
* For validation, and only when the user is ready for longer commands, suggest
61+
or run:
62+
* `cd rust && just code-format`
63+
* `cd rust && just code-lint`
64+
* `cd rust && just pre-push` (heavier, CI‑like checks)
65+
66+
## CUE/CDDL Specs and Generated JSON
67+
68+
* Specification source is primarily in `specs/definitions` (CUE, CDDL, etc.).
69+
Treat these as **normative** and make changes carefully and incrementally.
70+
* Where both a CUE definition and a JSON spec exist (e.g. `specs/signed_doc.json`),
71+
assume the JSON is **generated** from the CUE/source definitions.
72+
* Prefer editing the source definitions and let the project’s existing
73+
tooling regenerate derived artifacts.
74+
* Do not hand‑edit large generated JSON files unless explicitly instructed.
75+
76+
## Earthly, Just, and CI
77+
78+
* This repo uses Earthly (`Earthfile`s) and `just` for repeatable workflows.
79+
* Respect the intended execution context:
80+
* Targets or functions marked as `LOCALLY` are meant to run on the host, not
81+
inside container builds.
82+
* Do not try to retrofit such targets into containerized steps without a
83+
clear reason and user confirmation.
84+
* When adding new Earthly targets or Just recipes, mirror the style of
85+
existing ones and keep names short and descriptive.
86+
87+
## Things to Avoid
88+
89+
* Do not:
90+
* Change licensing files, `CODE_OF_CONDUCT.md`, or security policies.
91+
* Introduce breaking API changes (in Rust or Python) without calling that
92+
out explicitly to the user.
93+
* Mass‑reformat the entire repo; limit formatting to files you touch.
94+
* Avoid speculative “cleanup” in areas unrelated to the user’s request, even
95+
if you notice possible improvements; mention them in your summary instead.

‎docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ COSE_Document_Header_Map = {
3333
; COSE Standard headers used by a Document
3434
COSE_Document_Standard_Headers = (
3535
3 => media_type
36-
"content-encoding" => http_content_encoding
36+
?"content-encoding" => http_content_encoding
3737
)
3838

3939
; Supported Content Media Types.

‎docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,8 +141,23 @@ publish a new version of the document.
141141

142142
This list does not imply these collaborators have consented to collaborate, only that the author/s
143143
are permitting these potential collaborators to participate in the drafting and submission process.
144-
However, any document submission referencing a proposal MUST be signed by all collaborators in
145-
addition to the author.
144+
How collaborators are counted on a final submission is determined by a parameter defined at the
145+
Brand/Campaign/Category level (parameter name TBD).
146+
Depending on that configuration:
147+
148+
* All listed collaborators may be required to submit a `final` Submission Action in addition
149+
to the author; **OR**
150+
* Only collaborators who submit a `final` Submission Action for the referenced version are
151+
included as collaborators on that submission.
152+
153+
If the parameter is not present, default to the latter mode (only final-signing collaborators are
154+
included).
155+
In all modes a document is only considered final when the original author has submitted `final`.
156+
157+
In the event there are **MULTIPLE** [`collaborators`](../metadata.md#collaborators) listed, they **MUST** be sorted.
158+
159+
Sorting for each element of [`collaborators`](../metadata.md#collaborators) follows the same sort order as specified for Map Keys,
160+
as defined by [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] (4.3.2 Length-First Map Key Ordering).
146161

147162
### [`revocations`](../metadata.md#revocations)
148163

@@ -211,6 +226,7 @@ of the previous submitted document's version.
211226

212227
* Generalized as another kind of form data document
213228

229+
[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
214230
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
215231
[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
216232
[RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7

‎docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,8 +142,23 @@ publish a new version of the document.
142142

143143
This list does not imply these collaborators have consented to collaborate, only that the author/s
144144
are permitting these potential collaborators to participate in the drafting and submission process.
145-
However, any document submission referencing a proposal MUST be signed by all collaborators in
146-
addition to the author.
145+
How collaborators are counted on a final submission is determined by a parameter defined at the
146+
Brand/Campaign/Category level (parameter name TBD).
147+
Depending on that configuration:
148+
149+
* All listed collaborators may be required to submit a `final` Submission Action in addition
150+
to the author; **OR**
151+
* Only collaborators who submit a `final` Submission Action for the referenced version are
152+
included as collaborators on that submission.
153+
154+
If the parameter is not present, default to the latter mode (only final-signing collaborators are
155+
included).
156+
In all modes a document is only considered final when the original author has submitted `final`.
157+
158+
In the event there are **MULTIPLE** [`collaborators`](../metadata.md#collaborators) listed, they **MUST** be sorted.
159+
160+
Sorting for each element of [`collaborators`](../metadata.md#collaborators) follows the same sort order as specified for Map Keys,
161+
as defined by [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] (4.3.2 Length-First Map Key Ordering).
147162

148163
### [`revocations`](../metadata.md#revocations)
149164

@@ -240,6 +255,7 @@ of the previous submitted document's version.
240255

241256
* Generalized as another kind of form data document
242257

258+
[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
243259
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
244260
[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
245261
[RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7

‎docs/src/architecture/08_concepts/signed_doc/docs/category_parameters.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,8 +142,23 @@ publish a new version of the document.
142142

143143
This list does not imply these collaborators have consented to collaborate, only that the author/s
144144
are permitting these potential collaborators to participate in the drafting and submission process.
145-
However, any document submission referencing a proposal MUST be signed by all collaborators in
146-
addition to the author.
145+
How collaborators are counted on a final submission is determined by a parameter defined at the
146+
Brand/Campaign/Category level (parameter name TBD).
147+
Depending on that configuration:
148+
149+
* All listed collaborators may be required to submit a `final` Submission Action in addition
150+
to the author; **OR**
151+
* Only collaborators who submit a `final` Submission Action for the referenced version are
152+
included as collaborators on that submission.
153+
154+
If the parameter is not present, default to the latter mode (only final-signing collaborators are
155+
included).
156+
In all modes a document is only considered final when the original author has submitted `final`.
157+
158+
In the event there are **MULTIPLE** [`collaborators`](../metadata.md#collaborators) listed, they **MUST** be sorted.
159+
160+
Sorting for each element of [`collaborators`](../metadata.md#collaborators) follows the same sort order as specified for Map Keys,
161+
as defined by [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] (4.3.2 Length-First Map Key Ordering).
147162

148163
### [`revocations`](../metadata.md#revocations)
149164

@@ -240,6 +255,7 @@ of the previous submitted document's version.
240255

241256
* Generalized as another kind of form data document
242257

258+
[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
243259
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
244260
[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
245261
[RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7

‎docs/src/architecture/08_concepts/signed_doc/docs/comment_moderation_action.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,10 @@ The following must be true for a valid reference:
137137
* The Referenced Document **MUST** Exist
138138
* Every value in the `document_locator` must consistently reference the exact same document.
139139
* The `document_id` and `document_ver` **MUST** match the values in the referenced document.
140+
* In the event there are **MULTIPLE** [`ref`](../metadata.md#ref) listed, they **MUST** be sorted.
141+
142+
Sorting for each element of [`ref`](../metadata.md#ref) follows the same sort order as specified for Map Keys,
143+
as defined by [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] (4.3.2 Length-First Map Key Ordering).
140144

141145
## Payload
142146

@@ -172,6 +176,7 @@ Only the original author can update and sign a new version of documents.
172176
* First Published Version
173177

174178
[CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
179+
[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
175180
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
176181
[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
177182
[IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid

‎docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot_checkpoint.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,10 @@ The following must be true for a valid reference:
171171
* The Referenced Document **MUST** Exist
172172
* Every value in the `document_locator` must consistently reference the exact same document.
173173
* The `document_id` and `document_ver` **MUST** match the values in the referenced document.
174+
* In the event there are **MULTIPLE** [`ref`](../metadata.md#ref) listed, they **MUST** be sorted.
175+
176+
Sorting for each element of [`ref`](../metadata.md#ref) follows the same sort order as specified for Map Keys,
177+
as defined by [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] (4.3.2 Length-First Map Key Ordering).
174178

175179
### [`parameters`](../metadata.md#parameters)
176180

@@ -525,6 +529,7 @@ Only the original author can update and sign a new version of documents.
525529
* Add Voting Ballots and Ballot Checkpoint Documents
526530

527531
[CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
532+
[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
528533
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
529534
[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
530535
[IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid

‎docs/src/architecture/08_concepts/signed_doc/docs/contest_delegation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,10 @@ The following must be true for a valid reference:
208208
* The Referenced Document **MUST** Exist
209209
* Every value in the `document_locator` must consistently reference the exact same document.
210210
* The `document_id` and `document_ver` **MUST** match the values in the referenced document.
211+
* In the event there are **MULTIPLE** [`ref`](../metadata.md#ref) listed, they **MUST** be sorted.
212+
213+
Sorting for each element of [`ref`](../metadata.md#ref) follows the same sort order as specified for Map Keys,
214+
as defined by [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] (4.3.2 Length-First Map Key Ordering).
211215

212216
### [`revocations`](../metadata.md#revocations)
213217

@@ -372,6 +376,7 @@ Only the original author can update and sign a new version of documents.
372376
* Allow Multi Delegation
373377

374378
[CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
379+
[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
375380
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
376381
[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
377382
[IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid

0 commit comments

Comments
 (0)