diff --git a/Makefile b/Makefile index 88f17dcf9..d082dc1b9 100644 --- a/Makefile +++ b/Makefile @@ -16,11 +16,11 @@ clean: # runs a limited set of tests against a minimal config # run pytest with `-m` option to full suite -test: +test: all pytest -m minimal_config tests/ -$(BUILD_DIR)/phase0: +$(BUILD_DIR)/phase0: $(SPEC_DIR)/core/0_beacon-chain.md $(SCRIPT_DIR)/phase0/*.py $(UTILS_DIR)/phase0/*.py mkdir -p $@ python3 $(SCRIPT_DIR)/phase0/build_spec.py $(SPEC_DIR)/core/0_beacon-chain.md $@/spec.py mkdir -p $@/utils diff --git a/README.md b/README.md index d06e846d4..8ce119f13 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Core specifications for eth2.0 client validation can be found in [specs/core](sp Accompanying documents can be found in [specs](specs) and include * [SimpleSerialize (SSZ) spec](specs/simple-serialize.md) * [BLS signature verification](specs/bls_signature.md) -* [General test format](specs/test-format.md) +* [General test format](specs/test_formats/README.md) * [Honest validator implementation doc](specs/validator/0_beacon-chain-validator.md) * [Merkle proof formats](specs/light_client/merkle_proofs.md) * [Light client syncing protocol](specs/light_client/sync_protocol.md) diff --git a/configs/constant_presets/README.md b/configs/constant_presets/README.md new file mode 100644 index 000000000..45148862e --- /dev/null +++ b/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. + diff --git a/configs/constant_presets/mainnet.yaml b/configs/constant_presets/mainnet.yaml new file mode 100644 index 000000000..6eef9ad81 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/configs/constant_presets/minimal.yaml b/configs/constant_presets/minimal.yaml new file mode 100644 index 000000000..e4c869ded --- /dev/null +++ b/configs/constant_presets/minimal.yaml @@ -0,0 +1,124 @@ +# Minimal preset + + +# Misc +# --------------------------------------------------------------- + +# [customized] Just 8 shards for testing purposes +SHARD_COUNT: 8 + +# [customized] unsecure, but fast +TARGET_COMMITTEE_SIZE: 4 +# 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 +# [customized] 2 slots +MIN_ATTESTATION_INCLUSION_DELAY: 2 +# [customized] fast epochs +SLOTS_PER_EPOCH: 8 +# 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 +# [customized] smaller state +SLOTS_PER_HISTORICAL_ROOT: 64 +# 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 +# --------------------------------------------------------------- +# [customized] smaller state +LATEST_RANDAO_MIXES_LENGTH: 64 +# [customized] smaller state +LATEST_ACTIVE_INDEX_ROOTS_LENGTH: 64 +# [customized] smaller state +LATEST_SLASHED_EXIT_LENGTH: 64 + + +# 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 \ No newline at end of file diff --git a/configs/fork_timelines/README.md b/configs/fork_timelines/README.md new file mode 100644 index 000000000..c93b415f5 --- /dev/null +++ b/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. + diff --git a/configs/fork_timelines/mainnet.yaml b/configs/fork_timelines/mainnet.yaml new file mode 100644 index 000000000..8d51d6582 --- /dev/null +++ b/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 diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index 8a7b24cec..bdce2e348 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -51,7 +51,7 @@ - [`xor`](#xor) - [`hash`](#hash) - [`hash_tree_root`](#hash_tree_root) - - [`signed_root`](#signed_root) + - [`signing_root`](#signing_root) - [`get_temporary_block_header`](#get_temporary_block_header) - [`slot_to_epoch`](#slot_to_epoch) - [`get_previous_epoch`](#get_previous_epoch) @@ -67,8 +67,8 @@ - [`get_permuted_index`](#get_permuted_index) - [`get_split_offset`](#get_split_offset) - [`get_epoch_committee_count`](#get_epoch_committee_count) + - [`get_shard_delta`](#get_shard_delta) - [`compute_committee`](#compute_committee) - - [`get_current_epoch_committee_count`](#get_current_epoch_committee_count) - [`get_crosslink_committees_at_slot`](#get_crosslink_committees_at_slot) - [`get_block_root`](#get_block_root) - [`get_state_root`](#get_state_root) @@ -96,7 +96,6 @@ - [`bls_verify`](#bls_verify) - [`bls_verify_multiple`](#bls_verify_multiple) - [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys) - - [`process_deposit`](#process_deposit) - [Routines for updating validator status](#routines-for-updating-validator-status) - [`activate_validator`](#activate_validator) - [`initiate_validator_exit`](#initiate_validator_exit) @@ -138,10 +137,6 @@ - [Voluntary exits](#voluntary-exits) - [Transfers](#transfers) - [State root verification](#state-root-verification) -- [References](#references) - - [Normative](#normative) - - [Informative](#informative) -- [Copyright](#copyright) @@ -170,12 +165,16 @@ Code snippets appearing in `this style` are to be interpreted as Python code. * **Crosslink** - a set of signatures from a committee attesting to a block in a shard chain that can be included into the beacon chain. Crosslinks are the main means by which the beacon chain "learns about" the updated state of shard chains. * **Slot** - a period during which one proposer has the ability to create a beacon chain block and some attesters have the ability to make attestations. * **Epoch** - an aligned span of slots during which all [validators](#dfn-validator) get exactly one chance to make an attestation. -* **Finalized**, **justified** - see Casper FFG finalization [[casper-ffg]](#ref-casper-ffg). +* **Finalized**, **justified** - see the [Casper FFG paper](https://arxiv.org/abs/1710.09437). * **Withdrawal period** - the number of slots between a [validator](#dfn-validator) exit and the [validator](#dfn-validator) balance being withdrawable. * **Genesis time** - the Unix time of the genesis beacon chain block at slot 0. ## Constants +Note: the default mainnet values for the constants are included here for spec-design purposes. +The different configurations for mainnet, testnets, and yaml-based testing can be found in the `configs/constant_presets/` directory. +These configurations are updated for releases, but may be out of sync during `dev` changes. + ### Misc | Name | Value | @@ -233,7 +232,7 @@ Code snippets appearing in `this style` are to be interpreted as Python code. | `SLOTS_PER_HISTORICAL_ROOT` | `2**13` (= 8,192) | slots | ~13 hours | | `MIN_VALIDATOR_WITHDRAWABILITY_DELAY` | `2**8` (= 256) | epochs | ~27 hours | | `PERSISTENT_COMMITTEE_PERIOD` | `2**11` (= 2,048) | epochs | 9 days | -| `MAX_CROSSLINK_EPOCHS` | `2**6` (= 64) | +| `MAX_CROSSLINK_EPOCHS` | `2**6` (= 64) | epochs | ~7 hours | * `MAX_CROSSLINK_EPOCHS` should be a small constant times `SHARD_COUNT // SLOTS_PER_EPOCH` @@ -283,7 +282,7 @@ Code snippets appearing in `this style` are to be interpreted as Python code. ## Data structures -The following data structures are defined as [SimpleSerialize (SSZ)](https://github.com/ethereum/eth2.0-specs/blob/master/specs/simple-serialize.md) objects. +The following data structures are defined as [SimpleSerialize (SSZ)](../simple-serialize.md) objects. The types are defined topologically to aid in facilitating an executable version of the spec. @@ -659,11 +658,11 @@ Note: We aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethere ### `hash_tree_root` -`def hash_tree_root(object: SSZSerializable) -> Bytes32` is a function for hashing objects into a single root utilizing a hash tree structure. `hash_tree_root` is defined in the [SimpleSerialize spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/simple-serialize.md#tree-hash). +`def hash_tree_root(object: SSZSerializable) -> Bytes32` is a function for hashing objects into a single root utilizing a hash tree structure. `hash_tree_root` is defined in the [SimpleSerialize spec](../simple-serialize.md#merkleization). -### `signed_root` +### `signing_root` -`def signed_root(object: SSZContainer) -> Bytes32` is a function defined in the [SimpleSerialize spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/simple-serialize.md#signed-roots) to compute signed messages. +`def signing_root(object: SSZContainer) -> Bytes32` is a function defined in the [SimpleSerialize spec](../simple-serialize.md#self-signed-containers) to compute signing messages. ### `get_temporary_block_header` @@ -677,7 +676,7 @@ def get_temporary_block_header(block: BeaconBlock) -> BeaconBlockHeader: previous_block_root=block.previous_block_root, state_root=ZERO_HASH, block_body_root=hash_tree_root(block.body), - # signed_root(block) is used for block id purposes so signature is a stub + # signing_root(block) is used for block id purposes so signature is a stub signature=EMPTY_SIGNATURE, ) ``` @@ -840,19 +839,27 @@ def get_split_offset(list_size: int, chunks: int, index: int) -> int: ### `get_epoch_committee_count` ```python -def get_epoch_committee_count(active_validator_count: int) -> int: +def get_epoch_committee_count(state: BeaconState, epoch: Epoch) -> int: """ Return the number of committees in one epoch. """ + active_validators = get_active_validator_indices(state.validator_registry, epoch) return max( 1, min( SHARD_COUNT // SLOTS_PER_EPOCH, - active_validator_count // SLOTS_PER_EPOCH // TARGET_COMMITTEE_SIZE, + len(active_validators) // SLOTS_PER_EPOCH // TARGET_COMMITTEE_SIZE, ) ) * SLOTS_PER_EPOCH ``` +### `get_shard_delta` + +```python +def get_shard_delta(state: BeaconState, epoch: Epoch) -> int: + return min(get_epoch_committee_count(state, epoch), SHARD_COUNT - SHARD_COUNT // SLOTS_PER_EPOCH) +``` + ### `compute_committee` ```python @@ -874,20 +881,6 @@ def compute_committee(validator_indices: List[ValidatorIndex], **Note**: this definition and the next few definitions are highly inefficient as algorithms, as they re-calculate many sub-expressions. Production implementations are expected to appropriately use caching/memoization to avoid redoing work. -### `get_current_epoch_committee_count` - -```python -def get_current_epoch_committee_count(state: BeaconState) -> int: - """ - Return the number of committees in the current epoch of the given ``state``. - """ - current_active_validators = get_active_validator_indices( - state.validator_registry, - get_current_epoch(state), - ) - return get_epoch_committee_count(len(current_active_validators)) -``` - ### `get_crosslink_committees_at_slot` ```python @@ -906,16 +899,17 @@ def get_crosslink_committees_at_slot(state: BeaconState, state.validator_registry, epoch, ) - committees_per_epoch = get_epoch_committee_count(len(indices)) if epoch == current_epoch: start_shard = state.latest_start_shard elif epoch == previous_epoch: - start_shard = (state.latest_start_shard - committees_per_epoch) % SHARD_COUNT + previous_shard_delta = get_shard_delta(state, previous_epoch) + start_shard = (state.latest_start_shard - previous_shard_delta) % SHARD_COUNT elif epoch == next_epoch: - current_epoch_committees = get_current_epoch_committee_count(state) - start_shard = (state.latest_start_shard + current_epoch_committees) % SHARD_COUNT + current_shard_delta = get_shard_delta(state, current_epoch) + start_shard = (state.latest_start_shard + current_shard_delta) % SHARD_COUNT + committees_per_epoch = get_epoch_committee_count(state, epoch) committees_per_slot = committees_per_epoch // SLOTS_PER_EPOCH offset = slot % SLOTS_PER_EPOCH slot_start_shard = (start_shard + committees_per_slot * offset) % SHARD_COUNT @@ -1196,7 +1190,7 @@ def verify_indexed_attestation(state: BeaconState, indexed_attestation: IndexedA if len(custody_bit_1_indices) > 0: # [TO BE REMOVED IN PHASE 1] return False - total_attesting_indices = len(custody_bit_0_indices + custody_bit_1_indices) + total_attesting_indices = len(custody_bit_0_indices) + len(custody_bit_1_indices) if not (1 <= total_attesting_indices <= MAX_ATTESTATION_PARTICIPANTS): return False @@ -1277,85 +1271,15 @@ def get_delayed_activation_exit_epoch(epoch: Epoch) -> Epoch: ### `bls_verify` -`bls_verify` is a function for verifying a BLS signature, defined in the [BLS Signature spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/bls_signature.md#bls_verify). +`bls_verify` is a function for verifying a BLS signature, defined in the [BLS Signature spec](../bls_signature.md#bls_verify). ### `bls_verify_multiple` -`bls_verify_multiple` is a function for verifying a BLS signature constructed from multiple messages, defined in the [BLS Signature spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/bls_signature.md#bls_verify_multiple). +`bls_verify_multiple` is a function for verifying a BLS signature constructed from multiple messages, defined in the [BLS Signature spec](../bls_signature.md#bls_verify_multiple). ### `bls_aggregate_pubkeys` -`bls_aggregate_pubkeys` is a function for aggregating multiple BLS public keys into a single aggregate key, defined in the [BLS Signature spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/bls_signature.md#bls_aggregate_pubkeys). - -### `process_deposit` - -Used to add a [validator](#dfn-validator) or top up an existing [validator](#dfn-validator)'s balance by some `deposit` amount: - -```python -def process_deposit(state: BeaconState, deposit: Deposit) -> None: - """ - Process a deposit from Ethereum 1.0. - Note that this function mutates ``state``. - """ - # Deposits must be processed in order - assert deposit.index == state.deposit_index - - # Verify the Merkle branch - merkle_branch_is_valid = verify_merkle_branch( - leaf=hash(serialize(deposit.data)), # 48 + 32 + 8 + 96 = 184 bytes serialization - proof=deposit.proof, - depth=DEPOSIT_CONTRACT_TREE_DEPTH, - index=deposit.index, - root=state.latest_eth1_data.deposit_root, - ) - assert merkle_branch_is_valid - - # Increment the next deposit index we are expecting. Note that this - # needs to be done here because while the deposit contract will never - # create an invalid Merkle branch, it may admit an invalid deposit - # object, and we need to be able to skip over it - state.deposit_index += 1 - - validator_pubkeys = [v.pubkey for v in state.validator_registry] - pubkey = deposit.data.pubkey - amount = deposit.data.amount - - if pubkey not in validator_pubkeys: - # Verify the proof of possession - proof_is_valid = bls_verify( - pubkey=pubkey, - message_hash=signed_root(deposit.data), - signature=deposit.data.proof_of_possession, - domain=get_domain( - state.fork, - get_current_epoch(state), - DOMAIN_DEPOSIT, - ) - ) - if not proof_is_valid: - return - - # Add new validator - validator = Validator( - pubkey=pubkey, - withdrawal_credentials=deposit.data.withdrawal_credentials, - activation_eligibility_epoch=FAR_FUTURE_EPOCH, - activation_epoch=FAR_FUTURE_EPOCH, - exit_epoch=FAR_FUTURE_EPOCH, - withdrawable_epoch=FAR_FUTURE_EPOCH, - slashed=False, - high_balance=0 - ) - - # Note: In phase 2 registry indices that have been withdrawn for a long time will be recycled. - state.validator_registry.append(validator) - state.balances.append(0) - set_balance(state, len(state.validator_registry) - 1, amount) - else: - # Increase balance by deposit amount - index = validator_pubkeys.index(pubkey) - increase_balance(state, index, amount) -``` +`bls_aggregate_pubkeys` is a function for aggregating multiple BLS public keys into a single aggregate key, defined in the [BLS Signature spec](../bls_signature.md#bls_aggregate_pubkeys). ### Routines for updating validator status @@ -1674,9 +1598,9 @@ We now define the state transition function. At a high level, the state transiti 4. The per-block transitions, which happens at every block. Transition section notes: -* The state caching caches the state root of the previous slot. +* The state caching caches the state root of the previous slot and updates block and state roots records. * The per-epoch transitions focus on the [validator](#dfn-validator) registry, including adjusting balances and activating and exiting [validators](#dfn-validator), as well as processing crosslinks and managing block justification/finalization. -* The per-slot transitions focus on the slot counter and block roots records updates. +* The per-slot transitions focus on the slot counter. * The per-block transitions generally focus on verifying aggregate signatures and saving temporary records relating to the per-block activity in the `BeaconState`. Beacon blocks that trigger unhandled Python exceptions (e.g. out-of-range list accesses) and failed `assert`s during the state transition are considered invalid. @@ -1699,7 +1623,7 @@ def cache_state(state: BeaconState) -> None: state.latest_block_header.state_root = previous_slot_state_root # store latest known block for previous slot - state.latest_block_roots[state.slot % SLOTS_PER_HISTORICAL_ROOT] = signed_root(state.latest_block_header) + state.latest_block_roots[state.slot % SLOTS_PER_HISTORICAL_ROOT] = signing_root(state.latest_block_header) ``` ### Per-epoch processing @@ -1809,8 +1733,8 @@ def update_justification_and_finalization(state: BeaconState) -> None: new_justified_epoch = state.current_justified_epoch new_finalized_epoch = state.finalized_epoch - # Rotate the justification bitfield up one epoch to make room for the current epoch - state.justification_bitfield <<= 1 + # Rotate the justification bitfield up one epoch to make room for the current epoch (and limit to 64 bits) + state.justification_bitfield = (state.justification_bitfield << 1) % 2**64 # If the previous epoch gets justified, fill the second last bit previous_boundary_attesting_balance = get_attesting_balance(state, get_previous_epoch_boundary_attestations(state)) if previous_boundary_attesting_balance * 3 >= get_previous_total_balance(state) * 2: @@ -2040,7 +1964,7 @@ def update_registry(state: BeaconState) -> None: state.latest_start_shard = ( state.latest_start_shard + - get_current_epoch_committee_count(state) + get_shard_delta(state, get_current_epoch(state)) ) % SHARD_COUNT ``` @@ -2123,7 +2047,7 @@ def process_block_header(state: BeaconState, block: BeaconBlock) -> None: # Verify that the slots match assert block.slot == state.slot # Verify that the parent matches - assert block.previous_block_root == signed_root(state.latest_block_header) + assert block.previous_block_root == signing_root(state.latest_block_header) # Save current block as the new latest block state.latest_block_header = get_temporary_block_header(block) # Verify proposer is not slashed @@ -2132,7 +2056,7 @@ def process_block_header(state: BeaconState, block: BeaconBlock) -> None: # Verify proposer signature assert bls_verify( pubkey=proposer.pubkey, - message_hash=signed_root(block), + message_hash=signing_root(block), signature=block.signature, domain=get_domain(state.fork, get_current_epoch(state), DOMAIN_BEACON_BLOCK) ) @@ -2196,7 +2120,7 @@ def process_proposer_slashing(state: BeaconState, for header in (proposer_slashing.header_1, proposer_slashing.header_2): assert bls_verify( pubkey=proposer.pubkey, - message_hash=signed_root(header), + message_hash=signing_root(header), signature=header.signature, domain=get_domain(state.fork, slot_to_epoch(header.slot), DOMAIN_BEACON_BLOCK) ) @@ -2294,7 +2218,76 @@ def process_attestation(state: BeaconState, attestation: Attestation) -> None: Verify that `len(block.body.deposits) == min(MAX_DEPOSITS, latest_eth1_data.deposit_count - state.deposit_index)`. -For each `deposit` in `block.body.deposits`, run `process_deposit(state, deposit)`. +For each `deposit` in `block.body.deposits`, run the following function: + +```python +def process_deposit(state: BeaconState, deposit: Deposit) -> None: + """ + Process a deposit from Ethereum 1.0. + Used to add a validator or top up an existing validator's + balance by some ``deposit`` amount. + + Note that this function mutates ``state``. + """ + # Deposits must be processed in order + assert deposit.index == state.deposit_index + + # Verify the Merkle branch + merkle_branch_is_valid = verify_merkle_branch( + leaf=hash(serialize(deposit.data)), # 48 + 32 + 8 + 96 = 184 bytes serialization + proof=deposit.proof, + depth=DEPOSIT_CONTRACT_TREE_DEPTH, + index=deposit.index, + root=state.latest_eth1_data.deposit_root, + ) + assert merkle_branch_is_valid + + # Increment the next deposit index we are expecting. Note that this + # needs to be done here because while the deposit contract will never + # create an invalid Merkle branch, it may admit an invalid deposit + # object, and we need to be able to skip over it + state.deposit_index += 1 + + validator_pubkeys = [v.pubkey for v in state.validator_registry] + pubkey = deposit.data.pubkey + amount = deposit.data.amount + + if pubkey not in validator_pubkeys: + # Verify the proof of possession + proof_is_valid = bls_verify( + pubkey=pubkey, + message_hash=signing_root(deposit.data), + signature=deposit.data.proof_of_possession, + domain=get_domain( + state.fork, + get_current_epoch(state), + DOMAIN_DEPOSIT, + ) + ) + if not proof_is_valid: + return + + # Add new validator + validator = Validator( + pubkey=pubkey, + withdrawal_credentials=deposit.data.withdrawal_credentials, + activation_epoch=FAR_FUTURE_EPOCH, + exit_epoch=FAR_FUTURE_EPOCH, + withdrawable_epoch=FAR_FUTURE_EPOCH, + initiated_exit=False, + slashed=False, + high_balance=0 + ) + + # Note: In phase 2 registry indices that have been withdrawn for a long time will be recycled. + state.validator_registry.append(validator) + state.balances.append(0) + set_balance(state, len(state.validator_registry) - 1, amount) + else: + # Increase balance by deposit amount + index = validator_pubkeys.index(pubkey) + increase_balance(state, index, amount) +``` ##### Voluntary exits @@ -2320,7 +2313,7 @@ def process_voluntary_exit(state: BeaconState, exit: VoluntaryExit) -> None: # Verify signature assert bls_verify( pubkey=validator.pubkey, - message_hash=signed_root(exit), + message_hash=signing_root(exit), signature=exit.signature, domain=get_domain(state.fork, exit.epoch, DOMAIN_VOLUNTARY_EXIT) ) @@ -2365,7 +2358,7 @@ def process_transfer(state: BeaconState, transfer: Transfer) -> None: # Verify that the signature is valid assert bls_verify( pubkey=transfer.pubkey, - message_hash=signed_root(transfer), + message_hash=signing_root(transfer), signature=transfer.signature, domain=get_domain(state.fork, slot_to_epoch(transfer.slot), DOMAIN_TRANSFER) ) @@ -2383,17 +2376,3 @@ Verify the block's `state_root` by running the following function: def verify_block_state_root(state: BeaconState, block: BeaconBlock) -> None: assert block.state_root == hash_tree_root(state) ``` - -# References - -This section is divided into Normative and Informative references. Normative references are those that must be read in order to implement this specification, while Informative references are merely helpful information. An example of the former might be the details of a required consensus algorithm, and an example of the latter might be a pointer to research that demonstrates why a particular consensus algorithm might be better suited for inclusion in the standard than another. - -## Normative - -## Informative - _**casper-ffg**_
  _Casper the Friendly Finality Gadget_. V. Buterin and V. Griffith. URL: https://arxiv.org/abs/1710.09437 - - _**python-poc**_
  _Python proof-of-concept implementation_. Ethereum Foundation. URL: https://github.com/ethereum/beacon_chain - -# Copyright -Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index e28536d34..6399a13c9 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -348,7 +348,7 @@ def process_bit_challenge(state: BeaconState, challenger = state.validator_registry[challenge.challenger_index] assert bls_verify( pubkey=challenger.pubkey, - message_hash=signed_root(challenge), + message_hash=signing_root(challenge), signature=challenge.signature, domain=get_domain(state, get_current_epoch(state), DOMAIN_CUSTODY_BIT_CHALLENGE), ) diff --git a/specs/core/1_shard-data-chains.md b/specs/core/1_shard-data-chains.md index 8f2d12a91..dc990567d 100644 --- a/specs/core/1_shard-data-chains.md +++ b/specs/core/1_shard-data-chains.md @@ -20,6 +20,7 @@ - [`ShardAttestation`](#shardattestation) - [Helper functions](#helper-functions) - [`get_period_committee`](#get_period_committee) + - [`get_switchover_epoch`](#get_switchover_epoch) - [`get_persistent_committee`](#get_persistent_committee) - [`get_shard_proposer_index`](#get_shard_proposer_index) - [`get_shard_header`](#get_shard_header) @@ -137,6 +138,14 @@ def get_period_committee(state: BeaconState, ) ``` +### `get_switchover_epoch` + +```python +def get_switchover_epoch(state: BeaconState, epoch: Epoch, index: ValidatorIndex): + earlier_start_epoch = epoch - (epoch % PERSISTENT_COMMITTEE_PERIOD) - PERSISTENT_COMMITTEE_PERIOD * 2 + return bytes_to_int(hash(generate_seed(state, earlier_start_epoch) + bytes3(index))[0:8]) % PERSISTENT_COMMITTEE_PERIOD +``` + ### `get_persistent_committee` ```python @@ -146,6 +155,7 @@ def get_persistent_committee(state: BeaconState, """ Return the persistent committee for the given ``shard`` at the given ``slot``. """ + epoch = slot_to_epoch(slot) earlier_start_epoch = epoch - (epoch % PERSISTENT_COMMITTEE_PERIOD) - PERSISTENT_COMMITTEE_PERIOD * 2 later_start_epoch = epoch - (epoch % PERSISTENT_COMMITTEE_PERIOD) - PERSISTENT_COMMITTEE_PERIOD @@ -160,14 +170,11 @@ def get_persistent_committee(state: BeaconState, earlier_committee = get_period_committee(state, shard, earlier_start_epoch, index, committee_count) later_committee = get_period_committee(state, shard, later_start_epoch, index, committee_count) - def get_switchover_epoch(index): - return bytes_to_int(hash(earlier_seed + bytes3(index))[0:8]) % PERSISTENT_COMMITTEE_PERIOD - # Take not-yet-cycled-out validators from earlier committee and already-cycled-in validators from # later committee; return a sorted list of the union of the two, deduplicated return sorted(list(set( - [i for i in earlier_committee if epoch % PERSISTENT_COMMITTEE_PERIOD < get_switchover_epoch(i)] + - [i for i in later_committee if epoch % PERSISTENT_COMMITTEE_PERIOD >= get_switchover_epoch(i)] + [i for i in earlier_committee if epoch % PERSISTENT_COMMITTEE_PERIOD < get_switchover_epoch(state, epoch, i)] + + [i for i in later_committee if epoch % PERSISTENT_COMMITTEE_PERIOD >= get_switchover_epoch(state, epoch, i)] ))) ``` @@ -287,7 +294,7 @@ def is_valid_shard_block(beacon_blocks: List[BeaconBlock], # Check beacon block beacon_block = beacon_blocks[block.slot] - assert block.beacon_block_root == signed_root(beacon_block) + assert block.beacon_block_root == signing_root(beacon_block) assert beacon_block.slot <= block.slot: # Check state root @@ -299,12 +306,12 @@ def is_valid_shard_block(beacon_blocks: List[BeaconBlock], else: parent_block = next( block for block in valid_shard_blocks if - signed_root(block) == candidate.previous_block_root + signing_root(block) == candidate.previous_block_root , None) assert parent_block != None assert parent_block.shard == block.shard assert parent_block.slot < block.slot - assert signed_root(beacon_blocks[parent_block.slot]) == parent_block.beacon_chain_root + assert signing_root(beacon_blocks[parent_block.slot]) == parent_block.beacon_chain_root # Check attestations assert len(block.attestations) <= MAX_SHARD_ATTESTIONS @@ -319,7 +326,7 @@ def is_valid_shard_block(beacon_blocks: List[BeaconBlock], assert proposer_index is not None assert bls_verify( pubkey=validators[proposer_index].pubkey, - message_hash=signed_root(block), + message_hash=signing_root(block), signature=block.signature, domain=get_domain(beacon_state, slot_to_epoch(block.slot), DOMAIN_SHARD_PROPOSER) ) @@ -342,7 +349,7 @@ def is_valid_shard_attestation(valid_shard_blocks: List[ShardBlock], # Check shard block shard_block = next( block for block in valid_shard_blocks if - signed_root(block) == candidate.attestation.data.shard_block_root + signing_root(block) == candidate.attestation.data.shard_block_root , None) assert shard_block != None assert shard_block.slot == attestation.data.slot diff --git a/specs/networking/rpc-interface.md b/specs/networking/rpc-interface.md index fa49bcd75..5d408b5a0 100644 --- a/specs/networking/rpc-interface.md +++ b/specs/networking/rpc-interface.md @@ -9,7 +9,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", NOT", "SHOULD", # Dependencies -This specification assumes familiarity with the [Messaging](./messaging.md), [Node Identification](./node-identification), and [Beacon Chain](../core/0_beacon-chain.md) specifications. +This specification assumes familiarity with the [Messaging](./messaging.md), [Node Identification](./node-identification.md), and [Beacon Chain](../core/0_beacon-chain.md) specifications. # Specification @@ -26,7 +26,7 @@ Message body schemas are notated like this: Embedded types are serialized as SSZ Containers unless otherwise noted. -All referenced data structures can be found in the [0-beacon-chain](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#data-structures) specification. +All referenced data structures can be found in the [0-beacon-chain](../core/0_beacon-chain.md#data-structures) specification. ## `libp2p` Protocol Names diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md index 378a1a7cb..bc621da1a 100644 --- a/specs/simple-serialize.md +++ b/specs/simple-serialize.md @@ -54,7 +54,7 @@ For convenience we alias: We recursively define the `serialize` function which consumes an object `value` (of the type specified) and returns a bytestring of type `"bytes"`. -*Note*: In the function definitions below (`serialize`, `hash_tree_root`, `signed_root`, etc.) objects implicitly carry their type. +*Note*: In the function definitions below (`serialize`, `hash_tree_root`, `signing_root`, etc.) objects implicitly carry their type. ### `"uintN"` @@ -108,17 +108,17 @@ We now define Merkleization `hash_tree_root(value)` of an object `value` recursi ## Self-signed containers -Let `value` be a self-signed container object. The convention is that the signature (e.g. a `"bytes96"` BLS12-381 signature) be the last field of `value`. Further, the signed message for `value` is `signed_root(value) = hash_tree_root(truncate_last(value))` where `truncate_last` truncates the last element of `value`. +Let `value` be a self-signed container object. The convention is that the signature (e.g. a `"bytes96"` BLS12-381 signature) be the last field of `value`. Further, the signed message for `value` is `signing_root(value) = hash_tree_root(truncate_last(value))` where `truncate_last` truncates the last element of `value`. ## Implementations | Language | Project | Maintainer | Implementation | |-|-|-|-| | Python | Ethereum 2.0 | Ethereum Foundation | [https://github.com/ethereum/py-ssz](https://github.com/ethereum/py-ssz) | -| Rust | Lighthouse | Sigma Prime | [https://github.com/sigp/lighthouse/tree/master/beacon_chain/utils/ssz](https://github.com/sigp/lighthouse/tree/master/beacon_chain/utils/ssz) | +| Rust | Lighthouse | Sigma Prime | [https://github.com/sigp/lighthouse/tree/master/eth2/utils/ssz](https://github.com/sigp/lighthouse/tree/master/eth2/utils/ssz) | | Nim | Nimbus | Status | [https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim](https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim) | | Rust | Shasper | ParityTech | [https://github.com/paritytech/shasper/tree/master/util/ssz](https://github.com/paritytech/shasper/tree/master/util/ssz) | -| Javascript | Lodestart | Chain Safe Systems | [https://github.com/ChainSafeSystems/ssz-js/blob/master/src/index.js](https://github.com/ChainSafeSystems/ssz-js/blob/master/src/index.js) | +| TypeScript | Lodestar | ChainSafe Systems | [https://github.com/ChainSafe/ssz-js](https://github.com/ChainSafe/ssz-js) | | Java | Cava | ConsenSys | [https://www.github.com/ConsenSys/cava/tree/master/ssz](https://www.github.com/ConsenSys/cava/tree/master/ssz) | | Go | Prysm | Prysmatic Labs | [https://github.com/prysmaticlabs/prysm/tree/master/shared/ssz](https://github.com/prysmaticlabs/prysm/tree/master/shared/ssz) | | Swift | Yeeth | Dean Eigenmann | [https://github.com/yeeth/SimpleSerialize.swift](https://github.com/yeeth/SimpleSerialize.swift) | diff --git a/specs/test-format.md b/specs/test-format.md deleted file mode 100644 index d4256ef72..000000000 --- a/specs/test-format.md +++ /dev/null @@ -1,71 +0,0 @@ -# General test format [WIP] - -This document defines the general YAML format to which all tests should conform. Testing specifications in Eth2.0 are still a work in progress. _Expect breaking changes_ - -## ToC - -* [About](#about) -* [YAML Fields](#yaml-fields) -* [Example test suite](#example-test-suite) - -## About -Ethereum 2.0 uses YAML as the format for all cross client tests. This document describes at a high level the general format to which all test files should conform. - -The particular formats of specific types of tests (test suites) are defined in separate documents. - -## YAML fields -`title` _(required)_ - -`summary` _(optional)_ - -`test_suite` _(required)_ string defining the test suite to which the test cases conform - -`fork` _(required)_ production release versioning - -`version` _(required)_ version for particular test document - -`test_cases` _(required)_ list of test cases each of which is formatted to conform to the `test_case` standard defined by `test_suite`. All test cases have optional `name` and `description` string fields. - -## Example test suite -`shuffle` is a test suite that defines test cases for the `shuffle()` helper function defined in the `beacon-chain` spec. - -Test cases that conform to the `shuffle` test suite have the following fields: - -* `input` _(required)_ the list of items passed into `shuffle()` -* `output` _(required)_ the expected list returned by `shuffle()` -* `seed` _(required)_ the seed of entropy passed into `shuffle()` - -As for all test cases, `name` and `description` are optional string fields. - -The following is a sample YAML document for the `shuffle` test suite: - -```yaml -title: Shuffling Algorithm Tests -summary: Test vectors for shuffling a list based upon a seed using `shuffle` -test_suite: shuffle -fork: tchaikovsky -version: 1.0 - -test_cases: -- input: [] - output: [] - seed: !!binary "" -- name: boring_list - description: List with a single element, 0 - input: [0] - output: [0] - seed: !!binary "" -- input: [255] - output: [255] - seed: !!binary "" -- input: [4, 6, 2, 6, 1, 4, 6, 2, 1, 5] - output: [1, 6, 4, 1, 6, 6, 2, 2, 4, 5] - seed: !!binary "" -- input: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13] - output: [4, 7, 10, 13, 3, 1, 2, 9, 12, 6, 11, 8, 5] - seed: !!binary "" -- input: [65, 6, 2, 6, 1, 4, 6, 2, 1, 5] - output: [6, 65, 2, 5, 4, 2, 6, 6, 1, 1] - seed: !!binary | - JlAYJ5H2j8g7PLiPHZI/rTS1uAvKiieOrifPN6Moso0= -``` diff --git a/specs/test_formats/README.md b/specs/test_formats/README.md new file mode 100644 index 000000000..2c1ef2d03 --- /dev/null +++ b/specs/test_formats/README.md @@ -0,0 +1,171 @@ +# General test format + +This document defines the YAML format and structure used for ETH 2.0 testing. + +## ToC + +* [About](#about) +* [Glossary](#glossary) +* [Test format philosophy](#test-format-philosophy) +* [Test Suite](#test-suite) +* [Config](#config) +* [Fork-timeline](#fork-timeline) +* [Config sourcing](#config-sourcing) +* [Test structure](#test-structure) + +## About + +Ethereum 2.0 uses YAML as the format for all cross client tests. This document describes at a high level the general format to which all test files should conform. + +The particular formats of specific types of tests (test suites) are defined in separate documents. + +## Glossary + +- `generator`: a program that outputs one or more `suite` files. + - A generator should only output one `type` of test. + - A generator is free to output multiple `suite` files, optionally with different `handler`s. +- `type`: the specialization of one single `generator`. +- `suite`: a YAML file with: + - a header: describes the `suite`, and defines what the `suite` is for + - a list of test cases +- `runner`: where a generator is a *"producer"*, this is the *"consumer"*. + - A `runner` focuses on *only one* `type`, and each type has *only one* `runner`. +- `handler`: a `runner` may be too limited sometimes, you may have a `suite` with a specific focus that requires a different format. + To facilitate this, you specify a `handler`: the runner can deal with the format by using the specified handler. + Using a `handler` in a `runner` is optional. +- `case`: a test case, an entry in the `test_cases` list of a `suite`. A case can be anything in general, + but its format should be well-defined in the documentation corresponding to the `type` (and `handler`).\ + A test has the same exact configuration and fork context as the other entries in the `case` list of its `suite`. +- `forks_timeline`: a fork timeline definition, a YAML file containing a key for each fork-name, and an epoch number as value. + +## Test format philosophy + +### Config design + +After long discussion, the following types of configured constants were identified: +- Never changing: genesis data +- Changing, but reliant on old value: e.g. an epoch time may change, but if you want to do the conversion + `(genesis data, timestamp) -> epoch number` you end up needing both constants. +- Changing, but kept around during fork transition: finalization may take a while, + e.g. an executable has to deal with new deposits and old deposits at the same time. Another example may be economic constants. +- Additional, back-wards compatible: new constants are introduced for later phases +- Changing: there is a very small chance some constant may really be *replaced*. + In this off-chance, it is likely better to include it as an additional variable, + and some clients may simply stop supporting the old one, if they do not want to sync from genesis. + +Based on these types of changes, we model the config as a list of key value pairs, + that only grows with every fork (they may change in development versions of forks however, git manages this). +With this approach, configurations are backwards compatible (older clients ignore unknown variables), and easy to maintain. + +### Fork config design + +There are two types of fork-data: +1) timeline: when does a fork take place? +2) coverage: what forks are covered by a test? + +The first is neat to have as a separate form: we prevent duplication, and can run with different presets + (e.g. fork timeline for a minimal local test, for a public testnet, or for mainnet) + +The second is still somewhat ambiguous: some tests may want cover multiple forks, and can do so in different ways: +- run one test, transitioning from one to the other +- run the same test for both +- run a test for every transition from one fork to the other +- more + +There is a common factor here however: the options are exclusive, and give a clear idea on what test suites need to be ran to cover testing for a specific fork. +The way this list of forks is interpreted, is up to the test-runner: +State-transition test suites may want to just declare forks that are being covered in the test suite, + whereas shuffling test suites may want to declare a list of forks to test the shuffling algorithm for individually. + +### Test completeness + +Tests should be independent of any sync-data. If one wants to run a test, the input data should be available from the YAML. +The aim is to provide clients with a well-defined scope of work to run a particular set of test-suites. + +- Clients that are complete are expected to contribute to testing, seeking for better resources to get conformance with the spec, and other clients. +- Clients that are not complete in functionality can choose to ignore suites that use certain test-runners, or specific handlers of these test-runners. +- Clients that are on older versions can test there work based on older releases of the generated tests, and catch up with newer releases when possible. + +## Test Suite + +``` +title: -- Display name for the test suite +summary: -- Summarizes the test suite +forks_timeline: -- Used to determine the forking timeline +forks: -- Runner decides what to do: run for each fork, or run for all at once, each fork transition, etc. + - ... +config: -- Used to determine which set of constants to run (possibly compile time) with +runner: *MUST be consistent with folder structure* +handler: *MUST be consistent with folder structure* + +test_cases: + ... + +``` + +## Config + +A configuration is a separate YAML file. +Separation of configuration and tests aims to: +- Prevent duplication of configuration +- Make all tests easy to upgrade (e.g. when a new config constant is introduced) +- Clearly define which constants to use +- Shareable between clients, for cross-client short or long lived testnets +- Minimize the amounts of different constants permutations to compile as a client. + Note: 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: + - we do not allocate or optimize any code based on epoch numbers + - when we transition from one fork to the other, it is preferred to stay online. + - 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: + +``` +/configs/constant_presets/.yaml +``` + +And copied by CI for testing purposes to: + +``` +/configs/constant_presets/.yaml +``` + + +The fork timelines are located in: + +``` +/configs/fork_timelines/.yaml +``` + +And copied by CI for testing purposes to: + +``` +/configs/fork_timelines/.yaml +``` + +## Test structure + +To prevent parsing of hundreds of different YAML files to test a specific test type, + or even more specific, just a handler, tests should be structured in the following nested form: + +``` +. <--- root of eth2.0 tests repository +├── bls <--- collection of handler for a specific test-runner, example runner: "bls" +│   ├── signing <--- collection of test suites for a specific handler, example handler: "signing". If no handler, use a dummy folder "main" +│   │   ├── sign_msg.yml <--- an entry list of test suites +│   │   ... <--- more suite files (optional) +│   ... <--- more handlers +... <--- more test types +``` diff --git a/specs/validator/0_beacon-chain-validator.md b/specs/validator/0_beacon-chain-validator.md index 0d6033acd..60d283664 100644 --- a/specs/validator/0_beacon-chain-validator.md +++ b/specs/validator/0_beacon-chain-validator.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 0 -- Honest Validator -__NOTICE__: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md) that describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. +__NOTICE__: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](../core/0_beacon-chain.md) that describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. ## Table of Contents @@ -66,7 +66,7 @@ A validator is an entity that participates in the consensus of the Ethereum 2.0 ## Prerequisites -All terminology, constants, functions, and protocol mechanics defined in the [Phase 0 -- The Beacon Chain](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md) doc are requisite for this document and used throughout. Please see the Phase 0 doc before continuing and use as a reference throughout. +All terminology, constants, functions, and protocol mechanics defined in the [Phase 0 -- The Beacon Chain](../core/0_beacon-chain.md) doc are requisite for this document and used throughout. Please see the Phase 0 doc before continuing and use as a reference throughout. ## Constants @@ -84,7 +84,7 @@ A validator must initialize many parameters locally before submitting a deposit #### BLS public key -Validator public keys are [G1 points](https://github.com/ethereum/eth2.0-specs/blob/master/specs/bls_signature.md#g1-points) on the [BLS12-381 curve](https://z.cash/blog/new-snark-curve). A private key, `privkey`, must be securely generated along with the resultant `pubkey`. This `privkey` must be "hot", that is, constantly available to sign data throughout the lifetime of the validator. +Validator public keys are [G1 points](../bls_signature.md#g1-points) on the [BLS12-381 curve](https://z.cash/blog/new-snark-curve). A private key, `privkey`, must be securely generated along with the resultant `pubkey`. This `privkey` must be "hot", that is, constantly available to sign data throughout the lifetime of the validator. #### BLS withdrawal key @@ -96,15 +96,16 @@ The validator constructs their `withdrawal_credentials` via the following: ### Submit deposit -In phase 0, all incoming validator deposits originate from the Ethereum 1.0 PoW chain. Deposits are made to the [deposit contract](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#ethereum-10-deposit-contract) located at `DEPOSIT_CONTRACT_ADDRESS`. +In phase 0, all incoming validator deposits originate from the Ethereum 1.0 PoW chain. Deposits are made to the [deposit contract](../core/0_beacon-chain.md#ethereum-10-deposit-contract) located at `DEPOSIT_CONTRACT_ADDRESS`. To submit a deposit: -* Pack the validator's [initialization parameters](#initialization) into `deposit_input`, a [`DepositInput`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#depositinput) SSZ object. -* Let `proof_of_possession` be the result of `bls_sign` of the `signed_root(deposit_input)` with `domain=DOMAIN_DEPOSIT`. -* Set `deposit_input.proof_of_possession = proof_of_possession`. +* Pack the validator's [initialization parameters](#initialization) into `deposit_data`, a [`DepositData`](../core/0_beacon-chain.md#depositdata) SSZ object. +* Let `proof_of_possession` be the result of `bls_sign` of the `signing_root(deposit_data)` with `domain=DOMAIN_DEPOSIT`. +* Set `deposit_data.proof_of_possession = proof_of_possession`. * Let `amount` be the amount in Gwei to be deposited by the validator where `MIN_DEPOSIT_AMOUNT <= amount <= MAX_DEPOSIT_AMOUNT`. -* Send a transaction on the Ethereum 1.0 chain to `DEPOSIT_CONTRACT_ADDRESS` executing `deposit` along with `serialize(deposit_input)` as the singular `bytes` input along with a deposit `amount` in Gwei. +* Set `deposit_data.amount = amount`. +* Send a transaction on the Ethereum 1.0 chain to `DEPOSIT_CONTRACT_ADDRESS` executing `deposit(deposit_input: bytes[512])` along with `serialize(deposit_data)` as the singular `bytes` input along with a deposit of `amount` Gwei. _Note_: Deposits made for the same `pubkey` are treated as for the same validator. A singular `Validator` will be added to `state.validator_registry` with each additional deposit amount added to the validator's balance. A validator can only be activated when total deposits for the validator pubkey meet or exceed `MAX_DEPOSIT_AMOUNT`. @@ -114,13 +115,13 @@ Deposits cannot be processed into the beacon chain until the eth1.0 block in whi ### Validator index -Once a validator has been processed and added to the beacon state's `validator_registry`, the validator's `validator_index` is defined by the index into the registry at which the [`ValidatorRecord`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#validator) contains the `pubkey` specified in the validator's deposit. A validator's `validator_index` is guaranteed to not change from the time of initial deposit until the validator exits and fully withdraws. This `validator_index` is used throughout the specification to dictate validator roles and responsibilities at any point and should be stored locally. +Once a validator has been processed and added to the beacon state's `validator_registry`, the validator's `validator_index` is defined by the index into the registry at which the [`ValidatorRecord`](../core/0_beacon-chain.md#validator) contains the `pubkey` specified in the validator's deposit. A validator's `validator_index` is guaranteed to not change from the time of initial deposit until the validator exits and fully withdraws. This `validator_index` is used throughout the specification to dictate validator roles and responsibilities at any point and should be stored locally. ### Activation In normal operation, the validator is quickly activated at which point the validator is added to the shuffling and begins validation after an additional `ACTIVATION_EXIT_DELAY` epochs (25.6 minutes). -The function [`is_active_validator`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#is_active_validator) can be used to check if a validator is active during a given shuffling epoch. Note that the `BeaconState` contains a field `current_shuffling_epoch` which dictates from which epoch the current active validators are taken. Usage is as follows: +The function [`is_active_validator`](../core/0_beacon-chain.md#is_active_validator) can be used to check if a validator is active during a given shuffling epoch. Note that the `BeaconState` contains a field `current_shuffling_epoch` which dictates from which epoch the current active validators are taken. Usage is as follows: ```python shuffling_epoch = state.current_shuffling_epoch @@ -138,7 +139,7 @@ A validator has two primary responsibilities to the beacon chain -- [proposing b ### Block proposal -A validator is expected to propose a [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconblock) at the beginning of any slot during which `get_beacon_proposer_index(state, slot)` returns the validator's `validator_index`. To propose, the validator selects the `BeaconBlock`, `parent`, that in their view of the fork choice is the head of the chain during `slot - 1`. The validator is to create, sign, and broadcast a `block` that is a child of `parent` and that executes a valid [beacon chain state transition](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beacon-chain-state-transition-function). +A validator is expected to propose a [`BeaconBlock`](../core/0_beacon-chain.md#beaconblock) at the beginning of any slot during which `get_beacon_proposer_index(state, slot)` returns the validator's `validator_index`. To propose, the validator selects the `BeaconBlock`, `parent`, that in their view of the fork choice is the head of the chain during `slot - 1`. The validator is to create, sign, and broadcast a `block` that is a child of `parent` and that executes a valid [beacon chain state transition](../core/0_beacon-chain.md#beacon-chain-state-transition-function). There is one proposer per slot, so if there are N active validators any individual validator will on average be assigned to propose once per N slots (eg. at 312500 validators = 10 million ETH, that's once per ~3 weeks). @@ -152,7 +153,7 @@ _Note:_ there might be "skipped" slots between the `parent` and `block`. These s ##### Parent root -Set `block.previous_block_root = signed_root(parent)`. +Set `block.previous_block_root = signing_root(parent)`. ##### State root @@ -199,7 +200,7 @@ Set `block.signature = block_signature` where `block_signature` is defined as: ```python block_signature = bls_sign( privkey=validator.privkey, # privkey store locally, not in state - message_hash=signed_root(block), + message_hash=signing_root(block), domain=get_domain( fork=fork, # `fork` is the fork object at the slot `block.slot` epoch=slot_to_epoch(block.slot), @@ -212,25 +213,25 @@ block_signature = bls_sign( ##### Proposer slashings -Up to `MAX_PROPOSER_SLASHINGS` [`ProposerSlashing`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#proposerslashing) objects can be included in the `block`. The proposer slashings must satisfy the verification conditions found in [proposer slashings processing](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#proposer-slashings). The validator receives a small "whistleblower" reward for each proposer slashing found and included. +Up to `MAX_PROPOSER_SLASHINGS` [`ProposerSlashing`](../core/0_beacon-chain.md#proposerslashing) objects can be included in the `block`. The proposer slashings must satisfy the verification conditions found in [proposer slashings processing](../core/0_beacon-chain.md#proposer-slashings). The validator receives a small "whistleblower" reward for each proposer slashing found and included. ##### Attester slashings -Up to `MAX_ATTESTER_SLASHINGS` [`AttesterSlashing`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attesterslashing) objects can be included in the `block`. The attester slashings must satisfy the verification conditions found in [Attester slashings processing](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attester-slashings). The validator receives a small "whistleblower" reward for each attester slashing found and included. +Up to `MAX_ATTESTER_SLASHINGS` [`AttesterSlashing`](../core/0_beacon-chain.md#attesterslashing) objects can be included in the `block`. The attester slashings must satisfy the verification conditions found in [Attester slashings processing](../core/0_beacon-chain.md#attester-slashings). The validator receives a small "whistleblower" reward for each attester slashing found and included. ##### Attestations -Up to `MAX_ATTESTATIONS` aggregate attestations can be included in the `block`. The attestations added must satisfy the verification conditions found in [attestation processing](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attestations). To maximize profit, the validator should attempt to gather aggregate attestations that include singular attestations from the largest number of validators whose signatures from the same epoch have not previously been added on chain. +Up to `MAX_ATTESTATIONS` aggregate attestations can be included in the `block`. The attestations added must satisfy the verification conditions found in [attestation processing](../core/0_beacon-chain.md#attestations). To maximize profit, the validator should attempt to gather aggregate attestations that include singular attestations from the largest number of validators whose signatures from the same epoch have not previously been added on chain. ##### Deposits -If there are any unprocessed deposits for the existing `state.latest_eth1_data` (i.e. `state.latest_eth1_data.deposit_count > state.deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, latest_eth1_data.deposit_count - state.deposit_index)`. These [`deposits`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [Eth1.0 deposit contract](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#ethereum-10-deposit-contract) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#deposits). +If there are any unprocessed deposits for the existing `state.latest_eth1_data` (i.e. `state.latest_eth1_data.deposit_count > state.deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, latest_eth1_data.deposit_count - state.deposit_index)`. These [`deposits`](../core/0_beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [Eth1.0 deposit contract](../core/0_beacon-chain.md#ethereum-10-deposit-contract) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](../core/0_beacon-chain.md#deposits). The `proof` for each deposit must be constructed against the deposit root contained in `state.latest_eth1_data` rather than the deposit root at the time the deposit was initially logged from the 1.0 chain. This entails storing a full deposit merkle tree locally and computing updated proofs against the `latest_eth1_data.deposit_root` as needed. See [`minimal_merkle.py`](https://github.com/ethereum/research/blob/master/spec_pythonizer/utils/merkle_minimal.py) for a sample implementation. ##### Voluntary exits -Up to `MAX_VOLUNTARY_EXITS` [`VoluntaryExit`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#voluntaryexit) objects can be included in the `block`. The exits must satisfy the verification conditions found in [exits processing](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#voluntary-exits). +Up to `MAX_VOLUNTARY_EXITS` [`VoluntaryExit`](../core/0_beacon-chain.md#voluntaryexit) objects can be included in the `block`. The exits must satisfy the verification conditions found in [exits processing](../core/0_beacon-chain.md#voluntary-exits). ### Attestations @@ -240,7 +241,7 @@ A validator should create and broadcast the attestation halfway through the `slo #### Attestation data -First the validator should construct `attestation_data`, an [`AttestationData`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attestationdata) object based upon the state at the assigned slot. +First the validator should construct `attestation_data`, an [`AttestationData`](../core/0_beacon-chain.md#attestationdata) object based upon the state at the assigned slot. * Let `head_block` be the result of running the fork choice during the assigned slot. * Let `head_state` be the state of `head_block` processed through any empty slots up to the assigned slot. @@ -255,11 +256,11 @@ Set `attestation_data.shard = shard` where `shard` is the shard associated with ##### Beacon block root -Set `attestation_data.beacon_block_root = signed_root(head_block)`. +Set `attestation_data.beacon_block_root = signing_root(head_block)`. ##### Target root -Set `attestation_data.target_root = signed_root(epoch_boundary)` where `epoch_boundary` is the block at the most recent epoch boundary. +Set `attestation_data.target_root = signing_root(epoch_boundary)` where `epoch_boundary` is the block at the most recent epoch boundary. _Note:_ This can be looked up in the state using: * Let `epoch_start_slot = get_epoch_start_slot(get_current_epoch(head_state))`. @@ -285,7 +286,7 @@ Set `attestation_data.source_root = head_state.current_justified_root`. #### Construct attestation -Next the validator creates `attestation`, an [`Attestation`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attestation) object. +Next the validator creates `attestation`, an [`Attestation`](../core/0_beacon-chain.md#attestation) object. ##### Data @@ -399,7 +400,7 @@ _Note_: Signed data must be within a sequential `Fork` context to conflict. Mess ### Proposer slashing -To avoid "proposer slashings", a validator must not sign two conflicting [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#proposalsigneddata) where conflicting is defined as two distinct blocks within the same epoch. +To avoid "proposer slashings", a validator must not sign two conflicting [`BeaconBlock`](../core/0_beacon-chain.md#beaconblock) where conflicting is defined as two distinct blocks within the same epoch. _In phase 0, as long as the validator does not sign two different beacon blocks for the same epoch, the validator is safe against proposer slashings._ @@ -411,7 +412,7 @@ If the software crashes at some point within this routine, then when the validat ### Attester slashing -To avoid "attester slashings", a validator must not sign two conflicting [`AttestationData`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attestationdata) objects where conflicting is defined as a set of two attestations that satisfy either [`is_double_vote`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#is_double_vote) or [`is_surround_vote`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#is_surround_vote). +To avoid "attester slashings", a validator must not sign two conflicting [`AttestationData`](../core/0_beacon-chain.md#attestationdata) objects where conflicting is defined as a set of two attestations that satisfy either [`is_double_vote`](../core/0_beacon-chain.md#is_double_vote) or [`is_surround_vote`](../core/0_beacon-chain.md#is_surround_vote). Specifically, when signing an `Attestation`, a validator should perform the following steps in the following order: 1. Save a record to hard disk that an attestation has been signed for source -- `attestation_data.source_epoch` -- and target -- `slot_to_epoch(attestation_data.slot)`. diff --git a/tests/phase0/helpers.py b/tests/phase0/helpers.py index 34f2f8d7f..5fe22e6a4 100644 --- a/tests/phase0/helpers.py +++ b/tests/phase0/helpers.py @@ -3,7 +3,7 @@ from copy import deepcopy from py_ecc import bls import build.phase0.spec as spec -from build.phase0.utils.minimal_ssz import signed_root +from build.phase0.utils.minimal_ssz import signing_root from build.phase0.spec import ( # constants EMPTY_SIGNATURE, @@ -101,7 +101,7 @@ def build_empty_block_for_next_slot(state): previous_block_header = deepcopy(state.latest_block_header) if previous_block_header.state_root == spec.ZERO_HASH: previous_block_header.state_root = state.hash_tree_root() - empty_block.previous_block_root = signed_root(previous_block_header) + empty_block.previous_block_root = signing_root(previous_block_header) return empty_block @@ -114,7 +114,7 @@ def build_deposit_data(state, pubkey, privkey, amount): proof_of_possession=EMPTY_SIGNATURE, ) proof_of_possession = bls.sign( - message_hash=signed_root(deposit_data), + message_hash=signing_root(deposit_data), privkey=privkey, domain=get_domain( state.fork, @@ -161,7 +161,7 @@ def build_voluntary_exit(state, epoch, validator_index, privkey): signature=EMPTY_SIGNATURE, ) voluntary_exit.signature = bls.sign( - message_hash=signed_root(voluntary_exit), + message_hash=signing_root(voluntary_exit), privkey=privkey, domain=get_domain( fork=state.fork, @@ -220,12 +220,12 @@ def get_valid_proposer_slashing(state): domain_type=spec.DOMAIN_BEACON_BLOCK, ) header_1.signature = bls.sign( - message_hash=signed_root(header_1), + message_hash=signing_root(header_1), privkey=privkey, domain=domain, ) header_2.signature = bls.sign( - message_hash=signed_root(header_2), + message_hash=signing_root(header_2), privkey=privkey, domain=domain, ) diff --git a/tests/phase0/test_sanity.py b/tests/phase0/test_sanity.py index 7ed31b7bd..9b2bf9c7f 100644 --- a/tests/phase0/test_sanity.py +++ b/tests/phase0/test_sanity.py @@ -5,7 +5,7 @@ import pytest from py_ecc import bls import build.phase0.spec as spec -from build.phase0.utils.minimal_ssz import signed_root +from build.phase0.utils.minimal_ssz import signing_root from build.phase0.spec import ( # constants EMPTY_SIGNATURE, @@ -293,7 +293,7 @@ def test_voluntary_exit(state): signature=EMPTY_SIGNATURE, ) voluntary_exit.signature = bls.sign( - message_hash=signed_root(voluntary_exit), + message_hash=signing_root(voluntary_exit), privkey=privkeys[validator_index], domain=get_domain( fork=pre_state.fork, @@ -371,7 +371,7 @@ def test_transfer(state): signature=EMPTY_SIGNATURE, ) transfer.signature = bls.sign( - message_hash=signed_root(transfer), + message_hash=signing_root(transfer), privkey=transfer_privkey, domain=get_domain( fork=pre_state.fork, diff --git a/utils/phase0/minimal_ssz.py b/utils/phase0/minimal_ssz.py index c4828d08f..902ed8460 100644 --- a/utils/phase0/minimal_ssz.py +++ b/utils/phase0/minimal_ssz.py @@ -205,7 +205,7 @@ def truncate(container): return truncated_class(**kwargs) -def signed_root(container): +def signing_root(container): return hash_tree_root(truncate(container))