{"id":13632765,"url":"https://github.com/filecoin-project/specs","last_synced_at":"2025-04-18T05:33:16.446Z","repository":{"id":34484742,"uuid":"159554854","full_name":"filecoin-project/specs","owner":"filecoin-project","description":"The Filecoin protocol specification","archived":false,"fork":false,"pushed_at":"2024-10-31T08:09:44.000Z","size":22802,"stargazers_count":367,"open_issues_count":220,"forks_count":170,"subscribers_count":54,"default_branch":"master","last_synced_at":"2024-10-31T08:18:48.687Z","etag":null,"topics":["fil","filecoin-protocol","filecoin-specification","spec","specification"],"latest_commit_sha":null,"homepage":"https://spec.filecoin.io","language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filecoin-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-28T19:36:35.000Z","updated_at":"2024-10-31T08:09:33.000Z","dependencies_parsed_at":"2023-02-10T09:31:30.742Z","dependency_job_id":"8f57bf37-73ab-4058-b9da-cb56bb21d886","html_url":"https://github.com/filecoin-project/specs","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filecoin-project%2Fspecs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filecoin-project%2Fspecs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filecoin-project%2Fspecs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filecoin-project%2Fspecs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filecoin-project","download_url":"https://codeload.github.com/filecoin-project/specs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223775245,"owners_count":17200481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fil","filecoin-protocol","filecoin-specification","spec","specification"],"created_at":"2024-08-01T22:03:15.189Z","updated_at":"2024-11-09T01:30:48.069Z","avatar_url":"https://github.com/filecoin-project.png","language":"SCSS","readme":"# Filecoin Specification\n\n![CI](https://github.com/filecoin-project/specs/workflows/CI/badge.svg)\n\nThis is the [Filecoin Specification](https://github.com/filecoin-project/specs), a repository that contains documents, code, models, and diagrams that constitute the specification of the [Filecoin Protocol](https://filecoin.io). This repository is the singular source of truth for the Filecoin Protocol. All implementations of the Filecoin Protocol should match and comply with the descriptions, interfaces, code, and models defined in this specification.\n\n\u003chttps://spec.filecoin.io\u003e is the user-friendly website rendering, which we recommend for reading this repository. The website is updated automatically with every merge to `master`.\n\n## Table of Contents\n\n- [Install](#install)\n- [Writing the spec](#writing-the-spec)\n- [Check your markdown](#check-your-markdown)\n- [Page Template](#page-template)\n- [Code](#code)\n- [Images](#images)\n- [Links](#links)\n- [Shortcodes](#shortcodes)\n  - [`embed`](#embed)\n  - [`listing`](#listing)\n  - [`mermaid`](#mermaid)\n  - [`hint`](#hint)\n  - [`katex`](#katex)\n- [Math mode](#math-mode)\n  - [Wrap `def`, `gdef`, etc.](#wrap-def-gdef-etc)\n  - [Wrap inline math text with code blocks](#wrap-inline-math-text-with-code-blocks)\n  - [Wrap math blocks with code fences](#wrap-math-blocks-with-code-fences)\n- [Front-matter](#front-matter)\n- [References](#references)\n\n## Install\n\nTo build the spec website you need\n\n- [`node` \u0026 `npm`](https://nodejs.org/en/download)\n\nOn macOS you can get node from Homebrew\n\n```bash\nbrew install node\n```\n\nClone the repo, and use `npm install` to fetch the dependencies\n\n```sh\ngit clone https://github.com/filecoin-project/specs.git\nnpm install\n```\n\nTo run the development server with live-reload locally, run:\n\n```sh\nnpm start\n```\n\nThen open \u003chttp://localhost:1313\u003e in the browser\n\n## Writing the spec\n\nThe spec is written in markdown. Each section is markdown document in the `content` directory. The first level of the directory structure denotes the top level sections of the spec; (Introduction, Systems, etc.) The `_index.md` file in each folder is used as the starting point for each section. For example the **Introduction** starts in `content/intro/_index.md`.\n\nSections can be split out into multiple markdown documents. The build process combines them into a single html page. The sections are ordered by the `weight` front-matter property. The introduction appears at the start of the html page because `content/intro/_index.md` has `weight: 1`, while `content/systems/_index.html` has `weight: 2` so it appears as the second section.\n\nYou can split out sub-sections by adding additional pages to a section directory. The `content/intro/concepts.md` defines the Key Concepts sub-section of the the Introduction. The order of sub-sections within a section is again controlled by setting the `weight` property. This pattern repeats for sub sub folders which represent sub sub sections.\n\nThe markdown documents should all be well formed, with a single h1, and headings should increment by a single level.\n\n\u003e Note: Regular markdown files like `content/intro/concepts.md` can't reference resources such as images, or other files. Such resources can be referenced only from `_index.md` files. Given that a folder will have an `_index.md` file already, there is the following work around to reference resources from any file: create a new sub-folder in the same folder where the initial .md file was, e.g., `content/intro/concepts/_index.md`, include the content from `concepts.md` in the `_index.md` file, add the resource files (for example, images) in the new folder and reference the resource file from the new `_index.md` file inside the `concepts` folder. The referencing syntax and everything else works the same way.\n\n## Check your markdown\n\nUse `npm test` to run a markdown linter and prettier to check for common errors. It runs in CI and you can run it locally with:\n\n```bash\nnpm test\ncontent/algorithms/crypto/randomness.md\n  15:39-15:46  warning  Found reference to undefined definition  no-undefined-references  remark-lint\n  54:24-54:31  warning  Found reference to undefined definition  no-undefined-references  remark-lint\n\n⚠ 2 warnings\n```\n\nFormat errors can be fixed by running `npm run format`.\n\n```bash\nChecking formatting...\n[warn] content/systems/filecoin_token/block_reward_minting.md\n[warn] Code style issues found in the above file(s). Forgot to run Prettier?\n```\n\n## Page Template\n\nA spec document should start with a YAML front-matter section and contain at least a single h1, as below.\n\n```md\n---\ntitle: Important thing\nweight: 1\ndashboardState: wip\ndashboardAudit: missing\n---\n\n# Important thing\n```\n\n## Code\n\nWrap code blocks in _code fences_. Code fences should **always** have a lang. It is used to provide syntax highlighting. Use `text` as the language flag for pseudocode for no highlighting.\n\n````text\n```text\nYour algorithm here\n```\n````\n\nYou can embed source code from local files or external other repos using the `embed` [shortcode](#embed).\n\n```text\n{{\u003cembed src=\"/path/to/local/file/types.go\"  lang=\"go\" symbol=\"Channel\"\u003e}}\n\n{{\u003cembed src=\"https://github.com/filecoin-project/lotus/blob/master/build/bootstrap.go\" lang=\"go\"\u003e}}\n```\n\n## Images\n\nUse normal markdown syntax to include images.\n\nFor `dot` and `mermaid` diagrams you link to the source file and the pipelines will handle converting that to `svg`.\n\n```md\n# relative to the markdown file\n\n![Alt text](picture.jpg)\n\n# relative to the content folder\n\n![Alt text](/content/intro/diagram1.mmd)\n\n![Alt text](graph.dot 'Graph title')\n```\n\n\u003e The alt text is used as the title if not provided.\n\n## Links\n\nUse markdown syntax `[text](markdown-document-name)`.\n\nThese links use \"portable links\" just like `relref`. Just give it the name of the file and it will fetch the correct relative path and title automatically. You can override the title by passing a second `string` in the link definition.\n\n\u003e **Note**: When using anchors the title can't be fetched automatically.\n\n```md\n[](storage_power_consensus)\n\n# Renders to\n\n\u003ca href=\"/systems/filecoin_blockchain/storage_power_consensus\" title=\"Storage Power Consensus\"\u003eStorage Power Consensus\u003c/a\u003e\n\n[Storage Power](storage_power_consensus 'Title to override the page original title')\n\n# Renders to\n\n\u003ca href=\"/systems/filecoin_blockchain/storage_power_consensus\" title=\"Title to override the page original title\"\u003eStorage Power\u003c/a\u003e\n\n[Tickets](storage_power_consensus#the-ticket-chain-and-drawing-randomness 'The Ticket chain and drawing randomness')\n\n# Renders to\n\n\u003ca href=\"/systems/filecoin_blockchain/storage_power_consensus#the-ticket-chain-and-drawing-randomness\" title=\"The Ticket chain and drawing randomness\"\u003eTickets\u003c/a\u003e\n```\n\n## Shortcodes\n\nhugo shortcodes you can add to your markdown.\n\n### `embed`\n\n```md\n# src relative to the page\n\n{{\u003cembed src=\"piece_store.go\" lang=\"go\"\u003e}}\n\n# src relative to content folder\n\n{{\u003cembed src=\"/systems/piece_store.go\" lang=\"go\"\u003e}}\n\n# can just embed a markdown file\n\n{{\u003cembed src=\"section.md\" markdown=\"true\"\u003e}}\n\n# can embed symbols from Go files\n\n# extracts comments and symbol body\n\n{{\u003cembed src=\"types.go\"  lang=\"go\" symbol=\"Channel\"\u003e}}\n\n# can embed from external sources like github\n\n{{\u003cembed src=\"https://github.com/filecoin-project/lotus/blob/master/build/bootstrap.go\" lang=\"go\"\u003e}}\n```\n\nThis shortcode also supports the property `title` to add a permalink below the embed.\n\n### `listing`\n\nThe listing shortcode creates tables from externals sources, supports Go `struct`.\n\n```md\n# src relative to the page\n\n{{\u003clisting src=\"piece_store.go\" symbol=\"Channel\"\u003e}}\n\n# src relative to content folder\n\n{{\u003clisting src=\"/systems/piece_store.go\" symbol=\"Channel\"\u003e}}\n\n# src can also be from the externals repos\n\n{{\u003clisting src=\"/externals/go-data-transfer/types.go\"  symbol=\"Channel\"\u003e}}\n```\n\n### `mermaid`\n\nInline mermaid syntax rendering\n\n```html\n{{\u003c mermaid \u003e}}\ngraph TD\n  A[Christmas] --\u003e|Get money| B(Go shopping)\n  B --\u003e C{Let me think}\n  C --\u003e|One| D[Laptop]\n  C --\u003e|Two| E[iPhone]\n  C --\u003e|Three| F[fa:fa-car Car]\n\n{{\u003c/ mermaid \u003e}}\n```\n\n### `hint`\n\n```md\n\u003c!-- info|warning|danger --\u003e\n\n{{\u003c hint info \u003e}}\n**Markdown content**  \nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\n{{\u003c /hint \u003e}}\n```\n\n### `katex`\n\nWe should **only** use `inline` mode for now! Display mode has a bug and is not responsive the formulas don't break in small screen. Track: \u003chttps://github.com/KaTeX/KaTeX/issues/2271\u003e\n\n```md\n\u003c!-- Use $ math $ for inline mode--\u003e\n\n{{\u003ckatex\u003e}}\n$SectorInitialConsensusPledge = \\\\[0.2cm] 30\\% \\times FILCirculatingSupply \\times \\frac{SectorQAP}{max(NetworkBaseline, NetworkQAP)}$\n{{\u003c/katex \u003e}}\n\n\u003c!-- Use $$ math $$ for display mode--\u003e\n\n{{\u003ckatex\u003e}}\n$$SectorInitialConsensusPledge = \\\\[0.2cm] 30\\% \\times FILCirculatingSupply \\times \\frac{SectorQAP}{max(NetworkBaseline, NetworkQAP)}$$\n{{\u003c/katex \u003e}}\n```\n\n## Math mode\n\nFor short snippets of math text (e.g., inline reference to parameters, or single formulas) it is easier to use the `{{\u003ckatex\u003e}}`/`{{/katex}}` shortcode (as described just [above](specs#katex)). Check how KaTeX parses math typesetting [here](https://katex.org/docs/api.html).\n\nFor extensive blocks of math content it is more convenient to use `math-mode` to avoid having to repeat the katex shortcode for every math formula.\n\nCheck this example [example](https://spec.filecoin.io/math-mode/)\n\n\u003e Some syntax like `\\_` can't go through HUGO markdown parser and for that reason we need to wrap math text with code blocks, code fendes or the shortcode `{{\u003cplain\u003e}}`. See examples below.\n\u003e\n\u003e ### Add `math-mode` prop to the Frontmatter\n\u003e\n\u003e ```md\n\u003e ---\n\u003e title: Math Mode\n\u003e math-mode: true\n\u003e ---\n\u003e ```\n\n### Wrap `def`, `gdef`, etc.\n\nMath text needs to be wrapped to avoid Hugo's Markdown parser. When wrapping defs or any math block that doesn't need to be rendered the recommended option is to use the shortcode `{{\u003cplain hidden}}` with the hidden argument.\n\n```md\n{{\u003cplain hidden\u003e}}\n\n$$\n\\gdef\\createporepbatch{\\textsf{create_porep_batch}}\n\\gdef\\GrothProof{\\textsf{Groth16Proof}}\n\\gdef\\Groth{\\textsf{Groth16}}\n\\gdef\\GrothEvaluationKey{\\textsf{Groth16EvaluationKey}}\n\\gdef\\GrothVerificationKey{\\textsf{Groth16VerificationKey}}\n{{\u003c/plain\u003e}}\n$$\n```\n\n### Wrap inline math text with code blocks\n\n```md\nThe index of a node in a `$\\BinTree$` layer `$l$`. The leftmost node in a tree has `$\\index_l = 0$`.\n```\n\n### Wrap math blocks with code fences\n\n````md\n```text\n$\\overline{\\underline{\\Function \\BinTree\\dot\\createproof(c: \\NodeIndex) \\rightarrow \\BinTreeProof_c}}$\n$\\line{1}{\\bi}{\\leaf: \\Safe = \\BinTree\\dot\\leaves[c]}$\n$\\line{2}{\\bi}{\\root: \\Safe = \\BinTree\\dot\\root}$\n\n$\\line{3}{\\bi}{\\path: \\BinPathElement^{[\\BinTreeDepth]}= [\\ ]}$\n$\\line{4}{\\bi}{\\for l \\in [\\BinTreeDepth]:}$\n$\\line{5}{\\bi}{\\quad \\index_l: [\\len(\\BinTree\\dot\\layer_l)] = c \\gg l}$\n$\\line{6}{\\bi}{\\quad \\missing: \\Bit = \\index_l \\AND 1}$\n$\\line{7}{\\bi}{\\quad \\sibling: \\Safe = \\if \\missing = 0:}$\n$\\quad\\quad\\quad \\BinTree\\dot\\layer_l[\\index_l + 1]$\n$\\quad\\quad\\thin \\else:$\n$\\quad\\quad\\quad \\BinTree\\dot\\layer_l[\\index_l - 1]$\n$\\line{8}{\\bi}{\\quad \\path\\dot\\push(\\BinPathElement \\thin \\{\\ \\sibling, \\thin \\missing\\ \\} \\thin )}$\n\n$\\line{9}{\\bi}{\\return \\BinTreeProof_c \\thin \\{\\ \\leaf, \\thin \\root, \\thin \\path\\ \\}}$\n```\n````\n\n## Front-matter\n\nDescription for all the available frontmatter properties\n\n```yaml\n# Page Title to be used in the navigation\ntitle: Libraries\n# Small description for html metadata, if not present the first couple of paragraphs will be used instead\ndescription: Libraries used from Filecoin\n# This will be used to order the ToC, navigation and any other listings of pages\nweight: 3\n# This will make a page section collapse in the navigation\nbookCollapseSection: true\n# This will hidden the page from the navigation\nbookhidden: true\n# This is used in the dashboard to describe the importance of the page content\ndashboardWeight: 2\n# This is used in the dashboard to describe the state of the page content options are \"missing\", \"incorrect\", \"wip\", \"reliable\", \"stable\" or \"n/a\"\ndashboardState: stable\n# This is used in the dashboard to describe if the theory of the page has been audited, options are \"missing\", \"wip\", \"done\" or \"n/a\"\ndashboardAudit: wip\n# When dashboardAudit is stable we should have a report url\ndashboardAuditURL: https://url.to.the.report\n# The date that the report at dashboardAuditURL was completed\ndashboardAuditDate: '2020-08-01'\n# This is used in the dashboard to describe if the page content has compliance tests, options are 0 or numbers of tests\ndashboardTests: 0\n```\n\n## References\n\n- [hugo theme book](https://themes.gohugo.io//theme/hugo-book/docs/shortcodes/columns/)\n- [Katex](https://katex.org/)\n- [Mermaid](https://mermaid-js.github.io/mermaid/#/)\n  - [config](https://github.com/mermaid-js/mermaid/blob/master/docs/mermaidAPI.md#mermaidapi-configuration-defaults)\n  - [editor](https://mermaid-js.github.io/mermaid-live-editor)\n- [Pan/Zoom for SVG](https://github.com/anvaka/panzoom)\n- [Icons](https://css.gg/)\n","funding_links":[],"categories":["Decentralized Storage Platforms","SCSS","Web 3.0"],"sub_categories":["Filecoin"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilecoin-project%2Fspecs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilecoin-project%2Fspecs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilecoin-project%2Fspecs/lists"}