Separation of Constant, Preset and Configuration variables

.gitignore

@@ -29,3 +29,6 @@ tests/core/pyspec/test-reports
 tests/core/pyspec/eth2spec/test_results.xml
 
 *.egg-info
+
+# TOC tool outputs temporary files
+*.tmp

Makefile

@@ -96,11 +96,11 @@ install_test:
 
 test: pyspec
 	. venv/bin/activate; cd $(PY_SPEC_DIR); \
-	python3 -m pytest -n 4 --disable-bls --cov=eth2spec.phase0.spec --cov=eth2spec.altair.spec --cov-report="html:$(COV_HTML_OUT)" --cov-branch eth2spec
+	python3 -m pytest -n 4 --disable-bls --cov=eth2spec.phase0.mainnet --cov=eth2spec.altair.mainnet --cov-report="html:$(COV_HTML_OUT)" --cov-branch eth2spec
 
 find_test: pyspec
 	. venv/bin/activate; cd $(PY_SPEC_DIR); \
-	python3 -m pytest -k=$(K) --disable-bls --cov=eth2spec.phase0.spec --cov=eth2spec.altair.spec --cov-report="html:$(COV_HTML_OUT)" --cov-branch eth2spec
+	python3 -m pytest -k=$(K) --disable-bls --cov=eth2spec.phase0.mainnet --cov=eth2spec.altair.mainnet --cov-report="html:$(COV_HTML_OUT)" --cov-branch eth2spec
 
 citest: pyspec
 	mkdir -p tests/core/pyspec/test-reports/eth2spec; . venv/bin/activate; cd $(PY_SPEC_DIR); \
@@ -167,7 +167,7 @@ define run_generator
 	if ! test -d venv; then python3 -m venv venv; fi; \
 	. venv/bin/activate; \
 	pip3 install -r requirements.txt; \
-	python3 main.py -o $(CURRENT_DIR)/$(TEST_VECTOR_DIR) -c $(CURRENT_DIR)/$(CONFIGS_DIR); \
+	python3 main.py -o $(CURRENT_DIR)/$(TEST_VECTOR_DIR); \
 	echo "generator $(1) finished"
 endef
 

configs/README.md

@@ -1,34 +1,49 @@
-# Configs
+# Presets & Configurations
 
-This directory contains a set of constants presets used for testing, testnets, and mainnet.
+This directory contains a set of presets and configurations used for testing, testnets, and mainnet.
 
-A preset file contains all the constants known for its target.
-Later-fork constants can be ignored, e.g. ignore Sharding constants as a client that only supports Phase 0 currently.
+**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.
 
 
 ## Forking
 
-Configs 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 constant, the constant name is prefixed with a short abbreviation of the fork.
+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.
 
 Over time, the need to sync an older state may be deprecated.
-In this case, the prefix on the new constant may be removed, and the old constant will keep a special name before completely being removed.
+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.
 
-A previous iteration of forking made use of "timelines", but this collides with the definitions used in the spec (constants for special forking slots, etc.), and was not integrated sufficiently in any of the spec tools or implementations.
+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.
-
-Another reason to prefer forking through constants is the ability to program a forking moment based on context, instead of being limited to a static slot number.
 
 ## Format
 
-Each preset is a key-value mapping.
+Each preset and configuration is a key-value mapping.
 
-**Key**: an `UPPER_SNAKE_CASE` (a.k.a. "macro case") formatted string, name of the constant.
+**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`
 
-Presets may contain comments to describe the values.
+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/phase0.yaml`](./mainnet/phase0.yaml) for a complete example.
+See: [`mainnet_config.yaml`](./mainnet_config.yaml) and [`minimal_config.yaml`](./minimal_config.yaml).

configs/mainnet_config.yaml

@@ -0,0 +1,73 @@
+# Mainnet config
+
+# Extends the mainnet preset
+PRESET_BASE: 'mainnet'
+
+# Genesis
+# ---------------------------------------------------------------
+# `2**14` (= 16,384)
+MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 16384
+# Dec 1, 2020, 12pm UTC
+MIN_GENESIS_TIME: 1606824000
+# Mainnet initial fork version, recommend altering for testnets
+GENESIS_FORK_VERSION: 0x00000000
+# 604800 seconds (7 days)
+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
+
+# Altair
+ALTAIR_FORK_VERSION: 0x01000000
+ALTAIR_FORK_EPOCH: 18446744073709551615
+# Merge
+MERGE_FORK_VERSION: 0x02000000
+MERGE_FORK_EPOCH: 18446744073709551615
+# Sharding
+SHARDING_FORK_VERSION: 0x03000000
+SHARDING_FORK_EPOCH: 18446744073709551615
+
+# TBD, 2**32 is a placeholder. Merge transition approach is in active R&D.
+TRANSITION_TOTAL_DIFFICULTY: 4294967296
+
+
+# Time parameters
+# ---------------------------------------------------------------
+# 12 seconds
+SECONDS_PER_SLOT: 12
+# 14 (estimate from Eth1 mainnet)
+SECONDS_PER_ETH1_BLOCK: 14
+# 2**8 (= 256) epochs ~27 hours
+MIN_VALIDATOR_WITHDRAWABILITY_DELAY: 256
+# 2**8 (= 256) epochs ~27 hours
+SHARD_COMMITTEE_PERIOD: 256
+# 2**11 (= 2,048) Eth1 blocks ~8 hours
+ETH1_FOLLOW_DISTANCE: 2048
+
+
+# Inactivity penalties
+# ---------------------------------------------------------------
+# 2**2 (= 4)
+INACTIVITY_SCORE_BIAS: 4
+# 2**4 (= 16)
+INACTIVITY_SCORE_RECOVERY_RATE: 16
+
+
+# Validator Churn
+# ---------------------------------------------------------------
+# 2**2 (= 4)
+MIN_PER_EPOCH_CHURN_LIMIT: 4
+# 2**16 (= 65,536)
+CHURN_LIMIT_QUOTIENT: 65536
+
+
+# Deposit contract
+# ---------------------------------------------------------------
+# Ethereum PoW Mainnet
+DEPOSIT_CHAIN_ID: 1
+DEPOSIT_NETWORK_ID: 1
+DEPOSIT_CONTRACT_ADDRESS: 0x00000000219ab540356cBB839Cbe05303d7705Fa

configs/mainnet_preset/altair.yaml

@@ -0,0 +1,24 @@
+# Mainnet preset - Altair
+
+# Updated penalty values
+# ---------------------------------------------------------------
+# 3 * 2**24 (= 50,331,648)
+INACTIVITY_PENALTY_QUOTIENT_ALTAIR: 50331648
+# 2**6 (= 64)
+MIN_SLASHING_PENALTY_QUOTIENT_ALTAIR: 64
+# 2
+PROPORTIONAL_SLASHING_MULTIPLIER_ALTAIR: 2
+
+
+# Sync committee
+# ---------------------------------------------------------------
+# 2**9 (= 512)
+SYNC_COMMITTEE_SIZE: 512
+# 2**9 (= 512)
+EPOCHS_PER_SYNC_COMMITTEE_PERIOD: 512
+
+
+# Sync protocol
+# ---------------------------------------------------------------
+# 1
+MIN_SYNC_COMMITTEE_PARTICIPANTS: 1

configs/mainnet/custody_game.yaml → configs/mainnet_preset/custody_game.yaml

@@ -13,14 +13,6 @@ CUSTODY_PERIOD_TO_RANDAO_PADDING: 2048
 # 2**15 (= 32,768) epochs, ~146 days
 MAX_CHUNK_CHALLENGE_DELAY: 32768
 
-# Misc parameters
-# ---------------------------------------------------------------
-# 2**256 - 189
-CUSTODY_PRIME: 115792089237316195423570985008687907853269984665640564039457584007913129639747
-# 3
-CUSTODY_SECRETS: 3
-# 1/1024 chance of custody bit 1
-CUSTODY_PROBABILITY_EXPONENT: 10
 
 # Max operations
 # ---------------------------------------------------------------
@@ -35,14 +27,9 @@ MAX_CUSTODY_CHUNK_CHALLENGE_RESP: 16
 # 2**0 (= 1)
 MAX_CUSTODY_SLASHINGS: 1
 
+
 # Reward and penalty quotients
 # ---------------------------------------------------------------
 EARLY_DERIVED_SECRET_REVEAL_SLOT_REWARD_MULTIPLE: 2
 # 2**8 (= 256)
 MINOR_REWARD_QUOTIENT: 256
-
-# Signature domains
-# ---------------------------------------------------------------
-DOMAIN_CUSTODY_BIT_SLASHING: 0x83000000
-DOMAIN_LIGHT_SELECTION_PROOF: 0x84000000
-DOMAIN_LIGHT_AGGREGATE_AND_PROOF: 0x85000000

configs/mainnet_preset/merge.yaml

@@ -0,0 +1,3 @@
+# Mainnet preset - The Merge
+
+# No presets here.

configs/mainnet/phase0.yaml → configs/mainnet_preset/phase0.yaml

@@ -1,4 +1,4 @@
-# Mainnet preset
+# Mainnet preset - Phase0
 
 # Misc
 # ---------------------------------------------------------------
@@ -8,16 +8,8 @@ MAX_COMMITTEES_PER_SLOT: 64
 TARGET_COMMITTEE_SIZE: 128
 # 2**11 (= 2,048)
 MAX_VALIDATORS_PER_COMMITTEE: 2048
-# 2**2 (= 4)
-MIN_PER_EPOCH_CHURN_LIMIT: 4
-# 2**16 (= 65,536)
-CHURN_LIMIT_QUOTIENT: 65536
 # See issue 563
 SHUFFLE_ROUND_COUNT: 90
-# `2**14` (= 16,384)
-MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 16384
-# Dec 1, 2020, 12pm UTC
-MIN_GENESIS_TIME: 1606824000
 # 4
 HYSTERESIS_QUOTIENT: 4
 # 1 (minus 0.25)
@@ -32,29 +24,6 @@ HYSTERESIS_UPWARD_MULTIPLIER: 5
 SAFE_SLOTS_TO_UPDATE_JUSTIFIED: 8
 
 
-# Validator
-# ---------------------------------------------------------------
-# 2**11 (= 2,048)
-ETH1_FOLLOW_DISTANCE: 2048
-# 2**4 (= 16)
-TARGET_AGGREGATORS_PER_COMMITTEE: 16
-# 2**0 (= 1)
-RANDOM_SUBNETS_PER_VALIDATOR: 1
-# 2**8 (= 256)
-EPOCHS_PER_RANDOM_SUBNET_SUBSCRIPTION: 256
-# 14 (estimate from Eth1 mainnet)
-SECONDS_PER_ETH1_BLOCK: 14
-
-
-# Deposit contract
-# ---------------------------------------------------------------
-# Ethereum PoW Mainnet
-DEPOSIT_CHAIN_ID: 1
-DEPOSIT_NETWORK_ID: 1
-# **TBD**
-DEPOSIT_CONTRACT_ADDRESS: 0x00000000219ab540356cBB839Cbe05303d7705Fa
-
-
 # Gwei values
 # ---------------------------------------------------------------
 # 2**0 * 10**9 (= 1,000,000,000) Gwei
@@ -67,19 +36,8 @@ EJECTION_BALANCE: 16000000000
 EFFECTIVE_BALANCE_INCREMENT: 1000000000
 
 
-# Initial values
-# ---------------------------------------------------------------
-# Mainnet initial fork version, recommend altering for testnets
-GENESIS_FORK_VERSION: 0x00000000
-BLS_WITHDRAWAL_PREFIX: 0x00
-
-
 # Time parameters
 # ---------------------------------------------------------------
-# 604800 seconds (7 days)
-GENESIS_DELAY: 604800
-# 12 seconds
-SECONDS_PER_SLOT: 12
 # 2**0 (= 1) slots 12 seconds
 MIN_ATTESTATION_INCLUSION_DELAY: 1
 # 2**5 (= 32) slots 6.4 minutes
@@ -90,17 +48,13 @@ MIN_SEED_LOOKAHEAD: 1
 MAX_SEED_LOOKAHEAD: 4
 # 2**6 (= 64) epochs ~6.8 hours
 EPOCHS_PER_ETH1_VOTING_PERIOD: 64
-# 2**13 (= 8,192) slots ~13 hours
+# 2**13 (= 8,192) slots ~27 hours
 SLOTS_PER_HISTORICAL_ROOT: 8192
-# 2**8 (= 256) epochs ~27 hours
-MIN_VALIDATOR_WITHDRAWABILITY_DELAY: 256
-# 2**8 (= 256) epochs ~27 hours
-SHARD_COMMITTEE_PERIOD: 256
 # 2**2 (= 4) epochs 25.6 minutes
 MIN_EPOCHS_TO_INACTIVITY_PENALTY: 4
 
 
-# State vector lengths
+# State list lengths
 # ---------------------------------------------------------------
 # 2**16 (= 65,536) epochs ~0.8 years
 EPOCHS_PER_HISTORICAL_VECTOR: 65536
@@ -140,14 +94,3 @@ MAX_ATTESTATIONS: 128
 MAX_DEPOSITS: 16
 # 2**4 (= 16)
 MAX_VOLUNTARY_EXITS: 16
-
-
-# Signature domains
-# ---------------------------------------------------------------
-DOMAIN_BEACON_PROPOSER: 0x00000000
-DOMAIN_BEACON_ATTESTER: 0x01000000
-DOMAIN_RANDAO: 0x02000000
-DOMAIN_DEPOSIT: 0x03000000
-DOMAIN_VOLUNTARY_EXIT: 0x04000000
-DOMAIN_SELECTION_PROOF: 0x05000000
-DOMAIN_AGGREGATE_AND_PROOF: 0x06000000