[Feature Request]: Hyperlane Support

[mojtaba-esk]

Add Hyperlane Relayer Support to Tastora

Summary

Add support for the Hyperlane Relayer agent in Tastora's E2E testing framework. This is a prerequisite for enabling Hyperlane warp route E2E tests (see celestia-zkevm#306).

Scope: This issue focuses on getting the Hyperlane relayer agent running in a container. Contract deployment, warp route setup, and other Hyperlane features will be addressed in follow-up issues.

Requirements

Functional Requirements

1. Hyperlane Relayer Container Management

   • Create and manage Hyperlane relayer agent containers
   • Support lifecycle operations (start, stop, remove)
   • Handle container configuration and volume management
   • Implementation Note: All functionality should be supported by embedding a *container.Node

2. Configuration Management

   • Generate Hyperlane relayer configuration files from chain configs
   • Support custom configuration overrides via functional options
   • Implementation Note: Mirror the patterns from within the relayer package (like Hermes) to keep things consistent

Architecture

Follow the Hermes Relayer Pattern:

framework/docker/ibc/relayer/
├── hyperlane.go          # Main Hyperlane relayer implementation (composed of *container.Node)
├── hyperlane_config.go   # Configuration generation (similar to hermes_config.go)
├── hyperlane_types.go    # Type definitions
└── node_type.go          # NodeType implementation

Package Structure:

• Hyperlane relayer implementation should live in the relayer package (alongside Hermes)
• Full E2E tests that deploy multiple docker resources should live in the docker package

Implementation Pattern

The Hyperlane relayer should follow the same pattern as the Hermes relayer:

• Define a new type which is composed of a *container.Node
• Pass in a TastoraDockerClient during construction
• Use functional options pattern for configuration (like Hermes, no builder pattern needed initially)

Docker Image

Use the multi-stage Docker image pattern from celestia-zkevm:

• Base: node:24-slim with @hyperlane-xyz/cli installed
• Include hyp Go CLI (for Cosmos native support)
• Include Foundry (for EVM contract operations)

API Design

Basic Usage (Following Hermes Pattern)

// Create Hyperlane relayer (similar to Hermes)
hyperlane, err := relayer.NewHyperlane(ctx, dockerClient, testName, networkID, index, logger)
if err != nil {
    t.Fatal(err)
}
defer hyperlane.Remove(ctx)

// Initialize with chains (similar to Hermes.Init)
err = hyperlane.Init(ctx, []types.Chain{chainA, chainB}, func(config *relayer.HyperlaneConfig) {
    // apply modifications that are not the default
    // config.Chains[0].SomeSetting = "value"
    // config.Chains[1].SomeSetting = "value"
})

// Start the relayer agent
err = hyperlane.Start(ctx)

Configuration Pattern (Mirroring Hermes)

The configuration should follow the same pattern as Hermes, using functional options:

err = hyperlane.Init(ctx, []types.Chain{chainA, chainB}, func(config *relayer.HyperlaneConfig) {
    // apply a modification that is not the default
    // config.Chains[0].SomeSetting = "value"
})

Out of Scope (Future Issues)

• Contract deployment (core stack, warp routes)
• Mailbox creation and configuration
• ISM (Interchain Security Module) setup
• Warp route deployment
• Cross-chain message sending utilities
• E2E test for warp route validation (see celestia-zkevm#306)

Related Issues

• celestia-zkevm#306 - E2E test for basic Hyperlane warp route validation (depends on this issue)
• Reference: celestia-zkevm hyperlane README - Deployment guide showing relayer usage

[chatton]

Hyperlane Service Management

All of this should be supported by embedding a *container.Node

Multi-Chain Support

I think the first iteration can be just to support the zk usecase from the interop team now. I don't think supporting more use cases would add a lot of work, but I don't think it needs to be in scope for this issue.

Contract Deployment

Again let's focus on the one use case we have now before we fully generalize it, but again I think it probably looks the same.

Configuration Management

Let's try and mirror the patterns from within the relayer package if possible to keep things as consistent as possible.

I think the creation and wiring up of multiple chains can be done a similar fashion as the hermes relayer. Where it basically defines a new type which is composed of a *container.Node and is passed in a TastoraDockerClient.

The hermes relayer wasn't complex enough to need the builder pattern, but if there is a lot more configuration required for hyperlane I think we can use it. In hermes, linking 2 chains just looked like

	err = hermes.Init(ctx, []types.Chain{chainA, chainB}, func(config *relayer.HermesConfig) {
		// apply a modification that is not the default.
		config.Chains[0].ClockDrift = "6s"
		config.Chains[1].ClockDrift = "6s"
	})

It should probably live in the relayer package if possible, and then full E2E tests within tastora that deploy multiple docker resources can live in the docker package.

[chatton]

corresponding zk issue celestiaorg/celestia-zkevm#306