Joachim Breitner's Homepage

Two months ago was my last day of working as an employee for DFINITY, and as I mentioned in the previous blog post, one of my main contributions was the introduction and maintenance of the Interface Specification.

Hence I was especially happy to find that my former colleague Hans Larsen has, as a farewell gift and token of appreciation, created a hard copy of the document, with 107 pages of dry technical content that, and a very sweet dedication on the back. This is especially valuable as it came from Lars personally (i.e. it’s not “just” routine HR work to keep former employees happy, which I could imagine to be a thing in big and mature corporations), and despite the fact that he himself has left DFINITY since.

I also take this as further confirmation that this specification-driven design process, despite the initial resistance and daily hurdles, is a good one. A rough list of guiding principles would be:

• Describe the complete interface, not just signatures (schemas), but also semantics (behavior), in one document. The teams on either side of the interface should not need any other information. In particular, they should never have to peek into the other team’s code to see how it works.
• New features or changes are first designed by writing down how they affect the interface specification, discussed on that level with the “other” teams, agreed upon, and then implemented. Treating the document as code and discussing these features on pull requests is helpful here. Depending on how quickly DFINITY becomes more open, we may get to see that happening on the currently internal ic-ref repository.
• The interface semantics is described not just using possibly ambiguous or incomplete prose, but also a comprehensive formalism. That formalism is ideally mechanized, but pseudo-math is better than nothing.
• The interface is implemented more than once (e.g. a prototype reference implementation, and the production implementation) to keep the implementations honest.
• Dually, the interface has more than one consumer, one ideally being a executable test suite that is implementation-agnostic.

The similarity to the concept of “deep specifications” from the DeepSpec project is indeed striking.

One of my hopes at DFINITY was that these principles would catch on and that other components (e.g the NNS, the nodes or the ICP ledger canister) would follow suite. That did not happen, it seems. Or rather, it did not happen yet…

PS, in case you are wondering how: The rendering of the document that’s shown at at https://sdk.dfinity.org/docs/interface-spec/index.html is not great; the internal website had a different style with made navigating this large document more possible, as it was a dedicated site with the document’s nested table of content on the left.