From d22b82381e284471580a7699d6e8a0175d969bf9 Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Sun, 27 Oct 2019 02:59:31 +0300 Subject: [PATCH 1/3] Add guidelines for implementing Goerli-based phase 0 testnets --- interop/deposit_contract_testnets/README.md | 69 +++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 interop/deposit_contract_testnets/README.md diff --git a/interop/deposit_contract_testnets/README.md b/interop/deposit_contract_testnets/README.md new file mode 100644 index 0000000..4786fc9 --- /dev/null +++ b/interop/deposit_contract_testnets/README.md @@ -0,0 +1,69 @@ +# Guidelines for Eth2 testnets using a deposit contract + +This document provides a set of implementation guidelines for clients, aiming to simplify the interoperability testing in Eth2 phase 0 testnets using an Eth1 validator deposit contract. + +## Client-operated testnets + +An Eth2 testnet can be identified by an address of a deployed validator deposit contract, running on the Görli network. Multiple testnets can be running at the same time and all client teams are encouraged to deploy as many contracts as they see fit. + +To facilitate discovering and connecting to existing testnets, all client teams are encouraged to publish metadata files for their active testnets in the following repository: + +https://github.com/eth2-clients/eth2-testnets + +Please create a sub-folder for your team, where each active testnet will be stored as a nested sub-folder with a descriptive name. For example: + +``` +trinity/1000_validators_testnet/bootstrap_nodes.txt +trinity/1000_validators_testnet/deposit_contract.txt +trinity/1000_validators_testnet/config.yaml +trinity/1000_validators_testnet/genesis.ssz +``` + +`bootstrap_nodes.txt` is a line-delimited text file with [multiaddr](https://github.com/multiformats/multiaddr) records for the bootstrap nodes of the testnet. For example: + +``` +/ip4/10.20.30.40/tcp/9100/p2p/16Uiu2HAmEAmp4FdpPzypKwTMmsbCdnUafDvXZCpFrUDbYJZNk7hX +/ip4/10.20.30.50/tcp/9100/p2p/16Uiu2HAmV5SpcmrEymmaj1mymSHkbMpMVUXFRiXRxpHkfWdQ7bi3 +``` + +To connect to the testnet, the user should either pass the entire file as a command-line parameter named `bootstrap_file` or she should specify the individual entries with a repeatable command-line parameter named `bootstrap_node`. + +`deposit_contract.txt` is a single-line text file with the address of the testnet's deposit contract on the Görli network. To connect to the testnet, the user should specify the address as a command-line parameter named `deposit_contract`. + +The `genesis.ssz` represents the genesis state snapshot. The user should specify the path to this file with a command-line parameter named `state_snapshot`. + +The `config.yaml` file is optional and it specifies the [Eth2 constants parameters](https://github.com/ethereum/eth2.0-specs/tree/dev/configs) used by the testnet. When no config file is present, it should be assumed that the testnet is using the `minimal` config. Users are expected to check each client's documentation for instructions regarding the usage of config preset files. Config presets are usually specified either at build-time or at run-time depending on the client. + +Any additional information and instructions for interacting with the specific testnet can be provided in a README file in the same folder. + +### Making deposits + +To obtain the 32 GöETH required for making a deposit, please use the social faucet at https://faucet.goerli.mudit.blog/ + +It's expected that the users will use a web-site or a command-line command provided by the client to make a deposit. + +### Creating testnets + +Please note that a testnet genesis file can feature a pre-populated validator set. The monitoring of Eth1 deposit events should start from the Eth1 block referenced in the `.eth1_data.eth1_block_hash` field of the genesis state. Thus, to create a testnet, you need to deploy a new deposit contract and then generate a genesis state that references a recent Görli block hash. + +The client teams may choose any of the following options when generating a new testnet: + +* **Start with a empty validator set** + This mimics the future mainnet setup. The genesis event will be triggered when `MIN_GENESIS_ACTIVE_VALIDATOR_COUNT` deposits are made (according the used config). + +* **Start with randomly generated keys** + The randomly generated keys can be distributed to nodes operated by the client team. The testnet can start immediately and the users can use the deposit contract to become validators. + +* **Start with a mix of random and mock start keys** + The secret random keys can be used by the client team, while the mock start keys can be freely used by the users (yes, this will give us a chance to test the slashing conditions). + +To facilitate the reuse of GöETH, the client teams may choose to modify the deposit contract by adding additional features such as the ability to [drain the accumulated funds](https://github.com/prysmaticlabs/prysm/blob/master/contracts/deposit-contract/depositContract.v.py#L121). + + +## Official multi-client testnet + +After significant progress is reached in client-operated testnets, the EF will deploy an official multi-client testnet. Metadata files will be published in the following folder: + +https://github.com/eth2-clients/eth2-testnets/serenity-phase0 + + From f1faca34b712b21602437b7627192cb9ba64edff Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Wed, 6 Nov 2019 12:33:04 +0000 Subject: [PATCH 2/3] Use a more traditional unix-like convention for the CLI parameter names --- interop/deposit_contract_testnets/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/interop/deposit_contract_testnets/README.md b/interop/deposit_contract_testnets/README.md index 4786fc9..8a78842 100644 --- a/interop/deposit_contract_testnets/README.md +++ b/interop/deposit_contract_testnets/README.md @@ -26,11 +26,11 @@ trinity/1000_validators_testnet/genesis.ssz /ip4/10.20.30.50/tcp/9100/p2p/16Uiu2HAmV5SpcmrEymmaj1mymSHkbMpMVUXFRiXRxpHkfWdQ7bi3 ``` -To connect to the testnet, the user should either pass the entire file as a command-line parameter named `bootstrap_file` or she should specify the individual entries with a repeatable command-line parameter named `bootstrap_node`. +To connect to the testnet, the user should either pass the entire file as a command-line parameter named `--bootstrap-file` or she should specify the individual entries with a repeatable command-line parameter named `--bootstrap-node`. -`deposit_contract.txt` is a single-line text file with the address of the testnet's deposit contract on the Görli network. To connect to the testnet, the user should specify the address as a command-line parameter named `deposit_contract`. +`deposit_contract.txt` is a single-line text file with the address of the testnet's deposit contract on the Görli network. To connect to the testnet, the user should specify the address as a command-line parameter named `--deposit-contract`. -The `genesis.ssz` represents the genesis state snapshot. The user should specify the path to this file with a command-line parameter named `state_snapshot`. +The `genesis.ssz` represents the genesis state snapshot. The user should specify the path to this file with a command-line parameter named `--state-snapshot`. The `config.yaml` file is optional and it specifies the [Eth2 constants parameters](https://github.com/ethereum/eth2.0-specs/tree/dev/configs) used by the testnet. When no config file is present, it should be assumed that the testnet is using the `minimal` config. Users are expected to check each client's documentation for instructions regarding the usage of config preset files. Config presets are usually specified either at build-time or at run-time depending on the client. From d9a396d619c287ca4fba61dc968bf1e31f8c46bb Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Thu, 7 Nov 2019 17:58:16 +0000 Subject: [PATCH 3/3] Clarify the contents of the deposit_contract.txt file --- interop/deposit_contract_testnets/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/interop/deposit_contract_testnets/README.md b/interop/deposit_contract_testnets/README.md index 8a78842..0cb64ab 100644 --- a/interop/deposit_contract_testnets/README.md +++ b/interop/deposit_contract_testnets/README.md @@ -19,6 +19,8 @@ trinity/1000_validators_testnet/config.yaml trinity/1000_validators_testnet/genesis.ssz ``` +The `config.yaml` file is optional and it specifies the [Eth2 constants parameters](https://github.com/ethereum/eth2.0-specs/tree/dev/configs) used by the testnet. When no config file is present, it should be assumed that the testnet is using the `minimal` config. Users are expected to check each client's documentation for instructions regarding the usage of config preset files. Config presets are usually specified either at build-time or at run-time depending on the client. + `bootstrap_nodes.txt` is a line-delimited text file with [multiaddr](https://github.com/multiformats/multiaddr) records for the bootstrap nodes of the testnet. For example: ``` @@ -28,12 +30,10 @@ trinity/1000_validators_testnet/genesis.ssz To connect to the testnet, the user should either pass the entire file as a command-line parameter named `--bootstrap-file` or she should specify the individual entries with a repeatable command-line parameter named `--bootstrap-node`. -`deposit_contract.txt` is a single-line text file with the address of the testnet's deposit contract on the Görli network. To connect to the testnet, the user should specify the address as a command-line parameter named `--deposit-contract`. +`deposit_contract.txt` is a single-line text file with the address of the testnet's deposit contract on the Görli network. To connect to the testnet, the user should specify the address as a command-line parameter named `--deposit-contract`. If the used constants preset specifies a non-empty value for the `DEPOSIT_CONTRACT_ADDRESS` constant, it should be used as the default value for this parameter. The supplied address consists of 20 bytes encoded in hex form and prefixed with "0x". The `genesis.ssz` represents the genesis state snapshot. The user should specify the path to this file with a command-line parameter named `--state-snapshot`. -The `config.yaml` file is optional and it specifies the [Eth2 constants parameters](https://github.com/ethereum/eth2.0-specs/tree/dev/configs) used by the testnet. When no config file is present, it should be assumed that the testnet is using the `minimal` config. Users are expected to check each client's documentation for instructions regarding the usage of config preset files. Config presets are usually specified either at build-time or at run-time depending on the client. - Any additional information and instructions for interacting with the specific testnet can be provided in a README file in the same folder. ### Making deposits @@ -66,4 +66,3 @@ After significant progress is reached in client-operated testnets, the EF will d https://github.com/eth2-clients/eth2-testnets/serenity-phase0 -