Skip to content

Comments

feat(infra): migrate keyfunder to standalone Docker package#7718

Closed
paulbalaji wants to merge 6 commits intomainfrom
pbio/standalone-keyfunder
Closed

feat(infra): migrate keyfunder to standalone Docker package#7718
paulbalaji wants to merge 6 commits intomainfrom
pbio/standalone-keyfunder

Conversation

@paulbalaji
Copy link
Collaborator

@paulbalaji paulbalaji commented Jan 7, 2026

Summary

Migrates the keyfunder from embedded infra code to a standalone package at typescript/keyfunder/ with its own Docker image. This follows the pattern established by ccip-server (#7565), rebalancer (#7545), and warp-monitor (#7653).

Linear Issues

  • ENG-2985 - Create standalone keyfunder package
  • ENG-2986 - Add Docker workflow for keyfunder image
  • ENG-2987 - Migrate infra to standalone keyfunder package

Key Changes

New Standalone Package (typescript/keyfunder/)

  • Config-driven: Reads YAML configuration from --config flag or KEYFUNDER_CONFIG_FILE env var
  • Registry integration: Uses REGISTRY_URI for chain metadata with commit pinning support
  • RPC overrides: Per-chain RPC URLs via RPC_URL_<CHAIN_UPPER_SNAKE> env vars
  • Simplified design: Removed L2 bridging - keyfunder is now a pure fund dispersal tool
  • No GCP SDK: All secrets injected via K8s ExternalSecrets
  • Prometheus metrics: Push gateway pattern for CronJob compatibility
  • Package-level turbo.json: Ensures build runs before bundle (matches rebalancer pattern)

Config Structure (Option A: Global Roles)

Roles define WHO (address once), chains define HOW MUCH (balances reference role names):

version: '1'

roles:
  hyperlane-relayer:
    address: '0x74cae0ecc47b02ed9b9d32e000fd70b9417970c5'
  hyperlane-kathy:
    address: '0x5fb02f40f56d15f0442a39d11a23f73747095b20'

chains:
  ethereum:
    balances:
      hyperlane-relayer: '0.5'
      hyperlane-kathy: '0.4'
    igp:
      address: '0x6cA0B6D43F8e45C82e57eC5a5F2Bce4bF2b6F1f7'
      claimThreshold: '0.2'
    sweep:
      enabled: true
      address: '0x478be6076f31E9666123B9721D0B6631baD944AF'
      threshold: '0.3'
  arbitrum:
    balances:
      hyperlane-relayer: '0.1'

funder:
  privateKeyEnvVar: 'FUNDER_PRIVATE_KEY'
metrics:
  pushGateway: 'http://prometheus-pushgateway:9091'
  jobName: 'keyfunder-mainnet3'

Helm Chart Updates (typescript/infra/helm/key-funder/)

  • New ConfigMap template for keyfunder.yaml config content
  • Updated CronJob to run standalone Docker image
  • Simplified ExternalSecret (just funder key + RPC URLs)
  • Removed addresses-external-secret.yaml (addresses now in config YAML)

Infra Package Updates

  • KeyFunderHelmManager.forEnvironment() now requires registryCommit parameter
  • Added generateKeyfunderYaml() method to transform legacy environment config
  • deploy-key-funder.ts now uses .registryrc as default with override option

CI/CD

  • Added .github/workflows/keyfunder-docker.yml - builds and pushes gcr.io/abacus-labs-dev/hyperlane-keyfunder
  • Triggers on changes to typescript/keyfunder/** or manual dispatch
  • Comments image tags on PRs

Misc

  • Added .opencode/ to root .gitignore

Deleted

  • fund-keys-from-deployer.ts (37KB legacy script)
  • addresses-external-secret.yaml (addresses embedded in config)

Testing

  • 39 unit tests passing (Zod schemas, config loader, metrics)
  • pnpm build passes
  • pnpm lint passes
  • pnpm bundle produces working bundle
  • Docker workflow builds successfully in CI
  • Deploy to testnet4 for validation

Commits

  1. a128253b0 - feat(infra): migrate keyfunder to standalone Docker package
  2. 21e0afa4f - refactor(keyfunder): use global roles with per-chain balances
  3. bb53853c4 - fix: add keyfunder package.json COPY to Dockerfile
  4. a030115af - ci: add keyfunder Docker build workflow
  5. b8d2f02f3 - fix(keyfunder): add package turbo.json to ensure build runs before bundle
  6. b093a7a96 - feat(infra): use .registryrc as default for deploy-key-funder with override option

Migrates the keyfunder from embedded infra code to a standalone package
at typescript/keyfunder/ with its own Docker image, following the pattern
established by ccip-server, rebalancer, and warp-monitor.

Key changes:
- New standalone package with config-driven YAML configuration
- Removed L2 bridging - keyfunder is now a pure fund dispersal tool
- No GCP SDK dependency - secrets injected via K8s ExternalSecrets
- Uses Prometheus push gateway for metrics (CronJob pattern)
- Registry URI with commit pinning via REGISTRY_URI env var
- RPC overrides via RPC_URL_<CHAIN> env vars

Helm chart updates:
- ConfigMap for keyfunder.yaml config
- Updated CronJob to run standalone Docker image
- Simplified ExternalSecret for funder key and RPC URLs

Deleted:
- fund-keys-from-deployer.ts (37KB legacy script)
- addresses-external-secret.yaml (addresses now in config YAML)
@changeset-bot
Copy link

changeset-bot bot commented Jan 7, 2026

⚠️ No Changeset found

Latest commit: 532846b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Config now uses a 'roles' section to define addresses once, and chains
reference role names in their 'balances' map. This simplifies config
management for roles that use the same address across all chains
(relayer, kathy, rebalancer).

Before (address repeated per chain):
  chains:
    ethereum:
      keys:
        - address: '0x...'
          role: 'relayer'
          desiredBalance: '0.5'
    arbitrum:
      keys:
        - address: '0x...'  # same address repeated
          role: 'relayer'
          desiredBalance: '0.1'

After (address defined once):
  roles:
    hyperlane-relayer:
      address: '0x...'
  chains:
    ethereum:
      balances:
        hyperlane-relayer: '0.5'
    arbitrum:
      balances:
        hyperlane-relayer: '0.1'
@paulbalaji paulbalaji force-pushed the pbio/standalone-keyfunder branch from c4759af to e57e92c Compare January 7, 2026 16:42
@paulbalaji paulbalaji force-pushed the pbio/standalone-keyfunder branch from e57e92c to b8d2f02 Compare January 7, 2026 16:43
@paulbalaji paulbalaji force-pushed the pbio/standalone-keyfunder branch from b093a7a to 532846b Compare January 7, 2026 17:17
@hyper-gonk
Copy link
Contributor

hyper-gonk bot commented Jan 7, 2026

🔑 KeyFunder Docker Image Built Successfully

Image Tags:

gcr.io/abacus-labs-dev/hyperlane-keyfunder:pr-7718
gcr.io/abacus-labs-dev/hyperlane-keyfunder:532846b-20260107-171825

@hyper-gonk
Copy link
Contributor

hyper-gonk bot commented Jan 7, 2026

🐳 Monorepo Docker Image Built Successfully

Image Tags:

gcr.io/abacus-labs-dev/hyperlane-monorepo:pr-7718
gcr.io/abacus-labs-dev/hyperlane-monorepo:532846b-20260107-171813

@paulbalaji
Copy link
Collaborator Author

@paulbalaji paulbalaji closed this Jan 7, 2026
@github-project-automation github-project-automation bot moved this from In Review to Done in Hyperlane Tasks Jan 7, 2026
@codecov
Copy link

codecov bot commented Jan 7, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.02%. Comparing base (e4fed47) to head (532846b).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #7718   +/-   ##
=======================================
  Coverage   77.02%   77.02%           
=======================================
  Files         117      117           
  Lines        2651     2651           
  Branches      244      244           
=======================================
  Hits         2042     2042           
  Misses        593      593           
  Partials       16       16           
Components Coverage Δ
core 87.80% <ø> (ø)
hooks 71.86% <ø> (ø)
isms 81.10% <ø> (ø)
token 86.67% <ø> (ø)
middlewares 84.98% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant