⚠️ Alpha Release Warning: This is an alpha release of the Concero V2 Relayers. The code is not yet production ready and is subject to change.
Concero V2 Relayers are specialized nodes that enable secure cross-chain communication in the Concero V2 network. They serve as the bridge between different blockchain networks, ensuring messages are validated and delivered reliably across chains while maintaining the highest security standards.
- Overview
- What is a Relayer?
- Architecture
- Relayer Types
- Core Components
- Getting Started
- Configuration
- Deployment
- Security
- Monitoring
- Documentation Links
- Contributing
Concero V2 represents a significant advancement in cross-chain interoperability, extending beyond the capabilities of V1 to support any-to-any network communication. The relayer network is economically secured by Symbiotic restaking and leverages Chainlink Functions for verifiable compute, ensuring both security and decentralization.
- Unlimited Network Reach: Connect any blockchain network
- Modular Security: Choose your security modules based on requirements
- Economic Security: Backed by Symbiotic restaking protocol
- Cryptographic Verification: Trust-minimized validation via Chainlink Functions
- Large Data Support: Up to 1.875 MB per message (limited only by network constraints)
- Fast Finality: ~10-20 second challenge periods
A relayer in Concero V2 is a specialized node operator responsible for:
- Message Validation: Request validation reports from Chainlink Functions for cross-chain messages
- Message Delivery: Deliver validated messages to destination chains within allocated time windows
- Uptime Maintenance: Ensure operational availability to avoid downtime penalties
- Resource Management: Maintain sufficient gas and deposits across all supported chains
Relayers earn rewards through:
- Report Request Rewards: From ConceroVerifier contracts
- Message Delivery Rewards: From ConceroRouter contracts
Relayers face penalties for:
- Missed Deliveries: Failing to deliver within 10-second time slots
- Downtime: Extended periods of unavailability
The Concero V2 relayer system follows a modular architecture designed for reliability, scalability, and maintainability:
┌─────────────────────────────────────────────────────────────┐
│ Concero V2 Relayer │
├─────────────────────────────────────────────────────────────┤
│ Block Manager Registry │
│ ├── Block Manager (Network 1) │
│ ├── Block Manager (Network 2) │
│ └── Block Manager (Network N) │
├─────────────────────────────────────────────────────────────┤
│ Core Managers │
│ ├── TX Manager (Read/Write/Monitor) │
│ ├── Network Manager │
│ ├── Deployment Manager │
│ ├── Viem Client Manager │
│ └── RPC_MANAGER Manager │
├─────────────────────────────────────────────────────────────┤
│ Infrastructure │
│ ├── DB Manager (Prisma) │
│ ├── Block Checkpoint Manager │
│ └── Nonce Manager │
└─────────────────────────────────────────────────────────────┘
The primary relayer responsible for essential operations:
- Event Monitoring: Captures
ConceroMessageSentevents from router contracts - CLF Integration: Triggers Chainlink Functions for message validation
- Report Relay: Delivers validation reports to destination chains
- Economic Security: Manages deposits and stake requirements
Provides additional consensus layer for enhanced security:
- Consensus Participation: Works alongside Chainlink Functions for multi-party validation
- Custom Verification: Enables application-specific security requirements
- Risk Adjustment: Allows developers to balance speed vs. security
Central repository for network-specific BlockManagers, enabling dynamic network addition and management.
- Fetches and reports new block ranges for individual networks
- Handles block polling and event detection
- Supports both sequential and catchup processing modes
- Tracks latest successfully processed blocks
- Enables recovery from checkpoints after downtime
- Ensures continuity of operations during system interruptions
Central transaction coordination layer providing:
- TX Reader: Handles all blockchain data retrieval operations
- TX Writer: Manages write operations across all networks
- TX Monitor: Ensures transaction finality and reliability
- Oversees supported networks by monitoring
@concero/v2-networks - Enables dynamic network addition without operator intervention
- Manages network configurations and chain selectors
- Tracks ConceroVerifier and ConceroRouter contract deployments
- Maintains up-to-date contract addresses
- Enables immediate contract availability for new networks
- Creates, retrieves, and disposes of Viem Fallback Clients
- Manages RPC_MANAGER connections with fallback support
- Optimizes client lifecycle management
- Implements custom nonce tracking for optimal transaction throughput
- Prevents nonce-related transaction failures
- Enables faster transaction processing
- Maintains updatable lists of RPC_MANAGER endpoints
- Monitors
@concero/rpcsfor endpoint updates - Provides failover and load balancing capabilities
- Node.js: v22 or higher
- Database: PostgreSQL (configured via Prisma)
- Symbiotic Registration: Required for mainnet operations
- ETH Deposits: Sufficient for network operations and staking
# Clone the repository
git clone https://github.com/concero/v2-operators.git
cd v2-operators
# Install dependencies
npm install
# Generate Prisma client
npx prisma generate --schema=prisma/schema.prisma
# Set up database (if needed)
npx prisma migrate resetCreate a .env file based on the provided template:
cp .env.example .envRequired environment variables:
NETWORK_MODE:mainnet,testnet, orlocalhostOPERATOR_ADDRESS: Your relayer's Ethereum addressLOG_LEVEL_DEFAULT: Logging level (debug,info,warn,error)- Database connection strings for Prisma
# Start Relayer A
npm run start:relayerA
# Or using bun for faster startup
bun ./src/relayer-a/index.ts# Build and start with Docker Compose
./start.sh
# Or manually
docker compose -f docker/docker-compose.yml up -dBefore operating on mainnet, you must:
- Deposit Funds: Deposit native tokens to ConceroVerifier contract
- Request Registration: Call
requestOperatorRegistrationwith:- Chain types you want to support (0 for EVMs)
- Registration actions
- Operator addresses
- Wait for Verification: Chainlink Functions verifies your Symbiotic stake
- Begin Operations: Start relaying messages once registration is confirmed
The relayer automatically fetches network configurations from:
- Mainnet:
@concero/v2-networks/networks/mainnet.json - Testnet:
@concero/v2-networks/networks/testnet.json
RPC_MANAGER endpoints are managed via @concero/rpcs with automatic updates.
Contract addresses are fetched from @concero/v2-contracts deployment files.
// Block Manager Settings
BLOCK_MANAGER_POLLING_INTERVAL_MS=5000
USE_CHECKPOINTS=true
// Transaction Settings
DRY_RUN=false
SIMULATE_TX=true
DEFAULT_CONFIRMATIONS=3
// Logging
LOG_LEVEL_DEFAULT=infoThe relayer includes production-ready Docker configuration:
# docker-compose.yml
version: "3.8"
services:
app:
build:
context: .
dockerfile: ./docker/Dockerfile
env_file:
- .env
volumes:
- ./logs:/app/logs
restart: always- Logging: Structured logging with Winston
- Metrics: Built-in performance monitoring
- Alerts: Slack integration for critical events
- Checkpoints: Automatic recovery from failures
- Symbiotic Staking: Relayers must maintain delegated stake
- Slashing Conditions: Penalties for downtime and incorrect behavior
- Deposit Requirements: Funds held in ConceroVerifier for security
- Chainlink Functions: Verifiable compute for message validation
- Multi-signature: DON consensus for report authenticity
- Hash Verification: Tamper-proof message integrity
- Key Management: Secure private key storage
- Access Control: Restricted operator permissions
- Monitoring: Continuous uptime and performance tracking
- Updates: Regular software updates and security patches
- Message Processing Rate: Messages per minute
- Success Rate: Percentage of successful deliveries
- Response Time: Average delivery latency
- Uptime: Operational availability percentage
Structured logs are written to:
- Console: Real-time monitoring
- Files: Persistent log storage (
./logs/) - External: Slack notifications for critical events
- Database Connectivity: Prisma connection status
- RPC_MANAGER Endpoints: Network connectivity verification
- Contract Interactions: Successful contract calls
- Balance Monitoring: Sufficient gas and deposits
- Concero V2 Technical Overview
- Concero V2 Relayer Documentation
- Symbiotic Protocol
- Chainlink Functions
We welcome contributions to improve the Concero V2 relayer software:
# Install dependencies
npm install
# Run linting
npm run lint
# Format code
npm run format
# Run tests
npm test- TypeScript: Strict typing requirements
- ESLint: Configured linting rules
- Prettier: Consistent code formatting
- SOLID Principles: Clean architecture patterns
- Fork the repository
- Create a feature branch
- Implement changes with tests
- Run quality checks
- Submit a pull request
This project is licensed under the terms specified in the LICENSE file.
Need Help?
Built with ❤️ by the Concero Team