Adapter Layer Spec

Adapter Layer Specification - Chain Integration

This document specifies the adapter layer interface for integrating different blockchains with the Roru Protocol.

Adapter Interface

Core Interface

Trait Definition:

pub trait ChainAdapter {
    fn chain_id(&self) -> ChainId;
    
    async fn get_balance(&self, address: &Address) -> Result<u64>;
    
    async fn create_settlement(
        &self,
        tx: &SettlementTransaction,
    ) -> Result<SettlementTx>;
    
    async fn submit_settlement(
        &self,
        settlement: &SettlementTx,
    ) -> Result<TxHash>;
    
    async fn get_confirmation(
        &self,
        hash: &TxHash,
    ) -> Result<ConfirmationStatus>;
    
    async fn estimate_fees(
        &self,
        settlement: &SettlementTx,
    ) -> Result<Fees>;
    
    async fn get_latest_block(&self) -> Result<BlockNumber>;
}

Ethereum Adapter

Implementation

Ethereum Adapter:

pub struct EthereumAdapter {
    pub rpc_client: Web3Client,
    pub chain_id: u64,
    pub contract_address: Address,
}

impl ChainAdapter for EthereumAdapter {
    fn chain_id(&self) -> ChainId {
        ChainId::Ethereum(self.chain_id)
    }
    
    async fn create_settlement(
        &self,
        tx: &SettlementTransaction,
    ) -> Result<SettlementTx> {
        // Create Ethereum transaction
        let eth_tx = self.build_ethereum_tx(tx)?;
        Ok(SettlementTx::Ethereum(eth_tx))
    }
    
    async fn submit_settlement(
        &self,
        settlement: &SettlementTx,
    ) -> Result<TxHash> {
        if let SettlementTx::Ethereum(tx) = settlement {
            let hash = self.rpc_client.send_transaction(tx).await?;
            Ok(TxHash::Ethereum(hash))
        } else {
            Err(Error::InvalidSettlementType)
        }
    }
    
    // ... other methods
}

Ethereum-Specific Features

Features:

• ERC-20 token support

• Gas estimation

• EIP-1559 support

• Event listening

• Contract interaction

Solana Adapter

Implementation

Solana Adapter:

pub struct SolanaAdapter {
    pub rpc_client: RpcClient,
    pub program_id: Pubkey,
}

impl ChainAdapter for SolanaAdapter {
    fn chain_id(&self) -> ChainId {
        ChainId::Solana
    }
    
    async fn create_settlement(
        &self,
        tx: &SettlementTransaction,
    ) -> Result<SettlementTx> {
        // Create Solana transaction
        let sol_tx = self.build_solana_tx(tx)?;
        Ok(SettlementTx::Solana(sol_tx))
    }
    
    async fn submit_settlement(
        &self,
        settlement: &SettlementTx,
    ) -> Result<TxHash> {
        if let SettlementTx::Solana(tx) = settlement {
            let signature = self.rpc_client.send_transaction(tx).await?;
            Ok(TxHash::Solana(signature))
        } else {
            Err(Error::InvalidSettlementType)
        }
    }
    
    // ... other methods
}

Solana-Specific Features

Features:

• SPL token support

• Program interaction

• Account management

• Transaction building

• Fast settlement

Bitcoin Adapter

Implementation

Bitcoin Adapter:

pub struct BitcoinAdapter {
    pub rpc_client: BitcoinRpcClient,
    pub network: Network,
}

impl ChainAdapter for BitcoinAdapter {
    fn chain_id(&self) -> ChainId {
        ChainId::Bitcoin(self.network)
    }
    
    async fn create_settlement(
        &self,
        tx: &SettlementTransaction,
    ) -> Result<SettlementTx> {
        // Create Bitcoin transaction
        let btc_tx = self.build_bitcoin_tx(tx)?;
        Ok(SettlementTx::Bitcoin(btc_tx))
    }
    
    async fn submit_settlement(
        &self,
        settlement: &SettlementTx,
    ) -> Result<TxHash> {
        if let SettlementTx::Bitcoin(tx) = settlement {
            let txid = self.rpc_client.send_raw_transaction(tx).await?;
            Ok(TxHash::Bitcoin(txid))
        } else {
            Err(Error::InvalidSettlementType)
        }
    }
    
    // ... other methods
}

Bitcoin-Specific Features

Features:

• UTXO management

• SegWit support

• Fee estimation

• Transaction building

• Block monitoring

Adapter Factory

Factory Pattern

Factory Implementation:

pub struct AdapterFactory;

impl AdapterFactory {
    pub fn create_adapter(chain_id: ChainId, config: &Config) -> Result<Box<dyn ChainAdapter>> {
        match chain_id {
            ChainId::Ethereum(id) => {
                Ok(Box::new(EthereumAdapter::new(id, config)?))
            }
            ChainId::Solana => {
                Ok(Box::new(SolanaAdapter::new(config)?))
            }
            ChainId::Bitcoin(network) => {
                Ok(Box::new(BitcoinAdapter::new(network, config)?))
            }
            // ... other chains
        }
    }
}

Settlement Transaction Format

Format Definition

Settlement Transaction:

pub enum SettlementTx {
    Ethereum(EthereumTx),
    Solana(SolanaTx),
    Bitcoin(BitcoinTx),
    // ... other chains
}

Common Fields

Common Structure:

• State root update

• Nullifier additions

• New note commitments

• Proof data

• Metadata

Error Handling

Error Types

Adapter Errors:

• Network errors

• RPC errors

• Transaction errors

• Confirmation errors

• Chain-specific errors

Error Recovery

Recovery Strategies:

• Retry with backoff

• Fallback RPC endpoints

• Error reporting

• State recovery

Testing

Test Adapter

Mock Adapter:

pub struct TestAdapter {
    pub chain_id: ChainId,
    pub mock_state: MockState,
}

impl ChainAdapter for TestAdapter {
    // Mock implementations for testing
}

Integration Tests

Test Framework:

• Unit tests per adapter

• Integration tests

• Chain-specific tests

• End-to-end tests

Performance

Optimization

Optimizations:

• Connection pooling

• Batch RPC calls

• Caching

• Parallel processing

Metrics

Performance Metrics:

• RPC latency

• Transaction submission time

• Confirmation time

• Error rate

Security

Security Considerations

Security Measures:

• Secure RPC connections

• Transaction signing

• Input validation

• Error handling

Threat Model

Protected Against:

• RPC attacks

• Transaction manipulation

• Network attacks

• State inconsistencies

Conclusion

The adapter layer provides:

• Abstraction: Unified interface

• Flexibility: Multiple chains

• Extensibility: Easy to add chains

• Reliability: Robust error handling

• Performance: Optimized operations

Understanding adapters is essential for chain integration.