From 91b38e008a3ae9d228312f00300a11061ee49722 Mon Sep 17 00:00:00 2001 From: zengzengzenghuy Date: Tue, 24 Sep 2024 13:18:22 +0800 Subject: [PATCH 1/3] docs: update readme --- README_WIP.md | 89 ++++++++++++++++++++++++++++++++++ packages/common/README.md | 22 ++++++++- packages/evm/README.md | 72 +++++++++++++++++++++++++++ packages/executor/README.md | 62 +++++++++++------------ packages/relayer/README.md | 59 +++++++++++----------- packages/reporter/.env.example | 3 +- packages/reporter/README.md | 46 +++++++++++------- packages/reporter/package.json | 1 + 8 files changed, 267 insertions(+), 87 deletions(-) create mode 100644 README_WIP.md create mode 100644 packages/evm/README.md diff --git a/README_WIP.md b/README_WIP.md new file mode 100644 index 00000000..c4661fd7 --- /dev/null +++ b/README_WIP.md @@ -0,0 +1,89 @@ +# 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). + +The primary insight being that the vast majority of bridge-related security incidents could have had minimal impact if +the systems relying on them had built in some redundancy. In other words, it's much more secure to require messages be +validated by multiple independent mechanisms, rather than by just one. + +We call this setup a **RAIHO** (Redundant Array of Independent Hash Oracles). + +# 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 + + ```sh + git clone https://github.com/gnosis/hashi # Clone the repo + cd hashi + nvm use + yarn install + ``` + +## 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). + +The audit results are available as a [pdf in this repo](https://github.com/g0-group/Audits/blob/master/HashiMar2024.pdf). + +Please note, there have been changes to contract code since this audit. A subsequent audit of the changed code is pending. + +## Security and Liability + +All contracts are WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. + +## License + +Created under the [LGPL-3.0+ license](LICENSE). diff --git a/packages/common/README.md b/packages/common/README.md index d0553e6e..ea0d70fa 100644 --- a/packages/common/README.md +++ b/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 +``` diff --git a/packages/evm/README.md b/packages/evm/README.md new file mode 100644 index 00000000..b4692f81 --- /dev/null +++ b/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 diff --git a/packages/executor/README.md b/packages/executor/README.md index 0a0d0449..5800d3bf 100644 --- a/packages/executor/README.md +++ b/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: diff --git a/packages/relayer/README.md b/packages/relayer/README.md index 812afc57..be78cce2 100644 --- a/packages/relayer/README.md +++ b/packages/relayer/README.md @@ -1,56 +1,51 @@ -# relayer +# Hashi Relayer -The Relayer is a service used to relay batches of dispatched messages through Yaho to the adapters. +The Relayer is a service used to relay batches of dispatched messages through Yaho to the reporter contracts. -  +## 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 Relayer, 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 Relayer, 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/relayer +``` -  +Run mongoDB and export port 27017 -## Usage +```sh +docker run -d \ + --name mongodb \ + -p 27017:27017 \ + mongo +``` To start Relayer, run the following command: -```bash +```sh cd packages/relayer -``` - -```bash -yarn start dotenv_config_path="your env file" +yarn start ``` ### Building and Running the Docker Image -Relayer is usually run with Executor and MongoDB, the `docker-compose.yml` demonstrates how to run these three images -together. +Relayer needs to connect with MongoDB, the `docker-compose.yml` demonstrates how to run these images together. Run the following command: diff --git a/packages/reporter/.env.example b/packages/reporter/.env.example index 8ff12943..c3887b37 100644 --- a/packages/reporter/.env.example +++ b/packages/reporter/.env.example @@ -1,4 +1,3 @@ -# Fake private key PRIVATE_KEY= REPORTERS_ENABLED=WormholeReporterController,AMBReporterController,LayerZeroReporterController @@ -17,7 +16,7 @@ GOERLI_BEACON_API_URL= AMB_REPORTER_HEADERS_GAS=200000 AXELAR_REPORT_HEADERS_VALUE=0.0001 CELER_REPORT_HEADERS_VALUE=0.0001 -LAYER_ZERO_REPORT_HEADERS_VALUE=0.00015 +LAYER_ZERO_REPORT_HEADERS_VALUE=0 CCIP_REPORT_HEADERS_VALUE=0.002 CONNEXT_REPORT_HEADERS_VALUE=0.00003 ZETA_CHAIN_REPORT_HEADERS_VALUE=0.001 diff --git a/packages/reporter/README.md b/packages/reporter/README.md index 68e80f2c..4a171633 100644 --- a/packages/reporter/README.md +++ b/packages/reporter/README.md @@ -1,20 +1,36 @@ -# reporter +# Hashi Reporter -Script to call Header Reporter contracts of different oracle from source chain to destination chain. +Script to call Reporter contract's `dispatchBlocks` function of different oracle from source chain to destination chain. -  +## Getting Started ---- +These instructions will cover the usage information and how to run the code locally for development using Docker. -  +### Configuration -## Getting Started +Configure the mode you want to run by editing the variable in `.env` by checking `.env.example` + +```sh +cp .env.example .env +``` -These instructions will cover the usage information and how to run the code using Docker. +### Install -### Create the .env file +Please make sure you have run `yarn install` on the root level. -Configure the mode you want to run by editing the variable in `.env` by checking `.env.example` +```sh +cd ../.. # To the root level +nvm use +yarn install +cd packages/reporter +``` + +To start Reporter, run the following command: + +```sh +cd packages/reporter +yarn start:dev +``` ### Building and Running the Docker Image @@ -43,16 +59,10 @@ To stop the running container: docker stop [CONTAINER_ID or CONTAINER_NAME] ``` -  - ---- - -  - ## How to add a new controller -1. Add a new file under `/controllers`, create the constructor and `onBlocks` function to call block header reporter - contract periodically. +1. Add a new file under `src/controllers`, create the constructor and `onBlocks` function to call reporter contract + periodically. 2. Configure the settings under `settings/index.ts`. -3. Add the new controller instant in `index.ts`. +3. Add the new controller instance in `index.ts`. 4. Add the env variable in `.env.example`. diff --git a/packages/reporter/package.json b/packages/reporter/package.json index b8cfb84f..e4eee5a3 100644 --- a/packages/reporter/package.json +++ b/packages/reporter/package.json @@ -11,6 +11,7 @@ "lint": "eslint --ignore-path ./.eslintignore --ext .js,.ts .", "prettier:check": "prettier --check \"**/*.{js,json,md,sol,ts,yml}\"", "prettier:write": "prettier --write \"**/*.{js,json,md,sol,ts,yml}\"", + "start": "node --loader ts-node/esm ./src/index.ts", "start:dev": "nodemon" }, "dependencies": { From b4d322fc30b429b79d25162e796fdbd7e1962321 Mon Sep 17 00:00:00 2001 From: zengzengzenghuy Date: Tue, 24 Sep 2024 13:51:20 +0800 Subject: [PATCH 2/3] docs: update README --- README.md | 83 ++++++++++++++++++++++++++++++++++++----------- README_WIP.md | 89 --------------------------------------------------- 2 files changed, 64 insertions(+), 108 deletions(-) delete mode 100644 README_WIP.md diff --git a/README.md b/README.md index 7bc62e23..f7ccdbd3 100644 --- a/README.md +++ b/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,7 +49,7 @@ 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 @@ -63,19 +57,60 @@ We call this setup a **RAIHO** (Redundant Array of Independent Hash Oracles). - 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 + + ```sh + git clone https://github.com/gnosis/hashi # Clone the repo + cd hashi + nvm use + yarn install + ``` -- 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. +## Build & Run -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. +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). @@ -84,6 +119,16 @@ The audit results are available as a [pdf in this repo](https://github.com/gnosi 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). + +Please note, there have been changes to contract code since this audit. A subsequent audit of the changed code is pending. + ## Security and Liability All contracts are WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR diff --git a/README_WIP.md b/README_WIP.md deleted file mode 100644 index c4661fd7..00000000 --- a/README_WIP.md +++ /dev/null @@ -1,89 +0,0 @@ -# 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). - -The primary insight being that the vast majority of bridge-related security incidents could have had minimal impact if -the systems relying on them had built in some redundancy. In other words, it's much more secure to require messages be -validated by multiple independent mechanisms, rather than by just one. - -We call this setup a **RAIHO** (Redundant Array of Independent Hash Oracles). - -# 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 - - ```sh - git clone https://github.com/gnosis/hashi # Clone the repo - cd hashi - nvm use - yarn install - ``` - -## 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). - -The audit results are available as a [pdf in this repo](https://github.com/g0-group/Audits/blob/master/HashiMar2024.pdf). - -Please note, there have been changes to contract code since this audit. A subsequent audit of the changed code is pending. - -## Security and Liability - -All contracts are WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR -PURPOSE. - -## License - -Created under the [LGPL-3.0+ license](LICENSE). From 392880bfb46a90d3712646c2aeca2f5a8b1fd6b9 Mon Sep 17 00:00:00 2001 From: Alessandro Manfredi Date: Fri, 27 Sep 2024 10:31:10 +0200 Subject: [PATCH 3/3] chore(global): <- updates README --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index f7ccdbd3..621fedd6 100644 --- a/README.md +++ b/README.md @@ -117,8 +117,6 @@ All issues and notes of the audit have been addressed as of commit hash [9f37363 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). @@ -127,7 +125,7 @@ All issues and notes of the audit have been addressed as of commit hash [f1a9fdb The audit results are available as a [pdf in this repo](https://github.com/g0-group/Audits/blob/master/HashiMar2024.pdf). -Please note, there have been changes to contract code since this audit. A subsequent audit of the changed code is pending. +Additional audits can be found [here](https://crosschain-alliance.gitbook.io/hashi/v0.2/audit-report). ## Security and Liability