# icon-project/centralized-relay architecture

> Architecture diagram of the GitHub repository icon-project/centralized-relay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icon-project/centralized-relay
- Repository: https://github.com/icon-project/centralized-relay

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Config Loader"
        Root["root.go"]:::core
        Flags["flags.go"]:::core
        Config["config.go"]:::core
        Start["start.go"]:::core
        Keystore["keystore.go"]:::core
    end
    subgraph "Relay Core"
        RelayCore["relay.go"]:::core
        Chain["chain.go"]:::core
        ChainRT["chain_runtime.go"]:::core
    end
    subgraph "Chain Connectors"
        EVM["EVM Connector"]:::connector
        ICON["ICON Connector"]:::connector
        SOL["Solana Connector"]:::connector
        STELLAR["Stellar Connector"]:::connector
        SUI["Sui Connector"]:::connector
        WASM["WASM Connector"]:::connector
        MOCK["Mockchain Connector"]:::connector
    end
    subgraph "Persistence Layer"
        StoreI["Store Interface"]:::storage
        BlockStore["BlockStore"]:::storage
        MessageStore["MessageStore"]:::storage
        FinalityStore["FinalityStore"]:::storage
        TxStore["TX Store"]:::storage
        LevelDB["LevelDB Impl"]:::storage
    end
    KMS["KMS"]:::kms
    subgraph "External Interfaces"
        Server["Socket Server"]:::core
        ClientI["Socket Client"]:::core
        Types["Types"]:::core
    end
    subgraph "Deployment & Operations"
        Docker["Dockerfile"]:::infra
        Ansible["Ansible Roles"]:::infra
    end
    subgraph "External Blockchains"
        ChainNodes["Blockchain Nodes"]:::external
    end

    Root -->|boots| RelayCore
    Flags --> RelayCore
    Config --> RelayCore
    Start --> RelayCore
    Keystore --> RelayCore

    RelayCore -->|listens| EVM
    RelayCore --> ICON
    RelayCore --> SOL
    RelayCore --> STELLAR
    RelayCore --> SUI
    RelayCore --> WASM
    RelayCore --> MOCK

    EVM -->|store events| StoreI
    ICON -->|store events| StoreI
    SOL -->|store events| StoreI
    STELLAR -->|store events| StoreI
    SUI -->|store events| StoreI
    WASM -->|store events| StoreI
    MOCK -->|store events| StoreI

    StoreI -->|retrieve events| RelayCore

    RelayCore -->|submit TX| EVM
    RelayCore -->|submit TX| ICON
    RelayCore -->|submit TX| SOL
    RelayCore -->|submit TX| STELLAR
    RelayCore -->|submit TX| SUI
    RelayCore -->|submit TX| WASM
    RelayCore -->|submit TX| MOCK

    EVM -->|sign| KMS
    ICON --> KMS
    SOL --> KMS
    STELLAR --> KMS
    SUI --> KMS
    WASM --> KMS
    MOCK --> KMS

    Server --> RelayCore
    ClientI --> RelayCore
    Types --> RelayCore

    Docker --> Root
    Ansible --> Docker

    ChainNodes --> EVM
    ChainNodes --> ICON
    ChainNodes --> SOL
    ChainNodes --> STELLAR
    ChainNodes --> SUI
    ChainNodes --> WASM
    ChainNodes --> MOCK

    click Root "https://github.com/icon-project/centralized-relay/blob/main/cmd/root.go"
    click Flags "https://github.com/icon-project/centralized-relay/blob/main/cmd/flags.go"
    click Config "https://github.com/icon-project/centralized-relay/blob/main/cmd/config.go"
    click Start "https://github.com/icon-project/centralized-relay/blob/main/cmd/start.go"
    click Keystore "https://github.com/icon-project/centralized-relay/blob/main/cmd/keystore.go"
    click RelayCore "https://github.com/icon-project/centralized-relay/blob/main/relayer/relay.go"
    click Chain "https://github.com/icon-project/centralized-relay/blob/main/relayer/chain.go"
    click ChainRT "https://github.com/icon-project/centralized-relay/blob/main/relayer/chain_runtime.go"
    click EVM "https://github.com/icon-project/centralized-relay/tree/main/relayer/chains/evm/"
    click ICON "https://github.com/icon-project/centralized-relay/tree/main/relayer/chains/icon/"
    click SOL "https://github.com/icon-project/centralized-relay/tree/main/relayer/chains/solana/"
    click STELLAR "https://github.com/icon-project/centralized-relay/tree/main/relayer/chains/steller/"
    click SUI "https://github.com/icon-project/centralized-relay/tree/main/relayer/chains/sui/"
    click WASM "https://github.com/icon-project/centralized-relay/tree/main/relayer/chains/wasm/"
    click MOCK "https://github.com/icon-project/centralized-relay/blob/main/relayer/chains/mockchain/provider.go"
    click StoreI "https://github.com/icon-project/centralized-relay/blob/main/relayer/store/store.go"
    click BlockStore "https://github.com/icon-project/centralized-relay/blob/main/relayer/store/blockStore.go"
    click MessageStore "https://github.com/icon-project/centralized-relay/blob/main/relayer/store/messageStore.go"
    click FinalityStore "https://github.com/icon-project/centralized-relay/blob/main/relayer/store/finalityStore.go"
    click TxStore "https://github.com/icon-project/centralized-relay/blob/main/relayer/store/txStore.go"
    click LevelDB "https://github.com/icon-project/centralized-relay/blob/main/relayer/lvldb/lvldb.go"
    click KMS "https://github.com/icon-project/centralized-relay/blob/main/relayer/kms/kms.go"
    click Server "https://github.com/icon-project/centralized-relay/blob/main/relayer/socket/server.go"
    click ClientI "https://github.com/icon-project/centralized-relay/blob/main/relayer/socket/client.go"
    click Types "https://github.com/icon-project/centralized-relay/blob/main/relayer/socket/types.go"
    click Docker "https://github.com/icon-project/centralized-relay/tree/main/Dockerfile"
    click Ansible "https://github.com/icon-project/centralized-relay/blob/main/deployment/ansible/centralized_relay.yml"

    classDef core fill:#3498db,stroke:#1f618d,color:#fff
    classDef connector fill:#e67e22,stroke:#b35415,color:#fff
    classDef storage fill:#2ecc71,stroke:#27ae60,color:#fff
    classDef kms fill:#9b59b6,stroke:#8e44ad,color:#fff
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:#fff
    classDef infra fill:#d35400,stroke:#ba4a00,color:#fff
```
