Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update filecoin-plus.md #2365

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update filecoin-plus.md #2365

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 20 additions & 18 deletions basics/how-storage-works/filecoin-plus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,3 @@
---
description: >-
Learn how the Filecoin Plus 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 plus

## What is Filecoin Plus?
Expand All @@ -27,7 +20,8 @@ DataCap is a token paid to storage providers as part of a deal in which the clie

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 Plus deal if a deal in that sector involves DataCap paid to the storage provider. The more Filecoin Plus 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 Plus 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 Plus 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.
#### Important
There is a common misconception that a Filecoin Plus 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 Plus 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:

Expand All @@ -41,7 +35,7 @@ If two of these storage providers begin filling their sectors with verified deal

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)
![filecoinplus3](https://github.com/user-attachments/assets/634f96eb-c0b4-4230-95ca-b9a4875b180d)

As seen in the diagrams above, Filecoin Plus increases the collateral requirements needed by a storage provider. As a higher percentage of storage providers include verified deals in their sectors, the collateral needed by each storage provider will increase. To learn more about storage provider collateral, see [this link](https://docs.filecoin.io/storage-providers/filecoin-economics/fil-collateral).

Expand All @@ -55,18 +49,18 @@ The participants of the Filecoin+ program, along with how they interact with eac
* 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.

## How Filecoin Plus Works
A visualization of the interactions between parties involved in a Filecoin+ deal described above is shown below in Figure 1.

![Screenshot 2024-06-28 at 12 11 23 AM](https://github.com/filecoin-project/filecoin-docs/assets/46801006/efd006ae-ea6f-4851-b072-ae73787e6975)

Figure 1 | Diagram showing participant interactions in a Filecoin+ deal.
![Figure 1 | Diagram showing participant interactions in a Filecoin+ deal.](https://github.com/user-attachments/assets/61d1e3c9-438c-4614-b333-14c4fb0dc0e1)

## Acquiring DataCap for Clients & Builders

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)](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).

### Steps to Acquire Mainnet DataCap as a Client
The steps a client should follow to acquire DataCap are as follows:

1. Create a [Filecoin wallet](https://docs.filecoin.io/basics/assets/wallets).
Expand All @@ -75,23 +69,28 @@ The steps a client should follow to acquire DataCap are as follows:
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.

### Steps to Acquire Testnet DataCap as a Builder
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. 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).

## **Smart contracts**
## **DataCap for Smart contracts**

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.

## Spend 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.

## How to Use 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.

[Learn more about Storage Deals.](https://docs.filecoin.io/storage-providers/filecoin-deals/storage-deals)

By default, when you make a deal with an address with DataCap allocated, you will spend that DataCap when making the deal.

### How to Use DataCap, using the API

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`.

Comment on lines +92 to 95
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the Client api endpoints have all been removed from the lotus daemon, so this section should be removed

```json
Expand All @@ -117,23 +116,26 @@ If making deals through the [API](https://github.com/filecoin-project/lotus/blob
]
```

### How to Use DataCap, using the Command Line
If making deals from the command line, make sure to pass the flag `--verified-deal=true` as a parameter.

```shell
lotus client deal --verified-deal=true
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the client subcommand no longer exists in the lotus cli, so this whole section should be removed.

```

### Checking remaining DataCap balance
### Checking DataCap Balance

Once you have received DataCap to an address, you can check the remaining balance by querying your address on a node.

#### With the lotus cli

Run the following command, replacing "f0000" with your Filecoin address.

```shell
lotus filplus check-client-datacap f00000
```

## Visualizing the Blockchain Data for Filecoin+
## Visualizing Blockchain Data for Filecoin+

There are three resources you can use to check the current status of the Filecoin+ deals and participants:

Expand Down