Skip to main content

Middleware Architecture

Relay Contracts are built on a modular architecture with five core modules that work together to manage validator networks. This design provides flexibility while maintaining clear separation of concerns.

Modules​

Network​

Purpose: Standard contract for Symbiotic ecosystem integration

  • Provides verifiable delays for network actions (middleware changes, resolver changes)
  • Serves as the "network" address across the Symbiotic ecosystem
  • Enables standardized network lifecycle management

Key Interface: Basic network registration and configuration

VotingPowerProvider​

Purpose: Manages operator and vault voting power with extensible rules

  • Connects to Symbiotic Core's OperatorRegistry and VaultFactory
  • Calculates voting power based on stake and configured rules
  • Supports modular extensions for operator onboarding, slashing, rewards
  • Handles operator registration and key management integration

Key Features:

  • Flexible voting power calculation strategies
  • Extensive extension system for custom behavior
  • Integration with vault stake and operator management

KeyRegistry​

Purpose: Verifies and manages operators' cryptographic keys

  • Supports multiple key types: BLS BN254, ECDSA SECP256K1
  • Handles key registration, verification, and lifecycle management
  • Provides cryptographic primitives for signature verification
  • Integrates with operator identity management

Supported Key Types:

  • BlsBn254: Efficient for signature aggregation, ideal for consensus
  • EcdsaSecp256k1: Standard Ethereum keys, widely supported

ValSetDriver​

Purpose: Drives validator set derivation and maintenance for off-chain components

  • Provides the main integration point for Relay binary nodes
  • Manages epoch-based validator set transitions
  • Combines voting power data with key registry information
  • Enables validator set queries and historical access

Core Responsibility: Bridge between on-chain stake/power and off-chain consensus

Settlement​

Purpose: Commits compressed validator sets and verifies signatures

  • Requires validator set headers to be committed each epoch
  • Provides signature verification against committed validator sets
  • Supports deployment on multiple blockchains for cross-chain validation
  • Offers different verification mechanisms based on validator set size

Verification Types:

  • SimpleVerifier: Best for up to ~125 validators, requires full validator set input
  • ZKVerifier: Constant gas cost using gnark-based ZK proofs, supports larger sets

Module Interactions​

The modules work together in a coordinated flow:

Symbiotic Core → VotingPowerProvider → ValSetDriver → Settlement
     ↓               ↓                     ↓           ↓
  Vaults &         Voting Power         Validator   Committed
  Operators         + Rules              Sets        State
                       ↑
                  KeyRegistry
                  (Keys & Sigs)

Data Flow​

  1. Stake Management: Symbiotic Core manages operator registration and vault stakes
  2. Power Calculation: VotingPowerProvider translates stakes into voting power using configured rules
  3. Key Integration: KeyRegistry provides cryptographic keys for each operator
  4. Set Derivation: ValSetDriver combines voting power and keys to create validator sets
  5. State Commitment: Settlement contracts commit validator set state to blockchains
  6. Verification: Applications verify signatures against committed validator sets

Epoch-Based Lifecycle​

The system operates on epochs with the following cycle:

  • Epoch N: Current validator set is active and signing
  • Epoch Transition: ValSetDriver derives new validator set based on current stake/power
  • Epoch N+1: Settlement commits new validator set header
  • Verification: Applications can verify signatures from either epoch during transition

Extension System​

The architecture's key innovation is the modular extension system, primarily on VotingPowerProvider:

Extension Categories​

  • Operator Management: Control who can participate (whitelist, blacklist, jail)
  • Vault Integration: Different vault attachment strategies (shared, operator-specific)
  • Economic Mechanisms: Slashing and reward distribution frameworks
  • Token Support: Multi-token voting power calculation
  • Automation: Auto-deployment of vaults and other infrastructure

Design Philosophy​

  • Composable: Extensions can be combined for complex behaviors
  • Standardized: Common interfaces enable interoperability
  • Gas Efficient: Optimized storage patterns and execution paths

Integration Points​

With Symbiotic Core​

  • OperatorRegistry: Source of truth for operator identity and status
  • VaultFactory: Creates and manages vaults that provide stake
  • MiddlewareService: Network-level configuration and lifecycle management

With Relay Binary​

  • ValSetDriver: Primary interface for validator set queries
  • KeyRegistry: Source of cryptographic material for consensus
  • Settlement: Coordination of validator set transitions

With Applications​

  • Settlement: Verification of signatures and validator set state
  • Events: updates on validator set changes
  • Historical Data: Access to past validator set configurations

This modular design enables developers to customize specific aspects of their validator network while leveraging battle-tested components for core functionality.