> This is part 1 of 2 of the full documentation (pages 1–100 of 190).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.filecoin.io/llms-full.txt/1
> Page index: https://docs.filecoin.io/llms.txt
# Welcome to Filecoin Docs
Filecoin is a decentralized, peer-to-peer network enabling anyone to store and retrieve data over the internet. Economic incentives are built in, ensuring files are stored and accessible reliably over
Choose your own path to start exploring Filecoin:
💡 Get started
New to Filecoin and looking for foundational concepts? Start with the Getting Started section to understand the essentials and kick off your journey!
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/)
# Quickstart
Start storing data on Filecoin in minutes. Set up and fund your account, create a session key, and upload with the tool you prefer.
**Storing data on Filecoin takes three steps: fund your account, create a session key, and connect the tool you want to store data with.**
You'll need an email or Google account, or a wallet you already use, plus a payment card, USDC, or USDFC to add funds.
## 1. Set up and fund your account
1. **Open the console.** Go to [pay.filecoin.cloud/console](https://pay.filecoin.cloud/console?utm_source=docs\&utm_medium=quickstart\&utm_campaign=relaunch\&foc_ref=docs-quickstart).
2. **Sign in.** New to crypto? Continue with email or Google, and the console creates a Filecoin Pay wallet for you. Already use MetaMask or another wallet? Connect it instead.
3. **Add funds.** Select **Add funds** and choose a method:
* **Buy USDC with card:** buy USDC on Base, then swap and deposit it into Filecoin Pay.
* **Swap to USDFC:** pay USDC from another chain and deposit the resulting USDFC.
* **Deposit token:** deposit USDFC you already hold on Filecoin.
4. **Add the storage service.** Select **Deposit and Add Service**, choose **Filecoin Warm Storage**, enter a deposit amount, and confirm in your wallet. Funds stay in your account, and the service bills them as you use it. If you already deposited in step 3, leave the amount empty.
> Your wallet also needs a little FIL for transaction fees. Buying with a card or swapping to USDFC adds 0.05 FIL by default. If you deposit USDFC you already hold, the console shows how much FIL to add and lets you add it.
## 2. Create a session key
A session key lets a tool upload data for you without holding your wallet key. It can't move your funds.
1. Open [Session keys](https://pay.filecoin.cloud/console/session-keys) in the console and select **+ New session key**.
2. Select the scopes **Create data set** and **Add pieces**, and pick an expiration (30 days by default).
3. Select **Create session key** and confirm in your wallet.
4. Copy the key or select **Download .env**. The key is shown only once, so save it before you close the dialog.
You can revoke a key on the same page at any time.
## 3. Start storing data
Pick the tool that fits how you work, then use your session key to connect it.
* [**CLI**](https://github.com/filecoin-project/filecoin-pin)**:** store files from your terminal with Filecoin Pin.
* [**SDK**](https://docs.filecoin.cloud/getting-started/)**:** build storage into your app with the Synapse SDK.
* [**Agent skill**](/core-concepts/filecoin-for-agents)**:** let your AI agent store files for you.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/quickstart)
# What is Filecoin
This section offers a detailed overview of Filecoin for developers, serving as a go-to reference for their needs.
### Introduction to Filecoin
Filecoin is a peer-to-peer network that enables reliable, decentralized file storage through built-in economic incentives and cryptographic proofs. Clients, or users, pay any number of storage providers, or data centers, to store the client's data --storage providers then provide cryptographic proofs daily as evidence to the clients that the data is still at the data center. Storage providers lock a certain amount of Filecoin as collateral --should they repeatedly fail to provide a proof, their collateral gets burned, serving as a strong deterrent from the data center losing the data.
Anyone can join Filecoin as a client looking to store their data, or as a storage provider offering storage services. Storage availability and pricing aren’t controlled by any single entity; instead, Filecoin fosters an open market for file storage and retrieval accessible to all. Clients can review the history of each storage provider, along with their credentials and compliance record, before choosing to store their data with them.
Note that most Filecoin nodes are [IPFS protocol](https://docs.ipfs.tech/) nodes. IPFS is a open system, a hypermedia protocol, to manage data without a central server that makes use of [content addressing](https://docs.ipfs.tech/concepts/content-addressing/) to provide permanent data references without dependency on specific devices or cloud providers. A client who knows the content address (CID) of their file can retrieve it from any IPFS node (or Filecoin storage provider) that currently has a copy and is able to serve it. Given a CID, the [CID Contact](https://cid.contact/) network indexer will locate and providing routing details for the relevant file.
Historically, IPFS node operators offered pinning services to the community out of interest and often for free, meaning there was no financial incentive for the IPFS node operators to stay online or keep a given file for a long period of time. Filecoin solves this issue by introducing an incentive layer (clients pay storage providers for long term data center use) to ensure more reliable long term cold storage. Since most Filecoin nodes are also IPFS nodes, they can pin a hot copy of the given file to the IPFS node to allow the client to easily retrieve the file later.
Filecoin is used as a storage solution for a range of products, including from Web3-native NFT storage, incentivized permanent storage, and archival traditional Web2 datasets. For instance, [NFT.Storage](https://nft.storage/) leverages Filecoin for NFT content and metadata storage. Organizations such as the [Shoah Foundation](https://sfi.usc.edu/) and the [Internet Archive](https://archive.org/) use Filecoin for content preservation and backup.
Filecoin is compatible with various data types, including audio and video files. This versatility allows Web3 platforms like [Audius](https://audius.co/) and [Huddle01](https://huddle01.com/) to use Filecoin as a decentralized storage backend for music streaming and video conferencing.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin)
# Crypto-economics
Crypto-economics is the study of how cryptocurrency can incentivize usage of a blockchain network. This page covers how Filecoin manages incentivization within the network.
## Native currency
Filecoin’s native currency, FIL, is a utility token that incentivizes persistent storage on the Filecoin network. Storage providers earn FIL by offering reliable storage services or committing storage capacity to the network. With a maximum circulating supply of 2 billion FIL, no more than 2 billion Filecoin will ever exist.
As a utility token aligned with the network’s long-term growth, Filecoin issuance depends on the network’s provable utility and growth. Most of the Filecoin supply is only minted as the network achieves specific growth and utility milestones.
Filecoin uses a dual minting model for block reward distribution:
## Baseline minting
Up to 770 million FIL tokens are minted based on network performance. Full release of these tokens would only occur if the Filecoin network reaches a yottabyte of storage capacity within 20 years, approximately 1,000 times the capacity of today’s cloud storage.
## Simple minting
An additional 330 million FIL tokens are released on a 6-year half-life schedule, with 97% of these tokens projected to be released over about 30 years.
Additionally, 300 million FIL tokens are held in a mining reserve to incentivize future mining models.
## Vesting
Mining rewards are subject to a vesting schedule to support long-term network alignment. For instance, 75% of block rewards earned by miners vest linearly over 180 days, while 25% are immediately accessible, improving miner cash flow and profitability. Note that if the miner has incurred "[fee debt](/provide-storage/filecoin-economics/slashing)," the immediately accessible block rewards will automatically go towards paying down those fees.
A certain portion of initially printed FIL tokens are vested to Protocol Labs teams and the Filecoin Foundation over six years, and to SAFT investors over three years, as outlined in the [vesting schedule](https://observablehq.com/@starboard/a-primer-to-filecoin-circulating-supply/2).
To learn more about Filecoin block rewards vesting, review [FIP004: Liquidity Improvement for Storage Miners](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0004.md).
## Collateral and slashing
To ensure network security and reliable storage, storage providers must lock FIL as pledge collateral during block reward mining. Pledge collateral is based on projected block rewards a miner could earn. Collateral and all earned rewards are subject to slashing if the storage fails to meet reliability standards throughout a sector’s lifecycle.
## Total supply
FIL’s maximum circulating supply is capped at 2 billion FIL. However, this maximum will never be reached, as a portion of FIL is permanently removed from circulation through gas fees, penalties, and other mechanisms.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin/crypto-economics)
# Blockchain
A blockchain is a distributed database shared among nodes in a computer network. This page covers the design and functions of the Filecoin blockchain.
## Blockchain
### Tipsets
A tipset is a set of blocks with the same height, allowing multiple storage providers to produce blocks in each epoch, increasing network throughput. The Filecoin blockchain consists of a chain of tipsets rather than individual blocks. Each tipset is assigned a weight, enabling the consensus protocol to guide nodes to build on the heaviest chain and preventing interference from nodes attempting to produce invalid blocks.
### Actors
Actors are ‘objects’ within the Filecoin network, each with a state and a set of methods for interaction, that pass messages to each other and ensure the system operates appropiately.
#### Built-in actors
Several built-in system actors power the Filecoin network as a decentralized storage network:
* **Init actor**: Initializes new actors and records the network name.
* **Cron actor**: Scheduler that runs critical functions at every epoch.
* **Account actor**: Manages user accounts (non-singleton).
* **Reward actor**: Manages block rewards and token vesting (singleton).
* **Storage miner actor**: Manages storage mining operations and validates storage proofs.
* **Storage power actor**: Tracks storage power allocation for each provider.
* **Storage market actor**: Manages storage deals.
* **Multisig actor**: Handles Filecoin multi-signature wallet operations.
* **Payment channel actor**: Sets up and settles payment channel funds.
* **Datacap actor**: Manages datacap tokens.
* **Verified registry actor**: Manages verified clients.
* **Ethereum Address Manager (EAM) actor**: Assigns Ethereum-compatible addresses on Filecoin, including EVM smart contract addresses.
* **Ethereum Virtual Machine (EVM) account actor**: Represents an external Ethereum identity backed by a secp256k1 key.
* **System actor**: General system actor.
### Nodes
Filecoin nodes are categorized by the services they provide to the storage network, including chain verifier nodes, client nodes, storage provider nodes, and retrieval provider nodes. All participating nodes must provide chain verification services.
Filecoin supports multiple protocol implementations to enhance security and resilience. Active implementations include:
* [Lotus](https://lotus.filecoin.io/)
* [Venus](https://github.com/filecoin-project/venus)
* [Forest](https://github.com/ChainSafe/forest)
### Addresses
In the Filecoin network, addresses identify actors in the Filecoin state. Each address encodes information about the corresponding actor, making it easy to use and resistant to errors. Filecoin has five address types. Mainnet addresses start with `f`, and Testnet addresses start with `t`.
* **`f0/t0`**: ID address for an actor in a human-readable format, such as `f0123261` for a storage provider.
* **`f1/t1`**: secp256k1 wallet address, generated from an encrypted secp256k1 public key.
* **`f2/t2`**: Address assigned to an actor in a way that ensures stability across network forks.
* **`f3/t3`**: BLS wallet address, generated from a BLS public key.
* **`f4/t4`**: Address created and assigned to user-defined actors by customizable "address management" actors. This address can receive funds before an actor is deployed.
* **`f410/t410`**: Address space managed by the Ethereum Address Manager (EAM) actor, allowing Ethereum-compatible addresses to interact seamlessly with the Filecoin network. Ethereum addresses can be cast as `f410/t410` addresses and vice versa, enabling compatibility with existing Ethereum tools.
### Consensus
#### Expected consensus
Expected Consensus (EC) is the probabilistic, Byzantine fault-tolerant consensus algorithm underlying Filecoin. EC conducts a leader election among storage providers each epoch to determine which provider submits a block. Similar to proof-of-stake, Filecoin’s leader election relies on proof-of-storage, meaning the probability of being elected depends on how much provable storage a miner contributes to the network --measured in something called "storage power".
The consensus process uses [Drand](https://drand.love) as a randomness beacon for leader election, ensuring the leader election is secret, fair, and verifiable. Election participants and their storage power are drawn from a data structure called the "Power Table", which is continuously calculated and maintained by the storage power actor.
Ultimately, the EC process ends by gathering all valid blocks produced in an epoch to a tipset, applying a weighting function to select the heaviest chain, and adding the tipset to the heaviest chain accordingly.
#### Block production process
The block production process for each epoch is as follows:
* Elect leaders from eligible miners.
* Miners check if they are elected.
* Elected miners generate WinningPoSt using randomness.
* Miners build and propagate a block.
* Verify the winning miner and election.
* Select the heaviest chain to add the tipset.
#### Finality
EC enforces soft finality, where miners at round `N` reject blocks forking off before round `N - F` (where `F` is set to `900`). This ensures finality without compromising chain availability.
### Proofs
Filecoin operates on proof-of-storage, where miners offer storage space and provide proofs to verify data storage.
#### Proof of replication
With proof-of-replication (PoRep), storage providers prove they have created a unique copy of the client’s data for the network.
#### Proof of spacetime
Storage providers must continuously prove that they are storing clients' data throughout the entire duration of the storage deal. The proof-of-spacetime (PoSt) process includes two types of challenges:
* **Winning PoSt**: Verifies that a storage provider holds a copy of the data at a specific point in time.
* **Window PoSt**: Confirms that the data has been consistently stored over a defined period.
#### Slashing
If storage providers fail to maintain reliable uptime or act maliciously, they face penalties through a process called slashing. Filecoin enforces two types of slashing:
* **Storage Fault Slashing**: Penalizes providers who fail to maintain healthy and reliable storage sectors.
* **Consensus Fault Slashing**: Penalizes providers attempting to disrupt the security or availability of the consensus process.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin/blockchain)
# Storage model
A storage model defines how data is stored within a system. This page covers the basic aspects of Filecoin’s storage model.
The Filecoin storage model consists of three main components:
* Providers
* Deals
* Sectors
## Providers
Providers offer storage and retrieval services to network users. There are two types of providers:
* Storage Providers
* Retrieval Providers
### Storage providers
Storage providers, often called SPs, are responsible for storing files and data for clients on the network. They also provide cryptographic proofs to verify that data is stored securely. The majority of providers on the Filecoin network are SPs.
### Retrieval providers
Retrieval providers, or RPs, specialize in delivering quick access to data rather than long-term storage. While many storage providers also offer retrieval services, stand-alone RPs are increasingly joining the network to enhance data accessibility.
## Deals
In the Filecoin network, SPs and RPs offer storage or retrieval services to clients through deals. These deals are negotiated between two parties and outline terms such as data size, price, duration, and collateral.
The deal-making process initially occurs *off-chain*. Once both parties agree to the terms, the deal is published *on-chain* for network-wide visibility and validation.
## Sectors
Sectors are the fundamental units of provable storage where storage providers securely store client data and generate PoSt (Proof of Spacetime) for the Filecoin network. Sectors come in standard sizes, typically `32 GiB` or `64 GiB`, and have a set lifespan that providers can extend before it expires.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin/storage-model)
# Storage market
The storage market is the entry point where storage providers and clients negotiate and publish storage deals on-chain.
## Deal making
The lifecycle of a deal within the storage market includes four distinct phases:
* **Discovery**: The client identifies potential storage providers (SPs) and requests their prices.
* **Negotiation**: After selecting an SP, both parties agree to the terms of the deal.
* **Publishing**: The deal is published on-chain.
* **Handoff**: The deal is added to a sector, where the SP can provide cryptographic proofs of data storage.
## Filecoin Plus
Filecoin Plus aims to maximize useful storage on the Filecoin network by incentivizing the storage of meaningful and valuable data. It offers verified clients low-cost or free storage through a system called datacap, a storage quota that boosts incentives for storage providers.
Verified clients use datacap allocated by community-selected allocators to store data on the network. In exchange for storing verified deals, storage providers receive a 10x boost in storage power, which increases their block rewards as an incentive.
* **Datacap**: A token allocated to verified clients to spend on storage deals, offering a 10x quality multiplier for deals.
* **Allocators**: Community-selected entities responsible for verifying storage clients and allocating datacap tokens.
* **Verified Clients**: Active participants with datacap allocations for their data storage needs.
## Storage on-ramps
To simplify data storage on the Filecoin network, several tools offer streamlined integration of Filecoin and IPFS storage for applications or smart contracts.
These storage helpers provide libraries that abstract the Filecoin deal-making process into simple API calls. They also store data on IPFS for efficient and fast content retrieval.
Available storage helpers include:
* [Filecoin Onchain Cloud](/build-on-filecoin/filecoin-onchain-cloud): A programmable, on-chain storage platform with verifiable storage proofs and automatic payments (Filecoin Pay). Warm storage is accessed through the Synapse SDK, and the [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss) stores sealed copies of large datasets.
* [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin/getting-started): A CLI and API path for pinning IPFS-compatible content to Filecoin-backed storage with Filecoin Pay.
* [fil.one](https://fil.one/): S3-compatible object storage backed by Filecoin, with flat per-terabyte pricing and no egress fees.
* [lighthouse.storage](https://www.lighthouse.storage/): An SDK for builders, providing tools for storing data from dApps.
* [Akave](https://www.akave.ai/): A modular L2 solution for decentralized data management, combining Filecoin storage with encryption and easy-to-use interfaces.
* [Pinata](https://pinata.cloud/): An IPFS pinning service for storing and serving files, media, and app data over IPFS.
* [Curio](https://curiostorage.org/): A next-gen platform within the Filecoin ecosystem, streamlining storage provider operations.
* [boost.filecoin.io](https://boost.filecoin.io/): A tool for storage providers to manage data onboarding and retrieval on the Filecoin network.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin/storage-market)
# Retrieval
Retrieval is how users fetch content from Filecoin storage providers, IPFS, and Filecoin-backed storage services.
Retrieval means fetching stored data back from Filecoin. The right retrieval path depends on how the data was stored, which identifiers you have, and whether you want a managed service API or direct storage-provider retrieval.
Use this page as a starting point. For implementation details, see the [How retrieval works](/getting-started/how-retrieval-works) section.
## Common retrieval paths
### Retrieve from Filecoin Onchain Cloud
Use the [Filecoin Onchain Cloud retrieval docs](https://docs.filecoin.cloud/core-concepts/retrieval/) when your data was stored through Filecoin Onchain Cloud or the Synapse SDK. Those docs cover the current FOC retrieval paths, SDK flows, and service-specific options.
### Retrieve from the Filecoin Cold Storage Service
Data stored through the [Filecoin Cold Storage Service (FCSS)](/build-on-filecoin/filecoin-onchain-cloud/fcss#retrieve-a-dataset) is served by its storage providers one piece at a time, by PieceCID. A piece is free or paid: [`retrieval-client`](https://github.com/fidlabs/large-paid-retrievals) finds the providers that store it, compares prices, pays through Filecoin Pay when needed, and downloads it. Private deals are served only to the client and the wallets it authorizes.
### Retrieve from Fil One
[Fil One](https://docs.fil.one/) is an S3-compatible object storage service backed by Filecoin. If your data is stored in Fil One, retrieve it with the same S3-compatible tools, SDKs, or application paths you use for object storage.
### Retrieve directly from Filecoin storage providers
Use direct storage-provider retrieval when your data was stored through direct deal making or another provider-specific workflow and you need to fetch it from the providers that hold it.
Direct retrieval usually starts with either a PieceCID or an IPFS CID:
* For a PieceCID, use Filecoin deal, sector, storage-service, or provider metadata to identify a provider that stores the piece, then retrieve from the provider's HTTP `/piece/{pieceCid}` endpoint when available.
* For an IPFS CID, use content routing such as the [InterPlanetary Network Indexer](https://cid.contact/) to find providers that advertised the CID. Some providers expose an `/ipfs/{cid}` endpoint for IPFS-style retrieval.
Use [Lassie](https://github.com/filecoin-project/lassie) for CID-based retrieval from Filecoin and IPFS. Lassie can discover providers for advertised CID content and fetch it with `lassie fetch `, or run as an HTTP daemon for `/ipfs/{cid}` requests. For whole-piece retrieval by PieceCID, use a provider or service path that supports `/piece`.
## Where to go next
* [Filecoin Onchain Cloud retrieval](https://docs.filecoin.cloud/core-concepts/retrieval/) covers retrieval for data stored through Filecoin Onchain Cloud.
* [FCSS retrieval](/build-on-filecoin/filecoin-onchain-cloud/fcss#retrieve-a-dataset) covers free and paid retrieval of cold storage datasets.
* [Fil One docs](https://docs.fil.one/) cover retrieval through S3-compatible object storage APIs.
* [Basic retrieval](/getting-started/how-retrieval-works/basic-retrieval) covers fetching CID-addressed data with Lassie.
* [Serving retrievals](/getting-started/how-retrieval-works/serving-retrievals) explains provider advertisements, IPNI, and retrieval protocols.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin/retrieval)
# Programming on Filecoin
Once data is stored, computations can be performed directly on it without needing retrieval. This page covers the basics of programming on Filecoin.
## Compute-over-data
Beyond storage and retrieval, data often needs transformation. Compute-over-data protocols enable computations over IPLD, the data layer used by content-addressed systems like Filecoin. Working groups are developing compute solutions for Filecoin data, including large-scale parallel compute and cryptographically verifiable compute (e.g., [Lurk](https://filecoin.io/blog/posts/introducing-lurk-a-programming-language-for-recursive-zk-snarks/)).
Some compute-over-data platforms provide public, transparent, and verifiable distributed computation, allowing users to run Docker containers and WebAssembly (Wasm) images as tasks on data stored in InterPlanetary File System (IPFS).
Filecoin is uniquely positioned to support large-scale off-chain computation because storage providers have compute resources, such as GPUs and CPUs, colocated with their data. This setup enables a new paradigm where computations occur directly on the data where it resides, reducing the need to move data to external compute nodes.
## Filecoin Virtual Machine
The Filecoin Virtual Machine (FVM) is a runtime environment for executing smart contracts on the Filecoin network. These smart contracts allow users to run bounded computations and establish rules for storing and accessing data. The FVM ensures that these contracts are executed securely and reliably.
The FVM is designed to support both native Filecoin actors written in languages that compile to Wasm and smart contracts from other runtimes, such as Solidity for the Ethereum Virtual Machine (EVM), Secure EcmaScript (SES), and eBPF. The [reference FVM](https://github.com/filecoin-project/ref-fvm) and SDK are written in Rust, ensuring high performance and security.
Initially, the FVM supports smart contracts written in Solidity, with plans to expand to other languages that compile to Wasm.
By enabling compute-over-states on the Filecoin network, the FVM unlocks a wide range of potential use cases. Examples include:
### Data Organizations
FVM enables a new kind of organization centered around data.
#### Data DAOs and tokenized datasets
The FVM makes it possible to create and manage decentralized and autonomous organizations (Data DAOs) focused on data curation and preservation. Data DAOs allow groups of individuals or organizations to govern and monetize data access, pooling returns into a shared treasury to fund preservation and growth. These data tokens can also be exchanged among peers or used to request computation services, such as validation, analysis, feature detection, and machine learning.
#### Perpetual storage
The FVM allows users to store data once and use repair and replication bots to manage ongoing storage deals, ensuring perpetual data storage. Through smart contracts, users can fund a wallet with FIL, allowing storage providers to maintain data storage indefinitely. Repair bots monitor these storage deals and replicate data across providers as needed, offering long-term data permanence.
### Financial services for storage providers
The FVM can facilitate unique financial services tailored for storage providers (SPs) in the Filecoin ecosystem.
#### Lending and staking protocols
Users can lend Filecoin to storage providers to be used as storage collateral, earning interest in return. Loans may be undercollateralized based on SP performance history, with reputation scores generated from on-chain data. Loans can also be automatically repaid to investors using a multisig wallet, which includes lenders and a third-party arbitrator. New FVM-enabled smart contracts create yield opportunities for FIL holders while supporting the growth of storage services on the network.
#### Insurance
SPs may require financial products to protect against risks in providing storage solutions. Attributes such as payment history, operational length, and availability can be used to underwrite insurance policies, shielding SPs from financial impacts due to storage faults or token price fluctuations.
### Core chain infrastructure
The FVM is expected to achieve feature parity with other persistent EVM chains, supporting critical infrastructure for decentralized exchanges and token bridges.
#### Decentralized exchanges
To facilitate on-chain token exchange, the FVM may support decentralized exchanges like Uniswap or Sushi, or implement decentralized order books similar to Serum on Solana.
#### Token bridges
Although not an immediate focus, token bridges will eventually connect Filecoin to EVM, Move, and Cosmos chains, enabling cross-chain wrapped tokens. While Filecoin currently offers unique value without needing to bootstrap liquidity from other chains, long-term integration with other blockchains is anticipated.
In addition to these, the FVM could support various other use cases, such as data access control, trustless reputation systems, replication workers, storage bounties, and L2 networks. For more details on potential use cases, see our [Request for Startups](https://protocollabs.notion.site/Request-for-Startups-FVM-edition-8cd3e76982d14e29b33335ca458fb087) post.
If you are interested in building these use cases, the following solution blueprints may be helpful:
* [DataDAO Solution Blueprint](https://docs.google.com/document/d/1OYDh_gs7mAk2M_O9m-2KedQA7MNo6ysIzH6eaQZxMOk/edit?pli=1)
* [Perpetual Storage Solution Blueprint](https://docs.google.com/document/d/19Kck1PiGGrUKyd6XBYj6NtsC5NiCjndUSsv0OFA1Lv0/edit)
* [Lending Pool Cookbook](https://docs.google.com/document/d/18in74On0bY7KyEsPgItvNvfUUPcPtHjNQtVfLdJUyzM/edit)
### Filecoin EVM
The Filecoin EVM (FEVM) is an Ethereum Virtual Machine (EVM) runtime built on top of the FVM. It allows developers to port existing EVM-based smart contracts directly onto Filecoin. The FEVM emulates EVM bytecode at a low level, supporting contracts written in Solidity, Vyper, and Yul. The EVM runtime is based on open-source libraries, including [SputnikVM](https://github.com/rust-blockchain/evm) and Revm. More details can be found in the [EVM <> FVM mapping specification](https://github.com/filecoin-project/fvm-project/blob/main/04-evm-mapping.md).
Since Filecoin nodes support the Ethereum JSON-RPC API, FEVM is compatible with existing EVM development tools, such as Hardhat, Brownie, and MetaMask. Most smart contracts deployed to Filecoin require minimal adjustments, if any. For example, new ERC-20 tokens can be launched on Filecoin or bridged to other chains.
Developers can choose between deploying actors on the FEVM or native FVM: for optimal performance, actors should be written in languages that compile to Wasm and deployed to the native FVM. For familiarity with Solidity and EVM tools, the FEVM is a convenient alternative.
In summary, the FEVM provides a straightforward path for Web3 developers to begin building on Filecoin using familiar tools and languages, while gaining native access to Filecoin storage deals.
The primary difference between FEVM and EVM contracts is that FEVM contracts can interact directly with Filecoin-specific actors, such as miner actors, which are inaccessible to Ethereum contracts. To enable seamless integration, a Filecoin-Solidity API library has been developed to facilitate interactions with Filecoin-specific actors and syscalls.
For example FEVM contracts, see the available [example contracts here](https://github.com/lotus-web3/client-contract).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin/programming-on-filecoin)
# Networks
The Filecoin network has several networks for testing, staging, and production purposes. This page provides information on available networks.
## Mainnet
[Mainnet](/networks-and-tools/networks/mainnet) is the live production network that connects all nodes on the Filecoin network. It operates continuously without resets.
## Testnets
Test networks, or testnets, are versions of the Filecoin network that simulate various aspects of the mainnet. They are intended for testing and should not be used for production applications or services.
### Calibration
The [Calibration](/networks-and-tools/networks/calibration) testnet offers the closest simulation of the mainnet. It provides realistic sealing performance and hardware requirements due to the use of finalized proofs and parameters, allowing prospective storage providers to test their setups. Storage clients can also store and retrieve real data on this network, participating in deal-making workflows and testing storage/retrieval functionalities. Calibration testnet uses the same sector size as the mainnet.
* [Public RPC endpoints](/networks-and-tools/networks/calibration/rpcs)
* [Blockchain explorer](https://calibration.filscan.io/)
* [Calibration Faucet - Chainsafe](https://faucet.calibnet.chainsafe-fil.io)
* [Calibration Faucet - Zondax](https://beryx.zondax.ch/faucet/)
* [Calibration Faucet - Forest Explorer](https://forest-explorer.chainsafe.dev/faucet/calibnet)
* [Calibration USDFC Faucet - Chainsafe](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/what-is-filecoin/networks)
# How storage works
How data is stored on the Filecoin network, from uploading files to using storage onramps.
This section covers the primary methods for storing data on Filecoin and how Filecoin relates to IPFS.
## Table of contents
* [Filecoin and IPFS](/getting-started/how-storage-works/filecoin-and-ipfs) — how Filecoin and IPFS work together for storage and retrieval
* [Upload to Filecoin](/getting-started/how-storage-works/upload-to-filecoin) — the fastest path to storing data on the network
* [Storage onramps](/getting-started/how-storage-works/storage-onramps) — managed services for ingesting data into Filecoin
* [Filecoin Plus](broken://pages/ONanf0Ny7ISDeH7beMKF) — a program that subsidizes storage for verified clients
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/how-storage-works)
# Filecoin and IPFS
Explore the features that make Filecoin a compelling system for storing files. This is an overview of features offered by Filecoin that make it a compelling system for storing files.
#### Verifiable storage
Filecoin has built-in processes to check the history of files and verify that they have been stored correctly over time. Every storage provider proves that they are maintaining their files in every 24-hour window. Clients can efficiently scan this history to confirm that their files have been stored correctly, even if the client was offline at the time. Any observer can check any storage provider’s track record and will notice if the provider has been faulty or offline in the past.
[Learn about storage verification at ProtoSchool](https://proto.school/#/verifying-storage-on-filecoin)
#### Open market
In Filecoin, file storage and retrieval deals are negotiated in open markets. Anybody can join the Filecoin network without needing permission. By lowering the barriers to entry, Filecoin enables a thriving ecosystem of many independent storage providers.
#### Competitive prices
Prices for storage and retrieval are determined by supply and demand, not corporate pricing departments. Filecoin makes reliable storage available at hyper-competitive prices. Miners compete based on their storage, reliability, and speed rather than through marketing or locking users in.
#### Reliable storage
Because storage is paid for, Filecoin provides a viable economic reason for files to stay available over time. Files are stored on computers that are reliable and well-connected to the internet.
#### Reputation, not marketing
In Filecoin, storage providers prove their reliability through their track record published on the blockchain, not through marketing claims published by the providers themselves. Users don’t need to rely on status pages or self-reported statistics from storage providers.
#### Choice of tradeoffs
Users get to choose their own tradeoffs between cost, redundancy, and speed. Users are not limited to a set group of data centers offered by their provider but can choose to store their files on any storage provider participating in Filecoin.
#### Censorship resistance
Filecoin resists censorship because no central provider can be coerced into deleting files or withholding service. The network is made up of many different computers run by many different people and organizations. Faulty or malicious actors are noticed by the network and removed automatically.
#### Useful blockchain
In Filecoin, storage providers are rewarded for providing storage, not for performing wasteful computations. Filecoin secures its blockchain using proof of file replication and proof of storage over time. It doesn’t rely on energy-intensive proof-of-work schemes like other blockchains. Miners are incentivized to amass hard drives and put them to use by storing files. Filecoin doesn’t incentivize the hoarding of graphics cards or application-specific integrated circuits for the sole purpose of mining.
#### Provides storage to other blockchains
Filecoin’s blockchain is designed to store large files, whereas other blockchains can typically only store tiny amounts of data, very expensively. Filecoin can provide storage to other blockchains, allowing them to store large files. In the future, mechanisms will be added to Filecoin, enabling Filecoin’s blockchain to interoperate with transactions on other blockchains.
#### Content addressing
Files are referred to by the data they contain, not by fragile identifiers such as URLs. Files remain available no matter where they are hosted or who they are hosted by. When a file becomes popular, it can be quickly distributed by swarms of computers instead of relying on a central computer, which can become overloaded by network traffic.
When multiple users store the same file (and choose to make the file public by not encrypting it), everyone who wants to download the file benefits from Filecoin, keeping it available. No matter where a file is downloaded from, users can verify that they have received the correct file and that it is intact.
#### Content distribution network
Retrieval providers are computers that have good network connections to lots of users who want to download files. By prefetching popular files and distributing them to nearby users, retrieval providers are rewarded for making network traffic flow smoothly and files download quickly.
#### Single protocol
Applications implementing Filecoin can store their data on any storage provider using the same protocol. There isn’t a different API to implement for each provider. Applications wishing to support several different providers aren’t limited to the lowest-common-denominator set of features supported by all their providers.
#### No lock-in
Migrating to a different storage provider is made easier because they all offer the same services and APIs. Users aren’t locked into providers because they rely on a particular feature of the provider. Also, files are content-addressed, enabling them to be transferred directly between providers without the user having to download and re-upload the files.
Traditional cloud storage providers lock users by making it cheap to store files but expensive to retrieve them again. Filecoin avoids this by facilitating a retrieval market where providers compete to give users their files back as fast as possible, at the lowest possible price.
#### Open source code
The code that runs both clients and storage providers is open-source. Storage providers don’t have to develop their own software for managing their infrastructure. Everyone benefits from improvements made to Filecoin’s code.
#### Active community
Filecoin has an active community of contributors to answer questions and help newcomers get started. There is an open dialog between users, developers, and storage providers. If you need help, you can reach the person who designed or built the system in question. Reach out on [Filecoin’s chat and forums](/getting-started/community/forums-and-fips).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/how-storage-works/filecoin-and-ipfs)
# Upload to Filecoin
Choose a storage path on Filecoin based on your needs, from managed on-chain storage to direct deal-making with providers.
Filecoin offers several ways to store data. Each path trades off simplicity against control. This page describes what each option does and links to the relevant documentation.
## Filecoin Onchain Cloud
[Filecoin Onchain Cloud (FOC)](/build-on-filecoin/filecoin-onchain-cloud) is a programmable storage platform built on the Filecoin Virtual Machine. It handles the full lifecycle of storing data: the Filecoin Warm Storage Service (FWSS) stores your data with fast retrieval, the Filecoin Cold Storage Service (FCSS) preserves large datasets as sealed copies, Proof of Data Possession (PDP) cryptographically verifies providers still hold it, and Filecoin Pay settles payments automatically based on verified storage delivery. All operations are on-chain and auditable.
Developers interact with FOC through the [Synapse SDK](https://docs.filecoin.cloud/developer-guides/synapse), which provides a high-level API for uploads, payments, and provider discovery. See the [FOC documentation](https://docs.filecoin.cloud/) for setup guides and API reference.
{% hint style="success" %}
**Best for**: developers who want verifiable, programmable storage with minimal infrastructure.
{% endhint %}
### Filecoin Cold Storage Service
FOC also offers cold storage. The [Filecoin Cold Storage Service (FCSS)](/build-on-filecoin/filecoin-onchain-cloud/fcss) stores sealed copies of large datasets with separate storage providers, under on-chain deals with terms the client sets: duration, price, retrievability, bandwidth, latency, and indexing. Clients onboard with a CLI, a web app, or an AI agent skill that prepares the dataset with Singularity.
{% hint style="success" %}
**Best for**: archives and large datasets, from 1 TiB up, that must be preserved and verifiable but are read rarely.
{% endhint %}
## Fil One
[Fil One](https://fil.one/) is S3-compatible object storage backed by Filecoin. Point any S3 SDK or tool at its endpoint and store data with flat per-terabyte pricing, no egress fees, and cryptographic integrity proofs from the Filecoin network. It suits teams that want a drop-in S3 replacement without managing deals or running infrastructure. See the [Fil One documentation](https://docs.fil.one/) for the endpoint, SDKs, and API reference.
{% hint style="success" %}
**Best for**: teams that want a familiar S3 workflow with Filecoin-backed durability.
{% endhint %}
## Storage onramps
[Storage onramps](/getting-started/how-storage-works/storage-onramps) are third-party services that handle Filecoin deal-making behind the scenes. You send data through a web UI, API, or SDK, and the onramp manages provider selection, deal negotiation, and data transfer. Services like [Pinata](https://pinata.cloud/) (IPFS pinning), [Lighthouse](https://lighthouse.storage/), and [Akave](https://www.akave.ai/) each offer different features. See the [storage onramps page](/getting-started/how-storage-works/storage-onramps) for the full list with links to their documentation.
{% hint style="success" %}
**Best for**: teams who prefer a managed service and do not need direct on-chain control.
{% endhint %}
## Filecoin Plus
[Filecoin Plus](broken://pages/ONanf0Ny7ISDeH7beMKF) is a program that subsidizes storage costs for verified clients storing useful data. Allocators vet clients and grant them DataCap tokens. When a client spends DataCap in a storage deal, the provider earns higher block rewards, which incentivizes storing verified data at reduced cost. See the [Filecoin Plus page](broken://pages/ONanf0Ny7ISDeH7beMKF) for how the allocator process works.
{% hint style="success" %}
**Best for**: large datasets where cost efficiency is a priority.
{% endhint %}
## Direct deal-making
For full control over provider selection, pricing, and deal terms, you can negotiate storage deals directly. [Curio](https://curiostorage.org/) is the modern storage-provider stack for running this infrastructure, see the [Curio documentation](https://docs.curiostorage.org/), with [Boost](https://boost.filecoin.io/) as the established deal engine and the [Lotus client](/provide-storage/nodes/lotus) providing CLI tools for proposing and managing deals. This path requires running infrastructure and understanding the Filecoin deal lifecycle.
{% hint style="success" %}
**Best for**: storage providers, large-scale data onboarders, and users with custom deal requirements.
{% endhint %}
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/how-storage-works/upload-to-filecoin)
# Storage onramps
Storage on-ramps and helpers are APIs and services that abstract Filecoin dealmaking into simple, streamlined API calls.
Developers use web UIs, APIs, or libraries to send data to storage onramps. Behind the scenes, storage onramps receive the data and handle the underlying processes to store it in a reliable way, making deals with Filecoin storage providers.
Examples of maintained storage onramps include:
* [Filecoin Onchain Cloud](/build-on-filecoin/filecoin-onchain-cloud) is a programmable, on-chain storage platform with verifiable storage proofs and automatic payments (Filecoin Pay). Warm storage is accessed through the Synapse SDK, and the [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss) stores sealed copies of large datasets.
* [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin/getting-started) is a CLI and API path for pinning IPFS-compatible content to Filecoin-backed storage with Filecoin Pay.
* [Fil One](https://fil.one/) is S3-compatible object storage backed by Filecoin, with flat per-terabyte pricing and no egress fees. Point any S3 SDK or tool at its endpoint to store data with cryptographic integrity proofs. See the [Fil One docs](https://docs.fil.one/).
* [Lighthouse](https://lighthouse.storage/) offers permanent, decentralized storage powered by Filecoin.
* [Akave](https://www.akave.ai/) provides a decentralized data-lake and object-storage layer backed by Filecoin.
* [Pinata](https://pinata.cloud/) is an IPFS pinning service for storing and serving files, media, and app data over IPFS. See the [Pinata docs](https://docs.pinata.cloud/).
* [Singularity](https://data-programs.gitbook.io/singularity) facilitates onboarding large quantities of data to the Filecoin network.
* [CID Gravity](https://www.cidgravity.com/) provides a web UI for uploading files to Filecoin and IPFS.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/how-storage-works/storage-onramps)
# How retrieval works
How to retrieve data from the Filecoin network, from finding providers to fetching content.
This section covers the implementation details behind Filecoin retrieval: finding providers, choosing a retrieval path, and fetching CID-addressed content.
For a high-level overview of managed and direct retrieval paths, see [Retrieval](/getting-started/what-is-filecoin/retrieval).
## Table of contents
* [Basic retrieval](/getting-started/how-retrieval-works/basic-retrieval) - fetch CID-addressed data with Lassie and work with CAR output
* [Serving retrievals](/getting-started/how-retrieval-works/serving-retrievals) - understand provider advertisements, IPNI, and storage-provider retrieval endpoints
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/how-retrieval-works)
# Basic retrieval
There are multiple ways to fetch data from a storage provider. This page covers some of the most popular methods.
### Lassie
Lassie is a simple retrieval client for IPFS and Filecoin. It finds and fetches your data over the best retrieval protocols available. Lassie makes Filecoin retrieval easy. While Lassie is powerful, the core functionality is expressed in a single CLI command:
```shell
lassie fetch
```
Lassie also provides an HTTP interface for retrieving IPLD data from IPFS and Filecoin peers. Developers can use this interface directly in their applications to retrieve data by CID.
Lassie fetches content in content-addressed archive (CAR) form, so in most cases, you will need additional tooling to work with CAR files. Lassie can also be used as a Go library. It retrieves CID-addressed IPLD data over the available protocols advertised for that content, including HTTP, Bitswap, or Graphsync depending on provider support. Use provider or service `/piece` endpoints when you need to retrieve a whole PieceCID.
#### Retrieve using Lassie
Make sure that you have [Go](https://go.dev/) installed and that your `GOPATH` is set up. By default, your `GOPATH` will be set to `~/go`.\\
**Install Lassie**
1. Download the [Lassie Binary from the latest release](https://github.com/filecoin-project/lassie/releases/latest) based on your system architecture.
Or download and install Lassie using the Go package manager:
```sh
go install github.com/filecoin-project/lassie/cmd/lassie@latest
```
2. Download the [go-car binary from the latest release](https://github.com/ipld/go-car/releases/latest) based on your system architecture or install the [go-car](https://github.com/ipld/go-car) package using the Go package manager. The go-car package makes it easier to work with content-addressed archive (CAR) files:
```sh
go install github.com/ipld/go-car/cmd/car@latest
```
You now have everything you need to retrieve a file with Lassie and extract the contents with `go-car`.
**Retrieve**
To retrieve data from Filecoin using Lassie, all you need is the CID of the content you want to download.
The video below demonstrates how Lassie can be used to render content directly from Filecoin and IPFS.
Lassie and `go-car` can work together to retrieve and extract data from Filecoin. All you need is the CID of the content to download.
```shell
lassie fetch -o - | car extract -
```
This command uses a `|` to chain two commands together. This will work on Linux or macOS. Windows users may need to use PowerShell to use this form. Alternatively, you can use the commands separately, as explained later on this page.
An example of fetching and extracting a single file, identified by its CID:
```shell
lassie fetch -o - bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6 | car extract - > lidar-data.tar
```
Basic progress information, similar to the output shown below, is displayed:
```plaintext
Fetching bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6................................................................................................................................................
Fetched [bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6] from [12D3KooWPNbkEgjdBNeaCGpsgCrPRETe4uBZf1ShFXStobdN18ys]:
Duration: 42.259908785s
Blocks: 144
Bytes: 143 MiB
extracted 1 file(s)
```
The resulting file is a tar archive:
```shell
ls -l
# total 143M
# -rw-rw-r-- 1 user user 143M Feb 16 11:21 lidar-data.tar
```
**Lassie CLI usage**
Lassie's usage for retrieving data is as follows:
```shell
lassie fetch -p -o /path/to/content
```
* `-p` is an optional flag that tells Lassie that you would like to see detailed progress information as it fetches your data.
For example:
```plaintext
Fetching bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6
Querying indexer for bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6...
Found 4 storage providers candidates from the indexer, querying all of them:
12D3KooWPNbkEgjdBNeaCGpsgCrPRETe4uBZf1ShFXStobdN18ys
12D3KooWNHwmwNRkMEP6VqDCpjSZkqripoJgN7eWruvXXqC2kG9f
12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj
12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU
Querying [12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU] (started)...
Querying [12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj] (started)...
...
```
* `-o` is an optional flag that tells Lassie where to write the output to. If you don’t specify a file, it will append `.car` to your CID and use that as the output file name.
Use `-o -` to write the CAR stream to `stdout` so it can be piped to another command, such as `go-car`, or redirected to a file.
* `/path/to/content` is the CID of the content you want to retrieve and an optional path to a specific file within that content. Example:
```
lassie fetch -o - bafybeiaysi4s6lnjev27ln5icwm6tueaw2vdykrtjkwiphwekaywqhcjze/wiki/Cryptographic_hash_function | car extract - | less
```
A CID is always necessary, and if you don’t specify a path, Lassie will attempt to download the entire content. If you specify a path, Lassie will only download that specific file or, if it is a directory, the entire directory and its contents.
**go-car CLI usage**
The `car extract` command can be used to extract files and directories from a CAR:
```shell
car extract -f [/path/to/file/or/directory] []
```
* `-f` is an optional flag that tells `go-car` where to read the input from. If omitted, it will read from `stdin`, as in our example above where we piped `lassie fetch -o -` output to `car extract`.
* `/path/to/file/or/directory` is an optional path to a specific file or directory within the CAR. If omitted, it will attempt to extract the entire CAR.
* `` is an optional argument that tells `go-car` where to write the output to. If omitted, it will be written to the current directory.
If you supply `-p`, `car extract` writes extracted file bytes directly to `stdout`. This only works when extracting a single file.
In the example above, where we fetched a file named `lidar-data.tar`, the `>` operator was used to redirect the output of `car extract` to a named file. This is because the content we fetched was raw file data that did not have a name encoded. In this case, if we didn’t use `-` and `> filename`, `go-car` would write to a file named `unknown`. In this instance, `go-car` was used to reconstitute the file from the raw blocks contained within Lassie’s CAR output.
`go-car` has other useful commands. The first is `car ls`, which can be used to list the contents of a CAR. The second is `car inspect`, which can be used to inspect the contents of the CAR and optionally verify the integrity of a CAR.
Lassie and go-car are the recommended command-line tools for retrieving and inspecting Filecoin data by CID.
#### Lassie HTTP daemon
The Lassie HTTP daemon is an HTTP interface for retrieving IPLD data from IPFS and Filecoin peers. It fetches content from peers known to have it and provides the resulting data in CAR format.
```http
GET /ipfs/{cid}[/path][?params]
```
A `GET` query against a Lassie HTTP daemon allows retrieval from peers that have the content identified by the given root CID, streaming the DAG in the response in [CAR (v1)](https://ipld.io/specs/transport/car/carv1/) format. You can read more about the HTTP request and response to the daemon in [Lassie’s HTTP spec](https://github.com/filecoin-project/lassie/blob/main/docs/HTTP_SPEC.md). Lassie’s HTTP interface can be a very powerful tool for web applications that require fetching data from Filecoin and IPFS.
#### Lassie’s CAR format
Lassie only returns data in CAR format, specifically, [CARv1](https://ipld.io/specs/transport/car/carv1/) format. [Lassie’s car spec](https://github.com/filecoin-project/lassie/blob/main/docs/CAR.md) describes the nature of the CAR data returned by Lassie and the various options available to the client for manipulating the output.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/how-retrieval-works/basic-retrieval)
# Serving retrievals
In this article, we will discuss the functions of storage providers in the Filecoin network, the role of the indexer, and the retrieval process for publicly available data.
### The indexer
When data should be publicly discoverable, the storage provider publishes an advertisement to the InterPlanetary Network Indexer (IPNI). IPNI maps content identifiers to storage providers and retrieval metadata so clients can discover where content is available.
IPNI can also include the retrieval protocols or endpoints a provider advertises for specific CIDs. Filecoin storage providers may serve retrievals over HTTP, Bitswap, Graphsync, or service-specific endpoints depending on their software and configuration.
### Retrieval process
If a client wants to retrieve publicly available data from the Filecoin network, then they generally follow this process.
#### Query the IPNI
Before the client can retrieve from a storage provider, they first need to find which providers hold the data. To do this, the client sends a query to the InterPlanetary Network Indexer.
#### Select a provider
Assuming IPNI returns more than one storage provider, the client can select which provider to retrieve from. Here, they will also get additional details based on the retrieval path they want to use.
#### Initiate retrieval
The client then retrieves the data from the storage provider over one of the advertised paths. HTTP retrieval is the common path for whole-piece `/piece/{pieceCid}` retrieval. Providers that index and advertise IPFS CIDs can also expose `/ipfs/{cid}` style retrieval.
#### Finalize the retrieval
Once the client has received the last chunk of data, the connection is closed.
### Implementation paths
Different retrieval workflows use different tools:
| Workflow | Maintained path |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Serving PDP retrievals as a storage provider | Use [Curio](https://curiostorage.org/) for PDP retrievals. |
| Serving PoRep retrievals as a storage provider | Use [Boost](https://boost.filecoin.io/) to serve retrievals. Boost supports Graphsync retrievals by default, and storage providers can run [`booster-http`](https://boost.filecoin.io/http-retrieval) for HTTP retrievals when configured. |
| Retrieving data as a client | Use [Lassie](https://github.com/filecoin-project/lassie) to fetch CID-addressed content from Filecoin and IPFS using the best available retrieval path. For whole-piece retrieval, use provider or service `/piece` endpoints. |
| Serving paid FCSS retrievals as a storage provider | Put [`sp-proxy`](https://github.com/fidlabs/large-paid-retrievals#for-storage-providers) in front of your piece server. It quotes a price per piece and settles payment through Filecoin Pay before serving. |
| Retrieving FCSS datasets as a client | Use [`retrieval-client`](https://github.com/fidlabs/large-paid-retrievals#for-dataset-consumers) to find providers, compare prices, pay when needed, and download pieces. |
| Retrieving application data with Filecoin Onchain Cloud | See the [Filecoin Onchain Cloud retrieval docs](https://docs.filecoin.cloud/core-concepts/retrieval/) for maintained Synapse SDK retrieval flows. |
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/how-retrieval-works/serving-retrievals)
# Interplanetary consensus
InterPlanetary Consensus (IPC) powers planetary-scale decentralized applications (dApps) through horizontal scalability of Filecoin, Ethereum and more.
## What is IPC?
[Interplanetary Consensus (IPC)](https://www.ipc.space/) is a framework that enables on-demand horizontal scalability of networks, by deploying "subnets" running different consensus algorithms depending on the application's requirements.
### What is horizontal scalability and why is it important for dApps?
[Horizontal scalability](https://en.wikipedia.org/wiki/Scalability#Horizontal_or_scale_out) generally refers to the addition of nodes to a system, to increase its performance. For example, adding more nodes to a compute network helps distribute the effort needed to run a single compute task. This reduces cost per task and decreases latency, while improving overall throughput.
In web3, horizontal scalability refers to *scaling* blockchains, for *desired* performance. More specifically, *scaling* the ability of a blockchain to process transactions and achieve consensus, across an increasing number of users, at *desired* latencies and throughput. IPC is one such scaling solution, alongside other popular layer 2 solutions, like [sidechains](https://ethereum.org/en/developers/docs/scaling/sidechains/) and [rollups](https://ethereum.org/en/developers/docs/scaling/#rollups).
For decentralized applications (dApps), there are several key motivations to adopt scaling - performance, decentralization, security. The challenge is that these factors are known to be conflicting goals.
### How does IPC achieve horizontal scalability?
IPC is a scaling solution intentionally designed to achieve considerable performance, decentralization and security for dApps.
It achieves scaling through the permissionless spawning of new blockchain sub-systems, which are composed of [subnets](https://docs.ipc.space/concepts/subnets).
Subnets are organized in a hierarchy, with one parent subnet being able to spawn infinite child subnets. Within a hierarchical subsystem, subnets can seamlessly communicate with each other, reducing the need for cross-chain bridges.
Subnets also have their own specific consensus algorithms, whilst leveraging security features from parent subnets. This allows dApps to use subnets for hosting sets of applications or to [shard](https://en.wikipedia.org/wiki/Shard_\(database_architecture\)) a single application, according to its various cost or performance needs.
### How is IPC unique as a scaling solution?
Earlier, we talked about the challenge of scaling solutions to balance performance, security and decentralization. IPC is a standout framework that strikes a considerable balance between these factors, to achieve breakthroughs in scaling.
* **Highly customizable without compromising security.** Most L2 scaling solutions today either inherit the L1's security features but don't have their own consensus algorithms (e.g. rollups), or do the reverse (e.g. sidechains). They are also deployed in isolation and require custom bridges or protocols to transfer assets and state between L2s that share a common L1, which are vulnerable to attacks. In contrast, IPC subnets have their own consensus algorithms, inherit security features from the parent subnet and have native cross-net communication, eliminating the need for bridges.
* **Multi-chain interoperability.** IPC uses the [Filecoin Virtual Machine (FVM)](/core-concepts/filecoin-virtual-machine) as its transaction execution layer. The FVM is a WASM-based polyglot execution environment for IPLD data and is designed to support smart contracts written in any programming language, compiled to WASM. It currently supports Filecoin and Ethereum. Today, IPC is fully compatible with Filecoin and Ethereum and can use either as a rootnet. IPC will eventually allow any chain to be taken as rootnet.
* **Tight storage integration with Filecoin.** IPC was designed from the data-centric L1, [Filecoin](/getting-started/what-is-filecoin), which is the largest decentralized storage network. IPC can leverage its storage primitives, like IPLD data integration, to deliver enhanced solutions for data availability and more.
## Applications of IPC
Here are some practical examples of how IPC improves the performance of dApps:
* **Distributed Computation**: Spawn ephemeral subnets to run distributed computation jobs.
* **Coordination**: Assemble into smaller subnets for decentralized orchestration with high throughput and low fees.
* **Localization**: Leverage proximity to improve performance and operate with very low latency in geographically constrained settings.
* **Partition tolerance**: Deploy blockchain substrates in mobile settings or other environments with limited connectivity.
With better performance, lower fees and faster transactions, IPC can rapidly improve horizontal and vertical markets with decentralized technology:
* **Artificial Intelligence:** IPC is fully compatible with [Filecoin](/getting-started/what-is-filecoin), the world’s largest decentralized data storage. Leveraging Filecoin, IPC can enable distributed computation to power hundreds of innovative AI models.
* **Decentralized Finance (DeFi):** Enabling truly high-frequency trading and traditional backends with verifiability and privacy.
* **Big Data and Data Science:** Multiple teams are creating global-scale distributed compute networks to enable Data Science analysis on Exabytes of decentralized stored data.
* **Metaverse/Gaming:** Enabling real-time tracking of player interactions in virtual worlds.
* **DAOs:** Assemble into smaller subnets for decentralized orchestration with high throughput and low fees. Partition tolerance: Deploy blockchain substrates in mobile settings or other environments with limited connectivity.
### Get involved
* Visit the [website](https://www.ipc.space/)
* Read the [docs](https://docs.ipc.space/)
* Check out the [repository](https://github.com/consensus-shipyard/ipc)
* Connect with the community on [Discord](https://discord.gg/QtNbXf75)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/interplanetary-consensus)
# Community
Learn about the Filecoin project, connect with the community, and find ways to contribute.
The Filecoin community includes developers, storage providers, researchers, and users working together to build a decentralized storage network. This section covers how to get involved, where to find help, and how the project is organized.
## Table of contents
* [Forums and FIPs](/getting-started/community/forums-and-fips) — discussion channels, governance proposals, and community calls
* [Filecoin compared to](/getting-started/community/filecoin-compared-to) — how Filecoin differs from other storage solutions
* [Filecoin FAQs](/getting-started/community/filecoin-faqs) — common questions about storage costs, hardware, and economics
* [FAQs](/getting-started/community/faqs) — frequently asked questions about FVM and building on Filecoin
* [Related projects](/getting-started/community/related-projects) — protocols and tools in the Filecoin ecosystem
* [Social media](/getting-started/community/social-media) — official Filecoin channels and online presence
* [The Filecoin project](/getting-started/community/the-filecoin-project) — roadmap, research, and ongoing development
* [Ways to contribute](/getting-started/community/ways-to-contribute) — how to participate in code, docs, and community efforts
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community)
# Forums and FIPs
Connect with the Filecoin community in discussion forums or on IRC. The Filecoin community is active and here to answer your questions in your channel of choice.
### Discussion Forums
For shorter-lived discussions, our community chat open to all on both Slack and Discord:
* [Slack](https://filecoinproject.slack.com/ssb/redirect)
* [Discord](https://discord.com/invite/filecoin)
For long-lived discussions and for support, please use the [discussion tab on GitHub](https://github.com/filecoin-project/community#forums) instead of Slack. It’s easy for complex discussions to get lost in a sea of new messages on those chat platforms, and posting longer discussions and support requests on the forums helps future visitors, too.
### Filecoin improvement proposals
Filecoin improvement proposals (FIPs) are design documents that propose changes and improvements to the Filecoin network, giving detailed specifications and their rational, and allowing the community to document their consensus or dissent. All technical FIPs that are accepted are later reflected in the [Filecoin Spec](https://spec.filecoin.io/).
There are three types of FIPs:
* Technical FIPs (FTP): protocol changes, standards, API changes. They can include core (consensus-related changes, networking (network protocol improvements, interface (API/RPC or language-level updates), or can be informational (updates to general guidelines or documentation).
* Organizational FIPs (FOP): changes to processes, tools, or governance.
* Recovery FIPs (FRP): emergency fixes requiring state changes (e.g., major bugs).
Typically, the FIP lifecycle looks something like this:
\[ WIP ] -> \[ DRAFT ] -> \[ LAST CALL ] -> \[ ACCEPTED ] -> \[ FINAL ]
1. WIP: A community member has an idea for a FIP, and begins discussing the idea publicly on the Filecoin Discord, in the [Filecoin Slack channel for discussing FIPs](https://filecoinproject.slack.com/archives/C01EU76LPCJ), or in Github issues for the relevant repo.
2. DRAFT: If there is a chance the FIP could be adopted, the author submits a draft for the FIP as a pull request in the [FIPs repo](https://github.com/filecoin-project/FIPs).
3. LAST CALL: This status allows the community to submit final changes to the draft.
4. ACCEPTED: Once the FIP is voted on and accepted, the core engineers will work to implement it.
5. FINAL: This status represents the current state-of-the-art, and it should only be updated to correct errors.
It is the authors' responsibility to request status updates for the FIP. A more robust explainer of the FIP process can be found in [FIP001](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0001.md#what-is-a-fip).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/forums-and-fips)
# Filecoin compared to
While Filecoin shares some similarities to other file storage solutions, the protocol has significant differences that one should consider.
Filecoin combines many elements of other file storage and distribution systems. What makes Filecoin unique is that it runs on an open, peer-to-peer network while still providing economic incentives and proofs to ensure files are being stored correctly. This page compares Filecoin against other technologies that share some of the same properties.
* [Filecoin vs. Amazon S3, Google Cloud Storage](#filecoin-vs.-amazon-s3-google-cloud-storage)
* [Filecoin vs. Bitcoin](#filecoin-tokens-fil-vs.-bitcoin-tokens-btc)
#### Filecoin vs. Amazon S3, Google Cloud Storage
| | Filecoin | Amazon S3, Google Cloud Storage |
| --------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Main use case | Storing files at hypercompetitive prices | Storing files using a familiar, widely-supported service |
| Pricing | Determined by a hypercompetitive open market | Set by corporate pricing departments |
| Centralization | Many small, independent storage providers | A handful of large companies |
| Reliability stats | Independently checked by the network and publicly verifiable | Companies self-report their own stats |
| API | Applications can access all storage providers using the Filecoin protocol | Applications must implement a different API for each storage provider |
| Retrieval | Competitive market for retrieving files | Typically more expensive than storing files to lock users in |
| Fault handling | If a file is lost, the user is refunded automatically by the network | Companies can offer users credit if files are lost or unavailable |
| Support | If something goes wrong, the Filecoin protocol determines what happens without human intervention | If something goes wrong, users contact the support help desk to seek resolution |
| Physical location | Miners located anywhere in the world | Limited to where provider’s data centres are located |
| Becoming a storage provider | Low barrier to entry for storage providers (computer, hard drive, internet connection) | High barrier to entry for storage providers (legal agreements, marketing, support staff) |
#### Filecoin tokens (FIL) vs. Bitcoin tokens (BTC)
| | FIL | BTC |
| ------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Main use case | File storage | Payment network |
| Data storage | Good at storing large amounts of data inexpensively | Small amounts of data can be stored on blockchain at significant cost |
| Proof | Blockchain secured using proof of replication and proof of spacetime | Blockchain secured using proof of work |
| Consensus power | Miners with the most storage have the most power | Miners with the most computational speed have the most power |
| Mining hardware | Hard drives, GPUs, and CPUs | ASICs |
| Mining usefulness | Mining results in peoples’ files being stored | Mining results in heat |
| Types of provider | Storage provider, retrieval provider, repair provider | All providers perform proof of work |
| Uptime requirements | Storage providers rewarded for uptime, penalized for downtime | Miners can go offline without being penalized |
| Network status | Mainnet running since 2020 | Mainnet running since 2009 |
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/filecoin-compared-to)
# Filecoin FAQs
Answers to your frequently asked questions on everything from Filecoin’s crypto-economics and storage expenses to hardware and networking.
#### What are some of the primary use cases for Filecoin?
Filecoin is a protocol that provides core primitives, enabling a truly trustless decentralized storage network. These primitives and features include publicly verifiable cryptographic storage proofs, [cryptoeconomic mechanisms](https://filecoin.io/blog/filecoin-cryptoeconomic-constructions/), and a public blockchain. Filecoin provides these primitives to solve the really hard problem of creating a trustless decentralized storage network.
On top of the core Filecoin protocol, there are a number of layer 2 solutions that enable a broad array of use cases and applications, many of which also use [IPFS](https://ipfs.tech), such as [Lighthouse](https://www.lighthouse.storage/) or [Tableland](https://tableland.xyz/). Using these solutions, any use case that can be built on top of IPFS can also be built on Filecoin!
Some of the primary areas for development on Filecoin are:
* Additional developer tools and layer-2 solutions and libraries that strengthen Filecoin as a developer platform and ecosystem.
* IPFS apps that rely on decentralized storage solutions and want a decentralized data persistence solution as well.
* Financial tools and services on Filecoin, like wallets, signing libraries, and more.
* Applications that use Filecoin’s publicly verifiable cryptographic proofs in order to provide trustless and timestamped guarantees of storage to their users.
#### How can a website or app be free if it costs to retrieve data from the Filecoin network?
Most websites and apps make money by displaying ads. This type of income-model could be replaced with a Filecoin incentivized retrieval setup, where users pay small amounts of FIL for whatever files they’re hoping to download. Several large datasets are hosted through Amazon’s *pay per download* S3 buckets, which Filecoin retrieval could also easily augment or replace.
#### How will Filecoin attract developers to use Filecoin for storage?
It’s going to require a major shift in how we think about the internet. At the same time, it is a very exciting shift, and things are slowly heading that way. Browser vendors like Brave, Opera, and Firefox are investing into decentralized infrastructure.
We think that the internet must return to its *decentralized roots* to be resilient, robust, and efficient enough for the challenges of the next several decades. Early developers in the Filecoin ecosystem are those who believe in that same vision and potential for the internet, and we’re excited to work with them to build this space.
#### What are the detailed parameters of Filecoin’s cryptoeconomics?
We are still finalizing our cryptoeconomic parameters, and they will continue to evolve.
Here is a blog about Filecoin economics from December 2020: [Filecoin network economics](https://filecoin.io/blog/filecoin-network-economics/).
#### How expensive will Filecoin storage be at launch?
As Filecoin is a free market, the price will be determined by a number of variables related to the supply and demand for storage. It’s difficult to predict before launch. However, a few design elements of the network help support inexpensive storage.
Along with revenue from active storage deals, Storage Miners receive block rewards, where the expected value of winning a given block reward is proportional to the amount of storage they have on the network. These block rewards are weighted heavily towards the early days of the network (with the frequency of block rewards exponentially decaying over time). As a result, Storage Miners are relatively incentivized to charge less for storage to win more deals, which would increase their expected block reward.
Further, Filecoin introduces a concept called *Verified Clients*, where clients can be verified to actually be storing useful data. Storage Miners who store data from *Verified Clients* also increase their expected block reward. Anyone running a Filecoin-backed IPFS Pinning Services should qualify as a *Verified Client*. We do not have the process of verification finalized, but we expect it to be similar to submitting a GitHub profile.
#### Will it be cheaper to store data on Filecoin than other centralized cloud services?
Filecoin creates a hyper-competitive market for data storage. There will be many storage providers offering many prices, rather than one fixed price on the network. We expect Filecoin’s permissionless model and low barriers to entry to result in some very efficient operations and low-priced storage, but it’s impossible to say what exact prices will be until the network is live.
#### What happens to the existing content on IPFS once Filecoin launches? What if nodes continue to host content for free and undermine the Filecoin incentive layer?
IPFS will continue to exist as it is, enhanced with Filecoin nodes. There are many use cases that require no financial incentive. Think of it like IPFS is HTTP, and Filecoin is a storage cloud-like S3 – only a fraction of IPFS content will be there.
People with unused storage who want to earn monetary rewards should pledge that storage to Filecoin, and clients who want guaranteed storage should store that data with Filecoin storage providers.
#### Lotus or Venus, which is better for storage providers?
Lotus is the primary reference implementation for the Filecoin protocol. At this stage, we would recommend most storage providers use lotus to participate in the Filecoin network.
#### What is your recommendation on the right hardware to use?
While the Filecoin team does not recommend a specific hardware configuration, we document various setups [here](/provide-storage/infrastructure). Additionally, [this getting-started guide for storage providers](/provide-storage/getting-started) covers hardware considerations and operational planning. However, it is likely that there are more efficient setups, and we strongly encourage storage providers to test and experiment to find the best combinations.
#### We are worried about the ability of our network to handle the additional overhead of running a Filecoin node and still provide fast services for our customers. What are the computational demands of a Lotus node? Are there any metrics for node performance given various requirements?
For information on Lotus requirements, see [Prerequisites > Minimal requirements](https://lotus.filecoin.io/lotus/install/prerequisites/#minimal-requirements).
For information on Lotus full nodes and lite nodes, see [Types of nodes](https://lotus.filecoin.io/lotus/get-started/use-cases/).
#### We bought a lot of hard drives of data through the Discover project. When will they be shipped to China?
There are a number of details that are still being finalized between the verified deals construction and the associated cryptoeconomic parameters.
Our aim is to allow these details to finalize before shipping, but given timelines, we’re considering enabling teams to take receipt of these drives before the parameters are set. We will publish updates on the status of the Discover project on the Filecoin blog.
#### Do Filecoin storage providers need a fixed IP?
For mainnet, you will need a public IP address, but it doesn’t need to be fixed (just accessible).
#### What if we lost a sector accidentally, is there any way to fix that?
If you lost the data itself, then no, there’s no way to recover that, and you will be slashed for it. If the data itself is recoverable, though (say you just missed a *WindowPoSt*), then the Recovery process will let you regain the sector.
#### Has Filecoin confirmed the use of the SDR algorithm? Is there any evidence of malicious construction?
SDR ([Stacked DRG PoRep](https://spec.filecoin.io/algorithms/porep-old/stacked_drg/#section-algorithms.porep-old.stacked_drg)) is confirmed and used, and we have no evidence of malicious construction. The algorithm is also going through both internal and external security audits.
If you have any information about any potential security problem or malicious construction, reach out to our team at .
#### How likely is it that the Filecoin protocol will switch to the NSE Proof-of-Replication construction later?
Native storage extension (NSE) is one of the best candidates for a proof upgrade, and teams are working on implementation. But there are other candidates too, which are promising as well. It may be that another algorithm ends up better than NSE – we don’t know yet. Proof upgrades will arrive after the mainnet launch and will coexist.
AMD may be optimal hardware for SDR. You can [see this description](https://github.com/filecoin-project/lotus/blob/master/documentation/en/sealing-procs.md) for more information on why.
#### How are you working on bootstrapping the demand side of the marketplace? The Discover program is nice, but who is the target market for users, and how do you get them?
In addition to [Filecoin Discover](https://filecoin.io/blog/introducing-filecoin-discover/), a number of groups are actively building tools and services to support the adoption of the Filecoin network with developers and clients. For example, check out the recordings from our [Virtual Community Meetup](https://filecoin.io/blog/filecoin-virtual-community-meetup-recap/) to see updates about Textile and Starling Storage. You can also read more about teams building on Filecoin through the [HackFS event](https://ethglobal.com/events/hackfs).
#### Does Filecoin have an implementation of client and storage provider order matching through order books?
There will be off-chain [order books](https://www.investopedia.com/terms/o/order-book.asp) and storage provider marketplaces – some are in development now from some teams. They will work mostly off-chain because transactions per second on-chain are not enough for the volume of usage we expect on Filecoin. These order books build on the basic deal-flow on-chain. These order books will arrive in their own development trajectory – most likely around or soon after the mainnet launch.
#### Why does Filecoin mining work best on AMD?
Currently, Filecoin’s Proof of Replication (PoRep) prefers to be run on AMD processors. See this description of Filecoin sealing for more information. More accurately, it runs much slower on Intel CPUs. It runs competitively fast on some ARM processors, like the ones in newer Samsung phones, but they lack the RAM to seal the larger sector sizes. The main reason that we see this benefit on AMD processors is due to their implementation of the SHA hardware instructions.
#### What do storage providers have to do to change a committed capacity (CC) sector into a “real-data” sector?
Storage providers will publish storage deals that they will upgrade the CC sector with, announce to the chain that they are doing an upgrade, and prove to the chain that a new sector has been sealed correctly. We expect to evolve and make this cheaper and more attractive over time after the mainnet launch.
#### What does “terminating a sector” mean?
When a committed capacity sector is added to the chain, it can upgrade to a sector with deals, extend its lifetime, or terminate through either faults or voluntary actions. While we don’t expect this to happen very often on mainnet, a storage provider may deem it rational to terminate their promise to the network and their clients, and accept a penalty for doing so.
#### Does the committed capacity sector still need to be sealed before it upgrades to one with real data?
For the first iteration of the protocol, yes. We have plans to make it cheaper and more economically attractive after mainnet with no resealing required and other perks.
#### What’s the minimum time period for the storage contract between the provider and the buyer?
The minimum duration for a deal is set in the storage provider’s ask. There’s also a practical limitation because sectors have a minimum duration (currently 180 days).
#### After I made a deal with a storage provider and sent my data to them, how exactly is the data supposed to be recoverable and healable if that storage provider goes down?
Automatic repair of faulted data is a feature we’ve pushed off until after the mainnet launch. For now, the way to ensure resiliency is to store your data with multiple storage providers, to gain some level of redundancy. If you want to learn more about how we are thinking about repair in the future, [here are some notes](https://github.com/filecoin-project/specs/pull/245/files).
#### How do I know that my storage provider will not charge prohibitively high costs for data retrieval?
To avoid extortion, always ensure you store your data with a fairly decentralized set of storage providers (and note: it’s pretty difficult for a storage provider to be sure they are the only person storing a particular piece of data, especially if you encrypt the data).
Storage providers currently provide a ‘dumb box’ interface and will serve anyone any data they have. Maybe in the future, storage providers will offer access control lists (ACLs) and logins and such, but that requires that you trust the storage provider. The recommended (and safest) approach here is to encrypt data you don’t want others to see yourself before storing it.
#### How do you update data stored on Filecoin?
We have some really good ideas around ‘warm’ storage (that is mutable and provable) that we will probably implement in the near future. But for now, your app will have to treat Filecoin as an append-only log. If you want to change your data, you just write new data.
‘Warm’ storage can be done with a small amount of trust, where you make a deal with a storage provider with a start date quite far in the future. The storage provider can choose to store your data in a sector now (but they won’t get paid for proving it until the actual start date), or they can hold it for you (and even send you proofs of it on request), and you can then send them new data to overwrite it, along with a new storage deal that overwrites the previous one.
There’s a pretty large design space here, and we can do a bunch of different things depending on the levels of trust involved, the price sensitivity, and the frequency of updates clients desire.
#### Who will be selected to be verifiers to verify clients on the network?
Allocators, selected through an application process, serve as fiduciaries for the Filecoin network and are responsible for allocating DataCap to clients with valuable storage use cases.
See [Filecoin Plus](broken://pages/ONanf0Ny7ISDeH7beMKF).
#### Will the existence of Filecoin mining pools lead to centralized storage and away from the vision of distributed storage?
No – Filecoin creates a decentralized storage network in part by massively decreasing the barrier to entry to becoming a storage provider. Even if there were some large pools, anyone can join the network and provide storage with just a modest hardware purchase, and we expect clients to store their files with many diverse storage providers.
Also, note that world location matters for mining: many clients will prefer storage providers in specific regions of the world, so this enables lots of storage providers to succeed across the world, where there is storage demand.
#### Even though Filecoin will be backed up to our normal IPFS pinning layer, we still need to know how quickly we can access data from the Filecoin network. How fast will retrieval be from the Filecoin network?
If you are retrieving your data from IPFS or a remote pinning layer, retrieval should take on the order of milliseconds to seconds in the worst case. Our latest tests for retrieval from the Filecoin network directly show that a sealed sector holding data takes \~1 hour to unseal. 1-5 hours is our best real-world estimate to go from sector unsealing to delivery of the data. If you need faster data retrieval for your application, we recommend building on IPFS.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/filecoin-faqs)
# FAQs
A list of frequent asked questions about FVM, FEVM and how to build on Filecoin network.
Here’s a collection of general FAQs that the team has gathered. If you are looking for more technical FAQs, please head to [Filecoin Community Discussion](https://github.com/filecoin-project/community/discussions/categories/q-a).
## **What is FVM**
The [FVM](https://fvm.filecoin.io) (Filecoin virtual machine) enables developers to write and deploy custom code to run on top of the Filecoin blockchain. This means developers can create apps, markets, and organizations built around data stored on Filecoin.
## **What broader implications does FVM have**
FVM allows us to think about data stored on Filecoin differently. Apps can now build a new layer on the Filecoin network to enable trading, lending, data derivatives, and decentralized organizations built around datasets.
## **What problems does FVM solve**
FVM can create incentives to solve problems that Filecoin participants face today around data replication, data aggregation, and liquidity for miners. Beyond these, there is a long tail of data storage and retrieval problems that will also be resolved by user programmability on top of Filecoin.
## **How does Aptos compare to FVM**
[Aptos](https://aptoslabs.com/) is a Move-based L1 chain, whereas FVM is a WASM runtime on the Filecoin chain. The latter comes with an EVM right of the box; the former does not. The FVM also supports programmable storage with deals on Filecoin.
## **How does the FVM directly interact with data on Filecoin**
The FVM operates on blockchain state data — it does *not* operate on data stored in the Filecoin network. This is because access to that data depends on network requests, an unsealed copy’s availability, and the SPs’ availability to supply that data.
Access and manipulation of data stored in the network will happen via L2 solutions, for example, retrieval networks or compute-over-data networks.
## **How do other EVMs compare to FEVM**
Unlike other EVM chains, FEVM specifically allows you to write contracts that orchestrate programmable storage. This means contracts that can coordinate storage providers, data health, perpetual storage mechanisms, and more. Other EVM chains do not have direct access to Filecoin blockchain state data.
## **What is an actor**
An actor is code that the Filecoin virtual machine can run. Actors are also referred to as smart contracts.
## **What are built-in actors**
[Built-in actors](https://github.com/filecoin-project/builtin-actors) are code that come precompiled into the Filecoin clients and can be run using the FVM. They are similar to [Ethereum precompiles](https://www.evm.codes/precompiled?fork=merge).
## **Why use the FEVM vs any other EVM compatible chain**
Having storage contracts as a native primitive open to smart contract developers. Reduce costs of writing to storage from an EVM smart contract to a separate storage service.
## **Why FEVM vs native FVM**
FEVM allows Solidity developers to easily write/port actors to the FVM using the tools that have already been introduced in the Ethereum ecosystem.
## **What applications make FVM/FEVM unique**
Applications that natively make use of storage contracts. Perpetual storage contracts, Data DAOs, etc.
## **What is perpetual storage**
Perpetual storage is a unique actor design paradigm only available on the FVM that allows users the ability to renew Filecoin storage deals and to keep them active indefinitely. This could be achieved by using a Decentralized Autonomous Organization (DAO) structure for example.
## **What are Data DAOs**
Data DAOs are a unique design paradigm FVM developers could create which use Filecoin storage to store all their data instead of a service like AWS (which is currently used).
## **Is FVM part of Filecoin clients like Lotus**
Yes.
## **Do I have to install Lotus to work with FVM**
Not necessarily. You can use public RPC nodes on either [mainnet](/networks-and-tools/networks/mainnet/rpcs) or the [Calibration testnet](/networks-and-tools/networks/calibration/rpcs).
## **Why does the FVM use WASM**
Many [different languages](https://github.com/appcypher/awesome-wasm-langs) already compile to WASM so developers can pick their favorite.
## **Is the FEVM a bridge to the EVM**
No, the FEVM is its own instance of the EVM built on top of Filecoin. You will need to redeploy smart contracts that exist in the EVM to the FEVM. Bridges can be built to top of the FEVM which connect it to other blockchains however.
## **How is the Filecoin network accessed through Solidity**
When an EVM is deployed to FEVM, it is compiled with WASM and an actor instance is created in FEVM that runs the EVM bytecode. The user-defined FEVM actor is then able to interact with the Filecoin network via built-in actors like the Market and Miner APIs.
## **Can I deploy EVM bytecode to the native FVM**
No, it must be deployed to the FEVM.
## **What frontend framework should I use?**
React, Ethers.js, web.js, ReactJS work well.
## **How do we convert from msg.sender in a FEVM contract, which returns an EVM `0x` address, to the underlying Filecoin `f` address?**
You can use the npm [`@glif/filecoin-address`](https://www.npmjs.com/package/@glif/filecoin-address) package or the [Zondax mock API](https://github.com/Zondax/fevm-solidity-mock-api) has the constructor that calls `mock_generate_deals();`.
## **How do I bound the replicator factor from solidity FEVM?**
Store a number limit on running `DealClient` and `publish_deal` and have it authorized to replicate.
## **How can I use FVM to store data to Filecoin**
The intent of FEVM/FVM is to compute over state data (the metadata of your stored data). Storage providers are the ones that are able to store your data and upload the deal to the Filecoin network. Data retrieval happens via Retrieval Providers, accepting the client’s ask to retrieve and working with storage providers to decrypt the data to deliver to the client. FEVM/FVM is able to build logic around these 2 processes and automate, add verification and proofs, time-lock retrievals etc.
## **How do I close a storage deal on Filecoin and stop storage providers (SP) from storing my data on-chain**
It’s not impossible but storage providers are incentivized not to close the storage deal as they are slashed for not providing [Proof of Spacetime (PoSt)](/reference/general/glossary#proof-of-spacetime-post). Someone has to pay for the broken promise a miner makes to the chain and you need a custom market actor for it most likely to make the deal. You need to make deals for a certain amount of time - right now the boundaries are 6-18 months. You cannot ask a storage provider to take down your data without contacting them off-chain.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/faqs)
# Related projects
Filecoin is a highly modular project that is itself made out of many different protocols and tools. Many of these exist as their own projects, supported by Protocol Labs. Learn more about them below.
## Libp2p
A modular network stack, libp2p enables you to run your network applications free from runtime and address services, independently of their location. Learn more at [libp2p.io/](http://libp2p.io/).
### IPLD
IPLD is the data model of the content-addressable web. It allows us to treat all hash-linked data structures as subsets of a unified information space, unifying all data models that link data with hashes as instances of IPLD. Learn more at [ipld.io/](https://ipld.io/).
### IPFS
IPFS is a distributed system for storing and accessing files, websites, applications, and data. However, it does not have support for incentivization or guarantees of this distributed storage; Filecoin provides the incentive layer. Learn more at [ipfs.tech/](https://ipfs.tech/).
### Multiformats
The Multiformats Project is a collection of protocols which aim to future-proof systems through self-describing format values that allow for interoperability and protocol agility. Learn more at [multiformats.io/](https://multiformats.io/).
### ProtoSchool
Interactive tutorials on decentralized web protocols, designed to introduce you to decentralized web concepts, protocols, and tools. Complete code challenges right in your web browser and track your progress as you go. Explore ProtoSchool’s tutorials on Filecoin at [proto.school/](https://proto.school/#/tutorials?course=filecoin).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/related-projects)
# Social media
Filecoin is everywhere on the internet — and that includes social media. Find your favorite flavor here.
### YouTube
The [Filecoin YouTube channel](https://www.youtube.com/channel/UCPyYmtJYQwxM-EUyRUTp5DA) is home to a wealth of information about the Filecoin project — everything from developer demos to recordings of mining community calls — so you can explore playlists and subscribe to ones that interest and inform you.
### Blog
Explore the latest news, events and other happenings on the official [Filecoin Blog](https://filecoin.io/blog/).
### Updates
Follow the [Filecoin blog](https://filecoin.io/blog/) and [Filecoin events](https://fil.org/events) for official project updates.
### Twitter
Get your Filecoin news in tweet-sized bites. Follow these accounts for the latest:
* `@Filecoin` for news and other updates from the Filecoin project
* `@ProtoSchool` for updates on ProtoSchool workshops and tutorials
### WeChat
Follow FilecoinOfficial on [WeChat](https://www.wechat.com/) for project updates and announcements in Chinese.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/social-media)
# The Filecoin project
Curious about how it all got started, or where we’re headed? Learn about the history, current state, and future trajectory of the Filecoin project here.
### Roadmap
The [Filecoin Community Roadmap](https://github.com/filecoin-project/community/discussions/456) is updated quarterly. It provides insight into the strategic development of the network and offers pathways for community members to learn more about ongoing work and connect directly with project teams.
### Research
Learn about the ongoing cryptography research and design efforts that underpin the Filecoin protocol on the [Filecoin Research website](https://github.com/filecoin-project/research). The [research groups at Protocol Labs](https://research.protocol.ai/groups/) also actively research improvements.
### Code of conduct
The Filecoin community believes that our mission is best served in an environment that is friendly, safe, and accepting, and free from intimidation or harassment. To that end, we ask that everyone involved in Filecoin read and respect our [code of conduct](https://github.com/filecoin-project/community/blob/master/CODE_OF_CONDUCT.md).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/getting-started/community/the-filecoin-project)
# Ways to contribute
So you want to contribute to Filecoin and the ecosystem? Here is a quick listing of things to which you can contribute and an overview on how you can get started.
### Ways to contribute
#### Code
Filecoin and its sister-projects are big, with lots of code written in multiple languages. We always need help writing and maintaining code, but it can be daunting to just jump in. We use the label *Help Wanted* on features or bug fixes that people can help out with. They are an excellent place for you to start contributing code.
The biggest and most active repositories we have today are:
* [`filecoin-project/venus`](https://github.com/filecoin-project/venus)
* [`filecoin-project/lotus`](https://github.com/filecoin-project/lotus)
* [`filecoin-project/rust-fil-proofs`](https://github.com/filecoin-project/rust-fil-proofs)
If you want to start contributing to the core of Filecoin, those repositories are a great place start. But the *Help Wanted* label exists in several related projects:
* [IPFS](https://github.com/ipfs)
* [libp2p](https://github.com/libp2p)
* [IPLD](https://github.com/ipld)
* [Multiformats](https://github.com/multiformats)
#### Documentation
Filecoin is a huge project and undertaking, and with lots of code comes the need for lots of good documentation! However, we need a lot more help to write the awesome docs the project needs. If writing technical documentation is your area, any and all help is welcome!
Before contributing to the Filecoin docs, please read these quick guides; they'll save you time and help keep the docs accurate and consistent!
1. [Style and formatting guide](#style)
2. [Writing guide](#writing-guide)
3. [GitBook documentation guide](#gitbook-documentation)
If you have never contributed to an open-source project before, or just need a refresher, take a look at the [contribution tutorial](#contribution-tutorial).
#### Community
If interacting with people is your favorite thing to do in this world, join the [Filecoin chat and discussion forums](/getting-started/community/forums-and-fips) to say hello, meet others who share your goals, and connect with other members of the community. You should also consider joining [Filecoin Slack](https://filecoinproject.slack.com/ssb/redirect).
#### Build Applications
Filecoin is designed for you to integrate into your own applications and services.
Get started by looking at the list of projects currently built on Filecoin. Build anything you think is missing! If you're unsure about something, you can join the chat and discussion forums to get help or feedback on your specific problem/idea. You can also join a Filecoin Hackathon, apply for a Filecoin Developer Grant or apply to the Filecoin accelerator program to support the development of your project.
* [Filecoin Hackathons](https://hackathons.filecoin.io/)
* [Filecoin Developer Grants](https://www.fil.org/grants)
* [Filecoin Accelerator Program](https://ecosystem-wg.notion.site/Protocol-Labs-Accelerator-Program-d45d8792a7d544eca9beb7d3e3d3b05d)
#### Protocol Design
Filecoin is ultimately about building better protocols, and the community always welcome ideas and feedback on how to improve those protocols.
* [`filecoin-project/specs`](https://github.com/filecoin-project/specs)
#### Research
Finally, we see Protocol Labs as a research lab, where YOUR ideas can become technologies that have a real impact on the world. If you're interested in contributing to our research, please reach out to for more information. Include what your interests are so we can make sure you get to work on something fun and valuable.
### GitBook documentation
This site is built with [GitBook](https://www.gitbook.com/) and synced from a Git repository. You can contribute by editing markdown files directly in the repo or through the GitBook UI.
#### Content structure
GitBook organizes content through pages (markdown files), grouped into sections defined in `SUMMARY.md`. The key files are:
* **`SUMMARY.md`** defines the table of contents and sidebar navigation.
* **`WELCOME.md`** is the homepage.
* **`.gitbook.yaml`** configures the space (root path, redirects).
Every page is a markdown file with optional YAML frontmatter:
```markdown
---
description: A short summary for SEO and link previews
icon: book-open
layout:
width: default
---
# Page title
Content starts here.
```
#### Frontmatter fields
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.
#### Internal links
Always use relative file paths for links between documentation pages:
```markdown
[Networks overview](../what-is-filecoin/networks.md)
[Getting started](../../getting-started/README.md)
```
External links use full URLs:
```markdown
[Filecoin GitHub](https://github.com/filecoin-project)
```
#### GitBook custom blocks
This site uses several GitBook-specific markdown extensions. Here are the ones you will encounter most frequently.
**Hints** draw attention to important information:
```markdown
{% raw %}
{% hint style="info" %}
This is an informational callout.
{% endhint %}
{% hint style="warning" %}
Be careful when running this command in production.
{% endhint %}
{% hint style="danger" %}
This action cannot be undone.
{% endhint %}
{% endraw %}
```
Supported styles: `info`, `warning`, `danger`, `success`.
**Expandable sections** hide optional or lengthy content:
````markdown
Advanced configuration
Detailed information that most users do not need.
```yaml
advanced:
option1: value1
```
````
**Tabs** present alternative options (languages, platforms):
````markdown
{% raw %}
{% tabs %}
{% tab title="macOS" %}
```shell
brew install lotus
```
{% endtab %}
{% tab title="Linux" %}
```shell
sudo apt install lotus
```
{% endtab %}
{% endtabs %}
{% endraw %}
````
**Cards** create visual navigation grids:
```markdown
```
**Code blocks with titles** label file names or context:
````markdown
{% raw %}
{% code title="hardhat.config.js" %}
```javascript
module.exports = {
solidity: "0.8.17",
};
```
{% endcode %}
{% endraw %}
````
#### Common pitfalls
\* Do not reference the same markdown file twice in \`SUMMARY.md\`. \* Keep \`SUMMARY.md\` synchronized with actual file paths. \* Test custom blocks in GitBook after editing locally.
### Writing guide
This guide explains things to keep in mind when writing for Filecoin's documentation. While the [grammar, formatting, and style guide](#style) lets you know the rules you should follow, this guide will help you to properly structure your writing and choose the correct tone for your audience.
#### Walkthroughs
The purpose of a walkthrough is to tell the user *how* to do something. They do not need to convince the reader of something or explain a concept. Walkthroughs are a list of steps the reader must follow to achieve a process or function.
The vast majority of documentation within the Filecoin documentation project falls under the *Walkthrough* category. Walkthroughs are generally quite short, have a neutral tone, and teach the reader how to achieve a particular process or function. They present the reader with concrete steps on where to go, what to type, and things they should click on. There is little to no *conceptual* information within walkthroughs.
**Goals**
Use the following goals when writing walkthroughs:
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.
**Function or process**
The end goal of a walkthrough is for the reader to achieve a very particular function. *Installing the Filecoin Desktop application* is an example. Following this walkthrough isn't going to teach the reader much about working with the decentralized web or what Filecoin is. Still, by the end, they'll have the Filecoin Desktop application installed on their computer.
**Short length**
Since walkthroughs cover one particular function or process, they tend to be quite short. The estimated reading time of a walkthrough is somewhere between 2 and 10 minutes. Most of the time, the most critical content in a walkthrough is presented in a numbered list. Images and GIFs can help the reader understand what they should be doing.
If a walkthrough is converted into a video, that video should be no longer than 5 minutes.
**Walkthrough structure**
Walkthroughs are split into three major sections:
1. What we're about to do.
2. The steps we need to do.
3. Summary of what we just did, and potential next steps.
#### Conceptual articles
Articles are written with the intent to inform and explain something. These articles don't contain any steps or actions that the reader has to perform *right now*.
These articles are vastly different in tone when compared to walkthroughs. Some topics and concepts can be challenging to understand, so creative writing and interesting diagrams are highly sought-after for these articles. Whatever writers can do to make a subject more understandable, the better.
**Article goals**
Use the following goals when writing conceptual articles:
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.
**Article structure**
Articles are separated into five major sections:
1. Introduction to the thing we're about to explain.
2. What the thing is.
3. Why it's essential.
4. What other topics it relates to.
5. Summary review of what we just read.
#### Tutorials
When writing a tutorial, you're teaching a reader how to achieve a complex end-goal. Tutorials are a mix of walkthroughs and conceptual articles. Most tutorials will span several pages, and contain multiple walkthroughs within them.
Take the hypothetical tutorial *Get up and running with Filecoin*, for example. This tutorial will likely have the following pages:
1. A brief introduction to what Filecoin is.
2. Choose and install a command line client.
3. Understanding storage deals.
4. Import and store a file.
Pages `1` and `3` are conceptual articles, describing particular design patterns and ideas to the reader. All the other pages are walkthroughs instructing the user how to perform one specific action.
When designing a tutorial, keep in mind the walkthroughs and articles that already exist, and note down any additional content items that would need to be completed before creating the tutorial.
### Grammar and formatting
Here are some language-specific rules that the Filecoin documentation follows. If you use a writing service like [Grammarly](https://www.grammarly.com/), most of these rules are turned on by default.
#### American English
While Filecoin is a global project, the fact is that American English is the most commonly used *style* of English used today. With that in mind, when writing content for the Filecoin project, use American English spelling. The basic rules for converting other styles of English into American English are:
1. Swap the `s` for a `z` in words like *categorize* and *pluralize*.
2. Remove the `u` from words like *color* and *honor*.
3. Swap `tre` for `ter` in words like *center*.
#### The Oxford comma
In a list of three or more items, follow each item except the last with a comma `,`:
| Use | Don't use |
| ----------------------------- | ---------------------------- |
| One, two, three, and four. | One, two, three and four. |
| Henry, Elizabeth, and George. | Henry, Elizabeth and George. |
#### References to Filecoin
As a proper noun, the name "Filecoin" (capitalized) should be used only to refer to the overarching project, to the protocol, or to the project's canonical network:
> Filecoin \[the project] has attracted contributors from around the globe! Filecoin \[the protocol] rewards contributions of data storage instead of computation! Filecoin \[the network] is currently storing 50 PiB of data!
The name can also be used as an adjective:
> The Filecoin ecosystem is thriving! I love contributing to Filecoin documentation!
When referring to the token used as Filecoin's currency, the name `FIL`, is preferred. It is alternatively denoted by the Unicode symbol for an integral with a double stroke ⨎:
* Unit prefix: **100 FIL**.
* Symbol prefix: **⨎ 100**.
The smallest and most common denomination of FIL is the `attoFIL` (10^-18 FIL).
> The collateral for this storage deal is 5 FIL. I generated ⨎100 as a storage provider last month!
Examples of discouraged usage:
> Filecoin rewards storage providers with Filecoin. There are many ways to participate in the Filecoin community. My wallet has thirty filecoins.
Consistency in the usage of these terms helps keep these various concepts distinct.
#### References to Lotus
Lotus is the main implementation of Filecoin. As such, it is frequently referenced in the Filecoin documentation. When referring to the Lotus implementation, use a capital *L*. A lowercase *l* should only be used when referring to the Lotus executable commands such as `lotus daemon`. Lotus executable commands should always be within code blocks:
````markdown
1. Start the Lotus daemon:
```shell
lotus daemon
```
2. After your Lotus daemon has been running for a few minutes, use `lotus` to check the number of other peers that it is connected to in the Filecoin network:
```shell
lotus net peers
```
````
#### Acronyms
If you have to use an acronym, spell the full phrase first and include the acronym in parentheses `()` the first time it is used in each document. Exception: This generally isn't necessary for commonly-encountered acronyms like *IPFS*, unless writing for a stand-alone article that may not be presented alongside project documentation.
> Virtual Machine (VM), Decentralized Web (DWeb).
### Formatting
How the Markdown syntax looks, and code formatting rules to follow.
#### Syntax
The Filecoin Docs project follows the *GitHub Flavoured Markdown* syntax for markdown. This way, all articles display properly within GitHub itself.
#### Rules
We use the rules set out in the [VSCode Markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension. You can import these rules into any text editor like Vim or Sublime. All rules are listed [within the Markdownlint repository](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md).
We highly recommend installing [VSCode](https://code.visualstudio.com/) with the [Markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension to help with your writing. The extension shows warnings within your markdown whenever your copy doesn't conform to a rule.
### Style
The following rules explain how we organize and structure our writing. The rules outlined here are in addition to the [rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md) found within the [Markdownlinter extension](https://github.com/DavidAnson/vscode-markdownlint).
#### Text
The following rules apply to editing and styling text.
**Titles**
1. All titles follow sentence structure. Only *names* and *places* are capitalized, along with the first letter of the title. All other letters are lower-case:
## This is a title
### Only capitalize names and places
### The capital city of France is Paris
1. Every article starts with a *front-matter* title and description:
```markdown
---
title: Example article
description: This is a brief description that shows up in link teasers in services like Twitter and Slack.
---
## This is a subtitle
Example body text.
```
In the above example `title:` serves as a `
` 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 for Agents
How AI agents can use Filecoin Cloud (FC) for storage that is persistent, portable, open, and verifiable, without a human in the loop.
**AI agents can use Filecoin Cloud (FC) to give their context, artifacts, and records a home that survives the session, the tool, and the vendor: storage that stays portable across agents and frameworks, open with no single point of lock-in, and verifiable end to end.**
This page is a starting point for building agents that use FC. It links out to the CLIs, SDKs, and console you'll actually use, rather than repeating their full documentation here.
{% hint style="info" %}
**Storing files and folders with the `filecoin` CLI?** The [Filecoin for Agents build guide](/build-on-filecoin/filecoin-for-agents) covers the `filecoin` CLI, its agent plugin and skill for Claude Code, Codex, and other agents, and a read-only MCP server. The `publish` skill below is for pinning with Filecoin Pin.
{% endhint %}
## Overview
Agents forget. When a session ends, a tool gets swapped, or a vendor shuts down, whatever an agent learned or produced usually disappears with it. Every skill built on Filecoin Cloud (FC), starting with `publish` below, aims to fix that around four ideas:
* **Persistent.** Your agent's context, artifacts, and records survive the session, the tool, and the vendor. Nothing it learns or makes disappears when the window closes.
* **Portable.** Move useful state across agents, models, frameworks, and teammates, including across org boundaries.
* **Open.** Neutral infrastructure with exportable ownership and no lock-in of valuable agent state.
* **Verifiable.** Underneath it all, the retrieved bytes are the written bytes. This isn't the pitch, it's the reason the pitch is credible, and it surfaces where it earns its keep: enterprise audit conversations.
## Filecoin for agentic use cases
A few patterns come up often when agents use FC:
* **Durable agent memory and outputs.** Agents that need to persist state, logs, or generated artifacts (files, datasets, reports) across restarts or across a fleet can pin them to Filecoin and keep a verifiable, addressable record of what they produced and when.
* **Verifiable identity and provenance.** Agents that register a verifiable identity (for example, under [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004)) can back that identity with metadata stored on Filecoin, so other agents or services can verify both who an agent is and that its declared capabilities/data haven't disappeared. See [Filecoin Pin for ERC-8004 Agents](/build-on-filecoin/cookbook/filecoin-pin/erc-8004-agent-registration) for a full walkthrough.
* **IPFS-compatible by default.** If an agent (or the framework it's built on) already speaks IPFS, adding Filecoin persistence doesn't require new tooling. Content stays addressable by the same Content Identifier (CID).
* **Paying as it goes.** Storage and other services can be funded once and drawn against automatically, instead of a human provisioning and paying upfront for each use.
## Quickstart: publish an artifact
`publish` is the first in a growing set of packaged skills for the use cases above; more are on the way for agent memory, identity, and beyond. The fastest way to see it working end to end is to have an agent publish a file using the `publish` skill, the way an agent would share an artifact it just produced. The skill drives the [Filecoin Pin CLI](https://github.com/filecoin-project/filecoin-pin) underneath, so everything here works whether an agent invokes the skill or you run the CLI directly.
Before you start, make sure you have:
* **An Ethereum-style wallet on Filecoin.** See [Wallets](/networks-and-tools/assets/wallets). You'll use it to approve access from a browser, not to hand a key to the agent.
* **FIL in that wallet,** to cover transaction fees.
* **USDFC in that wallet,** to pay for storage. USDFC is Filecoin Cloud's storage-payment stablecoin. 5 USDFC is enough to start.
* **Node.js 24 or later.**
1. **Install the skill and the CLI it drives:**
```sh
npx skills add filecoin-project/filecoin-skills --skill publish
npm install -g filecoin-pin
```
2. **Log in once.** Run `filecoin-pin login` and approve a scoped session key in the Filecoin Cloud console from your wallet. No private key ever touches the agent, and the key can be revoked from the console at any time.
```sh
filecoin-pin login
```
3. **Set up payments in the console.** Authorize the Warm Storage Service to spend USDFC and deposit funds into Filecoin Pay, both in the console's Add Service flow, in a single wallet transaction. A session key can't move money, so this step is always a human's.
4. **Ask the agent to publish something.** Say "publish this," "share this file," or "pin this." The agent hands back a link like `https://inbrowser.link/ipfs/`, first the moment the CID is known, then confirmed once verification passes.
Prefer to drive the CLI directly instead of through the skill? The same `filecoin-pin add`, `filecoin-pin payments setup`, and `filecoin-pin data-set` commands work standalone, including a direct private-key mode. See [Filecoin Pin: Getting Started](/build-on-filecoin/cookbook/filecoin-pin/getting-started) for that walkthrough.
## Common questions
**How does an agent verify its data is still stored, instead of just trusting the upload succeeded?** Storage providers submit proof, on a recurring schedule, that they still hold the data (Proof of Data Possession, or PDP). An agent can query this directly at any time (for example with `filecoin-pin data-set show `) rather than relying on a one-time confirmation.
**Can an AI agent use Filecoin without a human approving each transaction?** Yes. Once an agent's wallet is funded and payment authorization is set up (a one-time step, typically done by a human operator), the agent can store data and pay for it directly. No per-transaction approval is required.
**Does an agent need to hold and manage FIL and USDFC directly?** Yes, today. An agent's wallet needs FIL (for transaction fees) and USDFC (Filecoin Cloud's storage-payment stablecoin) for payments. Filecoin Pay is where those payments settle; the [Filecoin Pay Console](#filecoin-pay-console) is where a human operator can inspect or adjust what an agent's wallet is authorized to spend.
**How does an agent authenticate for payments today?** By running `filecoin-pin login` (or using the `publish` skill in the Quickstart above, which calls it by default), which pairs the agent with a scoped, revocable session key instead of a raw wallet private key: a human approves a one-time pairing link from their wallet, and the agent holds only that limited key afterward. Direct private-key access still works as a fallback for the CLI; see [Filecoin Pay Console](#filecoin-pay-console) below for where session keys are managed.
## Resources
### Filecoin Pin CLI
A CLI (and JS library, and GitHub Action) for pinning IPFS-compatible content to Filecoin with verifiable, provider-proven persistence. This is what the quickstart above uses, and it's the right starting point for any agent that just needs to store and retrieve files or datasets.
[Filecoin Pin: Getting Started →](https://docs.filecoin.cloud/getting-started/filecoin-pin)
### Filecoin Cloud CLI
A community-built CLI (also installable as an agent skill and MCP server) for the broader FC stack: wallet setup, dataset management, and storage-provider queries via the Synapse SDK. Where Filecoin Pin focuses on pinning content, Filecoin Cloud CLI is closer to a general-purpose control surface for FC, and it's built to be driven by an agent directly (`npx skills add FIL-Builders/foc-cli`), not just by a human at a terminal.
[Filecoin Cloud CLI →](https://docs.filecoin.cloud/resources/community-projects/#FC-cli)
### Filecoin Pay Console
A web console for managing the payment side of FC: connect a wallet to view and manage payment rails, deposits made in USDFC, and the services you've authorized to draw against them. A human operator uses it directly to authorize spending and fund an agent's session; an agent-driven CLI also opens it briefly, for the one-time wallet approval a session-key login requires.
The console is currently in beta and interacts directly with the underlying payment contracts. Verify transaction details before confirming anything.
{% hint style="info" %}
**Session-key login.** Instead of connecting a full wallet, an agent (or the CLI it's driving) can authenticate with a scoped, revocable session key: it opens a one-time pairing link in a browser, a human approves it from their wallet, and the agent receives a key limited to just what it needs. Run this from the [Filecoin Pin CLI](https://github.com/filecoin-project/filecoin-pin) with `filecoin-pin login`, or see the Quickstart above for the packaged agent skill that uses it by default.
{% endhint %}
[Filecoin Pay Console →](https://pay.filecoin.cloud/console)
***
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-for-agents)
# 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:
Extensible, user-defined actor addresses. f410 addresses refers to Ethereum-compatible address space, each f410 address is equivalent to an 0x address.
Each of the address types is described below.
## Actor IDs
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:
```plaintext
Address type
|
f 0 9 9
| |
| Actor ID
|
Network identifier
```
ID addresses are often referred to by their shorthand `f0`.
## Public keys
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](https://en.wikipedia.org/wiki/Secp256k1) that begin with the prefix `f1`.
* [BLS addresses](https://en.wikipedia.org/wiki/BLS_digital_signature) 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`.
## Actors
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`.
## Extensible user-defined actors
Filecoin supports extensible, user-defined actor addresses through the `f4` address class, introduced in [Filecoin Improvement Proposal (FIP) 0048](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0048.md). 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 `f4f`, where `` is the actor ID of the *address manager*, and `` 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](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0048.md), `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 `` chosen by that actor.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-virtual-machine/addresses)
# Blocks and tipsets
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.
## 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
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.
## Tipsets
As described in [Consensus](/core-concepts/filecoin-virtual-machine/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*.
### Benefits of tipsets
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.
### Tipsets in the Ethereum JSON-RPC
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*.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-virtual-machine/blocks-and-tipsets)
# Consensus
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
## Overview
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](/reference/general/glossary#epoch) where a set number of participants may become eligible to submit a block to the chain based on fair and verifiable criteria.
## Properties
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.
## Steps
In summary, EC involves the following steps at each *epoch*:
1. A storage provider checks to see if they are elected to propose a block by generating an *election proof*.
2. 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.
3. Each potential block producer elected generates a storage proof using [WinningPoSt](/reference/general/glossary#winning-proof-of-spacetime-winningpost) for a randomly selected [*sector*](/reference/general/glossary#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.
4. Blocks generated by block producers are grouped into a [tipset](/reference/general/glossary#tipset).
5. The tipset that reflects the biggest amount of committed storage on the network is selected.
6. Using the selected tipset, the chain state is propagated.
7. EC returns to step 1 in the next epoch.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-virtual-machine/consensus)
# Drand
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](https://www.drand.love/developers).
## Randomness outputs
By polling the appropriate endpoint, a Filecoin node will get back a Drand value formatted as follows:
```json
{
"round": 367,
"signature": "b62dd642e939191af1f9e15bef0f0b0e9562a5f570a12a231864afe468377e2a6424a92ccfc34ef1471cbd58c37c6b020cf75ce9446d2aa1252a090250b2b1441f8a2a0d22208dcc09332eaa0143c4a508be13de63978dbed273e3b9813130d5",
"previous_signature": "afc545efb57f591dbdf833c339b3369f569566a93e49578db46b6586299422483b7a2d595814046e2847494b401650a0050981e716e531b6f4b620909c2bf1476fd82cf788a110becbc77e55746a7cccd47fb171e8ae2eea2a22fcc6a512486d"
}
```
* `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.
## Polling the network
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/` to get the randomness value produced by the beacon at a given round.
## Using Drand
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.
## Edge cases and outages
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.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-virtual-machine/drand)
# Proofs
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*](/core-concepts/filecoin-virtual-machine/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)](#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)](#proof-of-spacetime-post): a procedure to validate that an SP is *continuing to store* a unique copy of some piece of data.
## Proof-of-Replication (PoRep)
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:
1. The data is placed into a [sector](/reference/general/glossary#sector).
2. The sector is sealed by the SP.
3. 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](#sealing-as-proof)).
4. The proof is compressed.
5. The result of the compression is submitted to the network as certification of storage.
### Sealing as proof
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.
## Proof-of-Spacetime (PoSt)
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](#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](#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
*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](/reference/general/glossary#epoch), a small number of SPs are elected to mine new blocks using the [Expected Consensus algorithm](https://spec.filecoin.io/algorithms/expected_consensus/), which guarantees that validators will be chosen based on a probability proportional to their [storage power](/reference/general/glossary#storage-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](/provide-storage/filecoin-economics/block-rewards).
* 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
*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](/provide-storage/filecoin-economics/storage-proving#proving-deadlines). Sector availability is not proved individually; rather, SPs must prove a whole [partition](/provide-storage/filecoin-economics/storage-proving#proving-deadlines) 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.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-virtual-machine/proofs)
# Filecoin EVM runtime
This page details what exactly EVM compatibility means for the FVM, and any other information that Ethereum developers may need to build applications on Filecoin.
The Ethereum Virtual Machine is an execution environment initially designed, built for, and run on the Ethereum blockchain. The EVM was revolutionary because, for the first time, any arbitrary code could be deployed to and run on a blockchain. This code inherited all the decentralized properties of the Ethereum blockchain. Before the EVM, a new blockchain had to be created with custom logic and then bootstrapped with validators every time a new type of decentralized application needed to be built.
Code deployed to EVM is typically written in the high-level language Solidity, although other languages, such as Vyper, exist. The high-level Solidity code is compiled to EVM bytecode which is what is actually deployed to and run on the EVM. Due to it being the first virtual machine to run on top of a blockchain, the EVM has developed one of the strongest developer ecosystems in Web3 to date. Today, many different blockchains run their own instance of the EVM to allow developers to easily port their existing applications into the new blockchain’s ecosystem.
## Ethereum Virtual Machine
The Filecoin EVM, often just referred to as *FEVM*, is the Ethereum virtual machine virtualized as a runtime on top of the Filecoin virtual machine. It allows developers to port any existing EVM-based smart contracts straight onto the FVM. The Filecoin EVM runtime is completely compatible with any EVM development tools, such as Hardhat, Brownie, and MetaMask, making deploying and interacting with EVM-based actors easy! This is because Filecoin nodes offer the Ethereum JSON-RPC API.
## Deep dive
For a deeper dive into the concepts discussed on this page, see this presentation Ethereum compatibility of FVM, see:
{% embed url="" %}
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/architecture/filecoin-evm-runtime)
# Actors
In the Filecoin network, an address is a unique identifier that refers to an actor in the Filecoin state. All actors in Filecoin have a corresponding address which varies from the different usages.
The Filecoin EVM runtime introduces three new actor types:
1. [Placeholder actors](#placeholder).
2. [Ethereum-style accounts](#ethereum-style-account), also called `EthAccount`.
3. [EVM smart contracts](#evm-smart-contract).
## Placeholder
A *placeholder* is a particular type of pseudo-actor that holds funds until an actual actor is deployed at a specific address. When funds are sent to an address starting with `f410f` that doesn’t belong to any existing actor, a *placeholder* is created to hold the said funds until either an account or smart contract is deployed to that address.
A placeholder can become a *real* actor in one of two ways:
1. A message is sent from the account that would exist at that placeholder’s address. If this happens, the placeholder is automatically upgraded into an account.
2. An EVM smart contract is deployed to the address.
## Ethereum-style account
An Ethereum-style account is the Filecoin EVM runtime equivalent of an account with an `f1` or `f3` address, also known as native accounts. However, there are a few key differences:
1. These accounts have `0x`-style addresses and an equivalent `f`-style address starting with `f410f`.
2. Messages from these accounts can be sent with Ethereum wallets like MetaMask by connecting the wallet to a Filecoin client.
3. These accounts can be used to transfer funds to native or Ethereum-style.
4. They can be used to call EVM smart contracts and can be used to deploy EVM smart contracts. However, they cannot be used to call native actors such as multisig or miner actors.
## EVM smart contract
An EVM smart contract actor hosts a single EVM smart contract. Every EVM smart contract will have a `0x`-style address.
### Deploying
An EVM smart contract can be deployed in one of three ways:
1. An existing EVM smart contract can use the EVM’s `CREATE`/`CREATE2` opcode.
2. Ethereum-native tooling can be used in conjunction with an Ethereum-style account such as [Remix](/build-on-filecoin/development-frameworks/remix) or [Hardhat](/build-on-filecoin/development-frameworks/hardhat).
3. A native account can call method `4` on the Ethereum account manager `f010`, passing the EVM init code as a CBOR-encoded byte-string (major type 2) in the message parameters.
### Calling
An EVM smart contract may be called in one of three ways:
1. An EVM smart contract can use the EVM’s `CALL` opcode.
2. Ethereum-native tooling, like [MetaMask](/networks-and-tools/assets/metamask-setup), can be used in conjunction with an Ethereum-style account.
3. Finally, a native account can call method `3844450837` (`FRC42(InvokeEVM)`):
1. The input data should either be empty or encoded as a CBOR byte string.
2. The return data will either be empty or encoded as a CBOR byte string.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/architecture/filecoin-evm-runtime/actor-types)
# Address types
In the Filecoin network, an address is a unique identifier that refers to an actor in the Filecoin state. All actors in Filecoin have a corresponding address which varies from the different usages.
Filecoin has five address classes, and actors tend to have *multiple* addresses. Furthermore, each address class has its own rules for converting between binary and text.
The goal of using different types of addresses is to provide a robust address format that is scalable, easy to use, and reliable. These addresses encode information including：
* Network prefix: indicates the network the actor belongs to.
* Protocol indicator: identify the type and version of this address.
* Payload: identify the actor according to the protocol.
* Checksum: validate the address.
Filecoin addresses can be represented either as raw bytes or a string. Raw bytes format will always be used on-chain. An address can also be encoded to a string, including a checksum and network prefix. The string format will never appear on-chain and is only for human-readable purposes.
Filecoin address can be broken down like this:
| Network prefix | Protocol indicator | Payload | Checksum |
| -------------- | ----------------------------------- | --------- | -------- |
| `f` / `t` | 1 byte: `0` / `1` / `2` / `3` / `4` | *n* bytes | 4 bytes |
The network prefix is prepended to an address when encoding to a string. The network prefix indicates which network an address belongs to. Network prefixes never appear on-chain and are only used when encoding an address to a human-readable format.
* `f` - addresses on the Filecoin mainnet.
* `t` - addresses used on any Filecoin testnet.
The protocol indicator identifies the address type, which describes how a method should interpret the information in the `payload` field of an address.
* `0`: An ID address.
* `1`: A wallet address generated from a secp256k public key.
* `2`: An actor address.
* `3`: A wallet address generated from BLS public key.
* `4`: A delegated address for user-defined foreign actors:
* `410`: Ethereum-compatible address space managed by the Ethereum address manager (EAM). Each 410 address is equivalent to an 0x address.
Each address type is described below.
## ID addresses
All addresses have a short integer assigned to them by `InitActor` sequentially, a unique actor that can create *new* actors. The 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 protocol indicator. Therefore, any address in the Filecoin network has a unique ID address assigned to it.
The mainnet burn account ID address is `f099` and is structured as follows:
```plaintext
Protocol Indicator
|
f 0 9 9
| |
| Actor ID
|
Network identifier
```
## Actor addresses
Addressed representing an actor deployed through the init actor in the Filecoin network. It provides 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.
Actor addresses are often referred to by their shorthand, `2`.
## Wallet addresses
Addresses 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 wallet address. 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 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](https://en.wikipedia.org/wiki/Secp256k1) that begin with the protocol indicator as `1`.
* [BLS addresses](https://en.wikipedia.org/wiki/BLS_digital_signature) that begin with the protocol indicator as `3`.
`t1iandfn6d...ddboqxbhoeva` - a testnet wallet address generated using secp256k1. `t3vxj34sbdr3...road7cbygq` - a testnet wallet address generated using BLS.
## Delegated addresses
Filecoin supports extensible, user-defined actor addresses through the `4` address class, introduced in [Filecoin Improvement Proposal (FIP) 0048](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0048.md). The `4` address class provides the following benefits to the network:
* Implement foreign addressing systems in Filecoin.
* A predictable addressing scheme to support interactions with addresses that do not yet exist on-chain.
* User-defined, programmable addressing systems without extensive changes and network upgrades.
For example, a testnet delegated address using the Ethereum Addressing System is structured as follows:
```plaintext
Address manager actor ID
|
t 410 iandfn6d...
| |
| New actor ID
|
Network identifier
```
The *address manager actor ID* is the actor ID of the address manager actor, which creates new actors and assigns a `4` address to the new actor. This leverages the extensible feature of the `f4` address class.
The *new actor ID* is the arbitrary actor ID chosen by that actor.
### Restrictions
Currently, per [FIP 0048](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0048.md), `f4` addresses may only be assigned by and in association with specific, built-in actors called *address managers*. This restriction will likely be relaxed once users are able to deploy custom WebAssembly actors.
This address type plays an essential role in supporting the FEVM. It allows the Filecoin network to be able to recognize the foreign address and validate and execute the transactions sent and signed by the supported foreign addresses.
The supported foreign addresses can be cast as `f4/t4` addresses, and vice-versa. But not with `f1/t1` or `f3/t3` addresses.
### Ethereum Address Manager
Ethereum Address Manager (EAM) is a built-in actor that manages the Ethereum address space, anchored at the `410` address namespace. It acts like an EVM smart contract factory, offering methods to create and assign the `f410/t410` Filecoin address to Ethereum address.
The subaddress of an `f410/t410` address is the original Ethereum address. Ethereum addresses can be cast as `f410` addresses, and vice-versa. The `f410/t410` address will be used for the Ethereum-compatible FVM (FEVM) development tools and applications built on FEVM.
**Example**
```plaintext
# An Ethereum wallet address.
0xd388ab098ed3e84c0d808776440b48f685198498
# The corresponding Filecoin address on Calibration.
t410f2oekwcmo2pueydmaq53eic2i62crtbeyuzx2gmy
```
If you have an Ethereum wallet address starting with `0x`, then the Ethereum Address Manager (EAM) will assign a corresponding `t410` Filecoin address to it. If you send 10 tFIL to `0xd388ab098ed3e84c0d808776440b48f685198498` using a wallet like MetaMask, you will receive 10 tFIL to your `t410f2oekwcmo2pueydmaq53eic2i62crtbeyuzx2gmy` address on Filecoin Calibration testnet.
```plaintext
# A Filecoin smart contract address.
t410fl5qeigmkcytz7b6sqoojtcetqwf37dm4zv4aijq
# The corresponding Ethereum smart contract address.
0x5f6044198a16279f87d2839c998893858bbf8d9c
```
Again, assume you have deployed a solidity smart contract on Filecoin Calibration. Then you will receive a smart contract address starting with `t410`. EAM will also assign a corresponding `0x` Ethereum address to it.
When you try to invoke this smart contract on Filecoin using Ethereum tooling, you need to use your `0x5f6044198a16279f87d2839c998893858bbf8d9c` smart contract address.
### Converting to a 0x-style Address
The Filecoin EVM runtime introduces support for `0x` Ethereum-style addresses. Filecoin addresses starting with either `f0` or `f410f` can be converted to the `0x` format as follows:
Addresses starting with `f0` can be converted to the `0x` format by:
* Extracting the `actor_id` (e.g., the `1234` in `f01234`).
* Hex encode with a `0xff` prefix: `sprintf("0xff0000000000000000000000%016x", actor_id)`.
Addresses starting with `f410f` address can be converted to the `0x` format by:
* Removing the `f410f` prefix.
* Decoding the remainder as base 32 (RFC 4648 without padding).
* Trim off the last 4 bytes. This is a *checksum* that can optionally be verified, but that’s beyond the scope of this documentation.
* Assert that the remaining address is 20 bytes long.
* Hex-encode: `sprintf(0x%040x", actor_id)`.
{% hint style="danger" %}
`f0` addresses are **not** re-org stable and should not be used until the chain has settled.
{% endhint %}
### Converting to a Filecoin Address
On the flip side, Ethereum-style addresses can be converted to a Filecoin address as follows:
Addresses starting with `0xff0000000000000000000000` can be converted to a Filecoin address by:
* Decoding the last 16 hex digits into a uint64
* Format the address as `f0${decimal(id)}` where decimal(id) is the decimal representation of the decoded actor ID.
Otherwise, it maps to f410f…
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/architecture/filecoin-evm-runtime/address-types)
# FILForwarder
The FilForwarder is a smart contract that lets users transfer FIL from an Ethereum-based f4 address to a Filecoin address of a different type.
## The problem
Filecoin has multiple [address spaces](/core-concepts/filecoin-virtual-machine/addresses): `f0`, `f1`, `f2`, `f3`, and `f4`. Each address space fits a particular need for the Filecoin network. The `f410` address spaces allow Ethereum addresses to be integrated into the Filecoin network.
Users interacting with the Filecoin EVM runtime need to use `f4` addresses, masked to the Ethereum-style `0x` address. These addresses can be created from wallets like MetaMask, Coinbase wallet, or any other EVM-based wallet that allows for custom networks. There are use cases where a user with FIL in an `0x`-style address would want to send FIL to an `f1`, `f2`, or `f3` address. For example, taking FIL out of a smart contract and sending it to a multi-sig account or an exchange.
This is where the problem lies. Ethereum-based wallets do not recognize the `f1`, `f2`, or `f3` address formats, making it impossible to send FIL from an Ethereum-style address.
## The solution
The FilForwarder exposes a smart contract method called `forward` that takes a byte-level definition of a protocol address in an *f-style* and a message value. It then uses the internal Filecoin APIs exposed using the Filecoin EVM runtime to properly send FIL funds reliably and as cheaply as possible. This also has the side effect of creating the actor ID should the address receiving address be considered new. In this way, using FilForwarder from an Ethereum wallet to any other Filecoin address space is safe and reliable.
## Use FILForwarder
You can use the FilForwarder contract in two ways:
* Using the Glif.io browser wallet
* Manually invoking the contract
### Glif.io
Before we start, make sure you know the address you’d like to forward your FIL to. You’ll need to ensure that the `f410` Ethereum-style address has enough FIL to cover the transaction costs.
1. Go to [Glif.io](https://glif.io/en).
2. Select the network you want to use from the dropdown and click **Connect Wallet**.
In this example, we’re using the (now deprecated) Hyperspace testnet.
3. Confirm that you want to connect your wallet to Glif.io. You will only be prompted to do this once.
4. Click **Close** on the connection confirmation screen.
5. Select your wallet address from the dropdown and click **Forward FIL**.
6. Enter the destination address for your FIL, along with the amount of FIL you want to send:
7. Double-check that your destination address is correct and click **Send**.
8. You can check the transaction by clicking the transaction ID.
9. Your funds should be available at the destination after around two minutes. You can check that your funds have arrived by searching for the destination address in a block explorer.
10. If you can’t see your funds, make sure you’re viewing the correct network.
It generally takes around two minutes for a transaction to complete and for the funds to be available at the destination.
### Manually
The FilForwarder contract can be interacted with using standard Ethereum tooling like Hardhat or Remix. In this guide, we’re going to use Hardhat, but these steps can be easily replicated using the [web-based IDE Remix](/build-on-filecoin/development-frameworks/remix).
#### **Prerequisites**
This guide assumes you have the following installed:
* [Yarn](https://yarnpkg.com/)
* A Filecoin address stored in [MetaMask](/networks-and-tools/assets/metamask-setup)
#### **Environment setup**
First, we need to grab the FilForwarder kit and install the dependencies:
1. Clone the FilForwarder repository and install the dependencies:
```
git clone [https://github.com/FilOzone/FilForwarder](https://github.com/FilOzone/FilForwarder)
cd FilForwarder
```
2. Use Yarn to install the project's dependencies:
```
yarn install
[1/4] 🔍 Resolving packages...
[2/4] 🚚 Fetching packages...
[3/4] 🔗 Linking dependencies...
...
✨ Done in 16.34s.
```
3. Create an environment variable for your private key.
```shell
export PRIVATE_KEY=''
# For example
# export PRIVATE_KEY='d52cd65a5746ae71cf3d07a8cf392ca29d7acb96deba7d94b19a9cf3c9f63022'l
```
Always be careful when dealing with your private key. Double-check that you’re not hardcoding it anywhere or committing it to source control like GitHub. Anyone with access to your private key has complete control over your funds.
#### **Invoke the contract**
The contract is deterministically deployed on all Filecoin networks at `0x2b3ef6906429b580b7b2080de5ca893bc282c225`. Any contract claiming to be a FilForwarder that does not reside at this address should not be trusted. Any dApp can connect to the wallet and use the ABI in this repository to call this method using any frontend. See the [Glif section](/core-concepts/filecoin-evm-runtime/filforwarder) above for steps on using a GUI.
Inside this repository is a Hardhat task called `forward`. This task will use the private key to send funds using the contract. This task uses the `fil-forwarder-{CHAIN_ID}.json` file to determine the deployed contract address for a given network. These addresses should always be the same, but these files prevent you from having to specify it each time.
The `forward` command uses the following syntax:
```shell
yarn hardhat forward \
--network \
--destination \
--amount
```
* `NETWORK`: The network you want to use. The options are `mainnet` and `calibration`.
* `DESTINATION_ADDRESS`: The address you want to send FIL to. This is a string, like `t01024` or `t3tejq3lb3szsq7spvttqohsfpsju2jof2dbive2qujgz2idqaj2etuolzgbmro3owsmpuebmoghwxgt6ricvq`.
* `AMOUNT`: The amount of FIL you want to send. The value `3.141` would be 3.141 FIL.
#### **Examples**
1. To send 9 FIL to a `t3` address on the Calibration testnet, run:
```sh
yarn hardhat forward \
--network calibration \
--destination t3tejq3lb3szsq7spvttqohsfpsju2jof2dbive2qujgz2idqaj2etuolzgbmro3owsmpuebmoghwxgt6ricvq \
--amount 9.0
```
2. To send 42.5 FIL to a `t1` address on the Calibration testnet, run:
```shell
yarn hardhat forward \
--network calibration \
--destination t010135 \
--amount 42.5
```
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/architecture/filecoin-evm-runtime/filforwarder)
# Difference with Ethereum
While Filecoin EVM runtime aims to be compatible with the Ethereum ecosystem, it has some marked differences.
## Gas costs
Filecoin charges Filecoin gas only. This includes the Filecoin EVM runtime. Instead of the Filecoin EVM runtime charging gas according to the EVM spec for each EVM opcode executed, the Filecoin virtual machine (FVM) charges Filecoin gas for executing the EVM interpreter itself. The [How gas works](/core-concepts/filecoin-evm-runtime/how-gas-works) page goes into this in more detail. Importantly, this means that Filecoin EVM runtime gas costs and EVM gas costs will be very different:
1. EVM and Filecoin gas are different units of measurement and are not 1:1. Purely based on chain throughput (gas/second), the ratio of Ethereum gas to Filecoin gas is about 1:444. Expect Filecoin gas numbers to look *much* larger than those in Ethereum.
2. Because Filecoin charges Filecoin gas for executing the Filecoin EVM runtime interpreter:
1. Some instructions may be more expensive and/or cheaper in Filecoin EVM runtime than they are in the EVM.
2. EVM instruction costs can depend on the exact Filecoin EVM runtime code-paths taken, and caching.
{% hint style="danger" %}
Filecoin gas costs are not set in stone and should never be hard-coded. Future network upgrades will break any smart contracts that depend on gas costs not changing.
{% endhint %}
## Gas stipend
Solidity calls `address.transfer` and `address.send` to grant a fixed gas stipend of 2300 Ethereum gas to the called contract. The Filecoin EVM runtime automatically detects such calls, and sets the gas limit to 10 million Filecoin gas. This is a relatively more generous limit than Ethereum’s, but it’s future-proof. You should expect the address called to be able to carry out more work than in Ethereum.
## Self destruct
Filecoin EVM runtime emulates EVM self-destruct behavior but isn’t able to entirely duplicate it:
1. There is no gas refund for self-destruct.
2. On self-destruct, the contract is marked as self-destructed, but is not actually deleted from the Filecoin state-tree. Instead, it simply behaves as if it does not exist. It acts like an empty contract.
3. Unlike in the EVM, in Filecoin EVM runtime, self-destruct can *fail* causing the executing contract to revert. Specifically, this can happen if the specified beneficiary address is an embedded [ID address](/core-concepts/filecoin-virtual-machine/addresses) and no actor exists with the specified ID.
4. If funds are sent to a self-destructed contract after it self-destructs but before the end of the transaction, those funds remain with the self-destructed contract. In Ethereum, these funds would vanish after the transaction finishes executing.
## CALLCODE
The `CALLCODE` opcode has not been implemented. Use the newer `DELEGATECALL` opcode.
## BLOCKHASH
Ethereum has one block at every height while Filecoin can have none, one, or many (usually around 4-5). This means that the `BLOCKHASH` instruction behaves a bit differently in the Filecoin EVM:
* Because there can be multiple blocks at any given height, `BLOCKHASH` returns the hash of all the concatenation of the CIDs of all the blocks at the requested height.
* Because there can be no blocks at any given height, if `BLOCKHASH` is called on a height with *no blocks*, it returns the `BLOCKHASH` of the first preceding height with blocks.
## Bare-value sends
In Ethereum, `SELFDESTRUCT` is the only way to send funds to a smart contract without giving the target smart contract a chance to execute code.
In Filecoin, any actor can use `method 0`, also called a bare-value send, to transfer funds to any other actor without invoking the target actor’s code. You can think of this behavior as having the suggested [`PAY` opcode](https://eips.ethereum.org/EIPS/eip-5920) already implemented in Filecoin. However by default, Solidity smart contracts do not accept bare value transfers, unless the author implements the [receive() or fallback() function](https://docs.soliditylang.org/en/v0.8.17/contracts.html#receive-ether-function). For more information see [FIP Discussion #592](https://github.com/filecoin-project/FIPs/discussions/592#discussioncomment-4819619).
Therefore in case the recipient is a smart contract, **it is recommended to always use the `InvokeEVM`** **`method 3844450837` for sends to prevent loss of funds** when sending to an `f410f`/`0x` address recipient.
## Precompiles
The Filecoin EVM runtime, unlike Ethereum, does not usually enforce gas limits when calling precompiles. This means that it isn’t possible to prevent a precompile from consuming all remaining gas. The `call actor` and `call actor id` precompiles are the exception. However, they apply the passed gas limit to the actor call, not the entire precompile operation (i.e., the full precompile execution end-to-end can use more gas than specified, it’s only the final `send` to the target actor that will be limited).
## Multiple Addresses
In Filecoin, contracts generally have multiple addresses. Two of these address types, `f0` and `f410f`, can be converted to 0x-style (Ethereum) addresses which can be used in the `CALL` opcode. See [Converting to a 0x-style address](/core-concepts/filecoin-evm-runtime/address-types#converting-to-a-0x-style-address) for details on how these addresses are derived.
Importantly, this means that any contract can be called by either its “normal” EVM address (corresponding to the contract’s `f410f` address) or its “masked ID address” (corresponding from the contract’s `f0` address).
However, the addresses returned by the CALLER, ORIGIN, and ADDRESS instructions will always be the same for the same contract.
* The ADDRESS will always be derived from the executing contract’s `f410f` address, even if the contract was called via a masked ID address.
* The CALLER/ORIGIN will be derived from the caller/origin’s `f410f` address, if the caller/origin is an Ethereum-style account or an EVM smart contract. Otherwise, the caller/origin’s “masked ID address” (derived from their `f0` address) will be used.
## Deferred execution model
When calling an Ethereum method that allows the user to ask for the `latest` block, Filecoin will return the `chain head` - `1` block. This behavior was implemented for compatibility with the deferred execution mode that Filecoin uses. In this mode, messages submitted at a given `height` are only processed at `height` + `1`. This means that receipts for a block produced at `height` are only available at `height` + `1`.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/core-concepts/filecoin-evm-runtime/difference-with-ethereum)
# How gas works
Instead of assigning a fixed gas cost in each instruction, the Filecoin EVM runtime charges FIL gas based on the WASM code execution of the Filecoin EVM runtime interpreter.
When executing a message that invokes an EVM contract, the Filecoin virtual machine charges for the message chain inclusion (when the message originates off-chain) and then invokes the actor that hosts the contract. The actor is an instance of the EVM actor, which uses the Filecoin EVM runtime interpreter to execute the contract.
The FEVM interpreter must first load its state, including the contract state, which costs additional gas. The interpreter then begins the execution of the contract bytecode. Each opcode interpreted may perform computation, syscalls, state i/o, and send new messages, all of which are charged with FIL gas. Finally, if the contract state is modified, the interpreter must flush it to the blockstore, which costs additional gas.
Generally, it is not possible to compute gas costs for a contract invocation without using gas estimation through speculative execution.
## Calculation example
The total gas fee of a message is calculated as the following:
```plaintext
(Gas usage × Base fee)
+ (GasLimit × GasPremium)
+ (OverEstimationBurn × BaseFee)
```
Take a look at the [Gas usage section of the How Filecoin works page](/core-concepts/filecoin-evm-runtime/how-gas-works) for more information on the various gas-related parameters attached to each message.
Let’s take a transaction as an example. Our gas parameters are:
* `GasUsage` = `1000` attoFIL
* `BaseFee` = `20` attoFIL
* `Gas limit` = `2000` attoFIL
* `Gas premium` = `5` attoFIL
The total fee is `(GasUsage × BaseFee) + (Gaslimit x GasPremium)`:
```plaintext
1000
x 20
= 20000
2000
x 5
= 10000
20000
+ 10000
= 30000 attoFIL
```
Additionally, the message sender can also set the `GasFeeCap` parameter they are willing to pay. If the sender sets the `GasLimit` too high, the network will compute the amount of gas to be refunded and the amount of gas to be burned as `OverEstimationBurn`.
## Estimate gas
Filecoin nodes, such as Lotus, have several JSON-API API endpoints designed to help developers estimate gas usage. The available JSON-RPC APIs are:
* `GasEstimateMessageGas`: estimate gas values for a message without any gas fields set, including GasLimit, GasPremium, and GasFeeCap. Returns a message object with those gas fields set.
* `GasEstimateGasLimit` takes the input message and estimates the `GasLimit` based on the execution cost as well as a transaction multiplier.
* `GasEstimateGasPremium`: estimates what `GasPremium` price you should set to ensure a message will be included in `N` epochs. The smaller `N` is the larger `GasPremium` is likely to be.
* `GasEstimateFeeCap`: estimate the `GasFeeCap` according to `BaseFee` in the parent blocks.
If you want to learn more about how to use those JSON-RPC APIs for the Filecoin gas model, please check the [JSON RPC API docs for Gas](/reference/json-rpc).
Gas estimation varies from network to network. For example, the `BaseFee` on mainnet is different from the `BaseFee` on the Calibration testnet.
If you’d rather not calculate and estimate gas for every message, you can just leave the optional fields unset. The gas fields will be estimated and set when the message is pushed to the mempool.
## Ethereum compatibility
Since Filecoin is fully EVM-compatible, Filecoin nodes also provide Ethereum-compatible APIs to support gas estimation:
* [EthEstimateGas](/reference/json-rpc/eth#ethestimategas): generates and returns an estimate of how much gas is necessary to allow the transaction to complete.
* [EthMaxPriorityFeePerGas](/reference/json-rpc/eth#ethmaxpriorityfeepergas): returns a fee per gas that is an estimate of how much you can pay as a priority fee, or “tip”, to get a transaction included in the current block.
To request the current max priority fee in the network, you can send a request to a public Filecoin endpoint:
```shell
curl --location --request POST 'https://api.calibration.node.glif.io/rpc/v1' \
--header 'Content-Type: application/json' \
--data-raw '{
"jsonrpc":"2.0",
"method":"eth_maxPriorityFeePerGas",
"params": null,
"id":1
}' | jq
```
This will output something like:
```plaintext
{
"jsonrpc": "2.0",
"result": "0x31157",
"id": 1
}
```
You can convert the `result` field from hexadecimal to base 10 in your terminal. Take the `result` output and remove the `0x` from the start. Then use `echo` to output the conversion:
```shell
echo $((16#31157))
# 201047
```
## Additional Resources
* Gas Filecoin improvement proposals (FIPs):
* [FIP 0032](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0032.md)
* [FIP 0037](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0037.md)
* [FIP 0054](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0054.md)
* [Primitive Gas Price list](https://github.com/filecoin-project/ref-fvm/blob/master/fvm/src/gas/price_list.rs)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/architecture/filecoin-evm-runtime/how-gas-works)
# Precompiles
A precompile refers to a pre-existing piece of code or a smart contract that is already deployed on the Filecoin network for use by developers.
The Filecoin virtual machine (FVM) has several pre-compiled contracts called precompiles. Each precompile address starts with `0xfe000...`. Specifically:
* [Resolve address `0xfe00..01`](#resolve-address)
* [Lookup delegated address `0xfe00..02`](#lookup-delegated-address)
* [Call actor by address `0xfe00..03`](#call-actor-by-address)
* [Call actor by ID `0xfe00..05`](#call-actor-by-id)
## Resolve Address
Address: `0xfe00000000000000000000000000000000000001`
Resolves a Filecoin address (e.g., “f01”, “f2abcde”) into a Filecoin actor ID (`uint64`). Every actor in Filecoin has an actor ID.
* Input: The Filecoin address in its *bytes* representation.
* Output:
* If the target actor exists, succeed and return an ABI-encoded actor ID (u64).
* If the target actor doesn’t exist, succeed with no return value.
* If the supplied address is invalid (cannot be parsed as a Filecoin address), revert.
Example:
```solidity
(bool success, bytes memory actor_id_bytes) = address(0xfe00000000000000000000000000000000000001).staticcall(fil_address_bytes);
require(success, "invalid address");
require(actor_id_bytes.length == 32, "actor not found");
uint64 actor_id = abi.decode(actor_id_bytes);
```
## Lookup Delegated Address
Address: `0xfe00000000000000000000000000000000000002`
Looks up the “delegated address” (f4 address) of an actor by ID. This precompile is *usually* used to lookup the Ethereum-style address of an actor by:
1. Looking up the delegated address.
2. Checking that the delegated address is 22 bytes long and starts with `0x040a`.
3. Returning the last 20 bytes (which will be the Ethereum-style address of the target actor).
* Input: An ABI-encoded actor ID (u64 encoded as a u256).
* Output:
* If the supplied actor ID is larger than max u64, revert.
* If the target actor exists and has a delegated address, succeed and return the delegated address as raw bytes.
* Otherwise, succeed with no return value.
Example:
```solidity
(bool success, bytes memory delegated_address_bytes) = address(0xfe00000000000000000000000000000000000002).staticcall(abi.encode(uint256(actor_id)));
```
## Call Actor By Address
Address: `0xfe00000000000000000000000000000000000003`
Calls the specified actor using the native FVM calling convention by its *Filecoin* address. This precompile must be called with `DELEGATECALL` as the precompile will call the target actor *on behalf of* the currently executing contract.
### Input: ABI Encoded
{% code overflow="wrap" %}
```json
(uint64 method, uint256 value, uint64 flags, uint64 codec, bytes params, bytes filAddress)
```
{% endcode %}
* `method` is the Filecoin method number. The precompile will revert if the method number is not either 0 (bare value transfer) or at least 1024. Methods between 1 and 1023 inclusive are currently restricted (but may be allowed in the future).
* `value` is the value to transfer in attoFIL.
* `codec` is the IPLD codec of the parameters. This must either be 0x51 or 0x00 (for now) and will revert if passed an illegal codec:
* If the parameters are non-empty, they must be CBOR, and the codec must be 0x51.
* If the parameters are empty, the codec must be 0x00.
* `params` are the CBOR-encoded message parameters, if any.
* `filAddress` is the Filecoin address of the caller.
### Output: ABI Encoded
```
(int256 exit_code, uint64 return_codec, bytes return_value)
```
* `exit_code` is one of:
* `= 0` to indicate the call exited successfully.
* `> 0` to indicate that the target actor *reverted* with the specified `exit_code`.
* `< 0` to indicate the call itself failed with the [syscall-error](https://docs.rs/fvm_sdk/0.6.1/fvm_sdk/sys/enum.ErrorNumber.html) `-exit_code`.
* `return_codec` codec of returned data. This will be one of (for now):
* 0x51 or 0x71 - CBOR
* 0x55 - raw (the target actor returned raw data)
* 0x00 - nothing (the returned data will be empty as well).
{% hint style="danger" %}
This precompile only reverts if an input is statically invalid. If the precompile fails to call the target actor for any other reason, it will return a non-zero `exit_code` but will not revert.
{% endhint %}
Example:
```solidity
(bool success, bytes memory data) = address(0xfe00000000000000000000000000000000000003).delegatecall(abi.encode(method, value, flags, codec, params, filAddress));
(int256 exit, uint64 return_codec, bytes memory return_value) = abi.decode(data, (int256, uint64, bytes));
```
## Call Actor By ID
Address: `0xfe00000000000000000000000000000000000005`
This precompile is identical to the “Call Actor By Address” (0xfe00..03) except that it accepts an actor ID (`uint64`) instead of an actor address as the last parameter. That is:
```solidity
(uint64 method, uint256 value, uint64 flags, uint64 codec, bytes params, uint64 actorId)
```
Example:
```solidity
(bool success, bytes memory data) = address(0xfe00000000000000000000000000000000000005).delegatecall(abi.encode(method, value, flags, codec, params, id));
(int256 exit, uint64 return_codec, bytes memory return_value) = abi.deco
```
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/architecture/filecoin-evm-runtime/precompiles)
# Getting started
Start building on Filecoin. Choose a path based on what you want to build — from simple storage integrations to full smart-contract applications.
This guide helps you pick the right path based on what you want to build on Filecoin.
## Choose your path
### Store data on Filecoin
Filecoin provides multiple storage paths depending on how much control you need. [Filecoin Onchain Cloud (FOC)](/build-on-filecoin/filecoin-onchain-cloud) is the recommended starting point. It provides a complete on-chain storage stack with warm storage through the [Synapse SDK](/build-on-filecoin/filecoin-onchain-cloud/synapse-quickstart), cold storage for large datasets through the [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss), cryptographic verification, and automated payments. If you prefer a managed service, [storage onramps](/getting-started/how-storage-works/storage-onramps) let you store data through simple APIs or web UIs without managing infrastructure. For operators who want to run their own PDP-enabled storage provider, see the [PDP setup guide](/provide-storage/pdp).
| Path | Best for | Complexity |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------- |
| [Filecoin Onchain Cloud (FOC)](/build-on-filecoin/filecoin-onchain-cloud) | Verifiable on-chain storage with FWSS, PDP, and Filecoin Pay via the Synapse SDK | Low |
| [Filecoin Cold Storage Service (FCSS)](/build-on-filecoin/filecoin-onchain-cloud/fcss) | Sealed, verifiable copies of datasets of 1 TiB and up, part of FOC, via a CLI, web app, or AI agent | Medium |
| [Storage onramps](/getting-started/how-storage-works/storage-onramps) | Managed services with simple APIs or drag-and-drop UIs | Low |
| [PDP](/provide-storage/pdp) | Run your own PDP-enabled storage provider (part of the FOC stack) | Medium |
*For a walkthrough of all storage options, see* [*Upload to Filecoin*](/getting-started/how-storage-works/upload-to-filecoin)*.*
### Deploy smart contracts
Filecoin runs an EVM-compatible runtime, so you can write Solidity contracts and deploy them using familiar Ethereum tooling. Choose a [development framework](/build-on-filecoin/development-frameworks) (Remix, Hardhat, or Foundry), get [test tokens](/build-on-filecoin/developing-contracts/get-test-tokens) on Calibration, and deploy your first contract with the [ERC-20 quickstart](/build-on-filecoin/developing-contracts/erc-20-quickstart). Once deployed, [verify your contract](/build-on-filecoin/verification) through a block explorer.
Filecoin contracts can also interact with the storage network directly. Use [Filecoin.sol](/build-on-filecoin/developing-contracts/filecoin.sol) to access storage primitives from Solidity, or [call built-in actors](/build-on-filecoin/developing-contracts/call-built-in-actors) to work with miner, market, and power actors on-chain.
### Integrate advanced features
After you have a working contract, Filecoin supports deeper integrations. [Oracles](/build-on-filecoin/advanced/oracles) bring off-chain data into your contracts. [Cross-chain bridges](/build-on-filecoin/advanced/cross-chain-bridges) let you move assets between Filecoin and other networks. [FEVM indexers](/build-on-filecoin/advanced/fevm-indexers) provide efficient on-chain data queries without running an archival node. [Decentralized databases](/build-on-filecoin/advanced/decentralized-databases) add structured data storage alongside Filecoin.
*Browse more in the* [*Advanced*](/build-on-filecoin/advanced) *section or find solution-focused recipes in the* [*Cookbook*](/build-on-filecoin/cookbook)*.*
## Key resources
| Resource | Description |
| -------------------------------------------------------------------------------- | --------------------------------------------------- |
| [Networks](/networks-and-tools/networks) | Mainnet, Calibration testnet, and local development |
| [Metamask setup](/networks-and-tools/assets/metamask-setup) | Connect your wallet to Filecoin |
| [FEVM vs Ethereum](/core-concepts/filecoin-evm-runtime/difference-with-ethereum) | Key differences for Ethereum developers |
| [How gas works](/core-concepts/filecoin-evm-runtime/how-gas-works) | Filecoin gas model for transaction planning |
| [Support](/build-on-filecoin/developing-contracts/support) | Where to get help |
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/getting-started)
# Filecoin Onchain Cloud
Filecoin Onchain Cloud is a programmable storage, retrieval, and payments stack built on Filecoin, with a warm storage service and a cold storage service.
Filecoin Onchain Cloud (FOC) is a programmable storage platform built on the Filecoin Virtual Machine. It combines storage, cryptographic storage verification, retrieval, and payments into one stack, and offers two storage services:
* **Filecoin Warm Storage Service (FWSS)** for data that applications read often. Providers keep the data unsealed and hot, and prove it with Proof of Data Possession (PDP).
* **Filecoin Cold Storage Service (FCSS)** for archives and large datasets that must be preserved and verifiable but are read rarely. Providers seal the data with Proof of Replication (PoRep) under deals with service-level terms the client sets.
Both services pay storage providers through Filecoin Pay, in USDFC, on on-chain payment rails.
## Choose a service
| | **Warm storage (FWSS)** | **Cold storage (FCSS)** |
| ------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Best for** | Application data, media, agent artifacts, anything read often | Archives, research and enterprise datasets, backups, from 1 TiB up |
| **Proof** | PDP: providers answer random on-chain challenges on the stored data | PoRep and Proof of Spacetime: providers seal a unique replica and prove it every day |
| **Provider matching** | The FWSS contract selects providers from the on-chain registry | The PoRep Market matches each deal to a provider offer that meets the client's terms |
| **Price** | Fixed by the FWSS contract | One service price per TiB per month in the [FCSS client app](https://clients.fcss.fidl.tech/#pricing). Providers set their own offers in the PoRep Market |
| **Terms the client sets** | Number of copies | Duration (6 months or more), price, retrievability, bandwidth, latency, and IPNI indexing |
| **Copies** | One or more, chosen by the client | One or more, chosen by the client |
| **Retrieval** | Hot, over HTTPS, with Filecoin Beam for faster delivery | From the provider's unsealed copy. Free or paid per piece, and public or limited to the client |
| **Start with** | [Synapse SDK](/build-on-filecoin/filecoin-onchain-cloud/synapse-quickstart) | [FCSS](/build-on-filecoin/filecoin-onchain-cloud/fcss) |
If you only need a managed IPFS pinning-style workflow, start with [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin).
## Core components
| Component | Role |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| FWSS | Filecoin Warm Storage Service. Stores data with retrievability-oriented provider selection, proven with PDP. |
| FCSS | Filecoin Cold Storage Service. Stores sealed copies of large datasets under deals with service-level terms, proven with PoRep. |
| PDP | Proof of Data Possession verifies that providers still hold warm data without requiring a full download. |
| PoRep Market | On-chain contracts that match FCSS deals to provider offers, track provider capacity, and gate each deal's payments on its service-level indicators. |
| Filecoin Pay | Payment rails fund storage and settle provider payments based on service delivery, for both services. |
| Filecoin Beam | Retrieval infrastructure for fast delivery of warm data. |
| Synapse SDK | TypeScript SDK for funding warm storage, selecting providers, uploading, downloading, and managing storage operations. |
## Developer paths
| Path | Use when | Start here |
| --------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Synapse SDK | You are building a JavaScript or TypeScript application that stores and retrieves warm data with FOC. | [FOC quickstart and Synapse docs](/build-on-filecoin/filecoin-onchain-cloud/synapse-quickstart) |
| Filecoin Pin | You want a CLI or API path for pinning IPFS-compatible content to Filecoin-backed storage. | [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin) |
| FCSS | You have a dataset of 1 TiB or more to preserve, and want to onboard it with a CLI, a web app, or an AI agent. | [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss) |
| Warm storage provider | You want to sell FWSS storage from your own hardware (≈5 min Docker setup). | [Run a PDP provider](/provide-storage/pdp/install-and-run-pdp) · [Curio-PDP](https://docs.curiostorage.org/getting-started/curio-pdp) |
| Cold storage provider | You run, or plan to run, a PoRep sealing cluster and want FCSS deals. | [Path D of the storage provider quickstart](/provide-storage/agent-quickstart#path-d) |
| Full FOC docs | You need the complete FOC guides, API reference, architecture, pricing, or contract references. | [docs.filecoin.cloud](https://docs.filecoin.cloud/) |
## Learn more
The FOC documentation is the source of truth for detailed warm storage docs, pricing, API references, and contract addresses:
* [FOC quick start](https://docs.filecoin.cloud/getting-started)
* [Architecture](https://docs.filecoin.cloud/core-concepts/architecture)
* [FWSS overview](https://docs.filecoin.cloud/core-concepts/fwss-overview)
* [PDP overview](https://docs.filecoin.cloud/core-concepts/pdp-overview)
* [Filecoin Pay overview](https://docs.filecoin.cloud/core-concepts/filecoin-pay-overview)
* [Synapse SDK guide](https://docs.filecoin.cloud/developer-guides/synapse)
* [Contract addresses](https://docs.filecoin.cloud/resources/contracts)
For cold storage, see [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss), the [PoRep Market contracts](https://github.com/fidlabs/porep-market), and the [PoRep Market CLI](https://github.com/fidlabs/filecoin-porep-market-tooling).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-onchain-cloud)
# Synapse SDK quickstart
Start with the maintained Filecoin Onchain Cloud docs for the current Synapse SDK quickstart, funding, upload, and retrieval steps.
The Synapse SDK is the main developer interface for Filecoin Onchain Cloud (FOC). The current setup steps, SDK APIs, payment behavior, pricing, and contract references live in the dedicated FOC documentation.
To avoid this page drifting from the maintained FOC guides, use it as a routing page instead of a duplicated quickstart.
## Start in the FOC docs
* [FOC getting started](https://docs.filecoin.cloud/getting-started) - install the Synapse SDK, connect a wallet, fund storage, upload data, and retrieve it.
* [Synapse SDK guide](https://docs.filecoin.cloud/developer-guides/synapse) - integrate the SDK into applications and review the current API surface.
* [Storage operations](https://docs.filecoin.cloud/developer-guides/storage/storage-operations) - manage uploads, retrievals, data sets, and storage lifecycle operations.
* [Payment operations](https://docs.filecoin.cloud/developer-guides/payments/payment-operations) - understand deposits, approvals, withdrawals, and payment rails.
* [Contract addresses](https://docs.filecoin.cloud/resources/contracts) - find current mainnet and testnet contract references.
For a CLI-oriented pinning workflow in these docs, use [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-onchain-cloud/synapse-quickstart)
# Filecoin Cold Storage Service
The Filecoin Cold Storage Service (FCSS) preserves large datasets as sealed, verifiable copies with storage providers, under deals with service-level terms that the client sets.
The Filecoin Cold Storage Service (FCSS) is the cold storage service of [Filecoin Onchain Cloud](/build-on-filecoin/filecoin-onchain-cloud), next to the Filecoin Warm Storage Service (FWSS). It gives clients verifiable, off-site preservation for datasets of 1 TiB and up.
Each dataset is stored as sealed copies with separate storage providers. The client sets the terms of each deal: how long the data is kept, the price, and the service levels the provider must meet for retrievability, bandwidth, latency, and IPNI indexing. Providers prove the data with Proof of Replication (PoRep) and Proof of Spacetime, and are paid in USDFC through Filecoin Pay only while they meet those terms.
## When to use FCSS
FCSS is a good fit when you need:
* **Long-term preservation** of a large dataset, such as research data, media archives, or enterprise backups, that is read rarely.
* **Enforceable service levels** written into an on-chain deal, not a vendor's promise.
* **Control over access.** A deal is either public, so anyone can retrieve the data, or private, so only the client and the wallets it authorizes can.
For data that applications read often, use the [Filecoin Warm Storage Service](/build-on-filecoin/filecoin-onchain-cloud#choose-a-service) instead.
## How it works
1. **Prepare the dataset.** [Singularity](https://github.com/data-preservation-programs/singularity) packs the raw files into CAR files. Each CAR file is a piece with a PieceCID. A manifest lists every piece in the dataset.
2. **Publish the pieces.** The client uploads the pieces and the manifest to storage it controls, such as an S3, Cloudflare R2, or Google Cloud Storage bucket, so providers can download them. The client's machine can then go offline.
3. **Propose a deal.** The client proposes a deal on the [PoRep Market](https://github.com/fidlabs/porep-market) with the manifest URL and the deal terms. The market matches the deal to a provider offer that meets those terms and reserves the provider's capacity.
4. **Fund the deal.** Once the deal is matched to providers, the client creates the deal's payment rail in Filecoin Pay, deposits USDFC, and allocates DataCap for the data.
5. **Store and prove.** The provider downloads the pieces, seals them into 32 GiB sectors, and claims the allocations. The deal becomes active, and payments start.
6. **Get paid on service levels.** An oracle records each provider's service-level indicators on chain. When the payment rail settles, the deal's validator pays the provider according to how well it met the deal's terms.
DataCap is how the PoRep Market checks that a deal's data is stored today. When [FIP-0118](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0118.md) retires DataCap, new deals move to its replacement, and existing deals keep the mechanism they started with.
## Tools
FCSS has the same kinds of tools as warm storage, for clients, agents, and providers:
| Tool | What it does |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [PoRep Market CLI](https://github.com/fidlabs/filecoin-porep-market-tooling) | Command-line deal making for clients, and onboarding and offer management for providers |
| [FCSS client app](https://clients.fcss.fidl.tech) | A web app for clients: sign up, review and fund a storage term, follow deal status and storage proofs, and repair a dataset |
| [`fcss-client` agent skill](https://github.com/fidlabs/agent-skills/tree/main/fcss-client) | Takes an AI agent from raw data to active deals: it runs Singularity in Docker, prepares and uploads the dataset, and proposes and funds the deals |
| [Dataset dashboards](https://status.fcss.fidl.tech) | Review each dataset's deals, providers, and storage status |
| SLA dashboards | Track each provider's service levels against the deal terms. Coming soon |
| [Paid retrievals](https://github.com/fidlabs/large-paid-retrievals) | A retrieval client for dataset consumers, and a proxy that lets providers charge per piece through Filecoin Pay |
| Repairs | Moves a dataset to a new provider when its current provider stops delivering. Fully automated once triggered. Trigger it from the client app's dashboard or the PoRep Market CLI |
| [Provider registration](https://peertopool.fidl.tech/) | Provider sign-up with KYC, and the public [directory of FCSS providers](https://peertopool.fidl.tech/directory) |
## Pricing
Through the [FCSS client app](https://clients.fcss.fidl.tech/#pricing), storage costs one price per TiB per month for a term of at least 6 months. Retrieval is billed per TiB retrieved, with one free full-dataset retrieval a year. Storage proofs and heartbeat checks are always free. The client app has two tiers today:
* **Archive** for static data you rarely access.
* **Backup**, which adds continuous heartbeat monitoring and a deal health dashboard.
See the [client app](https://clients.fcss.fidl.tech/#pricing) for current prices.
## Store a dataset
{% hint style="warning" %}
**FCSS runs on Filecoin mainnet.** Proposing a deal, allocating DataCap, and depositing USDFC all spend real FIL and USDFC.
{% endhint %}
You need:
* A dataset of 1 TiB or more.
* A bucket you control that can serve the pieces publicly, such as AWS S3, Cloudflare R2, Google Cloud Storage, or another S3-compatible service.
* A wallet with FIL for gas and USDFC to pay for storage. A Lotus wallet keeps the private key out of the tooling.
{% tabs %}
{% tab title="AI agent" %}
The `fcss-client` skill needs only Docker, Docker Compose, git, Python 3.10 or newer, curl, and jq. It installs Singularity, the PoRep Market CLI, and rclone on its own. Add it to your agent, then ask the agent to archive your dataset on Filecoin:
```sh
npx skills add fidlabs/agent-skills --skill fcss-client
```
The agent prepares and uploads the dataset, shows you the cost of the deals, and proposes them only after you agree. It never asks for your private key: you configure the wallet yourself.
{% endtab %}
{% tab title="CLI" %}
Prepare the dataset with Singularity and publish the pieces and manifest first. Then install the [PoRep Market CLI](https://github.com/fidlabs/filecoin-porep-market-tooling), which needs Python 3.10 or newer:
```sh
git clone https://github.com/fidlabs/filecoin-porep-market-tooling
cd filecoin-porep-market-tooling
python3 -m pip install -r requirements.txt
cp .env.mainnet .env
```
Set your wallet in `.env`, then propose a deal, initialize its payment rail, and allocate DataCap:
```sh
python3 ./porep_tooling_cli.py client propose-deal \
--price-per-tib-per-month --duration-months \
--retrievability-pct --bandwidth-mbps --latency-ms \
--indexing-pct --deal-type
python3 ./porep_tooling_cli.py client init-deal
python3 ./porep_tooling_cli.py client make-allocations
```
Every transaction asks you to confirm before it is sent. `client get-deals` shows whether the market matched your deal; only the `ACTIVE` state means the data is stored.
The CLI's `--price-per-tib-per-month` is the price paid to providers in the PoRep Market. Through the client app you pay the FCSS service price instead.
{% endtab %}
{% tab title="Web app" %}
1. Create an account in the [FCSS client app](https://clients.fcss.fidl.tech/signup), verify your email, and complete identity verification.
2. Prepare your dataset and publish its manifest, following the app's data preparation guide.
3. Review the size and price of your storage term, then approve the deal from your wallet.
4. Follow deal status and storage proofs from your dashboard for the life of the term.
{% endtab %}
{% endtabs %}
## Retrieve a dataset
Providers serve FCSS data from an unsealed copy over HTTP, one piece at a time. A piece can be free or paid:
* A free piece downloads directly.
* A paid piece returns `402 Payment Required` with a price in USDFC. The client pays once per piece through Filecoin Pay, then downloads it.
[`retrieval-client`](https://github.com/fidlabs/large-paid-retrievals#for-dataset-consumers) finds the providers that store each piece, compares their prices, pays when needed, and downloads the CAR files. Repeat `--cid` for several pieces:
```sh
retrieval-client fetch --filpay-private-key-file ./client.key --cid --out-dir ./downloads
```
Add `--dry-run` to see the prices without paying. Anyone can retrieve a public deal's data. Only the client can retrieve a private deal's data, unless it signs a retrieval voucher for another wallet with `client sign-retrieval-voucher`.
## Monitor and repair
* **Deals and datasets.** The client app's dashboard, the [dataset dashboards](https://status.fcss.fidl.tech), or `client get-deals` in the CLI show each deal's state, providers, and storage proofs.
* **Service levels.** Each deal's payments already depend on the provider's service levels. SLA dashboards that show them over time are coming soon.
* **Repairs.** If a provider stops delivering, a repair moves the dataset to a new provider. Trigger it from the client app's dashboard or the PoRep Market CLI. Once triggered, the repair runs automatically.
## Provide cold storage
FCSS deals are sealed PoRep deals, so FCSS providers run a PoRep sealing cluster. See [Path D of the storage provider quickstart](/provide-storage/agent-quickstart#path-d) to register, publish offers, and take FCSS deals.
## Learn more
* [PoRep Market contracts](https://github.com/fidlabs/porep-market): deal lifecycle, provider registry, and payment validation
* [PoRep Market CLI](https://github.com/fidlabs/filecoin-porep-market-tooling): client and provider workflows
* [`fcss-client` skill](https://github.com/fidlabs/agent-skills/tree/main/fcss-client)
* [Paid retrievals](https://github.com/fidlabs/large-paid-retrievals): protocol, pricing, and the provider proxy
* [Singularity](https://github.com/data-preservation-programs/singularity): data preparation
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-onchain-cloud/fcss)
# Filecoin for Agents
The filecoin CLI, agent plugin, and read-only MCP server let AI agents store files and folders on Filecoin and return links they can share.
`filecoin` stores files and folders on Filecoin and returns links you can share. People run it in a terminal, and agents run it in a shell. Every command writes one JSON result that an agent can act on.
{% hint style="warning" %}
**Prototype.** `filecoin` and its services are a proof of concept. They run on the Calibration testnet unless you choose mainnet. The source is in [filecoin-project/agents](https://github.com/filecoin-project/agents).
{% endhint %}
To pin IPFS content instead, use Filecoin Pin and its `publish` skill, described in [Filecoin for Agents](/core-concepts/filecoin-for-agents) in Core Concepts, along with why agents use Filecoin at all.
## Ways to use it
| Tool | What it does | Docs |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| CLI | `filecoin put ./site` stores a folder and returns a browser link. `filecoin get` downloads and verifies it. | [CLI](/build-on-filecoin/filecoin-for-agents/cli) |
| Agent plugin and skill | Teaches Claude Code, Codex, and other agents when and how to run `filecoin`. | [Connect an agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent) |
| MCP server | Read-only tools for storage providers, data sets, pieces, payment rails, and session keys. | [API and MCP](/build-on-filecoin/filecoin-for-agents/api-and-mcp) |
| Console and explorer | The filecoin-app dashboard, where the wallet owner approves keys and funds storage, and PDP Explorer for looking up stored data. | [Console and explorer](/build-on-filecoin/filecoin-for-agents/console-and-explorer) |
## How an agent gets access
The agent never holds the wallet key. It gets a session key, which the wallet owner approves in the filecoin-app dashboard and which cannot move funds. [Connect an agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent) shows the way in for each kind of agent: local, cloud, browser, or chat app.
## Start
* [Quickstart](/build-on-filecoin/filecoin-for-agents/quickstart): install the CLI, log in, and store a file.
* [Connect an agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent): add `filecoin` to Claude, ChatGPT, or another agent.
* [Retrieve and verify](/build-on-filecoin/filecoin-for-agents/retrieve-and-verify): what each retrieval link checks.
* [Source code](https://github.com/filecoin-project/agents) on GitHub.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-for-agents)
# Quickstart
Install the filecoin CLI, log in with a session key, store a file, and download it again on the Calibration testnet.
This guide installs `filecoin`, logs in, stores a file, and downloads it again. It uses the Calibration testnet, so storage is paid with test USDFC.
You need:
* Node.js 24 or newer.
* A browser wallet, such as [MetaMask](/networks-and-tools/assets/metamask-setup), with Calibration tFIL for gas and test USDFC. See [Get test tokens](/build-on-filecoin/developing-contracts/get-test-tokens).
## Hand it to an agent
Add `filecoin` to your agent, then ask it to store a file. On its first run, the agent sends you a link to approve its key with your wallet. [Connect an agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent) covers cloud and browser agents.
{% tabs %}
{% tab title="Plugin" %}
Adds the agent skill and the read-only MCP server to Claude Code or Codex.
```sh
claude plugin marketplace add filecoin-project/agents
claude plugin install filecoin@filecoin
# In Codex
codex plugin marketplace add filecoin-project/agents
codex plugin add filecoin@filecoin
```
{% endtab %}
{% tab title="Agent skill" %}
Teaches any agent with a shell when and how to run `filecoin`.
```sh
npx skills add filecoin-project/agents
```
{% endtab %}
{% tab title="MCP server" %}
Read-only tools for providers, data sets, and pieces. It cannot store files.
```sh
npx -y add-mcp https://mcp.filecoin.io -g
```
{% endtab %}
{% endtabs %}
To do it yourself, follow the steps below.
## Install the CLI
```sh
npm install -g filecoin
filecoin --help
```
## Log in
```sh
filecoin login
```
`filecoin login` makes a session key, saves it on your machine, and opens the filecoin-app dashboard's setup page at `poc.filecoin.cloud` with the key filled in. Connect your wallet there, review the request, and approve it. The private key never leaves your machine, and the CLI finds the approval on chain, so there is nothing to copy back.
Then check the account:
```sh
filecoin status
```
`filecoin status` reports when each permission expires, your USDFC funds, and the Warm Storage approval. If the account needs a deposit, it also returns a funding link to the same setup page, where you deposit USDFC and, if you haven't yet, approve the Warm Storage service. Each is its own wallet transaction.
## Store a file
Check the size, provider, and cost first. A dry run stores nothing:
```sh
filecoin put ./report.pdf --dry-run
```
Then store it:
```sh
filecoin put ./report.pdf
```
The result's `urls.browser` is the link to share. A new link to a file can return `404` for a while. [Retrieve and verify](/build-on-filecoin/filecoin-for-agents/retrieve-and-verify) explains why, and what each link checks.
## Get it back
```sh
filecoin ls
filecoin get res_… --output ./copy.pdf
```
`filecoin get` downloads from the provider and checks the bytes against the PieceCID.
## Next
* [CLI](/build-on-filecoin/filecoin-for-agents/cli) explains how `filecoin` works and where its help and schemas are.
* [Connect an agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent) shows how to give an agent the same access.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-for-agents/quickstart)
# Connect an agent
Give a local, cloud, browser, or chat agent access to Filecoin storage through the filecoin plugin, agent skill, CLI, or MCP server.
Pick the way in that matches what your agent can do. In every case, a person owns the wallet and approves what the agent may do, and the agent never holds the wallet key.
| Agent | What it can do | Way in |
| ------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
| Local agent, such as Claude Code, Codex, or Cursor | Run a shell, keep files, and open pages for you | [Plugin, or CLI and agent skill](#local-agents) |
| Cloud agent, such as a coding agent in a hosted sandbox | Run a shell, but its files are gone when the session ends | [CLI with a key from secrets](#cloud-agents) |
| Browser agent | Read and use web pages in the browser that holds your wallet | [Dashboard links and PDP Explorer](#browser-agents), read-only |
| Chat app with connectors, such as Claude or ChatGPT | Call remote tools | [MCP server](#mcp-server), read-only |
[Retrieve and verify](/build-on-filecoin/filecoin-for-agents/retrieve-and-verify) compares what each way can store, retrieve, and check.
## Local agents
In Claude Code and Codex, install the filecoin plugin. It adds the agent skill and the read-only [MCP server](#mcp-server) in one step.
{% tabs %}
{% tab title="Claude Code" %}
```sh
claude plugin marketplace add filecoin-project/agents
claude plugin install filecoin@filecoin
```
{% endtab %}
{% tab title="Codex" %}
```sh
codex plugin marketplace add filecoin-project/agents
codex plugin add filecoin@filecoin
```
{% endtab %}
{% endtabs %}
The plugin follows the [Agent Plugins](https://agent-plugins.org) format, so other agents that support it can load it from the repository's [`plugins/filecoin`](https://github.com/filecoin-project/agents/tree/main/plugins/filecoin) directory.
In other agents, install the agent skill. It tells the agent when to use `filecoin`, the workflow, and the rules, and points it to the CLI's own help, which always matches the installed version:
```sh
npx skills add filecoin-project/agents
```
The agent runs the CLI with `npx -y filecoin`, which needs Node.js 24 or newer. To install it instead, run `npm install -g filecoin`. Then `filecoin skills install` installs the copy of the skill that matches the installed CLI.
The first `filecoin login` asks you to [approve the agent's key](#approve-the-agents-key).
## Cloud agents
A cloud agent has a shell, so it uses the same skill and CLI as a local agent. It has no browser to open for you, and its disk is gone when the session ends. `filecoin login` saves the session key on that disk, so each session would ask you to approve a new key.
Give the agent a key that outlives the session instead:
1. On the filecoin-app dashboard's [Session keys page](https://poc.filecoin.cloud/dashboard/session-keys), generate a session key, authorize it with at least `createDataSet` and `addPieces`, and copy its private key with **Export key**.
2. In the agent's environment settings, add the session key's private key as the secret `FILECOIN_SESSION_KEY`, and your wallet address as `FILECOIN_ROOT_ADDRESS`.
`filecoin` then skips `filecoin login`, and `filecoin status` confirms the key works. The key cannot move funds, and it expires. Revoke it on the same page to stop the agent.
{% hint style="danger" %}
Never paste the session key into a chat. Store it only as a secret in the agent's environment.
{% endhint %}
`filecoin ls` and `filecoin operations` read a local database, which a new session starts without. [Find stored content](/build-on-filecoin/filecoin-for-agents/retrieve-and-verify#find-stored-content) shows how to look it up by wallet.
## Browser agents
A browser agent cannot run the CLI, so it cannot store content. It can open the [dashboard links](/build-on-filecoin/filecoin-for-agents/console-and-explorer#links-from-the-cli) a wallet owner needs, look up data sets, providers, and pieces on [PDP Explorer](https://pdp.filecoin.cloud), and open a folder's link, which verifies in the browser.
## MCP server
The MCP server gives any agent read-only tools for storage providers, data sets, pieces, Filecoin Pay rails, and session keys, on mainnet and Calibration. It uses Streamable HTTP and needs no authentication. It cannot store or delete content.
```
https://mcp.filecoin.io
```
The [filecoin plugin](#local-agents) adds it in Claude Code and Codex. To add the server alone, [add-mcp](https://github.com/neon-solutions/add-mcp) writes it into the configuration of Claude Code, Codex, Cursor, VS Code, and about 20 other agents:
```sh
npx -y add-mcp https://mcp.filecoin.io
```
It asks which agents to configure, and adds the server to the current project. Add `-g` to add it for your user instead.
Claude Code and Codex also add it with their own commands:
```sh
claude mcp add --transport http filecoin-api https://mcp.filecoin.io
codex mcp add filecoin-api --url https://mcp.filecoin.io
```
In the Claude and ChatGPT apps, add the URL as a custom connector. [API and MCP](/build-on-filecoin/filecoin-for-agents/api-and-mcp#mcp-server) lists the tools.
## Approve the agent's key
The agent never holds the wallet key. It gets a session key instead, and the wallet owner approves it:
1. The agent runs `filecoin login`. It gets a `login_pending` error with an approval link, and relays the link to you.
2. You open the link, which goes to the filecoin-app dashboard's setup page with the key filled in. Connect your wallet, review the request, and approve it.
3. The agent runs `filecoin login --check` to confirm. `--check` never makes a new key, so it can't replace the one you approved.
4. If the account has no funds yet, the agent relays a funding link. It opens the same setup page, where you deposit USDFC and, if you haven't yet, approve the Warm Storage service, each as its own wallet transaction.
When the account runs low, `filecoin status` reports `ready: false` with the same funding link, and `filecoin put` fails with `insufficient_funds` and that link. To stop the agent, revoke its key on the dashboard's [Session keys page](https://poc.filecoin.cloud/dashboard/session-keys).
## Docs for agents
These docs are published in formats agents can read directly:
| Path | Contents |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](https://docs.filecoin.io/llms.txt) | An index of every page on docs.filecoin.io in Markdown, from [llmstxt.org](https://llmstxt.org) |
| [`/llms-full.txt`](https://docs.filecoin.io/llms-full.txt) | Every page in one Markdown file |
| [`/sitemap.xml`](https://docs.filecoin.io/sitemap.xml) | Every page |
| `https://docs.filecoin.io/~gitbook/mcp` | An MCP server that searches and reads these docs, described at [`/.well-known/mcp/server-card.json`](https://docs.filecoin.io/.well-known/mcp/server-card.json). This is separate from the read-only [Filecoin MCP server](#mcp-server) |
Every page also has a Markdown version. Add `.md` to the path, such as [`/build-on-filecoin/filecoin-for-agents/cli.md`](https://docs.filecoin.io/build-on-filecoin/filecoin-for-agents/cli.md), or send `Accept: text/markdown`.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-for-agents/connect-an-agent)
# CLI
How the filecoin CLI logs in, stores and retrieves content, resumes interrupted operations, and reports results and errors.
`filecoin` stores a file or a folder as one copy on one storage provider and returns retrieval links. It runs on the Calibration testnet unless you choose mainnet. It needs Node.js 24 or newer:
```sh
npm install -g filecoin
```
Or run it without installing, as `npx -y filecoin`.
This page explains how `filecoin` works. The CLI describes its own commands, which always match the installed version:
* `filecoin --help` lists the commands, and `filecoin --help` shows examples and flags.
* `filecoin schema ` prints the command's input and output as JSON Schema, and what each error code means. `filecoin schema --list` lists every command with its side effects.
## Log in
```sh
filecoin login
```
`filecoin login` makes a session key and saves it on your machine. It then opens the setup page of the [filecoin-app dashboard](/build-on-filecoin/filecoin-for-agents/console-and-explorer) with the key's address and permissions filled in. The wallet owner reviews the request there and approves it with their wallet. The CLI finds the approval on chain, so there is nothing to copy back.
By default, `filecoin login` asks for the `createDataSet`, `addPieces`, and `schedulePieceRemovals` permissions. Repeat `--scopes` to ask for others.
The session key signs each request, the provider submits the transactions, and the wallet pays for storage.
In a terminal, `filecoin login` opens the browser and waits for approval, for up to 10 minutes by default (`--timeout`). If the wait runs out, it returns `login_pending` like a non-interactive run. An agent, or any run without a terminal, gets a `login_pending` error instead and never waits. The error's `next` steps are the approval link for the user and `filecoin login --check` for the agent to run after the user approves. `--check` only confirms the saved key and never makes a new one.
Running `filecoin login` again never changes a saved key's request: flags you leave out keep its scopes. An interrupted login resumes with the same key, and an approved key is reused when it has the requested permissions. `filecoin login` replaces a saved key on its own only when the key has expired. If `--scopes` asks for more than a pending or valid key has, you get a `session_conflict` error and the key stays, because the owner may already have approved it. Pass `--fresh` to replace it.
For CI or a [cloud agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent#cloud-agents), set `FILECOIN_SESSION_KEY` and `FILECOIN_ROOT_ADDRESS` instead of running `filecoin login`.
## Check the account
The session key cannot fund the account. `filecoin status` reports when each permission expires, the USDFC funds, and the Warm Storage approval. When the account needs a deposit, it also returns a prefilled funding link to the dashboard's setup page.
`filecoin doctor` shows the network, RPC, console and API origins, and state directory that `filecoin` uses, with where each value came from.
## Store and retrieve
```sh
filecoin put ./report.pdf # a file, stored as its exact bytes
filecoin put ./site # a folder, packed into a UnixFS CAR
filecoin put ./site --dry-run # size, provider, cost, and authorization; stores nothing
filecoin publish ./site # same as put
filecoin get res_… --output ./copy # verifies the PieceCID and extracts folders
filecoin ls # add --all to include content pending removal
filecoin inspect res_… --check # checks that the piece link answers
filecoin delete res_… --yes # same as rm; schedules removal
```
`put` returns `urls.browser`, the link to share, and `urls.piece`, the exact stored bytes. [Retrieve and verify](/build-on-filecoin/filecoin-for-agents/retrieve-and-verify) explains what each link and `filecoin get` check.
Packing skips dotfiles and rejects symlinks. The file, or the packed folder, must be between 127 bytes and 68,182,605,824 bytes (63.5 GiB).
`delete` schedules removal, and the provider then deletes the stored copy. The content's state becomes `removal_pending`. Without `--yes`, `delete` asks a person at a terminal to confirm. Everyone else, including agents, gets `confirmation_required` with a step for the user.
## Resume an interrupted put or delete
```sh
filecoin operations ls --incomplete
filecoin operations inspect op_…
filecoin operations resume op_…
```
Each `put` and `delete` saves an operation before it changes anything, and prints its ID to stderr at once. An error from a put or a delete carries a `filecoin operations resume ` step. Run that step instead of the original command, which would start a new paid operation.
A resumed put never stores or pays twice:
* It skips the upload when the provider already has the piece.
* It checks on chain whether the commit landed before it sends it again.
* It fails with `source_changed` when the source file changed.
* It returns the saved result of an operation that already completed.
Ctrl+C stops the work at the next step and returns an `interrupted` result with the resume step. The process then exits by the signal, not with code `1`.
## Output and errors
When an agent runs `filecoin`, or when you pass `--json` or redirect stdout, `filecoin` writes one JSON object to stdout: `data` on success or `error` on failure, then optional `next` steps. The exit code is `0` with `data` and `1` with `error`. Progress goes to stderr.
Each error has a stable `code`, and `filecoin schema ` lists the codes the command returns and what they mean. Errors that need a person, such as `login_pending` and `insufficient_funds`, carry a `next` step with a dashboard link for the user.
## Configuration
| Variable | Purpose |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `FILECOIN_NETWORK` | `mainnet` or `calibration`. `--network` wins, then `FILECOIN_NETWORK`, then the config file, then `calibration` |
| `FILECOIN_SESSION_KEY`, `FILECOIN_ROOT_ADDRESS` | Session key and wallet address, used instead of `filecoin login` |
| `FILECOIN_CONFIG_DIR` | Config directory. Default: the platform config directory for `filecoin` |
| `FILECOIN_STATE_DIR` | Local state and staged folders. Default: the platform data directory for `filecoin` |
| `FILECOIN_RPC_URL` | RPC endpoint |
| `FILECOIN_CONSOLE_URL` | Dashboard origin for approval and funding links. Default: `https://poc.filecoin.cloud` |
| `FILECOIN_API_URL` | API origin for retrieval links. Default: `https://api.filecoin.io` |
| `FIL_OUTPUT`, `FIL_AGENT` | Override the output mode (`json` or `human`) and agent detection (`1`, `0`, `true`, or `false`). `--json` and `--format` win over `FIL_OUTPUT` |
The prototype saves the session key in the config file, readable only by its owner. `filecoin logout` deletes the local key. The key stays authorized on chain until it expires or you revoke it on the dashboard's [Session keys page](https://poc.filecoin.cloud/dashboard/session-keys).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-for-agents/cli)
# Retrieve and verify
The links filecoin put returns, what each retrieval path verifies, and how to find stored content by wallet.
Everything `filecoin` stores has a PieceCID, and a folder also has a root CID:
* The **PieceCID** (`bafkzcib…`) identifies the exact stored bytes. The storage provider proves on chain that it still holds them.
* The **root CID** identifies a folder on IPFS. `filecoin` packs a folder into a UnixFS CAR, and the PieceCID covers that CAR.
`filecoin put` returns two links on the API's [`/get/{cid}` route](/build-on-filecoin/filecoin-for-agents/api-and-mcp#retrieval), which redirects to a provider that stores the content:
* `urls.browser` is the link to share. A browser renders a file straight from the provider, and opens a folder through [inbrowser.link](https://inbrowser.link).
* `urls.piece` returns the exact stored bytes.
The API finds providers through its indexer, so a new piece link returns `404` until the indexer has the piece. `filecoin inspect --check` reports when the piece link answers.
While the commit confirms, `filecoin put` prints an early browser link to stderr. When an agent runs it, or stderr is not a terminal, the line reads `filecoin: link: `. In a terminal, it shows as `link: ` on the status line:
* **A file's early link** works as soon as the provider has the piece. It names the provider, so the API can redirect before its indexer catches up.
* **A folder's early link** comes once the commit is sent. It starts working shortly after, when the provider has indexed the folder and announced it to IPFS.
## What each way checks
| Way | Who can use it | Gets | Checks |
| ---------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `filecoin get ` | Agents with a shell, and people | A file, or the folder, extracted | The bytes against the PieceCID, and for a folder the root CID. On a mismatch it keeps nothing and fails with `verification_failed` |
| `filecoin get ` | Agents with a shell, and people | When the PieceCID has no matching local resource record, it returns stored bytes as one file. For a folder, that is the CAR. If the CLI already knows the piece represents a folder, it extracts the folder even when called with its PieceCID. | The bytes against the PieceCID |
| A folder's `urls.browser` | Browser agents, and people | The folder, rendered | Each block, in the browser |
| A file's `urls.browser`, or `urls.piece` | Anything that speaks HTTP | The bytes | Nothing |
Use `filecoin get` when the content must be intact. When you hand over a link that checks nothing, say so.
## Find stored content
`filecoin ls` lists what this machine stored. The list lives in a local database, so a new machine, or a cloud sandbox that was reset, starts empty. The content is still on Filecoin, under the wallet that paid for it:
* Over MCP, `list_pieces` with the wallet as `owner`. Over HTTP, `GET /{network}/pieces?owner=` on the API.
* In a browser, [PDP Explorer](https://pdp.filecoin.cloud) looks up a data set ID, provider ID, or PieceCID that you already have.
Each piece comes with a retrieval link. `filecoin get ` downloads and checks one with the same wallet's session key.
## Store without the CLI
The MCP server and the REST API cannot store anything. To store content, use the CLI, or build on the [Synapse SDK](/build-on-filecoin/filecoin-onchain-cloud/synapse-quickstart).
For more on how retrieval works on Filecoin, see [How retrieval works](/getting-started/how-retrieval-works).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-for-agents/retrieve-and-verify)
# API and MCP
A read-only REST API and MCP server for Filecoin storage providers, data sets, pieces, Filecoin Pay rails, and session keys.
The [API](https://api.filecoin.io) serves read-only Filecoin data: storage providers, data sets, pieces, Filecoin Pay rails, and session keys. It reads from an indexer of the Filecoin chain, so its data trails the chain. `/health` reports the latest indexed block. It cannot store, delete, or sign anything.
The interactive reference is at [`/docs`](https://api.filecoin.io/docs), and the OpenAPI 3.1 document is at [`/openapi.json`](https://api.filecoin.io/openapi.json).
## Routes
`GET /openapi.json` lists every route and its filters. The [MCP server](#mcp-server) has its own host, `https://mcp.filecoin.io`. `GET /health` reports the latest indexed block per network, and [`GET /get/{cid}`](#retrieval) redirects to where content can be retrieved. Every data route starts with the network, `/calibration/...` or `/mainnet/...`, and reads one of: indexer status, storage providers, data sets and their pieces, pieces by owner or PieceCID, Filecoin Pay rails and their settlements, and session keys and their history.
Conventions:
* **Owner** is the address that pays for a data set.
* **Big numbers**, such as IDs, amounts, and epochs, are decimal strings.
* **Pagination** uses `limit` (1 to 200, default 50) and an opaque `cursor`. Each response looks like `{ data, nextCursor }`.
* **Errors** look like `{ error: { code, message } }`.
* **Operation IDs**, such as `listDataSets` and `retrieve`, name every operation in the OpenAPI document, for function calling and generated clients.
## Retrieval
`GET /get/{cid}?network=mainnet&browser=false` redirects to where the content can be fetched. It never proxies the bytes. `network` defaults to `mainnet`.
| CID | `browser` | Redirect |
| ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
| PieceCID v2 (`bafkzcib…`) | `false` or absent | The provider's `/piece/{cid}` |
| PieceCID v2 (`bafkzcib…`) | `true` | `https://inbrowser.link/ipfs/{root}` when the piece is a folder, otherwise the provider's `/piece/{cid}` |
| Other CID (IPFS content) | `false` or absent | The provider's `/ipfs/{cid}` |
| Other CID (IPFS content) | `true` | `https://inbrowser.link/ipfs/{cid}` |
`provider={id}` names a provider to redirect to when the indexer has no copy yet. It covers the time between a provider receiving a piece and the indexer seeing the commit. An indexed copy always wins over it. `filecoin put` adds it to the early links it prints before the commit confirms.
Legacy v1 PieceCIDs (`baga…`) and strings that aren't CIDs return `400`. If no live copy exists and no `provider` applies, the response is `404`. When several providers store the content, the route prefers endorsed providers, then approved ones, then the oldest copy.
## MCP server
The MCP server at `https://mcp.filecoin.io` offers one read-only tool for each data route, and each of those requires a `network` argument. A further tool, `search_docs`, searches these docs.
| Tool | Reads |
| -------------------------------------------------- | -------------------------------------------------------------------------- |
| `get_status` | Indexer progress |
| `list_providers`, `get_provider` | Storage providers |
| `list_data_sets`, `get_data_set` | Data sets |
| `list_data_set_pieces`, `get_piece`, `list_pieces` | Pieces |
| `list_rails`, `get_rail`, `list_rail_settlements` | Filecoin Pay rails and settlements |
| `list_session_keys`, `list_session_key_events` | Session keys and their history |
| `search_docs` | Pages on docs.filecoin.io that match a query. Takes `query`, not `network` |
[Connect an agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent#mcp-server) shows how to add it to an agent.
## Limits
* **Rate limits.** 120 requests a minute per IP for the REST API, and 60 for MCP. Over the limit, requests get `429` with `Retry-After`.
* **Caching.** Data reads are not cached by browsers, so every read returns the latest indexed data.
* **No authentication.** Every route is public and read-only.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-for-agents/api-and-mcp)
# Console and explorer
The filecoin-app dashboard, where wallet owners approve agent session keys and fund storage, and PDP Explorer, where anyone can look up stored data.
`filecoin` relies on two web apps:
* **The filecoin-app dashboard** at [poc.filecoin.cloud/dashboard](https://poc.filecoin.cloud/dashboard). The wallet owner connects their wallet there to approve session keys, deposit USDFC, approve the Warm Storage service, and revoke keys. While `filecoin` is a prototype, it uses this app instead of the [Filecoin Pay console](https://pay.filecoin.cloud/console).
* **PDP Explorer** at [pdp.filecoin.cloud](https://pdp.filecoin.cloud). Public pages for storage providers, data sets, and pieces on mainnet and Calibration. Search by data set ID, provider ID, or PieceCID.
## Session keys
A session key lets a tool sign storage requests for your wallet. It can create data sets, add pieces, schedule piece removals, and end service, but it can never move funds.
The dashboard's [Session keys page](https://poc.filecoin.cloud/dashboard/session-keys) lists every key your wallet authorized, with when each permission expires. Revoke a key there to stop the tool that holds it. You can also generate a key there, authorize it, and copy its private key with **Export key**, which is how a [cloud agent](/build-on-filecoin/filecoin-for-agents/connect-an-agent#cloud-agents) gets a key.
Keys made by `filecoin login` stay on the agent's machine. The dashboard only approves them.
## Links from the CLI
When `filecoin` needs the wallet owner, it returns a link to the dashboard's setup page with the request filled in. You review it, change anything you need, connect your wallet, and approve each step. Each step is its own wallet transaction, so nothing is signed until you confirm it in your wallet.
| Link | Opens | Sent by |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `/dashboard/setup?network=&signer=&name=&scopes=&days=` | The setup page, ready to authorize the session key `` for the listed scopes | `filecoin login` |
| `/dashboard/setup?network=&deposit=` | The setup page, ready to deposit ``, with a step to approve the Warm Storage service when the wallet hasn't yet | `filecoin status` and `filecoin put` when the account needs funds |
`scopes` is a comma-separated list of `createDataSet`, `addPieces`, `schedulePieceRemovals`, and `terminateService`. `network` is `mainnet` or `calibration`. When the connected wallet is on the other network, the page asks you to switch before you can review the request, so an approval for Calibration is never granted on mainnet by mistake.
`filecoin logout` only deletes the key on your machine. To revoke the key on chain, use the [Session keys page](https://poc.filecoin.cloud/dashboard/session-keys).
{% hint style="info" %}
The dashboard is a prototype and interacts directly with the Filecoin Pay and Warm Storage contracts. Check the details in your wallet before you confirm a transaction.
{% endhint %}
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/filecoin-for-agents/console-and-explorer)
# Development Frameworks
Supported development frameworks for building and deploying smart contracts on Filecoin.
Filecoin supports popular Ethereum development frameworks for writing, testing, and deploying smart contracts. Choose the framework that fits your workflow.
## Table of contents
* [Remix](/build-on-filecoin/development-frameworks/remix) — browser-based IDE for writing and deploying contracts without local setup
* [Hardhat](/build-on-filecoin/development-frameworks/hardhat) — JavaScript framework with the FEVM Hardhat Kit for local development and testing
* [Foundry](/build-on-filecoin/development-frameworks/foundry) — fast Rust-based toolkit for contract development, testing, and deployment
# Remix
The Filecoin EVM runtime allows developers to use Ethereum tooling, like Remix, with the Filecoin network.
## Launch an ERC-20 token
As a simple introduction, we’re going to use Remix to create an ERC-20 token on the Filecoin network. In this guide, we’re using the Calibration testnet, but this process is the same for mainnet.
This guide assumes you’ve already connected your [MetaMask extension to a Filecoin network](/networks-and-tools/assets/metamask-setup).
### Create a workspace
In Remix, workspaces are where you can create a contract, or group of contracts, for each project. Let’s create a new workspace to create our new ERC-20 token.
1. Open [remix.ethereum.org](https://remix.ethereum.org).
2. Click the `+` icon next to **Workspaces** to create a new workspace.
3. In the **Choose a template** dropdown, select **ERC20**.
4. Select the **Mintable** checkbox.
5. Enter a fun name for your token in the **Workspace name** field. Something like `CorgiCoin` works fine.
6. Click **OK** to create your new workspace.
### Customize the contract
The contract template we’re using is pretty simple. We just need to modify a couple of variables.
1. Under the **contract** directory, click **MyToken.sol**.
2. In the editor panel, replace `MyToken` with whatever you’d like to name your token. In this example, we’ll use `CorgiCoin`.
3. On the same line, replace the second string with whatever you want the symbol of your token to be. In this example, we’ll use `CRG`
That’s all we need to change within this contract. You can see on line 4 that this contract is importing another contract from `@openzeppelin` for us, meaning that we can keep our custom token contract simple.
### Compile
1. Click the green play symbol at the top of the workspace to compile your contract. You can also press `CMD` + `s` on MacOS or `CTRL` + `s` on Linux and Windows.
2. Remix automatically fetches the two `import` contracts from the top of our `.sol` contract. You can see these imported contracts under the `.deps` directory. You can browse the contracts there, but Remix will not save any changes you make.
### Deploy
Now that we’ve successfully compiled our contract, we need to deploy it somewhere! This is where our previous MetaMask setup comes into play.
1. Click the **Deploy** tab from the left.
2. Under the **Environment** dropdown, select **Injected Provider - MetaMask**.
3. MetaMask will open a new window confirming that you want to connect your account to Remix.
4. Click **Next**:
5. Click **Connect** to connect your `tFIL` account to Remix.
6. Back in Remix, under the **Account** field, you’ll see that it says something like `0x11F... (5 ether)`. This value is 5 `tFIL`, but Remix doesn’t support the Filecoin network, so it doesn’t understand what `tFIL` is. This isn’t a problem; it’s just a little quirk of using Remix.
7. Under the **Contract** dropdown, ensure the contract you created is selected.
8. Click **Deploy**.
9. MetaMask will open a window and ask you to confirm the transaction. Scroll down and click **Confirm** to have MetaMask deploy the contract. If you’re deploying to mainnet, we advise you to [adjust your gas fees](#adjusting-your-gas-fees) for a cheaper deployment.
10. Back in Remix, a message at the bottom of the screen shows that the creation of your token is pending.
11. Wait around 90 seconds for the deployment to complete.
On the Filecoin network, a new set of blocks, also called a tipset, is created every thirty seconds. When deploying a contract, the transaction needs to be received by the network, and then the network needs to confirm the contract. This process takes around one to two tipsets to process – or around 60 to 90 seconds.
## Use your contract
Now that we’ve compiled and deployed the contract, it’s time to actually interact with it!
### Mint your tokens
Let’s call a method within the deployed contract to mint some tokens.
1. Back in Remix, open the **Deployed Contracts** dropdown, within the **Deploy** sidebar tab.
2. Expand the `mint` method. You must fill in two fields here: `to` and `amount`.
3. The `to` field specifies which address you want these initial tokens sent to. Open MetaMask, copy your address, and paste it into this field.
4. The `amount` field expects the token’s smallest unit, not a `FIL` amount. The OpenZeppelin ERC-20 template uses 18 decimals by default, so minting `100` whole tokens means entering `100` followed by 18 zeros: `100000000000000000000`.
5. Click **Transact**.
6. MetaMask will open a window and ask you to confirm the transaction:
Again, you must wait for the network to process the transaction, which should take about 90 seconds. You can move on to the next section while you’re waiting.
### Add to MetaMask
Currently, MetaMask has no idea what our token is or what it even does. We can fix this by explicitly telling MetaMask the address of our contract.
1. Go back to Remix and open the **Deploy** sidebar tab.
2. Under **Deployed Contracts**, you should see your contract address at the top. Click the copy icon to copy the address to your clipboard.
3. Open MetaMask, select **Assets**, and click **Import your tokens.**
4. In the **Token contract address** field, paste the contract address you just copied from Remix and then click **Add custom token**. MetaMask should autofill the rest of the information based on what it can find from the Filecoin network.
5. Click **Import token**:
6. You should now be able to see that you have 100 of your tokens within your MetaMask wallet!
And that’s it! Deploying an ERC-20 token on Filecoin is simple!
### Adjusting your gas fees
Remix uses a default of 2.5 nanoFIL per gas as a priority fee, which is usually too high for the Filecoin network. If you don’t adjust this, you may end up overpaying when deploying to mainnet. We recommend that you switch from the site-suggested gas fees to oracle-supplied gas fees when deploying your contract.
1. When the deployment transaction confirmation pop-up window shows up, click on **Site suggested**.
2. Switch to **Market**, **Aggressive**, or **Low**. The **Market** option is generally suitable for most situations.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/development-frameworks/remix)
# Hardhat
Hardhat is an open-source development environment designed to provide developers with a flexible and extensible framework for building, testing, and deploying smart contracts.
While originally created for the Ethereum blockchain, the Filecoin Ethereum Virtual Machine runtime (FEVM) allows Hardhat to be used to develop and deploy smart contracts on the Filecoin network.
## Quickstart
The [FEVM Hardhat kit](https://github.com/filecoin-project/FEVM-Hardhat-Kit) is a starter hardhat project for developing, deploying, and testing Solidity smart contracts on the Filecoin network. It functions in the same way as other Hardhat development kits. Check out the quickstart below to test it out!
### Prerequisites
This guide assumes you have the following installed:
* [Git](https://git-scm.com/)
* [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/)
* A Filecoin address stored in [MetaMask](/networks-and-tools/assets/metamask-setup)
* Calibration testnet `tFIL` or mainnet `FIL` for the account you will deploy from
### Environment setup
First, we need to grab the starter kit and install the dependencies.
1. Clone the Hardhat starter kit and move into the new `fevm-hardhat-kit` directory:
```shell
git clone --recurse-submodules https://github.com/filecoin-project/fevm-hardhat-kit.git
cd fevm-hardhat-kit
```
2. Use Yarn to install the project’s dependencies:
```shell
yarn install
```
3. Create your `.env` file and replace the placeholder private key:
```shell
cp .env.example .env
```
```shell
PRIVATE_KEY=your_private_key_here
```
{% hint style="info" %}
Always be careful when dealing with your private key. Double-check that you’re not hardcoding it anywhere or committing it to Git. Remember: anyone with access to your private key has complete control over your funds.
{% endhint %}
4. Get the addresses associated with the private key from Hardhat:
```shell
yarn hardhat get-address
```
The command output is environment-dependent. It prints the Ethereum-style `0x` address and the Filecoin `f4` address for the private key in `.env`. Use the Ethereum-style address with the Calibration faucet and most FEVM tools.
Now that we’ve got the kit set up, we can start using it to develop and deploy our contracts.
### Manage the contracts
There are two main types of contracts:
* Basic Solidity examples: Simple contracts to show off basic Solidity.
* Filecoin API Examples: Contracts that demo how to use the Filecoin APIs in Solidity to access storage deals and other Filecoin-specific functions.
Make sure that your account has funds. You won’t be able to deploy any contracts without `FIL` or `tFIL`.
1. Run `hardhat deploy` to deploy the kit contracts. The current kit defaults to the Calibration network:
```shell
yarn hardhat deploy
```
Deployment is network-dependent and may attempt Blockscout and Filfox verification after broadcasting. To deploy without verifier calls, set the kit’s skip flags:
```shell
IGNORE_FILFOX_VERIFICATION=true IGNORE_BLOCKSCOUT_VERIFICATION=true yarn hardhat deploy
```
2. Interact with the contracts using the available functions within the `tasks` folder. For example, you can get the balance of the `simple-coin` contract by calling the `get-balance` function:
```shell
export CONTRACT_ADDRESS=0xYourDeployedSimpleCoinAddress
export ACCOUNT_ADDRESS=0xYourEthereumStyleAccountAddress
yarn hardhat get-balance --contract "$CONTRACT_ADDRESS" --account "$ACCOUNT_ADDRESS"
```
## Hardhat docs
You can view the official Hardhat documentation over at [`hardhat.org/docs`](https://hardhat.org/docs).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/development-frameworks/hardhat)
# Foundry
Foundry is a fast toolkit for application development written in Rust equipped with a testing framework, as well as utilities for interacting with smart contracts and getting chain data.
The [FEVM Foundry Kit](https://github.com/filecoin-project/fevm-foundry-kit) is a Foundry template for Filecoin EVM projects. It includes Solidity examples, Filecoin API examples, Foundry remappings, and verification tooling for Filecoin explorers.
## Prerequisites
You must have the following installed:
* [Git](https://git-scm.com/)
* [Node.js](https://nodejs.org/) and npm
* [Foundry](https://getfoundry.sh/)
You should also have an address on the Filecoin Calibration testnet. See the [MetaMask setup page](/networks-and-tools/assets/metamask-setup) for information on how to get an address. You also need test `tFIL` in your wallet.
## Steps
1. Clone the `filecoin-project/fevm-foundry-kit` repository and move into the `fevm-foundry-kit` directory:
```shell
git clone https://github.com/filecoin-project/fevm-foundry-kit
cd fevm-foundry-kit
```
2. Build the contracts and install the project’s npm dependencies:
```shell
forge build
npm install
```
3. Export your private key from MetaMask. See the [MetaMask documentation](https://support.metamask.io/configure/accounts/how-to-export-an-accounts-private-key/) to find out how to export your private key.
4. Create your env file by running:
```shell
cp .env.example .env
```
5. In your newly created `.env`, replace `PRIVATE_KEY` with the private key exported from MetaMask. Keep the Calibration RPC URL or replace it with your preferred Filecoin Calibration RPC endpoint:
```bash
PRIVATE_KEY=your_private_key_here
CALIBRATIONNET_RPC_URL=https://api.calibration.node.glif.io/rpc/v1
```
6. Load the variables in your current shell before running deployment commands:
```shell
source .env
```
{% hint style="info" %}
Never commit `.env` files or real private keys. Anyone with access to the private key can spend funds from the account.
{% endhint %}
7. Deploy the kit’s `DealClient` example contract to Calibration:
```shell
forge create \
--rpc-url "$CALIBRATIONNET_RPC_URL" \
--private-key "$PRIVATE_KEY" \
--broadcast \
src/basic-deal-client/DealClient.sol:DealClient
```
The deployment output is environment-dependent. Record the `Deployed to` address from Foundry’s output; you will need it for contract interactions and verification.
8. You can now interact with your contract using the contract address given by Foundry.
Done! For more information, see the [Foundry book](https://book.getfoundry.sh/).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/development-frameworks/foundry)
# Developing contracts
Write, deploy, and test smart contracts on the Filecoin Virtual Machine.
This section covers how to build dApps by writing smart contracts on the Filecoin Virtual Machine.
## Table of contents
* [Get test tokens](/build-on-filecoin/developing-contracts/get-test-tokens) — obtain tFIL from a faucet for testing on Calibration
* [ERC-20 quickstart](/build-on-filecoin/developing-contracts/erc-20-quickstart) — deploy your first ERC-20 token on Filecoin
* [Call built-in actors](/build-on-filecoin/developing-contracts/call-built-in-actors) — interact with Filecoin system actors from your contracts
* [Filecoin.sol](/build-on-filecoin/developing-contracts/filecoin.sol) — Solidity libraries for accessing Filecoin storage primitives
* [Solidity libraries](/build-on-filecoin/developing-contracts/solidity-libraries) — third-party contract templates and libraries
* [Best practices](/build-on-filecoin/developing-contracts/best-practices) — guidelines for building reliable FVM dApps
* [Support](/build-on-filecoin/developing-contracts/support) — where to get help with contract development
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts)
# Get test tokens
Test funds are available to developers so that they can test their smart contracts and applications within the confines of a test network. This page covers how to get test funds.
## Calibration testnet
MetaMask is one of the easier ways to manage addresses on the Calibration testnet. MetaMask displays Filecoin EVM accounts in Ethereum `0x` format; on Filecoin testnets those accounts map to delegated `t4` [addresses](/core-concepts/filecoin-evm-runtime/address-types). Follow the [MetaMask setup guide](/networks-and-tools/assets/metamask-setup) if you haven’t set up an address in your MetaMask wallet yet.
On Calibration, tFIL pays for gas and test USDFC pays for storage in applications such as the `filecoin` CLI. Request both tokens for the same wallet.
### Get tFIL
1. In your browser, open MetaMask and copy your address to your clipboard.
2. Go to [faucet.calibnet.chainsafe-fil.io](https://faucet.calibnet.chainsafe-fil.io/funds.html) and click **Send Funds**.
3. Paste your address into the address field and click **Send funds**:
4. The webpage will give you a transaction ID:
5. You can copy this ID into a block explorer to track the progress of your transaction:
### Get test USDFC
1. In MetaMask, select the **Filecoin Calibration** network and copy the same wallet's `0x` address used above.
2. Open the [Filecoin Calibration USDFC faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc), paste your address, and click **Claim tUSDFC**.
3. Wait for the transaction to be marked **confirmed** under **Transactions**. Follow its link to view the transfer in a block explorer.
## Local testnet
Before we begin, you must have a local testnet running. Follow the [Run a local network guide](/networks-and-tools/networks/local-testnet) if you haven’t got a local testnet set up yet. Run the commands below from the directory that contains your local `lotus` binary, and replace the placeholder addresses with addresses from your local node.
1. Change directory to where you created the `lotus` and `lotus-miner` binaries. If you followed the [Run a local network guide](/networks-and-tools/networks/local-testnet) these binaries will be in `~/lotus-devnet`:
```shell
cd ~/lotus-devnet
```
2. View the wallets available on this node with `lotus wallet list`:
```shell
./lotus wallet list
```
3. Create the send request with `lotus send`, supplying a funded local wallet as the `--from` address, the receiving address, and the amount of FIL you want to send:
```shell
./lotus send --from
```
To create a delegated address for local Filecoin EVM testing, run:
```shell
./lotus wallet new delegated
```
4. Check the balance of your receiving address with `lotus wallet balance`:
```shell
./lotus wallet balance
```
If you want to manage your local testnet tokens in MetaMask, use a delegated address and [connect MetaMask to your local testnet](/networks-and-tools/assets/metamask-setup) to see the new balance within the MetaMask extension.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts/get-test-tokens)
# ERC-20 quickstart
In this quickstart tutorial we’ll walk through how to deploy your first smart-contract to the Filecoin network.
We’re going to install a browser-based wallet called MetaMask, create a new wallet address, supply some test currency to that wallet, and then use a browser-based development environment called Remix to deploy a smart contract to the Filecoin network. We’re going to be creating an ERC-20 token in this quickstart. The ERC-20 contract is used a lot in representing a massive array of tokens across multiple blockchains, primarily the Ethereum blockchain.
{% hint style="info" %}
If you’re an Ethereum developer, check out the [FEVM Hardhat kit](/build-on-filecoin/development-frameworks/hardhat).
{% endhint %}
## Accounts and assets
We’re going to be using MetaMask, a cryptocurrency wallet that lives in your browser making it very easy for users to interact with web3-based sites!
### Create a wallet
Before we can interact with the Filecoin network, we need funds. But before we can get any funds, we need somewhere to put them!
1. Open your browser and visit the [MetaMask website](https://metamask.io/).
2. Install the wallet by clicking the **Download for** button. MetaMask is available for Brave, Chrome, Edge, Firefox, and Opera.
3. Once you have installed MetaMask, it will open a **Get started** window.
4. Click **Create a new wallet**.
5. Enter a password to secure your MetaMask wallet. You will need to enter this password every time you use the wallet.
6. Follow the prompts until you get to the **Secret Recovery Phrase** window. Read the information about what this *recovery phrase* is on this page.
7. Eventually you should get to the *Wallet creation success* page!
8. Once you’ve done that, you should have your account set up!
### Switch networks
You may notice that we are currently connected to the **Ethereum Mainnet**. We need to point MetaMask to the Filecoin network, specifically the [Calibration testnet](/networks-and-tools/networks/calibration). We’ll use a website called [chainlist.org](https://chainlist.org) to give MetaMask the information it needs quickly.
1. Go to [chainlist.org](https://chainlist.org).
2. Enable the **Testnets** toggle and enter `Filecoin` into the search bar.
3. Scroll down to find the **Filecoin – Calibration** **testnet**.
4. In MetaMask click **Next**.
5. Click **Connect.**
6. Click **Approve** when prompted to *Allow this site to add a network.*
7. Click **Switch network** when prompted by MetaMask.
8. Open MetaMask from the browser extensions tab:
9. You should see the *Filecoin Calibration* testnet listed at the top.
Nice! Now we’ve got the Filecoin Calibration testnet set up within MetaMask. You’ll notice that our MetaMask window shows `0 tFIL`. Test-filecoin (`tFIL`) is `FIL` that has no value in the *real world*, and developers use it for testing. We’ll grab some `tFIL` next.
### Get some funds
1. In your browser, open MetaMask and copy your address to your clipboard:
2. Go to [faucet.calibnet.chainsafe-fil.io](https://faucet.calibnet.chainsafe-fil.io) and click **Send Funds.**
3. Paste your address into the address field, and click **Send Funds**.
4. The faucet will show a transaction ID. You can copy this ID into a Calibration testnet [block explorer](/networks-and-tools/networks/calibration/explorers) to view your transaction. After a couple of minutes, you should see some `tFIL` transferred to your address.
That’s all there is to it! Getting `tFIL` is easy!
## Contract creation
The development environment we’re going to be using is called Remix, viewable at [remix.ethereum.org](https://remix.ethereum.org/). Remix is an incredibly sophisticated tool, and there’s a lot you can play around with! In this tutorial however, we’re going to stick to the very basics. If you want to learn more, check out [the Remix documentation](https://remix-ide.readthedocs.io/en/latest/).
### Create a workspace
In Remix, workspaces are where you can create a contract, or group of contracts, for each project. Let’s create a new workspace to create our new ERC-20 token.
1. Open [remix.ethereum.org](https://remix.ethereum.org).
2. Open the dropdown menu and click **create a new workspace**.
3. In the **Choose a template** dropdown, select **ERC20**.
4. Under **Customize template** > **Features**, check the **Mintable** box.
5. Enter a fun name for your token in the **Workspace name** field. Something like `CorgiCoin` works fine.
6. Click **OK** to create your new workspace.
### Customize the contract
The contract template we’re using is pretty simple. We just need to modify a couple of variables.
1. Click the compiler icon to open the compiler panel. Update the compiler version by selecting `0.8.20` from the compiler dropdown.
2. Under the **contract** directory, click **MyToken.sol**.
3. In the editor panel, replace `MyToken` with whatever you’d like to name your token. In this example, we’ll use `CorgiCoin`.
4. On the same line, replace the second string with whatever you want the symbol of your token to be. In this example, we’ll use `CRG`.
That’s all we need to change within this contract. You can see on line 4 that this contract is importing another contract from `@openzeppelin` for us, meaning that we can keep our custom token contract simple.
### Compile
1. Click the green play symbol at the top of the workspace to compile your contract. You can also press `CMD` + `s` on MacOS or `CTRL` + `s` on Linux and Windows.
2. Remix automatically fetches the three `import` contracts from the top of our `.sol` contract. You can see these imported contracts under the `.deps` directory. You can browse the contracts there, but Remix will not save any changes you make.
### Deploy
Now that we’ve successfully compiled our contract, we need to deploy it somewhere! This is where our previous MetaMask setup comes into play.
1. Click the **Deploy** tab from the left.
2. Under the **Environment** dropdown, select **Injected Provider - MetaMask**.
3. MetaMask will open a new window confirming that you want to connect your account to Remix.
4. Click **Next**:
5. Click **Connect** to connect your `tFIL` account to Remix.
6. Back in Remix, under the **Account** field, you’ll see that it says something like `0x11F... (5 ether)`. This value is 5 `tFIL`, but Remix doesn’t support the Filecoin network so doesn’t understand what `tFIL` is. This isn’t a problem, it’s just a little quirk of using Remix.
7. Under the **Contract** dropdown, ensure the contract you created is selected.
8. Gather your MetaMask account address and populate the deploy field in Remix.
9. Click **Deploy**.
10. MetaMask will open a window and as you to confirm the transaction. Scroll down and click **Confirm** to have MetaMask deploy the contract.
11. Back in Remix, a message at the bottom of the screen shows that the creation of your token is pending.
12. Wait around 90 seconds for the deployment to complete.
On the Filecoin network, a new set of blocks, also called a tipset, is created every thirty seconds. When deploying a contract, the transaction needs to be received by the network, and then the network needs to confirm the contract. This process takes around one to two tipsets to process – or around 60 to 90 seconds.
## Use your contract
Now that we’ve compiled and deployed the contract, it’s time to actually interact with it!
### Mint your tokens
Let’s call a method within the deployed contract to mint some tokens.
1. Back in Remix, open the **Deployed Contracts** dropdown, within the **Deploy** sidebar tab.
2. Expand the `mint` method. You must fill in two fields here: `to` and `amount`.
3. The `to` field specifies where address you want these initial tokens sent to. Open MetaMask, copy your address, and paste it into this field.
4. This field expects an `attoFil` value. 1 `FIL` is equal to 1,000,000,000,000,000,000 `attoFil`. So if you wanted to mint 100 `FIL`, you would enter `100` followed by 18 zeros: `100000000000000000000`.
5. Click **Transact**.
6. MetaMask will open a window and ask you to confirm the transaction:
Again, you must wait for the network to process the transaction, which should take about 90 seconds. You can move on to the next section while you’re waiting.
### Add to MetaMask
Currently, MetaMask has no idea what our token is or what it even does. We can fix this by explicitly telling MetaMask the address of our contract.
1. Go back to Remix and open the **Deploy** sidebar tab.
2. Under **Deployed Contracts**, you should see your contract address at the top. Click the copy icon to copy the address to your clipboard:
3. Open MetaMask, select **Assets**, and click **Import your tokens**:
4. In the **Token contract address** field, paste the contract address you just copied from Remix and then click **Add custom token**. MetaMask should autofill the rest of the information based on what it can find from the Filecoin network.
5. Click **Import token**:
6. You should now be able to see that you have 100 of your tokens within your MetaMask wallet!
### Share your tokens
Having a bunch of tokens in your personal MetaMask is nice, but why not send some tokens to a friend? Your friend needs to create a wallet in MetaMask as we did in the [Create a wallet](#create-a-wallet) and [Switch networks](#switch-networks) sections. They will also need to import your contract deployment address like you did in the [Add your tokens to MetaMask](/networks-and-tools/assets/metamask-setup) section. Remember, you need to pay gas for every transaction that you make! If your friend tries to send some of your tokens to someone else but can’t, it might be because they don’t have any `tFIL`.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts/erc-20-quickstart)
# Call built-in actors
Filecoin built-in actors can be invoked in a smart contract using either the Protocol API or the Filecoin.sol library. This page provides instructions on how to use each method.
{% hint style="info" %}
For conceptual information on built-in actors, including their purposes, how they work and available types, see the [conceptual guide](/reference/built-in-actors)
{% endhint %}
Built-in actors can be invoked using the Protocol *JSON-RPC* API or the Filecoin.sol API.
## APIs compared
The Protocol *JSON-RPC* API:
* Is maintained by Protocol Labs (PL).
* Uses JSON-RPC, a standardized way to encode remote procedure calls in JSON that can be transported using HTTP or WebSockets.
* Provides a language agnostic interface for Filecoin functionality.
* Allows applications to access Filecoin functionality using HTTP or WebSockets calls to a Filecoin node, like the Lotus daemon.
* Requires authentication for some API calls.
* Serves as the foundation for language-specific libraries (some of which are maintained by organizations other than PL) such as [filecoin.js](https://filecoin-shipyard.github.io/filecoin.js/).
The Filecoin.sol API:
* Supports [*some but not all* of the built-in actors and their methods](#available-actors-and-methods).
## Protocol API
Applications and off-chain services can access built-in actors and methods using the Filecoin JSON-RPC API exposed by nodes such as Lotus. Smart contracts should use Filecoin.sol or the actor precompiles instead. Links to the reference guides for each of the available actor methods are listed below:
* [Account actor](#account)
* [Datacap](#datacap)
* [Miner](#miner)
* [Multisig](#multisig)
* [Storage market actor](#storage-market)
* [Storage power actor](#storage-power)
* [Verified registry actor](#verified-registry)
## Filecoin.sol
Smart contracts can access built-in actor methods with the `filecoin.sol` library, a set of Solidity libraries that allow Solidity smart contracts to call methods of Filecoin built-in actors. The maintained npm package is `filecoin-solidity-api`, and its current import paths use `contracts/v0.8`. This section contains information on the actors and methods available from `filecoin.sol`, along with installation instructions and references for examples of smart contracts that call built-in actor methods.
To invoke built-in actor methods using `filecoin.sol`, follow these steps:
1. Review the [available actors and methods](#available-actors-and-methods).
2. [Import `filecoin.sol`](#import-filecoinsol).
3. [Call a built-in actor](#call-a-built-in-actor).
### Available actors and methods
The majority of the Account, DataCap, Storage Market, Miner, Storage Owner and Verified Registry actor methods are supported and are listed below. **Cron, Payment Channel, Reward and System actor methods are currently not supported.**
#### **Account**
| Method | Supported? |
| --------------------- | ---------- |
| AuthenticateMessage | ✔️ |
| Constructor | ✖️ |
| PubkeyAddress | ✖️ |
| UniversalReceiverHook | ✔️ |
#### **DataCap**
| Method | Supported? |
| ----------------- | ---------- |
| Allowance | ✔️ |
| BalanceOf | ✔️ |
| Burn | ✔️ |
| BurnFrom | ✔️ |
| Constructor | ✖️ |
| DecreaseAllowance | ✔️ |
| Destroy | ✖️ |
| IncreaseAllowance | ✔️ |
| Mint | ✖️ |
| Name | ✔️ |
| RevokeAllowance | ✔️ |
| Symbol | ✔️ |
| TotalSupply | ✔️ |
| Transfer | ✔️ |
| TransferFrom | ✔️ |
#### **Miner**
| Method | Supported? |
| ------------------------- | ---------- |
| ApplyRewards | ✖️ |
| ChangeBeneficiary | ✔️ |
| ChangeMultiaddrs | ✔️ |
| ChangeOwnerAddress | ✔️ |
| ChangePeerID | ✔️ |
| ChangeWorkerAddress | ✔️ |
| CheckSectorProven | ✖️ |
| CompactPartitions | ✖️ |
| CompactSectorNumbers | ✖️ |
| ConfirmSectorProofsValid | ✖️ |
| ConfirmUpdateWorkerKey | ✖️ |
| Constructor | ✖️ |
| ControlAddresses | ✖️ |
| DeclareFaults | ✖️ |
| DeclareFaultsRecovered | ✖️ |
| DisputeWindowedPoSt | ✖️ |
| ExtendSectorExpiration | ✖️ |
| ExtendSectorExpiration2 | ✖️ |
| GetAvailableBalance | ✔️ |
| GetBeneficiary | ✔️ |
| GetOwner | ✔️ |
| GetSectorSize | ✔️ |
| GetVestingFunds | ✔️ |
| IsControllingAddress | ✔️ |
| OnDeferredCronEvent | ✖️ |
| PreCommitSector | ✖️ |
| PreCommitSectorBatch | ✖️ |
| PreCommitSectorBatch2 | ✖️ |
| ProveCommitAggregate | ✖️ |
| ProveCommitSector | ✖️ |
| ProveReplicaUpdates | ✖️ |
| ProveReplicaUpdates2 | ✖️ |
| Read fee debt | ✖️ |
| Read initial pledge total | ✖️ |
| Read peer ID, multiaddr | ✔️ |
| Read pre-commit deposit | ✖️ |
| RepayDebt | ✔️ |
| ReportConsensusFault | ✖️ |
| SubmitWindowedPoSt | ✖️ |
| TerminateSectors | ✖️ |
| WithdrawBalance | ✔️ |
#### **Multisig**
| Method | Supported? |
| --------------------------- | ---------- |
| AddSigner | ✔️ |
| Approve | ✔️ |
| Cancel | ✔️ |
| ChangeNumApprovalsThreshold | ✖️ |
| Constructor | ✖️ |
| List signers and threshold | ✖️ |
| LockBalance | ✔️ |
| Propose | ✔️ |
| RemoveSigner | ✔️ |
| SwapSigner | ✔️ |
| UniversalReceiverHook | ✔️ |
#### **Storage market**
| Method | Supported? |
| ------------------------- | ---------- |
| ActivateDeals | ✖️ |
| AddBalance | ✔️ |
| ComputeDataCommitment | ✖️ |
| Constructor | ✖️ |
| CronTick | ✖️ |
| GetBalance | ✔️ |
| GetDealActivation | ✔️ |
| GetDealClient | ✔️ |
| GetDealClientCollateral | ✔️ |
| GetDealDataCommitment | ✔️ |
| GetDealEpochPrice | ✔️ |
| GetDealLabel | ✔️ |
| GetDealProvider | ✔️ |
| GetDealProviderCollateral | ✔️ |
| GetDealTerm | ✔️ |
| GetDealVerified | ✔️ |
| OnMinerSectorsTerminate | ✖️ |
| PublishStorageDeals | ✔️ |
| VerifyDealsForActivation | ✖️ |
| WithdrawBalance | ✔️ |
#### **Storage power**
| Method | Supported? |
| ---------------------------------------- | ---------- |
| Compute pledge collateral for new sector | ✖️ |
| Constructor | ✖️ |
| CreateMiner | ✔️ |
| CurrentTotalPower | ✖️ |
| EnrollCronEvent | ✖️ |
| Get miner count, consensus count | ✔️ |
| Get miner’s QA power | ✖️ |
| Get network bytes committed? | ✖️ |
| Get network epoch pledge collateral | ✖️ |
| Get network epoch QA power | ✖️ |
| Get network total pledge collateral? | ✖️ |
| MinerRawPower | ✔️ |
| NetworkRawPower | ✔️ |
| OnEpochTickEnd | ✖️ |
| SubmitPoRepForBulkVerify | ✖️ |
| UpdateClaimedPower | ✖️ |
| UpdatePledgeTotal | ✖️ |
#### **Verified registry**
| Method | Supported? |
| --------------------------- | ---------- |
| AddVerifiedClient | ✔️ |
| AddVerifier | ✖️ |
| ClaimAllocations | ✖️ |
| Constructor | ✖️ |
| ExtendClaimTerms | ✔️ |
| GetClaims | ✔️ |
| List claims | ✖️ |
| List/check verifiers | ✖️ |
| List/get allocations | ✖️ |
| RemoveExpiredAllocations | ✔️ |
| RemoveExpiredClaims | ✔️ |
| RemoveVerifiedClientDataCap | ✖️ |
| RemoveVerifier | ✖️ |
| UniversalReceiverHook | ✔️ |
### Import filecoin.sol
The `filecoin.sol` library is embeddable into your smart contract, which means it does not need be present on chain first. Instead, you can just import the library and call the available methods. The `filecoin.sol` library can be [added via `npm`](#import-filecoinsol-with-npm) or [manually imported](#import-filecoinsol-manually) into your contract. The `npm`-based import is simpler, and is recommended.
#### **Import filecoin.sol with npm**
1. Install the Filecoin Solidity API package:
```shell
npm install filecoin-solidity-api
```
{% hint style="info" %}
Use the maintained `filecoin-solidity-api` package and import paths. Older examples may use legacy Zondax package names or repository paths; do not copy those into new projects.
{% endhint %}
#### **Import filecoin.sol manually**
1. Navigate to your smart contract project folder ``:
```shell
cd my-project
```
2. Create a folder named `libs`:
```shell
mkdir libs
```
3. Move into the `libs` directory:
```shell
cd libs
```
4. Copy the Filecoin Solidity API contracts with the methods you wish to call from [the contracts folder](https://github.com/filecoin-project/filecoin-solidity/tree/master/contracts/v0.8) into `libs`. Preserve the subdirectories such as `types`, `utils`, and `cbor`, because the actor API files import those dependencies.
### Call a built-in actor
Once you’ve either imported particular contracts manually or installed `filecoin-solidity-api` using npm, create a callable method to access the built-in actor methods the way you normally would in a Solidity smart contract. See the [Filecoin.sol guide](/build-on-filecoin/developing-contracts/filecoin.sol) for npm import examples and the [reference guide](/reference/built-in-actors/filecoin.sol) for actor-specific method examples.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts/call-built-in-actors)
# Filecoin.sol
External Solidity libraries can help developers create their applications quicker by offloading some of the work to already existing smart contracts.
The Filecoin Solidity library allows developers to:
* Interact with Filecoin built-in actors.
* Simplify the interaction with the Filecoin storage market, miner actors, the verified registry for Filecoin Plus automation, and more.
* Use Filecoin-specific data types such as `FilAddress`, `FilActorId`, `Cid`, storage deals, and more.
* OpenZeppelin-like utilities specific to Filecoin.
* CBOR serialization and deserialization for parameters and return data.
In order to access exported Filecoin built-in actor methods in your smart contract, you will need to import Filecoin.sol in your Solidity project. As they are embeddable libraries, they don’t need to be present on-chain. You can just import the library you desire and call its methods.
Once the library is installed in your project, you can write Solidity code to call APIs from different built-in actors using Filecoin-specific data types or data conversions from the utility library.
## Add to your contract
Run the following command in your Solidity project, which is created using any smart contract development framework such as Hardhat or Foundry.
```shell
npm install filecoin-solidity-api
```
## Works on
Filecoin.sol calls Filecoin built-in actors from contracts deployed to Filecoin EVM networks. Use it on Filecoin mainnet or Calibration testnet with the current FVM actors and the Filecoin Solidity API package shown above. For local development, use a Filecoin EVM-compatible local network that exposes the same built-in actor precompiles.
## Usage
Once installed, you can call built-in actors in the library after importing them into your smart contract.
```solidity
// contracts/MyFilecoinContract.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.18;
import { MarketAPI } from "filecoin-solidity-api/contracts/v0.8/MarketAPI.sol";
import { MarketTypes } from "filecoin-solidity-api/contracts/v0.8/types/MarketTypes.sol";
import { Errors } from "filecoin-solidity-api/contracts/v0.8/utils/Errors.sol";
contract MyFilecoinContract {
function getDealTerm(uint64 dealID) public view returns (MarketTypes.GetDealTermReturn memory) {
(int256 exitCode, MarketTypes.GetDealTermReturn memory result) = MarketAPI.getDealTerm(dealID);
Errors.revertOnError(exitCode);
return result;
}
}
```
You can find the list of supported built-in actors and methods in the [Filecoin.sol documentation](/reference/built-in-actors/filecoin.sol). You can access certain Filecoin-related features through these actors:
* `AccountAPI.sol`: validates signatures from an address.
* `MinerAPI.sol`: manages storage provider operation.
* `MarketAPI.sol`: manages storage deals on Filecoin.
* `PowerAPI.sol`: manages storage power for each storage provider and the whole network.
* `DataCapAPI.sol` and `VerifRegAPI.sol`: manages DataCap and verified clients for Filecoin Plus.
Unlike OpenZeppelin contracts, you do not need to inherit contracts to use their features. With Filecoin.sol you just need to call the methods from those solidity contracts:
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.18;
import { MinerAPI } from "filecoin-solidity-api/contracts/v0.8/MinerAPI.sol";
import { CommonTypes } from "filecoin-solidity-api/contracts/v0.8/types/CommonTypes.sol";
import { MinerTypes } from "filecoin-solidity-api/contracts/v0.8/types/MinerTypes.sol";
import { Errors } from "filecoin-solidity-api/contracts/v0.8/utils/Errors.sol";
contract MinerQuery {
function getVestingFunds(uint64 minerActorID) public view returns (MinerTypes.VestingFunds[] memory) {
CommonTypes.FilActorId minerID = CommonTypes.FilActorId.wrap(minerActorID);
(int256 exitCode, MinerTypes.VestingFunds[] memory vestingFunds) = MinerAPI.getVestingFunds(minerID);
Errors.revertOnError(exitCode);
return vestingFunds;
}
}
```
Filecoin.sol also offers several utility libraries to help developers convert data types for different variables, including FIL addresses, big integers, actor IDs, and CBOR. Import only the utilities your contract uses. For example:
```solidity
import { Actor } from "filecoin-solidity-api/contracts/v0.8/utils/Actor.sol";
import { BigInts } from "filecoin-solidity-api/contracts/v0.8/utils/BigInts.sol";
import { FilAddresses } from "filecoin-solidity-api/contracts/v0.8/utils/FilAddresses.sol";
```
## Example
We can write a simple Solidity smart contract to query basic information for a Filecoin storage deal:
```solidity
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.18;
import "filecoin-solidity-api/contracts/v0.8/MarketAPI.sol";
import "filecoin-solidity-api/contracts/v0.8/types/CommonTypes.sol";
import "filecoin-solidity-api/contracts/v0.8/types/MarketTypes.sol";
import "filecoin-solidity-api/contracts/v0.8/utils/Errors.sol";
contract StorageDealQuery {
// Query the start epoch and duration, in epochs, of a deal proposal.
function get_deal_term(uint64 dealID) public view returns (MarketTypes.GetDealTermReturn memory) {
(int256 exitCode, MarketTypes.GetDealTermReturn memory result) = MarketAPI.getDealTerm(dealID);
Errors.revertOnError(exitCode);
return result;
}
// Query the storage provider who stores the data for this deal.
function get_deal_provider(uint64 dealID) public view returns (uint64) {
(int256 exitCode, uint64 result) = MarketAPI.getDealProvider(dealID);
Errors.revertOnError(exitCode);
return result;
}
// Query the collateral required from the storage provider for this deal proposal.
function get_deal_provider_collateral(uint64 dealID) public view returns (CommonTypes.BigInt memory) {
(int256 exitCode, CommonTypes.BigInt memory result) = MarketAPI.getDealProviderCollateral(dealID);
Errors.revertOnError(exitCode);
return result;
}
}
```
#### Next steps
Check out these links to learn more about the Filecoin.sol library.
* [Filecoin-Solidity GitHub](https://github.com/filecoin-project/filecoin-solidity)
* [Built-In Actor APIs](/reference/built-in-actors/filecoin.sol)
* [FEVM Hardhat Kit](https://github.com/filecoin-project/fevm-hardhat-kit/)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts/filecoin.sol)
# Solidity libraries
With Filecoin Virtual Machine (FVM), Solidity developers can use existing libraries listed on this page in their FVM smart contracts.
## OpenZeppelin
[OpenZeppelin](https://www.openzeppelin.com/contracts) provides a library of battle-tested smart contract templates, including widely used implementations of ERC token standards. For a guided example that implements an ERC20 token on the Filecoin network, see [Example using an ERC20 contract](/build-on-filecoin/developing-contracts/erc-20-quickstart).
### Benefits
OpenZeppelin offers the following to smart contract developers:
* Implementations of standards like ERC20, ERC721, and ERC1155.
* Flexible access control schemes like `Ownable`, `AccessControl`, and `onlyRole`.
* Useful and secure utilities for signature verification, math, strings, and cryptography.
Token standards, such as [ERC20](https://docs.openzeppelin.com/contracts/5.x/erc20), are the most widely used smart contract libraries from OpenZeppelin. These contracts, listed below, implement both *fungible* and *non-fungible* tokens:
* [ERC20](https://docs.openzeppelin.com/contracts/5.x/erc20) is the simplest and most widespread token standard for fungible assets.
* [ERC721](https://docs.openzeppelin.com/contracts/5.x/erc721) is the standard solution for non-fungible tokens and is often used for collectibles and games.
* [ERC1155](https://docs.openzeppelin.com/contracts/5.x/erc1155) is a multi-token standard where a single contract represents multiple fungible and non-fungible tokens, and operations are batched for increased gas efficiency.
* [ERC6909](https://docs.openzeppelin.com/contracts/5.x/erc6909) is a compact multi-token standard for managing several token IDs in one contract.
### Using OpenZeppelin with FVM
The *general* procedure for using OpenZeppelin with FVM is as follows:
1. Install OpenZeppelin. For example, using `npm`:
```shell
npm install @openzeppelin/contracts
```
2. Import the specific library you want to use.
3. In your smart contract, inherit the library.
Thanks to the FVM, your contract can be integrated and deployed on the Filecoin network with OpenZeppelin inheritance. For a guided example that implements an ERC20 token on the Filecoin network, see [Example using an ERC20 contract](/build-on-filecoin/developing-contracts/erc-20-quickstart).
### Example using an ERC-20 contract
In the following tutorial, you’ll write and deploy a smart contract that implements the [ERC-20](https://docs.openzeppelin.com/contracts/5.x/erc20) on the Calibration testnet using Remix and MetaMask:
**Prerequisites**
Let’s take an ERC20 contract as an example to write and deploy it on the Calibration testnet using Remix & MetaMask:
* Remix.
* MetaMask.
* [MetaMask connected to the Calibration testnet](/networks-and-tools/networks/calibration).
* Test tokens (tFIL) [from the faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html).
**Procedure**
In this procedure, you will create, deploy, mint and send an [ERC20](https://docs.openzeppelin.com/contracts/5.x/erc20) token on Calibration using Remix and MetaMask.
1. Navigate to [remix.ethereum.org](https://remix.ethereum.org/).
2. Next to **Workspaces**, click the **+** icon to create a new workspace.
3. In the **Choose a template** dropdown, select **Blank**.
4. Click **OK**.
5. In the **contracts** directory, create a file named **MyToken.sol**.
6. Paste the following contract:
```solidity
// contracts/MyToken.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
contract MyToken is ERC20, Ownable {
constructor(address initialOwner) ERC20("Calibration Gold", "CGLD") Ownable(initialOwner) {}
function mint(address to, uint256 amount) public onlyOwner {
_mint(to, amount);
}
}
```
7. Next, compile and deploy the contract on Filecoin.
8. At the top of the workspace, click the green play symbol to compile the contract.
9. Once the contract compiles, open the **Deploy** tab on the left.
10. Under the **Environment** dropdown, select **Injected Provider - MetaMask**.
11. In the MetaMask popup window, select **Confirmed connection**.
12. Set `initialOwner` to your wallet address, click **Deploy**, and confirm the transaction on MetaMask. Your token contract will be deployed to the Calibration testnet once the network confirms the transaction.
13. In Remix, open the **Deployed Contracts** dropdown.
14. In the `mint` method, set:
* `to` to your wallet address.
* `amount` to `1000000000000000000` (1 token with 18 decimals).
15. Click **Transact**.
16. In MetaMask, confirm the transaction.
Once the network processes the transaction, the token is minted and sent to your network address. Congratulations, you’ve completed the tutorial!
### Additional resources
Learn more about OpenZeppelin with the following resources:
* [OpenZeppelin Contracts website](https://www.openzeppelin.com/contracts)
* [Documentation](https://docs.openzeppelin.com/contracts/5.x/)
* [GitHub](https://github.com/OpenZeppelin/openzeppelin-contracts)
## DappSys
The DappSys library provides safe, simple, and flexible Ethereum contract building blocks for common Ethereum and Solidity use cases.
* [Documentation](https://dappsys.readthedocs.io/en/latest/)
* [GitHub](https://github.com/dapphub/dappsys)
## 0x protocol
The 0x protocol library provides a set of secure smart contracts that facilitate peer-to-peer exchange of Ethereum-based assets.
* [Documentation](https://0x.org/docs/introduction/0x-cheat-sheet)
* [GitHub](https://github.com/0xProject)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts/solidity-libraries)
# Best practices
This page describes best practices for testing, developing and deploying smart contracts on the Filecoin network.
## Transactions
Best practices for transactions are described below.
### Consistently generating transaction receipts
Since receipts in Filecoin are generated in the next tipset, depending on when a transaction is submitted to the mempool, the receipt may take between 30 and 90 seconds to return. To consistently return transaction receipts when deploying a transaction or awaiting confirmation, change the default transaction receipt timeout (60000 ms or 1 minute for many toolchains) to 90 seconds or more. In a Hardhat script that already defines `upgrades`, `contract`, and `preparedArguments`, the relevant option for an OpenZeppelin upgradeable proxy is:
```js
const deployment = await upgrades.deployProxy(contract, preparedArguments, {
timeout: 180000
});
```
### Unstuck a message from the mempool
When users send messages to the Filecoin network, those messages will first land in the mempool. Once a node receives your message, it will verify the gas fee and signature and then process the transaction. Depending on network traffic and other factors, this process may take some time.
If the Filecoin network still needs to confirm a message, it’s because it has yet to be processed and is sitting in the mempool. Several causes exist, such as network congestion, insufficient gas fees, or an invalid message signature.
We recommend users resubmit the message with a higher gas fee or priority fee so those messages will not block the mempool and potentially impact the block-producing time. Gas fees on the network can fluctuate depending on network demand, so it’s always a good idea to monitor gas prices and adjust your fees accordingly to ensure your transaction is processed promptly.
#### **Metamask**
If you are building your project using MetaMask, it would be easier to educate the users to speed up a transaction by increasing the gas fee directly in MetaMask. Refer to the [official MetaMask documentation](https://support.metamask.io/manage-crypto/transactions/how-to-speed-up-or-cancel-a-pending-transaction/) for more details.
#### **Lotus**
Developers using Lotus can [replace an existing message with an updated gas fee](https://lotus.filecoin.io/kb/update-msg-gas-fee/).
#### **SDKs**
Developers processing messages using SDKs, such as ethers.js or web3.js, must replace the message with higher gas fees by following these steps:
1. Get the original message using its hash.
2. Create a new message with the same `nonce`, `to`, and `value` fields as the original message.
3. Set a higher `gasLimit` and `gasPrice` for this message.
4. Sign and send the new message.
## Futureproofing
Developers should take the time to thoroughly read through the following summary of possible contract future-proofing updates, as failure to properly future proof smart contracts may result in incompatibility with future Filecoin releases.
* **All contracts** must [accept both `DAG_CBOR (0x71)` and `CBOR (0x51)` in inputs and treat them identically, and use `CBOR (0x51)` in outputs](#accept-both-dag_cbor-0x71-and-cbor-0x51-in-inputs-and-treat-them-identically).
* If a contract uses the FRC42 hash of `GranularityExported`, it must be updated and redeployed.
* If a contract sends funds to actors that are non-native, Ethereum, or EVM smart contract accounts, it [must use the `call_actor` precompile](#contracts-sending-funds-to-specific-actors).
* If a contract is interacting with built-in actors, it must use the maintained `filecoin-solidity-api` package and the current `contracts/v0.8` imports.
### All contracts
All contracts must do the following:
#### **Accept both `DAG_CBOR (0x71)` and `CBOR (0x51)` in inputs and treat them identically**
Smart contracts should accept both `DAG_CBOR (0x71)` and `CBOR (0x51)` in inputs and treat them identically. Specifically:
* Treat `DAG_CBOR` and `CBOR` as equivalent when returned from the `call_actor` precompile.
* Treat `DAG_CBOR` and `CBOR` as equivalent when received as a parameter to `handle_filecoin_method`.
#### **Use CBOR (0x51) in outputs**
Smart contracts should use `CBOR (0x51)` in outputs. Specifically:
* Always pass `CBOR` to the `call_actor` precompile. `DAG_CBOR` is currently forbidden.
* Always return `CBOR` from `handle_filecoin_method`. `DAG_CBOR` is currently forbidden.
### Contracts using `GranularityExported` hash
The `GranularityExported` method in the Datacap actor was renamed to `Granularity`, so any contracts which use the FRC42 hash of `GranularityExported` (`953701584`) must update the hash to `3936767397` and redeploy.
### Contracts sending funds to specific actors
Any contracts sending funds to actors that are not native accounts (`f1` or `f3` addresses), Ethereum accounts, or EVM smart contracts must now use the `call_actor` precompile. **Solidity’s transfer function will no longer work as that will attempt to invoke the target actor as an EVM contract**.
### Contracts interacting with built-in actors
All contracts interacting with built-in actors must use the maintained [`filecoin-solidity-api` package and its `contracts/v0.8` imports](https://github.com/filecoin-project/filecoin-solidity/tree/master/contracts/v0.8). The IPLD codec used in the `handle_filecoin_method` solidity entrypoint and the `call_actor` should now be `CBOR (0x51)`, not `DAG_CBOR (0x71)`, as previously used. The underlying encoding (i.e. the payload bytes) are the same, but the codec numbers are now different. `DAG_CBOR` support will be re-enabled in the future but the usage of the codec implies additional runtime guarantees that have not yet been implemented.
## Contract Verification
When deploying contracts to mainnet, it is important to verify your contracts to improve transparency, security and trustlessness of the network. The process of verifying your contract involves recompiling your contract’s source code to ensure that the produced bytecode matches the bytecode that is already live on the network since it was deployed.
It is highly recommended for all FVM smart contracts to complete the verification process, soon after deployment.
Developers can easily do so through the following block explorers:
* [Filfox contract verifier](https://filfox.info/en/contract/)
* [Beryx contract verifier](https://beryx.zondax.ch/contract_verifier)
You can find this tutorial in the [FEVM ERC-20 Quickstart](/build-on-filecoin/developing-contracts/erc-20-quickstart).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts/best-practices)
# Support
If you need assistance while exploring the Filecoin virtual machine, you can reach out to the team and community using the links on this page.
## Slack
Like many other distributed teams, the Filecoin developer relations, led by the [FIL Builders](https://fil.builders/) team, works mostly on Slack and Discord. You can access the Filecoin Project Slack at [Filecoin Project Slack](https://filecoinproject.slack.com/ssb/redirect) and join the Discord at .
The following Slack channels are most relevant for Filecoin builders:
* [`#fil-builders`](https://filecoinproject.slack.com/archives/CRK2LKYHW) for building solutions on FVM and Filecoin
* [`#fil-fvm-dev`](https://filecoinproject.slack.com/archives/C029MT4PQB1) for development of the FVM
* [`#fvm-docs`](https://filecoinproject.slack.com/archives/C03MDFERKMJ) for FVM documentation
## Forum
If you just need a general pointer or looking for technical FAQs, you can head over to the [FVM GitHub Discussion tab](https://github.com/filecoin-project/community/discussions/categories/developers).
## Developer grants
The [Filecoin Grant Platform](https://github.com/filecoin-project/devgrants) connects grant makers with builders and researchers in the Filecoin community. Whether you represent a foundation that wants to move the space forward, a company looking to accelerate development on the features your application needs, or a developer team itching to hack on the FVM, [take a look at the supported grant types and available opportunities →](https://github.com/filecoin-project/devgrants)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/developing-contracts/support)
# Contract verification
Verify smart contracts on Filecoin using development frameworks or block explorer interfaces.
Contract verification lets users inspect the source code of deployed contracts and confirm they work as intended. This section covers how to verify contracts through both development tools and web interfaces.
## Table of contents
* [Verify using Hardhat](/build-on-filecoin/verification/hardhat) — automate verification from your Hardhat development environment
* [Verify using Foundry](/build-on-filecoin/verification/foundry) — automate verification from your Foundry development environment
* [Verify using Blockscout](/build-on-filecoin/verification/blockscout) — verify contracts through the Blockscout web interface
* [Verify using Filfox](/build-on-filecoin/verification/filfox) — verify contracts through the Filfox web interface
# Verify using Hardhat
Learn how to verify smart contracts on the Filecoin network using Hardhat with various verification services including Blockscout, Sourcify, and Filfox.
This guide shows you how to verify your smart contracts using Hardhat on the Filecoin network.
## Prerequisites
* A Hardhat project set up for Filecoin development. If you don't have one, start with the [FEVM Hardhat Kit](/build-on-filecoin/development-frameworks/hardhat).
* The `@nomicfoundation/hardhat-verify` plugin installed and imported in your Hardhat config.
* A deployed contract address on Filecoin mainnet or Calibration testnet.
* The same Solidity version, optimizer settings, and source tree that were used for deployment.
* Contract constructor arguments, if the contract was deployed with any.
* A Filecoin RPC URL for the target network. Filecoin mainnet uses chain ID `314`; Calibration testnet uses chain ID `314159`.
## Verification Methods
### Blockscout Verification
Blockscout is a popular blockchain explorer that supports contract verification. The FEVM Hardhat Kit already includes the Filecoin networks and verifier configuration. In another Hardhat v2 project, add equivalent configuration to `hardhat.config.ts`:
```typescript
import "@nomicfoundation/hardhat-verify";
import { HardhatUserConfig } from "hardhat/config";
const config: HardhatUserConfig = {
solidity: {
version: "0.8.23",
settings: {
optimizer: {
enabled: true,
runs: 1000,
},
},
},
networks: {
filecoin: {
url: process.env.FILECOIN_RPC_URL ?? "https://api.node.glif.io/rpc/v1",
chainId: 314,
},
calibration: {
url: process.env.CALIBRATION_RPC_URL ?? "https://api.calibration.node.glif.io/rpc/v1",
chainId: 314159,
},
},
etherscan: {
apiKey: {
filecoin: "empty",
calibration: "empty",
},
customChains: [
{
network: "filecoin",
chainId: 314,
urls: {
apiURL: "https://filecoin.blockscout.com/api",
browserURL: "https://filecoin.blockscout.com",
},
},
{
network: "calibration",
chainId: 314159,
urls: {
apiURL: "https://filecoin-testnet.blockscout.com/api",
browserURL: "https://filecoin-testnet.blockscout.com",
},
},
],
}
};
export default config;
```
Set RPC URLs in your shell or `.env` if you do not want to use the example defaults:
```bash
export FILECOIN_RPC_URL=https://api.node.glif.io/rpc/v1
export CALIBRATION_RPC_URL=https://api.calibration.node.glif.io/rpc/v1
```
Compile with the same settings used for deployment, then verify the deployed address. Put constructor arguments after the address and omit them if the constructor had no arguments.
**Verify on Filecoin mainnet:**
```bash
npx hardhat compile
npx hardhat verify --network filecoin 0xYourContractAddress "constructor arg 1"
```
**Verify on Calibration testnet:**
```bash
npx hardhat compile
npx hardhat verify --network calibration 0xYourContractAddress "constructor arg 1"
```
If Hardhat cannot infer which local contract matches the deployed bytecode, pass the fully qualified contract name:
```bash
npx hardhat verify \
--network calibration \
--contract contracts/MyContract.sol:MyContract \
0xYourContractAddress \
"constructor arg 1"
```
### Sourcify Verification
Sourcify provides decentralized contract verification. Include the Blockscout configuration above and add the following Sourcify configuration:
```typescript
const config: HardhatUserConfig = {
sourcify: {
enabled: true, // verifies both on Sourcify and on Blockscout
apiUrl: "https://sourcify.dev/server",
browserUrl: "https://repo.sourcify.dev",
},
};
export default config;
```
This configuration enables dual verification on both Sourcify and Blockscout when running the `npx hardhat verify` task.
If Blockscout verification is also enabled, keep passing constructor arguments when the deployed constructor required them.
For more information, see the [Sourcify documentation](https://docs.sourcify.dev/docs/how-to-verify/).
### Filfox Verification
Filfox is the native Filecoin explorer with dedicated verification support.
**Installation:**
Install the `@fil-b/filfox-verifier` package into your Hardhat project. The FEVM Hardhat Kit already includes this package.
```bash
npm install --save-dev @fil-b/filfox-verifier
```
**Configuration:** Import the plugin in your Hardhat configuration file. This will add the `verifyfilfox` task into your Hardhat project!
```javascript
// hardhat.config.js
require("@fil-b/filfox-verifier/hardhat");
// or in hardhat.config.ts
import "@fil-b/filfox-verifier/hardhat";
```
**Usage:**
```bash
# Verify on Filecoin mainnet
npx hardhat verifyfilfox --address 0xYourContractAddress --network filecoin
# Verify on Calibration testnet
npx hardhat verifyfilfox --address 0xYourContractAddress --network calibration
```
The Filfox Hardhat task requires Node.js 20 or later and a compiled Hardhat project. The verifier can discover supported Hardhat deployment artifacts, including `hardhat-deploy`, Ignition, and standard Hardhat artifacts.
For detailed information, see the [@fil-b/filfox-verifier documentation](https://www.npmjs.com/package/@fil-b/filfox-verifier).
# Verify using Foundry
Learn how to verify smart contracts on the Filecoin network using Foundry with various verification services including Blockscout, Sourcify, and Filfox.
This guide shows you how to verify your smart contracts using Foundry on the Filecoin network.
## Prerequisites
* A Foundry project set up for Filecoin development. If you don't have one, start with the [FEVM Foundry Kit](/build-on-filecoin/development-frameworks/foundry).
* Foundry installed with `forge` and `cast` available in your `PATH`.
* A deployed contract address on Filecoin mainnet or Calibration testnet.
* The same source tree, compiler version, optimizer settings, and `foundry.toml` settings that were used for deployment.
* Contract constructor arguments, if the contract was deployed with any.
* A Filecoin RPC URL for the target network. Filecoin mainnet uses chain ID `314`; Calibration testnet uses chain ID `314159`.
## Verification Methods
Set RPC URLs in your shell before running the examples:
```bash
export FILECOIN_RPC_URL=https://api.node.glif.io/rpc/v1
export CALIBRATION_RPC_URL=https://api.calibration.node.glif.io/rpc/v1
```
### Blockscout Verification
Blockscout is a popular blockchain explorer that supports contract verification.
**Verify on Calibration testnet:**
```bash
forge verify-contract \
--rpc-url "$CALIBRATION_RPC_URL" \
--chain 314159 \
--verifier blockscout \
--verifier-url "https://filecoin-testnet.blockscout.com/api/" \
0xYourContractAddress \
src/MyContract.sol:MyContract
```
**Verify on Filecoin mainnet:**
```bash
forge verify-contract \
--rpc-url "$FILECOIN_RPC_URL" \
--chain 314 \
--verifier blockscout \
--verifier-url "https://filecoin.blockscout.com/api/" \
0xYourContractAddress \
src/MyContract.sol:MyContract
```
For constructors, pass ABI-encoded constructor arguments. The constructor signature and values must match the deployment:
```bash
CONSTRUCTOR_ARGS=$(cast abi-encode "constructor(string,string)" "MyToken" "MYT")
forge verify-contract \
--rpc-url "$CALIBRATION_RPC_URL" \
--chain 314159 \
--verifier blockscout \
--verifier-url "https://filecoin-testnet.blockscout.com/api/" \
--constructor-args "$CONSTRUCTOR_ARGS" \
0xYourContractAddress \
src/MyToken.sol:MyToken
```
If Blockscout reports that the contract is already verified while you are retrying the same address, add `--force --skip-is-verified-check`.
### Sourcify Verification
Sourcify provides decentralized contract verification.
**Verify on Filecoin mainnet:**
```bash
forge verify-contract \
--rpc-url "$FILECOIN_RPC_URL" \
--chain 314 \
--verifier sourcify \
--verifier-url https://sourcify.dev/server/ \
--guess-constructor-args \
0xYourContractAddress \
src/MyToken.sol:MyToken
```
**Verify on Calibration testnet:**
```bash
forge verify-contract \
--rpc-url "$CALIBRATION_RPC_URL" \
--chain 314159 \
--verifier sourcify \
--verifier-url https://sourcify.dev/server/ \
--guess-constructor-args \
0xYourContractAddress \
src/MyToken.sol:MyToken
```
For more information, see the [Sourcify documentation](https://docs.sourcify.dev/docs/how-to-verify/).
### Filfox Verification
Filfox is the native Filecoin explorer with dedicated verification support.
**Installation:**
```bash
npm install --save-dev @fil-b/filfox-verifier
```
**Usage:**
```bash
npx filfox-verifier forge --chain
```
**Examples:**
```bash
# Verify on Filecoin mainnet
npx filfox-verifier forge 0xYourContractAddress src/MyContract.sol:MyContract --chain 314
# Verify on Calibration testnet
npx filfox-verifier forge 0xYourContractAddress src/MyContract.sol:MyContract --chain 314159
```
The Filfox verifier requires Node.js 20 or later and a Foundry project with `foundry.toml`. It runs `forge build` and extracts the metadata needed for the Filfox verification request.
For detailed information, see the [@fil-b/filfox-verifier documentation](https://www.npmjs.com/package/@fil-b/filfox-verifier).
# Verify using Blockscout
Step-by-step guide for verifying smart contracts on the Filecoin network using the Blockscout explorer's web interface.
The following guide walks you through the process of contract verification using the [Blockscout](https://filecoin.blockscout.com/) explorer.
## Prerequisites
* A deployed smart contract on Filecoin mainnet or Calibration testnet
* Your contract source code, either as a flattened `.sol` file or the same source files and metadata used at compile time
* The deployed contract address
* The Solidity compiler version used for deployment
* The license, optimization settings, optimizer runs, EVM version, and `viaIR` setting used for deployment
* Constructor arguments, if the contract was deployed with any
## Step-by-Step Verification Process
### Step 1: Prepare Your Contract Source Code
1. **Open Remix IDE** if you are using Blockscout's single-file Solidity verification method:
2. **Flatten your contract:**
* In the **File Explorer** sidebar, under **contracts**, right-click on your contract
* Select **Flatten** from the menu
* This creates a `_flattened.sol` file with all dependencies included
3. **Verify contract details:**
* Ensure the license and Solidity version match your original contract
* Click **Save** to save the flattened contract
4. **Download the flattened contract:**
* Right-click on `_flattened.sol`
* Select **Download** to save the file locally
5. **Gather required information:**
* Contract deployment address
* Contract license type (optional)
* Solidity compiler version used for deployment
* Optimization settings, including enabled/disabled and runs count
* EVM version and `viaIR` setting, if your deployment used non-default values
* ABI-encoded constructor arguments, if your contract constructor used arguments
### Step 2: Submit for Verification
6. **Access Blockscout verification page:**
* For Filecoin mainnet, navigate to [Filecoin Blockscout Contract Verification](https://filecoin.blockscout.com/contract-verification). Mainnet uses chain ID `314`.
* For Calibration testnet, navigate to [Calibration Blockscout Contract Verification](https://filecoin-testnet.blockscout.com/contract-verification). Calibration uses chain ID `314159`.
7. **Fill in contract information:**
* Enter your contract's deployment address
* Select the appropriate license type (optional)
* Choose verification method: `Solidity (Single file)`
* Select the compiler version used for deployment
* Paste the source code from your `_flattened.sol` file
* Configure the `Optimization enabled` checkbox to match your deployment settings
* Enter optimizer runs, constructor arguments, and any advanced compiler settings if the form prompts for them
8. **Submit for verification:**
* Click **Verify & Publish** to submit your contract
### Step 3: Verification Complete
Upon successful verification, Blockscout will display a success message and redirect you to your verified contract dashboard where you can view the source code and interact with your contract.
# Verify using Filfox
Step-by-step guide for verifying smart contracts on the Filecoin network using the Filfox explorer's web interface.
The following guide walks you through the process of contract verification using the [Filfox Contract Verification](https://filfox.info/en/contract) page.
## Prerequisites
* A deployed smart contract on Filecoin mainnet or Calibration testnet
* Your contract source code, either as a flattened `.sol` file or the source files requested by the Filfox form
* The deployed contract address
* The Solidity compiler version used for deployment
* The license, optimization settings, optimizer runs, EVM version, and `viaIR` setting used for deployment
* Constructor arguments, if the contract was deployed with any and the form prompts for them
## Step-by-Step Verification Process
### Step 1: Prepare Your Contract Source Code
1. **Open Remix IDE** if you are preparing a flattened source file for upload:
2. **Flatten your contract:**
* In the **File Explorer** sidebar, under **contracts**, right-click on your contract
* Select **Flatten** from the menu
* This creates a `_flattened.sol` file with all dependencies included
3. **Verify contract details:**
* Ensure the license and Solidity version match your original contract
* Click **Save** to save the flattened contract
4. **Download the flattened contract:**
* Right-click on `_flattened.sol`
* Select **Download** to save the file locally
5. **Gather required information:**
* Contract deployment address
* Contract license type (if any)
* Solidity compiler version used for deployment
* Optimization settings, optimizer runs, EVM version, and `viaIR` setting
* Constructor arguments, if your contract constructor used arguments
### Step 2: Submit for Verification
6. **Access Filfox verification page:**
* For Filecoin mainnet, navigate to the [Filfox Contract Verification](https://filfox.info/en/contract) page. Mainnet uses chain ID `314`.
* For Calibration testnet, navigate to the [Calibration Filfox Contract Verification](https://calibration.filfox.info/en/contract) page. Calibration uses chain ID `314159`.
7. **Fill in contract information:**
* Enter your contract's deployment address
* Select the appropriate license type
* Choose the compiler version used for deployment
* Match any prompted compiler and constructor settings to the original deployment
8. **Upload source code:**
* Click **Continue** to proceed
* Click **Select .sol files**
* Choose your flattened `.sol` file
* Click **Verify and Publish** to submit
### Step 3: Verification Complete
Once submitted, Filfox will process your verification request. Upon successful verification, you'll see a success message confirming your contract is now verified.
## Viewing Your Verified Contract
1. **Navigate to your contract:**
* Enter your contract address in the [Filfox search bar](https://filfox.info/)
* This will take you to your contract's page
2. **View verification status:**
* Scroll down and select the **Contract** tab
* Look for the **Contract Source Code Verified** banner
* Your contract's source code and ABI will now be publicly visible
3. **Explore verified contracts:**
* Browse [other verified contracts on Filfox](https://filfox.info/en/fevm/verified-contracts)
* Learn from verified contract examples in the ecosystem
# Advanced
Advanced tools and integrations for smart contract developers building on Filecoin.
This section covers advanced integrations and services available to smart contract developers on Filecoin, including bridges, oracles, databases, and automation tools. For programmable storage, retrieval, and payments, start with [Filecoin Onchain Cloud](/build-on-filecoin/filecoin-onchain-cloud).
## Table of contents
* [Wrapped FIL](/build-on-filecoin/advanced/wrapped-fil) — ERC-20 token that bridges native FIL to other blockchains
* [Oracles](/build-on-filecoin/advanced/oracles) — connect smart contracts to external data sources
* [Multicall](/build-on-filecoin/advanced/multicall) — batch multiple contract calls into a single transaction
* [Multisig](/build-on-filecoin/advanced/multisig) — wallets that require multiple signatures for transactions
* [FEVM indexers](/build-on-filecoin/advanced/fevm-indexers) — query Filecoin chain data without running an archival node
* [Cross-chain bridges](/build-on-filecoin/advanced/cross-chain-bridges) — transfer assets between Filecoin and other networks
* [Contract automation](/build-on-filecoin/advanced/contract-automation) — trigger smart contract actions based on off-chain events
* [Relay](/build-on-filecoin/advanced/relay) — meta-transactions that let users interact without paying gas
* [Decentralized databases](/build-on-filecoin/advanced/decentralized-databases) — store application data using Tableland on Filecoin
* [Privacy and access control](/build-on-filecoin/advanced/privacy-and-access-control) — tools for managing data access and privacy
* [Interplanetary consensus](/getting-started/interplanetary-consensus) — scalable consensus for cross-chain communication
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/advanced)
# Wrapped FIL
Wrapped FIL (wFIL) is the canonical wrapper token of the native Filecoin (FIL) token. Wrapped FIL features a 1-to-1 ratio pegged to FIL.
Wrapped FIL (wFIL) is a wrapper token based on the ERC-20 token standard for the native Filecoin token (FIL). It allows FIL to be bridged and used in Ethereum-compatible decentralized applications (dapps) hosted on other blockchains, such as decentralized exchanges (DEXs), lending platforms, and other places where FIL is not natively supported.
Wrapped FIL operates like any other ERC20-wrapped native blockchain token: a user deposits FIL into the wFIL contract and gets back an equal number of wFIL tokens. When users want to convert their wFIL back to FIL, they can burn the wFIL and unlock the same amount of FIL that was initially locked in the wFIL contract.
Overall, wFIL provides additional liquidity and interoperability for FIL tokens, making the Filecoin network more accessible for a broader range of decentralized finance (defi) use cases across multiple blockchains.
{% hint style="danger" %}
When wrapping and unwrapping FIL ensure you are using the correct wFIL contract address on Filecoin.
{% endhint %}
### Wrapped FIL contract addresses
Only use the following addresses when wrapping and unwrapping FIL:
* Mainnet: `0x60E1773636CF5E4A227d9AC24F20fEca034ee25A`
* Calibration testnet: `0xaC26a4Ab9cF2A8c5DBaB6fb4351ec0F4b07356c4`
### Wrapping and unwrapping process
There are a couple of options for users to wrap and unwrap FIL using a web browser:
* [Glif](https://www.glif.io/en)
* [Squid](https://app.squidrouter.com/?chains=314%2C314\&tokens=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee%2C0x60e1773636cf5e4a227d9ac24f20feca034ee25a)
To wrap FIL into wFIL, follow these steps:
1. **Obtain FIL**: Ensure you have FIL in your MetaMask wallet before wrapping it.
2. **Connect your wallet**: You will need to connect your wallet to a platform that supports wFIL wrapping, such as [Glif](https://www.glif.io/en) or [Squid](https://app.squidrouter.com/?chains=314%2C314\&tokens=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee%2C0x60e1773636cf5e4a227d9ac24f20feca034ee25a).
3. **Wrap your FIL**: After you’ve connected your wallet, you can wrap your FIL by following the platform’s instructions. Generally, you’ll need to select the amount of FIL you want to wrap and confirm the transaction on MetaMask. The platform will then mint an equivalent amount of wFIL and deposit it into your wallet.
4. **Use wFIL**: Once you have wFIL in your wallet, you can use it on various Defi products that support token swapping or bridging wFIL to other blockchains.
To unwrap FIL and receive FIL back to your wallet, users can directly go to supported platforms such as [Glif](https://www.glif.io/en) or [Squid](https://app.squidrouter.com/?chains=314%2C314\&tokens=0x60e1773636cf5e4a227d9ac24f20feca034ee25a%2C0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee) to unwrap FIL following the platform’s instructions. Once the network confirms the unwrap transaction, FIL tokens are transferred back to your wallet address.
### Programmatic interaction
Developers integrating wFIL into applications or protocols can wrap and unwrap FIL programmatically. The wFIL smart contract is deployed on the Filecoin Mainnet and Calibration testnet.
#### Wrap FIL
To add wrapping features to a project, developers must interact with the wFIL smart contract that manages the wFIL minting and burning process. The source code of the wFIL smart contract is in the [wFIL GitHub repo](https://github.com/glifio/wfil).
Do not directly send FIL to the wFIL contract address. Also, ensure you do not send FIL using the `METHOD_SEND` method. Always use the `InvokeEVM` method.
There are two options to wrap FIL:
1. Call the `deposit()` method in the wFIL contract and attach the amount of FIL tokens users want to wrap. This process will mint wFIL 1:1 and transfer to the `msg.sender` address.
```solidity
function deposit() public payable virtual {
_mint(msg.sender, msg.value);
emit Deposit(msg.sender, msg.value);
}
```
2. Since the wFIL implements the receive function, you can send FIL to the wFIL contract using the `InvokeEVM` method to wrap FIL. This method will trigger the `deposit` function, minting the caller with wFIL 1:1.
```solidity
receive() external payable virtual {
deposit();
}
```
#### Unwrap FIL
To unwrap wFIL into FIL, developers need to call the `withdraw` method in the wFIL contract and specify how many wFIL you would like to unwrap. The `withdraw` method looks like this:
```solidity
function withdraw(uint _amount) public virtual {
_burn(msg.sender, _amount);
emit Withdrawal(msg.sender, _amount);
payable(msg.sender).sendValue(_amount);
}
```
This process will burn the amount of wFIL from the caller’s balance and transfer the unwrapped FIL 1:1 back to the caller’s address.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/advanced/wrapped-fil)
# Oracles
Oracles act as a bridge between the Filecoin network and external data sources. Secure oracles allow smart contracts on the FVM to access and use external data sources.
In the Filecoin network, on-chain data and the state of smart contracts are isolated from external data sources. They cannot access real-world information without breaking the deterministic attributes of the network. Since smart contracts cannot access information outside the Filecoin network, oracles are used as trusted entities to provide external data to the network.
Oracles are an essential component of many blockchain applications, as they enable the blockchain to interact with the real world and provide more functionality to blockchain-based systems. Oracles can retrieve data from external sources, verify the data, and submit it to the blockchain for use by smart contracts and decentralized applications (dapps).
Oracles enable builders to integrate the following features into their projects:
* **Price feeds**: DeFi protocols like cross-chain lending rely on oracles for various token or token pair prices.
* **Cross-chain storage deal verification**: enable applications running on any blockchains to use the Filecoin decentralized storage and allow them to verify deal status and proofs.
* **Perpetual storage**: enable automated deal renewal and repair with the oracle providing deal status off-chain.
## Available oracles
There are several oracle-protocols built upon the FVM. Builders can integrate these oracles into their applications today.
### [Pyth](https://pyth.network/)
Pyth data is sourced directly from financial institutions across both traditional finance and the cryptocurrency industry.
Pyth publishes both the price feed and a confidence interval for each product. Learn more about [Pyth confidence intervals](https://docs.pyth.network/price-feeds/best-practices#confidence-intervals).
**Pyth smart contracts**
Pyth’s smart contracts are live on the Filecoin Mainnet and Calibration testnet.
| Name | Address | Mainnet | Calibration |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------- | ----------- |
| [Pyth - Mainnet](https://filecoin.blockscout.com/address/0xA2aa501b19aff244D90cc15a4Cf739D2725B5729?tab=contract) | `0xA2aa501b19aff244D90cc15a4Cf739D2725B5729` | ✔️ | |
| [Pyth - Calibration](https://calibration.filfox.info/en/address/0xA2aa501b19aff244D90cc15a4Cf739D2725B5729) | `0xA2aa501b19aff244D90cc15a4Cf739D2725B5729` | | ✔️ |
**Pyth x Filecoin Price Feed IDs**
Price Feed IDs for FIL are also available on various chains. These can be found at [Pyth - Price Feed IDs](https://pyth.network/developers/price-feed-ids) and search for 'FIL'.
#### **Further Pyth resources**
* [Pyth docs](https://docs.pyth.network/)
* [Pyth - Best Practices](https://docs.pyth.network/price-feeds/best-practices)
* [Pyth Benchmarks - historical price feeds](https://docs.pyth.network/metrics/)
### [Tellor](https://tellor.io/)
Tellor is an *optimistic* oracle. Builders should not accept instant price quotes and should wait a few minutes before locking in details.
Tellor supports a price feed oracle and a data oracle for the Filecoin network. The data oracle can provide Filecoin-specific data, such as the reputation of storage providers, which helps lending protocols determine interest rates for SPs.
**Tellor smart contracts**
Tellor’s smart contracts are live on the Filecoin Mainnet and Calibration testnet.
| Name | Address | Mainnet | Calibration |
| ---------------- | -------------------------------------------- | ------- | ----------- |
| Bridged TRB | `0x045CE60839d108B43dF9e703d4b25402a6a28a0d` | ✔️ | |
| Playground/TRB | `0x15e6Cc0D69A162151Cadfba035aa10b82b12b970` | | ✔️ |
| Oracle | `0xb2CB696fE5244fB9004877e58dcB680cB86Ba444` | ✔️ | ✔️ |
| Governance | `0xb55bB55f7D8b4F26Bd18198088C96488D95cab39` | ✔️ | ✔️ |
| Autopay | `0x60cBf3991F05a0671250e673Aa166e9D1A0C662E` | ✔️ | ✔️ |
| TellorFlex | `0xb2CB696fE5244fB9004877e58dcB680cB86Ba444` | ✔️ | ✔️ |
| QueryDataStorage | `0xf44166ca8bdB612268a4D401e4c5147968E5a190` | ✔️ | ✔️ |
| Multisig | `0x34Fae97547E990ef0E05e05286c51E4645bf1A85` | ✔️ | ✔️ |
#### **Further Tellor resources**
* [Tellor docs](https://docs.tellor.io/)
* [Filecoin Storage Insurance Contract](https://github.com/tellor-io/filecoin-query-insurance-impl/tree/main)
* [Getting Tellor Data for any use case](https://www.youtube.com/watch?v=AQIDqTLguyI) - FVM Dataverse Hackathon
### [eOracle](https://www.eoracle.io/)
eOracle extends Ethereum's trust to connect decentralized applications with off-chain data as the largest restaking protocol backed by over $5B of stake ETH through 120,000 stakers and over 110 validators distributed around the globe. eOracle provides reliable and secure on-chain price feeds, as well as custom data feeds.
**eOracle Smart Contracts**
eOracle's smart contracts are live on the Filecoin Calibration testnet.
| Name | Address | Mainnet | Calibration |
| ------------------------------ | -------------------------------------------- | ------- | ----------- |
| EOFeedManager | `0x4BCafd5f3fB32221BaEAF6B986d1449772885D1E` | | ✔️ |
| EOFeedAdapter - AUD/USD | `0x6243357B9241Fe9C3BAfbA79DeD3300a855113FA` | | ✔️ |
| EOFeedAdapter - BTC/USD | `0x705256d9B37950628F97A1a8De7Ab557345a0A80` | | ✔️ |
| EOFeedAdapter - ETH/USD | `0x2bada837140A310f4A1d9D0e7fab114da6b87031` | | ✔️ |
| EOFeedAdapter - EUR/USD | `0x7C01e105B9c3772Bc72ef55F450b9B96f81EDE82` | | ✔️ |
| EOFeedAdapter - FIL/USD | `0x335C47CF754cf7f5d6DF78EF9fAb065aa5988D89` | | ✔️ |
| EOFeedAdapter - GBP/USD | `0x2Af9bb239936aC3e5a35CC804CD09a8CF3B589e7` | | ✔️ |
| EOFeedAdapter - LINK/USD | `0x7E8326Fd75aCa5A7dF43E999A1119c392EDFC93a` | | ✔️ |
| EOFeedAdapter - SOL/USD | `0x7E3e2953d69890f6B7E5831144986113E9199593` | | ✔️ |
| EOFeedAdapter - USDT/USD | `0x30f43F80279b7BB1b9206896DB90Aabf69494c16` | | ✔️ |
| EOFeedAdapter - XAU/USD | `0x8609B3087D473cD2B6bc7674dD54FF13c909027f` | | ✔️ |
| EOFeedAdapter - sFRAX/FRAX | `0xd56f6CC400f3bFC77faeC4bBb1e0400c6A26A925` | | ✔️ |
| EOFeedAdapter - sfrxETH/frxETH | `0x626A1Cb309289Eb542710D6093C6341562769983` | | ✔️ |
| EOFeedAdapter - stETH/ETH | `0x0834Bb4baf2758a3642636C89D18F97ED6672D1C` | | ✔️ |
#### **Further eOracle resources**
* [eOracle GitHub](https://github.com/eoracle)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/advanced/oracles)
# Multicall
Multicall allows you to aggregate multiple contract reads into a single JSON-RPC request, and execute multiple state-changing calls in a single transaction on the FVM.
## Multicall3
[Multicall3](https://www.multicall3.com/) is a powerful tool that offers batch contract calls to smart contracts on the Filecoin Virtual Machine (FVM).
Multicall3 is deployed on over 100 chains at `0xcA11bde05977b3631167028862bE2a173976CA11`. A sortable, searchable list of all chains it's deployed on can be found [here](https://multicall3.com/deployments).
The [multicall3 ABI](https://multicall3.com/abi) can be downloaded or copied to the clipboard in various formats, including:
* Solidity interface.
* JSON ABI, prettified.
* JSON ABI, minified.
* [ethers.js](https://docs.ethers.org/v5/) human readable ABI.
* [viem](https://viem.sh/) human readable ABI.
Alternatively, you can:
* Download the ABI from the [releases](https://github.com/mds1/multicall/releases) page.
* Copy the ABI from [Etherscan](https://etherscan.io/address/0xcA11bde05977b3631167028862bE2a173976CA11#code).
* Install [Foundry](https://github.com/gakonst/foundry/) and run `cast interface 0xcA11bde05977b3631167028862bE2a173976CA11`.
### Contract address
Multicall has the same, precomputed address for all of the networks it is deployed on.
| Name | Address | Mainnet | Calibration |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------- | ----------- |
| [Multicall - Mainnet](https://filfox.info/en/address/0xcA11bde05977b3631167028862bE2a173976CA11?t=3) | `0xcA11bde05977b3631167028862bE2a173976CA11` | ✔️ | ❌ |
| [Multicall - Calibration](https://calibration.filscan.io/en/address/0xcA11bde05977b3631167028862bE2a173976CA11/) | `0xcA11bde05977b3631167028862bE2a173976CA11` | ❌ | ✔️ |
### Usage
To use Multicall3 to send batch contract read/write to your smart contract, you will need to:
1. Obtain the Multicall3 contract address for the network you're using (Filecoin mainnet or Calibration testnet).
2. Get the Multicall3 ABI, which can be downloaded or copied from various sources mentioned above.
3. Create an instance of the Multicall3 contract using a web3 library like ethers.js or viem.
4. Prepare your batch calls, including the target contract addresses, function selectors, and input data.
5. Use the appropriate Multicall3 method (e.g., `aggregate3` for multiple calls) to execute your batch operations.
6. Process the returned data from the Multicall3 contract.
The steps above differ slightly for integrations using smart contracts, where steps 2 and 3 are replaced with:
2. Import the Multicall3 interface in your smart contract.
3. Create a function that interacts with the Multicall3 contract using the imported interface.
Many libraries and tools such as [ethers-rs](https://docs.rs/ethers/latest/ethers/), [viem](https://viem.sh/), and [ape](https://apeworx.io/) have native Multicall3 integration which can be used in your projects directly. To learn how to use Multicall3 with these tools, check out [Multicall3 examples folder](https://github.com/mds1/multicall/blob/main/examples)
#### Batching Contract Reads
Batching contract reads, one of the most common use cases, allows a single `eth_call` JSON RPC request to return the results of multiple contract function calls. It has many benefits:
1. **Reduced JSON RPC Requests**: Multicall reduces the number of separate JSON RPC requests that need to be sent. This is particularly useful when using remote nodes, such as GLIF. By aggregating multiple contract reads into a single JSON-RPC request, Multicall (1) reduces RPC usage and therefore costs, and (2) reduces the number of round trips between the client and the node, which can significantly improve performance
2. **Consistent Data from the Same Block**: Multicall guarantees that all values returned are from the same block. This ensures data consistency and reliability, as all the read operations are performed on the same state of the blockchain.
3. **Detection of Stale Data**: Multicall enables the block number or timestamp to be returned with the read data. This feature helps in detecting stale data, as developers can compare the block number or timestamp with the current state of the blockchain to ensure the data is up-to-date.
When directly interacting with the Multicall3 contract to batch calls, you'll typically use the `aggregate3` method. This method allows you to execute multiple contract calls in a single transaction. Here's an explanation of how it works, along with examples:
1. Solidity Implementation: The `aggregate3` method is implemented in the Multicall3 contract like this:
```solidity
function aggregate3(Call3[] calldata calls) public payable returns (Result[] memory returnData) {
uint256 length = calls.length;
returnData = new Result[](length);
for (uint256 i = 0; i < length;) {
(bool success, bytes memory ret) = calls[i].target.call(calls[i].callData);
if (calls[i].allowFailure) {
returnData[i] = Result(success, ret);
} else {
require(success, "Multicall3: call failed");
returnData[i] = Result(true, ret);
}
unchecked { ++i; }
}
}
```
2. Example of sending multicalls to this smart contract: Here's an example using ethers.js to interact with the Multicall3 contract:
```javascript
const { ethers } = require("ethers");
const provider = new ethers.providers.JsonRpcProvider("https://api.node.glif.io/rpc/v1");
const multicallAddress = "0xcA11bde05977b3631167028862bE2a173976CA11";
const multicallAbi = [/* Multicall3 ABI */];
const multicall = new ethers.Contract(multicallAddress, multicallAbi, provider);
// Example: Batch balance checks for multiple addresses
async function batchBalanceChecks(addresses) {
const calls = addresses.map(address => ({
target: "0x...", // ERC20 token address
allowFailure: false,
callData: ethers.utils.id("balanceOf(address)").slice(0, 10) +
ethers.utils.defaultAbiCoder.encode(["address"], [address]).slice(2)
}));
const results = await multicall.aggregate3(calls);
return results.map(result => ethers.utils.defaultAbiCoder.decode(["uint256"], result.returnData)[0]);
}
batchBalanceChecks(["0x123...", "0x456...", "0x789..."]).then(console.log);
```
This example demonstrates how to use Multicall3 to batch multiple `balanceOf` calls for an ERC20 token in a single transaction, significantly reducing the number of separate RPC calls needed.
#### Batch Contract Writes
> :warning: Multicall3, while unaudited, can be safely used for batching on-chain writes when used correctly. As a stateless contract, it should never hold funds after a transaction ends, and users should never approve it to spend tokens.
When using Multicall3, it's crucial to understand two key aspects: the behavior of `msg.sender` in calls versus delegatecalls, and the risks associated with `msg.value` in multicalls.
In FVM, there are two types of accounts: Externally Owned Accounts (EOAs) controlled by private keys, and Contract Accounts controlled by code. The `msg.sender` value during contract execution depends on whether a CALL or DELEGATECALL opcode is used. CALL changes the execution context, while DELEGATECALL preserves it.
For EOAs, which can only use CALL, Multicall3's address becomes the `msg.sender` for subsequent calls. This limits its usefulness from EOAs to scenarios where **`msg.sender` is irrelevant**. However, contract wallets or other contracts can use either CALL or DELEGATECALL, with the latter preserving the original `msg.sender`.
The handling of `msg.value` in multicalls requires caution. Since `msg.value` doesn't change with delegatecalls, relying on it within a multicall can lead to security vulnerabilities. To learn more about this, see [here](https://github.com/runtimeverification/verified-smart-contracts/wiki/List-of-Security-Vulnerabilities#payable-multicall) and [here](https://samczsun.com/two-rights-might-make-a-wrong/).
## Hints
Lotus FEVM RPC supports Ethereum batch transactions. The key difference between `multicall` and batch transactions is that `multicall` aggregates multiple RPC requests into a single call, while batch transactions are simply an array of transactions executed sequentially but sent in one request. For more details, please refer to the [Ethereum documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc/batch).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/advanced/multicall)
# Multisig
Multisig wallets enhance security and decentralization by requiring multiple signatures for transactions, distributing control among multiple participants.
In the Filecoin network, multisig wallets allow multiple parties to jointly manage a wallet by requiring a predefined number of signatures (approvals) for a transaction to be executed. This enhances security and decentralization by distributing control among multiple participants.
Multisig wallets are an essential component of many blockchain applications, as they enable collaborative management of funds and application state. Users initiate a transaction to be signed by fellow collaborators. Once the required number of approvals is met, the transaction is executed.
Multisig wallets enable builders to integrate the following features into their projects:
* **Decentralized Governance**: Parties asynchronously approve transactions initiated by its members.
* **Security**: Distributing control among multiple participants ensures that no single party has full control over the wallet.
* **Collaborative fund management**: Multiple parties can jointly manage a wallet by requiring a predefined number of signatures (approvals) for a transaction to be executed.
## Available multisig wallet implementations
There are several multisig wallet implementations on Filecoin. Builders can integrate these multisig wallets into their applications today.
### Filecoin Native Multisig
The Filecoin Native [MultisigActor](/core-concepts/filecoin-virtual-machine/actors#multisigactor) is a built-in actor that does not interact directly with the Filecoin EVM. Like other Filecoin actors, native multisig addresses begin with `f2` and represent a group of transaction signers with a maximum of 256 signers. Signers may be external users or the MultisigActor itself and can include `f1` and `f3` [addresses](/core-concepts/filecoin-virtual-machine/addresses).
#### Filecoin Native Multisig UIs
* [Glif Multisig](https://www.glif.io/en/multisig/) is a non-custodial web UI for the Filecoin Native Multisig wallet
* [MultisigActor CLI](https://lotus.filecoin.io/lotus/manage/multisig/) can also be used and is available from the Lotus CLI
### Safe multisig
[Safe](https://safe.global/) is a popular smart EVM multisig account infrastructure provider that allows users to manage their digital assets securely and can be used with many popular EVM wallets. It is non-custodial, formally verified, secures over $100B in assets, and is used by more than 200 projects. Safe has been deployed to the Filecoin EVM.
#### Safe UI
A web UI for the Safe multisig on Filecoin is available at:
* - the default network is set to [Filecoin Mainnet](/networks-and-tools/networks/mainnet)
#### Safe Troubleshooting
* **Signing a transaction** from an account with no previous activity on the Filecoin blockchain will fail. You can send a transaction to this account with zero funds to initiate its on-chain activity to work around this issue.
* **Executing a transaction** can produce gas estimation issues for accounts that have a very small amount of funds (that would not or would barely cover the transaction).
* **Transaction confirmation times** may lead to prolonged "processing" status in the UI.
* **Safe addresses from other networks** can sometimes be used but require additional technical steps.
* In some cases the same Safe address and owner structure is not possible.
* Confirm complete creation (not just as a Placeholder) of the Safe multisig as an EVM contract on Filecoin prior to sending major funds.
* Instructions for deploying a Safe at the same address on another chain are available in [this video](https://share.zight.com/z8uBKZYr). Note that a compatible version of the Safe Proxy on the original chain must exist on Filecoin. Contact Safe-related support for help.
* If the previous address and chain use the L1 implementation of Safe Proxy, more complex technical migration steps will be required to map to the L2 version on Filecoin. Contact Safe-related support for more info.
* **Safe-related support** can be found in the "Need Help?" section of the Safe web UI.
#### Safe Transaction Service
The [Safe transaction service](https://docs.safe.global/core-api/api-safe-transaction-service) on Filecoin is available at:
* on [Filecoin Mainnet](/networks-and-tools/networks/mainnet)
* on [Filecoin Calibration testnet](/networks-and-tools/networks/calibration)
* Note:
* Faster finality is coming to Filecoin soon. For now, the Filecoin Safe transaction service sets `ETH_REORG_BLOCKS` to 60 blocks (i.e. Filecoin epochs) (30min) based on [FRC-0089](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0089.md) but users may want to wait 900 epochs (\~7.5h) for full finality.
#### Safe Smart Contracts
Safe’s multisig smart contracts are live on the Filecoin Mainnet and Calibration testnet.
| Name | Address | Mainnet | Calibration |
| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | ------- | ----------- |
| [SimulateTxAccessor](https://filecoin.blockscout.com/address/0x3d4BA2E0884aa488718476ca2FB8Efc291A46199) | `0x3d4BA2E0884aa488718476ca2FB8Efc291A46199` | ✔️ | ✔️ |
| [SafeProxyFactory](https://filecoin.blockscout.com/address/0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67) | `0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67` | ✔️ | ✔️ |
| [TokenCallbackHandler](https://filecoin.blockscout.com/address/0xeDCF620325E82e3B9836eaaeFdc4283E99Dd7562) | `0xeDCF620325E82e3B9836eaaeFdc4283E99Dd7562` | ✔️ | ✔️ |
| [CompatibilityFallbackHandler](https://filecoin.blockscout.com/address/0xfd0732Dc9E303f09fCEf3a7388Ad10A83459Ec99) | `0xfd0732Dc9E303f09fCEf3a7388Ad10A83459Ec99` | ✔️ | ✔️ |
| [CreateCall](https://filecoin.blockscout.com/address/0x9b35Af71d77eaf8d7e40252370304687390A1A52) | `0x9b35Af71d77eaf8d7e40252370304687390A1A52` | ✔️ | ✔️ |
| [MultiSend](https://filecoin.blockscout.com/address/0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526) | `0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526` | ✔️ | ✔️ |
| [MultiSendCallOnly](https://filecoin.blockscout.com/address/0x9641d764fc13c8B624c04430C7356C1C7C8102e2) | `0x9641d764fc13c8B624c04430C7356C1C7C8102e2` | ✔️ | ✔️ |
| [SignMessageLib](https://filecoin.blockscout.com/address/0xd53cd0aB83D845Ac265BE939c57F53AD838012c9) | `0xd53cd0aB83D845Ac265BE939c57F53AD838012c9` | ✔️ | ✔️ |
| [SafeL2](https://filecoin.blockscout.com/address/0x29fcB43b46531BcA003ddC8FCB67FFE91900C762) | `0x29fcB43b46531BcA003ddC8FCB67FFE91900C762` | ✔️ | ✔️ |
| [Safe](https://filecoin.blockscout.com/address/0x41675C099F32341bf84BFc5382aF534df5C7461a) | `0x41675C099F32341bf84BFc5382aF534df5C7461a` | ✔️ | ✔️ |
#### **Further Safe resources**
* [Safe Docs](https://docs.safe.global/home/what-is-safe)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/advanced/multisig)
# FEVM Indexers
FEVM Indexers allow users and developers to query Filecoin chain data in an extremely quick manner. Learn what FEVM indexers are available on Filecoin and how to use them through existing data provide
> *Not to be confused with* [*IPNI Indexer*](/provide-storage/architecture/network-indexer)
Blockchain indexers are used for accessing blockchain data efficiently. They process and organize storage-optimized raw blockchain data into retrieve-optimized and well-queryable formats. This benefits developers and users looking to retrieve specific information because they don't need to:
1. Run their own [archival node](/networks-and-tools/networks/mainnet/rpcs).
2. Parse entire blockchain histories to crawl for events that might not exist for thousands of [tipsets](/core-concepts/filecoin-virtual-machine/blocks-and-tipsets#tipsets).
3. Spend significant time required to retrieve data from the blockchain node.
4. Determine complex interconnections between smart contracts.
5. Spend substantial compute power to calculate advanced queries.
Additionally, blockchain indexers provide a better developer experience by leveraging well-known API standards and query languages like GraphQL.
## Goldsky
[Goldsky](https://goldsky.com/) offers high-performance subgraph hosting and real-time data indexing for blockchain data. These are GraphQL-based APIs built on top of smart contracts. With Goldsky, developers can access structured blockchain data quickly and efficiently without needing to run their own nodes or build custom indexing backends.
Goldsky officially supports the Filecoin, allowing developers to create subgraphs that index smart contract data from the Filecoin mainnet & testnet.
**Ways to Deploy a Subgraph with Goldsky**
**1. Goldsky Web App (No-Code)** A visual interface that guides you step-by-step to configure and deploy a subgraph. Ideal for quick prototyping or less technical users.
**2. Goldsky CLI (Developer Tooling)** A command-line interface for creating, editing, and deploying subgraphs programmatically.
* From Subgraph source code
* Migrating from The Graph or any other subgraph host
* Via instant, no-code subgraphs
In this tutorial, we will use no-code Goldsky’s deploy wizard to create a subgraph for the wFIl ERC-20 token on the Filecoin testnet.
### Prerequisites
Make sure you have the following tools and setup ready:
* Node.js
* Create a Goldsky account and generate a Goldsky API key
* Goldsky CLI installed
```shell
curl https://goldsky.com | sh
```
* Authenticate Goldsky CLI with your API key
```shell
goldsky login
```
* wFIl Contract information
* contract address: `0xaC26a4Ab9cF2A8c5DBaB6fb4351ec0F4b07356c4`
* [contract ABI](https://beryx.io/fil/calibration/address/0xaC26a4Ab9cF2A8c5DBaB6fb4351ec0F4b07356c4?tab=contract): saved it as `wfil_abi.json` locally.
### Deploy a subgraph
Goldsky’s Deploy Wizard simplifies the creation of subgraphs using a CLI-guided flow.
Run:
```shell
goldsky subgraph init
```
Follow the prompts from the Goldsky subgraph configuration wizard:
* *Subgraph name*: wfil-subgraph
* *Subgraph version*: 1.0.0
* *Subgraph target path*: Choose default or specify your own
* *Contract ABI source*: path/to/wfil\_abi.json
* *Contract Address*: `0xaC26a4Ab9cF2A8c5DBaB6fb4351ec0F4b07356c4`
* *Contract network*: filecoin-testnet
* *Start block*: Which block is the wfil created, can be 0.
* *Contract name*: wfil
* *Enable subgraph call handlers?*: no
Once you complete the above information following the prompt, the Goldsky wizard will guide you through building and deploying your subgraph. Once the subgraph is successfully deployed, Goldsky will output a deployment URL (GraphQL endpoint).
Indexing all the data for your smart contract will take time after the subgraph is deployed. You can also check the indexing status of your subgraph from the [Goldsky dashboard](https://app.goldsky.com/).
### Query the Subgraph
You can use the provided GraphQL endpoint to query the subgraph.
For example:
```graphql
{
transfers(
where: {from: "0xf49d33f54ce41354dcd7e698aa54256781a6dd30"}
orderBy: timestamp_
orderDirection: desc
first: 10
) {
id
from
to
amount
timestamp_
}
}
```
Use the Goldsky Playground or integrate it into your app to consume indexed data.
## The Graph
[The Graph](https://thegraph.com) is a decentralized protocol for indexing blockchain data. It enables developers to build and publish custom open APIs, known as subgraphs, that applications can query to retrieve blockchain data using GraphQL in a time-efficient manner.
#### Glossary
* **Subgraphs**: Customizable schemas that define how to index data from specific blockchain smart contracts and events.
* **GraphQL**: A query language that allows clients to request exactly the data they need, making data fetching more efficient.
#### Querying Subgraphs on Filecoin FEVM
There are many ways to query existing subgraphs, including numerous well-known libraries for [JavaScript](https://thegraph.com/docs/en/querying/querying-from-an-application/) and [Python](https://thegraph.com/docs/en/querying/querying-with-python/). But even without any third-party tooling, querying a subgraph is no more complicated than querying [RPC nodes](/reference/json-rpc). The only complexity is that you have to know the schema of the subgraph beforehand, similar to knowing SQL database tables and columns before being able to query them. Luckily, The Graph provides several ways to discover the subgraph schema. The most convenient one is called the ["Playground"](https://graphql.org/blog/2020-04-03-graphiql-graphql-playground/), and it is available upon a GET request to the subgraph query URL. Alternatively, you may use the discovery method that exists on every subgraph, called the [Introspection Query](https://graphql.org/learn/introspection/).
#### Developing Subgraphs on Filecoin FEVM
Developing a subgraph requires specialized knowledge that can be obtained through [The Graph Academy](https://thegraph.academy).
### Deploying Subgraphs
Just as with database data queried through SQL, subgraphs have to be stored somewhere. You may run a self-hosted instance as described in [The Graph Academy examples](https://thegraph.academy/developers/local-development/) and deploy a subgraph there. However, as with RPC nodes and databases, running subgraphs locally in production is not recommended from an uptime standpoint. For hosting the subgraph, it is reasonable to use online web services such as AWS or refer to professional subgraph providers such as [Protofire (aka Glif Nodes)](https://api.node.glif.io/graph).
#### Example: Deploying a Subgraph with Glif Nodes (Protofire)
[Protofire (aka Glif Nodes)](https://api.node.glif.io) offers public access to The Graph services, simplifying the process of deploying and managing subgraphs.
1. **Connect Your Wallet**
* On the [Protofire (Glif Nodes) platform - SUBGRAPHS](https://api.node.glif.io/graph), connect your [Filecoin-compatible wallet](/networks-and-tools/assets/wallets).
2. **Create an API Key**
* Choose the **API keys** tab.
* Click **Create new key**.
* Generate an API key to authenticate your requests.
3. **Activate Your Free Subscription**
* Go to the **Subscription** tab.
* If you have created a key, you will see one The Graph subscription pending.
* Click **Pay** and proceed with providing your credit card details to activate a free subscription.
{% hint style="warning" %}
Glif Nodes currently offers this service completely **free of charge**. If this ever changes, you will be notified at least one month in advance. It is recommended to provide your contact details on the Glif Nodes website to receive updates. Credit card details are used solely for DDoS protection. No charges will be made without prior notification.
{% endhint %}
4. **Create a Subgraph**
* Switch back to the **Subgraphs** tab.
* Click on **Create a New Subgraph** to set up a new subgraph instance.
5. **Manage Your Subgraphs**
* Select **MY** in the subgraphs switcher.
* Select the subgraph you just created to access deployment instructions and endpoints.
* Should you have any additional inquiries, do not hesitate to contact the Glif Nodes team through the **Contact us** button in the website header.
### Querying Existing Subgraphs
One of the popular subgraphs is a subgraph containing information about all the blocks on the network, essentially providing an alternative to the `eth_getBlock...` subset of commands. Let's see how we can query the `eth_getBlockByNumber` using the Linux command-line interface and the Protofire (Glif Nodes) platform.
* Visit the [Protofire (Glif Nodes) platform](https://api.node.glif.io).
* Navigate to the **SUBGRAPHS** tab.
* Select the relevant subgraph from [Protofire](https://api.node.glif.io/graph).
* In the opened **Playground** tab, click the **Show GraphQL Explorer** button (folder icon, 3rd from the top in the left bar) to verify the subgraph schema.
* Click the elements that you are looking to query and adjust the query if necessary. For the sake of this example, let's query the first block this subgraph supports (#2867000). The resulting query should look like the following:
```graphql
query MyQuery {
blocks(block: {number: 2867000}) {
number
id
timestamp
gasLimit
gasUsed
}
}
```
* Click **Execute query** (alternatively Ctrl+Enter, the icon with white triangle in the red square) and adjust query if needed.
```json
{
"data": {
"blocks": [
{
"number": "2867000",
"id": "0x2df02173a94343c971733e0c94b854dee9100fbd37c70d69956bf35bca7020da",
"timestamp": "1684316400",
"gasLimit": "70000000000",
"gasUsed": "24086592799"
}
]
}
}
```
* Copy **Queries (HTTP)** URL on the top of the Playground as well as resulting query to your code. The subgraph querying is free so far, although it requires an API key.
# Cross-chain bridges
Blockchain networks are often isolated and cannot interact with each other directly, so cross-chain bridges serve as a link between them and bring interoperability between different blockchains.
Cross-chain bridges have many use cases, such as enabling decentralized exchanges to support the trading of assets from multiple blockchain networks or allowing users to access decentralized applications (dApps) on different networks. They are also helpful for interoperability between separate blockchain networks, essential for the growth and adoption of blockchain technology.
## Available bridges
Regarding bridges, security is the top concern. The Filecoin team is focused on integrating with notary-based bridges that have a solid security model. Eventually, trustless light-client-based bridging solutions will be available.
### [Axelar](https://axelar.network/)
Axelar enables both token bridge and general message passing and is well-connected to major EVM chains & Cosmos ecosystem.
Initially, the bridge will support the following assets: wFIL, wETH, wBTC, USDC, and USDT.
#### **Axelar smart contracts**
Currently, Axelar supports Filecoin Mainnet.
| Name | Mainnet |
| ------- | -------------------------------------------- |
| wFIL | `0x60E1773636CF5E4A227d9AC24F20fEca034ee25A` |
| axlUSDC | `0xEB466342C4d449BC9f53A865D5Cb90586f405215` |
| axlUSDT | `0x7f5373AE26c3E8FfC4c77b7255DF7eC1A9aF52a6` |
| axlWBTC | `0x1a35EE4640b0A3B87705B0A4B45D227Ba60Ca2ad` |
| axlWETH | `0xb829b68f57CC546dA7E5806A929e53bE32a4625D` |
| axlDAI | `0x5C7e299CF531eb66f2A1dF637d37AbB78e6200C7` |
#### **Further Axelar resources**
* [Axelar docs for developers](https://docs.axelar.dev/dev/intro)
* [Axelar with Squid Router](https://app.squidrouter.com/)
* [Getting Started with Axelar on FVM Tutorial](https://www.youtube.com/watch?v=L7cw5FhxW4s)
### [Celer](https://cbridge.celer.network/1/314)
Celer is a blockchain interoperability protocol enabling a one-click user experience accessing tokens, DeFi, GameFi, NFTs, governance, and privacy solutions across multiple chains. Celer has been successfully supporting Filecoin on both assets bridging using it’s CBridge and messaging passing through Celer Inter-chain Messaging (Celer IM).
Initially, the bridge will support the following assets: wFIL, wETH, wBTC, USDC, and USDT.
### **Celer smart contracts**
Celar’s CBridge supports both Filecoin Mainnet and Calibration testnet.
| Name | Mainnet | Calibration |
| ---------- | -------------------------------------------- | -------------------------------------------- |
| wFIL | `0x60E1773636CF5E4A227d9AC24F20fEca034ee25A` | |
| ceUSDC | `0x2421db204968A367CC2C866CD057fA754Cb84EdF` | `0xf5C6825015280CdfD0b56903F9F8B5A2233476F5` |
| ceUSDT | `0x422849b355039bc58f2780cc4854919fc9cfaf94` | `0x7d43AABC515C356145049227CeE54B608342c0ad` |
| ceWBTC | `0x592786e04c47844aa3b343b19ef2f50a255a477f` | `0x265B25e22bcd7f10a5bD6E6410F10537Cc7567e8` |
| ceWETH | `0x522b61755b5ff8176b2931da7bf1a5f9414eb710` | `0x5471ea8f739dd37E9B81Be9c5c77754D8AA953E4` |
| MessageBus | `0x6ff2130fbdd2837b0c92d7f56f6c017642d84f66` | `0xd5818D039A702DdccfD11A900A40B3dc6DA03CEc` |
### **Further Celer resources**
* [cBridge docs](https://cbridge-docs.celer.network/)
* [Celer IM Docs](https://im-docs.celer.network/)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/advanced/cross-chain-bridges)
# Contract automation
Smart contract automation enables decentralized applications (dapps) to interact with both on-chain and off-chain data in an automated and trustless manner. Automation tools allow developers to build
In the Filecoin network, smart contracts benefit from a secure, deterministic environment. While this ensures reliability, it also limits direct access to external data sources. However, developers can leverage automation services to seamlessly connect off-chain data with on-chain smart contracts. This unlocks advanced capabilities such as price feeds, data verification, and much more, empowering Filecoin dapps with dynamic, real-world functionality by integrating external data into on-chain logic.
## Available automation services
### [Gelato](https://gelato.network/)
Gelato's Web3 Functions is a powerful automation system designed to streamline and enhance Web3 operations. Web3 Functions serve as a comprehensive tool, enabling developers to effortlessly set up, manage, and automate their smart contract tasks.
#### **How Gelato Web3 functions work?**
Web3 Functions can be triggered by various events and allow developers to write both off-chain logic (TypeScript) and on-chain logic (Solidity). Once deployed, they handle automated smart contract interactions, providing real-time monitoring and flexibility.
**Off-chain Data or Computation?** Sometimes, automation tasks require data that isn't readily available on the blockchain, or they might need computations that are better performed off-chain. In such cases, Typescript Functions should be the choice.
**All Checks On-chain?** If all the conditions necessary for your automation task can be directly verified on the blockchain, you have the option to select between Typescript Functions, Solidity Functions & Automated Transactions
## Triggers
1. Time Interval Use this trigger to execute tasks at regular intervals, e.g., every 10 minutes or once every 24 hours. It's like setting a straightforward, recurring alarm.
2. Cron Expressions This offers a more refined control compared to the Time Interval. With cron expressions, you can set tasks to run at specific moments, such as "every Tuesday at 3 PM" or "on the 1st of every month". It gives you precision in task scheduling.
3. On-Chain Event Ideal for those wanting their tasks to respond dynamically to blockchain activities. Whenever a specified event occurs on the blockchain, this trigger springs your task into action. It's like a vigilant watcher, always ready to act.
4. Every Block This function operates with the rhythm of the blockchain itself, executing your chosen function each time a new block is created.
## What to Execute?
### Typescript Functions
Typescript Functions are decentralized cloud functions that work similarly to AWS Lambda or Google Cloud, just for web3. They enable developers to execute on-chain transactions based on arbitrary off-chain data (APIs / subgraphs, etc) & computation. These functions are written in Typescript, stored on IPFS and run by Gelato.
### Solidity Functions
Solidity Functions are crucial for making on-chain tasks automatic and more efficient. They connect set conditions with specific actions in a smart contract, providing a straightforward method to turn user needs into automated processes. Consider them as a set of "if-then" rules: If certain conditions are met on the blockchain, then a specific function gets executed. This level of automation ensures that the decentralized application can operate with minimal manual intervention, providing a seamless user experience.
### Automated Transaction
Automated Transaction ensures that a specific function on the target smart contract gets reliably triggered. When you pre-define the inputs, it means that every time Gelato initiates the function call, it uses consistent, predetermined arguments.
#### **What is dedicatedMsgSender?**
For security reasons, during task creation, you will see an address that acts as the msg.sender for your task executions. This address is a proxy contract deployed by Gelato. It ensures that every task execution on behalf of your contract uses this dedicated msg.sender address, which is essential for validating the origin of the task.
## Quick Start
### Writing and deploying TypeScript functions
1. Clone Gelato's maintained Web3 Functions template:
```bash
git clone https://github.com/gelatodigital/web3-functions-template.git
```
2. Change into the template directory and install dependencies:
```bash
cd web3-functions-template && yarn install
```
3. Update `index.ts` in one of the examples.
The following TypeScript block is a skeleton only. It shows the shape of a Gelato Web3 Function that checks whether an oracle should be updated, then returns encoded call data. Replace the oracle ABI, input arguments, and off-chain data lookup with your application's logic. For maintained end-to-end examples, use the [Gelato Web3 Functions template](https://github.com/gelatodigital/web3-functions-template) and the [Gelato TypeScript Functions guide](https://docs.gelato.cloud/web3-functions/how-to-guides/write-typescript-functions/getting-started).
```typescript
import { Web3Function, Web3FunctionContext } from "@gelatonetwork/web3-functions-sdk";
import { Contract } from "@ethersproject/contracts";
const ORACLE_ABI = [
"function lastUpdated() external view returns (uint256)",
"function updatePrice(uint256)",
];
Web3Function.onRun(async (context: Web3FunctionContext) => {
const { userArgs, multiChainProvider } = context;
const provider = multiChainProvider.default();
const oracleAddress =
(userArgs.oracle as string) ?? "0x71B9B0F6C999CBbB0FeF9c92B80D54e4973214da";
const oracle = new Contract(oracleAddress, ORACLE_ABI, provider);
const lastUpdated = Number(await oracle.lastUpdated());
const latestBlock = await provider.getBlock("latest");
const nextUpdateTime = lastUpdated + 300;
if (!latestBlock || latestBlock.timestamp < nextUpdateTime) {
return { canExec: false, message: "Time not elapsed" };
}
const price = Number(userArgs.price ?? 0);
if (!Number.isFinite(price) || price <= 0) {
return { canExec: false, message: "No valid price supplied" };
}
return {
canExec: true,
callData: [
{
to: oracleAddress,
data: oracle.interface.encodeFunctionData("updatePrice", [price]),
},
],
};
});
```
4. Test and deploy the Web3 Function to IPFS:
```bash
npx w3f test web3-functions/YOUR-FUNCTION/index.ts --logs
npx w3f deploy web3-functions/YOUR-FUNCTION/index.ts
```
Example output:
```
✓ Web3Function deployed to IPFS.
✓ CID:
```
Finally, go to the [Gelato App](https://app.gelato.cloud), create a new task, decide on the trigger, and input the CID.
For a detailed guide on creating and deploying Web3 Functions, including setting up your development environment, triggers, and security configurations, see the [Gelato Web3 Functions docs](https://docs.gelato.cloud/web3-functions/how-to-guides/write-typescript-functions/getting-started).
#### **Further Resources**
* [Gelato Web3 Functions Docs](https://docs.gelato.cloud/web3-functions/how-to-guides/write-typescript-functions/getting-started)
* [Gelato Web3 Functions template](https://github.com/gelatodigital/web3-functions-template)
* [Gelato Web3 Functions examples](https://github.com/gelatodigital/how-tos-3-w3f-triggers)
# Relay
Relay is a service that allows users to interact with the Filecoin network using meta transactions. Users can submit transactions to the network without having to pay gas fees. Instead, a relayer pays
## Meta Transactions
Meta transactions are a type of transaction that allows users to interact with the Filecoin network without having to pay for gas fees. Instead, a third party, known as a relayer, pays the gas fees on behalf of the user. This enables users to interact with the network without having to hold FIL tokens or manage their own wallets.
## Available relayers
Relayer support and contract addresses change over time. Before deploying a Filecoin Mainnet or Calibration integration, verify that your target network is listed in the relayer's current supported-network documentation and use the current trusted forwarder or relay contract address for that network.
### [Gelato](https://gelato.network/)
Relay services, like Gelato Relay, act as intermediaries that handle the submission of meta-transactions to the blockchain. By integrating relay contracts (such as GelatoRelayContext or ERC2771Context) into a smart contract, developers can enable gasless transactions. This allows users to interact with decentralized applications without holding native tokens, while maintaining security through features like EIP-712 signature validation.
The relayer ensures the transaction is executed securely and promptly, handling the gas fee payment either off-chain (via a sponsor) or on-chain (with the user’s funds). This system simplifies blockchain interactions, broadening accessibility and reducing friction for dapp users.
### Use cases
* Highlight.xyz: Allows users to mint NFTs without incurring gas fees.
* ZED RUN: Automates breeding processes for digital racehorses.
* Reya: Enable gasless trading on the platform
#### Off-chain and on-chain payments
Transactions can be paid for in two primary ways: off-chain payments and on-chain payments. Each method offers flexibility depending on how developers wish to handle transaction fees for their users.
**Off-chain payments**
* **SponsoredCallERC2771**: In this method, Gelato uses the ERC-2771 meta-transaction standard to allow gasless transactions. The user signs a message, and the relay service covers the gas fees. ERC-2771Context ensures that the user’s identity is verified off-chain, by encoding the user’s address in the last 20 bytes of the transaction. This provides a secure, gasless experience where Gelato, using its 1Balance, sponsors the transaction fee.
* **SponsoredCall**: When there is no need for ERC-2771's off-chain signature verification, this more flexible method can be used. The transaction fees are still covered by the sponsor using 1balance, but the responsibility for managing security measures such as signature validation and replay protection lies with the project. This option is ideal for use cases that already have built-in security mechanisms.
**On-chain payments**
* **callWithSyncFeeERC2771**: This method combines ERC-2771 meta-transaction functionality with Gelato’s SyncFee model. The user’s gas fee is calculated and paid directly from the smart contract during the transaction execution. Gelato’s Fee Oracle estimates the fee in real-time, and the GelatoRelayContext contract automatically handles the fee transfer. This is ideal for developers who want to maintain user signature verification while ensuring users cover their transaction costs.
* **callWithSyncFee**: This method is similar to callWithSyncFeeERC2771 but without the need for ERC-2771’s off-chain signature verification. The user’s gas fee is calculated and paid directly from the target smart contract during the transaction execution. This approach is useful for applications where users are expected to pay for their own gas without requiring meta-transaction features.
### Implementation
We will require three simple steps to implement Gelato Relay. Here, we are going to showcase the three steps required to implement the method `sponsoredCallERC2771`, which is the most used one.
#### Step 1: Inherit Context Contract
Depending on the method, you must inherit different contracts as they will provide other methods. In this case, we will have to inherit the `ERC2771Context`. The `ERC2771Context` provides us with the methods `_msgSender()` and `_msgData()` that will allow us to recover the original user sending the transaction.
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.17;
import {
ERC2771Context
} from "@gelatonetwork/relay-context/contracts/vendor/ERC2771Context.sol";
contract CounterERC2771 is ERC2771Context {
mapping(address => uint256) public contextCounter;
event IncrementContextCounter(address indexed account, uint256 value);
// ERC2771Context: setting the immutable trustedForwarder variable
constructor(address trustedForwarder) ERC2771Context(trustedForwarder) {}
function incrementContext() external {
address sender = _msgSender();
uint256 nextValue = contextCounter[sender] + 1;
// Incrementing the counter mapped to the _msgSender!
contextCounter[sender] = nextValue;
// Emitting an event for testing purposes
emit IncrementContextCounter(sender, nextValue);
}
}
```
#### Step 2: Import the relay SDK
In your frontend or backend, import and instantiate the relay class. For ERC-2771 calls, deploy your contract with the trusted forwarder for the relay method and network you are targeting. Check Gelato's [supported networks](https://docs.gelato.cloud/relay/additional-resources/supported-networks) page before deploying.
```typescript
import {
GelatoRelay,
type CallWithERC2771Request,
} from "@gelatonetwork/relay-sdk";
const relay = new GelatoRelay();
```
#### Step 3: Send the payload to Gelato
This is a TypeScript skeleton for sending a `sponsoredCallERC2771` request. Replace the counter address, trusted forwarder, and API key with values for your deployed contract and supported target network.
```typescript
import { ethers } from "ethers";
// Set up on-chain variables, such as target address
const counter = "0x00172f67db60E5fA346e599cdE675f0ca213b47b";
const abi = ["function incrementContext() external"];
const apiKey = process.env.NEXT_PUBLIC_GELATO_RELAY_API_KEY;
if (!apiKey) {
throw new Error("Missing Gelato Relay API key");
}
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const user = await signer.getAddress();
// Generate the target payload
const contract = new ethers.Contract(counter, abi, signer);
const { data } = await contract.incrementContext.populateTransaction();
// Populate a relay request
const request: CallWithERC2771Request = {
chainId: (await provider.getNetwork()).chainId,
target: counter,
data,
user,
};
// Without a specific API key, the relay request will fail!
// Go to https://app.gelato.cloud to get an API key with 1Balance funding.
// Send a relay request using Gelato Relay!
const relayResponse = await relay.sponsoredCallERC2771(request, provider, apiKey);
```
#### Further Gelato resources
* [Gelato Relay Docs](https://docs.gelato.cloud/relay/erc2771-recommended/sponsoredcall-erc2771)
* [Gelato Supported Networks](https://docs.gelato.cloud/relay/additional-resources/supported-networks)
* [GitHub Repository](https://github.com/gelatodigital/how-tos-5-6-7-8-relay-intro-methods)
# Decentralized databases
Learn how to store the application data with a decentralized database on Filecoin.
### Store data with Tableland
Tableland is a **decentralized database** built on the SQLite engine, which offers developers a web3-native, relational database that seamlessly integrates into their EVM-compatible stacks. Under the hood, Tableland records database tables as ERC721 tokens on-chain and enables the execution of SQL statements in a completely decentralized manner through on-chain smart contracts.
To learn more about what is tableland and how to use it, you can visit .
#### **Ingredients**
Ensure that you install and import the necessary dependencies in your projects.
* [Tableland](https://tableland.xyz/)
* [`@tableland/evm`](https://www.npmjs.com/package/@tableland/evm)
* [`@tableland/sdk`](https://www.npmjs.com/package/@tableland/sdk)
* [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts/5.x/)
#### **Instructions**
Let's take storage deal aggregation as an example to demonstrate how to integrate it with Tableland.
When uploading data via storage aggregation providers to the Filecoin network, you can choose to store its metadata in Tableland tables instead of storing it in the chain state. This metadata can then be easily accessed from the Tableland database and utilized directly within your application.
If you require sample datasets to use, you can use the [Filecoin Dataset Explorer](https://datasets.filecoin.io/).
As an example, let's design the deal aggregator table as follows. You can add more columns to this table to include additional aggregation metadata.
| column | data Type |
| --------- | ------------ |
| ID | int |
| CID | bytes/string |
| deal\_ID | int |
| miner\_ID | int |
| status | string |
1. **Create aggregator table**
To track all deal aggregation requests submitted to the smart contract, we need to create a database table. The following Solidity excerpt assumes the contract imports `SQLHelpers`, `TablelandDeployments`, and OpenZeppelin's `Strings` utility. It creates an aggregator table in the contract constructor so the deployed contract owns the table.
```solidity
import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
import {SQLHelpers} from "@tableland/evm/contracts/utils/SQLHelpers.sol";
import {TablelandDeployments} from "@tableland/evm/contracts/utils/TablelandDeployments.sol";
uint256 private _tableId;
string private constant _TABLE_PREFIX = "aggregator_table";
constructor() {
_tableId = TablelandDeployments.get().create(
address(this),
SQLHelpers.toCreateFromSchema(
"id integer primary key, cid text, deal_id integer, miner_id integer, status text",
_TABLE_PREFIX
)
);
}
```
2. We will create an `insert` function within the smart contract to add a record whenever an aggregation request is made.
```solidity
function insertRecord(uint256 id, string memory cid, string memory status) internal {
TablelandDeployments.get().mutate(
address(this), // Table owner, i.e., this contract
_tableId,
SQLHelpers.toInsert(
_TABLE_PREFIX,
_tableId,
"id,cid,status",
string.concat(
Strings.toString(id),
",",
SQLHelpers.quote(cid),
",",
SQLHelpers.quote(status)
)
)
);
}
```
Whenever the `submit` function is called, a record will be inserted into the aggregator table instead of being stored in the blockchain's state.
```solidity
function submit(string calldata cid) external returns (uint256) {
// Increment the transaction ID
transactionId++;
// Save the CID record to aggregator_table
insertRecord(transactionId, cid, "PROPOSED");
// Emit the event
emit SubmitAggregatorRequest(transactionId, cid);
return transactionId;
}
```
3. We create an `updateRecord` function to modify an aggregator record once the `complete` function is called after the storage deal has been made on the Filecoin network.
```solidity
function updateRecord(
uint256 id,
uint256 dealId,
uint256 minerId,
string memory status
) internal {
string memory setters = string.concat(
"deal_id=",
Strings.toString(dealId),
",miner_id=",
Strings.toString(minerId),
",status=",
SQLHelpers.quote(status)
);
string memory filters = string.concat("id=", Strings.toString(id));
TablelandDeployments.get().mutate(
address(this),
_tableId,
SQLHelpers.toUpdate(_TABLE_PREFIX, _tableId, setters, filters)
);
}
```
After SP finishes publishing the storage deal on-chain to include an aggregation request, a callback function `complete` will be called to notify the contract that a CID is packed into a storage deal. Then we can call `updateRecord` to update the details for this CID record in the Tableland database. This is an excerpt from the broader aggregator contract; keep your existing proof verification and return-data logic around the table update.
```solidity
function complete(
uint256 id,
uint64 dealId,
uint64 minerId,
InclusionProof memory proof,
InclusionVerifierData memory verifierData
) external returns (InclusionAuxData memory) {
// Verify proof and update the storage-deal state.
InclusionAuxData memory auxData;
updateRecord(id, dealId, minerId, "FINISHED");
// Return the verifier data required by the full aggregator contract.
return auxData;
}
```
4. **Query aggregation records**
By using the Tableland SDK, you can query the aggregation status of all data stored with the aggregator using SQL statements. For instance, you can retrieve all records associated with a specific CID by executing a SELECT statement.
```typescript
import { Database } from "@tableland/sdk";
const db = new Database();
const tableName = "aggregator_314159_123";
const cid = "bafy...";
const { results } = await db
.prepare(`SELECT * FROM ${tableName} WHERE cid = ?1`)
.bind(cid)
.all();
console.log(results);
```
To learn how to write different select statements using Tableland SDK, see the [Tableland prepared statements guide](https://docs.tableland.xyz/sdk/database/prepared-statements). For current Solidity helper signatures, use the [Tableland SQL helpers library](https://docs.tableland.xyz/smart-contracts/sql-helpers).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/advanced/decentralized-databases)
# Privacy & Access Control
Reference-only guide to official privacy and access-control resources for data stored on Filecoin.
{% hint style="info" %}
This page is reference-only.
We do not maintain step-by-step third-party privacy/access-control tutorials in Builder Cookbook. Use the official resources below for implementation details.
{% endhint %}
### Encrypting data for storing on Filecoin
Use these official references for encryption workflows and secure upload patterns:
* [Lighthouse encryption docs](https://docs.lighthouse.storage/how-to/upload-encrypted-data)
* [Lighthouse access-control conditions](https://docs.lighthouse.storage/how-to/encryption-features/access-control-conditions)
* [Lighthouse SDK docs](https://docs.lighthouse.storage)
When building production flows, validate key management, signer auth, and recovery procedures in your own threat model.
### Gated access to your dataset
For condition-based access control and policy design:
* [Lighthouse access-control docs](https://docs.lighthouse.storage/how-to/encryption-features/access-control-conditions)
* [Filecoin smart contracts best practices](/build-on-filecoin/developing-contracts/best-practices)
* [Built-in actors reference](/reference/built-in-actors)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/cookbook/data-storage/privacy-and-access-control)
# Cookbook
Task-focused guidance for building on Filecoin. Each page points you to the official, actively maintained tools and resources for a specific task, rather than duplicating third-party tutorials that drift out of date. The Filecoin Pin pages include full step-by-step walkthroughs.
## Table of contents
* [Store data](/build-on-filecoin/cookbook/store-data) — recipes for programmable storage of public or private data on Filecoin
* [Retrieve data](/build-on-filecoin/cookbook/retrieve-data) — recipes for fetching stored data from the network
* [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin) — recipes for using Filecoin Pin to store and retrieve data on Filecoin Onchain Cloud
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/cookbook)
# Store data
Reference-only guide to official storage onboarding resources for Filecoin data storage workflows.
{% hint style="info" %}
This page is reference-only.
We do not maintain step-by-step third-party storage tutorials in Builder Cookbook. Use the official resources below for implementation details.
{% endhint %}
### Prepare data for Filecoin storage
Use these resources to prepare CAR artifacts and storage inputs:
* [Lighthouse documentation](https://docs.lighthouse.storage/)
* [go-car command-line tooling](https://github.com/ipld/go-car)
* [IPLD CAR specification and JavaScript libraries](https://github.com/ipld/js-car)
* [IPFS Desktop / Kubo docs](https://docs.ipfs.tech/)
Recommended outputs before proposing storage workflows:
* Piece CID / Payload CID
* CAR size and piece size
* A durable retrieval URL or CID
### Store large data with Filecoin Onchain Cloud
Use the FOC stack for programmatic, verifiable storage at scale:
* [Filecoin Onchain Cloud overview](/build-on-filecoin/filecoin-onchain-cloud)
* [FOC quickstart and Synapse docs](/build-on-filecoin/filecoin-onchain-cloud/synapse-quickstart)
* [FOC developer guides](https://docs.filecoin.cloud/developer-guides)
* [PDP documentation](/provide-storage/pdp)
* [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss) for archives and datasets of 1 TiB and up
### Store small data with storage onramps
For smaller datasets and managed ingestion paths:
* [Storage onramps overview](/getting-started/how-storage-works/storage-onramps)
* [Filecoin Pin getting started](/build-on-filecoin/cookbook/filecoin-pin/getting-started)
* [Lighthouse documentation](https://docs.lighthouse.storage/)
### Monitor storage deal status from a smart contract
For actor-level deal status lookups and contract integration references:
* [Built-in actors overview](/reference/built-in-actors)
* [Protocol API reference](/reference/built-in-actors/protocol-api)
* [Filecoin.sol reference](/reference/built-in-actors/filecoin.sol)
### Incentivized data storage
For incentive design and onboarding programs:
* [Filecoin Data Onboarding](https://dataonboarding.filecoin.io/)
* [Filecoin storage market basics](/getting-started/what-is-filecoin/storage-market)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/cookbook/store-data)
# Retrieve data
Reference-only guide to official retrieval resources for accessing data stored on Filecoin.
### Retrieve data using retrieval clients
To retrieve data stored on the Filecoin network, the basic process involves making retrieval requests to storage providers or IPFS peers using the root Content ID (CID) for the data.
Filecoin retrieval clients handle provider discovery and transport selection behind the scenes. Provide the root CID, and the client returns the data through a command-line interface or a library integration.
#### **Ingredients**
With a given CID, you can use the following maintained retrieval tooling:
* [Lassie](https://github.com/filecoin-project/lassie): retrieves IPFS and Filecoin content over the best available protocols.
* [go-car](https://github.com/ipld/go-car): reads, lists, and extracts content-addressed archive (CAR) files.
#### **Instructions**
**Retrieving content with Lassie**
Install the current Lassie and go-car command-line tools. Make sure [Go](https://go.dev/doc/install) is installed and that your Go binary directory is on your `PATH`, or download the latest binaries from the [Lassie releases](https://github.com/filecoin-project/lassie/releases/latest) and [go-car releases](https://github.com/ipld/go-car/releases/latest):
```sh
go install github.com/filecoin-project/lassie/cmd/lassie@latest
go install github.com/ipld/go-car/cmd/car@latest
```
Lassie fetches content in CAR form. Stream the CAR to go-car when you want to extract the UnixFS files immediately:
```sh
lassie fetch -o - | car extract -
```
To save the CAR for later inspection or extraction:
```sh
lassie fetch -p -o .car
car ls -f .car
car extract -f .car
```
For example:
```sh
lassie fetch -o - bafybeic56z3yccnla3cutmvqsn5zy3g24muupcsjtoyp3pu5pm5amurjx4 | car extract -
```
For library integrations, use the current [Lassie Go library documentation](https://github.com/filecoin-project/lassie?tab=readme-ov-file#golang-library) instead of copying an example from this reference page.
For quick retrieval of existing datasets with the methods above, check out the [Filecoin Dataset Explorer](https://datasets.filecoin.io/).
* [Filecoin Dataset Explorer](https://datasets.filecoin.io/)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/cookbook/retrieve-data)
# Real World Assets (RWAs)
Verifiable data infrastructure for tokenized assets. Connect onchain assets to the offchain records they depend on using IPFS + Filecoin to make deeds, appraisals, certifications and other source data
Connect onchain assets to the offchain records they depend on. Use IPFS + Filecoin to make deeds, appraisals, certifications and other source data durable, content-addressed and independently verifiable.
* [Explore the working demo →](https://sgtpooki.github.io/Avalanche-IPFS-Filecoin-RWA-reference-Architecture/) (runs live on Avalanche Fuji and Filecoin Calibration; no wallet needed)
* [View implementation →](https://github.com/SgtPooki/Avalanche-IPFS-Filecoin-RWA-reference-Architecture)
## Your asset is onchain. Its source of truth usually isn't.
Tokenized assets rely on offchain records to establish what they represent. If those records live only in an issuer's database or cloud account, applications depend on that infrastructure to preserve the data unchanged.
IPFS + Filecoin give RWA applications a verifiable data layer: **IPFS identifies the exact content, Filecoin persistently stores it with cryptographic proofs, and your onchain application references the CID.**
## A hybrid architecture for real-world assets
| Component | What it does | Output |
| --------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| **RWA source record** | Deed, title, appraisal, certification, disclosure | The document |
| **IPFS** | Content-addresses the record | A CID (content identifier) derived from the bytes |
| **Filecoin** | Persists the underlying data | Verifiable storage, backed by cryptographic proofs |
| **Avalanche** | References the CID from the onchain asset or application | Onchain state and transactions |
The result is a durable link between an onchain asset and the exact offchain data it represents.
## How it works
1. **Store the source record.** An issuer adds an offchain asset record such as a deed, appraisal or certification.
2. **Create a content-addressed reference.** IPFS generates a CID derived from the content itself. If the record changes, its CID changes too.
3. **Persist it on Filecoin.** The referenced data is stored on Filecoin, giving durable storage backed by cryptographic proofs.
4. **Reference it from Avalanche.** The application records the CID alongside the relevant asset or transaction on Avalanche.
5. **Verify independently.** A third party retrieves the record and checks that it matches the CID the application referenced.
## See it in action: property record
The [working example](https://sgtpooki.github.io/Avalanche-IPFS-Filecoin-RWA-reference-Architecture/) publishes a synthetic property record set for 123 Main Street: a deed, a survey, a parcel file and two tax assessments, issued by a county recorder. Each file is content-addressed with IPFS, stored on Filecoin, and listed in a manifest whose CID is anchored on Avalanche.
| Field | Value |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| Property | 123 Main Street, Fairview |
| Record type | Property deed |
| Parcel | 07-14-226-0031 |
| Issuer | Fairview County Recorder |
| IPFS CID of the deed | `bafkreidh5qsi5z6uo2thzvynr27ioajoviafqiveunrielhugyj65l6rzu` |
| Filecoin status | Persisted, with a current storage proof |
| Avalanche reference | [Registry on Fuji](https://testnet.snowtrace.io/address/0x7fdfdb7F166A3dEE947A5533e20B8E5Ce8c80863) |
| Verification | Retrieved record matches the referenced CID |
Press **Verify now** in the demo, or run it from a terminal with no key:
```sh
git clone https://github.com/SgtPooki/Avalanche-IPFS-Filecoin-RWA-reference-Architecture.git
cd Avalanche-IPFS-Filecoin-RWA-reference-Architecture
npm ci
npm run verify
```
## What happens if the record changes?
Because the CID is derived from the content, changing the underlying record produces a different identifier. Applications can therefore verify that the retrieved document is the exact record originally referenced.
| Document | CID |
| ------------------------------------- | ------------------------------------------------------------- |
| `deed.pdf` (original) | `bafkreidh5qsi5z6uo2thzvynr27ioajoviafqiveunrielhugyj65l6rzu` |
| `deed-tampered.pdf` (one line edited) | `bafkreiausintabvl4n4hvgv2jdmazvy35bg26gku2ufu2bosxhrd7dzxqi` |
In the demo, open **Check a document** and drop in either file. The file is hashed in your browser and never uploaded; the edited copy is reported as not a document of record.
## What each layer provides
| Layer | Role |
| --------------- | ---------------------------------------------------- |
| **Avalanche** | Asset state, transactions and the onchain reference |
| **IPFS** | Content addressing and integrity verification |
| **Filecoin** | Durable storage backed by cryptographic proofs |
| **Application** | Connects the onchain asset to its underlying records |
Verification here means that particular content was persisted and that the retrieved content matches its CID. None of these layers judges whether a deed is legitimate.
## Built for assets that depend on offchain truth
Real-world assets often depend on supporting data that cannot or should not be stored directly onchain. A content-addressed storage layer creates a durable connection between an onchain asset and those records without asking the blockchain itself to hold them.
* **Integrity.** Know whether the underlying record has changed.
* **Persistence.** Reduce dependence on a single application's database or cloud provider.
* **Portability.** Reference the same content-addressed data across applications and infrastructure.
### Example: tokenized real estate
A tokenized property can reference many offchain records throughout its lifecycle: deeds, parcel data, appraisals, inspections, certifications and disclosures. Rather than placing those documents directly onchain, an RWA platform can content-address them with IPFS, persist them on Filecoin, and reference their CIDs from its Avalanche application.
This reference implementation was developed to explore architectures for real-world asset platforms building on Avalanche.
## Build this pattern
Explore the implementation, run the demo, or adapt the architecture for your own RWA application.
* [View on GitHub](https://github.com/SgtPooki/Avalanche-IPFS-Filecoin-RWA-reference-Architecture)
* [Architecture: what is stored where](https://github.com/SgtPooki/Avalanche-IPFS-Filecoin-RWA-reference-Architecture#what-the-issuer-publishes)
* [Run the demo](https://github.com/SgtPooki/Avalanche-IPFS-Filecoin-RWA-reference-Architecture#verify-the-example)
* [Implementation guide](https://github.com/SgtPooki/Avalanche-IPFS-Filecoin-RWA-reference-Architecture#fork-map)
The implementation stores bytes with [Filecoin Onchain Cloud](https://docs.filecoin.cloud/) through the Synapse SDK, anchors a manifest pointer in a plain EVM registry contract on Avalanche, and verifies by re-hashing retrieved bytes and reading data set proof state. It builds on the [Avalanche and Filecoin data bridge](https://www.avalanche.com/about/blog/avalanche-and-filecoin-launch-cross-chain-data-bridge-for-scalable-web3) announced in May 2025.
## Building real-world assets on Avalanche?
We're looking for RWA teams interested in applying this architecture to production data and helping shape the next generation of Filecoin + IPFS tooling.
* [Talk to the Filecoin team](https://filecoin.cloud/contact)
* [View the implementation](https://github.com/SgtPooki/Avalanche-IPFS-Filecoin-RWA-reference-Architecture)
### About the demo
This open-source demo application was created to illustrate the reference architecture. The property in the example is synthetic.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/build/cookbook/rwa-reference-architecture)
# Filecoin Pin
Pin IPFS content to Filecoin using familiar IPFS tools and workflows.
{% hint style="success" %}
**Production-ready on Filecoin Mainnet**
Filecoin Pin is live on Filecoin Mainnet and ready for use. Register for product updates and announcements at [filecoin.cloud](https://filecoin.cloud/).
{% endhint %}
## What is Filecoin Pin?
Filecoin Pin is a fully decentralised persistence layer for IPFS content, backed by the global network of Filecoin storage providers and cryptographic proofs of storage.
When you pin content with Filecoin Pin, your IPFS data gains:
* **Verifiable persistence** - Storage providers must cryptographically prove daily that they continue to store and serve your data.
* **Economic incentives** - You only pay when storage proofs are successfully delivered and verified onchain.
* **Decentralised infrastructure** - Your data is stored across a global network of independent storage providers.
* **Sovereign data** - Choose your providers, audit storage proofs and payments onchain, with no dependency on a single company.
* **Seamless IPFS integration** - Keep using standard [IPFS Mainnet](https://docs.ipfs.tech/concepts/glossary/#mainnet) tooling like Kubo, Helia, and IPFS HTTP Gateways while gaining Filecoin's persistence guarantees.
## Who is Filecoin Pin for?
Filecoin Pin is for anyone who needs reliable, verifiable IPFS pinning:
* **People moving from another pinning service** - If you're coming from Storacha, Pinata, or any other IPFS pinning service, Filecoin Pin gives you a place to keep your IPFS content pinned and accessible.
* **Developers building on IPFS** - If you're building dApps, websites, AI agents, or other applications that rely on IPFS, Filecoin Pin provides the missing persistence layer with cryptographic guarantees.
{% hint style="info" %}
**Already have content pinned elsewhere?** This guide focuses on pinning new content. To move CIDs you already have pinned on Pinata, Storacha, or any public IPFS gateway onto Filecoin - without changing those CIDs - see [Migrating IPFS pins to Filecoin Onchain Cloud](/build-on-filecoin/cookbook/filecoin-pin/migrate-ipfs-pins).
{% endhint %}
## How to Get Started
The fastest path to pinning your first file is the **Getting Started** guide below. It walks you through installing the CLI, connecting your wallet, depositing storage credit, and pinning content - end to end.
1. [**Getting Started**](/build-on-filecoin/cookbook/filecoin-pin/getting-started) - Install Filecoin Pin and pin your first file in around 10 minutes. Start here.
2. [**Migrating IPFS pins to Filecoin Onchain Cloud**](/build-on-filecoin/cookbook/filecoin-pin/migrate-ipfs-pins) - Bring CIDs you have already pinned on IPFS onto Filecoin Onchain Cloud, unchanged.
3. [Filecoin Pin GitHub Actions](/build-on-filecoin/cookbook/filecoin-pin/github-action) - Automate pinning of websites or build artifacts as part of your CI/CD pipeline.
4. [Filecoin Pin dApp Demo](/build-on-filecoin/cookbook/filecoin-pin/dapp-demo) - Run or fork a demo dApp showing browser-based file uploads to Filecoin.
5. [Filecoin Pin for ERC-8004 Agents](/build-on-filecoin/cookbook/filecoin-pin/erc-8004-agent-registration) - Register a trustless autonomous agent on the ERC-8004 Identity Registry with verifiable persistent storage for agent metadata.
## Learn More
* [**FAQ**](/build-on-filecoin/cookbook/filecoin-pin/faq) - Common questions about Filecoin Pin.
* [**Filecoin Pin GitHub Repository**](https://github.com/filecoin-project/filecoin-pin) - Source code and technical documentation.
* [**Community and Support**](https://github.com/filecoin-project/filecoin-pin?tab=readme-ov-file#community-and-support) - Join the community for real-time developer support and updates.
# Getting Started
Install Filecoin Pin, connect your wallet, deposit storage credit, and pin your first file to Filecoin in around 10 minutes.
This guide walks you through pinning your first file to Filecoin using the Filecoin Pin CLI. By the end, you'll be set up to:
* ✅ Install the Filecoin Pin CLI
* ✅ Connect your Ethereum-style wallet on Filecoin
* ✅ Deposit storage credit on Filecoin Pay
* ✅ Pin a file to Filecoin and retrieve it using standard IPFS tooling
***
## 🚀 Prerequisites
Before starting, make sure you have:
* **An Ethereum-style wallet on Filecoin** - MetaMask is the easiest option. If you don't have one set up, see [Wallets](/networks-and-tools/assets/wallets) and [Metamask setup](/networks-and-tools/assets/metamask-setup).
* **FIL in your wallet** - to pay transaction gas fees on Filecoin.
* **USDFC in your wallet** - to pay for storage. USDFC is the stablecoin used by Filecoin Onchain Cloud. The easiest way to get some is to [swap FIL for USDFC on Sushi](https://www.sushi.com/filecoin/swap?token0=NATIVE\&token1=0x80b98d3aa09ffff255c3ba4a241111ff1262f045).
* **Node.js 24 or later** - the Filecoin Pin CLI runs on Node.js. Install from [nodejs.org](https://nodejs.org/) or via your package manager.
***
## 📦 Install the Filecoin Pin CLI
Install the CLI globally with npm:
```sh
npm install -g filecoin-pin@latest
```
Verify the installation:
```sh
filecoin-pin --version
```
To see all available commands at any time:
```sh
filecoin-pin --help
```
***
## 🔐 Connect your wallet
The Filecoin Pin CLI signs transactions using your wallet's private key. You provide it as an environment variable - the CLI reads it directly and never stores it on disk.
### 1️⃣ Export your private key from MetaMask
{% hint style="danger" %}
**Treat your private key like a password.** Anyone with your private key has full control of your wallet and any funds in it. Never paste it into a website, share it over chat, commit it to a repository, or store it in plain text on a shared system.
{% endhint %}
In MetaMask:
1. Open the MetaMask extension.
2. Click the three dots next to your account name.
3. Select **Account details**.
4. Click **Show private key**.
5. Enter your MetaMask password.
6. Copy the private key shown.
The private key is a 64-character hex string, with or without an `0x` prefix.
### 2️⃣ Save or export the private key
The Filecoin Pin CLI does not store your key, but a `.env` file is still a local file on disk. Use a private working directory, keep `.env` out of git, and delete the file when you no longer need it.
Create a file named `.env` in your working directory containing:
```sh
export PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"
```
Then secure it and load it into your shell:
```sh
printf '.env\n' >> .gitignore
chmod 600 .env
source .env
```
For a one-off shell session, you can avoid writing the key to disk and export it directly instead:
```sh
export PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"
```
***
## 💰 Set up payments
Filecoin Pin uses [Filecoin Pay](https://github.com/FilOzone/filecoin-pay) to manage storage payments. Before you can pin anything, you need to:
1. Authorise the Warm Storage Service contract to spend USDFC on your behalf.
2. Deposit USDFC into Filecoin Pay so storage providers can be paid.
The CLI walks you through both steps interactively.
```sh
filecoin-pin payments setup
```
The CLI will guide you through the following stages:
#### 1️⃣ Connect and check balances
The CLI confirms it can connect to Filecoin Mainnet and reports your wallet's FIL and USDFC balances.
{% hint style="info" %}
If you don't have enough FIL for gas or USDFC for storage, the CLI will tell you and stop. Top up your wallet and try again.
{% endhint %}
#### 2️⃣ Review pricing
The CLI shows current storage pricing per GiB per month and per TiB per month. Use this to estimate how much USDFC you want to deposit.
#### 3️⃣ Choose a deposit amount
The CLI asks: **"Would you like to deposit USDFC to enable storage?"** Answer **Yes**.
It then shows example monthly costs for common storage amounts (100 GiB, 1 TiB, 10 TiB) so you can pick a sensible deposit.
When prompted **"How much USDFC would you like to deposit?"**, enter the amount you want. A first-time deposit of `10.0` USDFC is a reasonable starting point.
{% hint style="info" %}
**Coming from Storacha?** Refer to the email we sent you for the specific USDFC amount we'd recommend depositing for your dataset size.
{% endhint %}
#### 4️⃣ Confirm the deposit
The CLI submits the deposit transaction onchain and shows the transaction hash and your new storage capacity.
{% hint style="success" %}
You should see something like:
```
✓ Deposit complete
Deposit tx: 0x1234...abcd
New Storage Capacity:
Total deposit: 10.00 USDFC
Capacity: ~XX GiB for 1 month
```
{% endhint %}
***
## 💵 Top up your runway (optional)
If you want to ensure your deposit covers a specific number of days at your current storage usage, run:
```sh
filecoin-pin payments fund --days 30
```
This deposits (or withdraws) the right amount of USDFC to give you exactly 30 days of runway based on what you're currently storing. You can use any number of days you like.
To check your current deposit balance, runway, and payment status at any time:
```sh
filecoin-pin payments status
```
***
## 📌 Pin your first file
Now you're ready to pin. Create a test file:
```sh
echo "Hello Filecoin Pin @ $(date)!" > demo.txt
```
Pin it to Filecoin:
```sh
filecoin-pin add demo.txt
```
The CLI will:
1. Pack your file into IPFS-compatible format (a CAR file).
2. Select storage providers automatically.
3. Store your file with two providers for redundancy.
4. Verify the upload was advertised to [IPNI indexers](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/glossary.md#ipni).
{% hint style="success" %}
You should see something like:
```
✓ File validated (20 B)
✓ Connected to Filecoin Mainnet
✓ File packed with root CID: bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
✓ IPFS content loaded (96 B)
━━━ Add Complete ━━━
Root CID: bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
Piece CID: bafkzcibcfab4grpgq6e6rva4kfuxfcvibdzx3kn2jdw6q3zqgwt5cou7j6k4wfq
Copies: 2/2
Add completed successfully
```
{% endhint %}
The **Root CID** is your IPFS Content Identifier - it's how you'll retrieve your data. Save it somewhere.
You can also pin a directory by passing the directory path instead of a file:
```sh
mkdir my-data
echo "File 1" > my-data/file1.txt
echo "File 2" > my-data/file2.txt
filecoin-pin add my-data/
```
***
## 🌐 Retrieve your file
Your file is now retrievable via standard IPFS tooling using its Root CID. For example:
```
https://.ipfs.inbrowser.link
```
Or via the dweb.link gateway:
```
https://dweb.link/ipfs/
```
Try opening one of those URLs in your browser - your file should load.
You can also retrieve it programmatically using any IPFS-compatible client (Kubo, Helia, Lassie, etc.) by referencing the Root CID.
***
## 🛡️ Inspect your storage proofs
Filecoin storage providers must cryptographically prove daily that they continue to store your data. You can inspect those proofs and the on-chain payment rails at any time.
List the data sets associated with your wallet:
```sh
filecoin-pin data-set list
```
Then get the full on-chain detail for a specific data set:
```sh
filecoin-pin data-set show
```
This queries the smart contracts directly, so the values are live blockchain state.
{% hint style="success" %}
You'll see something like:
```
Data Set #279 • live
Managed by Warm Storage: yes
Pieces stored: 2
Total size: 672.0 B
PDP rail ID: 631
Payer: 0xYOUR_WALLET_ADDRESS
Payee: 0xPROVIDER_ADDRESS
Provider
Provider: (ID )
Provider Service
Service URL: https://
Min proving period: 30 epochs
Pieces
#0
CommP: bafkzcib...
Root CID: bafybei...
```
{% endhint %}
Key things to look for:
* **Status: `live`** - your data set is active and being proved.
* **PDP rail ID** - your active storage-proof payment rail.
* **Min proving period** - how often the provider must submit a fresh proof.
* **Provider Service URL** - direct retrieval endpoint for your pieces.
* **CommP / Root CID** per piece - the piece CID is what the provider proves; the Root CID is what you use to retrieve.
***
## 🎉 You're Done!
You've successfully pinned your first file to Filecoin. You now have:
* ✅ The Filecoin Pin CLI installed and configured
* ✅ Your wallet connected with funded payments on Filecoin Pay
* ✅ Files pinned to two Filecoin storage providers with daily cryptographic proofs
* ✅ Your content retrievable via standard IPFS gateways
***
## 🔜 Next Steps
* 📖 Run `filecoin-pin --help` to explore advanced usage, including auto-funding and custom provider selection.
* 🔍 Want to understand what's happening behind the scenes? Read [Behind the Scenes of Adding a File](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/behind-the-scenes-of-adding-a-file.md) for a deep dive into each step.
* 🤖 Automate pinning in your CI/CD pipeline with the [Filecoin Pin GitHub Action](/build-on-filecoin/cookbook/filecoin-pin/github-action).
* 💬 Join the community in Filecoin Slack [#fil-foc](https://filecoinproject.slack.com/archives/C07CGTXHHT4) for help, discussion, and updates.
* 🐛 Found a bug or have a feature request? [Open an issue](https://github.com/filecoin-project/filecoin-pin/issues) on GitHub.
# Migrating IPFS pins to Filecoin Onchain Cloud
Move content you have already pinned on IPFS onto Filecoin Onchain Cloud without changing your CIDs.
IPFS2FOC exists to bring content you have already pinned on IPFS onto Filecoin Onchain Cloud. Once your existing CIDs are moved, everything you upload from then on should go through [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin).
***
## What is IPFS2FOC?
[**IPFS2FOC**](https://github.com/FilOzone/ipfs2foc) is a migration tool that seamlessly transfers content from IPFS to the Filecoin Onchain Cloud. It takes a list of CIDs you already have pinned - whether on a pinning service like Pinata or Storacha, or any public IPFS gateway - and commits that data directly to Filecoin storage providers.
Once migrated, your data is paid for onchain and backed by Filecoin's ongoing cryptographic proofs of possession, ensuring verifiable, long-term persistence.
{% hint style="info" %}
**IPFS2FOC is a bridge, and it is moving.** Bulk migration is actively being moved into a native `filecoin-pin migrate` subcommand, so that migrating an existing inventory and pinning new content end up in one tool. Until that lands, `ipfs2foc` is how you move an inventory across - [migrate from the command line](/build-on-filecoin/cookbook/filecoin-pin/migrate-ipfs-pins/command-line) is the path to use today.
{% endhint %}
### Key features and guarantees
* **Zero CID changes** - The defining property of IPFS2FOC is that your CIDs are immutable. The tool never re-encodes or re-chunks your data. Every object remains byte-for-byte identical to its original state.
* **Preserved links and embeds** - Because your original CIDs are preserved, every existing link, reference, app integration, and web embed you have already published keeps working without modification.
* **Identical retrieval** - After the migration, you continue to retrieve your content exactly as you always have: by its original CID, over standard IPFS networks and trusted gateways.
* **Verifiable onchain end state** - The end state of your migration is not a dashboard claim. Storage deals, provider commitments, and proofs of possession are verified directly against the Filecoin blockchain itself.
***
## Who is IPFS2FOC for?
IPFS2FOC is built for anyone who relies on IPFS for content addressing and wants to move that content wholesale onto Filecoin storage providers, for the verifiable durability, cryptographic guarantees, and decentralized backing they bring. That is the whole qualification - you have CIDs today, and you want all of them on Filecoin Onchain Cloud, migrated efficiently and resumably rather than one upload at a time.
It is a one-time tool. Once the existing IPFS content you care about is on Filecoin Onchain Cloud, IPFS2FOC is no longer needed.
{% hint style="info" %}
If you have no existing pins and simply want to start storing content on Filecoin, you do not need IPFS2FOC. Go straight to [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin).
{% endhint %}
### Primary use cases
* **Teams migrating pinning providers** - Built for teams offboarding from traditional pinning services. If your content is already public and addressable on IPFS, re-uploading everything one-by-one is inefficient, time-consuming, and may end up storing the content using different hashing algorithms, resulting in broken links. IPFS2FOC manages this process for you.
* **Projects with immutable CIDs** - Essential for projects where changing a content identifier is simply not an option, including:
* **NFT metadata and media** - Smart contracts referencing fixed IPFS URIs that cannot be edited.
* **Dataset releases and scientific archives** - Published research data that must remain byte-for-byte identical for citation and reproducibility.
* **Documentation sites and web apps** - Published links, static assets, and embeds that would break if re-hashed.
* **Permanent archives** - Long-term historical data where address stability is critical.
***
## IPFS2FOC and Filecoin Pin
These two tools are companions, and it is worth being precise about which does what.
| | IPFS2FOC | Filecoin Pin |
| ------------------- | ----------------------------------- | --------------------------- |
| **Purpose** | Move content already pinned on IPFS | Pin new content |
| **When you use it** | Once, during your transition | Every day, ongoing |
| **Input** | A list of CIDs you already have | Files you are uploading now |
The intended path is a single handoff:
1. Move your existing pins across with **IPFS2FOC**.
2. From that point forward, everything new goes through **Filecoin Pin**.
That handoff is being collapsed into one tool: as noted above, bulk migration is moving into the native `filecoin-pin migrate` subcommand.
***
## Where your content is fetched from
The migration reads each CID from an HTTPS gateway, and that gateway has to return content in a **verifiable** form - bytes that re-hash back to the CID being requested. A gateway that reassembles content into an ordinary file response cannot be used, because the storage provider re-validates what it receives before committing anything.
Support varies by pinning provider. Some serve the required format out of the box, some depend on per-bucket or per-account configuration, and one cannot be used as a source directly at all.
| Where your pins live today | Gateway to pass to `--gateway` | Works as a source? |
| -------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Pinata** | `https://gateway.pinata.cloud` | Yes. Both the shared gateway and dedicated `*.mypinata.cloud` hostnames. |
| **Public IPFS network** | `https://trustless-gateway.link` | Yes. A public, no-account trustless gateway, and the tool's default. |
| **Filebase** | `https://.myfilebase.com` | Depends on the bucket's gateway configuration - some buckets return reassembled files. Probe each bucket before you run. |
| **Storj** | A gateway-MT share link | Only with share links generated for raw or trustless linksharing. Default share links return landing pages and do not work. |
| **nft.storage (classic)** | `https://nftstorage.link` | Mixed. Behavior changed across their own migration, so probe the specific CIDs you care about. |
| **web3.storage (w3up)** | None per account | Not directly - there is no per-account gateway to target. You'll need to expose the same CIDs through a gateway you control. |
| **Self-hosted Kubo** | Your own HTTPS host | Yes, on a public hostname with valid TLS, with `Gateway.DeserializedResponses` set to `false`, and holding the CIDs locally. |
On w3up, your options are a self-hosted Kubo node, a Pinata account pinning the same CIDs, or `trustless-gateway.link` if the content is on the public IPFS network.
### Probe before you plan a run
Confirm a gateway serves your content before spending anything. Check a single CID with `ipfs2foc probe --gateway `, or pre-flight a whole list with `ipfs2foc analyze --cids cids.txt --gateway ` to get a pass rate.
| Result | What it means |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OK` | The gateway serves verifiable content for that CID. Use it - pass it with `--gateway` on every command in your run. |
| `WARN` | The gateway responded, but not with verifiable content. It cannot be a source - pick another row from the table above. |
| `FAIL` | The request did not complete at all. This covers everything from a DNS failure to a blocked TLS connection, and public gateways are not reachable from every network. Try another gateway before assuming your content is at fault. |
***
## How a migration works
Four stages, all driven by one command.
1. **Read** - For each CID, the tool fetches the content from a public IPFS gateway and computes its Filecoin piece commitment. Nothing is uploaded and nothing is charged at this stage; it is a measurement pass.
2. **Pack** - Many objects are bundled into larger pieces before any onchain commitments are made. This is what makes the migration affordable, as onchain cost scales with the number of *pieces*, not with the number of CIDs. Packing thousands of small IPFS files costs roughly the same in onchain confirmation fees as migrating a single file.
3. **Upload** - Your machine streams each packed piece directly to a storage provider. By default your data is stored across two storage providers for redundancy. The primary provider receives the initial upload directly from your machine, while the secondary provider automatically pulls its copy from the primary. The data is deleted from your local machine as soon as it is confirmed as stored with a Filecoin Onchain Cloud storage provider.
4. **Commit** - The new pieces are committed and recorded onchain in batches. Upon completion, the tool outputs a summary containing your Data Set IDs and direct Filecoin explorer links. Once committed, storage providers must continuously generate cryptographic Proofs of Data Possession (PDP) on a recurring schedule to remain eligible for automated onchain payment.
Data sets are created automatically during the run with IPFS indexing enabled, which is what keeps every original CID retrievable by its own identifier afterwards.
***
## Next steps
* [**Migrate from the command line**](/build-on-filecoin/cookbook/filecoin-pin/migrate-ipfs-pins/command-line) - the full walkthrough, from install through to onchain verification.
* [**Filecoin Pin**](/build-on-filecoin/cookbook/filecoin-pin) - where all your new uploads should go once the migration is done.
* [**IPFS2FOC on GitHub**](https://github.com/FilOzone/ipfs2foc) - source code and full command reference.
* [**IPFS to Filecoin**](https://filecoin.cloud/ipfs2filecoin) - check a CID list and estimate what a migration costs before you install anything.
# Migrate from the command line
Migrate your IPFS pins to Filecoin Onchain Cloud from the terminal with the ipfs2foc CLI. The recommended path for any serious migration.
The `ipfs2foc` CLI migrates your pins in a single command. It handles files of any size, scales to large inventories, and requires nothing about your machine to be reachable from the internet.
This is the recommended path for any serious migration.
{% hint style="info" %}
**`ipfs2foc` is a bridge.** This migration logic is actively being moved into a native `filecoin-pin migrate` subcommand. Everything on this page works today, but once that subcommand lands it becomes the supported path, and migrating will be one command inside the [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin) tool you already use for new uploads.
{% endhint %}
***
## What you need
* **Node.js 24 or newer.** Check with `node --version`.
* **A wallet** with FIL for gas and USDFC for storage. You will export its private key, so use one kept for this purpose.
* **A list of CIDs** to migrate.
* **Content that is fetchable from an IPFS gateway.** Support varies by pinning provider - check [Where your content is fetched from](/build-on-filecoin/cookbook/filecoin-pin/migrate-ipfs-pins#where-your-content-is-fetched-from) for yours.
The walkthrough below takes one CID end to end on Filecoin Mainnet. By the end you'll have measured a piece, uploaded it, committed it onchain, and confirmed it with `report`.
***
## Step 1: Install
```bash
npm install -g ipfs2foc
```
Confirm the install:
```bash
npm ls -g ipfs2foc
```
{% hint style="success" %}
You should see `ipfs2foc@0.8.1` or later.
{% endhint %}
***
## Step 2: Set your signing key
Export the private key of a Filecoin wallet funded with FIL and USDFC on Filecoin Mainnet. The key must be `0x` followed by 64 hex characters:
```bash
export PRIVATE_KEY=0x
```
Verify the format. This must print `66`:
```bash
echo ${#PRIVATE_KEY}
```
{% hint style="danger" %}
**This one key does everything.** It signs every transaction in the migration and authorizes spending from your deposited balance. Use a dedicated wallet funded with roughly what the migration needs. Never use a wallet holding significant funds, and never paste this key into a web page.
{% endhint %}
Keep this terminal open for the rest of the guide - the variable is lost when you close it.
***
## Step 3: Check your gateway
Before spending anything, confirm a gateway serves your content in the verifiable form the migration requires. Pick any one CID from your list:
```bash
ipfs2foc probe --gateway https://trustless-gateway.link
```
{% hint style="success" %}
A working gateway returns a line beginning `OK` and ending `deterministic`:
```
OK https://trustless-gateway.link — CAR 663286 bytes, sha256 86c15ec1…, deterministic
```
{% endhint %}
{% hint style="warning" %}
**Seeing `FAIL` or `fetch failed`? Try a different gateway before assuming your content is at fault.** Public gateways are not reachable from every network. Try your own pinning provider's gateway instead:
`ipfs2foc probe --gateway https://gateway.pinata.cloud`
{% endhint %}
Whichever gateway returns `OK` is the one to use - pass it with `--gateway` on every command below. For what `WARN` and `FAIL` each mean, and the gateway to use for your provider, see [Where your content is fetched from](/build-on-filecoin/cookbook/filecoin-pin/migrate-ipfs-pins#where-your-content-is-fetched-from).
***
## Step 4: Fund your account
Two currencies do two different jobs. **FIL** pays gas on your own transactions. **USDFC** pays storage providers.
Confirm you have a sufficient balance before going further:
```bash
npx filecoin-pin@latest payments status
```
You should see a positive USDFC balance with approvals in place.
{% hint style="warning" %}
**Deposit a comfortable margin.** If your balance or allowance falls short, the migration fails at the commit stage, and the error may not tell you how much more is needed.
{% endhint %}
***
## Step 5: Build your CID list
One CID per line in a plain text file. Blank lines and lines beginning with `#` are ignored:
```bash
cat > cids.txt <<'END'
# my site assets
bafybeihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku
END
```
***
## Step 6: Migrate
One command runs the whole migration:
```bash
ipfs2foc upload --cids cids.txt --car-store ./cars --db migrate.db \
--gateway https://trustless-gateway.link
```
| Flag | Purpose |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cids` | Your list of CIDs. |
| `--car-store` | **Required.** A working directory where content is staged. Files are deleted as each piece is confirmed, so it stays near 1 GiB rather than growing to the size of your migration. |
| `--db` | Progress file, so an interrupted run resumes instead of restarting. |
| `--gateway` | The gateway you validated in step 3. |
{% hint style="danger" %}
**Do not press Ctrl+C.** Interrupting between upload and onchain confirmation can leave a piece in an unconfirmed state needing manual recovery. If the run seems stuck, let it time out.
{% endhint %}
### What you'll see
The run reads and measures your content, packs it, then uploads and commits.
{% hint style="success" %}
You should see something like:
```
registered 1 CID(s) from cids.txt
packed 1 multi-root CAR(s) under ./cars
direct upload to 2 provider(s): primary 4 (https://…), secondary 12 (https://…)
parked bafkzcib… (647.74 KiB) on primary 4 in 18.7s
parked bafkzcib… on secondary 12 (pulled from primary)
flush [batch] provider 4: committing 1 piece(s)
committed 1 piece(s) on provider 4 (data set 25983)
direct upload finished in 2m 1s: 647.74 KiB stored
```
{% endhint %}
It finishes with a JSON summary of the run.
To store a single copy instead of two - cheaper, less redundant - add `--copies 1`.
***
## Step 7: Confirm it landed
Reconcile your local record against what is actually onchain:
```bash
ipfs2foc report --db migrate.db --data-set-id
```
The line that matters is the CID count.
{% hint style="success" %}
You should see something like:
```
CIDs: 1/1 committed on chain, 0 pending, 0 failed, 0 oversized
```
{% endhint %}
**When committed equals your total and failed is zero, your migration succeeded.**
{% hint style="info" %}
**A "not yet proven" warning here is expected.** Committing your data onchain and *proving* it is stored are two separate events. Providers prove possession on a recurring schedule, and the first proof after your migration can be up to a couple of hours away. The command also exits with a non-zero code while that is pending.
If your CID count reads fully committed with zero failures, you are done. Run the same command again later and the warning clears.
{% endhint %}
***
## Step 8: Verify retrieval
The whole point is that nothing about retrieval changes. Fetch one of your CIDs the way you always have:
```bash
curl -sL -o /dev/null -w "%{http_code}\n" \
"https://trustless-gateway.link/ipfs/"
```
`200` means your content still resolves by its original CID.
***
## Now switch to Filecoin Pin
Your existing pins are on Filecoin Onchain Cloud, and this migration is a one-time job.
**From here, use Filecoin Pin for everything new.** IPFS2FOC is built for moving a backlog, not for day-to-day uploads. [Filecoin Pin](/build-on-filecoin/cookbook/filecoin-pin) is the ongoing workflow: it pins new content, gives the same verifiable Filecoin persistence, and works with the standard IPFS tooling you already use.
***
## Related
* [About migrating IPFS pins](/build-on-filecoin/cookbook/filecoin-pin/migrate-ipfs-pins) - what IPFS2FOC is and how a migration works.
* [IPFS to Filecoin](https://filecoin.cloud/ipfs2filecoin) - check a CID list and estimate what a migration costs before you install anything.
# Filecoin Pin GitHub Action
Host a static website with Filecoin Pin using GitHub Actions
`filecoin-pin` can be used in CI pipelines like GitHub Actions to upload assets to the Filecoin decentralized storage network. Static website assets are particularly good candidates, given the existing tooling within the IPFS ecosystem for static website retrieval.
The [Filecoin Pin repo](https://github.com/filecoin-project/filecoin-pin) has an [example upload to Filecoin GitHub Action](https://github.com/filecoin-project/filecoin-pin/tree/master/upload-action) that can be used directly or as a starting point for your own CI pipeline.
The example filecoin-pin upload action itself has a [usage example](https://github.com/filecoin-project/filecoin-pin/tree/master/upload-action/examples), and you can even see it in production as part of [filecoin-pin-website's CI pipeline](https://github.com/filecoin-project/filecoin-pin-website/tree/main/.github/workflows)!
Below is also a video walkthrough of the example GitHub Action in use!
Note: there is more work coming soon to add "filecoin-pin functionality" directly to the robust [ipshipyard/ipfs-deploy-action](https://github.com/ipshipyard/ipfs-deploy-action) ([tracking issue](https://github.com/ipshipyard/ipfs-deploy-action/issues/39)).
# Filecoin Pin dApp Demo
See an example of Filecoin Pin working end to end within a web context.
## What You'll Build
In this walkthrough, you’ll build a simple drag-and-drop file uploader that:
* Stores IPFS files directly on Filecoin with built-in payments, all in browser!
* Tracks real-time upload progress through each step
* Retrieves data easily from IPFS Mainnet and the underlying Filecoin Service Provider
* Verifies persistent storage with on-chain Filecoin proofs
* Multi-user support with session-based authentication
* Seamlessly integrates with React, TypeScript, and Vite
## Walkthrough Recording
{% embed url="" %}
## Setup
We will start building by [forking the \*filecoin-pin-website demo repo](https://github.com/filecoin-project/filecoin-pin-website/fork).\* Make sure you have **Node.js 24+** and **npm 9+** installed. The dapp works with Filecoin Calibration testnet.
This will take \~10min. ⏲️
### Step 1: Fork, Clone, and Install Dependencies
```bash
# Fork the repo using the command below
# or visit [https://github.com/filecoin-project/filecoin-pin-website/fork](https://github.com/filecoin-project/filecoin-pin-website/fork)
gh repo fork filecoin-project/filecoin-pin-website
git clone https://github.com/YOUR-USERNAME/filecoin-pin-website.git
cd filecoin-pin-website
npm install
```
### **Step 2: Set Up Your Filecoin Wallet**
A Filecoin wallet is needed to send transactions on Filecoin and pay for the Filecoin storage service.
This demo dapp supports two authentication methods:
* **Private Key:** easiest for local development and learning.
* **Session Key:** recommended for production deployments - allows multiple users to share one wallet safely.
💡 The demo repo supports deployment with a shared session key, allowing multiple users to safely upload files using the same wallet. It has hardcoded DEFAULT\_WALLET\_ADDRESS and DEFAULT\_SESSION\_KEY that are ready to go, but please do NOT use it for production. You can override these defaults with env vars, see instructions [here](https://github.com/filecoin-project/filecoin-pin-website/blob/main/CONTRIBUTING.md#local-setup)!
**2.1 Get test FIL and test USDFC**
If you are using your own wallet, you need to get test FIL and test USDFC to pay for the Filecoin storage service and transactions.
1. Create or use an existing Filecoin wallet on the **Calibration testnet** ([such as MetaMask](/networks-and-tools/assets/metamask-setup)).
2. Visit the [Filecoin Calibration Faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html) to get free test FIL (to pay for transaction gas).
3. Visit the [Filecoin USDFC faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc) to get test USDFC, which is a USD stablecoin backed by FIL that can be used to pay for services.
### **Step 3: Run Your dApp**
Fire up your local development server:
```bash
npm run dev
```
Visit `http://localhost:5173` and you should see your dApp running! That is all it takes to set up your app. Now, let’s upload a file to see the magic happen!
## Store IPFS Files on Filecoin
The magic happens in one key file [**`src/hooks/use-filecoin-upload.ts`**](https://github.com/filecoin-project/filecoin-pin-website/blob/main/src/hooks/use-filecoin-upload.ts). This is where your IPFS files get uploaded to Filecoin.
### Step 1: Upload the data
* **Prepare Service** - Validates wallet balance and gets the Filecoin Warm Storage service initialized.
* **Create CAR** - Converts your file to an IPFS CAR (Content Addressed aRchive) file.
* **Upload** - Sends the CAR file to a Filecoin Storage Provider (SP).
### Step 2: Announce CIDs and confirm the transaction
The Filecoin SP:
* indexes the IPFS CAR file and publishes all the contained CIDs to the IPFS network via IPNI.
* commits to the Filecoin network via onchain transactions to store the data. Once the transaction is confirmed, your data is paid to be persisted on Filecoin.
### Step 3: Download the data
Your data is available from both the IPFS Mainnet network using standard traditional IPFS tooling and/or directly from Filecoin SPs.
### **Step 4: Verify your data storage**
Filecoin storage providers submit cryptographic proofs regularly onchain to prove that they are storing your data, and you can verify and see it for yourself [on the PDP Scan](https://pdp.vxb.ai/calibration).
That is it - you now have a dapp with a drag-and-drop interface to store IPFS Files on Filecoin!
## Next Steps
1. Check back on the [filecoin-pin-website repo](https://github.com/filecoin-project/filecoin-pin-website) - it will continue to be updated as new functionality is brought to filecoin-pin.
2. Feel free to report any issues with the dApp demo to .
3. Check out the [other Filecoin Pin guides](/build-on-filecoin/cookbook/filecoin-pin).
4. Ask questions or get help with filecoin-pin in the [supported communication channels](https://github.com/filecoin-project/filecoin-pin?tab=readme-ov-file#community-and-support).
# Filecoin Pin for ERC-8004 Agents
How to use the Filecoin Pin CLI with ERC-8004 autonomous agents
Learn how to register a trustless autonomous agent on the ERC-8004 Identity Registry with verifiable persistent storage using Filecoin Pin for the agent registration file.
***
## Overview
This tutorial walks you through registering an [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) compliant agent with cryptographically-verified persistent storage on Filecoin. You'll create an agent card (metadata describing your agent's capabilities), store it on Filecoin & IPFS using Filecoin Pin, and register it on-chain as an NFT on Base Sepolia.
**What you'll learn:**
* How to create an ERC-8004 compliant agent card
* How to use Filecoin Pin for persistent, verifiable storage
* How to register an agent on the ERC-8004 Identity Registry
* How to verify Filecoin storage proofs and on-chain registration
**What you'll build:** A GitHub Integration Agent that references GitHub's official MCP server, demonstrating how real-world services can be integrated with ERC-8004.
***
## Example Code and Scripts
For example code and helper scripts to help with using Filecoin Pin and agent registration, check out the quickstart repository:
**GitHub Repository**: [FilOzone/FilecoinPin-for-ERC8004](https://github.com/FilOzone/FilecoinPin-for-ERC8004)
***
## Why Filecoin Pin for Agent Storage?
Agent cards need persistent storage with provable guarantees. Unlike generic IPFS pinning services that may stop hosting your data without notice, Filecoin Pin provides:
* ✅ **Cryptographic proof** your data is stored (daily PDP proofs)
* ✅ **Ongoing verification** ensures storage persistence
* ✅ **Decentralized** storage across a global network
* ✅ **IPFS compatible** - works with existing tools and gateways
* ✅ **Crypto payments** - onchain payments
* ✅ **Limited time - sponsored storage coming soon** available for ERC-8004 builders
***
## Prerequisites
### Required Tools
Before starting, you'll need:
1. **Filecoin Pin CLI** - Follow the complete setup guide here:
* [Filecoin Pin Getting Started](/build-on-filecoin/cookbook/filecoin-pin/getting-started)
* This covers wallet creation, funding your wallet with FIL and USDFC, and payment setup
2. **Foundry** - Ethereum development toolkit for contract interactions
```bash
curl -L https://foundry.paradigm.xyz | bash
foundryup
```
3. **jq** (optional but recommended) - JSON processor for viewing outputs
```bash
# macOS
brew install jq
# Ubuntu/Debian
sudo apt-get install jq
```
### Required Tokens
You'll need testnet tokens on **two networks**:
#### Filecoin Calibration Testnet
* **tFIL** (testnet Filecoin) - For gas fees
* Request tFIL from [Filecoin Calibration Faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html)
* Amount requested: 100 tFIL
* **USDFC** (Filecoin stablecoin) - For storage payments
* Request test USDFC from [Filecoin Calibnet USDFC Faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc)
* Or Mint at [USDFC website](https://stg.usdfc.net) (requires tFIL as collateral)
* Amount needed: \~5 USDFC
#### Base Sepolia Testnet
* **Sepolia ETH** - For NFT minting and registration
* Request test ETH on Base Sepolia on [Faucet](https://www.alchemy.com/faucets/base-sepolia)
* Amount needed: \~0.001 ETH
> **NOTE!** The same Ethereum wallet works on both Filecoin Calibration and Base Sepolia. You only need one private key.
### ERC-8004 Registry Address
We'll be using the reference ERC-8004 Identity Registry deployed on the Base Sepolia testnet:
```
0x8004A818BFB912233c491871b3d84c89A494BD9e
```
***
## Step 1: Create Your Agent Card
An agent card is a JSON file that describes your agent's capabilities, endpoints, and trust model according to the [ERC-8004 specification](https://eips.ethereum.org/EIPS/eip-8004).
### Create the Agent Card JSON
Create a file named `github-agent-card.json`:
```bash
cat > github-agent-card.json << 'EOF'
{
"type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
"name": "GitHub Integration Agent",
"description": "AI agent providing GitHub repository, issue, and pull request management capabilities through GitHub's official MCP server. Enables automated code review, issue triage, PR management, and repository analysis.",
"image": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png",
"endpoints": [
{
"name": "MCP",
"endpoint": "https://api.githubcopilot.com/mcp/",
"version": "1.0.0",
"capabilities": {
"tools": [
{
"name": "repository_management",
"description": "Browse code, search files, analyze commits across GitHub repositories"
},
{
"name": "issue_management",
"description": "Create, update, search, and manage GitHub issues with AI assistance"
},
{
"name": "pull_request_management",
"description": "Review PRs, manage approvals, merge conflicts, and code reviews"
}
]
}
},
{
"name": "agentWallet",
"endpoint": "eip155:84532:0x0000000000000000000000000000000000000000"
}
],
"registrations": [],
"supportedTrust": [
"reputation"
]
}
EOF
```
### Validate the JSON
Verify your agent card is valid JSON:
```bash
jq . github-agent-card.json
```
You should see the formatted JSON output with syntax highlighting.
### Understanding the Agent Card Structure
Key fields in the agent card:
* **`type`** - Links to the ERC-8004 specification version
* **`name`** - Human-readable name for your agent
* **`description`** - What the agent does
* **`image`** - Avatar or logo URL
* **`endpoints`** - Array of service endpoints:
* **MCP endpoint** - Points to GitHub's official MCP server
* **agentWallet** - The agent's wallet address (chain:chainId:address format)
* **`capabilities`** - Tools and functions the agent provides
* **`supportedTrust`** - Trust mechanisms (reputation, stake, etc.)
> **💡 Note**: This example uses GitHub's real public MCP server at `https://api.githubcopilot.com/mcp/`. You can replace this with your own MCP server endpoint.
***
## Step 2: Upload to Filecoin Pin
Now we'll store the agent card on Filecoin with PDP proofs.
### Setup Payment System
If this is your first time using Filecoin Pin, set up the payment system:
```bash
export PRIVATE_KEY="0x..." # Your wallet private key
filecoin-pin payments setup --auto
```
This configures your wallet to pay for storage automatically. This may take a few minutes to complete.
You'll see output similar to:
```bash
filecoin-pin payments setup --auto
┌ Filecoin Onchain Cloud Payment Setup
│
│ Running in auto mode...
│
◇ ✓ Connected to calibration
│
◇ ✓ Balance check complete
│
│ Account:
│ Wallet: 0x44896a716F7b5Ed343C6962b3D56FaA5377Cd052
│ Network: calibration
│ Balances:
│ FIL: 354.9996 tFIL
│ USDFC wallet: 199.6428 USDFC
│ USDFC deposited: 0.0000 USDFC
│
◇ ✓ Deposited 1.0000 USDFC
│
│ Transaction details:
│ Deposit: 0x3b9cb71e21c9df895c9a2f50df437e0dfa5cf00d20bff6cf6deea0c231b5b128
│
◇ ━━━ Configuration Summary ━━━
│
│ Network: calibration
│ Deposit: 1.0000 USDFC
│ Storage: ~372.4 GiB for 1 month
│ Status: Ready to upload
│
└ Payment setup completed successfully
```
> **NOTE!** You only need to run this once per wallet. Subsequent uploads will use the existing payment configuration.
### Upload Your Agent Card
Upload the agent card to Filecoin:
```bash
filecoin-pin add --auto-fund github-agent-card.json
```
The `--auto-fund` flag ensures your storage provider wallet has sufficient funds.
You'll see output similar to:
```bash
filecoin-pin add --auto-fund github-agent-card.json
┌ Filecoin Pin Add
│
◇ ✓ File validated (1.3 KiB)
│
◇ ✓ Connected to calibration
│
◇ ✓ Minimum payment setup verified (~0.066 USDFC required)
│
◇ ✓ File packed with root CID: bafybeihhal5hlbylkibniig6j72wdrm7lr4nf6z47natleh2jkyosrg7di
│
◇ ✓ IPFS content loaded (1.5 KiB)
│
◇ ✓ Funding requirements met
│
◑ Creating storage context..Provider 0xB709A785c765d7d3F7d94dbA367DA6a611D7972b failed ping test: fetch failed
◇ ✓ Storage context ready
│
│ Storage Context
│
│ Data Set ID: undefined
│ Provider: pspsps-calibnet
│
◇ ━━━ Add Complete ━━━
│
│ Network: calibration
│
│ Add Details
│ File: github-agent-card.json
│ Size: 1.5 KiB
│ Root CID: bafybeihhal5hlbylkibniig6j72wdrm7lr4nf6z47natleh2jkyosrg7di
│
│ Filecoin Storage
│ Piece CID: bafkzcibdricannieziik7jobrwqia4qfq6g7cwxfspsppv5aa76uev4u6ek7awz5
│ Piece ID: 0
│ Data Set ID: 11653
│
│ Storage Provider
│ Provider ID: 11
│ Name: pspsps-calibnet
│ Direct Download URL: https://calibnet.pspsps.io/piece/bafkzcibdricannieziik7jobrwqia4qfq6g7cwxfspsppv5aa76uev4u6ek7awz5
│
└ Add completed successfully
```
> **NOTE!** Data storage on the Calibration Testnet has a retention period of approximately 1 week. For production use and to ensure your data remains available, please switch to Filecoin mainnet.
### Save Important Values
Copy these values from the output - you'll need them later:
* **Root CID** - The IPFS content identifier (e.g., `bafybeihhal5hlbylkibniig6j72wdrm7lr4nf6z47natleh2jkyosrg7di`).
* **Dataset ID** - For checking PDP proof status (e.g., `11653`)
> **⚠️ IMPORTANT**: The Token URI for ERC-8004 registration must include the filename! Format it as:
>
> ```
> ipfs:///github-agent-card.json
> ```
### Verify IPFS Retrieval
Test that your agent card is accessible via IPFS (it may take a few minutes to propagate!):
```bash
# Replace with your actual CID
curl -s "https://ipfs.io/ipfs//github-agent-card.json" | jq .
```
You should see your agent card JSON returned:
```bash
curl -s "https://ipfs.io/ipfs/bafybeihhal5hlbylkibniig6j72wdrm7lr4nf6z47natleh2jkyosrg7di/github-agent-card.json" | jq .
{
"type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
"name": "GitHub Integration Agent",
"description": "AI agent providing GitHub repository, issue, and pull request management capabilities through GitHub's official MCP server. Enables automated code review, issue triage, PR management, and repository analysis.",
"image": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png",
"endpoints": [
{
"name": "MCP",
"endpoint": "https://api.githubcopilot.com/mcp/",
"version": "1.0.0",
"capabilities": {
"tools": [
{
"name": "repository_management",
"description": "Browse code, search files, analyze commits across GitHub repositories"
},
{
"name": "issue_management",
"description": "Create, update, search, and manage GitHub issues with AI assistance"
},
{
"name": "pull_request_management",
"description": "Review PRs, manage approvals, merge conflicts, and code reviews"
}
]
}
},
{
"name": "agentWallet",
"endpoint": "eip155:84532:0x0000000000000000000000000000000000000000"
}
],
"registrations": [],
"supportedTrust": [
"reputation"
]
}
```
***
## Step 3: Register on Base Sepolia
Now we'll register the agent on-chain as an ERC-8004 NFT on Base Sepolia.
### Set Environment Variables
```bash
export PRIVATE_KEY="0x..." # Your wallet private key
export TOKEN_URI="ipfs:///github-agent-card.json" # From Step 2
export IDENTITY_REGISTRY="0x8004A818BFB912233c491871b3d84c89A494BD9e"
export BASE_SEPOLIA_RPC="https://sepolia.base.org"
```
> **⚠️ SECURITY WARNING**: Never commit your private key to version control or share it publicly.
### Check Your Balance
Ensure you have sufficient Base Sepolia ETH:
```bash
cast balance --rpc-url $BASE_SEPOLIA_RPC --ether
```
You should have at least 0.001 ETH for the registration transaction.
### Register the Agent
Send the registration transaction:
```bash
cast send $IDENTITY_REGISTRY \
"register(string)" \
"$TOKEN_URI" \
--rpc-url $BASE_SEPOLIA_RPC \
--private-key $PRIVATE_KEY
```
You'll see output similar to:
```bash
cast send $IDENTITY_REGISTRY \
"register(string)" \
"$TOKEN_URI" \
--rpc-url $BASE_SEPOLIA_RPC \
--private-key $PRIVATE_KEY
blockHash 0x8699f29397c8b6b921d5e3f754220fa84ba049a0cfed875dc5deffcfd5f5dcb9
blockNumber 37478106
contractAddress
cumulativeGasUsed 6675540
effectiveGasPrice 1200000
from 0x44896a716F7b5Ed343C6962b3D56FaA5377Cd052
gasUsed 200928
logs [{"address":"0x8004a818bfb912233c491871b3d84c89a494bd9e","topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef","0x0000000000000000000000000000000000000000000000000000000000000000","0x00000000000000000000000044896a716f7b5ed343c6962b3d56faa5377cd052","0x000000000000000000000000000000000000000000000000000000000000018e"],"data":"0x","blockHash":"0x8699f29397c8b6b921d5e3f754220fa84ba049a0cfed875dc5deffcfd5f5dcb9","blockNumber":"0x23bdeda","blockTimestamp":"0x698b1c94","transactionHash":"0x0edda2928ec45aaa4091a2fa2cc863f249e78b86931aed31e2c5365d3b99175c","transactionIndex":"0x13","logIndex":"0xe0","removed":false},{"address":"0x8004a818bfb912233c491871b3d84c89a494bd9e","topics":["0xf8e1a15aba9398e019f0b49df1a4fde98ee17ae345cb5f6b5e2c27f5033e8ce7"],"data":"0x000000000000000000000000000000000000000000000000000000000000018e","blockHash":"0x8699f29397c8b6b921d5e3f754220fa84ba049a0cfed875dc5deffcfd5f5dcb9","blockNumber":"0x23bdeda","blockTimestamp":"0x698b1c94","transactionHash":"0x0edda2928ec45aaa4091a2fa2cc863f249e78b86931aed31e2c5365d3b99175c","transactionIndex":"0x13","logIndex":"0xe1","removed":false},{"address":"0x8004a818bfb912233c491871b3d84c89a494bd9e","topics":["0xca52e62c367d81bb2e328eb795f7c7ba24afb478408a26c0e201d155c449bc4a","0x000000000000000000000000000000000000000000000000000000000000018e","0x00000000000000000000000044896a716f7b5ed343c6962b3d56faa5377cd052"],"data":"0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000059697066733a2f2f626166796265696868616c35686c62796c6b69626e696967366a37327764726d376c72346e66367a34376e61746c6568326a6b796f7372673764692f6769746875622d6167656e742d636172642e6a736f6e00000000000000","blockHash":"0x8699f29397c8b6b921d5e3f754220fa84ba049a0cfed875dc5deffcfd5f5dcb9","blockNumber":"0x23bdeda","blockTimestamp":"0x698b1c94","transactionHash":"0x0edda2928ec45aaa4091a2fa2cc863f249e78b86931aed31e2c5365d3b99175c","transactionIndex":"0x13","logIndex":"0xe2","removed":false},{"address":"0x8004a818bfb912233c491871b3d84c89a494bd9e","topics":["0x2c149ed548c6d2993cd73efe187df6eccabe4538091b33adbd25fafdb8a1468b","0x000000000000000000000000000000000000000000000000000000000000018e","0x2ac6109326e720d1435c0db66f7e35eda7839f52b6f1f5520a60788e132b4e39"],"data":"0x00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000b6167656e7457616c6c6574000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001444896a716f7b5ed343c6962b3d56faa5377cd052000000000000000000000000","blockHash":"0x8699f29397c8b6b921d5e3f754220fa84ba049a0cfed875dc5deffcfd5f5dcb9","blockNumber":"0x23bdeda","blockTimestamp":"0x698b1c94","transactionHash":"0x0edda2928ec45aaa4091a2fa2cc863f249e78b86931aed31e2c5365d3b99175c","transactionIndex":"0x13","logIndex":"0xe3","removed":false}]
logsBloom 0x00000000000000000000000000000000000000000000000000000000000000000000000080000000001000000000010200000000000000000000000000000000000000000000000000000008000080000000000000000000000000000000000000000000a20000000000000008000800000000000000000000000010000000000000000000100000000000000000000080000000000000000000000000000000000000000000000040000000000000002000000000000000010000000000008000000002000000002000000000000000000000000000000000800000000020000000081000010000200000000000000000000000000000000000000004000000
root
status 1 (success)
transactionHash 0x0edda2928ec45aaa4091a2fa2cc863f249e78b86931aed31e2c5365d3b99175c
transactionIndex 19
type 2
blobGasPrice
blobGasUsed 46176
to 0x8004A818BFB912233c491871b3d84c89A494BD9e
daFootprintGasScalar 312
l1BaseFeeScalar 1101
l1BlobBaseFee 63508363
l1BlobBaseFeeScalar 659851
l1Fee 8679909892
l1GasPrice 928642664
l1GasUsed 2383
```
A `status` of `1` means the transaction succeeded and your agent NFT was minted!
### Get Your Agent ID
Your agent ID is the **token ID** of the ERC-721 NFT that was minted when you registered. You can extract it from the transaction logs with `cast` and `jq` (install `jq` if needed, e.g. `brew install jq` on macOS):
1. Set `TX_HASH` to the `transactionHash` from your `cast send` output (e.g. `0x0edda2928ec45aaa4091a2fa2cc863f249e78b86931aed31e2c5365d3b99175c`).
2. Get the receipt and read the **Transfer** event's `tokenId` (fourth topic):
```bash
export TX_HASH="0x..." # from your cast send output
# Extract agent ID (token ID) from the Transfer event in the receipt logs
AGENT_ID=$(cast receipt $TX_HASH --rpc-url $BASE_SEPOLIA_RPC --json \
| jq -r '.logs[] | select(.topics[0] == "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef") | .topics[3]' \
| head -1 \
| xargs cast --to-dec)
echo "Agent ID: $AGENT_ID"
```
This filters logs for the ERC-721 **Transfer** event and converts the `tokenId` topic to decimal. Use `$AGENT_ID` in the [Verify Registration](#verify-registration) step below.
**Alternative:** You can also look up the transaction on [BaseScan (Base Sepolia)](https://sepolia.basescan.org/) → **Logs** tab → **Transfer** or **Registered** event, and read the `tokenId` / `agentId` from the event (e.g. [example transaction](https://sepolia.basescan.org/tx/0x0edda2928ec45aaa4091a2fa2cc863f249e78b86931aed31e2c5365d3b99175c) shows token ID 398).
### Verify Registration
Confirm your agent is registered correctly using the agent ID from the previous step (use `$AGENT_ID` if you extracted it with `cast`, or the value you read from BaseScan):
```bash
cast call $IDENTITY_REGISTRY \
"tokenURI(uint256)" \
$AGENT_ID \
--rpc-url $BASE_SEPOLIA_RPC
```
You will get ABI-encoded output similar to:
```bash
0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000059697066733a2f2f626166796265696868616c35686c62796c6b69626e696967366a37327764726d376c72346e66367a34376e61746c6568326a6b796f7372673764692f6769746875622d6167656e742d636172642e6a736f6e00000000000000
```
The output is ABI-encoded. Decode it:
```bash
cast --abi-decode "f()(string)"
```
You should see your Token URI returned: `ipfs:///github-agent-card.json`:
```bash
cast --abi-decode "f()(string)" 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000059697066733a2f2f626166796265696868616c35686c62796c6b69626e696967366a37327764726d376c72346e66367a34376e61746c6568326a6b796f7372673764692f6769746875622d6167656e742d636172642e6a736f6e00000000000000
"ipfs://bafybeihhal5hlbylkibniig6j72wdrm7lr4nf6z47natleh2jkyosrg7di/github-agent-card.json"
```
### View on Block Explorer
Visit your agent on the Base Sepolia block explorer:
```
https://sepolia.basescan.org/nft/0x8004a818bfb912233c491871b3d84c89a494bd9e/
```
Replace `` with your agent's ID (e.g., `398`).
Base Sepolia block explorer, showing NFT minted
***
## Step 4: Check On-chain Storage Proofs
Finally, let's verify that your agent card is persistently stored with cryptographic proofs.
### Check PDP Proof Status
Use the Dataset ID from Step 2:
```bash
filecoin-pin data-set show 11653 # Replace with your Dataset ID
```
You'll see output like:
```bash
filecoin-pin data-set show 11653
┌ Filecoin Onchain Cloud Data Set Details for #11653
│
◇ ━━━ Data Set ━━━
│
│ Network: calibration
│ Client address: 0x44896a716F7b5Ed343C6962b3D56FaA5377Cd052
│
│ #11653
│ Status: live
│ CDN add-on: disabled
│
│ Provider
│ ID: 11
│ Address: 0x682467D59F5679cB0BF13115d4C94550b8218CF2
│ Name: pspsps-calibnet
│ Description: herding cats
│ Service URL: https://calibnet.pspsps.io
│ Active: yes
│ Location: C=DE;ST=Bavaria;L=Nuremberg
│
│ Metadata
│ source: "filecoin-pin"
│ withIPFSIndexing: ""
│
│ Payment
│ PDP rail ID: 12908
│ Payer: 0x44896a716F7b5Ed343C6962b3D56FaA5377Cd052
│ Payee: 0x682467D59F5679cB0BF13115d4C94550b8218CF2
│
│ Pieces
│ Total pieces: 1
│ Total size: 1.5 KiB
│ Unique PieceCIDs: 1
│ Unique IPFS Root CIDs: 1
│
│ #0 (active)
│ PieceCID: bafkzcibdricannieziik7jobrwqia4qfq6g7cwxfspsppv5aa76uev4u6ek7awz5
│ Size: 1.5 KiB
│ Metadata
│ ipfsRootCID: "bafybeihhal5hlbylkibniig6j72wdrm7lr4nf6z47natleh2jkyosrg7di"
│
│
└ Data set inspection complete
```
> **💡 Note**: PDP proofs may take up to 24 hours to begin after initial upload. This is normal.
### Summary
✅ Your agent is now:
* 🔒 **Persistently stored** on Filecoin with cryptographic PDP proofs
* 🌐 **Registered on-chain** as an ERC-8004 NFT on Base Sepolia
* 🔍 **Discoverable** via the Identity Registry by any third party
* ✅ **Verifiable** - anyone can check storage proofs and on-chain data
* 🚀 **Ready to use** by other agents and applications
***
## Step 5: Deploy on Mainnet
Ready to move to production? This step covers deploying your agent on Filecoin mainnet and Base mainnet.
### Required Tokens (Mainnet)
You'll need real tokens on **two networks**:
#### Filecoin Mainnet
* **FIL** - For gas fees on Filecoin
* **USDFC** - For storage payments
Get FIL and USDFC via the [USDFC Bridge](https://app.usdfc.net/#/bridge) - bridge from any token on any network to FIL and USDFC on Filecoin mainnet. You can also use [Sushi](https://www.sushi.com/filecoin/swap?token0=NATIVE\&token1=0x80b98d3aa09ffff255c3ba4a241111ff1262f045) to swap FIL for USDFC.
#### Base Mainnet
* **ETH** - For NFT minting and registration on Base
### ERC-8004 Registry Address (Base Mainnet)
```
0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
```
View on explorer: [Base Mainnet Registry](https://basescan.org/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432)
### Upload to Filecoin Mainnet
Filecoin Pin defaults to Mainnet, so no extra flags are needed for mainnet operations.
#### Setup Payment System (Mainnet)
```bash
export PRIVATE_KEY="0x..." # Your wallet private key
filecoin-pin payments setup --auto
```
#### Upload Your Agent Card (Mainnet)
```bash
filecoin-pin add --auto-fund github-agent-card.json
```
Save the **Root CID** and **Dataset ID** from the output.
### Register on Base Mainnet
#### Set Environment Variables
```bash
export PRIVATE_KEY="0x..." # Your wallet private key
export TOKEN_URI="ipfs:///github-agent-card.json" # From previous step
export IDENTITY_REGISTRY="0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
export BASE_MAINNET_RPC="https://mainnet.base.org"
```
#### Register the Agent
```bash
cast send $IDENTITY_REGISTRY \
"register(string)" \
"$TOKEN_URI" \
--rpc-url $BASE_MAINNET_RPC \
--private-key $PRIVATE_KEY
```
#### Verify Registration
```bash
export TX_HASH="0x..." # from your cast send output
# Extract agent ID (token ID) from the Transfer event in the receipt logs
AGENT_ID=$(cast receipt $TX_HASH --rpc-url $BASE_MAINNET_RPC --json \
| jq -r '.logs[] | select(.topics[0] == "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef") | .topics[3]' \
| head -1 \
| xargs cast --to-dec)
echo "Agent ID: $AGENT_ID"
```
### Check Mainnet Storage Proofs
```bash
filecoin-pin data-set show
```
***
## Troubleshooting
### Issue: `filecoin-pin: command not found`
**Solution**: Install the Filecoin Pin CLI:
```bash
npm install -g filecoin-pin@latest
```
### Issue: `Insufficient USDFC`
**Solution**: Request more test USDFC at [Filecoin Calibnet USDFC Faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc)
### Issue: `Transaction reverted` on Base Sepolia
**Solution**: Check your Base Sepolia ETH balance:
```bash
cast balance --rpc-url https://sepolia.base.org --ether
```
Get more from the [faucet](https://www.alchemy.com/faucets/base-sepolia) if needed.
### Issue: IPFS retrieval is slow or fails
**Solution**: IPFS propagation can take a few minutes. Try different gateways:
```bash
curl -s "https://ipfs.io/ipfs//github-agent-card.json" | jq .
curl -s "https://gateway.pinata.cloud/ipfs//github-agent-card.json" | jq .
curl -s "https://dweb.link/ipfs//github-agent-card.json" | jq .
```
### Issue: PDP proofs not showing
**Solution**: PDP proofs can take up to 24 hours to begin after upload. This is normal - your data is still stored, proofs just take time to generate. Check back later with:
```bash
filecoin-pin data-set show
```
### Issue: Token URI doesn't include filename
**Solution**: The Token URI must include the full path including filename. Correct format:
```
ipfs:///github-agent-card.json
```
If you registered with the wrong format, you'll need to register a new agent with the corrected Token URI.
***
## What's Next?
Now that your agent is registered with verifiable persistent storage, you can:
### Build Your Own Agent
1. **Create custom agent cards** for your services
2. **Deploy your own MCP server** and reference it in the agent card
3. **Register multiple agents** for different capabilities
4. **Update agent cards** by uploading new versions (CID changes) and updating on-chain
### Explore ERC-8004 Features
* **Reputation Registry** - Build reputation for your agents
* **Validation Registry** - Add validators to verify agent behavior
* **Multi-agent coordination** - Discover and compose multiple agents
### Join the Community
* **Filecoin Builders**: [on telegram](https://t.me/+Xj6_zTPfcUA4MGQ1); [on Slack](https://filecoinproject.slack.com/archives/CRK2LKYHW)
* **ERC-8004 Discussion**: [GitHub Discussions](https://github.com/ethereum/EIPs/issues/8004)
* **Filecoin Pin**: [Documentation](/build-on-filecoin/cookbook/filecoin-pin)
* **Builder Channels**: Join ERC-8004 builder communities
### Sponsored Storage for ERC-8004 Builders
Coming soon, stay tuned!
***
## Additional Resources
* [**ERC-8004 Specification**](https://eips.ethereum.org/EIPS/eip-8004)
* [**Reference Implementation**](https://github.com/ChaosChain/trustless-agents-erc-ri)
* [**Filecoin Pin Getting Started**](/build-on-filecoin/cookbook/filecoin-pin/getting-started)
* [**Base Sepolia Explorer**](https://sepolia.basescan.org)
* [**GitHub MCP Server**](https://github.com/github/github-mcp-server)
***
**Happy building!** 🚀
# FAQ
## What is Filecoin Pin?
Filecoin Pin stores IPFS content on the Filecoin Network of decentralized Storage Providers. It enables developers to programmatically pay for storage and retrieval with Filecoin Pay. When SPs prove storage, they are paid from the developers' Filecoin Pay Account.
***
### How can I use Filecoin Pin today?
Three paths are available:
* **CLI:** Upload files from your terminal on Filecoin Mainnet. Fund storage from your own wallet. [Get started here](/build-on-filecoin/cookbook/filecoin-pin/getting-started).
* **GitHub Action:** Automate pinning of websites or build artifacts in your CI/CD pipeline.
* **Website (demo):** Upload files in your browser using a pre-funded test wallet on Calibration testnet.
***
### What do I need to get started?
* You can find different links related to Filecoin Pin here: [Filecoin Pin documentation](/build-on-filecoin/cookbook/filecoin-pin)
***
### How do payments and approvals work?
* **Website (demo):** The demo wallet handles payments. It has been prefunded with testnet USDFC and FIL. Users don't need to connect their own wallet.
* **CLI / GitHub Action:** Your wallet handles payments on Mainnet. You approve and deposit USDFC funds through Filecoin Pay once, then the CLI manages payments automatically.
{% hint style="info" %}
Storage providers receive payment after cryptographically proving data possession.
{% endhint %}
***
### How does auto-funding work?
Use `--auto-fund` when uploading. The CLI calculates storage costs automatically. It deposits the right amount of USDFC to your payment rail.
{% hint style="info" %}
No manual deposit calculations needed. The system handles it.
{% endhint %}
***
### How long is my data stored?
On **Mainnet** (the default), data persists as long as you maintain deposits in Filecoin Pay. Storage providers must prove they hold your data daily or they stop receiving payment. The CLI supports auto-funding to keep your runway healthy.
On **Calibration testnet** (the demo website), data has no persistence guarantees. Treat it as a demo environment only.
***
### What is a Data Set?
A Data Set groups your uploads together. Each upload becomes a "piece" within the Data Set. Multiple files you upload share the same payment rail.
Check your Data Set with `filecoin-pin data-set show `.
***
### How do I retrieve my data?
Three methods:
1. **IPFS Gateways:** Use public gateways with your root CID: `https://gateway.example.com/ipfs/`
2. **Direct from Storage Provider:** Get the direct download URL from `filecoin-pin data-set show `
3. **IPFS Tools:** Use Kubo, Helia, IPFS Desktop with your root CID.
***
### What is a piece CID vs root CID?
**Root CID** (bafybei...) is your IPFS content identifier. Use this to retrieve your data.
**Piece CID** (bafkzci...) is the Filecoin commitment. Storage Providers prove they store this piece.
{% hint style="info" %}
Both are linked cryptographically on-chain.
{% endhint %}
***
### How do I verify my data is actually stored?
Two ways to verify:
1. **CLI:** Run `filecoin-pin data-set show ` to see on-chain verification. Check proof status and piece details.
2. **PDP Explorer:** Visit `https://pdp.vxb.ai/calibration/dataset/{datasetID}` to view proofs in your browser.
{% hint style="info" %}
Both methods show CommP and proof state directly from blockchain state.
{% endhint %}
***
### How do I access the code for the dApp and CLI?
See the repos as reference implementations and to fork for my own project?
* **Website**:
* **CLI:**
***
## References
* Filecoin Pin CLI Docs: [Filecoin Pin documentation](/build-on-filecoin/cookbook/filecoin-pin)
* Filecoin Pin dApp Repo:
* Synapse SDK:
* USDFC documentation:
# Plan your Filecoin storage provider business
This page will help you understand how to plan a profitable business, design a suitable storage provider architecture, and make the right hardware investments.
The Filecoin network provides decentralized data storage and makes sure data is verified, always available, and immutable. Storage providers in the Filecoin network are in charge of storing, providing content and issuing new blocks.
To become a storage provider in the Filecoin network you need a range of technical, financial and business skills. We will explain all the key concepts you need to understand in order to design a suitable architecture, make the right hardware investments, and run a profitable storage provider business.
In a hurry? The [storage provider agent quickstart](/provide-storage/agent-quickstart) takes you from zero to running warm storage, Consensus Mining, both, or cold storage, on a single page.
There are two ways to participate in Filecoin:
* **Serve Storage Service on Filecoin**
* **Warm Storage (Recommended):** backed by PDP proofs, FWSS, and Filecoin Pay. No GPU required; a single-machine Docker stack is enough to start. Some data is provided by the network for you to store.
* **Cold Storage:** the Filecoin Cold Storage Service (FCSS), sealed with PoRep, for archives of 1 TiB and up. Runs on a Consensus Mining cluster, and the PoRep Market matches client deals to your offers. See [Path D](/provide-storage/agent-quickstart#path-d).
* **Consensus Mining (PoRep):** the classic Filecoin sealing path: seal sectors, prove them over time, and take FIL collateral. GPU-heavy hardware and a larger operational footprint. You manage your own data business relationships.
* **Both:** run Consensus Mining and Storage Service on one Curio cluster. See [Path C](/provide-storage/agent-quickstart#path-c).
Planning to become a storage provider? Tell us about your setup in the [storage provider interest form](https://docs.google.com/forms/d/e/1FAIpQLSdTd7Znz5uJeF8f98LccjZ-q7dq9Nh861t_rFkH_kcNO6HCtw/viewform).
## Storage Service (PDP)
FOC lets you sell warm storage from your own hardware without a PoRep sealing pipeline. One Docker Compose command brings up Forest, Yugabyte, and Curio-PDP, and a web guide on `http://127.0.0.1:4701` walks you through wallet, storage, domain, and FOC registration. Downloads aside, setup takes about five minutes.
```bash
git clone https://github.com/filecoin-project/curio.git
cd curio/docker/skiff
# Mainnet
SKIFF_IMAGE=filecoin/curio-pdp:latest docker compose -f docker-compose.yaml up -d
# Calibration test network (free test funds)
SKIFF_IMAGE=filecoin/curio-pdp:calibnet docker compose -f docker-compose.yaml -f docker-compose.calibnet.yaml up -d
```
Keep the `SKIFF_IMAGE=` prefix on any later `docker compose up`, or the stack falls back to building the `:dev` image.
Full walkthrough — what’s in the box, hardware, the PDP Guide steps, and what you earn: [**Run a PDP provider**](/provide-storage/pdp/install-and-run-pdp). Deeper operator docs (custom disks, external chain nodes, troubleshooting): [**Curio-PDP**](https://docs.curiostorage.org/getting-started/curio-pdp) on [docs.curiostorage.org](https://docs.curiostorage.org/).
### Choose your operation profile
Storage providers run at three broad sizes. The sizes below are for Storage Service (PDP), and each starts from the per-node hardware floor in [Path A of the agent quickstart](/provide-storage/agent-quickstart#path-a). Consensus Mining needs a sealing and proving cluster instead: see [Path B](/provide-storage/agent-quickstart#path-b).
| Profile | What it looks like |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solo** | One machine at the hardware floor. Start with 10 TiB+ of HDD and add disks as you fill. Today's endorsed providers declare between 60 and 500 TiB. |
| **Renting (colocation/DC operator)** | A bare-metal storage server from a large host, 40 to 175 TiB raw per box before RAID. |
| **Enterprise Data Center Operator** | 1 PiB and up: the hardware floor per head node, with JBOD shelves for piece data. |
Protocol background: [About PDP](/provide-storage/pdp/about).
## Cold Storage Service (FCSS)
The Filecoin Cold Storage Service (FCSS) is the cold storage service of Filecoin Onchain Cloud, next to warm storage. Clients store sealed copies of large datasets under deals with terms they set: duration, price, retrievability, bandwidth, latency, and IPNI indexing. The [PoRep Market](https://github.com/fidlabs/porep-market) matches each deal to a provider offer that meets those terms, and Filecoin Pay pays the provider in USDFC according to how well it meets them.
FCSS providers run a Consensus Mining cluster (below) with Curio's storage market turned on. On top of that, they:
* Register and complete KYC at [peertopool.fidl.tech](https://peertopool.fidl.tech/), and are listed in the public [FCSS provider directory](https://peertopool.fidl.tech/directory).
* Publish offers and onboard deals with the [PoRep Market CLI](https://github.com/fidlabs/filecoin-porep-market-tooling).
* Keep unsealed copies of client data and serve retrievals, free or [paid per piece](https://github.com/fidlabs/large-paid-retrievals).
Step-by-step setup: [**Path D of the agent quickstart**](/provide-storage/agent-quickstart#path-d). Client side: [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss).
The sections below cover the **Consensus Mining** path, which FCSS builds on.
## Consensus Mining (PoRep)
PoRep is the classic Filecoin storage-provider business: seal sectors, prove them over time, take FIL collateral, and (optionally) make storage deals. The sections below cover architecture, hardware, and how to run that operation profitably.
Follow these steps:
1. Understand Filecoin economics
2. Plan your business
3. Build the right core competencies
4. Build the right infrastructure
5. Get to know the ecosystem
6. Understand ROI and collateral
7. Choose your provider software stack
8. Set up a local development environment
9. Become a storage provider
10. Configure PoRep deal-making and retrieval services
11. Explore verified deals and ecosystem tools
## Understand Filecoin economics
To understand how you can run a profitable business as a Filecoin storage provider, it is important to make sure you understand the economics of Filecoin. Once you understand all core concepts, you can build out a strategy for your desired ROI.
Storage providers can also add additional value to clients when they offer certain certifications. These can enable a storage provider to charge customers additional fees for storing data in compliance with those standards, for example, HIPAA, SOC2, PCI, GDPR and others.
[Filecoin economics ->](/provide-storage/filecoin-economics/storage-proving)
## Plan your business
The hardware and other requirements for running a Filecoin storage provider business are significantly higher than regular blockchain mining operations. The mechanisms are designed this way because, in contrast to some other blockchain solutions, where you can simply configure one or more nodes to "mine" tokens, the Filecoin network's primary goal is to provide decentralized storage for humanity's most valuable data.
You need to understand the various earning mechanisms in the Filecoin network.
[Filecoin deals ->](/provide-storage/filecoin-deals/storage-deals)
### Daily fees and startup readiness (FIP-0100)
With the activation of [FIP-0100](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0100.md) in network version 25, all new sectors — and any sectors that are extended or updated — incur a daily fee. This fee replaces the previous batch fee model and introduces a predictable cost structure tied to each sector's quality-adjusted power and the network's circulating supply.
The fee begins accruing the day after a sector is committed or extended. It is deducted automatically at the end of each proving deadline. The network first draws from vesting block rewards. If those are insufficient, it draws from the miner's available balance. If both are empty, the unpaid amount becomes **fee debt**.
Fee debt does not directly cause faults. However, it can impact operations:
* A miner with fee debt may be blocked from submitting certain messages (e.g., pre-commits or recoveries).
* If the balance is too low to pay for WindowPoSt messages, sectors may fault.
* Critically, a miner with outstanding fee debt cannot win block rewards until the debt is repaid.
To avoid this, storage providers should:
* Keep a FIL buffer in the miner actor's balance.
* Avoid fully withdrawing unlocked funds unless upcoming rewards will cover future fees.
### Startup considerations
Miners become eligible to win block rewards once they reach **10 TiB of raw byte power (RBP)**.
However, rewards are not guaranteed as soon as that threshold is met. Block production is probabilistic, and smaller miners may wait longer to win a block — especially when competing against larger ones.
This creates a funding gap during the startup phase.
New storage providers must plan for this by funding their miner actor with enough FIL to:
* Cover daily fees during onboarding,
* Support message submission (like WindowPoSt),
* And continue sealing until rewards start arriving.
While the amount of FIL required is relatively small compared to overall infrastructure costs, it is operationally critical. Without it, the miner may become stuck — unable to seal new sectors, submit required messages, or produce blocks and win block rewards due to fee debt or insufficient balance.
To estimate how much FIL may be needed, review the [FIP-0100 discussion thread](https://github.com/filecoin-project/FIPs/discussions/1105) or use the [real-time fee calculator](https://penalty.660688.xyz/dailyfee) to model your expected onboarding rate.
## Build the right core competencies
As will become clear, running a storage operation is a serious business, with client data and pledged funds at stake. You will be required to run a highly-available service, and there are automatic financial penalties if you cannot demonstrate data availability to the network. There are many things that can go wrong in a data center, on your network, on your OS, or at an application level.
You will need skilled people to operate your storage provider business. Depending on the size and complexity of your setup this can be 1 person with skills across many different domains, or multiple dedicated people or teams.
[Core competencies ->](/provide-storage/core-competencies)
## Build the right infrastructure
At the lowest level, you will need datacenter infrastructure. You need people capable of architecting, racking, wiring and operating infrastructure components. Alternatively, you can get it collocated, or even entirely as a service from a datacenter provider.
Take availability and suitable redundancy into consideration when choosing your datacenter or collocation provider. Any unavailability of your servers, network or storage can result in automatic financial penalties on the Filecoin network.
[Software architecture ->](/provide-storage/architecture/lotus-components)
[Infrastructure ->](/provide-storage/infrastructure)
## Get to know the ecosystem
One of the enriching elements of the Filecoin ecosystem lies in its vibrant community. Within this dynamic network, you will find individuals eager to share their experiences and offer solutions to the challenges they have encountered. Whether it is navigating the intricacies of storage provider operations or overcoming hurdles on the blockchain, this supportive community stands ready to help. Embrace the spirit of collaboration and tap into this remarkable network.
[Filecoin Slack ->](https://filecoinproject.slack.com/ssb/redirect)
## Understand ROI and collateral
To run a successful storage provider business, it is crucial to understand the concept of Return on Investment (ROI) and the significance of collateral. By planning ahead and considering various factors, such as CAPEX, OPEX, network variables, and collateral requirements, you can make informed decisions that impact your business's profitability and desired capacity.
## Choose your provider software stack
Storage providers usually run several pieces of software together. Start by understanding which component handles each part of the operation:
| Component | Role |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Curio](https://curiostorage.org/) | Modern storage-provider stack for running provider operations, including PDP storage, proving, and retrieval, and PoRep sealing and proving workflows. Its built-in [storage market](https://docs.curiostorage.org/curio-market/storage-market) handles PoRep storage deals and retrievals. |
| [Lotus](https://lotus.filecoin.io) | Reference Filecoin implementation for chain sync, node operations, miner actor interactions, and client tooling. |
| [Boost](https://boost.filecoin.io) | Deal-making and retrieval for the older `lotus-miner` stack. Not compatible with current Curio releases. |
For new storage-provider planning, treat Curio as the provider operations stack, including deal-making through its built-in storage market, and Lotus as the underlying Filecoin node and chain tooling. If you run `lotus-miner` and Boost today, see [Migrating from Boost](https://docs.curiostorage.org/curio-market/migrating-from-boost). Use each project's maintained documentation for installation and production configuration.
[Curio documentation ->](https://docs.curiostorage.org/)
[Lotus documentation ->](https://lotus.filecoin.io)
## Set up a local development environment
Setting up a local development network (devnet) is the most accessible way to begin your hands-on Filecoin journey. A local devnet lets you experiment with sealing sectors and observe firsthand how the process works without risking real FIL or affecting the mainnet.
[Local devnet ->](/networks-and-tools/networks/local-testnet)
## Become a storage provider
Once ready, determine your starting capacity and architect a solution to accommodate it. Equip yourself with the necessary hardware and test your setup on the calibration testnet to fine-tune your skills and ensure seamless operations before joining the mainnet.
[Reference architectures ->](/provide-storage/infrastructure/reference-architectures)
## Configure PoRep deal-making and retrieval services
As you step into the mainnet, Curio's built-in storage market lets you accept PoRep storage deals and serve retrievals to data owners. Boost is no longer compatible with current Curio releases.
[Curio storage market ->](https://docs.curiostorage.org/curio-market/storage-market)
## Explore verified deals and ecosystem tools
Within the Filecoin network there are many programs and tools designed to enhance your storage provider setup. Explore the documentation to gain insights into verified deals, client programs, and other resources that can improve your operations and expand your client base.
[Filecoin programs ->](/provide-storage/filecoin-deals/filecoin-programs)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/storage-providers/getting-started)
# Storage Provider Agent Quickstart
One page covering everything you need to start providing storage on Filecoin: as a PDP service provider, a consensus miner, both on one Curio cluster, or a cold storage (FCSS) provider.
**Using an AI agent?** Copy this prompt into it and it will walk you through the page:
{% code overflow="wrap" %}
```
Help me become a Filecoin storage provider by following this page step by step:
https://docs.filecoin.io/provide-storage/agent-quickstart.md
Read the whole page before you start. Then:
1. Ask me which path I want (A, B or C) using the "Choose your path" table, and check my hardware against it.
2. Work on the Calibration testnet first. Don't move to mainnet until I say so.
3. Run the commands for my path in order, and run each check in "Quick reference for agents" before moving on.
4. Stop and hand over to me for anything you can't or shouldn't do yourself: DNS records, buying or sending FIL, steps in the Curio web GUI, and creating or exporting private keys.
5. Never ask me to paste a private key, seed phrase or wallet export into this chat.
6. If a step fails or the page doesn't match what you see, stop and tell me what happened and which step it was.
```
{% endcode %}
This page walks you through becoming a Filecoin storage provider, from choosing a path to running your first proofs. It is optimized for agents, but a human should be able to follow, if you have read [Plan Your Filecoin Storage Provider Business](/provide-storage/getting-started). It's written so that a person or an AI agent can follow it from top to bottom without needing any other page.
There are three kinds of storage you can provide on Filecoin today: warm storage for the Filecoin Warm Storage Service (FWSS), proven with PDP; consensus mining, sealed with PoRep; and cold storage for the Filecoin Cold Storage Service (FCSS), which seals client datasets with PoRep on a consensus-mining cluster. Both FWSS and FCSS are part of Filecoin Onchain Cloud. This page has four paths. Pick one before you buy hardware, because they need very different machines, amounts of capital, and skills.
## Choose your path
| | **A: Storage Service (PDP)** | **B: Consensus Mining** | **C: Both (one cluster)** | **D: Cold Storage Service (FCSS)** |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **What you do** | Store client data as-is and prove you still hold it using Proof of Data Possession (PDP). You serve it over HTTPS as part of Filecoin Onchain Cloud. | Seal data or empty capacity into sectors using Proof of Replication (PoRep). You prove the sectors every 24 hours, gain storage power, and compete to produce blocks. | Everything in B, plus PDP service storage for clients, all on the same Curio cluster. | Seal client datasets that the PoRep Market matches to your offers, prove them as in B, and serve them for retrieval. |
| **How you earn** | Storage fees from clients, paid in USDFC through Filecoin Pay. | Block rewards (FIL) plus fees from storage deals. | Block rewards and PoRep deal fees (as in B), plus PDP storage fees in USDFC (as in A). | Block rewards (as in B), plus FCSS deal payments in USDFC through Filecoin Pay, scaled by how well you meet each deal's service levels. Optionally, paid retrievals. |
| **Collateral** | No sector pledge. A small FIL balance pays for proof messages. | FIL initial pledge locked for each sector, plus a working balance for fees and messages. | B's pledge and balances, plus a small FIL balance in a separate PDP wallet. | As in B. |
| **Minimum hardware** | 1 server: 16+ threads, 64 GB+ RAM, 1 TiB NVMe for the chain and database, 10 TiB+ HDD for client data. No GPU. | A sealing and proving cluster: SHA-extension CPUs, 512 GiB–1 TiB RAM on sealing nodes, 10 GB+ GPUs, several TiB of NVMe scratch, and PiB-scale disk to be competitive. | B's cluster, plus disk set aside for PDP pieces and a public HTTPS domain. | B's cluster, plus disk for unsealed copies of client data and bandwidth to download datasets and serve retrievals. |
| **Software** | Curio-PDP in Docker (bundles Forest and YugabyteDB). | Lotus + YugabyteDB + Curio. | B's stack with PDP turned on in Curio. **Curio labels this alpha.** | B's stack with Curio's market turned on, plus the PoRep Market CLI. |
| **Time to first proof** | Hours, mostly waiting for the chain to sync. | Days to weeks, including hardware setup, chain sync, and sealing. | Same as B for mining. PDP adds a few hours once B is running. | Same as B. Your first deal also needs FCSS registration and KYC, and a client whose terms match your offer. |
| **Retrieval** | Data is always hot and served over HTTPS. | Sealed data must be unsealed (or kept unsealed) to serve retrievals. | As in B for sealed sectors. PDP data is always hot. | Keep an unsealed copy and serve pieces over HTTPS, free or paid per piece. Deals set retrievability, bandwidth, and latency terms. |
| **Good fit if you…** | Run reliable, internet-facing servers and want a fast, low-capital start. | Run data-center infrastructure, can lock up FIL, and want to earn block rewards. | Already mine (or are building a mining cluster), want service-deal revenue on the same infrastructure, and accept an alpha feature. | Run (or are building) a PoRep cluster and want client datasets matched to you, with terms set up front and payment on chain. |
How to choose:
* **Path A** if you want to be a service provider only, with no mining, pledge, or sealing hardware.
* **Path B** if you want to be a consensus miner. Step B12 (optional) adds sealed PoRep storage deals through Curio's built-in market, but no PDP service deals.
* **Path C** if you already run, or are setting up, a Path B cluster and also want PDP service deals on the same hardware without standing up a second Curio-PDP stack. You must be willing to run a feature that Curio labels alpha. If you'd rather avoid that, run Path A on separate hardware next to your Path B cluster.
* **Path D** if you run, or are setting up, a Path B cluster and want sealed client datasets from FCSS. The PoRep Market matches clients' deals to your offers, so you don't need to find clients yourself.
All four paths run on Curio, so skills carry over. Many operators start with Path A and add mining later.
Planning to become a storage provider? Tell us about your setup in the [storage provider interest form](https://docs.google.com/forms/d/e/1FAIpQLSdTd7Znz5uJeF8f98LccjZ-q7dq9Nh861t_rFkH_kcNO6HCtw/viewform).
{% hint style="info" %}
**Always start on the Calibration testnet.** Calibration is a full copy of the network that uses free test FIL (tFIL). Every step on this page works on Calibration first. Once your setup survives a few days of proving there, repeat the same steps on mainnet.
{% endhint %}
Jump to your path:
* [Path A: Storage Service (PDP)](#path-a)
* [Path B: Consensus Mining](#path-b)
* [Path C: Both (one cluster)](#path-c)
* [Path D: Cold Storage Service (FCSS)](#path-d)
***
## Before you start (all paths)
You need the following no matter which path you choose:
* **Linux admin skills.** You'll work in a terminal on Ubuntu or Debian (22.04 or newer recommended), manage systemd services or Docker containers, open firewall ports, and read logs.
* **A machine that stays online.** Every path proves to the chain on a fixed schedule. When your node is down, proofs are missed. On the consensus path, missed proofs cost you FIL (see [Know the penalties](#b1-understand-the-economics)).
* **A way to get FIL.** On Calibration, a faucet gives you tFIL for free. To find one, search "Filecoin Calibration faucet"; the ChainSafe faucet at `faucet.calibnet.chainsafe-fil.io` is a common choice. On mainnet you buy FIL.
* **A place to ask for help.** In the Filecoin Slack, `#fil-curio-help` covers Curio, `#fil-sp-help` covers Filecoin Onchain Cloud (PDP, FWSS, and FCSS), and `#fil-lotus-help` covers Lotus.
***
## Path A: Storage Service (PDP)
A PDP service provider stores client data and answers random, on-chain challenges that prove the data is stored. PDP is the verification layer of data storage. Clients pay providers through **Filecoin Pay**. Once you register your node with the SP registry, services can find you. You will get client deals if you meet the SLA requirements of services, like Filecoin Warm Storage Service (FWSS).
Here's how PDP proving works. You compute Merkle trees over the pieces you store. A smart contract uses the drand randomness beacon to challenge you at random. You answer with Merkle inclusion proofs, and the contract checks them on-chain.
You'll run **Curio-PDP**, the Docker-based, PDP-only build of Curio. Release images are published on Docker Hub as `filecoin/curio-pdp` ([tags and networks](https://github.com/filecoin-project/curio/blob/main/documentation/en/curio-pdp.md#published-images)). It is the supported way to run a PDP-only provider. One `docker compose` stack runs three containers:
* **Forest**, a Filecoin chain node. It downloads a snapshot and syncs automatically.
* **YugabyteDB**, which stores Curio's state, piece indexes, and your PDP wallet key.
* **Curio-PDP**, which runs PDP proving, the public PDP HTTPS API, and a local admin GUI.
### A1. Get the hardware and a domain
| Resource | Requirement |
| --------- | ------------------------------------------------------------------------------------------------------ |
| CPU | 16+ threads |
| RAM | 64 GB+ |
| Fast disk | 1 TiB+ NVMe or SSD for the chain, the database, and the Curio repo |
| Bulk disk | 10 TiB+ HDD (or more) for client piece data |
| GPU | Not required |
| Network | Public IPv4 address and stable upstream bandwidth |
| DNS | A domain name (for example `pdp.example.com`) with an **A record pointing to your server's public IP** |
| Firewall | Inbound **TCP 80 and 443 only**. Keep everything else closed. |
Curio-PDP gets a TLS certificate from Let's Encrypt automatically. For that to work, your domain must already resolve to the server and port 443 must be reachable from the internet.
#### Start at any size
The table above is the floor for one node. How much storage you put behind it is up to you: you declare it as Storage Capacity (TiB) when you register (A9) and can change it later.
| Size | What it looks like |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solo** | One machine at the floor above. Start with 10 TiB+ of HDD and add disks as you fill. Today's endorsed providers declare between 60 and 500 TiB. |
| **Renting (colocation/DC operator)** | A bare-metal storage server from a large host, 40 to 175 TiB raw per box before RAID. Take the 64 GB memory option if you run Lotus. |
| **Enterprise Data Center Operator** | 1 PiB and up: the floor above per head node, with JBOD shelves for piece data. Node counts and shelf sizing to follow. |
### A2. Install Docker
If Docker isn't installed yet, install Docker Engine and the Compose plugin:
```sh
sudo apt update && sudo apt install -y ca-certificates curl git
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER" # log out and back in afterwards
docker compose version
```
### A3. Get Curio-PDP and configure your disks and domain
Clone the Curio repository **onto your fast disk** and go to the Curio-PDP compose directory:
```sh
cd /mnt/nvme # your NVMe/SSD mount
git clone https://github.com/filecoin-project/curio.git
cd curio/docker/skiff
```
Edit `.env` in this directory **before the first start**. The domain is written into Curio's configuration on first start, and the data paths decide which disk everything lands on.
```bash
# Image: use the published release image, not the default :dev
SKIFF_IMAGE=filecoin/curio-pdp:calibnet # Calibration
# SKIFF_IMAGE=filecoin/curio-pdp:latest # Mainnet
# Your public PDP domain (must already resolve to this server)
SKIFF_HTTP_DOMAIN=pdp.example.com
# Fast disk (NVMe/SSD): database, chain, Curio repo
YUGABYTE_DATA=/mnt/nvme/curio-pdp/yugabyte
FOREST_DATA=/mnt/nvme/curio-pdp/forest
FOREST_TOKEN_DATA=/mnt/nvme/curio-pdp/forest-token
SKIFF_REPO_DATA=/mnt/nvme/curio-pdp/skiff
# Bulk disk (HDD): client piece data, visible inside the container as /data
SKIFF_STORAGE=/mnt/hdd/curio-pdp-pieces
```
Create the directories you listed:
```sh
mkdir -p /mnt/nvme/curio-pdp/{yugabyte,forest,forest-token,skiff} /mnt/hdd/curio-pdp-pieces
```
{% hint style="info" %}
Curio-PDP ships with its own Forest chain node. If you already run a synced Lotus or Forest node, set `FULLNODE_API_INFO` in `.env` (for example `FULLNODE_API_INFO=/ip4/host.docker.internal/tcp/1234/http` for Lotus on the same host). Inside the container, use `host.docker.internal` or a LAN IP, never `127.0.0.1`.
{% endhint %}
### A4. Start the stack
**Calibration:**
```sh
docker compose -f docker-compose.yaml -f docker-compose.calibnet.yaml up -d
```
**Mainnet:**
```sh
docker compose up -d
```
Check health and follow the logs (Ctrl-C stops following, not the containers):
```sh
docker compose ps
docker compose logs -f
```
On first start, Forest downloads a chain snapshot. The mainnet snapshot is large, so this can take a while. Curio-PDP starts as soon as Forest accepts RPC connections, but wallet balances and FWSS registration only work **after Forest has finished syncing**. To watch progress:
```sh
docker compose logs -f forest
```
To stop the stack later, run `docker compose down`. Your data remains in the directories set in `.env`.
### A5. Open the admin GUI
The admin GUI listens on `127.0.0.1:4701` on the server. **It has no login.** Anyone who can reach it can manage your keys, so never expose port 4701 to the internet.
From your laptop, open an SSH tunnel to the server and browse to it locally:
```sh
ssh -fN -L 4701:127.0.0.1:4701 youruser@your-server
# then open http://127.0.0.1:4701 in your browser
```
### A6. Attach piece storage
In the GUI, open **Storage**:
1. Pick a suggested folder under `/data`. This is the `SKIFF_STORAGE` bulk disk from `.env`. You can also enter any existing path inside the container.
2. Select **Attach**. Paths aren't registered automatically, so you must attach at least one.
Client piece data is written to the attached folders. Piece indexes stay in YugabyteDB on your fast disk.
### A7. Create and fund your PDP wallet
Curio-PDP signs its on-chain PDP messages with an Ethereum-style (0x) key stored in YugabyteDB.
1. In the GUI, open **PDP** → wallet section.
2. Choose one:
* **Create** generates a new key on the node. **The private key is shown only once.** Copy it into your password manager or secrets store before you close the dialog.
* **Import** lets you paste the hex private key of a 0x address you already control.
3. Copy the **0x address** that the GUI displays and fund it:
* **Calibration:** at least **5 tFIL** from a faucet.
* **Mainnet:** about **8 FIL**. Any wallet or exchange that can send to a 0x (f410) address works.
This balance pays gas for registration and for your ongoing proof messages. Keep it topped up. Curio allows only one PDP key per cluster.
{% hint style="warning" %}
The key lives in YugabyteDB. Back up the `YUGABYTE_DATA` directory, or use YugabyteDB's backup tooling, before you redeploy or move servers. If you lose the database without a backup, you lose the key.
{% endhint %}
### A8. Turn on the public HTTPS endpoint
In the GUI, open **Configurations** and edit the **`base`** layer. Curio-PDP reads only `base`, so don't create separate layers. Confirm these values:
```toml
[Subsystems]
EnablePDP = true
EnableWebGui = true
GuiAddress = "127.0.0.1:4701" # never 0.0.0.0
[HTTP]
Enable = true
DomainName = "pdp.example.com"
DelegateTLS = false # Curio-PDP terminates TLS itself using Let's Encrypt on port 443
```
Save, then restart Curio-PDP:
```sh
docker compose restart skiff
```
From a machine **outside** your network, check that the endpoint answers over HTTPS:
```sh
curl https://pdp.example.com
```
The response should be a short "Hello" message from Curio. If the check only succeeds from the server itself, see [A10. Troubleshooting](#a10-troubleshooting).
### A9. Register with the Filecoin Warm Storage Service
Registration publishes your node to the on-chain FWSS service provider registry. That's how clients find you.
In the GUI, open **PDP** and find the registration section (labelled **Register**, or **Filecoin Service Registry**):
1. **Register Provider.** Fill in these fields, then submit:
| Field | Value |
| ---------------------- | ------------------------------------------------------------------------ |
| Name | Up to 128 characters |
| Description | Up to 256 characters |
| Location | For example `C=US;ST=California;L=San Francisco`. Only `C=` is required. |
| Storage Capacity (TiB) | Your available capacity, as a whole number of TiB |
The **Register Provider** button stays disabled until your PDP wallet from A7 is set up and funded. Registration also publishes a default PDP offering: pieces from 1 MiB to 64 GiB, IPNI on, and the default proving period.
2. **Update PDP Offering.** Set **Service URL** to `https://pdp.example.com` and check the location and capacity. Then use **Add Capability** to add the key `serviceStatus` with the value `prod`, and submit.
Each submission is an on-chain transaction paid from your PDP wallet. You can come back and change the offering at any time.
**You don't set a price.** The FWSS contract fixes the price for every provider: **2.5 USDFC per TiB per month**, plus **0.12 USDFC per data set per month**, plus a **0.5% network fee** taken at settlement. There's no price field to fill in, and the offering can't change these rates.
**Registering doesn't bring client data right away.** Registration puts you in the registry. Before any client data is sent to you, the network tests your node and the working group approves you. Expect a gap between registering and your first data. Keep the node online, proving, and reachable while you wait.
Optionally, confirm end-to-end reachability with `pdptool`, which ships in the Curio repo and needs Go installed:
```sh
cd ~/curio/cmd/pdptool && go build . # use the path where you cloned Curio in A3
./pdptool ping --service-url https://pdp.example.com --service-name public
# Expected: Ping successful: Service is reachable and JWT token is valid.
```
**You're now a PDP service provider.** Your node syncs the chain, stores pieces on your bulk disk, answers PDP challenges, and is listed in the FWSS registry. When you're comfortable on Calibration, repeat A3–A9 on mainnet with the mainnet image, a mainnet domain, and a new mainnet data directory.
### A10. Troubleshooting
| Symptom | What to check |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| Wallet balance shows an error | Forest is still syncing. Run `docker compose logs -f forest` and wait. |
| Curio-PDP can't reach the chain node | Bundled Forest: check that the `forest` container is healthy. External node: use `host.docker.internal` or a LAN IP, not `127.0.0.1`. |
| "PDP wallet not configured" alert | Complete [A7](#a7-create-and-fund-your-pdp-wallet). |
| No storage paths | Complete [A6](#a6-attach-piece-storage). Check that the container can write to the folder. |
| HTTPS works locally but not remotely | Check that the DNS A record points to your public IP, that ports 80 and 443 are open inbound, and that no other service holds port 443. |
| Registration fails | Check that the wallet is funded, Forest is synced, and `HTTP.DomainName` matches a domain that resolves to this server. |
***
## Path B: Consensus Mining
A consensus miner (the traditional Filecoin storage provider) commits storage to the network in **sectors**. Each sector is 32 GiB or 64 GiB of data, or empty "committed capacity," sealed with Proof of Replication. The sectors you prove give you **storage power**. Every 30-second epoch, the network elects miners in proportion to their power to produce blocks and earn **block rewards**.
A PoRep-backed provider can also earn Filecoin Onchain Cloud (FOC) service revenue on the same cluster: sealed cold storage deals from FCSS (see [Path D](#path-d)), or PDP warm storage deals (see [Path C](#path-c)).
You'll run three pieces of software:
* **Lotus**, a full Filecoin chain node. It syncs the chain, holds your wallets, and sends messages.
* **YugabyteDB**, the database that coordinates every Curio node in your cluster (Curio calls it HarmonyDB).
* **Curio**, the storage provider software. It seals sectors, runs WindowPoSt and WinningPoSt, and runs the storage market. It replaces the older `lotus-miner`, `lotus-worker`, and Boost stack. Boost no longer works with current Curio releases.
If you still run `lotus-miner` and Boost, move to Curio with **Migrate from existing Lotus-Miner** in [B8](#b8-create-your-miner). Docs for the older stack: [Boost](https://boost.filecoin.io).
### B1. Understand the economics
Read this section before you buy anything. Consensus mining locks up capital, and penalties are automatic.
**How you prove storage:**
* **Sealing (PoRep).** Sealing encodes each sector into a unique replica. It's the compute-heavy step, and it's what your sealing hardware is for.
* **WindowPoSt.** Every sector is proven once every 24 hours. The day is split into 48 deadlines of 30 minutes each. Your sectors are assigned to deadlines, and you must submit each proof on-chain within its 30-minute window.
* **WinningPoSt.** When you're elected to produce a block, you must produce a short proof within seconds to claim the reward.
**How you earn:**
* **Block rewards.** Your odds of winning a block are proportional to your share of network power. You need **at least 10 TiB of raw power** to be eligible at all. Even above that threshold, small miners may wait a long time for their first block. 25% of each reward is available immediately; the other 75% vests over about 180 days.
* **Deal fees.** Clients can pay you to store their data in your sectors.
* **Quality-adjusted power.** From the Solstice network upgrade ([FIP-0118](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0118.md)), every new sector gets 10× quality-adjusted power, with or without client data, and Filecoin Plus datacap is retired. Existing sectors can be upgraded to 10×. The multiplier raises your block-reward odds and your pledge by the same factor. Until Solstice reaches mainnet, only verified deals (Filecoin Plus) get it.
**What you lock up and pay:**
* **Initial pledge.** FIL locked per sector for the sector's lifetime. As a rule of thumb, *pledge for X TiB ≈ (current initial pledge per 32 GiB sector) × 32 × X*. Chain explorers show the current per-sector pledge. For example, at 0.20 FIL per sector, 100 TiB needs about 640 FIL.
* **Pre-commit deposit.** A smaller deposit when a sector is pre-committed. You lose it if the sector never completes sealing.
* **Gas.** Paid for pre-commit, prove-commit, and WindowPoSt messages.
* **Daily sector fee (FIP-0100).** Every new, extended, or updated sector pays a small daily fee based on its power. The fee comes first from your vesting rewards, then from your miner's available balance. Any shortfall becomes **fee debt**. While you have fee debt, you can't win block rewards, and some messages (such as new pre-commits) may be blocked.
**What it costs you when things go wrong:**
* **Fault fee.** Charged for each day a sector misses its WindowPoSt.
* **Sector penalty.** Charged for a fault you didn't declare before the proof was due.
* **Termination fee.** Charged when a sector ends early.
* **Consensus fault slashing.** For provably malicious behavior.
{% hint style="warning" %}
**Plan for the startup gap.** Before your first block reward arrives, you pay pledge, gas, and daily fees out of pocket. Keep a FIL buffer in your miner actor for fees and WindowPoSt messages, and don't withdraw it all. An underfunded miner can get stuck: it can't seal new sectors, it can miss proofs, and it can't win blocks.
{% endhint %}
Committed capacity (CC) sectors, which are sealed with no client data, are the simplest way to start. Their profitability depends heavily on the FIL price. Most serious operators add client deals over time, either by sealing them into new sectors or by upgrading CC sectors in place with SnapDeals.
### B2. Get the hardware
You can start on Calibration with everything on one large machine. A production mainnet setup splits the work across roles. Sector sizes on Calibration match mainnet, so you need real sealing hardware on Calibration too.
| Role | Typical spec | Notes |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chain node** (Lotus) | 8+ cores, 64 GiB+ RAM, 2 TB NVMe, public IP | Must be available at all times. Run a second daemon for failover in production. |
| **YugabyteDB** | 3 nodes in production (can share hosts with Curio) | A single node is fine for testing. In production, losing the database stops Curio, so run 3+ nodes, back them up, and don't use ZFS for the database disks. |
| **PoSt node(s)** (Curio `post` layer) | 16 cores, 128 GiB+ RAM, 1 GPU with 10 GB+ VRAM | Runs WindowPoSt and WinningPoSt. Run at least two for redundancy. Missing a proof costs you FIL. |
| **Sealing: SDR (PC1)** | 32+ cores **with SHA extensions** (AMD EPYC or recent Xeon), 1 TiB RAM, about 450 GiB NVMe scratch per parallel sector | CPU-bound. Check support with `grep -c sha_ni /proc/cpuinfo` (any non-zero result means supported). |
| **Sealing: trees (PC2) and SNARK (C2)** | 32 cores, 512 GiB RAM, GPU with 24 GB+ VRAM, NVMe scratch | GPU-bound. Plan about two PC2 GPUs per PC1 node. |
| **Long-term storage** | Large HDD pools (for example RAIDZ2, 12-disk vdevs) with about 20% headroom | Holds sealed (and optionally unsealed) sectors. Must be readable by your PoSt nodes. |
| **Network** | 10 GbE internally, 1–10 Gbps internet if you take online deals | Deal data ingest is bandwidth-heavy. |
For scale, a well-balanced 1 PiB setup seals up to about 7 TiB per day. To start without owning sealing hardware, you can buy sealing from a Sealing-as-a-Service provider. You still need the chain node, the database, PoSt nodes, and storage.
### B3. Prepare each Linux host
Run the following on every host that will run Lotus or Curio (Ubuntu or Debian).
```sh
sudo apt update && sudo apt upgrade -y && sudo apt install -y \
mesa-opencl-icd ocl-icd-opencl-dev gcc git jq pkg-config curl clang \
build-essential hwloc libhwloc-dev libarchive-dev wget ntp \
python-is-python3 aria2 libgmp-dev libconfig++-dev protobuf-compiler
# Raise the UDP buffer (needed by Curio and Lotus networking)
sudo sysctl -w net.core.rmem_max=2097152
sudo sysctl -w net.core.rmem_default=2097152
echo 'net.core.rmem_max=2097152' | sudo tee -a /etc/sysctl.conf
echo 'net.core.rmem_default=2097152' | sudo tee -a /etc/sysctl.conf
```
If you'll build from source, which you must for Calibration, also install Go and Rust. Use the Go version that Curio's `go.mod` requires (1.26.8 at the time of writing):
```sh
wget -c https://go.dev/dl/go1.26.8.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # choose the default install
source "$HOME/.cargo/env"
```
On GPU hosts, install your NVIDIA driver and the **CUDA Toolkit 12.x or later** so that `nvcc` is on your `PATH`. Curio's Linux build uses CUDA by default.
### B4. Run the Lotus chain node
Build Lotus from the latest release:
```sh
git clone https://github.com/filecoin-project/lotus.git && cd lotus
git checkout $(curl -s https://api.github.com/repos/filecoin-project/lotus/releases/latest | jq -r .tag_name)
make clean && make GOFLAGS="-tags=calibnet" lotus # Calibration
# make clean && make lotus # Mainnet
sudo make install-daemon
lotus --version
```
Import a recent snapshot instead of syncing from genesis, then start the daemon:
```sh
aria2c -x5 -o snapshot.car.zst https://forest-archive.chainsafe.dev/latest/calibnet/ # Calibration
# aria2c -x5 -o snapshot.car.zst https://forest-archive.chainsafe.dev/latest/mainnet/ # Mainnet
lotus daemon --import-snapshot snapshot.car.zst --remove-existing-chain --halt-after-import
nohup lotus daemon > ~/lotus.log 2>&1 &
lotus sync wait # returns when the node has caught up with the chain
```
In production, run the daemon as a systemd service rather than with `nohup`.
### B5. Create and fund your wallets
A miner needs an **owner** address (it controls the miner and receives withdrawals), a **worker** address (it signs routine messages), and a **sender** address (it pays for the create-miner message). The same address can fill more than one role. On the Lotus node, create two BLS wallets:
```sh
lotus wallet new bls # wallet 1: owner and sender
lotus wallet new bls # wallet 2: worker
lotus wallet list
```
Fund each wallet. On Calibration, about 5 tFIL each from a faucet is plenty to get started. On mainnet, the owner or miner balance must eventually cover your initial pledge (see [B1](#b1-understand-the-economics)).
{% hint style="danger" %}
Back up your owner key offline: `lotus wallet export > owner.key`. Store the file in a secure location, not on the server. Whoever holds the owner key controls your miner and its funds.
{% endhint %}
### B6. Run YugabyteDB
For a test setup, run a single node. For production, deploy a 3-node cluster using the same steps on each host.
```sh
# Raise the open-file limit first
echo "$(whoami) soft nofile 1048576" | sudo tee -a /etc/security/limits.conf
echo "$(whoami) hard nofile 1048576" | sudo tee -a /etc/security/limits.conf
ulimit -n 1048576
wget https://software.yugabyte.com/releases/2.25.1.0/yugabyte-2.25.1.0-b381-linux-x86_64.tar.gz
tar xvfz yugabyte-2.25.1.0-b381-linux-x86_64.tar.gz && cd yugabyte-2.25.1.0
./bin/post_install.sh
./bin/yugabyted start --advertise_address 127.0.0.1 \
--master_flags rpc_bind_addresses=127.0.0.1 \
--tserver_flags rpc_bind_addresses=127.0.0.1
./bin/yugabyted status
```
If the start fails with a locale error, run `sudo locale-gen en_US.UTF-8` and try again. The default connection values are host `127.0.0.1`, port `5433`, user `yugabyte`, password `yugabyte`, and database `yugabyte`.
### B7. Install Curio
**Mainnet, Debian package (recommended):**
```sh
sudo wget -O /usr/share/keyrings/curiostorage-archive-keyring.gpg https://filecoin-project.github.io/apt/KEY.gpg
echo "deb [signed-by=/usr/share/keyrings/curiostorage-archive-keyring.gpg] https://filecoin-project.github.io/apt stable main" \
| sudo tee /etc/apt/sources.list.d/curiostorage.list
sudo apt update
sudo apt install curio-cuda # NVIDIA GPUs
# sudo apt install curio-opencl # OpenCL GPUs
```
**Calibration, or building from source on any network:**
```sh
git clone https://github.com/filecoin-project/curio.git && cd curio
git checkout $(curl -s https://api.github.com/repos/filecoin-project/curio/releases/latest | jq -r .tag_name)
export RUSTFLAGS="-C target-cpu=native -g"
export FFI_BUILD_FROM_SOURCE=1
export FFI_USE_CUDA=1 FFI_USE_CUDA_SUPRASEAL=1 # NVIDIA; for OpenCL use FFI_USE_OPENCL=1 instead
make clean calibnet # Calibration
# make clean build # Mainnet
sudo make install # installs /usr/local/bin/curio
curio --version
```
Download the proving parameters on every Curio host. The download is large, so put the cache on fast disk:
```sh
export FIL_PROOFS_PARAMETER_CACHE=/mnt/nvme/filecoin-proof-parameters
curio fetch-params 32GiB
```
### B8. Create your miner
Run the guided setup on your first Curio node. Curio must be built for the same network as your Lotus node. A Calibration Lotus node can't be used with a mainnet Curio.
```sh
export FULLNODE_API_INFO=$(lotus auth api-info --perm admin | cut -d= -f2-)
curio guided-setup
```
1. Choose **Create a new miner**. If you're moving an existing `lotus-miner`, choose **Migrate from existing Lotus-Miner** instead, and run the setup on the `lotus-miner` host.
2. Enter your YugabyteDB connection details (the defaults from B6), then choose **Continue to connect and update schema**.
3. Enter your **owner**, **worker**, and **sender** addresses from B5. Set **Sector size** to `32 GiB`. You can't change the sector size later without creating a new miner.
4. Wait for the `CreateMiner` message to land. Curio prints your new miner ID (for example `t01004` on Calibration or `f0…` on mainnet) and writes it into the `base` configuration layer.
5. Choose what telemetry to share with the Curio team, then finish.
If a later step fails after the miner was created, complete the configuration with `curio config new-cluster `.
### B9. Run Curio as a service
Curio's configuration lives in YugabyteDB as stackable **layers**. `base` is always applied. The built-in layers `post` (WindowPoSt and WinningPoSt), `seal` (the full sealing pipeline), and `gui` (the web UI on port 4701) switch on the matching tasks. Each node runs the layers that match its hardware. On a single test machine, run all of them.
Create `/etc/curio.env`. The Debian package creates it for you, so just edit it.
```sh
CURIO_LAYERS=gui,post,seal
CURIO_ALL_REMAINING_FIELDS_ARE_OPTIONAL=true
CURIO_DB_HOST=127.0.0.1 # comma-separate all Yugabyte nodes in production
CURIO_DB_USER=yugabyte
CURIO_DB_PASSWORD=yugabyte
CURIO_DB_PORT=5433
CURIO_DB_NAME=yugabyte
CURIO_DB_CASSANDRA_PORT=9042
CURIO_REPO_PATH=/home/youruser/.curio # use an absolute path; systemd doesn't expand ~
CURIO_NODE_NAME=curio-1
FIL_PROOFS_USE_MULTICORE_SDR=1
FIL_PROOFS_PARAMETER_CACHE=/mnt/nvme/filecoin-proof-parameters
```
If you built from source, create `/etc/systemd/system/curio.service`:
```ini
[Unit]
Description=Curio
After=network.target
[Service]
ExecStart=/usr/local/bin/curio run
Environment=GOLOG_FILE="/var/log/curio/curio.log"
Environment=GOLOG_LOG_FMT="json"
EnvironmentFile=/etc/curio.env
LimitNOFILE=1000000
Restart=always
RestartSec=10
RestartForceExitStatus=100
[Install]
WantedBy=multi-user.target
```
Start it:
```sh
sudo mkdir -p /var/log/curio
sudo systemctl daemon-reload
sudo systemctl enable --now curio.service
systemctl status curio.service
```
To reach the web GUI, open an SSH tunnel to port 4701 (`ssh -fN -L 4701:127.0.0.1:4701 youruser@your-server`) and browse to `http://127.0.0.1:4701`. The GUI has no login, so don't expose it publicly. To add more machines, install Curio on each one, give it the same `/etc/curio.env` with the `CURIO_LAYERS` that match its role, and start the service.
### B10. Attach storage
Each Curio node needs to know where it can seal and where to store finished sectors. Run the following on the node that owns each disk:
```sh
curio cli storage attach --init --seal /mnt/nvme/sealing # fast NVMe scratch for sealing
curio cli storage attach --init --store /mnt/hdd/sectors # long-term storage for sealed sectors
curio cli storage list
```
To attach storage on a remote node, add `--machine :12300` after `cli`. Curio can place sealed and unsealed copies on different paths. Each path's `sectorstore.json` file controls which file types it accepts (`AllowTypes` and `DenyTypes`).
### B11. Test proving, then seal your first sectors
Before you seal anything, confirm that the cluster can compute a WindowPoSt:
```sh
curio test window-post task --addr
```
The task should be picked up by a node running the `post` layer and complete without errors. Then seal one committed-capacity sector end to end:
```sh
curio seal start --now --cc --count 1 --actor
curio seal events --actor # follow the pipeline
```
You can also watch the sector move through the pipeline (SDR, trees, pre-commit, PoRep, commit) on the sealing pipeline page in the GUI. When it finishes, your miner has storage power. Increase `--count` as your hardware allows. By default, sectors are committed for 1,278 days (about 3.5 years); set a different term with `--duration-days`.
Once you have **10 TiB of power**, you become eligible for block rewards.
### B12. Take storage deals (optional)
Sealing client data earns deal fees. From Solstice, the 10× power multiplier no longer depends on deals (see [B1](#b1-understand-the-economics)). Curio has a built-in storage market. You don't need Boost.
To have client deals matched to you, join the Filecoin Cold Storage Service: [Path D](#path-d) builds on this step. You can also take deals directly from clients you find yourself.
1. Point a domain at the node that will run the market, and open port 443 on it.
2. Put the domain in the `base` layer (`curio config edit base`):
```toml
[HTTP]
Enable = true
DomainName = "market.example.com"
ListenAddress = "0.0.0.0:443"
```
3. Create a `market` layer (`curio config edit market`) and add it to that node's `CURIO_LAYERS`:
```toml
[Subsystems]
EnableDealMarket = true
EnableCommP = true
EnableParkPiece = true
```
4. Restart Curio. If it fails to bind port 443, run `sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/curio` and restart again.
5. From outside your network, run `curl https://market.example.com`. You should get a "Hello" response from Curio.
To find clients, join FCSS ([Path D](#path-d)), or look at data onboarding programs. Ask in `#fil-curio-help` for current options.
**You're now a consensus miner.** Your miner has an on-chain identity, proves its sectors every day, gains power as it seals, and becomes eligible to win blocks. When you're ready for mainnet, repeat B4–B11 with mainnet builds, new wallets, and real FIL.
### B13. Day-two checklist
* **Watch every WindowPoSt deadline.** The GUI shows proving status per deadline. Set up alerts so a missed deadline pages a human.
* **Keep balances funded.** Keep enough FIL in your worker and sender wallets for messages, and in the miner actor for FIP-0100 daily fees. Fee debt blocks block rewards.
* **Keep the database healthy.** Losing YugabyteDB stops Curio, so run a multi-node cluster and back it up regularly.
* **Upgrade on time.** Network upgrades have hard deadlines, and outdated Lotus or Curio builds stop working at the upgrade epoch.
* **Protect your keys.** Store the owner key offline, restrict SSH access, and never expose ports 4701 (GUI) or 12300 (Curio API) to the internet.
***
## Path C: Both (Consensus Mining and Storage Service on one cluster)
This path is for operators who run a consensus-mining Curio cluster (Path B) and also want to take PDP service deals on the same cluster. You don't need a second Curio-PDP stack.
**Why this path exists.** A miner who wants revenue beyond block rewards can take sealed FCSS deals ([Path D](#path-d)), take deals directly, or add PDP service deals. This path covers PDP service deals. Once you register with FWSS, clients find you in the on-chain registry and pay you in USDFC through Filecoin Pay. Turning on PDP in the Curio cluster you already run lets it reuse your chain node, database, storage, and HTTPS endpoint.
{% hint style="danger" %}
**Curio labels PDP on a full cluster as alpha.** Curio lists "Enable PDP" (running PDP on a full Curio cluster) under **Experimental Features**. Its banner reads "ALPHA FEATURE - UNDER DEVELOPMENT" and says the feature is "intended for testing and experimental use only." Curio's experimental-features section says these features are not recommended for production. The `EnablePDP` setting's own description calls it **BETA** and says to enable it only on nodes that are part of a PDP network. Only the Docker-based Curio-PDP in Path A is labelled a supported path.
PDP runs in the same Curio processes and database that submit your WindowPoSt. Try this path on Calibration before you turn it on in a mainnet cluster that holds pledged sectors. If you don't want to run an alpha feature beside your mining, run Path A on separate hardware instead.
{% endhint %}
**What PDP adds and what it doesn't.** PDP data is stored unsealed as "piece" files under an internal placeholder actor (`f00`), not in your miner's sectors. It adds no storage power and doesn't improve your block-reward odds. It earns FWSS storage fees only. Your mining is unchanged.
**Before you start Path C:**
* Complete Path B steps **B1–B11**: economics, hardware, Lotus, wallets, YugabyteDB, Curio, miner, service, storage, and proving. B12 (PoRep deals) is optional. If you've done it, you already have the domain and HTTPS setup that C4 needs.
* Have a **domain** with an A record pointing to the Curio node that will serve PDP, with **inbound TCP 80 and 443** open to that node.
* Have **bulk disk** set aside for PDP pieces on a node running Curio.
* Have **8 FIL** for mainnet, or **5 tFIL** for Calibration, to fund a new PDP wallet.
The steps below are everything Path C adds on top of Path B.
### C1. Turn on Lotus's Ethereum RPC and indexer
PDP talks to its smart contracts through your Lotus node's Ethereum-compatible RPC. Curio's PDP guide says to turn these settings on if Curio reports errors about them. Turning them on now avoids that. On the Lotus node from B4:
```sh
sed -i 's/^\( *\)#*EnableEthRPC = .*/\1EnableEthRPC = true/; s/^\( *\)#*EnableIndexer = .*/\1EnableIndexer = true/' ~/.lotus/config.toml
# then restart the Lotus daemon
```
### C2. Check your Curio build
The standard Curio binary you installed in B7 includes the PDP code, and PDP turns on through configuration. You don't need a different build. Keep Curio on a recent release, because PDP's database tables are added by Curio's automatic schema migrations when it starts. After upgrading, check the Curio startup logs for the schema upgrade.
{% hint style="warning" %}
Curio's "Enable PDP" page tells you to build from a branch named `pdpM3d`. That branch no longer exists in the Curio repository (checked 2026-09-26). Use the release build from B7.
{% endhint %}
### C3. Attach PDP storage and keep it off your sealed disks
PDP pieces are stored as the `piece` file type. They need a **store** path. A `--seal`-only path won't accept PDP uploads. On the node that owns the PDP disk:
```sh
curio cli storage attach --init --store --allow-types piece /mnt/pdp
```
To keep PDP pieces off the long-term paths that hold your sealed sectors, deny the `piece` type on those paths. Add `"DenyTypes": ["piece"]` to each path's `sectorstore.json` file, then restart Curio on that node. For new paths, attach them with `--deny-types piece` instead. Pieces parked by the storage market (B12) use the same `piece` type, so they also land on the PDP disks.
### C4. Add a `pdp` configuration layer
Create the layer with `curio config edit pdp` (or in the GUI under **Configurations**):
```toml
[Subsystems]
EnableParkPiece = true
EnablePDP = true
EnableCommP = true
EnableMoveStorage = true
```
PDP also needs Curio's HTTPS server. If you completed B12, HTTPS is already set up in `base` and one domain serves both the market and PDP. Otherwise, add the `[HTTP]` block from B12 step 2 to `base` (`Enable = true`, your `DomainName`, and `ListenAddress = "0.0.0.0:443"`).
Add `pdp` to `CURIO_LAYERS` in `/etc/curio.env` on the node that serves HTTPS and can reach the PDP storage (for example `CURIO_LAYERS=gui,post,seal,pdp`). Then restart it:
```sh
sudo systemctl restart curio.service
```
If Curio can't bind port 443, run `sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/curio` and restart again.
### C5. Create, import, and fund the PDP wallet
PDP signs its messages with an Ethereum-style (0x) key. Create a new **delegated** wallet on your Lotus node for this purpose, separate from your owner and worker wallets:
```sh
lotus wallet new delegated # prints a t410…/f410… address
lotus wallet export | xxd -r -p | jq -r '.PrivateKey' | base64 -d | xxd -p -c 32
```
The second command prints the key as 64 hex characters. In the Curio GUI, open **PDP** → **Owner Address** → **Import Key**, paste the key into **Private Key (Hex)**, and confirm. The matching 0x address appears on the page. Fund it with **8 FIL** on mainnet or **5 tFIL** on Calibration, and keep it topped up for proof messages.
{% hint style="warning" %}
The hex key you just printed controls the PDP wallet. Don't leave it in your shell history or in plain-text files. The imported key is stored in YugabyteDB, so keep backing up the database as B13 describes.
{% endhint %}
### C6. Verify and register with FWSS
From outside your network, check that the endpoint answers:
```sh
curl https://pdp.example.com
```
Then register with FWSS in the GUI's **PDP** page. The fields and suggested values are the same as in [A9](#a9-register-with-the-filecoin-warm-storage-service): Register Provider with your location and Storage Capacity (TiB), then Update PDP Offering with your service URL (pricing is set by the contract) and the `serviceStatus` capability. Confirm reachability with `pdptool ping --service-url https://pdp.example.com --service-name public`. The A9 section shows how to build `pdptool`.
**You're now running both.** Your cluster seals and proves sectors for block rewards and also stores and proves PDP data for FWSS clients. To operate it, follow B13 and add these checks:
* Keep the PDP wallet funded.
* Watch PDP proving in the GUI's **PDP** page alongside your WindowPoSt deadlines.
* Upgrade Curio promptly, because this feature is changing quickly.
***
## Path D: Cold Storage Service (FCSS)
This path is for operators who run a consensus-mining Curio cluster (Path B) and want sealed client datasets from the Filecoin Cold Storage Service (FCSS), the cold storage service of Filecoin Onchain Cloud.
**How FCSS deals work.** A client prepares a dataset, publishes its pieces and a manifest, and proposes a deal on the PoRep Market with its terms: duration, price, retrievability, bandwidth, latency, and IPNI indexing. The market matches the deal to a provider offer that meets those terms. You download the pieces, seal them, and claim the deal's DataCap allocations. While the deal is active, an oracle records your service-level indicators on chain, and Filecoin Pay pays you in USDFC according to how well you meet the deal's terms. See [Filecoin Cold Storage Service](/build-on-filecoin/filecoin-onchain-cloud/fcss) for the client side.
{% hint style="warning" %}
**FCSS runs on mainnet only.** Prove your cluster on Calibration with Path B first, then join FCSS with your mainnet miner.
{% endhint %}
**Before you start Path D:**
* Complete Path B steps **B1–B12**, including Curio's storage market in B12, with a domain that serves `https://` from outside your network.
* Have **disk for unsealed copies** of client data. Deals set retrievability, bandwidth, and latency terms, and you serve pieces from those copies.
* Have **bandwidth** to download client datasets, which are often many TiB, and to serve retrievals.
* Install **Python 3.10 or newer** and **`aria2`** (`sudo apt install aria2`) on the host that will download deal data.
### D1. Register as an FCSS provider
Register your organization at [peertopool.fidl.tech](https://peertopool.fidl.tech/): your name, server locations, miner IDs, and the client geographies you accept. Complete the KYC check that it emails you. Approved providers are listed in the public [FCSS provider directory](https://peertopool.fidl.tech/directory).
The PoRep Market CLI can't register your first miner until this step is done.
### D2. Create a controller wallet
Don't use your miner's owner or worker wallet for the PoRep Market. Create a separate delegated wallet, fund it with a little FIL for gas, and add it as a control address of every miner you'll use in FCSS. The PoRep Market checks control-address status to confirm that you may act for a miner.
```bash
lotus wallet new delegated
```
See [Control addresses](https://lotus.filecoin.io/storage-providers/operate/addresses/#control-addresses) for how to add it to your miner.
### D3. Install the PoRep Market CLI
```bash
git clone https://github.com/fidlabs/filecoin-porep-market-tooling
cd filecoin-porep-market-tooling
python3 -m pip install -r requirements.txt
cp .env.mainnet .env
chmod 600 .env
```
The PoRep Market uses controller status to verify that the command sender is authorised to send commands on behalf of your miner. Follow the steps here to create a miner controller wallet:
Export the private key of your newly created wallet:
```bash
lotus wallet export | xxd -r -p | jq -r '.PrivateKey' | base64 -d | xxd -p -c 32 | sed 's/^/0x/'
```
And set it as SP\_PRIVATE\_KEY in your .env file. The value you store there must be this exported private key in 32-byte hex format with a 0x prefix - not the wallet address you pass to lotus wallet export. You then should set your SP\_ORGANIZATION.
### D4. Register your miner and publish an offer
Register each miner with the capacity you'll give to FCSS and the address that receives payments:
```bash
python3 ./porep_tooling_cli.py sp register-sp --available-capacity --payee-address
```
Then publish an offer. It sets the deals the market may match to you: deal size, duration, minimum price per TiB per month, and the retrievability, bandwidth, latency, and IPNI indexing you guarantee. Run `sp register-offer --help` for every option. Deals last at least 6 months, and the market uses 32 GiB sectors only.
Check what you published with `sp get-sps` and `sp get-offers`.
### D5. Onboard deals
List the deals matched to your miners, then download and seal one:
```bash
python3 ./porep_tooling_cli.py sp get-deals ACCEPTED
python3 ./porep_tooling_cli.py sp onboard-data --output-dir /mnt/fcss-downloads --port 443 --claim-allocations curio
```
`onboard-data` reads the deal's manifest, downloads every piece with `aria2`, and with `--claim-allocations curio` hands each piece to Curio as a DDO deal (`curio market ddo`) to seal it and claim the deal's DataCap allocation. To claim later instead, run `sp claim-allocations curio `. `sp get-allocations ` and `sp get-claims` show progress.
### D6. Serve retrievals
Keep an unsealed copy of every FCSS piece and serve it from Curio's market over `https:///piece/`. FCSS measures retrievability, bandwidth, and latency against your deals' terms, and your payments depend on them.
To charge for retrievals, put the paid-retrieval proxy `sp-proxy` from [large-paid-retrievals](https://github.com/fidlabs/large-paid-retrievals#for-storage-providers) in front of your piece server. It quotes a price per piece and settles each payment through Filecoin Pay before it serves the data. Private deals are served only to the client and the wallets it authorizes.
### D7. Get paid
Payments for each deal accrue on a Filecoin Pay rail and settle to your payee address. Check and withdraw them with the CLI:
```bash
python3 ./porep_tooling_cli.py sp get-filecoinpay-account
python3 ./porep_tooling_cli.py sp withdraw-from-filecoinpay --help
```
**You're now an FCSS provider.** Your cluster mines as in Path B, and also seals and serves client datasets for FCSS. To operate it, follow B13 and add these checks:
* Watch for newly matched deals and onboard them promptly.
* Watch retrievals from outside your network: your payments depend on retrievability, bandwidth, and latency.
* Keep your offers' capacity current with `sp register-sp` and `sp set-offer-active`.
***
## Quick reference for agents
If you're automating any path, these are the minimum steps and the checks that must pass at each stage.
**Storage Service (Curio-PDP)**
1. The host meets A1. DNS A record → public IP. Inbound TCP 80 and 443 are open.
2. `git clone https://github.com/filecoin-project/curio.git && cd curio/docker/skiff`
3. Set `.env`: `SKIFF_IMAGE`, `SKIFF_HTTP_DOMAIN`, `*_DATA` → NVMe, `SKIFF_STORAGE` → HDD.
4. `docker compose [-f docker-compose.yaml -f docker-compose.calibnet.yaml] up -d`. Check: `docker compose ps` shows all three services healthy.
5. Wait for Forest to sync. Check: `docker compose logs forest` shows the chain at head.
6. GUI (`127.0.0.1:4701` via SSH tunnel) → Storage → attach `/data/...`.
7. GUI → PDP → Create or Import a key → fund the 0x address (5 tFIL or 8 FIL).
8. GUI → Configurations → `base`: `HTTP.Enable = true`, `HTTP.DomainName` set. Then `docker compose restart skiff`. Check: external `curl https://` succeeds.
9. GUI → PDP → Register Provider: name, description, location, Storage Capacity (TiB). Then Update PDP Offering: Service URL, `serviceStatus=prod`. Check: `pdptool ping --service-url https:// --service-name public` succeeds.
**Consensus Mining (Lotus + YugabyteDB + Curio)**
1. The host meets B2 and has the B3 packages. `sha_ni` is present on the SDR hosts.
2. Lotus is built for the target network, imported from a snapshot, and running. Check: `lotus sync wait` returns.
3. `lotus wallet new bls` ×2, funded. The owner key is exported and stored offline.
4. YugabyteDB is running. Check: `yugabyted status` reports healthy.
5. Curio is installed for the same network. Check: `curio --version`. Run `curio fetch-params 32GiB`.
6. `curio guided-setup` → Create a new miner → 32 GiB sectors. Record the miner ID.
7. `/etc/curio.env` with `CURIO_LAYERS=gui,post,seal`. `systemctl enable --now curio`.
8. `curio cli storage attach --init --seal …` and `--store …`.
9. Check: `curio test window-post task --addr ` succeeds.
10. `curio seal start --now --cc --count 1 --actor `. Check: the sector reaches the proving state and the miner has non-zero power.
**Both (Path B cluster + PDP, alpha)**
1. Complete consensus miner steps 1–10 above. A domain points to the PDP-serving node, and inbound TCP 80 and 443 are open.
2. Lotus `config.toml`: `EnableEthRPC = true`, `EnableIndexer = true`. Restart Lotus.
3. `curio cli storage attach --init --store --allow-types piece /mnt/pdp`. Add `"DenyTypes": ["piece"]` to the sealed store paths' `sectorstore.json` and restart Curio.
4. `pdp` layer: `EnableParkPiece`, `EnablePDP`, `EnableCommP`, `EnableMoveStorage`. `base`: `[HTTP] Enable = true`, `DomainName`, `ListenAddress = "0.0.0.0:443"`. Add `pdp` to `CURIO_LAYERS` and restart Curio. Check: external `curl https://` succeeds.
5. `lotus wallet new delegated` → export as hex → GUI → PDP → Import Key → fund the 0x address (5 tFIL or 8 FIL).
6. GUI → PDP → register with FWSS as in path A step 9. Check: `pdptool ping` succeeds.
**Cold Storage Service (Path B cluster + FCSS, mainnet)**
1. Complete consensus miner steps 1–10 above and B12's market. Check: external `curl https://` returns Curio's "Hello".
2. Register the organization and complete KYC at `peertopool.fidl.tech`. A person must do this step.
3. `lotus wallet new delegated`, fund it, and add it as a control address of each miner.
4. Clone `fidlabs/filecoin-porep-market-tooling`, `pip install -r requirements.txt`, `cp .env.mainnet .env`. Set `SP_ORGANIZATION`, `SP_LOTUS_WALLET`, `SP_LOTUS_TOKEN`.
5. `sp register-sp --available-capacity … --payee-address …`, then `sp register-offer …`. Check: `sp get-offers` lists the offer.
6. `sp get-deals AVAILABLE` → `sp onboard-data --output-dir --claim-allocations curio`. Check: `sp get-claims` lists the deal's claims.
***
## Getting help
* **Curio, sealing, and proving:** Filecoin Slack `#fil-curio-help`
* **PDP, FWSS, FCSS, and Filecoin Onchain Cloud:** Filecoin Slack `#fil-sp-help`
* **Lotus chain node:** Filecoin Slack `#fil-lotus-help`
When you ask for help, include your Curio and Lotus versions (`curio --version`, `lotus --version`), which network you're on, the exact command you ran, and the relevant log lines.
## Sources
This page copies facts from other documentation instead of linking to it, so it can be followed on its own. The table lists each copied fact, where it came from, and when it was last checked against that source, so maintainers can spot drift. Rows marked **estimate, not sourced** are editorial judgment and weren't verified against any source. Curio paths are relative to `documentation/en/` in the `filecoin-project/curio` repository; other paths are in this repository.
| Fact on this page | Source | Last verified |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Go version pin `1.26.8` (B3) | Curio `installation.md` and `experimental-features/Enable-PDP.md` (both defer to Curio's `go.mod`) | 2026-09-23 |
| CUDA Toolkit 12.x+ required; Linux build uses CUDA by default (B3, B7) | Curio `installation.md` | 2026-09-23 |
| Curio build flags, `make clean calibnet` / `make clean build`, Debian apt repository and `curio-cuda` / `curio-opencl` packages (B7) | Curio `installation.md` | 2026-09-23 |
| System packages and UDP buffer `sysctl` values (B3) | Curio `installation.md`; `storage-providers/pdp/install-and-run-pdp.md` | 2026-09-23 |
| Lotus build commands and Forest snapshot URLs (B4) | `storage-providers/pdp/install-and-run-pdp.md` | 2026-09-23 |
| YugabyteDB `2.25.1.0` tarball, `ulimit` values, start flags, default connection values (B6) | Curio `setup.md`; `storage-providers/pdp/install-and-run-pdp.md` | 2026-09-23 |
| YugabyteDB: 3+ nodes for production, no ZFS for database disks (B2, B6) | Curio `getting-started.md`, `setup.md`, `best-practices.md` | 2026-09-23 |
| Wallet roles (owner, worker, sender), 2 BLS wallets, about 5 FIL each, `curio guided-setup` flow, `curio config new-cluster` recovery (B5, B8) | Curio `setup.md` | 2026-09-23 |
| `/etc/curio.env` variables and `curio.service` unit (B9) | Curio `curio-service.md` | 2026-09-23 |
| Built-in config layers `post`, `seal`, `gui` (B9) | Curio `configuration/README.md` | 2026-09-23 |
| `curio cli storage attach` commands, port `12300`, `AllowTypes`/`DenyTypes` (B10) | Curio `storage-configuration.md` | 2026-09-23 |
| `curio seal start` flags and 1,278-day default duration; `curio test window-post task` (B11) | Curio `curio-cli/curio.md` | 2026-09-23 |
| Market settings `EnableDealMarket`, `EnableCommP`, `HTTP.DomainName` in `base` (B12) | Curio `curio-market/storage-market.md` | 2026-09-23 |
| `EnableParkPiece` in the market layer (B12) | Curio `market/mk12/mk12.go` (online deals park their data as short-term pieces) and `cmd/curio/tasks/tasks.go` (the ParkPiece task only runs when `EnableParkPiece` is on). Not in `storage-market.md`'s enable list. | 2026-10-06 |
| Boost no longer compatible with current Curio (Path B intro) | Curio `getting-started.md` | 2026-09-23 |
| Sealing and PoSt hardware specs: PoSt 16 cores / 128 GiB / 10 GB GPU; PC1 32 cores with SHA extensions / 1 TiB RAM / about 450 GiB scratch per sector; PC2 512 GiB / 24 GB GPU; about 2 PC2 per PC1; RAIDZ2 12-disk vdevs with 20% headroom; about 7 TiB/day for 1 PiB; 1–10 Gbps for deals (B2) | `storage-providers/infrastructure/reference-architectures.md` | 2026-09-23 |
| Run multiple PoSt nodes (B2) | Curio `best-practices.md` | 2026-09-23 |
| **Chain node sizing: 8+ cores, 64 GiB+ RAM, 2 TB NVMe (B2)** | **Estimate, not sourced.** | n/a |
| **Calibration uses the same sector sizes as mainnet, so it needs real sealing hardware (B2)** | **Estimate, not sourced** (general protocol knowledge, not checked against a source) | n/a |
| **Comparison-table summaries: time to first proof, "good fit if you…", "many operators start with PDP" (Choose your path)** | **Estimate, not sourced** (editorial judgment) | n/a |
| 10 TiB minimum raw power for block rewards (B1, B11) | `storage-providers/filecoin-economics/block-rewards.md`; `storage-providers/getting-started.md` | 2026-09-23 |
| 25% of block rewards immediately available, 75% vesting over about 180 days (B1) | Curio `readme/filecoin-storage-provider.md` | 2026-09-23 |
| 10× quality-adjusted power: verified deals only until Solstice; every new sector from Solstice, datacap retired, existing sectors upgradable (B1, B12) | FIP-0118 (Accepted) | 2026-10-01 |
| Initial pledge rule of thumb and 640 FIL example (B1) | `storage-providers/filecoin-economics/fil-collateral.md` | 2026-09-23 |
| WindowPoSt every 24 hours, 48 deadlines of 30 minutes (B1) | `storage-providers/filecoin-economics/storage-proving.md` | 2026-09-23 |
| FIP-0100 daily fee, fee-debt effects, startup funding gap (B1) | `storage-providers/getting-started.md` | 2026-09-23 |
| Fault fee, sector penalty, termination fee, consensus fault slashing (B1) | `storage-providers/filecoin-economics/slashing.md` | 2026-09-23 |
| PDP hardware floor: 16+ threads, 64 GB+ RAM (Choose your path, A1) | SP profile floor set 2026-09-28, measured with Lotus as the chain node; not yet measured for Forest | 2026-09-28 |
| PDP hardware: 1 TiB NVMe, 10 TiB HDD, no GPU, public HTTPS domain (Choose your path, A1) | Curio `experimental-features/Enable-PDP.md`; `storage-providers/pdp/install-and-run-pdp.md` | 2026-09-23 |
| PDP proving mechanics: Merkle trees, drand challenges, on-chain verification (Path A intro) | `storage-providers/pdp/about.md` | 2026-09-23 |
| Curio-PDP stack contents, `.env` variables, image tags `filecoin/curio-pdp:latest` / `:calibnet`, compose commands, GUI on `127.0.0.1:4701`, ports 80/443 only (A3–A5) | Curio `curio-pdp.md`; Curio `docker/skiff/docker-compose.yaml`, `docker-compose.calibnet.yaml`, `.env` | 2026-09-23 |
| `SKIFF_HTTP_DOMAIN` seeded into `base` on first start (A3) | Curio `docker/skiff/.env` (comment) | 2026-09-23 |
| Curio-PDP reads only the `base` layer; `EnablePDP`, `EnableWebGui`, `GuiAddress`, `HTTP.Enable` settings (A8) | Curio `curio-pdp.md`, `skiff-binary.md` | 2026-09-23 |
| `DelegateTLS = false` for Let's Encrypt on 443 and `docker compose restart skiff` (A8) | Inferred from the port labels and service name in Curio `docker/skiff/docker-compose.yaml`. **Not tested end to end.** | 2026-09-23 |
| PDP wallet Create/Import, one key per cluster, key stored in YugabyteDB (A7) | Curio `curio-pdp.md` | 2026-09-23 |
| PDP wallet funding: 5 tFIL (Calibration), 8 FIL (mainnet) (A7) | `storage-providers/pdp/install-and-run-pdp.md`; Curio `experimental-features/Enable-PDP.md` | 2026-09-23 |
| FWSS registration fields: name ≤ 128 chars, description ≤ 256 chars, location format, Storage Capacity (TiB) as a whole number, default offering (1 MiB–64 GiB pieces, IPNI on), Service URL and capability `serviceStatus=prod` (A9) | Curio `web/static/pages/pdp/register.mjs` and `web/api/webrpc/pdp.go` at v1.29.0-rc1; `documentation/en/experimental-features/Enable-PDP.md` | 2026-10-01 |
| FWSS pricing fixed by contract, not set by the SP: 2.5 USDFC per TiB per month, plus 0.12 USDFC per data set per month, plus a 0.5% network fee at settlement (A9) | Review, 2026-09-28 | 2026-09-28 |
| Registration doesn't route client data right away; the network tests the SP and the working group approves it first (A9) | Review, 2026-09-28 | 2026-09-28 |
| Registration section labelled **Register** / **Filecoin Service Registry** (A9) | Curio `curio-pdp.md` ("Register tab"); `storage-providers/pdp/install-and-run-pdp.md` ("Filecoin Service Registry"). Current UI label not confirmed. | 2026-09-23 |
| `pdptool ping` command and expected output (A9) | Curio `experimental-features/Enable-PDP.md` | 2026-09-23 |
| Curio-PDP troubleshooting table (A10) | Curio `curio-pdp.md` | 2026-09-23 |
| PDP on a full Curio cluster is alpha and experimental ("ALPHA FEATURE - UNDER DEVELOPMENT", "intended for testing and experimental use only"; experimental features not recommended in production) (Choose your path, Path C) | Curio `experimental-features/Enable-PDP.md` and `experimental-features/README.md` | 2026-09-26 |
| `EnablePDP` setting described as BETA, "should only be enabled on nodes which are part of a PDP network" (Path C) | Curio `deps/config/doc_gen.go` (the `EnablePDP` config comment) | 2026-09-26 |
| Docker-based Curio-PDP is the supported PDP-only path (Path C) | Curio `getting-started.md`, `curio-pdp.md` | 2026-09-26 |
| PDP pieces use the `piece` file type and placeholder actor `f00`, not the SP miner ID (Path C) | Curio `storage-configuration.md` | 2026-09-26 |
| **PDP data adds no storage power or block-reward odds (Path C)** | **Inference, not sourced.** Follows from PDP pieces not being sealed into the miner's sectors, but not stated in Curio's docs. | n/a |
| **Running PDP in the same processes and database as WindowPoSt is a reason to test on Calibration first (Path C)** | **Editorial judgment, not sourced.** | n/a |
| Standard `curio` binary includes PDP, enabled by config (C2) | Curio `skiff-binary.md` ("When PDP is enabled in full `curio`…") | 2026-09-26 |
| PDP schema added by HarmonyDB migrations on startup (C2) | Curio `experimental-features/Enable-PDP.md` | 2026-09-26 |
| Branch `pdpM3d` named in Curio's Enable PDP build step no longer exists (C2) | Checked against the `filecoin-project/curio` repository's branch list (GitHub API returned 404) | 2026-09-26 |
| `EnableEthRPC` / `EnableIndexer` `sed` fix for Lotus (C1) | Curio `experimental-features/Enable-PDP.md`; `storage-providers/pdp/install-and-run-pdp.md` | 2026-09-26 |
| `--allow-types piece` / `--deny-types piece` attach commands; PDP needs store paths, not seal-only; market parking shares the `piece` type (C3) | Curio `storage-configuration.md` | 2026-09-26 |
| `pdp` layer subsystems `EnableParkPiece`, `EnablePDP`, `EnableCommP`, `EnableMoveStorage`; `HTTP` `Enable`, `DomainName`, `ListenAddress 0.0.0.0:443`; `setcap` fix for port 443 (C4) | Curio `experimental-features/Enable-PDP.md` | 2026-09-26 |
| One domain can serve both market and PDP routes (C4) | Curio `experimental-features/Enable-PDP.md` ("Pattern A: single domain, one Curio HTTP server") | 2026-09-26 |
| Delegated wallet creation, hex key export pipeline, GUI **Import Key** flow, 8 FIL / 5 tFIL funding (C5) | Curio `experimental-features/Enable-PDP.md`; `storage-providers/pdp/install-and-run-pdp.md` | 2026-09-26 |
| Slack channels `#fil-curio-help`, `#fil-sp-help`, `#fil-lotus-help` (Before you start, Getting help) | Filecoin Slack (`#fil-pdp` renamed `#fil-sp-help` on 2026-09-30) | 2026-09-30 |
| FCSS provider registration, KYC, and directory at `peertopool.fidl.tech`; first SP must be registered there before `sp register-sp` (D1, D4) | `fidlabs/filecoin-porep-market-tooling` `cli/commands/sp/register_sp.py`; `peertopool.fidl.tech` | 2026-10-14 |
| Controller wallet as a miner control address, `SP_ORGANIZATION`, `SP_LOTUS_WALLET`, `SP_LOTUS_TOKEN`, `aria2`, `sp get-deals`, `sp onboard-data`, `sp get-allocations`, `sp claim-allocations {curio\|boost}`, Python 3.10+ (D2–D5) | `fidlabs/filecoin-porep-market-tooling` `README.md` and `.env.mainnet` | 2026-10-14 |
| `sp register-sp` and `sp register-offer` options; 6-month minimum duration; price per TiB per month (D4) | `fidlabs/filecoin-porep-market-tooling` `cli/commands/sp/register_sp.py`, `register_offer.py` | 2026-10-14 |
| 32 GiB sectors only (D4) | `fidlabs/filecoin-porep-market-tooling` `README.md` | 2026-10-14 |
| `--claim-allocations curio` runs `curio market ddo --actor ` (D5) | `fidlabs/filecoin-porep-market-tooling` `cli/commands/sp/claim_allocations.py` | 2026-10-14 |
| Deal matching to offers, DataCap evidence, per-deal Filecoin Pay validator, SLI oracle and scorer (Path D intro) | `fidlabs/porep-market` `README.md` | 2026-10-14 |
| `sp-proxy` paid retrievals, settle-before-serve through Filecoin Pay, private deals limited to the client (D6) | `fidlabs/large-paid-retrievals` `README.md` | 2026-10-14 |
| FCSS runs on mainnet only (Path D) | Confirmed by FIDL; `fidlabs/agent-skills` `fcss-client/SKILL.md` | 2026-10-14 |
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/storage-providers/agent-quickstart)
# Filecoin economics
How storage providers earn rewards, post collateral, and manage economic risks on Filecoin.
This section explains the financial mechanics of running a storage provider, including how rewards are earned, what collateral is required, and what penalties apply for failures.
## Table of contents
* [Storage proving](/provide-storage/filecoin-economics/storage-proving) — how providers prove they are storing data using Proof-of-Spacetime
* [FIL collateral](/provide-storage/filecoin-economics/fil-collateral) — the token commitment required to begin providing storage
* [Block rewards](/provide-storage/filecoin-economics/block-rewards) — how providers earn FIL by mining blocks based on storage power
* [Slashing](/provide-storage/filecoin-economics/slashing) — penalties for failing to prove storage or acting maliciously
* [Committed capacity](/provide-storage/filecoin-economics/committed-capacity) — sectors filled with placeholder data to earn consensus power
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/storage-providers/filecoin-economics)
# Storage proving
Storage proving, known as *Proof-of-Spacetime* (“PoSt”), is the mechanism that the Filecoin blockchain uses to validate that storage providers are continuously providing the storage they claim. Storage providers earn block rewards each time they successfully answer a PoSt challenge.
## Proving deadlines
As a storage provider, you must preserve the data for the duration of the [deal](/reference/general/glossary#deal), which are on-chain agreements between a client and a storage provider. As of March 2023, deals must have a minimum duration of 180 days, and maximum duration of 540 days. The latter value was chosen to balance long deal length with cryptographic security. Storage providers must be able to continuously prove the availability and integrity of the data they are storing. Every storage sector of 32 GiB or 64 GiB gets verified once in each 24 hour period. This period is called a *proving period*. Every proving period of 24 hours is broken down into a series of 30 minute, non-overlapping *deadlines*. This means there are 48 deadlines per day. Storage sectors are grouped in a *partition*, and assigned to a proving deadline. All storage sectors in a given partition will always be verified during the same deadline.
## WindowPoSt
The cryptographic challenge for storage proving is called *Window Proof-of-Spacetime* (WindowPoSt). Storage providers have a deadline of 30 minutes to respond to this WindowPoSt challenge via a message on the blockchain containing a [zk-SNARK](https://en.wikipedia.org/wiki/Zero-knowledge_proof) proof of the verified sector. Failure to submit this proof within the 30 minute deadline, or failure to submit it at all, results in *slashing*. Slashing means a portion of the [collateral](/provide-storage/filecoin-economics/fil-collateral) will be forfeited to the f099 burn address and the *storage power* of the storage provider gets reduced. Slashing is a way to penalize storage providers who fail to meet the agreed upon standards of storage.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/storage-providers/filecoin-economics/storage-proving)
# FIL collateral
This page discusses the concept of collateral in Filecoin for storage providers.
As a storage provider on the network, you will have to create FIL wallets and add FIL to them. This is used to send messages to the blockchain but is also used for collateral. Providing storage capacity to the network requires you to provide FIL as collateral, which goes into a locked wallet on your Lotus instance. The [Lotus documentation](https://lotus.filecoin.io/storage-providers/operate/addresses/) details the process of setting up your wallets and funding wallets for the initial setup. Filecoin uses upfront token collateral, as in proof-of-stake protocols, proportional to the storage hardware committed. This gets the best of both worlds to protect the network: attacking the network requires both acquiring and running the hardware, but it also requires acquiring large quantities of the token.
## Types of collateral
To satisfy the varied collateral needs of storage providers in a minimally burdensome way, Filecoin includes three different collateral mechanisms:
* *Initial pledge collateral*, an initial commitment of FIL that a miner must provide with each sector.
* *Block rewards as collateral*, a mechanism to reduce the initial token commitment by vesting block rewards over time.
* *Storage deal provider collateral*, which aligns incentives between storage provider and client and can allow storage providers to differentiate themselves in the market.
For more detailed information about how collateral requirements are calculated, see the [miner collateral section in the Filecoin spec](https://spec.filecoin.io/systems/filecoin_mining/miner_collaterals/).
When a storage provider fails to answer to the WindowsPoSt challenges within the 30-minute deadline (see [Storage Proving](/provide-storage/filecoin-economics/storage-proving)), storage is taken offline, or any storage deal rules are broken, the provider is penalized against the provided collateral. This penalty is called [*slashing*](/provide-storage/filecoin-economics/slashing) and means that a portion of the pledged collateral is forfeited to the `f099` address from your locked or available rewards, and your storage power is reduced. The `f099` address is the address where all burned FIL goes.
## Commit Pledge
The amount of required collateral depends on the amount of storage pledged to the Filecoin network. The bigger volume you store, the more collateral is required. Additionally, Filecoin Plus uses a [QAP](/reference/general/glossary#quality-adjusted-storage-power) multiplier to increase the collateral requirement. See [Verified Deals with Filecoin Plus](/provide-storage/filecoin-deals/verified-deals) for more information.
The formula for the required collateral is as follows:
*Collateral needed for X TiB = (Current Sector Initial Pledge) x (32) x (X TiB)*
For instance, for 100 TiB at 0.20 FIL / 32 GiB sector, this means:
*0.20 FIL x 32 x 100 = 640 FIL*
The “Current Sector Initial Pledge" can be found on blockchain explorers like [Filfox](https://filfox.info/en) and on the [Starboard dashboards](https://dashboard.starboard.ventures/capacity-services#commit-pledge-per-32gib-qap).
## Gas fees
Another cost factor in the network is gas. Storage providers not only pledge collateral for the capacity they announce on-chain. The network also burns FIL in the form of gas fees. Most activity on-chain has some level of gas involved. For storage providers, this is the case for committing sectors.
The gas fees fluctuate over time and can be followed on various websites like [Filfox - Gas Statistics](https://filfox.info/en/stats/gas/) and [Beryx - Gas Estimator](https://beryx.io/estimate_gas).
## FIL lending programs
The ecosystem has FIL lenders who can provide you FIL (with interest) to get you started, which you can pay back over time and with the help of earned block rewards. Every lender, though, will still require you to supply up to 20% of the required collateral. The [Filecoin Virtual Machine](/core-concepts/filecoin-virtual-machine), introduced in March 2023, enables the creation of new lending mechanisms via smart contracts.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/storage-providers/filecoin-economics/fil-collateral)
# Block rewards
This page describes block rewards in Filecoin, where storage providers are elected to produce new blocks and earn FIL as rewards.
## What are block rewards?
WinningPoSt (short for [Winning Proof of SpaceTime](https://spec.filecoin.io/algorithms/pos/post/)) is the cryptographic challenge through which storage providers are rewarded for their contributions to the network. At the beginning of each epoch (1 epoch = 30 seconds), a small number of storage providers are elected by the network to mine new [blocks](/reference/general/glossary#block). Each elected storage provider who successfully creates a block is granted Filecoin tokens by means of a *block reward*. The amount of FIL per block reward varies over time and is listed on various blockchain explorers like [Filfox](https://filfox.info/en).
The election mechanism of the Filecoin network is based on the “storage power” of the storage providers. A minimum of 10 TiB in storage power is required to be eligible for WinningPoSt, and hence to earn block rewards. The more storage power a storage provider has, the more likely they will be elected to mine a block. This concept becomes incredibly advantageous in the context of [Filecoin Plus verified deals](broken://pages/ONanf0Ny7ISDeH7beMKF).
Note that the deadline cron, a built-in actor that processes all miner actors every 60 epochs (every 30 minutes), is responsible for updating the rewards vesting table. A miner operator wishing to process vesting manually, ahead of the per-deadline cron call, could do so by calling WithdrawFunds with an amount of zero. Such a call would require use of the miner's Owner address. More details can be found in [FIP005: Remove ineffective reward vesting](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0005.md).
## Filecoin’s storage capacity
The Filecoin network is composed of storage providers who offer storage capacity to the network. This capacity is used to secure the network, as it takes a significant amount of storage to take part in the consensus mechanism. This large capacity makes it impractical for a single party to reach 51% of the network power, since an attacker would need 10 EiB in storage to control the network. Therefore, it is important that the raw capacity also referred to as *raw byte power*, remains high. The Filecoin spec also included a *baseline power* above which the network yields maximum returns for the storage providers.
The graph below shows the evolution of network capacity on the Filecoin network. As can be seen, the baseline power goes up over time (and becomes exponential). This means from May 2021 to February 2023 the network yielded maximum returns for storage providers. However, in recent history, Quality Adjusted Power (QAP) has taken over as a leading indicator of relevance for the Filecoin network. QAP is the result of the multiplier when storing verified deals:
Check out the Starboard dashboard for the most up-to-date [Network Storage Capacity](https://dashboard.starboard.ventures/capacity-services#network-storage-capacity).
## Impact of storage capacity on block rewards
As mentioned before, when the Raw Byte Power is above the Baseline Power, storage providers yield maximum returns. When building a business plan as a storage provider, it is important not to rely solely on block rewards. Block rewards are an incentive mechanism for storage providers. However, they are volatile and depend on the state of the network, which is largely beyond the control of storage providers.
The amount of FIL that is flowing to the storage provider per earned block reward is based on a combination of simple minting and baseline minting. Simple minting is the minimum amount of FIL any block will always have, which is 5.5. Baseline minting is the extra FIL on top of the 5.5 that comes from how close the Raw Byte Power is to the Baseline Power.
The below graph shows the evolution of FIL per block reward over time:
There is a positive side to releasing less FIL per block reward too. As Filecoin has a capped maximum token supply of 2 billion FIL, the slower minting rate allows for minting over a longer period. A lower circulating supply also has a positive effect on the price of FIL.
See the [Crypto Economics](/getting-started/what-is-filecoin/crypto-economics) page of this documentation and the [Filecoin spec](https://spec.filecoin.io/#section-systems.filecoin_token.minting_model) for more information.
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/storage-providers/filecoin-economics/block-rewards)
# Slashing
Slashing penalizes storage providers that either fail to provide reliable uptime or act maliciously against the network. This page discusses what slashing means to storage providers.
## Storage fault slashing
This term encompasses a broad set of penalties which are to be paid by storage providers if they fail to provide sector reliability or decide to voluntarily exit the network. These include:
* **Fault fees** are incurred for each day a storage provider’s sector is offline (fails to submit Proofs-of-Spacetime to the chain). Fault fees continue until the associated wallet is empty and the storage provider is removed from the network. In the case of a faulted sector, there will be an additional sector penalty added immediately following the fault fee. Sector fault fees are equal to 3.51 days of expected block rewards.
* **Sector penalties** are incurred for a faulted sector that was not declared faulted before a *WindowPoSt* check occurs. The sector will pay a fault fee after a Sector Penalty once the fault is detected.
* **Termination fees** are incurred when a sector is voluntarily or involuntarily terminated and is removed from the network.
* **Consensus fault slashing** is a penalty incurred when committing consensus faults. This penalty is applied to storage providers that have acted maliciously against the network’s consensus functionality.
## Honest Storage Providers
Note that occasionally, storage providers may experience operational issues, such as downtime or bugs, that cause them to miss their delivery of a WindowPoSt. To ensure reliability and to encourage smaller miners to join the network, there are built-in exceptions to the fault fees:
* If the Storage Provider has a history of acting honestly, there is no penalty in the current proving period for a faulted sector in the case of a missed WindowPoSt.
* There are no fees if the sector is successfully recovered in a later proving period.
* The fault fee applies only to the sectors already faulty, meaning, they are from a previous proving period, or marked for recovery. Penalties are only applied to faulty sectors from previous proving periods, never the current proving period.
To learn more about fault fee exceptions, review [FIP002: Free Faults on Newly Faulted Sectors of a Missed WindowPoSt](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0002.md).
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/storage-providers/filecoin-economics/slashing)
---
[Next Page](https://docs.filecoin.io/llms-full.txt/1)
