Replace case with a simpler assertion

Reviewed-on: #31

.gitignore

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

doc/custom/stylesheet.css

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

doc/overview.edoc

@@ -1,5 +1,6 @@
-@author Craig Everett <craigeverett@qpq.swiss> [https://git.qpq.swiss/QPQ-AG/hakuzaru]
+@author Craig Everett <craigeverett@qpq.swiss> [https://zxq9.com]
-@version 0.8.0
+@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"},
+              {vsn,"0.9.2"},
-              {modules,[hakuzaru,hz,hz_fetcher,hz_format,hz_grids,
+              {modules,[hakuzaru,hz,hz_aaci,hz_fetcher,hz_format,hz_grids,
-                        hz_key_master,hz_man,hz_sup]},
+                        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,
@@ -71,7 +71,7 @@
          contract_call/5,
          contract_call/6,
          contract_call/10,
-         decode_bytearray_fate/1, decode_bytearray/2,
+         decode_bytearray/2,
          spend/5, spend/10,
          sign_tx/2, sign_tx/3,
          sign_message/2, verify_signature/3,
@@ -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
+%% read-only queries, put the sticky node in the list twice.
-%% the tail.
 
 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) ->
+% TODO
-    JSON = zj:binary_encode(Map),
+%dry_run_map(Map) ->
-    request("/v3/dry_run", JSON).
+%    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
@@ -701,8 +695,9 @@ decode_bytearray_fate(EncodedStr) ->
             {ok, Object}
     end.
 
--spec decode_bytearray(Type, EncodedStr) -> {ok, Result} | {error, Reason}
+-spec decode_bytearray(EncodedStr, Format) -> {ok, Result} | {error, Reason}
-    when Type       :: term(),
+    when Format     :: fate | sophia | {sophia, Type} | {erlang, Type},
+         Type       :: term(),
          EncodedStr :: binary() | string(),
          Result     :: none | term(),
          Reason     :: term().
@@ -713,13 +708,18 @@ decode_bytearray_fate(EncodedStr) ->
 %% must be the result type of the same function in the same AACI that was used
 %% to create the transaction that EncodedStr came from.
 
-decode_bytearray(Type, EncodedStr) ->
+decode_bytearray(EncodedStr, Format) ->
     case decode_bytearray_fate(EncodedStr) of
         {ok, none} -> {ok, none};
-        {ok, Object} -> hz_aaci:fate_to_erlang(Type, Object);
+        {ok, FATE} -> decode_bytearray2(FATE, Format);
         {error, Reason} -> {error, Reason}
     end.
 
+decode_bytearray2(FATE, fate)           -> FATE;
+decode_bytearray2(FATE, sophia)         -> hz_sophia:fate_to_list(FATE);
+decode_bytearray2(FATE, {sophia, Type}) -> hz_sophia:fate_to_list(Type, FATE);
+decode_bytearray2(FATE, {erlang, Type}) -> hz_aaci:fate_to_erlang(Type, FATE).
+
 to_binary(S) when is_binary(S) -> S;
 to_binary(S) when is_list(S)   -> list_to_binary(S).
 
@@ -785,20 +785,43 @@ contract_code(ID) ->
     end.
 
 
--spec contract_source(ID) -> {ok, Bytecode} | {error, Reason}
+-spec contract_source(ID) -> Result
-    when ID       :: contract_id(),
+    when ID     :: contract_id(),
-         Bytecode :: contract_byte_array(),
+         Result :: {ok,      Source}
-         Reason   :: chain_error() | string().
+                 | {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(),
@@ -878,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).
 
@@ -892,14 +921,17 @@ result(Received)                    -> Received.
 -spec contract_create(CreatorID, Path, InitArgs) -> Result
     when CreatorID :: unicode:chardata(),
          Path      :: file:filename(),
-         InitArgs  :: [string()],
+         InitArgs  :: [string()]
+                    | {erlang, [term()]}
+                    | {fate,   [term()]}
+                    | {sophia, [string()]},
          Result    :: {ok, CreateTX} | {error, Reason},
          CreateTX  :: binary(),
          Reason    :: file:posix() | term().
 %% @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
@@ -910,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
@@ -918,16 +950,19 @@ 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()],
+         InitArgs  :: [string()]
+                    | {erlang, [term()]}
+                    | {fate,   [term()]}
+                    | {sophia, [string()]},
          Result    :: {ok, CreateTX} | {error, Reason},
          CreateTX  :: binary(),
          Reason    :: term().
@@ -959,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.
@@ -1009,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
@@ -1032,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
+%%   according to the function's spec. Arguments can be represented as a list of
-%%   argument of `10' must be cast to the textual representation `"10"').
+%%   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
@@ -1041,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),
@@ -1052,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,
+            contract_create2(CreatorID, Nonce, Gas, GasPrice, Amount, TTL,
-                             Source, Options, InitArgs);
+                             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,
+            Named = maps:put(contract_name, Name, Compiled),
-                                  Compiled, InitArgs);
+            contract_create_built(CreatorID, Nonce, Gas, GasPrice, Amount, TTL,
+                                  Named, InitArgs);
         Error ->
             Error
     end.
@@ -1072,14 +1110,17 @@ contract_create2(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Source, Options,
 -spec contract_create_built(CreatorID, Compiled, InitArgs) -> Result
     when CreatorID :: unicode:chardata(),
          Compiled  :: map(),
-         InitArgs  :: [string()],
+         InitArgs  :: [string()]
+                    | {erlang, [term()]}
+                    | {fate,   [term()]}
+                    | {sophia, [string()]},
          Result    :: {ok, CreateTX} | {error, Reason},
          CreateTX  :: binary(),
          Reason    :: file:posix() | bad_fun_name | aaci_not_found | term().
 %% @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
@@ -1090,36 +1131,56 @@ 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.
 
 
-contract_create_built(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, InitArgs) ->
+-spec contract_create_built(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, InitArgs) -> Result
-    AACI = hz_aaci:prepare_aaci(maps:get(aci, Compiled)),
+    when CreatorID :: unicode:chardata(),
+         Nonce     :: pos_integer(),
+         Gas       :: pos_integer(),
+         GasPrice  :: pos_integer(),
+         Amount    :: non_neg_integer(),
+         TTL       :: non_neg_integer(),
+         Compiled  :: map(),
+         InitArgs  :: [string()]
+                    | {erlang, [term()]}
+                    | {fate,   [term()]}
+                    | {sophia, [string()]},
+         Result    :: {ok, CreateTX} | {error, Reason},
+         CreateTX  :: binary(),
+         Reason    :: file:posix() | bad_fun_name | aaci_not_found | term().
+%% @doc
+%% See `contract_create/8' for detailed information on argument types.
+%% The `Compiled' argument is the output of contract compilation and replaces the `File'
+%% argument in `contract_create/8'.
+
+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,
+            assemble_calldata(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData);
-                              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) ->
+assemble_calldata2(OwnerID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData) ->
-    Code = gmser_contract_code:serialize(Compiled),
+    Compressed = #{contract_source := Bundle} = bundle_source(Compiled),
-    Source = unicode:characters_to_binary(maps:get(contract_source, Compiled, <<>>)),
+    Code = gmser_contract_code:serialize(Compressed),
     VM = 1,
     ABI = 1,
     <<CTVersion:32>> = <<VM:16, ABI:16>>,
@@ -1129,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},
@@ -1156,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(),
@@ -1192,7 +1290,10 @@ read_aci(Path) ->
          AACI     :: aaci() | {aaci, Label :: term()},
          ConID    :: unicode:chardata(),
          Fun      :: string(),
-         Args     :: [string()],
+         Args     :: [string()]
+                   | {erlang, [term()]}
+                   | {fate,   [term()]}
+                   | {sophia, [string()]},
          Result   :: {ok, CallTX} | {error, Reason},
          CallTX   :: binary(),
          Reason   :: term().
@@ -1227,7 +1328,10 @@ contract_call(CallerID, AACI, ConID, Fun, Args) ->
          AACI     :: aaci() | {aaci, Label :: term()},
          ConID    :: unicode:chardata(),
          Fun      :: string(),
-         Args     :: [string()],
+         Args     :: [string()]
+                   | {erlang, [term()]}
+                   | {fate,   [term()]}
+                   | {sophia, [string()]},
          Result   :: {ok, CallTX} | {error, Reason},
          CallTX   :: binary(),
          Reason   :: term().
@@ -1265,7 +1369,10 @@ contract_call(CallerID, Gas, AACI, ConID, Fun, Args) ->
          AACI     :: aaci() | {aaci, Label :: term()},
          ConID    :: unicode:chardata(),
          Fun      :: string(),
-         Args     :: [string()],
+         Args     :: [string()]
+                   | {erlang, [term()]}
+                   | {fate,   [term()]}
+                   | {sophia, [string()]},
          Result   :: {ok, CallTX} | {error, Reason},
          CallTX   :: binary(),
          Reason   :: term().
@@ -1362,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
+%%   according to the function's spec. Arguments can be represented as a list of
-%%   argument of `10' must be cast to the textual representation `"10"').
+%%   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
@@ -1437,7 +1545,7 @@ contract_call4(PK, Nonce, Gas, GasPrice, Amount, TTL, CK, CallData) ->
 
 prepare_contract(File) ->
     case so_compiler:file(File, [{aci, json}]) of
-        {ok, #{aci := ACI}} -> {ok, hz_aaci:prepare_aaci(ACI)};
+        {ok, #{aci := ACI}} -> {ok, hz_aaci:prepare(ACI)};
         Error               -> Error
     end.
 
@@ -1503,7 +1611,7 @@ min_gas_price() ->
 %% This function always returns 200,000 in the current version.
 
 min_gas() ->
-    200000.
+    200_000.
 
 
 encode_call_data({aaci, _ContractName, FunDefs, _TypeDefs}, Fun, Args) ->
@@ -1517,12 +1625,43 @@ encode_call_data({aaci, Label}, Fun, Args) ->
         error      -> {error, aaci_not_found}
     end.
 
-encode_call_data2(ArgDef, Fun, Args) ->
+encode_call_data2(ArgDef, Fun, {sophia, Args}) ->
+    case convert(ArgDef, Args) of
+        {ok, Converted} -> gmb_fate_abi:create_calldata(Fun, Converted);
+        Errors          -> Errors
+    end;
+encode_call_data2(ArgDef, Fun, {erlang, Args}) ->
     case hz_aaci:erlang_args_to_fate(ArgDef, Args) of
         {ok, Coerced} -> gmb_fate_abi:create_calldata(Fun, Coerced);
-        Errors -> Errors
+        Errors        -> Errors
-    end.
+    end;
+encode_call_data2(_, Fun, {fate, Args}) ->
+    % TODO: This should probably be moved back closer to the initiating call.
+    %       2026-02-13: Craig
+    gmb_fate_abi:create_calldata(Fun, Args);
+encode_call_data2(ArgDef, Fun, Args) ->
+    encode_call_data2(ArgDef, Fun, {sophia, Args}).
 
+convert(Defs, Args) -> convert(Defs, Args, 1, [], []).
+
+convert([{Name, Def} | Defs], [Arg | Args], Nth, Terms, Errors) ->
+    case hz_sophia:parse_literal(Def, Arg) of
+        {ok, Term}      -> convert(Defs, Args, Nth + 1, [Term | Terms], Errors);
+        {error, Reason} -> convert(Defs, Args, Nth + 1, Terms, [{Nth, Name, Reason} | Errors])
+    end;
+convert([], [], _, Terms, []) ->
+    {ok, lists:reverse(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
@@ -1530,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),
@@ -1549,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.
@@ -1579,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,
@@ -1589,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,
@@ -1633,11 +1809,10 @@ spend2(DSenderID,
 
 
 decode_account_id(B) ->
-    try
+    case gmser_api_encoder:safe_decode(account_pubkey, B) of
-        {account_pubkey, PK}  = gmser_api_encoder:decode(B),
+        {ok, PK}                -> {ok, PK};
-        {ok, PK}
+        {error, invalid_prefix} -> gmser_api_encoder:safe_decode(contract_pubkey, B);
-    catch
+        Error                   -> Error
-        E:R -> {E, R}
     end.
 
 
@@ -1692,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(),
@@ -1770,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(),
@@ -1784,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_aaci.erl

@@ -10,46 +10,391 @@
 %%% @end
 
 -module(hz_aaci).
--vsn("0.8.2").
+-vsn("0.9.2").
 -author("Jarvis Carroll <spiveehere@gmail.com>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
 
 % Contract call and serialization interface functions
--export([prepare_contract/1,
+-export([prepare_from_file/1,
-         prepare_aaci/1,
+         prepare/1,
          erlang_to_fate/2,
          fate_to_erlang/2,
          erlang_args_to_fate/2,
          get_function_signature/2]).
-% Internal stuff that is useful for writing AACI unit tests.
--export([aaci_from_string/1, annotate_type/2]).
 
 %%% Types
 
--export_type([aaci/0]).
+-export_type([aaci/0, annotated_type/0, erlang_repr/0]).
 
 -include_lib("eunit/include/eunit.hrl").
 
--type aaci() :: {aaci, term(), term(), term()}.
+-type erlang_repr() ::   erlang_repr_int()
+                       | erlang_repr_address()
+                       | erlang_repr_contract()
+                       | erlang_repr_signature()
+                       | erlang_repr_bool()
+                       | erlang_repr_string()
+                       | erlang_repr_char()
+                       | erlang_repr_bytes()
+                       | erlang_repr_bits()
+                       | erlang_repr_list()
+                       | erlang_repr_map()
+                       | erlang_repr_tuple()
+                       | erlang_repr_variant()
+                       | erlang_repr_record().
+% The Sophia-flavored 'Erlang representation' of on-chain data.
+% Data is stored and manipulated on the chain without knowledge of Sophia
+% types, which leads to a specialized representation that is confusing to
+% manipulate directly. If you want to form contract arguments using an Erlang
+% program, or pattern match the outputs of a contract call using an Erlang
+% program, this Sophia-flavored representation is much more convenient. It
+% de-anonymizes variant types and record types, and is more lenient in how it
+% interprets a variety of cryptographic, binary, and string data types.
+%
+% When calling functions that manipulate this erlang representation, AACI type
+% information representing the Sophia type of that term must be provided. The
+% Sophia type used to produce that AACI type will determine what Erlang terms
+% are actually accepted without producing errors.
+
+
+%-type erlang_repr() ::   integer()
+                       %| string()
+                       %| boolean()
+                       %| binary()
+                       %| tuple() % Tuples, variants, or raw addresses
+                       %| [erlang_repr()]
+                       %| #{erlang_repr() => erlang_repr()}.
+
+
+-type erlang_repr_int() :: integer() | string().
+% The Erlang representation of a Sophia `int'
+% Integers will be used as-is. Strings will be parsed using `list_to_integer/1'.
+% `fate_to_erlang/2' always produces the integer representation.
+
+
+-type erlang_repr_address() :: unicode:chardata() | {raw, <<_:32*8>>}.
+% The Erlang representation of a Sophia `address'
+% This can either be the `"ak_..."' string produced by gmserialization,
+% GajuDesk, etc. or a 'raw' binary of 32 bytes. `fate_to_erlang/2' always
+% produces the `"ak_..."' string as an Erlang list. The Sophia-flavored Erlang
+% representation should not be used if this is undesirable.
+
+
+-type erlang_repr_contract() :: unicode:chardata() | {raw, <<_:32*8>>}.
+% The Erlang representation of a Sophia `contract'
+% This can either be the `"ct_..."' string produced by gmserialization,
+% GajuDesk, etc. or a 'raw' binary of 32 bytes. fate_to_erlang/2 always
+% produces the `"ct_..."' string as an Erlang list.
+
+
+-type erlang_repr_signature() :: unicode:chardata() | <<_:64*8>> | {raw, <<_:64*8>>}.
+% The Erlang representation of a Sophia `signature'
+% This can either be the `"sg_..."' string produced by gmserialization,
+% GajuDesk, etc. or a 'raw' binary of 64 bytes. (Not 32.) Unlike addresses and
+% contracts, 'raw' binaries can be wrapped or unwrapped when representing a
+% signature. fate_to_erlang/2 always produces the `"sg_..."' string as an Erlang
+% list.
+
+
+-type erlang_repr_bool() :: true | false | string().
+% The Erlang representation of a Sophia `bool'
+% `fate_to_erlang/2' always produces atoms, but `erlang_to_fate/2' also accepts
+% the lists `"true"' and `"false"'.
+
+
+-type erlang_repr_string() :: unicode:chardata().
+% The Erlang representation of a Sophia `string'
+% The conversion uses `unicode:characters_to_binary/1', so a list, a UTF8
+% binary, or an iolist mixing both are all acceptable inputs. `fate_to_erlang/2'
+% always produces a list.
+
+
+-type erlang_repr_char() :: integer() | unicode:chardata().
+% The Erlang representation of a Sophia `char'
+% On-chain a `char' means one unicode code point, and is just a FATE integer.
+% `fate_to_erlang/2' will provide this integer as-is, but `erlang_to_fate/2' can
+% be passed an arbitrary unicode string, as long as it decodes to a single
+% unicode code point.
+
+
+-type erlang_repr_bytes() :: binary().
+% The Erlang representation of Sophia `bytes()'
+% Sophia has fixed-length `bytes(10)' etc. and variable length `bytes()'.
+% These are treated the same in the Erlang representation, but
+% `erlang_to_fate/2' will check the length of the binary in the fixed length
+% case, and provide errors if it doesn't agree.
+
+
+-type erlang_repr_bits() :: bitstring().
+% The Erlang representation of Sophia `bits()'
+% FATE has a representation of bitstrings that one might call novel. A
+% FATE/Sophia bitstring is actually represented as an integer, so there is no
+% concept of bitstring 'length', all bitstrings have infinitely many leading
+% zeroes, if the integer is positive, and, surprisingly, infinitely many
+% leading ones, if the integer is negative! To represent this in the general
+% case, `erlang_to_fate/2' accepts arbitrary integers, positive or negative, and
+% `fate_to_erlang/2' always produces integers, but for convenience,
+% `erlang_to_fate/2' also accepts arbitrary Erlang bitstrings, which are
+% converted into positive integers, i.e. '0 by default' FATE bitstrings.
+
+
+-type erlang_repr_list() :: [erlang_repr()].
+% The Erlang representation of a Sophia `list(_)'
+% Simply a list. Each element of the list is converted forwards/backwards as
+% normal.
+
+
+-type erlang_repr_map() :: #{erlang_repr() => erlang_repr()}.
+% The Erlang representation of a Sophia `map(_, _)'
+% Simply a map. Each key and value is converted forwards/backwards as normal.
+
+
+-type erlang_repr_tuple() :: {}
+                           | {erlang_repr(), erlang_repr()}
+                           | tuple().
+% The Erlang representation of a Sophia tuple
+% In Sophia these types are written `a * b', `a * b * c', and so on. Despite
+% the binary infix notation, a product of more than two types gives a single
+% tuple type with that many elements, so `(1, 2, 3)' is an `int * int * int'.
+% `gmbytecode' requires FATE tuples to be wrapped in `{tuple, {X, Y}}', etc. but
+% the Erlang representation specifically requires that the tuple be provided
+% without any wrappers, so `{X, Y}', etc. These representations cannot be mixed,
+% since at the highest level they are both just tuples. Each element of the
+% tuple is also converted forwards/backwards as normal. Although FATE has
+% singleton tuples, Sophia doesn't, so an ACI/AACI will never produce a
+% singleton tuple in an interface; if your contract takes singleton tuples,
+% these Sophia representations will probably still work, but you won't be able
+% to generate the AACI that makes them work, so it is likely simpler to just
+% use the FATE representation.
+
+
+-type erlang_repr_variant() :: string()
+                             | {string()}
+                             | {string(), erlang_repr()}
+                             | tuple().
+% The Erlang representation of a Sophia ADT
+% Sophia has a `datatype' keyword that allows the definition of algebraic data
+% types, also known as variants, tagged unions, sum types, coproduct types,
+% etc. In Erlang these are normally represented as an atom, or as a tuple
+% whose first term is an atom, so for familiarity, `erlang_to_fate/2' accepts
+% lists in place of atoms, or tuples whose first term is a list. Note that
+% constructors in Sophia have to be capitalized, so actual atoms wouldn't be
+% that convenient. `fate_to_erlang/2' always produces a tuple whose first term
+% is a list, even if that tuple is a singleton. This allows the user to
+% blindly call `element(0)' or `tuple_to_list(_)' without annoying special cases.
+%
+% Sophia also has a few built-in algebraic data types, for building its
+% standard library, and for exposing certain FATE primitives, which will
+% therefore also use this representation, e.g. `"None"', `{"None"}', or
+% `{"Some", Datum}' for the `option(_)' type.
+
+
+-type erlang_repr_record() :: #{string() => erlang_repr()}.
+% The Erlang representation of a Sophia record type
+% Sophia has a `record' keyword, that allows the definition of new record
+% types. Sophia records are meant to be reminiscent of Sophia maps, so in the
+% Erlang representation of Sophia records, we use a map, with strings as keys,
+% and arbitrary `erlang_repr()' terms as values.
+
+
+-type aaci() :: {aaci, string(), #{string() => function_spec()}, #{string() => typedef()}}.
+% The Accelerated Aeternity Contract Interface
+% Sophia tooling was originally written around a javascript use-case, but
+% hakuzaru is written for Erlang, so we don't really want to walk through big
+% JSON trees every time we do an on-chain action, so the AACI exists to
+% accelerate these actions, so that interacting with contract entrypoints from
+% within a pure Erlang environment is convenient and fast.
+%
+% The layout may change, but an AACI basically consists of three parts:
+% <ul>
+%  <li>The name of the contract,</li>
+%  <li>The 'annotated' entrypoint specs, designed for fast conversion to/from
+%   the representation used on-chain, see `function_spec/0',</li>
+%  <li>The 'opaque' type definitions, all the internal type aliases and
+%   definitions within the contract and its imported namespaces.</li>
+% </ul>
+
+
+-type function_spec() :: {[{string(), annotated_type()}], annotated_type()}.
+% The fully annotated spec of a contract entrypoint, for fast call formation
+% The first term is a list of parameter names and their types, as expected by
+% `erlang_args_to_fate/2', and the second term is a single type, as expected by
+% `fate_to_erlang/2'. See annotated_type/0 for the details of how these types
+% are represented and why, but for most purposes it is fine to just store and
+% pass these type terms around without looking at their contents.
+
+
+-type annotated_type() :: {opaque_type(), already_normalized | opaque_type(), annotated_type_body()}.
+% A fully annotated Sophia type.
+% Sophia allows for arbitrary nesting of type aliases, each with parameters,
+% and each potentially substituting for another arbitrarily complex type
+% alias, so there is a potentially indefinite amount of work converting the
+% type `my_type_alias' as it would appear in Sophia/in the ACI, into the
+% actual variant/record/list/map/tuple type expression that it ultimately
+% represents. To overcome this, we 'annotate' a type, recording what its
+% aliased name was, along with its actual definition.
+%
+% Normally you can extract the annotated types from a `function_spec()', and
+% pass them into the conversion function that needs them, but it can also be
+% useful to walk through the annotated types yourself. Confusingly, if you
+% want to recursively descend down an annotated type, you want to recurse on
+% the third element in the tuple, not the first two, as the first two
+% represent incomplete levels of normalization, which can be more descriptive
+% for users, but aren't as actionable as the fully normalized third element.
+%
+% Despite the third term being the most important, it is kept at the end,
+% because that is what is most memorable, since each element of the triple is
+% more normalized than the last, and because that is what is easiest to read,
+% since the third term is usually an explosion of nested braces and brackets,
+% making anything written after it basically unreadable.
+%
+% If you look at examples of annotated types produced in your own programs,
+% you will tend to see things like `{integer, alread_normalized, integer}',
+% making it even less clear that the third element is the important one, or
+% why that is. For some fairly simple but informative examples, consider these
+% type aliases:
+% <pre>
+%   contract C =
+%     record my_record('t) = {x: 't, y: 't}
+%     type my_alias1 = int
+%     type my_alias2 = list(my_alias1)
+%     type my_alias3 = my_record(my_alias1)
+% </pre>
+% If these type aliases appeared in a function spec, the AACI would represent
+% them as the following annotated types:
+% <pre>
+%    {"my_alias1", integer, integer}
+%    {"my_alias2", {list, ["my_alias1"]}, {list, [{"my_alias1", integer, integer}]}}
+%    {"my_alias3", {"my_record", ["my_alias1"]}, {record, [{"x", {"my_alias1", integer, integer}}, {"y", {"my_alias1", integer, integer}}]}}
+% </pre>
+%
+% The first term is the type roughly as it appeared in the ACI, see
+% opaque_type/0 for more information.
+%
+% The second term is that same type but 'head normalized', chasing type
+% aliases iteratively, until it is some built in type like an integer, or some
+% user-defined record type or ADT. If the alias reduces to a list or map or
+% tuple with more aliased types nested inside, these nested type
+% subexpressions are not normalized any further, as the 'list' or 'map'
+% connective is considered the 'head' of the type expression, and is
+% normalized. Record type names and ADT names are not considered aliases, and
+% so are considered head normalized, but both can take parameters, which can
+% also stay un-normalized, as with lists or maps. If the head normalized type
+% is the same as the opaque type, then the atom `already_normalized' is placed
+% instead, as a hint that instead of printing messages like
+% `my_alias1 (i.e.  int)', a simple message like `list(my_record)' will do.
+%
+% The third term is the head normalized type with two changes, first, record
+% and variant definitions are subtituted in as well, giving a list of field
+% names or constructor names in full, and second, each subexpression is
+% recursively annotated, meaning its opaque, head-normalized, and fully
+% normalized parts also appear as triples.
+
+
+-type builtin_type(T) :: {bytes, [integer() | any]}
+                       | {tuple, [T]}
+                       | {list, [T]}
+                       | {map, [T]}
+                       | integer
+                       | boolean
+                       | bits
+                       | char
+                       | string
+                       | address
+                       | signature
+                       | contract
+                       | channel
+                       | unknown_type.
+% The primitive connectives that complex type expressions can be built out of.
+% It takes a parameter, since `builtin_type(opaque_type())',
+% `builtin_type(annotated_type())', and `builtin_type(typedef_expression())' are
+% all useful recursive applications of these connectives.
+
+
+-type user_defined_type(T) :: {record, [{string(), T}]}
+                            | {variant, [{string(), [T]}]}.
+% The connectives for defining new records and ADTs.
+% Record types and ADTs can both appear in the original type definitions in
+% the body of a contract, as well as in the recursively normalized 'annotated
+% types' that the AACI stores. We use the same layout in both cases.
+
+
+-type opaque_type() :: string()
+                     | {string(), [opaque_type()]}
+                     | builtin_type(opaque_type()).
+% An opaque type as it originally appeared in a function spec.
+% The Sophia compiler may have a different representation for these type
+% expressions, but we make a simple representation here as well.
+% These type expressions are really function applications, in a limited sort
+% of rewrite calculus without higher order functions. After performing some
+% rewrites, the format actually stays the same, so the second term in a type
+% triple is also this 'opaque type', but that is a coincidence; this type is
+% primarily designed to represent types that haven't been head-normalized at
+% all % yet.
+
+
+-type annotated_type_body() :: builtin_type(annotated_type())
+                             | user_defined_type(annotated_type()).
+% The recursively annotated part of an annotated type triple
+% This can be any anonymous type connective, with annotated types inside, or
+% it can be a record definition, with annotated types for fields, or it can be
+% an ADT definition, with annotated types for each constructor input.
+
+
+-type typedef_expression() :: {var, string()}
+                            | string()
+                            | {string(), [typedef_expression()]}
+                            | builtin_type(typedef_expression()).
+% The recursive type expressions that can appear in the definitions of type aliases.
+% Similar to opaque_type(), but type aliases can take parameters as well,
+% which means those parameters can also appear anywhere within the recursive
+% type expression that defines the type alias.
+
+
+-type typedef() :: {[string()], typedef_body()}.
+% A type definition as it appears in the AACI.
+% A type definition has a list of parameter names, and then some body defined
+% using builtin type connectives, other defined types, and those parameters.
+
+
+-type typedef_body() :: typedef_expression()
+                      | user_defined_type(typedef_expression()).
+% The possible right-hand-sides of a type definition
+% A type definition means a type alias, a record definition, or an ADT
+% definition. Aliases are just some type expression, possibly with type
+% parameters, and records and variants are already defined above in
+% user_defined_type/1, with arbitrary type expressions in each one, but again,
+% they could contain type parameters as well.
+
+
 
 %%% ACI/AACI
 
--spec prepare_contract(File) -> {ok, AACI} | {error, Reason}
+-spec prepare_from_file(Path) -> {ok, AACI} | {error, Reason}
-    when File   :: file:filename(),
+    when Path   :: file:filename(),
          AACI   :: aaci(),
          Reason :: term().
 %% @doc
-%% Compile a contract and extract the function spec meta for use in future formation
+%% Compile a contract and extract the contract type information for forming contract calls
-%% of calldata
+%% This is the simplest (but slowest) way of getting access to the AACI
+%% structure for a contract. Having the AACI is not strictly necessary, but
+%% makes it much more convenient to form contract calls and view their results.
 
-prepare_contract(File) ->
+prepare_from_file(Path) ->
-    case so_compiler:file(File, [{aci, json}]) of
+    case so_compiler:file(Path, [{aci, json}]) of
-        {ok, #{aci := ACI}} -> {ok, prepare_aaci(ACI)};
+        {ok, #{aci := ACI}} -> {ok, prepare(ACI)};
         Error               -> Error
     end.
 
-prepare_aaci(ACI) ->
+-spec prepare(ACI) -> AACI
+    when ACI  :: term(),
+         AACI :: aaci().
+%% @doc
+%% Convert the ACI structure produced by the compiler into the AACI format used by Hakuzaru
+%% See the documentation for the aaci/0 type for more information.
+
+prepare(ACI) ->
     % We want to take the types represented by the ACI, things like N1.T(N2.T),
     % and dereference them down to concrete types like
     % {tuple, [integer, string]}. Our type dereferencing algorithms
@@ -64,9 +409,15 @@ prepare_aaci(ACI) ->
     % make error messages easier to understand.
     InternalTypeDefs = maps:merge(builtin_typedefs(), TypeDefs),
     Specs = annotate_function_specs(OpaqueSpecs, InternalTypeDefs, #{}),
-
     {aaci, Name, Specs, TypeDefs}.
 
+
+-spec convert_aci_types(ACI) -> {Name, OpaqueSpecs, TypeDefs}
+    when ACI         :: term(),
+         Name        :: string(),
+         OpaqueSpecs :: [{string(), [{string(), opaque_type()}], opaque_type()}],
+         TypeDefs    :: #{string() => typedef()}.
+
 convert_aci_types(ACI) ->
     % Find the main contract, so we can get the specifications of its
     % entrypoints.
@@ -91,17 +442,20 @@ convert_aci_types(ACI) ->
     % just pre-compute and acceleration.
     {Name, Specs, TypeDefMap}.
 
+
 convert_function_spec(#{name := NameBin, arguments := Args, returns := Result}) ->
     Name = binary_to_list(NameBin),
     ArgTypes = lists:map(fun convert_arg/1, Args),
     ResultType = opaque_type([], Result),
     {Name, ArgTypes, ResultType}.
 
+
 convert_arg(#{name := NameBin, type := TypeDef}) ->
     Name = binary_to_list(NameBin),
     Type = opaque_type([], TypeDef),
     {Name, Type}.
 
+
 convert_namespace_typedefs(#{namespace := NS}) ->
     Name = namespace_name(NS),
     convert_typedefs(NS, Name);
@@ -135,6 +489,14 @@ convert_typedefs_loop([Next | Rest], NamePrefix, Converted) ->
     Def = opaque_type(Params, DefACI),
     convert_typedefs_loop(Rest, NamePrefix, [Converted, {Name, Params, Def}]).
 
+
+-spec collect_opaque_types(Tree, TypeDefs) -> TypeDefs
+    when Tree     :: typedef_tree(),
+         TypeDefs :: #{string() => typedef()}.
+
+-type typedef_tree() :: {string(), [string()], typedef_body()} | list(typedef_tree()).
+
+
 collect_opaque_types([], Types) ->
     Types;
 collect_opaque_types([L | R], Types) ->
@@ -143,10 +505,17 @@ collect_opaque_types([L | R], Types) ->
 collect_opaque_types({Name, Params, Def}, Types) ->
     maps:put(Name, {Params, Def}, Types).
 
+
+
 %%% ACI Type -> Opaque Type
 
+-spec opaque_type(Params, ACIType) -> Opaque
+    when Params  :: [string()],
+         ACIType :: binary() | map(),
+         Opaque  :: opaque_type().
 % Convert an ACI type defintion/spec into the 'opaque type' representation that
 % our dereferencing algorithms can reason about.
+
 opaque_type(Params, NameBin) when is_binary(NameBin) ->
     Name = opaque_type_name(NameBin),
     case not is_atom(Name) and lists:member(Name, Params) of
@@ -172,8 +541,11 @@ opaque_type(Params, Pair) when is_map(Pair) ->
     [{Name, TypeArgs}] = maps:to_list(Pair),
     {opaque_type_name(Name), [opaque_type(Params, Arg) || Arg <- TypeArgs]}.
 
+
+-spec opaque_type_name(binary()) -> atom() | string().
 % Atoms for any builtins that aren't qualified by a namespace in Sophia.
 % Everything else stays as a string, user-defined or not.
+
 opaque_type_name(<<"int">>)       -> integer;
 opaque_type_name(<<"bool">>)      -> boolean;
 opaque_type_name(<<"bits">>)      -> bits;
@@ -189,6 +561,7 @@ opaque_type_name(<<"map">>)       -> map;
 opaque_type_name(<<"channel">>)   -> channel;
 opaque_type_name(Name)            -> binary_to_list(Name).
 
+
 builtin_typedefs() ->
     #{"unit" => {[], {tuple, []}},
       "void" => {[], {variant, []}},
@@ -246,14 +619,15 @@ builtin_typedefs() ->
       "MCL_BLS12_381.fp" => {[], {bytes, [48]}}
      }.
 
+
 %%% Opaque Type -> Accelerated 'Annotated' Type
 
 % Type preparation has two goals. First, we need a data structure that can be
 % traversed quickly, to take sophia-esque erlang expressions and turn them into
 % fate-esque erlang expressions that gmbytecode can serialize. Second, we need
 % partially substituted names, so that error messages can be generated for why
-% "foobar" is not valid as the third field of a `bazquux`, because the third
+% "foobar" is not valid as the third field of a `bazquux', because the third
-% field is supposed to be `option(integer)`, not `string`.
+% field is supposed to be `option(integer)', not `string'.
 %
 % To achieve this we need three representations of each type expression, which
 % together form an 'annotated type'. First, we need the fully opaque name,
@@ -269,10 +643,20 @@ builtin_typedefs() ->
 %
 % In a lot of cases the opaque type given will already be normalized, in which
 % case either the normalized field or the non-normalized field of an annotated
-% type can simple be the atom `already_normalized`, which means error messages
+% type can simple be the atom `already_normalized', which means error messages
 % can simply render the normalized type expression and know that the error will
 % make sense.
 
+-spec annotate_function_specs(OpaqueSpecs, Types, Acc) -> Specs
+    when OpaqueSpecs     :: [{string(), ArgsOpaque, ResultOpaque}],
+         ArgsOpaque      :: [{string(), opaque_type()}],
+         ResultOpaque    :: opaque_type(),
+         Types           :: #{string() => typedef()},
+         Acc             :: #{string() => {ArgsAnnotated, ResultAnnotated}},
+         Specs           :: #{string() => {ArgsAnnotated, ResultAnnotated}},
+         ArgsAnnotated   :: [{string(), annotated_type()}],
+         ResultAnnotated :: annotated_type().
+
 annotate_function_specs([], _Types, Specs) ->
     Specs;
 annotate_function_specs([{Name, ArgsOpaque, ResultOpaque} | Rest], Types, Specs) ->
@@ -281,34 +665,30 @@ annotate_function_specs([{Name, ArgsOpaque, ResultOpaque} | Rest], Types, Specs)
     NewSpecs = maps:put(Name, {Args, Result}, Specs),
     annotate_function_specs(Rest, Types, NewSpecs).
 
+
+-spec annotate_type(Opaque, Types) -> {ok, Annotated}
+    when Opaque    :: opaque_type(),
+         Types     :: #{string() => typedef()},
+         Annotated :: annotated_type().
+
 annotate_type(T, Types) ->
     case normalize_opaque_type(T, Types) of
+        {ok, _, _, unknown_type} ->
+            {ok, {T, unknown_type, unknown_type}};
         {ok, AlreadyNormalized, NOpaque, NExpanded} ->
-            annotate_type2(T, AlreadyNormalized, NOpaque, NExpanded, Types);
+            annotate_type2(T, AlreadyNormalized, NOpaque, NExpanded, Types)
-        Error ->
-            Error
     end.
 
-annotate_type2(T, _, _, unknown_type, _) ->
-    % If a type is unknown, then it should not be reported as the normalized
-    % name.
-    {ok, {T, unknown_type, unknown_type}};
 annotate_type2(T, AlreadyNormalized, NOpaque, NExpanded, Types) ->
-    case annotate_type_subexpressions(NExpanded, Types) of
+    {ok, Flat} = annotate_type_subexpressions(NExpanded, Types),
-        {ok, Flat} ->
+    case AlreadyNormalized of
-            case AlreadyNormalized of
+        true -> {ok, {T, already_normalized, Flat}};
-                true -> {ok, {T, already_normalized, Flat}};
+        false -> {ok, {T, NOpaque, Flat}}
-                false -> {ok, {T, NOpaque, Flat}}
-            end;
-        Error ->
-            Error
     end.
 
 annotate_types([T | Rest], Types, Acc) ->
-    case annotate_type(T, Types) of
+    {ok, Type} = annotate_type(T, Types),
-        {ok, Type} -> annotate_types(Rest, Types, [Type | Acc]);
+    annotate_types(Rest, Types, [Type | Acc]);
-        Error      -> Error
-    end;
 annotate_types([], _Types, Acc) ->
     {ok, lists:reverse(Acc)}.
 
@@ -319,37 +699,35 @@ annotate_type_subexpressions({bytes, [Count]}, _Types) ->
     % opaque type.
     {ok, {bytes, [Count]}};
 annotate_type_subexpressions({variant, VariantsOpaque}, Types) ->
-    case annotate_variants(VariantsOpaque, Types, []) of
+    {ok, Variants} = annotate_variants(VariantsOpaque, Types, []),
-        {ok, Variants} -> {ok, {variant, Variants}};
+    {ok, {variant, Variants}};
-        Error          -> Error
-    end;
 annotate_type_subexpressions({record, FieldsOpaque}, Types) ->
-    case annotate_bindings(FieldsOpaque, Types, []) of
+    {ok, Fields} = annotate_bindings(FieldsOpaque, Types, []),
-        {ok, Fields} -> {ok, {record, Fields}};
+    {ok, {record, Fields}};
-        Error        -> Error
-    end;
 annotate_type_subexpressions({T, ElemsOpaque}, Types) ->
-    case annotate_types(ElemsOpaque, Types, []) of
+    {ok, Elems} = annotate_types(ElemsOpaque, Types, []),
-        {ok, Elems} -> {ok, {T, Elems}};
+    {ok, {T, Elems}}.
-        Error       -> Error
+
-    end.
+
+-spec annotate_bindings(Bindings, Types, Acc) -> {ok, Annotated}
+    when Bindings  :: [{string(), opaque_type()}],
+         Types     :: #{string() => typedef()},
+         Acc       :: [{string(), annotated_type()}],
+         Annotated :: [{string(), annotated_type()}].
 
 annotate_bindings([{Name, T} | Rest], Types, Acc) ->
-    case annotate_type(T, Types) of
+    {ok, Next} = annotate_type(T, Types),
-        {ok, Type} -> annotate_bindings(Rest, Types, [{Name, Type} | Acc]);
+    annotate_bindings(Rest, Types, [{Name, Next} | Acc]);
-        Error      -> Error
-    end;
 annotate_bindings([], _Types, Acc) ->
     {ok, lists:reverse(Acc)}.
 
 annotate_variants([{Name, Elems} | Rest], Types, Acc) ->
-    case annotate_types(Elems, Types, []) of
+    {ok, ElemsFlat} = annotate_types(Elems, Types, []),
-        {ok, ElemsFlat} -> annotate_variants(Rest, Types, [{Name, ElemsFlat} | Acc]);
+    annotate_variants(Rest, Types, [{Name, ElemsFlat} | Acc]);
-        Error           -> Error
-    end;
 annotate_variants([], _Types, Acc) ->
     {ok, lists:reverse(Acc)}.
 
+
 % This function evaluates type aliases in a loop, until eventually a usable
 % definition is found.
 normalize_opaque_type(T, Types) -> normalize_opaque_type(T, Types, true).
@@ -444,8 +822,28 @@ substitute_opaque_types(Bindings, Types) ->
     Each = fun(Type) -> substitute_opaque_type(Bindings, Type) end,
     lists:map(Each, Types).
 
+
+
 %%% Erlang to FATE
 
+-spec erlang_args_to_fate(VarTypes, Terms) -> {ok, FATE} | {error, Errors}
+    when VarTypes :: [{string(), annotated_type()}],
+         Terms    :: [erlang_repr()],
+         FATE     :: gmb_fate_data:fate_type(),
+         Errors   :: [{Reason, [PathStep]}],
+         Reason   :: term(),
+         PathStep :: term().
+%% @doc
+%% Call erlang_to_fate/2 on a list of named values.
+%% See the documentation for the `erlang_repr/0' type for more information on the
+%% format required.
+%%
+%% This is mainly used by `hz' to form contract calls. The parameter names
+%% and parameter types are provided in one zipped list, exactly as they appear
+%% in the AACI datatype, and then a second list of concrete arguments are
+%% provided in the format that `erlang_to_fate/2' expects. The parameter names
+%% are used to provide slightly more informative errors.
+
 erlang_args_to_fate(VarTypes, Terms) ->
     DefLength = length(VarTypes),
     ArgLength = length(Terms),
@@ -455,6 +853,23 @@ erlang_args_to_fate(VarTypes, Terms) ->
         DefLength   < ArgLength -> {error, too_many_args}
     end.
 
+
+-spec erlang_to_fate(Type, Erlang) -> {ok, FATE} | {error, Errors}
+    when Type     :: annotated_type(),
+         FATE     :: gmb_fate_data:fate_type(),
+         Erlang   :: erlang_repr(),
+         Errors   :: [{Reason, [PathStep]}],
+         Reason   :: term(),
+         PathStep :: term().
+%% @doc
+%% Convert one Sophia-flavored Erlang term into one FATE-flavored Erlang terms.
+%% This is not usually used on its own, since if you need to form a contract
+%% call, you have a list of arguments, not a single argument. Nonetheless, if
+%% for some reason you want to use a mix of FATE-flavored Erlang terms and
+%% Sophia-flavored Erlang terms in one function call, it may be useful to
+%% convert the Sophia-flavored terms individually, to form a single
+%% FATE-flavored list for call formation.
+
 erlang_to_fate({_, _, integer}, S) when is_integer(S) ->
     {ok, S};
 erlang_to_fate({O, N, integer},  S) when is_list(S) ->
@@ -721,6 +1136,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 ->
@@ -746,10 +1165,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 ->
+        {error, Errors} ->
-            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 = [_|_]}} ->
@@ -787,6 +1214,7 @@ combine_errors(Broken) ->
     lists:foldl(F, [], Broken).
 
 
+
 %%% FATE to Erlang
 
 % Not sure if this is needed... fate_to_erlang shouldn't fail.
@@ -795,6 +1223,22 @@ coerce_direction(Type, Term, to_fate) ->
 coerce_direction(Type, Term, from_fate) ->
     fate_to_erlang(Type, Term).
 
+
+-spec fate_to_erlang(Type, FATE) -> {ok, Erlang} | {error, Errors}
+    when Type     :: annotated_type(),
+         FATE     :: gmb_fate_data:fate_type(),
+         Erlang   :: erlang_repr(),
+         Errors   :: [{Reason, [PathStep]}],
+         Reason   :: term(),
+         PathStep :: term().
+%% @doc
+%% Convert a FATE-flavored Erlang term into a Sophia-flavored Erlang term
+%% Typically this is called by hakuzaru for you when decoding results from the
+%% chain, if you ask for the `erlang' format, but you can call this function
+%% manually if you have a result in the `fate' format, and need the `erlang'
+%% format now. See the documentation of the `erlang_repr/0' type for more
+%% information.
+
 fate_to_erlang({_, _, integer}, S) when is_integer(S) ->
     {ok, S};
 fate_to_erlang({_, _, address}, {address, Bin}) ->
@@ -832,6 +1276,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) ->
@@ -844,15 +1293,31 @@ fate_to_erlang({O, N, {unknown_type, _}}, Data) ->
             io:format(Message, [O, N, Data])
     end,
     {ok, Data};
-fate_to_erlang({O, N, _}, Data) ->
+fate_to_erlang(Type, Data) ->
-    case N of
+    TypeStr = type_to_iolist(Type),
-        already_normalized ->
+    io:format("Warning: Could not coerce term into ~s. Using term as is: ~p~n", [TypeStr, Data]),
-            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,
     {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
@@ -862,11 +1327,13 @@ fate_to_erlang({O, N, _}, Data) ->
          Fun    :: binary() | string(),
          Type   :: {term(), term()}, % FIXME
          Reason :: bad_fun_name.
-
 %% @doc
-%% Look up the type information of a given function, in the AACI provided by
+%% Extract the type information for a particular function from the AACI
-%% prepare_contract/1. This type information, particularly the return type, is
+%% If you want to manually convert a FATE result into the Sophia-flavored
-%% useful for calling decode_bytearray/2.
+%% Erlang representation, or manually convert some or all of the inputs for a
+%% contract call yourself, this function gives you all of the annotated types
+%% associated with a contract entrypoint. For more information, see the
+%% documentation for the `annotated_type/0' type.
 
 get_function_signature({aaci, _, FunDefs, _}, Fun) ->
     case maps:find(Fun, FunDefs) of
@@ -967,9 +1434,9 @@ coerce_tuple_test() ->
     check_roundtrip(Type, {123, "456"}, {tuple, {123, <<"456">>}}).
 
 coerce_variant_test() ->
-    {ok, Type} = annotate_type({variant, [{"A", [integer]},
+    Definition = {variant, [{"A", [integer]},
-                                                {"B", [integer, integer]}]},
+                            {"B", [integer, integer]}]},
-                                     #{}),
+    {ok, Type} = annotate_type("t", #{"t" => {[], Definition}}),
     check_roundtrip(Type, {"A", 123}, {variant, [1, 2], 0, {123}}),
     check_roundtrip(Type, {"B", 456, 789}, {variant, [1, 2], 1, {456, 789}}).
 
@@ -979,7 +1446,8 @@ coerce_option_test() ->
     check_roundtrip(Type, {"Some", 1}, {variant, [0, 1], 1, {1}}).
 
 coerce_record_test() ->
-    {ok, Type} = annotate_type({record, [{"a", integer}, {"b", integer}]}, #{}),
+    Definition = {record, [{"a", integer}, {"b", integer}]},
+    {ok, Type} = annotate_type("t", #{"t" => {[], Definition}}),
     check_roundtrip(Type, #{"a" => 123, "b" => 456}, {tuple, {123, 456}}).
 
 coerce_bytes_test() ->
@@ -1011,7 +1479,7 @@ coerce_hash_test() ->
 
 aaci_from_string(String) ->
     case so_compiler:from_string(String, [{aci, json}]) of
-        {ok, #{aci := ACI}} -> {ok, prepare_aaci(ACI)};
+        {ok, #{aci := ACI}} -> {ok, prepare(ACI)};
         Error               -> Error
     end.
 
@@ -1037,6 +1505,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.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").
+-vsn("0.9.2").
--export([url/2, url/3, url/4, parse/1, req/2, req/3]).
+-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

@@ -1,18 +1,43 @@
 %%% @doc
-%%% Key functions
+%%% Hakuzaru Key Functions
 %%%
-%%% The main reason this is a module of its own is that in the original architecture
+%%% The Gajumaru's default key type is based on Elliptical Curve Cryptography (ECC).
-%%% it was a process rather than just a library of functions. Now that it exists, though,
+%%% The specific curve used is 25519, and the typical key representation is Ed25519.
-%%% there is little motivation to cram everything here into the controller process's
+%%%
-%%% code.
+%%% The "Ed" in "Ed25519" stands for Harold Edwards. This form represents
+%%% a coordinate on a "Twisted Edwards Curve".
+%%%
+%%% The "X" in "X25519" stands for the X-coordinate, also known as the
+%%% "Montgomery u-coordinate" on a "Montgomery Curve".
+%%%
+%%% The two are equivalent, but have meaningfully different properties.
 %%% @end
 
 -module(hz_key_master).
--vsn("0.8.2").
+-vsn("0.9.2").
+
+-export([make_key/0, make_key/1, encode/1, decode/1]).
+-export([shared_secret_a/6, shared_secret_b/6,
+         ed25519_pk_to_x25519/1, ed25519_sk_to_x25519/1,
+         hkdf/4, hkdf/5]).
 
 
--export([make_key/1, encode/1, decode/1]).
+-spec make_key() -> {ID, KeyPair}
--export([lcg/1]).
+    when ID      :: string(),
+         KeyPair :: #{secret => binary(), public => binary()}.
+%% @doc
+%% @equiv make_key(<<>>)
+
+make_key() ->
+    make_key(<<>>).
+
+
+-spec make_key(Secret) -> {ID, KeyPair}
+    when Secret  :: <<>> | <<_:32*8>>,
+         ID      :: string(),
+         KeyPair :: #{secret => binary(), public => binary()}.
+%% @doc
+%% Generate a Ed25519 keypair tagged with the corresponding Gajumaru ID.
 
 make_key(<<>>) ->
     Pair = #{public := Public} = ecu_eddsa:sign_keypair(),
@@ -126,28 +151,212 @@ sumcheck(Width, Bits) ->
     end.
 
 
-
+-spec shared_secret_a(A_E_E_SK, B_P_E_PK, B_E_E_PK, Protocol, Version, Salt) -> SS
--spec lcg(integer()) -> integer().
+    when A_E_E_SK :: binary(),
-%% A simple PRNG that fits into 32 bits and is easy to implement anywhere (Kotlin).
+         B_P_E_PK :: <<_:32*8>>,
-%% Specifically, it is a "linear congruential generator" of the Lehmer variety.
+         B_E_E_PK :: <<_:32*8>>,
-%% The constants used are based on recommendations from Park, Miller and Stockmeyer:
+         Protocol :: binary(),
-%% https://www.firstpr.com.au/dsp/rand31/p105-crawford.pdf#page=4
+         Version  :: binary(),
+         Salt     :: binary(),
+         SS       :: <<_:32*8>>.
+%% @doc
+%% Alice's side of a shared key derivation based on ed25519 keys as generated by this module.
 %%
-%% The input value should be between 1 and 2^31-1.
+%% Typically Alice would be providing an ephemeral key to establish
-%%
+%% a shared secret while remaining (at least initially) anonymous from Bob. Bob,
-%% The purpose of this PRNG is for password-based dictionary shuffling.
+%% on the other hand, is providing a permanent key and also an ephemeral key,
+%% proving identity without exposing the shared secret in the future were one of
+%% the secrets to be compromised.
+%% <ul>
+%%  <li>`A_E_E_SK' Alice's Ephemeral Ed25519 Secret Key.</li>
+%%  <li>`B_P_E_PK' Bob's Permanent Ed25519 Public Key.</li>
+%%  <li>`B_E_E_PK' Bob's Ephemeral Ed25519 Public Key.</li>
+%%  <li>`Protocol' is an arbitrary binary string, typically a protocol name in UTF-8.</li>
+%%  <li>`Version' is another arbitrary binary string, typically a protocol version in UTF-8.</li>
+%%  <li>`Salt' is a binary salt, which if empty will be replaced by a binary string of zeroes.</li>
+%%  <li>`SS' is the resulting 32-byte shared secret.</li>
+%% </ul>
 
-lcg(N) ->
+shared_secret_a(A_E_E_SK, B_P_E_PK, B_E_E_PK, Protocol, Version, Salt) ->
-    M = 16#7FFFFFFF,
+    A_E_X_SK = ed25519_sk_to_x25519(A_E_E_SK),
-    A = 48271,
+    B_P_X_PK = ed25519_pk_to_x25519(B_P_E_PK),
-    Q = 44488,  %  M div A
+    B_E_X_PK = ed25519_pk_to_x25519(B_E_E_PK),
-    R = 3399,   %  M rem A
+    DH_Permanent = crypto:compute_key(ecdh, B_P_X_PK, A_E_X_SK, x25519),
-    Div = N div Q,
+    DH_Ephemeral = crypto:compute_key(ecdh, B_E_X_PK, A_E_X_SK, x25519),
-    Rem = N rem Q,
+    finalize_hkdf(DH_Permanent, DH_Ephemeral, Protocol, Version, Salt).
-    S = Rem * A,
+
-    T = Div * R,
+
-    Result = S - T,
+-spec shared_secret_b(B_P_E_SK, B_E_E_SK, A_E_E_PK, Protocol, Version, Salt) -> SS
-    case Result < 0 of
+    when B_P_E_SK :: binary(),
-        false -> Result;
+         B_E_E_SK :: binary(),
-        true  -> Result + M
+         A_E_E_PK :: <<_:32*8>>,
+         Protocol :: binary(),
+         Version  :: binary(),
+         Salt     :: binary(),
+         SS       :: <<_:32*8>>.
+%% @doc
+%% Bobs's side of a shared key derivation based on ed25519 keys as generated by this module.
+%%
+%% Typically Alice would be providing an ephemeral key to establish
+%% a shared secret while remaining (at least initially) anonymous from Bob. Bob,
+%% on the other hand, is providing a permanent key and also an ephemeral key,
+%% proving identity without exposing the shared secret in the future were one of
+%% the secrets to be compromised.
+%% <ul>
+%%  <li>`B_P_E_SK' Bob's Permanent Ed25519 Secret Key.</li>
+%%  <li>`B_E_E_SK' Bob's Ephemeral Ed25519 Secret Key.</li>
+%%  <li>`A_E_E_PK' Alice's Ephemeral Ed25519 Public Key.</li>
+%%  <li>`Protocol' is an arbitrary binary string, typically a protocol name in UTF-8.</li>
+%%  <li>`Version' is another arbitrary binary string, typically a protocol version in UTF-8.</li>
+%%  <li>`Salt' is a binary salt, which if empty will be replaced by a binary string of zeroes.</li>
+%%  <li>`SS' is the resulting 32-byte shared secret.</li>
+%% </ul>
+
+shared_secret_b(B_P_E_SK, B_E_E_SK, A_E_E_PK, Protocol, Version, Salt) ->
+    B_P_X_SK = ed25519_sk_to_x25519(B_P_E_SK),
+    B_E_X_SK = ed25519_sk_to_x25519(B_E_E_SK),
+    A_E_X_PK = ed25519_pk_to_x25519(A_E_E_PK),
+    DH_Permanent = crypto:compute_key(ecdh, A_E_X_PK, B_P_X_SK, x25519),
+    DH_Ephemeral = crypto:compute_key(ecdh, A_E_X_PK, B_E_X_SK, x25519),
+    finalize_hkdf(DH_Permanent, DH_Ephemeral, Protocol, Version, Salt).
+
+finalize_hkdf(DH_Permanent, DH_Ephemeral, Protocol, Version, Salt) ->
+    MixedInput = <<DH_Permanent/binary, DH_Ephemeral/binary>>,
+    Info       = <<Protocol/binary, ":", Version/binary, ":">>,
+    hkdf(sha256, MixedInput, Salt, Info).
+
+
+%% Curve25519 Prime Field Constant: 2^255 - 19
+%% Yes, in hex it reads kind of like "lucky fed"
+p() -> 16#7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFED.
+
+
+-spec ed25519_pk_to_x25519(ED25519_PubKey) -> X25519_PubKey
+    when ED25519_PubKey :: <<_:32*8>>,
+         X25519_PubKey  :: <<_:32*8>>.
+%% @doc
+%% Convert a curve 25519 public key from Edwards representation to X-coordinate
+%% representation.
+
+ed25519_pk_to_x25519(<<ED25519_PK:32/binary>>) ->
+    <<CompressedInt:256/little-integer>> = ED25519_PK,
+    % Clear the sign bit (MSB) to get the raw y-coordinate
+    Y = CompressedInt band ((1 bsl 255) - 1),
+
+    % Compute u = (1 + y) / (1 - y) mod P
+    Num = (1 + Y) rem p(),
+    Den = (1 - Y + p()) rem p(),
+    case Den =:= 0 of
+        true -> 
+            % If y == 1, the point maps to the point at infinity.
+            % On X25519, this translates to u = 0.
+            <<0:256/little-integer>>;
+        false ->
+            U = (Num * mod_inv(Den, p())) rem p(),
+            <<U:256/little-integer>>
     end.
+
+
+-spec ed25519_sk_to_x25519(ED25519_SecKey) -> X25519_SecKey
+    when ED25519_SecKey :: binary(),
+         X25519_SecKey  :: <<_:32*8>>.
+%% @doc
+%% Convert a curve 25519 secret key from Edwards representation to X-coordinate
+%% representation.
+
+ed25519_sk_to_x25519(<<ED25519_SK_Secret:32/binary, _/binary>>) ->
+    <<X25519_SK:32/binary, _/binary>> = crypto:hash(sha512, ED25519_SK_Secret),
+    X25519_SK.
+
+mod_inv(A, M) ->
+    {1, X, _} = ext_gcd(A, M),
+    (X + M) rem M.
+
+ext_gcd(A, 0) ->
+    {A, 1, 0};
+ext_gcd(A, B) ->
+    {G, X1, Y1} = ext_gcd(B, A rem B),
+    {G, Y1, X1 - (A div B) * Y1}.
+
+
+-spec hkdf(Hash, IKM, Salt, Info) -> DerivedKey
+    when Hash       :: md5 | sha | sha224 | sha256 | sha384 | sha512,
+         IKM        :: binary(),
+         Salt       :: binary(),
+         Info       :: binary(),
+         DerivedKey :: <<_:32*8>>.
+%% @doc
+%% 32-byte HMAC-Based Extract-and-Expand Key Derivation
+%% @equiv hkdf(Hash, IKM, Salt, Info, 32)
+
+hkdf(Hash, IKM, Salt, Info) ->
+    hkdf(Hash, IKM, Salt, Info, 32).
+
+
+-spec hkdf(Hash, IKM, Salt, Info, Length) -> DerivedKey
+    when Hash       :: md5 | sha | sha224 | sha256 | sha384 | sha512,
+         IKM        :: binary(),
+         Salt       :: binary(),
+         Info       :: binary(),
+         Length     :: 16 | 20 | 28 | 32 | 48 | 64,
+         DerivedKey :: binary().
+%% @doc
+%% RFC-5869 compliant HMAC-Based Extract-and-Expand Key Derivation
+%%
+%% RFC-5869:
+%% <a href="https://datatracker.ietf.org/doc/html/rfc5869">https://datatracker.ietf.org/doc/html/rfc5869</a>
+%%
+%% The purpose of HKDF is to take an initial, raw secret input that might
+%% be mathematically strong but structurally "clumpy" and transform it into one
+%% or more uniform, high-entropy keys suitable for use in cryptography.
+%% 
+%% The problem is that when Alice and Bob compute a Diffie-Hellman shared secret
+%% over X25519, the resulting bytes are mathematically secure, but they are not
+%% evenly distributed as random noise. Cryptographic ciphers expect keys where
+%% every single bit has an exactly 50% chance of being a 0 or a 1. Passing raw
+%% DH outputs straight into a cipher can introduce subtle, exploitable patterns.
+%%
+%% HKDF "smooths out" the entropy.
+%%
+%% HMAC stands for "Keyed-Hash Message Authentication Code", but without the
+%% leading "K" just to keep us on our toes. The problem it solves is that simply
+%% concatenating a secret and some target data and hashing them together to produce
+%% a message authentication hash leaves the resulting hash vulnerable to a "length
+%% extension attack". An attacker can append additional data to the end of the
+%% message and arrive at a valid new hash without ever knowing the secret.
+%%
+%% RFC-2104 provides good background information on the technique:
+%% <a href="https://datatracker.ietf.org/doc/html/rfc2104">https://datatracker.ietf.org/doc/html/rfc2104</a>
+
+hkdf(Hash, IKM, Salt, Info, Length) ->
+    PRK = extract(Hash, Salt, IKM),
+    expand(Hash, PRK, Info, Length).
+
+extract(Hash, <<>>, IKM) ->
+    %% If salt is empty RFC 5869 requires a string of zeros equal to hash size
+    Salt = binary:copy(<<0>>, hash_size(Hash)),
+    extract(Hash, Salt, IKM);
+extract(Hash, Salt, IKM) ->
+    crypto:mac(hmac, Hash, Salt, IKM).
+
+expand(Hash, PRK, Info, OutLen) ->
+    HashLen = hash_size(Hash),
+    BlockCount = (OutLen + HashLen - 1) div HashLen,
+    true = BlockCount =< 255,
+    FullBlocks = expand_loop(Hash, PRK, Info, BlockCount, 1, <<>>, <<>>),
+    <<Output:OutLen/binary, _/binary>> = FullBlocks,
+    Output.
+
+expand_loop(Hash, PRK, Info, N, Counter, PrevT, Acc) when Counter =< N ->
+    Payload = <<PrevT/binary, Info/binary, Counter:8>>,
+    T = crypto:mac(hmac, Hash, PRK, Payload),
+    expand_loop(Hash, PRK, Info, N, Counter + 1, T, <<Acc/binary, T/binary>>);
+expand_loop(_, _, _, _, _, _, Acc) ->
+    Acc.
+
+hash_size(md5)    -> 16;
+hash_size(sha)    -> 20;
+hash_size(sha224) -> 28;
+hash_size(sha256) -> 32;
+hash_size(sha384) -> 48;
+hash_size(sha512) -> 64.

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_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}},