feat(docs): Improve cddl definitions

.config/dictionaries/project.dic

@@ -23,13 +23,15 @@ blosc
 bmac
 bootstrapper
 BROTLI
+Cabe
 cantopen
 cardano
 carryforward
 CBOR
 cbork
 cddlc
 cdylib
+CELLBORDER
 CEST
 chacha
 CHAINCODE
@@ -60,10 +62,13 @@ dbsync
 dcbor
 decompressor
 delegators
+direnv
 displaydoc
 dleq
 dlog
 dockerhub
+docstrings
+doctests
 Dominik
 dotenv
 dotenvy
@@ -76,6 +81,7 @@ encryptor
 Errno
 Eternl
 excalidraw
+explicitely
 extn
 fadvise
 fcntl
@@ -90,6 +96,7 @@ fmmap
 fmtchk
 fmtfix
 fontawesome
+fontname
 fromfiledate
 fsgr
 fstat
@@ -102,10 +109,12 @@ getres
 giantstep
 gmtime
 gossipsub
+graphviz
 happ
 hardano
 Hardlink
 hasher
+headlabel
 heaptrack
 hexdigit
 highwater
@@ -120,13 +129,16 @@ ioerr
 iohk
 ipfs
 ipld
+ipynb
+isort
 jetbrains
 jorm
 jormungandr
 Jörmungandr
 jsonschema
 Justfile
 kiduri
+labelloc
 lcov
 Leay
 Leshiy
@@ -168,6 +180,7 @@ MPMC
 msvc
 Multiaddr
 multiera
+mypy
 nanos
 netkey
 nextest
@@ -185,6 +198,7 @@ outlen
 Outparam
 outpubkey
 parameterises
+penwidth
 permissioned
 permissionless
 pg_isready
@@ -205,9 +219,17 @@ pubkey
 publickey
 pubspec
 pwrite
+pycodestyle
+pydantic
+pydot
+pyenv
+Pyflakes
+pypackages
 pytest
+pytype
 qpsg
 quic
+rankdir
 rapidoc
 readlinkat
 redoc
@@ -251,6 +273,7 @@ subsec
 symlinkat
 syscall
 tacho
+taillabel
 testcase
 testcov
 testdocs
@@ -267,6 +290,7 @@ tofiledate
 toobig
 toolsets
 Traceback
+tstr
 txmonitor
 txns
 typenum
@@ -282,6 +306,7 @@ utimensat
 UTXO
 uuidv4
 uuidv7
+venv
 vitss
 Vkey
 vkeywitness

Earthfile

@@ -1,8 +1,9 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/mdlint:v3.4.0 AS mdlint-ci
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/cspell:v3.4.0 AS cspell-ci
-
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/mdlint:v3.4.1 AS mdlint-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cspell:v3.4.1 AS cspell-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/python:v3.4.1 AS python-ci
+IMPORT github.com/input-output-hk/catalyst-ci:v3.4.1 AS cat-ci
 
 FROM debian:stable-slim
 
@@ -42,9 +43,22 @@ repo-docs:
  COPY --dir *.md LICENSE-APACHE LICENSE-MIT .
 
  SAVE ARTIFACT /repo repo
+
+# We lint python globally in repos, so that all scripts and programs
+# are linted equally.
+# Its also fast.
+check-python:
+ DO python-ci+LINT_PYTHON 
+
+# Sync standard configs.
+sync-config:
+ FROM scratch
+ COPY --dir cat-ci+repo-config/repo .
+
+ SAVE ARTIFACT /repo/ruff.toml AS LOCAL ruff.toml
 
 # copy-specs : Copy the specs source folder.
 copy-specs:
  FROM scratch
  COPY --dir specs ./specs
- SAVE ARTIFACT /specs specs
+ SAVE ARTIFACT /specs specs

Justfile

@@ -21,7 +21,8 @@ format-python-code:
  ruff format .
 
 # Fix and Check Markdown files
-lint-python:
+lint-python: format-python-code
+ ruff check --fix .
  ruff check .
 
 # generates specifications data

docs/Earthfile

@@ -1,7 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.4.0 AS docs-ci
-
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.4.1 AS docs-ci
 
 IMPORT .. AS repo
 

docs/src/appendix/important/license.md

@@ -9,11 +9,11 @@ icon: material/license
 ??? note "Apache 2 License"
 
  ```text
- {{ include_file('includes/repo/LICENSE-APACHE', 0, -1, 8) }}
+ {{ include_file('includes/repo/LICENSE-APACHE', indent=8) }}
  ```
 
 ??? note "MIT License"
 
  ```text
- {{ include_file('includes/repo/LICENSE-MIT', 0, -1, 8) }}
+ {{ include_file('includes/repo/LICENSE-MIT', indent=8) }}
  ```

docs/src/appendix/tags.md

@@ -4,4 +4,4 @@ icon: fontawesome/solid/tags
 
 # Tag Index
 
-[TAGS]
+<!-- material/tags -->

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

@@ -1,6 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.0 AS cddl-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.1 AS cddl-ci
 
 check-cddl:
  FROM cddl-ci+cddl-base

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

@@ -27,7 +27,7 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure
 ??? note "vote transaction definition: `gen_vote_tx.cddl`"
 
  ```CDDL
- {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl', indent=4) }}
+ {{ include_file('./cddl/gen_vote_tx.cddl', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 

docs/src/architecture/08_concepts/catalyst_voting/v1.md

@@ -29,7 +29,7 @@ An original Jörmungandr blockchain's `VoteCast` transaction structure.
 ??? note "V1 transaction definition: `jorm.abnf`"
 
  ```abnf
- {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf', indent=4) }}
+ {{ include_file('./abnf/jorm.abnf', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 

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

@@ -60,7 +60,7 @@ Following that spec need to define a `choice`, `proof` and `prop-id`.
 ??? note "Public vote transaction v2 definition: `vote_tx_v2_public.cddl`"
 
  ```CDDL
- {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl', indent=4) }}
+ {{ include_file('./cddl/vote_tx_v2_public.cddl', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 
@@ -84,7 +84,7 @@ Following that spec need to define a `choice`, `proof` and `prop-id`.
 ??? note "Private vote transaction v2 definition: `vote_tx_v2_private.cddl`"
 
  ```CDDL
- {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl', indent=4) }}
+ {{ include_file('./cddl/vote_tx_v2_private.cddl', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 

docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile

@@ -1,6 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.0 AS cddl-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.1 AS cddl-ci
 
 check-cddl:
  FROM cddl-ci+cddl-base

docs/src/architecture/08_concepts/immutable_ledger/ledger.md

@@ -114,7 +114,7 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati
 ??? note "Block CDDL definition: `block.cddl`"
 
  ```CDDL
- {{ include_file('src/architecture/08_concepts/immutable_ledger/cddl/block.cddl', indent=4) }}
+ {{ include_file('./cddl/block.cddl', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 

docs/src/architecture/08_concepts/signed_doc/cddl/Earthfile

@@ -1,8 +1,8 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.0 AS cddl-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.1 AS cddl-ci
 
-check-cddl:
+todo-check-cddl:
  FROM cddl-ci+cddl-base
 
  WORKDIR /cddl

docs/src/architecture/08_concepts/signed_doc/cddl/collaborators.cddl

@@ -0,0 +1,8 @@
+; collaborators
+
+
+; Allowed Collaborators on the next subsequent version of a document.
+collaborators = [ * catalyst_id_kid ]
+
+; UTF8 Catalyst ID URI encoded as a bytes string.
+catalyst_id_kid = bytes

docs/src/architecture/08_concepts/signed_doc/cddl/document_id.cddl

@@ -0,0 +1,8 @@
+; Unique Document Identifier
+
+
+; Document ID
+document_id = uuid_v7
+
+; UUIDv7
+uuid_v7 = #6.37(bytes .size 16)

docs/src/architecture/08_concepts/signed_doc/cddl/document_ref.cddl

@@ -0,0 +1,27 @@
+; document_ref
+
+
+; Reference to another Signed Document
+document_ref = [ 1* [
+ document_id,
+ document_ver,
+ document_locator
+] ]
+
+; Document ID
+document_id = uuid_v7
+
+; UUIDv7
+uuid_v7 = #6.37(bytes .size 16)
+
+; Document Version
+document_ver = uuid_v7
+
+; Where a document can be located, must be a unique identifier.
+document_locator = {
+ "cid" => cid
+}
+
+; IPLD content identifier
+; TODO: add size limits if possible
+cid = #6.42(bytes)

docs/src/architecture/08_concepts/signed_doc/cddl/document_type.cddl

@@ -0,0 +1,8 @@
+; Unique Document Type Identifier
+
+
+; Document Type
+document_type = [ 1* uuid_v4 ]
+
+; UUIDv4
+uuid_v4 = #6.37(bytes .size 16)

docs/src/architecture/08_concepts/signed_doc/cddl/document_ver.cddl

@@ -0,0 +1,8 @@
+; Unique Chronological Document Version Identifier
+
+
+; Document Version
+document_ver = uuid_v7
+
+; UUIDv7
+uuid_v7 = #6.37(bytes .size 16)

docs/src/architecture/08_concepts/signed_doc/cddl/revocations.cddl

@@ -0,0 +1,11 @@
+; revocations
+
+
+; List of revoked versions of this document.
+revocations = [ * document_ver ] / true
+
+; Document Version
+document_ver = uuid_v7
+
+; UUIDv7
+uuid_v7 = #6.37(bytes .size 16)

docs/src/architecture/08_concepts/signed_doc/cddl/section_ref.cddl

@@ -0,0 +1,8 @@
+; section_ref
+
+
+; Reference to a section in a referenced document.
+section_ref = json_pointer
+
+; RFC6901 Standard JSON Pointer
+json_pointer = text