diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 1ec8dc35d67..a7b018a2b9a 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -36,6 +36,7 @@ - [Generating Zebra Checkpoints](dev/zebra-checkpoints.md) - [Doing Mass Renames](dev/mass-renames.md) - [Updating the ECC dependencies](dev/ecc-updates.md) + - [Running a Private Testnet Test](dev/private-testnet.md) - [Zebra RFCs](dev/rfcs.md) - [Pipelinable Block Lookup](dev/rfcs/0001-pipelinable-block-lookup.md) - [Parallel Verification](dev/rfcs/0002-parallel-verification.md) diff --git a/book/src/dev/private-testnet.md b/book/src/dev/private-testnet.md new file mode 100644 index 00000000000..92386d2c47b --- /dev/null +++ b/book/src/dev/private-testnet.md @@ -0,0 +1,181 @@ +# Private Testnet Test + +The objective of a private Testnet test is to test Testnet activation of an upcoming +network upgrade in an isolated fashion, before the actual Testnet activation. +It is usually done using the current state of the existing Testnet. For NU6, it was done +by ZF and ECC engineers over a call. + +## Steps + +### Make Backup + +Make a backup of your current Testnet state. Rename/copy the `testnet` folder in +Zebra's state cache directory to the lowercase version of the configured network name, +or the default `unknowntestnet` if no network name is explicitly configured. + +### Set Protocol Version + +Double check that Zebra has bumped its protocol version. + +### Set Up Lightwalletd Server + +It's a good idea to set up a lightwalletd server connected to your node, and +have a (Testnet) wallet connected to your lightwalletd server. + +### Connect to Peers + +Make sure everyone can connect to each other. You can **use Tailscale** to do +that. Everyone needs to send invites to everyone else. Note that being able to +access someone's node does not imply that they can access yours, it needs to be +enabled both ways. + +### Choose an Activation Height + +Choose an activation height with the other participants. It should be in +the near future, but with enough time for people to set things up; something +like 30 minutes in the future? + +### Ensure the Activation Height is Set in Code + +While Zebra allows creating a private Testnet in the config file, the height is +also set in some librustzcash crates. For this reason, someone will need to +**create a branch of librustzcash** with the chosen height set and you will need +to **change Zebra to use that**. However, double check if that's still +necessary. + +### Configure Zebra to use a custom testnet + +See sample config file below. The critical part is setting the activation +height. It is good to enable verbose logging to help debug things. Some of the +participants must enable mining also. It's not a huge deal to keep the DNS +seeders; the blockchain will fork when the activation happens and only the +participants will stay connected. On the other hand, if you want to ensure you +won't connect to anyone else, set `cache_dir = false` in the `[network]` section +and delete the peers file (`~/.cache/zebra/network/unknowntestnet.peers`). + +### Run Nodes + +Everyone runs their nodes, and checks if they connect to other nodes. You can use +e.g. `curl --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": +"getpeerinfo", "params": [] }' -H 'Content-Type: application/json' +http://127.0.0.1:8232` to check that. See "Getting Peers" section below. + +### Wait Until Activation Happens + +And monitor logs for behaviour. + +### Do Tests + +Do tests, including sending transactions if possible (which will require the +lightwalletd server). Check if whatever activated in the upgrade works. + + +## Zebra + +Relevant information about Zebra for the testing process. + +### Getting peers + +It seems Zebra is not very reliable at returning its currently connected peers; +you can use `getpeerinfo` RPC as above or check the peers file +(`~/.cache/zebra/network/unknowntestnet.peers`) if `cache_dir = true` in the +`[network]` section. You might want to sort this out before the next private +testnet test. + +### Unredact IPs + +Zebra redacts IPs when logging for privacy reasons. However, for a test like +this it can be annoying. You can disable that by editing `peer_addr.rs` +with something like + + +```diff +--- a/zebra-network/src/meta_addr/peer_addr.rs ++++ b/zebra-network/src/meta_addr/peer_addr.rs +@@ -30,7 +30,7 @@ impl fmt::Display for PeerSocketAddr { + let ip_version = if self.is_ipv4() { "v4" } else { "v6" }; + + // The port is usually not sensitive, and it's useful for debugging. +- f.pad(&format!("{}redacted:{}", ip_version, self.port())) ++ f.pad(&format!("{}:{}", self.ip(), self.port())) + } + } +``` + +### Sample config file + +Note: Zebra's db path will end in "unknowntestnet" instead of "testnet" with +this configuration. + +``` +[consensus] +checkpoint_sync = true + +[mempool] +eviction_memory_time = "1h" +tx_cost_limit = 80000000 + +[metrics] + +[mining] +debug_like_zcashd = true +miner_address = "t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v" +# if you want to enable mining, which also requires selecting the `internal-miner` compilation feature +internal_miner = true + +[network] +# This will save peers to a file. Take care that it also reads peers from it; +# if you want to be truly isolated and only connect to the other participants, +# either disable this or delete the peers file before starting. +cache_dir = true +crawl_new_peer_interval = "1m 1s" + +initial_mainnet_peers = [] + +initial_testnet_peers = [ + # List the other participant's Tailscale IPs here. + # You can also keep the default DNS seeders if you wish. + "100.10.0.1:18233", +] + +listen_addr = "0.0.0.0:18233" +max_connections_per_ip = 1 +network = "Testnet" +peerset_initial_target_size = 25 + +[network.testnet_parameters] + +[network.testnet_parameters.activation_heights] +BeforeOverwinter = 1 +Overwinter = 207_500 +Sapling = 280_000 +Blossom = 584_000 +Heartwood = 903_800 +Canopy = 1_028_500 +NU5 = 1_842_420 +NU6 = 2_969_920 + +[rpc] +debug_force_finished_sync = false +parallel_cpu_threads = 0 +listen_addr = "127.0.0.1:8232" +indexer_listen_addr = "127.0.0.1:8231" + +[state] +delete_old_database = true +ephemeral = false + +[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 +# This enables debug network logging. It can be useful but it's very verbose! +filter = 'info,zebra_network=debug' +``` \ No newline at end of file