clarify config/preset separation, address review comments by @djrtwo

This commit is contained in:
protolambda 2021-05-19 17:15:34 +02:00
parent 48e1ef193a
commit 291168e1e3
No known key found for this signature in database
GPG Key ID: EC89FDBB2B4C7623
19 changed files with 65 additions and 56 deletions

View File

@ -1,20 +1,26 @@
# Presets & Configurations
# Configurations
This directory contains a set of presets and configurations used for testing, testnets, and mainnet.
This directory contains a set of configurations used for testing, testnets, and mainnet.
A client binary may be compiled for a specific `PRESET_BASE`,
and then load different configurations around that preset to participate in different networks or tests.
**Presets** are for deeper customization for different modes of operation, compile-time changes.
**Configurations** are intended for different network configurations, fully runtime-configurable.
Later-fork variables can be ignored, e.g. ignore Sharding variables as a client that only supports Phase 0 currently.
Standard configs:
- [`mainnet.yaml`](./mainnet.yaml): Mainnet configuration
- [`minimal.yaml`](./minimal.yaml): Minimal configuration, used in spec-testing along with the [`minimal`](../presets/minimal) preset.
Not all network configurations are in scope for the specification,
see [`github.com/eth2-clients/eth2-networks`](https://github.com/eth2-clients/eth2-networks) for common networks,
and additional testnet assets.
## Forking
Variables are not replaced, but extended with forks. This is to support syncing from one state to the other over a fork boundary, without hot-swapping a config.
Instead, for forks that introduce changes in a variable, the variable name is prefixed with a short abbreviation of the fork.
Instead, for forks that introduce changes in a variable, the variable name is suffixed with the fork name, e.g. `INACTIVITY_PENALTY_QUOTIENT_ALTAIR`.
Future-fork variables can be ignored, e.g. ignore Sharding variables as a client that only supports Phase 0 currently.
Over time, the need to sync an older state may be deprecated.
In this case, the prefix on the new variable may be removed, and the old variable will keep a special name before completely being removed.
In this case, the suffix on the new variable may be removed, and the old variable will keep a special name before completely being removed.
A previous iteration of forking made use of "timelines", but this collides with the definitions used in the spec (variables for special forking slots, etc.), and was not integrated sufficiently in any of the spec tools or implementations.
Instead, the config essentially doubles as fork definition now, e.g. changing the value for `ALTAIR_FORK_EPOCH` changes the fork.
@ -31,19 +37,3 @@ Each preset and configuration is a key-value mapping.
This format is fully YAML compatible.
The presets and configurations may contain comments to describe the values.
## Presets
Presets are more extensive than runtime configurations, and generally only applicable during compile-time.
Each preset is defined as a directory, with YAML files per fork.
Configurations can extend a preset by setting the `PRESET_BASE` variable.
An implementation may choose to only support 1 preset per build-target and should validate this `PRESET_BASE` variable.
See: [`mainnet_preset/`](./mainnet_preset) and [`minimal_preset/`](./minimal_preset).
## Configuration
Configurations are more minimal, singular YAML files, to define different network definitions.
Besides different (test-)network definitions, implementations also apply these during runtime for spec-tests.
See: [`mainnet_config.yaml`](./mainnet_config.yaml) and [`minimal_config.yaml`](./minimal_config.yaml).

View File

@ -18,8 +18,8 @@ GENESIS_DELAY: 604800
# Forking
# ---------------------------------------------------------------
# Some forks are disabled for now:
# - They may be re-assigned another fork-version later
# - They set a temporarily max uint64 value: 2**64 - 1
# - These may be re-assigned to another fork-version later
# - Temporarily set to max uint64 value: 2**64 - 1
# Altair
ALTAIR_FORK_VERSION: 0x01000000
@ -49,16 +49,14 @@ SHARD_COMMITTEE_PERIOD: 256
ETH1_FOLLOW_DISTANCE: 2048
# Inactivity penalties
# Validator cycle
# ---------------------------------------------------------------
# 2**2 (= 4)
INACTIVITY_SCORE_BIAS: 4
# 2**4 (= 16)
INACTIVITY_SCORE_RECOVERY_RATE: 16
# Validator Churn
# ---------------------------------------------------------------
# 2**4 * 10**9 (= 16,000,000,000) Gwei
EJECTION_BALANCE: 16000000000
# 2**2 (= 4)
MIN_PER_EPOCH_CHURN_LIMIT: 4
# 2**16 (= 65,536)

View File

@ -48,16 +48,14 @@ SHARD_COMMITTEE_PERIOD: 64
ETH1_FOLLOW_DISTANCE: 16
# Inactivity penalties
# Validator cycle
# ---------------------------------------------------------------
# 2**2 (= 4)
INACTIVITY_SCORE_BIAS: 4
# 2**4 (= 16)
INACTIVITY_SCORE_RECOVERY_RATE: 16
# Validator Churn
# ---------------------------------------------------------------
# 2**4 * 10**9 (= 16,000,000,000) Gwei
EJECTION_BALANCE: 16000000000
# 2**2 (= 4)
MIN_PER_EPOCH_CHURN_LIMIT: 4
# 2**16 (= 65,536)

26
presets/README.md Normal file
View File

@ -0,0 +1,26 @@
## Presets
Presets are more extensive than runtime configurations, and generally only applicable during compile-time.
Each preset is defined as a directory, with YAML files per fork.
Configurations can extend a preset by setting the `PRESET_BASE` variable.
An implementation may choose to only support 1 preset per build-target and should validate
the `PRESET_BASE` variable in the config matches the running build.
Standard presets:
- [`mainnet/`](./mainnet): Used in mainnet, mainnet-like testnets (e.g. Prater), and spec-testing
- [`minimal/`](./minimal): Used in low-resource local dev testnets, and spec-testing
Client implementers may opt to support additional presets, e.g. for extra large beacon states for benchmarking.
See [`/configs/`](../configs) for run-time configuration, e.g. to configure a new testnet.
## Forking
Like the [config forking](../configs/README.md#forking),
the preset extends with every fork, instead of overwriting previous values.
An implementation can ignore preset files as a whole for future forks,
and can thus implement stricter compile-time warnings on unrecognized or missing variables in current forks.
## Format
The preset format matches the [config format](../configs/README.md#format).

View File

@ -30,8 +30,6 @@ SAFE_SLOTS_TO_UPDATE_JUSTIFIED: 8
MIN_DEPOSIT_AMOUNT: 1000000000
# 2**5 * 10**9 (= 32,000,000,000) Gwei
MAX_EFFECTIVE_BALANCE: 32000000000
# 2**4 * 10**9 (= 16,000,000,000) Gwei
EJECTION_BALANCE: 16000000000
# 2**0 * 10**9 (= 1,000,000,000) Gwei
EFFECTIVE_BALANCE_INCREMENT: 1000000000

View File

@ -30,8 +30,6 @@ SAFE_SLOTS_TO_UPDATE_JUSTIFIED: 2
MIN_DEPOSIT_AMOUNT: 1000000000
# 2**5 * 10**9 (= 32,000,000,000) Gwei
MAX_EFFECTIVE_BALANCE: 32000000000
# 2**4 * 10**9 (= 16,000,000,000) Gwei
EJECTION_BALANCE: 16000000000
# 2**0 * 10**9 (= 1,000,000,000) Gwei
EFFECTIVE_BALANCE_INCREMENT: 1000000000

View File

@ -141,7 +141,7 @@ def _get_eth2_spec_comment(child: LinkRefDef) -> Optional[str]:
def _parse_value(name: str, typed_value: str) -> VariableDefinition:
comment = None
if name == "BLS12_381_Q":
comment = " # noqa: E501"
comment = "noqa: E501"
typed_value = typed_value.strip()
if '(' not in typed_value:
@ -842,8 +842,8 @@ class PySpecCommand(Command):
self.md_doc_paths = ''
self.out_dir = 'pyspec_output'
self.build_targets = """
minimal:configs/minimal_preset:configs/minimal_config.yaml
mainnet:configs/mainnet_preset:configs/mainnet_config.yaml
minimal:presets/minimal:configs/minimal.yaml
mainnet:presets/mainnet:configs/mainnet.yaml
"""
def finalize_options(self):
@ -1003,11 +1003,13 @@ setup(
url="https://github.com/ethereum/eth2.0-specs",
include_package_data=False,
package_data={'configs': ['*.yaml'],
'presets': ['*.yaml'],
'specs': ['**/*.md'],
'eth2spec': ['VERSION.txt']},
package_dir={
"eth2spec": "tests/core/pyspec/eth2spec",
"configs": "configs",
"presets": "presets",
"specs": "specs",
},
packages=find_packages(where='tests/core/pyspec') + ['configs', 'specs'],

View File

@ -22,7 +22,7 @@
- [Configuration](#configuration)
- [Genesis settings](#genesis-settings)
- [Time parameters](#time-parameters-1)
- [Validator Churn](#validator-churn)
- [Validator cycle](#validator-cycle)
- [Containers](#containers)
- [Misc dependencies](#misc-dependencies)
- [`Fork`](#fork)
@ -231,7 +231,6 @@ Additional preset configurations can be found in the [`configs`](../../configs)
| - | - |
| `MIN_DEPOSIT_AMOUNT` | `Gwei(2**0 * 10**9)` (= 1,000,000,000) |
| `MAX_EFFECTIVE_BALANCE` | `Gwei(2**5 * 10**9)` (= 32,000,000,000) |
| `EJECTION_BALANCE` | `Gwei(2**4 * 10**9)` (= 16,000,000,000) |
| `EFFECTIVE_BALANCE_INCREMENT` | `Gwei(2**0 * 10**9)` (= 1,000,000,000) |
### Time parameters
@ -305,10 +304,11 @@ Testnets and other types of chain instances may use a different configuration.
| `SHARD_COMMITTEE_PERIOD` | `uint64(2**8)` (= 256) | epochs | ~27 hours |
| `ETH1_FOLLOW_DISTANCE` | `uint64(2**11)` (= 2,048) | Eth1 blocks | ~8 hours |
### Validator Churn
### Validator cycle
| Name | Value |
| - | - |
| `EJECTION_BALANCE` | `Gwei(2**4 * 10**9)` (= 16,000,000,000) |
| `MIN_PER_EPOCH_CHURN_LIMIT` | `uint64(2**2)` (= 4) |
| `CHURN_LIMIT_QUOTIENT` | `uint64(2**16)` (= 65,536) |

View File

@ -1,8 +1,11 @@
# Eth2 config util
For configuration, see [Configs documentation](../../../../../configs/README.md).
For run-time configuration, see [Configs documentation](../../../../../configs/README.md).
## Usage:
For compile-time presets, see [Presets documentation](../../../../../presets/README.md)
and the `build-targets` flag for the `pyspec` distutils command.
## Config usage:
```python
from eth2spec.config import config_util
@ -17,4 +20,4 @@ spec.config = spec.Configuration(**config_util.load_config_file(Path('mytestnet.
Note: previously the testnet config files included both preset and runtime-configuration data.
The new config loader is compatible with this: all config vars are loaded from the file,
but those that have become presets will be ignored.
but those that have become presets can be ignored.

View File

@ -56,8 +56,8 @@ loaded_defaults = False
def load_defaults(spec_configs_path: Path) -> None:
global mainnet_config_data, minimal_config_data
mainnet_config_data = load_config_file(spec_configs_path / 'mainnet_config.yaml')
minimal_config_data = load_config_file(spec_configs_path / 'minimal_config.yaml')
mainnet_config_data = load_config_file(spec_configs_path / 'mainnet.yaml')
minimal_config_data = load_config_file(spec_configs_path / 'minimal.yaml')
global loaded_defaults
loaded_defaults = True

View File

@ -6,8 +6,4 @@ ZERO_BYTES32 = b'\x00' * 32
def hash(x: Union[bytes, bytearray, memoryview]) -> Bytes32:
try:
return Bytes32(sha256(x).digest())
except TypeError:
print(x)
raise Exception("bad")