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