Document the architecture about the automated datacap allocation for clients

[aaitor]

NOTE: This design is complemented by: https://github.com/keyko-io/filecoin-verifier/issues/26

How applications can on-board their users in Filecoin?

Introduction

The current Filecoin Registry application allows to the verifier to allocate some of their datacap to clients. This is okay from a functional point of view because there is a mechanism to distribute the datacap from the verifiers to the associated clients to that verifier.

Also there are applications like Slate wanting to provide storage capabilities to their users using Filecoin as substrate. To support that capabilities, all the new Slate users should be able to receive automatically a datacap allocation from the verifier associated with that application (Textile in this case).

The current manual flow supported in the Filecoin registry application is totally functional but is not optimal for supporting automatic datacap allocation.

The objective of this document is to describe the technical solution allowing to allocate datacap in an automatic way to clients/users of these Filecoin applications.

Architecture

Here we distinguiss different actors:

• The VERIFIER (Textile for example)
• The CLIENT running an APP (Slate for example)
• The USERS of the APP (Slate users able to sign up in the website)

To support the level of automation required, there will be a micro-service (aka SERVICE) with the following characteristics:

• An instance of this micro-service must be executed for each VERIFIER (like Textile) requiring to automate the datacap allocation for the APP USERS (like Slate users)
• When a new USER is registered in the APP (like Slate or similar) using the APP sign-up process, this APP will send a datacap requests for the USER just registered to the SERVICE run by the VERIFIER
• The SERVICE will authenticate the datacap request coming from the APP via pre-shared token (aka PSK). The PSK identifies to a specific CLIENT (Slate in this case)
• The APPs will have a pre-allocation of datacap in the VERIFIER for all their potential USERS
• The SERVICE will expose a REST interface in the following endpoint POST /verifier/client/datacap. The PSK will be sent in the HTTP Authorization header. This endpoint will request the following JSON payload as input:

  {
  "clientAddress": "t01032",
  "applicationId": "LIKE_SLATE_ID",
  "userId": "INTERNAL_USER_ID",
  "datetimeRequested": "2020-02-08T08:13:49Z"
  }

• The SERVICE will authenticate the user via PSK
• The SERVICE will authorize the user request checking in the internal configuration if there is the existing allocation and mapping between the PSK and the client address and the client total datap pre-allocation
• In the internal configuration of the SERVICE this should have the key material related with the VERIFIER and allowing to interact with the Filecoin network via lotus node. Also the configuration will include a default datacap allocation for clients (1gb?). Each VERIFIER running the SERVICE depending on their needs can modify this configuration to allocate more or less datacap to new APP USERS.
• The SERVICE checks the existing allocation of the CLIENT (in this case Slate) to validate if there is datacap available to share. If that's the case the service allocate the datacap for the user.
• If everything goes right the SERVICE will return a response like this:

  HTTP 201
  {
  "clientAddress": "t01032",
  "applicationId": "LIKE_SLATE_ID",
  "userId": "INTERNAL_USER_ID",
  "datetimeApproved": "2020-02-08T08:13:49Z",
  "transactionId": "0x1234567890abcdeefgh1234567890abcdeefgh",
  "datacapAllocated": "1000000000000"
  }

• If the request can't be processed the SERVICE will return a response like this:

  HTTP 401 or 500
  {
  "clientAddress": "t01032",
  "applicationId": "INTERNAL_APPLICATION_ID",
  "message": "The verifier can't distribute more datacap at this time"
  }

• As owner of the SERVICE, I can attestate the datacap requests writing the output of the previous method and writing into IPFS or similar
• The technologies suggested for this service are Node.js and Express for the micro-service implementation
• It's recommended to have the SERVICE as much isolated possible from a networking point of view

[josepablofm78]

If we want to use Multisig accounts to keep traceability about the app that "approves" the datacap request the flow could be like this:

• Textile's Service exposes an endpoint, /verifier/app/register, that allows app, like slate, to register itself as a "verifier" for their clients. The request could be like: { "applicationAddress": "t01032", "applicationId": "LIKE_SLATE_ID", "datetimeRequested": "2020-02-08T08:13:49Z" }

• Textile's Service gets the request, authenticates the PSK, and setup all the multisig configuration (creates M1 multisig including app address, adds M1 to M0)
• Service assigns a limit of datacap the app can request (¿?)
• Service return a 201 Message indicating the addresses of both M0 and M1 multisig accounts { "applicationAddress": "t01032", "applicationId": "LIKE_SLATE_ID", "datetimeApproved": "2020-02-08T08:13:49Z", "M0Address": "t1xxxx", // think a name for this "M1Address": "t1yyy", //think a name for this }
• When a user of the app wants datacap, it will request it to the app using an endpoint
• The app implementation will include a library that allows to request datacap for the client using directly the multi sign account.
• So the app must custody a private key to sign the Tx and needs to configure the ws to a lotus node connected to the network
• Using a method from the library, the app executes M1.propose(M0.propose(verifreg.addDatacap(user, cap))
• Textile's Service gets the pending transaction to sign
• If there is enough datacap, Textile approves the tx and the user of the app gets the datacap