[Tutorial] Dynamic Retrieval Pricing For Storage Provider

[stuberman]

Discussed in #6780

^{Originally posted by jennijuju July 18, 2021}

Retrieval pricing

Lotus allows you to set different strategy to calculate the quoted price of a retrieval deal:

  [Dealmaking.RetrievalPricing]
    Strategy = "external"
    [Dealmaking.RetrievalPricing.Default]
      VerifiedDealsFreeTransfer = true
    [Dealmaking.RetrievalPricing.External]
      Path = "/var/price"

• default: Lotus is shipped with an in-built default pricing policy that offers free retrievals for Verified Unsealed deals. Storage miners can still charge clients for data-transfer if they wish to by turning off free data-transfer for verified deals(VerifiedDealsFreeTransfer) in the Miner config. Miners can also charge clients for Unsealing if they don't have an Unsealed sector file to retrieve the deal payload from.

• external: Storage providers can configure an external pricing script that will be used instead of the default pricing policy to price retrieval deals. The script will be called with the relevant deal parameters and the output quote will be used by Lotus to price deals.

Using the default retrieval pricing policy

• The default pricing policy uses the price configured in the Ask Store (set via the lotus retrieval-deals set-ask CLI command) to price all retrieval deals.
• However, it will not charge for data-transfer if there exists a verified storage deal for the payload being retrieved. This behaviour can be turned off by setting the VerifiedDealsFreeTransfer flag to false in the DealMaking.RetrievalPricing section of the config as shown below.

 [Dealmaking.RetrievalPricing]
    Strategy = "default"
    [Dealmaking.RetrievalPricing.Default]
      VerifiedDealsFreeTransfer = false

• It will also not charge for Unsealing if we already have an Unsealed sector file containing the retrieval payload.

Using the external retrieval pricing policy

• Users can configure an external pricing script(similar to the deal filter mechanism) that takes a json marshalled PricingInput as the input and outputs a json marshalled Ask i.e. the quote. The PricingInput struct is defined as follows:

type PricingInput struct {
	// PayloadCID is the cid of the payload to retrieve.
	PayloadCID cid.Cid
	// PieceCID is the cid of the Piece from which the Payload will be retrieved.
	PieceCID cid.Cid
	// PieceSize is the size of the Piece from which the payload will be retrieved.
	PieceSize abi.UnpaddedPieceSize
	// Client is the peerID of the retrieval client.
	Client peer.ID
	// VerifiedDeal is true if there exists a verified storage deal for the PayloadCID.
	VerifiedDeal bool
	// Unsealed is true if there exists an unsealed sector from which we can retrieve the given payload.
	Unsealed bool
	// CurrentAsk is the ask configured in the ask-store via the `lotus retrieval-deals set-ask` CLI command.
	CurrentAsk Ask
}

The output Ask is defined as:

type Ask struct {
   PricePerByte            abi.TokenAmount
   UnsealPrice             abi.TokenAmount
   PaymentInterval         uint64
   PaymentIntervalIncrease uint64
}

• To use this mode, set the DealMaking.RetrievalPricing strategy to "external" and needs to be given the absolute path of the pricing script as shown below:

[Dealmaking.RetrievalPricing]
    Strategy = "external"
    [Dealmaking.RetrievalPricing.External]
      Path = "<absolute path to the script>"

This example in go sets the ask price of the deals from certain clients to 0.003 FIL/Byte and unseal price to be zero. To use the script:

• Build it by running go build -o retrievalpricing ../fil-dynretprice/main.go, where retrievalpricing is the built script file name.
• Then set the Path of Dealmaking.RetrievalPricing.External to be the absolute path of retrievalpricing.
• Restart your lotus-miner for the script to be effective.

Reference: #6175 (comment) by @aarshkshah1992

[stuberman]

Corrected spelling errors for "RetrievalPricing" (not RetreivalPricing)

[jennijuju]

thanks @stuberman ! updated

[Byeager1]

@jennijuju , if we want to modify the retrieval price, do we set the following:

UnsealPrice: abi.NewTokenAmount(int64(.00000001 * float64(build.FilecoinPrecision)))

?