explorer-monorepo/docs/specs/multichain/chain-adapter-interface.md

Chain Adapter Interface Specification

Overview

This document specifies the abstract chain adapter interface that enables multi-chain support by abstracting chain-specific differences behind a unified interface.

Adapter Interface

Core Interface

interface ChainAdapter {
  // Chain identification
  getChainId(): number;
  getChainName(): string;
  
  // RPC capabilities
  getBlock(blockNumber: number | string): Promise<Block>;
  getBlockByHash(hash: string): Promise<Block>;
  getTransaction(hash: string): Promise<Transaction>;
  getTransactionReceipt(hash: string): Promise<Receipt>;
  getBalance(address: string, blockNumber?: string): Promise<string>;
  call(transaction: CallRequest, blockNumber?: string): Promise<string>;
  
  // Advanced capabilities
  traceTransaction(hash: string): Promise<Trace[]>;
  traceBlock(blockNumber: number): Promise<Trace[]>;
  getCode(address: string, blockNumber?: string): Promise<string>;
  
  // Subscription capabilities
  subscribeNewBlocks(callback: (block: Block) => void): Subscription;
  subscribePendingTransactions(callback: (tx: Transaction) => void): Subscription;
  
  // Capability queries
  supportsTracing(): boolean;
  supportsArchive(): boolean;
  supportsDebug(): boolean;
}

RPC Capabilities Abstraction

Archive Mode

Interface:

interface ArchiveCapability {
  getHistoricalBalance(address: string, blockNumber: number): Promise<string>;
  getHistoricalCode(address: string, blockNumber: number): Promise<string>;
  getHistoricalStorage(address: string, slot: string, blockNumber: number): Promise<string>;
}

Implementation:

• EVM chains: Use eth_getBalance with block number
• Non-EVM: Chain-specific historical queries

Tracing Capabilities

Interface:

interface TracingCapability {
  traceCall(call: CallRequest, traceType: string[]): Promise<TraceResult>;
  traceTransaction(hash: string, traceType: string[]): Promise<Trace[]>;
  traceBlock(blockNumber: number, traceType: string[]): Promise<Trace[][]>;
}

Trace Types:

• call: Call traces
• trace: Full trace information
• vmTrace: VM execution trace
• stateDiff: State differences

Implementation:

• EVM chains: Use debug_trace* methods
• Non-EVM: Chain-specific trace methods

Debug Capabilities

Interface:

interface DebugCapability {
  debugTraceTransaction(hash: string, options: TraceOptions): Promise<TraceResult>;
  debugTraceBlock(blockNumber: number, options: TraceOptions): Promise<TraceResult[]>;
  debugTraceCall(call: CallRequest, blockNumber: number, options: TraceOptions): Promise<TraceResult>;
}

Use Cases: Advanced debugging, detailed transaction analysis

Token Standards Abstraction

Token Interface

interface TokenStandard {
  // Common methods
  getBalance(address: string, tokenAddress: string): Promise<string>;
  getTotalSupply(tokenAddress: string): Promise<string>;
  getDecimals(tokenAddress: string): Promise<number>;
  getName(tokenAddress: string): Promise<string>;
  getSymbol(tokenAddress: string): Promise<string>;
  
  // Standard-specific
  getTokenId(owner: string, index: number): Promise<string>; // ERC-721/1155
  getTokenURI(tokenAddress: string, tokenId: string): Promise<string>; // ERC-721/1155
}

Standard Detection

ERC-20:

• Detect balanceOf, totalSupply, transfer functions
• Standard interface ID: 0x36372b07

ERC-721:

• Detect balanceOf, ownerOf, tokenURI functions
• Standard interface ID: 0x80ac58cd

ERC-1155:

• Detect balanceOf, balanceOfBatch, uri functions
• Standard interface ID: 0xd9b67a26

Non-EVM Standards:

• Chain-specific token standards
• Custom detection logic

Gas Model Abstraction

Gas Interface

interface GasModel {
  // Gas estimation
  estimateGas(transaction: TransactionRequest): Promise<number>;
  
  // Fee calculation
  getGasPrice(): Promise<string>;
  getFeeData(): Promise<FeeData>; // EIP-1559
  
  // Gas limit
  getBlockGasLimit(): Promise<number>;
  getBlockGasUsed(): Promise<number>;
}

EIP-1559 Support

Interface:

interface EIP1559GasModel extends GasModel {
  getBaseFee(): Promise<string>;
  getMaxFeePerGas(): Promise<string>;
  getMaxPriorityFeePerGas(): Promise<string>;
}

Detection: Check for baseFeePerGas in block header

Legacy Gas Model

Interface: Simple gas price model (pre-EIP-1559)

Finality Model Abstraction

Finality Interface

interface FinalityModel {
  getFinalityDepth(): number; // Blocks until final
  isFinal(blockNumber: number): Promise<boolean>;
  getFinalityTime(): number; // Estimated time to finality (seconds)
}

Finality Types

Immediate Finality (BFT chains):

• Finality depth: 1
• Examples: Cosmos, Polkadot (with finality gadgets)

Probabilistic Finality (PoW):

• Finality depth: 12-100 blocks
• Examples: Ethereum (pre-merge), Bitcoin

Economic Finality (PoS):

• Finality depth: 1-2 epochs
• Examples: Ethereum (post-merge), Cardano

Implementation Examples

EVM Chain Adapter

class EVMChainAdapter implements ChainAdapter {
  constructor(private rpcUrl: string, private chainId: number) {}
  
  async getBlock(blockNumber: number | string): Promise<Block> {
    const response = await this.rpcCall('eth_getBlockByNumber', [
      blockNumber === 'latest' ? 'latest' : `0x${blockNumber.toString(16)}`,
      true
    ]);
    return this.transformBlock(response);
  }
  
  supportsTracing(): boolean {
    return true; // Most EVM chains support tracing
  }
  
  // ... other methods
}

Non-EVM Chain Adapter

class NonEVMChainAdapter implements ChainAdapter {
  // Chain-specific implementation
  // Map chain-specific RPC calls to standard interface
}

Adapter Registry

Registry Interface

interface ChainAdapterRegistry {
  register(chainId: number, adapter: ChainAdapter): void;
  get(chainId: number): ChainAdapter;
  list(): ChainAdapter[];
  supports(chainId: number): boolean;
}

Configuration

chains:
  - chain_id: 138
    name: "ChainID 138"
    adapter: "evm"
    rpc_url: "http://192.168.11.221:8545"  # Internal IP for direct connection
    supports_tracing: true
    supports_archive: true
  
  - chain_id: 1
    name: "Ethereum Mainnet"
    adapter: "evm"
    rpc_url: "https://eth-mainnet.alchemyapi.io/v2/..."
    supports_tracing: true
    supports_archive: true

Error Handling

Chain-Specific Errors

Handling:

• Map chain-specific errors to standard error codes
• Provide error context (chain_id, method called)
• Log chain-specific error details

Capability Errors

Handling:

• Check capability before calling method
• Return appropriate error if capability not supported
• Provide alternative methods when possible

Testing

Adapter Tests

Test Cases:

• Standard interface methods
• Error handling
• Capability detection
• Data transformation

Integration Tests

Test Cases:

• Multi-chain queries
• Adapter switching
• Error propagation

References

• Multi-chain Indexing: See multichain-indexing.md
• Database Schema: See ../database/postgres-schema.md