review: docs (#98)

* wip

* project structure & overview

* toc

* swap

* docs: owner -> <signer>

* build: yarn berry

* env: yarn

* env: add cw-hpl command

* docs: wip guide & example

* fix: line break

* fix: rename compose file

* fix: use localosmosis key

* refactor: restruct guide

* fix: remove DATA_PATH

* fix: add `yarn install`

* fix: use localwasmd

* fix: hrp

* fix: use osmosis testnet

* line spacing

* feat: more info to replace

* fix: osmosis testnet network name

* chore: ignore example

* docs: done

* docs: update README.md

* merge: remove conflicts

* docs: move to root

* docs: remove outdated docs

.gitattributes

@@ -0,0 +1,4 @@
+/.yarn/**            linguist-vendored
+/.yarn/releases/*    binary
+/.yarn/plugins/**/*  binary
+/.pnp.*              binary linguist-generated

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

DEPLOYMENT.md

@@ -0,0 +1,225 @@
+# Deploying Hyperlane with Osmosis Testnet
+
+> This guide will help you to setup Hyperlane betweeen Osmosis Testnet and Ethereum Sepolia Testnet.
+
+## Prerequisites
+
+- [Cast](https://book.getfoundry.sh/cast/)
+- Sepolia Testnet account with enough balance ([faucet](https://sepolia-faucet.pk910.de/))
+- Osmosis Testnet account with enough balance ([faucet](https://faucet.testnet.osmosis.zone/))
+
+- Recommanded to use same account for both networks
+
+  - You can easily get the bech32 address by running below command (need to setup `config.yaml` first)
+
+    - Get from private key  
+      `yarn cw-hpl wallet address -n [network-id] --private-key [private-key]`
+    - Get from mnemonic phrase  
+      `yarn cw-hpl wallet address -n [network-id] --mnemonic [mnemonic]`
+
+  - You also can get the ethereum address by running below command
+
+    - Get from private key  
+      `cast wallet address --private-key [private-key]`
+    - Get from mnemonic phrase  
+      `cast wallet address --mnemonic [mnemonic]`
+
+  - Or, You can use `yarn cw-hpl wallet new -n [network-id]` to create new wallet
+
+## 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 localwasmd.
+
+You can check full list of example in [config.example.yaml](../config.example.yaml) file.
+
+```yaml
+networks:
+  - id: "osmo-test-5"
+    hrp: "osmo"
+    endpoint:
+      rpc: "https://rpc.testnet.osmosis.zone"
+      rest: "https://lcd.testnet.osmosis.zone"
+      grpc: "https://grpc.testnet.osmosis.zone"
+    gas:
+      price: "0.025"
+      denom: "uosmo"
+    # osmo-test-5 -> ascii / decimal -> sum.
+    # It's very arbitrary value, Perhaps you must need to change this value.
+    domain: 1037 # osmo-test-5 -> ascii / decimal -> sum
+
+signer: "<private-key> or <mnemonic>"
+
+deploy:
+  ism:
+    - 11155111
+
+  hooks:
+    default:
+      type: aggregate
+      owner: <signer>
+      hooks:
+        - type: merkle
+
+        - type: igp
+          owner: <signer>
+          configs:
+            11155111:
+              exchange_rate: 3000
+              gas_price: 5000
+          default_gas_usage: 30000
+
+    required:
+      type: aggregate
+      owner: <signer>
+      hooks:
+        - type: pausable
+          owner: <signer>
+          paused: false
+
+        - type: fee
+          owner: <signer>
+          fee:
+            amount: 1
+```
+
+## 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
+$ yarn install
+
+# Build contracts from local environment
+$ make optimize
+# Run compatibility test
+$ make check
+
+# This command will make one file.
+# - context with artifacts (default path: {project-root}/context/osmo-test-5.json)
+$ yarn cw-hpl upload local -n osmo-test-5
+```
+
+### Remote
+
+```bash
+$ yarn install
+
+# check all versions of contract codes from Github
+$ yarn cw-hpl upload remote-list -n osmo-test-5
+
+# This command will make one file.
+# - context with artifacts (default path: {project-root}/context/osmo-test-5.json)
+$ yarn cw-hpl upload remote v0.0.6-rc8 -n osmo-test-5
+```
+
+## 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/osmo-test-5.json)
+# - Hyperlane agent-config  (default path: ./context/osmo-test-5.config.json)
+$ yarn cw-hpl deploy -n osmo-test-5
+```
+
+## 4. Setup Validator / Relayer config
+
+Replace every `{sepolia_private_key}` and `{osmosis_private_key}` from files below with your private key.
+
+- Sepolia Testnet (`{sepolia_private_key}`)
+
+  - [./example/hyperlane/relayer.json](./example/hyperlane/relayer.json)
+  - [./example/hyperlane/validator.sepolia.json](./example/hyperlane/validator.sepolia.json)
+
+- Osmosis Testnet (`{osmosis_private_key}`)
+
+  - [./example/hyperlane/relayer.json](./example/hyperlane/relayer.json)
+  - [./example/hyperlane/validator.osmotest5.json](./example/hyperlane/validator.osmotest5.json)
+
+And run with below command.
+
+```bash
+# Merge osmo-test-5.config.json and agent-config.docker.json
+OSMOSIS_TESTNET_AGENT_CONFIG=$(cat ./context/osmo-test-5.config.json) && \
+  OSMOSIS_TESTNET_AGENT_CONFIG_NAME=$(echo $OSMOSIS_TESTNET_AGENT_CONFIG | jq -r '.name') && \
+    cat ./example/hyperlane/agent-config.docker.json \
+      | jq ".chains.$OSMOSIS_TESTNET_AGENT_CONFIG_NAME=$(echo $OSMOSIS_TESTNET_AGENT_CONFIG)" > merge.tmp && \
+  mv merge.tmp ./example/hyperlane/agent-config.docker.json
+
+# Change workdir to example
+cd example
+
+# Run Hyperlane with docker-compose
+docker compose up
+
+# Run this if you want to run in background
+docker compose up -d
+
+# Run this if you want to see logs
+docker compose logs -f
+
+# Run this if you want to stop
+docker compose down
+```
+
+## 5. Deploy Test contracts on Sepolia
+
+```bash
+# 1. Deploy TestRecipient contract
+$ cast send \
+    --rpc-url https://rpc.sepolia.org \
+    --private-key $SEPOLIA_PRIVATE_KEY \
+    --create $(cat ./TestRecipient.bin)
+
+# 2. Deploy MultisigIsm for validating osmo-test-5 network
+# Below address is messageIdMultisigIsmFactory came from agent-config.docker.json
+$ cast send \
+    0xFEb9585b2f948c1eD74034205a7439261a9d27DD \
+    'deploy(address[],uint8)(address)' \
+    [$(cast wallet address --private-key $SEPOLIA_PRIVATE_KEY)] 1 \ # 1 validator and 1/1 threshold
+    --rpc-url https://rpc.sepolia.org \
+    --private-key $SEPOLIA_PRIVATE_KEY
+
+# 3. Get deployed multisig ism address from receipt of above command
+$ cast send \
+    $SEPOLIA_TEST_RECIPIENT_ADDRESS \ # output of step 1
+    'setInterchainSecurityModule(address)' \
+    $SEPOLIA_MULTISIG_ISM_ADDRESS \ # output of step 2
+    --rpc-url https://rpc.sepolia.org \
+    --private-key $SEPOLIA_PRIVATE_KEY
+```
+
+## 6. Run Messaging Test
+
+### Sepolia -> osmo-test-5
+
+```bash
+# Below address is mailbox came from agent-config.docker.json
+$ cast send \
+    0xfFAEF09B3cd11D9b20d1a19bECca54EEC2884766 --value 1wei \
+    'dispatch(uint32,bytes32,bytes)' \
+    1037 $OSMOSIS_TESTNET_TEST_RECIPIENT_ADDRESS 0x68656c6c6f \ # 0x68656c6c6f -> 'hello'
+    --rpc-url 'https://rpc.sepolia.org' \
+    --private-key $SEPOLIA_PRIVATE_KEY
+```
+
+### osmo-test-5 -> Sepolia
+
+```bash
+# [dest-domain] [recipient-address] [message]
+$ yarn cw-hpl contract test-dispatch -n osmo-test-5 11155111 $SEPOLIA_TEST_RECIPIENT_ADDRESS hello
+```
+
+## 7. Done 🎉
+
+This is it! You have successfully deployed Hyperlane between Osmosis Testnet and Sepolia Testnet.
+
+Current setup you've made is for testing purpose, and not production ready. So, if you want to run Hyperlane agents in production, you need to check these guides below.
+
+- [Running Relayers](https://docs.hyperlane.xyz/docs/operate/relayer/run-relayer)
+- [Running Validators](https://docs.hyperlane.xyz/docs/operate/validators/run-validators)

Makefile

@@ -8,7 +8,7 @@ clean:
 install: install-dev
 
 install-dev: install-prod
-	cargo install --force cw-optimizoor beaker
+	cargo install --force cargo-llvm-cov cw-optimizoor beaker
 
 install-prod:
 	cargo install --force cosmwasm-check

README.md

@@ -1,77 +1,94 @@
-# cw-hyperlane
+# CW Hyperlane
 
 [![codecov](https://codecov.io/gh/many-things/cw-hyperlane/branch/main/graph/badge.svg?token=SGYE7FBTAO)](https://codecov.io/gh/many-things/cw-hyperlane)
 [![crates.io](https://img.shields.io/crates/v/hpl-interface)](https://crates.io/crates/hpl-interface)
 
-> This project is under active development...!
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Project Structure](#project-structure)
+- [Prerequisites](#prerequisites)
+- [How to build](#how-to-build)
+- [How to test](#how-to-test)
+- [How to deploy](#how-to-deploy)
+
+## Architecture
+
+![Architecture](./asset/hyperlane-all.png)
 
 ## Prerequisites
 
 - rust (wasm32-wasm32-unknown target)
 - go 1.20 or higher
-- grcov
+- llvm-cov
 
 ## How to build
 
 ```bash
-cargo build
+make install-dev
 
-cargo wasm
+make build
 ```
 
 ## How to test
 
 ```bash
-# testing
-cargo test
-
-# coverage
-export RUSTFLAGS="-Cinstrument-coverage"
-export LLVM_PROFILE_FILE="eddy-%p-%m.profraw"
+cargo test --workspace --exclude hpl-tests
 
-cargo build
-
-cargo test
-
-grcov . -s . --binary-path ./target/debug/ -t lcov --branch --ignore-not-existing -o ./target/debug/coverage/
+cargo llvm-cov --workspace --exclude hpl-tests
 ```
 
-## Deploy Sequence
-
-1. Deploy [Mailbox](./contracts/core/mailbox)
-
-2. Deploy [Validator Announce](./contracts/core/va)
-
-3. Deploy hooks to use with Mailbox (default hook, required hook)
-
-   - [interchain gas paymaster (IGP)](./contracts/igps/core)
-
-   - [IGP oracle](./contracts/igps/oracle)
-
-   - [merkle](./contracts/hooks/merkle)
-
-   - [pausable](./contracts/hooks/pausable)
-
-   - [domain routing](./contracts/hooks/routing)
-
-   - [domain routing custom](./contracts/hooks/routing-custom)
-
-   - [domain routing fallback](./contracts/hooks/routing-fallback)
-
-   - For testing: [mock hook](./contracts/mocks/mock-hook)
-
-4. Deploy isms to use with Mailbox (defualt ism)
-
-   - [multisig ism](./contracts/isms/multisig)
-
-   - [routing ism](./contracts/isms/routing)
-
-   - [aggregate ism](./contracts/isms/aggregate)
-
-   - [pausable](./contracts/isms/pausable)
-
-   - For testing: [mock ism](./contracts/mocks/mock-ism)
-
-5. Set deployed hooks and isms to Mailbox
-
-6. Deployment for core protocol is done! You can deploy some contracts on the top.
+## [How to deploy](./DEPLOYMENT.md)
+
+## Project Structure
+
+```text
+├── contracts
+│   │
+│   ├── core
+│   │   ├── mailbox
+│   │   └── va
+│   │
+│   ├── hooks
+│   │   ├── aggregate
+│   │   ├── fee # protocol fee
+│   │   ├── merkle
+│   │   ├── pausable
+│   │   ├── routing
+│   │   ├── routing-custom
+│   │   └── routing-fallback
+│   │
+│   ├── igps # also this is a part of `hook`
+│   │   ├── core
+│   │   └── oracle
+│   │
+│   ├── isms
+│   │   ├── aggregate
+│   │   ├── multisig
+│   │   ├── pausable
+│   │   └── routing
+│   │
+│   ├── mocks # for testing
+│   │   ├── mock-hook
+│   │   ├── mock-ism
+│   │   └── mock-msg-receiver
+│   │
+│   └── warp
+│       ├── cw20
+│       └── native
+│
+├── integration-test
+│
+├── packages
+│   │
+│   ├── connection # same as `MailboxClient` of evm implementation
+│   ├── interface # package for contract interfaces (external)
+│   ├── ownable
+│   ├── pausable
+│   └── router
+│
+├── scripts # useful scripts for development (e.g. code uploading. contract deployment)
+│
+└── ts
+    └── sdk # typescript sdk for contract integration. (auto generated via ts-codegen)
+```