How Filecoin Works

Filecoin Basics

A more thorough explanation of these concepts can be found in the Filecoin docs

The Filecoin network is a distributed, peer-to-peer network formed by Filecoin peers who participate in different ways.

Peers communicate over secure channels to distribute information around the network (gossiping). They transfer data among themselves, discover other peers, and maintain a well-connected swarm; information like blocks and messages flow swiftly even when thousands of peers participate.

Filecoin Storage Basics | Rod Vagg

Learn about mining, sealing, sector types, Collateral, making deals, Filecoin+, offline deals.

Filecoin Nodes

Filecoin Nodes or Filecoin clients are peers that sync the Filecoin blockchain and validate the messages in every block, which once applied, provide a global state.

Filecoin Nodes can also publish different types of messages to the network by broadcasting them.

Storage and Retrieval

Filecoin Storage Providers (Miners)

The storage providers provide services to the network by executing different types of deals and appending new blocks to the chain (every 30 seconds), for which they collect FIL rewards.

Storage & Retrieval Markets | Filecoin Research - Juan Benet and Jeromy Johnson

In this 4 minute talk by Jeromy Johnson & Juan Benet, understand how Filecoin, which differs from most blockchains in how it incentivizes storage, interacts with both storage and retrieval markets.


There are two main types of deals in Filecoin: storage deals and retrieval deals.

Storage deals are agreements between clients and storage providers to store some data in the network. Once a deal is initiated, and the storage provider has received the data to store, it will repeatedly prove to the chain that it is still storing the data per the agreement so that it can collect rewards. If not, the storage provider will be slashed and lose FIL.

Anatomy of a Filecoin Deal


As mentioned above, storage providers must prove that they are storing the data per the terms of a deal. That means that:

  • They must store all the data submitted by the client
  • They must store it during the whole lifetime of the deal


Executing messages, for example by including transactions or proofs in the chain, consumes both computation and storage resources on the network. Gas is a measure of resources consumed by messages. The gas consumed by a message directly affects the cost that the sender has to pay for it to be included in a new block by a storage provider.

Important Gas Concepts

  • GasUsage: the amount of gas that a message’s execution actually consumes.
  • BaseFee: the amount of FIL that gets burned per unit of gas consumed for the execution of every message.
  • GasLimit: the limit on the amount of gas that a message’s execution can consume, estimated and specified by a message sender.
  • GasFeeCap: the maximum token amount that a sender is willing to pay per GasUnit for including a message in a block.
  • GasPremium: a priority fee that is paid to the block-producing storage provider.
  • Overestimation burn: an additional amount of gas to burn that grows larger when the difference between GasLimit and GasUsage is large. (See current implementation).


Actors are a software design pattern for managing state. Accounts, Multisigs, Storage Providers, and anything with a state, such as an account balance, are implemented as an actor.


In Filecoin, addresses are used to identify actors. There are 4 address types:

  • 0 - ID Address
  • 1 - SECP256K1 Public Key Address
  • 2 - Actor Address
  • 3 - BLS Public Key

Filecoin Plus

Filecoin Plus is a mechanism for onboarding data into the Filecoin market that incentivizes the storage providers on the Filecoin network to store real, valuable, and usable data. It is a layer of social trust on top of the Filecoin Network to help incentivize this storage. Storage providers who store data that has been approved for DataCap have more power to win block rewards. The Filecoin Plus Dashboard provides data about verification, storage, and more.

There are a few ways one can get approved to store data on the Filecoin network, and there are governance processes and roles, including root key-holders, notaries, clients, and storage providers who interact through the allocation and spending of DataCap, and help onboard that data to the network.

Filecoin Plus Governance

Filecoin Deep Dive (Optional)

Filecoin for Developers & Builders | Pooja Shah

In this talk by Pooja Shah of Protocol Labs, learn about the basic functioning and purpose of Filecoin. The Core features and use cases of Filecoin will be covered, and Pooja will also go over some of the activity going on in the ecosystem, including the core developer projects that make it possible to implement, develop, and use Filecoin.

Filecoin Core Features

  • Granular control over parameters for data Storage
  • Storage receipts
  • Control over storage pricing (and what you will pay)
  • Content addressing
  • Data persistence

Filecoin Use Cases

  • Filecoin for data storage
  • Filecoin for payments
  • Ancillary tools and services

Filecoin Tools and Services (Products for Developers)

Lotus Common Architecture Currently for those using lotus directly, it is recommended that you have a hardware configuration with 32GB of RAM, an 8-core CPU, and at least 200 GB of SSD storage. See the Filecoin docs on Hardware requirements

Getting Started with Filecoin

Now that you understand the basics of Filecoin, here are some ways to start building on the network:

Run a Local Testnet The easiest way to start is by running a local testnet using Lotus. This will allow you to deploy smart contracts, send messages, and get a feel for how Filecoin works without using real FIL. Follow the guide to set up Lotus and run a local testnet.

Try Examples and Tutorials Work through the example contracts, dapps, and tutorials in the Filecoin documentation. Some options:

  • Deploy an ERC-20 contract
  • Build a “Hello, World!” dapp
  • Create and fund a multisig wallet
  • Build Your Own Dapp
  • Once you get the hang of Filecoin development, you can start building your own decentralized application! Some project ideas:

A decentralized storage marketplace

  • A non-fungible token (NFT) minting and trading platform
  • A DAO for funding public goods
  • Decentralized finance (DeFi) apps for lending, borrowing, and more
  • Participate in the Community
  • The Filecoin community is active and always open to new members. Some ways to get involved:

Join the Filecoin Slack and Discord

  • Contribute to Lotus, documentation, or other repos on GitHub
  • Attend or speak at upcoming events like Distributed Camp
  • Get Filecoin updates by following @Filecoin on Twitter