Merge branch '63-implement-stake-withdrawal' into 'main'

Resolve "Implement stake withdrawal for UTT endorsements"

Closes #63

See merge request ututrust/utu-trust-token-solidity!62

Author: databu

.env.example

@@ -1,7 +1,7 @@
 # Default network to work on; can be overridden with --network param
 HARDHAT_NETWORK="testnet_ethereum" 
 
-ETHERSCAN_API_KEY=<Etherscan API Key> 
+ETHERSCAN_API_KEY=<Etherscan API Key>
 
 TESTNET_ETHEREUM_URL=<ETHEREUM testnet (Sepolia) node URL>
 
@@ -21,4 +21,4 @@ TESTNET_LISK_URL=<Lisk testnet node URL>
 LISK_URL=<Lisk mainnet node URL>
 
 TESTNET_BASE_URL=<Base testnet node URL>
-BASE_URL=<Base mainnet node URL>
+BASE_URL=<Base mainnet node URL>

contracts/Endorsement.sol

@@ -232,6 +232,42 @@ abstract contract Endorsement is
         _triggerEndorse(msg.sender, target, amount, transactionId);
     }
 
+    function _withdrawStake(
+        address source,
+        address target,
+        uint256 amount,
+        string memory transactionId
+    ) internal {
+        require(amount > 0, "UTT: withdraw amount must be greater than zero");
+
+        uint256 currentStake = previousEndorserStakes[target][source];
+        require(currentStake >= amount, "UTT: withdraw amount exceeds stake");
+        require(
+            totalStake[target] >= amount,
+            "UTT: withdraw amount exceeds total stake"
+        );
+
+        previousEndorserStakes[target][source] = currentStake - amount;
+        totalStake[target] -= amount;
+
+        _mint(source, amount);
+
+        emit WithdrawStake(source, target, amount, transactionId);
+    }
+
+    /**
+     * @inheritdoc EndorsementInterface
+     */
+    function withdrawStake(
+        address target,
+        uint256 amount,
+        string memory transactionId
+    ) public override virtual {
+        require(msg.sender == tx.origin, "should be a user");
+
+        _withdrawStake(msg.sender, target, amount, transactionId);
+    }
+
     /**
      * @dev This is called via oracle to forward an endorse call from a proxy contract. The caller must have the
      *      PROXY_ENDORSER_ROLE.

contracts/EndorsementInterface.sol

@@ -24,6 +24,20 @@ interface EndorsementInterface {
         string memory transactionId
     ) external;
 
+    /**
+     * @notice Reduces or removes part of the caller's existing staked endorsement for a target.
+     *         A WithdrawStake event is emitted once the stake is withdrawn.
+     * @param target the endorsed entity (address is just used as an id here)
+     * @param amount the stake amount to withdraw
+     * @param transactionId an id representing the "business transaction" for which the stake withdrawal was made; this is
+     *        _not_ necessarily an Ethereum transaction id.
+     */
+    function withdrawStake(
+        address target,
+        uint256 amount,
+        string memory transactionId
+    ) external;
+
     // Events that might be emitted during the endorsement process.
 
     /** A new staked endorsement was created. */
@@ -34,6 +48,14 @@ interface EndorsementInterface {
         string _transactionId
     );
 
+    /** Existing staked endorsement was reduced or removed. */
+    event WithdrawStake(
+        address indexed _from,
+        address indexed _to,
+        uint256 _value,
+        string _transactionId
+    );
+
     /** A first-level previous endorser was rewarded */
     event RewardPreviousEndorserLevel1(address endorser, uint256 reward);
 

contracts/MigratableEndorsement.sol

@@ -52,6 +52,14 @@ abstract contract MigratableEndorsement is Migratable, Endorsement {
         super.endorse(target, amount, transactionId);
     }
 
+    function withdrawStake(
+        address target,
+        uint256 amount,
+        string memory transactionId
+    ) public virtual override onlyNotMigrating {
+        super.withdrawStake(target, amount, transactionId);
+    }
+
     function proxyEndorse(
         address source,
         address target,

contracts/MigratableReward.sol

@@ -117,6 +117,19 @@ contract MigratableReward is
         super.endorse(target, amount, transactionId);
     }
 
+    function withdrawStake(
+        address target,
+        uint256 amount,
+        string memory transactionId
+    )
+        public
+        virtual
+        override(Endorsement, MigratableEndorsement)
+        onlyNotMigrating
+    {
+        super.withdrawStake(target, amount, transactionId);
+    }
+
     function proxyEndorse(
         address source,
         address target,

contracts/UTTProxy.sol

@@ -126,6 +126,14 @@ contract UTTProxy is Initializable, OwnableUpgradeable, ChainlinkClient, Endorse
         });
     }
 
+    function withdrawStake(
+        address,
+        uint256,
+        string memory
+    ) external pure override {
+        revert("UTTProxy: withdrawStake not supported");
+    }
+
     function fulfill(
         bytes32 _requestId
     ) external recordChainlinkFulfillment(_requestId) {

hardhat.config.ts

@@ -194,10 +194,10 @@ const config = {
       testnet_aurora: process.env.AURORA_ETHERSCAN_API_KEY,
       optimism: process.env.OPTIMISM_ETHERSCAN_API_KEY,
       testnet_optimism: process.env.OPTIMISM_ETHERSCAN_API_KEY,
-      lisk: null, // lisk's blockscout currently doesn't require one 
+      lisk: null, // lisk's blockscout currently doesn't require one
       testnet_lisk: null, // lisk's blockscout currently doesn't require one
-      base: null, 
-      testnet_base: null 
+      base: null,
+      testnet_base: null
     },
     customChains: [
       {

scripts/upgrade.args.testnet_polygon.js

@@ -0,0 +1,4 @@
+
+module.exports = [
+  "0xCa5cD80157334dAc231B65d886467B036CDf0024", // UTT token address
+];

scripts/upgrade.ts

@@ -21,8 +21,11 @@ async function upgradeUTT() {
 
   await utt.waitForDeployment();
   const uttAddress = await utt.getAddress();
+  const implementationAddress =
+    await upgrades.erc1967.getImplementationAddress(uttAddress);
 
   console.log("UTT upgraded to:", uttAddress);
+  console.log("Implementation at:", implementationAddress);
 }
 
 // We recommend this pattern to be able to use async/await everywhere

test/UTT.test.ts

@@ -236,6 +236,168 @@ describe("UTT", function () {
     });
   });
 
+  describe("Stake withdrawal", function () {
+    async function deployWithUserStake(stakeAmount = 1000) {
+      const fixture = await loadFixture(deployUTT);
+      const { utt, mockOperator, user1, service1, connector } = fixture;
+
+      await addConnection(utt, connector, user1.address);
+      await endorse(
+        utt,
+        mockOperator,
+        user1,
+        service1.address,
+        stakeAmount,
+        mockTransactionId,
+        [],
+        []
+      );
+
+      return fixture;
+    }
+
+    async function deployWithClaimableRewards() {
+      const fixture = await loadFixture(deployUTT);
+      const { utt, mockOperator, admin, user1, service1, connector } =
+        fixture;
+
+      await addConnection(utt, connector, user1.address);
+      await endorse(
+        utt,
+        mockOperator,
+        user1,
+        service1.address,
+        200,
+        mockTransactionId,
+        [],
+        []
+      );
+      await endorse(
+        utt,
+        mockOperator,
+        admin,
+        service1.address,
+        200,
+        mockTransactionId,
+        [user1.address],
+        []
+      );
+
+      return fixture;
+    }
+
+    it("should allow a user to withdraw part of their stake", async function () {
+      const { utt, user1, service1 } = await deployWithUserStake();
+      const balanceBefore = await utt.balanceOf(user1.address);
+      const stakeBefore = await utt.previousEndorserStakes(
+        service1.address,
+        user1.address
+      );
+      const totalStakeBefore = await utt.totalStake(service1.address);
+
+      const withdrawP = utt
+        .connect(user1)
+        .withdrawStake(service1.address, 400, mockTransactionId);
+
+      await expect(withdrawP)
+        .to.emit(utt, "WithdrawStake")
+        .withArgs(user1.address, service1.address, 400, mockTransactionId);
+      expect(await utt.balanceOf(user1.address)).to.eq(balanceBefore + 400n);
+      expect(
+        await utt.previousEndorserStakes(service1.address, user1.address)
+      ).to.eq(stakeBefore - 400n);
+      expect(await utt.totalStake(service1.address)).to.eq(
+        totalStakeBefore - 400n
+      );
+    });
+
+    it("should allow a user to withdraw all of their stake", async function () {
+      const { utt, user1, service1 } = await deployWithUserStake();
+
+      await utt
+        .connect(user1)
+        .withdrawStake(service1.address, 1000, mockTransactionId);
+
+      expect(
+        await utt.previousEndorserStakes(service1.address, user1.address)
+      ).to.eq(0);
+      expect(await utt.totalStake(service1.address)).to.eq(0);
+    });
+
+    it("should revert when withdrawing an invalid amount", async function () {
+      const { utt, user1, service1 } = await deployWithUserStake();
+
+      await expect(
+        utt.connect(user1).withdrawStake(service1.address, 0, mockTransactionId)
+      ).to.be.revertedWith("UTT: withdraw amount must be greater than zero");
+      await expect(
+        utt
+          .connect(user1)
+          .withdrawStake(service1.address, 1001, mockTransactionId)
+      ).to.be.revertedWith("UTT: withdraw amount exceeds stake");
+    });
+
+    it("should revert when withdrawing stake for a target the user never endorsed", async function () {
+      const { utt, user1, service1 } = await loadFixture(deployUTT);
+
+      await expect(
+        utt.connect(user1).withdrawStake(service1.address, 1, mockTransactionId)
+      ).to.be.revertedWith("UTT: withdraw amount exceeds stake");
+    });
+
+    it("should not emit reward events", async function () {
+      const { utt, user1, service1 } = await deployWithUserStake();
+
+      const withdrawP = utt
+        .connect(user1)
+        .withdrawStake(service1.address, 250, mockTransactionId);
+
+      await expect(withdrawP)
+        .to.not.emit(utt, "RewardPreviousEndorserLevel1")
+        .to.not.emit(utt, "RewardPreviousEndorserLevel2")
+        .to.not.emit(utt, "RewardUTUCoin");
+    });
+
+    it("should not change claimable UTU Coin", async function () {
+      const { utt, user1, service1 } = await deployWithClaimableRewards();
+      const claimableBefore = await utt.claimableUTUCoin(user1.address);
+      const totalClaimableBefore = await utt.totalClaimableUTUCoin();
+      expect(claimableBefore).to.be.gt(0);
+      expect(totalClaimableBefore).to.be.gt(0);
+
+      await utt
+        .connect(user1)
+        .withdrawStake(service1.address, 50, mockTransactionId);
+
+      expect(await utt.claimableUTUCoin(user1.address)).to.eq(claimableBefore);
+      expect(await utt.totalClaimableUTUCoin()).to.eq(totalClaimableBefore);
+    });
+
+    it("should block stake withdrawal while migration is active", async function () {
+      const { utt, admin, user1, service1 } = await deployWithUserStake();
+
+      await utt.connect(admin).startMigrationToNewContract();
+
+      await expect(
+        utt
+          .connect(user1)
+          .withdrawStake(service1.address, 250, mockTransactionId)
+      ).to.be.revertedWith("Contract is migrating");
+    });
+
+    it("should revert stake withdrawal while the contract is paused", async function () {
+      const { utt, admin, user1, service1 } = await deployWithUserStake();
+
+      await utt.connect(admin).pause();
+
+      await expect(
+        utt
+          .connect(user1)
+          .withdrawStake(service1.address, 250, mockTransactionId)
+      ).to.be.reverted;
+    });
+  });
+
   describe("User tries to addConnection", function () {
     it("should not allow a user to add a connection by themselves", async function () {
       const { utt, user1 } = await loadFixture(deployUTT);