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_idfield is REQUIRED for proper network connectivity. Without it, your gateway will fail to connect to the network with handshake errors. Useoptimum_hoodi_v0_1for the official Hoodi testnet.
yaml
# 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
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
eth_topics_subscribe:
- /eth2/82556a32/beacon_block/ssz_snappy
- /eth2/82556a32/beacon_aggregate_and_proof/ssz_snappy
- /eth2/82556a32/attestation_subnet_0/ssz_snappyTopic Configuration
Default Configuration (Recommended)
For Hoodi testnet validators, use this comprehensive configuration that covers all critical topics:
yaml
eth_topics_subscribe:
- /eth2/82556a32/beacon_aggregate_and_proof/ssz_snappy
- /eth2/82556a32/beacon_block/ssz_snappy
- /eth2/82556a32/voluntary_exit/ssz_snappy
- /eth2/82556a32/proposer_slashing/ssz_snappy
- /eth2/82556a32/attester_slashing/ssz_snappy
- /eth2/82556a32/sync_committee_contribution_and_proof/ssz_snappy
- /eth2/82556a32/bls_to_execution_change/ssz_snappy
- /eth2/82556a32/blob_sidecar_0/ssz_snappy
- /eth2/82556a32/blob_sidecar_1/ssz_snappy
- /eth2/82556a32/blob_sidecar_2/ssz_snappy
- /eth2/82556a32/blob_sidecar_3/ssz_snappy
- /eth2/82556a32/blob_sidecar_4/ssz_snappy
- /eth2/82556a32/blob_sidecar_5/ssz_snappy
- /eth2/82556a32/blob_sidecar_6/ssz_snappy
- /eth2/82556a32/blob_sidecar_7/ssz_snappy
- /eth2/82556a32/blob_sidecar_8/ssz_snappy
- /eth2/82556a32/attestation_subnet_0/ssz_snappy
- /eth2/82556a32/attestation_subnet_1/ssz_snappy
- /eth2/82556a32/attestation_subnet_2/ssz_snappy
- /eth2/82556a32/attestation_subnet_3/ssz_snappy
- /eth2/82556a32/attestation_subnet_4/ssz_snappy
- /eth2/82556a32/attestation_subnet_5/ssz_snappy
- /eth2/82556a32/attestation_subnet_6/ssz_snappy
- /eth2/82556a32/attestation_subnet_7/ssz_snappy
- /eth2/82556a32/attestation_subnet_8/ssz_snappy
- /eth2/82556a32/attestation_subnet_9/ssz_snappy
- /eth2/82556a32/attestation_subnet_10/ssz_snappy
- /eth2/82556a32/attestation_subnet_11/ssz_snappy
- /eth2/82556a32/attestation_subnet_12/ssz_snappy
- /eth2/82556a32/attestation_subnet_13/ssz_snappy
- /eth2/82556a32/attestation_subnet_14/ssz_snappy
- /eth2/82556a32/attestation_subnet_15/ssz_snappy
- /eth2/82556a32/attestation_subnet_16/ssz_snappy
- /eth2/82556a32/attestation_subnet_17/ssz_snappy
- /eth2/82556a32/attestation_subnet_18/ssz_snappy
- /eth2/82556a32/attestation_subnet_19/ssz_snappy
- /eth2/82556a32/attestation_subnet_20/ssz_snappy
- /eth2/82556a32/attestation_subnet_21/ssz_snappy
- /eth2/82556a32/attestation_subnet_22/ssz_snappy
- /eth2/82556a32/attestation_subnet_23/ssz_snappy
- /eth2/82556a32/attestation_subnet_24/ssz_snappy
- /eth2/82556a32/attestation_subnet_25/ssz_snappy
- /eth2/82556a32/attestation_subnet_26/ssz_snappy
- /eth2/82556a32/attestation_subnet_27/ssz_snappy
- /eth2/82556a32/attestation_subnet_28/ssz_snappy
- /eth2/82556a32/attestation_subnet_29/ssz_snappy
- /eth2/82556a32/attestation_subnet_30/ssz_snappy
- /eth2/82556a32/attestation_subnet_31/ssz_snappy
- /eth2/82556a32/attestation_subnet_32/ssz_snappy
- /eth2/82556a32/attestation_subnet_33/ssz_snappy
- /eth2/82556a32/attestation_subnet_34/ssz_snappy
- /eth2/82556a32/attestation_subnet_35/ssz_snappy
- /eth2/82556a32/attestation_subnet_36/ssz_snappy
- /eth2/82556a32/attestation_subnet_37/ssz_snappy
- /eth2/82556a32/attestation_subnet_38/ssz_snappy
- /eth2/82556a32/attestation_subnet_39/ssz_snappy
- /eth2/82556a32/attestation_subnet_40/ssz_snappy
- /eth2/82556a32/attestation_subnet_41/ssz_snappy
- /eth2/82556a32/attestation_subnet_42/ssz_snappy
- /eth2/82556a32/attestation_subnet_43/ssz_snappy
- /eth2/82556a32/attestation_subnet_44/ssz_snappy
- /eth2/82556a32/attestation_subnet_45/ssz_snappy
- /eth2/82556a32/attestation_subnet_46/ssz_snappy
- /eth2/82556a32/attestation_subnet_47/ssz_snappy
- /eth2/82556a32/attestation_subnet_48/ssz_snappy
- /eth2/82556a32/attestation_subnet_49/ssz_snappy
- /eth2/82556a32/attestation_subnet_50/ssz_snappy
- /eth2/82556a32/attestation_subnet_51/ssz_snappy
- /eth2/82556a32/attestation_subnet_52/ssz_snappy
- /eth2/82556a32/attestation_subnet_53/ssz_snappy
- /eth2/82556a32/attestation_subnet_54/ssz_snappy
- /eth2/82556a32/attestation_subnet_55/ssz_snappy
- /eth2/82556a32/attestation_subnet_56/ssz_snappy
- /eth2/82556a32/attestation_subnet_57/ssz_snappy
- /eth2/82556a32/attestation_subnet_58/ssz_snappy
- /eth2/82556a32/attestation_subnet_59/ssz_snappy
- /eth2/82556a32/attestation_subnet_60/ssz_snappy
- /eth2/82556a32/attestation_subnet_61/ssz_snappy
- /eth2/82556a32/attestation_subnet_62/ssz_snappy
- /eth2/82556a32/attestation_subnet_63/ssz_snappyReward-sensitive topics: Attestation subnets are critical for validator rewards - missing these messages can result in penalties.
Hoodi testnet: All topics use the Hoodi fork digest 82556a32. The gateway supports all 64 attestation subnets (0-63).
Custom Topic Selection
If you need to customize your topic selection, you can modify the configuration based on your specific requirements:
yaml
eth_topics_subscribe:
# Standard topics
- /eth2/82556a32/beacon_block/ssz_snappy
- /eth2/82556a32/beacon_aggregate_and_proof/ssz_snappy
# Attestation subnet topics (optional)
- /eth2/82556a32/attestation_subnet_0/ssz_snappy
- /eth2/82556a32/attestation_subnet_1/ssz_snappy
# Range: 0-63 (64 total attestation subnet topics)
# Example: attestation_subnet_63/ssz_snappy for subnet 63Note: Attestation subnet range is 0-63 (64 topics total).
For Block Proposers
Add additional topics if you have proposing validators:
yaml
eth_topics_subscribe:
- /eth2/82556a32/beacon_block/ssz_snappy
- /eth2/82556a32/beacon_aggregate_and_proof/ssz_snappy
- /eth2/82556a32/voluntary_exit/ssz_snappy
- /eth2/82556a32/proposer_slashing/ssz_snappy
- /eth2/82556a32/attester_slashing/ssz_snappy
- /eth2/82556a32/blob_sidecar_0/ssz_snappy # For blob transactions
# Add more blob sidecars (0-8) if needed| 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. |
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/82556a32/beacon_block/ssz_snappy). |
Env Overrides
All YAML fields can be overridden via env (examples):
sh
OPT_GRPC_PORT=50051
OPT_LOG_LEVEL=info
OPT_AGENT_LIB_P2P_PORT=33212
OPT_AGENT_OPT_P2P_PORT=33213
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/82556a32/beacon_block/ssz_snappy,/eth2/82556a32/beacon_aggregate_and_proof/ssz_snappy
OPT_ENABLE_AGGREGATION=trueValidation
After starting your gateway, verify the configuration works:
Check Gateway Health
sh
# Should show your configured gateway_id
curl http://localhost:48123/metrics | grep gateway_idVerify Topic Subscriptions
sh
# Should show "successfully subscribed to topics"
docker logs optimum-gateway | grep "successfully subscribed"Check CL Client Connection
sh
# 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:
sh
# 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.
Common Issues
- Missing gateway_cluster_id: Gateway fails with handshake errors if
gateway_cluster_idis not set. Useoptimum_hoodi_v0_1 - Missing gateway_id: Gateway won't start if
gateway_idis not set - Missing enable_aggregation: OptP2P metrics will show 0 if
enable_aggregation: trueis not set. This is CRITICAL for proper OptP2P operation. Note: When aggregation is enabled, individual libp2p topic metrics become unavailable - Wrong fork digest: Use
82556a32for Hoodi testnet - Port conflicts: Ensure ports 33212, 33213, 48123 are available
- Proxy connectivity: Test with
nc -zv <proxy_host> 50051
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