Comprehensive information about Cardano wire protocol

[coot]

Problem statement

The goal is to make the Cardano wire protocol more accessible and thus easier to integrate against. Right now, we provide CDDL specifications for node-to-node and node-to-client protocols, but they are polymorphic and thus, data structures like blocks, headers, and transactions are not specified. The ledger provides CDDL specs for all data structures in all eras, which are glued by the hard fork combinator, which is informally specified in network-spec.

Requirements

We want a solution which:

1. provides clarity for the Cardano developers,
2. can be easily maintained and evolves as Cardano develops,
3. can be provided reasonably, without locking too much dev time

Full CDDL Spec - not a solution

A full CDDL spec would provide clarity for developers, but we believe that satisfying 2. & 3. at the same time is not possible. Cardano is split by three largely independent components: ledger, consensus & network; the development happens mostly independently in all three areas, and this is also reflected how the code is split into three repositories: cardano-ledger, ouroboros-consensus, ouroboros-network. Two satisfy 3, one needs to check the CDDL spec against the reference implementation - something we do in ouroboros-network and cardano-ledger repositories.

Proposed solution

We propose to specify in a pseudo code (how all polymorphic type variables are instantiated, e.g. what header is in the ChainSync mini-protocol. I suspect that generating this information from the code will reveal too much low-level detail about the HFC. This gives us the opportunity to explain the HFC in this context.

Then, we shall maintain tables with links to the ledger CDDL spec for each era.