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:

telescope8<byron, shelley, allegra, mary, alonzo, babbage, conway, dijkstra>
  = [pastEra, pastEra, pastEra, pastEra, pastEra, pastEra, pastEra, currentEra<dijkstra>] /
    [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>]

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

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:

;; Blockchain types
pastEra = [bound, bound]
currentEra<st> = [bound, st]
bound = [relativeTime, slotno, epochno]
eraIdx = word8
individualPoolStake = [stake, hash]
nonce = [0] / [1, hash]
point = [] / [ slotno, hash ]
poolDistr = map<keyhash, individualPoolStake>
slotno = word64
roundno = word64
stake = rational

withOrigin<v> = [] / [v]

;; Collections
either<x, y> = [0, x] / [1, y]
map<x, y> = { * x => y }
maybe<x> = [] / [x]
seq<x> = [*23 x] / [24* x] ; encoded with indefinite-length encoding
set<x> = #6.258([* x])

;; Types from other packages
blockno = word64
epochno = word64
coin = word64
rational = [int, int]
keyhash = bstr .size 28
hash = bstr .size 32
relativeTime = int

;; Base word types
word8  = uint .size 1
word16 = uint .size 2
word32 = uint .size 4
word64 = uint .size 8

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