solution: make more clear how to setup round-robin

rel: #7

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].
 

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
+<8> in addition to HTTPS is uses Websocket protocol to connect to Infura, used to subscribe to updates
-<9> and another for Bitcoin <10> with Basic Auth for bitcoin node connection
+<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]
 

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]
 ----
@@ -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