GIP-0006: Withdraw helper contract to support collecting funds from Vector channels

ari · May 27, 2021, 4:29pm

This proposal is to deploy a new peripheral contract to connect Vector state channels with the core protocol. For this contract to work the Council will need to set its address as asset holder in the Staking contract.

Motivation

Vector state channels are contracts that hold funds used as collateral for consumer-to-indexer payments. When an indexer closes an allocation, both parties sign a withdrawal commitment to transfer the query fees accumulated for the allocation back to the network. Vector, by default, supports plain transfers from the channel to any destination defined in the withdrawal commitment. In the case of the Graph Network, all funds should be collected by calling the collect() function in the Staking contract. For the purpose of calling custom logic when transferring from channels, Vector supports using a WithdrawHelper contract. In this proposal we describe the implementation of such a contract for connecting a Vector withdrawal transfer to the Graph Network.

Implementation

A contract called GRTWithdrawHelper that extends the base WithdrawHelper provided by the Vector framework. This contract has a function execute(WithdrawData _wd, uint256 _actualAmount) external that is called in the same transaction when the indexer withdraw funds from the channel. The execute function evaluates the validity of the WithdrawData struct, and then approve and transfer the received funds to the Staking contract by calling collect() .

This contract does not hold funds, it just forward the received funds from the Vector channels in the context of an atomic transaction.

Status

A candidate contract was implemented in this PR:

github.com/graphprotocol/contracts

Withdraw helper contract to support collecting funds from channels

graphprotocol:master ← graphprotocol:ariel/withdraw-helper

opened 08:57PM - 12 Mar 21 UTC

abarmat

+323 -3

### Summary Introduces a contract called `GRTWithdrawHelper`. The main goal o…f this contract is to encode custom logic in the process of withdrawing funds from the Vector Channel Multisigs. The contract receives funds from a Channel Multisig, then it forwards them to the Staking contract related to an Allocation. ### Features - The **GRTWithdrawHelper** is deployed with the token address that will be used for transfers, in our case it is the GRT token address. It can't be changed at later stage but this can easily be solved deploying a new contract if needed. - The contract expects to have available tokens in balance when `execute(WithdrawData calldata wd, uint256 actualAmount)` is called by the Channel. For that to happen the Channel needs to transfer funds to the WithdrawHelper before execute is called. - On execute the WithdrawHelper will approve the funds to send to the Staking contract and then execute `collect()` passing the proper allocationID and amount. The Staking contract will then pull the tokens. - If the call to `collect()` fails, the funds are returned to the channelAddress. This is important for Vector accounting of funds. ### Requirements - Set the **GRTWithdrawHelper** contract as AssetHolder in the Staking contract. This way we allow accepting funds from this contract. - The cooperative withdrawal commitments must have the following data (indicated with arrows): ``` struct WithdrawData { address channelAddress; address assetId; // -> GRT token address address payable recipient; // -> GRTWithdrawHelper contract address uint256 amount; uint256 nonce; address callTo; // -> GRTWithdrawHelper contract address bytes callData; // -> CollectData struct defined below } ``` ``` struct CollectData { address staking; // -> Staking contract address address allocationID; // -> AllocationID to send collected funds } ``` The parties must agree and sign the WithdrawalCommitment with that information to achieve proper execution of the withdrawals. ### Exceptions The following conditions will result in reverts of the execution: - **assetId** in **WithdrawData** not matching the token address configured in the _GRTWithdrawHelper_. - _GRTWithdrawHelper_ not having enough balance to transfer the Staking contract as stated in **actualAmount**. - Setting an invalid **staking** contract address. Note: To avoid unexpected conditions in the Vector offchain logic, it is encouraged that the parties verify the WithdrawData does not revert by doing a call/estimateGas. ### Handled Exceptions These reverts are handled and will make the contract to return the funds to the channel address. - Doing a withdrawal on a non-existing allocationID as defined in **CollectData** when calling `collect()`. ### Known Behaviour - This contract does not know if a WithdrawalCommitment is right or wrong. It just accepts a transfer and WithdrawData that defines a destination. - A properly formatted WithdrawData can be crafted to send outside funds to the Staking contract. In that case, the person will get those funds distributed with Curators + Delegators + taxed a protocol percentage. There is no rational economic incentive to do so.

The contract was audited by ChainSafe and deployed and tested in Rinkeby:

A GIP will be published with additional information on Radicle.

Topic		Replies	Views
GIP-0046: L2 Transfer Tools Graph Improvement Proposals (GIP)	35	5928	May 31, 2023
GIP-0032: Make GNS signal transferrable Graph Improvement Proposals (GIP)	3	1670	May 16, 2022
GIP-0060: Early allocation closure Graph Improvement Proposals (GIP)	5	3303	April 22, 2024

GIP-0006: Withdraw helper contract to support collecting funds from Vector channels

Motivation

Implementation

Status

Related Topics