unwrap fate_to_erlang results

fate_to_erlang can only really fail at runtime if the wrong AACI is
provided, in which case the details of how failure occured are not
helpful, or recoverable. Anything else will be so broken that dialyzer
will catch it, or is a bug in hakuzaru, that we want to know about.

.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,5 +1,6 @@
-@author Craig Everett <craigeverett@qpq.swiss> [https://git.qpq.swiss/QPQ-AG/hakuzaru]
-@version 0.8.0
+@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
@@ -21,7 +22,7 @@ After startup `hz_man' must be given the address and port of a list of Gajumaru
 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.
 
 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`.
+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".
 
 The first node in the list of chain nodes provided during configuration is designated as the sticky node.

ebin/hakuzaru.app

@@ -3,7 +3,7 @@
               {included_applications,[]},
               {applications,[stdlib,kernel]},
               {description,"Gajumaru interoperation library"},
-              {vsn,"0.8.2"},
-              {modules,[hakuzaru,hz,hz_fetcher,hz_format,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.8.2").
+-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.8.2").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -45,7 +45,7 @@
          acc/1, acc_at_height/2, acc_at_block_id/2,
          acc_pending_txs/1,
          next_nonce/1,
-         dry_run/1, dry_run/2, dry_run/3, dry_run_map/1,
+         dry_run/1, dry_run/2, dry_run/3, % dry_run_map/1,
          tx/1, tx_info/1,
          post_tx/1,
          contract/1, contract_code/1, contract_source/1,
@@ -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>
@@ -272,8 +273,7 @@ chain_nodes() ->
 %% transactions are submitted is called the "sticky node". This is the first node
 %% (head position) in the list of nodes submitted to the chain when `chain_nodes/1'
 %% is called. If using multiple nodes but the sticky node should also be used for
-%% read-only queries, submit the sticky node at the head of the list and again in
-%% the tail.
+%% read-only queries, put the sticky node in the list twice.
 
 chain_nodes(List) when is_list(List) ->
     hz_man:chain_nodes(List).
@@ -284,7 +284,7 @@ chain_nodes(List) when is_list(List) ->
 %% Check whether TLS is in use. The typical situation is to not use TLS as nodes that
 %% serve as part of the backend of an application are typically run in the same
 %% backend network as the application service. When accessing chain nodes over the WAN
-%% however, TLS is strongly recommended to avoid a MITM attack.
+%% however, TLS is recommended to avoid a MitM attack.
 %%
 %% In this version of Hakuzaru TLS is either on or off for all nodes, making a mixed
 %% infrastructure complicated to support without two Hakuzaru instances. This will
@@ -299,7 +299,7 @@ tls() ->
 -spec tls(boolean()) -> ok.
 %% @doc
 %% Set TLS true or false. That's what a boolean is, by the way, `true' or `false'.
-%% This is a condescending comment. That means I am talking down to you.
+%% This is a condescending comment. That means to talk down to someone.
 %%
 %% TLS defaults to `false'.
 
@@ -343,7 +343,8 @@ timeout(MS) ->
 %% NOTE:
 %% This will return the currently synced height, which may be different than the
 %% actual current top of the entire chain if the node being queried is still syncing
-%% (has not yet caught up with the chain).
+%% (has not yet caught up with the chain). More complete information, including
+%% whether the node is currently syncing, can be gained from a `status()' query.
 
 top_height() ->
     case top_block() of
@@ -353,10 +354,10 @@ top_height() ->
 
 
 -spec top_block() -> {ok, TopBlock} | {error, Reason}
-    when TopBlock :: microblock_header(),
+    when TopBlock :: microblock_header() | keyblock(),
          Reason   :: chain_error().
 %% @doc
-%% Returns the current block height as an integer.
+%% Returns the header of the current top block.
 
 top_block() ->
     request("/v3/headers/top").
@@ -386,7 +387,7 @@ kb_current() ->
 kb_current_hash() ->
     case request("/v3/key-blocks/current/hash") of
         {ok, #{"reason" := Reason}} -> {error, Reason};
-        {ok, #{"hash" := Hash}}     -> {ok, Hash};
+        {ok, #{"hash"   := Hash}}   -> {ok, Hash};
         Error                       -> Error
     end.
 
@@ -444,10 +445,6 @@ kb_by_height(Height) ->
     result(request(["/v3/key-blocks/height/", StringN])).
 
 
-%kb_insert(KeyblockData) ->
-%    request("/v3/key-blocks", KeyblockData).
-
-
 -spec mb_header(ID) -> {ok, MB_Header} | {error, Reason}
     when ID        :: microblock_hash(),
          MB_Header :: microblock_header(),
@@ -607,12 +604,6 @@ next_nonce(AccountID) ->
         {ok, #{"reason" := Reason}}              -> {error, Reason};
         Error                                    -> Error
     end.
-%   case request_sticky(["/v3/accounts/", AccountID]) of
-%       {ok, #{"nonce"  := Nonce}}               -> {ok, Nonce + 1};
-%       {ok, #{"reason" := "Account not found"}} -> {ok, 1};
-%       {ok, #{"reason" := Reason}}              -> {error, Reason};
-%       Error                                    -> Error
-%   end.
 
 
 -spec dry_run(TX) -> {ok, Result} | {error, Reason}
@@ -671,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}
@@ -691,8 +683,10 @@ decode_bytearray_fate(EncodedStr) ->
     Encoded = unicode:characters_to_binary(EncodedStr),
     {contract_bytearray, Binary} = gmser_api_encoder:decode(Encoded),
     case Binary of
-        <<>> -> {ok, none};
-        <<"Out of gas">> -> {error, out_of_gas};
+        <<>> ->
+            {ok, none};
+        <<"Out of gas">> ->
+            {error, out_of_gas};
         _ ->
             % FIXME there may be other errors that are encoded directly into
             % the byte array. We could try and catch to at least return
@@ -791,20 +785,43 @@ contract_code(ID) ->
     end.
 
 
--spec contract_source(ID) -> {ok, Bytecode} | {error, Reason}
-    when ID       :: contract_id(),
-         Bytecode :: contract_byte_array(),
-         Reason   :: chain_error() | string().
+-spec contract_source(ID) -> Result
+    when ID     :: contract_id(),
+         Result :: {ok,      Source}
+                 | {project, Bundle}
+                 | {error,   Reason},
+         Source :: binary(),
+         Bundle :: [{FilePath :: string(), Contents :: binary()}],
+         Reason :: chain_error() | string().
 %% @doc
 %% Retrieve the code of a contract as represented on chain.
 
 contract_source(ID) ->
     case request(["/v3/contracts/", ID, "/source"]) of
-        {ok, #{"source" := Source}} -> {ok, Source};
+        {ok, #{"source" := Blobby}} -> extract(list_to_binary(Blobby));
         {ok, #{"reason" := Reason}} -> {error, Reason};
         Error                       -> Error
     end.
 
+extract(Blobby) ->
+    case gmser_api_encoder:safe_decode(bytearray, Blobby) of
+        {ok, TarBaby}             -> extract2(TarBaby);
+        {error, invalid_encoding} -> {ok, Blobby}
+    end.
+
+extract2(TarBaby) ->
+    case erl_tar:extract({binary, TarBaby}, [memory, compressed]) of
+        {ok, [{_, Source}]} ->
+            {ok, Source};
+        {ok, Bundle} ->
+            {project, Bundle};
+        {error,invalid_tar_checksum} ->
+            {ok, TarBaby};
+        Error ->
+            ok = io:format("erl_tar:extract/2 error: ~tp~n", [Error]),
+            {ok, TarBaby}
+    end.
+
 
 -spec contract_poi(ID) -> {ok, Bytecode} | {error, Reason}
     when ID       :: contract_id(),
@@ -884,6 +901,12 @@ request(Path) ->
     hz_man:request(unicode:characters_to_list(Path)).
 
 
+-spec request(Path, Payload) -> {ok, Value} | {error, Reason}
+    when Path    :: unicode:charlist(),
+         Payload :: unicode:charlist(),
+         Value   :: map(),
+         Reason  :: hz:chain_error().
+
 request(Path, Payload) ->
     hz_man:request(unicode:characters_to_list(Path), Payload).
 
@@ -908,7 +931,7 @@ result(Received)                    -> Received.
 %% @doc
 %% This function reads the source of a Sophia contract (an .aes file)
 %% and returns the unsigned create contract call data with default values.
-%% For more control over exactly what those values are, use create_contract/8.
+%% For more control over exactly what those values are, use contract_create/8.
 
 contract_create(CreatorID, Path, InitArgs) ->
     case next_nonce(CreatorID) of
@@ -919,7 +942,7 @@ contract_create(CreatorID, Path, InitArgs) ->
             Gas = 500000,
             GasPrice = min_gas_price(),
             contract_create(CreatorID, Nonce,
-                            Amount, TTL, Gas, GasPrice,
+                            Gas, GasPrice, Amount, TTL,
                             Path, InitArgs);
         Error ->
             Error
@@ -927,14 +950,14 @@ contract_create(CreatorID, Path, InitArgs) ->
 
 
 -spec contract_create(CreatorID, Nonce,
-                      Amount, TTL, Gas, GasPrice,
+                      Gas, GasPrice, Amount, TTL,
                       Path, InitArgs) -> Result
     when CreatorID :: pubkey(),
          Nonce     :: pos_integer(),
-         Amount    :: non_neg_integer(),
-         TTL       :: non_neg_integer(),
          Gas       :: pos_integer(),
          GasPrice  :: pos_integer(),
+         Amount    :: non_neg_integer(),
+         TTL       :: non_neg_integer(),
          Path      :: file:filename(),
          InitArgs  :: [string()]
                     | {erlang, [term()]}
@@ -971,24 +994,6 @@ contract_create(CreatorID, Path, InitArgs) ->
 %%   querying your Gajumaru node (via `hz:next_nonce(CallerID)', for example).
 %%  </li>
 %%  <li>
-%%   <b>Amount:</b>
-%%   All Gajumaru transactions can carry an "amount" spent from the origin account
-%%   (in this case the `CallerID') to the destination. In a "Spend" transaction this
-%%   is the only value that really matters, but in a contract call the utility is
-%%   quite different, as you can pay money <em>into</em> a contract and have that
-%%   contract hold it (for future payouts, to be held in escrow, as proof of intent
-%%   to purchase or engage in an auction, whatever). Typically this value is 0, but
-%%   of course there are very good reasons why it should be set to a non-zero value
-%%   in the case of calls related to contract-governed payment systems.
-%%  </li>
-%%  <li>
-%%   <b>TTL:</b>
-%%   This stands for "Time-To-Live", meaning the height beyond which this element is
-%%   considered to be eligible for garbage collection (and therefore inaccessible!).
-%%   The TTL can be extended by a "live extension" transaction (basically pay for the
-%%   data to remain alive longer).
-%%  </li>
-%%  <li>
 %%   <b>Gas:</b>
 %%   This number sets a limit on the maximum amount of computation the caller is willing
 %%   to pay for on the chain.
@@ -1021,6 +1026,24 @@ contract_create(CreatorID, Path, InitArgs) ->
 %%   transaction, thus making miners more likely to prioritize the high value ones.
 %%  </li>
 %%  <li>
+%%   <b>Amount:</b>
+%%   All Gajumaru transactions can carry an "amount" spent from the origin account
+%%   (in this case the `CallerID') to the destination. In a "Spend" transaction this
+%%   is the only value that really matters, but in a contract call the utility is
+%%   quite different, as you can pay money <em>into</em> a contract and have that
+%%   contract hold it (for future payouts, to be held in escrow, as proof of intent
+%%   to purchase or engage in an auction, whatever). Typically this value is 0, but
+%%   of course there are very good reasons why it should be set to a non-zero value
+%%   in the case of calls related to contract-governed payment systems.
+%%  </li>
+%%  <li>
+%%   <b>TTL:</b>
+%%   This stands for "Time-To-Live", meaning the height beyond which this element is
+%%   considered to be eligible for garbage collection (and therefore inaccessible!).
+%%   The TTL can be extended by a "live extension" transaction (basically pay for the
+%%   data to remain alive longer).
+%%  </li>
+%%  <li>
 %%   <b>ACI:</b>
 %%   This is the compiled contract's metadata. It provides the information necessary
 %%   for the contract call data to be formed in a way that the Gajumaru runtime will
@@ -1044,8 +1067,9 @@ contract_create(CreatorID, Path, InitArgs) ->
 %%  <li>
 %%   <b>Args:</b>
 %%   This is a list of the arguments to provide to the function, listed in order
-%%   according to the function's spec, and represented as strings (that is, an integer
-%%   argument of `10' must be cast to the textual representation `"10"').
+%%   according to the function's spec. Arguments can be represented as a list of
+%%   Sophia literals (a simple list of strings), or alternately as a list of compatible
+%%   Erlang, FATE or Sophia terms wrapped in a tuple which specifies the representation.
 %%  </li>
 %% </ul>
 %% As should be obvious from the above description, it is pretty helpful to have a
@@ -1053,9 +1077,10 @@ contract_create(CreatorID, Path, InitArgs) ->
 %% if you do not already have a copy, and can check the spec of a function before
 %% trying to form a contract call.
 
-contract_create(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Path, InitArgs) ->
+contract_create(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Path, InitArgs) ->
     case file:read_file(Path) of
         {ok, Source} ->
+            Name = filename:basename(Path),
             Dir = filename:dirname(Path),
             {ok, CWD} = file:get_cwd(),
             SrcDir = so_utils:canonical_dir(Path),
@@ -1064,18 +1089,19 @@ contract_create(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Path, InitArgs) ->
                  {src_file, Path},
                  {src_dir, SrcDir},
                  {include, {file_system, [CWD, so_utils:canonical_dir(Dir)]}}],
-            contract_create2(CreatorID, Nonce, Amount, TTL, Gas, GasPrice,
-                             Source, Options, InitArgs);
+            contract_create2(CreatorID, Nonce, Gas, GasPrice, Amount, TTL,
+                             Name, Source, Options, InitArgs);
         Error ->
             Error
     end.
 
 
-contract_create2(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Source, Options, InitArgs) ->
+contract_create2(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Name, Source, Options, InitArgs) ->
     case so_compiler:from_string(Source, Options) of
         {ok, Compiled} ->
-            contract_create_built(CreatorID, Nonce, Amount, TTL, Gas, GasPrice,
-                                  Compiled, InitArgs);
+            Named = maps:put(contract_name, Name, Compiled),
+            contract_create_built(CreatorID, Nonce, Gas, GasPrice, Amount, TTL,
+                                  Named, InitArgs);
         Error ->
             Error
     end.
@@ -1094,7 +1120,7 @@ contract_create2(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Source, Options,
 %% @doc
 %% This function takes the compiler output (instead of starting from source),
 %% and returns the unsigned create contract call data with default values.
-%% For more control over exactly what those values are, use create_contract/8.
+%% For more control over exactly what those values are, use contract_create/8.
 
 contract_create_built(CreatorID, Compiled, InitArgs) ->
     case next_nonce(CreatorID) of
@@ -1105,20 +1131,20 @@ contract_create_built(CreatorID, Compiled, InitArgs) ->
             Gas = 500000,
             GasPrice = min_gas_price(),
             contract_create_built(CreatorID, Nonce,
-                                  Amount, TTL, Gas, GasPrice,
+                                  Gas, GasPrice, Amount, TTL,
                                   Compiled, InitArgs);
         Error ->
             Error
     end.
 
 
--spec contract_create_built(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, InitArgs) -> Result
+-spec contract_create_built(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, InitArgs) -> Result
     when CreatorID :: unicode:chardata(),
          Nonce     :: pos_integer(),
-         Amount    :: non_neg_integer(),
-         TTL       :: non_neg_integer(),
          Gas       :: pos_integer(),
          GasPrice  :: pos_integer(),
+         Amount    :: non_neg_integer(),
+         TTL       :: non_neg_integer(),
          Compiled  :: map(),
          InitArgs  :: [string()]
                     | {erlang, [term()]}
@@ -1132,28 +1158,29 @@ contract_create_built(CreatorID, Compiled, InitArgs) ->
 %% The `Compiled' argument is the output of contract compilation and replaces the `File'
 %% argument in `contract_create/8'.
 
-contract_create_built(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, InitArgs) ->
+contract_create_built(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, InitArgs) ->
     AACI = hz_aaci:prepare(maps:get(aci, Compiled)),
     case encode_call_data(AACI, "init", InitArgs) of
         {ok, CallData} ->
-            assemble_calldata(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallData);
+            assemble_calldata(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData);
         Error ->
             Error
     end.
 
 
-assemble_calldata(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallData) ->
+assemble_calldata(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData) ->
     PK = unicode:characters_to_binary(CreatorID),
     try
         {account_pubkey, OwnerID} = gmser_api_encoder:decode(PK),
-        assemble_calldata2(OwnerID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallData)
+        assemble_calldata2(OwnerID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData)
     catch
-        Error:Reason -> {Error, Reason}
+        Error:Reason:Stack ->
+            {Error, {Reason, Stack}}
     end.
 
-assemble_calldata2(OwnerID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallData) ->
-    Code = gmser_contract_code:serialize(Compiled),
-    Source = unicode:characters_to_binary(maps:get(contract_source, Compiled, <<>>)),
+assemble_calldata2(OwnerID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData) ->
+    Compressed = #{contract_source := Bundle} = bundle_source(Compiled),
+    Code = gmser_contract_code:serialize(Compressed),
     VM = 1,
     ABI = 1,
     <<CTVersion:32>> = <<VM:16, ABI:16>>,
@@ -1163,7 +1190,7 @@ assemble_calldata2(OwnerID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallDat
         [{owner_id,   gmser_id:create(account, OwnerID)},
          {nonce,      Nonce},
          {code,       Code},
-         {source,     Source},
+         {source,     Bundle},
          {ct_version, CTVersion},
          {ttl,        TTL},
          {deposit,    0},
@@ -1190,6 +1217,43 @@ assemble_calldata2(OwnerID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallDat
         error:Reason -> {error, Reason}
     end.
 
+bundle_source(Compiled) ->
+    case maps:find(contract_source, Compiled) of
+        {ok, Source} -> bundle_source2(unicode:characters_to_binary(Source), Compiled);
+        error        -> <<>>
+    end.
+
+bundle_source2(Source, Compiled) ->
+    File = unicode:characters_to_list(maps:get(contract_name, Compiled, "contract.aes")),
+    TempDir = temp_dir(),
+    TgzName = File ++ ".tgz",
+    TarGzPath = filename:join(TempDir, TgzName),
+    ok = filelib:ensure_dir(TarGzPath),
+    {ok, CWD} = file:get_cwd(),
+    ok = file:set_cwd(TempDir),
+    ok = erl_tar:create(TarGzPath, [{File, Source}], [compressed]),
+    {ok, TgzBin} = file:read_file(TarGzPath),
+    ok = file:set_cwd(CWD),
+    ok = file:del_dir_r(TempDir),
+    {ok, Hash} = eblake2:blake2b(32, TgzBin),
+    Compiled#{contract_source => TgzBin, source_hash => Hash}.
+
+temp_dir() ->
+    case erlang:function_exported(zx_lib, path, 3) of
+        true ->
+            TS = integer_to_list(erlang:system_time()),
+            filename:join(zx_lib:path(tmp, "otpr", "hakuzaru"), TS);
+        false ->
+            temp_dir(os:type())
+    end.
+
+temp_dir({unix, _}) ->
+    string:trim(os:cmd("mktemp -d"));
+temp_dir({win32, _}) ->
+    Temp = os:getenv("TEMP"),
+    TS = integer_to_list(erlang:system_time()),
+    filename:join([Temp, "hakuzaru", TS]).
+
 
 -spec read_aci(Path) -> Result
     when Path   :: file:filename(),
@@ -1405,8 +1469,9 @@ contract_call(CallerID, Gas, AACI, ConID, Fun, Args) ->
 %%  <li>
 %%   <b>Args:</b>
 %%   This is a list of the arguments to provide to the function, listed in order
-%%   according to the function's spec, and represented as strings (that is, an integer
-%%   argument of `10' must be cast to the textual representation `"10"').
+%%   according to the function's spec. Arguments can be represented as a list of
+%%   Sophia literals (a simple list of strings), or alternately as a list of compatible
+%%   Erlang, FATE or Sophia terms wrapped in a tuple which specifies the representation.
 %%  </li>
 %% </ul>
 %% As should be obvious from the above description, it is pretty helpful to have a
@@ -1589,6 +1654,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
@@ -1596,6 +1669,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),
@@ -1615,10 +1697,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.
@@ -1645,6 +1738,23 @@ 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(),
+         NetworkID   :: unicode:chardata(),
+         Result      :: term(), % FIXME
+         Reason      :: chain_error() | string().
+%% @doc
+%% Forms a spend transaction and submits it to the chain.
+
 spend(SenderID,
       SecKey,
       RecipientID,
@@ -1655,7 +1765,7 @@ spend(SenderID,
       Nonce,
       Payload,
       NetworkID) ->
-    case decode_account_id(unicode:characters_to_binary(SenderID)) of
+    case gmser_api_encoder:safe_decode(account_pubkey, unicode:characters_to_binary(SenderID)) of
         {ok, DSenderID} ->
             spend2(gmser_id:create(account, DSenderID),
                    SecKey,
@@ -1699,11 +1809,10 @@ spend2(DSenderID,
 
 
 decode_account_id(B) ->
-    try
-        {account_pubkey, PK}  = gmser_api_encoder:decode(B),
-        {ok, PK}
-    catch
-        E:R -> {E, R}
+    case gmser_api_encoder:safe_decode(account_pubkey, B) of
+        {ok, PK}                -> {ok, PK};
+        {error, invalid_prefix} -> gmser_api_encoder:safe_decode(contract_pubkey, B);
+        Error                   -> Error
     end.
 
 
@@ -1758,6 +1867,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(),
@@ -1836,6 +1949,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(),
@@ -1850,6 +1969,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_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.8.2").
+-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.8.2").
+-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,8 +37,8 @@
 %%% @end
 
 -module(hz_grids).
--vsn("0.8.2").
--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
@@ -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.8.2").
-
+-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.8.2").
+-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_sophia.erl

@@ -1,22 +1,30 @@
 -module(hz_sophia).
--vsn("0.8.2").
+-vsn("0.9.2").
 -author("Jarvis Carroll <spiveehere@gmail.com>").
 -copyright("Jarvis Carroll <spiveehere@gmail.com>").
 -license("GPL-3.0-or-later").
 
--export([parse_literal/1, parse_literal/2]).
+-export([parse_literal/2, parse_literal/1]).
 -export([fate_to_list/1, fate_to_list/2, fate_to_iolist/1, fate_to_iolist/2]).
 
 -include_lib("eunit/include/eunit.hrl").
 
+-spec parse_literal(Type, Sophia) -> {ok, FATE} | {error, Reason}
+    when Type :: hz_aaci:annotated_type(),
+         Sophia :: string(),
+         FATE   :: gmb_fate_data:fate_type(),
+         Reason :: term().
 
--spec parse_literal(String) -> Result
-    when String :: string(),
-         Result :: {ok, gmb_fate_data:fate_type()}
-                 | {error, Reason :: term()}.
-
-parse_literal(String) ->
-    parse_literal(unknown_type(), String).
+%% @doc
+%% Parse a typed Sophia expression into a FATE term
+%% The Sophia expression must consist only of literals, thus making a 'Sophia
+%% term', which means no arithmetic, no function calls, no variables, etc.
+%% The FATE term is in the format that gmbytecode expects as input, for forming
+%% contract calls, etc. Used by the hz module to implement the 'sophia' format.
+%%
+%% The function takes type information retrieved from the AACI data structure,
+%% which is used to interpret record types and variant types, but is also used
+%% to check inputs and generate errors.
 
 parse_literal(Type, String) ->
     case parse_expression(Type, {1, 1}, String) of
@@ -37,6 +45,29 @@ parse_literal2(Result, Pos, String) ->
             {error, Reason}
     end.
 
+
+-spec parse_literal(Sophia) -> {ok, FATE} | {error, Reason}
+    when Sophia :: string(),
+         FATE   :: gmb_fate_data:fate_type(),
+         Reason :: term().
+
+%% @doc
+%% Parse an untyped Sophia expression into a FATE term
+%% Like `parse_literal/2', but will not produce type errors. This function can
+%% still produce parsing errors, and can produce errors when variants or
+%% records are encountered, since they can't be parsed unless you have type
+%% information.
+%%
+%% Note that since records are implemented as tuples, if you are trying to call
+%a function that you know takes a record, but you don't have type information
+%% available in the context where the expression is being passed, then tuples
+%% can be used instead. This does not work if you have type information,
+%% though, as tuples and records are different Sophia/AACI types.
+
+parse_literal(String) ->
+    parse_literal(unknown_type(), String).
+
+
 %%% Tokenizer
 
 -define(IS_LATIN_UPPER(C), (((C) >= $A) and ((C) =< $Z))).
@@ -222,6 +253,8 @@ escape_char($\") -> "\\\"";
 escape_char($\\) -> "\\\\";
 escape_char(I) -> I.
 
+
+
 %%% Sophia Literal Parser
 
 %%% This parser is a simple recursive descent parser, written explicitly in
@@ -310,6 +343,12 @@ parse_expression2(_, _, _, Token) ->
 unknown_type() ->
     {unknown_type, already_normalized, unknown_type}.
 
+int_type() ->
+    {integer, already_normalized, integer}.
+
+int_list_type() ->
+    {{list, [integer]}, alread_normalized, {list, [int_type()]}}.
+
 expect_tokens([], Pos, String) ->
     {ok, {Pos, String}};
 expect_tokens([Str | Rest], Pos, String) ->
@@ -344,11 +383,14 @@ parse_alphanum(Type, Pos, String, ["Bits", "all"], Row, Start, End) ->
     typecheck_bits(Type, Pos, String, -1, Row, Start, End);
 parse_alphanum(Type, Pos, String, ["Bits", "none"], Row, Start, End) ->
     typecheck_bits(Type, Pos, String, 0, Row, Start, End);
+parse_alphanum(Type, Pos, String, ["variant"], Row, Start, End) ->
+    parse_anonymous_variant(Type, Pos, String, Row, Start, End);
 parse_alphanum(Type, Pos, String, [[C | _] = S], Row, Start, End) when ?IS_LATIN_LOWER(C) ->
     % From a programming perspective, we are trying to parse a constant, so
     % an alphanum token can really only be a constructor, or a chain object.
-    % Constructors start with uppercase characters, so lowercase can only be a
-    % chain object.
+    % Constructors start with uppercase characters, and we have handled our
+    % made-up 'variant' case explicitly, so the only other lowercase constants
+    % are serialized chain objects.
     try
         case gmser_api_encoder:decode(unicode:characters_to_binary(S)) of
             {account_pubkey, Data} ->
@@ -367,8 +409,8 @@ parse_alphanum(Type, Pos, String, [[C | _] = S], Row, Start, End) when ?IS_LATIN
         _:_ -> {error, {unexpected_identifier, S, Row, Start, End}}
     end;
 parse_alphanum(Type, Pos, String, Path, Row, Start, End) ->
-    % Inversely, chain object prefixes are always lowercase, so any other path
-    % must be a variant constructor, or invalid.
+    % Now having handled all lowercase terms, anything else must be uppercase,
+    % which is either a variant constructor, or totally invalid.
     parse_variant(Type, Pos, String, Path, Row, Start, End).
 
 typecheck_integer({_, _, integer}, Pos, String, Value, _, _, _) ->
@@ -698,6 +740,12 @@ parse_variant({O, N, {variant, Variants}}, Pos, String, [Namespace, Constructor]
         _ ->
             {error, {invalid_constructor, O, N, Namespace ++ "." ++ Constructor, Row, Start, End}}
     end;
+parse_variant({_, _, unknown_type}, Pos, String, ["None"], _, _, _) ->
+    % Special case for None without type info.
+    parse_variant3([0, 1], 0, [], Pos, String);
+parse_variant({_, _, unknown_type}, Pos, String, ["Some"], _, _, _) ->
+    % Also a special case for Some.
+    parse_variant3([0, 1], 1, [unknown_type()], Pos, String);
 parse_variant({_, _, unknown_type}, _, _, _, Row, Start, End) ->
     {error, {unresolved_variant, Row, Start, End}};
 parse_variant({O, N, _}, _, _, _, Row, Start, End) ->
@@ -720,8 +768,7 @@ get_typename(Name) ->
 parse_variant2(O, N, Variants, Pos, String, Prefix, Constructor, Row, Start, End) ->
     case lookup_variant(Constructor, Variants, 0) of
         {ok, {Tag, ElemTypes}} ->
-            GetArity = fun({_, OtherElemTypes}) -> length(OtherElemTypes) end,
-            Arities = lists:map(GetArity, Variants),
+            Arities = get_arities(Variants),
             parse_variant3(Arities, Tag, ElemTypes, Pos, String);
         error ->
             {error, {invalid_constructor, O, N, Prefix ++ Constructor, Row, Start, End}}
@@ -757,6 +804,112 @@ lookup_variant(Ident, [{Ident, ElemTypes} | _], Tag) ->
 lookup_variant(Ident, [_ | Rest], Tag) ->
     lookup_variant(Ident, Rest, Tag + 1).
 
+get_arities(Variants) ->
+    GetArity = fun({_, OtherElemTypes}) -> length(OtherElemTypes) end,
+    lists:map(GetArity, Variants).
+
+parse_anonymous_variant({O, N, {variant, Variants}}, Pos, String, _, _, _) ->
+    parse_anonymous_variant2({O, N, {variant, Variants}}, Pos, String);
+parse_anonymous_variant({O, N, unknown_type}, Pos, String, _, _, _) ->
+    parse_anonymous_variant2({O, N, unknown_type}, Pos, String);
+parse_anonymous_variant({O, N, _}, _, _, Row, Start, End) ->
+    {error, {wrong_type, O, N, variant, Row, Start, End}}.
+
+parse_anonymous_variant2(Type, Pos, String) ->
+    case expect_tokens(["("], Pos, String) of
+        {ok, {NewPos, NewString}} ->
+            parse_anonymous_variant3(Type, NewPos, NewString);
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_anonymous_variant3(Type, Pos, String) ->
+    case parse_arities(Type, Pos, String) of
+        {ok, {Arities, NewPos, NewString}} ->
+            parse_anonymous_variant4(Type, NewPos, NewString, Arities);
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_anonymous_variant4(Type, Pos, String, Arities) ->
+    case expect_tokens([","], Pos, String) of
+        {ok, {NewPos, NewString}} ->
+            parse_anonymous_variant5(Type, NewPos, NewString, Arities);
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_anonymous_variant5(Type, Pos, String, Arities) ->
+    case parse_anonymous_tag(Pos, String, Arities) of
+        {ok, {Tag, NewPos, NewString}} ->
+            parse_anonymous_variant6(Type, NewPos, NewString, Arities, Tag);
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_anonymous_variant6(Type, Pos, String, Arities, Tag) ->
+    ElemTypes = infer_anonymous_variant_elem_types(Type, Arities, Tag),
+    case parse_multivalue3(ElemTypes, Pos, String, []) of
+        {ok, {Terms, NewPos, NewString}} ->
+            Result = {variant, Arities, Tag, list_to_tuple(Terms)},
+            {ok, {Result, NewPos, NewString}};
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_arities(Type, Pos, String) ->
+    case next_token(Pos, String) of
+        {ok, {Token, NewPos, NewString}} ->
+            parse_arities2(Type, NewPos, NewString, Token);
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_arities2(Type, Pos, String, Token = {_, _, _, Row, Start, _}) ->
+    case parse_expression2(int_list_type(), Pos, String, Token) of
+        {ok, {Arities, NewPos, NewString}} ->
+            parse_arities3(Type, NewPos, NewString, Arities, Row, Start);
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_arities3({O, N, {variant, Variants}}, Pos, String, Arities, Row, Start) ->
+    ExpectedArities = get_arities(Variants),
+    case Arities == ExpectedArities of
+        true ->
+            {ok, {Arities, Pos, String}};
+        false ->
+            {error, {wrong_arities, O, N, Arities, Row, Start}}
+    end;
+parse_arities3(_, Pos, String, Arities, _, _) ->
+    {ok, {Arities, Pos, String}}.
+
+parse_anonymous_tag(Pos, String, Arities) ->
+    case next_token(Pos, String) of
+        {ok, {Token, NewPos, NewString}} ->
+            parse_anonymous_tag2(NewPos, NewString, Arities, Token);
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+parse_anonymous_tag2(Pos, String, Arities, Token = {_, _, _, Row, Start, End}) ->
+    TagCount = length(Arities),
+    case parse_expression2(int_type(), Pos, String, Token) of
+        {ok, {Tag, _, _}} when Tag < 0 ->
+            {error, {negative_tag, Tag, Row, Start, End}};
+        {ok, {Tag, _, _}} when Tag >= TagCount ->
+            {error, {invalid_tag, Tag, TagCount, Row, Start, End}};
+        Result ->
+            Result
+    end.
+
+infer_anonymous_variant_elem_types({_, _, {variant, Variants}}, _, Tag) ->
+    {_Name, ElemTypes} = lists:nth(Tag + 1, Variants),
+    ElemTypes;
+infer_anonymous_variant_elem_types({_, _, unknown_type}, Arities, Tag) ->
+    Arity = lists:nth(Tag + 1, Arities),
+    lists:duplicate(Arity, unknown_type()).
+
 %%% Record parsing
 
 parse_record_or_map({_, _, {map, [KeyType, ValueType]}}, Pos, String, _, _) ->
@@ -917,16 +1070,69 @@ wrap_error(Reason, _) -> Reason.
 
 %%% Pretty Printing
 
+-spec fate_to_list(FATE) -> Sophia
+    when FATE   :: gmb_fate_data:fate_type(),
+         Sophia :: string().
+
+%% @doc
+%% Print a FATE term from gmbytecode in Sophia syntax
+%% FATE terms usually come from using gmbytecode to decode the result of an
+%% on-chain transaction.
+%%
+%% This function does not use any type information to interpret the data, and
+%% so can make mistakes. It's okay for interpreting tuples, lists, maps,
+%% integers, and strings, but it will misinterpret the types of records and
+%% unicode characters, and will crash the process if variants are encountered.
+%%
+%% `fate_to_list/2' should be used whenever possible, especially since
+%% transaction results are type checked by nodes at runtime.
+
 fate_to_list(Term) ->
     fate_to_list(unknown_type(), Term).
 
+-spec fate_to_list(Type, FATE) -> Sophia
+    when Type   :: hz_aaci:annotated_type(),
+         FATE   :: gmb_fate_data:fate_type(),
+         Sophia :: string().
+
+
+%% @doc
+%% Print a FATE term from gmbytecode in Sophia syntax
+%% Like `fate_to_list/1', but now type information from the AACI data structure
+%% can be provided, in order to correctly interpret types like records,
+%% variants, and unicode characters.  If the type information you provide is
+%% incorrect for the FATE term provided, then the function will fall back to
+%% untyped pretty printing like in fate_to_list/1, but this is not recommended,
+%% as correct type information should always be available.
+
 fate_to_list(Type, Term) ->
     IOList = fate_to_iolist(Type, Term),
     unicode:characters_to_list(IOList).
 
+%% @doc
+%% Print a FATE term in Sophia syntax, without concatenating
+%% The `fate_to_list/1' function builds an iolist, and then concatenates it into
+%% a list. If you are going to put the term into a bigger iolist directly
+%% after, or write it to a streaming device, then it can save effort and memory
+%% to just use the iolist directly.
+
+-spec fate_to_iolist(FATE) -> Sophia
+    when FATE   :: gmb_fate_data:fate_type(),
+         Sophia :: iolist().
+
 fate_to_iolist(Term) ->
     fate_to_iolist(unknown_type(), Term).
 
+-spec fate_to_iolist(Type, FATE) -> Sophia
+    when Type   :: hz_aaci:annotated_type(),
+         FATE   :: gmb_fate_data:fate_type(),
+         Sophia :: iolist().
+
+%% @doc
+%% Print a FATE term in Sophia syntax, without concatenating
+%% Prints using type information, like `fate_to_list/2', but without spending
+%% time or memory concatenating the result into a list, like fate_to_iolist/1.
+
 % Special case for singleton records, since they are erased during compilation.
 fate_to_iolist({_, _, {record, [{FieldName, FieldType}]}}, Term) ->
     singleton_record_to_iolist(FieldName, FieldType, Term);
@@ -941,15 +1147,12 @@ fate_to_iolist(Type, {tuple, Tuple}) ->
         _ ->
             tuple_to_iolist([], Tuple)
     end;
-fate_to_iolist(Type, {variant, _, Tag, Tuple}) ->
+fate_to_iolist(Type, {variant, Arities, Tag, Tuple}) ->
     case Type of
         {O, N, {variant, VariantTypes}} when Tag < length(VariantTypes) ->
             variant_to_iolist(O, N, VariantTypes, Tag, Tuple);
-        {O, N, _} ->
-            % TODO: Make up a special syntax for anonymous variant terms.
-            erlang:exit({untyped_variant, O, N});
-        _ ->
-            erlang:exit({untyped_variant, unknown_type, already_normalized})
+        {_, _, _} ->
+            anonymous_variant_to_iolist(Arities, Tag, Tuple)
     end;
 fate_to_iolist(Type, List) when is_list(List) ->
     case Type of
@@ -1044,6 +1247,22 @@ choose_variant_prefix(O, N) ->
             []
     end.
 
+% We don't have type information, but the Sophia programming language doesn't
+% have syntax for anonymous variants, so we have to make a syntax up. This
+% syntax is also supported when parsing terms, so that the output of one
+% contract call can be fed easily into another contract call.
+anonymous_variant_to_iolist(Arities, Tag, Tuple) ->
+    % Extract the elements of the tuple.
+    Elems = tuple_to_list(Tuple),
+
+    % Turn the arities, tag, and elements into an iolist.
+    AritiesStr = list_to_iolist(int_type(), Arities),
+    TagStr = integer_to_list(Tag),
+    FullTermsStr = list_elems_to_iolist(unknown_type(), Elems, [AritiesStr, ", ", TagStr]),
+
+    % Wrap that iolist in the anonymous 'variant' constructor.
+    ["variant(", FullTermsStr, ")"].
+
 multivalue_to_iolist([FirstType | ElemTypes], [FirstTerm | Elems]) ->
     FirstTermChars = fate_to_iolist(FirstType, FirstTerm),
     multivalue_to_iolist(ElemTypes, Elems, FirstTermChars);
@@ -1196,16 +1415,18 @@ check_parser_roundtrip(Sophia) ->
     % syntax. Let's do a lenient test.
     roundtrip_parser_lenient(unknown_type(), Sophia, Fate).
 
-check_parser_with_typedef(Typedef, Sophia) ->
+check_parser_with_typedef(Typedef, Sophia, UntypedSophia) ->
     % Compile the type definitions alongside the usual literal expression.
     Source = "contract C =\n  " ++ Typedef ++ "\n  entrypoint f() = " ++ Sophia,
     {Fate, Type} = compile_entrypoint_value_and_type(Source, "f"),
 
-    % Do a typed parse, as usual, but there are probably record/variant
-    % definitions in the AACI, so untyped parses probably don't work, and
-    % variants often have optional namespaces, so the sophia result might not
-    % match exactly, but should still be equivalent.
-    roundtrip_parser_lenient(Type, Sophia, Fate).
+    % Do a typed parse, as usual. Variant namespaces can make pretty printing
+    % ambiguous, so make the roundtrip lenient.
+    roundtrip_parser_lenient(Type, Sophia, Fate),
+    % Do an untyped parse, but using a second special Sophia expression that
+    % doesn't require type info to parse. This one *doesn't* need to be
+    % lenient, since we are specifying a distinct sophia expression.
+    roundtrip_parser(unknown_type(), UntypedSophia, Fate).
 
 anon_types_test() ->
     % Integers.
@@ -1237,6 +1458,10 @@ anon_types_test() ->
     check_parser_roundtrip("(1, [2, 3], (4, 5))"),
     % Map.
     check_parser_roundtrip("{[1] = 2, [3] = 4}"),
+    % Option.
+    check_parser_roundtrip("None"),
+    check_parser_roundtrip("Some(1)"),
+    check_parser_roundtrip("Some([1, 2, 3])"),
 
     ok.
 
@@ -1256,7 +1481,7 @@ string_escape_codes_test() ->
 records_test() ->
     TypeDef = "record pair = {x: int, y: int}",
     Sophia = "{x = 1, y = 2}",
-    check_parser_with_typedef(TypeDef, Sophia),
+    check_parser_with_typedef(TypeDef, Sophia, "(1, 2)"),
     % The above won't run an untyped parse on the expression, but we can. It
     % will error, though.
     {error, {unresolved_record, _, _, _}} = parse_literal(unknown_type(), Sophia).
@@ -1264,11 +1489,11 @@ records_test() ->
 variant_test() ->
     TypeDef = "datatype multi('a) = Zero | One('a) | Two('a, 'a)",
 
-    check_parser_with_typedef(TypeDef, "Zero"),
-    check_parser_with_typedef(TypeDef, "One(0)"),
-    check_parser_with_typedef(TypeDef, "Two(0, 1)"),
-    check_parser_with_typedef(TypeDef, "Two([], [1, 2, 3])"),
-    check_parser_with_typedef(TypeDef, "C.Zero"),
+    check_parser_with_typedef(TypeDef, "Zero", "variant([0, 1, 2], 0)"),
+    check_parser_with_typedef(TypeDef, "One(0)", "variant([0, 1, 2], 1, 0)"),
+    check_parser_with_typedef(TypeDef, "Two(0, 1)", "variant([0, 1, 2], 2, 0, 1)"),
+    check_parser_with_typedef(TypeDef, "Two([], [1, 2, 3])", "variant([0, 1, 2], 2, [], [1, 2, 3])"),
+    check_parser_with_typedef(TypeDef, "C.Zero", "variant([0, 1, 2], 0)"),
 
     {error, {unresolved_variant, _, _, _}} = parse_literal(unknown_type(), "Zero"),
 
@@ -1276,10 +1501,10 @@ variant_test() ->
 
 ambiguous_variant_test() ->
     TypeDef = "datatype mytype = C | D",
-    check_parser_with_typedef(TypeDef, "C"),
-    check_parser_with_typedef(TypeDef, "D"),
-    check_parser_with_typedef(TypeDef, "C.C"),
-    check_parser_with_typedef(TypeDef, "C.D"),
+    check_parser_with_typedef(TypeDef, "C", "variant([0, 0], 0)"),
+    check_parser_with_typedef(TypeDef, "D", "variant([0, 0], 1)"),
+    check_parser_with_typedef(TypeDef, "C.C", "variant([0, 0], 0)"),
+    check_parser_with_typedef(TypeDef, "C.D", "variant([0, 0], 1)"),
 
     ok.
 
@@ -1324,9 +1549,9 @@ bits_test() ->
 
 singleton_records_test() ->
     TypeDef = "record singleton('a) = {it: 'a}",
-    check_parser_with_typedef(TypeDef, "{it = 123}"),
-    check_parser_with_typedef(TypeDef, "{it = {it = {it = 5}}}"),
-    check_parser_with_typedef(TypeDef, "[{it = 1}, {it = 2}, {it = 3}]"),
+    check_parser_with_typedef(TypeDef, "{it = 123}", "123"),
+    check_parser_with_typedef(TypeDef, "{it = {it = {it = 5}}}", "5"),
+    check_parser_with_typedef(TypeDef, "[{it = 1}, {it = 2}, {it = 3}]", "[1, 2, 3]"),
 
     ok.
 
@@ -1335,9 +1560,9 @@ singleton_variants_test() ->
     % actually a special case; singleton variants are in fact wrapped in the
     % FATE too.
     TypeDef = "datatype wrapped('a) = Wrap('a)",
-    check_parser_with_typedef(TypeDef, "Wrap(123)"),
-    check_parser_with_typedef(TypeDef, "Wrap(Wrap(123))"),
-    check_parser_with_typedef(TypeDef, "[Wrap(1), Wrap(2), Wrap(3)]"),
+    check_parser_with_typedef(TypeDef, "Wrap(123)", "variant([1], 0, 123)"),
+    check_parser_with_typedef(TypeDef, "Wrap(Wrap(123))", "variant([1], 0, variant([1], 0, 123))"),
+    check_parser_with_typedef(TypeDef, "[Wrap(1), Wrap(2), Wrap(3)]", "[variant([1], 0, 1), variant([1], 0, 2), variant([1], 0, 3)]"),
 
     ok.
 
@@ -1430,6 +1655,6 @@ singleton_test() ->
 
     % Also if we wanted an integer, the singleton is NOT dropped, so is also an
     % error.
-    {error, {expected_close_paren, 1, 3}} = parse_literal({integer, alread_normalized, integer}, "(1,)"),
+    {error, {expected_close_paren, 1, 3}} = parse_literal({integer, already_normalized, integer}, "(1,)"),
 
     ok.

src/hz_sup.erl

@@ -9,7 +9,7 @@
 %%% @end
 
 -module(hz_sup).
--vsn("0.8.2").
+-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,8,2}}}.
+{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}},