diff --git a/.yarn/install-state.gz b/.yarn/install-state.gz index 671b132c..e4b2b493 100644 Binary files a/.yarn/install-state.gz and b/.yarn/install-state.gz differ diff --git a/README.md b/README.md index 3f28b564..207aca95 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ cargo llvm-cov --workspace --exclude hpl-tests ## How to deploy +[Go to README of ./example](./example/README.md) [Go to README of ./script](./script/README.md) ## Project Structure diff --git a/script/GUIDE_DEPLOY.md b/example/README.md similarity index 52% rename from script/GUIDE_DEPLOY.md rename to example/README.md index 61a740d0..85102638 100644 --- a/script/GUIDE_DEPLOY.md +++ b/example/README.md @@ -2,6 +2,12 @@ > 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 @@ -85,7 +91,7 @@ deploy: ## 2. Upload Contract Codes -You can upload contract codes from local environment or from [Github](https://github.com/many-things/cw-hyperlane/releases/). +You can upload contract codes from local environment or from [Github](https://github.com/many-things/cw-hyperlane/releases). ### Local @@ -96,7 +102,7 @@ $ make optimize $ make check # This command will make one file. -# - context with artifacts (default path: ./context/localosmosis.json) +# - context with artifacts (default path: {project-root}/context/localosmosis.json) $ yarn cw-hpl upload local -n localosmosis ``` @@ -107,7 +113,7 @@ $ yarn cw-hpl upload local -n localosmosis $ yarn cw-hpl upload remote-list -n localosmosis # This command will make one file. -# - context with artifacts (default path: ./context/localosmosis.json) +# - context with artifacts (default path: {project-root}/context/localosmosis.json) $ yarn cw-hpl upload remote v0.0.6-rc8 -n localosmosis ``` @@ -123,3 +129,79 @@ $ 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 +``` diff --git a/example/TestRecipient.bin b/example/TestRecipient.bin new file mode 100644 index 00000000..952b111e --- /dev/null +++ b/example/TestRecipient.bin @@ -0,0 +1 @@ +0x608060405234801561001057600080fd5b5061001a3361001f565b61006f565b600080546001600160a01b038381166001600160a01b0319831681178455604051919092169283917f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e09190a35050565b61084c8061007e6000396000f3fe60806040526004361061009b5760003560e01c8063715018a611610064578063715018a61461015c5780638da5cb5b14610171578063a4982fde1461018f578063de523cf3146101a4578063f07c1f47146101c4578063f2fde38b146101e457600080fd5b80626e75ec146100a05780630e72cc06146100cb5780632113522a146100ed578063256fec881461012557806356d5d47514610149575b600080fd5b3480156100ac57600080fd5b506100b5610204565b6040516100c29190610510565b60405180910390f35b3480156100d757600080fd5b506100eb6100e636600461052a565b610292565b005b3480156100f957600080fd5b5060045461010d906001600160a01b031681565b6040516001600160a01b0390911681526020016100c2565b34801561013157600080fd5b5061013b60025481565b6040519081526020016100c2565b6100eb61015736600461059c565b6102bc565b34801561016857600080fd5b506100eb610317565b34801561017d57600080fd5b506000546001600160a01b031661010d565b34801561019b57600080fd5b506100b561032b565b3480156101b057600080fd5b5060015461010d906001600160a01b031681565b3480156101d057600080fd5b506100eb6101df366004610601565b610338565b3480156101f057600080fd5b506100eb6101ff36600461052a565b6103a2565b600380546102119061064d565b80601f016020809104026020016040519081016040528092919081815260200182805461023d9061064d565b801561028a5780601f1061025f5761010080835404028352916020019161028a565b820191906000526020600020905b81548152906001019060200180831161026d57829003601f168201915b505050505081565b61029a610420565b600180546001600160a01b0319166001600160a01b0392909216919091179055565b34838563ffffffff167fecdc36fa3681f5d9c559dcbc399417db6f0ac0d81a78529685a1150265971d5585856040516102f69291906106b0565b60405180910390a460028390556003610310828483610733565b5050505050565b61031f610420565b610329600061047a565b565b600580546102119061064d565b336001600160a01b03167f97d8367a1f39eb9e97f262fafbb05925c0bcfe120aaad7b9737cae34f749c206848484604051610375939291906107f3565b60405180910390a2600480546001600160a01b03191633179055600561039c828483610733565b50505050565b6103aa610420565b6001600160a01b0381166104145760405162461bcd60e51b815260206004820152602660248201527f4f776e61626c653a206e6577206f776e657220697320746865207a65726f206160448201526564647265737360d01b60648201526084015b60405180910390fd5b61041d8161047a565b50565b6000546001600160a01b031633146103295760405162461bcd60e51b815260206004820181905260248201527f4f776e61626c653a2063616c6c6572206973206e6f7420746865206f776e6572604482015260640161040b565b600080546001600160a01b038381166001600160a01b0319831681178455604051919092169283917f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e09190a35050565b6000815180845260005b818110156104f0576020818501810151868301820152016104d4565b506000602082860101526020601f19601f83011685010191505092915050565b60208152600061052360208301846104ca565b9392505050565b60006020828403121561053c57600080fd5b81356001600160a01b038116811461052357600080fd5b60008083601f84011261056557600080fd5b50813567ffffffffffffffff81111561057d57600080fd5b60208301915083602082850101111561059557600080fd5b9250929050565b600080600080606085870312156105b257600080fd5b843563ffffffff811681146105c657600080fd5b935060208501359250604085013567ffffffffffffffff8111156105e957600080fd5b6105f587828801610553565b95989497509550505050565b60008060006040848603121561061657600080fd5b83359250602084013567ffffffffffffffff81111561063457600080fd5b61064086828701610553565b9497909650939450505050565b600181811c9082168061066157607f821691505b60208210810361068157634e487b7160e01b600052602260045260246000fd5b50919050565b81835281816020850137506000828201602090810191909152601f909101601f19169091010190565b6020815260006106c4602083018486610687565b949350505050565b634e487b7160e01b600052604160045260246000fd5b601f82111561072e576000816000526020600020601f850160051c8101602086101561070b5750805b601f850160051c820191505b8181101561072a57828155600101610717565b5050505b505050565b67ffffffffffffffff83111561074b5761074b6106cc565b61075f83610759835461064d565b836106e2565b6000601f841160018114610793576000851561077b5750838201355b600019600387901b1c1916600186901b178355610310565b600083815260209020601f19861690835b828110156107c457868501358255602094850194600190920191016107a4565b50868210156107e15760001960f88860031b161c19848701351681555b505060018560011b0183555050505050565b83815260406020820152600061080d604083018486610687565b9594505050505056fea2646970667358221220e74b9ce655ed9c3a34678c7f1f825221c112607de021b8a463cd377e3305ee6564736f6c63430008170033 \ No newline at end of file diff --git a/script/example/docker-compose.yml b/example/docker-compose.yml similarity index 100% rename from script/example/docker-compose.yml rename to example/docker-compose.yml diff --git a/script/example/hyperlane/agent-config.docker.json b/example/hyperlane/agent-config.docker.json similarity index 100% rename from script/example/hyperlane/agent-config.docker.json rename to example/hyperlane/agent-config.docker.json diff --git a/script/example/hyperlane/relayer.json b/example/hyperlane/relayer.json similarity index 100% rename from script/example/hyperlane/relayer.json rename to example/hyperlane/relayer.json diff --git a/script/example/hyperlane/validator.localosmosis.json b/example/hyperlane/validator.localosmosis.json similarity index 100% rename from script/example/hyperlane/validator.localosmosis.json rename to example/hyperlane/validator.localosmosis.json diff --git a/script/example/hyperlane/validator.sepolia.json b/example/hyperlane/validator.sepolia.json similarity index 100% rename from script/example/hyperlane/validator.sepolia.json rename to example/hyperlane/validator.sepolia.json diff --git a/script/GUIDE_TOOL.md b/script/GUIDE_TOOL.md deleted file mode 100644 index 62ced17e..00000000 --- a/script/GUIDE_TOOL.md +++ /dev/null @@ -1,72 +0,0 @@ -# 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 index 64786025..62ced17e 100644 --- a/script/README.md +++ b/script/README.md @@ -1,8 +1,72 @@ -# CW Hyperlane Scripts +# cw-hpl -This directory contains scripts for the CW Hyperlane project. +## Prerequisites -## Guides +- \>= Node v20 +- \>= Yarn v4.1 -- [Tool](./GUIDE_TOOL.md) -- [Deploy](./GUIDE_DEPLOY.md) +## 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!