| Field | Purpose |
|---|---|
description | SEO description and link previews. Supports multiline with >-. |
icon | Font Awesome icon name (e.g., bolt, book-open). |
hidden: true | Hides page from the table of contents. |
layout.width | default or wide for broader content area. |
Advanced configuration
Detailed information that most users do not need. ```yaml advanced: option1: value1 ```| Title | Target |
|---|---|
| Getting started | Start here |
| Goal | Keyword | Explanation |
|---|---|---|
| Audience | General | Easy for anyone to read with minimal effort. |
| Formality | Neutral | Slang is restricted, but standard casual expressions are allowed. |
| Domain | Technical | Acronyms and tech-specific language is used and expected. |
| Tone | Neutral | Writing contains little to no emotion. |
| Intent | Instruct | Tell the reader how to do something. |
| Goal | Keyword | Explanation |
|---|---|---|
| Audience | Knowledgeable | Requires a certain amount of focus to understand. |
| Formality | Neutral | Slang is restricted, but standard casual expressions are allowed. |
| Domain | Any | Usually technical, but depends on the article. |
| Tone | Confident and friendly | The reader must feel confident that the writer knows what they're talking about. |
| Intent | Describe | Tell the reader why something does the thing that it does, or why it exists. |
## This is a title
### Only capitalize names and places
### The capital city of France is Paris
` or `#` tag. There is only ever one title of this level in each article. 1. Titles do not contain punctuation. If you have a question within your title, rephrase it as a statement: ```markdown ## What is Filecoin? ## Filecoin explained ``` **Bold text** Double asterisks `**` are used to define **boldface** text. Use bold text when the reader must interact with something displayed as text: buttons, hyperlinks, images with text in them, window names, and icons. ```markdown In the **Login** window, enter your email into the **Username** field and click **Sign in**. ``` **Italics** Underscores `_` are used to define *italic* text. Style the names of things in italics, except input fields or buttons: ```markdown Here are some American things: - The _Spirit of St Louis_. - The _White House_. - The United States _Declaration of Independence_. Try entering them into the **American** field and clicking **Accept**. ``` Quotes or sections of quoted text are styled in italics and surrounded by double quotes `"`: ```markdown In the wise words of Winnie the Pooh _"People say nothing is impossible, but I do nothing every day."_ ``` **Code blocks** Tag code blocks with the syntax of the core they are presenting: ````markdown ```javascript console.log(error); ``` ```` Output from command-line actions can be displayed by adding another codeblock directly after the input codeblock. Here's an example telling the use to run `go version` and then the output of that command in a separate codeblock immediately after the first: ````markdown ```shell go version ``` ```plaintext go version go1.19.7 darwin/arm64 ``` ```` Command-line examples can be truncated with three periods `...` to remove extraneous information: ````markdown ```shell lotus-miner info ``` ```shell Miner: t0103 Sector Size: 16.0 MiB ... Sectors: map[Committing:0 Proving:0 Total:0] ``` ```` **Inline code tags** Surround directories, file names, and version numbers between inline code tags `` ` ``. ```markdown Version `1.2.0` of the program is stored in `~/code/examples`. Open `exporter.exe` to run the program. ``` **List items** All list items follow sentence structure. Only *names* and *places* are capitalized, along with the first letter of the list item. All other letters are lowercase: 1. Never leave Nottingham without a sandwich. 2. Brian May played guitar for Queen. 3. Oranges. List items end with a period `.`, or a colon `:` if the list item has a sub-list: 1. Charles Dickens novels: 1. Oliver Twist. 2. Nicholas Nickelby. 3. David Copperfield. 2. J.R.R Tolkien non-fiction books: 1. The Hobbit. 2. Silmarillion. 3. Letters from Father Christmas. **Unordered lists** Use the asterisk character `*` for un-numbered list items: ```markdown * An apple. * Three oranges. * As many lemons as you can carry. * Half a lime. ``` **Special characters** Whenever possible, spell out the name of the special character, followed by an example of the character itself within a code block. ```markdown Use the dollar sign `$` to enter debug-mode. ``` **Keyboard shortcuts** When instructing the reader to use a keyboard shortcut, surround individual keys in code tags: ```shell Press `ctrl` + `c` to copy the highlighted text. ``` The plus symbol `+` stays outside of the code tags. #### Images The following rules and guidelines define how to use and store images. **Alt text** All images contain alt text so that screen-reading programs can describe the image to users with limited sight: ```markdown  ``` [Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/ways-to-contribute) # Filecoin Virtual Machine The Filecoin Virtual Machine (FVM) is a runtime environment enabling users to deploy their own smart contracts on the Filecoin blockchain. This page covers the basics of the FVM. NOTE: As of January 2025, for developer support, please visit the [FILB](https://fil.builders/) website. For Filecoin product updates, please visit the [FILOz](https://www.filoz.org/) website or see the Lotus [Github discussion page](https://github.com/filecoin-project/lotus/discussions). ## Introduction Filecoinâs storage and retrieval capabilities can be thought of as the base layer of the Filecoin blockchain, and [FVM](https://fvm.filecoin.io) can be thought of as a layer on top of Filecoin that unlocks programmability on the network (e.g. programmable storage primitives). Whereas other blockchains do have smart contract capabilities, FVMâs smart contracts can use Filecoin storage and retrieval primitives with computational logic conditions. FVM will also enable Layer 2 capabilities, such as âcompute over dataâ and [content delivery networks](https://github.com/filecoin-saturn). Some additional notes about FVMâs technical specifications: * WASM-based: The FVM is a WASM-based polyglot execution environment for IPLD data, meaning that FVM gives developers access to IPFS / IPLD data primitives and can accommodate smart contracts (actors) written in any programming language that compiles to WASM. * FEVM Compatibility: Are you an Ethereum / Solidity developer? You can build the next killer app on FVM and make use of the [Filecoin Solidity library](https://docs.zondax.ch/fevm/filecoin-solidity/). Learn more about how FVM is Ethereum runtime and solidity compatible in the next section. * VM Agnostic: The FVM is built to be VM-agnostic, meaning support for other foreign VMs can be added in the near future. Future versions of FVM can serve as a useful hypervisor enabling cross run-time invocations. FVM brings user programmability to Filecoin, unleashing the enormous potential of an open data economy through various applications. ### Use Cases FVM Actors enable a huge range of use cases to be built on Filecoin. Here are just a few potential examples: * Data Access Control: FVM Actors can enable a client to grant retrieval permission for certain files to a limited set of third-party Filecoin wallet addresses. * DataDAO: FVM Actors can enable the creation of decentralized autonomous organizations where members govern and manage the storage, accessibility, and monetization of certain data sets and pool returns into a shared treasury. * Perpetual Storage: Because all Filecoin storage deals are time-limited, when a client makes a deal with a storage provider to store a data set with them, the client has to begin to consider whether they will want to renew this deal for the next time-period with the same storage provider or seek out other storage providers that may be cheaper. However, FVM enables a client to automatically renew deals or find a cheaper storage provider when the time limit of a given deal has reached maturity. This automated renewal of deals can persist, even in perpetuity, for as many cycles as can be financed by an associated endowment of FIL. FVM Actors enable the creation and management of this endowment. * Replication: In addition to allowing a client to store one data set with one storage provider in perpetuity, FVM Actors enable data resiliency by allowing a client to store one data set once manually and then have the Actor replicate that data with multiple other storage providers automatically. Additional conditions that can be set in an automated replication Actor include choices about the geographic region of the storage providers, latency, and deal price limits. * Leasing: FVM Actors enable a FIL token holder to provide collateral to clients looking to do a storage deal, and be repaid the principal and interest over time. FVM Actors can also trace the borrowing and repayment history of a given client, generating a community-developed reputation score. Additional use cases enabled by FVM include, but are not limited to, tokenized data sets, trustless reputation systems, NFTs, storage bounties and auctions, Layer 2 bridges, futures and derivatives, or conditional leasing. ### Start building on the FVM If youâre ready to start building on the FVM, here are some resources you should explore: * FVM Reference Implementation: The [Github repo](https://github.com/filecoin-project/ref-fvm) containing the reference implementation for FVM. * FVM Quickstart Guide: The Quickstart guide will walk you through deploying your first ERC-20 contract on FVM. In addition to being provided this code, we also walk you through the developer environment set-up. * Developing Contracts: If you are ready to build your dApp on FVM, you can skip ahead and review our [best practices](/build-on-filecoin/developing-contracts/best-practices) section for developing contracts. Here, you can find a guide for the Filecoin solidity libraries, details on tools such as Foundry, Remix, and Hardhat, and tutorials for calling built-in actors and building client contracts. The next page will walk you through the process of deciding whether you need to use FVMâs programmatic storage when building a dApp with storage on Filecoin. [Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-virtual-machine) # Actors 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](/core-concepts/filecoin-virtual-machine). In the Filecoin network, there are two types of actors: * [*Built-in 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*](#user-actors-smart-contracts): Code implemented by **any developer** that interacts with the Filecoin Virtual Machine (FVM). ## Built-in actors 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: 1. The [`StorageMinerActor`](#storagemineractor) processes proof of storage from a storage provider. 2. The storage provider is awarded storage power based on whether the proof is valid or not. 3. The [`StoragePowerActor`](#storagepoweractor) accounts for the storage power. 4. During block validation, the [`StoragePowerActor`](#storagepoweractor) state, which includes information on storage power allocated to each storage provider, is read. 5. Using the state information, the consensus mechanism randomly awards blocks to the storage providers with the most power, and the [`RewardActor`](#rewardactor) sends FIL to storage providers. ### Blocks 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. ### State tree A [Merkle Directed Acyclic Graph (Merkle DAG)](/reference/general/glossary#merkle-directed-acyclic-graph) 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 ### Messages 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 ### Actor code 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. ### Types of built-in actors The 11 different types of built-in actors are as follows: * [CronActor](#cronactor) * [InitActor](#initactor) * [AccountActor](#accountactor) * [RewardActor](#rewardactor) * [StorageMarketActor](#storagemarketactor) * [StorageMinerActor](#storagemineractor) * [MultisigActor](#multisigactor) * [PaymentChannelActor](#paymentchannelactor) * [StoragePowerActor](#storagepoweractor) * [VerifiedRegistryActor](#verifiedregistryactor) * [SystemActor](#systemactor) #### CronActor 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. #### InitActor 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. #### AccountActor 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. #### RewardActor 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. #### StorageMarketActor 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. #### StorageMinerActor 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. #### MultisigActor 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. #### PaymentChannelActor 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. #### StoragePowerActor 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. #### VerifiedRegistryActor 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. #### SystemActor For more information on `SystemActor`, see the [source code](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/system/system_actor.go). ## User actors (smart contracts) 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*](#user-actors-smart-contracts). 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. [Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-virtual-machine/actors) # Addresses 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:
| Address prefix | Description |
|---|---|
0 | An ID address. |
1 | A SECP256K1 public key address. |
2 | An actor address. |
3 | A BLS public key address. |
4 | Extensible, user-defined actor addresses. f410 addresses refers to Ethereum-compatible address space, each f410 address is equivalent to an 0x address. |
| Filecoin Pin Repository | https://github.com/filecoin-project/filecoin-pin | https://github.com/filecoin-project/filecoin-pin |
| Filecoin Pin Support Channels | Filecoin Slack - #fil-foc | https://filecoinproject.slack.com/archives/C07CGTXHHT4 |
Base Sepolia block explorer, showing NFT minted