Codec basics

Common encoding format and binary interface description used across blueprints.

CBOR

TODO: justify the use of CBOR and briefly describe it. Mention cbor2diag.rb and related tools. (I believe it is the cbor-tools Ruby gem).

CDDL

CDDLs are often times the combination of partial CDDLs definitions from Network, Consensus and Ledger layers. To combine all these, we will make use of the cddlc tool specified in this RFC. This tool provide meaning to the ;# import and ;# include directives to have a modular system over CDDL definitions.

The CDDL specs presented in this section will make use of the following base definitions that we will consider defined globally:

blockNo = word64
epochNo = word64
slotNo = word64

coin = word64

rational = [int, int]

keyhash = bstr .size 28
hash = bstr .size 32

relativeTime = int

; Words
word8  = uint .size 1; 1 byte
word16 = uint .size 2; 2 bytes
word32 = uint .size 4; 4 bytes
word64 = uint .size 8; 8 bytes

In addition, we add the following types to represent tag-encoded alternatives, commonly used at the consensus level to encode a different tag for each one of the eras in the Cardano blockchain:

telescope7<byron, shelley, allegra, mary, alonzo, babbage, conway>
  = [pastEra, pastEra, pastEra, pastEra, pastEra, pastEra, currentEra<conway>] /
    [pastEra, pastEra, pastEra, pastEra, pastEra, currentEra<babbage>] /
    [pastEra, pastEra, pastEra, pastEra, currentEra<alonzo>] /
    [pastEra, pastEra, pastEra, currentEra<mary>] /
    [pastEra, pastEra, currentEra<allegra>] /
    [pastEra, currentEra<shelley>] /
    [currentEra<byron>]

ns7<byron, shelley, allegra, mary, alonzo, babbage, conway>
  = [6, conway] /
    [5, babbage] /
    [4, alonzo] /
    [3, mary] /
    [2, allegra] /
    [1, shelley] /
    [0, byron]

These definitions are made available in the base.cddl file which we will import qualified with ;# import base as base.

On the other side, Ledger CDDL specs are fully self-contained for each era, hence there are repetitions of basic types, which we will bring in qualified by the era name. We will usually import the Ledger CDDLs as:

;# include byron as byron
;# include shelley as shelley
;# include allegra as allegra
;# include mary as mary
;# include alonzo as alonzo
;# include babbage as babbage
;# include conway as conway