Relayer Service
Relevant source files
The following files were used as context for generating this wiki page:
The Relayer Service is a critical bridge infrastructure component designed to synchronize state between external blockchain networks and the X3 runtime. Its primary purpose is to watch for finalized blocks and slots on Ethereum (EVM) and Solana (SVM), extract relevant block information and state roots, and submit cryptographic proofs to the X3 runtime for verification. This ensures cross-chain interoperability by maintaining an accurate representation of external chain states within the X3 ecosystem.
Sources: crates/x3-relayer/PHASE_13D_README.md:9-14, crates/x3-relayer/PHASE_13E_MAINNET_PREP.md:9-12
System Architecture
The Relayer Service operates as a production-grade Rust binary that orchestrates multiple watcher modules and a centralized submission pipeline. It is architected to handle asynchronous polling of diverse RPC providers while enforcing strict finality thresholds to ensure the integrity of the proofs submitted to the X3 runtime.
Core Components
The service is divided into several specialized modules:
- Watcher Modules: Dedicated pollers for Ethereum (Sepolia/Mainnet) and Solana (Testnet/Mainnet) that track block height and finality.
- Relay Orchestrator: The main loop that coordinates watchers, integrates finality checking, and manages the proof processing pipeline.
- Submitter: Handles the actual submission of proofs to the X3 runtime, featuring exponential backoff retry logic and nonce management.
- Deduplication Logic: Uses a
BTreeSetcache to prevent redundant proof submissions.
Sources: crates/x3-relayer/PHASE_13D_README.md:104-142, crates/x3-relayer/PHASE_13E_MAINNET_PREP.md:150-168
Technical Data Flow
The following diagram illustrates the flow from block polling on external chains to proof finalization in the X3 runtime.
The Relayer Service uses separate tracking per domain to manage finality before proof processing. Sources: crates/x3-relayer/PHASE_13D_README.md:73-100
Configuration and Environment
The Relayer Service utilizes a YAML-based configuration system supplemented by environment variables for sensitive data. This allows for seamless transitions between Testnet and Mainnet environments by simply updating RPC endpoints and finality thresholds.
Key Configuration Parameters
| Parameter | Description | Testnet Value | Mainnet Value |
|---|---|---|---|
finality_threshold (EVM) | Blocks required for confirmation | 12 blocks | 64 blocks |
finality_threshold (SVM) | Slots required for confirmation | 32 slots | 128 slots |
poll_interval (EVM) | Frequency of Ethereum polling | 13,000ms | 13,000ms |
poll_interval (SVM) | Frequency of Solana polling | 15,000ms | 6,000ms |
max_concurrent_requests | Limit on parallel RPC calls | 5 (EVM) / 20 (SVM) | 10 (EVM) / 50 (SVM) |
Sources: crates/x3-relayer/PHASE_13E_MAINNET_PREP.md:70-98, crates/x3-relayer/PHASE_13D_README.md:195-205
Required Environment Variables
Sensitive credentials must be managed via environment variables rather than plain-text configuration files:
X3_RELAYER_ETHEREUM_KEY: Private key for Ethereum interactions.X3_RPC_URL: Endpoint for the X3 runtime node.ETH_ALCHEMY_KEY/ETH_INFURA_KEY: API keys for EVM RPC providers.SOL_QUICKNODE_KEY: API key for SVM RPC provider.
Sources: crates/x3-relayer/PHASE_13F_INFRASTRUCTURE_VALIDATION.md:78-83, crates/x3-relayer/PHASE_13D_README.md:166-168
Operational Management
The service is deployed as a systemd unit in production environments to provide high availability, automatic restarts, and integrated logging.
Service Lifecycle
Execution is managed through standard system commands:
- Start:
sudo systemctl start x3-relayer - Stop:
sudo systemctl stop x3-relayer - Status Check:
sudo systemctl status x3-relayer - Log Inspection:
tail -f /var/log/x3-relayer/relayer.log
Sources: crates/x3-relayer/PHASE_13F_QUICK_REFERENCE_GUIDE.md:65-70, crates/x3-relayer/PHASE_13E_MAINNET_PREP.md:112-132
Monitoring and Metrics
The service exports metrics to Prometheus, which are visualized through Grafana dashboards. Key metrics include:
x3_blocks_polled: Counter for total blocks retrieved from external chains.x3_proofs_submitted: Counter for proofs successfully sent to X3.x3_relayer_poll_failures: Tracks errors encountered during RPC polling.
Sources: crates/x3-relayer/PHASE_13F_INFRASTRUCTURE_VALIDATION.md:214-225, crates/x3-relayer/PHASE_13E_MAINNET_PREP.md:150-165
Incident Response and Failover
The Relayer Service implements a multi-tier failover strategy to maintain uptime despite RPC provider outages or network partitions.
RPC Failover Logic
If a primary RPC provider (e.g., Alchemy) fails or exceeds latency thresholds, the service automatically rotates through a list of backup providers (e.g., Infura, QuickNode) defined in the configuration. This transition is designed to be idempotent; because proofs are tied to specific block hashes and nonces, switching providers does not result in duplicate or inconsistent state transitions.
Emergency Procedures
In the event of a critical failure that cannot be resolved via failover (such as a persistent memory leak or X3 runtime error), the following procedures are documented:
- Restart: Execute
sudo systemctl restart x3-relayerto clear state. - Pause: Governance may pause the bridge; the relayer handles this by queuing proofs locally until operations resume.
- Rollback: If a binary update is faulty, operators utilize the
rollback-mainnet.shscript to restore the previous stable binary and configuration.
Sources: crates/x3-relayer/MAINNET_DEPLOYMENT_RUNBOOK.md:280-305, crates/x3-relayer/PHASE_13F_QUICK_REFERENCE_GUIDE.md:43-55
Summary
The Relayer Service is a robust, production-ready component of the X3 architecture. It ensures cross-chain state integrity through continuous monitoring of Ethereum and Solana, sophisticated finality verification, and a resilient submission pipeline. Supported by comprehensive monitoring via Prometheus and Grafana, and hardened with multi-tier failover capabilities, the service provides the necessary reliability for mainnet blockchain operations.