WIP

Reviewed-on: #16

doc/overview.edoc

@@ -1,77 +1,79 @@
-@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://git.qpq.swiss/QPQ-AG/hakuzaru]
+@version 0.8.0
+@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,6 +3,7 @@
               {included_applications,[]},
               {applications,[stdlib,kernel]},
               {description,"Gajumaru interoperation library"},
-              {vsn,"0.3.1"},
-              {modules,[hakuzaru,hz,hz_fetcher,hz_man,hz_sup]},
+              {vsn,"0.8.2"},
+              {modules,[hakuzaru,hz,hz_fetcher,hz_format,hz_grids,
+                        hz_key_master,hz_man,hz_sup]},
               {mod,{hakuzaru,[]}}]}.

src/hakuzaru.erl

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

src/hz_fetcher.erl

@@ -1,12 +1,10 @@
 -module(hz_fetcher).
--vsn("0.3.1").
+-vsn("0.8.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("MIT").
 
--export([connect/4, slowly_connect/4]).
-
--include("$zx_include/zx_logger.hrl").
+-export([connect/4, connect_slowly/4]).
 
 
 connect(Node = {Host, Port}, Request, From, Timeout) ->
@@ -78,7 +76,7 @@ parse(Received, Sock, From, Timer) ->
         <<"HTTP/1.1 500 Internal Server Error\r\n", Tail/binary>> ->
             parse2(500, Tail, Sock, From, Timer);
         _ ->
-            ok = zx_net:disconnect(Sock),
+            ok = disconnect(Sock),
             ok = erlang:cancel_timer(Timer, [{async, true}]),
             gen_server:reply(From, {error, {received, Received}})
     end.
@@ -115,7 +113,7 @@ consume2(Length, Received, Sock, From, Timer) ->
     if
         Size == Length ->
             ok = erlang:cancel_timer(Timer, [{async, true}]),
-            ok = zx_net:disconnect(Sock),
+            ok = disconnect(Sock),
             Result = zj:decode(Received),
             gen_server:reply(From, Result);
         Size  < Length ->
@@ -208,7 +206,7 @@ read_hval(_, Received, _, _, _) ->
     {error, headers}.
 
 
-slowly_connect(Node, {get, Path}, From, Timeout) ->
+connect_slowly(Node, {get, Path}, From, Timeout) ->
     HttpOptions = [{connect_timeout, 3000}, {timeout, Timeout}],
     URL = lists:flatten(url(Node, Path)),
     Request = {URL, []},
@@ -219,7 +217,7 @@ slowly_connect(Node, {get, Path}, From, Timeout) ->
             BAD                          -> {error, BAD}
         end,
     gen_server:reply(From, Result);
-slowly_connect(Node, {post, Path, Payload}, From, Timeout) ->
+connect_slowly(Node, {post, Path, Payload}, From, Timeout) ->
     HttpOptions = [{connect_timeout, 3000}, {timeout, Timeout}],
     URL = lists:flatten(url(Node, Path)),
     Request = {URL, [], "application/json", Payload},
@@ -236,3 +234,45 @@ url({Node, Port}, Path) when is_list(Node) ->
     ["https://", Node, ":", integer_to_list(Port), Path];
 url({Node, Port}, Path) when is_tuple(Node) ->
     ["https://", inet:ntoa(Node), ":", integer_to_list(Port), Path].
+
+
+disconnect(Socket) ->
+    case peername(Socket) of
+        {ok, {Addr, Port}} ->
+            Host = inet:ntoa(Addr),
+            disconnect(Socket, Host, Port);
+        {error, Reason} ->
+            log(warning, "Disconnect failed with: ~w", [Reason])
+    end.
+
+disconnect(Socket, Host, Port) ->
+    case gen_tcp:shutdown(Socket, read_write) of
+        ok ->
+            ok;
+        {error, enotconn} ->
+            receive
+                {tcp_closed, Socket} -> ok
+                after 0              -> ok
+            end;
+        {error, E} ->
+            ok = log(warning, "~ts:~w disconnect failed with: ~w", [Host, Port, E]),
+            receive
+                {tcp_closed, Socket} -> ok
+                after 0              -> ok
+            end
+    end.
+
+peername(Socket) ->
+    case inet:peername(Socket) of
+        {ok, {{0, 0, 0, 0, 0, 65535, X, Y}, Port}} ->
+            <<A:8, B:8, C:8, D:8>> = <<X:16, Y:16>>,
+            {ok, {{A, B, C, D}, Port}};
+        Other ->
+            Other
+    end.
+
+
+log(Level, Format, Args) ->
+    Raw = io_lib:format("~w ~w: " ++ Format, [?MODULE, self() | Args]),
+    Entry = unicode:characters_to_list(Raw),
+    logger:log(Level, Entry).

src/hz_format.erl

@@ -0,0 +1,728 @@
+%%% @doc
+%%% Formatting and reading functions for Gaju and Puck quantities
+%%%
+%%% The numbers involved in dealing with blockchain amounts are enormous
+%%% by comparison to legacy forms of currency. It isn't so much that
+%%% thousands of Gajus is hard to reason about, but rather that quadrillions
+%%% of Pucks is quite hard to even lock on to visually.
+%%%
+%%% A normal commas and underscores method of decimal formatting is provided, as
+%%% `us' formatting along with two additional approaches:
+%%% - Japanese traditional myriad structure (`jp' style)
+%%% - An internationalized variant inspired by the Japanese technique over periods
+%%%   (`metric' for SI prefixes, and `legacy' for Anglicized prefixes)
+%%%
+%%% These are all accessible via the `amount/N' functions.
+%%%
+%%% The `read/1' function can accept any of the output variants as a string and
+%%% will return the number of pucks indicated by the provided string, allowing for
+%%% simple copy/paste functionality as well as direct input using any of the
+%%% supported notations.
+%%% @end
+
+-module(hz_format).
+-vsn("0.8.2").
+-author("Craig Everett <ceverett@tsuriai.jp>").
+-copyright("Craig Everett <ceverett@tsuriai.jp>").
+-license("GPL-3.0-or-later").
+
+-export([amount/1, amount/2, amount/3,
+         approx_amount/2, approx_amount/3,
+         read/1,
+         one/1, mark/1,
+         price_to_string/1, string_to_price/1]).
+
+-spec amount(Pucks) -> Formatted
+    when Pucks     :: integer(),
+         Formatted :: string().
+%% @doc
+%% A convenience formatting function.
+%% ```
+%%   hz_format:amount(1) ->
+%%   木0.000,000,000,000,000,001
+%%
+%%   hz_format:amount(5000) ->
+%%   木0.000,000,000,000,005
+%%
+%%   hz_format:amount(5000000000000000000) ->
+%%   木5
+%%
+%%   hz_format:amount(500000123000000000000000) ->
+%%   木500,000.123
+%% '''
+%% @equiv amount(us, Pucks)
+
+amount(Pucks) ->
+    amount(us, Pucks).
+
+
+-spec amount(Style, Pucks) -> Formatted
+    when Style     :: us | jp | metric | legacy | {Separator, Span},
+         Separator :: $, | $_,
+         Span      :: 3 | 4,
+         Pucks     :: integer(),
+         Formatted :: string().
+%% @doc
+%% A money formatting function.
+%% ```
+%%   hz_format:amount(us, 100500040123000000000000000) ->
+%%   木100,500,040.123
+%%
+%%   hz_format:amount(jp, 100500040123000000000000000) ->
+%%   1億50万40木 12京3000兆本
+%%
+%%   hz_format:amount(metric, 100500040123000000000000000) ->
+%%   木100m 500k 40 G 123p P
+%%
+%%   hz_format:amount(legacy, 100500040123000000000000000) ->
+%%   木100m 500k 40 G 123q P
+%%
+%%   hz_format:amount({$_, 3}, 100500040123000000000000000) ->
+%%   木100_500_040.123
+%%
+%%   hz_format:amount({$_, 4}, 100500040123000000000000000) ->
+%%   木1_0050_0040.123
+%% '''
+%% @equiv amount(gaju, Style, Pucks)
+    
+amount(Style, Pucks) ->
+    amount(gaju, Style, Pucks).
+
+
+-spec amount(Unit, Style, Pucks) -> Formatted
+    when Unit      :: gaju | puck,
+         Style     :: us | jp | metric | legacy | {Separator, Span},
+         Separator :: $, | $_,
+         Span      :: 3 | 4,
+         Pucks     :: integer(),
+         Formatted :: string().
+%% @doc
+%% A simplified format function covering the most common formats desired.
+%% ```
+%%   hz_format:amount(gaju, us, 100500040123000004500000000) ->
+%%   木100,500,040.123,000,004,5
+%%
+%%   hz_format:amount(puck, us, 100500040123000004500000000) ->
+%%   本100,500,040,123,000,004,500,000,000
+%%
+%%   hz_format:amount(gaju, jp, 100500040123000004500000000) ->
+%%   1億50万40木 12京3000兆45億本
+%%
+%%   hz_format:amount(puck, jp, 100500040123000004500000000) ->
+%%   100秭5000垓4012京3000兆45億本
+%%
+%%   hz_format:amount(gaju, metric, 100500040123000004500000000) ->
+%%   木100m 500k 40 G 123p 4g 500m P
+%%
+%%   hz_format:amount(puck, metric, 100500040123000004500000000) ->
+%%   本100y 500z 40e 123p 4g 500m P
+%%
+%%   hz_format:amount(gaju, legacy, 100500040123000004500000000) ->
+%%   木100m 500k 40 G 123q 4b 500m P
+%%
+%%   hz_format:amount(puck, legacy, 100500040123000004500000000) ->
+%%   本100y 500z 40e 123q 4b 500m P
+%% '''
+
+amount(gaju, us, Pucks) ->
+    western($,, $., 3, all, Pucks);
+amount(puck, us, Pucks) ->
+    western($,, 3, Pucks);
+amount(Unit, jp, Pucks) ->
+    jp(Unit, all, Pucks);
+amount(Unit, metric, Pucks) ->
+    bestern(Unit, ranks(metric), all, Pucks);
+amount(Unit, legacy, Pucks) ->
+    bestern(Unit, ranks(heresy), all, Pucks);
+amount(gaju, {Separator, Span}, Pucks) ->
+    western(Separator, $., Span, all, Pucks);
+amount(puck, {Separator, Span}, Pucks) ->
+    western(Separator, Span, Pucks).
+
+
+
+-spec approx_amount(Precision, Pucks) -> Serialized
+    when Precision  :: all | 0..18,
+         Pucks      :: integer(),
+         Serialized :: string().
+%% A formatter for decimal notation which permits a precision
+%% value to be applied to the puck side of the format.
+%% ```
+%%   hz_format:approx_amount(3, 100500040123000004500000001) ->
+%%   木100,500,040.123
+%%
+%%   hz_format:approx_amount(13, 100500040123000004500000001) ->
+%%   木100,500,040.123,000,004,5...
+%%
+%%   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).
+
+
+-spec approx_amount(Style, Precision, Pucks) -> Serialized
+    when Style      :: us | {Separator, Span},
+         Precision  :: all | 0..18,
+         Separator  :: $, | $_,
+         Span       :: 3 | 4,
+         Pucks      :: integer(),
+         Serialized :: string().
+%% @doc
+%% A formatter for decimal notation which permits a precision
+%% value to be applied to the puck side of the format.
+%% ```
+%%   hz_format:approx_amount({$_, 3}, 3, 100500040123000004500000001) ->
+%%   木100_500_040.123...
+%%
+%%   hz_format:approx_amount({$_, 4}, 12, 100500040123000004500000001) ->
+%%   木1_0050_0040.1230_0000_45...
+%% '''
+
+approx_amount(us, Precision, Pucks) ->
+    western($,, $., 3, Precision, Pucks);
+approx_amount({Separator, Span}, Precision, Pucks) ->
+    western(Separator, $., Span, Precision, Pucks).
+
+
+western(Separator, Span, Pucks) when Pucks >= 0 ->
+    western2(Separator, Span, Pucks);
+western(Separator, Span, Pucks) when Pucks  < 0 ->
+    [$- | western2(Separator, Span, Pucks * -1)].
+
+western2(Separator, Span, Pucks) ->
+    P = lists:reverse(integer_to_list(Pucks)),
+    [mark(puck) | separate(Separator, Span, P)].
+
+
+western(Separator, Break, Span, Precision, Pucks) when Pucks >= 0 ->
+    western2(Separator, Break, Span, Precision, Pucks);
+western(Separator, Break, Span, Precision, Pucks) when Pucks  < 0 ->
+    [$- | western2(Separator, Break, Span, Precision, Pucks * -1)].
+
+
+western2(Separator, _, Span, 0, Pucks) ->
+    G = lists:reverse(integer_to_list(Pucks div one(gaju))),
+    [mark(gaju) | separate(Separator, Span, G)];
+western2(Separator, Break, Span, Precision, Pucks) ->
+    SP = integer_to_list(Pucks),
+    Length = length(SP),
+    Over18 = Length > 18,
+    NoPucks = (Pucks rem one(gaju)) =:= 0,
+    case {Over18, NoPucks} of
+        {true, true} ->
+            Gs = lists:reverse(lists:sublist(SP, Length - 18)),
+            [mark(gaju) | separate(Separator, Span, Gs)];
+        {true, false} ->
+            {PChars, GChars} = lists:split(18, lists:reverse(SP)),
+            H = [mark(gaju) | separate(Separator, Span, GChars)],
+            {P, E} = decimal_pucks(Precision, lists:reverse(PChars)),
+            T = lists:reverse(separate(Separator, Span, P)),
+            lists:flatten([H, Break, T, E]);
+        {false, true} ->
+            [mark(gaju), $0];
+        {false, false} ->
+            PChars = lists:flatten(string:pad(SP, 18, leading, $0)),
+            {P, E} = decimal_pucks(Precision, PChars),
+            T = lists:reverse(separate(Separator, Span, P)),
+            lists:flatten([mark(gaju), $0, Break, T, E])
+    end.
+
+decimal_pucks(all, PChars) ->
+    RTrailing = lists:reverse(PChars),
+    {lists:reverse(lists:dropwhile(fun(C) -> C =:= $0 end, RTrailing)), ""};
+decimal_pucks(Precision, PChars) ->
+    {Significant, Rest} = lists:split(min(Precision, 18), PChars),
+    RTrailing = lists:reverse(Significant),
+    Trailing = lists:reverse(lists:dropwhile(fun(C) -> C =:= $0 end, RTrailing)),
+    case lists:all(fun(C) -> C =:= $0 end, Rest) of
+        true  -> {Trailing, ""};
+        false -> {Trailing, "..."}
+    end.
+
+separate(_, _, "") ->
+    "";
+separate(S, P, G) ->
+    separate(S, P, 1, G, []).
+
+separate(_, _, _, [H], A) ->
+    [H | A];
+separate(S, P, P, [H | T], A) ->
+    separate(S, P, 1, T, [S, H | A]);
+separate(S, P, N, [H | T], A) ->
+    separate(S, P, N + 1, T, [H | A]).
+
+
+bestern(gaju, Ranks, Precision, Pucks) when Pucks >= 0 ->
+    [mark(gaju), bestern2(gaju, Ranks, 3, Precision, Pucks)];
+bestern(gaju, Ranks, Precision, Pucks) when Pucks  < 0 ->
+    [$-, mark(gaju), bestern2(gaju, Ranks, 3, Precision, Pucks * -1)];
+bestern(puck, Ranks, Precision, Pucks) when Pucks >= 0 ->
+    [mark(puck), bestern2(puck, Ranks, 3, Precision, Pucks)];
+bestern(puck, Ranks, Precision, Pucks) when Pucks  < 0 ->
+    [$-, mark(puck), bestern2(puck, Ranks, 3, Precision, Pucks * -1)].
+
+jp(Unit, Precision, Pucks) when Pucks >= 0 ->
+    bestern2(Unit, ranks(jp), 4, Precision, Pucks);
+jp(Unit, Precision, Pucks) when Pucks  < 0 ->
+    [$－, bestern2(Unit, ranks(jp), 4, Precision, Pucks * -1)].
+
+bestern2(gaju, Ranks, Span, 0, Pucks) ->
+    G = lists:reverse(integer_to_list(Pucks div one(gaju))),
+    case Span of
+        3 -> period("G", Ranks, G);
+        4 -> myriad(mark(gaju), Ranks, G)
+    end;
+bestern2(gaju, Ranks, Span, all, Pucks) ->
+    P = lists:flatten(string:pad(integer_to_list(Pucks rem one(gaju)), 18, leading, $0)),
+    Zilch = lists:all(fun(C) -> C =:= $0 end, P),
+    {H, T} =
+        case {Span, Zilch} of
+            {3, false} -> {bestern2(gaju, Ranks, 3, 0, Pucks), period("P", Ranks, lists:reverse(P))};
+            {4, false} -> {jp(gaju, 0, Pucks),                 myriad(mark(puck), Ranks, lists:reverse(P))};
+            {3, true}  -> {bestern2(gaju, Ranks, 3, 0, Pucks), ""};
+            {4, true}  -> {jp(gaju, 0, Pucks),                 ""}
+        end,
+    lists:flatten([H, " ",  T]);
+bestern2(gaju, Ranks, Span, Precision, Pucks) ->
+    P = lists:flatten(string:pad(integer_to_list(Pucks rem one(gaju)), 18, leading, $0)),
+    H =
+        case Span of
+            3 -> bestern2(gaju, Ranks, 3, 0, Pucks);
+            4 -> jp(gaju, 0, Pucks)
+        end,
+    Digits = min(Precision, 18),
+    T =
+        case length(P) < Digits of
+            false ->
+                ReverseP = lists:reverse(lists:sublist(P, Digits)),
+                PuckingString = lists:flatten(string:pad(ReverseP, 18, leading, $0)),
+                case lists:all(fun(C) -> C =:= $0 end, PuckingString) of
+                    false ->
+                        case Span of
+                            3 -> period("P", Ranks, PuckingString);
+                            4 -> myriad(mark(puck), Ranks, PuckingString)
+                        end;
+                    true ->
+                        ""
+                end;
+            true ->
+                []
+        end,
+    lists:flatten([H, " ",  T]);
+bestern2(puck, Ranks, Span, all, Pucks) ->
+    P = lists:reverse(integer_to_list(Pucks)),
+    case lists:all(fun(C) -> C =:= $0 end, P) of
+        false ->
+            case Span of
+                3 -> period("P", Ranks, P);
+                4 -> myriad(mark(puck), Ranks, P)
+            end;
+        true ->
+            case Span of
+                3 -> [$0, " P"];
+                4 -> [$0, mark(puck)]
+            end
+    end;
+bestern2(puck, Ranks, Span, Precision, Pucks) ->
+    Digits = min(Precision, 18),
+    P = lists:flatten(string:pad(integer_to_list(Pucks), 18, leading, $0)),
+    case length(P) < Digits of
+        true ->
+            case Span of
+                3 -> [$0, " P"];
+                4 -> [$0, mark(puck)]
+            end;
+        false ->
+            PucksToGive = lists:sublist(P, Digits),
+            PuckingString = lists:flatten(string:pad(lists:reverse(PucksToGive), 18, leading, $0)),
+            case lists:all(fun(C) -> C =:= $0 end, PuckingString) of
+                false ->
+                    case Span of
+                        3 -> period("P", Ranks, PuckingString);
+                        4 -> myriad(mark(puck), Ranks, PuckingString)
+                    end;
+                true ->
+                    case Span of
+                        3 -> [$0, " P"];
+                        4 -> [$0, mark(puck)]
+                    end
+            end
+    end.
+
+
+period(Symbol, Ranks, [$0, $0, $0 | PT]) ->
+    rank3(Ranks, PT, [Symbol]);
+period(Symbol, Ranks, [P3, $0, $0 | PT]) ->
+    rank3(Ranks, PT, [P3, 32, Symbol]);
+period(Symbol, Ranks, [P3, P2, $0 | PT]) ->
+    rank3(Ranks, PT, [P2, P3, 32, Symbol]);
+period(Symbol, Ranks, [P3, P2, P1 | PT]) ->
+    rank3(Ranks, PT, [P1, P2, P3, 32, Symbol]);
+period(Symbol, _, [P3]) ->
+    [P3, 32, Symbol];
+period(Symbol, _, [P3, P2]) ->
+    [P2, P3, 32, Symbol].
+
+rank3([_  | RT], [$0, $0, $0 | PT], A) ->
+    rank3(RT, PT, A);
+rank3([RH | RT], [P3, $0, $0 | PT], A) ->
+    rank3(RT, PT, [P3, RH | A]);
+rank3([RH | RT], [P3, P2, $0 | PT], A) ->
+    rank3(RT, PT, [P2, P3, RH | A]);
+rank3([RH | RT], [P3, P2, P1 | PT], A) ->
+    rank3(RT, PT, [P1, P2, P3, RH | A]);
+rank3(_,          [$0, $0, $0],     A) ->
+    A;
+rank3(_,          [$0, $0],         A) ->
+    A;
+rank3(_,          [$0],             A) ->
+    A;
+rank3(_,          [],               A) ->
+    A;
+rank3([RH |  _], [P3, $0, $0],      A) ->
+    [P3, RH | A];
+rank3([RH |  _], [P3, $0],          A) ->
+    [P3, RH | A];
+rank3([RH |  _], [P3],              A) ->
+    [P3, RH | A];
+rank3([RH |  _], [P3, P2, $0],      A) ->
+    [P2, P3, RH | A];
+rank3([RH |  _], [P3, P2],          A) ->
+    [P2, P3, RH | A];
+rank3([RH |  _], [P3, P2, P1],      A) ->
+    [P1, P2, P3, RH | A].
+
+
+myriad(Symbol, Ranks, [$0, $0, $0, $0 | PT]) ->
+    rank4(Ranks, PT, [Symbol]);
+myriad(Symbol, Ranks, [P4, $0, $0, $0 | PT]) ->
+    rank4(Ranks, PT, [P4, Symbol]);
+myriad(Symbol, Ranks, [P4, P3, $0, $0 | PT]) ->
+    rank4(Ranks, PT, [P3, P4, Symbol]);
+myriad(Symbol, Ranks, [P4, P3, P2, $0 | PT]) ->
+    rank4(Ranks, PT, [P2, P3, P4, Symbol]);
+myriad(Symbol, Ranks, [P4, P3, P2, P1 | PT]) ->
+    rank4(Ranks, PT, [P1, P2, P3, P4, Symbol]);
+myriad(Symbol, _, [P4]) ->
+    [P4, Symbol];
+myriad(Symbol, _, [P4, P3]) ->
+    [P3, P4, Symbol];
+myriad(Symbol, _, [P4, P3, P2]) ->
+    [P2, P3, P4, Symbol].
+
+rank4([_  | RT], [$0, $0, $0, $0 | PT], A) ->
+    rank4(RT, PT, A);
+rank4([RH | RT], [P4, $0, $0, $0 | PT], A) ->
+    rank4(RT, PT, [P4, RH | A]);
+rank4([RH | RT], [P4, P3, $0, $0 | PT], A) ->
+    rank4(RT, PT, [P3, P4, RH | A]);
+rank4([RH | RT], [P4, P3, P2, $0 | PT], A) ->
+    rank4(RT, PT, [P2, P3, P4, RH | A]);
+rank4([RH | RT], [P4, P3, P2, P1 | PT], A) ->
+    rank4(RT, PT, [P1, P2, P3, P4, RH | A]);
+rank4(_,          [$0, $0, $0, $0],     A) ->
+    A;
+rank4(_,          [$0, $0, $0],         A) ->
+    A;
+rank4(_,          [$0, $0],             A) ->
+    A;
+rank4(_,          [$0],                 A) ->
+    A;
+rank4(_,          [],                   A) ->
+    A;
+rank4([RH |  _], [P4, $0, $0, $0],      A) ->
+    [P4, RH | A];
+rank4([RH |  _], [P4, $0, $0],          A) ->
+    [P4, RH | A];
+rank4([RH |  _], [P4, $0],              A) ->
+    [P4, RH | A];
+rank4([RH |  _], [P4],                  A) ->
+    [P4, RH | A];
+rank4([RH |  _], [P4, P3, $0, $0],      A) ->
+    [P3, P4, RH | A];
+rank4([RH |  _], [P4, P3, $0],          A) ->
+    [P3, P4, RH | A];
+rank4([RH |  _], [P4, P3],              A) ->
+    [P3, P4, RH | A];
+rank4([RH |  _], [P4, P3, P2, $0],      A) ->
+    [P2, P3, P4, RH | A];
+rank4([RH |  _], [P4, P3, P2],          A) ->
+    [P2, P3, P4, RH | A];
+rank4([RH |  _], [P4, P3, P2, P1],      A) ->
+    [P1, P2, P3, P4, RH | A].
+
+ranks(jp) ->
+    "万億兆京垓秭穣溝澗正載極";
+ranks(metric) ->
+    ["k ", "m ", "g ", "t ", "p ", "e ", "z ", "y ", "r ", "Q "];
+ranks(heresy) ->
+    ["k ", "m ", "b ", "t ", "q ", "e ", "z ", "y ", "r ", "Q "].
+
+
+mark(gaju) -> $木;
+mark(puck) -> $本.
+
+one(gaju) -> 1_000_000_000_000_000_000;
+one(puck) -> 1.
+
+
+-spec read(Format) -> Result
+    when Format :: string(),
+         Result :: {ok, Pucks} | error,
+         Pucks  :: integer().
+%% @doc
+%% Convert any valid string formatted representation and output a value in pucks.
+%% NOTE: This function does not accept approximated values.
+%% ```
+%%   1> hz_format:read("木100,500,040.123,000,004,5").
+%%   {ok,100500040123000004500000000}
+%%   2> hz_format:read("本100,500,040,123,000,004,500,000,000").
+%%   {ok,100500040123000004500000000}
+%%   3> hz_format:read("1億50万40木 12京3000兆45億本").
+%%   {ok,100500040123000004500000000}
+%%   4> hz_format:read("100秭5000垓4012京3000兆45億本").
+%%   {ok,100500040123000004500000000}
+%%   5> hz_format:read("木100m 500k 40 G 123p 4g 500m P").
+%%   {ok,100500040123000004500000000}
+%%   6> hz_format:read("本100y 500z 40e 123p 4g 500m P").
+%%   {ok,100500040123000004500000000}
+%%   7> hz_format:read("木100m 500k 40 G 123q 4b 500m P").
+%%   {ok,100500040123000004500000000}
+%%   8> hz_format:read("本100y 500z 40e 123q 4b 500m P").
+%%   {ok,100500040123000004500000000}
+%% '''
+
+read([$木 | Rest]) ->
+    read_w_gajus(Rest, []);
+read([$本 | Rest]) ->
+    read_w_pucks(Rest, []);
+read([C | Rest])
+        when C =:= $- orelse
+             C =:= $− orelse
+             C =:= $－ ->
+    case read(Rest) of
+        {ok, Pucks} -> {ok, Pucks * -1};
+        Error       -> Error
+    end;
+read([C | Rest])
+        when C =:= 32    orelse % ASCII space
+             C =:= 12288 orelse % full-width space
+             C =:= $\t   orelse
+             C =:= $\r   orelse
+             C =:= $\n ->
+    read(Rest);
+read([C | Rest]) when $0 =< C andalso C =< $9 ->
+    read(Rest, [C], []);
+read([C | Rest]) when $０ =< C andalso C =< $９ ->
+    NumC = C - $０ + $0,
+    read(Rest, [NumC], []);
+read(String) when is_binary(String) ->
+    read(binary_to_list(String));
+read(_) ->
+    error.
+
+read_w_gajus([C | Rest], A) when $0 =< C andalso C =< $9 ->
+    read_w_gajus(Rest, [C | A]);
+read_w_gajus([C | Rest], A) when $０ =< C andalso C =< $９ ->
+    NumC = C - $０ + $0,
+    read_w_gajus(Rest, [NumC | A]);
+read_w_gajus([$, | Rest], A) ->
+    read_w_gajus(Rest, A);
+read_w_gajus([$_ | Rest], A) ->
+    read_w_gajus(Rest, A);
+read_w_gajus([$. | 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_w_gajus([], A) ->
+    G = list_to_integer(lists:reverse(A)) * one(gaju),
+    {ok, G};
+read_w_gajus([C, 32 | Rest], A) ->
+    read(Rest, [], [{C, A}]);
+read_w_gajus([32, $G, 32 | Rest], A) ->
+    read(Rest, [], [{$G, A}], []);
+read_w_gajus([32, $G], A) ->
+    calc([{$G, A}], []);
+read_w_gajus([32, $P], A) ->
+    calc([], [{$P, A}]);
+read_w_gajus(_, _) ->
+    error.
+
+read_w_pucks([C | Rest], A) when $0 =< C andalso C =< $9 ->
+    read_w_pucks(Rest, [C | A]);
+read_w_pucks([C | Rest], A) when $０ =< C andalso C =< $９ ->
+    NumC = C - $０ + $0,
+    read_w_pucks(Rest, [NumC | A]);
+read_w_pucks([$, | Rest], A) ->
+    read_w_pucks(Rest, A);
+read_w_pucks([$_ | Rest], A) ->
+    read_w_pucks(Rest, A);
+read_w_pucks([C, 32 | Rest], A) ->
+    read(Rest, [], [], [{C, A}]);
+read_w_pucks([32, $P], A) ->
+    calc([], [{$P, A}]);
+read_w_pucks([], A) ->
+    Padded = lists:flatten(string:pad(lists:reverse(A), 18, trailing, $0)),
+    {ok, list_to_integer(Padded)}.
+
+
+read([C | Rest], A, G) when $0 =< C andalso C =< $9 ->
+    read(Rest, [C | A], G);
+read([C | Rest], A, G) when $０ =< C andalso C =< $９ ->
+    NumC = C - $０ + $0,
+    read(Rest, [NumC | A], G);
+read([$木], A, G) ->
+    calc([{$G, A} | G], []);
+read([$G], A, G) ->
+    calc([{$G, A} | G], []);
+read([32, $G], A, G) ->
+    calc([{$G, A} | G], []);
+read([32, $G, 32 | Rest], A, G) ->
+    read(Rest, [], [{$G, A} | G], []);
+read([$木, 32 | Rest], A, G) ->
+    read(Rest, [], [{$G, A} | G], []);
+read([$G, 32 | Rest], A, G) ->
+    read(Rest, [], [{$G, A} | G], []);
+read([$本], A, P) ->
+    calc([], [{$P, A} | P]);
+read([$P], A, P) ->
+    calc([], [{$P, A} | P]);
+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([], A, []) ->
+    read_w_gajus([], A);
+read(_, _, _) ->
+    error.
+
+
+read([C | Rest], A, G, P) when $0 =< C andalso C =< $9 ->
+    read(Rest, [C | A], G, P);
+read([C | Rest], A, G, P) when $０ =< C andalso C =< $９ ->
+    NumC = C - $０ + $0,
+    read(Rest, [NumC | A], G, P);
+read([$本], A, G, P) ->
+    calc(G, [{$P, A} | P]);
+read([$P], A, G, P) ->
+    calc(G, [{$P, A} | P]);
+read([32, $P], A, G, P) ->
+    calc(G, [{$P, A} | P]);
+read([C, 32 | Rest], A, G, P) ->
+    read(Rest, [], G, [{C, A} | P]);
+read([C | Rest], A, G, P) ->
+    read(Rest, [], G, [{C, A} | P]);
+read(_, _, _, _) ->
+    error.
+
+calc(G, P) ->
+    case calc(gaju, G, 0) of
+        {ok, Gajus} ->
+            case calc(puck, P, 0) of
+                {ok, Pucks} -> {ok, Gajus + Pucks};
+                error       -> error
+            end;
+        error ->
+            error
+    end.
+
+calc(U, [{_, []} | S], A) ->
+    calc(U, S, A);
+calc(U, [{M, Cs} | S], A) ->
+    case magnitude(M) of
+        {ok, J} ->
+            N = list_to_integer(lists:reverse(Cs)) * J * one(U),
+            calc(U, S, A + N);
+        Error ->
+            Error
+    end;
+calc(_, [], A) ->
+    {ok, A}.
+
+
+magnitude($G) ->
+    {ok, 1};
+magnitude($P) ->
+    {ok, 1};
+magnitude(Mark) ->
+    case rank(Mark, ranks(jp), 1_0000, 1) of
+        {ok, J} ->
+            {ok, J};
+        error ->
+            case rank([Mark, 32], ranks(metric), 1_000, 1) of
+                {ok, J} -> {ok, J};
+                error   -> rank([Mark, 32], ranks(heresy), 1_000, 1)
+            end
+    end.
+
+rank(Mark, [Mark | _], Magnitude, Sum) ->
+    {ok, Sum * Magnitude};
+rank(Mark, [_ | Rest], Magnitude, Sum) ->
+    rank(Mark, Rest, Magnitude, Sum * Magnitude);
+rank(_, [], _, _) ->
+    error.
+
+
+-spec price_to_string(Pucks) -> Gajus
+    when Pucks :: integer(),
+         Gajus :: string().
+%% @doc
+%% A simplified formatting function that converts an integer value in Pucks to a string representation
+%% in Gajus. Useful for formatting generic output for UI elements
+
+price_to_string(Pucks) ->
+    Gaju = one(gaju),
+    H = integer_to_list(Pucks div Gaju),
+    R = Pucks rem Gaju,
+    case string:strip(lists:flatten(io_lib:format("~18..0w", [R])), right, $0) of
+        [] -> H;
+        T  -> string:join([H, T], ".")
+    end.
+
+
+-spec string_to_price(Gajus) -> Pucks
+    when Gajus :: string(),
+         Pucks :: integer().
+%% @doc
+%% A simplified formatting function that converts a Gaju value represented as a string to an
+%% integer value in Pucks.
+
+string_to_price(String) ->
+    case string:split(String, ".") of
+        [H]    -> join_price(H, "0");
+        [H, T] -> join_price(H, T);
+        _      -> {error, bad_price}
+    end.
+
+join_price(H, T) ->
+    try
+        Parts = [H, string:pad(T, 18, trailing, $0)],
+        Price = list_to_integer(unicode:characters_to_list(Parts)),
+        case Price < 0 of
+            false -> {ok, Price};
+            true  -> {error, negative_price}
+        end
+    catch
+        error:R -> {error, R}
+    end.

src/hz_grids.erl

@@ -0,0 +1,250 @@
+%%% @doc
+%%% GRIDS URL parsing
+%%%
+%%% GRID(S): Gajumaru Remote Instruction Dispatch (Serialization)
+%%% GRIDS is a Gajumaru protocol for encoding wallet instructions as URLs.
+%%% Version 1 of the protocol consists of two verbs with two contexts each, collapsed to
+%%% four symbols for brevity.
+%%%
+%%% The GRIDS schema begins with "grids://" or "grid://"
+%%% Which way this is interpreted can vary depending on the verb.
+%%%
+%%% The typical "host" component is either an actual hostname or address and an optional
+%%% port number (the defaut port being 3013), or a Gajumaru chain network IDi (in which
+%%% case the port number is ignored if provided). Which way this field is interpreted
+%%% depends on the verb.
+%%%
+%%% The first element of the path after the host component indicates the protocol version.
+%%% Only version 1 exists at the time of this release.
+%%%
+%%% The next element of the path after the version is a single letter that indicates which
+%%% action to take. The following actions are available:
+%%%   "s": Spend on Chain
+%%%     Constructs a spend transaction to the address indicated in the path component
+%%%     indicated in the final path element. Two qargs are valid in the trailing arguments
+%%%     section: "a" for amount (in Pucks, not Gajus!), and "p" for data payload.
+%%%     In this context the "host" field in the URL is interpreted as a chain network ID.
+%%%   "t": Transfer (spend) on Host
+%%%     The same as "spend" above, but in this context the host field of the URL is
+%%%     interpreted as host[:port] information and the network chain ID that will be used
+%%%     will be derived from whatever chain the given host reports.
+%%%   "d": Dead-drop signature request
+%%%     This instructs the wallet to retrieve a signature data blob from an HTTP or HTTPS
+%%%     URL that can be reconstructed by replacing "grids" with "https" or "grid" with
+%%%     "http", omitting the "/1/d" path component and then recnstructing the URL.
+%%%     This provides a lightweight method for services to enable contract calls from
+%%%     wallets that are not capable of compiling contract source.
+%%% @end
+
+-module(hz_grids).
+-vsn("0.8.2").
+-export([url/2, url/3, url/4, parse/1, req/2, req/3]).
+
+
+-spec url(Instruction, HTTP) -> Result
+    when Instruction :: spend | transfer | sign,
+         HTTP        :: uri_string:uri_string(),
+         Result      :: {ok, GRIDS} | uri_string:uri_error(),
+         GRIDS       :: uri_string:uri_string().
+%% @doc
+%% Takes 
+
+url(Instruction, HTTP) ->
+    case uri_string:parse(HTTP) of
+        U = #{scheme := "https"} -> url2(Instruction, U#{scheme := "grids"});
+        U = #{scheme := "http"}  -> url2(Instruction, U#{scheme := "grid"});
+        Error                    -> Error
+    end.
+
+url2(Instruction, URL = #{path := Path}) ->
+    GRIDS =
+        case Instruction of
+            spend    -> URL#{path := "/1/s" ++ Path};
+            transfer -> URL#{path := "/1/t" ++ Path};
+            sign     -> URL#{path := "/1/d" ++ Path}
+        end,
+    {ok, uri_string:recompose(GRIDS)}.
+
+
+-spec url(Instruction, Recipient, Amount) -> GRIDS
+    when Instruction :: {spend, Network} | {transfer, Node},
+         Network     :: string(),
+         Node        :: {inet:ip_address() | inet:hostname(), inet:port_number()}
+                      | uri_string:uri_string(),
+         Recipient   :: string(),
+         Amount      :: non_neg_integer(),
+         GRIDS       :: uri_string:uri_string().
+%% @doc
+%% Forms a GRIDS URL for spends or transfers.
+%% @equiv uri(Instruction, Recipient, Amount, "")
+
+url(Instruction, Recipient, Amount) ->
+    url(Instruction, Recipient, Amount, "").
+
+
+-spec url(Instruction, Recipient, Amount, Payload) -> GRIDS
+    when Instruction :: {spend, Network} | {transfer, Node},
+         Network     :: string(),
+         Node        :: {inet:ip_address() | inet:hostname(), inet:port_number()}
+                      | uri_string:uri_string(), % "http://..." | "https://..."
+         Recipient   :: string(),
+         Amount      :: non_neg_integer() | none,
+         Payload     :: binary(),
+         GRIDS       :: uri_string:uri_string().
+%% @doc
+%% Forms a GRIDS URL for spends or transfers.
+
+url({spend, Network}, Recipient, Amount, Payload) ->
+    Elements = ["grids://", Network, "/1/s/", Recipient, qwargs(Amount, Payload)],
+    unicode:characters_to_list(Elements);
+url({transfer, Node}, Recipient, Amount, Payload) ->
+    Prefix =
+        case Node of
+            {H, P}                   -> ["grid://", h_to_s(H), ":", integer_to_list(P)];
+            "https://" ++ H          -> ["grids://", H];
+            "http://"  ++ H          -> ["grid://",  H];
+            <<"https://", H/binary>> -> ["grids://", H];
+            <<"http://",  H/binary>> -> ["grid://",  H]
+        end,
+    unicode:characters_to_list([Prefix, "/1/t/", Recipient, qwargs(Amount, Payload)]).
+
+h_to_s(Host) when is_list(Host)   -> Host;
+h_to_s(Host) when is_binary(Host) -> Host;
+h_to_s(Host) when is_tuple(Host)  -> inet:ntoa(Host);
+h_to_s(Host) when is_atom(Host)   -> atom_to_list(Host).
+
+qwargs(none, "") ->
+    [];
+qwargs(Amount, "") ->
+    ["?a=", integer_to_list(Amount)];
+qwargs(none, Payload) ->
+    [$? | uri_string:compose_query([{"p", Payload}])];
+qwargs(Amount, Payload) ->
+    [$? | uri_string:compose_query([{"a", integer_to_list(Amount)}, {"p", Payload}])].
+
+
+-spec parse(GRIDS) -> Result
+    when GRIDS       :: string(),
+         Result      :: {ok, Instruction} | uri_string:error(),
+         Instruction :: {{spend, chain | node}, {Location, Recipient, Amount, Payload}}
+                      | {{sign, http | https}, URL},
+         Location    :: Node  :: {inet:ip_address() | inet:hostname(), inet:port_number()}
+                      | Chain :: binary(),
+         Recipient   :: gajudesk:id(),
+         Amount      :: non_neg_integer(),
+         Payload     :: binary(),
+         URL         :: string().
+
+parse(GRIDS) ->
+    case uri_string:parse(GRIDS) of
+        #{path := "/1/s/" ++ R, host := H, query := Q, scheme := "grids"} ->
+            spend(R, chain, list_to_binary(H), Q);
+        #{path := "/1/s/" ++ R, host := H, query := Q, scheme := "grid"} ->
+            spend(R, chain, list_to_binary(H), Q);
+        #{path := "/1/t/" ++ R, host := H, port := P, query := Q, scheme := "grids"} ->
+            spend(R, node, {H, P}, Q);
+        #{path := "/1/t/" ++ R, host := H, port := P, query := Q, scheme := "grid"} ->
+            spend(R, node, {H, P}, Q);
+        #{path := "/1/t/" ++ R, host := H, query := Q, scheme := "grids"} ->
+            spend(R, node, {H, 3013}, Q);
+        #{path := "/1/t/" ++ R, host := H, query := Q, scheme := "grid"} ->
+            spend(R, node, {H, 3013}, Q);
+        U = #{path := "/1/d/" ++ L, scheme := "grids"} ->
+            HTTP = uri_string:recompose(U#{scheme := "https", path := L}),
+            {ok ,{{sign, https}, HTTP}};
+        U = #{path := "/1/d/" ++ L, scheme := "grid"} ->
+            HTTP = uri_string:recompose(U#{scheme := "http", path := L}),
+            {ok, {{sign, http}, HTTP}};
+        Error ->
+            Error
+    end.
+
+spend(Recipient, Context, Location, Qwargs) ->
+    case dissect_query(Qwargs) of
+        {ok, Amount, Payload} ->
+            {ok, {{spend, Context}, {Location, Recipient, Amount, Payload}}};
+        Error ->
+            Error
+    end.
+
+
+dissect_query(Qwargs) ->
+    case uri_string:dissect_query(Qwargs) of
+        {error, Reason, Info} ->
+            {error, Reason, Info};
+        ArgList ->
+            case l_to_i(proplists:get_value("a", ArgList, "0")) of
+                {ok, Amount} ->
+                    Payload = list_to_binary(proplists:get_value("p", ArgList, "")),
+                    {ok, Amount, Payload};
+                Error ->
+                    Error
+            end
+    end.
+
+l_to_i(S) ->
+    try
+        {ok, list_to_integer(S)}
+    catch
+        error:badarg -> {error, bad_url}
+    end.
+
+
+-spec req(Type, Message) -> RequestMap
+    when Type       :: {sign, message | binary | bitcoin}
+                     | tx
+                     | ack
+                     | sign,
+         Message    :: binary(),
+         RequestMap :: map().
+%% @doc
+%% GRIDS maps always contain the following keys:
+%% ```
+%%  #{"grids"      => 1,
+%%    "chain"      => "gajumaru",
+%%    "network_id" => "groot.mainnet.gajumaru.io",
+%%    "type"       => "message" | "binary" | "binary" | "tx" | "ack"
+%%    "public_id"  => term(),
+%%    "payload"    => string()};
+%% '''
+
+req(Type, Message) ->
+    req(Type, Message, false).
+
+req({sign, message}, Message, ID) ->
+    #{"grids"      => 1,
+      "chain"      => "gajumaru",
+      "network_id" => hz:network_id(),
+      "type"       => "message",
+      "public_id"  => ID,
+      "payload"    => Message};
+req({sign, binary}, Binary, ID) ->
+    #{"grids"      => 1,
+      "chain"      => "gajumaru",
+      "network_id" => hz:network_id(),
+      "type"       => "binary",
+      "public_id"  => ID,
+      "payload"    => base64:encode(Binary)};
+req({sign, bitcoin}, Binary, ID) ->
+    #{"grids"      => 1,
+      "chain"      => "gajumaru",
+      "network_id" => hz:network_id(),
+      "type"       => "bitcoin",
+      "public_id"  => ID,
+      "payload"    => base64:encode(Binary)};
+req(tx, Data, ID) ->
+    #{"grids"      => 1,
+      "chain"      => "gajumaru",
+      "network_id" => hz:network_id(),
+      "type"       => "tx",
+      "public_id"  => ID,
+      "payload"    => Data};
+req(ack, Message, ID) ->
+    #{"grids"      => 1,
+      "chain"      => "gajumaru",
+      "network_id" => hz:network_id(),
+      "type"       => "ack",
+      "public_id"  => ID,
+      "payload"    => Message};
+req(sign, Message, ID) ->
+    req({sign, message}, Message, ID).

src/hz_key_master.erl

@@ -0,0 +1,153 @@
+%%% @doc
+%%% Key functions
+%%%
+%%% The main reason this is a module of its own is that in the original architecture
+%%% it was a process rather than just a library of functions. Now that it exists, though,
+%%% there is little motivation to cram everything here into the controller process's
+%%% code.
+%%% @end
+
+-module(hz_key_master).
+-vsn("0.8.2").
+
+
+-export([make_key/1, encode/1, decode/1]).
+-export([lcg/1]).
+
+make_key(<<>>) ->
+    Pair = #{public := Public} = ecu_eddsa:sign_keypair(),
+    ID = gmser_api_encoder:encode(account_pubkey, Public),
+    {ID, Pair};
+make_key(Seed) ->
+    Pair = #{public := Public} = ecu_eddsa:sign_seed_keypair(Seed),
+    ID = gmser_api_encoder:encode(account_pubkey, Public),
+    {ID, Pair}.
+
+
+-spec encode(Secret) -> Phrase
+    when Secret :: binary(),
+         Phrase :: string().
+%% @doc
+%% The encoding and decoding procesures are written to be able to handle any
+%% width of bitstring or binary and a variable size dictionary. The magic numbers
+%% 32, 4096 and 12 have been dropped in because currently these are known, but that
+%% will change in the future if the key size or type changes.
+
+encode(Bin) ->
+    <<Number:(32 * 8)>> = Bin,
+    DictSize = 4096,
+    Words = read_words(),
+%   Width = chunksize(DictSize - 1, 2),
+    Width = 12,
+    Chunks = chunksize(Number, DictSize),
+    Binary = <<Number:(Chunks * Width)>>,
+    encode(Width, Binary, Words).
+
+encode(Width, Bits, Words) ->
+    CheckSum = checksum(Width, Bits),
+    encode(Width, <<CheckSum:Width, Bits/bitstring>>, Words, []).
+
+encode(_, <<>>, _, Acc) ->
+    unicode:characters_to_list(lists:join(" ", lists:reverse(Acc)));
+encode(Width, Bits, Words, Acc) ->
+    <<I:Width, Rest/bitstring>> = Bits,
+    Word = lists:nth(I + 1, Words),
+    encode(Width, Rest, Words, [Word | Acc]).
+
+
+-spec decode(Phrase) -> {ok, Secret} | {error, Reason}
+    when Phrase :: string(),
+         Secret :: binary(),
+         Reason :: bad_phrase | bad_word.
+%% @doc
+%% Reverses the encoded secret string back into its binary representation.
+
+decode(Encoded) ->
+    DictSize = 4096,
+    Words = read_words(),
+    Width = chunksize(DictSize - 1, 2),
+    decode(Width, Words, Encoded).
+
+decode(Width, Words, Encoded) when is_list(Encoded) ->
+    decode(Width, Words, list_to_binary(Encoded));
+decode(Width, Words, Encoded) ->
+    Split = string:lexemes(Encoded, " "),
+    decode(Width, Words, Split, <<>>).
+
+decode(Width, Words, [Word | Rest], Acc) ->
+    case find(Word, Words) of
+        {ok, N} -> decode(Width, Words, Rest, <<Acc/bitstring, N:Width>>);
+        Error   -> Error
+    end;
+decode(Width, _, [], Acc) ->
+    sumcheck(Width, Acc).
+
+
+chunksize(N, C) ->
+    chunksize(N, C, 0).
+
+chunksize(0, _, A) -> A;
+chunksize(N, C, A) -> chunksize(N div C, C, A + 1).
+
+
+read_words() ->
+    ModPath = code:which(?MODULE),
+    Path = filename:join([filename:dirname(filename:dirname(ModPath)), "priv", "words4096.txt"]),
+    {ok, Bin} = file:read_file(Path),
+    string:lexemes(Bin, "\n").
+
+
+find(Word, Words) ->
+    find(Word, Words, 0).
+
+find(Word, [Word | _], N) -> {ok, N};
+find(Word, [_ | Rest], N) -> find(Word, Rest, N + 1);
+find(Word, [], _)         -> {error, {bad_word, Word}}.
+
+
+checksum(Width, Bits) ->
+    checksum(Width, Bits, 0).
+
+checksum(_, <<>>, Sum) ->
+    Sum;
+checksum(Width, Bits, Sum) ->
+    <<N:Width, Rest/bitstring>> = Bits,
+    checksum(Width, Rest, N bxor Sum).
+
+
+sumcheck(Width, Bits) ->
+    <<CheckSum:Width, Binary/bitstring>> = Bits,
+    case checksum(Width, Binary) =:= CheckSum of
+        true ->
+            <<N:(bit_size(Binary))>> = Binary,
+            {ok, <<N:(32 * 8)>>};
+        false ->
+            {error, bad_phrase}
+    end.
+
+
+
+-spec lcg(integer()) -> integer().
+%% A simple PRNG that fits into 32 bits and is easy to implement anywhere (Kotlin).
+%% Specifically, it is a "linear congruential generator" of the Lehmer variety.
+%% The constants used are based on recommendations from Park, Miller and Stockmeyer:
+%% https://www.firstpr.com.au/dsp/rand31/p105-crawford.pdf#page=4
+%%
+%% The input value should be between 1 and 2^31-1.
+%%
+%% The purpose of this PRNG is for password-based dictionary shuffling.
+
+lcg(N) ->
+    M = 16#7FFFFFFF,
+    A = 48271,
+    Q = 44488,  %  M div A
+    R = 3399,   %  M rem A
+    Div = N div Q,
+    Rem = N rem Q,
+    S = Rem * A,
+    T = Div * R,
+    Result = S - T,
+    case Result < 0 of
+        false -> Result;
+        true  -> Result + M
+    end.

src/hz_man.erl

@@ -9,29 +9,28 @@
 %%% @end
 
 -module(hz_man).
--vsn("0.3.1").
+-vsn("0.8.2").
 -behavior(gen_server).
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("MIT").
 
 %% Admin functions
--export([network_id/0,  network_id/1,
-         tls/0,         tls/1,
+-export([tls/0,         tls/1,
          chain_nodes/0, chain_nodes/1,
          timeout/0,     timeout/1]).
 
+%% Contract caching
+-export([cache_aaci/2,  lookup_aaci/1]).
+
 %% The whole point of this module:
--export([request/1, request/2]).
+-export([request_sticky/1, request_sticky/2, request/1, request/2]).
 
 %% gen_server goo
 -export([start_link/0]).
 -export([init/1, handle_call/3, handle_cast/2, handle_info/2,
          code_change/3, terminate/2]).
 
-%% TODO: Make logging more flexible
--include("$zx_include/zx_logger.hrl").
-
 
 %%% Type and Record Definitions
 
@@ -44,12 +43,12 @@
          req  = none :: none | binary()}).
 
 -record(s,
-        {network_id  = "gm_mainnet" :: string(),
-         tls         = false        :: boolean(),
-         chain_nodes = {[], []}     :: {[hz:chain_node()], [hz:chain_node()]},
-         sticky      = none         :: none | hz:chain_node(),
-         fetchers    = []           :: [#fetcher{}],
-         timeout     = 5000         :: pos_integer()}).
+        {tls         = false    :: boolean(),
+         chain_nodes = {[], []} :: {[hz:chain_node()], [hz:chain_node()]},
+         sticky      = none     :: none | hz:chain_node(),
+         fetchers    = []       :: [#fetcher{}],
+         timeout     = 5000     :: pos_integer(),
+         cache       = #{}      :: #{Label :: term() := AACI :: hz:aaci()}}).
 
 
 -type state()   :: #s{}.
@@ -58,19 +57,6 @@
 
 %%% Service Interface
 
--spec network_id() -> Name
-    when Name :: hz:network_id().
-
-network_id() ->
-    gen_server:call(?MODULE, network_id).
-
-
--spec network_id(Name) -> ok
-    when Name :: hz:network_id().
-
-network_id(Name) ->
-    gen_server:cast(?MODULE, {network_id, Name}).
-
 
 -spec tls() -> boolean().
 
@@ -92,7 +78,7 @@ chain_nodes() ->
 
 
 -spec chain_nodes(ToUse) -> ok
-    when ToUse :: [hz:chain_nodes()].
+    when ToUse :: [hz:chain_node()].
 
 chain_nodes(ToUse) ->
     gen_server:cast(?MODULE, {chain_nodes, ToUse}).
@@ -112,6 +98,41 @@ timeout(Value) when 0 < Value, Value =< 120000 ->
     gen_server:cast(?MODULE, {timeout, Value}).
 
 
+-spec cache_aaci(Label, AACI) -> ok
+    when Label :: term(),
+         AACI  :: hz:aaci().
+
+cache_aaci(Label, AACI) ->
+    gen_server:call(?MODULE, {cache, Label, AACI}).
+
+
+-spec lookup_aaci(Label) -> Result
+    when Label  :: term(),
+         Result :: {ok, hz:aaci()} | error.
+
+lookup_aaci(Label) ->
+    gen_server:call(?MODULE, {lookup, Label}).
+
+
+-spec request_sticky(Path) -> {ok, Value} | {error, Reason}
+    when Path   :: unicode:charlist(),
+         Value  :: map(),
+         Reason :: hz:chain_error().
+
+request_sticky(Path) ->
+    gen_server:call(?MODULE, {request_sticky, {get, Path}}, infinity).
+
+
+-spec request_sticky(Path, Data) -> {ok, Value} | {error, Reason}
+    when Path   :: unicode:charlist(),
+         Data   :: unicode:charlist(),
+         Value  :: map(),
+         Reason :: hz:chain_error().
+
+request_sticky(Path, Data) ->
+    gen_server:call(?MODULE, {request_sticky, {post, Path, Data}}, infinity).
+
+
 -spec request(Path) -> {ok, Value} | {error, Reason}
     when Path   :: unicode:charlist(),
          Value  :: map(),
@@ -163,12 +184,19 @@ init(none) ->
 handle_call({request, Request}, From, State) ->
     NewState = do_request(Request, From, State),
     {noreply, NewState};
-handle_call(network_id, _, State = #s{network_id = Name}) ->
-    {reply, Name, State};
+handle_call({request_sticky, Request}, From, State) ->
+    NewState = do_request_sticky(Request, From, State),
+    {noreply, NewState};
+handle_call({lookup, Label}, _, State) ->
+    Result = do_lookup(Label, State),
+    {reply, Result, State};
+handle_call({cache, Label, AACI}, _, State) ->
+    NewState = do_cache_aaci(Label, AACI, State),
+    {reply, ok, NewState};
 handle_call(tls, _, State = #s{tls = TLS}) ->
     {reply, TLS, State};
-handle_call(chain_nodes, _, State = #s{chain_nodes = {Wait, Used}}) ->
-    Nodes = lists:append(Wait, Used),
+handle_call(chain_nodes, _, State) ->
+    Nodes = do_chain_nodes(State),
     {reply, Nodes, State};
 handle_call(timeout, _, State = #s{timeout = Value}) ->
     {reply, Value, State};
@@ -177,15 +205,12 @@ handle_call(Unexpected, From, State) ->
     {noreply, State}.
 
 
-handle_cast({network_id, Name}, State) ->
-    {noreply, State#s{network_id = Name}};
 handle_cast({tls, Boolean}, State) ->
     NewState = do_tls(Boolean, State),
     {noreply, NewState};
-handle_cast({chain_nodes, []}, State) ->
-    {noreply, State#s{chain_nodes = none}};
-handle_cast({chain_nodes, ToUse}, State) ->
-    {noreply, State#s{chain_nodes = {ToUse, []}}};
+handle_cast({chain_nodes, List}, State) ->
+    NewState = do_chain_nodes(List, State),
+    {noreply, NewState};
 handle_cast({timeout, Value}, State) ->
     {noreply, State#s{timeout = Value}};
 handle_cast(Unexpected, State) ->
@@ -197,7 +222,7 @@ handle_info({'DOWN', Mon, process, PID, Info}, State) ->
     NewState = handle_down(PID, Mon, Info, State),
     {noreply, NewState};
 handle_info(Unexpected, State) ->
-    ok = log("Unexpected info: ~tp~n", [Unexpected]),
+    ok = log(warning, "Unexpected info: ~tp~n", [Unexpected]),
     {noreply, State}.
 
 
@@ -240,6 +265,23 @@ terminate(_, _) ->
 
 %%% Doer Functions
 
+do_chain_nodes(#s{sticky = none, chain_nodes = {Wait, Used}}) ->
+    lists:append(Wait, Used);
+do_chain_nodes(#s{sticky = Sticky, chain_nodes = {Wait, Used}}) ->
+    case lists:append(Wait, Used) of
+        [Sticky] -> [Sticky];
+        Nodes    -> [Sticky | Nodes]
+    end.
+
+
+do_chain_nodes([], State) ->
+    State#s{sticky = none, chain_nodes = {[], []}};
+do_chain_nodes(List = [Sticky], State) ->
+    State#s{sticky = Sticky, chain_nodes = {List, []}};
+do_chain_nodes([Sticky | List], State) ->
+    State#s{sticky = Sticky, chain_nodes = {List, []}}.
+
+
 do_tls(true, State) ->
     ok = ssl:start(),
     State#s{tls = true};
@@ -249,17 +291,30 @@ do_tls(_, State) ->
     State.
 
 
-do_request(_, From, State = #s{chain_nodes = {[], []}}) ->
+do_cache_aaci(Label, AACI, State = #s{cache = Cache}) ->
+    NewCache = maps:put(Label, AACI, Cache),
+    State#s{cache = NewCache}.
+
+
+do_lookup(Label, #s{cache = Cache}) ->
+    maps:find(Label, Cache).
+
+
+do_request_sticky(_, From, State = #s{sticky = none}) ->
     ok = gen_server:reply(From, {error, no_nodes}),
     State;
-do_request(Request,
-           From,
-           State = #s{tls         = false,
-                      fetchers    = Fetchers,
-                      chain_nodes = {[Node | Rest], Used},
-                      timeout     = Timeout}) ->
+do_request_sticky(Request,
+                  From,
+                  State = #s{tls       = TLS,
+                             fetchers  = Fetchers,
+                             sticky    = Node,
+                             timeout   = Timeout}) ->
     Now = erlang:system_time(nanosecond),
-    Fetcher = fun() -> hz_fetcher:connect(Node, Request, From, Timeout) end,
+    Fetcher =
+        case TLS of
+            true  -> fun() -> hz_fetcher:connect_slowly(Node, Request, From, Timeout) end;
+            false -> fun() -> hz_fetcher:connect(Node, Request, From, Timeout) end
+        end,
     {PID, Mon} = spawn_monitor(Fetcher),
     New = #fetcher{pid  = PID,
                    mon  = Mon,
@@ -267,15 +322,24 @@ do_request(Request,
                    node = Node,
                    from = From,
                    req  = Request},
-    State#s{fetchers = [New | Fetchers], chain_nodes = {Rest, [Node | Used]}};
+    State#s{fetchers = [New | Fetchers]}.
+
+
+do_request(_, From, State = #s{chain_nodes = {[], []}}) ->
+    ok = gen_server:reply(From, {error, no_nodes}),
+    State;
 do_request(Request,
            From,
-           State = #s{tls         = true,
+           State = #s{tls         = TLS,
                       fetchers    = Fetchers,
                       chain_nodes = {[Node | Rest], Used},
                       timeout     = Timeout}) ->
     Now = erlang:system_time(nanosecond),
-    Fetcher = fun() -> hz_fetcher:slowly_connect(Node, Request, From, Timeout) end,
+    Fetcher =
+        case TLS of
+            true  -> fun() -> hz_fetcher:connect_slowly(Node, Request, From, Timeout) end;
+            false -> fun() -> hz_fetcher:connect(Node, Request, From, Timeout) end
+        end,
     {PID, Mon} = spawn_monitor(Fetcher),
     New = #fetcher{pid  = PID,
                    mon  = Mon,
@@ -287,3 +351,9 @@ do_request(Request,
 do_request(Request, From, State = #s{chain_nodes = {[], Used}}) ->
     Fresh = lists:reverse(Used),
     do_request(Request, From, State#s{chain_nodes = {Fresh, []}}).
+
+
+log(Level, Format, Args) ->
+    Raw = io_lib:format("~w ~w: " ++ Format, [?MODULE, self() | Args]),
+    Entry = unicode:characters_to_list(Raw),
+    logger:log(Level, Entry).

src/hz_sup.erl

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

zomp.meta

@@ -2,12 +2,12 @@
 {type,app}.
 {modules,[]}.
 {prefix,"hz"}.
-{author,"Craig Everett"}.
 {desc,"Gajumaru interoperation library"}.
-{package_id,{"otpr","hakuzaru",{0,3,1}}}.
-{deps,[{"otpr","sophia",{8,0,1}},
+{author,"Craig Everett"}.
+{package_id,{"otpr","hakuzaru",{0,8,2}}}.
+{deps,[{"otpr","sophia",{9,0,0}},
+       {"otpr","gmserialization",{0,1,3}},
        {"otpr","gmbytecode",{3,4,1}},
-       {"otpr","gmserialization",{0,1,2}},
        {"otpr","base58",{0,1,1}},
        {"otpr","eblake2",{1,0,1}},
        {"otpr","ec_utils",{1,0,0}},
@@ -19,6 +19,6 @@
 {copyright,"Craig Everett"}.
 {file_exts,[]}.
 {license,"MIT"}.
-{repo_url,"https://gitlab.com/ioecs/hakuzaru"}.
+{repo_url,"https://git.qpq.swiss/QPQ-AG/hakuzaru"}.
 {tags,["qpq","gajumaru","blockchain","hakuzaru","crypto","defi"]}.
-{ws_url,"https://gitlab.com/ioecs/hakuzaru"}.
+{ws_url,"https://git.qpq.swiss/QPQ-AG/hakuzaru"}.