diff --git a/README.md b/README.md index ffb0c50..f8fe728 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,12 @@ It uses Cosmos-SDK's [simapp](https://github.com/cosmos/cosmos-sdk/tree/main/sim **Note**: Requires [Go 1.20](https://go.dev/) + +## Feature-full setup + +For a more advanced setup that include `denom-metadata`, `genesis-accounts` and others, please refer to the [README.with-advanced-features.md](./README.with-advanced-features.md) + + ## Installing / Getting started Build and install the ```rollapp-evm``` binary: @@ -33,7 +39,8 @@ export the following variables: ```shell export ROLLAPP_CHAIN_ID="rollappevm_1234-1" export KEY_NAME_ROLLAPP="rol-user" -export DENOM="urax" +export BASE_DENOM="arax" +export DENOM=$(echo "$BASE_DENOM" | sed 's/^.//') export MONIKER="$ROLLAPP_CHAIN_ID-sequencer" ``` @@ -69,7 +76,8 @@ SEQUENCER_ADDR=`dymd keys show sequencer --address --keyring-backend test --keyr fund the sequencer account ```shell -dymd tx bank send local-user $SEQUENCER_ADDR 1000dym --keyring-backend test --broadcast-mode block --fees 1dym +BOND_AMOUNT="100000dym" +dymd tx bank send local-user $SEQUENCER_ADDR ${BOND_AMOUNT} --keyring-backend test --broadcast-mode block --fees 1dym ``` ### Register rollapp on settlement @@ -90,7 +98,8 @@ Modify `dymint.toml` in the chain directory (`~/.rollapp_evm/config`) set: ```shell -settlement_layer = "dymension" +ROLLAPP_HOME_DIR="$HOME/.rollapp_evm" +sed -i 's/settlement_layer.*/settlement_layer = "dymension"/' ${ROLLAPP_HOME_DIR}/config/dymint.toml ``` ### Run rollapp locally @@ -105,7 +114,7 @@ rollapp-evm start ```shell git clone https://github.com/dymensionxyz/go-relayer.git --branch v0.2.0-v2.3.1-relayer -cd relayer && make install +cd go-relayer && make install ``` ### Establish IBC channel @@ -126,4 +135,4 @@ rly start hub-rollapp ## Developers guide -TODO +TODO \ No newline at end of file diff --git a/README.with-advanced-features.md b/README.with-advanced-features.md new file mode 100644 index 0000000..e0ae700 --- /dev/null +++ b/README.with-advanced-features.md @@ -0,0 +1,180 @@ +# Dymension EVM Rollapp + +## Rollapp-evm - A template EVM RollApp chain + +This repository hosts `rollapp-evm`, a template implementation of a dymension rollapp with `EVM` execution layer. + +`rollapp-evm` is an example of a working RollApp using `dymension-RDK` and `dymint`. + +It uses Cosmos-SDK's [simapp](https://github.com/cosmos/cosmos-sdk/tree/main/simapp) as a reference, but with the following changes: + +- minimal app setup +- wired with EVM and ERC20 modules by [Evmos](https://github.com/evmos/evmos) +- wired IBC for [ICS 20 Fungible Token Transfers](https://github.com/cosmos/ibc/tree/main/spec/app/ics-020-fungible-token-transfer) +- Uses `dymint` for block sequencing and replacing `tendermint` +- Uses modules from `dymension-RDK` to sync with `dymint` and provide RollApp custom logic + +## Overview + +**Note**: Requires [Go 1.20](https://go.dev/) + +## Quick guide + +Get started with [building RollApps](https://docs.dymension.xyz/develop/get-started/setup) + +## Installing / Getting started + +Build and install the ```rollapp-evm``` binary: + +```shell +make install +``` + +### Initial configuration + +export the following variables: + +```shell +export ROLLAPP_CHAIN_ID="rollappevm_1234-1" +export KEY_NAME_ROLLAPP="rol-user" +export BASE_DENOM="arax" +export DENOM=$(echo "$BASE_DENOM" | sed 's/^.//') +export MONIKER="$ROLLAPP_CHAIN_ID-sequencer" +``` + +And initialize the rollapp: + +```shell +sh scripts/init.sh +``` + +### Run rollapp + +```shell +rollapp-evm start +``` + +You should have a running local rollapp! + +## Run a rollapp with a settlement node + +### Run local dymension hub node + +Follow the instructions on [Dymension Hub docs](https://docs.dymension.xyz/develop/get-started/run-base-layers) to run local dymension hub node + +all scripts are adjusted to use local hub node that's hosted on the default port `localhost:36657`. + +configuration with a remote hub node is also supported, the following variables must be set: + +```shell +export HUB_RPC_ENDPOINT="http://localhost" +export HUB_RPC_PORT="36657" # default: 36657 +export HUB_RPC_URL="http://3.71.160.88:36657" +export HUB_CHAIN_ID="dymension_100-1" +``` + +### Create sequencer keys + +create sequencer key using `dymd` + +```shell +dymd keys add sequencer --keyring-dir ~/.rollapp_evm/sequencer_keys --keyring-backend test +SEQUENCER_ADDR=`dymd keys show sequencer --address --keyring-backend test --keyring-dir ~/.rollapp_evm/sequencer_keys` +``` + +fund the sequencer account (if you're using a remote hub node, you must fund the sequencer account or you must have an account with enough funds in your keyring) + +```shell +BOND_AMOUNT="100000dym" +dymd tx bank send local-user $SEQUENCER_ADDR ${BOND_AMOUNT} --keyring-backend test --broadcast-mode block --fees 1dym -y --node ${HUB_RPC_URL} +``` + +### Generate denommetadata + +```shell +export ROLLAPP_SETTLEMENT_INIT_DIR_PATH="$HOME/.rollapp_evm/init" + +sh scripts/settlement/generate_denom_metadata.sh +``` + +### Add genesis accounts + + +```shell +sh scripts/settlement/add_genesis_accounts.sh +``` + +### Register rollapp on settlement + +```shell +# for permissioned deployment setup, you must have access to an account whitelisted for rollapp +# registration, assuming you want to import an existing account, you can do: +dymd keys add local-user --recover +# input mnemonic from the account that has the permission to register rollapp + +sh scripts/settlement/register_rollapp_to_hub.sh +``` + +### Register sequencer for rollapp on settlement + +```shell +sh scripts/settlement/register_sequencer_to_hub.sh +``` + +### Configure the rollapp + +Modify `dymint.toml` in the chain directory (`~/.rollapp_evm/config`) +set: + +```shell +ROLLAPP_HOME_DIR="$HOME/.rollapp_evm" +sed -i 's/settlement_layer.*/settlement_layer = "dymension"/' ${ROLLAPP_HOME_DIR}/config/dymint.toml +``` + +### Update the Genesis file to include the denommetadata, genesis accounts, module account and elevated accounts + +```shell +sh scripts/update_genesis_file.sh +``` + +### Update the Genesis file to include the denommetadata, genesis accounts, module account and elevated accounts + +```shell +# this script automatically adds 2 vesting accounts, adjust the timestampts to your liking or skip this step +sh scripts/add_vesting_accounts_to_genesis_file.sh +``` + +### Run rollapp locally + +```shell +rollapp-evm start +``` + +## Setup IBC between rollapp and local dymension hub node + +### Install dymension relayer + +```shell +git clone https://github.com/dymensionxyz/go-relayer.git --branch v0.2.0-v2.3.1-relayer +cd go-relayer && make install +``` + +### Establish IBC channel + +while the rollapp and the local dymension hub node running, run: + +```shell +sh scripts/ibc/setup_ibc.sh +``` + +After successful run, the new established channels will be shown + +### run the relayer + +```shell +rly start hub-rollapp +``` + +## Developers guide + +TODO diff --git a/scripts/add_vesting_accounts_to_genesis_file.sh b/scripts/add_vesting_accounts_to_genesis_file.sh new file mode 100644 index 0000000..ad3a5ba --- /dev/null +++ b/scripts/add_vesting_accounts_to_genesis_file.sh @@ -0,0 +1,12 @@ +#!/bin/bash +rollapp_evm keys add three-year-vester --keyring-backend test +rollapp_evm add-genesis-account three-year-vester \ + 10000000000000000000000a${BASE_DENOM} --keyring-backend test \ + --vesting-amount 10000000000000000000000a${BASE_DENOM} \ + --vesting-end-time 1805902584 + +rollapp_evm keys add two-year-vester-after-1-week --keyring-backend test +rollapp_evm add-genesis-account two-year-vester-after-1-week \ + 10000000000000000000000a${BASE_DENOM} --keyring-backend test \ + --vesting-amount 10000000000000000000000a${BASE_DENOM} \ + --vesting-end-time 1774366584 --vesting-start-time 1711985835 diff --git a/scripts/config.sh b/scripts/config.sh old mode 100644 new mode 100755 diff --git a/scripts/ibc/setup_ibc.sh b/scripts/ibc/setup_ibc.sh old mode 100644 new mode 100755 index 43efbba..d3d5219 --- a/scripts/ibc/setup_ibc.sh +++ b/scripts/ibc/setup_ibc.sh @@ -52,7 +52,7 @@ tmp=$(mktemp) jq --arg key "$RELAYER_KEY_FOR_ROLLAP" '.value.key = $key' $ROLLAPP_IBC_CONF_FILE > "$tmp" && mv "$tmp" $ROLLAPP_IBC_CONF_FILE jq --arg chain "$ROLLAPP_CHAIN_ID" '.value."chain-id" = $chain' $ROLLAPP_IBC_CONF_FILE > "$tmp" && mv "$tmp" $ROLLAPP_IBC_CONF_FILE jq --arg rpc "$ROLLAPP_RPC_FOR_RELAYER" '.value."rpc-addr" = $rpc' $ROLLAPP_IBC_CONF_FILE > "$tmp" && mv "$tmp" $ROLLAPP_IBC_CONF_FILE -jq --arg denom "0.0$DENOM" '.value."gas-prices" = $denom' $ROLLAPP_IBC_CONF_FILE > "$tmp" && mv "$tmp" $ROLLAPP_IBC_CONF_FILE +jq --arg denom "0.0$BASE_DENOM" '.value."gas-prices" = $denom' $ROLLAPP_IBC_CONF_FILE > "$tmp" && mv "$tmp" $ROLLAPP_IBC_CONF_FILE jq --arg key "$RELAYER_KEY_FOR_HUB" '.value.key = $key' $HUB_IBC_CONF_FILE > "$tmp" && mv "$tmp" $HUB_IBC_CONF_FILE jq --arg chain "$SETTLEMENT_CHAIN_ID" '.value."chain-id" = $chain' $HUB_IBC_CONF_FILE > "$tmp" && mv "$tmp" $HUB_IBC_CONF_FILE @@ -74,7 +74,7 @@ echo "From within the hub node: \"$SETTLEMENT_EXECUTABLE tx bank send $SETTLEMEN echo "# ------------------------------- balance of rly account on rollapp [$RLY_ROLLAPP_ADDR] ------------------------------ #" $EXECUTABLE q bank balances "$(rly keys show "$ROLLAPP_CHAIN_ID")" --node "$ROLLAPP_RPC_FOR_RELAYER" -echo "From within the rollapp node: \"$EXECUTABLE tx bank send $KEY_NAME_ROLLAPP $RLY_ROLLAPP_ADDR 100000000000000000000$DENOM --keyring-backend test --broadcast-mode block\"" +echo "From within the rollapp node: \"$EXECUTABLE tx bank send $KEY_NAME_ROLLAPP $RLY_ROLLAPP_ADDR 100000000000000000000$BASE_DENOM --keyring-backend test --broadcast-mode block\"" echo "waiting to fund accounts. Press to continue..." read -r answer diff --git a/scripts/init.sh b/scripts/init.sh old mode 100644 new mode 100755 index dbb98d2..2b9e5f8 --- a/scripts/init.sh +++ b/scripts/init.sh @@ -15,7 +15,7 @@ set_denom() { } set_EVM_params() { - jq '.consensus_params["block"]["max_gas"] = "40000000"' "$GENESIS_FILE" > "$tmp" && mv "$tmp" "$GENESIS_FILE" + jq '.consensus_params["block"]["max_gas"] = "400000000"' "$GENESIS_FILE" > "$tmp" && mv "$tmp" "$GENESIS_FILE" jq '.app_state["feemarket"]["params"]["no_base_fee"] = true' "$GENESIS_FILE" > "$tmp" && mv "$tmp" "$GENESIS_FILE" jq '.app_state["feemarket"]["params"]["min_gas_price"] = "0.0"' "$GENESIS_FILE" > "$tmp" && mv "$tmp" "$GENESIS_FILE" } @@ -23,8 +23,8 @@ set_EVM_params() { # ---------------------------- initial parameters ---------------------------- # # Assuming 1,000,000 tokens #half is staked -TOKEN_AMOUNT="1000000000000000000000000$DENOM" -STAKING_AMOUNT="500000000000000000000000$DENOM" +TOKEN_AMOUNT="1000000000000000000000000$BASE_DENOM" +STAKING_AMOUNT="500000000000000000000000$BASE_DENOM" CONFIG_DIRECTORY="$ROLLAPP_CHAIN_DIR/config" @@ -64,8 +64,8 @@ $EXECUTABLE init "$MONIKER" --chain-id "$ROLLAPP_CHAIN_ID" $EXECUTABLE config chain-id "$ROLLAPP_CHAIN_ID" # -------------------------------- app config -------------------------------- # -sed -i'' -e "s/^minimum-gas-prices *= .*/minimum-gas-prices = \"0$DENOM\"/" "$APP_CONFIG_FILE" -set_denom "$DENOM" +sed -i'' -e "s/^minimum-gas-prices *= .*/minimum-gas-prices = \"0$BASE_DENOM\"/" "$APP_CONFIG_FILE" +set_denom "$BASE_DENOM" set_EVM_params # --------------------- adding keys and genesis accounts --------------------- # diff --git a/scripts/settlement/add_genesis_accounts.sh b/scripts/settlement/add_genesis_accounts.sh new file mode 100755 index 0000000..7905a71 --- /dev/null +++ b/scripts/settlement/add_genesis_accounts.sh @@ -0,0 +1,24 @@ +#!/bin/bash + +if [ ! -d "$ROLLAPP_SETTLEMENT_INIT_DIR_PATH" ]; then + mkdir -p "$ROLLAPP_SETTLEMENT_INIT_DIR_PATH" + echo "Creating the ROLLAPP_SETTLEMENT_INIT_DIR_PATH: $ROLLAPP_SETTLEMENT_INIT_DIR_PATH" +else + echo "ROLLAPP_SETTLEMENT_INIT_DIR_PATH already exists: $ROLLAPP_SETTLEMENT_INIT_DIR_PATH" +fi + +dymd keys add alice-genesis --keyring-backend test +dymd keys add bob-genesis --keyring-backend test + +tee "$ROLLAPP_SETTLEMENT_INIT_DIR_PATH/genesis_accounts.json" >/dev/null </dev/null <"$tmp" && mv "$tmp" "$GENESIS_FILE" +jq '.consensus_params["block"]["max_bytes"] = "5242880"' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" + +jq '.app_state.gov.voting_params.voting_period = "300s"' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" + +# this is a static module account for the hubgenesis module +# retrieved using 'rollapp-evm q auth module-accounts' command +module_account_address="ethm1748tamme3jj3v9wq95fc3pmglxtqscljdy7483" + +# Construct the JSON object with the obtained address +module_account=$(jq -n \ + --arg address "$module_account_address" \ + '[{ + "@type": "/cosmos.auth.v1beta1.ModuleAccount", + "base_account": { + "account_number": "0", + "address": $address, + "pub_key": null, + "sequence": "0" + }, + "name": "hubgenesis", + "permissions": [] + }]') + +jq --argjson module_account "$module_account" '.app_state.auth.accounts += $module_account' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" + +module_account_balance=$( + jq -n \ + --arg address "$module_account_address" \ + --arg denom "$BASE_DENOM" \ + '[{ + "address": $address, + "coins": [ + { + "denom": $denom, + "amount": "60000000000000000000000" + } + ] + }]' +) + +jq '.app_state.bank.balances[0].coins[0].amount = "2000000000000000000000000000"' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" +jq --argjson module_account_balance "$module_account_balance" '.app_state.bank.balances += $module_account_balance' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" + +jq '.app_state.bank.supply[0].amount = "2000060000000000000000000000"' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" + +# ---------------------------- add elevated account ---------------------------- # +elevated_address=$(${EXECUTABLE} keys show ${KEY_NAME_ROLLAPP} --keyring-backend test --output json | jq -r .address) +elevated_address_json=$(jq -n \ + --arg address "$elevated_address" \ + '[{ + "address": $address + }]') +jq --argjson elevated_address_json "$elevated_address_json" '.app_state.hubgenesis.params.genesis_triggerer_whitelist += $elevated_address_json' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" +jq '.app_state.hubgenesis.hub.hub_id = "dymension_100-1"' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" + +# ---------------------------- add denom metadata ---------------------------- # +denom_metadata=$(cat $ROLLAPP_SETTLEMENT_INIT_DIR_PATH/denommetadata.json) +jq --argjson denom_metadata "$denom_metadata" '.app_state.bank.denom_metadata = $denom_metadata' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE" +jq --arg elevated_address "$elevated_address" '.app_state.denommetadata.params.allowed_addresses += [$elevated_address]' "$GENESIS_FILE" >"$tmp" && mv "$tmp" "$GENESIS_FILE"