How icon-project/centralized-relay works
Project Type and Purpose
• Type: A command-line/daemon application written in Go, designed as a “trusted medium” (central relay) for cross-chain message passing.
• Purpose: Listen to events on one blockchain, stage/validate messages, and relay them to another chain in a secure, pluggable way.
File Structure
Top-level directories:
• cmd/ → CLI entrypoint and command definitions (uses Cobra)
• relayer/ → Core relay logic and per-chain implementations (modular plug-ins)
• relayer/store/ → Persistent stores (LevelDB) for blocks, messages, finality
• relayer/kms/ → Key management abstraction
• relayer/socket/ → gRPC/HTTP or socket interfaces for external control
• deployment/ → Ansible roles and templates (for provisioning)
• Dockerfile → Container image definition
Other artifacts:
• example/ → Sample configs and keystores for supported chains
• docs/ → Design and configuration guidelines
• scripts/ → Helpers for build/test
• test/ → Chain simulators and e2e tests
README
• Points at Wiki for usage—implying documented runtime/configuration details.
Main Components & Their Interactions
A. CLI & Configuration Loader
– cmd/root.go + cmd/flags.go
– Reads sample_config.yml, keystore files, chain definitions.
B. Relay Core
– relayer/relay.go, chain.go, chain_runtime.go
– Orchestrates event listening, message staging, dispatch.
C. Chain Connector Modules (one per chain)
– Each module implements:
• listener.go → subscribes to new events/blocks
• client.go, provider.go → RPC/JSON-RPC wrappers
• event_parse.go → extract cross-chain payloads
• keys.go → local signing key interactions
D. Persistence Layer
– relayer/store/…
• BlockStore (blockStore.go)
• MessageStore (messageStore.go)
• FinalityStore (finalityStore.go)
– Underlying implementation: LevelDB (relayer/lvldb).
E. Key Management (KMS)
– relayer/kms/kms.go
– Abstracts access to local or remote key stores (e.g., AWS KMS, file system)
F. External Interfaces
– relayer/socket/server.go, client.go
– Optional HTTP/gRPC API for monitoring or controlling the relay.
G. Deployment & Operations
– Docker container wraps the CLI + binaries
– Ansible roles (deployment/ansible/…) for provisioning EC2, KMS policies, config distribution.
H. External Systems
– Blockchain nodes/endpoints for each supported chain
Relationships and Data Flow
• From Connector listener → Persistence Layer (store raw events).
• From Persistence → Relay Core → Connector client (to submit cross-chain TXs).
• KMS is used by connectors when signing outgoing transactions.
• External Interfaces connect to Relay Core for management.
Architectural Patterns & Design Principles
• Modular connector pattern: one plugin per chain, enabling easy extension.
• Layered architecture: CLI layer → orchestration layer → adapter layer → persistence layer
• Abstraction of key management and storage to swap implementations.
• Event-driven flow: listener → event parser → store → dispatcher.