Architecture Overview

Architecture Overview

This page provides an in-depth overview of the projects that make up the main Union repository. The goal of this page is to ensure that auditors and contributors are familiar with Union's projects and how these projects work together.

Projects

While the Union repo is host to many projects, the projects below makeup our core infrastructure.

• The Union Node (uniond) - Our Cosmos Node running CometBLS.
• Unionvisor - A supervisor for the uniond binary, ensuring it is updated correctly.
• Galois - The Union prover, used to conduct zero-knowledge proofs.
• Voyager - A relayer between Union's projects and it's counterparties.

The Union Node

Unionvisor

Galois

Voyager

Primary Workflows

Besides running our binaries, there are several workflows to be aware of to understand how our products work together.

This sections will walk you through those workflows and help you understand what parts of the codebase they touch.

Opening a Connection

Before transactions between Union and its counterparties can begin, a connection and channel needs to be opened. This can be accomplished by interfacing with the Voyager following the workflow below.

These steps will demonstrate opening a connection between a local Union and Ethereum devnet.

Creating Clients

Before creating a connection and channel to conduct transactions over, the Voyager needs to be made aware of the client networks. This can be done with the client create sub-command of Voyager:

# Create a union client
relayer client create union ethereum08-wasm --on union-devnet --counterparty ethereum-devnet --evm-preset minimal

# Create an evm client
relayer client create evm cometbls --on ethereum-devnet --counterparty union-devnet

The client create command has two sub-commands used above: union ethereum08-wasm and evm cometbls.

This will use the call the create_client function implemented by both Union and Evm. This function will contact either the Union or Ethereum chain to get a client ID that is unique to the network.

The entry-point for the client create command can be found here. After this point, the command follows this sequence diagram:

sequenceDiagram
    participant Union
    participant Relayer
    participant Evm

    par Create WASM Client
        Relayer->>+Union: create_client
        Union-->>-Relayer: client_id
    and Create IBC Handler Instance
        Relayer->>+Evm: create_client
        Evm-->>-Relayer: client_id
    end

Loading

With the client ID retrieved, the connection handshake can begin.

Connection Handshake

To start the connection handshake, we can use the connection open sub-command of Voyager.

relayer connection open --to-chain union-devnet --to-client 08-wasm-0 --from-chain ethereum-devnet --from-client cometbls-new-0

The example above creates a connection to the Union devnet from the Ethereum devnet.

This will start the process of collecting state data from both chains, submitting a proof request to Galois, and relaying the chain state and proof between networks. While relaying this data, a connection attempt is made and confirmed.

The entry-point for this command is here. After this point, the command follows this sequence diagram:

sequenceDiagram
    participant Union
    participant Relayer
    participant Evm

		note over Union, Evm: connection handshake

    Relayer->>+Evm: MsgConnectionOpenInit
    Evm-->>-Relayer: connection_id

    Relayer->>+Union: MsgConnectionOpenTry
    Union-->>-Relayer: <<success>>

    Relayer->>+Evm: MsgConnectionOpenAck
    Evm-->>-Relayer: <<success>>

    Relayer->>+Union: MsgConnectionOpenConfirm
    Union-->>-Relayer: <<success>>

Loading

Once success has been reported, the IBC connection is established.

Channel Handshake

Finally, before transactions can be conducted - a channel needs to be opened for the transaction to be conducted on.

To start a channel handshake, you can use the channel open sub-command of Voyager.

relayer channel open --from-chain union-devnet --from-connection connection-1 --from-port wasm.CONTRACT_ADDRESS --to-chain ethereum-devnet --to-connection connection-2 --to-port transfer

Similar to the connection open sub-command, the channel open sub-command will collect state data from both chains, submit a proof request to Galois, and relay the chain state and proof between networks.

The entry-point of this command can be found here. After this point, the command follows this sequence diagram:

sequenceDiagram
    participant Union
    participant Relayer
    participant Evm

		note over Union, Evm: channel handshake

    Relayer->>+Evm: MsgChannelOpenInit
    Evm-->>-Relayer: channel_id

    Relayer->>+Union: MsgChannelOpenTry
    Union-->>-Relayer: <<success>>

    Relayer->>+Evm: MsgChannelOpenAck
    Evm-->>-Relayer: <<success>>

    Relayer->>+Union: MsgChannelOpenConfirm
    Union-->>-Relayer: <<success>>

Loading

Once success has been reported, the IBC channel is established.

Instantiating Union's ICS20 Contract

uniond tx wasm instantiate 1 \
  '{"default_timeout":10000,"gov_contract":"union1jk9psyhvgkrt2cumz8eytll2244m2nnz4yt2g2","allowlist":[]}' \
  --label blah \
  --from alice \
  --gas auto \
  --keyring-backend test \
  --gas-adjustment 1.3 \
  --amount 100stake \
  --no-admin \
  --chain-id union-devnet-1 \
  -y

uniond query wasm list-contracts-by-code 1 | yq '.contracts[-1]' --raw-output

Sending Transactions

Cosmos → Ethereum

uniond tx wasm execute \
  union14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9s3e9fe2 \
  '{"transfer":{"channel":"channel-7","remote_address":"be68fc2d8249eb60bfcf0e71d5a0d2f2e292c4ed"}}' \
  --amount 100stake \
  --from alice \
  --keyring-backend test \
  --chain-id union-devnet-1 \
  --gas 10000000 \
  -y

Ethereum → Cosmos

relayer \
  --config-file-path ~/projects/union/union/relayer-config.json \
  transfer \
  --from ethereum-devnet --to union-devnet \
  --amount 10 \
  --denom "transfer/channel-0/stake" \
  --receiver union1jk9psyhvgkrt2cumz8eytll2244m2nnz4yt2g2 \
  --source-port transfer \
  --source-channel channel-0