LogoLogo
SDKAPI
Version-v1.4.0 (current)
Version-v1.4.0 (current)
  • Learn
    • Introduction
      • Obol Collective
      • OBOL Incentives
      • Key Staking Concepts
      • Obol vs Other DV Implementations
      • Obol Splits
      • DV Launchpad
      • Frequently Asked Questions
    • Charon
      • Introduction to Charon
      • Distributed Key Generation
      • Cluster Configuration
      • Charon Networking
      • CLI Reference
    • Futher Reading
      • Ethereum and Its Relationship With DVT
      • Community Testing
      • Peer Score
      • Useful Links
  • Run a DV
    • Quickstart
      • Quickstart Overview
      • Create a DV Alone
      • Create a DV With a Group
      • Push Metrics to Obol Monitoring
    • Prepare to Run a DV
      • How and Where To Run DVs
      • Deployment Best Practices
      • Test a Cluster
    • Running a DV
      • Activate a DV
      • Update a DV
      • Monitoring Your Node
      • Claim Rewards
      • Exit a DV
    • Partner Integrations
      • Create an EigenLayer DV
      • Create a Lido CSM DV
      • DappNode
  • Advanced & Troubleshooting
    • Advanced Guides
      • Create a DV Using the SDK
      • Migrate an Existing Validator
      • Enable MEV
      • Combine DV Private Key Shares
      • Self-Host a Relay
      • Advanced Docker Configs
      • Beacon node authentication
    • Troubleshooting
      • Errors & Resolutions
      • Handling DKG Failure
      • Client Configuration
      • Test Commands
    • Security
      • Overview
      • Centralization Risks and Mitigation
      • Obol Bug Bounty Program
      • Smart Contract Audit
      • Software Development at Obol
      • Charon Threat Model
      • Contacts
  • Community & Governance
    • Governance
      • Collective Overview
      • The Token House
      • The RAF
      • Delegate Guide
      • RAF1 Guide
    • The OBOL Token
      • Token Utility
      • Token Distribution & Liquidity
      • TGE FAQ
    • Community
      • Staking Mastery Program
      • Techne
    • Contribution & Feedback
      • Filing a Bug Report
      • Documentation Standards
      • Feedback
  • Walkthrough Guides
    • Walkthroughs
      • Walkthrough Guides
  • SDK
    • Intro
    • Enumerations
      • FORK_MAPPING
    • Classes
      • Client
    • Interfaces
      • ClusterDefinition
      • RewardsSplitPayload
    • Type-Aliases
      • BuilderRegistration
      • BuilderRegistrationMessage
      • ClusterCreator
      • ClusterLock
      • ClusterOperator
      • ClusterPayload
      • ClusterValidator
      • DepositData
      • DistributedValidator
      • ETH_ADDRESS
      • OperatorPayload
      • SplitRecipient
      • TotalSplitPayload
    • Functions
      • validateClusterLock
  • API
    • What is this API?
    • System
    • Metrics
    • Cluster Definition
    • Cluster Lock
    • State
    • DV Exit
    • Cluster Effectiveness
    • Terms And Conditions
    • Techne Credentials
    • Address
    • OWR Information
  • Specification
Powered by GitBook
On this page
  • Charon networking
  • Overview​
  • Internal Validator Stack​
  • External P2P Network​
Edit on GitHub
  1. Learn
  2. Charon

Charon Networking

PreviousCluster ConfigurationNextCLI Reference

Last updated 5 days ago

Charon networking

Overview

This document describes Charon's networking model which can be divided into two parts: the and the .

Internal Validator Stack

Charon is a middleware DVT client and is therefore connected to an upstream beacon node and a downstream validator client is connected to it. Each operator should run the whole validator stack (all 4 client software types), either on the same machine or on different machines. The networking between the nodes should be private and not exposed to the public internet.

Related Charon configuration flags:

  • --beacon-node-endpoints: Connects Charon to one or more beacon nodes.

  • --validator-api-address: Address for Charon to listen on and serve requests from the validator client.

  • --p2p-tcp-addresses: Addresses for Charon to listen on and serve p2p requests.

  • --p2p-relays: Connect Charon to one or more relay servers.

  • --private-key-file: Private key identifying the Charon client.

Each Charon node's secp256k1 private key is critical for authentication and must be kept secure to prevent cluster compromise.

Do not use the same key across multiple clusters, as this can lead to security issues.

Note that in order for two peers to discover each other, they must connect to the same relay. Cluster operators should therefore coordinate which relays to use.

  • --p2p-external-ip: Explicitly sets the external IP address.

  • --p2p-external-hostname: Explicitly sets the external DNS host name.

If a pair of Charon clients are not publicly accessible, due to being behind a NAT, they will not be able to upgrade their relay connections to a direct connection. Even though this is supported, it isn’t recommended as relay connections introduce additional latency and reduced throughput and will result in decreased validator effectiveness and possible missed block proposals and attestations.

Libp2p’s circuit-relay connections are end-to-end encrypted, even though relay servers accept connections between nodes from multiple different clusters, relays are merely routing opaque connections. And since Charon only accepts incoming connections from other peers in its cluster, the use of a relay doesn’t allow connections between clusters.

Only the following three libp2p protocols are established between a Charon node and a relay itself:

All other Charon protocols are only established between nodes in the same cluster.

The relay supports serving its runtime public multiaddrs via its --http-address flag.

The charon --p2p-relays flag therefore supports both multiaddrs as well as HTTP URls.

External P2P Network

The Charon clients in a DV cluster are connected to each other via a small p2p network consisting of only the clients in the cluster. Peer IP addresses are discovered via an external "relay" server. The p2p connections are over the public internet so the Charon p2p port must be publicly accessible. Charon leverages the popular protocol.

Related :

LibP2P Authentication and Security

Each Charon client has a secp256k1 private key. The associated public key is encoded into the to identify the nodes in the cluster. For ease of use and to align with the Ethereum ecosystem, Charon encodes these public keys in the , not in .

For more on p2p security, refer to .

Charon currently only supports libp2p tcp connections with security and only accepts incoming libp2p connections from peers defined in the cluster lock.

LibP2P Relays and Peer Discovery

Relays are simple libp2p servers that are publicly accessible supporting the protocol. Circuit-relay is a libp2p transport protocol that routes traffic between two peers over a third-party “relay” peer.

Obol hosts a publicly accessible relay at and will work with other organisations in the community to host alternatives Anyone can host their own relay server for their DV cluster.

Each Charon node knows which peers are in the cluster from the ENRs in the cluster lock file, but their IP addresses are unknown. By connecting to the same relay, nodes establish “relay connections” to each other. Once connected via relay they exchange their known public addresses via libp2p’s protocol. The relay connection is then upgraded to a direct connection. If a node’s public IP changes, nodes once again connect via relay, exchange the new IP, and then connect directly once again.

Libp2p’s protocol attempts to automatically detect the public IP address of a Charon client without the need to explicitly configure it. If this however fails, the following two configuration flags can be used to explicitly set the publicly advertised address:

: To establish relay e2e encrypted connections between two peers in a cluster.

: Auto-detection of public IP addresses to share with other peers in the cluster.

: Exchanges basic application for improved operational metrics and observability.\

Scalable Relay Clusters

In order for a Charon client to connect to a relay, it needs the relay's (containing its public key and IP address). But a single multiaddr can only point to a single relay server which can easily be overloaded if too many clusters connect to it. Charon therefore supports resolving a relay’s multiaddr via HTTP GET request. Since Charon also includes the unique cluster-hash header in this request, the relay provider can use to map clusters to one of many relays using a single HTTP address.

E.g., is actually a load-balancer that routes HTTP requests to one of many relays based on the cluster-hash header returning the target relay’s multiaddr which the Charon client then uses to connect to that relay.

​
libp2p
Charon configuration flags
​
cluster lock file
ENR format
libp2p’s Peer ID format
libp2p's article
noise
​
circuit-relay
https://0.relay.obol.tech
identify
identify
circuit-relay
identify
peerinfo
metadata
​
multiaddr
consistent header-based load-balancing
https://0.relay.obol.tech
​
internal validator stack
external p2p network
​