Add special anonymous variant syntax

This is outside of the scope of the sophia parser, but is a simple generalization to
'sophia terms' to make them able to represent any FATE term anonymously.

We also parse these anonymous variant expressions without type info, since it is convenient
for users to copy the output of one call into another call.

Anonymous parsing of None and Some was also added, since new users would be shocked if this
doesn't work, and advanced users will greatly appreciate that it does. The resulting FATE
terms are still rendered as variant([0, 1], ...), since user defined types can also have [0, 1]
as their arity list, and since automation and tooling programmers hate special case exceptions like that.

Anonymous parsing of other Chain and AENS terms are not added, since anonymous variants already cover those types,
so very little is gained by hard-coding such complex types into the term parser. Complex, version-specific compiler
types are already supported by hakuzaru, in the form of the ACI/AACI; parsing without AACI, on the other hand, is
intended to support language-agnostic communication using the primitives of FATE, and in general, variants
in FATE are anonymous.

.gitignore

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

doc/custom/stylesheet.css

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

doc/overview.edoc

@@ -1,5 +1,6 @@
-@author Craig Everett <craigeverett@qpq.swiss> [https://git.qpq.swiss/QPQ-AG/hakuzaru]
-@version 0.8.0
+@author Craig Everett <craigeverett@qpq.swiss> [https://zxq9.com]
+@author Jarvis Carrol <jarviscarrol@qpq.swiss> [https://jarviscarroll.net/]
+@version 0.9.2
 @title Hakuzaru: Gajumaru blockchain bindings for Erlang
 
 @doc
@@ -21,7 +22,7 @@ After startup `hz_man' must be given the address and port of a list of Gajumaru
 Note that the service nodes will need to have the dry-run endpoint enabled and the internal service query port made available in order to provide dry-runs and transaction submission.
 
 When configuring chain nodes a list of nodes should be provided.
-To avoid sync issues in the case of fast transaction formation/submission to the chain, only one node from the list of chain nodes is used for submitting transactions and querying `next_nonce/1`.
+To avoid sync issues in the case of fast transaction formation/submission to the chain, only one node from the list of chain nodes is used for submitting transactions and querying `next_nonce/1'.
 This node is called "the sticky node".
 
 The first node in the list of chain nodes provided during configuration is designated as the sticky node.

ebin/hakuzaru.app

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

src/hakuzaru.erl

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

src/hz.erl

@@ -23,7 +23,7 @@
 %%% @end
 
 -module(hz).
--vsn("0.8.2").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -45,7 +45,7 @@
          acc/1, acc_at_height/2, acc_at_block_id/2,
          acc_pending_txs/1,
          next_nonce/1,
-         dry_run/1, dry_run/2, dry_run/3, dry_run_map/1,
+         dry_run/1, dry_run/2, dry_run/3, % dry_run_map/1,
          tx/1, tx_info/1,
          post_tx/1,
          contract/1, contract_code/1, contract_source/1,
@@ -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
-%% the tail.
+%% read-only queries, put the sticky node in the list twice.
 
 chain_nodes(List) when is_list(List) ->
     hz_man:chain_nodes(List).
@@ -284,7 +284,7 @@ chain_nodes(List) when is_list(List) ->
 %% Check whether TLS is in use. The typical situation is to not use TLS as nodes that
 %% serve as part of the backend of an application are typically run in the same
 %% backend network as the application service. When accessing chain nodes over the WAN
-%% however, TLS is strongly recommended to avoid a MITM attack.
+%% however, TLS is recommended to avoid a MitM attack.
 %%
 %% In this version of Hakuzaru TLS is either on or off for all nodes, making a mixed
 %% infrastructure complicated to support without two Hakuzaru instances. This will
@@ -299,7 +299,7 @@ tls() ->
 -spec tls(boolean()) -> ok.
 %% @doc
 %% Set TLS true or false. That's what a boolean is, by the way, `true' or `false'.
-%% This is a condescending comment. That means I am talking down to you.
+%% This is a condescending comment. That means to talk down to someone.
 %%
 %% TLS defaults to `false'.
 
@@ -343,7 +343,8 @@ timeout(MS) ->
 %% NOTE:
 %% This will return the currently synced height, which may be different than the
 %% actual current top of the entire chain if the node being queried is still syncing
-%% (has not yet caught up with the chain).
+%% (has not yet caught up with the chain). More complete information, including
+%% whether the node is currently syncing, can be gained from a `status()' query.
 
 top_height() ->
     case top_block() of
@@ -353,10 +354,10 @@ top_height() ->
 
 
 -spec top_block() -> {ok, TopBlock} | {error, Reason}
-    when TopBlock :: microblock_header(),
+    when TopBlock :: microblock_header() | keyblock(),
          Reason   :: chain_error().
 %% @doc
-%% Returns the current block height as an integer.
+%% Returns the header of the current top block.
 
 top_block() ->
     request("/v3/headers/top").
@@ -386,7 +387,7 @@ kb_current() ->
 kb_current_hash() ->
     case request("/v3/key-blocks/current/hash") of
         {ok, #{"reason" := Reason}} -> {error, Reason};
-        {ok, #{"hash" := Hash}}     -> {ok, Hash};
+        {ok, #{"hash"   := Hash}}   -> {ok, Hash};
         Error                       -> Error
     end.
 
@@ -444,10 +445,6 @@ kb_by_height(Height) ->
     result(request(["/v3/key-blocks/height/", StringN])).
 
 
-%kb_insert(KeyblockData) ->
-%    request("/v3/key-blocks", KeyblockData).
-
-
 -spec mb_header(ID) -> {ok, MB_Header} | {error, Reason}
     when ID        :: microblock_hash(),
          MB_Header :: microblock_header(),
@@ -607,12 +604,6 @@ next_nonce(AccountID) ->
         {ok, #{"reason" := Reason}}              -> {error, Reason};
         Error                                    -> Error
     end.
-%   case request_sticky(["/v3/accounts/", AccountID]) of
-%       {ok, #{"nonce"  := Nonce}}               -> {ok, Nonce + 1};
-%       {ok, #{"reason" := "Account not found"}} -> {ok, 1};
-%       {ok, #{"reason" := Reason}}              -> {error, Reason};
-%       Error                                    -> Error
-%   end.
 
 
 -spec dry_run(TX) -> {ok, Result} | {error, Reason}
@@ -671,9 +662,10 @@ dry_run(TX, Accounts, KBHash) ->
     request("/v3/dry_run", JSON).
 
 
-dry_run_map(Map) ->
-    JSON = zj:binary_encode(Map),
-    request("/v3/dry_run", JSON).
+% TODO
+%dry_run_map(Map) ->
+%    JSON = zj:binary_encode(Map),
+%    request("/v3/dry_run", JSON).
 
 
 -spec decode_bytearray_fate(EncodedStr) -> {ok, Result} | {error, Reason}
@@ -691,8 +683,10 @@ decode_bytearray_fate(EncodedStr) ->
     Encoded = unicode:characters_to_binary(EncodedStr),
     {contract_bytearray, Binary} = gmser_api_encoder:decode(Encoded),
     case Binary of
-        <<>> -> {ok, none};
-        <<"Out of gas">> -> {error, out_of_gas};
+        <<>> ->
+            {ok, none};
+        <<"Out of gas">> ->
+            {error, out_of_gas};
         _ ->
             % FIXME there may be other errors that are encoded directly into
             % the byte array. We could try and catch to at least return
@@ -701,8 +695,9 @@ decode_bytearray_fate(EncodedStr) ->
             {ok, Object}
     end.
 
--spec decode_bytearray(Type, EncodedStr) -> {ok, Result} | {error, Reason}
-    when Type       :: term(),
+-spec decode_bytearray(EncodedStr, Format) -> {ok, Result} | {error, Reason}
+    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}
-    when ID       :: contract_id(),
-         Bytecode :: contract_byte_array(),
-         Reason   :: chain_error() | string().
+-spec contract_source(ID) -> Result
+    when ID     :: contract_id(),
+         Result :: {ok,      Source}
+                 | {project, Bundle}
+                 | {error,   Reason},
+         Source :: binary(),
+         Bundle :: [{FilePath :: string(), Contents :: binary()}],
+         Reason :: chain_error() | string().
 %% @doc
 %% Retrieve the code of a contract as represented on chain.
 
 contract_source(ID) ->
     case request(["/v3/contracts/", ID, "/source"]) of
-        {ok, #{"source" := Source}} -> {ok, Source};
+        {ok, #{"source" := Blobby}} -> extract(list_to_binary(Blobby));
         {ok, #{"reason" := Reason}} -> {error, Reason};
         Error                       -> Error
     end.
 
+extract(Blobby) ->
+    case gmser_api_encoder:safe_decode(bytearray, Blobby) of
+        {ok, TarBaby}             -> extract2(TarBaby);
+        {error, invalid_encoding} -> {ok, Blobby}
+    end.
+
+extract2(TarBaby) ->
+    case erl_tar:extract({binary, TarBaby}, [memory, compressed]) of
+        {ok, [{_, Source}]} ->
+            {ok, Source};
+        {ok, Bundle} ->
+            {project, Bundle};
+        {error,invalid_tar_checksum} ->
+            {ok, TarBaby};
+        Error ->
+            ok = io:format("erl_tar:extract/2 error: ~tp~n", [Error]),
+            {ok, TarBaby}
+    end.
+
 
 -spec contract_poi(ID) -> {ok, Bytecode} | {error, Reason}
     when ID       :: contract_id(),
@@ -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
-%%   argument of `10' must be cast to the textual representation `"10"').
+%%   according to the function's spec. Arguments can be represented as a list of
+%%   Sophia literals (a simple list of strings), or alternately as a list of compatible
+%%   Erlang, FATE or Sophia terms wrapped in a tuple which specifies the representation.
 %%  </li>
 %% </ul>
 %% As should be obvious from the above description, it is pretty helpful to have a
@@ -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,
-                             Source, Options, InitArgs);
+            contract_create2(CreatorID, Nonce, Gas, GasPrice, Amount, TTL,
+                             Name, Source, Options, InitArgs);
         Error ->
             Error
     end.
 
 
-contract_create2(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Source, Options, InitArgs) ->
+contract_create2(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Name, Source, Options, InitArgs) ->
     case so_compiler:from_string(Source, Options) of
         {ok, Compiled} ->
-            contract_create_built(CreatorID, Nonce, Amount, TTL, Gas, GasPrice,
-                                  Compiled, InitArgs);
+            Named = maps:put(contract_name, Name, Compiled),
+            contract_create_built(CreatorID, Nonce, Gas, GasPrice, Amount, TTL,
+                                  Named, InitArgs);
         Error ->
             Error
     end.
@@ -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) ->
-    AACI = hz_aaci:prepare_aaci(maps:get(aci, Compiled)),
+-spec contract_create_built(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, InitArgs) -> Result
+    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,
-                              Compiled, CallData);
+            assemble_calldata(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData);
         Error ->
             Error
     end.
 
 
-assemble_calldata(CreatorID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallData) ->
+assemble_calldata(CreatorID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData) ->
     PK = unicode:characters_to_binary(CreatorID),
     try
         {account_pubkey, OwnerID} = gmser_api_encoder:decode(PK),
-        assemble_calldata2(OwnerID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallData)
+        assemble_calldata2(OwnerID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData)
     catch
-        Error:Reason -> {Error, Reason}
+        Error:Reason:Stack ->
+            {Error, {Reason, Stack}}
     end.
 
-assemble_calldata2(OwnerID, Nonce, Amount, TTL, Gas, GasPrice, Compiled, CallData) ->
-    Code = gmser_contract_code:serialize(Compiled),
-    Source = unicode:characters_to_binary(maps:get(contract_source, Compiled, <<>>)),
+assemble_calldata2(OwnerID, Nonce, Gas, GasPrice, Amount, TTL, Compiled, CallData) ->
+    Compressed = #{contract_source := Bundle} = bundle_source(Compiled),
+    Code = gmser_contract_code:serialize(Compressed),
     VM = 1,
     ABI = 1,
     <<CTVersion:32>> = <<VM:16, ABI:16>>,
@@ -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
-%%   argument of `10' must be cast to the textual representation `"10"').
+%%   according to the function's spec. Arguments can be represented as a list of
+%%   Sophia literals (a simple list of strings), or alternately as a list of compatible
+%%   Erlang, FATE or Sophia terms wrapped in a tuple which specifies the representation.
 %%  </li>
 %% </ul>
 %% As should be obvious from the above description, it is pretty helpful to have a
@@ -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.
 
@@ -1475,10 +1583,10 @@ lookup_aaci(Label) ->
 %% useful for calling decode_bytearray/2.
 
 aaci_lookup_spec(AACI = {aaci, _, _, _}, Fun) ->
-    hz_aaci:aaci_get_function_signature(AACI, Fun);
+    hz_aaci:get_function_signature(AACI, Fun);
 aaci_lookup_spec({aaci, Label}, Fun) ->
     case hz_man:lookup_aaci(Label) of
-        {ok, AACI} -> hz_aaci:aaci_get_function_signature(AACI, Fun);
+        {ok, AACI} -> hz_aaci:get_function_signature(AACI, Fun);
         error      -> {error, aaci_not_found}
     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
-    end.
+        Errors        -> Errors
+    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
-        {account_pubkey, PK}  = gmser_api_encoder:decode(B),
-        {ok, PK}
-    catch
-        E:R -> {E, R}
+    case gmser_api_encoder:safe_decode(account_pubkey, B) of
+        {ok, PK}                -> {ok, PK};
+        {error, invalid_prefix} -> gmser_api_encoder:safe_decode(contract_pubkey, B);
+        Error                   -> Error
     end.
 
 
@@ -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_fetcher.erl

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

src/hz_format.erl

@@ -21,7 +21,7 @@
 %%% @end
 
 -module(hz_format).
--vsn("0.8.2").
+-vsn("0.9.2").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -462,9 +462,26 @@ ranks(heresy) ->
     ["k ", "m ", "b ", "t ", "q ", "e ", "z ", "y ", "r ", "Q "].
 
 
+-spec mark(Unit) -> Mark
+    when Unit :: gaju | puck,
+         Mark :: $木 | $本.
+%% @doc
+%% Retrieve the unicode codepoint for the `gaju' mark (木) or the `puck' mark (本).
+
 mark(gaju) -> $木;
 mark(puck) -> $本.
 
+
+-spec one(Unit) -> Pucks
+    when Unit  :: gaju | puck,
+         Pucks :: 1_000_000_000_000_000_000 | 1.
+%% @doc
+%% Quickly resolve the number of pucks in a given unit.
+%%
+%% The number of pucks in a gaju is so large that it can be a little bit annoying
+%% to remember the exact amount. This is a helper to simplify this when writing
+%% an app against the hakuzaru library when dealing in either unit.
+
 one(gaju) -> 1_000_000_000_000_000_000;
 one(puck) -> 1.
 

src/hz_grids.erl

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

src/hz_key_master.erl

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

src/hz_man.erl

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

src/hz_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}},