Introduction

Introduction

Filecoin is a distributed storage network based on a blockchain mechanism. Filecoin miners can elect to provide storage capacity for the network, and thereby earn units of the Filecoin cryptocurrency (FIL) by periodically producing cryptographic proofs that certify that they are providing the capacity specified. In addition, Filecoin enables parties to exchange FIL currency through transactions recorded in a shared ledger on the Filecoin blockchain. Rather than using Nakamoto-style proof of work to maintain consensus on the chain, however, Filecoin uses proof of storage itself: a miner’s power in the consensus protocol is proportional to the amount of storage it provides.

The Filecoin blockchain not only maintains the ledger for FIL transactions and accounts, but also implements the Filecoin VM, a replicated state machine which executes a variety of cryptographic contracts and market mechanisms among participants on the network. These contracts include storage deals, in which clients pay FIL currency to miners in exchange for storing the specific file data that the clients request. Via the distributed implementation of the Filecoin VM, storage deals and other contract mechanisms recorded on the chain continue to be processed over time, without requiring further interaction from the original parties (such as the clients who requested the data storage).

Spec Status

Each section of the spec must be stable and audited before it is considered done. The state of each section is tracked below.

  • The State column indicates the stability as defined in the legend.
  • The Theory Audit column shows the date of the last theory audit with a link to the report.

Spec Status Legend

Spec stateLabel
Unlikely to change in the foreseeable future.Stable
All content is correct. Important details are covered.Reliable
All content is correct. Details are being worked on.Draft/WIP
Do not follow. Important things have changed.Incorrect
No work has been done yet.Missing

Spec Status Overview

SectionStateTheory Audit
1 IntroductionReliable
1.2 Architecture DiagramsReliable
1.3 Key ConceptsReliable
1.4 Filecoin VMReliable
1.5 System DecompositionReliable
1.5.1 What are Systems? How do they work?Reliable
1.5.2 Implementing SystemsReliable
2 SystemsDraft/WIP
2.1 Filecoin NodesReliable
2.1.1 Node TypesStable
2.1.2 Node RepositoryStable
2.1.2.1 Key StoreReliable
2.1.2.2 IPLD StoreStableDraft/WIP
2.1.3 Network InterfaceStable
2.1.4 ClockReliable
2.2 Files & DataReliable
2.2.1 FileReliable
2.2.1.1 FileStore - Local Storage for FilesReliable
2.2.2 The Filecoin PieceStable
2.2.3 Data Transfer in FilecoinStable
2.2.4 Data Formats and SerializationReliable
2.3 Virtual MachineReliable
2.3.1 VM Actor InterfaceReliableDraft/WIP
2.3.2 State TreeReliableDraft/WIP
2.3.3 VM Message - Actor Method InvocationReliableDraft/WIP
2.3.4 VM Runtime Environment (Inside the VM)Reliable
2.3.5 Gas FeesReliableReport Coming Soon
2.3.6 System ActorsReliableReports
2.3.7 VM Interpreter - Message Invocation (Outside VM)Draft/WIPDraft/WIP
2.4 BlockchainReliableDraft/WIP
2.4.1 BlocksReliable
2.4.1.1 BlockReliable
2.4.1.2 TipsetReliable
2.4.1.3 Chain ManagerReliable
2.4.1.4 Block ProducerReliableDraft/WIP
2.4.2 Message PoolStableDraft/WIP
2.4.2.1 Message PropagationStable
2.4.2.2 Message StorageStable
2.4.3 ChainSyncStable
2.4.4 Storage Power ConsensusReliableDraft/WIP
2.4.4.6 Storage Power ActorReliableDraft/WIP
2.5 TokenReliable
2.5.1 Minting ModelReliable
2.5.2 Block Reward MintingReliable
2.5.3 Token AllocationReliable
2.5.4 Payment ChannelsStableDraft/WIP
2.5.5 Multisig Wallet & ActorReliableReports
2.6 Storage MiningReliableDraft/WIP
2.6.1 SectorStable
2.6.1.1 Sector LifecycleStable
2.6.1.2 Sector QualityStable
2.6.1.3 Sector SealingStableDraft/WIP
2.6.1.4 Sector FaultsStableDraft/WIP
2.6.1.5 Sector RecoveryReliableDraft/WIP
2.6.1.6 Adding StorageStableDraft/WIP
2.6.1.7 Upgrading SectorsStableDraft/WIP
2.6.2 Storage MinerReliableDraft/WIP
2.6.2.4 Storage Mining CycleReliableDraft/WIP
2.6.2.5 Storage Miner ActorDraft/WIPReports
2.6.3 Miner CollateralsReliable
2.6.4 Storage ProvingDraft/WIPDraft/WIP
2.6.4.2 Sector PosterDraft/WIPDraft/WIP
2.6.4.3 Sector SealerDraft/WIPDraft/WIP
2.7 MarketsStable
2.7.1 Storage Market in FilecoinStableDraft/WIP
2.7.2 Storage Market On-Chain ComponentsReliableDraft/WIP
2.7.2.3 Storage Market ActorReliableReports
2.7.2.4 Storage Deal FlowReliableDraft/WIP
2.7.2.5 Storage Deal StatesReliable
2.7.2.6 FaultsReliableDraft/WIP
2.7.3 Retrieval Market in FilecoinStable
2.7.3.5 Retrieval Peer ResolverStable
2.7.3.6 Retrieval ProtocolsStable
2.7.3.7 Retrieval ClientStable
2.7.3.8 Retrieval Provider (Miner)Stable
2.7.3.9 Retrieval Deal StatusStable
3 LibrariesReliable
3.1 DRANDStableReports
3.2 IPFSStableDraft/WIP
3.3 MultiformatsStable
3.4 IPLDStable
3.5 Libp2pStableDraft/WIP
4 AlgorithmsDraft/WIP
4.1 Expected ConsensusReliableDraft/WIP
4.2 Proof-of-StorageReliableDraft/WIP
4.2.2 Proof-of-Replication (PoRep)ReliableDraft/WIP
4.2.3 Proof-of-Spacetime (PoSt)ReliableDraft/WIP
4.3 Stacked DRG Proof of ReplicationStableReport Coming Soon
4.3.16 SDR Notation, Constants, and TypesStableReport Coming Soon
4.4 BlockSyncStable
4.5 GossipSubStableReports
4.6 Cryptographic PrimitivesDraft/WIP
4.6.1 SignaturesDraft/WIPReport Coming Soon
4.6.2 Verifiable Random FunctionIncorrect
4.6.3 RandomnessReliableDraft/WIP
4.7 Verified ClientsDraft/WIPDraft/WIP
4.8 Filecoin CryptoEconomicsReliableDraft/WIP
5 GlossaryReliable
6 AppendixDraft/WIP
6.1 Filecoin AddressReliable
6.2 Data StructuresReliable
6.3 Filecoin ParametersDraft/WIP
6.4 Audit ReportsReliable
7 Filecoin ImplementationsReliable
7.1 LotusReliable
7.2 VenusReliable
7.3 ForestReliable
7.4 Fuhon (cpp-filecoin)Reliable
8 Releases

Spec Stabilization Progress

This progress bar shows what percentage of the spec sections are considered stable.

WIP 11% Reliable 56% Stable 32%

Implementations Status

Known implementations of the filecoin spec are tracked below, with their current CI build status, their test coverage as reported by codecov.io, and a link to their last security audit report where one exists.

RepoLanguageCITest CoverageSecurity Audit
lotusgoFailed35%Reports
go-fil-marketsgoPassed65%Reports
specs-actorsgoPassed71%Reports
rust-fil-proofsrustFailedUnknownReports
venusgoFailed46%Missing
forestrustFailedUnknownMissing
cpp-filecoinc++Passed30%Missing