Configuration

Prerequisites: Quick Start complete.

Basic Setup

Create config/app_conf.yml:

log_level: debug
gateway_cluster_id: optimum_hoodi_v0_3  # REQUIRED
gateway_id: "your_unique_identifier"
partner_id: "your_partner_id"           # REQUIRED

agent_lib_p2p_port: 33212
agent_opt_p2p_port: 43213
sidecar_listen_port: 33211
telemetry_port: 48123
identity_libp2p_dir: /tmp/libp2p
identity_optp2p_dir: /tmp/optp2p
telemetry_enable: true
enable_aggregation: true

# Remote push observability (credentials shared separately by the team)
remote_push_enable: true
remote_push_client_id: "<shared by team>"
remote_push_client_secret: "<shared by team>"

# chain defaults to hoodi — set chain: mainnet on mainnet
# chain: hoodi

# All topics — beacon_block + all 64 attestation subnets
eth_topics_subscribe:
  - beacon_block
  - beacon_attestation_0
  - beacon_attestation_1
  # ... through beacon_attestation_63

Ethereum Mainnet

Set chain: mainnet. If omitted, the gateway uses hoodi. Restart after changing.

chain: mainnet
gateway_id: "yourorg-region-mainnet-01"

/api/v1/self_info shows fork_digest; it reflects the fork and bootstrap and can change over time.

curl -s http://localhost:48123/api/v1/self_info | jq '.chain, .fork_digest'

Expect "mainnet" when running mainnet.

Hoodi: use the Basic Setup block above (chain default).

Direct CL Peers (Recommended for All Partners)

Lighthouse does not automatically reconnect to the gateway after a gateway restart. To fix this, configure direct_cl_peers in the gateway — this starts a dedicated goroutine that retries the connection until the CL peer is reachable again.

direct_cl_peers:
  - /ip4/192.168.1.2/tcp/9000/p2p/16Uiu2HAmGj6AoMKe7fNrghXwwRgivXLpji3Hkm4QEGVpsHZYKwPQ

Replace the IP, port, and peer ID with your CL node's libp2p multiaddr.

Why this matters: Prysm re-dials peers on its own, but Lighthouse and Nimbus do not reliably hold the gateway link after a gateway restart. Without direct_cl_peers, the CL can stay disconnected until the next manual intervention. We recommend all partners add their CL nodes as direct peers.

Lighthouse beacon node CLI: upstream help marks --libp2p-addresses as deprecated; use --boot-nodes for the same comma-delimited multiaddrs (multiaddr or ENR). See Beacon Node help.

To find your CL node's multiaddr:

• Lighthouse: curl -s http://localhost:5052/eth/v1/node/identity | jq '.data.p2p_addresses[0]'
• Prysm: curl -s http://localhost:3500/eth/v1/node/identity | jq '.data.p2p_addresses[0]'
• Nimbus: curl -s http://localhost:9596/eth/v1/node/identity | jq '.data.p2p_addresses[0]'

Topic Configuration

Short topic names – Use topic names without the fork digest prefix; the gateway resolves the full topic path automatically.

eth_topics_subscribe:
  - beacon_block
  - beacon_attestation_0
  - beacon_attestation_1
  # ... through beacon_attestation_63

Supported topics (RC12): beacon_block + all 64 attestation subnets (beacon_attestation_0 through beacon_attestation_63).

Gateway Pairing Mode

The gateway exposes a paired_with field (visible in /api/v1/self_info) that declares what the gateway is paired with. This controls whether inbound beacon blocks from mump2p are re-forwarded to the local CL. For partner deployments, the default value partner is used — no action needed.

Attestation forwarding is identical in all modes.

Attestation Subnet Boost

When attestation subnets are subscribed, the gateway forwards to mump2p only attestations from your partner's known validators — not every attestation the CL sees. The partner validator list is fetched from bootstrap every 5 minutes and cached.

• Non-partner attestations: dropped before reaching mump2p (saves ~98% of mump2p bandwidth vs forwarding everything)
• Stale attestations (>3 slots old): dropped
• Inbound attestations from mump2p: always forwarded to CL (trust upstream filter)

This is fully automatic — no extra config. If bootstrap is unreachable at startup, the gateway forwards nothing until the first successful sync.

Note: Attestation performance will improve further when selected-publish mode is enabled (currently multi-publish to all peers). This is planned for a future release.

Dynamic Configuration

Starting with RC7, the gateway receives automatic config updates from bootstrap.

• Polls for updates periodically
• Changes apply without restart
• Dynamic config includes: AB testing toggle, self-message skip, aggregation interval

Config Reference

Key	Env Variable	Default	Description
gateway_cluster_id	OPT_GATEWAY_CLUSTER_ID	(required)	Hoodi: optimum_hoodi_v0_3. Mainnet: your assigned cluster ID
chain	OPT_CHAIN	hoodi	mainnet for mainnet; defaults to hoodi
gateway_id	OPT_GATEWAY_ID	(required)	Unique gateway identifier
agent_lib_p2p_port	OPT_AGENT_LIB_P2P_PORT	33212	CL clients connect here
agent_opt_p2p_port	OPT_AGENT_OPT_P2P_PORT	43213	mump2p agent port
sidecar_listen_port	SIDECAR_PORT	33211	mump2p tracer (must be exposed)
telemetry_enable	OPT_ENABLE_TELEMETRY	false	Enable metrics endpoint
telemetry_port	OPT_TELEMETRY_PORT	48123	Metrics HTTP port
enable_aggregation	OPT_ENABLE_AGGREGATION	true	Batch messages for efficient transport
direct_cl_peers	OPT_DIRECT_CL_PEERS	(empty)	CL node multiaddrs for auto-reconnect
eth_topics_subscribe	OPT_ETH_TOPICS_SUBSCRIBE	(required)	Short topic names
partner_id	OPT_PARTNER_ID	required	Partner identifier
remote_push_enable	OPT_REMOTE_PUSH_ENABLE	false	Enable remote push to Mimir/Loki
remote_push_client_id	OPT_REMOTE_PUSH_CLIENT_ID	(empty)	CF Access client ID (shared by team)
remote_push_client_secret	OPT_REMOTE_PUSH_CLIENT_SECRET	(empty)	CF Access client secret (shared by team)

Full reference: See Quick Start config block.

Validation

curl http://localhost:48123/health
curl http://localhost:48123/metrics | grep gateway_id
docker logs optimum-gateway | grep "successfully subscribed"

Common Issues

• Mainnet gateway unhealthy, chain still hoodi in /api/v1/self_info – Set chain: mainnet and restart; gateway_cluster_id alone is not enough
• Missing gateway_cluster_id – Hoodi: optimum_hoodi_v0_3. Mainnet: your assigned ID
• Missing gateway_id – Required
• Port conflicts – Ensure 33211, 33212, 43213, 48123 are free
• No attestations flowing – Ensure all 64 beacon_attestation_* topics are in eth_topics_subscribe

See Troubleshooting for more.