This guide is intended for validators running on bare-metal servers and explains how Union releases work. Check out the NixOS and the Kubernetes guide for more production-ready deployments.

Validators are the backbone of the network. Becoming one requires significant token bonding and delegations, and is not intended for non-power users.

Obtaining uniond

Note Currently, directly downloading the uniond binary requires access to our private GitHub repository. We are not currently providing the general public access to our GitHub repositories. If you don’t have access to our private GitHub repository, you can still run our node using the public Docker image.

You can obtain uniond from a recent release.

Caution Double-check the version and architecture in the link before downloading.

• x86_64-linux

• aarch64-linux

curl --output uniond --location https://github.com/unionlabs/union/releases/download/$UNIOND_VERSION/uniond-release-x86_64-linux

Where UNIOND_VERSION is v0.24.0

Verify that the binary works on your server by running:

./uniond --help

For convenience, we can add the binary to the PATH, to make it callable from anywhere.

mv ./uniond /usr/bin/

Using Docker

We also provide containers in our package registry.

docker pull ghcr.io/unionlabs/uniond-release:$UNIOND_VERSION

Where UNIOND_VERSION is v0.24.0

When running the container, make sure to map a volume to the path passed in --home options to ensure data persistence. From here on the guide assumes the usage of a regular binary. The docker-compose section is more suited for docker users.

Caution uniond is a stateful application and interacts with the file system. Make sure to use volumes.

Initialization

We’ll need to set up a few configuration files and obtain the genesis.json before we can run the node.

https://docs.union.build/genesis.json

First, set some environment variables, which are used throughout initialization.

export CHAIN_ID=union-testnet-8export MONIKER="Unionized Goblin"export KEY_NAME=aliceexport GENESIS_URL="https://union.build/genesis.json"

Then we’ll have uniond initialize our data and configuration directories. By default, /User/{USER}/.uniond is used.

uniond init $MONIKER --chain-id $CHAIN_ID

Seeds

Next, edit ~/.union/config/config.toml. We’ll set the seeds to ensure your node can connect to the peer-to-peer network.

For union-testnet-8 replace seeds = "" with:

seeds = "c2bf0d5b2ad3a1df0f4e9cc32debffa239c0af90@testnet.seed.poisonphang.com:26656"

Genesis Configuration

Download the genesis.json and copy it to your uniond home directory.

curl $GENESIS_URL | jq '.result.genesis' > ~/.union/config/genesis.json

Registration

To join as a validator, you need to submit a registration transaction. You can do this from the command line on your validator node.

First, add a wallet that holds Union tokens.

uniond keys add $KEY_NAME --recover

Caution For production usage, we recommend not storing the wallet on a server.

To submit the registration transaction and become a validator, you must submit a create-validator transaction:

uniond tx staking create-validator \  --amount 1000000muno \  --pubkey $(uniond tendermint show-validator) \  --moniker $MONIKER \  --chain-id $CHAIN_ID \  --from $KEY_NAME \  --commission-max-change-rate "0.1" \  --commission-max-rate "0.20" \  --commission-rate "0.1" \  --min-self-delegation "1"

Note If your own node isn’t set up to accept RPC request, you can send them to another node via the --node option.

Systemd Service

We recommend running uniond as a systemd service. Create a file in /etc/systemd/system called uniond.service. Make sure to replace $USER with your username.

[Unit]Description=uniond[Service]Type=simpleRestart=alwaysRestartSec=1User=$USERExecStart=/usr/bin/uniond start[Install]WantedBy=multi-user.target

You should be able to view the node logs by executing

sudo journalctl -f --user uniond

It’s then recommended to back up these files from ~/.union/config in a secure location:

• priv_validator_key.json

• node_key.json

Docker Compose

This guide assumes you are familiar with running a Union validator. If not, start with the validator guide.

docker-compose is a tool for running containers in a declarative manner. This allows for better automation, upgrades, and monitoring.

Configuration

Our base compose.yml is fairly simple:

services:  node:    image: "ghcr.io/unionlabs/uniond-release:$UNIOND_VERSION"    volumes:      - ~/.union:/.union      - /tmp:/tmp    network_mode: "host"    restart: unless-stopped    command: start --home /.union

Pay special attention to the volumes key. Here we map an already initialized ~/.uniond directory to the node service. The ~/.uniond directory should contain a config and data directory. To properly set these up, check out the validator guide.

Monitoring

We suggest adding additional monitoring services, such as datadog.

NixOS

NixOS deployments can use our module to easily manage their validator. It creates a systemd service with a production configuration

Caution The current example does not support remote signers yet. We will expand the guide once horcrux support is implemented.

Configuration

Below is an example configuration.nix which can be used in production.

Caution The example currently uses git+ssh:// syntax rather than github: syntax because our repository is not public yet. Once it is, this will be simplified. When this happens, GIT_LFS_SKIP_SMUDGE will also no longer be required.

{  inputs = {    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";    union.url = "git+ssh://git@github.com/unionlabs/union";  };  outputs = {self,nixpkgs,union, ... }:    {      nixosConfigurations.testnet-validator =        let          system = "x86_64-linux";          pkgs = importnixpkgs { inherit system; };        in        nixpkgs.lib.nixosSystem {          inherit system;          modules = [            union.nixosModules.unionvisor            {              system.stateVersion = "23.11";              # Base configuration for openstack-based VPSs              imports = [ "${nixpkgs}/nixos/modules/virtualisation/openstack-config.nix" ];              # Allow other validators to reach you              networking.firewall.allowedTCPPorts = [ 80 443 26656 26657 ];              # Unionvisor module configuration              services.unionvisor = {                enable = true;                moniker = "your-testnet-moniker";              };              # OPTIONAL: Some useful inspection tools for when you SSH into your validator              environment.systemPackages = with pkgs; [                bat                bottom                helix                jq                fastfetch                tree              ];            }          ];        };    };}

You can then deploy the configuration by running

GIT_LFS_SKIP_SMUDGE=1 nixos-rebuild switch --flake .\#testnet-validator --target-host user@validator.domain -L

Upgrading

To upgrade to newer versions, simply run

nix flake updateGIT_LFS_SKIP_SMUDGE=1 nixos-rebuild switch --flake .\#testnet-validator --target-host user@validator.domain -L

This will pull in the latest changes to union configurations and prepare your node for future upgrades.

Node Configuration

After successfully running your node with uniond, you can refer to this guide to aid you in configuring your node.

This is not a complete guide to all node configuration options, this is intended to help ensure that your node is fully operational.

This guide will assume that you’re starting at the root of your Union node configuration (located at ~/.union/ by default or ~/.unionvisor/home if you’re using Unionvisor).

Client Configuration

Located in config/client.toml, this file is host to client settings.

The Network Chain ID

Update this value to ensure that your client is supplied with the correct chain ID.

For the Union Testnet, this value should be "union-testnet-8".

# The network chain IDchain-id = "union-testnet-8"

Host/Port for the Tendermint RPC

This will determine which address your client will listen for Tendermint RPC request on.

This will default to "tcp://localhost:26657", setting this to "tcp://0.0.0.0:26657" will ensure it’s listening on every available network interface.

# <host>:<port> to Tendermint RPC interface for this chainnode = "tcp://0.0.0.0:26657"

App Configuration

Located in config/app.toml, this file is host to app settings.

Minimum Gas Price

Located under the “Base Configuration” section of config/app.toml.

While optional, you may wish to ensure your node receives a minimum fee when processing transactions. Whatever you choose for this value, ensure it uses the correct denom. For the Union Testnet, the correct denom is muno.

# The minimum gas prices a validator is willing to accept for processing a# transaction. A transaction's fees must meet the minimum of any denomination# specified in this config (e.g. 0.25token1;0.0001token2).minimum-gas-prices = "0muno"

Pruning

Located under the “Base Configuration” section of config/app.toml.

Several options are available here, ensure you’ve selected the one that best fits your nodes storage capabilities.

# default: the last 362880 states are kept, pruning at 10 block intervals# nothing: all historic states will be saved, nothing will be deleted (i.e. archiving node)# everything: 2 latest states will be kept; pruning at 10 block intervals.# custom: allow pruning options to be manually specified through 'pruning-keep-recent', and 'pruning-interval'pruning = "default"

Node Configuration

Located in config/config.toml, this file is host to many settings.

Consensus

To achieve a low target block time, the Union team asks validators to make the following changes to their configuration.

Located in the consensus TOML table under the “Consensus Configuration Options” section.

# How long we wait for a proposal block before pre-voting niltimeout_propose = "3s"# How much timeout_propose increases with each roundtimeout_propose_delta = "500ms"# How long we wait after receiving +2/3 prevotes for “anything” (ie. not a single block or nil)timeout_prevote = "1s"# How much the timeout_prevote increases with each roundtimeout_prevote_delta = "500ms"# How long we wait after receiving +2/3 precommits for “anything” (ie. not a single block or nil)timeout_precommit = "1s"# How much the timeout_precommit increases with each roundtimeout_precommit_delta = "500ms"# How long we wait after committing a block, before starting on the new# height (this gives us a chance to receive some more precommits, even# though we already have +2/3).timeout_commit = "1s"

RPC Listening Address

Located in the rpc TOML table under the “RPC Server Configuration Options” section.

You’ll want to ensure your node is configured to accept rpc connections. To do so, set this value to the appropriate address.

For example, to listen on every available network interface - set this to "tcp://0.0.0.0:26657".

# TCP or UNIX socket address for the RPC server to listen onladdr = "tcp://0.0.0.0:26657"

P2P Listening Address

Located in the p2p TOML table under the “P2P Configuration Options” section.

You’ll want to ensure your node is configured to accept p2p connections. To do so, set this value to the appropriate address.

For example, to listen on every available network interface - set this to "tcp://0.0.0.0:26656".

# Address to listen for incoming connectionsladdr = "tcp://0.0.0.0:26656"

External Address

Located in the p2p TOML table under the “P2P Configuration Options” section.

If you’ve configured a domain name for your node, this is the place to inform your node of it.

# Address to advertise to peers for them to dial# If empty, will use the same port as the laddr,# and will introspect on the listener or use UPnP# to figure out the address. ip and port are required# example: 159.89.10.97:26656external_address = "example.com:26656"

Seeds

Located in the p2p TOML table under the “P2P Configuration Options” section.

Seed nodes help orchestrate initial connections to the network. For union-testnet-8, the seed nodes are:

seeds = "c2bf0d5b2ad3a1df0f4e9cc32debffa239c0af90@testnet.seed.poisonphang.com:26656"

Seed Mode

Located in the p2p TOML table under the “P2P Configuration Options” section.

If you’d like to be a seed node, be sure to set this to true.

Caution If you plan for your node to be a validator, it should not also be a seed node.

# Seed mode, in which node constantly crawls the network and looks for# peers. If another node asks it for addresses, it responds and disconnects.## Does not work if the peer-exchange reactor is disabled.seed_mode = false

Overview of 0G Labs

0G Labs aims to develop a modular blockchain that separates data processing into distinct storage and publishing channels. This innovative design allows transactions to interact only with the necessary parts of the network, enhancing efficiency and reducing the load on validators. The integration of AI is intended to optimize network functionality and address the blockchain trilemma.

Key features of 0G Labs include:

• Modular Architecture: Enables flexibility and scalability for various decentralized applications (dApps).

• AI Integration: Enhances transaction efficiency and overall network performance.

• Decentralization Commitment: Maintains a decentralized structure to foster security and trust within the ecosystem.

Funding and Investor Interest

The recent funding round attracted investments from over 40 prominent crypto institutions, including Hack VC, Animoca Brands, OKX Ventures, and Delphi Digital. Originally aiming to raise $5 million, the overwhelming interest from investors led to a substantial oversubscription of the round. This reflects the growing confidence in 0G Labs' potential to contribute meaningfully to the blockchain landscape.

Partnership Opportunities

0G Labs is actively seeking partnerships with companies that align with its vision. Collaborating with 0G Labs offers numerous benefits, such as:

• Access to Innovative Technology: Partners can leverage advanced solutions for data accessibility and scalability.

• Development Support: Ongoing assistance to help partners enhance their projects and minimize operational costs.

Community Engagement

To foster community involvement, 0G Labs encourages active participation through various initiatives, including airdrops and testing phases. Community members can engage by following 0G Labs on platforms like Twitter, Telegram, and Discord, as well as participating in quests and tasks on platforms like Galxe to earn rewards and recognition.

Conclusion

With its ambitious goals and innovative approach, 0G Labs is poised to redefine the blockchain industry. By addressing critical challenges through AI integration and community engagement, the project is well-positioned to lead the way in developing scalable, secure, and decentralized applications. As 0G Labs continues to evolve, it will be exciting to observe the opportunities it creates for its partners and the broader blockchain community.