refactor: restruct guide

example/README.md

@@ -0,0 +1,207 @@
+# Deploy Guide with LocalOsmosis
+
+> This guide will help you to setup Hyperlane betweeen LocalOsmosis and Ethereum Sepolia Testnet.
+
+## Prerequisites
+
+- Sepolia Testnet account with enough balance
+  - will use for deploying test contracts on Sepolia
+  - and relaying / validating messages between LocalOsmosis and Sepolia
+
+## 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
+
+# default mnemonic key of LocalOsmosis (https://github.com/osmosis-labs/osmosis/blob/d45a3baf684e55cdc83ef23c4fc11ae1df1726af/tests/localosmosis/scripts/setup.sh#L9C11-L9C159)
+# osmo12smx2wdlyttvyzvzg54y2vnqwq2qjateuf7thj
+# 0xae7d1F30e324D4e348EF04D9a9e867F863f23067
+# 9ff80c31b47c7f2946654f569a6b1530db78d7fa5b3ea16db82570cdfd6d43f6
+signer: "bottom loan skill merry east cradle onion journey palm apology verb edit desert impose absurd oil bubble sweet glove shallow size build burst effort"
+
+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: {project-root}/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: {project-root}/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
+
+Replace every `{private_key}` from files below with your Sepolia Testnet private key.
+
+- [./hyperlane/relayer.json](./hyperlane/relayer.json)
+- [./hyperlane/validator.sepolia.json](./hyperlane/validator.sepolia.json)
+
+And run with below command.
+
+```bash
+# Merge localosmosis.config.json and agent-config.docker.json
+$ LOCALOSMOSIS_AGENT_CONFIG=$(cat ../context/localosmosis.config.json) && \
+  LOCALOSMOSIS_AGENT_CONFIG_NAME=$(echo $LOCALOSMOSIS_AGENT_CONFIG | jq -r '.name') && \
+    cat ./hyperlane/agent-config.docker.json \
+      | jq ".chains.$LOCALOSMOSIS_AGENT_CONFIG_NAME=$(echo $LOCALOSMOSIS_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 localosmosis 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 -> LocalOsmosis
+
+```bash
+# Below address is mailbox came from agent-config.docker.json
+$ cast send \
+    0xfFAEF09B3cd11D9b20d1a19bECca54EEC2884766 --value 1wei \
+    'dispatch(uint32,bytes32,bytes)' \
+    1304 $LOCALOSMOSIS_TEST_RECIPIENT_ADDRESS 0x68656c6c6f \ # 0x68656c6c6f -> 'hello'
+    --rpc-url 'https://rpc.sepolia.org' \
+    --private-key $SEPOLIA_PRIVATE_KEY
+```
+
+### LocalOsmosis -> Sepolia
+
+```bash
+# [dest-domain] [recipient-address] [message]
+$ yarn cw-hpl contract test-dispatch -n localosmosis 11155111 $SEPOLIA_TEST_RECIPIENT_ADDRESS hello
+```

example/TestRecipient.bin

@@ -0,0 +1 @@
+0x608060405234801561001057600080fd5b5061001a3361001f565b61006f565b600080546001600160a01b038381166001600160a01b0319831681178455604051919092169283917f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e09190a35050565b61084c8061007e6000396000f3fe60806040526004361061009b5760003560e01c8063715018a611610064578063715018a61461015c5780638da5cb5b14610171578063a4982fde1461018f578063de523cf3146101a4578063f07c1f47146101c4578063f2fde38b146101e457600080fd5b80626e75ec146100a05780630e72cc06146100cb5780632113522a146100ed578063256fec881461012557806356d5d47514610149575b600080fd5b3480156100ac57600080fd5b506100b5610204565b6040516100c29190610510565b60405180910390f35b3480156100d757600080fd5b506100eb6100e636600461052a565b610292565b005b3480156100f957600080fd5b5060045461010d906001600160a01b031681565b6040516001600160a01b0390911681526020016100c2565b34801561013157600080fd5b5061013b60025481565b6040519081526020016100c2565b6100eb61015736600461059c565b6102bc565b34801561016857600080fd5b506100eb610317565b34801561017d57600080fd5b506000546001600160a01b031661010d565b34801561019b57600080fd5b506100b561032b565b3480156101b057600080fd5b5060015461010d906001600160a01b031681565b3480156101d057600080fd5b506100eb6101df366004610601565b610338565b3480156101f057600080fd5b506100eb6101ff36600461052a565b6103a2565b600380546102119061064d565b80601f016020809104026020016040519081016040528092919081815260200182805461023d9061064d565b801561028a5780601f1061025f5761010080835404028352916020019161028a565b820191906000526020600020905b81548152906001019060200180831161026d57829003601f168201915b505050505081565b61029a610420565b600180546001600160a01b0319166001600160a01b0392909216919091179055565b34838563ffffffff167fecdc36fa3681f5d9c559dcbc399417db6f0ac0d81a78529685a1150265971d5585856040516102f69291906106b0565b60405180910390a460028390556003610310828483610733565b5050505050565b61031f610420565b610329600061047a565b565b600580546102119061064d565b336001600160a01b03167f97d8367a1f39eb9e97f262fafbb05925c0bcfe120aaad7b9737cae34f749c206848484604051610375939291906107f3565b60405180910390a2600480546001600160a01b03191633179055600561039c828483610733565b50505050565b6103aa610420565b6001600160a01b0381166104145760405162461bcd60e51b815260206004820152602660248201527f4f776e61626c653a206e6577206f776e657220697320746865207a65726f206160448201526564647265737360d01b60648201526084015b60405180910390fd5b61041d8161047a565b50565b6000546001600160a01b031633146103295760405162461bcd60e51b815260206004820181905260248201527f4f776e61626c653a2063616c6c6572206973206e6f7420746865206f776e6572604482015260640161040b565b600080546001600160a01b038381166001600160a01b0319831681178455604051919092169283917f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e09190a35050565b6000815180845260005b818110156104f0576020818501810151868301820152016104d4565b506000602082860101526020601f19601f83011685010191505092915050565b60208152600061052360208301846104ca565b9392505050565b60006020828403121561053c57600080fd5b81356001600160a01b038116811461052357600080fd5b60008083601f84011261056557600080fd5b50813567ffffffffffffffff81111561057d57600080fd5b60208301915083602082850101111561059557600080fd5b9250929050565b600080600080606085870312156105b257600080fd5b843563ffffffff811681146105c657600080fd5b935060208501359250604085013567ffffffffffffffff8111156105e957600080fd5b6105f587828801610553565b95989497509550505050565b60008060006040848603121561061657600080fd5b83359250602084013567ffffffffffffffff81111561063457600080fd5b61064086828701610553565b9497909650939450505050565b600181811c9082168061066157607f821691505b60208210810361068157634e487b7160e01b600052602260045260246000fd5b50919050565b81835281816020850137506000828201602090810191909152601f909101601f19169091010190565b6020815260006106c4602083018486610687565b949350505050565b634e487b7160e01b600052604160045260246000fd5b601f82111561072e576000816000526020600020601f850160051c8101602086101561070b5750805b601f850160051c820191505b8181101561072a57828155600101610717565b5050505b505050565b67ffffffffffffffff83111561074b5761074b6106cc565b61075f83610759835461064d565b836106e2565b6000601f841160018114610793576000851561077b5750838201355b600019600387901b1c1916600186901b178355610310565b600083815260209020601f19861690835b828110156107c457868501358255602094850194600190920191016107a4565b50868210156107e15760001960f88860031b161c19848701351681555b505060018560011b0183555050505050565b83815260406020820152600061080d604083018486610687565b9594505050505056fea2646970667358221220e74b9ce655ed9c3a34678c7f1f825221c112607de021b8a463cd377e3305ee6564736f6c63430008170033

example/docker-compose.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

example/hyperlane/agent-config.docker.json

@@ -0,0 +1,63 @@
+{
+  "chains": {
+    "sepolia": {
+      "blockExplorers": [
+        {
+          "apiUrl": "https://api-sepolia.etherscan.io/api",
+          "family": "etherscan",
+          "name": "Etherscan",
+          "url": "https://sepolia.etherscan.io"
+        }
+      ],
+      "blocks": {
+        "confirmations": 1,
+        "estimateBlockTime": 13,
+        "reorgPeriod": 2
+      },
+      "chainId": 11155111,
+      "displayName": "Sepolia",
+      "domainId": 11155111,
+      "isTestnet": true,
+      "name": "sepolia",
+      "nativeToken": {
+        "decimals": 18,
+        "name": "Ether",
+        "symbol": "ETH"
+      },
+      "protocol": "ethereum",
+      "rpcUrls": [
+        {
+          "http": "https://ethereum-sepolia.blockpi.network/v1/rpc/public"
+        },
+        {
+          "http": "https://eth-sepolia.g.alchemy.com/v2/demo"
+        },
+        {
+          "http": "https://rpc.sepolia.org"
+        }
+      ],
+      "merkleRootMultisigIsmFactory": "0x0a71AcC99967829eE305a285750017C4916Ca269",
+      "messageIdMultisigIsmFactory": "0xFEb9585b2f948c1eD74034205a7439261a9d27DD",
+      "aggregationIsmFactory": "0xC83e12EF2627ACE445C298e6eC418684918a6002",
+      "aggregationHookFactory": "0x160C28C92cA453570aD7C031972b58d5Dd128F72",
+      "proxyAdmin": "0x97Bbc6bBaFa5Ce3b2FA966c121Af63bD09e940f8",
+      "storageGasOracle": "0x71775B071F77F1ce52Ece810ce084451a3045FFe",
+      "interchainGasPaymaster": "0x6f2756380FD49228ae25Aa7F2817993cB74Ecc56",
+      "aggregationHook": "0xe3147d5618f5e2e100690B50ec923009a4cde14A",
+      "protocolFee": "0x13AC3349Cb159fE86A22cf42DdA803D9f7309DB5",
+      "mailbox": "0xfFAEF09B3cd11D9b20d1a19bECca54EEC2884766",
+      "merkleTreeHook": "0x4917a9746A7B6E0A57159cCb7F5a6744247f2d0d",
+      "validatorAnnounce": "0xE6105C59480a1B7DD3E4f28153aFdbE12F4CfCD9",
+      "fallbackRoutingHook": "0x17Dc724B7a2F09141C13b8AC33B396073785c2BC",
+      "testRecipient": "0xeDc1A3EDf87187085A3ABb7A9a65E1e7aE370C07",
+      "testTokenRecipient": "0x031AD9c560D37baC7d6Bd2d27A2443bAfd10101A",
+      "routingIsmFactory": "0x3F100cBBE5FD5466BdB4B3a15Ac226957e7965Ad",
+      "interchainSecurityModule": "0x958124472b14B7940Ed5317C44a2508791dB1d48",
+      "pausableHook": "0xa68022e53Fd28119D07C8336a8eC84A298Fd38Fd",
+      "index": {
+        "from": 4517401,
+        "chunk": 100000
+      }
+    }
+  }
+}

example/hyperlane/relayer.json

@@ -0,0 +1,31 @@
+{
+  "db": "/etc/data/db",
+  "relayChains": "localosmosis,sepolia",
+  "allowLocalCheckpointSyncers": "true",
+  "gasPaymentEnforcement": [{ "type": "none" }],
+  "whitelist": [
+    {
+      "origindomain": [11155111],
+      "destinationDomain": [1304]
+    },
+    {
+      "origindomain": [1304],
+      "destinationDomain": [11155111]
+    }
+  ],
+  "chains": {
+    "sepolia": {
+      "signer": {
+        "type": "hexKey",
+        "key": "{private_key}"
+      }
+    },
+    "localosmosis": {
+      "signer": {
+        "type": "cosmosKey",
+        "key": "9ff80c31b47c7f2946654f569a6b1530db78d7fa5b3ea16db82570cdfd6d43f6",
+        "prefix": "osmo"
+      }
+    }
+  }
+}

example/hyperlane/validator.localosmosis.json

@@ -0,0 +1,21 @@
+{
+  "db": "/etc/data/db",
+  "checkpointSyncer": {
+    "type": "localStorage",
+    "path": "/etc/validator/localosmosis/checkpoint"
+  },
+  "originChainName": "localosmosis",
+  "validator": {
+    "type": "hexKey",
+    "key": "9ff80c31b47c7f2946654f569a6b1530db78d7fa5b3ea16db82570cdfd6d43f6"
+  },
+  "chains": {
+    "localosmosis": {
+      "signer": {
+        "type": "cosmosKey",
+        "key": "9ff80c31b47c7f2946654f569a6b1530db78d7fa5b3ea16db82570cdfd6d43f6",
+        "prefix": "osmo"
+      }
+    }
+  }
+}