From 44ca045158b0f98c56927ccb8acaed746632b4d0 Mon Sep 17 00:00:00 2001 From: fluidvanadium Date: Wed, 18 Feb 2026 17:31:58 +0000 Subject: [PATCH 1/6] Rephrase a zainod start error. --- zaino-fetch/src/jsonrpsee/connector.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zaino-fetch/src/jsonrpsee/connector.rs b/zaino-fetch/src/jsonrpsee/connector.rs index b59519d5f..b27b09e4a 100644 --- a/zaino-fetch/src/jsonrpsee/connector.rs +++ b/zaino-fetch/src/jsonrpsee/connector.rs @@ -921,7 +921,7 @@ pub async fn test_node_and_return_url( } interval.tick().await; } - error!("Error: Could not establish connection with node. Please check config and confirm node is listening at {url} and the correct authorisation details have been entered. Exiting.."); + error!("Error: Zainod needs to connect to a zcash Validator node. (either zcashd or zebrad). Failed to connect to a Validator at {url}. Perhaps the Validator is not running or perhaps there was an authentication error. Exiting.."); std::process::exit(1); } From f634d77095ce2f618ea8811abbb445055c7c3d88 Mon Sep 17 00:00:00 2001 From: fluidvanadium Date: Wed, 18 Feb 2026 22:54:27 +0000 Subject: [PATCH 2/6] Add tutorial doc. Stuck on not knowing what error is actually happening. --- zaino-fetch/src/jsonrpsee/connector.rs | 3 ++- zainod/Z3.md | 33 ++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 zainod/Z3.md diff --git a/zaino-fetch/src/jsonrpsee/connector.rs b/zaino-fetch/src/jsonrpsee/connector.rs index b27b09e4a..f5087c03e 100644 --- a/zaino-fetch/src/jsonrpsee/connector.rs +++ b/zaino-fetch/src/jsonrpsee/connector.rs @@ -916,12 +916,13 @@ pub async fn test_node_and_return_url( return Ok(url); } Err(_) => { + // TOdo actually show this error. tokio::time::sleep(std::time::Duration::from_secs(3)).await; } } interval.tick().await; } - error!("Error: Zainod needs to connect to a zcash Validator node. (either zcashd or zebrad). Failed to connect to a Validator at {url}. Perhaps the Validator is not running or perhaps there was an authentication error. Exiting.."); + error!("Error: Zainod needs to connect to a zcash Validator node. (either zcashd or zebrad). Failed to connect to a Validator at {url}. Perhaps the Validator is not running or perhaps there was an authentication error."); std::process::exit(1); } diff --git a/zainod/Z3.md b/zainod/Z3.md new file mode 100644 index 000000000..75d65d8ba --- /dev/null +++ b/zainod/Z3.md @@ -0,0 +1,33 @@ +This is a tutorial to launch zaino, connected to a local validator. + +Step 0: Git check out zaino. + +Step 1: Set up a zebra. (According to the zebra README.) +```sh +cargo install --locked zebrad +``` + +As mentioned in +zebra-rpc/src/config/rpc.rs + > /// Note: The RPC server is disabled by default. + > /// To enable the RPC server, set a listen address in the config: + > /// ```toml + > /// [rpc] + > /// listen_addr = '127.0.0.1:8232' + > /// ``` + + +As explained in +book/src/user/startup.md + > The RPC service is optional, if it is not configured, its tasks do not run. + > + > ``` + > zebra_rpc::server: Trying to open RPC endpoint at 127.0.0.1:57638... + > zebra_rpc::server: Opened RPC endpoint at 127.0.0.1:57638 + > ``` + + +Therefore we need the following message from zebrad: +zebra_rpc::server: Opened RPC endpoint + +Use ```zebrad generate``` to generate a config file, and set it up so that zebra is launching with the custom config. Add the listen address. The default zaino listen address is 127.0.0.1:18232 From 10afbeb727cc4d4923548365411d4f4dfdedb859 Mon Sep 17 00:00:00 2001 From: fluidvanadium Date: Mon, 23 Feb 2026 18:00:31 +0000 Subject: [PATCH 3/6] Debugging connection. --- wj/notes/zainodstart.txt | 82 ++++++++++++++++++++++++++ zaino-fetch/src/jsonrpsee/connector.rs | 5 +- zainod/Z3.md | 16 ++++- 3 files changed, 98 insertions(+), 5 deletions(-) create mode 100644 wj/notes/zainodstart.txt diff --git a/wj/notes/zainodstart.txt b/wj/notes/zainodstart.txt new file mode 100644 index 000000000..c060845b9 --- /dev/null +++ b/wj/notes/zainodstart.txt @@ -0,0 +1,82 @@ +zebra off: +[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( + reqwest::Error { + kind: Request, + url: "http://127.0.0.1:18232/", + source: hyper_util::client::legacy::Error( + Connect, + ConnectError( + "tcp connect error", + 127.0.0.1:18232, + Os { + code: 111, + kind: ConnectionRefused, + message: "Connection refused", + }, + ), + ), + }, +) + +zebra 4.1 on: +listen_addr = '127.0.0.1:18232' + +[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( + reqwest::Error { + kind: Request, + url: "http://127.0.0.1:18232/", + source: hyper_util::client::legacy::Error( + SendRequest, + hyper::Error( + Parse( + Version, + ), + ), + ), + }, +) + +zebra on: +indexer_listen_addr = '127.0.0.1:18232' +[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( + reqwest::Error { + kind: Request, + url: "http://127.0.0.1:18232/", + source: hyper_util::client::legacy::Error( + SendRequest, + hyper::Error( + Parse( + Version, + ), + ), + ), + }, +) +[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( + reqwest::Error { + kind: Request, + url: "http://127.0.0.1:18232/", + source: hyper_util::client::legacy::Error( + Canceled, + hyper::Error( + Canceled, + hyper::Error( + UnexpectedMessage, + ), + ), + ), + }, +) +[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( + reqwest::Error { + kind: Request, + url: "http://127.0.0.1:18232/", + source: hyper_util::client::legacy::Error( + Canceled, + hyper::Error( + Canceled, + "connection was not ready", + ), + ), + }, +) diff --git a/zaino-fetch/src/jsonrpsee/connector.rs b/zaino-fetch/src/jsonrpsee/connector.rs index f5087c03e..9b3e1e646 100644 --- a/zaino-fetch/src/jsonrpsee/connector.rs +++ b/zaino-fetch/src/jsonrpsee/connector.rs @@ -910,12 +910,13 @@ pub async fn test_node_and_return_url( let url: Url = format!("http://{}:{}", host, addr.port()).parse()?; let mut interval = tokio::time::interval(tokio::time::Duration::from_millis(500)); - for _ in 0..3 { + for _ in 0..6 { match test_node_connection(url.clone(), auth_method.clone()).await { Ok(_) => { return Ok(url); } - Err(_) => { + Err(e) => { + dbg!(e); // TOdo actually show this error. tokio::time::sleep(std::time::Duration::from_secs(3)).await; } diff --git a/zainod/Z3.md b/zainod/Z3.md index 75d65d8ba..7cf5ea744 100644 --- a/zainod/Z3.md +++ b/zainod/Z3.md @@ -2,10 +2,14 @@ This is a tutorial to launch zaino, connected to a local validator. Step 0: Git check out zaino. -Step 1: Set up a zebra. (According to the zebra README.) -```sh -cargo install --locked zebrad +Step 1: Set up zebra v3.1.0. ``` +git clone git@github.com:ZcashFoundation/zebra.git +git checkout v3.1.0 +cargo install --path zebrad --locked +zebrad generate > zebrad_config_3.1.0.toml +``` + As mentioned in zebra-rpc/src/config/rpc.rs @@ -31,3 +35,9 @@ Therefore we need the following message from zebrad: zebra_rpc::server: Opened RPC endpoint Use ```zebrad generate``` to generate a config file, and set it up so that zebra is launching with the custom config. Add the listen address. The default zaino listen address is 127.0.0.1:18232 +``` +zebrad -c zebrad_config_3.1.0.toml +``` + +cargo run --release -- generate-config -o ../local_programs/zainod.toml +cargo run --release --features no_tls_use_unencrypted_traffic -- start -c ../local_programs/zainod.toml From 3bd2a088bd6e6289b5986197dbf0fbcf99cef8be Mon Sep 17 00:00:00 2001 From: fluidvanadium Date: Mon, 23 Feb 2026 18:00:56 +0000 Subject: [PATCH 4/6] Added TestNodeConnectionError. --- zaino-fetch/src/jsonrpsee/connector.rs | 29 ++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/zaino-fetch/src/jsonrpsee/connector.rs b/zaino-fetch/src/jsonrpsee/connector.rs index 9b3e1e646..6f002f661 100644 --- a/zaino-fetch/src/jsonrpsee/connector.rs +++ b/zaino-fetch/src/jsonrpsee/connector.rs @@ -830,13 +830,30 @@ impl JsonRpSeeConnector { } } +#[derive(Debug)] // +#[derive(thiserror::Error)] // +pub(crate) enum TestNodeConnectionError { + #[error("Building Reqwest Client: {{0}}")] + ClientBuild(reqwest::Error), + #[error("Reqwest Response: {{0}}")] + ReqwestResponse(reqwest::Error), + #[error("Response Body: {{0}}")] + ResponseBody(reqwest::Error), + #[error("Json body: {{0}}")] + BodyJson(serde_json::Error), +} + /// Tests connection with zebrad / zebrad. -async fn test_node_connection(url: Url, auth_method: AuthMethod) -> Result<(), TransportError> { +async fn test_node_connection( + url: Url, + auth_method: AuthMethod, +) -> Result<(), TestNodeConnectionError> { let client = Client::builder() .connect_timeout(std::time::Duration::from_secs(2)) .timeout(std::time::Duration::from_secs(5)) .redirect(reqwest::redirect::Policy::none()) - .build()?; + .build() + .map_err(TestNodeConnectionError::ClientBuild)?; let request_body = r#"{"jsonrpc":"2.0","method":"getinfo","params":[],"id":1}"#; let mut request_builder = client @@ -862,13 +879,13 @@ async fn test_node_connection(url: Url, auth_method: AuthMethod) -> Result<(), T let response = request_builder .send() .await - .map_err(TransportError::ReqwestError)?; + .map_err(TestNodeConnectionError::ReqwestResponse)?; let body_bytes = response .bytes() .await - .map_err(TransportError::ReqwestError)?; - let _response: RpcResponse = serde_json::from_slice(&body_bytes) - .map_err(|e| TransportError::BadNodeData(Box::new(e), ""))?; + .map_err(TestNodeConnectionError::ResponseBody)?; + let _response: RpcResponse = + serde_json::from_slice(&body_bytes).map_err(TestNodeConnectionError::BodyJson)?; Ok(()) } From 083dab1ffc0f29c337be8bf0615e9a8f80c6f20b Mon Sep 17 00:00:00 2001 From: fluidvanadium Date: Thu, 26 Feb 2026 19:57:02 +0000 Subject: [PATCH 5/6] Add tutorial and example_configs. --- docs/tutorial.md | 24 ++++++ example_configs/zainod.toml | 35 ++++++++ example_configs/zebrad_config_3.1.0.toml | 103 +++++++++++++++++++++++ zainod/Z3.md | 43 ---------- 4 files changed, 162 insertions(+), 43 deletions(-) create mode 100644 docs/tutorial.md create mode 100644 example_configs/zainod.toml create mode 100644 example_configs/zebrad_config_3.1.0.toml delete mode 100644 zainod/Z3.md diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 000000000..62b15ff5c --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,24 @@ +This is a tutorial to launch zaino, connected to a local validator. + +Step 0: Git check out zaino. + +Step 1: Set up zebra v3.1.0. +``` +git clone git@github.com:ZcashFoundation/zebra.git +git checkout v3.1.0 +cargo install --path zebrad --locked +``` + +EASY PATH: +Use included Testnet Configuration + +In the zaino git root, run +``` +zebrad -c example_configs/zebrad_config_3.1.0.toml +``` +in another shell, +``` +cargo run --release -- start -c example_configs/zainod.toml +``` + + diff --git a/example_configs/zainod.toml b/example_configs/zainod.toml new file mode 100644 index 000000000..136a7b2c3 --- /dev/null +++ b/example_configs/zainod.toml @@ -0,0 +1,35 @@ +# Zaino Configuration +# +# Generated with `zainod generate-config` +# +# Configuration sources are layered (highest priority first): +# 1. Environment variables (prefix: ZAINO_) +# 2. TOML configuration file +# 3. Built-in defaults +# +# For detailed documentation, see: +# https://github.com/zingolabs/zaino + +backend = 'fetch' +zebra_db_path = '/home/cupress/.cache/zebra' +network = 'Testnet' + +[grpc_settings] +listen_address = '127.0.0.1:8137' + +[validator_settings] +validator_grpc_listen_address = '127.0.0.1:18232' +validator_jsonrpc_listen_address = '127.0.0.1:18231' +validator_user = 'xxxxxx' +validator_password = 'xxxxxx' + +[service] +timeout = 30 +channel_size = 32 +[storage.cache] +capacity = 10000 +shard_power = 4 + +[storage.database] +path = '/home/cupress/.cache/zaino' +size = 128 diff --git a/example_configs/zebrad_config_3.1.0.toml b/example_configs/zebrad_config_3.1.0.toml new file mode 100644 index 000000000..85580b4cd --- /dev/null +++ b/example_configs/zebrad_config_3.1.0.toml @@ -0,0 +1,103 @@ +# Default configuration for zebrad. +# +# This file can be used as a skeleton for custom configs. +# +# Unspecified fields use default values. Optional fields are Some(field) if the +# field is present and None if it is absent. +# +# This file is generated as an example using zebrad's current defaults. +# You should set only the config options you want to keep, and delete the rest. +# Only a subset of fields are present in the skeleton, since optional values +# whose default is None are omitted. +# +# The config format (including a complete list of sections and fields) is +# documented here: +# https://docs.rs/zebrad/latest/zebrad/config/struct.ZebradConfig.html +# +# CONFIGURATION SOURCES (in order of precedence, highest to lowest): +# +# 1. Environment variables with ZEBRA_ prefix (highest precedence) +# - Format: ZEBRA_SECTION__KEY (double underscore for nested keys) +# - Examples: +# - ZEBRA_NETWORK__NETWORK=Testnet +# - ZEBRA_RPC__LISTEN_ADDR=127.0.0.1:8232 +# - ZEBRA_STATE__CACHE_DIR=/path/to/cache +# - ZEBRA_TRACING__FILTER=debug +# - ZEBRA_METRICS__ENDPOINT_ADDR=0.0.0.0:9999 +# +# 2. Configuration file (TOML format) +# - At the path specified via -c flag, e.g. `zebrad -c myconfig.toml start`, or +# - At the default path in the user's preference directory (platform-dependent, see below) +# +# 3. Hard-coded defaults (lowest precedence) +# +# The user's preference directory and the default path to the `zebrad` config are platform dependent, +# based on `dirs::preference_dir`, see https://docs.rs/dirs/latest/dirs/fn.preference_dir.html : +# +# | Platform | Value | Example | +# | -------- | ------------------------------------- | ---------------------------------------------- | +# | Linux | `$XDG_CONFIG_HOME` or `$HOME/.config` | `/home/alice/.config/zebrad.toml` | +# | macOS | `$HOME/Library/Preferences` | `/Users/Alice/Library/Preferences/zebrad.toml` | +# | Windows | `{FOLDERID_RoamingAppData}` | `C:\Users\Alice\AppData\Local\zebrad.toml` | + +[consensus] +checkpoint_sync = true + +[health] +enforce_on_test_networks = false +min_connected_peers = 1 +ready_max_blocks_behind = 2 +ready_max_tip_age = "5m" + +[mempool] +eviction_memory_time = "1h" +tx_cost_limit = 80000000 + +[metrics] + +[mining] +internal_miner = false + +[network] +cache_dir = true +crawl_new_peer_interval = "1m 1s" +initial_mainnet_peers = [ + "dnsseed.z.cash:8233", + "dnsseed.str4d.xyz:8233", + "mainnet.seeder.zfnd.org:8233", +] +initial_testnet_peers = [ + "dnsseed.testnet.z.cash:18233", + "testnet.seeder.zfnd.org:18233", +] +listen_addr = "[::]:8233" +max_connections_per_ip = 1 +network = "Testnet" +peerset_initial_target_size = 25 + +[rpc] +cookie_dir = "/home/cupress/.cache/zebra" +debug_force_finished_sync = false +enable_cookie_auth = false +max_response_body_size = 52428800 +parallel_cpu_threads = 0 +listen_addr = '127.0.0.1:18231' +indexer_listen_addr = '127.0.0.1:18232' + +[state] +cache_dir = "/home/cupress/.cache/zebra" +delete_old_database = true +ephemeral = false +should_backup_non_finalized_state = true + +[sync] +checkpoint_verify_concurrency_limit = 1000 +download_concurrency_limit = 50 +full_verify_concurrency_limit = 20 +parallel_cpu_threads = 0 + +[tracing] +buffer_limit = 128000 +force_use_color = false +use_color = true +use_journald = false diff --git a/zainod/Z3.md b/zainod/Z3.md deleted file mode 100644 index 7cf5ea744..000000000 --- a/zainod/Z3.md +++ /dev/null @@ -1,43 +0,0 @@ -This is a tutorial to launch zaino, connected to a local validator. - -Step 0: Git check out zaino. - -Step 1: Set up zebra v3.1.0. -``` -git clone git@github.com:ZcashFoundation/zebra.git -git checkout v3.1.0 -cargo install --path zebrad --locked -zebrad generate > zebrad_config_3.1.0.toml -``` - - -As mentioned in -zebra-rpc/src/config/rpc.rs - > /// Note: The RPC server is disabled by default. - > /// To enable the RPC server, set a listen address in the config: - > /// ```toml - > /// [rpc] - > /// listen_addr = '127.0.0.1:8232' - > /// ``` - - -As explained in -book/src/user/startup.md - > The RPC service is optional, if it is not configured, its tasks do not run. - > - > ``` - > zebra_rpc::server: Trying to open RPC endpoint at 127.0.0.1:57638... - > zebra_rpc::server: Opened RPC endpoint at 127.0.0.1:57638 - > ``` - - -Therefore we need the following message from zebrad: -zebra_rpc::server: Opened RPC endpoint - -Use ```zebrad generate``` to generate a config file, and set it up so that zebra is launching with the custom config. Add the listen address. The default zaino listen address is 127.0.0.1:18232 -``` -zebrad -c zebrad_config_3.1.0.toml -``` - -cargo run --release -- generate-config -o ../local_programs/zainod.toml -cargo run --release --features no_tls_use_unencrypted_traffic -- start -c ../local_programs/zainod.toml From c1bbcb1def7edfce0e9ab3934d551d65f9a5f90f Mon Sep 17 00:00:00 2001 From: fluidvanadium Date: Thu, 5 Mar 2026 16:56:00 +0000 Subject: [PATCH 6/6] Remove accidentally included note file. --- wj/notes/zainodstart.txt | 82 ---------------------------------------- 1 file changed, 82 deletions(-) delete mode 100644 wj/notes/zainodstart.txt diff --git a/wj/notes/zainodstart.txt b/wj/notes/zainodstart.txt deleted file mode 100644 index c060845b9..000000000 --- a/wj/notes/zainodstart.txt +++ /dev/null @@ -1,82 +0,0 @@ -zebra off: -[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( - reqwest::Error { - kind: Request, - url: "http://127.0.0.1:18232/", - source: hyper_util::client::legacy::Error( - Connect, - ConnectError( - "tcp connect error", - 127.0.0.1:18232, - Os { - code: 111, - kind: ConnectionRefused, - message: "Connection refused", - }, - ), - ), - }, -) - -zebra 4.1 on: -listen_addr = '127.0.0.1:18232' - -[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( - reqwest::Error { - kind: Request, - url: "http://127.0.0.1:18232/", - source: hyper_util::client::legacy::Error( - SendRequest, - hyper::Error( - Parse( - Version, - ), - ), - ), - }, -) - -zebra on: -indexer_listen_addr = '127.0.0.1:18232' -[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( - reqwest::Error { - kind: Request, - url: "http://127.0.0.1:18232/", - source: hyper_util::client::legacy::Error( - SendRequest, - hyper::Error( - Parse( - Version, - ), - ), - ), - }, -) -[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( - reqwest::Error { - kind: Request, - url: "http://127.0.0.1:18232/", - source: hyper_util::client::legacy::Error( - Canceled, - hyper::Error( - Canceled, - hyper::Error( - UnexpectedMessage, - ), - ), - ), - }, -) -[zaino-fetch/src/jsonrpsee/connector.rs:919:17] e = ReqwestError( - reqwest::Error { - kind: Request, - url: "http://127.0.0.1:18232/", - source: hyper_util::client::legacy::Error( - Canceled, - hyper::Error( - Canceled, - "connection was not ready", - ), - ), - }, -)