docs: wip guide & example

many-things · Feb 26, 2024 · e791815 · e791815
1 parent 99ec989
commit e791815
Show file tree

Hide file tree

Showing 9 changed files with 386 additions and 82 deletions.
diff --git a/README.md b/README.md
@@ -37,6 +37,10 @@ cargo test --workspace --exclude hpl-tests
 cargo llvm-cov --workspace --exclude hpl-tests
 ```
 
+## How to deploy
+
+[Go to README of ./script](./script/README.md)
+
 ## Project Structure
 
 ```text

diff --git a/script/GUIDE_DEPLOY.md b/script/GUIDE_DEPLOY.md
@@ -0,0 +1,121 @@
+# Deploy Guide with LocalOsmosis
+
+> This guide will help you to setup Hyperlane betweeen LocalOsmosis and Ethereum Sepolia Testnet.
+
+## 0. Run LocalOsmosis
+
+```bash
+# Move to your working directory
+$ cd {working_directory}
+
+# Clone osmosis repository & cd to it
+$ git clone https://github.com/osmosis-labs/osmosis.git && cd osmosis
+
+# Run localnet in background
+$ make localnet-startd
+
+# Stop / Clean localnet
+$ make localnet-stop
+$ make localnet-clean
+```
+
+## 1. Create `config.yaml` with your network config
+
+> Don't forget to setup deploy settings below
+
+Below is an example of `config.yaml` file for localosmosis.
+
+You can check full list of example in [config.example.yaml](../config.example.yaml) file.
+
+```yaml
+networks:
+  - id: localosmosis
+    hrp: osmo
+    endpoint:
+      rpc: http://localhost:26657
+      rest: http://localhost:1317
+      grpc: http://localhost:9090
+    gas:
+      price: 0.025
+      denom: uosmo
+    # localosmosis -> ascii / decimal -> sum.
+    # It's very arbitrary value, Perhaps you must need to change this value.
+    domain: 1304
+
+signer: <private_key> | <mnemonic>
+
+deploy:
+  ism:
+    - 11155111
+
+  hooks:
+    default:
+      type: mock
+
+    required:
+      type: aggregate
+      # if you keep it as "<signer>", the script will identify this as deployer address
+      owner: <signer>
+      hooks:
+        - type: merkle
+
+        - type: pausable
+          owner: <signer>
+          paused: false
+
+        - type: fee
+          owner: <signer>
+          fee:
+            # if you didn't set the denom, it will be set as gas denom of network config
+            denom: uosmo
+            amount: 1
+
+        - type: igp
+          owner: <signer>
+          configs:
+            11155111:
+              exchange_rate: 3000
+              gas_price: 5000
+          default_gas_usage: 30000
+```
+
+## 2. Upload Contract Codes
+
+You can upload contract codes from local environment or from [Github](https://github.com/many-things/cw-hyperlane/releases/).
+
+### Local
+
+```bash
+# Build contracts from local environment
+$ make optimize
+# Run compatibility test
+$ make check
+
+# This command will make one file.
+# - context with artifacts (default path: ./context/localosmosis.json)
+$ yarn cw-hpl upload local -n localosmosis
+```
+
+### Remote
+
+```bash
+# check all versions of contract codes from Github
+$ yarn cw-hpl upload remote-list -n localosmosis
+
+# This command will make one file.
+# - context with artifacts (default path: ./context/localosmosis.json)
+$ yarn cw-hpl upload remote v0.0.6-rc8 -n localosmosis
+```
+
+## 3. Instantiate Contracts
+
+If you configured / uploaded contract codes correctly, you can deploy contract with one simple command.
+
+```bash
+# This command will output two results.
+# - context + deployment    (default path: ./context/localosmosis.json)
+# - Hyperlane agent-config  (default path: ./context/localosmosis.config.json)
+$ yarn cw-hpl deploy -n localosmosis
+```
+
+## 4. Setup Validator / Relayer config
diff --git a/script/GUIDE_TOOL.md b/script/GUIDE_TOOL.md
@@ -0,0 +1,72 @@
+# cw-hpl
+
+## Prerequisites
+
+- \>= Node v20
+- \>= Yarn v4.1
+
+## Configuration
+
+Create a `config.yaml` file in the root directory of the project.
+
+You can check the [config.example.yaml](../config.example.yaml) file to see all supported options. And also you can check the full list of options in the [config.ts](./src/config.ts) file.
+
+After setup your config file, you can use cw-hpl command-line toolkit from now.
+
+## Usage
+
+### Contract
+
+```bash
+# List all supported contracts
+$ yarn cw-hpl contract list
+
+# Test dispatch to a mailbox (needs to run 'cw-hpl deploy' first)
+$ yarn cw-hpl contract test-dispatch
+```
+
+### Deploy
+
+```bash
+# Deploy all contracts based on setting in config file
+$ yarn cw-hpl deploy
+```
+
+### Upload
+
+```bash
+# Upload contract codes that from local environment
+$ yarn cw-hpl upload local
+
+# Fetch & Upload contract codes from Github
+$ yarn cw-hpl upload remote
+
+# List all versions of contract codes from Github
+$ yarn cw-hpl upload remote-list
+```
+
+## Maintaining
+
+### Adding a new contract
+
+- ism
+
+  1. Append [contractNames](./shared/constants.ts) with new contract name
+  2. Add new ISM type to [ISMType](./shared/config.ts) and [ContextIsm](./shared/context.ts)
+  3. Write deploy script for new ISM in [ism.ts](./deploy/ism.ts)
+  4. Done!
+
+- hook
+
+  1. Append [contractNames](./shared/constants.ts) with new contract name
+  2. Add new Hook type to [HookType](./shared/config.ts) and [ContextHook](./shared/context.ts)
+  3. Write deploy script for new Hook in [hook.ts](./deploy/hook.ts)
+  4. Done!
+
+- others
+
+  1. Append [contractNames](./shared/constants.ts) with new contract name
+  2. Add new config type to [Config](./shared/config.ts) if it needs to be configured.
+  3. Add new contract field to [ContextDeployment](./shared/context.ts)
+  4. Write deploy script for new contract in [deploy.ts](./commands/deploy.ts)
+  5. Done!
diff --git a/script/README.md b/script/README.md
@@ -1,85 +1,8 @@
-# Deploy Scripts
+# CW Hyperlane Scripts
 
-## Prerequisites
+This directory contains scripts for the CW Hyperlane project.
 
-- [pnpm](https://pnpm.io/)
+## Guides
 
-## Configuration
-
-Create a `config.yaml` file in the root directory of the project. Default option for Osmosis testnet is following.
-
-Also, you can check the full list of options in the [config.ts](./src/config.ts) file.
-
-```yaml
-network:
-  id: "osmo-test-5"
-  hrp: "osmo"
-  url: "https://rpc.osmotest5.osmosis.zone/"
-  gas:
-    price: "0.025"
-    denom: "uosmo"
-  domain: 1037 # osmo-test-5 -> ascii / decimal -> sum
-
-signer: { PRIVATE_KEY }
-
-deploy:
-  ism:
-    type: multisig
-    owner: { SIGNER_ADDRESS }
-    validators:
-      5:
-        addrs:
-          - { SIGNER_ETH_ADDRESS }
-        threshold: 1
-      420:
-        addrs:
-          - { SIGNER_ETH_ADDRESS }
-        threshold: 1
-      421613:
-        addrs:
-          - { SIGNER_ETH_ADDRESS }
-        threshold: 1
-
-  hooks:
-    default:
-      type: mock
-
-    required:
-      type: aggregate
-      owner: { SIGNER_ADDRESS }
-      hooks:
-        - type: merkle
-
-        - type: pausable
-          owner: { SIGNER_ADDRESS }
-          paused: false
-        - type: fee
-          owner: { SIGNER_ADDRESS }
-          fee:
-            denom: uosmo
-            amount: 1
-```
-
-## Usage
-
-### Uploading Contract Codes
-
-```bash
-pnpm upload
-```
-
-### Deploying Contracts
-
-```bash
-pnpm deploy
-```
-
-## Maintaining
-
-### Adding a new contract
-
-1. Add a new module with actual contract output name in the [contracts](./src/contracts/) directory.
-2. Class name should be upper camel case conversion of the contract name.
-3. Import new module [contracts/index.ts](./src/index.ts) file.
-4. If a new contract is ISM or Hook, add a new option to config type.
-5. Add a new field to the Contracts class in the [deploy.ts](./src/deploy.ts) file.
+- [Tool](./GUIDE_TOOL.md)
+- [Deploy](./GUIDE_DEPLOY.md)
diff --git a/script/example/hyperlane.yml b/script/example/hyperlane.yml
@@ -0,0 +1,58 @@
+version: "2"
+services:
+  relayer:
+    container_name: hpl-relayer
+    image: gcr.io/abacus-labs-dev/hyperlane-agent:3bb4d87-20240129-164519
+    user: root
+    # restart: always
+    entrypoint: ["sh", "-c"]
+    command:
+      - |
+        rm -rf /app/config/* && \
+        cp "/etc/hyperlane/agent-config.docker.json" "/app/config/agent-config.json" && \
+        CONFIG_FILES="/etc/hyperlane/relayer.json" \
+          ./relayer
+    ports:
+      - 9110:9090
+    volumes:
+      - ${DATA_PATH}/hyperlane:/etc/hyperlane
+      - ${DATA_PATH}/relayer:/etc/data
+      - ${DATA_PATH}/validator:/etc/validator
+
+  validator-sepolia:
+    container_name: hpl-validator-sepolia
+    image: gcr.io/abacus-labs-dev/hyperlane-agent:3bb4d87-20240129-164519
+    user: root
+    # restart: always
+    entrypoint: ["sh", "-c"]
+    command:
+      - |
+        rm -rf /app/config/* && \
+        cp "/etc/hyperlane/agent-config.docker.json" "/app/config/agent-config.json" && \
+        CONFIG_FILES="/etc/hyperlane/validator.sepolia.json" \
+          ./validator
+    ports:
+      - 9120:9090
+    volumes:
+      - ${DATA_PATH}/hyperlane:/etc/hyperlane
+      - ${DATA_PATH}/validator:/etc/validator
+      - ${DATA_PATH}/validator/sepolia:/etc/data
+
+  validator-localosmosis:
+    container_name: hpl-validator-localosmosis
+    image: gcr.io/abacus-labs-dev/hyperlane-agent:3bb4d87-20240129-164519
+    user: root
+    # restart: always
+    entrypoint: ["sh", "-c"]
+    command:
+      - |
+        rm -rf /app/config/* && \
+        cp "/etc/hyperlane/agent-config.docker.json" "/app/config/agent-config.json" && \
+        CONFIG_FILES="/etc/hyperlane/validator.localosmosis.json" \
+          ./validator
+    ports:
+      - 9121:9090
+    volumes:
+      - ${DATA_PATH}/hyperlane:/etc/hyperlane
+      - ${DATA_PATH}/validator:/etc/validator
+      - ${DATA_PATH}/validator/localosmosis:/etc/data