feat: Implement Allowlist contract for operator management

piotr-roslaniec · piotr-roslaniec · commit dc885cb8ef3d · 2025-08-18T11:13:10.000+02:00
- Add Allowlist contract to replace TokenStaking functionality
- Implement weight-based operator management without token staking
- Add deployment and initialization scripts
- Include consolidation script for operator reduction (20→4 operators)
- Add comprehensive test coverage
- Maintain compatibility with existing WalletRegistry interface
diff --git a/solidity/ecdsa/contracts/Allowlist.sol b/solidity/ecdsa/contracts/Allowlist.sol
@@ -19,11 +19,9 @@ import "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
 import "./WalletRegistry.sol";
 
 /// @title Allowlist
-/// @notice The allowlist contract replaces the Threshold TokenStaking contract
-///         and is as an outcome of TIP-092 and TIP-100 governance decisions.
+/// @notice The allowlist contract replaces the Threshold TokenStaking contract.
 ///         Staking tokens is no longer required to operate nodes. Beta stakers
-///         are selected by the DAO and operate the network based on the
-///         allowlist maintained by the DAO.
+///         operate the network based on the allowlist maintained by governance.
 /// @dev The allowlist contract maintains the maximum possible compatibility
 ///      with the old TokenStaking contract interface, as utilized by the
 ///      WalletRegistry contract.
@@ -160,8 +158,7 @@ contract Allowlist is Ownable2StepUpgradeable {
 
     /// @notice Returns the current weight of the staking provider.
     /// @dev The function signature maintains compatibility with Threshold
-    ///      TokenStaking contract to minimize the TIP-092 impact on the
-    ///      WalletRegistry contract.
+    ///      TokenStaking contract interface.
     function authorizedStake(address stakingProvider, address)
         external
         view
@@ -170,11 +167,10 @@ contract Allowlist is Ownable2StepUpgradeable {
         return stakingProviders[stakingProvider].weight;
     }
 
-    /// @notice No-op stake seize operation. After TIP-092 tokens are not staked
+    /// @notice No-op stake seize operation. Tokens are not staked
     ///         so there is nothing to seize from.
     /// @dev The function signature maintains compatibility with Threshold
-    ///      TokenStaking contract to minimize the TIP-092 impact on the
-    ///      WalletRegistry contract.
+    ///      TokenStaking contract interface.
     function seize(
         uint96,
         uint256,
@@ -185,13 +181,12 @@ contract Allowlist is Ownable2StepUpgradeable {
     }
 
     /// @notice Returns the stake owner, beneficiary, and authorizer roles for
-    ///         the given staking provider. After TIP-092 those roles are no
+    ///         the given staking provider. Those roles are no
     ///         longer relevant as no tokens are staked. The owner is set to the
     ///         allowlist owner, the beneficiary is the staking provider itself
     ///         and the authorizer is the zero address.
     /// @dev The function signature maintains compatibility with Threshold
-    ///      TokenStaking contract to minimize the TIP-092 impact on the
-    ///      WalletRegistry contract.
+    ///      TokenStaking contract interface.
     function rolesOf(address stakingProvider)
         external
         view
diff --git a/solidity/ecdsa/deploy/15_deploy_allowlist.ts b/solidity/ecdsa/deploy/15_deploy_allowlist.ts
@@ -0,0 +1,45 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async (hre: HardhatRuntimeEnvironment) => {
+  const { getNamedAccounts, deployments, ethers, helpers } = hre
+
+  const { deployer, governance } = await getNamedAccounts()
+
+  // Get the WalletRegistry deployment - this will be replaced by Allowlist
+  // but we still need it for initialization
+  const WalletRegistry = await deployments.get("WalletRegistry")
+
+  // Deploy the Allowlist contract using upgradeable proxy pattern
+  const [allowlist, proxyDeployment] = await helpers.upgrades.deployProxy(
+    "Allowlist",
+    {
+      initializerArgs: [WalletRegistry.address],
+      factoryOpts: {
+        signer: await ethers.getSigner(deployer),
+      },
+      proxyOpts: {
+        kind: "transparent",
+      },
+    }
+  )
+
+  // Transfer ownership to governance if specified and different from deployer
+  if (governance && governance !== deployer) {
+    await helpers.ownable.transferOwnership("Allowlist", governance, deployer)
+  }
+
+  // Log deployment information
+  console.log(`Allowlist deployed at: ${allowlist.address}`)
+  console.log(
+    `Allowlist proxy admin: ${proxyDeployment.receipt.contractAddress}`
+  )
+  console.log(`Allowlist owner: ${await allowlist.owner()}`)
+
+  return true
+}
+
+export default func
+
+func.tags = ["Allowlist"]
+func.dependencies = ["WalletRegistry"]
diff --git a/solidity/ecdsa/deploy/16_initialize_allowlist_weights.ts b/solidity/ecdsa/deploy/16_initialize_allowlist_weights.ts
@@ -0,0 +1,150 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async (hre: HardhatRuntimeEnvironment) => {
+  const { getNamedAccounts, deployments, ethers } = hre
+  const { deployer, governance } = await getNamedAccounts()
+
+  // Get contract instances
+  const allowlistDeployment = await deployments.get("Allowlist")
+  const walletRegistryDeployment = await deployments.get("WalletRegistry")
+  const tokenStakingDeployment = await deployments.get("TokenStaking")
+
+  const allowlist = await ethers.getContractAt(
+    "Allowlist",
+    allowlistDeployment.address
+  )
+  const walletRegistry = await ethers.getContractAt(
+    "WalletRegistry",
+    walletRegistryDeployment.address
+  )
+  const tokenStaking = await ethers.getContractAt(
+    "TokenStaking",
+    tokenStakingDeployment.address
+  )
+
+  // Get the governance signer (owner of Allowlist)
+  const governanceSigner = await ethers.getSigner(governance || deployer)
+
+  console.log("Starting beta staker migration to Allowlist...")
+
+  // Query all existing beta stakers from WalletRegistry
+  // We'll look for AuthorizationIncreased events to find all staking providers
+  const authorizationFilter = walletRegistry.filters.AuthorizationIncreased()
+  const authorizationEvents = await walletRegistry.queryFilter(
+    authorizationFilter
+  )
+
+  // Extract unique staking providers
+  const stakingProviders = new Set<string>()
+  for (const event of authorizationEvents) {
+    if (event.args && event.args.stakingProvider) {
+      stakingProviders.add(event.args.stakingProvider)
+    }
+  }
+
+  console.log(`Found ${stakingProviders.size} unique staking providers`)
+
+  // For each staking provider, get their current authorized stake and add to Allowlist
+  const migrationResults = []
+
+  for (const stakingProvider of stakingProviders) {
+    try {
+      // Get current authorized stake from TokenStaking
+      const authorizedStake = await tokenStaking.authorizedStake(
+        stakingProvider,
+        walletRegistry.address
+      )
+
+      if (authorizedStake.gt(0)) {
+        console.log(
+          `Migrating staking provider ${stakingProvider} with weight ${ethers.utils.formatEther(
+            authorizedStake
+          )} T`
+        )
+
+        // Add to Allowlist with current weight
+        const tx = await allowlist
+          .connect(governanceSigner)
+          .addStakingProvider(stakingProvider, authorizedStake)
+        await tx.wait()
+
+        migrationResults.push({
+          stakingProvider,
+          weight: authorizedStake,
+          status: "success",
+        })
+
+        console.log(`✓ Successfully migrated ${stakingProvider}`)
+      } else {
+        console.log(`Skipping ${stakingProvider} - no authorized stake`)
+        migrationResults.push({
+          stakingProvider,
+          weight: authorizedStake,
+          status: "skipped - no stake",
+        })
+      }
+    } catch (error) {
+      console.error(`✗ Failed to migrate ${stakingProvider}:`, error.message)
+      migrationResults.push({
+        stakingProvider,
+        weight: "0",
+        status: `failed: ${error.message}`,
+      })
+    }
+  }
+
+  // Summary
+  const successful = migrationResults.filter(
+    (r) => r.status === "success"
+  ).length
+  const failed = migrationResults.filter((r) =>
+    r.status.startsWith("failed")
+  ).length
+  const skipped = migrationResults.filter((r) =>
+    r.status.startsWith("skipped")
+  ).length
+
+  console.log("\n=== Migration Summary ===")
+  console.log(`Total staking providers found: ${stakingProviders.size}`)
+  console.log(`Successfully migrated: ${successful}`)
+  console.log(`Failed: ${failed}`)
+  console.log(`Skipped: ${skipped}`)
+
+  // Save migration results to file for record keeping
+  const fs = require("fs")
+  const path = require("path")
+  const resultsPath = path.join(__dirname, "../migration-results.json")
+  fs.writeFileSync(
+    resultsPath,
+    JSON.stringify(
+      {
+        timestamp: new Date().toISOString(),
+        network: hre.network.name,
+        results: migrationResults,
+      },
+      null,
+      2
+    )
+  )
+
+  console.log(`Migration results saved to: ${resultsPath}`)
+
+  if (failed > 0) {
+    console.warn(
+      `⚠️  Migration completed with ${failed} failures. Please review the results.`
+    )
+  } else {
+    console.log("✅ Migration completed successfully!")
+  }
+
+  return true
+}
+
+export default func
+
+func.tags = ["InitializeAllowlistWeights"]
+func.dependencies = ["Allowlist"]
+
+// Only run this script when explicitly requested
+func.skip = async (hre) => !process.env.MIGRATE_ALLOWLIST_WEIGHTS
diff --git a/solidity/ecdsa/docs/Allowlist.md b/solidity/ecdsa/docs/Allowlist.md
@@ -0,0 +1,128 @@
+# Allowlist Contract
+
+The Allowlist contract replaces the TokenStaking contract, enabling governance-controlled beta staker selection without requiring token staking.
+
+## Overview
+
+The Allowlist contract maintains compatibility with the existing WalletRegistry interface while providing a simpler, governance-controlled mechanism for managing beta stakers. Instead of requiring tokens to be staked, governance directly controls which operators can participate in the network and their respective weights.
+
+## Key Features
+
+- **Governance Control**: Only the contract owner (governance) can add staking providers or modify their weights
+- **Weight Management**: Supports weight decrease operations with the same delay mechanism as TokenStaking
+- **WalletRegistry Compatible**: Implements the same interface methods used by WalletRegistry
+- **Beta Staker Consolidation**: Enables setting operator weights to zero for gradual consolidation
+- **No Token Requirements**: Removes the need for operators to stake tokens
+
+## Contract Functions
+
+### Core Management
+
+#### `addStakingProvider(address stakingProvider, uint96 weight)`
+- **Access**: Owner only
+- **Purpose**: Add a new staking provider with specified weight
+- **Effects**: Calls `authorizationIncreased` on WalletRegistry
+- **Reverts**: If provider already exists with non-zero weight
+
+#### `requestWeightDecrease(address stakingProvider, uint96 newWeight)`
+- **Access**: Owner only
+- **Purpose**: Request weight decrease for existing provider
+- **Effects**: Sets pending weight and calls `authorizationDecreaseRequested` on WalletRegistry
+- **Notes**: Can set weight to zero for consolidation
+
+#### `approveAuthorizationDecrease(address stakingProvider)`
+- **Access**: WalletRegistry only
+- **Purpose**: Approve previously requested weight decrease
+- **Returns**: New weight value
+- **Effects**: Updates provider weight and clears pending value
+
+### Compatibility Interface
+
+#### `authorizedStake(address stakingProvider, address application)`
+- **Access**: Public view
+- **Purpose**: Return current weight for the provider
+- **Notes**: Second parameter (application) is ignored for compatibility
+
+#### `seize(uint96 amount, uint256 rewardMultiplier, address notifier, address[] memory stakingProviders)`
+- **Access**: Public
+- **Purpose**: No-op seize operation (no tokens to seize)
+- **Effects**: Only emits `MaliciousBehaviorIdentified` event
+
+#### `rolesOf(address stakingProvider)`
+- **Access**: Public view
+- **Returns**: (owner, stakingProvider, address(0))
+- **Purpose**: Return roles for compatibility
+
+## Deployment Process
+
+### 1. Deploy Allowlist Contract
+```bash
+npx hardhat deploy --tags Allowlist
+```
+
+### 2. Initialize with Existing Beta Stakers
+```bash
+MIGRATE_ALLOWLIST_WEIGHTS=true npx hardhat deploy --tags InitializeAllowlistWeights
+```
+
+### 3. Update WalletRegistry Integration
+Update WalletRegistry constructor to use Allowlist instead of TokenStaking.
+
+## Beta Staker Consolidation Workflow
+
+### Phase 1: Migration
+1. Deploy Allowlist contract
+2. Initialize with current beta staker weights from TokenStaking
+3. Verify all operators are properly migrated
+
+### Phase 2: Consolidation
+1. Identify redundant operators for each entity (Boar, P2P, Staked.us)
+2. Use weight management script to set redundant operator weights to zero
+3. Monitor natural fund drainage as redemptions occur
+
+### Phase 3: Cleanup
+1. Verify zero-weight operators have no remaining funds
+2. Coordinate with operators to shut down redundant nodes
+3. Confirm network operates correctly with ~20 operators instead of ~35
+
+## Beta Staker Consolidation
+
+#### Execute Full Consolidation
+```bash
+# Check current status
+npx hardhat run scripts/consolidate_beta_stakers.ts -- status --allowlist <address>
+
+# Dry run to see what would happen
+npx hardhat run scripts/consolidate_beta_stakers.ts -- execute --allowlist <address> --dry-run
+
+# Execute the consolidation (18 → 3 operators)
+npx hardhat run scripts/consolidate_beta_stakers.ts -- execute --allowlist <address>
+```
+
+## Events
+
+### `StakingProviderAdded(address indexed stakingProvider, uint96 weight)`
+Emitted when a new staking provider is added to the allowlist.
+
+### `WeightDecreaseRequested(address indexed stakingProvider, uint96 oldWeight, uint96 newWeight)`
+Emitted when a weight decrease is requested.
+
+### `WeightDecreaseFinalized(address indexed stakingProvider, uint96 oldWeight, uint96 newWeight)`
+Emitted when a weight decrease is approved and finalized.
+
+### `MaliciousBehaviorIdentified(address notifier, address[] stakingProviders)`
+Emitted by the seize function for compatibility (no actual slashing occurs).
+
+## Security Considerations
+
+1. **Owner Control**: The contract owner has complete control over the operator set
+2. **No Slashing**: Misbehavior cannot be punished through token slashing
+3. **Weight Decreases**: Include delay mechanism to prevent sudden operator removal
+4. **Gradual Changes**: Consolidation should be done gradually to maintain network stability
+
+## Integration Notes
+
+- WalletRegistry calls remain the same, ensuring minimal integration changes
+- Authorization flow maintains existing delay mechanisms
+- Event emissions preserve compatibility with monitoring systems
+- No changes required to operator client software
diff --git a/solidity/ecdsa/scripts/consolidate_beta_stakers.ts b/solidity/ecdsa/scripts/consolidate_beta_stakers.ts
diff --git a/solidity/ecdsa/test/Allowlist.test.ts b/solidity/ecdsa/test/Allowlist.test.ts
