Adds example configs to custom Testnet docs, moves note about inbound…

… connections on Regtest to a footnote.

book/src/user/custom-testnets.md

@@ -6,24 +6,108 @@ Zebra's Testnet can be configured with custom:
 - Network upgrade activation heights, 
 - Network names, 
 - Network magics, 
-- Slow start intervals, and
+- Slow start intervals, 
+- Genesis hashes, and
 - Target difficulty limits.
 
 It's also possible to disable Proof-of-Work validation by setting `disable_pow` to `true` so that blocks can be mined onto the chain without valid Equihash solutions, nor block hashes below their target difficulties.
 
 All of these parameters are optional, if they are all omitted or set to their default values, Zebra will run on the default public Testnet.
 
+## Usage
+
+In order to use a custom Testnet, Zebra must be configured to run on Testnet with non-default Testnet parameters. If the node is meant to mine blocks, it will need a `[mining]` section, and if it's meant to mine blocks with non-coinbase transactions, it will also need the `[rpc]` section so the `send_raw_transaction` RPC method is available.
+
+Relevant parts of the configuration file:
+
+```toml
+[mining]
+miner_address = 't27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v'
+
+[network]
+network = "Testnet"
+
+[network.testnet_parameters.activation_heights]
+network_name = "ConfiguredTestnet_1"
+network_magic = [0, 1, 0, 255]
+slow_start_interval = 0
+target_difficulty_limit = "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
+disable_pow = true
+
+# Configured activation heights must be greater than or equal to 1, and less than
+# or equal to Zebra's max block height of 2^31 - 1, block height 0 is reserved
+# for the Genesis network upgrade in Zebra.
+#
+# Network upgrades must be activated in the order that they were added to Zcash,
+# configuring the activation heights of recent network upgrades will activate
+# any omitted prior network upgrades at the same height. 
+#
+# For example, configuring the activation height of NU5 to block height 1 without
+# configuring any other network upgrade activation heights will set the
+# activation heights of BeforeOverwinter, Overwinter, Sapling, Blossom, 
+# Heartwood, and Canopy at block height 1 as well.
+[network.testnet_parameters.activation_heights]
+NU5 = 1
+
+# This section may be omitted if it's not necessary to 
+# add transactions to Zebra's mempool
+[rpc]
+listen_addr = "0.0.0.0:18232"
+```
+
+
+Relevant parts of the configuration file with Mainnet parameters:
+
+```toml
+[mining]
+miner_address = 't27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v'
+
+[network]
+network = "Testnet"
+
+[network.testnet_parameters.activation_heights]
+# The Mainnet, Testnet, and Regtest network names are reserved.
+network_name = "ConfiguredTestnet_2"
+
+# The Mainnet and Regtest network magics are reserved.
+network_magic = [0, 1, 0, 255]
+
+slow_start_interval = 20_000
+genesis_hash = "00040fe8ec8471911baa1db1266ea15dd06b4a8a5c453883c000b031973dce08"
+
+# Note that setting `disable_pow` to `false` with this target difficultly 
+# limit will make it very difficult to mine valid blocks onto the chain.
+target_difficulty_limit = "0008000000000000000000000000000000000000000000000000000000000000"
+disable_pow = false
+
+[network.testnet_parameters.activation_heights]
+BeforeOverwinter = 1
+Overwinter = 347_500
+Sapling = 419_200
+Blossom = 653_600
+Heartwood = 903_000
+Canopy = 1_046_400
+NU5 = 1_687_104
+
+# This section may be omitted if it's not necessary to 
+# add transactions to Zebra's mempool
+[rpc]
+listen_addr = "0.0.0.0:18232"
+```
+
+
 ## Caveats and Restrictions
 
 There are a few caveats:
 - Configured network upgrade activation heights must be above the genesis block height, which is reserved for Zebra's `Genesis` network upgrade, and must not be above Zebra's max block height of `2^31 -1`.
 - While it's possible to activate Canopy and later network upgrades after height 1, Zebra cannot currently produce pre-Canopy block templates, so the `getblocktemplate` RPC method and Zebra's internal miner which depends on the `getblocktemplate` method won't work until Canopy is activated. An alternative block source will be required to mine pre-Canopy blocks onto Zebra's chain.
 - While it's possible to use the default Testnet network magic with a configured Testnet, Zebra will panic when configured to use the default initial Testnet peers and Testnet parameters that are incompatible with the default public Testnet.
+- If the genesis hash is configured, a genesis block will need to be copied into the custom Testnet state or submitted via the `submitblock` RPC method, Zebra cannot currently generate genesis blocks. See the `CreateGenesisBlock()` function in `zcashd/src/chainparams.cpp` for use cases that require a new genesis block.
 
 There are also a few other restrictions on these parameters:
 - The network name must:
     - not be any of the reserved network names: `Testnet`, `Mainnet`, and `Regtest`,
-    - contain only alphanumeric characters, and
+    - contain only alphanumeric characters and underscores, and
     - be shorter than the `MAX_NETWORK_NAME_LENGTH` of `30`.
 - The network magic must not be any of the reserve network magics: `[36, 233, 39, 100]` and `[170, 232, 63, 95]`, these are the `Mainnet` and `Regtest` network magics respectively.
 - The network upgrade activation heights must be in order, such that the activation height for every network upgrade is at or above the activation height of every preceding network upgrade.
@@ -58,9 +142,10 @@ The remaining consensus differences between Mainnet and Testnet could be made co
 ## Differences Between Custom Testnets and Regtest
 
 Zebra's Regtest network is a special case of a custom Testnet that:
-- Won't make outbound peer connections and rejects inbound peer connections with a different network magic,
+- Won't make peer connections[^fn1],
 - Skips Proof-of-Work validation,
 - Uses a reserved network magic and network name,
+- Activates network upgrades up to and including Canopy at block height 1,
 - Tries to closely match the `zcashd` Regtest parameters, and
 - Expects the Regtest genesis hash.
 
@@ -75,3 +160,7 @@ Aside from the network name, configuring any Testnet parameters in Zebra will re
 In the absence of a configurable Zcash DNS seeder, Zebra nodes on custom Testnets will need to know the exact hostname or IP address of other Zebra nodes on the same custom Testnet to make peer connections. 
 
 Zebra nodes on custom Testnets will also reject peer connections with nodes that are using a different network magic or network protocol version, but may still make peer connections with other Zcash nodes which have incompatible network parameters. Zebra nodes should eventually drop those peer connections when it reaches its peerset connection limit and has more available peer candidates if they are consistently sending the node invalid blocks.
+
+##### Footnotes
+
+[^fn1]: Zebra won't make outbound peer connections on Regtest, but currently still listens for inbound peer connections, which will be rejected unless they use the Regtest network magic, and Zcash nodes using the Regtest network magic should not be making outbound peer connections. It may be updated to skip initialization of the peerset service altogether so that it won't listen for peer connections at all when support for isolated custom Testnets is added.

book/src/user/regtest.md

@@ -1,9 +1,11 @@
 # Regtest with Zebra
 
-The Regtest network in Zebra enables testing of custom functionalities in a private testnet environment with configurable network upgrade activation heights. It allows for starting an isolated node which won't connect to any peers and currently allows for committing blocks without validating their Proof of Work (in the future, it may use a very low target difficulty and easier Equihash parameters instead of skipping Proof of Work validation altogether).
+The Regtest network in Zebra enables testing of custom functionalities in a private Testnet environment with configurable network upgrade activation heights. It allows for starting an isolated node which won't connect to any peers and currently allows for committing blocks without validating their Proof of Work (in the future, it may use a very low target difficulty and easier Equihash parameters instead of skipping Proof of Work validation altogether).
 
 Zebra always activates the Canopy network upgrade at block height 1 due to limitations on its block construction.
 
+## Usage
+
 In order to use Regtest, Zebra must be configured to run on the Regtest network. The `[mining]` section is also necessary for mining blocks, and the `[rpc]` section is necessary for using the `send_raw_transaction` RPC method to mine non-coinbase transactions onto the chain.
 
 Relevant parts of the configuration file:
@@ -40,7 +42,7 @@ There are two ways to commit blocks to Zebra's state on Regtest:
 - Using the `getblocktemplate` and `submitblock` RPC methods directly
 - Using Zebra's experimental `internal-miner` feature
 
-## Using Zebra's Internal Miner
+### Using Zebra's Internal Miner
 
 Zebra can mine blocks on the Regtest network when compiled with the experimental `internal-miner` compilation feature and configured to enable to internal miner.
 
@@ -55,7 +57,7 @@ Zebra should now mine blocks on Regtest when it starts after a short delay (of a
 
 To confirm that it's working, look for `successfully mined a new block` messages in the logs, or that the tip height is increasing.
 
-## Using RPC methods directly
+### Using RPC methods directly
 
 Blocks could also be mined outside of Zebra and submitted via Zebra's RPC methods. This requires enabling the RPC server in the configuration by providing a `listen_addr` field:
 

zebrad/tests/common/configs/v1.8.0.toml

@@ -62,6 +62,7 @@ network_magic = [0, 0, 0, 0]
 slow_start_interval = 0
 target_difficulty_limit = "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
 disable_pow = true
+genesis_hash = "00040fe8ec8471911baa1db1266ea15dd06b4a8a5c453883c000b031973dce08"
 
 [network.testnet_parameters.activation_heights]
 BeforeOverwinter = 1