Supported Chains

This section details the blockchain networks supported by Khedra, the technical requirements for each, and the implementation approaches for multi-chain support.

Chain Support Architecture

Khedra implements a flexible architecture for supporting multiple EVM-compatible blockchains simultaneously.

Chain Abstraction Layer

At the core of Khedra's multi-chain support is a chain abstraction layer that:

Normalizes differences between chain implementations
Provides a uniform interface for blockchain interactions
Manages chain-specific configurations and behaviors
Isolates chain-specific code from the core application logic

// Simplified Chain interface
type Chain interface {
    // Return the chain name
    Name() string
    
    // Return the chain ID
    ChainID() uint64
    
    // Get RPC client for this chain
    Client() rpc.Client
    
    // Get path to chain-specific data directory
    DataDir() string
    
    // Check if this chain requires special handling for a feature
    SupportsFeature(feature string) bool
    
    // Get chain-specific configuration
    Config() ChainConfig
}

Core Chain Requirements

For a blockchain to be fully supported by Khedra, it must meet these technical requirements:

RPC Support

The chain must provide an Ethereum-compatible JSON-RPC API with these essential methods:

Basic Methods:
- eth_blockNumber: Get the latest block number
- eth_getBlockByNumber: Retrieve block data
- eth_getTransactionReceipt: Get transaction receipts with logs
- eth_chainId: Return the chain identifier
Trace Support:
- Either debug_traceTransaction or trace_transaction: Retrieve execution traces
- Alternatively: trace_block or debug_traceBlockByNumber: Get all traces in a block

Data Structures

The chain must use compatible data structures:

Addresses: 20-byte Ethereum-compatible addresses
Transactions: Compatible transaction format with standard fields
Logs: EVM-compatible event logs
Traces: Call traces in a format compatible with Khedra's processors

Consensus and Finality

The chain should have:

Deterministic Finality: Clear rules for when blocks are considered final
Manageable Reorgs: Limited blockchain reorganizations
Block Time Consistency: Relatively consistent block production times

Ethereum Mainnet

Ethereum mainnet is the primary supported chain and is required even when indexing other chains.

Special Considerations

Block Range: Support for full historical range from genesis
Archive Node: Full archive node required for historical traces
Trace Support: Must support either Geth or Parity trace methods
Size Considerations: Largest data volume among supported chains

Implementation Details

// Ethereum mainnet-specific configuration
type EthereumMainnetChain struct {
    BaseChain
    traceMethod string  // "geth" or "parity" style traces
}

func (c *EthereumMainnetChain) ProcessTraces(traces []interface{}) []Appearance {
    // Mainnet-specific trace processing logic
    // ...
}

EVM-Compatible Chains

Khedra supports a variety of EVM-compatible chains with minimal configuration.

Officially Supported Chains

These chains are officially supported with tested implementations:

Ethereum Testnets:
- Sepolia
- Goerli (legacy support)
Layer 2 Networks:
- Optimism
- Arbitrum
- Polygon
EVM Sidechains:
- Gnosis Chain (formerly xDai)
- Avalanche C-Chain
- Binance Smart Chain

Chain Configuration

Each chain is configured with these parameters:

chains:
  mainnet:  # Chain identifier
    rpcs:   # List of RPC endpoints
      - "https://ethereum-rpc.example.com"
    enabled: true  # Whether the chain is active
    trace_support: "geth"  # Trace API style
    # Chain-specific overrides
    scraper:
      batch_size: 500

Chain-Specific Adaptations

Some chains require special handling:

Optimism/Arbitrum: Modified trace processing for rollup architecture
Polygon: Adjusted finality assumptions for PoS consensus
BSC/Avalanche: Faster block times requiring different batch sizing

Chain Detection and Validation

Khedra implements robust chain detection and validation:

Auto-Detection

When connecting to an RPC endpoint:

Query eth_chainId to determine the actual chain
Verify against the configured chain identifier
Detect trace method support through API probing
Identify chain-specific capabilities

Connection Management

For each configured chain:

Connection Pool: Maintain multiple connections for parallel operations
Failover Support: Try alternative endpoints when primary fails
Health Monitoring: Track endpoint reliability and performance
Rate Limiting: Respect provider-specific rate limits

Data Isolation

Khedra maintains strict data isolation between chains:

Chain-Specific Directories: Separate storage locations for each chain
Independent Indices: Each chain has its own Unchained Index
Configuration Isolation: Chain-specific settings don't affect other chains
Parallel Processing: Chains can be processed concurrently

Adding New Chain Support

For adding support for a new EVM-compatible chain:

Configuration: Add the chain definition to config.yaml
Custom Handling: Implement any chain-specific processors if needed
Testing: Verify compatibility with the new chain
Documentation: Update supported chains documentation

Example: Adding a New Chain

// Register a new chain type
func RegisterNewChain() {
    registry.RegisterChain("new-chain", func(config ChainConfig) (Chain, error) {
        return &NewChain{
            BaseChain: NewBaseChain(config),
            // Chain-specific initialization
        }, nil
    })
}

// Implement chain-specific behavior
type NewChain struct {
    BaseChain
    // Chain-specific fields
}

func (c *NewChain) SupportsFeature(feature string) bool {
    // Chain-specific feature support
    switch feature {
    case "trace":
        return true
    case "state_diff":
        return false
    default:
        return c.BaseChain.SupportsFeature(feature)
    }
}

Khedra's flexible chain support architecture allows it to adapt to the evolving ecosystem of EVM-compatible blockchains while maintaining consistent indexing and monitoring capabilities across all supported networks.

The Khedra Book