feat: separate typescript relayer package

[paulbalaji]

Summary

Extracts HyperlaneRelayer and ISM metadata builders from SDK into a standalone @hyperlane-xyz/relayer package with browser/Node.js separation.

Changes

• New @hyperlane-xyz/relayer package with dual exports:
  • Main export (@hyperlane-xyz/relayer): Browser-safe core relayer and metadata builders
  • /fs subpath (@hyperlane-xyz/relayer/fs): Node.js daemon with file-based config, cache persistence, and metrics
• Moved from SDK: HyperlaneRelayer, all ISM metadata builders (BaseMetadataBuilder, MultisigMetadataBuilder, etc.)
• Prometheus metrics wired to relayer events via unified observer pattern - tracks message success/failure, retries, backlog size, relay duration
• Uses shared @hyperlane-xyz/metrics package for metrics server (includes error handling)
• ESLint rule enforces no Node.js imports in browser-safe code
• Docker build with ncc bundling: 229MB vs 6.39GB monorepo image (28x smaller)
• Updated CLI/infra imports to use new package

Package Exports

Export	Description	Browser-safe
@hyperlane-xyz/relayer	Core relayer, metadata builders, config schema	Yes
@hyperlane-xyz/relayer/fs	RelayerService, loadConfig, metrics	No

Breaking Changes

Imports moved from @hyperlane-xyz/sdk to @hyperlane-xyz/relayer:

• HyperlaneRelayer, RelayerCacheSchema, messageMatchesWhitelist
• All metadata builders: BaseMetadataBuilder, MultisigMetadataBuilder, AggregationMetadataBuilder, etc.
• Types: MetadataBuilder, MetadataContext, StructuredMetadata

Note: offchainLookupRequestMessageHash remains in SDK for ccip-server compatibility (also re-exported from relayer).

Metrics

Metric	Type	Description
hyperlane_relayer_messages_total	Counter	Messages processed (origin, dest, status labels)
hyperlane_relayer_retries_total	Counter	Retry attempts
hyperlane_relayer_backlog_size	Gauge	Current message backlog
hyperlane_relayer_relay_duration_seconds	Histogram	Time to relay messages (relayer processing, not e2e)
hyperlane_relayer_messages_skipped_total	Counter	Messages filtered by whitelist
hyperlane_relayer_messages_already_delivered_total	Counter	Messages already delivered

Recent Changes (CR: yorke)

Addressed review feedback:

• Unified event system: Replaced RelayerEventCallbacks with discriminated union RelayerEvent type and single RelayerObserver.onEvent() callback - events now include full DispatchedMessage object
• Simplified RelayerConfig: Replaced class with loadConfig() function, uses zod schema directly
• Static factory pattern: Added RelayerService.create() async factory (preferred over constructor + init)
• Unified config: Single relayerConfig?: RelayerConfigInput instead of dual config objects
• Zod env validation: Added EnvSchema for environment variable parsing in daemon
• Removed unused mode: Eliminated mode: 'daemon' | 'manual' option
• Fixed README: Added missing addresses definition in example
• Restored comments: Re-added explanatory comments for parallelization strategy and whitelist logic
• Code organization: Extracted cache.ts, events.ts, whitelist.ts modules for cleaner separation

Note: Relay duration metrics intentionally use process time (not onchain timestamps) - the scraper tracks e2e latency while these metrics measure relayer processing performance specifically.

Testing

• pnpm build passes
• pnpm test passes
• Docker image builds successfully

[changeset-bot]

🦋 Changeset detected

Latest commit: 65784b4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages

Name	Type
@hyperlane-xyz/relayer	Minor
@hyperlane-xyz/cli	Minor
@hyperlane-xyz/sdk	Minor
@hyperlane-xyz/infra	Minor
@hyperlane-xyz/ccip-server	Minor
@hyperlane-xyz/helloworld	Minor
@hyperlane-xyz/http-registry-server	Minor
@hyperlane-xyz/keyfunder	Patch
@hyperlane-xyz/metrics	Patch
@hyperlane-xyz/rebalancer	Patch
@hyperlane-xyz/warp-monitor	Patch
@hyperlane-xyz/widgets	Minor
@hyperlane-xyz/aleo-sdk	Minor
@hyperlane-xyz/starknet-core	Minor
@hyperlane-xyz/cosmos-sdk	Minor
@hyperlane-xyz/cosmos-types	Minor
@hyperlane-xyz/eslint-config	Minor
@hyperlane-xyz/github-proxy	Minor
@hyperlane-xyz/radix-sdk	Minor
@hyperlane-xyz/tsconfig	Minor
@hyperlane-xyz/utils	Minor
@hyperlane-xyz/deploy-sdk	Patch
@hyperlane-xyz/provider-sdk	Patch

Not sure what this means? Click here to learn what changesets are.

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

[paulbalaji]

@greptileai

[greptile-apps]

_{50 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[coderabbitai]

Warning

Rate limit exceeded

@paulbalaji has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 38 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch pbio/relayer-package-extraction

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[hyper-gonk]

⚙️ Node Service Docker Images Built Successfully

Service	Tag
🔑 key-funder	9f52957-20260128-184349
🔍 offchain-lookup-server	9f52957-20260128-184349
♻️ rebalancer	9f52957-20260128-184349
🚀 ts-relayer	9f52957-20260128-184349
🕵️ warp-monitor	9f52957-20260128-184349

Full image paths

gcr.io/abacus-labs-dev/hyperlane-key-funder:9f52957-20260128-184349
gcr.io/abacus-labs-dev/hyperlane-offchain-lookup-server:9f52957-20260128-184349
gcr.io/abacus-labs-dev/hyperlane-rebalancer:9f52957-20260128-184349
gcr.io/abacus-labs-dev/hyperlane-ts-relayer:9f52957-20260128-184349
gcr.io/abacus-labs-dev/hyperlane-warp-monitor:9f52957-20260128-184349

[hyper-gonk]

🐳 Monorepo Docker Image Built Successfully

Service	Tag
📦 monorepo	9f52957-20260128-184345

Full image paths

gcr.io/abacus-labs-dev/hyperlane-monorepo:9f52957-20260128-184345

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.02%. Comparing base (b2b795b) to head (9f52957).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7671   +/-   ##
=======================================
  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.