[#985] Create a ZIP Draft to document Regtest mode #986
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
pacu
force-pushed
the
regtest-zip-draft
branch
from
8a33bbb to
e4b17fc
Compare
nuttycom
reviewed
Feb 27, 2025
There was a problem hiding this comment.
nit: it's difficult to read this on a wide monitor, please hard-wrap lines.
nuttycom
reviewed
Feb 27, 2025
There was a problem hiding this comment.
Partial review; I have not yet reviewed beyond the section Behavior for ZIP-200 Network Upgrade Mechanism.
In general, specification language needs to be somewhat more precise than most of what is presented in this draft. In particular, the affected components and actors should be clearly identified in each portion of the specification, and particular care should be taken with respect to any conditionals. Focus on what has to happen more than the actor in each section.
| The terms "Mainnet" and "Testnet" in this document are to be interpreted as defined in the Zcash protocol specification [^protocol-networks]. | ||
|
|
||
| ## Abstract | ||
| At minimum, Regtest is a testing mode inherited from the Bitcoin node. It is a way to have a consensus node on a local network with a private state that a developer can drive at its will to reproduce certain situations deterministically and see how the code reacts to them. Regtest, as it was implemented on Zcashd, is similar to a “testnet” but without miners and remote peers. |
There was a problem hiding this comment.
Suggested change
| At minimum, Regtest is a testing mode inherited from the Bitcoin node. It is a way to have a consensus node on a local network with a private state that a developer can drive at its will to reproduce certain situations deterministically and see how the code reacts to them. Regtest, as it was implemented on Zcashd, is similar to a “testnet” but without miners and remote peers. | |
| Regtest is a testing mode inherited from the Bitcoin node. It provides a way to have a consensus node on a local network with a private state that a developer can control in order to reproduce certain situations deterministically for testing purposes. Regtest, as it was implemented on Zcashd, is similar to a “testnet” but without miners and remote peers. |
| At minimum, Regtest is a testing mode inherited from the Bitcoin node. It is a way to have a consensus node on a local network with a private state that a developer can drive at its will to reproduce certain situations deterministically and see how the code reacts to them. Regtest, as it was implemented on Zcashd, is similar to a “testnet” but without miners and remote peers. | ||
|
|
||
| ## Motivation | ||
| It is necessary to define Regtest mode so that different implementations of Zcash Full Nodes provide the same capabilities so that testing infrastructure can be interoperable. Regtest mode was inherited from Bitcoin functionality and never defined in a ZIP due to resource constraints and priorities. Differences between Zebra and Zcashd Regtest implementations found by developers involved in Zcashd deprecation motivated this ZIP as a way to document existing assumptions, expectations and functionalites of Regtest as well as new features that focus specifically on Zcash features. |
There was a problem hiding this comment.
Suggested change
| It is necessary to define Regtest mode so that different implementations of Zcash Full Nodes provide the same capabilities so that testing infrastructure can be interoperable. Regtest mode was inherited from Bitcoin functionality and never defined in a ZIP due to resource constraints and priorities. Differences between Zebra and Zcashd Regtest implementations found by developers involved in Zcashd deprecation motivated this ZIP as a way to document existing assumptions, expectations and functionalites of Regtest as well as new features that focus specifically on Zcash features. | |
| It is necessary to define Regtest mode so that different implementations of Zcash Full Nodes provide the same capabilities so that testing infrastructure can be interoperable. Regtest mode was inherited from Bitcoin functionality and never defined in a ZIP due to resource constraints and priorities. Differences between Zebra and Zcashd Regtest implementations found by developers involved in Zcashd deprecation motivated this ZIP as a way to document existing assumptions, expectations and functionalites of Regtest, and to document regtest-only features. |
|
|
||
|
|
||
| ## Requirements | ||
| The scope of this ZIP is to define the behavior of a Zcash full-node when set up to run in Regtest mode. It focuses on highlighting and specifying the difference in behavior, values, expectations and assumpions in comparison to Testnet. It uses the Zcash protocol and existing ZIPs as guiding principles for the document structure. It also documents pre-existing and previously *undocumented* requirements, constants and values that are present in the Zcashd 6.1.0 implementation and `zcash_protocol` crate 0.4.3[^zcash_protocol]. This ZIP should be useful for Core Developers working on full node implementations but also a handbook for developers and QA testers to make use and take advantage of Regtest functionality to ensure test coverage of their codebases and a high quality assurance to Zcash users. |
There was a problem hiding this comment.
This isn't really the correct sort of content for a requirements section: instead of requirements for this zip, which is abstract or motivation content, this section should describe the requirements that regtest mode should satisfy.
| TODO: Gather existing Zcashd and compare them to Zebra parameters. | ||
|
|
||
| ### Regtest nodes and Network connections | ||
| Nodes that start on Regtest mode should never connect to any external peers. Localhost connections MUST be enforced. Attempts to configure a Regtest setup in a way that violate this principle should cause a `FatalError` informing the developer of the problem an pointing to the relevant documentation. |
There was a problem hiding this comment.
Suggested change
| Nodes that start on Regtest mode should never connect to any external peers. Localhost connections MUST be enforced. Attempts to configure a Regtest setup in a way that violate this principle should cause a `FatalError` informing the developer of the problem an pointing to the relevant documentation. | |
| Nodes that start in Regtest mode MUST NOT connect to external peers. Localhost connections MUST be enforced. Attempts to configure a node in a way that violate this principle MUST cause the node to halt with an error informing the developer of the problem and pointing to the relevant documentation. |
FatalError is not well-defined here.
| Nodes that start on Regtest mode should never connect to any external peers. Localhost connections MUST be enforced. Attempts to configure a Regtest setup in a way that violate this principle should cause a `FatalError` informing the developer of the problem an pointing to the relevant documentation. | ||
|
|
||
| ### Global Effects on Network Upgrades | ||
| Regtest mode must allow Network Upgrades to occur at configurable arbitrary block heights in a way that all one of more of them can be activated at once at a given height. Effects from network upgrades activating MUST be guaranteed to occur in the intended order as it is defined on its **Testnet** or **Mainnet** implementation. This means that there is a hard requirement that guarantees a chronological order of NU's event so that it is not possible to enable a NU prior to one of its predecessors. Example: a configuration such as `NU1 -> NU3 -> NU2` should raise a critical error and fail the execution of the Regtest environment. The rationale of this is to avoid unfeasible chain states. |
There was a problem hiding this comment.
Suggested change
| Regtest mode must allow Network Upgrades to occur at configurable arbitrary block heights in a way that all one of more of them can be activated at once at a given height. Effects from network upgrades activating MUST be guaranteed to occur in the intended order as it is defined on its **Testnet** or **Mainnet** implementation. This means that there is a hard requirement that guarantees a chronological order of NU's event so that it is not possible to enable a NU prior to one of its predecessors. Example: a configuration such as `NU1 -> NU3 -> NU2` should raise a critical error and fail the execution of the Regtest environment. The rationale of this is to avoid unfeasible chain states. | |
| Regtest mode must allow Network Upgrades to occur at configurable arbitrary block heights in a way that all one of more of them can be activated at once at a given height. Effects that result from network upgrades activating MUST be guaranteed to occur in the order defined for the **Testnet** or **Mainnet** activation of those upgrades. It MUST NOT not be possible to enable a NU prior to one of its predecessors, and attempts to configure a node such that, for example, `NU1 -> NU3 -> NU2` should cause the node to raise a error and halt. |
| (TODO: check with Daira-Emma if this is really necessary or whether the ability to do such a mess with activation heights is actually a testing feature and not a bug.) | ||
|
|
||
| ## Effects of Regtest mode by ZIP | ||
|
|
There was a problem hiding this comment.
Some introduction for the table below should be provided here.
| ### Behevior for ZIP-155 | ||
| Peer-to-peer communications on Regtest MUST be restricted to localhost nodes. See "Regtest nodes and Network connections" | ||
|
|
||
| ### Behaviour for ZIP-200 Network Upgrade Mechanism |
There was a problem hiding this comment.
Suggested change
| ### Behaviour for ZIP-200 Network Upgrade Mechanism | |
| ### Behavior for ZIP-200 Network Upgrade Mechanism |
(or else change the occurrences of Behavior to Behaviour)
| Peer-to-peer communications on Regtest MUST be restricted to localhost nodes. See "Regtest nodes and Network connections" | ||
|
|
||
| ### Behaviour for ZIP-200 Network Upgrade Mechanism | ||
| Regtest nodes should implement a way to configure parameters such as Network Upgrade activation heights and their respective consensus branch IDs. For convenience these should be defined on this ZIP and to be used in all libraries that enable Regtest testing. Configuration should favor that such values can be altered and/or added if necessary, for example to develop a new Network Upgrade. Regtest client libraries SHOULD accommodate to such flexibility. |
There was a problem hiding this comment.
Suggested change
| Regtest nodes should implement a way to configure parameters such as Network Upgrade activation heights and their respective consensus branch IDs. For convenience these should be defined on this ZIP and to be used in all libraries that enable Regtest testing. Configuration should favor that such values can be altered and/or added if necessary, for example to develop a new Network Upgrade. Regtest client libraries SHOULD accommodate to such flexibility. | |
| It must be possible to configure a regtest node with a mapping between Network Upgrade activation heights and consensus branch IDs. It must be possible for such configuration to enable the development of functionality for not-yet-released Network Upgrades, in order to enable testing of new protocol features in advance of mainnet or testnet activation. Client libraries SHOULD also accommodate such flexibility. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
closes #985