This document describes the high-level architecture of Union and associated packages. If you are contributing, auditing or just having a look at the tech, this is the place to start. If you aren't a developer or unfamiliar with Go and Rust, it's probably better to have a look at the official docs instead.
At the root of the repository, you'll find directories such as uniond, unionvisor, and galoisd, which are binaries necessary to run the network. To see how to build one of these binaries, check the flake.nix file. These binaries can be built by running
nix build .\#uniond # or unionvisor or galoisdTo see all packages/apps that we define, run nix flake show. To see how these are built, check out flake.nix. Here we import all flake-parts, such as uniond/uniond.nix.
Currently generated code, such as protobuf definitions and a vendor directory, are checked into the repo. This will be removed later once we add support for private repos and proto derivations.
We attempt to have a README.md for every significant component, describing what it is and how to work on it.
Source code is always the source of truth. The best location to get into the nitty-gritty details is doc comments. We currently do not publish these, but might in the future.
We refrain from separating docs and links from the actual code, as refactors can create dead links and stale docs. It's best to use text search to find where components are defined, as PRs are still adding significant components.
uniond is the network node, which is run by validators to produce blocks.
unionvisor is a supervisor of uniond, which makes deployments easier and more resilient. It is not required for node operations but is recommended.
galoisd is the ZK prover. Validators do not need to run it, but IBC relayers and MEV searchers will need to process transactions and capture value.
tools is used to bring in 3rd party tooling and development tools.
networks is used to define docker-compose configurations of Union and Ethereum networks for local testing.