DVT-FOCIL Integration Library

Distributed Validator Technology integration for FOCIL (EIP-7805)

This library enables DVT clusters (SSV Network, Anchor, Obol Charon) to participate in FOCIL inclusion list committees, providing censorship resistance for 15-25% of Ethereum stake that runs on distributed validators.

Problem Statement

FOCIL (Fork-Choice Enforced Inclusion Lists) assumes single-signer validators. DVT clusters face unique challenges:

1. Different mempool views - Each DVT node may see different pending transactions
2. Threshold signing - IL requires consensus before signing
3. No coordination mechanism - Current spec has no DVT-aware protocol

Solution

┌─────────────────────────────────────────────────────┐
│                 DVT Cluster (3-of-4)                │
├─────────────────────────────────────────────────────┤
│  Node 1      Node 2      Node 3      Node 4        │
│  (Anchor)    (Go-SSV)    (Anchor)    (Go-SSV)      │
│     │           │           │           │          │
│     └───────────┴─────┬─────┴───────────┘          │
│                       ▼                             │
│           ┌───────────────────────┐                │
│           │    IL Aggregator      │  ◄─ Union of   │
│           │   (Mempool Sync)      │     mempools   │
│           └───────────┬───────────┘                │
│                       ▼                             │
│           ┌───────────────────────┐                │
│           │   BFT Consensus       │  ◄─ IBFT/QBFT  │
│           │   (3-of-4 agreement)  │                │
│           └───────────┬───────────┘                │
│                       ▼                             │
│           ┌───────────────────────┐                │
│           │  Threshold Signature  │  ◄─ BLS agg   │
│           └───────────────────────┘                │
└─────────────────────────────────────────────────────┘

Features

• Client Agnostic: Works with any CL (Lighthouse, Prysm, Teku, Nimbus, Lodestar)
• Multi-DVT Support: Supports SSV Network (IBFT) and Obol Charon (QBFT)
• Aggregation Strategies: Union, threshold, majority, MEV-aware
• Engine API Integration: Aggregates engine_getInclusionListV1 across EL endpoints

Quick Start

use dvt_focil::{ClusterConfig, ILAggregator, consensus::IbftBackend};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load cluster configuration
    let config = ClusterConfig::from_file("dvt-focil.yaml")?;
    
    // Create IL aggregator
    let mut aggregator = ILAggregator::new(
        config.clone(),
        0, // this node's ID
        dvt_focil::aggregator::AggregationStrategy::Union,
    );
    
    // When selected for IL committee duty at slot N
    let slot = 1234567;
    let validator_index = 42;
    
    // Build inclusion list from aggregated mempool
    let il = aggregator.build_inclusion_list(slot, validator_index).await?;
    
    // Run BFT consensus
    let consensus = IbftBackend::new(0, vec![0, 1, 2, 3], 3);
    let result = consensus.propose(il).await?;
    
    println!("IL consensus reached!");
    Ok(())
}

Configuration

See examples/dvt-focil.yaml for a complete configuration example.

cluster:
  threshold: 3
  total_nodes: 4
  consensus_protocol: ibft  # 'ibft' for SSV/Anchor, 'qbft' for Charon

nodes:
  - id: node-1
    dvt_client: anchor
    beacon_node:
      type: lighthouse
      endpoint: http://localhost:5052
    execution_node:
      type: geth
      endpoint: http://localhost:8551

Architecture

Module	Description
aggregator	Mempool aggregation across DVT nodes
consensus	BFT consensus abstraction (IBFT/QBFT)
engine_api	Engine API client for EL interaction
config	Cluster configuration management
types	Core types (Transaction, IL, etc.)

DVT Backend Compatibility

Feature	SSV/Anchor (IBFT)	Obol Charon (QBFT)
Consensus Protocol	IBFT	QBFT
Feature Flag	--features ssv	--features charon
Leader Selection	Round-robin	Round-based w/ justification

EIP-7805 Compliance

This library implements the DVT extension for:

• engine_getInclusionListV1 - Fetch pending transactions
• engine_updatePayloadWithInclusionListV1 - Apply IL to payload
• SignedInclusionList - Threshold-signed IL broadcast

Timeline

• Target: FOCIL activation in Hegota upgrade (Q1 2027)
• Testnet: Q3 2026
• Mainnet: Post-Hegota activation

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

Contributing

Contributions welcome! Please read CONTRIBUTING.md.