Crafting the Filecoin Spec
Yiannis Psaras ·Hugo Dias
About this talk
Yiannis Psaras and Hugo Dias describe the multi-month effort to rebuild the Filecoin specification at spec.filecoin.io as a single source of truth spanning theory, implementation, and testing across an open-source project with many external contributors. Yiannis covers the content side, including health-monitoring dashboards that track section-level status (stable, reliable, work-in-progress), links to internal and external audit reports, an implementation-agnostic dashboard pulling CI status and test coverage from Lotus, Venus, Forest, and other clients, and a stabilization progress bar showing over 80% of sections at stable/reliable. Hugo then walks through the tooling built around three goals — easy (plain Markdown authoring with `npm start` live preview or direct GitHub editing), consistent (validation, link checking, and formatting enforced via CI), and enabling (advanced features like GitHub symbol-lookup embeds with comment extraction that keep spec text in sync with implementation source, Mermaid and GraphViz diagram pipelines, and KaTeX math rendering). They close with planned work on FIP-driven versioning and surfacing Oni team test results directly inside the spec website.