From 420e73ce9f675553a3ff87ba9b58d0e4ae6f3021 Mon Sep 17 00:00:00 2001
From: likhita-809 <78951027+likhita-809@users.noreply.github.com>
Date: Wed, 19 May 2021 20:12:18 +0530
Subject: [PATCH] add cosmovisor docs on Auto-Download (#9358)

---
 docs/run-node/cosmovisor.md | 46 +++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/run-node/cosmovisor.md b/docs/run-node/cosmovisor.md
index 99cb81e0c..6e3b71e34 100644
--- a/docs/run-node/cosmovisor.md
+++ b/docs/run-node/cosmovisor.md
@@ -80,6 +80,52 @@ for those who wish to sync a fullnode from start.
 The `DAEMON` specific code and operations (e.g. tendermint config, the application db, syncing blocks, etc) are performed as normal.
 Application binaries' directives such as command-line flags and environment variables work normally.
 
+## Auto-Download
+
+Generally, the system requires that the system administrator place all relevant binaries
+on the disk before the upgrade happens. However, for people who don't need such
+control and want an easier setup (maybe they are syncing a non-validating fullnode
+and want to  do little maintenance), there is another option.
+
+If you set `DAEMON_ALLOW_DOWNLOAD_BINARIES=on` then when an upgrade is triggered and no local binary
+can be found, the `cosmovisor` will attempt to download and install the binary itself.
+The plan stored in the upgrade module has an info field for arbitrary json.
+This info is expected to be outputed on the halt log message. There are two
+valid format to specify a download in such a message:
+
+1. Store an os/architecture -> binary URI map in the upgrade plan info field
+as JSON under the `"binaries"` key, eg:
+```json
+{
+  "binaries": {
+    "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
+  }
+}
+```
+2. Store a link to a file that contains all information in the above format (eg. if you want
+to specify lots of binaries, changelog info, etc without filling up the blockchain).
+
+e.g `https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e`
+
+This file contained in link will be retrieved by [go-getter](https://github.com/hashicorp/go-getter) 
+and the "binaries" field will be parsed as above.
+
+If there is no local binary, `DAEMON_ALLOW_DOWNLOAD_BINARIES=on`, and we can access a canonical url for the new binary,
+then the `cosmovisor` will download it with [go-getter](https://github.com/hashicorp/go-getter) and
+unpack it into the `upgrades/<name>` folder to be run as if we installed it manually
+
+Note that for this mechanism to provide strong security guarantees, all URLS should include a
+sha{256,512} checksum. This ensures that no false binary is run, even if someone hacks the server
+or hijacks the dns. go-getter will always ensure the downloaded file matches the checksum if it
+is provided. And also handles unpacking archives into directories (so these download links should be
+a zip of all data in the bin directory).
+
+To properly create a checksum on linux, you can use the `sha256sum` utility. eg. 
+`sha256sum ./testdata/repo/zip_directory/autod.zip`
+which should return `29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7`.
+You can also use `sha512sum` if you like longer hashes, or `md5sum` if you like to use broken hashes.
+Make sure to set the hash algorithm properly in the checksum argument to the url.
+
 ## Example: simd
 
 The following instructions provide a demonstration of `cosmovisor`'s integration with the `simd` application