include example configs and fork timelines, with format spec

configs/constant_presets/README.md

@@ -0,0 +1,20 @@
+# Constant Presets
+
+This directory contains a set of constants presets 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 phase1 constants as a client that only supports phase 0 currently.
+
+## Format
+
+Each preset is a key-value mapping.
+
+**Key**: an `UPPER_SNAKE_CASE` (a.k.a. "macro case") formatted string, name of the constant.
+**Value**: can be any of:
+ - 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.
+
+See `mainnet.yaml` for a complete example.
+

configs/constant_presets/mainnet.yaml

@@ -0,0 +1,124 @@
+# Mainnet preset
+# Note: the intention of this file (for now) is to illustrate what a mainnet configuration could look like.
+# Some of these constants may still change before the launch of Phase 0.
+
+
+# Misc
+# ---------------------------------------------------------------
+# 2**10 ` (= 1,024)
+SHARD_COUNT: 1024
+# 2**7 ` (= 128)
+TARGET_COMMITTEE_SIZE: 128
+# 2**5 ` (= 32)
+MAX_BALANCE_CHURN_QUOTIENT: 32
+# 2**12 ` (= 4,096)
+MAX_ATTESTATION_PARTICIPANTS: 4096
+# 2**2 ` (= 4)
+MAX_EXIT_DEQUEUES_PER_EPOCH: 4
+# See issue 563
+SHUFFLE_ROUND_COUNT: 90
+
+
+# Deposit contract
+# ---------------------------------------------------------------
+# **TBD**
+DEPOSIT_CONTRACT_ADDRESS: 0x1234567890123567890123456789012357890
+# 2**5 ` (= 32)
+DEPOSIT_CONTRACT_TREE_DEPTH: 32
+
+
+# Gwei values
+# ---------------------------------------------------------------
+# 2**0 * 10**9 ` (= 1,000,000,000) Gwei
+MIN_DEPOSIT_AMOUNT: 1000000000
+# 2**5 * 10**9 ` (= 32,000,000,000) Gwei
+MAX_DEPOSIT_AMOUNT: 32000000000
+# 2**4 * 10**9 ` (= 16,000,000,000) Gwei
+EJECTION_BALANCE: 16000000000
+# 2**0 * 10**9 ` (= 1,000,000,000) Gwei
+HIGH_BALANCE_INCREMENT: 1000000000
+
+
+# Initial values
+# ---------------------------------------------------------------
+GENESIS_FORK_VERSION: 0x00000000
+# 2**32, GENESIS_EPOCH is derived from this constant
+GENESIS_SLOT: 4294967296
+GENESIS_START_SHARD: 0
+# 2**64 - 1
+FAR_FUTURE_EPOCH: 18446744073709551615
+BLS_WITHDRAWAL_PREFIX_BYTE: 0x00
+
+
+# Time parameters
+# ---------------------------------------------------------------
+# 6 seconds 6 seconds
+SECONDS_PER_SLOT: 6
+# 2**2 ` (= 4) slots 24 seconds
+MIN_ATTESTATION_INCLUSION_DELAY: 4
+# 2**6 ` (= 64) slots 6.4 minutes
+SLOTS_PER_EPOCH: 64
+# 2**0 ` (= 1) epochs 6.4 minutes
+MIN_SEED_LOOKAHEAD: 1
+# 2**2 ` (= 4) epochs 25.6 minutes
+ACTIVATION_EXIT_DELAY: 4
+# 2**4 ` (= 16) epochs ~1.7 hours
+EPOCHS_PER_ETH1_VOTING_PERIOD: 16
+# 2**13 ` (= 8,192) slots ~13 hours
+SLOTS_PER_HISTORICAL_ROOT: 8192
+# 2**8 ` (= 256) epochs ~27 hours
+MIN_VALIDATOR_WITHDRAWABILITY_DELAY: 256
+# 2**11 ` (= 2,048) epochs 9 days
+PERSISTENT_COMMITTEE_PERIOD: 2048
+# 2**6 ` (= 64)
+MAX_CROSSLINK_EPOCHS: 64
+
+
+# State list lengths
+# ---------------------------------------------------------------
+# 2**13 ` (= 8,192) epochs ~36 days
+LATEST_RANDAO_MIXES_LENGTH: 8192
+# 2**13 ` (= 8,192) epochs ~36 days
+LATEST_ACTIVE_INDEX_ROOTS_LENGTH: 8192
+# 2**13 ` (= 8,192) epochs ~36 days
+LATEST_SLASHED_EXIT_LENGTH: 8192
+
+
+# Reward and penalty quotients
+# ---------------------------------------------------------------
+# 2**5 ` (= 32)
+BASE_REWARD_QUOTIENT: 32
+# 2**9 ` (= 512)
+WHISTLEBLOWING_REWARD_QUOTIENT: 512
+# 2**3 ` (= 8)
+PROPOSER_REWARD_QUOTIENT: 8
+# 2**24 ` (= 16,777,216)
+INACTIVITY_PENALTY_QUOTIENT: 16777216
+
+
+# Max operations per block
+# ---------------------------------------------------------------
+# 2**5 ` (= 32)
+MIN_PENALTY_QUOTIENT: 32
+# 2**4 ` (= 16)
+MAX_PROPOSER_SLASHINGS: 16
+# 2**0 ` (= 1)
+MAX_ATTESTER_SLASHINGS: 1
+# 2**7 ` (= 128)
+MAX_ATTESTATIONS: 128
+# 2**4 ` (= 16)
+MAX_DEPOSITS: 16
+# 2**4 ` (= 16)
+MAX_VOLUNTARY_EXITS: 16
+# 2**4 ` (= 16)
+MAX_TRANSFERS: 16
+
+
+# Signature domains
+# ---------------------------------------------------------------
+DOMAIN_BEACON_BLOCK: 0
+DOMAIN_RANDAO: 1
+DOMAIN_ATTESTATION: 2
+DOMAIN_DEPOSIT: 3
+DOMAIN_VOLUNTARY_EXIT: 4
+DOMAIN_TRANSFER: 5

configs/constant_presets/minimal.yaml

@@ -0,0 +1,127 @@
+# Minimal preset
+
+
+# Misc
+# ---------------------------------------------------------------
+
+
+# Just 8 shards in the minimal testing setup
+SHARD_COUNT: 8
+# TODO: minimize other constants
+
+
+# 2**7 ` (= 128)
+TARGET_COMMITTEE_SIZE: 128
+# 2**5 ` (= 32)
+MAX_BALANCE_CHURN_QUOTIENT: 32
+# 2**12 ` (= 4,096)
+MAX_ATTESTATION_PARTICIPANTS: 4096
+# 2**2 ` (= 4)
+MAX_EXIT_DEQUEUES_PER_EPOCH: 4
+# See issue 563
+SHUFFLE_ROUND_COUNT: 90
+
+
+# Deposit contract
+# ---------------------------------------------------------------
+# **TBD**
+DEPOSIT_CONTRACT_ADDRESS: 0x1234567890123567890123456789012357890
+# 2**5 ` (= 32)
+DEPOSIT_CONTRACT_TREE_DEPTH: 32
+
+
+# Gwei values
+# ---------------------------------------------------------------
+# 2**0 * 10**9 ` (= 1,000,000,000) Gwei
+MIN_DEPOSIT_AMOUNT: 1000000000
+# 2**5 * 10**9 ` (= 32,000,000,000) Gwei
+MAX_DEPOSIT_AMOUNT: 32000000000
+# 2**4 * 10**9 ` (= 16,000,000,000) Gwei
+EJECTION_BALANCE: 16000000000
+# 2**0 * 10**9 ` (= 1,000,000,000) Gwei
+HIGH_BALANCE_INCREMENT: 1000000000
+
+
+# Initial values
+# ---------------------------------------------------------------
+GENESIS_FORK_VERSION: 0x00000000
+# 2**32, GENESIS_EPOCH is derived from this constant
+GENESIS_SLOT: 4294967296
+GENESIS_START_SHARD: 0
+# 2**64 - 1
+FAR_FUTURE_EPOCH: 18446744073709551615
+BLS_WITHDRAWAL_PREFIX_BYTE: 0x00
+
+
+# Time parameters
+# ---------------------------------------------------------------
+# 6 seconds 6 seconds
+SECONDS_PER_SLOT: 6
+# 2**2 ` (= 4) slots 24 seconds
+MIN_ATTESTATION_INCLUSION_DELAY: 4
+# 2**6 ` (= 64) slots 6.4 minutes
+SLOTS_PER_EPOCH: 64
+# 2**0 ` (= 1) epochs 6.4 minutes
+MIN_SEED_LOOKAHEAD: 1
+# 2**2 ` (= 4) epochs 25.6 minutes
+ACTIVATION_EXIT_DELAY: 4
+# 2**4 ` (= 16) epochs ~1.7 hours
+EPOCHS_PER_ETH1_VOTING_PERIOD: 16
+# 2**13 ` (= 8,192) slots ~13 hours
+SLOTS_PER_HISTORICAL_ROOT: 8192
+# 2**8 ` (= 256) epochs ~27 hours
+MIN_VALIDATOR_WITHDRAWABILITY_DELAY: 256
+# 2**11 ` (= 2,048) epochs 9 days
+PERSISTENT_COMMITTEE_PERIOD: 2048
+# 2**6 ` (= 64)
+MAX_CROSSLINK_EPOCHS: 64
+
+
+# State list lengths
+# ---------------------------------------------------------------
+# 2**13 ` (= 8,192) epochs ~36 days
+LATEST_RANDAO_MIXES_LENGTH: 8192
+# 2**13 ` (= 8,192) epochs ~36 days
+LATEST_ACTIVE_INDEX_ROOTS_LENGTH: 8192
+# 2**13 ` (= 8,192) epochs ~36 days
+LATEST_SLASHED_EXIT_LENGTH: 8192
+
+
+# Reward and penalty quotients
+# ---------------------------------------------------------------
+# 2**5 ` (= 32)
+BASE_REWARD_QUOTIENT: 32
+# 2**9 ` (= 512)
+WHISTLEBLOWING_REWARD_QUOTIENT: 512
+# 2**3 ` (= 8)
+PROPOSER_REWARD_QUOTIENT: 8
+# 2**24 ` (= 16,777,216)
+INACTIVITY_PENALTY_QUOTIENT: 16777216
+
+
+# Max operations per block
+# ---------------------------------------------------------------
+# 2**5 ` (= 32)
+MIN_PENALTY_QUOTIENT: 32
+# 2**4 ` (= 16)
+MAX_PROPOSER_SLASHINGS: 16
+# 2**0 ` (= 1)
+MAX_ATTESTER_SLASHINGS: 1
+# 2**7 ` (= 128)
+MAX_ATTESTATIONS: 128
+# 2**4 ` (= 16)
+MAX_DEPOSITS: 16
+# 2**4 ` (= 16)
+MAX_VOLUNTARY_EXITS: 16
+# 2**4 ` (= 16)
+MAX_TRANSFERS: 16
+
+
+# Signature domains
+# ---------------------------------------------------------------
+DOMAIN_BEACON_BLOCK: 0
+DOMAIN_RANDAO: 1
+DOMAIN_ATTESTATION: 2
+DOMAIN_DEPOSIT: 3
+DOMAIN_VOLUNTARY_EXIT: 4
+DOMAIN_TRANSFER: 5

configs/fork_timelines/README.md

@@ -0,0 +1,18 @@
+# Fork timelines
+
+This directory contains a set of fork timelines used for testing, testnets, and mainnet.
+
+A timeline file contains all the forks known for its target.
+Later forks can be ignored, e.g. ignore fork `phase1` as a client that only supports phase 0 currently.
+
+## Format
+
+Each preset is a key-value mapping.
+
+**Key**: an `lower_snake_case` (a.k.a. "python case") formatted string, name of the fork.
+**Value**: an unsigned integer number, epoch number of activation of the fork
+
+Timelines may contain comments to describe the values.
+
+See `mainnet.yaml` for a complete example.
+

configs/fork_timelines/mainnet.yaml

@@ -0,0 +1,12 @@
+# Mainnet fork timeline
+
+# Equal to GENESIS_EPOCH
+phase0: 67108864
+
+# Example 1:
+# phase0_funny_fork_name: 67116000
+
+# Example 2:
+# Should be equal to PHASE_1_GENESIS_EPOCH
+# (placeholder in example value here)
+# phase1: 67163000

specs/test_formats/README.md

@@ -107,15 +107,17 @@ test_cases: <list, values being maps defining a test case each>
 
 A configuration is a separate YAML file.
 Separation of configuration and tests aims to:
-- prevent duplication of a minimal set of tests
+- Prevent duplication of configuration
-- make all tests easy to upgrade when a new config constant is introduced.
+- Make all tests easy to upgrade (e.g. when a new config constant is introduced)
-- clearly define which constants to use
+- Clearly define which constants to use
-- share-able between clients, for cross-client short or long lived testnets
+- Shareable between clients, for cross-client short or long lived testnets
-- minimize the amounts of different constants permutations to compile as a client. \**
+- Minimize the amounts of different constants permutations to compile as a client.
- 
+  Note: Some clients prefer compile-time constants and optimizations.
-\**: Some clients prefer compile-time constants and optimizations.
   They should compile for each configuration once, and run the corresponding tests per build target.
 
+The format is described in `configs/constant_presets`.
+
+
 ## Fork-timeline
 
 A fork timeline is (preferably) loaded in as a configuration object into a client, as opposed to the constants configuration:
@@ -124,18 +126,20 @@ A fork timeline is (preferably) loaded in as a configuration object into a clien
  - we may decide on an epoch number for a fork based on external events (e.g. Eth1 log event),
     a client should be able to activate a fork dynamically.
 
+The format is described in `configs/fork_timelines`.
+
 ## Config sourcing
 
 The constants configurations are located in:
 
 ```
-<specs repo root>/configs/constants/<config name>.yaml
+<specs repo root>/configs/constant_presets/<config name>.yaml
 ```
 
 And copied by CI for testing purposes to:
 
 ```
-<tests repo root>/configs/constants/<config name>.yaml
+<tests repo root>/configs/constant_presets/<config name>.yaml
 ```