Configuration

Prerequisites: Complete the Quick Start guide first to get your gateway running with basic settings.

Basic Setup

Create config/app_conf.yml with these essential settings:

⚠️ Important: The gateway_cluster_id field is REQUIRED for proper network connectivity. Without it, your gateway will fail to connect to the network with handshake errors. Use optimum_hoodi_v0_1 for the official Hoodi testnet.

# Basic settings
log_level: debug
gateway_cluster_id: optimum_hoodi_v0_1  # REQUIRED - Network cluster identifier
gateway_id: "your_unique_identifier"

# Suggested Gateway ID format:
# yourorg-region-hoodi-xx
# Example: optimum-eu-hoodi-01

# Network ports
agent_lib_p2p_port: 33212  # CL clients connect here
agent_opt_p2p_port: 33213  # Internal mump2p protocol communication
sidecar_listen_port: 33211 # Sidecar service for trace collection (must be exposed, not behind firewall)
telemetry_port: 48123      # Metrics endpoint

# Identity persistence (important!)
identity_libp2p_dir: /tmp/libp2p
identity_optp2p_dir: /tmp/optp2p

# Enable monitoring
telemetry_enable: true

# Message aggregation (CRITICAL for OptP2P metrics)
enable_aggregation: true  # REQUIRED - Enables OptP2P message processing and metrics

# AB-Testing (latency comparison between libp2p vs libp2p+mump2p)
enable_ab_testing: false  # DEFAULT: false - Set to true for A/B latency testing

# Proxy endpoints (provided by Optimum team)
proxy_host:
  - PROXY_HOST_1:50051 # Real proxy hosts will be provided
  - PROXY_HOST_2:50051 # Real proxy hosts will be provided
  - PROXY_HOST_3:50051 # Real proxy hosts will be provided

# Essential topics for Hoodi testnet
# NOTE: Currently only beacon_block is supported for focused metrics collection and validation
# Future releases will support additional topics (attestations, aggregates, etc.)
eth_topics_subscribe:
  - /eth2/c6ecb76c/beacon_block/ssz_snappy

Required Configuration for Latency Measurement

For AB-testing and latency measurement, the following setup is required:

• 2 gateways in distant regions (sufficient propagation time)
• Each gateway connected to its own beacon node only (single origin per measurement)
• Validator blocks published to only one gateway (as trusted peer)

Note: For basic Gateway functionality, a single gateway setup is sufficient.

Dynamic Configuration

Starting with RC7, the gateway receives automatic updates from Optimum's bootstrap server.

How It Works

• Gateway polls for config updates every minute
• Changes apply automatically without restart
• Operators don't need to take any action

AB-Testing Mode

The enable_ab_testing setting can be toggled remotely for network performance experiments.

enable_ab_testing: false  # Default, can be changed remotely

What it does:

• Even slots: libp2p only
• Odd slots: libp2p + Optimum network
• Enables A/B performance comparison

The Optimum team may enable this temporarily for network validation.

Fusaka Upgrade - Fork Digest Changes

Important: The Hoodi testnet has undergone the Fusaka upgrade with multiple BPO (Blob Parameter Only) forks:

• Initial Fusaka: Fork digest 82556a32 (deprecated)
• Fusaka BPO1: Fork digest ae9f70a0 (deprecated)
• Fusaka BPO2: Fork digest c6ecb76c (current - blob capacity 14 target / 21 max)

Current Network State: BPO2 has activated. Use fork digest c6ecb76c for all new configurations.

To verify your network's fork digest: Check your consensus client logs during startup or observe the first 8 characters in gossip topic paths from connected peers (e.g., /eth2/c6ecb76c/beacon_block/ssz_snappy).

eth_topics_subscribe:
  # Use c6ecb76c for current Hoodi (BPO2)
  # Currently only beacon_block is supported
  - /eth2/c6ecb76c/beacon_block/ssz_snappy

The gateway supports all Fusaka fork digests (82556a32, ae9f70a0, c6ecb76c) for backward compatibility.

Network Compatibility Improvements

Docker Host Mode: RC7 fixes connection issues when running with network_mode: host. The gateway now listens on all interfaces (0.0.0.0), accepting connections from localhost, Docker bridges, and external IPs.

IPv6 Support: Full IPv6 address handling for improved network connectivity.

Topic Configuration

Current Configuration (Beacon Block Only)

Important: RC8 currently supports only the beacon_block topic for focused metrics collection and validation. This allows us to:

• Focus metrics analysis - Single topic enables more precise latency and propagation measurements
• Better validation - Simplified data flow makes it easier to validate gateway behavior and network performance
• Improved debugging - Reduced complexity helps identify and resolve issues faster

Future releases will support additional topics including attestations, aggregates, and other Ethereum consensus topics. For now, configure only the beacon_block topic:

eth_topics_subscribe:
  # Currently only beacon_block is supported
  # Future releases will support additional topics (attestations, aggregates, etc.)
  - /eth2/c6ecb76c/beacon_block/ssz_snappy

Config Key	Env Variable	Default	Description
grpc_port	OPT_GRPC_PORT	50051	gRPC server port for inter-gateway communication.
version	(build-time only)	""	Injected at build via -ldflags, shown in /version.
commit_hash	(build-time only)	""	Git commit hash, injected at build.
log_level	OPT_LOG_LEVEL	debug	Log level (debug, info, warn, error).
use_direct_connections	OPT_USE_DIRECT_CONNECTIONS	false	Legacy flag for future; ignore for now.
identity_libp2p_dir	OPT_IDENTITY_LIBP2P_DIR	/tmp/libp2p	Directory to store libp2p identity (persist PeerID across restarts).
identity_optp2p_dir	OPT_IDENTITY_OPT_P2P_DIR	/tmp/optimum	Directory to store mump2p protocol identity.
agent_lib_p2p_port	OPT_AGENT_LIB_P2P_PORT	33212	Local libp2p agent listening port. CL clients connect here as peers.
agent_opt_p2p_port	OPT_AGENT_OPT_P2P_PORT	33213	mump2p protocol agent port. Used for mump2p overlay communication.
sidecar_listen_port	SIDECAR_PORT	33211	Sidecar gRPC service port for trace collection and visualization. Must be exposed (not behind firewall).
proxy_host	OPT_PROXY_HOST	(none, required)	One or more Optimum Proxy RPC hosts (host:port). Used to discover mump2p protocol nodes.
telemetry_enable	OPT_ENABLE_TELEMETRY	false	Enable telemetry server (Prometheus + /version).
telemetry_port	OPT_TELEMETRY_PORT	48123	Telemetry HTTP server port (if enabled).
gateway_id	OPT_GATEWAY_ID	(none if telemetry off)	Unique ID of this gateway. Required when telemetry is enabled.
gateway_cluster_id	OPT_GATEWAY_CLUSTER_ID	(none, required)	REQUIRED - Network cluster identifier. Use optimum_hoodi_v0_1 for official Hoodi testnet.
enable_aggregation	OPT_ENABLE_AGGREGATION	true	If true, aggregates non-critical topics before sending to mump2p protocol nodes.
eth_topics_subscribe	OPT_ETH_TOPICS_SUBSCRIBE	(none, required)	List of Ethereum CL topics to subscribe and bridge (must include fork digest, e.g. /eth2/ae9f70a0/beacon_block/ssz_snappy).

Env Overrides

All YAML fields can be overridden via env (examples):

OPT_GRPC_PORT=50051
OPT_LOG_LEVEL=info
OPT_AGENT_LIB_P2P_PORT=33212
OPT_AGENT_OPT_P2P_PORT=33213
SIDECAR_PORT=33211
OPT_IDENTITY_LIBP2P_DIR=/data/libp2p
OPT_IDENTITY_OPT_P2P_DIR=/data/optp2p
OPT_ENABLE_TELEMETRY=true
OPT_TELEMETRY_PORT=48123
OPT_GATEWAY_ID=my_gateway_1
OPT_PROXY_HOST=Optimum_Proxy_1:50051,Optimum_Proxy_1:50051
OPT_ETH_TOPICS_SUBSCRIBE=/eth2/c6ecb76c/beacon_block/ssz_snappy
OPT_ENABLE_AGGREGATION=true

Validation

After starting your gateway, verify the configuration works:

Check Gateway Health

# Should show your configured gateway_id
curl http://localhost:48123/metrics | grep gateway_id

Verify Topic Subscriptions

# Should show "successfully subscribed to topics"
docker logs optimum-gateway | grep "successfully subscribed"

Check CL Client Connection

# Replace 3500 with your CL client's API port
curl -s "http://localhost:3500/eth/v1/node/peers" | grep -c "connected"

Verify OptP2P Metrics

If enable_aggregation: true is set correctly, you should see active OptP2P metrics:

# Check if OptP2P aggregation is working (should show increasing numbers)
curl -s http://localhost:48123/metrics | grep "aggregation_messages_total"

# Check OptP2P peer connections (should show >0)
curl -s http://localhost:48123/metrics | grep "opt_peers"

# Check aggregated message flow (should show increasing numbers)
curl -s http://localhost:48123/metrics | grep "aggregation_included_total"

Important: When enable_aggregation: true, individual libp2p topic metrics are replaced by aggregated metrics:

• ❌ libp2p_total_messages (not available with aggregation)
• ❌ libp2p_published_messages_per_topic_total (not available with aggregation)
• ❌ optimum_published_messages_per_topic_total (not available with aggregation)
• ✅ aggregation_messages_total (available with aggregation)
• ✅ aggregation_included_total (available with aggregation)

For a complete metrics reference, see Metrics Documentation.

Add gateway peers – connect each CL client to all Gateways as a static peer.

• Restart CLs with the peer (hot-add might not survive reboots).

No connections showing? See CL Client Issues in our troubleshooting guide.

CL Client Configuration

Prysm

Prysm works well with basic trusted peer configuration:

--peer=/ip4/GATEWAY_IP/tcp/33212/p2p/GATEWAY_PEER_ID

Lighthouse (v8.x - Post-Fulu Fork)

⚠️ Important: Lighthouse v8.x requires additional configuration after the Fulu/PeerDAS fork (Dec 3, 2025).

Required flags for stable gateway connection:

--semi-supernode              # Required for stable peer connections post-Fulu
--target-peers=500            # Prevents peer pruning
--libp2p-addresses=/ip4/GATEWAY_IP/tcp/33212
--trusted-peers=GATEWAY_PEER_ID

Why these are needed:

• --semi-supernode: Lighthouse v8.x activates PeerDAS which changes peer requirements. Without this flag, Lighthouse may disconnect peers that don't participate in data column sampling.
• --target-peers=500: Default peer limit (~150) may cause Lighthouse to prune the gateway connection.

See Lighthouse PeerDAS Configuration in the troubleshooting guide for detailed explanation.

Common Issues

• Missing gateway_cluster_id: Gateway fails with handshake errors if gateway_cluster_id is not set. Use optimum_hoodi_v0_1
• Missing gateway_id: Gateway won't start if gateway_id is not set
• Missing enable_aggregation: OptP2P metrics will show 0 if enable_aggregation: true is not set. This is CRITICAL for proper OptP2P operation. Note: When aggregation is enabled, individual libp2p topic metrics become unavailable
• Wrong fork digest: Use c6ecb76c for Hoodi testnet (Fusaka BPO2)
• Port conflicts: Ensure ports 33211 (sidecar), 33212, 33213, 48123 are available
• Unsupported topics: Only beacon_block topic is currently supported. Other topics will be supported in future releases.
• Proxy connectivity: Test with nc -zv <proxy_host> 50051
• Lighthouse disconnections: Lighthouse v8.x users must add --semi-supernode and --target-peers=500 flags. See Lighthouse Configuration.

For detailed troubleshooting steps, see our Troubleshooting Guide.

Next Steps

Configuration complete! Here's what to do next:

• Set Up Monitoring - Monitor your gateway's performance with Grafana dashboards
• Troubleshooting - Solutions for common configuration issues
• Quick Start - Return to basic setup if you need to restart