# Cross-chain minion using Zodiac/Nomad module

## Nomad overview

- A base layer for "Radically cheaper" cross-chain communication without header verification
- took inspiration from optimistic systems (e.g. public verification, lower gas fees, broader participation) **with a different security model**
- Nomad permits frauds but leaves info open for participant to submit fraud proofs before finalization
- **TL;DR**: rather than using a globally verifiable fraud-proof, Nomad relies on local verification by participants
- "**Updater**" needs to submit a bonding stake to send messages
- Fraud can always be proven to the "**Home* contract on the sending chain and bonds can be slashed if fraud is proven
- Security guarantees that all frauds may be published by any participant during a time window
- Relies only on widely-available cryptographic primitives (unlike header relays)
- Latency of 30 minutes (rather than an ORU’s one week latency)
- Imposes only about 120k gas overhead on message senders.

### How Nomad Works: An Overview


- The sending **HOME chain** produces a series of documents (messages) that needs notarization.
- A notary (**Updater**) is contracted to sign it.
- The notary can produce a fraudulent copy, but they will be punished by having their bond and license publicly revoked
- Just like Optimistic systems, Nomad sees an attestation of some data, and accepts it as valid after a timer elapses
- While the timer is running, honest participants have a chance to respond to the attestation and/or submit fraud proofs.
- Nomad spans **multiple chains**.
- The sending chain is the *source of truth*, and contains the **Home contract** where messages are enqueued.
- Messages are committed to in a merkle tree.
- Merkle root is notarized by the **Updater** and **relayed** to the receiving chain in an *update*.
- Updates are signed by the Updater. They commit to the previous root and a new root.
- Any chain can maintain a **Replica contract**, which holds knowledge of the Updater and the current merkle root.
- Signed updates are held by the Replica, and accepted after a timeout.
- The Replica effectively replays a series of updates to reach the same root as the Home chain.
- This leaves open the possibility that the Updater signs a fraudulent update.
- Unfortunately, certain types of fraud can't be objectively proven on the receiving chain; Replicas can't know which messages the home chain intended to send and therefore can't check message tree validity in all cases.
- However, if a message is falsified by an Updater and submitted to the Replica, that update is public
- Because the Replica waits to process messages, Nomad guarantees that honest dapps can always prevent processing of dishonest messages.
- Nomad built a robust system for delegating the responsibility of fraud detection, so Nomad guarantees:
- Frauds are costly
- Frauds knowledge is public -> all users can learn about potential frauds
- All users can block a fraudulent message before they are accepted

### Architecture Overview


#### On-chain Components

- **Home** contract ---> responsible for managing production of the message tree and holding custody of the Updater bond.
- **Replica** contract ---> responsible for managing optimistic replication and dispatching messages to end recipients

#### Off-chain Agents
- **Updater** ---> responsible for signing attestations of new roots & publishing the signed attestation to the Home chain
- **Watcher** ---> observes Updater's interactions with the Home contract and reacts to malicious or faulty attestations.
- Also observes any number of Replicas to ensure the Updater does not bypass the Home and go straight to a Replica.
- **Relayer** ---> forwards updates from the Home to one or more Replicas.
- **Processor** ---> proves the validity of pending messages and sends them to end recipients

#### Message forwarding between chains
- Nomad creates an authenticated data structure on a Home chain, and relays updates to that data structure on any number of Replicas
- By embedding data ("messages") in this data structure we can propagate it between chains with a high degree of confidence
- The home chain elects an "Updater" that must attest to the state of the message tree. The updater places a bond on the Home chain and is required to periodically sign attestations
- The new root MUST be a member of the queue otherwise Updater stake will be slashed
- Updates represent a batch commitment to the messages between the two roots
- Updates may occur at any frequency, as often as once per message
- Updates are chain-independent
- Data availability of signed updates is guaranteed by each chain
- Before accepting an update, a Replica places it into a queue of pending updates. Each update must wait for some time parameter before being accepted.
- Waiting system guarantees that fraud is publicly visible on the Home chain before being accepted by the Replica

#### Nomad channels for Cross-chain communication - Router contracts

- Nomad sends messages from one chain to another in the form of raw bytes
- Each cross-chain application **MUST** implement its own messaging protocol. (AKA **Router contract**).
- End goal: **create a working cross-chain application (xApp) using a common language and set of rules**
- Applications of this kind may deploy its Router contract across multiple-chains and **use Nomad as the cross-chain courier** for sending and receiving messages to each other.
- A Router contract must:
- maintain a permissioned set of the contract(s) on remote chains from which it will accept messages via Nomad (remote Routers)
- could be a single owner of the application on one chain
- could be a registry of other applications implementing the same rules on various chains
- maintain a permissioned registry of connections via the **XappConnectionManager** contract
- encode messages in a standardized format
- handle messages from remote Router contracts
- local handler decodes the message into application-specific instructions
- dispatch messages to remote Router contracts
- encode the instructions into bytes using standardized message format
- dispatch the bytes-encoded message to Nomad (to be sent to a remote chain)

### How to implement xApps

- Define the actions you would like to execute across chains. For each type of action in the Router contract:
- Implement a function `doAction(**param)` to initiate the action from one domain to another
- Implement a corresponding `_handle` function to receive, parse, and execute this type of message on the remote domain
- Add logic to the `handle` function (from Nomad Router abstract contract) to route incoming messages to the appropriate `_handle` function
- xApp Template:
- [Router Template](https://github.com/nomad-xyz/examples/blob/main/packages/xapp-example/contracts/xapp-template/MessageTemplate.sol)
- [Message Library Template](https://github.com/nomad-xyz/examples/blob/main/packages/xapp-example/contracts/xapp-template/MessageTemplate.sol)
- Uses [Memview-Sol](https://github.com/summa-tx/memview-sol) library for identifying action types within messages
- Implement a messaging protocol library that:
- has functions to **format** the message to send to the other chain
- has functions to **parse** the message once it is received on the other chain

### Nomad Benefits
- Nomad broadcast channel allows for a single-producer, multi-consumer model. This ensures that 1 accumulator can communicate with any number of receiving chains
- Much cheaper than other options, allowing updates and proofs to cost <100k gas and be checked by only 1 signature
- Rely on fraud publication rather than fraud proofs to improve the speed and cost of sending messages.
- Any potential fraud is disincentivized and costly

### Nomad Contracts

[Monorepo](https://github.com/nomad-xyz/monorepo)
[Examples xApps Repo](https://github.com/nomad-xyz/examples)

#### contracts-router/Router.sol

- An xApp Router needs to implement this [Abstract contract](https://github.com/nomad-xyz/monorepo/blob/main/packages/contracts-router/contracts/Router.sol)
- `function handle(
uint32 _origin,
uint32 _nonce,
bytes32 _sender,
bytes memory _message
) external virtual override`
- `modifier onlyReplica()`
- `modifier onlyRemoteRouter(uint32 _origin, bytes32 _router)`
- Only accept messages from remote Routers
- `function _home() internal view returns (Home)`
- Get the local Home contract from the xAppConnectionManager
- `function _isReplica(address _potentialReplica) internal view returns (bool)`
- whether _potentialReplica is an enrolled Replica from the xAppConnectionManager
- Implements the [XappConnectionClient](https://github.com/nomad-xyz/monorepo/blob/main/packages/contracts-router/contracts/XAppConnectionClient.sol) abstract contract
- Provides convenience functions for working with a `XAppConnectionManager` (XCM)
- When deploying an **xApp Router**, the xApp administrators must select an existing XCM, or deploy their own.
- The address of the XCM must be passed to the router's initialization method.

#### contracts-core/XAppConnectionManager.sol

- [Contract code](https://github.com/nomad-xyz/monorepo/blob/main/packages/contracts-core/contracts/XAppConnectionManager.sol)
- XCM is the primary permissioning point for channels. It provides functions by which xApp administrators can:
- Enroll/unenroll Replica contracts for inbound messages
- Enroll/unenroll a Home contract for outbound messages
- Permission/de-permission watchers
- Watchers can unenroll Replica contracts

#### contracts-core/Home.sol

- [Contract code](https://github.com/nomad-xyz/monorepo/blob/main/packages/contracts-core/contracts/Home.sol)
- Accepts messages to be dispatched to remote chains
- Constructs a Merkle tree of the messages
- Accepts signatures from a bonded Updater
- Accepts submissions of fraudulent signatures

#### contracts-core/Replica.sol

- [Contract code](https://github.com/nomad-xyz/monorepo/blob/main/packages/contracts-core/contracts/Replica.sol)
- Track root updates on Home
- Prove and dispatch messages to end recipients.

### Deployed contracts

- Some of the Nomad libraries are built through their [Rust monorepo](https://github.com/nomad-xyz/rust)
- [Config files](https://github.com/nomad-xyz/rust/tree/main/configuration/configs) are on `@nomad-xyz/configuration` package
- Contracts deployed on [Testnets](https://github.com/nomad-xyz/rust/blob/main/configuration/configs/development.json)
- Contracts deployed on [Production chains](https://github.com/nomad-xyz/rust/blob/main/configuration/configs/production.json)

## Zodiac/Nomad Module

[Repo](https://github.com/gnosis/zodiac-module-nomad)

#### Disecting components

- NomadModule -> this is the "Router" contract required for an xApp
- Deployment params
- address _owner -> safe address in Foreign chain
- address _avatar -> safe address in Foreign chain
- address _target -> safe address in Foreign chain
- address _manager -> XAppConnectionManager address in Foreign chain
- address _controller -> Safe Minion on the Home chain
- uint32 _controllerDomain -> Home chain domain Id
- List of Nomad domains (int Ids) seems imcomplete
- ~~https://docs.nomad.xyz/dev/domain-ids.html~~
- Actually Defined in `@nomad-xyz/configuration` (See [Deployed contracts](#Deployed-contracts))

#### Daohaus integration notes from Jun 22

Contract:

- deployment
- means creating a Safe on the hom chain and deploying the nomad module for the safe on the remote chain.
- sending messages
- Communicate with home contract (like AMB bridge)
- Controller sends message
- nomad module executes (gas payed by nomad unless mainnet)

Adding nomad module from UI
- process is similar to AMB

Subgraph changes
- added new field bridgeModule

example
bridgeModule: AMB/Nomad
minion type: Safe minion v0
details: Nomad

Front end changes
- basically a clone of cross chain module but pointing to the nomad module proxy factory on deploy. proposal details will need to monitor state from the nomad contracts.
- remote chain execute button (only needed on mainnet)

**to look into:** errors with new v2 summoner, verify the address on rinkeby and goerli front end. verify that deploy is working from block explorer