Merge pull request 'Fix docs' (#24) from contract-spend into master

Reviewed-on: #24

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

ebin/hakuzaru.app

@@ -3,7 +3,7 @@
               {included_applications,[]},
               {applications,[stdlib,kernel]},
               {description,"Gajumaru interoperation library"},
-              {vsn,"0.8.2"},
+              {vsn,"0.9.1"},
-              {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.1").
 -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.1").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").
@@ -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,
@@ -272,8 +272,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 +283,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 +298,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 +342,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
@@ -356,7 +356,7 @@ top_height() ->
     when TopBlock :: microblock_header(),
          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 +386,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 +444,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 +603,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}
@@ -691,8 +681,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 +693,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 +706,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 +783,39 @@ 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}
+                 | {project, Bundle}
+                 | {error,   Reason},
+         Source :: string(),
+         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, Bundle} ->
+            {project, Bundle};
+        Error ->
+            io:format("Dis chit happen: ~tp~n", [Error]),
+            {ok, TarBaby}
+    end.
+
 
 -spec contract_poi(ID) -> {ok, Bytecode} | {error, Reason}
     when ID       :: contract_id(),
@@ -892,14 +909,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
@@ -918,16 +938,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 +982,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 +1014,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 +1055,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 +1065,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 +1077,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 +1098,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 +1119,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 +1178,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 +1205,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 +1278,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 +1316,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 +1357,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 +1457,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 +1533,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 +1599,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,11 +1613,34 @@ 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}.
 
 
 sign_tx(Unsigned, SecKey) ->
@@ -1589,7 +1708,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 +1752,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.
 
 

src/hz_aaci.erl

@@ -10,14 +10,14 @@
 %%% @end
 
 -module(hz_aaci).
--vsn("0.8.2").
+-vsn("0.9.1").
 -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,
@@ -25,29 +25,65 @@
 
 %%% 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 aaci() :: {aaci, string(), #{string() => function_spec()}, #{string() => typedef()}}.
+-type function_spec() :: {[{string(), annotated_type()}], annotated_type()}.
+-type typedef() :: {[string()], typedef_rhs()}.
+
+-type annotated_type() :: {opaque_type(), already_normalized | opaque_type(), builtin_type(annotated_type())}.
+-type builtin_type(T) ::   {bytes, [integer() | any]}
+                         | {record, [{string(), T}]}
+                         | {variant, [{string(), [T]}]}
+                         | {tuple, [T]}
+                         | {list, [T]}
+                         | {map, [T]}
+                         | integer
+                         | boolean
+                         | bits
+                         | char
+                         | string
+                         | address
+                         | signature
+                         | contract
+                         | channel
+                         | unknown_type.
+
+-type opaque_type() :: string() | {string(), [opaque_type()]} | builtin_type(opaque_type()).
+
+-type typedef_rhs() :: {var, string()} | string() | {string(), [opaque_type()]} | builtin_type(typedef_rhs()).
+
+-type erlang_repr() ::   integer()
+                       | string()
+                       | boolean()
+                       | binary()
+                       | tuple() % Tuples, variants, or raw addresses
+                       | [erlang_repr()]
+                       | #{erlang_repr() => erlang_repr()}.
 
 %%% 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
 %% of calldata
 
-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().
+
+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
@@ -65,6 +101,12 @@ prepare_aaci(ACI) ->
 
     {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.
@@ -133,6 +175,12 @@ 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_rhs()} | list(typedef_tree()).
+
 collect_opaque_types([], Types) ->
     Types;
 collect_opaque_types([L | R], Types) ->
@@ -143,6 +191,11 @@ collect_opaque_types({Name, Params, Def}, Types) ->
 
 %%% ACI Type -> Opaque Type
 
+-spec opaque_type(Params, ACIType) -> Opaque
+    when Params  :: [string()],
+         ACIType :: binary() | map(),
+         Opaque  :: typedef_rhs().
+
 % 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) ->
@@ -170,6 +223,8 @@ 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;
@@ -279,6 +334,12 @@ 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} | {error, Reason}
+    when Opaque    :: opaque_type(),
+         Types     :: #{string() => typedef()},
+         Annotated :: annotated_type(),
+         Reason    :: none().
+
 annotate_type(T, Types) ->
     case normalize_opaque_type(T, Types) of
         {ok, AlreadyNormalized, NOpaque, NExpanded} ->
@@ -444,6 +505,14 @@ substitute_opaque_types(Bindings, 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().
+
 erlang_args_to_fate(VarTypes, Terms) ->
     DefLength = length(VarTypes),
     ArgLength = length(Terms),
@@ -453,6 +522,14 @@ 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().
+
 erlang_to_fate({_, _, integer}, S) when is_integer(S) ->
     {ok, S};
 erlang_to_fate({O, N, integer},  S) when is_list(S) ->
@@ -793,6 +870,14 @@ 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().
+
 fate_to_erlang({_, _, integer}, S) when is_integer(S) ->
     {ok, S};
 fate_to_erlang({_, _, address}, {address, Bin}) ->
@@ -1009,7 +1094,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.
 

src/hz_fetcher.erl

@@ -1,5 +1,5 @@
 -module(hz_fetcher).
--vsn("0.8.2").
+-vsn("0.9.1").
 -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.1").
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").
 -license("GPL-3.0-or-later").

src/hz_grids.erl

@@ -37,8 +37,8 @@
 %%% @end
 
 -module(hz_grids).
--vsn("0.8.2").
+-vsn("0.9.1").
--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
@@ -193,24 +193,28 @@ l_to_i(S) ->
 req(Type, Message) ->
     req(Type, Message, false).
 
-req(sign, Message, ID) ->
+req(Type, Message, ID) ->
+    {ok, NetworkID} = hz:network_id(),
+    req(Type, Message, ID, NetworkID).
+
+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.1").
-
 
 -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.1").
 -behavior(gen_server).
 -author("Craig Everett <ceverett@tsuriai.jp>").
 -copyright("Craig Everett <ceverett@tsuriai.jp>").

src/hz_sup.erl

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

zomp.meta

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