diff --git a/WELCOME.md b/WELCOME.md index 6246d8a0b..940dbb12b 100644 --- a/WELCOME.md +++ b/WELCOME.md @@ -19,7 +19,7 @@ layout: visible: true --- -# Welcome to the Filecoin Documentation +# Welcome to the Filecoin documentation Choose your own path to start exploring Filecoin: @@ -34,7 +34,7 @@ Choose your own path to start exploring Filecoin: - 💡 Learn the Basics + 💡 Learn the basics New to Filecoin and looking for foundational concepts? Start with the Basics section to understand the essentials and kick off your journey! what-is-filecoin @@ -52,7 +52,7 @@ Choose your own path to start exploring Filecoin: basics - 📊 Store Data + 📊 Store data Looking to store large volumes of data? Explore the Store section to review the various storage options Filecoin offers. storage-model.md diff --git a/basics/what-is-filecoin/blockchain.md b/basics/what-is-filecoin/blockchain.md index 0126ba635..4054db984 100644 --- a/basics/what-is-filecoin/blockchain.md +++ b/basics/what-is-filecoin/blockchain.md @@ -15,30 +15,30 @@ Each tipset is assigned a weight, enabling the consensus protocol to guide nodes An actor in the Filecoin blockchain is similar to a smart contract in the Ethereum Virtual Machine. It functions as an ‘object’ within the Filecoin network, with a state and a set of methods for interaction. -### Built-in Actors +### Built-in actors Several built-in system actors power the Filecoin network as a decentralized storage network: -- **System Actor**: General system actor. -- **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. -- **EVM Account Actor**: Represents an external Ethereum identity backed by a secp256k1 key. - -### User-Programmable Actors +- **System actor**: General system actor. +- **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. + +### User-programmable actors With the maturity of the FVM, developers can write actors and deploy them on the Filecoin network, similar to other blockchains' smart contracts. User-programmable actors can interact with built-in actors via the exported API from built-in actors. -## Distributed Randomness +## Distributed randomness Filecoin uses the [Drand](https://drand.love) protocol as a randomness beacon for leader election in the [expected consensus](blockchain.md#expected-consensus) process. This randomness ensures leader election is secret, fair, and verifiable. @@ -65,13 +65,13 @@ In the Filecoin network, addresses identify actors in the Filecoin state. Each a ## Consensus -### Expected Consensus +### Expected consensus Expected Consensus (EC) is the consensus algorithm underlying Filecoin. EC is a probabilistic, Byzantine fault-tolerant protocol that 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 power a miner contributes to the network. This storage power is recorded in the storage power table, managed by the Storage Power Actor. At a high level, the consensus process uses [Drand](https://drand.love) to provide distributed, verifiable randomness, ensuring that leader election is secret, fair, and unbiased. Election participants and their storage power are drawn from the Power Table, which is continuously calculated and maintained by the Storage Power Consensus subsystem. Ultimately, EC gathers all valid blocks produced in an epoch and applies a weighting function to select the heaviest chain, adding blocks accordingly. -### Block Production Process +### Block production process The block production process for each epoch is as follows: @@ -90,11 +90,11 @@ EC enforces soft finality, where miners at round `N` reject blocks forking off b Filecoin operates on proof-of-storage, where miners offer storage space and provide proofs to verify data storage. -### Proof of Replication +### 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 +### 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: diff --git a/basics/what-is-filecoin/crypto-economics.md b/basics/what-is-filecoin/crypto-economics.md index 1f8f86440..72f59bbe8 100644 --- a/basics/what-is-filecoin/crypto-economics.md +++ b/basics/what-is-filecoin/crypto-economics.md @@ -3,9 +3,9 @@ description: >- 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. --- -# Crypto-Economics +# Crypto-economics -## Native Currency +## 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. @@ -13,11 +13,11 @@ As a utility token aligned with the network’s long-term growth, Filecoin issua Filecoin uses a dual minting model for block reward distribution: -## Baseline Minting +## 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 +## 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. @@ -27,11 +27,11 @@ Additionally, 300 million FIL tokens are held in a mining reserve to incentivize 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. Further, 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. -## Collateral and Slashing +## 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 +## 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. diff --git a/basics/what-is-filecoin/programming-on-filecoin.md b/basics/what-is-filecoin/programming-on-filecoin.md index 4fe97f5c1..7d9ecf247 100644 --- a/basics/what-is-filecoin/programming-on-filecoin.md +++ b/basics/what-is-filecoin/programming-on-filecoin.md @@ -3,9 +3,9 @@ description: >- Once data is stored, computations can be performed directly on it without needing retrieval. This page covers the basics of programming on Filecoin. --- -# Programming on Filecoin +# Programming on filecoin -## Compute-over-Data +## 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 (e.g., [Bacalhau](https://www.bacalhau.org/)) and cryptographically verifiable compute (e.g., [Lurk](https://filecoin.io/blog/posts/introducing-lurk-a-programming-language-for-recursive-zk-snarks/)). @@ -27,19 +27,19 @@ By enabling compute-over-states on the Filecoin network, the FVM unlocks a wide FVM enables a new kind of organization centered around data. -#### Data DAOs and Tokenized Datasets +#### 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 +#### 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 Miners +### Financial services for miners The FVM can facilitate unique financial services tailored for storage providers (SPs) in the Filecoin ecosystem. -#### Lending and Staking Protocols +#### 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. @@ -47,15 +47,15 @@ Users can lend Filecoin to storage providers to be used as storage collateral, e 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 +### 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 +#### 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 +#### 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. diff --git a/basics/what-is-filecoin/retrieval-market.md b/basics/what-is-filecoin/retrieval-market.md index 67eea0b19..dadba5713 100644 --- a/basics/what-is-filecoin/retrieval-market.md +++ b/basics/what-is-filecoin/retrieval-market.md @@ -3,9 +3,9 @@ description: >- The retrieval market facilitates the negotiation of retrieval deals for serving stored data to clients in exchange for FIL. --- -# Retrieval Market +# Retrieval market -## Basic Retrieval +## Basic retrieval Currently, Filecoin nodes support direct retrieval from the storage miners who originally stored the data. Clients can send retrieval requests directly to a storage provider and pay a small amount of FIL to retrieve their data. diff --git a/basics/what-is-filecoin/storage-market.md b/basics/what-is-filecoin/storage-market.md index 483f35bb2..88b223520 100644 --- a/basics/what-is-filecoin/storage-market.md +++ b/basics/what-is-filecoin/storage-market.md @@ -3,9 +3,9 @@ description: >- The storage market is the entry point where storage providers and clients negotiate and publish storage deals on-chain. --- -# Storage Market +# Storage market -## Deal Making +## Deal making The lifecycle of a deal within the storage market includes four distinct phases: @@ -24,7 +24,7 @@ Verified clients use datacap allocated by community-selected allocators to store - **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 +## 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. diff --git a/basics/what-is-filecoin/storage-model.md b/basics/what-is-filecoin/storage-model.md index 31e9e479b..a25a78de9 100644 --- a/basics/what-is-filecoin/storage-model.md +++ b/basics/what-is-filecoin/storage-model.md @@ -18,11 +18,11 @@ Providers offer storage and retrieval services to network users. There are two t - Storage Providers - Retrieval Providers -### Storage 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 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. diff --git a/smart-contracts/developing-contracts/client-contract-tutorial.md b/smart-contracts/developing-contracts/client-contract-tutorial.md index ecffe2186..3a477ac0f 100644 --- a/smart-contracts/developing-contracts/client-contract-tutorial.md +++ b/smart-contracts/developing-contracts/client-contract-tutorial.md @@ -1,11 +1,11 @@ --- description: >- - This page covers the client contract, and includes a tutorial on how developers can use the client contract to create storage deals programmatically. + This page covers the client contract, and includes a tutorial on how developers can use the client contract to create storage deals programmatically. --- # Client contract tutorial -In this tutorial we will cover the background of creating storage deals using smart contracts, and how to create storage deals with smart contracts on the [Filecoin virtual machine](../../reference/general/glossary.md#filecoin-virtual-machine). +In this tutorial we will cover the background of creating storage deals using smart contracts, and how to create storage deals with smart contracts on the [Filecoin virtual machine](../../reference/general/glossary.md#filecoin-virtual-machine). You can find a video form of this walkthrough on [ETHGlobal’s YouTube Channel](https://www.youtube.com/watch?v=27EV3gQGY9k). @@ -13,11 +13,11 @@ You can find a video form of this walkthrough on [ETHGlobal’s YouTube Channel] Before continuing, make sure you have the following software installed and prerequisites ready: -* Git -* NodeJS -* Yarn or NPM (Yarn is used in this tutorial) -* A code editor such as VS Code -* A wallet with Calibration testnet FIL +- Git +- NodeJS +- Yarn or NPM (Yarn is used in this tutorial) +- A code editor such as VS Code +- A wallet with Calibration testnet FIL ## Steps @@ -68,32 +68,32 @@ Before storing a file with a storage provider it needs to be prepared by turning 1. Go to the [FVM Data Depot website](https://data.lighthouse.storage/) and create an account. 2. Click **Upload File** and select a file you wish to upload. -3. Select the **File ID** of the file to read all the relevant metadata. Make a note of the: +3. Select the **File ID** of the file to read all the relevant metadata. Make a note of the: - * Piece CID - * Payload CID - * Car size - * Piece size - * URL + - Piece CID + - Payload CID + - Car size + - Piece size + - URL - We’ll use this information in the next step when invoking the `MakeDealProposal` method. + We’ll use this information in the next step when invoking the `MakeDealProposal` method. ### Invoke the `MakeDealProposal` method Now that we have the `.car` file prepared in the data depot, we can invoke the MakeDealProposal method on the smart contract we deployed earlier. To do this, we will run the `make-deal-proposal` task in Hardhat. There are quite a few parameters to include in this call: -* `contract`: the address of your deployed `ClientContract.sol`. -* `piece-cid: gathered from the previous step. -* `piece-size`: gathered from the previous step. -* `car-size`: gathered from the previous step. -* `start-epoch`: The block number you want the deal to begin on. It should be a block in the future. You can find the current block number on [Beryx](https://beryx.io/), making sure to select the correct network. -* `end-epoch`: The block number you want the deal to end on. It should be a block in the future and after the `Start-Epoch`. You can find the current block number on [FILFOX](https://calibration.filfox.info/en). -* `location-ref`: The location of where the storage provider can find the .car file. This is the `URL` from the previous step. +- `contract`: the address of your deployed `ClientContract.sol`. +- `piece-cid: gathered from the previous step. +- `piece-size`: gathered from the previous step. +- `car-size`: gathered from the previous step. +- `start-epoch`: The block number you want the deal to begin on. It should be a block in the future. You can find the current block number on [Beryx](https://beryx.io/), making sure to select the correct network. +- `end-epoch`: The block number you want the deal to end on. It should be a block in the future and after the `Start-Epoch`. You can find the current block number on [FILFOX](http://47.109.105.51/en). +- `location-ref`: The location of where the storage provider can find the .car file. This is the `URL` from the previous step. When calling the `make-deal-proposal` task in Hardhat, your command will look something like this: ```shell -yarn hardhat make-deal-proposal \ +yarn hardhat make-deal-proposal \ --contract 0x0219eB1740C315fe5e20612D7E13AE2A883dB3f4 \ --piece-cid baga6ea4seaqn4eomxfk3ttog7lnvlvedu7nia377w4gotw2pm746k6kq7gwe6ga \ --piece-size 2097152 \