# FWS/PDP Design Doc

Useful Links:
* [Prototype code](https://github.com/nicola/fws-service/blob/main/contracts/FWS.sol)
* [PDP Service](https://hackmd.io/toA5xkuyREy30Q6_nX1dgQ)

## TODOs
* Specify early soft termination of Client and Provider

## Goals
**Make Filecoin the network of reference for a broad range of cloud services**
The current Filecoin offering today is limited to Proof of Replication. The proposed idea is to make it possible to deploy new services (e.g. ticketing systems for retrieval, retrieval guarantees protocols, compute over data, short term deals, proof of data possession) and that these services are offered and requested on the Filecoin network.

**Increase the storage and compute offer by lowering the barrier to entry to create and use services**
Although it is possible to deploy a new market on Filecoin for a specific type of service is possible, it is a very large endeavor. There are some core components that we can offer so that anyone can deploy new service or a deal policies, without having to redesign a new storage market, or compute network - which creates friction to new developers

**Increase the Filecoin network revenue, storage capacity, utilization and foster compute jobs**
The Filecoin network currently “earns” off gas fees, which currently are very low (and we expect with better technology to go to zero). There are pending proposals to add new fees at other layers of the stack (onboarding fee proportional to the amount of the storage onboarded, proof fee for generating a specific proof). The proposal here is that Filecoin takes a fee from the FWS contract on the volumes transacted (plus potentially a small service fee).

## Terminology

- **Provider**: party who is in charge of providing the service and proving that such service meets SLA conditions (eg, storing data and proving access to such data once a day);
- **Client**: party who requests and pays for the service;
- **Deal**: it specifies the terms over which a *client* and a *provider* agree with respect to a service for some data. It is associated with the commitment to the data (commP) and identified by the dealID;
- **SLA**: the agreement for what happens if the deal is carried honestly or dishonestly (payments, collateral, faults);

## Design Goals

**High level**
* **Unlikely to fork**\
FWS should create network effects such that it will be hard for someone to simply for the FWS smart contract. Examples of this goal:
* Deposits locked for payments and collateral are hard to fork
* Re-use deposits and collateral across services
* Future upgrades, UX and long-term support
* **Payments can be paid in any currency**\
The goal is to maximize the size of the market that we can tap into. This means that while the default would be to price things in Filecoin, FWS allows for payments in any currency.
* **Charge fees in Filecoin**\
Fees are charged on Filecoin specific services and as well on the volume of the value transacted. FWS fees are charged in FIL, if the users do not have FIL (or the payment is in another currency), this is converted into FIL using available approved AMMs.
* **Easy to launch a new service**\
It should be easy for developers to develop new services or connect an existing service into FWS. This can be done in a few ways:
* Simplifying the abstractions;
* Providing complex parts as libraries, templates or smart contracts to inherit;

**Design level**
* **Escrow**
* The Escrow contract is the main place for managing deals and payments
* All money management happens via the Escrow contract (deposits, withdrawal)
* All the deal management happens via the Escrow contract (check if deals can be removed, etc)
* **Services**
* The Service contracts are the main place for interaction for the service providers
* All service book keeping happens via the Service contracts (e.g. providing storage proofs, compute proofs, etc)
* All interactions for book keeping to the Escrow happen via the calls that the Service contract does to the Escrow

## Protocol

There are main contracts:
* Escrow (singleton)
* Services contracts (PDPService, RetrievService, SparkService,...)
* Deal SLA contracts

The main flows are as following

**Adding, removing, updating deals**
* Provider → Services using `service.update` on new deals, deal update and deal terminations
* Services → Escrow using `Escrow.start` for new deals
* Services → Escrow using `Escrow.stop` for deal terminations
* Escrow → DealSLA using `dealSLA.canRemoveDeal`

**Deposit, withrawing, getting paid**
* Provider/Clients → Escrow using `Escrow.Deposit()` to fund the account
* Provider/Clients → Escrow using `Escrow.Withdraw()` to withdraw funds
* If it's a Provider, Escrow → DealSLA using `dealSLA.canWithdraw` to calculate how much it can be withdrawn. Sum the total for each deal

### Data structures

#### Deal (Generic)

* `address Provider`
* `address Client`
* `address SLA`
* `address Service`

TODO: In the future deals that share the same data should be combined into a single deal**s** structs

### Smart Contract interfaces

#### Service (Generic)

* `update(newSignedDeals, newDeals, toBeReplacedIDs, toBeTerminatedIDs)`
* Called by the provider to start, stop, update existing deals using the service.
* For new deals, call `Escrow.start(signedDeal)`
* For deals to replace, call `Escrow.stop(toBeReplacedIDs)`
* For deals to be forced to terminate, call `Escrow.terminate(toBeTerminatedIDs)`
* `checkFaults(dealIDs)`
* Called by the Deal SLA to see outstanding faults for the set of deals

#### SLA (Generic)

* `canWithdraw(dealIDs)`
* Calculates how much can be withdrawn for these dealIDs, the rest is locked
* `canTerminate(dealIDs)`
* Returns whether or not the deal can be terminated

### Escrow
* Allows clients and providers to deposit funds for future collateral and payments.
* Should be easy for new services to be integrated with the escrow.
* Keeps track of all the deals
* Calculates how much money are locked

#### Contract
* State
* `mapping(uint escrowID => Deal deal) deals`
* A mapping of all the deals
* `mapping(address => uint256 amount) deposits`
* A mapping of all the deposits
* `uint256 IDCounter`
* Keeps a counter of the current deal number
* Methods
* `Start(signedDeals)`
* Stores info about the new deals
* `Deposit(amount)`
* Takes `amount` from user and transfers it to escrow
* `Withdraw(amount)`
* Checks the amount withdrawable by going through every commitment for payments or collateral that the user has (TODO can be computed or read from state, current proposal is to compute it);
* Burns collateral if required by some deals and collateral not yet burned;
* `GetDealInfo(dealID)`
* Returns deal info

## Building a PDP Service

### Building using auxiliary components

#### Storage Deal

Inherits `Deal`, plus

* `uint256 Size`
* `uint Frequency`

#### Pay-as-you-go Deal
Inherits `Deal`, plus

* `unit256 cancelBefore`

#### ProofSet Storage Service

A template for a storage service that keeps a list of CIDs to be stored. Storage is checked every round of size `frequency` blocks

If proofs are missed in between `frequency` blocks, the proofSet is considered faulty, and only becomes not faulty at the next proof

* **State**
* `mapping(uint256 ID => ProofSet) proofSets`
* Keeps a mapping from proofSet ID to a proofset struct
* `mapping(uint256 proofSetID => Faults[]) faults`
* Keeps a mapping from proofset ID to the history of faults
* **Methods**
* `function create(uint256 frequency) public returns (uint256 ID)`
* Creates a new proofSet with a specific frequency check
* `function currentFaults (uint256 ID) public virtual view returns (uint faults)`
* Returns current faults (based on how many proof rounds have been missed)
* `function _onValidProof(uint256 ID) internal`
* Performs book keeping when a valid proof has been reported for a proofset (e.g. records the last time it was correctly proven)

#### DealStoredOnchain Service
Inherits `ProofSetStorage`

A template for a ProofSet Storage service where all the deals in a proofset are stored on-chain.

* **State**
* `mapping(uint proofSetID => uint256[] escrowID) dealsMap`;
* `mapping(uint256 escrowID => ProofSetIndex psIndex) dealsIndex`;

The `update` function stores the mapping of new deals in a specific proof set

### Finally a simple PDP Service

contract SimplePDPService is ProofSetService, DealStoredOnchain {
  constructor (address _escrow)  {
    escrowAddress = _escrow;
  }

  function prove (
    uint256 proofSetID, uint256 challenge, ProofData calldata proof, bytes32 leaf
  ) public {

    // Get deal to be challenged
    uint256 challengedIndex = challenge % dealsMap[proofSetID].length;
    uint256 challengedEscrowID = dealsMap[proofSetID][challengedIndex];
    Deal memory deal = Escrow(escrowAddress).getDeal(challengedEscrowID);

    // Verify proof
    require(PoDSILib.verify(proof, leaf, deal.CID), "Proof did not verify");

    // Perform book keeping
    super._onValidProof(proofSetID);
  }
}

## Current Protocol (DRAFT)

This is a high level interaction flow of the protocol.

sequenceDiagram
    actor Client
    actor Provider
    participant Escrow
    participant DealSLA
    participant PDPService

    alt prepays and collaterals
        Client ->> Escrow: Escrow.deposit(amount)
        Provider ->> Escrow: Escrow.deposit(amount)
    end  

    alt adding a proofset
        Provider ->> PDPService: PDP.createProofSet(params) -> proofSetID
    end

    alt Client<>Provider match and exchange file
        Client -->> Provider: file
        Provider -->> Client: ok
        Client -->> Provider: signedDeal
    end

    alt updating a proofset
        Provider ->> PDPService: PDP.updateProofSet(proofSetID, newSignedDeals, toRemoveDealIDs)

        alt create a deal
            PDPService ->> Escrow: Escrow.start(signedDeal) -> dealID
        end
        
        alt remove deals
            PDPService ->> Escrow: Escrow.stop(dealIDs)
            Escrow ->> DealSLA: DealSLA.canRemoveDeals(dealIDs)
            DealSLA -->> Escrow: yes/no
        end
    end
    alt submit daily proof
        Provider ->> PDPService: PDP.Prove(ID, proof)
        PDPService ->> PDPService: Event(ProofOutcome(ID, outcome))
        PDPService ->> PDPService: If missed proofs>0 Event(FaultsEvent(ID, latestProofEpoch, proofsMissed))
    end

    alt get paid
    Provider ->> Escrow: Escrow.withdrawl(..) -> yes/no
    Escrow ->> DealSLA: DealSLA.canWithdraw(dealIDs)
    DealSLA ->> PDPService: PDPService.checkFaults(dealIDs)
    PDPService -->> DealSLA: yes/no
    DealSLA -->> Escrow: yes/no
    
    Escrow -->> Provider: tokens
    end

---

#### Old

sequenceDiagram
autonumber

participant Client
participant SP
participant Escrow

alt making deal

    alt Deposit to escrow
    Client ->> Escrow: Deposit(EscrowID)
    SP ->> Escrow: Collateral()
    end
    
    alt Deal making
    Client ->> Escrow: MakeDeal(EscrowID, SPSig(deal), min_expiry, faultOracle=PDP)
    end
    
    alt Honest SP
    SP ->> Escrow: Withdraw()
    Escrow ->> ServiceOracle: CheckPDPProofs
    ServiceOracle -->> Escrow: yes
    Escrow -->> SP: yes
    end
    
    alt Faulty SP
    SP ->> Escrow: Withdraw()
    Escrow ->> ServiceOracle: CheckPDPProofs
    ServiceOracle -->> Escrow: no
    Escrow -->> SP: no
    end
    
    alt SP gracefully terminates
    SP ->> Escrow: Terminate(ID)
    note left of Escrow: expiry time passes (then got back to Honest SP)
    end
    
    alt User gracefully terminates
    Client ->> Escrow: Withdraw(ID)
    note left of Escrow: Check that there are at least as much money for the next payment
    Escrow -->> Client: yes/no
    end

    
end