# How Filecoin Works

This page gives a basic introduction to how the Filecoin network operates. While Filecoin is similar to other cryptocurrencies, there are some differences that developers looking to build on the network should be aware of.

# The Network

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

Peers communicate over secure channels that they use to distribute information to the network (gossiping), to transfer data among themselves, and to discover other peers, maintaining a well-connected swarm in which information like blocks and messages flows swiftly even when many thousands of peers participate.

# 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. Nodes can manage Filecoin wallets and receive FIL on them.

Filecoin Nodes can also publish different types of messages to the network by broadcasting them. For example, a client can publish a message to send FIL from one address to a different one. Nodes can propose storage and retrieval deals to Filecoin miners and pay for them as they are executed.

Running a Filecoin Node is a low-level task that usually implies keeping a program running 24/7. There are several Filecoin Node implementations in the works, with Lotus being the most advanced.

# Filecoin miners

The miners 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. Additional details about types of miners, rewards, and deals execution from the miner perspective can be found in the How mining works section.

Running a Filecoin miner is a highly-technical task with strong hardware requirements, as needed to complete the necessary proofs. The Lotus Miner is the most advanced implementation of a Filecoin miner to this day.

# Deals

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

Storage deals are agreements between clients and storage miners to store some data in the network. Once a deal is initiated, and the miner 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 miner will be slashed and lose FIL.

Retrieval deals are agreements between clients and retrieval miners (which may or not be also storage miners) to extract data that is stored in the network (hopefully in a fast and reliable manner). Unlike storage deals, these deals are fulfilled off-chain, using payment channels to incrementally pay for the data received.

# Proofs

As mentioned above, storage miners 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

Cryptographic proofs are used to these ends, as explained in this article about the Filecoin proof system (opens new window).

Using Proof Of Replication (PoRep), miners demonstrate that they have received all the data and that they have encoded it in a way unique to that miner using their physical storage in a way that no other miner can replicate (so two deals for the same data cannot end up re-using the same disk). This proof is provided when the deal starts, and the sealing operation completes.

Once a deal is active and during its full lifetime, the miner will use Proof of Spacetime (PoSt) to prove that it is still storing the data associated with a deal. For PoSt, random miners need to prove that random parts of the data they store are still there.

Filecoin clients and other miners continuously verify that the proofs included in each block are valid, providing the necessary security and penalizing miners that do not honor their deals.

# Gas fees

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 miner.

Historically in other blockchains, miners specify a GasFee in a unit of native currency and then pay the block producing miners a priority fee based on how much gas is consumed by the message. Filecoin works similarly, except an amount of the fees is burned (sent to an irrecoverable address) to compensate for the network expenditure of resources, since all nodes need to validate the messages. The idea is based on Ethereum's EIP1559 (opens new window).

The amount of fees burned in the Filecoin network comes given by a dynamic *BaseFee which gets automatically adjusted according to the network congestion parameters (block sizes). The current value can be obtained from one of the block explorers or by inspecting the current head.

Additionally, a number of gas-related parameters are attached to each message and determine the amount of rewards that miners get. Here's an overview of the terms and concepts:

  • GasUsage: the amount of gas that a message's execution actually consumes. Current protocol does not know how much gas a message will exactly consume ahead of execution, but it can be estimated (see prices (opens new window)). GasUsage measured in units of Gas.
  • BaseFee: the amount of FIL that gets burned per unit of gas consumed for the execution of every message. It is measured in units of attoFIL/Gas.
  • GasLimit: the limit on the amount of gas that a message's execution can consume, estimated and specified by a message sender. It is measured in units of Gas. The sum of GasLimit for all messages included in a block must not exceed the BlockGasLimit. Messages will fail to execute if they run out of Gas, and any effects of the execution will be reverted.
  • GasFeeCap: the maximum token amount that a sender is willing to pay per GasUnit for including a message in a block. It is measured in units of attoFIL/Gas. A message sender must have a minimum balance of GasFeeCap * GasLimit when sending a message, even though not all of that will be consumed. GasFeeCap can serve as a safeguard against high, unexpected BaseFee fluctuations.
  • GasPremium: a priority fee that is paid to the block-producing miner. This is capped by GasFeeCap. The BaseFee has a higher priority. It is measured in units of attoFIL/Gas and can be as low as 1 attoFIL/Gas.
  • Overestimation burn: an additional amount of gas to burn that grows larger when the difference between GasLimit and GasUsage is large. See current implementation (opens new window)).

The total cost of a message for a sender will be:

  • GasUsage * BaseFee FIL (burned) +
  • GasLimit * GasPremium FIL (miner's reward) +
  • OverEstimationBurn * BaseFee FIL

An important detail is that a message will always pay the burn fee, regardless of the GasFeeCap used. Thus, a low GasFeeCap may result in a reduced GasPremium or even a negative one! In that case, the miners that include a message will have to pay the needed amounts out of their own pockets, which means they are unlikely to include such messages in new blocks.

Filecoin implementations may choose the heuristics of how their miners select messages for inclusion in new blocks, but they will usually attempt to maximize the miner's rewards.

# Additional materials

Filecoin is built on top of mature projects like libp2p (networking, addressing, message distribution), IPLD (data formats, encoding, and content-addressed data structures), IPFS (data transfers), and multiformats (future-proof data types).

Here are some links to useful introductory materials about the technology that powers Filecoin and about Filecoin itself: