feat: Charon

README.md

@@ -571,6 +571,33 @@ participants:
     # network parameter num_validator_keys_per_node
     validator_count: null
 
+  # Charon Distributed Validator Configuration
+    # The number of Charon nodes to create for distributed validation
+    # Each Charon node will run as a middleware between the beacon node and validator client
+    # Minimum 4 nodes recommended for fault tolerance
+    # Only used when vc_type is set to "charon"
+    # Defaults to 4
+    charon_node_count: 4
+
+    # Charon-specific parameters for distributed validator setup
+    # Only used when vc_type is set to "charon"
+    charon_params:
+      # The type of validator client to run with Charon
+      # Valid values are: lighthouse, lodestar, teku, nimbus, prysm
+      # Each Charon node will run this validator client type
+      # Defaults to "lighthouse"
+      charon_vc: lighthouse
+
+      # The Docker image for the validator client used with Charon
+      # This allows you to specify custom validator client images
+      # Defaults by client:
+      # - lighthouse: sigp/lighthouse:latest
+      # - lodestar: chainsafe/lodestar:latest
+      # - teku: consensys/teku:latest
+      # - nimbus: statusim/nimbus-validator-client:multiarch-latest
+      # - prysm: gcr.io/prysmaticlabs/prysm/validator:latest
+      charon_vc_image: sigp/lighthouse:latest
+
     # Whether to use a remote signer instead of the vc directly handling keys
     # Note Lighthouse VC does not support this flag
     # Defaults to false
@@ -2180,16 +2207,135 @@ participants:
       "/configs": "validator_config.json" # File available at: /configs/validator_config.json
 ```
 
+### Notes
+
+- All file paths must be relative to the package root directory
+- Files outside the package directory cannot be mounted directly
+- The entire directory structure is preserved when mounting directories
+
+## Charon Distributed Validator Technology (DVT)
+
+[Charon](https://github.com/ObolNetwork/charon) is a distributed validator middleware that enables fault-tolerant Ethereum validation by running validator duties across multiple nodes. This package supports deploying Charon clusters with any of the supported validator clients.
+
+### What is Distributed Validation?
+
+Distributed validation splits validator duties across multiple nodes (typically 4-7), providing:
+
+- **Fault Tolerance**: Continue validating even if some nodes go offline
+- **Reduced Slashing Risk**: Consensus mechanisms prevent double-signing
+- **Improved Uptime**: No single point of failure
+- **Decentralization**: Distribute validator operations across multiple operators
+
+### Charon Configuration
+
+To use Charon distributed validators, set `vc_type: charon` in your participant configuration:
+
+```yaml
+participants:
+  - el_type: geth
+    el_image: ethereum/client-go:latest
+    cl_type: lighthouse
+    cl_image: sigp/lighthouse:latest-unstable
+    use_separate_vc: true
+    # Charon Configuration
+    vc_type: charon
+    vc_image: obolnetwork/charon:latest
+    charon_node_count: 4
+    charon_params:
+      charon_vc: teku
+      charon_vc_image: consensys/teku:latest
+```
+
+### Supported Validator Clients with Charon
+
+All major Ethereum validator clients are supported with Charon:
+
+| Validator Client | Status | Implementation           | Notes                         |
+| ---------------- | ------ | ------------------------ | ----------------------------- |
+| **Lighthouse**   | ✅     | Two-stage health checks  | Default choice, most tested   |
+| **Lodestar**     | ✅     | Script-based execution   | Custom key management         |
+| **Teku**         | ✅     | Config file approach     | External signer mode          |
+| **Nimbus**       | ✅     | Two-service architecture | Key import + validator client |
+| **Prysm**        | ✅     | Wallet-based import      | Prysm wallet integration      |
+
+### Example Configurations
+
+#### Basic Charon Setup (4 nodes with Lighthouse)
+
+```yaml
+participants:
+  - vc_type: charon
+    vc_image: obolnetwork/charon:latest
+    charon_node_count: 4
+    charon_params:
+      charon_vc: lighthouse
+      charon_vc_image: sigp/lighthouse:latest-unstable
+```
+
+#### Mixed Network (Charon + Standard Validators)
+
+```yaml
+participants:
+  # Distributed validator with Charon
+  - vc_type: charon
+    charon_node_count: 4
+    charon_params:
+      charon_vc: prysm
+      charon_vc_image: gcr.io/prysmaticlabs/prysm/validator:latest
+  # Standard validator
+  - vc_type: lighthouse
+    vc_image: sigp/lighthouse:latest-unstable
+```
+
+### Running Charon Networks
+
+```bash
+# Create your network_params.yaml with Charon configuration
+kurtosis run --enclave charon-testnet github.com/ethpandaops/ethereum-package --args-file network_params.yaml
+```
+
+### Running Charon Networks from source code
+
+```bash
+# Create your network_params.yaml with Charon configuration
+kurtosis run . --args-file network_params_charon_example.yaml
+```
+
+
+### Charon Architecture
+
+When you deploy a Charon participant, the package creates:
+
+1. **Charon Cluster**: Multiple Charon nodes that form a distributed validator cluster
+2. **Validator Clients**: Each Charon node connects to a validator client of your chosen type
+3. **Key Distribution**: Validator keys are split and distributed across the Charon nodes
+4. **Consensus Layer**: All nodes connect to the same beacon node for chain data
+
+```
+Beacon Node
+     ↓
+┌─────────────────────────────────────┐
+│          Charon Cluster             │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ │
+│  │Charon-1 │ │Charon-2 │ │Charon-3 │ │
+│  │    ↓    │ │    ↓    │ │    ↓    │ │
+│  │ Teku VC │ │ Teku VC │ │ Teku VC │ │
+│  └─────────┘ └─────────┘ └─────────┘ │
+└─────────────────────────────────────┘
+```
+
 ## Beacon Node <> Validator Client compatibility
 
-|               | Lighthouse VC | Prysm VC | Teku VC | Lodestar VC | Nimbus VC
-|---------------|---------------|----------|---------|-------------|-----------|
-| Lighthouse BN | ✅            | ✅       | ✅      | ✅          | ✅
-| Prysm BN      | ✅            | ✅       | ✅      | ✅          | ✅
-| Teku BN       | ✅            | ✅       | ✅      | ✅          | ✅
-| Lodestar BN   | ✅            | ✅       | ✅      | ✅          | ✅
-| Nimbus BN     | ✅            | ✅       | ✅      | ✅          | ✅
-| Grandine BN   | ✅            | ✅       | ✅      | ✅          | ✅
+|               | Lighthouse VC | Prysm VC | Teku VC | Lodestar VC | Nimbus VC | Charon DVT |
+|---------------|---------------|----------|---------|-------------|-----------|------------|
+| Lighthouse BN | ✅            | ✅       | ✅      | ✅          | ✅        | ✅         |
+| Prysm BN      | ✅            | ✅       | ✅      | ✅          | ✅        | ✅         |
+| Teku BN       | ✅            | ✅       | ✅      | ✅          | ✅        | ✅         |
+| Lodestar BN   | ✅            | ✅       | ✅      | ✅          | ✅        | ✅         |
+| Nimbus BN     | ✅            | ✅       | ✅      | ✅          | ✅        | ✅         |
+| Grandine BN   | ✅            | ✅       | ✅      | ✅          | ✅        |            |
+
+**Note**: Charon DVT (Distributed Validator Technology) is compatible with all beacon node clients and can run any of the supported validator clients (Lighthouse, Lodestar, Teku, Nimbus, Prysm) in a distributed configuration.
 
 ## Custom labels for Docker and Kubernetes
 

kurtosis.yml

@@ -1 +1 @@
-name: "github.com/ethpandaops/ethereum-package"
+name: "github.com/ObolNetwork/ethereum-package"

main.star

@@ -530,6 +530,7 @@ def run(plan, args={}):
         network_id,
         osaka_time,
         shadowfork_block_height,
+        charon_metrics_jobs,
     ) = participant_network.launch_participant_network(
         plan,
         args_with_right_defaults,
@@ -549,6 +550,10 @@ def run(plan, args={}):
         detected_backend,
     )
 
+    # Charon clusters expose extra per-node/per-VC metrics endpoints that aren't
+    # captured by the single vc_context per participant; register them directly.
+    prometheus_additional_metrics_jobs.extend(charon_metrics_jobs)
+
     for p in all_participants:
         if p.el_context != None:
             plan.print(

network_params_charon_example.yaml

@@ -0,0 +1,168 @@
+participants:
+  # EL
+  - el_type: geth
+    el_image: ethereum/client-go:latest
+    # CL
+    cl_type: lighthouse
+    cl_image: sigp/lighthouse:latest-unstable
+    supernode: false
+    use_separate_vc: true
+    # Validator
+    vc_type: charon
+    vc_image: obolnetwork/charon:latest
+    charon_node_count: 4
+    charon_params:
+      charon_vc: teku
+      charon_vc_image: consensys/teku:latest
+    validator_count: null
+    use_remote_signer: false
+  - el_type: geth
+    el_image: ethereum/client-go:latest
+    # CL
+    cl_type: lighthouse
+    cl_image: sigp/lighthouse:latest-unstable
+    supernode: false
+    use_separate_vc: true
+    # Validator
+    vc_type: lighthouse
+    vc_image: sigp/lighthouse:latest-unstable
+    use_remote_signer: false
+  - el_type: geth
+    el_image: ethereum/client-go:latest
+    # CL
+    cl_type: lighthouse
+    cl_image: sigp/lighthouse:latest-unstable
+    supernode: false
+    use_separate_vc: true
+    # Validator
+    vc_type: lighthouse
+    vc_image: sigp/lighthouse:latest-unstable
+    use_remote_signer: false
+network_params:
+  network: kurtosis
+  network_id: "3151908"
+  deposit_contract_address: "0x00000000219ab540356cBB839Cbe05303d7705Fa"
+  seconds_per_slot: 12
+  num_validator_keys_per_node: 64
+  preregistered_validator_keys_mnemonic:
+    "giant issue aisle success illegal bike spike
+    question tent bar rely arctic volcano long crawl hungry vocal artwork sniff fantasy
+    very lucky have athlete"
+  preregistered_validator_count: 0
+  genesis_delay: 20
+  genesis_gaslimit: 30000000
+  max_per_epoch_activation_churn_limit: 8
+  churn_limit_quotient: 65536
+  ejection_balance: 16000000000
+  eth1_follow_distance: 2048
+  min_validator_withdrawability_delay: 256
+  shard_committee_period: 256
+  deneb_fork_epoch: 0
+  electra_fork_epoch: 0
+  fulu_fork_epoch: 18446744073709551615
+  network_sync_base_url: https://snapshots.ethpandaops.io/
+  force_snapshot_sync: false
+  samples_per_slot: 8
+  custody_requirement: 4
+  max_blobs_per_block_electra: 9
+  target_blobs_per_block_electra: 6
+  base_fee_update_fraction_electra: 5007716
+  additional_preloaded_contracts: {}
+  devnet_repo: ethpandaops
+  prefunded_accounts: {}
+additional_services: []
+dora_params:
+  image: ""
+tx_fuzz_params:
+  tx_fuzz_extra_args: []
+spamoor_params:
+  min_cpu: 100
+  max_cpu: 1000
+  min_mem: 20
+  max_mem: 300
+  extra_args: []
+prometheus_params:
+  storage_tsdb_retention_time: "1d"
+  storage_tsdb_retention_size: "512MB"
+  min_cpu: 10
+  max_cpu: 1000
+  min_mem: 128
+  max_mem: 2048
+grafana_params:
+  additional_dashboards: []
+  min_cpu: 10
+  max_cpu: 1000
+  min_mem: 128
+  max_mem: 2048
+assertoor_params:
+  image: ""
+  run_stability_check: false
+  run_block_proposal_check: false
+  run_transaction_test: false
+  run_blob_transaction_test: false
+  run_opcodes_transaction_test: false
+  run_lifecycle_test: false
+  tests: []
+wait_for_finalization: false
+global_log_level: info
+snooper_enabled: false
+ethereum_metrics_exporter_enabled: false
+parallel_keystore_generation: false
+disable_peer_scoring: false
+persistent: false
+mev_type: null
+mev_params:
+  mev_relay_image: ethpandaops/mev-boost-relay:main
+  mev_builder_image: ethpandaops/flashbots-builder:main
+  mev_builder_cl_image: sigp/lighthouse:latest
+  mev_boost_image: ethpandaops/mev-boost:develop
+  mev_boost_args: ["mev-boost", "--relay-check"]
+  mev_relay_api_extra_args: []
+  mev_relay_housekeeper_extra_args: []
+  mev_relay_website_extra_args: []
+  mev_builder_extra_args: []
+  mev_builder_prometheus_config:
+    scrape_interval: 15s
+    labels: {}
+  custom_flood_params:
+    interval_between_transactions: 1
+xatu_sentry_enabled: false
+xatu_sentry_params:
+  xatu_sentry_image: ethpandaops/xatu-sentry
+  xatu_server_addr: localhost:8000
+  xatu_server_tls: false
+  xatu_server_headers: {}
+  beacon_subscriptions:
+    - attestation
+    - block
+    - chain_reorg
+    - finalized_checkpoint
+    - head
+    - voluntary_exit
+    - contribution_and_proof
+    - blob_sidecar
+apache_port: 40000
+global_tolerations: []
+global_node_selectors: {}
+keymanager_enabled: false
+checkpoint_sync_enabled: false
+checkpoint_sync_url: ""
+ethereum_genesis_generator_params:
+  image: ethpandaops/ethereum-genesis-generator:4.0.4
+port_publisher:
+  nat_exit_ip: KURTOSIS_IP_ADDR_PLACEHOLDER
+  el:
+    enabled: false
+    public_port_start: 32000
+  cl:
+    enabled: false
+    public_port_start: 33000
+  vc:
+    enabled: false
+    public_port_start: 34000
+  remote_signer:
+    enabled: false
+    public_port_start: 35000
+  additional_services:
+    enabled: false
+    public_port_start: 36000

src/package_io/constants.star

@@ -31,6 +31,8 @@ VC_TYPE = struct(
     vero="vero",
     grandine="grandine",
     consensoor="consensoor",
+    charon="charon",
+    vouch="vouch",
 )
 
 REMOTE_SIGNER_TYPE = struct(web3signer="web3signer")
@@ -72,6 +74,7 @@ LITTLE_BIGTABLE_PORT_ID = "littlebigtable"
 VALIDATOR_GRPC_PORT_ID = "grpc"
 
 VALIDATING_REWARDS_ACCOUNT = "0x8943545177806ED17B9F23F0a21ee5948eCaa776"
+CHARON_WITHDRAWAL_ADDRESS = "0xBc7c960C1097ef1Af0FD32407701465f3c03e407"
 MAX_ENR_ENTRIES = 20
 MAX_ENODE_ENTRIES = 20
 MIN_PEERS = 0