doc: documentation (#95)

* wip

* project structure & overview

* toc

* swap

* fix(schema): reflect missing contracts

* refactor(ts): migrate sdk - 1

* refactor(script): pull back project setup to root

* reorg script / cli

* fix(script): make igp deployable

* build: redeploy

* build: stride hyperlane deployment

* fix(hook): default gas denom

* feat(script): add migrate command

* chore: detailed ignore policy

* feat(script): supprot mnemonic

* chore(script): cleanup

* chore: trailing comma

* feat: add grpc endpoint as config

* feat: generate agent config

* feat(script): add test-dispatch

* chore: redundant args

* docs: owner -> <signer>

* build: yarn berry

* env: yarn

* env: add cw-hpl command

* feat: mailbox null-check

* fix: prune imports

* docs: wip guide & example

* fix: rename compose file

* fix: use localosmosis key

* refactor: restruct guide

* fix: remove DATA_PATH

* fix: add `yarn install`

* fix: handle rest endpoint not working

* fix: use localwasmd

* fix: hrp

* feat: add wallet command

* feat: wallet generator

* fix: use osmosis testnet

* line spacing

* fix: xor

* fix: split length

* feat: more info to replace

* fix: osmosis testnet network name

* chore: ignore example

* feat: add test recipient

* fix: trouble shooting

* docs: done

* docs: update README.md

* fix: line break

* chore: remove testnet contexts

* wip: neutron deployment

* feat: context -> agent config

* feat: apply review changes (#97)

* docs: add context / example

* fix: real instant finality

* fix: typo

.editorconfig

@@ -9,3 +9,6 @@ insert_final_newline = true
 
 [*.rs]
 indent_size = 4
+
+[*.ts]
+indent_size = 2

.gitignore

@@ -28,3 +28,15 @@ Cargo.lock
 .idea/
 
 **/*.profraw
+
+# Script setup
+
+config.yaml
+config.*.yaml
+!config.example.yaml
+
+context/*.config.json
+
+tmp/
+dist/
+node_modules/

README.md

@@ -87,7 +87,11 @@ cargo llvm-cov --workspace --exclude hpl-tests
 │   ├── pausable
 │   └── router
 │
-├── scripts # useful scripts for development (e.g. code uploading. contract deployment)
+├── context # predeployed contract information
+│
+├── example # example of contract deployment & integration
+│
+├── script # useful scripts for development (e.g. code uploading. contract deployment)
 │
 └── ts
     └── sdk # typescript sdk for contract integration. (auto generated via ts-codegen)

codegen.ts

@@ -0,0 +1,37 @@
+import * as fs from "fs";
+import codegen from "@cosmwasm/ts-codegen";
+import path from "path";
+
+const SCHEMA_DIR = process.env.SCHEMA_DIR || path.join(process.cwd(), "schema");
+
+const capitalize = (str: string): string =>
+  str.charAt(0).toUpperCase() + str.slice(1);
+
+const contracts = fs
+  .readdirSync(SCHEMA_DIR, { withFileTypes: true })
+  .filter((c) => !c.isDirectory())
+  .map((c) => ({
+    name: c.name.replace(".json", ""),
+    dir: SCHEMA_DIR,
+  }));
+
+codegen({
+  contracts,
+  outPath: "./dist/",
+
+  // options are completely optional ;)
+  options: {
+    bundle: {
+      bundleFile: "index.ts",
+      scope: "contracts",
+    },
+    client: {
+      enabled: true,
+    },
+    messageComposer: {
+      enabled: true,
+    },
+  },
+}).then(() => {
+  console.log("✨ all done!");
+});

context/neutron-1.json

@@ -0,0 +1,21 @@
+{
+  "artifacts": {
+    "hpl_hook_aggregate": 405,
+    "hpl_hook_merkle": 406,
+    "hpl_hook_pausable": 407,
+    "hpl_hook_routing": 408,
+    "hpl_hook_routing_custom": 409,
+    "hpl_hook_routing_fallback": 410,
+    "hpl_igp": 433,
+    "hpl_igp_oracle": 412,
+    "hpl_ism_aggregate": 413,
+    "hpl_ism_multisig": 431,
+    "hpl_ism_routing": 415,
+    "hpl_mailbox": 416,
+    "hpl_test_mock_hook": 417,
+    "hpl_test_mock_msg_receiver": 418,
+    "hpl_validator_announce": 432,
+    "hpl_warp_cw20": 420,
+    "hpl_warp_native": 421
+  }
+}

example/README.md

@@ -0,0 +1,224 @@
+# 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: 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
+$ 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}`)
+
+* [./hyperlane/relayer.json](./hyperlane/relayer.json)
+* [./hyperlane/validator.sepolia.json](./hyperlane/validator.sepolia.json)
+
+- Osmosis Testnet (`{osmosis_private_key}`)
+
+* [./hyperlane/relayer.json](./hyperlane/relayer.json)
+* [./hyperlane/validator.osmotest5.json](./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 ./hyperlane/agent-config.docker.json \
+      | jq ".chains.$OSMOSIS_TESTNET_AGENT_CONFIG_NAME=$(echo $OSMOSIS_TESTNET_AGENT_CONFIG)" > merge.tmp && \
+  mv merge.tmp ./hyperlane/agent-config.docker.json
+
+# 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)

scripts/package.json → package.json

@@ -24,13 +24,17 @@
     "axios": "^1.6.7",
     "colors": "^1.4.0",
     "commander": "^11.1.0",
+    "decompress": "^4.2.1",
     "inversify": "^6.0.1",
     "readline": "^1.3.0",
     "reflect-metadata": "^0.1.13"
   },
   "devDependencies": {
+    "@cosmwasm/ts-codegen": "^0.35.7",
+    "@types/decompress": "^4.2.7",
     "@types/js-yaml": "^4.0.8",
-    "@types/node": "^20.4.4",
+    "@types/node": "^20.11.20",
+    "esbuild": "^0.20.1",
     "ts-node": "^10.9.1",
     "ts-yaml": "^1.0.0",
     "tsx": "^3.13.0",

script/commands/context.ts

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import { CONTAINER, Dependencies } from "../shared/ioc";
+import { saveAgentConfig } from "../shared/context";
+import { getNetwork } from "../shared/config";
+
+const contextCmd = new Command("context");
+
+contextCmd
+  .command("make-agent-config")
+  .description("Make an agent config")
+  .option("-o --output <output-dir>", "The output directory")
+  .action(async (_, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const { ctx } = CONTAINER.get(Dependencies);
+    const network = getNetwork(opts.networkId);
+
+    await saveAgentConfig(
+      network,
+      ctx,
+      opts.output && { contextPath: opts.output }
+    );
+  });
+
+export { contextCmd };