From c8de5f21973fa2ea8c65a08fd86ea6fe7c4c7fd7 Mon Sep 17 00:00:00 2001
From: deif <deif@pm.me>
Date: Mon, 1 May 2023 21:34:40 +0100
Subject: [PATCH] Add docker quickstart section for systems that can't use
 `wasmd` locally

---
 src/SUMMARY.md                               |   1 +
 src/wasmd-quick-start/running-docker.md      | 123 +++++++++++++++++++
 src/wasmd-quick-start/testned-interaction.md |  51 +++++++-
 3 files changed, 174 insertions(+), 1 deletion(-)
 create mode 100644 src/wasmd-quick-start/running-docker.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index da3ae55..5c5f591 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -8,6 +8,7 @@
 - [Quick start with wasmd](wasmd-quick-start.md)
   - [Testnet setup](wasmd-quick-start/testnet.md)
   - [Preparing account](wasmd-quick-start/preparing-account.md)
+  - [Running Docker](wasmd-quick-start/running-docker.md)
   - [Interaction with testnet](wasmd-quick-start/testned-interaction.md)
 
 # Smart contracts
diff --git a/src/wasmd-quick-start/running-docker.md b/src/wasmd-quick-start/running-docker.md
new file mode 100644
index 0000000..40aea3e
--- /dev/null
+++ b/src/wasmd-quick-start/running-docker.md
@@ -0,0 +1,123 @@
+# Running Docker
+
+If you are using a Windows machine, or have an M1 chip then it's best to use
+the Docker images that are provided. This section is a quick guide on working with
+`wasmd` through docker to test your smart contracts on the blockchain. If you are
+running `wasmd` locally or only want to develop contracts and test them with the
+UT environment, feel free to skip this section.
+
+If you have never heard of [docker](https://www.docker.com/), it is a way to
+ensure applications that have been prepared for specific systems and environments
+can be used easily by others no matter what system they might have themselves.
+After installing docker you can grab the latest image of `wasmd`:
+
+```bash
+$ docker image pull cosmwasm/wasmd:latest
+```
+
+Now you have the docker image you can initialize your own local testnet by setting
+up a validator:
+
+```
+$ docker run --rm -it -e PASSWORD=xxxxxxxx \
+  --mount type=volume,source=wasmd_client,target=/root \
+  cosmwasm/wasmd:latest /opt/setup_wasmd.sh
+```
+
+The `PASSWORD` parameter is setting an env variable for later use that you'll 
+need to enter every time a tx needs signing. The output of the above command 
+will give you the address that you'll add as a validator to our testnet, along 
+with its mnemonic. Save the details of these so you can use them for querying 
+later. The output will look something like the following:
+
+```
+- name: validator
+  type: local
+  address: wasm1u0grxl65reu6spujnf20ngcpz3jvjfsp5rs7lkavud3rhppnyhmqqnkcx6
+  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8pamTZH8x8+8UAFjndrvU4x7foJbCvcz78buyQ8q7+k"}'
+```
+
+The command also created a new volume called `wasmd_client`. This is the saved 
+state of our container that can be run at any time so that you can interact with 
+the local testnet. Now let's create a new container that will set our above 
+address as a genesis validator:
+
+```
+$ docker run --rm -it \
+  --mount type=volume,source=wasmd_data,target=/root \
+  cosmwasm/wasmd:latest /opt/setup_wasmd.sh wasm1u0grxl65reu6spujnf20ngcpz3jvjfsp5rs7lkavud3rhppnyhmqqnkcx6
+```
+
+A new volume that contains the blockchain state was created called `wasmd_data`.
+To start up the blockchain and servers, invoke:
+
+```
+$ docker run --rm -it -p 26657:26657 -p 26656:26656 -p 1317:1317 \
+  --mount type=volume,source=wasmd_data,target=/root \
+  cosmwasm/wasmd:latest /opt/run_wasmd.sh
+```
+
+From now on, if you ever need to access this blockchain and carry on from where
+you left off, run the above command. After executing the command, the terminal 
+will output the logs of all new blocks being produced. In a separate terminal 
+window you can interact with this testnet.
+
+```
+$ docker run --rm -it \
+  --mount type=volume,source=wasmd_client,target=/root \
+  --network=host \
+  cosmwasm/wasmd:latest wasmd \
+  query bank balances wasm1u0grxl65reu6spujnf20ngcpz3jvjfsp5rs7lkavud3rhppnyhmqqnkcx6
+
+...
+balances:
+- amount: "1000000000"
+  denom: ucosm
+- amount: "750000000"
+  denom: ustake
+pagination:
+  next_key: null
+  total: "0"
+...
+```
+
+To create a new wallet, simply invoke:
+
+```
+$ docker run --rm -it \
+  --mount type=volume,source=wasmd_client,target=/root \
+  --network=host \
+  cosmwasm/wasmd:latest wasmd \
+  keys add wallet
+
+...
+- name: wallet
+  type: local
+  address: wasm1wukxp2kldxae36rgjz28umqtq792twtxdfe6ux
+  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8pamTZH8x8+8UAFjndrvU4x7foJbCvcz78buyQ8q7+k"}'
+  mnemonic: ""
+...
+```
+
+If you want to transfer some funds to the new wallet you can send some from your 
+validator address:
+
+```
+$ docker run --rm -it \
+  --mount type=volume,source=wasmd_client,target=/root \
+  --network=host cosmwasm/wasmd:latest wasmd \
+  tx bank send validator wasm1wukxp2kldxae36rgjz28umqtq792twtxdfe6ux 1000000ucosm
+```
+
+This will send 1,000,000 ucosm to the new wallet you created.
+
+In the next section when you will upload a smart contract and interact with it, 
+ensure that all your `wasmd` commands are prepended with your docker container
+command:
+
+```
+$ docker run --rm -it \
+  --mount type=bind,src="$(pwd)",target=/code \ 
+  --mount type=volume,source=wasmd_client,target=/root \
+  --network=host cosmwasm/wasmd:latest wasmd
+```
diff --git a/src/wasmd-quick-start/testned-interaction.md b/src/wasmd-quick-start/testned-interaction.md
index aba1ce5..9a7e3b6 100644
--- a/src/wasmd-quick-start/testned-interaction.md
+++ b/src/wasmd-quick-start/testned-interaction.md
@@ -13,10 +13,20 @@ $ git clone git@github.com:CosmWasm/cw-plus.git
 Now go to cloned repo and run Rust optimizer on it:
 
 ```
+$ cd cw-plus
 $ docker run --rm -v "$(pwd)":/code \
   --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \
   --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
-  cosmwasm/workspace-optimizer:0.12.6
+  cosmwasm/workspace-optimizer:0.12.13
+```
+
+N.B. If you are working in Windows Powershell, the equivalent command is:
+
+```
+$ docker run --rm -v "$(pwd)":/code \
+  --mount type=volume,source="$((Get-Item "$(pwd)").basename)_cache",target=/code/target \
+  --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
+  cosmwasm/workspace-optimizer:0.12.13
 ```
 
 After a couple of minutes - it can take some for the first time - you should
@@ -157,3 +167,42 @@ to be able to play with your simple contracts. We would focus on testing them
 locally, but if you want to check in real life, you have some basics now.
 We will take a closer look at `wasmd` later when we would talk about the
 architecture of the actor model defining communication between smart contracts.
+
+## Troubleshooting Common Issues
+
+### Error: unsupported return type block; supported types: sync, async
+
+When using the `store` command, use `-b sync` instead of `-b block`. Block is 
+deprecated in 0.40.
+
+The resulting logs will not have the relevant tx details so after that you will 
+need to copy the `txhash` result and use the command:
+
+```bash
+$ wasmd query tx TXHASH
+```
+
+### Error: open ./artifacts/cw4_group.wasm: no such file or directory
+
+Check that your terminal is in the correct working directory. If you are using a 
+docker container then you should use the mount path instead 
+`/code/artifacts/cw4_group.wasm`.
+
+### Out of gas in location
+
+Increase the reserved gas space by adding `--gas 2000000` to the end of your 
+command.
+
+### Error: payload msg: invalid
+
+Check the JSON string passed is actually valid. If using Windows Powershell you 
+will need to escape the double quotes (i.e. `'{ \"admins\": \"wasm...\" }')`).
+
+### Contract state did not update
+
+Check the logs of the transaction for hints of the error by querying the 
+txhash of the tx that was supposed to update the state:
+
+```bash
+$ wasmd query tx TXHASH
+```
\ No newline at end of file