Architecture

TODO:

• Migrate references to ZNM

• Update links to stale documentation + old monorepo

Summary

Purpose

This document describes a governable system for executing permissioned actions across chains.

We aim to clearly describe

• what contracts comprise the system for calling permissioned functions across chains

• which functions will be delegated to this system at launch, and

• (directionally) who will have permission to call these functions at launch and in the future

Out of Scope

This document does NOT describe a system for how governance actions will be proposed, voted on, and/or approved before being executed.

It does not describe how contract upgrades will be written, reviewed, verified.

Overview

Pre-requisite Reading

• If you're not familiar with how Nomad cross-chain messaging passing works, we recommend checking out the Protocol section on Cross-chain Messaging.

• It may also help to familiarize yourself with the Router Pattern. The GovernanceRouter described below follows this pattern in the context of a cross-chain governance xApp.

We define a role, governor, with the power to perform permissioned actions across chains. In order to empower the governor, we deploy a cross-chain application comprised of a GovernanceRouter contract on each chain.

Each GovernanceRouter can be delegated control over an arbitrary set of permissioned functions on its local chain. The only way to access the permissioned functionality is to call the function via the GovernanceRouter contract.

Each GovernanceRouter is programmed to accept messages only from the governor, which is deployed on only one chain. The governor may call the contract locally (if it is deployed on the same chain), or it may send it messages remotely via Nomad. Because of its exclusive power over the GovernanceRouter contracts, the governor has exclusive rights to perform all of the permissioned roles that are delegated to the GovernanceRouter on each chain.

The system receives orders from the governor and carries out their effects across chains; it is agnostic to how the governor chooses to operate. This maintains flexibility to design the governance proposal process in the future.

At launch, the core functionality that will be delegated to the GovernanceRouter on each chain is the power to upgrade the implementation of the Home and Replica contracts. This way, the governor will have the power to conduct upgrades of the Nomad system on every chain. More details on the upgradability system can be found here.

At launch, the governor will be a multisig of trusted team and community members. In the near future, the governor role will most likely be transferred to a more fully-featured set of contracts capable of accepting proposals, tallying votes, and executing successful proposals.

Message Flow Diagram

1. governor sends message to its local GovernanceRouter

2. GovernanceRouter dispatches the message...

   1. if the recipient is local, to the recipient directly (→ process finished)

   2. if the recipient is remote, via Nomad to the local Home contract (→ continue to 3)

3. Message is relayed from local Home to remote Replica via Nomad

4. Replica dispatches message to the remote GovernanceRouter

5. GovernanceRouter dispatched the message directly to the local recipient

Note on message recipient:

• the recipient may be a Replica or Home contract

• it may be an UpgradeBeacon that controls the implementation of Replica or Home

• it may be any other app

For simplicity & clarity to show the message flow, this diagram represents the recipient as a generic "App"

Specification

Glossary of Terms

• xApp - Cross-Chain Application

• role —

  • an address stored in a smart contract's state that specifies an entity with special permissions on the contract

  • permission to call certain functions is usually implemented using a function modifier that requires that the caller of the function is one of the roles with permission to call it; all contract calls sent from callers that do not have valid permission will revert

  • example: owner is the role set on all Ownable contracts upon deployment; the owner role has exclusive permission to call functions with the onlyOwner modifier
• permissioned function —

  • any smart contract function that restricts callers of the function to a certain role or roles

  • example: functions using the onlyOwner modifier on Ownable contracts
• permissioned call — a call to a permissioned function

• governor chain —

  • the chain on which the governor is deployed

  • the chain whose GovernanceRouter is also the special GovernorRouter which can send messages; all GovernanceRouters on other chains can only receive governance messages

On-Chain Components

GovernanceRouter

• xApp designed to perform permissioned roles on core Nomad contracts on all chains

• State Variables

• governor state variable

  • if the governor is local, governor will be set to the EVM address of the governor

  • if the governor is remote, governor will be address(0)

• governorDomain state variable

  • the Nomad domain of the governor chain

  • stored as a state variable on all GovernanceRouters; should be the same on all GovernanceRouters; always non-zero

    • if the governor is local, governorDomain is equal to the originDomain of the local Home contract

    • if the governor is remote, governorDomain is equal to the originDomain of the remote Home contract

  • equal to the originDomain of the local Home contract on the chain of the GovernorRouter

  • used by all GovernanceRouters to determine whether an incoming Nomad message was sent from the GovernorRouter

    • if the message is from the GovernorRouter, the GovernanceRouter will handle the incoming message

    • if not, it will revert

• routers state variable

  • a mapping of domain → address of the remote GovernanceRouter on every other chain

• domains state variable

  • an array of all domains that are registered in routers

  • used to loop through and message all other chains when taking governance actions

  • there is the possibility that some domains in the array are null (if a chain has been de-registered)

• GovernorRouter

  • the special GovernanceRouter that has permission to send governance messages to all other GovernanceRouters

  • the GovernanceRouter on the governor chain

Governor

• via the GovernanceRouter system, it has the unique ability to call permissioned functions on any contract on any chain that transfers permission to the local GovernanceRouter

• the role with permission to send messages to the GovernorRouter

  • the GovernorRouter has exclusive permission to send messages via Nomad to all other GovernanceRouters

  • the GovernanceRouters can have arbitrary permissions delegated to them by any contract on their local chain

  • therefore, the governor is the entity with the power to call any permissioned function delegated to any GovernanceRouter on any chain

• there is only one governor throughout the Nomad system; it can be deployed on any chain

• the governor role can always be transferred to another contract, on the same chain or a different remote chain

• stored as a state variable on GovernanceRouters; set to zero on all GovernanceRouters except on the governor chain

• Any contract on any chain that wishes for this governance system to have discretion to call a set of its functions can create a role & a function modifier giving exclusive permission to that role to call the function(s) (similar pattern to Ownable). The contract must then set the local GovernanceRouter to the permissioned role, which — by extension — gives the governor exclusive permission to call those functions (regardless of whether the governor is remote or local)

Failure States#

If there is fraud on the Nomad Home contract on the governor chain, this is currently a "catastrophic failure state" — no further governance actions can be rolled out to remote chains; we must create a plan to recover the system in this case.

---

Message Types

Executing (Arbitrary) Calls

1. for each chain, the governor constructs the array of (to, data) calls to the permissioned functions on the contracts that will perform the upgrades on that chain

2. the governor sends a transaction to the GovernanceRouter.callRemote function on its local the , passing in the domain of the remote chain and the array of (to, data) calls of transactions to execute on that chain

3. the local GovernanceRouter constructs an Nomad-compatible message from the array of calls, addresses the message to the remote GovernanceRouter, and sends the message to the local Home contract

4. the message is relayed from the local Home to the remote Replica contract on the specified domain

5. the Replica dispatches the message to the specified recipient, which is the local GovernanceRouter

6. the GovernanceRouter parses the message to decode the array of (to, data) calls

7. the GovernanceRouter uses low-level call to execute each of the transactions in the array within the local chain

Transferring Governor

Possible State Transitions

1. called by the local owner to transfer ownership to another local owner (domain does not change, owner changes to a new bytes32 address)

2. called by the local owner to transfer ownership to a remote owner (domain changes to the remote, owner changes from a non-zero bytes32 to bytes32(0))

3. called by a remote owner to transfer ownership to a local owner (domain changes to the local domain, owner changes from bytes32(0) to a non-zero bytes32)

4. called by a remote owner to transfer ownership to another remote owner (domain changes to the new remote owner, owner remains bytes32(0))

Enrolling a Router

• used when a new chain is added to Nomad after we've already set up the system and transferred governorship

• add a new domain → address mapping to the routers mapping on every other GovernanceRouter

---

Functionality at Launch

Permissioned Roles

At launch, the GovernanceRouter system will have the following permissions:

1. upgrade the implementation of Home (via UpgradeBeacon pattern)

2. upgrade the implementation of all Replicas (via 1-to-N UpgradeBeacon pattern)

3. upgrade the implementation of itself (via UpgradeBeacon pattern)

The GovernanceRouter will NOT have permission to:

• un-enroll a Replica from the UsingNomad contract, which will require a specialized role that can act quickly

Governor

The flexibility of this system will support a move to progressive decentralization.

Initially, the governor will most likely be a multisig controlled by trusted team and community members

Later, the governor role will most likely be transferred to a decentralized governance contract