From bf43ce370359b9ffb74025c8d6030ae923899b26 Mon Sep 17 00:00:00 2001 From: Stefan Magdalinski Date: Fri, 28 Jun 2024 13:22:51 +0200 Subject: [PATCH 1/4] updates to FIL Token page --- basics/assets/the-fil-token.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/basics/assets/the-fil-token.md b/basics/assets/the-fil-token.md index e8cd6bb72..a72ad5c4a 100644 --- a/basics/assets/the-fil-token.md +++ b/basics/assets/the-fil-token.md @@ -10,21 +10,20 @@ description: >- FIL plays a vital role in incentivizing users to participate in the Filecoin network and ensuring its smooth operation. Here are some ways in which FIL is used on the Filecoin network: -### Storage payments +### Network payments -When a user wants to store data on the Filecoin network, they pay in FIL to the storage providers who offer their storage space. The payment is made in advance for a certain amount of time that the data will be stored on the network. The storage providers are then rewarded with FIL for providing their storage space and performing other useful tasks on the network. +When a user wants to store data on the Filecoin network, they pay in FIL to the storage providers who offer their storage space. The payment is made in advance for a certain amount of time that the data will be stored on the network. +When a user wants to retrieve their data from the Filecoin network, they can make a payment in FIL to the storage providers who stored the data. This payment incentivizes the storage providers to keep the data available for retrieval at all times. +Storage providers choose their own terms and payment mechanisms for providing storage and retrieval services so other options (such as fiat payments) can be available. -### Retrieval payments - -When a user wants to retrieve their data from the Filecoin network, they make a payment in FIL to the storage providers who stored the data. This payment incentivizes the storage providers to keep the data available for retrieval at all times. ### Blockchain rewards -FIL is used to reward providers who validate and add new blocks to the Filecoin blockchain. Providers receive a block reward in FIL for each new block they add to the blockchain and also earn transaction fees in FIL for processing storage and retrieval transactions. +Storage providers are also rewarded with FIL for providing their storage space and performing other useful tasks on the network. FIL is used to reward storage providers who validate and add new blocks to the Filecoin blockchain. Providers receive a block reward in FIL for each new block they add to the blockchain and also earn transaction fees in FIL for processing storage and retrieval transactions. ### Governance -FIL is used for network governance, allowing FIL holders to vote on proposals and make decisions that impact the future development and direction of the network. +As members of the Filecoin community, FIL holders are encouraged to participate in the Filecoin governance process. They can do so by proposing, deliberating, designing, and/or contributing to consensus for network changes, alongside other stakeholders in the Filecoin community- including implementers, Core Devs, storage providers, and other ecosystem partners. Learn more about the (Filecoin Governance process)[https://fil.org/governance]. ## Denominations From 9e1d4b413a753011345ee2631e96f40ff1682dc2 Mon Sep 17 00:00:00 2001 From: Stefan Magdalinski Date: Fri, 28 Jun 2024 13:38:42 +0200 Subject: [PATCH 2/4] fixed link --- basics/assets/the-fil-token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basics/assets/the-fil-token.md b/basics/assets/the-fil-token.md index a72ad5c4a..f70f82ff8 100644 --- a/basics/assets/the-fil-token.md +++ b/basics/assets/the-fil-token.md @@ -23,7 +23,7 @@ Storage providers are also rewarded with FIL for providing their storage space a ### Governance -As members of the Filecoin community, FIL holders are encouraged to participate in the Filecoin governance process. They can do so by proposing, deliberating, designing, and/or contributing to consensus for network changes, alongside other stakeholders in the Filecoin community- including implementers, Core Devs, storage providers, and other ecosystem partners. Learn more about the (Filecoin Governance process)[https://fil.org/governance]. +As members of the Filecoin community, FIL holders are encouraged to participate in the Filecoin governance process. They can do so by proposing, deliberating, designing, and/or contributing to consensus for network changes, alongside other stakeholders in the Filecoin community- including implementers, Core Devs, storage providers, and other ecosystem partners. Learn more about the [Filecoin Governance process](https://fil.org/governance). ## Denominations From 64bc10196a90807670d0249d1d0d318cce257db4 Mon Sep 17 00:00:00 2001 From: Stefan Magdalinski Date: Fri, 28 Jun 2024 14:16:58 +0200 Subject: [PATCH 3/4] tidyup and linting --- basics/assets/the-fil-token.md | 5 +- basics/how-storage-works/filecoin-plus.md | 59 ++++++++++++----------- 2 files changed, 33 insertions(+), 31 deletions(-) diff --git a/basics/assets/the-fil-token.md b/basics/assets/the-fil-token.md index f70f82ff8..848db30d1 100644 --- a/basics/assets/the-fil-token.md +++ b/basics/assets/the-fil-token.md @@ -12,11 +12,10 @@ FIL plays a vital role in incentivizing users to participate in the Filecoin net ### Network payments -When a user wants to store data on the Filecoin network, they pay in FIL to the storage providers who offer their storage space. The payment is made in advance for a certain amount of time that the data will be stored on the network. -When a user wants to retrieve their data from the Filecoin network, they can make a payment in FIL to the storage providers who stored the data. This payment incentivizes the storage providers to keep the data available for retrieval at all times. +When a user wants to store data on the Filecoin network, they pay in FIL to the storage providers who offer their storage space. The payment is made in advance for a certain amount of time that the data will be stored on the network. +When a user wants to retrieve their data from the Filecoin network, they can make a payment in FIL to the storage providers who stored the data. This payment incentivizes the storage providers to keep the data available for retrieval at all times. Storage providers choose their own terms and payment mechanisms for providing storage and retrieval services so other options (such as fiat payments) can be available. - ### Blockchain rewards Storage providers are also rewarded with FIL for providing their storage space and performing other useful tasks on the network. FIL is used to reward storage providers who validate and add new blocks to the Filecoin blockchain. Providers receive a block reward in FIL for each new block they add to the blockchain and also earn transaction fees in FIL for processing storage and retrieval transactions. diff --git a/basics/how-storage-works/filecoin-plus.md b/basics/how-storage-works/filecoin-plus.md index a5ff14456..02521b679 100644 --- a/basics/how-storage-works/filecoin-plus.md +++ b/basics/how-storage-works/filecoin-plus.md @@ -1,41 +1,44 @@ --- description: >- - Allocators verify that the data clients want to store with a Filecoin storage provider is useful. + Learn how the Filecoin+ program works, how DataCap is obtained and used by clients, and how allocators verify that the data clients want to store with a Filecoin storage provider is useful. --- # Filecoin+ - ## What is Filecoin+? -The goal of the Filecoin+ program is to increase the amount of useful data stored with storage providers by clients on the Filecoin network. +The goal of the Filecoin+ program is to increase the amount of useful data stored with storage providers by clients on the Filecoin network. -In short, this is achieved by appointing allocators responsible for assigning DataCap tokens to clients that are vetted by the allocator as trusted parties storing useful data. Clients then pay DataCap to storage providers as part of a storage deal, which increases a storage provider’s probability of earning block rewards. A full description of this mechanism is described below. +In short, this is achieved by appointing allocators responsible for assigning DataCap tokens to clients that are vetted by the allocator as trusted parties storing useful data. Clients then pay DataCap to storage providers as part of a storage deal, which increases a storage provider’s probability of earning block rewards. A full description of this mechanism is described below. -Filecoin+ creates honest demand on the Filecoin network, ensuring the datasets stored on the network are legitimate and useful to either the clients or a third party. +Filecoin+ creates demand on the Filecoin network, ensuring the datasets stored on the network are legitimate and useful to either the clients, or a third party. ## Storage Providers & DataCap -Filecoin+ introduces two concepts important to interactions on the Filecoin network – DataCap and Quality Adjusted Power. +Filecoin+ introduces two concepts important to interactions on the Filecoin network – DataCap and Quality Adjusted Power (QAP). + +### DataCap + +DataCap is a token paid to storage providers as part of a deal in which the client and the data they are storing is verified by a Filecoin+ allocator. Batches of DataCap are granted to allocators by root-key holders, allocators give DataCap to verified clients, and clients pay DataCap to storage providers as part of a deal. The more DataCap a storage provider ends up with, the higher probability they have to earn block rewards. The role of each of these participants, and how DataCap is used in a Filecoin+ deal, is described below in the "Filecoin+ Processes & Participants" section. -- DataCap | DataCap is a token paid to storage providers as part of a deal in which the client and the data they are storing is verified by a Filecoin+ allocator. Batches of DataCap are granted to allocators by root-key holders, allocators give DataCap to verified clients, and clients pay DataCap to storage providers as part of a deal. The more DataCap a storage provider ends up with, the higher probability they have to earn block rewards. The role of each of these participants, and how DataCap is used in a Filecoin+ deal, is described below in the "Filecoin+ Processes & Participants" section. +### Quality Adjusted Power -- Quality Adjusted Power | Quality Adjusted Power is an assigned rating to a given [sector](https://spec.filecoin.io/systems/filecoin_mining/sector/), the basic unit of storage on the Filecoin network. Quality Adjusted Power is a function of a number of features of the sector, including, but not limited to, the sector’s size and promised duration, and whether the sector includes a Filecoin+ deal. It's clear to the network that a sector includes a Filecoin+ deal if a deal in that sector involves DataCap paid to the storage provider. The more Filecoin+ verified data the storage provider has in a sector, the higher the Quality-Adjusted Power a storage provider has, which linearly increases the number of votes a miner has in the [Secret Leader Election](https://spec.filecoin.io/algorithms/expected_consensus/), determining which storage provider gets to serve as the verifier for the next block in the blockchain, and thus increasing the probability the storage provider is afforded the opportunity to earn block rewards. For more details on Quality Adjusted Power, see the [Filecoin specification](https://spec.filecoin.io/systems/filecoin_blockchain/storage_power_consensus/). +Quality Adjusted Power is an assigned rating to a given [sector](https://spec.filecoin.io/systems/filecoin_mining/sector/), the basic unit of storage on the Filecoin network. Quality Adjusted Power is a function of a number of features of the sector, including, but not limited to, the sector’s size and promised duration, and whether the sector includes a Filecoin+ deal. It's clear to the network that a sector includes a Filecoin+ deal if a deal in that sector involves DataCap paid to the storage provider. The more Filecoin+ verified data the storage provider has in a sector, the higher the Quality-Adjusted Power a storage provider has, which linearly increases the number of votes a miner has in the [Secret Leader Election](https://spec.filecoin.io/algorithms/expected_consensus/), determining which storage provider gets to serve as the verifier for the next block in the blockchain, and thus increasing the probability the storage provider is afforded the opportunity to earn block rewards. For more details on Quality Adjusted Power, see the [Filecoin specification](https://spec.filecoin.io/systems/filecoin_blockchain/storage_power_consensus/). [!IMPORTANT] There is a common misconception that a Filecoin+ deal increases the miner’s reward paid to a Filecoin storage provider by a factor of ten. This is not true, Filecoin+ does not increase the amount of block rewards available to storage providers. Including Filecoin+ deals in a sector increases the Quality Adjusted Power of a storage provider, which increases the probability a storage provider is selected as the block verifier for the next block on the Filecoin blockchain, and thus increases the probability they earn block rewards. -Consider first a network with ten storage providers. Initially, each storage provider has an equal 10% probability of winning available block rewards in a given period: +Consider first a network with ten storage providers. Initially, each storage provider has an equal 10% probability of winning available block rewards in a given period: filecoinplus1 -In the above visualization, "VD" means "verfied deals", that is, deals that have been reviewed by allocators and have associated spending of datacap. +In the above visualization, "VD" means "verfied deals", that is, deals that have been reviewed by allocators and have associated spending of datacap. If two of these storage providers begin filling their sectors with verified deals, their chances of winning a block reward increases by a factor of ten relative to their peers. Each one of these storage providers with verified deals in their sectors has a 36% chance of winning the block reward, while storage providers with only [regular deals](https://spec.filecoin.io/systems/filecoin_blockchain/storage_power_consensus/#section-systems.filecoin_mining.sector.sector_quality) in their sectors have a 4% probability of winning the block rewards. ![filecoinplus2](https://github.com/filecoin-project/filecoin-docs/assets/46801006/a13dcf38-0115-49b0-896c-11da82808d70) -Incentives for storage providers to accept verified deals is strongest initially. As more and more storage providers include verified deals in their sectors, the probability any one of them earns the block rewards returns to an equal chance. +Incentives for storage providers to accept verified deals is strongest initially. As more and more storage providers include verified deals in their sectors, the probability any one of them earns the block rewards returns to an equal chance. ![filecoinplus3](https://github.com/filecoin-project/filecoin-docs/assets/46801006/a7ec2921-ea7c-4c0b-94d8-94f8eb5a2824) @@ -45,15 +48,15 @@ As seen in the diagrams above, Filecoin+ increases the collateral requirements n The participants of the Filecoin+ program, along with how they interact with each other, is detailed here: -- Decisions as to who the Root-Key Holders should be, how they should grant and remove batches of DataCap to/from allocators, and other important decisions about the Filecoin+ program are determined through Filecoin Improvement Proposals (FIPs) the community governance process. To learn more about Filecoin+ governance, see this [Github repository](https://github.com/filecoin-project/allocator-governance/tree/main). To see a list of previous FIPs, see this [link](https://github.com/filecoin-project/FIPs). +- Decisions as to who the root-key holders should be, how they should grant and remove batches of DataCap to/from allocators, and other important decisions about the Filecoin+ program are determined through Filecoin Improvement Proposals (FIPs), the community governance process. Learn more about [Filecoin+ governance](https://github.com/filecoin-project/allocator-governance/tree/main). To see a list of FIPs, see this [link](https://github.com/filecoin-project/FIPs). -- Root-Key Holders execute the governance process for Filecoin+ as determined through community executed Filecoin Improvement Proposals, their role is to grant and remove batches of DataCap to/from allocators. Root-Key Holders are signers to a multisig wallet on-chain –a majority of signers are needed for an allocator to be granted or removed. +- Root-key holders execute the governance process for Filecoin+ as determined through community executed Filecoin Improvement Proposals, their role is to grant and remove batches of DataCap to/from allocators. Root-key holders are signers to a multisig wallet on-chain –a majority of signers are needed for an allocator to be granted or removed. -- Allocators perform due diligence on clients and the data they are storing, allocate DataCap to trusted clients, and facilitate predetermined dispute resolution processes. To learn more about how allocators are chosen and evaluated, see [this blog](https://blog.allocator.tech/2024/05/who-are-allocators.html). +- Allocators perform due diligence on clients and the data they are storing, allocate DataCap to trusted clients, and facilitate predetermined dispute resolution processes. To learn more about how allocators are chosen and evaluated, see [this blog](https://blog.allocator.tech/2024/05/who-are-allocators.html). -- Clients are participants in the Filecoin network who store data with a storage provider. A trusted client, as determined by an allocator who performs due diligence on the client and the data they are looking to store, will be given DataCap by the allocator. Clients offer to give this DataCap to a storage provider as part of a deal, which increases the “deal quality multiplier” of the deal, and in turn the likelihood a storage provider will accept the deal. +- Clients are participants in the Filecoin network who store data with a storage provider. A trusted client, as determined by an allocator who performs due diligence on the client and the data they are looking to store, will be given DataCap by the allocator. Clients offer to give this DataCap to a storage provider as part of a deal, which increases the “deal quality multiplier” of the deal, and in turn the likelihood a storage provider will accept the deal. -- Storage providers who receive DataCap as part of a deal are able to use this DataCap to increase their “quality adjusted power” of the storage provider on the network by a factor of ten. As described above, this increases their probability of being selected as the verifier for a block, affording them the opportunity to earn block rewards. +- Storage providers who receive DataCap as part of a deal are able to use this DataCap to increase their “quality adjusted power” of the storage provider on the network by a factor of ten. As described above, this increases their probability of being selected as the verifier for a block, affording them the opportunity to earn block rewards. A visualization of the interactions between parties involved in a Filecoin+ deal described above is shown below in Figure 1. @@ -65,23 +68,23 @@ Figure 1 | Diagram showing participant interactions in a Filecoin+ deal. Clients can secure DataCap by making a request to an allocator. Each one of the allocators maintain their own applications for requesting DataCap. -One such allocator is Filecoin Incentive Design Labs (FIDL). They maintain a [Github repository](https://github.com/fidlabs) that includes an [application](https://github.com/fidlabs/Open-Data-Pathway/issues/new/choose) where clients can make a request of FIDL for DataCap. Clients and builders looking to acquire DataCap may consider applying directly with FIDL, noting that all DataCap applications are transparent and open for public review on the [issues page](https://github.com/fidlabs/Open-Data-Pathway/issues). +One such allocator is [Filecoin Incentive Design Labs (FIDL)](https://www.fidl.tech). They maintain a [Github repository](https://github.com/fidlabs) that includes an [application](https://github.com/fidlabs/Open-Data-Pathway/issues/new/choose) where clients can make a request of FIDL for DataCap. Clients and builders looking to acquire DataCap may consider applying directly with FIDL, noting that all DataCap applications are transparent and open for public review on the [issues page](https://github.com/fidlabs/Open-Data-Pathway/issues). -The steps a client should follow to acquire DataCap are as follows: +The steps a client should follow to acquire DataCap are as follows: -1. Establish a [Filecoin wallet](https://docs.filecoin.io/basics/assets/wallets). +1. Create a [Filecoin wallet](https://docs.filecoin.io/basics/assets/wallets). 2. Choose an allocator from the [full list of active allocators](https://github.com/filecoin-project/Allocator-registry) or the [active list of allocators](https://allocator.tech/) who have verified public datasets. -3. Check that you satisfy the requirements of the allocator. In the case of uploading open source datasets with FIDL as the allocator, the client will need to demonstrate to FIDL that they can (1) satisfy a third party KYC (identity) check, (2) provide the details of storage provider (entity, storage location) where the data is intended to be stored, and (3) demonstrate proof that the dataset can be actively retrieved. More details on FIDL’s requirements can be found [HERE](https://www.fidl.tech/apply-for-datacap). +3. Check that you satisfy the requirements of the allocator. In the case of uploading open source datasets with FIDL as the allocator, the client will need to demonstrate to FIDL that they can (1) satisfy a third party Know Your Customer(KYC) identity check, (2) provide the details of storage provider (entity, storage location) where the data is intended to be stored, and (3) demonstrate proof that the dataset can be actively retrieved. You can learn more about [FIDL’s requirements and application process](https://www.fidl.tech/apply-for-datacap). -4. Submit an application for DataCap from an allocator. You can submit a request to FIDL via their [Github application](https://github.com/fidlabs/Open-Data-Pathway/issues/new/choose) or [Google Form](https://www.fidl.tech/apply-for-datacap). +4. Submit an application for DataCap from an allocator. You can submit a request to FIDL via their [Github application form](https://github.com/fidlabs/Open-Data-Pathway/issues/new/choose) or [Google Form](https://www.fidl.tech/apply-for-datacap). 5. Use the DataCap in a storage deal. -For builders on the Calibration testnet who need testnet DataCap to test their applications, a faucet is available. The steps a builder should follow to acquire testnet DataCap are as follows: +For builders on the [Calibration testnet](/networks/calibration) who need testnet DataCap to test their applications, a faucet is available. The steps a builder should follow to acquire testnet DataCap are as follows: -1. Establish a wallet on Filecoin Calibration testnet. For more information, see the Calibration [docs](https://docs.filecoin.io/networks/calibration) or [Github](https://github.com/filecoin-project/testnet-calibration). +1. Create a wallet on Filecoin Calibration testnet. For more information, see the [Calibration docs](/networks/calibration) or [Github](https://github.com/filecoin-project/testnet-calibration). 2. Grant the wallet address DataCap by using this [faucet](https://faucet.calibnet.chainsafe-fil.io/datacap.html). @@ -90,13 +93,13 @@ For builders on the Calibration testnet who need testnet DataCap to test their a Smart contracts can acquire and use DataCap just like any regular client. To do so, simply enter the `f410` address of the smart contract as the client address when making a request for DataCap. [!Important] -It’s important to note that DataCap allocations are a one-time credit for a Filecoin address and cannot be transferred between smart contracts. If you need to redeploy the smart contract, you must request additional DataCap. +It’s important to note that DataCap allocations are a one-time credit for a Filecoin address and cannot be transferred between smart contracts. If you need to redeploy the smart contract, you must request additional DataCap. ## Spend DataCap Once you have an address with DataCap, you can make deals using DataCap as a part of the payment. Because storage providers receive a deal quality multiplier for taking Filecoin+ deals, many storage providers offer special pricing and services to attract clients who use DataCap to make deals. -By default, when you make a deal with an address with DataCap allocated, you will spend DataCap when making the deal. +By default, when you make a deal with an address with DataCap allocated, you will spend that DataCap when making the deal. If making deals through the [API](https://github.com/filecoin-project/lotus/blob/master/documentation/en/api-v0-methods.md#ClientStartDeal), make sure that the `VerifiedDeal` parameter is set to `true` when calling `ClientStartDeal`. @@ -133,15 +136,15 @@ If making deals from the command line, make sure to pass the flag `--verified-de Once you have received DataCap to an address, you can check the remaining balance by querying your address on a node. -#### **With lotus v1.10.0 ^** +#### With the lotus cli ```shell lotus filplus check-client-datacap f00000 ``` -## Visualizing the Blockchain Data for Filecoin+ +## Visualizing the Blockchain Data for Filecoin+ -There are two resources you can use to check the current status of the Filecoin+ deals and participants: +There are three resources you can use to check the current status of the Filecoin+ deals and participants: - The [Filecoin Pulse dashboard](https://filecoinpulse.pages.dev/allocators/) includes visualizations of and tables for data about Filecoin+ deals on the Filecoin blockchain, organized by Allocators, Clients, and Storage Providers. - The [Datacap Stats dashboard](https://datacapstats.io) shows DataCap allocations, including the number of allocators, clients, and storage providers. You can also see number and size of deals. From 32381d019eb21b48a368125e1803a68b383e9965 Mon Sep 17 00:00:00 2001 From: smagdali Date: Fri, 28 Jun 2024 14:55:43 +0200 Subject: [PATCH 4/4] Update the-fil-token.md updated retrievals --- basics/assets/the-fil-token.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/basics/assets/the-fil-token.md b/basics/assets/the-fil-token.md index 848db30d1..73e0199ee 100644 --- a/basics/assets/the-fil-token.md +++ b/basics/assets/the-fil-token.md @@ -12,9 +12,9 @@ FIL plays a vital role in incentivizing users to participate in the Filecoin net ### Network payments -When a user wants to store data on the Filecoin network, they pay in FIL to the storage providers who offer their storage space. The payment is made in advance for a certain amount of time that the data will be stored on the network. -When a user wants to retrieve their data from the Filecoin network, they can make a payment in FIL to the storage providers who stored the data. This payment incentivizes the storage providers to keep the data available for retrieval at all times. -Storage providers choose their own terms and payment mechanisms for providing storage and retrieval services so other options (such as fiat payments) can be available. +When a user wants to store data on the Filecoin network, they pay in FIL to the storage providers who offer their storage space. The payment is made in advance, for a certain amount of time that the data will be stored on the network. + +In addition, Storage providers choose their own terms and payment mechanisms for providing storage and retrieval services so other options (such as fiat payments) can be available. ### Blockchain rewards