[EPIC] Storage Ask Protocol

[jennijuju]

• [x] https://github.com/filecoin-project/lotus/issues/3958
• [x] https://github.com/filecoin-project/lotus/issues/7301
• [x] https://github.com/filecoin-project/lotus/issues/5509

[jsign]

Maybe also an extra flag/boolean to say if miner is in maintenance mode or similar to signal that now isn't a good moment to make deals; so to avoid the usual "set a really high price" to do that signaling.

[de-authority]

summary from slack discussion: 1: We should add the ability to make different price for different clients/regions/data sizes/storage durations 2: We should expose the criteria by which we accept deals so that the client is clear about what is happening 3: How do we implement these features? 　　a. Extend the existing query-ask functionality, e.g. by adding fields 　　b. Call an external script to reply to each deal request with a json, or if there is no external script, call lotus' static rules to give a reply

[de-authority]

I think the main question now is can we have a different pricing strategy?　As far as I know storage providers can't do that, so it should be two different things 1: How do we expose the transaction acceptance policy, this is well done, by extending the fields or external scripts to respond to client requests. 2: How do we set different pricing criteria for different customers, this is a new feature altogether.

[s0nik42]

GET-ASK2 PROPOSAL // DRAFT PROPOSITION

Let me know what you think and if this can be our starting point

On get-ask :

Common lotus logic to all the use-cases

- Without get-ask-filter : lotus internal get-ask logic
- With get-ask-filter configured : 
	- Lotus execute basic integrity checks
	- Format the get-ask-query in json
	- Delegate completely the answer to the get-ask-filter
	- Pass the get-ask-query to get-ask-filter (stdin)
	- If Get-ask-Filter returned status code = 0 
		- Get-ask-filter return a json get-ask-response (stdout)
		- Any integrity check here done by lotus ?!?
		- Lotus send back get-ask-response to the requestor
	- If Get-ask-Filter returned status code != 0
		- Lotus return a generic error
		- Log internally get-ask-filter stderr + returned status code

Use case 1 Anonymous pricing request :

Requested content :

No specfic parameters

Expected Behaviour :

- Without get-ask-filter configured : lotus return the public pricing set in lotus
- With get-ask-filter configured  : get-ask-filter return the public pricing

Use Case 2 Signed pricing request :

Request content :

- ClientAddress
- ClientSignature

Expected Behaviour :

- Without get-ask-filter configured : lotus team ?!?
- With get-ask-filter configured : 
			- Lotus check the signature
			- get-ask-filter return the relevant pricing

get-ask returned FORMAT:

Disclaimer

• A rule can contain any number of criterias.
• Rules are ordered
• The pricing of the first matching rule give the price.
• A storage-deal-proposal that doesn't match any rules will be rejected

Json format

{
	"type": "pricingDiscover"
  "expiration": "epoch",
	"pricing": {
    "rules": [
      {
        "criterias": {
          "DealSizeMin": "bytes",
          "DealSizeMax": "bytes",
          "DealDurationMin": "epoch",
          "DealDurationMax": "epoch",
          "StartIn": "epoch",
          "FastRetrieval": "bool",
          "TransferType": "(graphsync/manual/etc...)",
          "DealType": "(verified/unverified)"
        },
        "price": "attoFil"
      },
      {
        "criterias": {
          "DealSizeMin": "bytes",
          "DealDurationMin": "epoch"
        },
        "price": "attoFil"
      }
    ]
  },
  "contact": "a contact link / email / slack / for client to reach out the miner"
  "x_nonstandard_key": "storage providers can send any extra non-standard data in the response by prefixing the custom keys name with x_"
}

Use case 3 Signer request with criterias (Optional but useful)

For both Anonymous and Signed request. the Client can query get-ask with a the folowing attributes :

Request content:

- attributes 
	- DealSize (bytes)
	- DealDuration (epoch)
	- StartIn (epoch) (number of epoch between DealProposal and StartEpoch)
	- FastRetrieval (true/false)
	- TransferType (graphsync/manual)  + http ?!?
	- DealType (verified/unverified)
- Xtra fields can be agreed between miner and client prefixed by x_. (max size ?!?)

Expected Behaviour :

- Without get-ask-filter : lotus team ?!?
- With get-ask-filter : 
			- Lotus check the signature
			- get-ask-filter return the relevant pricing

get-ask returned FORMAT:

{
	"type": "priceCheck"
  "expiration": "epoch",
	"acceptance": "accept/reject"
	"pricing": "attoFil"
  "contact": "a contact link / email / slack / for client to reach out the miner"
  "x_nonstandard_key": "storage providers can send any extra non-standard data in the response by prefixing the custom keys name with x_"
}

[jsign]

@s0nik42 , great kickoff! Some comments to keep the ball rolling...

Use Case 2 Signed pricing request :

Request content :

- ClientAddress
- ClientSignature

Expected Behaviour :

- Without get-ask-filter configured : lotus team ?!?
- With get-ask-filter configured : 
			- Lotus check the signature
			- get-ask-filter return the relevant pricing

I think this sounds reasonable, but I'm wondering how we can solve some use-case that we'll start supporting in bidbot, which is allowing external clients to sign with their own wallets. That means that bidbot should know the get-ask result for a wallet address that doesn't have private keys. Instead of building some complex and error-prone process that affects clients and providers to ask remote-wallets to also sign get-ask requests... maybe we can include some extra flag admin-token or similar that can bypass the signature check?

Seems like an easy solution, since that would mean all bidbot use of get-ask-v2 can specify that flag and avoid the signature. That flag is provided by the miner while configuring bidbot, so only the miner is allowing that kind of privileged calls.

get-ask returned FORMAT:

Disclaimer

• A rule can contain any number of criterias.
• Rules are ordered
• The pricing of the first matching rule give the price.
• A storage-deal-proposal that doesn't match any rules will be rejected

Json format

{
	"type": "pricingDiscover"
  "expiration": "epoch",
	"pricing": {
    "rules": [
      {
        "criterias": {
          "DealSize": "bytes",
          "DealDuration": "epoch",
          "StartIn": "epoch",
          "FastRetrieval": "bool",
          "TransferType": "(graphsync/manual/etc...)",
          "DealType": "(verified/unverified)"
        },
        "price": "attoFil"
      },
      {
        "criterias": {
          "DealSize": "bytes",
          "DealDuration": "epoch"
        },
        "price": "attoFil"
      }
    ]
  },
  "contact": "a contact link / email / slack / for client to reach out the miner"
  "x_nonstandard_key": "storage providers can send any extra non-standard data in the response by prefixing the custom keys name with x_"
}

Some comments:

• Startin is very interesting! I'm waiting for this for some time :100:
• Maybe the names of criteria fields could be different to auto-explain how they should be interpreted? e.g: how clients should use DealSize information for criteria? Does that mean this criterion applies if the deal size is less, less or equal, greater than that size? Depending on that, maybe MinOrEqDealSize, some more verbose description to make it 100% clear and self-contained.
• Might worth allowing "empty" values in fields to express "any value applies"? I'm asking this since if this isn't the case, you can have some explosion of combinations; like repeating most of the criteria for all pairs of combinations of [(verified/unverified), (online/offline), (possibly others)]. "Empty" values to express "all values" should be clearly defined (e.g: no field?, empty string?, zero-value for integers?, null/nil?, etc).
• The "if no criteria are satisfied, then reject the deal" sounds fine. I'd guess most miners will 99% of the time configure a last-criteria which is very general and just be more expensive, or ask for bigger start-deal-epoch, or similar.
• If the miner is in maintenance mode, I'd guess this would turn out to be an empty set of criteria, right? (considering point above).

[s0nik42]

@jsign thank you,

I think this sounds reasonable, but I'm wondering how we can solve some use-case that we'll start supporting in bidbot, which is allowing external clients to sign with their own wallets. That means that bidbot should know the get-ask result for a wallet address that doesn't have private keys. Instead of building some complex and error-prone process that affects clients and providers to ask remote-wallets to also sign get-ask requests... maybe we can include some extra flag admin-token or similar that can bypass the signature check?

Is that admin_token verification performed by lotus or the deal filter ?

Startin is very interesting! I'm waiting for this for some time 💯 Maybe the names of criteria fields could be different to auto-explain how they should be interpreted? e.g: how clients should use DealSize information for criteria? Does that mean this criterion applies if the deal size is less, less or equal, greater than that size? Depending on that, maybe MinOrEqDealSize, some more verbose description to make it 100% clear and self-contained.

Good catch, I updated my previous post to add more values. I propose to use just Min and Max implying "OrEq" like in lotus today.

Might worth allowing "empty" values in fields to express "any value applies"? I'm asking this since if this isn't the case, you can have some explosion of combinations; like repeating most of the criteria for all pairs of combinations of [(verified/unverified), (online/offline), (possibly others)]. "Empty" values to express "all values" should be clearly defined (e.g: no field?, empty string?, zero-value for integers?, null/nil?, etc).

In the proposal, the absence of a criteria means any values (as its not a criteria that we take into account for a specific rule)

If the miner is in maintenance mode, I'd guess this would turn out to be an empty set of criteria, right? (considering point above).

That's actually a good question. Shall the Get-ask cover the maintenance mode, any other opinion?

[jsign]

Is that admin_token verification performed by lotus or the deal filter ?

I guess whatever place the deal signature is verified.

I propose to use just Min and Max implying "OrEq" like in lotus today.

Cool, we can leave that "OrEq" at the documentation level. :+1:

Also, :+1: on the rest of unquoted things.

[s0nik42]

👍🏻

I guess whatever place the deal signature is verified.

• Can the admin_token be replaced by a delegate_key (bidbot owned address) signed by the client key ?
• We should also add the client key to the request.
• Delegate key sign the request, and include the signed delegate_key ?

I'm just thinking that if the admin_token is a Dealfilter thing it might be different per Dealfilter implementation. If its manage by lotus ... I don't know ...