Fix silly nodes report bug

src/hz.erl

@@ -9,7 +9,7 @@
 %%%
 %%% The get/set admin functions are for setting or checking things like the Gajumaru
 %%% "network ID" and list of addresses of nodes you want to use for answering
-%%% queries to the blockchain.
+%%% queries to the blockchain. Get functions are arity 0, and set functions are arity 1.
 %%%
 %%% The JSON query interface functions are the blockchain query functions themselves
 %%% which are translated to network queries and return Erlang messages as responses.
@@ -18,8 +18,8 @@
 %%% a desired call to a smart contract on the chain to call data serialized in a form
 %%% that a Gajumaru compatible wallet or library can sign and submit to a Gajumaru node.
 %%%
-%%% This module does not implement the OTP application behavior.
-%%% helper functions.
+%%% NOTE:
+%%% This module does not implement the OTP application behavior. Refer to hakuzaru.erl.
 %%% @end
 
 -module(hz).
@@ -225,7 +225,7 @@
          NetworkID :: string(),
          Reason    :: term().
 %% @doc
-%% Returns the network ID or the atom `none' if it is unset.
+%% Returns the network ID or the atom `none' if unavailable.
 %% Checking this is not normally necessary, but if network ID assignment is dynamic
 %% in your system it may be necessary to call this before attempting to form
 %% call data or perform other actions on chain that require a signature.
@@ -241,7 +241,9 @@ network_id() ->
 %% @doc
 %% Returns the list of currently assigned nodes.
 %% The normal reason to call this is in preparation for altering the nodes list or
-%% checking the current list in debugging.
+%% checking the current list in debugging. Note that the first node in the list is
+%% the "sticky" node: the one that will be used for submitting transactions and
+%% querying `next_nonce'.
 
 chain_nodes() ->
     hz_man:chain_nodes().
@@ -251,19 +253,26 @@ chain_nodes() ->
     when List   :: [chain_node()],
          Reason :: {invalid, [term()]}.
 %% @doc
-%% Sets the nodes that are intended to be used as your interface to the peer
-%% network. The common situation is that your project runs a non-mining node as
-%% part of your backend infrastructure. Typically one or two nodes is plenty, but
-%% this may need to expand depending on how much query load your application generates.
-%% The Hakuzaru manager will load balance by round-robin distribution.
+%% Sets the chain nodes that will be queried whenever you communicate with the chain.
 %%
-%% NOTE: When load balancing in this way be aware that there can be race conditions
-%% among the backend nodes with regard to a single account's current nonce when performing
-%% contract calls in quick succession. Round robin distribution is extremely useful when
-%% performing rapid lookups to the chain, but does not work well when submitting many
-%% transactions to the chain from a single user in a short period of time. A future version
-%% of this library will allow the caller to designate a single node as "sticky" to be used
-%% exclusively in the case of nonce reads and TX submissions.
+%% The common situation is that a project runs a non-mining node as part of the backend
+%% infrastructure. Typically one or two nodes is plenty, but this may need to expand
+%% depending on how much query load your application generates.
+%%
+%% There are two situations: one node, or multiple nodes.
+%%
+%% Single node:
+%% In the case of a single node, everything passes through that one node. Duh.
+%%
+%% Multiple nodes:
+%% In the case of multiple nodes a distinction is made between the node to which
+%% transactions that update the chain state are made and to which `next_nonce' queries
+%% are made, and nodes that are used for read-only queries. The node to which stateful
+%% transactions are submitted is called the "sticky node". This is the first node
+%% (head position) in the list of nodes submitted to the chain when `chain_nodes/1'
+%% is called. If using multiple nodes but the sticky node should also be used for
+%% read-only queries, submit the sticky node at the head of the list and again in
+%% the tail.
 
 chain_nodes(List) when is_list(List) ->
     hz_man:chain_nodes(List).
@@ -271,7 +280,16 @@ chain_nodes(List) when is_list(List) ->
 
 -spec tls() -> boolean().
 %% @doc
-%% Check whether TLS is in use.
+%% Check whether TLS is in use. The typical situation is to not use TLS as nodes that
+%% serve as part of the backend of an application are typically run in the same
+%% backend network as the application service. When accessing chain nodes over the WAN
+%% however, TLS is strongly recommended to avoid a MITM attack.
+%%
+%% In this version of Hakuzaru TLS is either on or off for all nodes, making a mixed
+%% infrastructure complicated to support without two Hakuzaru instances. This will
+%% likely become a per-node setting in the future.
+%%
+%% TLS defaults to `false'.
 
 tls() ->
     hz_man:tls().
@@ -281,6 +299,8 @@ tls() ->
 %% @doc
 %% Set TLS true or false. That's what a boolean is, by the way, `true' or `false'.
 %% This is a condescending comment. That means I am talking down to you.
+%%
+%% TLS defaults to `false'.
 
 tls(Boolean) ->
     hz_man:tls(Boolean).
@@ -291,6 +311,8 @@ tls(Boolean) ->
     when Timeout :: pos_integer() | infinity.
 %% @doc
 %% Returns the current request timeout setting in milliseconds.
+%% The default timeout is 5,000ms.
+%% The max timeout is 120,000ms.
 
 timeout() ->
     hz_man:timeout().
@@ -300,6 +322,8 @@ timeout() ->
     when MS :: pos_integer() | infinity.
 %% @doc
 %% Sets the request timeout in milliseconds.
+%% The default timeout is 5,000ms.
+%% The max timeout is 120,000ms.
 
 timeout(MS) ->
     hz_man:timeout(MS).
@@ -576,18 +600,18 @@ acc_pending_txs(AccountID) ->
 %% Retrieve the next nonce for the given account
 
 next_nonce(AccountID) ->
-%   case request(["/v3/accounts/", AccountID, "/next-nonce"]) of
-%       {ok, #{"next_nonce" := Nonce}}           -> {ok, Nonce};
-%       {ok, #{"reason" := "Account not found"}} -> {ok, 1};
-%       {ok, #{"reason" := Reason}}              -> {error, Reason};
-%       Error                                    -> Error
-%   end.
-    case request_sticky(["/v3/accounts/", AccountID]) of
-        {ok, #{"nonce"  := Nonce}}               -> {ok, Nonce + 1};
+    case request_sticky(["/v3/accounts/", AccountID, "/next-nonce"]) of
+        {ok, #{"next_nonce" := Nonce}}           -> {ok, Nonce};
         {ok, #{"reason" := "Account not found"}} -> {ok, 1};
         {ok, #{"reason" := Reason}}              -> {error, Reason};
         Error                                    -> Error
     end.
+%   case request_sticky(["/v3/accounts/", AccountID]) of
+%       {ok, #{"nonce"  := Nonce}}               -> {ok, Nonce + 1};
+%       {ok, #{"reason" := "Account not found"}} -> {ok, 1};
+%       {ok, #{"reason" := Reason}}              -> {error, Reason};
+%       Error                                    -> Error
+%   end.
 
 
 -spec dry_run(TX) -> {ok, Result} | {error, Reason}