Skip to content

Immutable Ledger Design

Title: Immutable Ledger Design

Status: Proposed

Authors: - Alex Pozhylenkov alex.pozhylenkov@iohk.io

Created: 2024-08-19

Abstract

This document describes a specification of the immutable ledger for various purposes of project "Catalyst".

Motivation

Project "Catalyst" requires a solution for storing people votes and any other data, in a transparent, verifiable, scalable and immutable way.

Specification

Ledger structure

Ledger schema

Ledger will be represented as a collection of distinct, unconnected chains, processed and run in parallel. The only common thing for all these chains will be a "tree" identifier, so these chains will serve and form an overall ledger state.

Obviously, given approach leads to data duplication, as each chain, will not know anything about others. And it also requires that the overall ledger state, could be deterministically defined at any point of time, considering potential transaction overlapping or duplication.

To achieve an immutability of data inside each chain Each particular chain, will be a common sequence of blocks. To achieve an immutability of data inside each chain, cryptographic hashing is applied. So each block from the chain reference to the hash of previous one. It is a widely used technic to prevent a modification of some data from previous blocks, without affecting structure of the current one.

The described approach allows to easily scale and increase throughput of the network on demand at any time, just by starting to process new chains.


Temporary chains

Temporary chain schema

It's a common thing for blockchains to have a starting block (genesis), but it's unusual to have a final block for a chain. After which no any block could be produced.

And that's a main distinguish for this Immutable Ledger design, it has a final block.

So any chain will be bounded by some period of time. Which is well suited where it comes to process some temporary event e.g. voting.


Block structure

Immutable ledger block is a Catalyst Signed Document, so its fully follows the structure of the Catalyst Signed Document specification.

Metadata Fields

  • id. Used as a unique identifier of the chain. So all blocks from the same chain must have the same id field value.
  • ver. Used as a unique identifier of the block itself. Also the block's creation timestamp value is determined from the ver field.
  • content type: application/cbor. Catalyst Signed Document content must be a CBOR encoded.
3 => 50

"content-type" => "br"
  • type: d9e7e6ce-2401-4d7d-9492-f4f7c64241c3 [UUID] value.
"type" => 37(h'D9E7E6CE24014D7D9492F4F7C64241C3')

Content format

Block CDDL definition: block.cddl 
; All encoders/decoders of this specification must follow deterministic cbor encoding rules
; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06

block = [
    block-header,
    block-data,
]

block-header = [
    height: int,
    ?ledger-type: UUID, ; UUID v4
    ?purpose-id: UUID, ; UUID v7
    ~extra-header-data,
]

block-data = encoded-cbor

UUID = #6.37(bytes) ; UUID type

kid = hash-bytes ; hash of the x509/c509 certificate

extra-header-data = [ *any ]

;# include hash

Header:

  • height - block's height. Also is used to identify the block type: genesis, regular, final (in more details described in validation section).
  • 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. As it was stated before, each Ledger instance will have a strict time boundaries, so each of them will run for different purposes. This is the way to distinguish them.
  • extra-header-data - fully optional field, to add some arbitrary data to the block header.

Block:

  • block-header - block header described above,
  • block-data - an array of some CBOR encoded data

Block validation rules

  • 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. E.g. previous block height is 9 and the Final block height is -10.

  • Final block is the last one for the specific chain and any other block could not be referenced to the Final one.

  • ver timestamp value MUST be greater or equals than the corresponding timestamp of the previous block (except for genesis).

  • ref_hash MUST be a reference to the previous block (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). MANDATORY field for Genesis and Final blocks.
  • kid field MUST be the same as for the previous block (except for genesis).
  • ref_hash's hash-bytes CBOR tag value and bytes 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.
  • ref_hash field for the Genesis block MUST be omitted.
  • block-data MUST be a deterministically encoded CBOR.

Rationale

Path to Active

Acceptance Criteria

Implementation Plan