IntersectMBO / IntersectMBO/ouroboros-network

Comprehensive information about Cardano wire protocol

Open
#5,049 1 comment 1 reaction 0 assignees View on GitHub
consensus documentation PI-9
Dominant language
Haskell
Stars
296
Forks
104
Avg merge
2d 10h
Merged PRs (30d)
4

Description

# 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.

[network-spec]: https://ouroboros-network.cardano.intersectmbo.org/pdfs/network-design
[cardano-ledger]: https://github.com/IntersectMBO/cardano-ledger
[ouroboros-network]: https://github.com/IntersectMBO/ouroboros-consensus
[ouroboros-consensus]: https://github.com/IntersectMBO/ouroboros-network
[ChainSync]: https://ouroboros-network.cardano.intersectmbo.org/ouroboros-network-protocols/Ouroboros-Network-Protocol-ChainSync-Type.html#t:ChainSync

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.