From 165a2ee807bd276d0019937666208f9168793165 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 19:34:29 +0200 Subject: [PATCH] fix immutable ledger cddl definitions --- .../immutable_ledger/cddl/Earthfile | 3 +- .../immutable_ledger/cddl/block.cddl | 15 +++--- .../cddl/genesis_to_prev_hash.cddl | 19 ++++---- .../immutable_ledger/cddl/hash.cddl | 5 ++ .../08_concepts/immutable_ledger/ledger.md | 46 +++++++++---------- 5 files changed, 44 insertions(+), 44 deletions(-) create mode 100644 docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile index 1b863ba5f8..c9c7ac1145 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile @@ -7,7 +7,8 @@ check-cddl: WORKDIR /cddl - COPY ./block.cddl ./genesis_to_prev_hash.cddl . + COPY ./block.cddl ./genesis_to_prev_hash.cddl ./hash.cddl . + RUN cddlc -2 hash.cddl RUN cddlc -2 block.cddl RUN cddlc -2 genesis_to_prev_hash.cddl diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl index 048d653534..d65f0fc78a 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl @@ -1,14 +1,14 @@ block = [ - block_header, + block-header, block-data, validator-signature, ] -block_header = [ +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 + prev-block-id: hash-bytes, ; hash of the previous block ?ledger-type: UUID, ?purpose-id: ULID / UUID, ?validator, @@ -20,14 +20,11 @@ block-data = encoded-cbor 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 +kid = hash-bytes ; hash of the x509/c509 certificate validator = (kid / [2* kid]) metadata = [ *any ] validator-signature = (bytes / [2* bytes]) + +;# include hash 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 index f6b22766eb..c30ecbf995 100644 --- 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 @@ -1,8 +1,8 @@ -genesis_to_prev_hash = [ - chain_id: ULID, - timestamp: ~#6.1(uint .ge 1722470400), ; Epoch-based date/time - ledger_type: UUID, - purpose_id: ULID / UUID, +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, ] @@ -10,9 +10,6 @@ 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 -) \ No newline at end of file +kid = hash-bytes ; hash of the x509/c509 certificate + +;# include hash diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl new file mode 100644 index 0000000000..32ca39ae72 --- /dev/null +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl @@ -0,0 +1,5 @@ +hash-bytes = ( + #6.32781(bytes) / ; Blake3 hash + #6.32782(bytes) / ; Blake2b hash + #6.32783(bytes) ; Blake2s hash +) diff --git a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md index b2a5396679..af4cb2c95b 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md +++ b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md @@ -82,17 +82,17 @@ Which is well suited where it comes to process some temporary event e.g. voting. Header: -* `chain_id` - unique identifier of the chain. +* `chain-id` - unique identifier of the chain. * `height` - block's height. Also is used to identify the block type: *genesis*, *regular*, *final* (in more details described in [validation section](#block-validation-rules)). * `timestamp` - block's timestamp. -* `prev_block_id` - previous block hash. -* `ledger_type` - unique identifier of the ledger type. - In general, this is the way to strictly bound and specify `block_data` of the ledger for the specific `ledger_type`. +* `prev-block-id` - previous block hash. +* `ledger-type` - unique identifier of the ledger type. + In general, this is the way to strictly bound and specify `block-data` of the ledger for the specific `ledger-type`. But such rules will be a part of the specific ledger type definition, and not specified by this document. -* `purpose_id` - unique identifier of the purpose. +* `purpose-id` - unique identifier of the purpose. As it was stated before, each Ledger instance will have a strict time boundaries, so each of them will run for different purposes. @@ -102,13 +102,13 @@ Header: Block: -* `block_header` - block header described above, -* `block_data` - an array of some CBOR encoded data -* `validator_signature` - a signature or signatures of the validator's. +* `block-header` - block header described above, +* `block-data` - an array of some CBOR encoded data +* `validator-signature` - a signature or signatures of the validator's. ### Block validation rules -* `chain_id` **MUST** be the same as for the previous block (except for genesis). +* `chain-id` **MUST** be the same as for the previous block (except for genesis). * `height` **MUST** be incremented by `1` from the previous block height value (except for genesis and final block). *Genesis* block **MUST** have `0` value. *Final* block **MUST** hash be incremented by `1` from the previous block height and changed the sign to negative. @@ -116,25 +116,25 @@ Block: * *Final* block is the last one for the specific chain and any other block could not be referenced to the *Final* one. * `timestamp` **MUST** be greater or equals than the `timestamp` of the previous block (except for genesis). -* `prev_block_id` **MUST** be a hash of the previous block bytes (except for genesis). +* `prev-block-id` **MUST** be a hash of the previous block bytes (except for genesis). -* `ledger_type` **MUST** be the same as for the previous block if present (except for genesis). +* `ledger-type` **MUST** be the same as for the previous block if present (except for genesis). **MANDATORY** field for *Genesis* and *Final* blocks. -* `purpose_id` **MUST** be the same as for the previous block if present (except for genesis). +* `purpose-id` **MUST** be the same as for the previous block if present (except for genesis). **MANDATORY** field for *Genesis* and *Final* blocks. * `validator` **MUST** be the same as for the previous block if present (except for genesis). **MANDATORY** field for *Genesis* and *Final* blocks. -* `prev_block_id`'s CBOR tag value and `bstr` size **MUST** be the same as for the previous block (except for genesis). +* `prev-block-id`'s CBOR tag value and `bstr` size **MUST** be the same as for the previous block (except for genesis). Means that the hash function type and hash size itself must be the same. -* `prev_block_id` and `validator_signature` **MUST** use the same hash function, defined with the - `hash_bytes`. +* `prev-block-id` and `validator-signature` **MUST** use the same hash function, defined with the + `hash-bytes`. -* `prev_block_id` for the *Genesis* block **MUST** be a hash of the `genesis_to_prev_hash` bytes. +* `prev-block-id` for the *Genesis* block **MUST** be a hash of the `genesis-to-prev-hash` bytes. -* `block_data` **MUST** be a [deterministically][CBOR-deterministically-encoded] encoded CBOR. +* `block-data` **MUST** be a [deterministically][CBOR-deterministically-encoded] encoded CBOR. -??? note "Genesis to previous block hash CDDL definition: `genesis_to_prev_hash.cddl`" +??? note "Genesis to previous block hash CDDL definition: `genesis-to-prev-hash.cddl`" ```CDDL {{ include_file('src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl',indent=4) }} @@ -143,16 +143,16 @@ Block: #### Signature rules -`validator_signature` -**MUST** be a signature of the hashed `block_header` bytes and the `block_data` bytes +`validator-signature` +**MUST** be a signature of the hashed `block-header` bytes and the `block-data` bytes (with the order the same as defined for `block`). Signed by the validator's keys defined in the corresponding certificates referenced by the `validator`. Signature algorithm is defined by the certificate. The format and size of this field **MUST** be totally the same as `validator` field: -* if `validator` is only one id => `validator_signature` contains only 1 signature; -* if `validator` is array => `validator_signature` contains an array with the same length; -* order of signatures from the `validator_signature`'s array corresponds to the validators order of `validator`'s array. +* if `validator` is only one id => `validator-signature` contains only 1 signature; +* if `validator` is array => `validator-signature` contains an array with the same length; +* order of signatures from the `validator-signature`'s array corresponds to the validators order of `validator`'s array. ## Rationale