Adjust error condition

I changed it from noting the index to just noting the field name, but
actually both pieces of information are important, since if there was
a type error, presumably the type information is actually wrong.

Now we put the index first, since that is the part of the FATE tuple
that failed, and then the field name that that would be if the type
information were correct, in case that is useful.

doc/overview.edoc

@@ -1,5 +1,5 @@
 @author Craig Everett <craigeverett@qpq.swiss> [https://git.qpq.swiss/QPQ-AG/hakuzaru]
-@version 0.9.1
+@version 0.9.2
 @title Hakuzaru: Gajumaru blockchain bindings for Erlang
 
 @doc

ebin/hakuzaru.app

@@ -3,7 +3,7 @@
               {included_applications,[]},
               {applications,[stdlib,kernel]},
               {description,"Gajumaru interoperation library"},
-              {vsn,"0.9.1"},
+              {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.9.1").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").

src/hz.erl

@@ -23,7 +23,7 @@
 %%% @end
 
 -module(hz).
--vsn("0.9.1").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -125,13 +125,14 @@
 %   "info"          => contract_byte_array(),
 %   "miner"         => account_id(),
 %   "nonce"         => non_neg_integer(),
-%   "pow"           => [non_neg_integer()],
 %   "prev_hash"     => microblock_hash(),
 %   "prev_key_hash" => keyblock_hash(),
+%   "seal"          => #{"data" => [int()],
+%                        "signature" => signature()}
 %   "state_hash"    => block_state_hash(),
 %   "target"        => non_neg_integer(),
 %   "time"          => non_neg_integer(),
-%   "version"       => 5}.
+%   "version"       => 1}.
 % </pre>
 -type microblock_header()   :: #{string() => term()}.
 % <pre>
@@ -353,7 +354,7 @@ top_height() ->
 
 
 -spec top_block() -> {ok, TopBlock} | {error, Reason}
-    when TopBlock :: microblock_header(),
+    when TopBlock :: microblock_header() | keyblock(),
          Reason   :: chain_error().
 %% @doc
 %% Returns the header of the current top block.
@@ -661,9 +662,10 @@ dry_run(TX, Accounts, KBHash) ->
     request("/v3/dry_run", JSON).
 
 
-dry_run_map(Map) ->
-    JSON = zj:binary_encode(Map),
-    request("/v3/dry_run", JSON).
+% TODO
+%dry_run_map(Map) ->
+%    JSON = zj:binary_encode(Map),
+%    request("/v3/dry_run", JSON).
 
 
 -spec decode_bytearray_fate(EncodedStr) -> {ok, Result} | {error, Reason}
@@ -811,8 +813,10 @@ extract2(TarBaby) ->
     case erl_tar:extract({binary, TarBaby}, [memory, compressed]) of
         {ok, Bundle} ->
             {project, Bundle};
+        {error,invalid_tar_checksum} ->
+            {ok, TarBaby};
         Error ->
-            io:format("Dis chit happen: ~tp~n", [Error]),
+            ok = io:format("erl_tar:extract/2 error: ~tp~n", [Error]),
             {ok, TarBaby}
     end.
 
@@ -1642,6 +1646,14 @@ convert([], [], _, Terms, []) ->
 convert([], [], _, _, Errors) ->
     {error, Errors}.
 
+-spec sign_tx(Unsigned, SecKey) -> Result
+    when Unsigned :: string(),
+         SecKey   :: binary(),
+         Result   :: {ok, SignedTX} | {error, Reason},
+         SignedTX :: binary(),
+         Reason   :: chain_error().
+%% @doc
+%% Signs transaction data with the provided secret key for the currently selected network.
 
 sign_tx(Unsigned, SecKey) ->
     case network_id() of
@@ -1649,6 +1661,15 @@ sign_tx(Unsigned, SecKey) ->
         Error           -> Error
     end.
 
+
+-spec sign_tx(Unsigned, SecKey, NetworkID) -> SignedTX
+    when Unsigned  :: string(),
+         SecKey    :: binary(),
+         NetworkID :: string(),
+         SignedTX  :: binary().
+%% @doc
+%% Signs transaction data with the provided secret key using the provided network ID.
+
 sign_tx(Unsigned, SecKey, MNetworkID) ->
     UnsignedBin = unicode:characters_to_binary(Unsigned),
     NetworkID   = unicode:characters_to_binary(MNetworkID),
@@ -1668,10 +1689,21 @@ sign_tx(Unsigned, SecKey, MNetworkID) ->
     gmser_api_encoder:encode(transaction, SignedTX).
 
 
-spend(SenderID, SecKey, ReceipientID, Amount, Payload) ->
+-spec spend(SenderID, SecKey, RecipientID, Amount, Payload) -> {ok, Result} | {error, Reason}
+    when SenderID    :: string(),
+         SecKey      :: binary(),
+         RecipientID :: string(),
+         Amount      :: non_neg_integer(),
+         Payload     :: binary(),
+         Result      :: term(), % FIXME
+         Reason      :: chain_error() | string().
+%% @doc
+%% Forms a spend transaction and submits it to the chain.
+
+spend(SenderID, SecKey, RecipientID, Amount, Payload) ->
     case status() of
         {ok, #{"top_block_height" := Height, "network_id" := NetworkID}} ->
-            spend(SenderID, SecKey, ReceipientID, Amount, Payload, Height, NetworkID);
+            spend(SenderID, SecKey, RecipientID, Amount, Payload, Height, NetworkID);
         Error  ->
             Error
     end.
@@ -1698,6 +1730,22 @@ spend(SenderID, SecKey, RecipientID, Amount, Payload, Height, NetworkID) ->
     end.
 
 
+-spec spend(SenderID, SecKey, RecipientID, Amount,
+            GasPrice, Gas, TTL, Nonce, Payload, NetworkID) -> {ok, Result} | {error, Reason}
+    when SenderID    :: string(),
+         SecKey      :: binary(),
+         RecipientID :: string(),
+         Amount      :: non_neg_integer(),
+         GasPrice    :: pos_integer(),
+         Gas         :: pos_integer(),
+         TTL         :: non_neg_integer(),
+         Nonce       :: non_neg_integer(),
+         Payload     :: binary(),
+         Result      :: term(), % FIXME
+         Reason      :: chain_error() | string().
+%% @doc
+%% Forms a spend transaction and submits it to the chain.
+
 spend(SenderID,
       SecKey,
       RecipientID,
@@ -1810,6 +1858,10 @@ spend3(DSenderID,
     when Message :: binary(),
          SecKey  :: binary(),
          Sig     :: binary().
+%% @doc
+%% Accepts a string to be signed, prepends the prefix `"Gajumaru Signed Message:\n"',
+%% encodes the string with `vencode/1', then hashes the encoded message and signs the
+%% hash.
 
 sign_message(Message, SecKey) ->
     Prefix = message_sig_prefix(),
@@ -1888,6 +1940,12 @@ eu(N, Size) ->
     when Binary :: binary(),
          SecKey :: binary(),
          Sig    :: binary().
+%% @doc
+%% This procedure signs an arbitrary binary blob with a special binary prefix
+%% attached. The reason for the binary prefix is to prevent signing of dangerous
+%% binaries which could be used to authorized dangerous actions on chain.
+%% The signature target becomes: `<<"Gajumaru Signed Binary:", Binary/binary>>'
+%% before being hashed, and then the resulting hash is signed.
 
 sign_binary(Binary, SecKey) ->
     Prefix = binary_sig_prefix(),
@@ -1902,6 +1960,8 @@ sign_binary(Binary, SecKey) ->
          PubKey  :: pubkey(),
          Result  :: {ok, Outcome :: boolean()}
                   | {error, Reason :: term()}.
+%% @doc
+%% Verifies a signature created with the `sign_binary/2' function.
 
 verify_bin_signature(Sig, Binary, PubKey) ->
     case gmser_api_encoder:decode(PubKey) of

src/hz_aaci.erl

@@ -10,7 +10,7 @@
 %%% @end
 
 -module(hz_aaci).
--vsn("0.9.1").
+-vsn("0.9.2").
 -author("Jarvis Carroll <spiveehere@gmail.com>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -796,6 +796,10 @@ coerce_map_to_record(O, N, MemberTypes, Map) ->
     case zip_record_fields(MemberTypes, Map) of
         {ok, Zipped} ->
             case coerce_zipped_bindings(Zipped, to_fate, field) of
+                {ok, [SingleElem]} ->
+                    % Singleton records aren't implemented as FATE tuples at
+                    % all.
+                    {ok, SingleElem};
                 {ok, Converted} ->
                     {ok, {tuple, list_to_tuple(Converted)}};
                 Errors ->
@@ -821,10 +825,18 @@ coerce_record_to_map(O, N, MemberTypes, Tuple) ->
             single_error({record_too_few_terms, O, N, Tuple});
         {error, too_many_terms} ->
             single_error({record_too_many_terms, O, N, Tuple});
-        Errors ->
-            Errors
+        {error, Errors} ->
+            correct_record_error_paths(Names, Errors)
     end.
 
+correct_record_error_paths(Names, Errors) ->
+    CorrectOne = fun({Error, [{record_element, N} | Path]}) ->
+                     FieldName = lists:nth(N + 1, Names),
+                     {Error, [{record_element, N, FieldName} | Path]}
+                 end,
+    Corrected = lists:map(CorrectOne, Errors),
+    {error, Corrected}.
+
 zip_record_fields(Fields, Map) ->
     case lists:mapfoldl(fun zip_record_field/2, {Map, []}, Fields) of
         {_, {_, Missing = [_|_]}} ->
@@ -915,6 +927,11 @@ fate_to_erlang({O, N, {variant, Variants}}, {variant, _, Tag, Tuple}) ->
     Terms = tuple_to_list(Tuple),
     {Name, TermTypes} = lists:nth(Tag + 1, Variants),
     coerce_variant2(O, N, Variants, Name, Tag, TermTypes, Terms, from_fate);
+fate_to_erlang({O, N, {record, [SingleMemberType]}}, Data) ->
+    % Singleton records aren't implemented as FATE tuples at all.
+    % Pretend they are, so we can get the full error indexing of the
+    % non-singletone case.
+    coerce_record_to_map(O, N, [SingleMemberType], {Data});
 fate_to_erlang({O, N, {record, MemberTypes}}, {tuple, Tuple}) ->
     coerce_record_to_map(O, N, MemberTypes, Tuple);
 fate_to_erlang({O, N, {unknown_type, _}}, Data) ->
@@ -927,15 +944,30 @@ fate_to_erlang({O, N, {unknown_type, _}}, Data) ->
             io:format(Message, [O, N, Data])
     end,
     {ok, Data};
-fate_to_erlang({O, N, _}, Data) ->
-    case N of
-        already_normalized ->
-            io:format("Warning: Unimplemented type ~p.~nUsing term as is:~n~p~n", [O, Data]);
-        _ ->
-            io:format("Warning: Unimplemented type ~p (i.e. ~p).~nUsing term as is:~n~p~n", [O, N, Data])
-    end,
+fate_to_erlang(Type, Data) ->
+    TypeStr = type_to_iolist(Type),
+    io:format("Warning: Could not coerce term into ~s. Using term as is: ~p~n", [TypeStr, Data]),
     {ok, Data}.
 
+type_to_iolist({O, already_normalized, S}) ->
+    % Already normalized. Example output:
+    %    type {map, [string, integer]}
+    opaque_type_to_iolist(O, S);
+type_to_iolist({O, N, S}) ->
+    % Type alias. Print the alias, and then print the normalized version in
+    % parentheses. Example output:
+    %    type "my_alias" (i.e. record type {"my_record_type", [integer]})
+    io_lib:format("type ~p (i.e. ~s)", [O, opaque_type_to_iolist(N, S)]).
+
+opaque_type_to_iolist(N, {record, _}) ->
+    % N is the name of a record definition.
+    io_lib:format("record type ~p", [N]);
+opaque_type_to_iolist(N, {variant, _}) ->
+    % N is the name of a variant definition.
+    io_lib:format("variant type ~p", [N]);
+opaque_type_to_iolist(N, _) ->
+    % N is some other constructive type.
+    io_lib:format("type ~p", [N]).
 
 
 %%% AACI Getters
@@ -1120,6 +1152,25 @@ record_substitution_test() ->
     {ok, {[], Output}} = get_function_signature(AACI, "f"),
     check_roundtrip(Output, #{"a" => 123, "b" => 456}, {tuple, {123, 456}}).
 
+singleton_record_substitution_test() ->
+    Contract = "
+        contract C =
+            record single('t) = { it: 't }
+            entrypoint f(): single(int) = { it = 1 }
+            entrypoint g(): single(single(int)) = { it = { it = 2 } }
+            entrypoint h(): single(int * int) = { it = (3, 4) }
+    ",
+    {ok, AACI} = aaci_from_string(Contract),
+    {ok, {[], FOutput}} = get_function_signature(AACI, "f"),
+    check_roundtrip(FOutput, #{"it" => 123}, 123),
+    {ok, {[], GOutput}} = get_function_signature(AACI, "g"),
+    check_roundtrip(GOutput, #{"it" => #{"it" => 123}}, 123),
+    {ok, {[], HOutput}} = get_function_signature(AACI, "h"),
+    check_roundtrip(HOutput, #{"it" => {123, 456}}, {tuple, {123, 456}}),
+    % Also check that records have accurate paths, since the implementation for
+    % record error paths is a bit fiddly.
+    {error, [{{tuple_too_many_terms, _, _, _}, [{record_element, 0, "it"}]}]} = fate_to_erlang(HOutput, {tuple, {1, 2, 3}}).
+
 tuple_substitution_test() ->
     Contract = "
         contract C =

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.9.1").
+-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.9.1").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -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.
 

src/hz_grids.erl

@@ -37,7 +37,7 @@
 %%% @end
 
 -module(hz_grids).
--vsn("0.9.1").
+-vsn("0.9.2").
 -export([url/2, url/3, url/4, parse/1, req/2, req/3, req/4]).
 
 
@@ -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
@@ -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,13 +192,43 @@ 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).
 
+
+-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",

src/hz_key_master.erl

@@ -8,7 +8,7 @@
 %%% @end
 
 -module(hz_key_master).
--vsn("0.9.1").
+-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.9.1").
+-vsn("0.9.2").
 -behavior(gen_server).
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").

src/hz_sophia.erl

@@ -1,5 +1,5 @@
 -module(hz_sophia).
--vsn("0.9.1").
+-vsn("0.9.2").
 -author("Jarvis Carroll <spiveehere@gmail.com>").
 -copyright("Jarvis Carroll <spiveehere@gmail.com>").
 -license("GPL-3.0-or-later").

src/hz_sup.erl

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

zomp.meta

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