This section covers the basic concepts surrounding the Filecoin blockchain.
Actors are smart contracts that run on the Filecoin virtual machine (FVM) and are used to manage, query, and update the state of the Filecoin network. Smart contracts are small, self-executing blocks.
For those familiar with the Ethereum virtual machine (EVM), actors work similarly to smart contracts. In the Filecoin network, there are two types of actors:
Built-in actors: Hardcoded programs written ahead of time by network engineers that manage and orchestrate key subprocesses and subsystems in the Filecoin network.
User actors: Code implemented by any developer that interacts with the Filecoin Virtual Machine (FVM).
Built-in actors are how the Filecoin network manages and updates global state. The global state of the network at a given epoch can be thought of as the set of blocks agreed upon via network consensus in that epoch. This global state is represented as a state tree, which maps an actor to an actor state. An actor state describes the current conditions for an individual actor, such as its FIL balance and its nonce. In Filecoin, actors trigger a state transition by sending a message. Each block in the chain can be thought of as a proposed global state, where the block selected by network consensus sets the new global state. Each block contains a series of messages and a checkpoint of the current global state after the application of those messages. The Filecoin Virtual Machine (FVM) is the Filecoin network component that is in charge of the execution of all actor code.
A basic example of how actors are used in Filecoin is the process by which storage providers prove storage and are subsequently rewarded. The process is as follows:
The StorageMinerActor processes proof of storage from a storage provider.
The storage provider is awarded storage power based on whether the proof is valid or not.
The StoragePowerActor accounts for the storage power.
During block validation, the StoragePowerActor state, which includes information on storage power allocated to each storage provider, is read.
Using the state information, the consensus mechanism randomly awards blocks to the storage providers with the most power, and the RewardActor sends FIL to storage providers.
Each block in the Filecoin chain contains the following:
Inline data such as current block height.
A pointer to the current state tree.
A pointer to the set of messages that, when applied to the network, generated the current state tree.
A Merkle Directed Acyclic Graph (Merkle DAG) is used to map the state tree and the set of messages. Nodes in the state tree contain information on:
Actors, like FIL balance, nonce, and a pointer (CID) to actor state data.
Messages in the current block
Like the state tree, a Merkle Directed Acyclic Graph (Merkle DAG) is used to map the set of messages for a given block. Nodes in the messages may contain information on:
The actor the message was sent to
The actor that sent the message
Target method to call on the actor being sent the message
A cryptographic signature for verification
The amount of FIL transferred between actors
The code that defines an actor in the Filecoin network is separated into different methods. Messages sent to an actor contain information on which method(s) to call and the input parameters for those methods. Additionally, actor code interacts with a runtime object, which contains information on the general state of the network, such as the current epoch, cryptographic signatures, and proof validations. Like smart contracts in other blockchains, actors must pay a gas fee, which is some predetermined amount of FIL to offset the cost (network resources used, etc.) of a transaction. Every actor has a Filecoin balance attributed to it, a state pointer, a code that tells the system what type of actor it is, and a nonce, which tracks the number of messages sent by this actor.
The 11 different types of built-in actors are as follows:
The CronActor sends messages to the StoragePowerActor and StorageMarketActor at the end of each epoch. The messages sent by CronActor indicate to StoragePowerActor and StorageMarketActor how they should maintain the internal state and process deferred events. This system actor is instantiated in the genesis block and interacts directly with the FVM.
The InitActor can initialize new actors on the Filecoin network. This system actor is instantiated in the genesis block and maintains a table resolving a public key and temporary actor addresses to their canonical ID addresses. The InitActor interacts directly with the FVM.
The AccountActor is responsible for user accounts. Account actors are not created by the InitActor but by sending a message to a public-key style address. The account actor updates the state tree with a new actor address and interacts directly with the FVM.
The RewardActor manages unminted Filecoin tokens and distributes rewards directly to miner actors, where they are locked for vesting. The reward value used for the current epoch is updated at the end of an epoch. The RewardActor interacts directly with the FVM.
The StorageMarketActor is responsible for processing and managing on-chain deals. This is also the entry point of all storage deals and data into the system. This actor keeps track of storage deals and the locked balances of both the client storing data and the storage provider. When a deal is posted on-chain through the StorageMarketActor, the actor will first check if both transacting parties have sufficient balances locked up and include the deal on-chain. Additionally, the StorageMarketActor holds Storage Deal Collateral provided by the storage provider to collateralize deals. This collateral is returned to the storage provider when all deals in the sector successfully conclude. This actor does not interact directly with the FVM.
The StorageMinerActor is created by the StoragePowerActor and is responsible for storage mining operations and the collection of mining proofs. This actor is a key part of the Filecoin storage mining subsystem, which ensures a storage miner can effectively commit storage to Filecoin and handles the following:
Committing new storage
Continuously proving storage
Declaring storage faults
Recovering from storage faults
This actor does not interact directly with the FVM.
The MultisigActor is responsible for dealing with operations involving the Filecoin wallet and represents a group of transaction signers with a maximum of 256. Signers may be external users or the MultisigActor itself. This actor does not interact directly with the FVM.
The PaymentChannelActor creates and manages payment channels, a mechanism for off-chain microtransactions for Filecoin dApps to be reconciled on-chain at a later time with less overhead than a standard on-chain transaction and no gas costs. Payment channels are uni-directional and can be funded by adding to their balance. To create a payment channel and deposit fund, a user calls the PaymentChannelActor. This actor does not interact directly with the FVM.
The StoragePowerActor is responsible for keeping track of the storage power allocated to each storage miner and has the ability to create a StorageMinerActor. This actor does not interact directly with the FVM.
The VerifiedRegistryActor is responsible for managing Filecoin Plus clients. This actor can add a verified client to the Filecoin Plus program, remove and reclaim expired DataCap allocations, and manage claims. This actor does not interact directly with the FVM.
For more information on SystemActor, see the source code.
A user actor is code defined by any developer that can interact with the FVM, otherwise known as a smart contract.
A smart contract is a small, self-executing block of custom code that runs on other blockchains, like Ethereum. In the Filecoin network, the term is a synonym for user actor. You may see the term smart contract used in tandem with user actor, but there is no difference between the two.
With the FVM, actors can be written in Solidity. In future updates, any language that compiles to WASM will be supported. With user actors, users can create and enforce custom rules for storing and accessing data on the network. The FVM is responsible for actors and ensuring that they are executed correctly and securely.
A Filecoin address is an identifier that refers to an actor in the Filecoin state. All actors (miner actors, the storage market actor, account actors) have an address.
All Filecoin addresses begin with an f to indicate the network (Filecoin), followed by any of the address prefix numbers (0, 1, 2, 3, 4) to indicate the address type. There are five address types:
Each of the address types is described below.
All actors have a short integer assigned to them by InitActor, a unique actor that can create new actors. This integer that gets assigned is the ID of that actor. An ID address is an actor’s ID prefixed with the network identifier and the address type.
Actor ID addresses are not robust in the sense that they depend on chain state and are defined on-chain by the InitActor. Additionally, actor IDs can change for a brief time after creation if the same ID is assigned to different actors on different forks. Actor ID addresses are similar to monotonically increasing numeric primary keys in a relational database. So, when a chain reorganization occurs (similar to a rollback in a SQL database), you can refer to the same ID for different rows. The expected consensus algorithm will resolve the conflict. Once the state that defines a new ID reaches finality, no changes can occur, and the ID is bound to that actor forever.
For example, the mainnet burn account ID address, f099, is structured as follows:
ID addresses are often referred to by their shorthand f0.
Actors 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. Public key addresses are referred to as robust addresses as they do not depend on the Filecoin chain state.
Public key addresses allow devices, like hardware wallets, to derive a valid Filecoin address for your account using just the public key. The device doesn’t need to ask a remote node what your ID address is. Public key addresses provide a concise, safe, human-readable 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.
Filecoin supports two types of public key addresses:
secp256k1 addresses that begin with the prefix f1.
BLS addresses that begin with the prefix f3.
For BLS addresses, Filecoin uses curve bls12-381 for BLS signatures, which is a pair of two related curves, G1 and G2.
Filecoin uses G1 for public keys, as G1 allows for a smaller representation of public keys and G2 for signatures. This implements the same design as ETH2 but contrasts with Zcash, which has signatures on G1 and public keys on G2. However, unlike ETH2, which stores private keys in big-endian order, Filecoin stores and interprets private keys in little-endian order.
Public key addresses are often referred to by their shorthand, f1 or f3.
Actor addresses provide a way to create robust addresses for actors not associated with a public key. They are generated by taking a sha256 hash of the output of the account creation. The ZH storage provider has the actor address f2plku564ddywnmb5b2ky7dhk4mb6uacsxuuev3pi and the ID address f01248.
Actor addresses are often referred to by their shorthand, f2.
Filecoin supports extensible, user-defined actor addresses through the f4 address class, introduced in Filecoin Improvement Proposal (FIP) 0048. The f4 address class provides the following benefits to the network:
A predictable addressing scheme to support interactions with addresses that do not yet exist on-chain.
User-defined, custom addressing systems without extensive changes and network upgrades.
Support for native addressing schemes from foreign runtimes such as the EVM.
An f4 address is structured as f4<address-manager-actor-id>f<new-actor-id>, where <address-manager-actor-id> is the actor ID of the address manager, and <new-actor-id> is the arbitrary actor ID chosen by that actor. An address manager is an actor that can create new actors and assign an f4 address to the new actor.
Currently, per FIP 0048, f4 addresses may only be assigned by and in association with specific, built-in actors called address managers. Once users are able to deploy custom WebAssembly actors, this restriction will likely be relaxed in a future FIP.
As an example, suppose an address manager has an actor ID (an f0 address) 123, and that address manager creates a new actor. Then, the f4 address of the actor created by the address manager is f4123fa3491xyz, where f4 is the address class, 123 is the actor ID of the address manager, f is a separator, and a3491xyz is the arbitrary <new-actor-id> chosen by that actor.
Like many other blockchains, blocks are a fundamental concept in Filecoin. Unlike other blockchains, Filecoin is a chain of groups of blocks called tipsets rather than a chain of individual blocks.
In Filecoin, a block consists of:
A block header
A list of messages contained in the block
A signed copy of each message listed
Every block refers to at least one parent block; that is, a block produced in a prior epoch.
A message represents communication between two actors and thus changes in network state. The messages are listed in their order of appearance, deduplicated, and returned in canonical order of execution. So, in other words, a block describes all changes to the network state in a given epoch.
Blocktime is a concept that represents the average time it takes to mine or produce a new block on a blockchain. In Ethereum, for example, the blocktime is approximately 15 seconds on average, meaning that a new block is added to the Ethereum blockchain roughly every 15 seconds.
In the Filecoin network, storage providers compete to produce blocks by providing storage capacity and participating in the consensus protocol. The block time determines how frequently new blocks are added to the blockchain, which impacts the overall speed and responsiveness of the network.
Filecoin has a block time of 30 seconds, and this duration was chosen for two main reasons:
Hardware requirements: If the block time were faster while maintaining the same gas limit or the number of messages per block, it would lead to increased hardware requirements. This includes the need for more storage space to accommodate the larger chain data resulting from more frequent block production.
Storage provider operations: The block time also takes into account the various operations that occur during that duration on the storage provider (SP) side. As SPs generate new blocks, the 30-second block time allows for the necessary processes and computations to be carried out effectively. If the blocktime were shorter, SPs would encounter significantly more blocktime failures.
By considering these factors, the Filecoin network has established a block time of 30 seconds, balancing the need for efficient operations and hardware requirements.
As described in Consensus, multiple potential block producers may be elected via Expected Consensus (EC) to create a block in each epoch, which means that more than one valid block may be produced in a given epoch. All valid blocks with the same height and same parent block are assembled into a group called a tipset.
In other blockchains, blocks are used as the fundamental representation of network state, that is, the overall status of each participant in the network at a given time. However, this structure has the following disadvantages:
Potential block producers may be hobbled by network latency.
Not all valid work is rewarded.
Decentralization and collaboration in block production are not incentivized.
Because Filecoin is a chain of tipsets rather than individual blocks, the network enjoys the following benefits:
All valid blocks generated in a given round are used to determine network state, increasing network efficiency and throughput.
All valid work is rewarded (that is, all validated block producers in an epoch receive a block reward).
All potential block producers are incentivized to produce blocks, disincentivizing centralization and promoting collaboration.
Because all blocks in a tipset have the same height and parent, Filecoin is able to achieve rapid convergence in the case of forks.
In summary, blocks, which contain actor messages, are grouped into tipsets in each epoch, which can be thought of as the overall description of the network state for a given epoch.
Wherever you see the term block in the Ethereum JSON-RPC, you should mentally read tipset. Before the inclusion of the Filecoin EVM runtime, there was no single hash referring to a tipset. A tipset ID was the concatenation of block CIDs, which led to a variable-length ID and poor user experience.
With the Ethereum JSON-RPC, we introduced the concept of the tipset CID for the first time. It is calculated by hashing the former tipset key using a Blake-256 hash. Therefore, when you see the term:
block hash, think tipset hash.
block height, think tipset epoch.
block messages, think messages in all blocks in a tipset, in their order of appearance, deduplicated and returned in canonical order of execution.
In the Filecoin blockchain, network consensus is achieved using the Expected Consensus (EC) algorithm, a secret, fair, and verifiable consensus protocol used by the network to agree on the chain state
In the Filecoin blockchain, network consensus is achieved using the Expected Consensus (EC) algorithm, a probabilistic, Byzantine fault-tolerant consensus protocol. At a high level, EC achieves consensus by running a secret, fair, and verifiable leader election at every epoch where a set number of participants may become eligible to submit a block to the chain based on fair and verifiable criteria.
Expected Consensus (EC) has the following properties:
Each epoch has potentially multiple elected leaders who may propose a block.
A winner is selected randomly from a set of network participants weighted according to the respective storage power they contribute to the Filecoin network.
All blocks proposed are grouped together in a tipset, from which the final chain is selected.
A block producer can be verified by any participant in the network.
The identity of a block producer is anonymous until they release their block to the network.
In summary, EC involves the following steps at each epoch:
A storage provider checks to see if they are elected to propose a block by generating an election proof.
Zero, one, or multiple storage providers may be elected to propose a block. This does not mean that an elected participant is guaranteed to be able to submit a block. In the case where:
No storage providers are elected to propose a block in a given epoch; a new election is run in the next epoch to ensure that the network remains live.
One or more storage providers are elected to propose a block in a given epoch; each must generate a WinningPoSt proof-of-storage to be eligible to actually submit a block.
Each potential block producer elected generates a storage proof using WinningPoSt for a randomly selected sector within in short window of time. Potential block producers that fail this step are not eligible to produce a block. In this step, the following could occur:
All potential block producers fail WinningPoSt, in which case EC returns to step 1 (described above).
One or more potential block producers pass WinningPoSt, which means they are eligible to submit that block to the epochs tipset.
Blocks generated by block producers are grouped into a tipset.
The tipset that reflects the biggest amount of committed storage on the network is selected.
Using the selected tipset, the chain state is propagated.
EC returns to step 1 in the next epoch.
Drand, pronounced dee-rand, is a distributed randomness beacon daemon written in Golang.
This page covers how Drand is used within the Filecoin network. For more information on Drand generally, take a look at the project’s documentation.
By polling the appropriate endpoint, a Filecoin node will get back a Drand value formatted as follows:
signature: the threshold BLS signature on the previous signature value and the current round number round.
previous_signature: the threshold BLS signature from the previous Drand round.
round: the index of randomness in the sequence of all random values produced by this Drand network.
The message signed is the concatenation of the round number treated as a uint64 and the previous signature. At the moment, Drand uses BLS signatures on the BLS12-381 curve with the latest v7 RFC of hash-to-curve, and the signature is made over G1.
Filecoin nodes fetch the Drand entry from the distribution network of the selected Drand network.
Drand distributes randomness using multiple distribution channels such as HTTP servers, S3 buckets, gossiping, etc. Simply put, the Drand nodes themselves will not be directly accessible by consumers; rather, highly-available relays will be set up to serve Drand values over these distribution channels.
On initialization, Filecoin initializes a Drand client with chain info that contains the following information:
Period: the period of time between each Drand randomness generation.
GenesisTime: at which the first round in the Drand randomness chain is created.
PublicKey: the public key to verify randomness.
GenesisSeed: the seed that has been used for creating the first randomness.
It is possible to simply store the hash of this chain info and to retrieve the contents from the Drand distribution network as well on the /info endpoint.
Thereafter, the Filecoin client can call Drand’s endpoints:
/public/latest to get the latest randomness value produced by the beacon.
/public/<round> to get the randomness value produced by the beacon at a given round.
Drand is used as a randomness beacon for leader election in Filecoin. While Drand returns multiple values with every call to the beacon (see above), Filecoin blocks need only store a subset of these in order to track a full Drand chain. This information can then be mixed with on-chain data for use in Filecoin.
Any Drand beacon outage will effectively halt Filecoin block production. Given that new randomness is not produced, Filecoin miners cannot generate new blocks. Specifically, any call to the Drand network for a new randomness entry during an outage should be blocked in Filecoin.
After a beacon downtime, Drand nodes will work to quickly catch up to the current round. In this way, the above time-to-round mapping in Drand used by Filecoin remains invariant after this catch-up following downtime.
While Filecoin miners were not able to mine during the Drand outage, they will quickly be able to run leader election thereafter, given a rapid production of Drand values. We call this a catch-up period.
During the catch-up period, Filecoin nodes will backdate their blocks in order to continue using the same time-to-round mapping to determine which Drand round should be integrated according to the time. Miners can then choose to publish their null blocks for the outage period, including the appropriate Drand entries throughout the blocks, per the time-to-round mapping. Or, as is more likely, try to craft valid blocks that might have been created during the outage.
Based on the level of decentralization of the Filecoin network, we expect to see varying levels of miner collaboration during this period. This is because there are two incentives at play: trying to mine valid blocks during the outage to collect block rewards and not falling behind a heavier chain being mined by a majority of miners who may or may not have ignored a portion of these blocks.
In any event, a heavier chain will emerge after the catch-up period and mining can resume as normal.
In Filecoin cryptographic proving systems, often simply referred to as proofs, are used to validate that a storage provider (SP) is properly storing data.
Different blockchains use different cryptographic proving systems (proofs) based on the network’s specific purpose, goals, and functionality. Regardless of which method is used, proofs have the following in common:
All blockchain networks seek to achieve consensus and rely on proofs as part of this process.
Proofs incentivize network participants to behave in certain ways and allow the network to penalize participants who do not abide by network standards.
Proofs allow decentralized systems to agree on a network state without a central authority.
Proof-of-Work and Proof-of-Stake are both fairly common proof methods:
Proof-of-Work: nodes in the network solve complex mathematical problems to validate transactions and create new blocks,
Proof-of-Stake: nodes in the network are chosen to validate transactions and create new blocks based on the amount of cryptocurrency they hold and “stake” in the network.
The Filecoin network aims to provide useful, reliable storage to its participants. With a traditional centralized entity like a cloud storage provider, explicit trust is placed in the entity itself that the data will be stored in a way that meets some minimum set of standards such as security, scalability, retrievability, or replication. Because the Filecoin network is a decentralized network of storage providers (SPs) distributed across the globe, network participants need an automated, trustless, and decentralized way to validate that an SP is doing a good job of handling the data.
In particular, the Filecoin proof process must verify the data was properly stored at the time of the initial request and is continuing to be stored based on the terms of the agreement between the client and the SP. In order for the proof processes to be robust, the process must:
Target a random part of the data.
Occur at a time interval such that it is not possible, profitable, or rational for an SP to discard and re-fetch the copy of data.
In Filecoin, this process is known as Proof-of-Storage, and consists of two distinct types of proofs:
Proof of Replication (PoRep): a procedure used at the time of initial data storage to validate that an SP has created and stored a unique copy of some piece of data.
Proof of Spacetime (PoST): a procedure to validate that an SP is continuing to store a unique copy of some piece of data.
In the Filecoin storage lifecycle process, Proof-of-Replication (PoRep) is used when an SP agrees to store data on behalf of a client and receives a piece of client data. In this process:
The data is placed into a sector.
The sector is sealed by the SP.
A unique encoding, which serves as proof that the SP has replicated a copy of the data they agreed to store, is generated (described in Sealing as proof).
The proof is compressed.
The result of the compression is submitted to the network as certification of storage.
The unique encoding created during the sealing process is generated using the following pieces of information:
The data is sealed.
The storage provider who seals the data.
The time at which the data was sealed.
Because of the principles of cryptographic hashing, a new encoding will be generated if the data changes, the storage provider sealing the data changes, or the time of sealing changes. This encoding is unique and can be used to verify that a specific storage provider did, in fact, store a particular piece of client data at a specific time.
After a storage provider has proved that they have replicated a copy of the data that they agreed to store, the SP must continue to prove to the network that:
They are still storing the requested data.
The data is available.
The data is still sealed.
Because this method is concerned with proving that data is being stored in a particular space for a particular period or at a particular time, it is called Proof-of-Spacetime (PoSt). In Filecoin, the PoSt process is handled using two different sub-methods, each of which serves a different purpose:
WinningPoSt is used to prove that an SP selected using an election process has a replica of the data at the specific time that they were asked and is used in the block consensus process.
WindowPoSt is used to prove that, for any and all SPs in the network, a copy of the data that was agreed to be stored is being continuously maintained over time and is used to audit SPs continuously.
WinningPoSt is used to prove that an SP selected via election has a replica of the data at the specific time that they were asked and is specifically used in Filecoin to determine which SPs may add blocks to the Filecoin blockchain.
At the beginning of each epoch, a small number of SPs are elected to mine new blocks using the Expected Consensus algorithm, which guarantees that validators will be chosen based on a probability proportional to their power. Each of the SPs selected must submit a WinningPoSt, proof that they have a sealed copy of the data that they have included in their proposed block. The deadline to submit this proof is the end of the current epoch and was intentionally designed to be short, making it impossible for the SP to fabricate the proof. Successful submission grants the SP:
The block reward .
The opportunity to charge other nodes fees in order to include their messages in the block.
If an SP misses the submission deadline, no penalty is incurred, but the SP misses the opportunity to mine a block and receive the block reward.
WindowPoSt is used to prove that, for any and all SPs in the network, a copy of the data that was agreed to be stored is being continuously maintained over time and is used to audit SPs continuously. In WindowPoSt, all SPs must demonstrate the availability of all sectors claimed every proving period. Sector availability is not proved individually; rather, SPs must prove a whole partition at once, and that sector must be proved by the deadline assigned (a 30-minute interval in the proving period).
The more sectors an SP has pledged to store, the more the partitions of sectors that the SP will need to prove per deadline. As this requires that the SP has access to sealed copies of each of the requested sectors, it makes it irrational for the SP to seal data every time they need to provide a WindowPoSt proof, thus ensuring that SPs on the network are continuously maintaining the data agreed to. Additionally, failure to submit WindowPoSt for a sector will result in the SPs’ pledge collateral being forfeited and their storage power being reduced.