chore(protocol-contracts): improve staking tasks (#1776)

Author: melanciani

protocol-contracts/staking/.env.example

@@ -18,8 +18,8 @@ DAO_ADDRESS=0x70997970C51812dc3A010C7d01b50e0d17dc79C8 # accounts[1] (address)
 # ----------------------------------------------------------------------------
 # Coprocessor
 # ----------------------------------------------------------------------------
-PROTOCOL_STAKING_COPRO_TOKEN_NAME=ProtocolStakingCoprocessors
-PROTOCOL_STAKING_COPRO_TOKEN_SYMBOL=stZAMAcoprocessors
+PROTOCOL_STAKING_COPRO_TOKEN_NAME="Staked ZAMA (Coprocessor)"
+PROTOCOL_STAKING_COPRO_TOKEN_SYMBOL=stZAMA-Coprocessor
 PROTOCOL_STAKING_COPRO_VERSION=1
 
 # Cooldown period in seconds before unstaked tokens can be released
@@ -32,8 +32,8 @@ PROTOCOL_STAKING_COPRO_REWARD_RATE=10000000000000000
 # ----------------------------------------------------------------------------
 # KMS
 # ----------------------------------------------------------------------------
-PROTOCOL_STAKING_KMS_TOKEN_NAME=ProtocolStakingKMS
-PROTOCOL_STAKING_KMS_TOKEN_SYMBOL=stZAMAkms
+PROTOCOL_STAKING_KMS_TOKEN_NAME="Staked ZAMA (KMS)"
+PROTOCOL_STAKING_KMS_TOKEN_SYMBOL=stZAMA-KMS
 PROTOCOL_STAKING_KMS_VERSION=1
 
 # Cooldown period in seconds before unstaked tokens can be released
@@ -52,9 +52,10 @@ PROTOCOL_STAKING_KMS_REWARD_RATE=10000000000000000
 # The number of OperatorStaking for coprocessors must be equal to the number of addresses defined below
 NUM_OPERATOR_STAKING_COPRO=2
 
+# ----------------------------------------------------------------------------
 # OperatorStaking coprocessor 1
-OPERATOR_STAKING_COPRO_TOKEN_NAME_0="OperatorStakingCopro1"
-OPERATOR_STAKING_COPRO_TOKEN_SYMBOL_0="stZAMAcopro1"
+OPERATOR_STAKING_COPRO_TOKEN_NAME_0="Zama1 Staked ZAMA (Coprocessor)"
+OPERATOR_STAKING_COPRO_TOKEN_SYMBOL_0="stZAMA-Zama1-Coprocessor"
 
 # Initial assets (in the smallest unit of $ZAMA, using 10^18 decimals) and receiver
 OPERATOR_STAKING_COPRO_INITIAL_DEPOSIT_ASSETS_0=100000000000000000000000
@@ -68,9 +69,10 @@ OPERATOR_REWARDER_COPRO_BENEFICIARY_0="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb9226
 OPERATOR_REWARDER_COPRO_MAX_FEE_0=2000
 OPERATOR_REWARDER_COPRO_FEE_0=2000
 
+# ----------------------------------------------------------------------------
 # OperatorStaking coprocessor 2
-OPERATOR_STAKING_COPRO_TOKEN_NAME_1="OperatorStakingCopro2"
-OPERATOR_STAKING_COPRO_TOKEN_SYMBOL_1="stZAMAcopro2"
+OPERATOR_STAKING_COPRO_TOKEN_NAME_1="Zama2 Staked ZAMA (Coprocessor)"
+OPERATOR_STAKING_COPRO_TOKEN_SYMBOL_1="stZAMA-Zama2-Coprocessor"
 
 # Initial assets (in the smallest unit of $ZAMA, using 10^18 decimals) and receiver
 OPERATOR_STAKING_COPRO_INITIAL_DEPOSIT_ASSETS_1=250000000000000000000000
@@ -90,9 +92,10 @@ OPERATOR_REWARDER_COPRO_FEE_1=1000
 # The number of OperatorStaking for KMS must be equal to the number of addresses defined below
 NUM_OPERATOR_STAKING_KMS=3
 
+# ----------------------------------------------------------------------------
 # OperatorStaking KMS 1
-OPERATOR_STAKING_KMS_TOKEN_NAME_0="OperatorStakingKms1"
-OPERATOR_STAKING_KMS_TOKEN_SYMBOL_0="stZAMAkms1"
+OPERATOR_STAKING_KMS_TOKEN_NAME_0="Zama1 Staked ZAMA (KMS)"
+OPERATOR_STAKING_KMS_TOKEN_SYMBOL_0="stZAMA-Zama1-KMS"
 
 # Initial assets (in the smallest unit of $ZAMA, using 10^18 decimals) and receiver
 OPERATOR_STAKING_KMS_INITIAL_DEPOSIT_ASSETS_0=500000000000000000000000
@@ -106,9 +109,10 @@ OPERATOR_REWARDER_KMS_BENEFICIARY_0="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
 OPERATOR_REWARDER_KMS_MAX_FEE_0=2000
 OPERATOR_REWARDER_KMS_FEE_0=1500
 
+# ----------------------------------------------------------------------------
 # OperatorStaking KMS 2
-OPERATOR_STAKING_KMS_TOKEN_NAME_1="OperatorStakingKms2"
-OPERATOR_STAKING_KMS_TOKEN_SYMBOL_1="stZAMAkms2"
+OPERATOR_STAKING_KMS_TOKEN_NAME_1="Zama2 Staked ZAMA (KMS)"
+OPERATOR_STAKING_KMS_TOKEN_SYMBOL_1="stZAMA-Zama2-KMS"
 
 # Initial assets (in the smallest unit of $ZAMA, using 10^18 decimals) and receiver
 OPERATOR_STAKING_KMS_INITIAL_DEPOSIT_ASSETS_1=750000000000000000000000
@@ -122,9 +126,10 @@ OPERATOR_REWARDER_KMS_BENEFICIARY_1="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
 OPERATOR_REWARDER_KMS_MAX_FEE_1=2000
 OPERATOR_REWARDER_KMS_FEE_1=1000
 
+# ----------------------------------------------------------------------------
 # OperatorStaking KMS 3
-OPERATOR_STAKING_KMS_TOKEN_NAME_2="OperatorStakingKms3"
-OPERATOR_STAKING_KMS_TOKEN_SYMBOL_2="stZAMAkms3"
+OPERATOR_STAKING_KMS_TOKEN_NAME_2="Zama3 Staked ZAMA (KMS)"
+OPERATOR_STAKING_KMS_TOKEN_SYMBOL_2="stZAMA-Zama3-KMS"
 
 # Initial assets (in the smallest unit of $ZAMA, using 10^18 decimals) and receiver
 OPERATOR_STAKING_KMS_INITIAL_DEPOSIT_ASSETS_2=1000000000000000000000000

protocol-contracts/staking/APY.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 7,
    "id": "df0d74f3-487b-4f31-9750-fd9f7d572932",
    "metadata": {},
    "outputs": [],
@@ -12,12 +12,89 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 8,
    "id": "4cd2e6ad-55c0-431c-971c-9a9208904f5c",
    "metadata": {},
    "outputs": [],
    "source": [
-    "SECONDS_PER_YEAR = 365 * 24 * 60 * 60"
+    "SECONDS_PER_YEAR = 365 * 24 * 60 * 60\n",
+    "\n",
+    "TOTAL_YEARLY_INFLATION_PROPORTION = 0.05\n",
+    "TOTAL_SUPPLY = 11_000_000_000 * 10**18"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "dea5a1cb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def get_reward_rate() -> tuple[int, int]:\n",
+    "    \"\"\"\n",
+    "    Compute the reward rates for KMS and Coprocessors based on total supply.\n",
+    "    \n",
+    "    Let totalFeesRewards be the total yearly fees and rewards (i.e. TOTAL_YEARLY_INFLATION_PROPORTION % of current total supply)\n",
+    "    Divide totalFeesRewards into totalFeesRewardsKMS (60%) and totalFeesRewardsCoprocessors (40%)\n",
+    "    Let rateKMS = totalFeesRewardsKMS / SECONDS_PER_YEAR\n",
+    "    Let rateCoprocessors = totalFeesRewardsCoprocessors / SECONDS_PER_YEAR\n",
+    "    \n",
+    "    :return: A tuple (rateKMS, rateCoprocessors) in tokens per second (with 18 decimals)\n",
+    "    \"\"\"\n",
+    "    # Calculate the total yearly fees and rewards\n",
+    "    total_fees_rewards = int(TOTAL_SUPPLY * TOTAL_YEARLY_INFLATION_PROPORTION)\n",
+    "    \n",
+    "    # Divide into KMS (60%) and Coprocessors (40%)\n",
+    "    total_fees_rewards_kms = int(total_fees_rewards * 0.60)\n",
+    "    total_fees_rewards_coprocessors = int(total_fees_rewards * 0.40)\n",
+    "    \n",
+    "    # Calculate the per-second rates\n",
+    "    rate_kms = total_fees_rewards_kms // SECONDS_PER_YEAR\n",
+    "    rate_coprocessors = total_fees_rewards_coprocessors // SECONDS_PER_YEAR\n",
+    "    \n",
+    "    return rate_kms, rate_coprocessors"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "0baefc2f",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Total Supply: 11,000,000,000 tokens\n",
+      "Total Yearly Rewards (5.0%): 550,000,000 tokens\n",
+      "  - KMS (60%): 330,000,000 tokens/year\n",
+      "  - Coprocessors (40%): 220,000,000 tokens/year\n",
+      "\n",
+      "Per-Second Rates (raw value with 18 decimals):\n",
+      "  - rateKMS: 10464231354642313336\n",
+      "  - rateCoprocessors: 6976154236428209254\n",
+      "\n",
+      "Per-Second Rates (in tokens):\n",
+      "  - rateKMS: 10.46 tokens/second\n",
+      "  - rateCoprocessors: 6.98 tokens/second\n"
+     ]
+    }
+   ],
+   "source": [
+    "rate_kms, rate_coprocessors = get_reward_rate()\n",
+    "\n",
+    "print(f\"Total Supply: {TOTAL_SUPPLY / 10**18:,.0f} tokens\")\n",
+    "print(f\"Total Yearly Rewards ({TOTAL_YEARLY_INFLATION_PROPORTION * 100}%): {TOTAL_SUPPLY * TOTAL_YEARLY_INFLATION_PROPORTION / 10**18:,.0f} tokens\")\n",
+    "print(f\"  - KMS (60%): {TOTAL_SUPPLY * TOTAL_YEARLY_INFLATION_PROPORTION * 0.60 / 10**18:,.0f} tokens/year\")\n",
+    "print(f\"  - Coprocessors (40%): {TOTAL_SUPPLY * TOTAL_YEARLY_INFLATION_PROPORTION * 0.40 / 10**18:,.0f} tokens/year\")\n",
+    "print()\n",
+    "print(f\"Per-Second Rates (raw value with 18 decimals):\")\n",
+    "print(f\"  - rateKMS: {rate_kms}\")\n",
+    "print(f\"  - rateCoprocessors: {rate_coprocessors}\")\n",
+    "print()\n",
+    "print(f\"Per-Second Rates (in tokens):\")\n",
+    "print(f\"  - rateKMS: {rate_kms / 10**18:.2f} tokens/second\")\n",
+    "print(f\"  - rateCoprocessors: {rate_coprocessors / 10**18:.2f} tokens/second\")\n"
    ]
   },
   {

protocol-contracts/staking/Makefile

@@ -5,6 +5,10 @@ ENV_PATH=.env.example
 prettier:
 	npx prettier . --write
 
+lint:
+	npm run lint:sol:fix
+	npm run lint:js:fix
+
 compile:
 	npx hardhat compile
 
@@ -24,4 +28,4 @@ test-tasks: clean
 
 
 # Conform to pre-commit checks
-conformance: prettier
+conformance: prettier lint

protocol-contracts/staking/contracts/mocks/ERC20Mock.sol

@@ -6,6 +6,9 @@ import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20P
 
 contract ERC20Mock is ERC1363, ERC20Permit {
     uint8 private immutable _decimals;
+    uint256 public constant MAX_MINT_AMOUNT_TOKENS = 1_000_000;
+
+    error MintAmountExceedsMax(uint256 amount, uint256 maxAmount);
 
     constructor(string memory name_, string memory symbol_, uint8 decimals_) ERC20(name_, symbol_) ERC20Permit(name_) {
         _decimals = decimals_;
@@ -16,6 +19,10 @@ contract ERC20Mock is ERC1363, ERC20Permit {
     }
 
     function mint(address to, uint256 amount) public virtual {
+        uint256 maxMintAmount = MAX_MINT_AMOUNT_TOKENS * 10 ** _decimals;
+        if (amount > maxMintAmount) {
+            revert MintAmountExceedsMax(amount, maxMintAmount);
+        }
         _mint(to, amount);
     }
 }

protocol-contracts/staking/tasks/deployment/mocks/ERC20Mock.ts

@@ -1,6 +1,11 @@
 import { task } from 'hardhat/config';
 import { HardhatRuntimeEnvironment } from 'hardhat/types';
 
+export const ERC20_MOCK_CONTRACT_NAME = 'ERC20Mock';
+export const ERC20_MOCK_TOKEN_NAME = 'ZamaMock';
+export const ERC20_MOCK_TOKEN_SYMBOL = 'ZAMAMock';
+export const ERC20_MOCK_TOKEN_DECIMALS = 18;
+
 // Deploy an ERC20Mock contract
 async function deployERC20MockAndMint(
   tokenName: string,
@@ -15,10 +20,8 @@ async function deployERC20MockAndMint(
   const { deployer } = await getNamedAccounts();
   const deployerSigner = await ethers.getSigner(deployer);
 
-  const contractName = 'ERC20Mock';
-
   // Get the contract factory and deploy the ERC20Mock contract
-  const erc20MockFactory = await ethers.getContractFactory(contractName, deployerSigner);
+  const erc20MockFactory = await ethers.getContractFactory(ERC20_MOCK_CONTRACT_NAME, deployerSigner);
   const erc20Mock = await erc20MockFactory.deploy(tokenName, symbol, decimals);
   await erc20Mock.waitForDeployment();
 
@@ -38,15 +41,15 @@ async function deployERC20MockAndMint(
     ].join('\n'),
   );
 
-  // Mint the deployer account with 1 billion tokens
-  const amount = BigInt(10 ** 9) * BigInt(10 ** decimals);
+  // Mint the deployer account with 1 million tokens
+  const amount = BigInt(10 ** 6) * BigInt(10 ** decimals);
   await erc20Mock.connect(deployerSigner).mint(deployer, amount);
 
   console.log(`👉 Minted ${amount} tokens to deployer account ${deployer}`);
 
   // Save the ERC20Mock contract artifact
-  const artifact = await getArtifact(contractName);
-  await save(contractName, { address: erc20MockAddress, abi: artifact.abi });
+  const artifact = await getArtifact(ERC20_MOCK_CONTRACT_NAME);
+  await save(ERC20_MOCK_CONTRACT_NAME, { address: erc20MockAddress, abi: artifact.abi });
 
   return erc20MockAddress;
 }
@@ -55,13 +58,9 @@ async function deployERC20MockAndMint(
 // Example usage:
 // npx hardhat task:deployERC20MockAndMintDeployer --network testnet
 task('task:deployERC20MockAndMintDeployer').setAction(async function (_, hre) {
-  const name = 'ZamaMock';
-  const symbol = 'ZAMAMock';
-  const decimals = 18;
-
-  console.log(`Deploying mocked ERC20 Zama token: ${name} (${symbol})...\n`);
+  console.log(`Deploying mocked ERC20 Zama token: ${ERC20_MOCK_TOKEN_NAME} (${ERC20_MOCK_TOKEN_SYMBOL})...\n`);
 
-  await deployERC20MockAndMint(name, symbol, decimals, hre);
+  await deployERC20MockAndMint(ERC20_MOCK_TOKEN_NAME, ERC20_MOCK_TOKEN_SYMBOL, ERC20_MOCK_TOKEN_DECIMALS, hre);
 
   console.log('Mocked ERC20 Zama token deployment complete\n');
 });

protocol-contracts/staking/tasks/deployment/mocks/index.ts

@@ -1 +1,2 @@
 export * from './ERC20Mock';
+export * from './verify';

protocol-contracts/staking/tasks/deployment/mocks/verify.ts

@@ -0,0 +1,18 @@
+import { ERC20_MOCK_TOKEN_NAME, ERC20_MOCK_TOKEN_SYMBOL, ERC20_MOCK_TOKEN_DECIMALS } from './ERC20Mock';
+import { task, types } from 'hardhat/config';
+
+// Verify a mock ERC20 contract
+// Example usage:
+// npx hardhat task:verifyERC20Mock --contract-address 0x1234567890123456789012345678901234567890 --network testnet
+task('task:verifyERC20Mock')
+  .addParam('contractAddress', 'The address of the ERC20Mock contract to verify', '', types.string)
+  .setAction(async function ({ contractAddress }, hre) {
+    const { run } = hre;
+
+    console.log(`Verifying ERC20Mock contract at ${contractAddress}...\n`);
+    await run('verify:verify', {
+      address: contractAddress,
+      constructorArguments: [ERC20_MOCK_TOKEN_NAME, ERC20_MOCK_TOKEN_SYMBOL, ERC20_MOCK_TOKEN_DECIMALS],
+    });
+    console.log(`ERC20Mock contract verification complete\n`);
+  });

protocol-contracts/staking/tasks/deposit.ts

@@ -70,14 +70,17 @@ task('task:depositOperatorStakingFromDeployer')
     );
   });
 
+// Deposit assets into all coprocessor operator staking contracts from the deployer account
+// Example usage:
+// npx hardhat task:depositAllCoproOperatorStakingFromDeployer --network testnet
 task('task:depositAllCoproOperatorStakingFromDeployer').setAction(async function (_, hre: HardhatRuntimeEnvironment) {
   console.log('Depositing assets into all coprocessor operator staking contracts from the deployer account...\n');
 
   // Get the addresses of all coprocessor operator staking contracts
   const operatorStakingAddresses = await getAllOperatorStakingCoproAddresses(hre);
 
   for (let i = 0; i < operatorStakingAddresses.length; i++) {
-    const assets = BigInt(parseInt(getRequiredEnvVar(`OPERATOR_STAKING_COPRO_INITIAL_DEPOSIT_ASSETS_${i}`)));
+    const assets = BigInt(getRequiredEnvVar(`OPERATOR_STAKING_COPRO_INITIAL_DEPOSIT_ASSETS_${i}`));
     const receiver = getRequiredEnvVar(`OPERATOR_STAKING_COPRO_INITIAL_DEPOSIT_RECEIVER_${i}`);
 
     await hre.run('task:depositOperatorStakingFromDeployer', {
@@ -88,14 +91,17 @@ task('task:depositAllCoproOperatorStakingFromDeployer').setAction(async function
   }
 });
 
+// Deposit assets into all KMS operator staking contracts from the deployer account
+// Example usage:
+// npx hardhat task:depositAllKMSOperatorStakingFromDeployer --network testnet
 task('task:depositAllKMSOperatorStakingFromDeployer').setAction(async function (_, hre: HardhatRuntimeEnvironment) {
   console.log('Depositing assets into all KMS operator staking contracts from the deployer account...\n');
 
   // Get the addresses of all KMS operator staking contracts
   const operatorStakingAddresses = await getAllOperatorStakingKMSAddresses(hre);
 
   for (let i = 0; i < operatorStakingAddresses.length; i++) {
-    const assets = BigInt(parseInt(getRequiredEnvVar(`OPERATOR_STAKING_KMS_INITIAL_DEPOSIT_ASSETS_${i}`)));
+    const assets = BigInt(getRequiredEnvVar(`OPERATOR_STAKING_KMS_INITIAL_DEPOSIT_ASSETS_${i}`));
     const receiver = getRequiredEnvVar(`OPERATOR_STAKING_KMS_INITIAL_DEPOSIT_RECEIVER_${i}`);
 
     await hre.run('task:depositOperatorStakingFromDeployer', {
@@ -106,6 +112,9 @@ task('task:depositAllKMSOperatorStakingFromDeployer').setAction(async function (
   }
 });
 
+// Deposit assets into all operator staking contracts from the deployer account
+// Example usage:
+// npx hardhat task:depositAllOperatorStakingFromDeployer --network testnet
 task('task:depositAllOperatorStakingFromDeployer').setAction(async function (_, hre: HardhatRuntimeEnvironment) {
   console.log('Depositing assets into all operator staking contracts from the deployer account...\n');
 

protocol-contracts/staking/tasks/ownership/index.ts

@@ -1,3 +1,2 @@
 export * from './protocolStakingManagerRole';
 export * from './protocolStakingGovernorRole';
-export * from './operatorStakingOwner';