release 1.1.0-alpha.6

configs/README.md

@@ -0,0 +1,39 @@
+# Configurations
+
+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.
+
+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 another over a fork boundary, without hot-swapping a config.
+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 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.
+
+## Format
+
+Each preset and configuration is a key-value mapping.
+
+**Key**: an `UPPER_SNAKE_CASE` (a.k.a. "macro case") formatted string, name of the variable.
+
+**Value** can be either:
+ - an unsigned integer number, can be up to 64 bits (incl.)
+ - a hexadecimal string, prefixed with `0x`
+
+This format is fully YAML compatible.
+The presets and configurations may contain comments to describe the values.

presets/README.md

@@ -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).