feat(keyfunder): automate deployer sweeps (#7211)

Author: paulbalaji

typescript/infra/config/environments/mainnet3/funding.ts

@@ -6,6 +6,7 @@ import { Contexts } from '../../contexts.js';
 
 import desiredRebalancerBalances from './balances/desiredRebalancerBalances.json' with { type: 'json' };
 import desiredRelayerBalances from './balances/desiredRelayerBalances.json' with { type: 'json' };
+import lowUrgencyKeyFunderBalances from './balances/lowUrgencyKeyFunderBalance.json' with { type: 'json' };
 import { environment } from './chains.js';
 import { mainnet3SupportedChainNames } from './supportedChainNames.js';
 
@@ -23,6 +24,13 @@ const desiredRebalancerBalancePerChain = objMap(
   (_, balance) => balance.toString(),
 ) as Record<DesiredRebalancerBalanceChains, string>;
 
+type LowUrgencyKeyFunderBalanceChains =
+  keyof typeof lowUrgencyKeyFunderBalances;
+const lowUrgencyKeyFunderBalancePerChain = objMap(
+  lowUrgencyKeyFunderBalances,
+  (_, balance) => balance.toString(),
+) as Record<LowUrgencyKeyFunderBalanceChains, string>;
+
 export const keyFunderConfig: KeyFunderConfig<
   typeof mainnet3SupportedChainNames
 > = {
@@ -153,4 +161,10 @@ export const keyFunderConfig: KeyFunderConfig<
     soon: '0',
     sonicsvm: '0',
   },
+  // Low urgency key funder balance thresholds for sweep calculations
+  // Automatic sweep enabled by default for all chains with these thresholds
+  // Defaults: sweep to 0x478be6076f31E9666123B9721D0B6631baD944AF when balance > 2x threshold, leave 1.5x threshold
+  lowUrgencyKeyFunderBalances: lowUrgencyKeyFunderBalancePerChain,
+  // Per-chain overrides for sweep (optional)
+  sweepOverrides: {},
 };

typescript/infra/package.json

@@ -35,7 +35,8 @@
     "prompts": "^2.4.2",
     "tmp": "^0.2.3",
     "yaml": "2.4.5",
-    "yargs": "^17.7.2"
+    "yargs": "^17.7.2",
+    "zod": "^3.21.2"
   },
   "devDependencies": {
     "@hyperlane-xyz/tsconfig": "workspace:^",

typescript/infra/scripts/funding/fund-keys-from-deployer.ts

@@ -9,6 +9,7 @@ import {
   ChainName,
   HyperlaneIgp,
   MultiProvider,
+  defaultMultisigConfigs,
 } from '@hyperlane-xyz/sdk';
 import { Address, objFilter, objMap, rootLogger } from '@hyperlane-xyz/utils';
 
@@ -29,6 +30,8 @@ import {
   ContextAndRoles,
   ContextAndRolesMap,
   KeyFunderConfig,
+  SweepOverrideConfig,
+  validateSweepConfig,
 } from '../../src/config/funding.js';
 import { FundableRole, Role } from '../../src/roles.js';
 import {
@@ -51,6 +54,11 @@ import L1ScrollMessenger from './utils/L1ScrollMessenger.json' with { type: 'jso
 
 const logger = rootLogger.child({ module: 'fund-keys' });
 
+// Default sweep configuration
+const DEFAULT_SWEEP_ADDRESS = '0x478be6076f31E9666123B9721D0B6631baD944AF';
+const DEFAULT_TARGET_MULTIPLIER = 1.5; // Leave 1.5x threshold after sweep
+const DEFAULT_TRIGGER_MULTIPLIER = 2.0; // Sweep when balance > 2x threshold
+
 const nativeBridges = {
   scrollsepolia: {
     l1ETHGateway: '0x8A54A2347Da2562917304141ab67324615e9866d',
@@ -173,6 +181,12 @@ async function main() {
     Role.Deployer, // Always fund from the deployer
   );
 
+  // Load sweep overrides and low urgency balances from the environment config
+  const keyFunderConfig = config.keyFunderConfig;
+  const sweepOverrides = keyFunderConfig?.sweepOverrides;
+  const lowUrgencyKeyFunderBalances =
+    keyFunderConfig?.lowUrgencyKeyFunderBalances ?? {};
+
   let contextFunders: ContextFunder[];
 
   if (argv.f) {
@@ -187,6 +201,8 @@ async function main() {
         argv.desiredKathyBalancePerChain ?? {},
         argv.desiredRebalancerBalancePerChain ?? {},
         argv.igpClaimThresholdPerChain ?? {},
+        sweepOverrides,
+        lowUrgencyKeyFunderBalances,
         path,
       ),
     );
@@ -205,6 +221,8 @@ async function main() {
           argv.desiredKathyBalancePerChain ?? {},
           argv.desiredRebalancerBalancePerChain ?? {},
           argv.igpClaimThresholdPerChain ?? {},
+          sweepOverrides,
+          lowUrgencyKeyFunderBalances,
         ),
       ),
     );
@@ -267,6 +285,8 @@ class ContextFunder {
     public readonly igpClaimThresholdPerChain: KeyFunderConfig<
       ChainName[]
     >['igpClaimThresholdPerChain'],
+    public readonly sweepOverrides: ChainMap<SweepOverrideConfig> | undefined,
+    public readonly lowUrgencyKeyFunderBalances: ChainMap<string>,
   ) {
     // At the moment, only blessed EVM chains are supported
     roleKeysPerChain = objFilter(
@@ -318,6 +338,8 @@ class ContextFunder {
     igpClaimThresholdPerChain: KeyFunderConfig<
       ChainName[]
     >['igpClaimThresholdPerChain'],
+    sweepOverrides: ChainMap<SweepOverrideConfig> | undefined,
+    lowUrgencyKeyFunderBalances: ChainMap<string>,
     filePath: string,
   ) {
     logger.info({ filePath }, 'Reading identifiers and addresses from file');
@@ -392,6 +414,8 @@ class ContextFunder {
       desiredKathyBalancePerChain,
       desiredRebalancerBalancePerChain,
       igpClaimThresholdPerChain,
+      sweepOverrides,
+      lowUrgencyKeyFunderBalances,
     );
   }
 
@@ -415,6 +439,8 @@ class ContextFunder {
     igpClaimThresholdPerChain: KeyFunderConfig<
       ChainName[]
     >['igpClaimThresholdPerChain'],
+    sweepOverrides: ChainMap<SweepOverrideConfig> | undefined,
+    lowUrgencyKeyFunderBalances: ChainMap<string>,
   ) {
     // only roles that are fundable keys ie. relayer and kathy
     const fundableRoleKeys: Record<FundableRole, Address> = {
@@ -465,6 +491,8 @@ class ContextFunder {
       desiredKathyBalancePerChain,
       desiredRebalancerBalancePerChain,
       igpClaimThresholdPerChain,
+      sweepOverrides,
+      lowUrgencyKeyFunderBalances,
     );
   }
 
@@ -573,6 +601,22 @@ class ContextFunder {
       }
     }
 
+    // Attempt to sweep excess funds after all claim/funding operations are complete
+    // Only sweep when processing the Hyperlane context to avoid duplicate sweeps
+    if (this.context === Contexts.Hyperlane) {
+      try {
+        await this.attemptToSweepExcessFunds(chain);
+      } catch (err) {
+        logger.error(
+          {
+            chain,
+            error: err,
+          },
+          `Error sweeping excess funds on chain ${chain}`,
+        );
+      }
+    }
+
     if (failedKeys.length > 0) {
       throw new Error(
         `Failed to fund ${
@@ -619,6 +663,140 @@ class ContextFunder {
     }
   }
 
+  // Attempts to sweep excess funds to a given address when balance exceeds threshold.
+  // To avoid churning txs, only sweep when balance > triggerMultiplier * threshold,
+  // and leave targetMultiplier * threshold after sweep.
+  private async attemptToSweepExcessFunds(chain: ChainName): Promise<void> {
+    // Skip if the chain isn't in production yet i.e. if the validator set size is still 1
+    if (defaultMultisigConfigs[chain].validators.length === 1) {
+      logger.debug(
+        { chain },
+        'Chain is not in production yet, skipping sweep.',
+      );
+      return;
+    }
+
+    // Skip if we don't have a threshold configured for this chain
+    const lowUrgencyBalanceStr = this.lowUrgencyKeyFunderBalances[chain];
+    if (!lowUrgencyBalanceStr) {
+      logger.debug(
+        { chain },
+        'No low urgency balance configured for chain, skipping sweep',
+      );
+      return;
+    }
+
+    const lowUrgencyBalance = ethers.utils.parseEther(lowUrgencyBalanceStr);
+
+    // Skip if threshold is zero or negligible
+    if (lowUrgencyBalance.lte(0)) {
+      logger.debug({ chain }, 'Low urgency balance is zero, skipping sweep');
+      return;
+    }
+
+    // Get override config for this chain, if any
+    const override = this.sweepOverrides?.[chain];
+
+    // Use override or default sweep address
+    const sweepAddress = override?.sweepAddress ?? DEFAULT_SWEEP_ADDRESS;
+
+    // Use override or default multipliers
+    const targetMultiplier =
+      override?.targetMultiplier ?? DEFAULT_TARGET_MULTIPLIER;
+    const triggerMultiplier =
+      override?.triggerMultiplier ?? DEFAULT_TRIGGER_MULTIPLIER;
+
+    // If we have overrides, validate the full config with all overrides applied.
+    if (override) {
+      try {
+        validateSweepConfig({
+          sweepAddress,
+          targetMultiplier,
+          triggerMultiplier,
+        });
+      } catch (error) {
+        logger.error(
+          {
+            chain,
+            override,
+            error: format(error),
+          },
+          'Invalid sweep override configuration',
+        );
+        throw new Error(
+          `Invalid sweep override configuration for chain ${chain}: ${error}`,
+        );
+      }
+    }
+
+    // Calculate threshold amounts
+    const targetBalance = lowUrgencyBalance
+      .mul(Math.floor(targetMultiplier * 100))
+      .div(100);
+    const triggerThreshold = lowUrgencyBalance
+      .mul(Math.floor(triggerMultiplier * 100))
+      .div(100);
+
+    // Get current funder balance
+    const funderAddress = await this.multiProvider.getSignerAddress(chain);
+    const funderBalance = await this.multiProvider
+      .getSigner(chain)
+      .getBalance();
+
+    logger.info(
+      {
+        chain,
+        funderAddress,
+        funderBalance: ethers.utils.formatEther(funderBalance),
+        lowUrgencyBalance: ethers.utils.formatEther(lowUrgencyBalance),
+        targetBalance: ethers.utils.formatEther(targetBalance),
+        triggerThreshold: ethers.utils.formatEther(triggerThreshold),
+        targetMultiplier,
+        triggerMultiplier,
+      },
+      'Checking if sweep is needed',
+    );
+
+    // Only sweep if balance exceeds trigger threshold
+    if (funderBalance.gt(triggerThreshold)) {
+      const sweepAmount = funderBalance.sub(targetBalance);
+
+      logger.info(
+        {
+          chain,
+          sweepAmount: ethers.utils.formatEther(sweepAmount),
+          sweepAddress,
+          funderBalance: ethers.utils.formatEther(funderBalance),
+          remainingBalance: ethers.utils.formatEther(targetBalance),
+        },
+        'Sweeping excess funds',
+      );
+
+      const tx = await this.multiProvider.sendTransaction(chain, {
+        to: sweepAddress,
+        value: sweepAmount,
+      });
+
+      logger.info(
+        {
+          chain,
+          tx:
+            this.multiProvider.tryGetExplorerTxUrl(chain, {
+              hash: tx.transactionHash,
+            }) ?? tx.transactionHash,
+          sweepAmount: ethers.utils.formatEther(sweepAmount),
+          sweepAddress,
+        },
+        'Successfully swept excess funds',
+      );
+    } else {
+      logger.info(
+        { chain },
+        'Funder balance below trigger threshold, no sweep needed',
+      );
+    }
+  }
+
   // Attempts to claim from the IGP if the balance exceeds the claim threshold.
   // If no threshold is set, infer it by reading the desired balance and dividing that by 5.
   private async attemptToClaimFromIgp(chain: ChainName): Promise<void> {

typescript/infra/src/config/funding.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 import { ChainMap, ChainName } from '@hyperlane-xyz/sdk';
 
 import { Contexts } from '../../config/contexts.js';
@@ -29,8 +31,75 @@ export interface KeyFunderConfig<SupportedChains extends readonly ChainName[]>
   desiredRebalancerBalancePerChain: ChainMap<string>;
   igpClaimThresholdPerChain: ChainMap<string>;
   chainsToSkip: ChainName[];
+  // Per-chain overrides for automatic sweep of excess funds to Safes
+  // Defaults: sweep to 0x478be6076f31E9666123B9721D0B6631baD944AF when balance > 2x threshold, leave behind 1.5x threshold
+  sweepOverrides?: ChainMap<SweepOverrideConfig>;
+  // Low urgency key funder balance thresholds for sweep calculations
+  lowUrgencyKeyFunderBalances?: ChainMap<string>;
 }
 
 export interface CheckWarpDeployConfig extends CronJobConfig {
   registryCommit?: string;
 }
+
+// Zod validation schema for sweep override configuration
+export type SweepOverrideConfig = z.infer<typeof SweepOverrideConfigSchema>;
+
+const MIN_TRIGGER_DIFFERENCE = 0.05;
+const MIN_TARGET = 1.05;
+const MIN_TRIGGER = 1.1;
+const MAX_TARGET = 10.0;
+const MAX_TRIGGER = 200.0;
+
+const SweepOverrideConfigSchema = z
+  .object({
+    sweepAddress: z
+      .string()
+      .regex(
+        /^0x[a-fA-F0-9]{40}$/,
+        'sweepAddress must be a valid Ethereum address (0x-prefixed, 40 hex characters)',
+      )
+      .optional(),
+    targetMultiplier: z
+      .number()
+      .min(MIN_TARGET, `Target multiplier must be at least ${MIN_TARGET}`)
+      .max(MAX_TARGET, `Target multiplier must be at most ${MAX_TARGET}`)
+      .optional(),
+    triggerMultiplier: z
+      .number()
+      .min(MIN_TRIGGER, `Trigger multiplier must be at least ${MIN_TRIGGER}`)
+      .max(MAX_TRIGGER, `Trigger multiplier must be at most ${MAX_TRIGGER}`)
+      .optional(),
+  })
+  .refine(
+    (data) => {
+      // Check both provided
+      if (
+        typeof data.targetMultiplier === 'number' &&
+        typeof data.triggerMultiplier === 'number'
+      ) {
+        // Enforce: trigger multiplier must be at least MIN_TRIGGER_DIFFERENCE greater than target
+        return (
+          data.triggerMultiplier >=
+          data.targetMultiplier + MIN_TRIGGER_DIFFERENCE
+        );
+      }
+      return true;
+    },
+    {
+      message: `Trigger multiplier must be at least ${MIN_TRIGGER_DIFFERENCE} greater than target multiplier`,
+      path: ['triggerMultiplier'],
+    },
+  );
+
+/**
+ * Validates a single sweep override configuration using Zod schema.
+ * Ensures multipliers are within reasonable bounds and trigger > target.
+ *
+ * @param config - The sweep override configuration to validate
+ * @returns Validated SweepOverrideConfig
+ * @throws Error if validation fails with formatted error message
+ */
+export function validateSweepConfig(config: unknown): SweepOverrideConfig {
+  return SweepOverrideConfigSchema.parse(config);
+}