Skip to content

POST /storage-plugins/privatestorageio-zkapauthz-v1/calculate-price

The Tahoe-LAFS node will have a new endpoint at /storage-plugins/privatestorageio-zkapauthz-v1/calculate-price. This endpoint accepts a POST request. The request body is application/json of the form:

{ "version": 1, "sizes": [ <integer>, ... ] }

The value for the version property must be 1. Each element of the list associated with the sizes property is the size of a file in a magic-folder. The response to the request is a 200 OK application/json-encoded response of the form:

{ "price": <integer>, "period": <integer> }

The price property gives an integer number of ZKAPs that need to be spent to store a collection of files of the indicated sizes for 1 lease period. The period property gives the length of a lease period in seconds.

The only thing the calculated price accounts for is the price of acquiring a lease for the indicated period on a collection of files with the indicated sizes. This price should exactly match the price to either:

  • Upload such a collection of files for the first time
  • Renew the leases on such a collection of files which have already been uploaded

The price does include any Tahoe-LAFS-incurred storage overhead (such as size expansion due to erasure encoding).

It does not include additional magic-folder-incurred costs such as creating a collective or DMD, a root cap, backing up ZKAPs, etc. Note that the costs of such extras could be computed using this API if some component of the system is capable of determining the sizes of these things (but that won't be this component).

It also does not account for whatever is currently stored on the grid. For example, if a magic-folder exists and has a collection of files in it which have already been uploaded and have 20 out of 31 days remaining on their leases this API will not discount the resulting price by the remaining 20 days of space-time which have already been paid for. It will just calculate the price to take out a new 31 day lease on those files. The error (from a user perspective) this introduces into the result can be mitigated by factoring in the time at which the least maintenance service will next run, I think. That is, it can be assumed that the price to renew leases on these files won't be paid until the lease maintenance service runs again and at that point it will buy a full lease period of storage. There is an API for reporting when the service last ran but I don't think it exposes the time of its next run yet. So this change should probably also include the addition of that information to the lease maintenance information endpoint (which is unblinded-tokens apparently ...).