diff --git a/.circleci/config.yml b/.circleci/config.yml index b612378e2..19ab1543a 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -103,6 +103,15 @@ jobs: command: make citest - store_test_results: path: test_libs/pyspec/test-reports + table_of_contents: + docker: + - image: circleci/node:10.16.3 + working_directory: ~/specs-repo + steps: + - checkout + - run: + name: Check table of contents + command: sudo npm install -g doctoc && make check_toc lint: docker: - image: circleci/python:3.6 @@ -148,6 +157,7 @@ workflows: - test: requires: - install_pyspec_test + - table_of_contents - lint: requires: - test diff --git a/Makefile b/Makefile index bfbc28070..2cdb1021f 100644 --- a/Makefile +++ b/Makefile @@ -17,18 +17,22 @@ GENERATOR_VENVS = $(patsubst $(GENERATOR_DIR)/%, $(GENERATOR_DIR)/%venv, $(GENER #$(info $$GENERATOR_TARGETS is [${GENERATOR_TARGETS}]) PY_SPEC_PHASE_0_TARGETS = $(PY_SPEC_DIR)/eth2spec/phase0/spec.py -PY_SPEC_PHASE_0_DEPS = $(SPEC_DIR)/core/0_*.md +PY_SPEC_PHASE_0_DEPS = $(wildcard $(SPEC_DIR)/core/0_*.md) PY_SPEC_PHASE_1_TARGETS = $(PY_SPEC_DIR)/eth2spec/phase1/spec.py -PY_SPEC_PHASE_1_DEPS = $(SPEC_DIR)/core/1_*.md +PY_SPEC_PHASE_1_DEPS = $(wildcard $(SPEC_DIR)/core/1_*.md) + +PY_SPEC_ALL_DEPS = $(PY_SPEC_PHASE_0_DEPS) $(PY_SPEC_PHASE_1_DEPS) PY_SPEC_ALL_TARGETS = $(PY_SPEC_PHASE_0_TARGETS) $(PY_SPEC_PHASE_1_TARGETS) +MARKDOWN_FILES = $(PY_SPEC_ALL_DEPS) $(wildcard $(SPEC_DIR)/*.md) $(wildcard $(SPEC_DIR)/light_client/*.md) $(wildcard $(SPEC_DIR)/networking/*.md) $(wildcard $(SPEC_DIR)/validator/*.md) + COV_HTML_OUT=.htmlcov COV_INDEX_FILE=$(PY_SPEC_DIR)/$(COV_HTML_OUT)/index.html .PHONY: clean partial_clean all test citest lint generate_tests pyspec phase0 phase1 install_test open_cov \ - install_deposit_contract_test test_deposit_contract compile_deposit_contract + install_deposit_contract_test test_deposit_contract compile_deposit_contract check_toc all: $(PY_SPEC_ALL_TARGETS) @@ -65,6 +69,14 @@ citest: $(PY_SPEC_ALL_TARGETS) open_cov: ((open "$(COV_INDEX_FILE)" || xdg-open "$(COV_INDEX_FILE)") &> /dev/null) & +check_toc: $(MARKDOWN_FILES:=.toc) + +%.toc: + cp $* $*.tmp && \ + doctoc $* && \ + diff -q $* $*.tmp && \ + rm $*.tmp + lint: $(PY_SPEC_ALL_TARGETS) cd $(PY_SPEC_DIR); . venv/bin/activate; \ flake8 --ignore=E252,W504,W503 --max-line-length=120 ./eth2spec \ diff --git a/specs/bls_signature.md b/specs/bls_signature.md index 652279cd7..284485afb 100644 --- a/specs/bls_signature.md +++ b/specs/bls_signature.md @@ -6,23 +6,25 @@ ## Table of contents + + -- [BLS signature verification](#bls-signature-verification) - - [Table of contents](#table-of-contents) - - [Curve parameters](#curve-parameters) - - [Point representations](#point-representations) - - [G1 points](#g1-points) - - [G2 points](#g2-points) - - [Helpers](#helpers) - - [`hash_to_G2`](#hash_to_g2) - - [`modular_squareroot`](#modular_squareroot) - - [Aggregation operations](#aggregation-operations) - - [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys) - - [`bls_aggregate_signatures`](#bls_aggregate_signatures) - - [Signature verification](#signature-verification) - - [`bls_verify`](#bls_verify) - - [`bls_verify_multiple`](#bls_verify_multiple) +- [Curve parameters](#curve-parameters) +- [Point representations](#point-representations) + - [G1 points](#g1-points) + - [G2 points](#g2-points) +- [Helpers](#helpers) + - [`hash_to_G2`](#hash_to_g2) + - [`modular_squareroot`](#modular_squareroot) +- [Aggregation operations](#aggregation-operations) + - [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys) + - [`bls_aggregate_signatures`](#bls_aggregate_signatures) +- [Signature verification](#signature-verification) + - [`bls_verify`](#bls_verify) + - [`bls_verify_multiple`](#bls_verify_multiple) + + ## Curve parameters diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index f881bef5f..22522b3bd 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -4,121 +4,121 @@ ## Table of contents + + -- [Ethereum 2.0 Phase 0 -- The Beacon Chain](#ethereum-20-phase-0----the-beacon-chain) - - [Table of contents](#table-of-contents) - - [Introduction](#introduction) - - [Notation](#notation) - - [Custom types](#custom-types) - - [Constants](#constants) - - [Configuration](#configuration) - - [Misc](#misc) - - [Gwei values](#gwei-values) - - [Initial values](#initial-values) - - [Time parameters](#time-parameters) - - [State list lengths](#state-list-lengths) - - [Rewards and penalties](#rewards-and-penalties) - - [Max operations per block](#max-operations-per-block) - - [Domain types](#domain-types) - - [Containers](#containers) - - [Misc dependencies](#misc-dependencies) - - [`Fork`](#fork) - - [`Checkpoint`](#checkpoint) - - [`Validator`](#validator) - - [`AttestationData`](#attestationdata) - - [`IndexedAttestation`](#indexedattestation) - - [`PendingAttestation`](#pendingattestation) - - [`Eth1Data`](#eth1data) - - [`HistoricalBatch`](#historicalbatch) - - [`DepositMessage`](#depositmessage) - - [`DepositData`](#depositdata) - - [`BeaconBlockHeader`](#beaconblockheader) - - [Beacon operations](#beacon-operations) - - [`ProposerSlashing`](#proposerslashing) - - [`AttesterSlashing`](#attesterslashing) - - [`Attestation`](#attestation) - - [`Deposit`](#deposit) - - [`VoluntaryExit`](#voluntaryexit) - - [Beacon blocks](#beacon-blocks) - - [`BeaconBlockBody`](#beaconblockbody) - - [`BeaconBlock`](#beaconblock) - - [Beacon state](#beacon-state) - - [`BeaconState`](#beaconstate) - - [Signed envelopes](#signed-envelopes) - - [`SignedVoluntaryExit`](#signedvoluntaryexit) - - [`SignedBeaconBlock`](#signedbeaconblock) - - [`SignedBeaconBlockHeader`](#signedbeaconblockheader) - - [Helper functions](#helper-functions) - - [Math](#math) - - [`integer_squareroot`](#integer_squareroot) - - [`xor`](#xor) - - [`int_to_bytes`](#int_to_bytes) - - [`bytes_to_int`](#bytes_to_int) - - [Crypto](#crypto) - - [`hash`](#hash) - - [`hash_tree_root`](#hash_tree_root) - - [`bls_verify`](#bls_verify) - - [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys) - - [Predicates](#predicates) - - [`is_active_validator`](#is_active_validator) - - [`is_eligible_for_activation_queue`](#is_eligible_for_activation_queue) - - [`is_eligible_for_activation`](#is_eligible_for_activation) - - [`is_slashable_validator`](#is_slashable_validator) - - [`is_slashable_attestation_data`](#is_slashable_attestation_data) - - [`is_valid_indexed_attestation`](#is_valid_indexed_attestation) - - [`is_valid_merkle_branch`](#is_valid_merkle_branch) - - [Misc](#misc-1) - - [`compute_shuffled_index`](#compute_shuffled_index) - - [`compute_proposer_index`](#compute_proposer_index) - - [`compute_committee`](#compute_committee) - - [`compute_epoch_at_slot`](#compute_epoch_at_slot) - - [`compute_start_slot_at_epoch`](#compute_start_slot_at_epoch) - - [`compute_activation_exit_epoch`](#compute_activation_exit_epoch) - - [`compute_domain`](#compute_domain) - - [Beacon state accessors](#beacon-state-accessors) - - [`get_current_epoch`](#get_current_epoch) - - [`get_previous_epoch`](#get_previous_epoch) - - [`get_block_root`](#get_block_root) - - [`get_block_root_at_slot`](#get_block_root_at_slot) - - [`get_randao_mix`](#get_randao_mix) - - [`get_active_validator_indices`](#get_active_validator_indices) - - [`get_validator_churn_limit`](#get_validator_churn_limit) - - [`get_seed`](#get_seed) - - [`get_committee_count_at_slot`](#get_committee_count_at_slot) - - [`get_beacon_committee`](#get_beacon_committee) - - [`get_beacon_proposer_index`](#get_beacon_proposer_index) - - [`get_total_balance`](#get_total_balance) - - [`get_total_active_balance`](#get_total_active_balance) - - [`get_domain`](#get_domain) - - [`get_indexed_attestation`](#get_indexed_attestation) - - [`get_attesting_indices`](#get_attesting_indices) - - [Beacon state mutators](#beacon-state-mutators) - - [`increase_balance`](#increase_balance) - - [`decrease_balance`](#decrease_balance) - - [`initiate_validator_exit`](#initiate_validator_exit) - - [`slash_validator`](#slash_validator) - - [Genesis](#genesis) - - [Genesis state](#genesis-state) - - [Genesis block](#genesis-block) - - [Beacon chain state transition function](#beacon-chain-state-transition-function) - - [Epoch processing](#epoch-processing) - - [Helper functions](#helper-functions-1) - - [Justification and finalization](#justification-and-finalization) - - [Rewards and penalties](#rewards-and-penalties-1) - - [Registry updates](#registry-updates) - - [Slashings](#slashings) - - [Final updates](#final-updates) - - [Block processing](#block-processing) - - [Block header](#block-header) - - [RANDAO](#randao) - - [Eth1 data](#eth1-data) - - [Operations](#operations) - - [Proposer slashings](#proposer-slashings) - - [Attester slashings](#attester-slashings) - - [Attestations](#attestations) - - [Deposits](#deposits) - - [Voluntary exits](#voluntary-exits) +- [Introduction](#introduction) +- [Notation](#notation) +- [Custom types](#custom-types) +- [Constants](#constants) +- [Configuration](#configuration) + - [Misc](#misc) + - [Gwei values](#gwei-values) + - [Initial values](#initial-values) + - [Time parameters](#time-parameters) + - [State list lengths](#state-list-lengths) + - [Rewards and penalties](#rewards-and-penalties) + - [Max operations per block](#max-operations-per-block) + - [Domain types](#domain-types) +- [Containers](#containers) + - [Misc dependencies](#misc-dependencies) + - [`Fork`](#fork) + - [`Checkpoint`](#checkpoint) + - [`Validator`](#validator) + - [`AttestationData`](#attestationdata) + - [`IndexedAttestation`](#indexedattestation) + - [`PendingAttestation`](#pendingattestation) + - [`Eth1Data`](#eth1data) + - [`HistoricalBatch`](#historicalbatch) + - [`DepositMessage`](#depositmessage) + - [`DepositData`](#depositdata) + - [`BeaconBlockHeader`](#beaconblockheader) + - [Beacon operations](#beacon-operations) + - [`ProposerSlashing`](#proposerslashing) + - [`AttesterSlashing`](#attesterslashing) + - [`Attestation`](#attestation) + - [`Deposit`](#deposit) + - [`VoluntaryExit`](#voluntaryexit) + - [Beacon blocks](#beacon-blocks) + - [`BeaconBlockBody`](#beaconblockbody) + - [`BeaconBlock`](#beaconblock) + - [Beacon state](#beacon-state) + - [`BeaconState`](#beaconstate) + - [Signed envelopes](#signed-envelopes) + - [`SignedVoluntaryExit`](#signedvoluntaryexit) + - [`SignedBeaconBlock`](#signedbeaconblock) + - [`SignedBeaconBlockHeader`](#signedbeaconblockheader) +- [Helper functions](#helper-functions) + - [Math](#math) + - [`integer_squareroot`](#integer_squareroot) + - [`xor`](#xor) + - [`int_to_bytes`](#int_to_bytes) + - [`bytes_to_int`](#bytes_to_int) + - [Crypto](#crypto) + - [`hash`](#hash) + - [`hash_tree_root`](#hash_tree_root) + - [`bls_verify`](#bls_verify) + - [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys) + - [Predicates](#predicates) + - [`is_active_validator`](#is_active_validator) + - [`is_slashable_validator`](#is_slashable_validator) + - [`is_slashable_attestation_data`](#is_slashable_attestation_data) + - [`is_valid_indexed_attestation`](#is_valid_indexed_attestation) + - [`is_valid_merkle_branch`](#is_valid_merkle_branch) + - [Misc](#misc-1) + - [`compute_shuffled_index`](#compute_shuffled_index) + - [`compute_proposer_index`](#compute_proposer_index) + - [`compute_committee`](#compute_committee) + - [`compute_epoch_at_slot`](#compute_epoch_at_slot) + - [`compute_start_slot_at_epoch`](#compute_start_slot_at_epoch) + - [`compute_activation_exit_epoch`](#compute_activation_exit_epoch) + - [`compute_domain`](#compute_domain) + - [Beacon state accessors](#beacon-state-accessors) + - [`get_current_epoch`](#get_current_epoch) + - [`get_previous_epoch`](#get_previous_epoch) + - [`get_block_root`](#get_block_root) + - [`get_block_root_at_slot`](#get_block_root_at_slot) + - [`get_randao_mix`](#get_randao_mix) + - [`get_active_validator_indices`](#get_active_validator_indices) + - [`get_validator_churn_limit`](#get_validator_churn_limit) + - [`get_seed`](#get_seed) + - [`get_committee_count_at_slot`](#get_committee_count_at_slot) + - [`get_beacon_committee`](#get_beacon_committee) + - [`get_beacon_proposer_index`](#get_beacon_proposer_index) + - [`get_total_balance`](#get_total_balance) + - [`get_total_active_balance`](#get_total_active_balance) + - [`get_domain`](#get_domain) + - [`get_indexed_attestation`](#get_indexed_attestation) + - [`get_attesting_indices`](#get_attesting_indices) + - [Beacon state mutators](#beacon-state-mutators) + - [`increase_balance`](#increase_balance) + - [`decrease_balance`](#decrease_balance) + - [`initiate_validator_exit`](#initiate_validator_exit) + - [`slash_validator`](#slash_validator) +- [Genesis](#genesis) + - [Genesis state](#genesis-state) + - [Genesis block](#genesis-block) +- [Beacon chain state transition function](#beacon-chain-state-transition-function) + - [Epoch processing](#epoch-processing) + - [Helper functions](#helper-functions-1) + - [Justification and finalization](#justification-and-finalization) + - [Rewards and penalties](#rewards-and-penalties-1) + - [Registry updates](#registry-updates) + - [Slashings](#slashings) + - [Final updates](#final-updates) + - [Block processing](#block-processing) + - [Block header](#block-header) + - [RANDAO](#randao) + - [Eth1 data](#eth1-data) + - [Operations](#operations) + - [Proposer slashings](#proposer-slashings) + - [Attester slashings](#attester-slashings) + - [Attestations](#attestations) + - [Deposits](#deposits) + - [Voluntary exits](#voluntary-exits) + + ## Introduction diff --git a/specs/core/0_deposit-contract.md b/specs/core/0_deposit-contract.md index 06962594e..c9f366330 100644 --- a/specs/core/0_deposit-contract.md +++ b/specs/core/0_deposit-contract.md @@ -4,19 +4,21 @@ ## Table of contents + + -- [Ethereum 2.0 Phase 0 -- Deposit Contract](#ethereum-20-phase-0----deposit-contract) - - [Table of contents](#table-of-contents) - - [Introduction](#introduction) - - [Constants](#constants) - - [Contract](#contract) - - [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract) - - [`deposit` function](#deposit-function) - - [Deposit amount](#deposit-amount) - - [Withdrawal credentials](#withdrawal-credentials) - - [`DepositEvent` log](#depositevent-log) - - [Vyper code](#vyper-code) +- [Introduction](#introduction) +- [Constants](#constants) + - [Contract](#contract) +- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract) + - [`deposit` function](#deposit-function) + - [Deposit amount](#deposit-amount) + - [Withdrawal credentials](#withdrawal-credentials) + - [`DepositEvent` log](#depositevent-log) +- [Vyper code](#vyper-code) + + ## Introduction diff --git a/specs/core/0_fork-choice.md b/specs/core/0_fork-choice.md index 98f07e5f0..2191c24a2 100644 --- a/specs/core/0_fork-choice.md +++ b/specs/core/0_fork-choice.md @@ -4,29 +4,31 @@ ## Table of contents + + -- [Ethereum 2.0 Phase 0 -- Beacon Chain Fork Choice](#ethereum-20-phase-0----beacon-chain-fork-choice) - - [Table of contents](#table-of-contents) - - [Introduction](#introduction) - - [Fork choice](#fork-choice) - - [Helpers](#helpers) - - [`LatestMessage`](#latestmessage) - - [`Store`](#store) - - [`get_genesis_store`](#get_genesis_store) - - [`get_slots_since_genesis`](#get_slots_since_genesis) - - [`get_current_slot`](#get_current_slot) - - [`compute_slots_since_epoch_start`](#compute_slots_since_epoch_start) - - [`get_ancestor`](#get_ancestor) - - [`get_latest_attesting_balance`](#get_latest_attesting_balance) - - [`filter_block_tree`](#filter_block_tree) - - [`get_filtered_block_tree`](#get_filtered_block_tree) - - [`get_head`](#get_head) - - [`should_update_justified_checkpoint`](#should_update_justified_checkpoint) - - [Handlers](#handlers) - - [`on_tick`](#on_tick) - - [`on_block`](#on_block) - - [`on_attestation`](#on_attestation) +- [Introduction](#introduction) +- [Fork choice](#fork-choice) + - [Configuration](#configuration) + - [Helpers](#helpers) + - [`LatestMessage`](#latestmessage) + - [`Store`](#store) + - [`get_genesis_store`](#get_genesis_store) + - [`get_current_slot`](#get_current_slot) + - [`compute_slots_since_epoch_start`](#compute_slots_since_epoch_start) + - [`get_ancestor`](#get_ancestor) + - [`get_latest_attesting_balance`](#get_latest_attesting_balance) + - [`filter_block_tree`](#filter_block_tree) + - [`get_filtered_block_tree`](#get_filtered_block_tree) + - [`get_head`](#get_head) + - [`should_update_justified_checkpoint`](#should_update_justified_checkpoint) + - [Handlers](#handlers) + - [`on_tick`](#on_tick) + - [`on_block`](#on_block) + - [`on_attestation`](#on_attestation) + + ## Introduction diff --git a/specs/core/1_beacon-chain-misc.md b/specs/core/1_beacon-chain-misc.md index d99aca0ef..b27c72b34 100644 --- a/specs/core/1_beacon-chain-misc.md +++ b/specs/core/1_beacon-chain-misc.md @@ -3,29 +3,31 @@ ## Table of contents + + -- [Phase 1 miscellaneous beacon chain changes](#phase-1-miscellaneous-beacon-chain-changes) - - [Table of contents](#table-of-contents) - - [Configuration](#configuration) - - [Containers](#containers) - - [`CompactCommittee`](#compactcommittee) - - [`ShardReceiptDelta`](#shardreceiptdelta) - - [`ShardReceiptProof`](#shardreceiptproof) - - [Helper functions](#helper-functions) - - [`pack_compact_validator`](#pack_compact_validator) - - [`unpack_compact_validator`](#unpack_compact_validator) - - [`committee_to_compact_committee`](#committee_to_compact_committee) - - [`verify_merkle_proof`](#verify_merkle_proof) - - [`compute_historical_state_generalized_index`](#compute_historical_state_generalized_index) - - [`get_generalized_index_of_crosslink_header`](#get_generalized_index_of_crosslink_header) - - [`process_shard_receipt_proof`](#process_shard_receipt_proof) - - [Changes](#changes) - - [Phase 0 container updates](#phase-0-container-updates) - - [`BeaconState`](#beaconstate) - - [`BeaconBlockBody`](#beaconblockbody) - - [Persistent committees](#persistent-committees) - - [Shard receipt processing](#shard-receipt-processing) +- [Configuration](#configuration) +- [Containers](#containers) + - [`CompactCommittee`](#compactcommittee) + - [`ShardReceiptDelta`](#shardreceiptdelta) + - [`ShardReceiptProof`](#shardreceiptproof) +- [Helper functions](#helper-functions) + - [`pack_compact_validator`](#pack_compact_validator) + - [`unpack_compact_validator`](#unpack_compact_validator) + - [`committee_to_compact_committee`](#committee_to_compact_committee) + - [`verify_merkle_proof`](#verify_merkle_proof) + - [`compute_historical_state_generalized_index`](#compute_historical_state_generalized_index) + - [`get_generalized_index_of_crosslink_header`](#get_generalized_index_of_crosslink_header) + - [`process_shard_receipt_proof`](#process_shard_receipt_proof) +- [Changes](#changes) + - [Phase 0 container updates](#phase-0-container-updates) + - [`BeaconState`](#beaconstate) + - [`BeaconBlockBody`](#beaconblockbody) + - [Persistent committees](#persistent-committees) + - [Shard receipt processing](#shard-receipt-processing) + + ## Configuration diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index 946165bb7..7eb9e2526 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -5,54 +5,56 @@ ## Table of contents + + -- [Ethereum 2.0 Phase 1 -- Custody Game](#ethereum-20-phase-1----custody-game) - - [Table of contents](#table-of-contents) - - [Introduction](#introduction) - - [Terminology](#terminology) - - [Constants](#constants) - - [Misc](#misc) - - [Custody game parameters](#custody-game-parameters) - - [Time parameters](#time-parameters) - - [Max operations per block](#max-operations-per-block) - - [Reward and penalty quotients](#reward-and-penalty-quotients) - - [Signature domain types](#signature-domain-types) - - [TODO PLACEHOLDER](#todo-placeholder) - - [Data structures](#data-structures) - - [Custody objects](#custody-objects) - - [`CustodyChunkChallenge`](#custodychunkchallenge) - - [`CustodyBitChallenge`](#custodybitchallenge) - - [`CustodyChunkChallengeRecord`](#custodychunkchallengerecord) - - [`CustodyBitChallengeRecord`](#custodybitchallengerecord) - - [`CustodyResponse`](#custodyresponse) - - [New beacon operations](#new-beacon-operations) - - [`CustodyKeyReveal`](#custodykeyreveal) - - [`EarlyDerivedSecretReveal`](#earlyderivedsecretreveal) - - [Phase 0 container updates](#phase-0-container-updates) - - [`Validator`](#validator) - - [`BeaconState`](#beaconstate) - - [`BeaconBlockBody`](#beaconblockbody) - - [Helpers](#helpers) - - [`ceillog2`](#ceillog2) - - [`is_valid_merkle_branch_with_mixin`](#is_valid_merkle_branch_with_mixin) - - [`get_crosslink_chunk_count`](#get_crosslink_chunk_count) - - [`legendre_bit`](#legendre_bit) - - [`custody_subchunkify`](#custody_subchunkify) - - [`get_custody_chunk_bit`](#get_custody_chunk_bit) - - [`get_chunk_bits_root`](#get_chunk_bits_root) - - [`get_randao_epoch_for_custody_period`](#get_randao_epoch_for_custody_period) - - [`get_custody_period_for_validator`](#get_custody_period_for_validator) - - [`replace_empty_or_append`](#replace_empty_or_append) - - [Per-block processing](#per-block-processing) - - [Operations](#operations) - - [Custody key reveals](#custody-key-reveals) - - [Early derived secret reveals](#early-derived-secret-reveals) - - [Chunk challenges](#chunk-challenges) - - [Bit challenges](#bit-challenges) - - [Custody responses](#custody-responses) - - [Per-epoch processing](#per-epoch-processing) - - [Handling of custody-related deadlines](#handling-of-custody-related-deadlines) +- [Introduction](#introduction) +- [Terminology](#terminology) +- [Constants](#constants) + - [Misc](#misc) + - [Custody game parameters](#custody-game-parameters) + - [Time parameters](#time-parameters) + - [Max operations per block](#max-operations-per-block) + - [Reward and penalty quotients](#reward-and-penalty-quotients) + - [Signature domain types](#signature-domain-types) + - [TODO PLACEHOLDER](#todo-placeholder) +- [Data structures](#data-structures) + - [Custody objects](#custody-objects) + - [`CustodyChunkChallenge`](#custodychunkchallenge) + - [`CustodyBitChallenge`](#custodybitchallenge) + - [`CustodyChunkChallengeRecord`](#custodychunkchallengerecord) + - [`CustodyBitChallengeRecord`](#custodybitchallengerecord) + - [`CustodyResponse`](#custodyresponse) + - [New beacon operations](#new-beacon-operations) + - [`CustodyKeyReveal`](#custodykeyreveal) + - [`EarlyDerivedSecretReveal`](#earlyderivedsecretreveal) + - [Phase 0 container updates](#phase-0-container-updates) + - [`Validator`](#validator) + - [`BeaconState`](#beaconstate) + - [`BeaconBlockBody`](#beaconblockbody) +- [Helpers](#helpers) + - [`ceillog2`](#ceillog2) + - [`is_valid_merkle_branch_with_mixin`](#is_valid_merkle_branch_with_mixin) + - [`get_crosslink_chunk_count`](#get_crosslink_chunk_count) + - [`legendre_bit`](#legendre_bit) + - [`custody_subchunkify`](#custody_subchunkify) + - [`get_custody_chunk_bit`](#get_custody_chunk_bit) + - [`get_chunk_bits_root`](#get_chunk_bits_root) + - [`get_randao_epoch_for_custody_period`](#get_randao_epoch_for_custody_period) + - [`get_custody_period_for_validator`](#get_custody_period_for_validator) + - [`replace_empty_or_append`](#replace_empty_or_append) +- [Per-block processing](#per-block-processing) + - [Operations](#operations) + - [Custody key reveals](#custody-key-reveals) + - [Early derived secret reveals](#early-derived-secret-reveals) + - [Chunk challenges](#chunk-challenges) + - [Bit challenges](#bit-challenges) + - [Custody responses](#custody-responses) +- [Per-epoch processing](#per-epoch-processing) + - [Handling of custody-related deadlines](#handling-of-custody-related-deadlines) + + ## Introduction diff --git a/specs/core/1_shard-data-chains.md b/specs/core/1_shard-data-chains.md index 6fce90626..d5964fe7d 100644 --- a/specs/core/1_shard-data-chains.md +++ b/specs/core/1_shard-data-chains.md @@ -5,45 +5,47 @@ ## Table of contents + + -- [Ethereum 2.0 Phase 1 -- Shard Data Chains](#ethereum-20-phase-1----shard-data-chains) - - [Table of contents](#table-of-contents) - - [Introduction](#introduction) - - [Custom types](#custom-types) - - [Configuration](#configuration) - - [Misc](#misc) - - [Initial values](#initial-values) - - [Time parameters](#time-parameters) - - [State list lengths](#state-list-lengths) - - [Rewards and penalties](#rewards-and-penalties) - - [Signature domain types](#signature-domain-types) - - [Containers](#containers) - - [`Crosslink`](#crosslink) - - [`ShardBlock`](#shardblock) - - [`ShardBlockHeader`](#shardblockheader) - - [`ShardState`](#shardstate) - - [`ShardAttestationData`](#shardattestationdata) - - [Helper functions](#helper-functions) - - [Misc](#misc-1) - - [`compute_epoch_of_shard_slot`](#compute_epoch_of_shard_slot) - - [`compute_shard_period_start_epoch`](#compute_shard_period_start_epoch) - - [Beacon state accessors](#beacon-state-accessors) - - [`get_period_committee`](#get_period_committee) - - [`get_shard_committee`](#get_shard_committee) - - [`get_shard_proposer_index`](#get_shard_proposer_index) - - [Shard state mutators](#shard-state-mutators) - - [`process_delta`](#process_delta) - - [Genesis](#genesis) - - [`get_genesis_shard_state`](#get_genesis_shard_state) - - [`get_genesis_shard_block`](#get_genesis_shard_block) - - [Shard state transition function](#shard-state-transition-function) - - [Period processing](#period-processing) - - [Block processing](#block-processing) - - [Block header](#block-header) - - [Attestations](#attestations) - - [Block body](#block-body) - - [Shard fork choice rule](#shard-fork-choice-rule) +- [Introduction](#introduction) +- [Custom types](#custom-types) +- [Configuration](#configuration) + - [Misc](#misc) + - [Initial values](#initial-values) + - [Time parameters](#time-parameters) + - [State list lengths](#state-list-lengths) + - [Rewards and penalties](#rewards-and-penalties) + - [Signature domain types](#signature-domain-types) +- [Containers](#containers) + - [`Crosslink`](#crosslink) + - [`ShardBlock`](#shardblock) + - [`ShardBlockHeader`](#shardblockheader) + - [`ShardState`](#shardstate) + - [`ShardAttestationData`](#shardattestationdata) +- [Helper functions](#helper-functions) + - [Misc](#misc-1) + - [`compute_epoch_of_shard_slot`](#compute_epoch_of_shard_slot) + - [`compute_shard_period_start_epoch`](#compute_shard_period_start_epoch) + - [Beacon state accessors](#beacon-state-accessors) + - [`get_period_committee`](#get_period_committee) + - [`get_shard_committee`](#get_shard_committee) + - [`get_shard_proposer_index`](#get_shard_proposer_index) + - [Shard state mutators](#shard-state-mutators) + - [`process_delta`](#process_delta) +- [Genesis](#genesis) + - [`get_genesis_shard_state`](#get_genesis_shard_state) + - [`get_genesis_shard_block`](#get_genesis_shard_block) +- [Shard state transition function](#shard-state-transition-function) + - [Period processing](#period-processing) + - [Block processing](#block-processing) + - [Block header](#block-header) + - [Attestations](#attestations) + - [Block body](#block-body) +- [Shard fork choice rule](#shard-fork-choice-rule) + + ## Introduction diff --git a/specs/light_client/merkle_proofs.md b/specs/light_client/merkle_proofs.md index c89235cb5..3e176f2aa 100644 --- a/specs/light_client/merkle_proofs.md +++ b/specs/light_client/merkle_proofs.md @@ -4,21 +4,23 @@ ## Table of contents + + -- [Merkle proof formats](#merkle-proof-formats) - - [Table of contents](#table-of-contents) - - [Helper functions](#helper-functions) - - [Generalized Merkle tree index](#generalized-merkle-tree-index) - - [SSZ object to index](#ssz-object-to-index) - - [Helpers for generalized indices](#helpers-for-generalized-indices) - - [`concat_generalized_indices`](#concat_generalized_indices) - - [`get_generalized_index_length`](#get_generalized_index_length) - - [`get_generalized_index_bit`](#get_generalized_index_bit) - - [`generalized_index_sibling`](#generalized_index_sibling) - - [`generalized_index_child`](#generalized_index_child) - - [`generalized_index_parent`](#generalized_index_parent) - - [Merkle multiproofs](#merkle-multiproofs) +- [Helper functions](#helper-functions) +- [Generalized Merkle tree index](#generalized-merkle-tree-index) +- [SSZ object to index](#ssz-object-to-index) + - [Helpers for generalized indices](#helpers-for-generalized-indices) + - [`concat_generalized_indices`](#concat_generalized_indices) + - [`get_generalized_index_length`](#get_generalized_index_length) + - [`get_generalized_index_bit`](#get_generalized_index_bit) + - [`generalized_index_sibling`](#generalized_index_sibling) + - [`generalized_index_child`](#generalized_index_child) + - [`generalized_index_parent`](#generalized_index_parent) +- [Merkle multiproofs](#merkle-multiproofs) + + ## Helper functions diff --git a/specs/light_client/sync_protocol.md b/specs/light_client/sync_protocol.md index 00edb990d..05180516b 100644 --- a/specs/light_client/sync_protocol.md +++ b/specs/light_client/sync_protocol.md @@ -5,20 +5,22 @@ ## Table of contents + + -- [Minimal Light Client Design](#minimal-light-client-design) - - [Table of contents](#table-of-contents) - - [Introduction](#introduction) - - [Custom types](#custom-types) - - [Constants](#constants) - - [Containers](#containers) - - [`LightClientUpdate`](#lightclientupdate) - - [Helpers](#helpers) - - [`LightClientMemory`](#lightclientmemory) - - [`get_persistent_committee_pubkeys_and_balances`](#get_persistent_committee_pubkeys_and_balances) - - [Light client state updates](#light-client-state-updates) - - [Data overhead](#data-overhead) +- [Introduction](#introduction) +- [Custom types](#custom-types) +- [Constants](#constants) +- [Containers](#containers) + - [`LightClientUpdate`](#lightclientupdate) +- [Helpers](#helpers) + - [`LightClientMemory`](#lightclientmemory) + - [`get_persistent_committee_pubkeys_and_balances`](#get_persistent_committee_pubkeys_and_balances) +- [Light client state updates](#light-client-state-updates) +- [Data overhead](#data-overhead) + + ## Introduction diff --git a/specs/networking/p2p-interface.md b/specs/networking/p2p-interface.md index 414dc8cde..dfddbb3f7 100644 --- a/specs/networking/p2p-interface.md +++ b/specs/networking/p2p-interface.md @@ -18,23 +18,88 @@ It consists of four main sections: - [Network fundamentals](#network-fundamentals) - [Transport](#transport) + - [Interop](#interop) + - [Mainnet](#mainnet) - [Encryption and identification](#encryption-and-identification) - - [Protocol negotiation](#protocol-negotiation) + - [Interop](#interop-1) + - [Mainnet](#mainnet-1) + - [Protocol Negotiation](#protocol-negotiation) + - [Interop](#interop-2) + - [Mainnet](#mainnet-2) - [Multiplexing](#multiplexing) - [Eth2 network interaction domains](#eth2-network-interaction-domains) - [Configuration](#configuration) - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) + - [Topics and messages](#topics-and-messages) + - [Global topics](#global-topics) + - [Attestation subnets](#attestation-subnets) + - [Interop](#interop-3) + - [Mainnet](#mainnet-3) + - [Encodings](#encodings) + - [Interop](#interop-4) + - [Mainnet](#mainnet-4) - [The Req/Resp domain](#the-reqresp-domain) + - [Protocol identification](#protocol-identification) + - [Req/Resp interaction](#reqresp-interaction) + - [Requesting side](#requesting-side) + - [Responding side](#responding-side) + - [Encoding strategies](#encoding-strategies) + - [SSZ-encoding strategy (with or without Snappy)](#ssz-encoding-strategy-with-or-without-snappy) + - [Messages](#messages) + - [Status](#status) + - [Goodbye](#goodbye) + - [BeaconBlocksByRange](#beaconblocksbyrange) + - [BeaconBlocksByRoot](#beaconblocksbyroot) - [The discovery domain: discv5](#the-discovery-domain-discv5) + - [Integration into libp2p stacks](#integration-into-libp2p-stacks) + - [ENR structure](#enr-structure) + - [Interop](#interop-5) + - [Mainnet](#mainnet-5) + - [Topic advertisement](#topic-advertisement) + - [Interop](#interop-6) + - [Mainnet](#mainnet-6) - [Design decision rationale](#design-decision-rationale) - [Transport](#transport-1) + - [Why are we defining specific transports?](#why-are-we-defining-specific-transports) + - [Can clients support other transports/handshakes than the ones mandated by the spec?](#can-clients-support-other-transportshandshakes-than-the-ones-mandated-by-the-spec) + - [What are the advantages of using TCP/QUIC/Websockets?](#what-are-the-advantages-of-using-tcpquicwebsockets) + - [Why do we not just support a single transport?](#why-do-we-not-just-support-a-single-transport) + - [Why are we not using QUIC for mainnet from the start?](#why-are-we-not-using-quic-for-mainnet-from-the-start) - [Multiplexing](#multiplexing-1) - - [Protocol negotiation](#protocol-negotiation-1) + - [Why are we using mplex/yamux?](#why-are-we-using-mplexyamux) + - [Protocol Negotiation](#protocol-negotiation-1) + - [When is multiselect 2.0 due and why are we using it for mainnet?](#when-is-multiselect-20-due-and-why-are-we-using-it-for-mainnet) + - [What is the difference between connection-level and stream-level protocol negotiation?](#what-is-the-difference-between-connection-level-and-stream-level-protocol-negotiation) - [Encryption](#encryption) + - [Why are we using SecIO for interop? Why not for mainnet?](#why-are-we-using-secio-for-interop-why-not-for-mainnet) + - [Why are we using Noise/TLS 1.3 for mainnet?](#why-are-we-using-noisetls-13-for-mainnet) + - [Why are we using encryption at all?](#why-are-we-using-encryption-at-all) + - [Will mainnnet networking be untested when it launches?](#will-mainnnet-networking-be-untested-when-it-launches) - [Gossipsub](#gossipsub) + - [Why are we using a pub/sub algorithm for block and attestation propagation?](#why-are-we-using-a-pubsub-algorithm-for-block-and-attestation-propagation) + - [Why are we using topics to segregate encodings, yet only support one encoding?](#why-are-we-using-topics-to-segregate-encodings-yet-only-support-one-encoding) + - [How do we upgrade gossip channels (e.g. changes in encoding, compression)?](#how-do-we-upgrade-gossip-channels-eg-changes-in-encoding-compression) + - [Why must all clients use the same gossip topic instead of one negotiated between each peer pair?](#why-must-all-clients-use-the-same-gossip-topic-instead-of-one-negotiated-between-each-peer-pair) + - [Why are the topics strings and not hashes?](#why-are-the-topics-strings-and-not-hashes) + - [Why are there `ATTESTATION_SUBNET_COUNT` attestation subnets?](#why-are-there-attestation_subnet_count-attestation-subnets) + - [Why are attestations limited to be broadcast on gossip channels within `SLOTS_PER_EPOCH` slots?](#why-are-attestations-limited-to-be-broadcast-on-gossip-channels-within-slots_per_epoch-slots) + - [Why are aggregate attestations broadcast to the global topic as `AggregateAndProof`s rather than just as `Attestation`s?](#why-are-aggregate-attestations-broadcast-to-the-global-topic-as-aggregateandproofs-rather-than-just-as-attestations) + - [Why are we sending entire objects in the pubsub and not just hashes?](#why-are-we-sending-entire-objects-in-the-pubsub-and-not-just-hashes) + - [Should clients gossip blocks if they *cannot* validate the proposer signature due to not yet being synced, not knowing the head block, etc?](#should-clients-gossip-blocks-if-they-cannot-validate-the-proposer-signature-due-to-not-yet-being-synced-not-knowing-the-head-block-etc) + - [How are we going to discover peers in a gossipsub topic?](#how-are-we-going-to-discover-peers-in-a-gossipsub-topic) - [Req/Resp](#reqresp) + - [Why segregate requests into dedicated protocol IDs?](#why-segregate-requests-into-dedicated-protocol-ids) + - [Why are messages length-prefixed with a protobuf varint in the SSZ-encoding?](#why-are-messages-length-prefixed-with-a-protobuf-varint-in-the-ssz-encoding) + - [Why do we version protocol strings with ordinals instead of semver?](#why-do-we-version-protocol-strings-with-ordinals-instead-of-semver) + - [Why is it called Req/Resp and not RPC?](#why-is-it-called-reqresp-and-not-rpc) - [Discovery](#discovery) + - [Why are we using discv5 and not libp2p Kademlia DHT?](#why-are-we-using-discv5-and-not-libp2p-kademlia-dht) + - [What is the difference between an ENR and a multiaddr, and why are we using ENRs?](#what-is-the-difference-between-an-enr-and-a-multiaddr-and-why-are-we-using-enrs) - [Compression/Encoding](#compressionencoding) + - [Why are we using SSZ for encoding?](#why-are-we-using-ssz-for-encoding) + - [Why are we compressing, and at which layers?](#why-are-we-compressing-and-at-which-layers) + - [Why are using Snappy for compression?](#why-are-using-snappy-for-compression) + - [Can I get access to unencrypted bytes on the wire for debugging purposes?](#can-i-get-access-to-unencrypted-bytes-on-the-wire-for-debugging-purposes) - [libp2p implementations matrix](#libp2p-implementations-matrix) @@ -567,7 +632,7 @@ Conscious of that, the libp2p community conceptualized [mplex](https://github.co Overlay multiplexers are not necessary with QUIC since the protocol provides native multiplexing, but they need to be layered atop TCP, WebSockets, and other transports that lack such support. -## Protocol negotiation +## Protocol Negotiation ### When is multiselect 2.0 due and why are we using it for mainnet? diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md index 556c31b27..860a27f01 100644 --- a/specs/simple-serialize.md +++ b/specs/simple-serialize.md @@ -4,30 +4,32 @@ ## Table of contents + + -- [SimpleSerialize (SSZ)](#simpleserialize-ssz) - - [Table of contents](#table-of-contents) - - [Constants](#constants) - - [Typing](#typing) - - [Basic types](#basic-types) - - [Composite types](#composite-types) - - [Variable-size and fixed-size](#variable-size-and-fixed-size) - - [Aliases](#aliases) - - [Default values](#default-values) - - [`is_zero`](#is_zero) - - [Illegal types](#illegal-types) - - [Serialization](#serialization) - - [`uintN`](#uintn) - - [`boolean`](#boolean) - - [`null`](#null) - - [`Bitvector[N]`](#bitvectorn) - - [`Bitlist[N]`](#bitlistn) - - [Vectors, containers, lists, unions](#vectors-containers-lists-unions) - - [Deserialization](#deserialization) - - [Merkleization](#merkleization) - - [Summaries and expansions](#summaries-and-expansions) - - [Implementations](#implementations) +- [Constants](#constants) +- [Typing](#typing) + - [Basic types](#basic-types) + - [Composite types](#composite-types) + - [Variable-size and fixed-size](#variable-size-and-fixed-size) + - [Aliases](#aliases) + - [Default values](#default-values) + - [`is_zero`](#is_zero) + - [Illegal types](#illegal-types) +- [Serialization](#serialization) + - [`uintN`](#uintn) + - [`boolean`](#boolean) + - [`null`](#null) + - [`Bitvector[N]`](#bitvectorn) + - [`Bitlist[N]`](#bitlistn) + - [Vectors, containers, lists, unions](#vectors-containers-lists-unions) +- [Deserialization](#deserialization) +- [Merkleization](#merkleization) +- [Summaries and expansions](#summaries-and-expansions) +- [Implementations](#implementations) + + ## Constants diff --git a/specs/validator/0_beacon-chain-validator.md b/specs/validator/0_beacon-chain-validator.md index 3b90350e3..76bcc3b7d 100644 --- a/specs/validator/0_beacon-chain-validator.md +++ b/specs/validator/0_beacon-chain-validator.md @@ -5,61 +5,64 @@ ## Table of contents + + -- [Ethereum 2.0 Phase 0 -- Honest Validator](#ethereum-20-phase-0----honest-validator) - - [Table of contents](#table-of-contents) - - [Introduction](#introduction) - - [Prerequisites](#prerequisites) - - [Constants](#constants) - - [Misc](#misc) - - [Becoming a validator](#becoming-a-validator) - - [Initialization](#initialization) - - [BLS public key](#bls-public-key) - - [BLS withdrawal key](#bls-withdrawal-key) - - [Submit deposit](#submit-deposit) - - [Process deposit](#process-deposit) - - [Validator index](#validator-index) - - [Activation](#activation) - - [Validator assignments](#validator-assignments) - - [Lookahead](#lookahead) - - [Beacon chain responsibilities](#beacon-chain-responsibilities) - - [Block proposal](#block-proposal) - - [Block header](#block-header) - - [Slot](#slot) - - [Parent root](#parent-root) - - [State root](#state-root) - - [Randao reveal](#randao-reveal) - - [Eth1 Data](#eth1-data) - - [Signature](#signature) - - [Block body](#block-body) - - [Proposer slashings](#proposer-slashings) - - [Attester slashings](#attester-slashings) - - [Attestations](#attestations) - - [Deposits](#deposits) - - [Voluntary exits](#voluntary-exits) - - [Attesting](#attesting) - - [Attestation data](#attestation-data) - - [General](#general) - - [LMD GHOST vote](#lmd-ghost-vote) - - [FFG vote](#ffg-vote) - - [Construct attestation](#construct-attestation) - - [Data](#data) - - [Aggregation bits](#aggregation-bits) - - [Aggregate signature](#aggregate-signature) - - [Broadcast attestation](#broadcast-attestation) - - [Attestation aggregation](#attestation-aggregation) - - [Aggregation selection](#aggregation-selection) - - [Construct aggregate](#construct-aggregate) - - [Data](#data-1) - - [Aggregation bits](#aggregation-bits-1) - - [Aggregate signature](#aggregate-signature-1) - - [Broadcast aggregate](#broadcast-aggregate) - - [`AggregateAndProof`](#aggregateandproof) - - [Phase 0 attestation subnet stability](#phase-0-attestation-subnet-stability) - - [How to avoid slashing](#how-to-avoid-slashing) - - [Proposer slashing](#proposer-slashing) - - [Attester slashing](#attester-slashing) +- [Introduction](#introduction) +- [Prerequisites](#prerequisites) +- [Constants](#constants) + - [Misc](#misc) +- [Becoming a validator](#becoming-a-validator) + - [Initialization](#initialization) + - [BLS public key](#bls-public-key) + - [BLS withdrawal key](#bls-withdrawal-key) + - [Submit deposit](#submit-deposit) + - [Process deposit](#process-deposit) + - [Validator index](#validator-index) + - [Activation](#activation) +- [Validator assignments](#validator-assignments) + - [Lookahead](#lookahead) +- [Beacon chain responsibilities](#beacon-chain-responsibilities) + - [Block proposal](#block-proposal) + - [Preparing for a `BeaconBlock`](#preparing-for-a-beaconblock) + - [Slot](#slot) + - [Parent root](#parent-root) + - [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody) + - [Randao reveal](#randao-reveal) + - [Eth1 Data](#eth1-data) + - [Proposer slashings](#proposer-slashings) + - [Attester slashings](#attester-slashings) + - [Attestations](#attestations) + - [Deposits](#deposits) + - [Voluntary exits](#voluntary-exits) + - [Packaging into a `SignedBeaconBlock`](#packaging-into-a-signedbeaconblock) + - [State root](#state-root) + - [Signature](#signature) + - [Attesting](#attesting) + - [Attestation data](#attestation-data) + - [General](#general) + - [LMD GHOST vote](#lmd-ghost-vote) + - [FFG vote](#ffg-vote) + - [Construct attestation](#construct-attestation) + - [Data](#data) + - [Aggregation bits](#aggregation-bits) + - [Aggregate signature](#aggregate-signature) + - [Broadcast attestation](#broadcast-attestation) + - [Attestation aggregation](#attestation-aggregation) + - [Aggregation selection](#aggregation-selection) + - [Construct aggregate](#construct-aggregate) + - [Data](#data-1) + - [Aggregation bits](#aggregation-bits-1) + - [Aggregate signature](#aggregate-signature-1) + - [Broadcast aggregate](#broadcast-aggregate) + - [`AggregateAndProof`](#aggregateandproof) +- [Phase 0 attestation subnet stability](#phase-0-attestation-subnet-stability) +- [How to avoid slashing](#how-to-avoid-slashing) + - [Proposer slashing](#proposer-slashing) + - [Attester slashing](#attester-slashing) + + ## Introduction