# unionlabs/union architecture

> Architecture diagram of the GitHub repository unionlabs/union, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unionlabs/union
- Repository: https://github.com/unionlabs/union

## Overview

Union is a cross-chain messaging and asset-transfer infrastructure project built around consensus verification and IBC compatibility. Its principal documented runtime workflow is Voyager relaying messages between supported ecosystems, using chain event sources, state access, and client modules; CosmWasm contracts and light clients provide on-chain protocol components. The repository also contains a user-facing app, SDKs, node, prover, and supporting services. The tree and excerpts establish these components but provide limited wiring evidence, so only README-documented relationships are connected; unsampled implementation links are omitted.

Main entry points: [`voyager/src/main.rs`](https://github.com/unionlabs/union/blob/main/voyager/src/main.rs) (Voyager relay), [`app2/src/lib/transfer`](https://github.com/unionlabs/union/tree/main/app2/src/lib/transfer) (Transfer workflows), [`cosmwasm/lightclient`](https://github.com/unionlabs/union/tree/main/cosmwasm/lightclient) (Light clients), [`cosmwasm`](https://github.com/unionlabs/union/tree/main/cosmwasm) (CosmWasm contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_relay["Relaying and state"]
  node_voyager["Voyager relay<br/>[main.rs]"]
  node_voyager_rpc["Voyager RPC<br/>[server.rs]"]
  node_voyager_queue["Relay queue<br/>[queue.rs]"]
  node_event_sources["Chain event sources"]
  node_state_modules["Chain state modules"]
  node_zkgm_filter["ZKGM filter<br/>[main.rs]"]
end

subgraph group_chain["Chain protocol"]
  node_light_clients["Light clients"]
  node_cosmwasm["CosmWasm contracts"]
  node_uniond["Union node<br/>[app.go]"]
end

subgraph group_app["User application"]
  node_app_transfer["Transfer workflows"]
  node_app_explorer["Chain explorer"]
  node_app_dashboard["Rewards dashboard"]
end

subgraph group_operations["Node and services"]
  node_galoisd["ZK prover<br/>[server.go]"]
  node_unionvisor["Node supervisor<br/>[main.rs]"]
  node_drip["Cosmos faucet<br/>[main.rs]"]
  node_mpc["MPC services<br/>[main.rs]"]
end

subgraph group_libraries["Shared libraries"]
  node_typescript_sdk["TypeScript SDK"]
end

node_operator(("Relayer operator"))

node_operator -->|"operates"| node_voyager
node_voyager -->|"relays across"| node_event_sources
node_voyager -.->|"queries chain state"| node_state_modules
node_voyager -->|"supports verification"| node_light_clients
node_voyager -.->|"relays messages"| node_cosmwasm
node_app_transfer -.->|"transfers assets"| node_cosmwasm
node_app_transfer -.->|"uses SDK"| node_typescript_sdk
node_uniond -->|"uses CometBLS"| node_light_clients

click node_voyager "https://github.com/unionlabs/union/blob/main/voyager/src/main.rs"
click node_voyager_rpc "https://github.com/unionlabs/union/blob/main/lib/voyager-core/src/server.rs"
click node_voyager_queue "https://github.com/unionlabs/union/blob/main/voyager/src/queue.rs"
click node_event_sources "https://github.com/unionlabs/union/tree/main/voyager/plugins/event-source"
click node_state_modules "https://github.com/unionlabs/union/tree/main/voyager/modules/state"
click node_zkgm_filter "https://github.com/unionlabs/union/blob/main/voyager/plugins/zkgm-filter/src/main.rs"
click node_light_clients "https://github.com/unionlabs/union/tree/main/cosmwasm/lightclient"
click node_cosmwasm "https://github.com/unionlabs/union/tree/main/cosmwasm"
click node_uniond "https://github.com/unionlabs/union/blob/main/uniond/app/app.go"
click node_app_transfer "https://github.com/unionlabs/union/tree/main/app2/src/lib/transfer"
click node_app_explorer "https://github.com/unionlabs/union/tree/main/app2/src/routes/explorer"
click node_app_dashboard "https://github.com/unionlabs/union/tree/main/app2/src/lib/dashboard"
click node_typescript_sdk "https://github.com/unionlabs/union/tree/main/ts-sdk/src"
click node_galoisd "https://github.com/unionlabs/union/blob/main/galoisd/grpc/server.go"
click node_unionvisor "https://github.com/unionlabs/union/blob/main/unionvisor/src/main.rs"
click node_drip "https://github.com/unionlabs/union/blob/main/drip/src/main.rs"
click node_mpc "https://github.com/unionlabs/union/blob/main/mpc/coordinator/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_voyager,node_voyager_rpc,node_voyager_queue,node_event_sources,node_state_modules,node_zkgm_filter toneBlue
class node_light_clients,node_cosmwasm,node_uniond toneAmber
class node_app_transfer,node_app_explorer,node_app_dashboard toneMint
class node_galoisd,node_unionvisor,node_drip,node_mpc toneRose
class node_typescript_sdk,node_operator toneIndigo
```

## Components

### Relaying and state

- [Voyager relay](https://github.com/unionlabs/union/blob/main/voyager/src/main.rs): `voyager/src/main.rs`
- [Voyager RPC](https://github.com/unionlabs/union/blob/main/lib/voyager-core/src/server.rs): `lib/voyager-core/src/server.rs`
- [Relay queue](https://github.com/unionlabs/union/blob/main/voyager/src/queue.rs): `voyager/src/queue.rs`
- [Chain event sources](https://github.com/unionlabs/union/tree/main/voyager/plugins/event-source): `voyager/plugins/event-source`
- [Chain state modules](https://github.com/unionlabs/union/tree/main/voyager/modules/state): `voyager/modules/state`
- [ZKGM filter](https://github.com/unionlabs/union/blob/main/voyager/plugins/zkgm-filter/src/main.rs): `voyager/plugins/zkgm-filter/src/main.rs`

### Chain protocol

- [Light clients](https://github.com/unionlabs/union/tree/main/cosmwasm/lightclient): `cosmwasm/lightclient`
- [CosmWasm contracts](https://github.com/unionlabs/union/tree/main/cosmwasm): `cosmwasm`
- [Union node](https://github.com/unionlabs/union/blob/main/uniond/app/app.go): `uniond/app/app.go`

### User application

- [Transfer workflows](https://github.com/unionlabs/union/tree/main/app2/src/lib/transfer): `app2/src/lib/transfer`
- [Chain explorer](https://github.com/unionlabs/union/tree/main/app2/src/routes/explorer): `app2/src/routes/explorer`
- [Rewards dashboard](https://github.com/unionlabs/union/tree/main/app2/src/lib/dashboard): `app2/src/lib/dashboard`

### Node and services

- [ZK prover](https://github.com/unionlabs/union/blob/main/galoisd/grpc/server.go): `galoisd/grpc/server.go`
- [Node supervisor](https://github.com/unionlabs/union/blob/main/unionvisor/src/main.rs): `unionvisor/src/main.rs`
- [Cosmos faucet](https://github.com/unionlabs/union/blob/main/drip/src/main.rs): `drip/src/main.rs`
- [MPC services](https://github.com/unionlabs/union/blob/main/mpc/coordinator/src/main.rs): `mpc/coordinator/src/main.rs`

### Shared libraries

- [TypeScript SDK](https://github.com/unionlabs/union/tree/main/ts-sdk/src): `ts-sdk/src`

### Other components

- **Relayer operator**

## Connections

- Relayer operator → Voyager relay: operates (evidence: `README.md`)
- Voyager relay → Chain event sources: relays across (evidence: `README.md`)
- Voyager relay → Chain state modules: queries chain state
- Voyager relay → Light clients: supports verification (evidence: `README.md`)
- Voyager relay → CosmWasm contracts: relays messages
- Transfer workflows → CosmWasm contracts: transfers assets
- Transfer workflows → TypeScript SDK: uses SDK
- Union node → Light clients: uses CometBLS (evidence: `README.md`)
