From 52826cc2ca4171394b63c15eb87f4be347913205 Mon Sep 17 00:00:00 2001 From: Mirko von Leipzig Date: Mon, 5 Jul 2021 11:11:49 +0200 Subject: [PATCH 1/4] docs: added prerequisites section to readme --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index 4cc94c89..6a8f2c4e 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,43 @@ and [zebra](https://github.com/ZcashFoundation/zebra) devs with this reliable fo *Note:* This project is a work in progress. +## Prerequisites + +Ziggurat is written in stable Rust; you can install the Rust toolchain by following the official instructions [here](*https://www.rust-lang.org/learn/get-started). + +You also need to install at least one node implementation to test. + +### ZCashd + +`zcashd` can be installed by using the [official instructions](https://zcash.readthedocs.io/en/latest/rtd_pages/zcashd.html) for your operating system. We recommend building from source for consistency and to ensure you're using the right versions. Alternatively, you can use ECC's Debian/Ubuntu package or the binary tarball. + +However, **please note that** **Docker is not supported** as it can theoretically produce unreliable test results and increases network complexity. + +```bash +# After installing dependencies +$ git clone https://github.com/zcash/zcash +$ cd zcash +$ git checkout v4.4.1 # optional, or use master +$ ./zcutil/fetch-params.sh +$ ./zcutil/clean.sh +$ ./zcutil/build.sh -j$(nproc) # or number of cores +``` + +After completing the above, you can skip the configuration steps, i.e. creating `~/.zcashd/zcash.conf` as Ziggurat will create new configuration files for each test run. Also, syncing the blockchain is not required. + +### `zebra` + +`zebra` can be installed from its [source code](https://github.com/ZcashFoundation/zebra) on GitHub. Although a Dockerfile is provided, **Docker is not supported.** We suggest following the instructions below, or similar. + +```bash +# After installing dependencies +$ git clone https://github.com/ZcashFoundation/zebra +$ cd zebra +$ cargo +stable build +``` + +Similarly to `zcashd`, configuration is not necessary since Ziggurat generates new configurations for each test run. + ## Configuration Ziggurat is configured with a `config.toml` file in the root. From cb540b0a323db01e58448e9b60d190896a89696b Mon Sep 17 00:00:00 2001 From: Mirko von Leipzig Date: Mon, 5 Jul 2021 11:12:05 +0200 Subject: [PATCH 2/4] docs: improved node config section in readme --- README.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 6a8f2c4e..5b92e065 100644 --- a/README.md +++ b/README.md @@ -55,26 +55,35 @@ Similarly to `zcashd`, configuration is not necessary since Ziggurat generates n ## Configuration -Ziggurat is configured with a `config.toml` file in the root. +Ziggurat is configured via a `config.toml` file in the root directory. It must contain the following fields: +- `kind`: one of `zebra` or `zcashd`. +- `path`: absolute path in which to run the start command. +- `start_command`: the command used to start the node + +We recommend using the following ZCashd config: +```toml +kind = "zcashd" +path = "path/to/zcash/repo" +start_command = "./src/zcashd -debug=1 -printtoconsole -logips=1 -dnsseed=0 -dns=0 -listenonion=0" +# debug=1 enables debug logging +# logips=1 adds connection IP spans to the logs +# printtoconsole logs to stdout +# dnsseed=0 disables looking for hardcoded DNS seeding nodes (we want to isolate our node to just the test) +# dns=0 disables DNS lookup +# listenonion=0 disables the Tor network +``` +and for Zebra: ```toml kind = "zebra" path = "path/to/zebra/repo" start_command = "cargo +stable r -- --verbose start" - -# kind = "zcashd" -# path = "path/to/zcash/repo" -# start_command = "./src/zcashd -debug=1 -dnsseed=0 -printtoconsole -logips=1 -listenonion=0 -dns=0" +# cargo +stable r run Zebra using stable Rust +# -- all args after this will get passed to Zebra +# verbose enables verbose logging +# start starts the node ``` -Information about the node to be tested can be set under the `[node]` table: - -- `kind`: one of `zebra` or `zcashd` -- `path`: absolute path in which to run the start and stop commands. -- `start_command`: the command used to start the node (args inline). - -When starting the node, this information and the configuration provided in the tests will be written to a configuration file compatible with and read by the node under test. - ## Building the docs Ziggurat's documentation can be built with `cargo doc --no-deps --open`. From 13f051d0de76fcfeda1f68c75418cee39162a000 Mon Sep 17 00:00:00 2001 From: Mirko von Leipzig Date: Mon, 5 Jul 2021 11:12:15 +0200 Subject: [PATCH 3/4] docs: added logging section to readme --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 5b92e065..5b1fcde2 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,25 @@ Ziggurat's documentation can be built with `cargo doc --no-deps --open`. Ziggurat currently uses rust's standard test runner, a simple `cargo test -- --test-threads=1` should suffice. We use the single threaded executor as spinning up multiple test nodes isn't currently supported. +### Logging + +Logs are disabled by default, as they usually just add noise and slow down the test. They can be very useful for debugging and can be enabled on a test case level. + +Ziggurat's `SyntheticNode` supports `tracing` - this can be enabled by inserting a call to `synthetic_node::enable_tracing()` inside the test case. + +The test node's `stdout` and `stderr` logs can be piped to `stdout` by inserting a call to `node.log_to_stdout(true)` before starting the node. Note that logs will need to be enabled for the node as detailed in [Configuration](##Configuration). + +```Rust +let mut node = Node::new().unwrap(); +node.initial_action(Action::WaitForConnection) + .log_to_stdout(true) // pipe's the node's `stdout` and `stderr` to `stdout` + .start() + .await + .unwrap(); +``` + +Tracing can also be enabled for Ziggurat's `SyntheticNode` by inserting a call to `synthetic_node::enable_tracing()`. + ## Test Status Short overview of test cases and their current status. In case of failure, the behaviour observed for `zebra` and `zcashd` is usually documented in the test case. From 1d2e1eae2efd84d7d091d7bc12d119a8b4969a84 Mon Sep 17 00:00:00 2001 From: Mirko von Leipzig Date: Mon, 5 Jul 2021 12:33:06 +0200 Subject: [PATCH 4/4] ref: removed duplicate line --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 5b1fcde2..98bdaa18 100644 --- a/README.md +++ b/README.md @@ -109,8 +109,6 @@ node.initial_action(Action::WaitForConnection) .unwrap(); ``` -Tracing can also be enabled for Ziggurat's `SyntheticNode` by inserting a call to `synthetic_node::enable_tracing()`. - ## Test Status Short overview of test cases and their current status. In case of failure, the behaviour observed for `zebra` and `zcashd` is usually documented in the test case.