diff --git a/docs/localosmosis/README.md b/docs/localosmosis/README.md index 50ef9e0fd..866ed5548 100644 --- a/docs/localosmosis/README.md +++ b/docs/localosmosis/README.md @@ -4,29 +4,129 @@ sidebar_position: 1 --- # LocalOsmosis + + +## What is LocalOsmosis? + +LocalOsmosis (a fork of LocalTerra) is a complete Osmosis testnet and ecosystem containerized with Docker and orchestrated with a simple `docker-compose` file. It simplifies the way smart-contract developers test their contracts in a sandbox before they deploy them on a testnet or mainnet. + +LocalOsmosis comes preconfigured with opinionated, sensible defaults for standard testing environments. If other projects mention testing on LocalOsmosis, they are referring to the settings defined in this repo. + +LocalOsmosis has the following advantages over a public testnet: + +- Easily modifiable world states +- Quick to reset for rapid iterations +- Simple simulations of different scenarios +- Controllable validator behavior + +## Prerequisites + +- [`Docker`](https://www.docker.com/) +- [`docker-compose`](https://github.com/docker/compose) +- [`Osmosisd`](https://get.osmosis.zone) + * Select option 3 (localosmosis), the installer will configure everything for you. + * The osmosisd dameon on your local computer is used to communicate with the localosmosis daemin running inside the Docker container. +- Supported known architecture: x86_64 +- 16+ GB of RAM is recommended + ## Get started +## 1. LocalOsmosis - No Initial State + +The following commands must be executed from the root folder of the Osmosis repository. -### Clone Osmosis +1. Make any change to the osmosis code that you want to test +2. Initialize LocalOsmosis: + +```bash +make localnet-init ``` -git clone https://github.com/osmosis-labs/osmosis.git -cd osmosis + +The command: + +- Builds a local docker image with the latest changes +- Cleans the `$HOME/.osmosisd-local` folder + +3. Start LocalOsmosis: + +```bash +make localnet-start ``` -### Run LocalOsmosis +> Note +> +> You can also start LocalOsmosis in detach mode with: +> +> `make localnet-startd` +4. (optional) Add your validator wallet and 9 other preloaded wallets automatically: + +```bash +make localnet-keys ``` -make localnet-build + +- These keys are added to your `--keyring-backend test` +- If the keys are already on your keyring, you will get an `"Error: aborted"` +- Ensure you use the name of the account as listed in the table below, as well as ensure you append the `--keyring-backend test` to your txs +- Example: `osmosisd tx bank send lo-test2 osmo1cyyzpxplxdzkeea7kwsydadg87357qnahakaks --keyring-backend test --chain-id localosmosis` + +5. You can stop chain, keeping the state with + +```bash +make localnet-stop ``` -### Advanced options +6. When you are done you can clean up the environment with: + +```bash +make localnet-clean +``` + +## 2. LocalOsmosis - With Mainnet State + +Running an osmosis network with mainnet state is now as easy as setting up a stateless localnet. + +1. Set up a mainnet node and stop it at whatever height you want to fork the network at. + +2. There are now two options you can choose from: + + - **Mainnet is on version X, and you want to create a testnet on version X.** + + On version X, run: + + ```bash + osmosisd in-place-testnet localosmosis osmo12smx2wdlyttvyzvzg54y2vnqwq2qjateuf7thj + ``` + + Where the first input is the desired chain-id of the new network and the second input is the desired validator operator address (where you vote from). + The address provided above is included in the localosmosis keyring under the name 'val'. + + You now have a network you own with the mainnet state on version X. + + - **Mainnet is on version X, and you want to create a testnet on version X+1.** + + On version X, run: + + ```bash + osmosisd in-place-testnet localosmosis osmo12smx2wdlyttvyzvzg54y2vnqwq2qjateuf7thj --trigger-testnet-upgrade + ``` + + Where the first input is the desired chain-id of the new network and the second input is the desired validator operator address (where you vote from). + The address provided above is included in the localosmosis keyring under the name 'val'. + + The network will start and hit 10 blocks, at which point the upgrade will trigger and the network will halt. + + Then, on version X+1, run: + + ```bash + osmosisd start + ``` -- [Test local Osmosis core changes](./test-local-changes.md) -- [Run local Osmosis with a copy of main state](./local-osmosis-mainstate.md) +You now have a network you own with the mainnet state on version X+1. ## Accounts -LocalOsmosis is pre-configured with one validator and 9 accounts with ION and OSMO balances. +LocalOsmosis is pre-configured with one validator and 9 accounts with ION and OSMO balances. You can also manually add these keys using `make localnet-keys` | Account | Address | Mnemonic | | --------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/localosmosis/local-osmosis-mainstate.md b/docs/localosmosis/local-osmosis-mainstate.md deleted file mode 100644 index f4e7547cc..000000000 --- a/docs/localosmosis/local-osmosis-mainstate.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Run LocalOsmosis with mainnet state -sidebar_position: 3 ---- -## LocalOsmosis with Mainnet State - -Running LocalOsmosis with mainnet state is resource intensive and can take a bit of time. It is recommended to only use this method if you are testing a new feature that must be thoroughly tested before pushing to production. - -A few things to note before getting started. The below method will only work if you are using the same version as mainnet. In other words, if mainnet is on v8.0.0 and you try to do this on a v9.0.0 tag or on main, you will run into an error when initializing the genesis. (yes, it is possible to create a state exported testnet on a upcoming release, but that is out of the scope of this tutorial) - -Additionally, this process requires 64GB of RAM. If you do not have 64GB of RAM, you will get an OOM error. - -1. Set up a node on mainnet (easiest to use the [get.osmosis.zone](https://get.osmosis.zone) tool). This will be the node you use to run the state exported testnet, so ensure it has at least 64GB of RAM. - -```sh -curl -sL https://get.osmosis.zone/install > i.py && python3 i.py -``` - -2. Once the installer is done, ensure your node is hitting blocks. - -```sh -source ~/.profile -journalctl -u osmosisd.service -f -``` - -3. Stop your Osmosis daemon - -```sh -systemctl stop osmosisd.service -``` - -4. Take a state export snapshot with the following command: - -```sh -cd $HOME -osmosisd export 2> testnet_genesis.json -``` - -After a while (~15 minutes), this will create a file called `testnet_genesis.json` which is a snapshot of the current mainnet state. - -5. Copy the `testnet_genesis.json` to the localosmosis folder within the osmosis repo - -```sh -cp -r $HOME/testnet_genesis.json $HOME/osmosis/tests/localosmosis -``` - -6. Ensure you have docker and docker compose installed/running: -Docker - -```sh -sudo apt-get remove docker docker-engine docker.io -sudo apt-get update -sudo apt install docker.io -y -``` - -Docker Compose - -```sh -sudo apt install docker-compose -y -``` - -7. Compile the local:osmosis-se docker image (~15 minutes, since this process modifies the testnet genesis you provided above). You may change the exported ID to whatever you want the chain-id to be. In this example, we will use the chain-id of localosmosis. - -```sh -cd $HOME/osmosis -export ID=local -make localnet-build-state-export -``` - -8. Start the local:osmosis-se docker image - -```sh -make localnet-start-state-export -``` - -You will then go through the genesis initialization process. This will take ~15 minutes. You will then hit the first block (not block 1, but the block number after your snapshot was taken), and then you will just see a bunch of p2p error logs with some KV store logs. **This will happen for about 1 hour**, and then you will finally hit blocks at a normal pace. - -9. On your host machine, add this specific wallet which holds a large amount of osmo funds - -```sh -echo "bottom loan skill merry east cradle onion journey palm apology verb edit desert impose absurd oil bubble sweet glove shallow size build burst effort" | osmosisd keys add wallet --recover --keyring-backend test -``` - -You now are running a validator with a majority of the voting power with the same mainnet state as when you took the snapshot. - -10. On your host machine, you can now query the state export testnet like so: - -```sh -osmosisd status -``` - -11. Here is an example command to ensure complete understanding: - -```sh -osmosisd tx bank send wallet osmo1nyphwl8p5yx6fxzevjwqunsfqpcxukmtk8t60m 10000000uosmo --chain-id testing1 --keyring-backend test -``` - -12. To stop the container and remove its data: - -```sh -make localnet-remove-state-export -``` - -Note: At some point, all the validators (except yours) will get jailed at the same block due to them being offline. When this happens, it make take a little bit of time to process. Once all validators are jailed, you will continue to hit blocks as you did before. If you are only running the validator for a short period of time (< 24 hours) you will not experience this. \ No newline at end of file diff --git a/docs/localosmosis/test-local-changes.md b/docs/localosmosis/test-local-changes.md deleted file mode 100644 index ecbea2de8..000000000 --- a/docs/localosmosis/test-local-changes.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Testing Local Changes -sidebar_position: 2 ---- -## Use LocalOsmosis to Test Local Changes - -You can now quickly test your changes to Osmosis with just a few commands: - -1. Make any change to the osmosis code that you want to test - -2. From the Osmosis home folder, run `make localnet-build` - - This compiles all your changes to docker image called local:osmosis (~60 seconds) - -3. Once complete, run `make localnet-start` - - You will now be running a local network with your changes! - - The files in `tests/e2e/localosmosis/.osmosisd` that are produced - by this command can only be removed by running `make localnet-remove` - - That will reset the chain to genesis - -4. To add your validator wallet and 9 other preloaded wallets automatically, run `make localnet-keys` - - These keys are added to your --keyring-backend test - - If the keys are already on your keyring, you will get an "Error: aborted" - - Ensure you use the name of the account as listed in the table below, as well as ensure you append the `--keyring-backend test` to your txs - - Example: `osmosisd tx bank send lo-test2 osmo1cyyzpxplxdzkeea7kwsydadg87357qnahakaks --keyring-backend test --chain-id localosmosis` - -5. To remove all block history and start from scratch, run `make localnet-remove` - -6. To stop the chain but keep the state, run `make localnet-stop` \ No newline at end of file diff --git a/src/sections.js b/src/sections.js index a965f6006..d4517cf1c 100644 --- a/src/sections.js +++ b/src/sections.js @@ -27,18 +27,6 @@ const SECTIONS = [ icon: OsmosisCore, section: 'core-sdk', }, - { - name: 'Local Osmosis', - id: 'localosmosis', - icon: LocalOsmosis, - section: 'core-sdk', - }, - { - name: 'Networks', - id: 'networks', - icon: Network, - section: 'core-sdk', - }, //Cosmwasm { name: 'Cosmwasm',