Doc formatting adjustments

Reviewed-on: #31

.gitignore

@@ -8,9 +8,9 @@ cancer
 erl_crash.dump
 ebin/*.beam
 doc/*.html
-doc/*.css
-doc/edoc-info
 doc/erlang.png
+doc/stylesheet.css
+doc/edoc-info
 rel/example_project
 .concrete/DEV_MODE
 .rebar

doc/custom/stylesheet.css

@@ -0,0 +1,75 @@
+/* standard EDoc style sheet */
+body {
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    margin-left: .25in;
+    margin-right: .2in;
+    margin-top: 0.2in;
+    margin-bottom: 0.2in;
+    color: #696969;
+    background-color: #ffffff;
+}
+a:link{
+    color: #000000;
+}
+a:visited{
+    color: #000000;
+}
+a:hover{
+    color: #d8613c;
+}
+h1,h2 {
+ 	margin-left: -0.2in;
+}
+div.navbar {
+	background-color: #000000;
+	padding: 0.2em;
+}
+h2.indextitle {
+	padding: 0.4em;
+    color: #dfdfdf;
+	background-color: #000000;
+}
+div.navbar a:link {
+    color: #dfdfdf;
+}
+div.navbar a:visited {
+    color: #dfdfdf;
+}
+div.navbar a:hover {
+    color: #d8613c;
+}
+h3.function,h3.typedecl {
+	background-color: #000000;
+    color: #dfdfdf;
+ 	padding-left: 1em;
+}
+div.spec {
+ 	margin-left: 2em;
+	background-color: #eeeeee;
+}
+a.module {
+	text-decoration:none
+}
+a.module:hover {
+	background-color: #eeeeee;
+}
+ul.definitions {
+	list-style-type: none;
+}
+ul.index {
+	list-style-type: none;
+	background-color: #eeeeee;
+}
+
+/*
+ * Minor style tweaks
+ */
+ul {
+	list-style-type: square;
+}
+table {
+	border-collapse: collapse;
+}
+td {
+	padding: 3
+}

doc/overview.edoc

@@ -1,77 +1,80 @@
-@author Craig Everett <ceverett@zxq9.com> [https://gitlab.com/zxq9/zj]
-@version 0.3.0
-@title Vanillae: Aeternity blockchain bindings for Erlang
+@author Craig Everett <craigeverett@qpq.swiss> [https://zxq9.com]
+@author Jarvis Carrol <jarviscarrol@qpq.swiss> [https://jarviscarroll.net/]
+@version 0.9.2
+@title Hakuzaru: Gajumaru blockchain bindings for Erlang
 
 @doc
-This Erlang application provides bindings for the Erlang blockchain.
-The primary goal is for usage to be easy to understand and as simple as possible to use.
-The secondary goal is to enable real-world projects to more easily connect with the blockchain in an obvious way and provide a clear path for them to provide feedback regarding areas that are difficult to understand, functionality that is lacking, and explain their use cases to us so we can more easily provide needed features and usage examples to make adoption easier.
+This Erlang application provides bindings for the Gajumaru blockchain and basic utilities for manipulating Gajumaru-related data.
 
-== Basic operation ==
-All external interfaces expected to be used by authors of programs that use Vanillae are built into the `vanillae' module.
+== To Start or Not To Start ==
+Starting the `hakuzaru' application is only required if you need to query the chain.
 
-When Vanillae is started as an application a named process called `vanillae_man' is spawned that manages interactions with and the state of the service, as well as a simple-one-for-one supervisor that manages the lifecycle of Vanillae workers (defined in `vanillae_fetcher').
+The application can be started via a call to `application', or with an explicit call to `hz:start()'.
 
-After startup `vanillae_man' must be given the address and port of a list of Aeternity nodes that are available to service requests. Note that the service nodes will need to have the "dry run" endpoint enabled and the internal service query port made available in order to provide "dry run" and mempool TX submission functionality.
+Hakuzaru can also be run as a local application from the shell by invoking it with `zxh run hakuzaru' if you have `zx' installed.
 
-The `vanillae_man' will round-robin requests to however many Aeternity nodes are provided in its configuration. Note that this congiruation is dynamic and can be changed completely at runtime.
+== Operation ==
+All blockchain-specific operations are accessible from the main interface modulle: `hz'
 
-== Functions ==
-The `vanillae' module exposes one function per blockchain feature provided. Most of these are actually wrappers for blockchain endpoint functions, others provide functionality specific to accomplishing a local processing task related to chain data.
+When Hakuzaru is started as an application a named process called `hz_man' is spawned that manages interactions with chain nodes, as well as a simple-one-for-one supervisor that manages the lifecycle of workers (defined in `hz_fetcher').
 
-== Initialization ==
-When Vanillae is first started the vanillae_man is started but does not yet know what Aeternity nodes to use to service queries. You will need to provide it with at least one node and port where it can make Aeternity endpoint calls.
+After startup `hz_man' must be given the address and port of a list of Gajumaru nodes that are available to service requests.
+Note that the service nodes will need to have the dry-run endpoint enabled and the internal service query port made available in order to provide dry-runs and transaction submission.
 
-Note that if you will need to make read-only calls to contracts that are deployed on chain (to queery their state or perform specific read-only operations provided by the contract) the backend nodes you configure will need to be configured with "dry-run" enabled.
+When configuring chain nodes a list of nodes should be provided.
+To avoid sync issues in the case of fast transaction formation/submission to the chain, only one node from the list of chain nodes is used for submitting transactions and querying `next_nonce/1'.
+This node is called "the sticky node".
 
-Example of a shell session where vanillae is started and initialized manually with an AE node in the local network at 192.168.10.10:3013:
+The first node in the list of chain nodes provided during configuration is designated as the sticky node.
+If you also want to use the sticky node as a query endpoint, include it twice in the list.
+
+The `hz_man' will round-robin requests to however many additional Gajumaru nodes are provided in the configuration.
+Note that this configuration is dynamic and can be changed at runtime, so your service can adapt to node availability on the fly if needed.
 
 ```
-1> vanillae:start().     
-Starting.
+ceverett@steak:~$ zxh run hakuzaru
+Erlang/OTP 27 [erts-15.2] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns]
+
+Eshell V15.2 (press Ctrl+G to abort, type help(). for help)
+Fetching otpr-hakuzaru-0.8.0
+[100.00%]
+Recompile: src/hz_sup
+Recompile: src/hz_man
+Recompile: src/hz_key_master
+Recompile: src/hz_grids
+Recompile: src/hz_format
+Recompile: src/hz_fetcher
+Recompile: src/hz
+Recompile: src/hakuzaru
+Starting otpr-hakuzaru-0.8.0.
+hz_man starting.
+Started [hakuzaru]
+1> hz:chain_nodes([{"groot.testnet.gajumaru.io", 3013}]).
 ok
-2> vanillae:status().
-{error,no_nodes}
-3> vanillae:ae_nodes([{"192.168.7.7", 3013}]).
-ok
-4> vanillae:status().                         
-{ok,#{"difficulty" => 59729882,
+2> hz:status().
+{ok,#{"difficulty" => 2877405482,
+      "finalized" =>
+          #{"hash" =>
+                "kh_PDSn6Xru5JVdpJfdDCNpfsL8gUZvvjyhTYuzgndoy98G5oLLR",
+            "height" => 277454,"type" => "height"},
       "genesis_key_block_hash" =>
-          "kh_wUCideEB8aDtUaiHCtKcfywU6oHZW6gnyci8Mw6S1RSTCnCRu",
-      "listening" => true,"network_id" => "ae_uat",
+          "kh_Qdi5MTuuhJm7xzn5JUAbYG12cX3qoLMnXrBxPGzBkMWJ4K8vq",
+      "hashrate" => 864394,"listening" => true,
+      "network_id" => "groot.testnet",
       "node_revision" =>
-          "3a08153c635c53d92029a617f2e784731ba367c6",
-      "node_version" => "6.7.0",
-      "peer_connections" => #{"inbound" => 25,"outbound" => 10},
-      "peer_count" => 50,
+          "7b3cc1db3bb36053023167b86f7d6f2d5dcbd01d",
+      "node_version" => "0.1.0+203.7b3cc1db3",
+      "peer_connections" => #{"inbound" => 1,"outbound" => 3},
+      "peer_count" => 5,
       "peer_pubkey" =>
-          "pp_fCBqobeSwhdnrzC8DoSsmWbf2GzDK61CJujmsCEd3RUkmh9Ny",
-      "pending_transactions_count" => 2,
+          "pp_2nQHucGyEt5wkYruNuRkg19cbZuEeyR9BZfvtv49F3AoyNSYMT",
+      "pending_transactions_count" => 0,
       "protocols" =>
-          [#{"effective_at_height" => 425900,"version" => 5},
-           #{"effective_at_height" => 154300,"version" => 4},
-           #{"effective_at_height" => 82900,"version" => 3},
-           #{"effective_at_height" => 40900,"version" => 2},
-           #{"effective_at_height" => 0,"version" => 1}],
+          [#{"effective_at_height" => 0,"version" => 1}],
       "solutions" => 0,"sync_progress" => 100.0,
-      "syncing" => false,"top_block_height" => 802644,
+      "syncing" => false,"top_block_height" => 277555,
+      "top_hash" =>
+          "kh_2vuNc8eG77aTmHcQDcievjKufFwR4MSSuZbEMWwW5TqUzSQy71",
       "top_key_block_hash" =>
-          "kh_28LZSvHZPCGqeWsMsqtSjxQjQHKW1pHzoBex97oMT7U2HcLPgV"}}
-'''
-
-Alternatively, here is a start function for an application using Vanillae that initializes vanillae_man with a list of nodes provided by a configuration file:
-
-```
-start(normal, _Args) ->
-    ok = application:ensure_started(sasl),
-    {ok, Started} = application:ensure_all_started(cowboy),
-    ok = application:ensure_started(vanillae),
-    Nodes = proplists:get_value(ae_nodes, read_config(), []),
-    ok = vanillae:ae_nodes(Nodes),
-    ok = log(info, "Started: ~p~n", [[vanillae | Started]]),
-    Routes = [{'_', [{"/", count_top, []}]}],
-    Dispatch = cowboy_router:compile(Routes),
-    Env = #{env => #{dispatch => Dispatch}},
-    {ok, _} = cowboy:start_clear(count_listener, [{port, 8080}], Env),
-    count_sup:start_link().
+          "kh_2vuNc8eG77aTmHcQDcievjKufFwR4MSSuZbEMWwW5TqUzSQy71"}}
 '''

ebin/hakuzaru.app

@@ -3,7 +3,7 @@
               {included_applications,[]},
               {applications,[stdlib,kernel]},
               {description,"Gajumaru interoperation library"},
-              {vsn,"0.7.0"},
-              {modules,[hakuzaru,hz,hz_fetcher,hz_grids,hz_key_master,hz_man,
-                        hz_sup]},
+              {vsn,"0.9.2"},
+              {modules,[hakuzaru,hz,hz_aaci,hz_fetcher,hz_format,hz_grids,
+                        hz_key_master,hz_man,hz_sophia,hz_sup]},
               {mod,{hakuzaru,[]}}]}.

src/hakuzaru.erl

@@ -6,7 +6,7 @@
 %%% @end
 
 -module(hakuzaru).
--vsn("0.7.0").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").

src/hz_fetcher.erl

@@ -1,5 +1,13 @@
+%%% @private
+%%% Hakuzaru Request Fetcher
+%%%
+%%% This module defines the request workers.
+%%% Each request to a remote chain node is handled by a worker that is spawned
+%%% to handle it and terminates on completion.
+%%% @end
+
 -module(hz_fetcher).
--vsn("0.7.0").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("MIT").

src/hz_format.erl

@@ -21,7 +21,7 @@
 %%% @end
 
 -module(hz_format).
--vsn("0.7.0").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -50,7 +50,7 @@
 %%   hz_format:amount(500000123000000000000000) ->
 %%   木500,000.123
 %% '''
-%% @equiv amount(us, Pucks).
+%% @equiv amount(us, Pucks)
 
 amount(Pucks) ->
     amount(us, Pucks).
@@ -83,7 +83,7 @@ amount(Pucks) ->
 %%   hz_format:amount({$_, 4}, 100500040123000000000000000) ->
 %%   木1_0050_0040.123
 %% '''
-%% @equiv amount(gaju, Style, Pucks).
+%% @equiv amount(gaju, Style, Pucks)
     
 amount(Style, Pucks) ->
     amount(gaju, Style, Pucks).
@@ -147,10 +147,9 @@ amount(puck, {Separator, Span}, Pucks) ->
          Serialized :: string().
 %% A formatter for decimal notation which permits a precision
 %% value to be applied to the puck side of the format.
-%% @equiv approx_amount(us, Precision, Pucks).
 %% ```
 %%   hz_format:approx_amount(3, 100500040123000004500000001) ->
-%%   木100,500,040.123...
+%%   木100,500,040.123
 %%
 %%   hz_format:approx_amount(13, 100500040123000004500000001) ->
 %%   木100,500,040.123,000,004,5...
@@ -158,6 +157,7 @@ amount(puck, {Separator, Span}, Pucks) ->
 %%   hz_format:approx_amount(all, 100500040123000004500000001) ->
 %%   木100,500,040.123,000,004,500,000,001
 %% '''
+%% @equiv approx_amount(us, Precision, Pucks)
 
 approx_amount(Precision, Pucks) ->
     approx_amount(us, Precision, Pucks).
@@ -462,9 +462,26 @@ ranks(heresy) ->
     ["k ", "m ", "b ", "t ", "q ", "e ", "z ", "y ", "r ", "Q "].
 
 
+-spec mark(Unit) -> Mark
+    when Unit :: gaju | puck,
+         Mark :: $木 | $本.
+%% @doc
+%% Retrieve the unicode codepoint for the `gaju' mark (木) or the `puck' mark (本).
+
 mark(gaju) -> $木;
 mark(puck) -> $本.
 
+
+-spec one(Unit) -> Pucks
+    when Unit  :: gaju | puck,
+         Pucks :: 1_000_000_000_000_000_000 | 1.
+%% @doc
+%% Quickly resolve the number of pucks in a given unit.
+%%
+%% The number of pucks in a gaju is so large that it can be a little bit annoying
+%% to remember the exact amount. This is a helper to simplify this when writing
+%% an app against the hakuzaru library when dealing in either unit.
+
 one(gaju) -> 1_000_000_000_000_000_000;
 one(puck) -> 1.
 
@@ -552,8 +569,7 @@ read_w_gajus([32, $G], A) ->
     calc([{$G, A}], []);
 read_w_gajus([32, $P], A) ->
     calc([], [{$P, A}]);
-read_w_gajus(A, B) ->
-    io:format("A: ~ts, B: ~p~n", [A, B]),
+read_w_gajus(_, _) ->
     error.
 
 read_w_pucks([C | Rest], A) when $0 =< C andalso C =< $9 ->
@@ -599,10 +615,23 @@ read([32, $P], A, P) ->
     calc([], [{$P, A} | P]);
 read([C, 32 | Rest], A, G) ->
     read(Rest, [], [{C, A} | G]);
+read([$, | Rest], A, []) ->
+    read_w_gajus(Rest, A);
+read([$_ | Rest], A, []) ->
+    read_w_gajus(Rest, A);
+read([$. | Rest], A, []) ->
+    case read_w_pucks(Rest, []) of
+        {ok, P} ->
+            G = list_to_integer(lists:reverse(A)) * one(gaju),
+            {ok, G + P};
+        Error ->
+            Error
+    end;
 read([C | Rest], A, G) ->
     read(Rest, [], [{C, A} | G]);
-read(Rest, A, G) ->
-    io:format("read(\"~ts\", ~tp, ~tp) -> died!~n", [Rest, A, G]),
+read([], A, []) ->
+    read_w_gajus([], A);
+read(_, _, _) ->
     error.
 
 
@@ -622,7 +651,6 @@ read([C, 32 | Rest], A, G, P) ->
 read([C | Rest], A, G, P) ->
     read(Rest, [], G, [{C, A} | P]);
 read(_, _, _, _) ->
-    io:format("read/4 died!~n"),
     error.
 
 calc(G, P) ->

src/hz_grids.erl

@@ -37,8 +37,8 @@
 %%% @end
 
 -module(hz_grids).
--vsn("0.7.0").
--export([url/2, url/3, url/4, parse/1, req/2, req/3]).
+-vsn("0.9.2").
+-export([url/2, url/3, url/4, parse/1, req/2, req/3, req/4]).
 
 
 -spec url(Instruction, HTTP) -> Result
@@ -47,7 +47,7 @@
          Result      :: {ok, GRIDS} | uri_string:uri_error(),
          GRIDS       :: uri_string:uri_string().
 %% @doc
-%% Takes 
+%% Takes an instruction and an HTTP endpoint location and forms a GRIDS URL.
 
 url(Instruction, HTTP) ->
     case uri_string:parse(HTTP) of
@@ -76,7 +76,7 @@ url2(Instruction, URL = #{path := Path}) ->
          GRIDS       :: uri_string:uri_string().
 %% @doc
 %% Forms a GRIDS URL for spends or transfers.
-%% @equiv uri(Instruction, Recipient, Amount, "").
+%% @equiv uri(Instruction, Recipient, Amount, "")
 
 url(Instruction, Recipient, Amount) ->
     url(Instruction, Recipient, Amount, "").
@@ -134,6 +134,8 @@ qwargs(Amount, Payload) ->
          Amount      :: non_neg_integer(),
          Payload     :: binary(),
          URL         :: string().
+%% @doc
+%% Translate a GRIDS URL into an Erlang terms instruction.
 
 parse(GRIDS) ->
     case uri_string:parse(GRIDS) of
@@ -190,27 +192,61 @@ l_to_i(S) ->
     end.
 
 
+-spec req(Type, Message) -> Format
+    when Type    :: sign | tx | ack,
+         Message :: string() | binary(),
+         Format  :: map().
+%% @doc
+%% @equiv req(Type, Message, false)
+
 req(Type, Message) ->
     req(Type, Message, false).
 
-req(sign, Message, ID) ->
+
+-spec req(Type, Message, ID) -> Format
+    when Type    :: sign | tx | ack,
+         Message :: string() | binary(),
+         ID      :: false | string() | binary(),
+         Format  :: map().
+%% @doc
+%% Creates a GRIDS message format with the current `NetworkID'.
+%%
+%% The `ID' parameter indicates which key the requestee should sign with or
+%% is `false' to indicate that which key to sign with is up to the requestee.
+%% @equiv req(Type, Message, ID, CurrentNetworkID)
+
+req(Type, Message, ID) ->
+    {ok, NetworkID} = hz:network_id(),
+    req(Type, Message, ID, NetworkID).
+
+
+-spec req(Type, Message, ID, NetworkID) -> Format
+    when Type      :: sign | tx | ack,
+         Message   :: string() | binary(),
+         ID        :: false | string() | binary(),
+         NetworkID :: string() | binary(),
+         Format    :: map().
+%% @doc
+%% Creates a GRIDS message format.
+
+req(sign, Message, ID, NetworkID) ->
     #{"grids"      => 1,
       "chain"      => "gajumaru",
-      "network_id" => hz:network_id(),
+      "network_id" => NetworkID,
       "type"       => "message",
       "public_id"  => ID,
       "payload"    => Message};
-req(tx, Data, ID) ->
+req(tx, Data, ID, NetworkID) ->
     #{"grids"      => 1,
       "chain"      => "gajumaru",
-      "network_id" => hz:network_id(),
+      "network_id" => NetworkID,
       "type"       => "tx",
       "public_id"  => ID,
       "payload"    => Data};
-req(ack, Message, ID) ->
+req(ack, Message, ID, NetworkID) ->
     #{"grids"      => 1,
       "chain"      => "gajumaru",
-      "network_id" => hz:network_id(),
+      "network_id" => NetworkID,
       "type"       => "ack",
       "public_id"  => ID,
       "payload"    => Message}.

src/hz_key_master.erl

@@ -8,8 +8,7 @@
 %%% @end
 
 -module(hz_key_master).
--vsn("0.7.0").
-
+-vsn("0.9.2").
 
 -export([make_key/1, encode/1, decode/1]).
 -export([lcg/1]).

src/hz_man.erl

@@ -9,7 +9,7 @@
 %%% @end
 
 -module(hz_man).
--vsn("0.7.0").
+-vsn("0.9.2").
 -behavior(gen_server).
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
@@ -172,7 +172,6 @@ start_link() ->
 %% preparatory work necessary for proper function.
 
 init(none) ->
-    ok = io:format("hz_man starting.~n"),
     State = #s{},
     {ok, State}.
 

src/hz_sup.erl

@@ -9,7 +9,7 @@
 %%% @end
 
 -module(hz_sup).
--vsn("0.7.0").
+-vsn("0.9.2").
 -behaviour(supervisor).
 -author("Craig Everett <zxq9@zxq9.com>").
 -copyright("Craig Everett <zxq9@zxq9.com>").

zomp.meta

@@ -2,9 +2,9 @@
 {type,app}.
 {modules,[]}.
 {prefix,"hz"}.
-{desc,"Gajumaru interoperation library"}.
 {author,"Craig Everett"}.
-{package_id,{"otpr","hakuzaru",{0,7,0}}}.
+{desc,"Gajumaru interoperation library"}.
+{package_id,{"otpr","hakuzaru",{0,9,2}}}.
 {deps,[{"otpr","sophia",{9,0,0}},
        {"otpr","gmserialization",{0,1,3}},
        {"otpr","gmbytecode",{3,4,1}},