From 2ca3ee3af889950bd2633e466c7c5505930bbf3c Mon Sep 17 00:00:00 2001 From: Ukeje Goodness Date: Tue, 24 Sep 2024 09:35:51 +0100 Subject: [PATCH] chore: refactored README for interactivity and readability (#7321) * [update]: refactored README for interactivity and readability Updated the readme for interactivity (copying the commands) and readability (gradual process view). * Update simapp/README.md Co-authored-by: Damian Nolan * Update simapp/README.md * chore: linter fixes * chore: add toml to fenced code block - linting --------- Co-authored-by: Damian Nolan Co-authored-by: DimitrisJim --- simapp/README.md | 157 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 110 insertions(+), 47 deletions(-) diff --git a/simapp/README.md b/simapp/README.md index a3488dc0d53..86efd020404 100644 --- a/simapp/README.md +++ b/simapp/README.md @@ -1,47 +1,110 @@ -# simapp - -simapp is an application built using the Cosmos SDK for testing and educational purposes. - -## Running testnets with `simd` - -If you want to spin up a quick testnet with your friends, you can follow these steps. -Unless otherwise noted, every step must be done by everyone who wants to participate -in this testnet. - -1. `$ make build`. This will build the `simd` binary and install it in your Cosmos SDK repo, - inside a new `build` directory. The following instructions are run from inside - that directory. -2. If you've run `simd` before, you may need to reset your database before starting a new - testnet: `$ ./simd unsafe-reset-all` -3. `$ ./simd init [moniker]`. This will initialize a new working directory, by default at - `~/.simapp`. You need a provide a "moniker," but it doesn't matter what it is. -4. `$ ./simd keys add [key_name]`. This will create a new key, with a name of your choosing. - Save the output of this command somewhere; you'll need the address generated here later. -5. `$ ./simd add-genesis-account $(simd keys show [key_name] -a) [amount]`, where `key_name` - is the same key name as before; and `amount` is something like `10000000000000000000000000stake`. -6. `$ ./simd gentx [key_name] [amount] --chain-id [chain-id]`. This will create the - genesis transaction for your new chain. -7. Now, one person needs to create the genesis file `genesis.json` using the genesis transactions - from every participant, by gathering all the genesis transactions under `config/gentx` and then - calling `./simd collect-gentxs`. This will create a new `genesis.json` file that includes data - from all the validators (we sometimes call it the "super genesis file" to distinguish it from - single-validator genesis files). -8. Once you've received the super genesis file, overwrite your original `genesis.json` file with - the new super `genesis.json`. -9. Modify your `config/config.toml` (in the simapp working directory) to include the other participants as - persistent peers: - - ```text - # Comma separated list of nodes to keep persistent connections to - persistent_peers = "[validator address]@[ip address]:[port],[validator address]@[ip address]:[port]" - ``` - - You can find `validator address` by running `./simd tendermint show-node-id`. (It will be hex-encoded.) - By default, `port` is 26656. -10. Now you can start your nodes: `$ ./simd start`. - -Now you have a small testnet that you can use to try out changes to the Cosmos SDK or Tendermint! - -NOTE: Sometimes creating the network through the `collect-gentxs` will fail, and validators will start -in a funny state (and then panic). If this happens, you can try to create and start the network first -with a single validator and then add additional validators using a `create-validator` transaction. +# `SimApp` + +`SimApp` is a CLI application built using the Cosmos SDK for testing and educational purposes. + +## Running Testnets with `simd` + +Want to spin up a quick testnet with your friends? Follow these steps. Unless stated otherwise, all participants in the testnet must follow through with each step. + +### 1. Download and Setup + +Download IBC-go and unzip it. You can do this manually (via the GitHub UI) or with the git clone command: + +```sh +git clone github.com/cosmos/ibc-go.git +``` + +Next, run this command to build the `simd` binary in the `build` directory: + +```sh +make build +``` + +Use the following command and skip all the next steps to configure your SimApp node: + +```sh +make init-simapp +``` + +If you've run `simd` in the past, you may need to reset your database before starting up a new testnet. You can do that with this command: + +```sh +# you need to provide the moniker and chain ID +$ ./simd init [moniker] --chain-id [chain-id] +``` + +The command should initialize a new working directory at the `~simapp` location. +The `moniker` and `chain-id` can be anything, but you must use the same `chain-id` subsequently. + +### 2. Create a New Key + +Execute this command to create a new key: + +```sh + ./simd keys add [key_name] +``` + +⚠️ The command will create a new key with your chosen name. +Save the output somewhere safe; you'll need the address later. + +### 3. Add Genesis Account + +Add a genesis account to your testnet blockchain: + +```sh +./simd genesis add-genesis-account [key_name] [amount] +``` + +Where `key_name` is the same key name as before, and the `amount` is something like `10000000000000000000000000stake`. + +### 4. Add the Genesis Transaction + +This creates the genesis transaction for your testnet chain: + +```sh +./simd genesis gentx [key_name] [amount] --chain-id [chain-id] +``` + +The amount should be at least `1000000000stake`. Providing too much or too little may result in errors when you start your node. + +### 5. Create the Genesis File + +A participant must create the genesis file `genesis.json` with every participant's transaction. +You can do this by gathering all the Genesis transactions under `config/gentx` and then executing this command: + +```sh +./simd genesis collect-gentxs +``` + +The command will create a new `genesis.json` file that includes data from all the validators. We sometimes call this the "super genesis file" to distinguish it from single-validator genesis files. + +Once you've received the super genesis file, overwrite your original `genesis.json` file with the new super `genesis.json`. + +Modify your `config/config.toml` (in the simapp working directory) to include the other participants as persistent peers: + +```toml +# Comma-separated list of nodes to keep persistent connections to +persistent_peers = "[validator_address]@[ip_address]:[port],[validator_address]@[ip_address]:[port]" +``` + +You can find `validator_address` by executing: + +```sh +./simd comet show-node-id +``` + +The output will be the hex-encoded `validator_address`. The default `port` is 26656. + +### 6. Start the Nodes + +Finally, execute this command to start your nodes: + +```sh +./simd start +``` + +Now you have a small testnet that you can use to try out changes to the Cosmos SDK or CometBFT! + +> ⚠️ NOTE: Sometimes, creating the network through the `collect-gentxs` will fail, and validators will start in a funny state (and then panic). +> +> If this happens, you can try to create and start the network first with a single validator and then add additional validators using a `create-validator` transaction.