Non-LaTeX specification format

[ch1bo]

Why

The Hydra protocol for creating state channels on Cardano should be an open standard, that is understandable and amenable by all interested contributors. For that the protocol specification needs to be easily approachable with a defined change process. A single PDF as a technical spec is not that great to explore and refer to.

What

We started work in this direction by creating a specification from the original paper (trimmed down, removing novelties, only one version) and integrating it into the hydra repository in this item.

However, the current status quo is still using "raw" LaTeX as the source of the specification and produces a PDF on the website.

A good example of an open and living specification is the BOLT spec of the lightning network. Another, more documentation focused example is ZKDocs. Something in-between is what we should aim for.

How

ZKDocs is using a static site generator that is extended for some latex capability. We could explore the same approach with docusaurus by converting the text to markdown and keeping the math LaTeX-like. pandoc is usually good at this. Also the flake template templates#pandoc-xelatex (nix flake init --template templates#pandoc-xelatex) does show how to build a LaTeX pdf from markdown. It should be possible to have both options from this source.