From 6d58ca853fff8ccec3e687be13f77662bbee0c81 Mon Sep 17 00:00:00 2001 From: Collin Date: Wed, 13 Sep 2023 11:57:36 -0500 Subject: [PATCH] README Updates (#224) * Initial README update * Remove Gravity items more suited for that repo * Line wrapping for easier editing * systemd file updates * README fixes * Add blurb about upgrading binaries during sync * Update config.toml example and typo fixes in README * Update peers list * Fix gas adjustments in example steward config * Revert "Update peers list" This reverts commit b578afe27d3a2bcf7ee4393b0d55d23ef6787d31. --- README.md | 242 +++++++++--------- contrib/mainnet/sommelier-3/config.toml | 19 +- contrib/systemd/geth.goerli.service | 15 -- contrib/systemd/geth.service | 15 -- .../{gorc.service => orchestrator.service} | 4 +- contrib/systemd/steward.service | 16 ++ 6 files changed, 154 insertions(+), 157 deletions(-) delete mode 100644 contrib/systemd/geth.goerli.service delete mode 100644 contrib/systemd/geth.service rename contrib/systemd/{gorc.service => orchestrator.service} (54%) create mode 100644 contrib/systemd/steward.service diff --git a/README.md b/README.md index f181da5c..1247ec12 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # Sommelier -Sommelier is a coprocessor blockchain for Ethereum DeFi. +Sommelier is a platform for running DeFi strategies in special vaults, called +Cellars, managed by off-chain computation. It's a blockchain built with the +[Cosmos SDK](https://github.com/cosmos/cosmos-sdk), and uses its own fork of the +[Gravity Bridge](https://github.com/peggyjv/gravity-bridge) to enable +cross-chain execution. + +For more information you can check out the [Sommelier Documentation](https://sommelier-finance.gitbook.io/sommelier-documentation/introduction/what-is-sommelier) [![codecov](https://codecov.io/gh/peggyjv/sommelier/branch/main/graph/badge.svg)](https://codecov.io/gh/peggyjv/sommelier) [![Go Report Card](https://goreportcard.com/badge/github.com/peggyjv/sommelier)](https://goreportcard.com/report/github.com/peggyjv/sommelier) @@ -18,78 +24,99 @@ We have active, helpful communities on Twitter, Discord, and Telegram. ## Sommelier -The initial release of the Sommelier blockchain will consist of a standard cosmos-sdk chain and the recently completed [Gravity Bridge refactor](https://github.com/peggyjv/gravity-bridge). - -### Gravity Bridge +The initial release of the Sommelier blockchain consists of a standard +cosmos-sdk chain and [Gravity Bridge +refactor](https://github.com/peggyjv/gravity-bridge). -The Gravity Bridge requires some additional pieces to be deployed to support it: - -- [ ] [Ethereum Contract](https://github.com/PeggyJV/gravity-bridge/tree/main/solidity) and associated tooling -- [ ] Orchestrator/Relayer binaries built from the `go.mod` commit +### Steward +[Steward](https://github.com/peggyjv/steward) is a sidecar process that +facilitates function calls by Strategists to Cellars. It's also a CLI that +subsumes the functionality of `gorc`, and is used in this document to configure +and run the orchestrator. ## Join the mainnet! +Running a validator node on the Sommelier mainnet requires three processes: + +1. The validator node +2. The Gravity Bridge Orchestrator +3. [Steward](https://github.com/peggyjv/steward) + +The Orchestrator (and Relayer if you are designated to run one) need an RPC +endpoint to interact with Ethereum. We recommend using a service such as +Alchemy or Infura. Larger validators may opt to use any existing full node they +are already running for other purposes. Setup and configuration of an Ethereum +node is left as an exercise for the reader. + +The Steward CLI now supports all of the same commands as `gorc` and is the +recommended way to configure delegate keys for new validators and to run the +Orchestrator. __The Steward CLI is used to run *both* the `steward` and +`orchestrator` processes__. There are post-installation steps for the `steward` +process outlined at the end of the installation steps below. These are required +for your Steward to participate in the protocol. For more information on these +setup steps for Steward, see [Validators Instructions for Setting Up +Steward](https://github.com/PeggyJV/steward/blob/3.x-main/docs/02-StewardForValidators.md) +in the Steward repository. + +> NOTE: The Steward CLI and Steward itself are distinct concepts in this +> document. The Steward CLI is used to start both the `steward` and +> `orchestrator` processes, while "Steward" refers specifically to the +> `steward` process. + ### Installation -```bash +```bash # Create an installation directory mkdir install && cd install -# Install Orchestrator -wget https://github.com/PeggyJV/gravity-bridge/releases/download/v0.3.9/gorc && chmod +x * && sudo mv * /usr/bin - -# Install Geth -wget https://gethstore.blob.core.windows.net/builds/geth-linux-amd64-1.10.4-aa637fd3.tar.gz && tar -xvf geth-linux-amd64-1.10.4-aa637fd3.tar.gz && sudo mv geth-linux-amd64-1.10.4-aa637fd3/geth /usr/bin/geth && rm -rf geth-linux-amd64-1.10.4-aa637fd3* +# Install Steward +wget https://github.com/PeggyJV/steward/releases/latest/download/steward \ + && chmod +x * \ + && sudo mv * /usr/bin # Install Sommelier -wget https://github.com/PeggyJV/sommelier/releases/download/v3.1.1/sommelier_3.1.1_linux_amd64.tar.gz && tar -xf sommelier_3.1.1_linux_amd64.tar.gz && sudo mv sommelier /usr/bin && rm -rf sommelier_3.1.1_linux_amd64* LICENSE README.md +wget https://github.com/PeggyJV/sommelier/releases/download/v3.1.1/sommelier_3.1.1_linux_amd64.tar.gz \ + && tar -xf sommelier_3.1.1_linux_amd64.tar.gz \ + && sudo mv sommelier /usr/bin \ + && rm -rf sommelier_3.1.1_linux_amd64* LICENSE README.md -# Fetch systemd unit files -wget https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/systemd/geth.service https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/systemd/gorc.service https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/systemd/sommelier.service +# Fetch systemd unit file examples +wget \ + https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/systemd/sommelier.service \ + https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/systemd/orchestrator.service \ + https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/systemd/steward.service # Modify the unit files to fit your environment -nano geth.service -nano gorc.service +nano orchestrator.service +nano steward.service nano sommelier.service # And install them to systemd -sudo mv geth.service /etc/systemd/system/geth.service && sudo mv gorc.service /etc/systemd/system/ && sudo mv sommelier.service /etc/systemd/system/ && sudo systemctl daemon-reload - -# Start geth -sudo systemctl start geth && sudo journalctl -u geth -f - -# Init gorc configuration -mkdir -p $HOME/gorc && cd $HOME/gorc +sudo mv orchestrator.service /etc/systemd/system/ \ + && sudo mv steward.service /etc/systemd/system/ \ + && sudo mv sommelier.service /etc/systemd/system/ \ + && sudo systemctl daemon-reload + +# Init steward/orchestrator configuration. Note that the steward and orchestrator processes share +# much of the same configuration fields, so we share the config.toml for convenience. +mkdir -p $HOME/steward && cd $HOME/steward wget https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/mainnet/sommelier-3/config.toml -# modify gorc config for your environment -# You can use alchemy, infura endpoint as RPC and not necessarily need to sync the blockchain eth with geth +# modify steward/orchestrator config for your environment, in particular your RPC URL and keystore path nano config.toml # Initialize the validator files sommelier init myval --chain-id sommelier-3 +``` -# create/restore 2 cosmos keys and 1 ethereum key -# NOTE: be sure to save the mnemonics and eth private key - -# restore orchestrator key with gorc -gorc --config $HOME/gorc/config.toml keys cosmos recover orchestrator "{menmonic}" - -# OR: create orchestrator key with gorc -gorc --config $HOME/gorc/config.toml keys cosmos add orchestrator - -# restore eth key - -# EITHER: restore eth priv key from metamask with gorc -gorc --config $HOME/gorc/config.toml keys eth import signer "0x0000..." - -# OR: restore eth mnemonic with gorc -gorc --config $HOME/gorc/config.toml keys eth recover signer "{menomonic}" - -# OR: create eth key with gorc -gorc --config $HOME/gorc/config.toml keys eth add signer +At this point you need to create orchestrator keys OR restore them if you +already created them. __Please follow [these +instructions](https://github.com/PeggyJV/steward/blob/main/docs/03-TheOrchestrator.md#setup) +to create or restore these keys with the Steward CLI__, then return to this doc +for steps to add them to your validator. +```bash # restore your validator mnemonic to the sommelier binary sommelier keys add validator --recover @@ -97,20 +124,37 @@ sommelier keys add validator --recover sommelier keys add validator # NOTE: at the end of this process you need to have: -# - a key named "orchestrator" with funds on the cosmos chain in the gorc keystore -# - a key named "signer" with funds on connected ETH chain in the gorc keystore +# - a key named "orchestrator" with funds on the cosmos chain in the steward keystore +# - a key named "signer" with funds on connected ETH chain in the steward keystore # - a key named "validator" with funds on the cosmos chain in the sommelier keystore # Add the peers from contrib/mainnet/sommelier-3/peers.txt to the ~/.sommelier/config/config.toml file nano ~/.sommelier/config/config.toml -# pull the genesis file -wget https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/mainnet/sommelier-3/genesis.json -O $HOME/.sommelier/config/genesis.json +# pull the genesis file +wget https://raw.githubusercontent.com/PeggyJV/sommelier/main/contrib/mainnet/sommelier-3/genesis.json \ + -O $HOME/.sommelier/config/genesis.json # start your sommelier node - note it may take a minute or two to sync all of the blocks sudo systemctl start sommelier && sudo journalctl -u sommelier -f +``` + +Your node should now be syncing from genesis. You will be required to update +the binary as your sync reaches upgrade block heights. The tool +[cosmovisor](https://docs.cosmos.network/main/tooling/cosmovisor) is useful for +handling this process automatically. Its setup and use is left as an exercise +for the reader. The order of binary versions you will need to complete the sync +process is shown below. -# once your node is synced, create your validator +| Height | Version | +|-|-| +| Genesis | 3.1.1 | +| 3610000 | [4.0.3](https://github.com/PeggyJV/sommelier/releases/tag/v4.0.3) | +| 7766725 | [5.0.0](https://github.com/PeggyJV/sommelier/releases/tag/v5.0.0) | +| 8704480 | [6.0.0](https://github.com/PeggyJV/sommelier/releases/tag/v6.0.0) | + +```bash +# once your node is synced, create your validator sommelier tx staking create-validator \ --amount=1000000usomm \ --pubkey=$(sommelier tendermint show-validator) \ @@ -120,89 +164,45 @@ sommelier tx staking create-validator \ --commission-max-rate="0.20" \ --commission-max-change-rate="0.01" \ --min-self-delegation="1" \ - --gas 300000 - --fees="0usomm" + --gas 300000 \ + --fees="0usomm" \ --from=validator # register delegate keys for eth and orchestrator keys sommelier tx gravity set-delegate-keys \ $(sommelier keys show validator --bech val -a) \ # validator address - $(gorc --config $HOME/gorc/config.toml keys cosmos show orchestrator) \ # orchestrator address (this must be run manually and address extracted) - $(gorc --config $HOME/gorc/config.toml keys eth show signer) \ # eth signer address - $(gorc --config $HOME/gorc/config.toml sign-delegate-keys signer $(sommelier keys show validator --bech val -a)) \ - --chain-id sommelier-3 \ - --from validator \ + $(steward --config $HOME/steward/config.toml keys cosmos show orchestrator) \ # orchestrator address (this must be run manually and address extracted) + $(steward --config $HOME/steward/config.toml keys eth show signer) \ # eth signer address + $(steward --config $HOME/steward/config.toml sign-delegate-keys signer $(sommelier keys show validator --bech val -a)) \ + --chain-id sommelier-3 \ + --from validator \ -y -# start the orchestrator -sudo systemctl start gorc && sudo journalctl -u gorc -f +# start the orchestrator. note that we are not yet starting steward +sudo systemctl start orchestrator && sudo journalctl -u orchestrator -f ``` -### Actions - -Now you can try the bridge!! - -```bash -# send somm to ethereum -gorc cosmos-to-eth \ - --cosmos-phrase="$(jq -r '.orchestrator' ~/keys.json)" \ - --cosmos-grpc="http://localhost:9090" \ - --cosmos-denom="somm" \ - --amount="100000000" \ - --eth-destination=$(gorc --config $HOME/gorc/config.toml keys eth show signer) \ - --cosmos-prefix="cosmos" - -# send goreli uniswap tokens to cosmos -gorc eth-to-cosmos \ - --ethereum-key="$(jq -r '.eth' ~/keys.json)" \ - --ethereum-rpc="http://localhost:8545" \ - --cosmos-prefix="cosmos" \ - --contract-address="$(jq -r '.gravity' ~/keys.json)" \ - --erc20-address="0x0000000000000000000000000000000000000000" \ - --amount="1.3530000" \ - --cosmos-destination="$(sommelier keys show orchestrator -a)" - -``` +At this point, you should have a running validator node and Orchestrator. -## Notes: +Now it's time to complete the setup for Steward. Please follow the detailed +guide in [Validators Instructions for Setting Up +Steward](https://github.com/PeggyJV/steward/blob/main/docs/02-StewardForValidators.md) +and return here. -### Genesis File Changes Necessary +At this point you should have a server CA and server certificate for Steward, +and your `config.toml` should be configured with those values. Now we can start +the Steward service that we created during the other installation steps. ```bash -# change stake to usomm -sed -i 's/stake/usomm/g' ~/.sommelier/config/genesis.json - -# denom metadata -# TODO: add name and symbol here -jq -rMc '.app_state.bank.denom_metadata += [{"base": "usomm", display: "somm", "description": "A staking test token", "denom_units": [{"denom": "usomm", "exponent": 0}, {"denom": "somm", "exponent": 6}]}]' ~/.sommelier/config/genesis.json > ~/.sommelier/config/genesis.json - -# gravity params -jq -rMc '.app_state.gravity.params.bridge_chain_id = "5"' ~/.sommelier/config/genesis.json > ~/.sommelier/config/genesis.json +# start steward +sudo systemctl start steward && sudo journalctl -u steward -f ``` -### Deploy Peggy Contract +Once your Steward is running, ensure that its server endpoint is reachable over +the internet. Then, if you haven't already, follow the steps outlined in the +[Steward Registry repository](https://github.com/PeggyJV/steward-registry) to +register your steward instance. -```bash -wget https://github.com/PeggyJV/gravity-bridge/releases/download/v0.1.21/Gravity.json -contract-deployer \ - --cosmos-node="http://localhost:26657" \ - --eth-node="http://localhost:8545" \ - --eth-privkey="0x0000000000000000000000000000000000000000000000000000000000000000" \ - --contract=Gravity.json \ - --test-mode=false -``` +Your installation is complete! If you have any problems, please reach out in +the validator lobby channels in Discord or Telegram. -### Deploy Somm ERC20 representation - -```bash -gorc deploy erc20 \ - --ethereum-key="0x0000000000000000000000000000000000000000000000000000000000000000" \ - --cosmos-grpc="http://localhost:9090" \ - --cosmos-prefix=cosmos \ - --cosmos-denom=usomm \ - --ethereum-rpc=http://localhost:8545 \ - --contract-address="0x8887F26882a3F920e40A91969D1A40D1Ef7efe10" \ - --erc20-name=usomm \ - --erc20-symbol=usomm \ - --erc20-decimals=6 -``` diff --git a/contrib/mainnet/sommelier-3/config.toml b/contrib/mainnet/sommelier-3/config.toml index e56229ac..da928880 100644 --- a/contrib/mainnet/sommelier-3/config.toml +++ b/contrib/mainnet/sommelier-3/config.toml @@ -1,20 +1,21 @@ -keystore = "/home/ubuntu/gorc/keystore/" #edit this value for what it is your sommelier v2 gorc +keystore = "/home/ubuntu/steward/keystore/" #edit this value for what it is for your sommelier v3 steward or gorc keystore. [gravity] -contract = "0x69592e6f9d21989a043646fE8225da2600e5A0f7" +contract = "0x69592e6f9d21989a043646fE8225da2600e5A0f7" fees_denom = "usomm" [ethereum] key_derivation_path = "m/44'/60'/0'/0/0" rpc = "http://localhost:8545" #Can use alchemy or infura here. gas_price_multiplier = 1.0 +gas_multiplier = 1.1 blocks_to_search = 5000 [cosmos] key_derivation_path = "m/44'/118'/0'/0/0" grpc = "http://localhost:9090" prefix = "somm" -gas_adjustment = 1.0 +gas_adjustment = 1.1 msg_batch_size = 5 [cosmos.gas_price] @@ -22,4 +23,14 @@ amount = 0.000 denom = "usomm" [metrics] -listen_addr = "127.0.0.1:3000" \ No newline at end of file +listen_addr = "127.0.0.1:3000" + +[keys] +delegate_key = "orchestrator" # Edit if your orchestrator's Cosmos key name is different + +# Please leave the client_ca_cert_path field unset for now +[server] +address = "0.0.0.0" +port = 5734 +server_cert_path = "/server/cert/path" # Edit this value after completing the Steward setup process +server_key_path = "/server/key/path" # Edit this value after completing the Steward setup process diff --git a/contrib/systemd/geth.goerli.service b/contrib/systemd/geth.goerli.service deleted file mode 100644 index 5357cf0c..00000000 --- a/contrib/systemd/geth.goerli.service +++ /dev/null @@ -1,15 +0,0 @@ -[Unit] -Description=Goreli Geth Node -After=online.target - -[Service] -Type=simple -User=ubuntu -WorkingDirectory=/home/ubuntu -ExecStart=/usr/bin/geth --syncmode "light" --goerli --http --cache 16 -Restart=on-failure -RestartSec=3 -LimitNOFILE=4096 - -[Install] -WantedBy=multi-user.target \ No newline at end of file diff --git a/contrib/systemd/geth.service b/contrib/systemd/geth.service deleted file mode 100644 index 87d33b25..00000000 --- a/contrib/systemd/geth.service +++ /dev/null @@ -1,15 +0,0 @@ -[Unit] -Description=Geth Node -After=online.target - -[Service] -Type=simple -User=ubuntu -WorkingDirectory=/home/ubuntu -ExecStart=/usr/bin/geth --syncmode "light" --http --cache 16 -Restart=on-failure -RestartSec=3 -LimitNOFILE=4096 - -[Install] -WantedBy=multi-user.target \ No newline at end of file diff --git a/contrib/systemd/gorc.service b/contrib/systemd/orchestrator.service similarity index 54% rename from contrib/systemd/gorc.service rename to contrib/systemd/orchestrator.service index 333e99cd..0a363b37 100644 --- a/contrib/systemd/gorc.service +++ b/contrib/systemd/orchestrator.service @@ -7,10 +7,10 @@ Type=simple User=ubuntu Environment="RUST_LOG=INFO" WorkingDirectory=/home/ubuntu -ExecStart=/usr/bin/gorc --config /home/ubuntu/gorc/config.toml orchestrator start --cosmos-key orchestrator --ethereum-key signer +ExecStart=/usr/bin/steward --config /home/ubuntu/steward/config.toml orchestrator start --cosmos-key orchestrator --ethereum-key signer --orchestrator-only Restart=on-failure RestartSec=3 LimitNOFILE=4096 [Install] -WantedBy=multi-user.target \ No newline at end of file +WantedBy=multi-user.target diff --git a/contrib/systemd/steward.service b/contrib/systemd/steward.service new file mode 100644 index 00000000..b1627812 --- /dev/null +++ b/contrib/systemd/steward.service @@ -0,0 +1,16 @@ +[Unit] +Description=Sommelier Steward +After=online.target + +[Service] +Type=simple +User=ubuntu +Environment="RUST_LOG=INFO" +WorkingDirectory=/home/ubuntu +ExecStart=/usr/bin/steward --config /home/ubuntu/steward/config.toml start +Restart=on-failure +RestartSec=3 +LimitNOFILE=4096 + +[Install] +WantedBy=multi-user.target