Ouroboros mini-protocols full specification

[scarmuega]

Several tools in the Cardano developer ecosystem rely on direct access to the node using Ouroboros mini-protocols. Most of the wire-format is fully defined by the spec, except for certain messages which are specific to the Cardano ledger implementation.

In particular, ATM, we lack information regarding:

• the "Local Tx-Submission" mini-protocol specification skips the definitions for the rejection reason message.
• the "Local State Query" mini-protocol specification skips the definitions for the query and result messages.

Several teams attempted to reverse-engineering the Haskell code or intercept wire data to infer the CBOR structures. This is a complex and error-prone process that doesn't scale. On top of that, each cardano-node version might potentially change / augment these definitions.

This is an example of a community-driven effort to document the local-state-query mini-protocol:
https://arsmagna.xyz/docs/network-lsq/

Having a well-documented and up-to-date spec (message flows, CDDL, etc) would simplify the process of building & maintaining client libraries and tools for low-level interaction with the node.