feat: add governance and protocol contract owner scripts (#107)

Seth-Schmidt · web-flow · commit 19c3ff150240 · 2026-04-21T09:43:53.000-04:00
Introduces new utility scripts to retrieve and report the owners and delegates of governance and protocol contracts. The following scripts have been added:
- `get-governance-oapp-owners.js`: Reports the owner and delegate of the GovernanceOAppSender and GovernanceOAppReceiver.
- `get-protocol-contract-owners.js`: Reports the owner and pending owner of the ACL and GatewayConfig contracts.
- `get-wrapper-owners.js`: Reports the owner and pending owner of the ConfidentialTokenWrappersRegistry and its associated wrappers.

Additionally, updates the `.env.example` file to include new environment variables for the added scripts and modifies the `package.json` to include new script commands for easy execution.
diff --git a/contracts/chains-config-checker/.env.example b/contracts/chains-config-checker/.env.example
@@ -17,6 +17,13 @@ ZAMA_SAFE_ADMIN_MODULE_GATEWAY="0x57f866b5E7Fb82Fb812Ed3D3C79cdB35E9e91518"
 ZAMA_SAFE_BSC="0xa40939fDe3883D2e7Cd5C32f53AB241804d2779B"
 ZAMA_SAFE_HYPEREVM="0x0d66642a5Bc6E32e013f47E08f9db9bDb1268827"
 ZAMA_ARAGON_DAO="0xB6D69D5F334d8B97B194617B53c6aB62f8681Ef3"
+ZAMA_GOVERNANCE_OAPP_SENDER_ETHEREUM="0x1c5D750D18917064915901048cdFb2dB815e0910"
+ZAMA_GOVERNANCE_OAPP_RECEIVER_GATEWAY="0x10795261A06285D3718674a9Cf98Ea66F7C6A0c6"
+
+ZAMA_ACL_ETHEREUM="0xcA2E8f1F656CD25C01F05d0b243Ab1ecd4a8ffb6"
+ZAMA_GATEWAY_CONFIG_GATEWAY="0xDE537Be194777A56f8B19d14079E6a78249390ab"
+
+ZAMA_WRAPPERS_REGISTRY_ETHEREUM="0xeb5015fF021DB115aCe010f23F55C2591059bBA0"
 
 # Solana
 SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"
diff --git a/contracts/chains-config-checker/README.md b/contracts/chains-config-checker/README.md
@@ -31,6 +31,9 @@ Currently, most useful scripts are:
 [*] get-oft-owners
 [*] get-multisig-info
 [*] get-staking-roles
+[*] get-governance-oapp-owners
+[*] get-protocol-contract-owners
+[*] get-wrapper-owners
 ```
 ### getCurrentPausers
 
@@ -392,4 +395,122 @@ The script will:
 [COPROCESSOR]
   Zama            : 0x31bB...
   ...
-```
+```
+
+### getGovernanceOappOwners
+
+```
+npm run get-governance-oapp-owners
+```
+
+Reports the **owner** and **LayerZero delegate** of the `GovernanceOAppSender` (Ethereum) and `GovernanceOAppReceiver` (Gateway). Uses on-chain view calls only (`owner()`, `endpoint()`, `delegates(oapp)`).
+
+For each configured chain it will:
+1. Read the governance OApp to get `owner()` and `endpoint()`.
+2. Read the endpoint's `delegates(contractAddress)` to get the current delegate.
+3. Print OApp address, owner, and delegate.
+4. Exit non-zero if `owner` and `delegate` differ on any chain.
+
+**Environment variables:**
+
+| Chain                       | RPC env       | Contract address env                    |
+|-----------------------------|---------------|------------------------------------------|
+| Ethereum (Sender)           | `RPC_ETHEREUM` | `ZAMA_GOVERNANCE_OAPP_SENDER_ETHEREUM`   |
+| Gateway (Receiver)          | `RPC_GATEWAY`  | `ZAMA_GOVERNANCE_OAPP_RECEIVER_GATEWAY`  |
+
+Example output:
+
+```
+=== Governance OApp ===
+
+[Ethereum GovernanceOAppSender]
+  OApp address : 0x1c5D750D18917064915901048cdFb2dB815e0910
+  Owner        : 0x...
+  Delegate     : 0x...
+
+[Gateway GovernanceOAppReceiver]
+  OApp address : 0x10795261A06285D3718674a9Cf98Ea66F7C6A0c6
+  Owner        : 0x...
+  Delegate     : 0x...
+
+Owner and Delegate should be IDENTICAL on each chain.
+```
+
+### getProtocolContractOwners
+
+```
+npm run get-protocol-contract-owners
+```
+
+Reports the **owner** (and any **pending owner**) of the `ACL` contract on Ethereum and the `GatewayConfig` contract on the Gateway chain. Both contracts use `Ownable2Step`, so a non-zero `pendingOwner()` indicates an in-flight ownership handover and causes the script to exit non-zero.
+
+For each configured contract it will:
+1. Call `owner()` and `pendingOwner()`.
+2. Print the contract address, owner, and (if non-zero) pending owner.
+3. Emit a WARNING summary if any contract has a pending owner. The script still exits zero.
+
+**Environment variables:**
+
+| Chain     | RPC env        | Contract address env            |
+|-----------|----------------|----------------------------------|
+| Ethereum  | `RPC_ETHEREUM` | `ZAMA_ACL_ETHEREUM`              |
+| Gateway   | `RPC_GATEWAY`  | `ZAMA_GATEWAY_CONFIG_GATEWAY`    |
+
+Example output:
+
+```
+=== Protocol Contract Owners ===
+
+[Ethereum ACL]
+  Contract address : 0x4E35869D1e8106058d11b414876B735F62A325e2
+  Owner            : 0x...
+
+[Gateway GatewayConfig]
+  Contract address : 0x3B19DA9b424f95f1d2787Ab2d3a43ad56D626AAE
+  Owner            : 0x...
+```
+
+### getWrapperOwners
+
+#### Usage
+
+```bash
+npm run get-wrapper-owners
+```
+
+Reports the **owner** (and any **pending owner**) of the `ConfidentialTokenWrappersRegistry` on Ethereum and of every confidential wrapper registered in it. The list of wrappers is read from the registry on-chain, so no per-wrapper env var is required.
+
+The script will:
+1. Read `owner()` and `pendingOwner()` on the registry.
+2. Read `getTokenConfidentialTokenPairsLength()` and iterate `getTokenConfidentialTokenPair(i)` on the registry to list all wrappers (including revoked entries).
+3. For each wrapper, read `owner()` and `pendingOwner()`.
+4. Compare each wrapper's owner to the registry owner. Mismatches are reported as a NOTE and do not cause the script to fail.
+5. Emit a WARNING summary if any contract has a pending owner. The script still exits zero.
+
+**Environment variables:**
+
+| Chain     | RPC env        | Contract address env                |
+|-----------|----------------|--------------------------------------|
+| Ethereum  | `RPC_ETHEREUM` | `ZAMA_WRAPPERS_REGISTRY_ETHEREUM`    |
+
+Example output:
+
+```
+=== Wrappers Registry & Confidential Wrappers ===
+
+[Wrappers Registry]
+  Address       : 0xeb5015fF021DB115aCe010f23F55C2591059bBA0
+  Owner         : 0x...
+
+[Confidential wrapper (underlying ...)]
+  Address       : 0x...
+  Owner         : 0x...
+
+...
+
+--------------------------------------------------
+Registry owner : 0x...
+Wrappers       : 7
+
+All wrapper owners are IDENTICAL to the registry owner.
+```
diff --git a/contracts/chains-config-checker/package.json b/contracts/chains-config-checker/package.json
@@ -10,7 +10,10 @@
     "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-staking-roles": "node utils/get-staking-roles.js"
+    "get-staking-roles": "node utils/get-staking-roles.js",
+    "get-governance-oapp-owners": "node utils/get-governance-oapp-owners.js",
+    "get-protocol-contract-owners": "node utils/get-protocol-contract-owners.js",
+    "get-wrapper-owners": "node utils/get-wrapper-owners.js"
   },
   "dependencies": {
     "@layerzerolabs/lz-solana-sdk-v2": "^3.0.136",
diff --git a/contracts/chains-config-checker/utils/get-governance-oapp-owners.js b/contracts/chains-config-checker/utils/get-governance-oapp-owners.js
@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+require('dotenv').config({ path: require('path').resolve(__dirname, '../.env') });
+const { ethers } = require('ethers');
+const { isValidAddress } = require('./get-deployment-block');
+
+const CHAINS = {
+  ethereumGovernanceOAppSender: {
+    name: 'Ethereum GovernanceOAppSender',
+    rpcEnv: 'RPC_ETHEREUM',
+    addrEnv: 'ZAMA_GOVERNANCE_OAPP_SENDER_ETHEREUM',
+  },
+  gatewayGovernanceOAppReceiver: {
+    name: 'Gateway GovernanceOAppReceiver',
+    rpcEnv: 'RPC_GATEWAY',
+    addrEnv: 'ZAMA_GOVERNANCE_OAPP_RECEIVER_GATEWAY',
+  },
+};
+
+const OAPP_ABI = [
+  'function owner() view returns (address)',
+  'function endpoint() view returns (address)',
+];
+
+const ENDPOINT_ABI = [
+  'function delegates(address) view returns (address)',
+];
+
+function buildChainConfigs() {
+  return Object.entries(CHAINS).map(([key, chain]) => ({
+    key,
+    name: chain.name,
+    rpcUrl: process.env[chain.rpcEnv],
+    contractAddress: process.env[chain.addrEnv],
+  }));
+}
+
+async function getOwnerAndDelegateForChain(chainConfig) {
+  const { name, rpcUrl, contractAddress } = chainConfig;
+
+  if (!rpcUrl) throw new Error(`[${name}] RPC URL is not configured`);
+  if (!contractAddress) throw new Error(`[${name}] Contract address is not configured`);
+  if (!isValidAddress(contractAddress)) throw new Error(`[${name}] Invalid contract address format`);
+
+  const provider = new ethers.JsonRpcProvider(rpcUrl);
+  const oapp = new ethers.Contract(contractAddress, OAPP_ABI, provider);
+
+  const [owner, endpointAddress] = await Promise.all([
+    oapp.owner(),
+    oapp.endpoint(),
+  ]);
+
+  const endpoint = new ethers.Contract(endpointAddress, ENDPOINT_ABI, provider);
+  const delegate = await endpoint.delegates(contractAddress);
+
+  return {
+    name,
+    contractAddress,
+    owner,
+    delegate,
+    equal: owner === delegate,
+  };
+}
+
+function printOwnerAndDelegate(info) {
+  const { name, contractAddress, owner, delegate } = info;
+  console.log(`\n[${name}]`);
+  console.log(`  OApp address : ${contractAddress}`);
+  console.log(`  Owner        : ${owner}`);
+  console.log(`  Delegate     : ${delegate}`);
+}
+
+async function main() {
+  const configs = buildChainConfigs();
+  const toRun = configs.filter((c) => c.rpcUrl && c.contractAddress && isValidAddress(c.contractAddress));
+  const toSkip = configs.filter((c) => !c.rpcUrl || !c.contractAddress || !isValidAddress(c.contractAddress || ''));
+
+  for (const c of toSkip) {
+    if (!c.rpcUrl) {
+      console.log(`  Skipping ${c.name}: RPC not configured`);
+    } else if (!c.contractAddress) {
+      console.log(`  Skipping ${c.name}: Contract address not configured`);
+    } else {
+      console.log(`  Skipping ${c.name}: Invalid address format`);
+    }
+  }
+
+  if (toRun.length === 0) {
+    console.error('Error: No chains configured. Set RPC and contract address env vars in .env');
+    process.exit(1);
+  }
+
+  let hadError = false;
+  const equalityResults = [];
+
+  console.log('\n=== Governance OApp ===');
+  for (const chainConfig of toRun) {
+    try {
+      const info = await getOwnerAndDelegateForChain(chainConfig);
+      printOwnerAndDelegate(info);
+      equalityResults.push({ name: chainConfig.name, equal: info.equal });
+    } catch (error) {
+      console.error(`\n[${chainConfig.name}] Error: ${error.message}`);
+      hadError = true;
+    }
+  }
+
+  if (hadError) process.exit(1);
+
+  const failed = equalityResults.filter((r) => !r.equal);
+  if (failed.length > 0) {
+    for (const { name } of failed) {
+      console.error(`Owner and Delegate are NOT IDENTICAL on ${name}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('\nOwner and Delegate should be IDENTICAL on each chain.');
+}
+
+main();
diff --git a/contracts/chains-config-checker/utils/get-protocol-contract-owners.js b/contracts/chains-config-checker/utils/get-protocol-contract-owners.js
@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+require('dotenv').config({ path: require('path').resolve(__dirname, '../.env') });
+const { ethers } = require('ethers');
+const { isValidAddress } = require('./get-deployment-block');
+
+const CONTRACTS = {
+  ethereumAcl: {
+    name: 'Ethereum ACL',
+    rpcEnv: 'RPC_ETHEREUM',
+    addrEnv: 'ZAMA_ACL_ETHEREUM',
+  },
+  gatewayConfig: {
+    name: 'Gateway GatewayConfig',
+    rpcEnv: 'RPC_GATEWAY',
+    addrEnv: 'ZAMA_GATEWAY_CONFIG_GATEWAY',
+  },
+};
+
+const OWNABLE2STEP_ABI = [
+  'function owner() view returns (address)',
+  'function pendingOwner() view returns (address)',
+];
+
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+function buildConfigs() {
+  return Object.entries(CONTRACTS).map(([key, contract]) => ({
+    key,
+    name: contract.name,
+    rpcUrl: process.env[contract.rpcEnv],
+    contractAddress: process.env[contract.addrEnv],
+  }));
+}
+
+async function getOwnerInfo(config) {
+  const { name, rpcUrl, contractAddress } = config;
+
+  if (!rpcUrl) throw new Error(`[${name}] RPC URL is not configured`);
+  if (!contractAddress) throw new Error(`[${name}] Contract address is not configured`);
+  if (!isValidAddress(contractAddress)) throw new Error(`[${name}] Invalid contract address format`);
+
+  const provider = new ethers.JsonRpcProvider(rpcUrl);
+  const contract = new ethers.Contract(contractAddress, OWNABLE2STEP_ABI, provider);
+
+  const [owner, pendingOwner] = await Promise.all([
+    contract.owner(),
+    contract.pendingOwner(),
+  ]);
+
+  return { name, contractAddress, owner, pendingOwner };
+}
+
+function printOwnerInfo(info) {
+  const { name, contractAddress, owner, pendingOwner } = info;
+  console.log(`\n[${name}]`);
+  console.log(`  Contract address : ${contractAddress}`);
+  console.log(`  Owner            : ${owner}`);
+  if (pendingOwner !== ZERO_ADDRESS) {
+    console.log(`  Pending owner    : ${pendingOwner}`);
+    console.log(`  WARNING: ownership handover in progress`);
+  }
+}
+
+async function main() {
+  const configs = buildConfigs();
+  const toRun = configs.filter((c) => c.rpcUrl && c.contractAddress && isValidAddress(c.contractAddress));
+  const toSkip = configs.filter((c) => !c.rpcUrl || !c.contractAddress || !isValidAddress(c.contractAddress || ''));
+
+  for (const c of toSkip) {
+    if (!c.rpcUrl) {
+      console.log(`  Skipping ${c.name}: RPC not configured`);
+    } else if (!c.contractAddress) {
+      console.log(`  Skipping ${c.name}: Contract address not configured`);
+    } else {
+      console.log(`  Skipping ${c.name}: Invalid address format`);
+    }
+  }
+
+  if (toRun.length === 0) {
+    console.error('Error: No contracts configured. Set RPC and contract address env vars in .env');
+    process.exit(1);
+  }
+
+  let hadError = false;
+  const pending = [];
+
+  console.log('\n=== Protocol Contract Owners ===');
+  for (const config of toRun) {
+    try {
+      const info = await getOwnerInfo(config);
+      printOwnerInfo(info);
+      if (info.pendingOwner !== ZERO_ADDRESS) pending.push(info.name);
+    } catch (error) {
+      console.error(`\n[${config.name}] Error: ${error.message}`);
+      hadError = true;
+    }
+  }
+
+  if (hadError) process.exit(1);
+
+  if (pending.length > 0) {
+    console.warn(`\nWARNING: ${pending.length} contract(s) have a pending owner: ${pending.join(', ')}`);
+  }
+}
+
+main();
diff --git a/contracts/chains-config-checker/utils/get-wrapper-owners.js b/contracts/chains-config-checker/utils/get-wrapper-owners.js
