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 state Label
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
  • State reliable
  • Theory Audit n/a
  • Edit this section
  • section-intro.spec-status-overview

Section State Theory Audit
1 Introduction Reliable
1.2 Architecture Diagrams Reliable
1.3 Key Concepts Reliable
1.4 Filecoin VM Reliable
1.5 System Decomposition Reliable
1.5.1 What are Systems? How do they work? Reliable
1.5.2 Implementing Systems Reliable
2 Systems Draft/WIP
2.1 Filecoin Nodes Reliable
2.1.1 Node Types Stable
2.1.2 Node Repository Stable
2.1.2.1 Key Store Reliable
2.1.2.2 IPLD Store Stable Draft/WIP
2.1.3 Network Interface Stable
2.1.4 Clock Reliable
2.2 Files & Data Reliable
2.2.1 File Reliable
2.2.1.1 FileStore - Local Storage for Files Reliable
2.2.2 The Filecoin Piece Stable
2.2.3 Data Transfer in Filecoin Stable
2.2.4 Data Formats and Serialization Reliable
2.3 Virtual Machine Reliable
2.3.1 VM Actor Interface Reliable Draft/WIP
2.3.2 State Tree Reliable Draft/WIP
2.3.3 VM Message - Actor Method Invocation Reliable Draft/WIP
2.3.4 VM Runtime Environment (Inside the VM) Reliable
2.3.5 Gas Fees Reliable Report Coming Soon
2.3.6 System Actors Reliable Reports
2.3.7 VM Interpreter - Message Invocation (Outside VM) Draft/WIP Draft/WIP
2.4 Blockchain Reliable Draft/WIP
2.4.1 Blocks Reliable
2.4.1.1 Block Reliable
2.4.1.2 Tipset Reliable
2.4.1.3 Chain Manager Reliable
2.4.1.4 Block Producer Reliable Draft/WIP
2.4.2 Message Pool Stable Draft/WIP
2.4.2.1 Message Propagation Stable
2.4.2.2 Message Storage Stable
2.4.3 ChainSync Stable
2.4.4 Storage Power Consensus Reliable Draft/WIP
2.4.4.6 Storage Power Actor Reliable Draft/WIP
2.5 Token Reliable
2.5.1 Minting Model Reliable
2.5.2 Block Reward Minting Reliable
2.5.3 Token Allocation Reliable
2.5.4 Payment Channels Stable Draft/WIP
2.5.5 Multisig Wallet & Actor Reliable Reports
2.6 Storage Mining Reliable Draft/WIP
2.6.1 Sector Stable
2.6.1.1 Sector Lifecycle Stable
2.6.1.2 Sector Quality Stable
2.6.1.3 Sector Sealing Stable Draft/WIP
2.6.1.4 Sector Faults Stable Draft/WIP
2.6.1.5 Sector Recovery Reliable Draft/WIP
2.6.1.6 Adding Storage Stable Draft/WIP
2.6.1.7 Upgrading Sectors Stable Draft/WIP
2.6.2 Storage Miner Reliable Draft/WIP
2.6.2.4 Storage Mining Cycle Reliable Draft/WIP
2.6.2.5 Storage Miner Actor Draft/WIP Reports
2.6.3 Miner Collaterals Reliable
2.6.4 Storage Proving Draft/WIP Draft/WIP
2.6.4.2 Sector Poster Draft/WIP Draft/WIP
2.6.4.3 Sector Sealer Draft/WIP Draft/WIP
2.7 Markets Stable
2.7.1 Storage Market in Filecoin Stable Draft/WIP
2.7.2 Storage Market On-Chain Components Reliable Draft/WIP
2.7.2.3 Storage Market Actor Reliable Reports
2.7.2.4 Storage Deal Flow Reliable Draft/WIP
2.7.2.5 Storage Deal States Reliable
2.7.2.6 Faults Reliable Draft/WIP
2.7.3 Retrieval Market in Filecoin Stable
2.7.3.5 Retrieval Peer Resolver Stable
2.7.3.6 Retrieval Protocols Stable
2.7.3.7 Retrieval Client Stable
2.7.3.8 Retrieval Provider (Miner) Stable
2.7.3.9 Retrieval Deal Status Stable
3 Libraries Reliable
3.1 DRAND Stable Reports
3.2 IPFS Stable Draft/WIP
3.3 Multiformats Stable
3.4 IPLD Stable
3.5 Libp2p Stable Draft/WIP
4 Algorithms Draft/WIP
4.1 Expected Consensus Reliable Draft/WIP
4.2 Proof-of-Storage Reliable Draft/WIP
4.2.2 Proof-of-Replication (PoRep) Reliable Draft/WIP
4.2.3 Proof-of-Spacetime (PoSt) Reliable Draft/WIP
4.3 Stacked DRG Proof of Replication Stable Report Coming Soon
4.3.16 SDR Notation, Constants, and Types Stable Report Coming Soon
4.4 BlockSync Stable
4.5 GossipSub Stable Reports
4.6 Cryptographic Primitives Draft/WIP
4.6.1 Signatures Draft/WIP Report Coming Soon
4.6.2 Verifiable Random Function Incorrect
4.6.3 Randomness Reliable Draft/WIP
4.6.4 Poseidon Incorrect Missing
4.7 Verified Clients Draft/WIP Draft/WIP
4.8 Filecoin CryptoEconomics Reliable Draft/WIP
5 Glossary Reliable
6 Appendix Draft/WIP
6.1 Filecoin Address Reliable
6.2 Data Structures Reliable
6.3 Filecoin Parameters Draft/WIP
6.4 Audit Reports Reliable
7 Filecoin Implementations Reliable
7.1 Lotus Reliable
7.2 Venus Reliable
7.3 Forest Reliable
7.4 Fuhon (cpp-filecoin) Reliable
8 Releases

Spec Stabilization Progress
  • State reliable
  • Theory Audit n/a
  • Edit this section
  • section-intro.spec-stabilization-progress

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

WIP 11% Reliable 55% Stable 32%

Implementations Status
  • State reliable
  • Theory Audit n/a
  • Edit this section
  • section-intro.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.

Repo Language CI Test Coverage Security Audit
lotus go Failed 40% Reports
go-fil-markets go Passed 58% Reports
specs-actors go Unknown 69% Reports
rust Unknown Unknown Reports
venus go Passed 23% Missing
forest rust Passed 56% Missing
cpp-filecoin c++ Passed 45% Missing