Union 架构解析：uniond、unionvisor、galoisd 三大二进制与可复现构建体系

Union 是一个零知识跨链桥接协议，其单仓库（mono-repo）架构围绕三个必须运行的网络二进制——uniond（网络节点）、unionvisor（节点监控器）与 galoisd（ZK 证明器）——以及一套基于 Nix flake-parts 的可复现构建体系组织而成。本文以仓库根目录的 ARCHITECTURE.md 为主线，结合各组件的构建定义、NixOS 模块与源码结构，完整梳理该仓库的目录布局、构建方式、三大二进制职责及支撑模块，帮助贡献者、审计者与运维人员快速定位关键代码并理解各组件的协作关系。

仓库顶层结构与组织原则

根据 ARCHITECTURE.md 的说明，仓库根目录下可以找到 uniond、unionvisor、galoisd 等运行网络所必需的目录，其余目录如 voyager、cosmwasm、evm、ts-sdk、lib、deployments、networks、tools 等分别对应中继器、合约栈、轻客户端、开发工具与网络定义。仓库组织遵循几条明确的原则，直接决定了阅读代码的方式：

• 每个重要组件都有 README：uniond、unionvisor、galoisd、voyager、cosmwasm、ts-sdk 等目录均配有各自的 README.md，说明组件用途与开发方式。例如 uniond/README.md 说明它是联盟网络的规范全节点实现，unionvisor/README.md 说明它是管理 uniond 部署、负责升级生命周期的工具。
• 源码是唯一事实来源：文档强调"Source code is always the source of truth"，最细致的说明在 doc comments 中；团队刻意不把文档链接从代码中分离出去，因为重构会产生死链和陈旧文档，推荐用文本搜索来定位组件定义。
• 生成代码暂时入库：目前 protobuf 定义等生成代码（如 uniond/proto/ 下的 .pb.go、generated/ 目录）被直接提交到仓库中，待私有仓库与 proto derivation 支持完善后移除。
• 构建入口统一为 flake.nix：所有包/应用的构建逻辑由 flake.nix 通过 flake-parts 导入各组件的 .nix 构建文件（如 uniond/uniond.nix）组装而成。

基于 Nix 的可复现构建

仓库要求使用 Nix 来可复现地构建任意组件，并进入包含全部依赖的开发环境。核心命令为：

nix build .#uniond   # 或 .#unionvisor、.#galoisd
nix flake show       # 查看全部已定义的 package/app
nix develop          # 进入包含 cargo、rustc、node、go 等依赖的 devshell
nix run .#pre-commit -L   # 全仓库格式化与拼写检查

构建细节可以从组件的构建定义中确认：

• uniond/uniond.nix 使用 buildGo123Module 构建 uniond，在 Linux 上采用 musl 静态链接（CGO_LDFLAGS 指定 -static，tags 为 netgo/muslc），并将 libwasmvm（仓库中为 libwasmvm-2_2_1 包）链接进二进制——这正是 uniond 能运行 CosmWasm 合约的运行时基础；同时该文件还定义了 uniond-image 与 uniond-release-image 两个 Docker 镜像包（Entrypoint 为 uniond，默认 Cmd = ["start"]）。
• unionvisor/unionvisor.nix 用 crane.buildWorkspaceMember "unionvisor" 构建 Rust 工作区成员 unionvisor，并通过 crane.lib.cargoTest 定义 checks.unionvisor-tests 集成测试。

这一构建方式的意义在于：任何一次 uniond 发布版本都能被固化进"bundle"（见下文 unionvisor 一节），使节点可以从零同步并逐版本验证完整链上历史。

三大核心二进制

ARCHITECTURE.md 在 "High-level Overview / Binaries" 中给出三个二进制的分工，下面逐一展开，并结合各组件源码与构建定义深化。

uniond：网络节点

uniond 是网络节点，由验证者运行以生产区块。从 uniond/README.md 可知其技术底座：

• 基于 Cosmos SDK 的区块链实现，除核心 SDK 模块外，集成 Wasmd 以托管"虚拟化的 IBC-Union 栈"，并支持 ibc-go 模块用于原生跨链连接；
• 共识使用 CometBLS（见根 README.md 组件表），mainnet 孵化期暂时采用 PoA（Proof of Authority），并在具备条件后迁移到 Proof of Stake；
• 主要面向验证者、RPC 与 archive 节点运营者。

从源码结构看，uniond 目录的划分印证了上述架构：

• uniond/app：应用装配层，其中 upgrades/ 子目录包含 v1_1_0、v1_2_0、v1_3_0 等分版本升级计划（每个版本含 constants.go 与 upgrade.go），wasm.go、ibc.go 对应 Wasmd 与 IBC 装配；
• uniond/cmd/uniond：CLI 入口（root.go、commands.go），另含 testnet.go/testnet_multi_node.go 用于生成本地多节点测试网，以及 possession.go 对应 BLS proof-of-possession 流程；
• uniond/proto/union/ibc/lightclients/cometbls/v1/cometbls.proto：CometBLS 轻客户端的 IBC 状态与交易 proto 定义，是 Union 跨链共识验证在节点侧的协议接口；
• uniond/x/staking：自定义 staking 模块（含 keeper、cli、types 与 msg_server.go），用于支撑 PoA→PoS 阶段的验证者治理。

日常使用上，uniond --help 即是命令总览，节点运行与链交互均可通过 CLI 完成；生产部署则推荐使用 unionvisor（这也是 ARCHITECTURE.md 明确给出的建议）。

unionvisor：节点监控器

unionvisor 是 uniond 的监控器（supervisor），使命是"让部署更容易、更有韧性"。它不是节点运行的必需组件，但生产环境强烈建议启用。其核心机制在 unionvisor/unionvisor.nix 中定义得非常具体：

Bundle（版本包）机制：mkBundle 函数将一个 unionvisor 可执行文件、meta.json（含 binary_name、versions_directory、fallback_version）、genesis.json 以及 versions/<版本号>/uniond 形式的全部历史 uniond 二进制（通过 flake 依赖动态加载各历史版本的 uniond-release 包）打成一个 bundle 目录，并可选加入 nextVersion（如 v1.3.0）用于即将执行的升级。由此 bundle "能从零同步链并执行升级，实际上引导（bootstrapping）并验证了完整历史"——见 unionvisor/README.md。flake 中定义的 bundle 包包括 bundle-union-1、bundle-union-testnet-10、bundle-union-1-next，genesis 文件取自 networks/genesis 下的 union-testnet-10/genesis.json。

NixOS 服务模块：flake.nixosModules.unionvisor 暴露 services.unionvisor 选项组，关键选项与默认值如下（摘自 unionvisor/unionvisor.nix）：

选项	说明	默认值
enable	启用 Unionvisor 服务	-
moniker	验证者节点名（必填字符串）	无
network	目标网络标识	union-1
seeds	种子节点列表	一个 testnet 种子地址
bundle	使用的 bundle 包	bundle-union-1
root / home	工作目录与 HOME	/var/lib/unionvisor
logFormat	日志格式（json / plain）	json
node-key-json / priv-validator-key-json	密钥文件路径（如 /run/secrets/...）	null
app-toml / config-toml / client-toml	覆盖对应 toml 配置文件的路径	null
extra-args	传给 unionvisor 的额外参数	[]

systemd 单元会先执行 unionvisor init --moniker ... --seeds ... --network ... --allow-dirty 完成初始化，再将用户提供的密钥/配置文件软链进 home/config/，最后执行 unionvisor run 并设置 Restart=always 与 UNIONVISOR_BUNDLE/UNIONVISOR_ROOT 环境变量。一个最小可用的 NixOS 验证者配置示例保存在 unionvisor/usage.nix（打开 80/443/26656/26657 端口并设置 services.unionvisor.enable = true）。

从源码结构看，unionvisor/src 下 bundle.rs、supervisor.rs、watcher.rs、init.rs、symlinker.rs 等模块与上述机制一一对应；src/testdata/ 中 test_restart（bundle 内含 upgrade1/upgrade2 两个版本）、test_early_exit、test_revert、test_swap 等目录说明升级回退、进程重启、二进制切换等生命周期场景都有集成测试覆盖，checks.unionvisor-tests 即运行这些测试。

galoisd：ZK 证明器

galoisd 是 ZK prover：验证者无需运行它，但 IBC 中继器与 MEV searcher 需要它来处理交易、捕获价值。它提供 gRPC 服务为 CometBLS 区块头生成共识证明，且自身不产生块数据——需要 IBC 中继器之类的外部服务把区块数据送进来做 ZKP 生成（见 galoisd/README.md）。

从仓库结构可确认其实现布局：

• galoisd/grpc：gRPC 服务层（server.go、bls12381_server.go 等），API 定义在 galoisd/proto/api；
• galoisd/pkg/lightclient：CometBLS 轻客户端电路，负责区块间（非）相邻转换的签名验证；
• galoisd/pkg/merkle、galoisd/pkg/emulated、galoisd/pkg/bls：分别对应 merkle（MiMC 验证者集根）、BN254 G2 仿射算术、BLS 聚合与签名验证三类 gadget。

其电路基于 Gnark，对 $2^n$ 个验证者泛型，且明确声明"为轻客户端定制，部分实现可能在不同上下文中不健全，不建议单独复用"。关键约束包括：聚合前每个公钥必须已做过 proof-of-possession 校验；唯一公输入是各输入字段的 SHA-256 截断至 31 字节（适配 BN254 标量域）；电路当前面向最多 128 个验证者设计。

生产部署方面，galoisd/README.md 给出明确警告：证明是计算密集型操作，galoisd 不设计为公共服务，错误配置可能招致拒绝服务攻击；生产环境应使用受控的 Docker 镜像（按 <VERSION> 拉取）或 Nix 包。

支撑模块：tools 与 networks

ARCHITECTURE.md 的 "Support" 一节列出了两个支撑目录，结合仓库实际内容：

• tools/：引入第三方与开发工具。tools/ 目录下包含 crane、scarb、rust-proto、move-bindgen、docgen、union-test、tidy 等以 Nix 函数或 Cargo 项目形式封装的工具，服务于 Rust/Cairo/Solidity 多语言工具链与 CI（如 tools/mkCi.nix、tools/vendor.nix）。
• networks/：定义 Union 与 Ethereum 网络的 docker-compose 配置用于本地测试。networks/README.md 将其结构说明为：networks 分 devnet（开发者本地模拟完整端到端网络）、testnet（Union 自持节点上的类主网环境）、mainnet（生产环境）三档；genesis/ 存放各网络创世配置（仓库中已有 40 个 genesis.json）；services/ 存放 Nix 函数形式的服务生成器，按需注入依赖与网络特定配置；networks/devnet.nix 把创世配置与服务函数组合进 arion（docker-compose 的 Nix 封装）spec，从而得到可复现的本地网络。

阅读与贡献路径小结

综合 ARCHITECTURE.md 与仓库现状，建议的探索路径是：先读本文件与 flake.nix 建立全局认知 → 按角色深入对应二进制（节点运维看 uniond/README.md 与 unionvisor/README.md，跨链证明看 galoisd/README.md）→ 用 nix flake show 枚举所有可用包 → 在组件目录内以文本搜索定位具体实现。需要注意的适用前提：生成代码当前入库、PoA 为孵化期临时共识、galoisd 电路面向 ≤128 验证者且不建议跨上下文复用，这些均以当前仓库内容为准，后续版本可能变化。