Aggregator Payment FRC

[honghaoq]

Introduction

This proposal extends the I*DataAggregator standard (see this FRC) with a new IAggregatorPayment interface for aggregators to handle payment, and provides its reference implementation. In the aggregator deal standard FRC, we defined a submit and complete workflow for deal making onchain, in this standard, we extends it by adding reference for end to end payment handling methods, including estimateFee, submit (payable), complete, withdraw functions, along with balance and allowance update.

Standardizing these interfaces and functions for payment handling allows various aggregators to offer a set of uniform methods to process payment for paid storage deals. This enhances community portability across different aggregators and promotes compatibility among tools and libraries.

Note that this standard applies toward both offchain aggregator (where deal aggregation and CommPa computation happens entirely offchain) and onchain aggregator (where deal aggregation happens offchain but CommPa computation happens onchain), as shown in the specification below.

Motivation / Context

This standard makes it possible for aggregator to take payments from client deals onchain, and distributes the fund toward aggregator and/or storage provider providing the service. This standard helps facilitate the adoption trend of paid deals, which is crucial for aggregators and storage providers to become long-term, self-sustainable businesses.

The main audience of this standard are: 1) clients that want to make payment directly via smart contract for paid aggregation and storage deals; and 2) aggregators that want to leverage onchain primitives to aggregate data and process deal payment from clients. Note that this FRC can be built on both FVM mainnet as well as IPC subnets.

Specification

IAggregatorPayment Interface for payment handling

Outlined below is the IAggregatorPayment interface with functions extending the I*DataAggregator standard to handle payment processing in smart contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.17;

/**
 * @title IAggregatorPayment Interface for payment handling
 * @notice Interface for an aggregator with payment handling on the Filecoin Virtual Machine (FVM)
 */
interface IAggregatorPayment {
   
/**
     * @notice Function to get a price quote from aggregator for the deal. Note that this function assumes a default storage term, e.g. returns a price estimate for perpetual storage of a given data size. If aggregator wants to accept flexible term storage deals, this function can be adjusted to take the deal term parameters to return price quote
     * @param _fileSize The size of the files to be stored (in Bytes)
     * @return The estimated fee for the deal
     */
    function estimateFee(uint256 memory _fileSize) external returns (uint256);

/**
     * @notice Function to withdraw fund from contract. User could withdraw if the deal is not made. Aggregator and storage provider can withdraw if deal is completed
     * @param _amount The amount to withdraw from contract, must be within allowance balance
     */
    function withdraw(uint256 amount) external {}

}

To enable aggregators with payment handling, we expect teams to implement the payment functions in IAggregatorPayment along with the payable submit and complete functions in the I*DataAggregator interface mentioned in the aggregator deal standard FRC. Here we show the submit (payable) and complete functions needed to handle payment for offchain data aggregator and onchain data aggregator respectively.

IOffchainDataAggregator interface with submit payable

The IAggregatorPayment interface works with the IOffchainDataAggregator standard in the aggregator deal standard FRC. It tightly follows the submit-complete two-step deal making process, and make it compatible for handling payments onchain. Here is the updated IOffchainDataAggregator interface to support payment handling.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.17;

/**
 * @title IOffchainDataAggregator Interface with payment handling
 * @notice Interface for an aggregator with payment handling on the Filecoin Virtual Machine (FVM)
 */
interface IOffchainDataAggregator {
   
    /**
     * @notice A payable function to submit a new file (as denominated by a piece CID) to the aggregator and to add balance based on the price quote. This function should also check if the balanace is enough as user submits the deal request
     * @param _cid The piece CID to be stored
     * @param _fetchLink A link to he piece CID to allow the aggregators to fetch the data in the piece CID
     * @return The identifier (transaction Id) for the submitted request
     */
    function submit(bytes memory _cid, bytes memory _fetchLink) external payable returns (uint256);

    /**
     * @notice Callback function that is called by the aggregator once data has been stored successfully, it also updates the allowance for specified addresses, which could be aggregator or storage provider's address
     * @param _id The identifier for the request
     * @param _dealId The deal's unique identifier
     * @param _providerId The provider's unique identifier
     * @param _proof Inclusion proof for the stored data segment
     * @param _verifierData Additional data needed to verify the inclusion proof
     * @return Additional auxiliary data
     */
    function complete(
        uint256 _id,
	uint64 _marketActorId,
        uint64 _dealId,
        uint64 _providerId,
        InclusionProof memory _proof,
        InclusionVerifierData memory _verifierData
    ) external returns (InclusionAuxData memory);

}

More details about the IOffchainDataAggregator interface can be found in this FRC, and a reference implementation to offchain data aggregator with onchain payment processing is available here.

IOnchainDataAggregator interface with submit payable

Similarly. for building onchain aggregators (aggregators that compute CommPa within smart contract onchain), the IAggregatorPayment interface would be implemented along with the IOnchainDataAggregator interface for payment processing. Here the submit function needs to be a payable function.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.17;

/**
 * @title IOnchainDataAggregator Interface with payment handling
 * @notice Interface for an aggregator with payment handling on the Filecoin Virtual Machine (FVM)
 */
interface IOnchainDataAggregator {
   
    /**
     * @notice A payable function to submit a new file (as denominated by a piece CID) to the aggregator and to add balance based on the price quote. This function should also check if the balanace is enough as user submits the deal request
     * @param _cid The piece CID to be stored
     * @param _fetchLink A link to he piece CID to allow the aggregators to fetch the data in the piece CID
     * @return The identifier (transaction Id) for the submitted request
     */
    function submit(bytes memory _cid, bytes memory _fetchLink) external payable returns (uint256);

    /**
     * @notice Callback function that is called by the onchain aggregator once data has been stored
     * @param _id The identifier for the request
     * @param _dealId The deal's unique identifier
     * @param _providerId The provider's unique identifier
     */
    function onchain_complete(
        uint256 _id,
	uint64 _marketActorId,
        uint64 _dealId,
        uint64 _providerId,
    ) external returns ();

}

More details about IOnchainDataAggregator interface with onchain_complete function can be found in the aggregator deal standard FRC.

Reference Implementation

A reference implementation of an offchain aggregator with payment handling enabled can be found here.

Rationale

A full-fledge data aggregator with payment handling will implement the IAggregatorPayment interface along with the I*DataAggregator interface and IDataAggregatorEnumerable Interface (as defined in the aggregator deal standard FRC with the following functions:

• estimateFee(): the first step for making a paid deal is to get price quote, estimateFee function allows client to estimate pricing based on the amount of data and storage deal term they need to make, pricing calculation would be implemented based on different aggregators’ pricing models;
• submit(): after getting price quote, client can submit the deal request to aggregator and add fund with the payablesubmit function. For aggregator running RaaS, it should makesubmitRaaS function payable, details of submitRaaS can be found in this FRC.
• complete(): after receiving the deal requests, aggregator will perform data aggregation and check if data size matches with the provided fee, if the check passes and deal is made successfully, aggregator will call back to contract with the complete function to update deal information and allowance for aggregator/storage provider. For aggregator running onchain aggregator service, it would use onchain_complete function instead, as defined in this FRC, the payment processing interface and workflow are the same.
• withdraw(): after deal is made successfully and allowance is updated, aggregator/storage provider can use the withdraw function to collect their portion of the fee from client. User can also withdraw the fund with this method if the deal is not made.

Essentially, this extends the two-step submit and complete deal-making workflow with payment handling properties. The updated workflow diagram with payment handling is shown in the diagram below:

Backwards Compatibility

This proposal introduces a new standard and does not alter or disrupt existing interfaces or implementations. However, aggregators wishing to conform to this standard for onchain payment handling will need to adopt this interface.

Test Cases

Testing for the implementation of the onchain payment interfaces should focus on:

• Successfully add and withdraw fund with accurate balance accounting
• User can withdraw back the fund if deal is not made
• Aggregator and Storage Provider can withdraw their portion of the fund if deal is made successfully
• Allowance is updated accordingly based on aggregator and SP revenue sharing business models

Security Considerations

Since it does not introduce Filecoin protocol level changes, there is no protocol level security concerns at this time.

Handling malicious fund withdraw behavior: there is a possibility where client adds fund and then withdraws while aggregator is making deal or after deal is made, in which case aggregator/Storage Provider won’t get paid afterwards since fund is withdrawn. Clients do need to be able to withdraw fund themselves in case aggregator/SP not taking actions, but to protect payment for aggregator/SP, we recommend to only change client's allowance after request submitted to lock that fund for 7 days (lock period up to aggregators to define). This would give aggregator 7 days to process the deal, if it doesn't happen, then the fund is unlocked (revert allowance back) so user can withdraw. If the deal goes through, then allowance is updated so aggregator/SP can get paid. Since this requires a mapping of clients and request time to lock/unlock fund, we recommend implementing it on IPC if there is cost concern.

Copyright Waiver

Copyright and related rights waived via CC0.