feat: add config checker for staking roles (#102)

* feat: add get-staking-roles script and update package.json and README

- Introduced a new script `get-staking-roles` to report roles of ProtocolStaking contracts and their beneficiaries.
- Updated `package.json` to include the new script in the npm tasks.
- Enhanced the README to document the usage of the new script and added it to the list of available scripts.
- Created a new `staking-addresses.json` file to store addresses for ProtocolStaking and OperatorStaking contracts.

* fix: trigger ci

* feat: enhance chains-config-checker with testnet support and documentation updates

- Added support for the Sepolia testnet in the chains-config-checker, including new RPC endpoint in `.env.example`.
- Updated `staking-addresses.json` to include separate configurations for mainnet and testnet, with deployment blocks for each contract.
- Enhanced the `README.md` to clarify the usage of the `get-staking-roles` script across both mainnet and testnet, including details on deployment blocks.
- Modified the `get-staking-roles.js` script to handle network-specific configurations and improve error handling for missing RPC URLs.

chore: streamline staking address configurations and enhance script functionality

- Removed the RPC_SEPOLIA variable from `.env.example` as it is no longer needed.
- Updated `README.md` to clarify the usage of the `get-staking-roles` script, emphasizing the separation of mainnet and testnet configurations.
- Introduced a new `staking-addresses-testnet.json` file for testnet-specific staking addresses.
- Refactored `get-staking-roles.js` to utilize network-specific configuration files, improving clarity and maintainability.

* docs: update README.md to include detailed usage for getStakingRoles script

- Added a new section for the `getStakingRoles` script, outlining its functionality to report roles of ProtocolStaking contracts and beneficiaries of OperatorStaking contracts.
- Clarified the usage instructions for mainnet and testnet configurations, including command examples and environment variable requirements.
- Enhanced documentation to improve clarity and usability for developers working with staking roles.

Author: Seth-Schmidt

contracts/chains-config-checker/README.md

@@ -30,6 +30,7 @@ Currently, most useful scripts are:
 [*] get-token-roles
 [*] get-oft-owners
 [*] get-multisig-info
+[*] get-staking-roles
 ```
 ### getCurrentPausers
 
@@ -326,3 +327,69 @@ Detected 2 active plugin address(es):
     2. ...
     ...
 ```
+
+### getStakingRoles
+
+Reports the roles of ProtocolStaking contracts and the beneficiaries of OperatorStaking contracts. Addresses are maintained in two config files:
+
+- `staking-addresses.json` — mainnet (Ethereum)
+- `staking-addresses-testnet.json` — testnet (Sepolia)
+
+#### Usage
+
+```bash
+npm run get-staking-roles                 # mainnet (default)
+npm run get-staking-roles -- --mainnet    # explicit
+npm run get-staking-roles -- --testnet    # testnet
+```
+
+The `--` separates npm's args from the script's args. Only one of `--mainnet` / `--testnet` may be passed.
+
+The script will:
+1. For each **ProtocolStaking** contract (KMS, Coprocessor), scan `RoleGranted`/`RoleRevoked` events to compute current holders of `DEFAULT_ADMIN_ROLE`, `MANAGER_ROLE`, and `ELIGIBLE_ACCOUNT_ROLE`.
+2. Verify that all `ELIGIBLE_ACCOUNT_ROLE` holders are known **OperatorStaking** addresses in the selected config file.
+3. For each **OperatorStaking** contract, read the `beneficiary()` from its OperatorRewarder.
+
+**Environment variables:**
+
+| Variable       | Description                                                                 |
+|----------------|-----------------------------------------------------------------------------|
+| `RPC_ETHEREUM` | Archive-capable RPC endpoint. Point it at Ethereum mainnet or Sepolia depending on the flag you pass. |
+
+`RPC_ETHEREUM` must be set, otherwise the script exits with an error. The endpoint must be **archive-capable**: the script binary-searches for each ProtocolStaking deployment block via `eth_getCode` at historical blocks, which pruned nodes reject.
+
+#### Example Output
+
+```
+=== ProtocolStaking Roles ===
+
+[ProtocolStaking - KMS]
+  Contract: 0xe9b1...
+  ...
+
+  DEFAULT_ADMIN_ROLE:
+    1. 0xB6D6...Ef3
+
+  MANAGER_ROLE:
+    1. 0xB6D6...Ef3
+
+  ELIGIBLE_ACCOUNT_ROLE:
+    1. 0x8305... <- Zama (kms)
+    2. 0xB968... <- Dfns (kms)
+    ...
+    All eligible accounts are known OperatorStaking addresses.
+
+[ProtocolStaking - COPROCESSOR]
+  ...
+
+=== OperatorStaking Beneficiaries ===
+
+[KMS]
+  Zama            : 0x31bB...
+  Dfns            : 0xb59F...
+  ...
+
+[COPROCESSOR]
+  Zama            : 0x31bB...
+  ...
+```

contracts/chains-config-checker/package.json

@@ -9,7 +9,8 @@
     "get-oft-owners-evm": "node utils/get-oft-owners-evm.js",
     "get-oft-owners-solana": "node utils/get-oft-owners-solana.js",
     "get-oft-owners": "node utils/get-oft-owners-evm.js && node utils/get-oft-owners-solana.js",
-    "get-multisig-info": "node utils/get-multisig-info.js"
+    "get-multisig-info": "node utils/get-multisig-info.js",
+    "get-staking-roles": "node utils/get-staking-roles.js"
   },
   "dependencies": {
     "@layerzerolabs/lz-solana-sdk-v2": "^3.0.136",

contracts/chains-config-checker/staking-addresses-testnet.json

@@ -0,0 +1,30 @@
+{
+  "protocolStaking": {
+    "kms": "0x0309b4308A6AC121B9b3A960aC7Bc9bd8256cf38",
+    "coprocessor": "0xc22E393D2A1C1BD65c88d34a3bE4DD77e8952E71"
+  },
+  "operatorStaking": {
+    "kms": {
+      "Zama": "0x454D1738C8eD25C744aF01730EE39a27B683A246",
+      "Dfns": "0x8e0bFD7736E9628E2179fB98d44223eF9840fBC7",
+      "Figment": "0x1a5f6C8FFdd869b30FFC73cC9424025829aCad04",
+      "Fireblocks": "0xe85765700Ef107E94fd57FbF1D1863ff87a2948D",
+      "InfStones": "0x5F1310b6E8F7DcC24A9A6F74229cf66EE075d4D6",
+      "Unit410": "0xFcC6F9cA8CC4A491B05306D57374a3F6c1f52484",
+      "LayerZero": "0x6c12eB5d89E6f89399610C7b3Efca40671E82F06",
+      "Ledger": "0xe52419533D0322a57d6db28d32463aa6717FeA3c",
+      "Omakase": "0xb1A7026C28cB91604FB7B1669f060aB74A30c255",
+      "Stake Capital": "0xdd0a1B86C8bf653e5bA575bE81bBD733E59803Ae",
+      "OpenZeppelin": "0x76427A3830295406d4aBae5b4754749048f58098",
+      "Etherscan": "0xDF3f304c291466F21BB711d00E48a0d9AD9D64aF",
+      "Conduit": "0xd6C131CD3c1243934658781a9F7A2CBd1E40f6bF"
+    },
+    "coprocessor": {
+      "Zama": "0x1504646d2e4F924db4c6D6F8e42713e5492604ce",
+      "Blockscape": "0xd32b8E13D9e9733f21068168637e68131122C212",
+      "P2P": "0x419Bcec8A8B60688AC7EfeFECC5f83E922191b2A",
+      "Artifact": "0x98B50c22245994360Ecf1F695a7383A3f983AeF4",
+      "Luganodes": "0xe89d9ca0579F19B77af04b201E73A26CECA07600"
+    }
+  }
+}

contracts/chains-config-checker/staking-addresses.json

@@ -0,0 +1,30 @@
+{
+  "protocolStaking": {
+    "kms": "0xe9b176CCaA8840DC3b3567bb83e2cD2a6c36F4Ab",
+    "coprocessor": "0x7147485b892158f2B875f7aC5Ea48A9937C66AE8"
+  },
+  "operatorStaking": {
+    "kms": {
+      "Zama": "0x8305d7c59886462B04C71Ecc5c5C331520C2a8E4",
+      "Dfns": "0xB9689c08A634B076849E61Ea4E42AB44aE2e5e2d",
+      "Figment": "0x8a3Bb2a9B28dAD4230a6dfE17124C398eA6416BF",
+      "Fireblocks": "0xF1BA887932d7559B3b00a58fE92F36CA8D7751d3",
+      "InfStones": "0x80c03b5be1417D18bAe68d5a1F0f2A97457b0C3c",
+      "Unit410": "0xFCAA267679B8364957560d7420E66Bb012013091",
+      "LayerZero": "0x9b5Cd13b8eFbB58Dc25A05CF411D8056058aDFfF",
+      "Ledger": "0x78F597F1Dcf5dA536745558368c825654A1A044B",
+      "Omakase": "0xff54739b16576FA5402F211D0b938469Ab9A5f3F",
+      "Stake Capital": "0xFf021fB13cA64e5354c62c954b949a88cfDEb25E",
+      "OpenZeppelin": "0x75355a85c6FB9df5f0C80FF54e8747EEe9a0BF57",
+      "Etherscan": "0x93c931278A2aad1916783F952f94276eA5111442",
+      "Conduit": "0x50C271E25Ee953DD21E916311db81E228c9Bdb59"
+    },
+    "coprocessor": {
+      "Zama": "0x5c9401fdA261fDb97188126e130e001DB38F1310",
+      "Blockscape": "0x126D6B697aD04228657Ba677c71CfE20A8745b03",
+      "P2P": "0xdB4FE5977d4f78f251C0F821C18C1F7A16Ad3A5e",
+      "Artifact": "0xf5A0f502C98Df9dC22A4E4f251eC3c75f2aD8098",
+      "Luganodes": "0xdD7fA0C796b3ca4fc1654F4eFFea5c4E9fF57a23"
+    }
+  }
+}

contracts/chains-config-checker/utils/get-staking-roles.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+require('dotenv').config({ path: require('path').resolve(__dirname, '../.env') });
+const path = require('path');
+const { ethers } = require('ethers');
+const { findDeploymentBlock } = require('./get-deployment-block');
+
+const MAX_BLOCK_RANGE = 49999;
+
+// Both networks read RPC_ETHEREUM; point it at an Ethereum mainnet or Sepolia
+// archive RPC depending on which --mainnet/--testnet flag you pass.
+const NETWORKS = {
+  mainnet: {
+    label: 'Mainnet (Ethereum)',
+    configFile: 'staking-addresses.json',
+  },
+  testnet: {
+    label: 'Testnet (Sepolia)',
+    configFile: 'staking-addresses-testnet.json',
+  },
+};
+
+const ROLE_EVENT_ABI = [
+  'event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender)',
+  'event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender)',
+];
+
+const OPERATOR_STAKING_ABI = [
+  'function rewarder() view returns (address)',
+];
+
+const OPERATOR_REWARDER_ABI = [
+  'function beneficiary() view returns (address)',
+];
+
+const ROLE_HASHES = {
+  DEFAULT_ADMIN_ROLE: ethers.ZeroHash,
+  MANAGER_ROLE: ethers.keccak256(ethers.toUtf8Bytes('MANAGER_ROLE')),
+  ELIGIBLE_ACCOUNT_ROLE: ethers.keccak256(ethers.toUtf8Bytes('ELIGIBLE_ACCOUNT_ROLE')),
+};
+
+const ROLE_NAMES_BY_HASH = new Map(
+  Object.entries(ROLE_HASHES).map(([name, hash]) => [hash, name])
+);
+
+function parseNetworkFlag(argv) {
+  const flags = argv.filter((a) => a === '--mainnet' || a === '--testnet');
+  if (flags.length > 1) {
+    console.error('Error: pass only one of --mainnet or --testnet');
+    process.exit(1);
+  }
+  return flags[0] === '--testnet' ? 'testnet' : 'mainnet';
+}
+
+async function queryEventsInChunks(contract, filter, fromBlock, toBlock, label) {
+  const events = [];
+  let currentFrom = fromBlock;
+
+  while (currentFrom <= toBlock) {
+    const currentTo = Math.min(currentFrom + MAX_BLOCK_RANGE, toBlock);
+    const progress = Math.round(((currentFrom - fromBlock) / (toBlock - fromBlock)) * 100) || 0;
+    process.stdout.write(`\r    ${label}: ${progress}% (block ${currentFrom})...`);
+
+    const chunk = await contract.queryFilter(filter, currentFrom, currentTo);
+    events.push(...chunk);
+
+    currentFrom = currentTo + 1;
+  }
+
+  console.log(`\r    ${label}: 100% - found ${events.length} events`);
+  return events;
+}
+
+// Build a set of all known OperatorStaking addresses (lowercased) for cross-referencing
+function getAllOperatorStakingAddresses(stakingAddresses) {
+  const addresses = new Set();
+  for (const roleOperators of Object.values(stakingAddresses.operatorStaking)) {
+    for (const addr of Object.values(roleOperators)) {
+      addresses.add(addr.toLowerCase());
+    }
+  }
+  return addresses;
+}
+
+// Reverse-lookup: address -> "Name (role)"
+function getOperatorStakingLabel(stakingAddresses, address) {
+  const lower = address.toLowerCase();
+  for (const [role, operators] of Object.entries(stakingAddresses.operatorStaking)) {
+    for (const [name, addr] of Object.entries(operators)) {
+      if (addr.toLowerCase() === lower) return `${name} (${role})`;
+    }
+  }
+  return null;
+}
+
+async function getProtocolStakingRoles(provider, rpcUrl, contractAddress) {
+  const contract = new ethers.Contract(contractAddress, ROLE_EVENT_ABI, provider);
+
+  console.log(`  Finding deployment block for ${contractAddress}...`);
+  const fromBlock = await findDeploymentBlock(contractAddress, { rpcUrl, silent: true });
+  const toBlock = await provider.getBlockNumber();
+  console.log(`  Deployment block: ${fromBlock}, current block: ${toBlock}`);
+
+  console.log('  Fetching role events...');
+  const grantedEvents = await queryEventsInChunks(contract, contract.filters.RoleGranted(), fromBlock, toBlock, 'RoleGranted');
+  const revokedEvents = await queryEventsInChunks(contract, contract.filters.RoleRevoked(), fromBlock, toBlock, 'RoleRevoked');
+
+  const allEvents = [
+    ...grantedEvents.map((e) => ({ type: 'grant', role: e.args.role, account: e.args.account, block: e.blockNumber, logIndex: e.index })),
+    ...revokedEvents.map((e) => ({ type: 'revoke', role: e.args.role, account: e.args.account, block: e.blockNumber, logIndex: e.index })),
+  ]
+    .filter((e) => ROLE_NAMES_BY_HASH.has(e.role))
+    .sort((a, b) => (a.block !== b.block ? a.block - b.block : a.logIndex - b.logIndex));
+
+  const roleSets = new Map(Object.keys(ROLE_HASHES).map((name) => [name, new Set()]));
+
+  for (const event of allEvents) {
+    const roleName = ROLE_NAMES_BY_HASH.get(event.role);
+    const set = roleSets.get(roleName);
+    if (event.type === 'grant') {
+      set.add(event.account);
+    } else {
+      set.delete(event.account);
+    }
+  }
+
+  return Object.fromEntries([...roleSets.entries()].map(([name, set]) => [name, Array.from(set)]));
+}
+
+async function getOperatorStakingBeneficiary(provider, address) {
+  const opStaking = new ethers.Contract(address, OPERATOR_STAKING_ABI, provider);
+  const rewarderAddr = await opStaking.rewarder();
+  const rewarder = new ethers.Contract(rewarderAddr, OPERATOR_REWARDER_ABI, provider);
+  return rewarder.beneficiary();
+}
+
+function printRoles(roles, stakingAddresses, allOpStakingAddresses) {
+  for (const [roleName, holders] of Object.entries(roles)) {
+    console.log(`\n  ${roleName}:`);
+    if (holders.length === 0) {
+      console.log('    (none)');
+      continue;
+    }
+    for (let i = 0; i < holders.length; i++) {
+      const addr = holders[i];
+      const label = getOperatorStakingLabel(stakingAddresses, addr);
+      const suffix = label ? ` <- ${label}` : '';
+      console.log(`    ${i + 1}. ${addr}${suffix}`);
+    }
+
+    // For ELIGIBLE_ACCOUNT_ROLE, check that every holder is a known OperatorStaking address
+    if (roleName === 'ELIGIBLE_ACCOUNT_ROLE') {
+      const unknown = holders.filter((a) => !allOpStakingAddresses.has(a.toLowerCase()));
+      if (unknown.length > 0) {
+        console.log('    WARNING: Unknown addresses in ELIGIBLE_ACCOUNT_ROLE:');
+        for (const addr of unknown) {
+          console.log(`      - ${addr}`);
+        }
+      } else {
+        console.log('    All eligible accounts are known OperatorStaking addresses.');
+      }
+    }
+  }
+}
+
+async function main() {
+  const networkKey = parseNetworkFlag(process.argv.slice(2));
+  const network = NETWORKS[networkKey];
+  const stakingAddresses = require(path.resolve(__dirname, '..', network.configFile));
+
+  const rpcUrl = process.env.RPC_ETHEREUM;
+  if (!rpcUrl) {
+    console.error('Error: RPC_ETHEREUM not configured');
+    process.exit(1);
+  }
+
+  console.log(`\n### ${network.label} (${network.configFile}) ###`);
+
+  const provider = new ethers.JsonRpcProvider(rpcUrl);
+  const allOpStakingAddresses = getAllOperatorStakingAddresses(stakingAddresses);
+  let hadError = false;
+
+  // Part 1: ProtocolStaking roles
+  console.log('\n=== ProtocolStaking Roles ===');
+
+  for (const [role, address] of Object.entries(stakingAddresses.protocolStaking)) {
+    console.log(`\n[ProtocolStaking - ${role.toUpperCase()}]`);
+    console.log(`  Contract: ${address}`);
+    try {
+      const roles = await getProtocolStakingRoles(provider, rpcUrl, address);
+      printRoles(roles, stakingAddresses, allOpStakingAddresses);
+    } catch (error) {
+      console.error(`  Error: ${error.message}`);
+      hadError = true;
+    }
+  }
+
+  // Part 2: OperatorStaking beneficiaries
+  console.log('\n=== OperatorStaking Beneficiaries ===');
+
+  for (const [role, operators] of Object.entries(stakingAddresses.operatorStaking)) {
+    console.log(`\n[${role.toUpperCase()}]`);
+
+    for (const [name, address] of Object.entries(operators)) {
+      try {
+        const beneficiary = await getOperatorStakingBeneficiary(provider, address);
+        console.log(`  ${name.padEnd(15)} : ${beneficiary}`);
+      } catch (error) {
+        console.error(`  ${name.padEnd(15)} : Error - ${error.message}`);
+        hadError = true;
+      }
+    }
+  }
+
+  if (hadError) {
+    process.exit(1);
+  }
+}
+
+main();