Filecoin Spec

You can also download the full spec in PDF format.

This collection of pages specify the protocols comprising the Filecoin network. The goal of these specs is to provide sufficient detail that another implementation, written using only this document as reference, can be fully compatible with go-filecoin peers, but this is still a work in progress.

Overview

Filecoin is a distributed storage network, with shared state persisted to a blockchain.

The network maintains consensus over the current state of a replicated state machine through expected consensus. This replicated state machine is used to run the filecoin storage market. This market provides a place to buy and sell storage within the distributed network of filecoin miners. The market also provides the needed mechanisms to ensure that the data stored by the network is actually being stored as promised, without requiring client interaction.

Clients interact with the system by sending messages to the network. These messages are gathered up and included by miners in blocks. Each of these messages defines a state transition in the state machine. The simplest messages say something like “move Filecoin from this account under my control to this other account”, but more complex ones describe storage sector commitments, storage deals struck, and proofs of storage.

The Filecoin protocol itself is really a suite of protocols, including:

• the chain protocol for propagating the data that constitutes the blockchain
• the block mining protocol for producing new blocks
• the consensus mechanism and rules for agreeing on canonical blockchain state
• all interacting with the state machine and the actors running on it:
  • the storage market protocol for storage miners to sell storage and clients to purchase it
  • the retrieval market protocol for retrieving files
  • the payment channel channel protocol for transferring FIL tokens between actors

Message Transport

Filecoin uses libp2p for all network communications. libp2p provides transport-agnostic services for peer discovery, naming, routing, pubsub channels and a distributed record store, and there are full or partial implementations in a number of languages. This spec assumes the use of libp2p and its services and does not specify transport-level details. That said, to be at least minimally compatible with other Filecoin nodes, it must support at least the mplex stream multiplexer, and the secio encrypted transport protocols. For more details on the exact wire protocol of libp2p, refer to the libp2p specs.

Filecoin uses IPLD for the representation and serialization of the majority of the data in the system. IPLD provides a canonical model for content-addressed data structures, providing a representation of basic data objects and links between them.