Open specification with change process

[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 great to explore and refer to.

What

A good example of such 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.

Currently the specification is a LaTeX document with source on Github https://github.com/ch1bo/hydra-spec and collaborative editing available via overleaf https://www.overleaf.com/4615313757crxctwbwjtrf. This was very helpful in the initial writing and reviewing of the protocol.

We want the specification to be

• reviewable / commentable on
• explorable
• Can be referred to
• have multiple versions
• changes an be proposed

To make the protocol more approachable, we need to make it available on the website and changes to it should follow a pull-request practice:

• The LaTeX PDF is available on the https://hydra.family/head-protocol/ website
• The introduction to the specification also documents how to propose changes to it
• Out of scope (unless super simple to do) is a more interactive rendering similar to https://www.zkdocs.com/docs/zkdocs/notation/ is available on the website (on top of a LaTeX PDF)

How

• A Github action building the PDF via nix should be trivial. A flake with texlive in a dev shell is available in https://github.com/ch1bo/hydra-spec/blob/main/flake.nix and building it should just be something like pdflatex -file-line-error --synctex=1 -interaction=nonstopmode main.tex

• Add spec to repository and website #833 to the repository
• Do a first contribution to the spec PR on hydra Unmark red items which were addressed in #777 #836
• Create follow-up Idea

---

Out of scope ideas:

• 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.
• Could monitor the page download to check whether spec is used by community

TBD

• How does this relate to the CIP process?

[ch1bo]

Moved out of scope ideas into this discussion #843.