From aaf79ad6431b3926ab4b74fb8997e29b6d6c2cec Mon Sep 17 00:00:00 2001
From: Igor Artamonov <igor@artamonov.ru>
Date: Wed, 27 May 2020 15:50:51 -0400
Subject: [PATCH] solution: make more clear how to setup round-robin rel: #7

---
 README.adoc                       |  6 ++++
 docs/02-quick-start.adoc          | 23 +++++++++++----
 docs/reference-configuration.adoc | 48 +++++++++++++++++--------------
 3 files changed, 50 insertions(+), 27 deletions(-)

diff --git a/README.adoc b/README.adoc
index 354611e4..6b7eb86a 100644
--- a/README.adoc
+++ b/README.adoc
@@ -103,6 +103,12 @@ Which sets the following:
 - for Bitcoin Mainet only JSON RPC is used
 - `${INFURA_USER}` will be provided through environment variable
 
+Please note that you can configure many upstreams for a single blockchains.
+If there is more that one upstream, then Dshackle makes requests to them with Round Robin Load Balancing.
+If one of them goes down, Dshackle continues to use only active nodes.
+
+I.e. you can set up a node in the local network, and the Infura, and if anything happened to you local node, you'll still be able to have access to a consistent state of the Ethereum blockchain.
+
 
 link:docs[See full documentations].
 
diff --git a/docs/02-quick-start.adoc b/docs/02-quick-start.adoc
index a022f1bf..d41639c4 100644
--- a/docs/02-quick-start.adoc
+++ b/docs/02-quick-start.adoc
@@ -36,16 +36,24 @@ cluster:
       connection:
         ethereum:
           rpc: # <6>
-            url: "https://mainnet.infura.io/v3/${INFURA_USER}" <7>
+            url: "https://mainnet.infura.io/v3/${INFURA_USER}" # <7>
           ws: # <8>
             url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}"
+    - id: local-eth # <9>
+      chain: ethereum
+      connection:
+        ethereum:
+          rpc:
+            url: "http://192.168.1.100:8545/" # <10>
+          ws:
+            url: "ws://192.168.1.100:8546"
     - id: bitcoin-main
-      chain: bitcoin # <9>
+      chain: bitcoin # <11>
       connection:
         bitcoin:
           rpc:
             url: "http://localhost:8332"
-            basic-auth: # <10>
+            basic-auth: # <12>
               username: bitcoin
               password: test
 ----
@@ -56,9 +64,14 @@ cluster:
 <5> one for Ethereum Mainnet, using
 <6> HTTP and
 <7> `${INFURA_USER}` value is provided through environment variable
-<8> Websocket conection
-<9> and another for Bitcoin <10> with Basic Auth for bitcoin node connection
+<8> in addition to HTTPS is uses Websocket protocol to connect to Infura, used to subscribe to updates
+<9> setup another upstream for Ethereum Mainnet
+<10> which connects to a node in the internal networks, without any authentication at this case
+<11> and another for Bitcoin
+<12> with Basic Auth for bitcoin node connection
 
+The configuration above sets up the Dshackle to provide a fault-tolerant access to Bitcoin and Ethereum blockchain.
+And for Ethereum, at this particular example, it uses a Round Robin Load Balancing over the Infura and the local node.
 
 See detailed link:reference-configuration.adoc[Configuration Reference]
 
diff --git a/docs/reference-configuration.adoc b/docs/reference-configuration.adoc
index 1e9d485f..01fa3af5 100644
--- a/docs/reference-configuration.adoc
+++ b/docs/reference-configuration.adoc
@@ -286,7 +286,7 @@ cache:
 [#cluster]
 == Cluster
 
-The cluster config is the main part that defines all connection to nodes and other servers
+The cluster config is the main part, that defines all connection to nodes and other servers
 
 [source,yaml]
 ----
@@ -334,25 +334,25 @@ configuration, and may be omitted for most of the situations.
 
 [source,yaml]
 ----
-    - id: local
-      chain: ethereum
-      labels:
-        fullnode: true
-      methods:
-        enabled:
-          - name: "parity_trace"
-        disabled:
-          - name: "admin_shutdown"
-      connection:
-        ethereum:
-          rpc:
-            url: "http://localhost:8545"
-          ws:
-            url: "ws://localhost:8546"
-            origin: "http://localhost"
-            basic-auth:
-              username: 9c199ad8f281f20154fc258fe41a6814
-              password: 258fe4149c199ad8f2811a68f20154fc
+- id: local
+  chain: ethereum
+  labels:
+    fullnode: true
+  methods:
+    enabled:
+      - name: "parity_trace"
+    disabled:
+      - name: "admin_shutdown"
+  connection:
+    ethereum:
+      rpc:
+        url: "http://localhost:8545"
+      ws:
+        url: "ws://localhost:8546"
+        origin: "http://localhost"
+        basic-auth:
+          username: 9c199ad8f281f20154fc258fe41a6814
+          password: 258fe4149c199ad8f2811a68f20154fc
 ----
 
 .Main Config
@@ -366,11 +366,15 @@ configuration, and may be omitted for most of the situations.
 
 | `chain`
 | yes
-| Blockchain which is the provided by the upstream. `bitcoin`, `bitcoin-testnet`, `ethereum`, `ethereum-classic`, or `kovan`
+| Blockchain which is the provided by the upstream.
+Cluster may have multiple upstreams for a single blockchain.
+Accepted types: `bitcoin`, `bitcoin-testnet`, `ethereum`, `ethereum-classic`, or `kovan`
 
 | `labels`
 | no
-| Key-Value pairs that are assigned to the upstream. Used to select an upstream per-request. See link:08-quorum-and-selectors.adoc[Quorum and Selectors]
+| Key-Value pairs that are assigned to the upstream.
+Used to select an upstream per-request.
+See link:08-quorum-and-selectors.adoc[Quorum and Selectors]
 
 | `methods`
 | no