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.
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.
Actors
Actors are a software design pattern (opens new window)for managing state. Accounts, Multisigs, Miners, and anything with a state, such as an account balance, are implemented as an actor.
Actors are the Filecoin equivalent of smart contracts in the Ethereum Virtual Machine. As such, Actors are very central components of the system. Any change to the current state of the Filecoin blockchain has to be triggered through an Actor.
see: https://spec.filecoin.io/#section-systems.filecoin_vm(opens new window)
Addresses
In Filecoin, addresses are used to identify actors. There are 4 address types:
0- ID Address1- SECP256K1 Public Key Address2- Actor Address3- BLS Public Key Address
ID addresses - f0
f0All actors have an ID such as 99, a short integer assigned to it by the InitActor when the actor is created. An ID address is an actor's ID prefixed with the network (f for mainnet) and address type 0 for ID.
For example, the Burn Account (opens new window)actor on the mainnet has the ID 99 and the ID Address f099.
Public key addresses - f1 and f3
f1 and f3Actors managed directly by users, like accounts, are derived from a public-private key pair. If you have access to a private key, you can sign messages sent from that actor. The public key is used to derive an address for the actor.
For example, the Huobi Hot Wallet (opens new window)has the secp256k1 Public Key Address f1abjxfbp274xpdqcpuaykwkfb43omjotacm2p3za and the ID Address f033259. Both addresses identify the same Account actor. Messages sent to either address will be applied to the same Account.
Public key addresses allow devices like the Ledger to derive a valid Filecoin address for your account from just the public key. It doens't need to ask a remote node what your ID address is.
Filecoin supports both secp256k1 addresses that begin with f1 and BLS addresses that begin with f3.
Robust addresses versus ID addresses
Public key addresses are referred to as "Robust Addresses" as they do not depend on the filecoin chain state.
Actor IDs are defined on-chain by the InitActor. An actor ID can change for a brief time after its creation if the same ID is assigned to different actors on different forks. You can think of ID addresses like a monotonically increasing numeric primary key in a relational database. Where a chain reorg occurs or a rollback in SQL terms, you can end up referring to the same id for different rows. The Expected Consensus (opens new window)algorithm will resolve the conflict, and once the state that defines a new ID is old enough (reaches finality in consensus terms), no changes can occur; the ID is bound to that actor forever.
Robust addresses provide a safe way to reference actors before the chain state is final. ID Addresses are used as a space-efficient way to identify actors in the filecoin chain state, where every byte matters, and as a human-friendly, concise form.
Actor addresses f2
f2Actor addresses provide a way to create robust addresses for actors not associated with a public key. They are the essentially random sha256 hash of the output of the account creation. The ZH Storage Miner (opens new window)has the Actor Address f2plku564ddywnmb5b2ky7dhk4mb6uacsxuuev3pi and the ID address f01248.
BLS Curve f3
f3In addition to secp256k1 f1 addresses, BLS addresses in Filecoin begin with f3. Filecoin uses curve bls12-381 for BLS signatures. Bls12-381 is a pair of two related curves: G1 and G2. Implementations of bls12-381 can vary based on if public keys are on G1 and signatures on G2 or vice-versa.
Filecoin uses G1 for public keys and G2 for signatures as G1 allows for a smaller representation of public keys. This is the same design decision made with ETH2, but contrasts to, for instance, Zcash which has signatures on G1 and public keys on G2.
Also note that Filecoin stores and interprets private keys in little-endian order. This is in contrast to ETH2 keys, which also use bls12-381 but are stored in big-endian order.
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:
Last updated