# hyperledger-labs/yui-relayer architecture

> Architecture diagram of the GitHub repository hyperledger-labs/yui-relayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperledger-labs/yui-relayer
- Repository: https://github.com/hyperledger-labs/yui-relayer

## Overview

##### Main Architectural Components
- Relayer Core – At the heart of the system is the core package (found under the “core” directory). It contains the main business logic such as channels, client management, connection handling, packet relays, and light client verification.
- Chain Modules – The “chains” directory (with a sample implementation in chains/tendermint) implements the specific handling for each blockchain type. Each chain module encapsulates chain-specific logic such as transaction creation, light client handling, and messaging.
- Provers – The “provers” (and provers/mock) directories include the logic for generating and verifying proofs of state from target chains.
- Config & Module Registration – The “config” directory holds the definitions for ChainConfig, ProverConfig, and Module interfaces. Modules register themselves here (as seen in the tendermint module example from the README), allowing the relayer to dynamically support new chains.
- CLI & Commands – The “cmd” directory and the command subpackages in chains/tendermint/cmd provide the command-line interface logic. They glue the relayer logic to actual commands, enabling user interaction.
- Utilities and Helpers – Other directories such as “helpers,” “log,” “metrics,” and “utils” provide supporting functions for querying, logging, metrics tracking, and serialization.
- Testing – The “tests” folder shows that end-to-end and integration tests exist to validate inter-chain communication.

##### Out the Relationships and Data Flows
- That the relayer core interacts with chain-specific modules (such as tendermint) through a standardized interface (i.e., the Module interface described in the README).
- That CLI commands (from the “cmd” directories) trigger operations in the core, which in turn delegate work to both the chain modules and the provers.
- External integrations such as connections with blockchains (via RPC endpoints, for example) and mention that these external systems are supported via specific adapters (e.g., Tendermint’s RPC, EVM’s ibc-solidity support, etc.).

##### Incorporate Architectural Patterns and Design Principles
- Modular Architecture – The decoupling between the core relayer logic and the chain-specific modules enables extensibility. Each module is responsible for registering itself (using methods like RegisterInterfaces) and providing its own CLI commands.
- Interface-Driven Design – Emphasize the abstraction between Chain and Prover configurations and implementations. This is critical because the same relayer core interfaces with completely different blockchain implementations.
- Clear Separation of Concerns – Different directories (core for business logic, config for orchestration, chains/provers for specific implementations) help organize the system properly.

##### Specify Technologies and Frameworks
- The project is written in Go (as indicated by go.mod and go.sum).
- It integrates with external (blockchain-specific) libraries like ibc-go for Cosmos/Tendermint and others for the additional supported chains.
- It uses Cobra for CLI (as seen in the sample module implementation) and Protobuf for protocol definitions (under the “proto” directory).

##### Elements
- Use clear labels for each component:
- “Relayer Core”
- “Configuration & Module Registration”
- “Chain Modules (e.g., Tendermint)”
- “Provers”
- “CLI Commands”
- “External Blockchain Networks”
- From CLI → Core → Modules/Provers
- From Core → External Blockchain (RPC, event feeds) and the reverse for query responses.
- Optionally, annotate important interactions such as “Load Config,” “Run Command,” “Relay Packet,” and “Verify Proof.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface / CLI Layer
    subgraph "User Interface / CLI Layer"
        CLI["CLI Commands"]:::cli
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        RC["Relayer Core"]:::core
        REG["Configuration & Module Registration"]:::config
    end

    %% Integration Layer
    subgraph "Integration Layer"
        CH["Chain Modules (Tendermint)"]:::modules
        PV["Provers"]:::modules
    end

    %% Support Layer
    subgraph "Support Layer"
        HP["Helpers"]:::utils
        LG["Log"]:::utils
        UT["Utils"]:::utils
    end

    %% External Systems
    subgraph "External Systems"
        EXT["External Blockchain Networks"]:::external
    end

    %% Testing
    TEST["Testing"]:::test

    %% Connections
    CLI -->|"RunCommand"| RC
    RC -->|"LoadConfig"| REG
    REG -->|"RegisterModule"| CH
    REG -->|"RegisterModule"| PV
    RC -->|"RelayPacket"| CH
    RC -->|"VerifyProof"| PV
    CH <-->|"RPCCalls"| EXT
    PV -->|"QueryState"| EXT
    TEST -->|"IntegrationTest"| RC

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef modules fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef config fill:#ffff99,stroke:#000,stroke-width:2px;
    classDef cli fill:#d8bfd8,stroke:#000,stroke-width:2px;
    classDef external fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef utils fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef test fill:#c0c0c0,stroke:#000,stroke-width:2px;

    %% Click Events
    click RC "https://github.com/hyperledger-labs/yui-relayer/tree/main/core/"
    click REG "https://github.com/hyperledger-labs/yui-relayer/tree/main/config/"
    click CH "https://github.com/hyperledger-labs/yui-relayer/tree/main/chains/tendermint/"
    click PV "https://github.com/hyperledger-labs/yui-relayer/tree/main/provers/"
    click CLI "https://github.com/hyperledger-labs/yui-relayer/tree/main/cmd/"
    click HP "https://github.com/hyperledger-labs/yui-relayer/tree/main/helpers/"
    click LG "https://github.com/hyperledger-labs/yui-relayer/tree/main/log/"
    click UT "https://github.com/hyperledger-labs/yui-relayer/tree/main/utils/"
    click TEST "https://github.com/hyperledger-labs/yui-relayer/tree/main/tests/"
```
