From 60c8adb4b183a8e5a26ff020f7463e3adbf18618 Mon Sep 17 00:00:00 2001 From: Craig Everett Date: Mon, 22 Dec 2025 11:39:46 +0900 Subject: [PATCH] Update docs --- doc/overview.edoc | 116 +++++++++++++++++++++++----------------------- ebin/hakuzaru.app | 4 +- 2 files changed, 61 insertions(+), 59 deletions(-) diff --git a/doc/overview.edoc b/doc/overview.edoc index 4890d35..64a0dbf 100644 --- a/doc/overview.edoc +++ b/doc/overview.edoc @@ -1,77 +1,79 @@ -@author Craig Everett [https://gitlab.com/zxq9/zj] -@version 0.3.0 -@title Vanillae: Aeternity blockchain bindings for Erlang +@author Craig Everett [https://git.qpq.swiss/zxq9] +@version 0.8.0 +@title Hakuzaru: Gajumaru blockchain bindings for Erlang @doc -This Erlang application provides bindings for the Erlang blockchain. -The primary goal is for usage to be easy to understand and as simple as possible to use. -The secondary goal is to enable real-world projects to more easily connect with the blockchain in an obvious way and provide a clear path for them to provide feedback regarding areas that are difficult to understand, functionality that is lacking, and explain their use cases to us so we can more easily provide needed features and usage examples to make adoption easier. +This Erlang application provides bindings for the Gajumaru blockchain and basic utilities for manipulating Gajumaru-related data. -== Basic operation == -All external interfaces expected to be used by authors of programs that use Vanillae are built into the `vanillae' module. +== To Start or Not To Start == +Starting the `hakuzaru' application is only required if you need to query the chain. -When Vanillae is started as an application a named process called `vanillae_man' is spawned that manages interactions with and the state of the service, as well as a simple-one-for-one supervisor that manages the lifecycle of Vanillae workers (defined in `vanillae_fetcher'). +The application can be started via a call to `application', or with an explicit call to `hz:start()'. -After startup `vanillae_man' must be given the address and port of a list of Aeternity nodes that are available to service requests. 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 run" and mempool TX submission functionality. +Hakuzaru can also be run as a local application from the shell by invoking it with `zxh run hakuzaru' if you have `zx' installed. -The `vanillae_man' will round-robin requests to however many Aeternity nodes are provided in its configuration. Note that this congiruation is dynamic and can be changed completely at runtime. +== Operation == +All blockchain-specific operations are accessible from the main interface modulle: `hz' -== Functions == -The `vanillae' module exposes one function per blockchain feature provided. Most of these are actually wrappers for blockchain endpoint functions, others provide functionality specific to accomplishing a local processing task related to chain data. +When Hakuzaru is started as an application a named process called `hz_man' is spawned that manages interactions with chain nodes, as well as a simple-one-for-one supervisor that manages the lifecycle of workers (defined in `hz_fetcher'). -== Initialization == -When Vanillae is first started the vanillae_man is started but does not yet know what Aeternity nodes to use to service queries. You will need to provide it with at least one node and port where it can make Aeternity endpoint calls. +After startup `hz_man' must be given the address and port of a list of Gajumaru nodes that are available to service requests. +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. -Note that if you will need to make read-only calls to contracts that are deployed on chain (to queery their state or perform specific read-only operations provided by the contract) the backend nodes you configure will need to be configured with "dry-run" enabled. +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`. +This node is called "the sticky node". -Example of a shell session where vanillae is started and initialized manually with an AE node in the local network at 192.168.10.10:3013: +The first node in the list of chain nodes provided during configuration is designated as the sticky node. +If you also want to use the sticky node as a query endpoint, include it twice in the list. + +The `hz_man' will round-robin requests to however many additional Gajumaru nodes are provided in the configuration. +Note that this configuration is dynamic and can be changed at runtime, so your service can adapt to node availability on the fly if needed. ``` -1> vanillae:start(). -Starting. +ceverett@steak:~$ zxh run hakuzaru +Erlang/OTP 27 [erts-15.2] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns] + +Eshell V15.2 (press Ctrl+G to abort, type help(). for help) +Fetching otpr-hakuzaru-0.8.0 +[100.00%] +Recompile: src/hz_sup +Recompile: src/hz_man +Recompile: src/hz_key_master +Recompile: src/hz_grids +Recompile: src/hz_format +Recompile: src/hz_fetcher +Recompile: src/hz +Recompile: src/hakuzaru +Starting otpr-hakuzaru-0.8.0. +hz_man starting. +Started [hakuzaru] +1> hz:chain_nodes([{"groot.testnet.gajumaru.io", 3013}]). ok -2> vanillae:status(). -{error,no_nodes} -3> vanillae:ae_nodes([{"192.168.7.7", 3013}]). -ok -4> vanillae:status(). -{ok,#{"difficulty" => 59729882, +2> hz:status(). +{ok,#{"difficulty" => 2877405482, + "finalized" => + #{"hash" => + "kh_PDSn6Xru5JVdpJfdDCNpfsL8gUZvvjyhTYuzgndoy98G5oLLR", + "height" => 277454,"type" => "height"}, "genesis_key_block_hash" => - "kh_wUCideEB8aDtUaiHCtKcfywU6oHZW6gnyci8Mw6S1RSTCnCRu", - "listening" => true,"network_id" => "ae_uat", + "kh_Qdi5MTuuhJm7xzn5JUAbYG12cX3qoLMnXrBxPGzBkMWJ4K8vq", + "hashrate" => 864394,"listening" => true, + "network_id" => "groot.testnet", "node_revision" => - "3a08153c635c53d92029a617f2e784731ba367c6", - "node_version" => "6.7.0", - "peer_connections" => #{"inbound" => 25,"outbound" => 10}, - "peer_count" => 50, + "7b3cc1db3bb36053023167b86f7d6f2d5dcbd01d", + "node_version" => "0.1.0+203.7b3cc1db3", + "peer_connections" => #{"inbound" => 1,"outbound" => 3}, + "peer_count" => 5, "peer_pubkey" => - "pp_fCBqobeSwhdnrzC8DoSsmWbf2GzDK61CJujmsCEd3RUkmh9Ny", - "pending_transactions_count" => 2, + "pp_2nQHucGyEt5wkYruNuRkg19cbZuEeyR9BZfvtv49F3AoyNSYMT", + "pending_transactions_count" => 0, "protocols" => - [#{"effective_at_height" => 425900,"version" => 5}, - #{"effective_at_height" => 154300,"version" => 4}, - #{"effective_at_height" => 82900,"version" => 3}, - #{"effective_at_height" => 40900,"version" => 2}, - #{"effective_at_height" => 0,"version" => 1}], + [#{"effective_at_height" => 0,"version" => 1}], "solutions" => 0,"sync_progress" => 100.0, - "syncing" => false,"top_block_height" => 802644, + "syncing" => false,"top_block_height" => 277555, + "top_hash" => + "kh_2vuNc8eG77aTmHcQDcievjKufFwR4MSSuZbEMWwW5TqUzSQy71", "top_key_block_hash" => - "kh_28LZSvHZPCGqeWsMsqtSjxQjQHKW1pHzoBex97oMT7U2HcLPgV"}} -''' - -Alternatively, here is a start function for an application using Vanillae that initializes vanillae_man with a list of nodes provided by a configuration file: - -``` -start(normal, _Args) -> - ok = application:ensure_started(sasl), - {ok, Started} = application:ensure_all_started(cowboy), - ok = application:ensure_started(vanillae), - Nodes = proplists:get_value(ae_nodes, read_config(), []), - ok = vanillae:ae_nodes(Nodes), - ok = log(info, "Started: ~p~n", [[vanillae | Started]]), - Routes = [{'_', [{"/", count_top, []}]}], - Dispatch = cowboy_router:compile(Routes), - Env = #{env => #{dispatch => Dispatch}}, - {ok, _} = cowboy:start_clear(count_listener, [{port, 8080}], Env), - count_sup:start_link(). + "kh_2vuNc8eG77aTmHcQDcievjKufFwR4MSSuZbEMWwW5TqUzSQy71"}} ''' diff --git a/ebin/hakuzaru.app b/ebin/hakuzaru.app index f3cfa4d..39efaaa 100644 --- a/ebin/hakuzaru.app +++ b/ebin/hakuzaru.app @@ -4,6 +4,6 @@ {applications,[stdlib,kernel]}, {description,"Gajumaru interoperation library"}, {vsn,"0.8.0"}, - {modules,[hakuzaru,hz,hz_fetcher,hz_grids,hz_key_master,hz_man, - hz_sup]}, + {modules,[hakuzaru,hz,hz_fetcher,hz_format,hz_grids, + hz_key_master,hz_man,hz_sup]}, {mod,{hakuzaru,[]}}]}.