Merge pull request #67 from gnosis/docs/README

docs/README

README.md

@@ -1,18 +1,8 @@
-> **⚠️ Warning ⚠️**
->
-> **⚠️ This code is being actively developed and is not yet production ready.**
->
-> **⚠️ DO NOT deploy this code or use deployments of this code for anything valuable.**
-
----
-
 [![Github Actions][gha-badge]][gha] [![Coverage Status][coveralls-badge]][coveralls]
 [![Hardhat][hardhat-badge]][hardhat] [![License: LGPL-3.0-only][license-badge]][license]
 
 ![Hashi](hashi.png)
 
-# Hashi 橋
-
 [coveralls]: https://coveralls.io/github/gnosis/hashi?branch=master
 [coveralls-badge]: https://coveralls.io/repos/github/gnosis/hashi/badge.svg?branch=main
 [gha]: https://github.com/gnosis/hashi/actions
@@ -22,6 +12,8 @@
 [license]: https://www.gnu.org/licenses/lgpl-3.0.en.html
 [license-badge]: https://img.shields.io/badge/License-LGPL%20v3.0-blue
 
+# Overview
+
 Hashi is an EVM Hash Oracle Aggregator, designed to facilitate a
 [principled approach to cross-chain bridge security](https://ethresear.ch/t/a-principled-approach-to-bridges/14725?u=auryn).
 
@@ -31,6 +23,8 @@ validated by multiple independent mechanisms, rather than by just one.
 
 We call this setup a **RAIHO** (Redundant Array of Independent Hash Oracles).
 
+For more details: https://crosschain-alliance.gitbook.io/hashi
+
 ## Features
 
 **Hashi** (橋) allows users to:
@@ -55,34 +49,83 @@ We call this setup a **RAIHO** (Redundant Array of Independent Hash Oracles).
 
 - dispatch arbitrary messages via Hashi, which:
   - emits the hash of arbitrary messages as events
-  - stores the arbitrary message in storage
+  - stores the hash of arbitrary message in storage
 - relay previously stored messages to any number of message adapters
 - dispatch messages and relay them to adapters in a single call
 
 **Yaru** (やる) allows `owner` to:
 
 - execute arbitrary messages passed from Yaho
 
-**Hashi Zodiac Module** allows users to:
+# Working with Hashi
+
+**Node**
+This repository targets v18 of node. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage your node version.  
+Once installed, you should change versions automatically with the `.nvmrc` file.
+
+**Docker**
+Make sure you have the correct version of [Docker](https://www.docker.com/) installed on your machine.  
+You may refer to `Dockerfile` under each workspace and `docker-compose.yml` on the root for more details regarding the build process.
+
+## Project Structure
+
+1. `packages/common`: Common logic that will be used across multiple workspaces.
+2. `packages/evm`: On chain components includes Solidity smart contracts, deploy tasks, tests. Built with [Hardhat](https://hardhat.org/).
+3. `packages/executor`: A service utilized to execute messages once they have achieved consensus.
+4. `packages/relayer`: A service used to relay batches of dispatched messages through Yaho to the reporter contracts.
+5. `packages/reporter`: Script to call Reporter contract's `dispatchBlocks` function of different oracle from source chain to destination chain.
+
+# Workspaces
+
+This monorepo uses [Yarn Workspaces](https://yarnpkg.com/features/workspaces). Installing dependencies can be done from the root directory of the repository.
+
+- Installing dependencies
 
-- Control an avatar (like a Safe) on one chain from a `controller` address on another chain, via messages passed over hashi.
-- Define an instance of Yaho which can pass it messages.
-- Define a `chainId` (usually called `domain` elsewhere in this repo).
-- Define a foreign `controller` address.
+  ```sh
+  git clone https://github.com/gnosis/hashi # Clone the repo
+  cd hashi
+  nvm use
+  yarn install
+  ```
 
-Hashi's additional redundancy obviously comes with a higher gas cost, along with moving only as quickly as the slowest
-oracle in a given set. However, this trade-off seems well worth it given the scope and frequency of past bridge-related
-security incidents.
+## Build & Run
+
+To build & run each packages, navigate to each package separately, check the README.md in each workspace for more details.
+
+## Run Docker
+
+Before running docker for the workspace, insert the correct environment variable in .env.
+
+```sh
+cp .env.example .env
+```
+
+Build & run
+Run the following command to build and run all the services.
+
+```sh
+docker compose up --build
+```
 
 ## Audits
 
+### v0.1
+
 Hashi has been audited by the [G0 group](https://github.com/g0-group).
 
 All issues and notes of the audit have been addressed as of commit hash [9f373635](https://github.com/gnosis/hashi/tree/9f373635730b59478bf23215906fdb5ad525d3b7/packages/evm/contracts).
 
 The audit results are available as a [pdf in this repo](https://github.com/gnosis/hashi/blob/main/packages/evm/contracts/docs/audits/HashiMay2023.pdf).
 
-Please note, there have been changes to contract code since this audit. A subsequent audit of the changed code is pending.
+### v0.2
+
+Hashi has been audited by the [G0 group](https://github.com/g0-group).
+
+All issues and notes of the audit have been addressed as of commit hash [f1a9fdb](https://github.com/gnosis/hashi/tree/f1a9fdb2998c7024268e9c69777f4dc43d2f775e/packages/evm)
+
+The audit results are available as a [pdf in this repo](https://github.com/g0-group/Audits/blob/master/HashiMar2024.pdf).
+
+Additional audits can be found [here](https://crosschain-alliance.gitbook.io/hashi/v0.2/audit-report).
 
 ## Security and Liability
 

packages/common/README.md

@@ -1 +1,21 @@
-# common
+# Common
+
+Common logic that will be used across multiple workspaces/packages.
+
+## Usage
+
+### Install
+
+Please make sure you have run `yarn install` on the root level.
+
+```sh
+cd ../.. # To the root level
+nvm use
+yarn install
+```
+
+### Compile
+
+```sh
+yarn compile
+```

packages/evm/README.md

@@ -0,0 +1,72 @@
+# EVM
+
+This workspace includes on chain components such as Solidity smart contracts, deploy tasks, and tests.  
+The project is built with [Hardhat](https://hardhat.org/).
+
+## Configuration
+
+Create a new `.env` with the required environment variables.
+
+```sh
+cp .env.example .env
+```
+
+## Usage
+
+### Install
+
+Please make sure you have run `yarn install` on the root level.
+
+```sh
+cd ../.. # To the root level
+nvm use
+yarn install
+cd packages/evm
+```
+
+### Compile the contracts
+
+```sh
+yarn build
+```
+
+### Deploy & Verify
+
+To deploy a specific contract,
+
+```sh
+yarn hardhat ${task_name} --${arg1Name} ${arg1Value} --${arg2Name} ${arg2Value} --network ${network name}
+```
+
+Run `yarn hardhat` to check the available options.
+
+To verify a contract,
+
+```sh
+yarn hardhat verify ${contract address} "${constructor arg1}" "${constructor arg2}" --network ${network name}
+```
+
+### Test
+
+```sh
+yarn test
+```
+
+## Adding a new adapter
+
+1. Create Reporter and Adapter contracts:
+
+   1. For General Message Passing oracle, there need to be a reporter contract on source chain, and adapter contract on
+      destination chain.
+   2. For Light Client based oracle, there is only an adapter contract on the destination chain.
+   3. A reporter contract need to inherit `Reporter.sol`, and override `_dispatch()` function that will eventually call
+      the relay logic of the bridge.
+   4. An adapter contract need to inherit `Adapter.sol` contract, and call `_storeHashes` to store the hash w.r.t an id.
+
+2. Add Deploy task
+   1. Create a new file under `/tasks/deploy/adapters`, and name it ${oracle_name}.ts
+   2. Add the reporter and adapter contracts deploy logic.
+3. Add test
+   1. Create a new file under `/test/adapters`.
+   2. Add the test logic.
+4. Create PR

packages/executor/README.md

@@ -1,59 +1,53 @@
-# executor
+# Hashi Executor
 
 The Executor is a service utilized to execute messages once they have achieved consensus, meaning when adapters have
 reached consensus on the message.
 
- 
+## Getting Started
 
----
+These instructions will cover the usage information and how to run the code locally for development or using Docker.
 
- 
-
-## Installation
+## Configuration
 
-To install the Executor, follow these steps:
+Before running the Relayer, you need to create an `.env` file. All parameters can be found within `.env.example`.
 
-```bash
-git clone https://github.com/gnosis/hashi
-cd hashi
-nvm use
-yarn install
+```sh
+cp .env.example .env
 ```
 
- 
-
----
-
- 
-
-## Configuration
+## Usage
 
-Before running the Executor, you need to create an `.env` file. All parameters can be found within `.env.example`.
+### Install
 
- 
+Please make sure you have run `yarn install` on the root level.
 
----
+```sh
+cd ../.. # To the root level
+nvm use
+yarn install
+cd packages/executor
+```
 
- 
+Run mongoDB and export port 27017
 
-## Usage
+```sh
+docker run -d \
+  --name mongodb \
+  -p 27017:27017 \
+  mongo
+```
 
 To start Executor, run the following command:
 
-```bash
+```sh
 cd packages/executor
-```
-
-```bash
-yarn start dotenv_config_path="your env file"
+yarn start
 ```
 
 ### Building and Running the Docker Image
 
-Executor is usually run with Relayer and MongoDB, the `docker-compose.yml` demonstrates how to run these three images
-together.
-
-Run the following command:
+Executor needs to connect with MongoDB, the `docker-compose.yml` demonstrates how to run these images together. Run the
+following command:
 
 ```sh
 cd ../..  # To the root level
@@ -70,7 +64,7 @@ docker logs -f [CONTAINER_ID or CONTAINER_NAME]
 
 You can find the `CONTAINER_ID` or `CONTAINER_NAME` using `docker ps`.
 
-### Stopping the relayer
+### Stopping the executor
 
 To stop the running container: