docs: Voting ledger design (#709)

* add initial ledger schema * add blake tags specefication * update block structure * cleanup * update * fix * fix CI * fix spelling * fix * fix * wip * fix * wip * add image * fix * fix * wip * wip * fix * fix * wip * fix * fix * fix * fix CI * fix cddl * fix spelling * Update docs/src/architecture/08_concepts/immutable_ledger/ledger.md Co-authored-by: bkioshn <[email protected]> * Update docs/src/architecture/08_concepts/immutable_ledger/ledger.md Co-authored-by: bkioshn <[email protected]> * Update docs/src/architecture/08_concepts/immutable_ledger/ledger.md Co-authored-by: bkioshn <[email protected]> * fix * cleanup * update from feedback --------- Co-authored-by: bkioshn <[email protected]> Co-authored-by: Steven Johnson <[email protected]> Co-authored-by: Oleksandr Prokhorenko <[email protected]>
input-output-hk · Sep 19, 2024 · fc7943a · fc7943a
1 parent 2d32951
commit fc7943a
Show file tree

Hide file tree

Showing 10 changed files with 1,730 additions and 0 deletions.
diff --git a/cspell.json b/cspell.json
@@ -157,6 +157,7 @@
         ".config/dictionaries/cspell/markdown/cspell-ext.json"
     ],
     "ignorePaths": [
+        "*.excalidraw",
         ".config/dictionaries/**",
         "tmp/**",
         "cspell.json",

diff --git a/docs/src/architecture/08_concepts/immutable_ledger/.pages b/docs/src/architecture/08_concepts/immutable_ledger/.pages
@@ -0,0 +1,3 @@
+title: Immutable Ledger
+arrange:
+ - ledger.md
diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl
@@ -0,0 +1,31 @@
+block = [
+    block_header,
+    block_data: ~encoded-cbor, ; deterministically encoded CBOR
+    validator_signature,
+]
+
+block_header = [
+    chain_id: ULID,
+    height: int,
+    timestamp: ~#6.1(uint .ge 1722470400), ; Epoch-based date/time
+    prev_block_id: hash_bytes, ; hash of the previous block
+    ?ledger_type: UUID,
+    ?purpose_id: ULID / UUID,
+    ?validator,
+    ~metadata,
+]
+
+UUID = #6.37(bytes) ; UUID type
+ULID = #6.32780(bytes) ; ULID type
+
+hash_bytes = (
+  #6.32781(bytes) \ ; Blake3 hash
+  #6.32782(bytes) \ ; Blake2b hash
+  #6.32783(bytes) ; Blake2s hash
+)
+kid = hash_bytes ; hash of the x509/c509 certificate
+
+validator = (kid / [2* kid])
+metadata = [ *Any ]
+
+validator_signature = (bytes / [2* bytes])
diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl
@@ -0,0 +1,18 @@
+genesis_to_prev_hash = [
+    chain_id: ULID,
+    timestamp: ~#6.1(uint .ge 1722470400), ; Epoch-based date/time
+    ledger_type: UUID,
+    purpose_id: ULID / UUID,
+    validator,
+]
+
+UUID = #6.37(bytes) ; UUID type
+ULID = #6.32780(bytes) ; ULID type
+
+validator = (kid / [2* kid])
+kid = hash_bytes ; hash of the x509/c509 certificate
+hash_bytes = (
+  #6.32781(bytes) \ ; Blake3 hash
+  #6.32782(bytes) \ ; Blake2b hash
+  #6.32783(bytes) ; Blake2s hash
+)