Skip to content
This repository has been archived by the owner on Nov 18, 2021. It is now read-only.

Guidelines for implementing Görli-based testnets #93

Merged
merged 3 commits into from
Nov 16, 2019
Merged

Guidelines for implementing Görli-based testnets #93

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d22b823
Add guidelines for implementing Goerli-based phase 0 testnets
zah Oct 26, 2019
f1faca3
Use a more traditional unix-like convention for the CLI parameter names
zah Nov 6, 2019
d9a396d
Clarify the contents of the deposit_contract.txt file
zah Nov 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions interop/deposit_contract_testnets/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
djrtwo marked this conversation as resolved.
Show resolved Hide resolved

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`.
djrtwo marked this conversation as resolved.
Show resolved Hide resolved

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/
djrtwo marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

even if we use a pre-populated validator set , we will also correspondingly need to send deposits with those validator's keys. Otherwise we would have differences in the deposit root in our local trie and in the contract. Also the deposit count we get from contract will be different from what we have in our current state. The monitoring of eth1 deposits should be from when the contract is deployed

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can pre-populate if we agree on a set of validator keys, like we did at interop.

Doing so it would be valuable to perhaps "reserve" a set of keys per client, so those clients can reliably do validator tests.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the initial keys are agreed upon in the sense that both clients load the same genesis state file.

The discrepancy with the data in the contract is a real problem, but our current implementation makes two compromises that seems reasonable for now:

  1. It takes into account the number of validators in the genesis state when comparing the validator counts.

  2. It monitors the contract only for deposit events. Only the locally computed root is considered valid. Since there is consensus on the latest Eth1 block, the set of deposit events in implicitly agreed upon as well.

Copy link
Contributor Author

@zah zah Nov 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea of "reserving" mock keys for the different clients. I think something like this can be described in the README file of each network. For example, we can clarify the number of used mock keys and the suggested assignments (e.g. any discovered mock key with index for which N % 10 == 6 is intended for LodeStar). Please note that it's also possible to discover the number of used mock keys and their indices just by examining the public keys of the validators appearing in the genesis state.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please note that it's also possible to discover the number of used mock keys and their indices just by examining the public keys of the validators appearing in the genesis state.

For sure! Just a quick&dirtier solution might be to reserve them... /shrug

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do like the idea of reserving keys for different clients to facilitate equal participation. However if we proceed having a mock genesis state with pre-populated validators we would need to also set a custom eth1Data for each genesis state that we create. Is there any reason we cant watch deposit events from contract deployment ?

  1. It would mirror more closely to how it would work in mainnet.
  2. We wouldnt need to implement one off logic just for the purposes of running a multi-client testnet.
  3. If we want to pre-populate with our desired validator set, that can be easily done by sending deposits with those keys included. For 64 deposits, it would take less than 2 minutes on Goerli for all of them to be mined.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was a little bit of additional reasoning behind this proposal that I didn't explicitly express.

The ability to start from a trusted genesis file that includes a list of validators and a reference to an Eth1 block is something that each client will have to implement eventually in order to handle the situation where the user has been offline for a period greater than the weak subjectivity period.

In this situation, you'll have to trust everything that you see in a supplied snapshot state. It's better to add additional sanity checks verifying that the Eth1 contract data is consistent with this trusted snapshot, but the compromise for now is to just not enforce these sanity checks.

For me, the most significant simplification from having pre-populated genesis states is not so much about the quick start-up times, but rather about reducing the required management of GoETH funds and their associated private keys.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Afaik we do have ways to reduce the amount of goETH required and also we should be able to successfully recycle them for each testnet. For the purposes of interop starting from a common genesis state maybe best, we can look at watching deposit events from contract deployment maybe later.


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