This is the Filecoin Specification, a repository that contains documents, code, models, and diagrams that constitute the specification of the Filecoin Protocol. 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.
Note that the beta branch of the specs moves quickly. We work to merge PRs as fast as possible into master, which means changes or reversals are possible here. Accordingly, we periodically compile swaths of spec along with a high-level difflog into the release branch. As the spec stabilizes, this practice will change.
https://beta.spec.filecoin.io is the user-friendly website rendering, which we recommend for reading this repository. The website is updated automatically with every merge to beta.
You can find the previous version of the Filecoin Spec in the master branch here.
git clone https://github.com/filecoin-project/specs.git
yarn installYou need to have Go installed https://golang.org/doc/install
brew install goyarn serve
# open http://localhost:1313/ in the browserExternal modules should be added as Hugo Modules
You can find examples in the config.toml
[module]
[[module.imports]]
path = "github.com/filecoin-project/specs-actors"
[[module.imports.mounts]]
source = "actors"
target = "content/modules/actors"This makes files from external repos available for Hugo rendering and allows for linking to up-to-date files that are directly pulled from other repositories.
The configuration above gives the following information:
path: gives the repository you want to mount content from.source: the folder from the repository referenced in thepaththat we want to mount into our local Hugo filesystem. This is the "root" seen from your Hugo site where you pull content from. In the above case, this means that the source that will be mounted ishttps://github.com/filecoin-project/specs-actors/actors/.target: the folder in your local Hugo site where the mounted content appears. In our case foldercontentis where we include all Hugo content.
Putting everything together in an example: if you want to link to the file xyz.go from https://github.com/filecoin-project/specs-actors/actors/xyz-folder/xyz.go, from any file within the local folder content (or any of its subfolders), then with the above configuration you have to include:
{{<embed src="/modules/actors/xyz-folder/xyz.go" lang="go">}}
These modules can be updated with
hugo mod get -uor use specific version with
hugo mod get github.com/filecoin-project/[email protected]Inline mermaid syntax rendering
{{< mermaid >}}
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
C -->|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
{{</ mermaid >}}This shortcode includes zoom and pad features.
<!-- Relative path -->
{{< svg src="pull-flow.mmd.svg" title="Data Transfer - Pull Flow" >}}
<!-- From hugo content folder -->
{{< svg src="/systems/pull-flow.mmd.svg" title="Data Transfer - Pull Flow" >}}<!-- info|warning|danger -->
{{< hint info >}}
**Markdown content**
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}{{< figure src="diagrams/pieces.png" title="Pieces, Proving Trees, and Piece Data Structures" zoom="true">}}# src relative to the page
{{<embed src="piece_store.id" lang="go">}}
# src relative to content folder
{{<embed src="/systems/piece_store.id" lang="go">}}The first heading should be # Head with --- like below and should refer to the overall title of the document. The right nav only starts on the second level of headings.
---
title: Storage Power Actor
---
# Storage Power Actor
---
## Header for a section in this document
Some text
### Sub header for the a nested section
## Another top level headerDescription for all the available frontmatter properties
<!-- Page Title to be used in the navigation -->
title: Libraries
<!-- Small description for html metadata, if not present the first couple of paragraphs will be used instead -->
description: Libraries used from Filecoin
<!-- This will be used to order the navigation and any other listing of pages -->
weight: 3
<!-- This will make a page section collapse in the navigation -->
bookCollapseSection: true
<!-- This will hidden the page from the navigation -->
bookhidden: true
<!-- This is used in the dashboard to describe the importance of the page content -->
dashboardWeight: 2
<!-- This is used in the dashboard to describe the state of the page content options are "incorrect", "wip", "incomplete" and "stable" -->
dashboardState: stable
<!-- This is used in the dashboard to describe if the theory of the page has been audited, options are 1 or 0 -->
dashboardAudit: 1
<!-- This is used in the dashboard to describe if the page content has compliance tests, options are 0 or numbers of tests -->
dashboardTests: 0Code fences should always have a lang, if you don't know or don't care just use text
```text
Random plain text context ...
``
These links use "portable links" just like relref so you can just give it the name of the file and it will fetch the correct relative link and title for the <a href="/relative/path" title="page title"> automatically.
You can override the <a> title by passing a second string in the link definition.
Note: When using anchors the title can't be fetched automatically.
[Storage Power](storage_power_consensus)
# <a href="/systems/filecoin_blockchain/storage_power_consensus" title="Storage Power Consensus">Storage Power</a>
[Storage Power](storage_power_consensus "Title to override the page original title")
# <a href="/systems/filecoin_blockchain/storage_power_consensus" title="Title to override the page original title">Storage Power</a>
[Tickets](storage_power_consensus#the-ticket-chain-and-drawing-randomness "The Ticket chain and drawing randomness")
# <a href="/systems/filecoin_blockchain/storage_power_consensus#the-ticket-chain-and-drawing-randomness" title="The Ticket chain and drawing randomness">Tickets</a>
For short snippets of math text you can just use the {{<katex>}} shortcode, but if you need to write lots of math in a page you can just use math-mode and avoid writting the katex shortcode everywhere.
Parses math typesetting with KaTeX
Check this example example
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{{<plain>}}. See examples below.
---
title: Math Mode
math-mode: true
---Math 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 {{<plain hidden}} with the hidden argument.
{{<plain hidden>}}
$$
\gdef\createporepbatch{\textsf{create_porep_batch}}
\gdef\GrothProof{\textsf{Groth16Proof}}
\gdef\Groth{\textsf{Groth16}}
\gdef\GrothEvaluationKey{\textsf{Groth16EvaluationKey}}
\gdef\GrothVerificationKey{\textsf{Groth16VerificationKey}}
{{</plain>}}The index of a node in a `$\BinTree$` layer `$l$`. The leftmost node in a tree has `$\index_l = 0$`.```text
$\overline{\underline{\Function \BinTree\dot\createproof(c: \NodeIndex) \rightarrow \BinTreeProof_c}}$
$\line{1}{\bi}{\leaf: \Safe = \BinTree\dot\leaves[c]}$
$\line{2}{\bi}{\root: \Safe = \BinTree\dot\root}$
$\line{3}{\bi}{\path: \BinPathElement^{[\BinTreeDepth]}= [\ ]}$
$\line{4}{\bi}{\for l \in [\BinTreeDepth]:}$
$\line{5}{\bi}{\quad \index_l: [\len(\BinTree\dot\layer_l)] = c \gg l}$
$\line{6}{\bi}{\quad \missing: \Bit = \index_l \AND 1}$
$\line{7}{\bi}{\quad \sibling: \Safe = \if \missing = 0:}$
$\quad\quad\quad \BinTree\dot\layer_l[\index_l + 1]$
$\quad\quad\thin \else:$
$\quad\quad\quad \BinTree\dot\layer_l[\index_l - 1]$
$\line{8}{\bi}{\quad \path\dot\push(\BinPathElement \thin \{\ \sibling, \thin \missing\ \} \thin )}$
$\line{9}{\bi}{\return \BinTreeProof_c \thin \{\ \leaf, \thin \root, \thin \path\ \}}$
```