staking: more concept changes

Author: abarmat

contracts/staking/IStaking.sol

@@ -16,7 +16,7 @@ interface IStaking {
     enum AllocationState { Null, Active, Settled, Finalized, Claimed }
 
     /**
-     * @dev GRT stake allocation to a channel
+     * @dev Allocate GRT tokens for the purpose of serving queries of a subgraph deployment
      * An allocation is created in the allocate() function and consumed in claim()
      */
     struct Allocation {
@@ -25,9 +25,9 @@ interface IStaking {
         uint256 tokens; // Tokens allocated to a SubgraphDeployment
         uint256 createdAtEpoch; // Epoch when it was created
         uint256 settledAtEpoch; // Epoch when it was settled
-        uint256 collectedFees; // Collected fees from channels
+        uint256 collectedFees; // Collected fees for the allocation
         uint256 effectiveAllocation; // Effective allocation when settled
-        address channelProxy; // Caller address of the collect() function
+        address authSender; // Authorized caller address of the collect() function
     }
 
     // -- Delegation Data --
@@ -115,7 +115,7 @@ interface IStaking {
         bytes32 _subgraphDeploymentID,
         uint256 _tokens,
         bytes calldata _channelPubKey,
-        address _channelProxy,
+        address _authSender,
         uint256 _price
     ) external;
 
@@ -124,15 +124,15 @@ interface IStaking {
         bytes32 _subgraphDeploymentID,
         uint256 _tokens,
         bytes calldata _channelPubKey,
-        address _channelProxy,
+        address _authSender,
         uint256 _price
     ) external;
 
-    function settle(address _channelID) external;
+    function settle(address _allocationID) external;
 
-    function collect(uint256 _tokens, address _channelID) external;
+    function collect(uint256 _tokens, address _allocationID) external;
 
-    function claim(address _channelID, bool _restake) external;
+    function claim(address _allocationID, bool _restake) external;
 
     // -- Getters and calculations --
 
@@ -142,11 +142,11 @@ interface IStaking {
 
     function getIndexerCapacity(address _indexer) external view returns (uint256);
 
-    function getAllocation(address _channelID) external view returns (Allocation memory);
+    function getAllocation(address _allocationID) external view returns (Allocation memory);
 
-    function getAllocationState(address _channelID) external view returns (AllocationState);
+    function getAllocationState(address _allocationID) external view returns (AllocationState);
 
-    function isChannel(address _channelID) external view returns (bool);
+    function isChannel(address _allocationID) external view returns (bool);
 
     function getDelegation(address _indexer, address _delegator)
         external

contracts/staking/Staking.sol

@@ -109,13 +109,13 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
         address allocationID,
         bytes channelPubKey,
         uint256 price,
-        address proxy
+        address authSender
     );
 
     /**
-     * @dev Emitted when `indexer` withdrew `tokens` amount in `epoch` from `allocationID` channel.
-     * The funds are related to `subgraphDeploymentID`.
-     * `from` attribute records the the multisig contract from where it was settled.
+     * @dev Emitted when `indexer` collected `tokens` amount in `epoch` for `allocationID`.
+     * These funds are related to `subgraphDeploymentID`.
+     * The `from` value is the sender of the collected funds.
      */
     event AllocationCollected(
         address indexed indexer,
@@ -129,8 +129,8 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
     );
 
     /**
-     * @dev Emitted when `indexer` settled an allocation in `epoch` for `allocationID` channel.
-     * The `tokens` getting unallocated from `subgraphDeploymentID`.
+     * @dev Emitted when `indexer` settled an allocation in `epoch` for `allocationID`.
+     * An amount of `tokens` get unallocated from `subgraphDeploymentID`.
      * The `effectiveAllocation` are the tokens allocated from creation to settlement.
      */
     event AllocationSettled(
@@ -707,49 +707,42 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
      * @dev Allocate available tokens to a subgraph deployment.
      * @param _subgraphDeploymentID ID of the SubgraphDeployment where tokens will be allocated
      * @param _tokens Amount of tokens to allocate
-     * @param _channelPubKey The public key used by the indexer to setup the off-chain channel
-     * @param _channelProxy Address of the multisig proxy used to hold channel funds
+     * @param _channelPubKey The public key used to route payments
+     * @param _authSender Authorized sender address of collected funds
      * @param _price Price the `indexer` will charge for serving queries of the `subgraphDeploymentID`
      */
     function allocate(
         bytes32 _subgraphDeploymentID,
         uint256 _tokens,
         bytes calldata _channelPubKey,
-        address _channelProxy,
+        address _authSender,
         uint256 _price
     ) external override {
         require(_onlyAuth(msg.sender), "Allocation: caller must be authorized");
 
-        _allocate(
-            msg.sender,
-            _subgraphDeploymentID,
-            _tokens,
-            _channelPubKey,
-            _channelProxy,
-            _price
-        );
+        _allocate(msg.sender, _subgraphDeploymentID, _tokens, _channelPubKey, _authSender, _price);
     }
 
     /**
      * @dev Allocate available tokens to a subgraph deployment.
      * @param _indexer Indexer address to allocate funds from.
      * @param _subgraphDeploymentID ID of the SubgraphDeployment where tokens will be allocated
      * @param _tokens Amount of tokens to allocate
-     * @param _channelPubKey The public key used by the indexer to setup the off-chain channel
-     * @param _channelProxy Address of the multisig proxy used to hold channel funds
+     * @param _channelPubKey The public key used to route payments
+     * @param _authSender Authorized sender address of collected funds
      * @param _price Price the `indexer` will charge for serving queries of the `subgraphDeploymentID`
      */
     function allocateFrom(
         address _indexer,
         bytes32 _subgraphDeploymentID,
         uint256 _tokens,
         bytes calldata _channelPubKey,
-        address _channelProxy,
+        address _authSender,
         uint256 _price
     ) external override {
         require(_onlyAuth(_indexer), "Allocation: caller must be authorized");
 
-        _allocate(_indexer, _subgraphDeploymentID, _tokens, _channelPubKey, _channelProxy, _price);
+        _allocate(_indexer, _subgraphDeploymentID, _tokens, _channelPubKey, _authSender, _price);
     }
 
     /**
@@ -817,16 +810,13 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
         // Allocation identifier validation
         require(_allocationID != address(0), "Collect: invalid allocation");
 
-        // The contract caller must be a channel proxy registered during allocation
-        require(
-            alloc.channelProxy == msg.sender,
-            "Collect: caller is not related to the allocation"
-        );
+        // The contract caller must be an authorized sender registered on allocate()
+        require(alloc.authSender == msg.sender, "Collect: caller is not authorized");
 
-        // Transfer tokens to collect from multisig to this contract
+        // Transfer tokens to collect from the authorized sender
         require(
             token.transferFrom(msg.sender, address(this), _tokens),
-            "Collect: cannot transfer tokens to settle"
+            "Collect: cannot transfer tokens to collect"
         );
 
         _collect(_allocationID, msg.sender, _tokens);
@@ -875,7 +865,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
         alloc.settledAtEpoch = 0;
         alloc.collectedFees = 0;
         alloc.effectiveAllocation = 0;
-        alloc.channelProxy = address(0); // This avoid collect() to be called
+        alloc.authSender = address(0); // This avoid collect() to be called
 
         // When there are tokens to claim from the rebate pool, transfer or restake
         if (tokensToClaim > 0) {
@@ -931,15 +921,15 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
      * @param _subgraphDeploymentID ID of the SubgraphDeployment where tokens will be allocated
      * @param _tokens Amount of tokens to allocate
      * @param _channelPubKey The public key used by the indexer to setup the off-chain channel
-     * @param _channelProxy Address of the multisig proxy used to hold channel funds
+     * @param _authSender Authorized sender address of collected funds
      * @param _price Price the `indexer` will charge for serving queries of the `subgraphDeploymentID`
      */
     function _allocate(
         address _indexer,
         bytes32 _subgraphDeploymentID,
         uint256 _tokens,
         bytes memory _channelPubKey,
-        address _channelProxy,
+        address _authSender,
         uint256 _price
     ) private {
         Stakes.Indexer storage indexerStake = stakes[_indexer];
@@ -960,9 +950,8 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
         );
 
         // A channel public key is derived by the indexer when creating the offchain payment channel.
-        // Get the Ethereum address from the public key and use as channel identifier.
-        // The channel identifier is the address of the indexer signing party of a multisig that
-        // will hold the funds received when the channel is settled.
+        // Get the Ethereum address from the public key and use as allocation identifier.
+        // The allocationID will work to identify collected funds related to this allocation.
         address allocationID = address(uint256(keccak256(_sliceByte(bytes(_channelPubKey)))));
 
         // Cannot reuse an allocationID that has already been used in an allocation
@@ -973,17 +962,16 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
 
         // Creates an allocation
         // Allocation identifiers are not reused
-        // The channel proxy address is the contract that will send tokens to be collected to
-        // this contract
+        // The authorized sender address can send collected funds to the allocation
         allocations[allocationID] = Allocation(
             _indexer,
             _subgraphDeploymentID,
             _tokens, // Tokens allocated
             epochManager.currentEpoch(), // createdAtEpoch
             0, // settledAtEpoch
-            0, // Initialize with zero collected fees
+            0, // Initialize collected fees
             0, // Initialize effective allocation
-            _channelProxy // Source address of allocation collected funds
+            _authSender // Source address for allocation collected funds
         );
 
         // Mark allocated tokens as used
@@ -997,7 +985,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking, Governed {
             allocationID,
             _channelPubKey,
             _price,
-            _channelProxy
+            _authSender
         );
     }
 

test/staking/allocation.test.ts

@@ -44,7 +44,7 @@ describe('Staking:Allocation', () => {
   let governor: Account
   let indexer: Account
   let slasher: Account
-  let channelProxy: Account
+  let authSender: Account
 
   let fixture: NetworkFixture
 
@@ -68,11 +68,11 @@ describe('Staking:Allocation', () => {
   const allocate = (tokens: BigNumber) => {
     return staking
       .connect(indexer.signer)
-      .allocate(subgraphDeploymentID, tokens, channelPubKey, channelProxy.address, price)
+      .allocate(subgraphDeploymentID, tokens, channelPubKey, authSender.address, price)
   }
 
   before(async function () {
-    ;[me, other, governor, indexer, slasher, channelProxy] = await getAccounts()
+    ;[me, other, governor, indexer, slasher, authSender] = await getAccounts()
 
     fixture = new NetworkFixture()
     ;({ curation, epochManager, grt, staking } = await fixture.load(
@@ -150,7 +150,7 @@ describe('Staking:Allocation', () => {
           channelID,
           channelPubKey,
           price,
-          channelProxy.address,
+          authSender.address,
         )
 
       // After state
@@ -167,7 +167,7 @@ describe('Staking:Allocation', () => {
       expect(afterAlloc.collectedFees).eq(toGRT('0'))
       expect(afterAlloc.settledAtEpoch).eq(toBN('0'))
       expect(afterAlloc.effectiveAllocation).eq(toGRT('0'))
-      expect(afterAlloc.channelProxy).eq(channelProxy.address)
+      expect(afterAlloc.authSender).eq(authSender.address)
     }
 
     it('reject allocate zero tokens', async function () {
@@ -184,7 +184,7 @@ describe('Staking:Allocation', () => {
           subgraphDeploymentID,
           tokensToAllocate,
           invalidChannelPubKey,
-          channelProxy.address,
+          authSender.address,
           price,
         )
       await expect(tx).revertedWith('Allocation: invalid channel public key')
@@ -220,7 +220,7 @@ describe('Staking:Allocation', () => {
             subgraphDeploymentID,
             tokensToAllocate,
             channelPubKey,
-            channelProxy.address,
+            authSender.address,
             price,
           )
         await expect(tx1).revertedWith('Allocation: caller must be authorized')
@@ -234,7 +234,7 @@ describe('Staking:Allocation', () => {
             subgraphDeploymentID,
             tokensToAllocate,
             channelPubKey,
-            channelProxy.address,
+            authSender.address,
             price,
           )
       })
@@ -273,7 +273,7 @@ describe('Staking:Allocation', () => {
       rebateFees = rebateFees.sub(curationFees)
 
       // Collect tokens from channel
-      const tx = staking.connect(channelProxy.signer).collect(tokensToCollect, channelID)
+      const tx = staking.connect(authSender.signer).collect(tokensToCollect, channelID)
       await expect(tx)
         .emit(staking, 'AllocationCollected')
         .withArgs(
@@ -282,7 +282,7 @@ describe('Staking:Allocation', () => {
           await epochManager.currentEpoch(),
           tokensToCollect,
           channelID,
-          channelProxy.address,
+          authSender.address,
           curationFees,
           rebateFees,
         )
@@ -310,8 +310,8 @@ describe('Staking:Allocation', () => {
 
       // Fund channel wallet
       const tokensToFund = toGRT('100000')
-      await grt.connect(governor.signer).mint(channelProxy.address, tokensToFund)
-      await grt.connect(channelProxy.signer).approve(staking.address, tokensToFund)
+      await grt.connect(governor.signer).mint(authSender.address, tokensToFund)
+      await grt.connect(authSender.signer).approve(staking.address, tokensToFund)
     })
 
     it('reject collect if invalid channel', async function () {
@@ -384,15 +384,15 @@ describe('Staking:Allocation', () => {
       await staking.connect(indexer.signer).settle(channelID)
 
       // Collect fees into the channel
-      const tx1 = staking.connect(channelProxy.signer).collect(tokensToCollect, channelID)
+      const tx1 = staking.connect(authSender.signer).collect(tokensToCollect, channelID)
       await tx1
 
       // Advance blocks to get channel in epoch where it can no longer collect funds (finalized)
       await advanceToNextEpoch(epochManager)
 
       // Revert if channel is finalized
       expect(await staking.getAllocationState(channelID)).eq(AllocationState.Finalized)
-      const tx2 = staking.connect(channelProxy.signer).collect(tokensToCollect, channelID)
+      const tx2 = staking.connect(authSender.signer).collect(tokensToCollect, channelID)
       await expect(tx2).revertedWith('Collect: channel must be active or settled')
     })
   })
@@ -560,7 +560,7 @@ describe('Staking:Allocation', () => {
       expect(afterAlloc.settledAtEpoch).eq(toGRT('0'))
       expect(afterAlloc.collectedFees).eq(toGRT('0'))
       expect(afterAlloc.effectiveAllocation).eq(toGRT('0'))
-      expect(afterAlloc.channelProxy).eq(AddressZero)
+      expect(afterAlloc.authSender).eq(AddressZero)
       // Rebate updated
       expect(afterRebatePool.settlementsCount).eq(beforeRebatePool.settlementsCount.sub(toBN('1')))
       if (afterRebatePool.settlementsCount.eq(toBN('0'))) {
@@ -583,8 +583,8 @@ describe('Staking:Allocation', () => {
       await staking.connect(governor.signer).setChannelDisputeEpochs(toBN('1'))
 
       // Fund wallets
-      await grt.connect(governor.signer).mint(channelProxy.address, tokensToCollect)
-      await grt.connect(channelProxy.signer).approve(staking.address, tokensToCollect)
+      await grt.connect(governor.signer).mint(authSender.address, tokensToCollect)
+      await grt.connect(authSender.signer).approve(staking.address, tokensToCollect)
     })
 
     it('reject claim for non-existing channel allocation', async function () {
@@ -603,7 +603,7 @@ describe('Staking:Allocation', () => {
     context('> when settled', function () {
       beforeEach(async function () {
         // Collect some funds
-        await staking.connect(channelProxy.signer).collect(tokensToCollect, channelID)
+        await staking.connect(authSender.signer).collect(tokensToCollect, channelID)
 
         // Advance blocks to get the channel in epoch where it can be settled
         await advanceToNextEpoch(epochManager)