diff --git a/README.md b/README.md
index f3aba3f64..c5c88daf9 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ 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)
+* [Honest validator implementation doc](specs/validator/0_beacon-chain-validator.md)
## Design goals
The following are the broad design goals for Ethereum 2.0:
diff --git a/specs/bls_signature.md b/specs/bls_signature.md
index 4dd479a6a..fd9bae58e 100644
--- a/specs/bls_signature.md
+++ b/specs/bls_signature.md
@@ -86,19 +86,23 @@ def hash_to_G2(message: bytes32, domain: uint64) -> [uint384]:
### `modular_squareroot`
-`modular_squareroot(x)` returns a solution `y` to `y**2 % q == x`, and `None` if none exists. If there are two solutions the one with higher imaginary component is favored; if both solutions have equal imaginary component the one with higher real component is favored.
+`modular_squareroot(x)` returns a solution `y` to `y**2 % q == x`, and `None` if none exists. If there are two solutions the one with higher imaginary component is favored; if both solutions have equal imaginary component the one with higher real component is favored (note that this is equivalent to saying that the single solution with either imaginary component > p/2 or imaginary component zero and real component > p/2 is favored).
+
+The following is a sample implementation; implementers are free to implement modular square roots as they wish. Note that `x2 = -x1` is an _additive modular inverse_ so real and imaginary coefficients remain in `[0 .. q-1]`. `coerce_to_int(element: Fq) -> int` is a function that takes Fq element `element` (ie. integers `mod q`) and converts it to a regular integer.
```python
Fq2_order = q ** 2 - 1
eighth_roots_of_unity = [Fq2([1,1]) ** ((Fq2_order * k) // 8) for k in range(8)]
-def modular_squareroot(value: int) -> int:
+def modular_squareroot(value: Fq2) -> Fq2:
candidate_squareroot = value ** ((Fq2_order + 8) // 16)
check = candidate_squareroot ** 2 / value
if check in eighth_roots_of_unity[::2]:
x1 = candidate_squareroot / eighth_roots_of_unity[eighth_roots_of_unity.index(check) // 2]
x2 = -x1
- return x1 if (x1.coeffs[1].n, x1.coeffs[0].n) > (x2.coeffs[1].n, x2.coeffs[0].n) else x2
+ x1_re, x1_im = coerce_to_int(x1.coeffs[0]), coerce_to_int(x1.coeffs[1])
+ x2_re, x2_im = coerce_to_int(x2.coeffs[0]), coerce_to_int(x2.coeffs[1])
+ return x1 if (x1_im > x2_im or (x1_im == x2_im and x1_re > x2_re)) else x2
return None
```
diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md
index 370b2c2bd..2827639af 100644
--- a/specs/core/0_beacon-chain.md
+++ b/specs/core/0_beacon-chain.md
@@ -15,18 +15,18 @@
- [Deposit contract](#deposit-contract)
- [Initial values](#initial-values)
- [Time parameters](#time-parameters)
+ - [State list lengths](#state-list-lengths)
- [Reward and penalty quotients](#reward-and-penalty-quotients)
- [Status flags](#status-flags)
- [Max operations per block](#max-operations-per-block)
- - [Validator registry delta flags](#validator-registry-delta-flags)
- [Signature domains](#signature-domains)
- [Data structures](#data-structures)
- [Beacon chain operations](#beacon-chain-operations)
- [Proposer slashings](#proposer-slashings)
- [`ProposerSlashing`](#proposerslashing)
- - [Casper slashings](#casper-slashings)
- - [`CasperSlashing`](#casperslashing)
- - [`SlashableVoteData`](#slashablevotedata)
+ - [Attester slashings](#attester-slashings)
+ - [`AttesterSlashing`](#attesterslashing)
+ - [`SlashableAttestation`](#slashableattestation)
- [Attestations](#attestations)
- [`Attestation`](#attestation)
- [`AttestationData`](#attestationdata)
@@ -47,77 +47,90 @@
- [`Crosslink`](#crosslink)
- [`PendingAttestation`](#pendingattestation)
- [`Fork`](#fork)
- - [`ValidatorRegistryDeltaBlock`](#validatorregistrydeltablock)
- [`Eth1Data`](#eth1data)
- [`Eth1DataVote`](#eth1datavote)
+ - [Custom Types](#custom-types)
+ - [Helper functions](#helper-functions)
+ - [`hash`](#hash)
+ - [`hash_tree_root`](#hash_tree_root)
+ - [`slot_to_epoch`](#slot_to_epoch)
+ - [`get_current_epoch`](#get_current_epoch)
+ - [`get_epoch_start_slot`](#get_epoch_start_slot)
+ - [`is_active_validator`](#is_active_validator)
+ - [`get_active_validator_indices`](#get_active_validator_indices)
+ - [`shuffle`](#shuffle)
+ - [`split`](#split)
+ - [`get_epoch_committee_count`](#get_epoch_committee_count)
+ - [`get_shuffling`](#get_shuffling)
+ - [`get_previous_epoch_committee_count`](#get_previous_epoch_committee_count)
+ - [`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_randao_mix`](#get_randao_mix)
+ - [`get_active_index_root`](#get_active_index_root)
+ - [`generate_seed`](#generate_seed)
+ - [`get_beacon_proposer_index`](#get_beacon_proposer_index)
+ - [`merkle_root`](#merkle_root)
+ - [`get_attestation_participants`](#get_attestation_participants)
+ - [`int_to_bytes1`, `int_to_bytes2`, ...](#int_to_bytes1-int_to_bytes2-)
+ - [`get_effective_balance`](#get_effective_balance)
+ - [`get_fork_version`](#get_fork_version)
+ - [`get_domain`](#get_domain)
+ - [`get_bitfield_bit`](#get_bitfield_bit)
+ - [`verify_bitfield`](#verify_bitfield)
+ - [`verify_slashable_attestation`](#verify_slashable_attestation)
+ - [`is_double_vote`](#is_double_vote)
+ - [`is_surround_vote`](#is_surround_vote)
+ - [`integer_squareroot`](#integer_squareroot)
+ - [`get_entry_exit_effect_epoch`](#get_entry_exit_effect_epoch)
+ - [`bls_verify`](#bls_verify)
+ - [`bls_verify_multiple`](#bls_verify_multiple)
+ - [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys)
+ - [`validate_proof_of_possession`](#validate_proof_of_possession)
+ - [`process_deposit`](#process_deposit)
+ - [Routines for updating validator status](#routines-for-updating-validator-status)
+ - [`activate_validator`](#activate_validator)
+ - [`initiate_validator_exit`](#initiate_validator_exit)
+ - [`exit_validator`](#exit_validator)
+ - [`penalize_validator`](#penalize_validator)
+ - [`prepare_validator_for_withdrawal`](#prepare_validator_for_withdrawal)
- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract)
- [Deposit arguments](#deposit-arguments)
- [Withdrawal credentials](#withdrawal-credentials)
- [`Deposit` logs](#deposit-logs)
- [`ChainStart` log](#chainstart-log)
- [Vyper code](#vyper-code)
+ - [On startup](#on-startup)
- [Beacon chain processing](#beacon-chain-processing)
- [Beacon chain fork choice rule](#beacon-chain-fork-choice-rule)
- [Beacon chain state transition function](#beacon-chain-state-transition-function)
- - [Helper functions](#helper-functions)
- - [`hash`](#hash)
- - [`hash_tree_root`](#hash_tree_root)
- - [`is_active_validator`](#is_active_validator)
- - [`get_active_validator_indices`](#get_active_validator_indices)
- - [`shuffle`](#shuffle)
- - [`split`](#split)
- - [`get_committee_count_per_slot`](#get_committee_count_per_slot)
- - [`get_shuffling`](#get_shuffling)
- - [`get_previous_epoch_committee_count_per_slot`](#get_previous_epoch_committee_count_per_slot)
- - [`get_current_epoch_committee_count_per_slot`](#get_current_epoch_committee_count_per_slot)
- - [`get_crosslink_committees_at_slot`](#get_crosslink_committees_at_slot)
- - [`get_block_root`](#get_block_root)
- - [`get_randao_mix`](#get_randao_mix)
- - [`get_beacon_proposer_index`](#get_beacon_proposer_index)
- - [`merkle_root`](#merkle_root)
- - [`get_attestation_participants`](#get_attestation_participants)
- - [`int_to_bytes1`, `int_to_bytes2`, ...](#int_to_bytes1-int_to_bytes2-)
- - [`get_effective_balance`](#get_effective_balance)
- - [`get_fork_version`](#get_fork_version)
- - [`get_domain`](#get_domain)
- - [`verify_slashable_vote_data`](#verify_slashable_vote_data)
- - [`is_double_vote`](#is_double_vote)
- - [`is_surround_vote`](#is_surround_vote)
- - [`integer_squareroot`](#integer_squareroot)
- - [`bls_verify`](#bls_verify)
- - [`bls_verify_multiple`](#bls_verify_multiple)
- - [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys)
- - [On startup](#on-startup)
- - [Routine for processing deposits](#routine-for-processing-deposits)
- - [Routines for updating validator status](#routines-for-updating-validator-status)
- - [Per-slot processing](#per-slot-processing)
- - [Misc counters](#misc-counters)
- - [Block roots](#block-roots)
- - [Per-block processing](#per-block-processing)
- - [Slot](#slot)
- - [Proposer signature](#proposer-signature)
- - [RANDAO](#randao)
- - [Eth1 data](#eth1-data)
- - [Operations](#operations)
- - [Proposer slashings](#proposer-slashings-1)
- - [Casper slashings](#casper-slashings-1)
- - [Attestations](#attestations-1)
- - [Deposits](#deposits-1)
- - [Exits](#exits-1)
- - [Custody](#custody)
- - [Per-epoch processing](#per-epoch-processing)
- - [Helpers](#helpers)
- - [Eth1 data](#eth1-data-1)
- - [Justification](#justification)
- - [Crosslinks](#crosslinks)
- - [Rewards and penalties](#rewards-and-penalties)
- - [Justification and finalization](#justification-and-finalization)
- - [Attestation inclusion](#attestation-inclusion)
- - [Crosslinks](#crosslinks-1)
- - [Ejections](#ejections)
- - [Validator registry](#validator-registry)
- - [Final updates](#final-updates)
- - [State root processing](#state-root-processing)
+ - [Per-slot processing](#per-slot-processing)
+ - [Slot](#slot)
+ - [Block roots](#block-roots)
+ - [Per-block processing](#per-block-processing)
+ - [Slot](#slot-1)
+ - [Proposer signature](#proposer-signature)
+ - [RANDAO](#randao)
+ - [Eth1 data](#eth1-data)
+ - [Operations](#operations)
+ - [Proposer slashings](#proposer-slashings-1)
+ - [Attester slashings](#attester-slashings-1)
+ - [Attestations](#attestations-1)
+ - [Deposits](#deposits-1)
+ - [Exits](#exits-1)
+ - [Per-epoch processing](#per-epoch-processing)
+ - [Helpers](#helpers)
+ - [Eth1 data](#eth1-data-1)
+ - [Justification](#justification)
+ - [Crosslinks](#crosslinks)
+ - [Rewards and penalties](#rewards-and-penalties)
+ - [Justification and finalization](#justification-and-finalization)
+ - [Attestation inclusion](#attestation-inclusion)
+ - [Crosslinks](#crosslinks-1)
+ - [Ejections](#ejections)
+ - [Validator registry and shuffling seed data](#validator-registry-and-shuffling-seed-data)
+ - [Final updates](#final-updates)
+ - [State root verification](#state-root-verification)
- [References](#references)
- [Normative](#normative)
- [Informative](#informative)
@@ -139,8 +152,8 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
## Terminology
-* **Validator** - a participant in the Casper/sharding consensus system. You can become one by depositing 32 ETH into the Casper mechanism.
-* **Active validator** - a [validator](#dfn-validator) currently participating in the protocol which the Casper mechanism looks to produce and attest to blocks, crosslinks and other consensus objects.
+* **Validator** - a registered participant in the beacon chain. You can become one by sending Ether into the Ethereum 1.0 deposit contract.
+* **Active validator** - an active participant in the Ethereum 2.0 consensus invited to, among other things, propose and attest to blocks and vote for crosslinks.
* **Committee** - a (pseudo-) randomly sampled subset of [active validators](#dfn-active-validator). When a committee is referred to collectively, as in "this committee attests to X", this is assumed to mean "some subset of that committee that contains enough [validators](#dfn-validator) that the protocol recognizes it as representing the committee".
* **Proposer** - the [validator](#dfn-validator) that creates a beacon chain block
* **Attester** - a [validator](#dfn-validator) that is part of a committee that needs to sign off on a beacon chain block while simultaneously creating a link (crosslink) to a recent shard block on a particular shard chain.
@@ -165,10 +178,7 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
| `EJECTION_BALANCE` | `2**4 * 1e9` (= 16,000,000,000) | Gwei |
| `MAX_BALANCE_CHURN_QUOTIENT` | `2**5` (= 32) | - |
| `BEACON_CHAIN_SHARD_NUMBER` | `2**64 - 1` | - |
-| `MAX_CASPER_VOTES` | `2**10` (= 1,024) | votes |
-| `LATEST_BLOCK_ROOTS_LENGTH` | `2**13` (= 8,192) | block roots |
-| `LATEST_RANDAO_MIXES_LENGTH` | `2**13` (= 8,192) | randao mixes |
-| `LATEST_PENALIZED_EXIT_LENGTH` | `2**13` (= 8,192) | epochs | ~36 days |
+| `MAX_INDICES_PER_SLASHABLE_VOTE` | `2**12` (= 4,096) | votes |
| `MAX_WITHDRAWALS_PER_EPOCH` | `2**2` (= 4) | withdrawals |
* For the safety of crosslinks `TARGET_COMMITTEE_SIZE` exceeds [the recommended minimum committee size of 111](https://vitalik.ca/files/Ithaca201807_Sharding.pdf); with sufficient active validators (at least `EPOCH_LENGTH * TARGET_COMMITTEE_SIZE`), the shuffling algorithm ensures committee sizes at least `TARGET_COMMITTEE_SIZE`. (Unbiasable randomness with a Verifiable Delay Function (VDF) will improve committee robustness and lower the safe minimum committee size.)
@@ -187,13 +197,16 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
| Name | Value |
| - | - |
| `GENESIS_FORK_VERSION` | `0` |
-| `GENESIS_SLOT` | `0` |
+| `GENESIS_SLOT` | `2**19` |
+| `GENESIS_EPOCH` | `slot_to_epoch(GENESIS_SLOT)` |
| `GENESIS_START_SHARD` | `0` |
-| `FAR_FUTURE_SLOT` | `2**64 - 1` |
+| `FAR_FUTURE_EPOCH` | `2**64 - 1` |
| `ZERO_HASH` | `int_to_bytes32(0)` |
| `EMPTY_SIGNATURE` | `int_to_bytes96(0)` |
| `BLS_WITHDRAWAL_PREFIX_BYTE` | `int_to_bytes1(0)` |
+* `GENESIS_SLOT` should be at least as large in terms of time as the largest of the time parameters or state list lengths below (ie. it should be at least as large as any value measured in slots, and at least `EPOCH_LENGTH` times as large as any value measured in epochs).
+
### Time parameters
| Name | Value | Unit | Duration |
@@ -201,10 +214,19 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
| `SLOT_DURATION` | `6` | seconds | 6 seconds |
| `MIN_ATTESTATION_INCLUSION_DELAY` | `2**2` (= 4) | slots | 24 seconds |
| `EPOCH_LENGTH` | `2**6` (= 64) | slots | 6.4 minutes |
-| `SEED_LOOKAHEAD` | `2**6` (= 64) | slots | 6.4 minutes |
-| `ENTRY_EXIT_DELAY` | `2**8` (= 256) | slots | 25.6 minutes |
-| `ETH1_DATA_VOTING_PERIOD` | `2**10` (= 1,024) | slots | ~1.7 hours |
-| `MIN_VALIDATOR_WITHDRAWAL_TIME` | `2**14` (= 16,384) | slots | ~27 hours |
+| `SEED_LOOKAHEAD` | `2**0` (= 1) | epochs | 6.4 minutes |
+| `ENTRY_EXIT_DELAY` | `2**2` (= 4) | epochs | 25.6 minutes |
+| `ETH1_DATA_VOTING_PERIOD` | `2**4` (= 16) | epochs | ~1.7 hours |
+| `MIN_VALIDATOR_WITHDRAWAL_EPOCHS` | `2**8` (= 256) | epochs | ~27 hours |
+
+### State list lengths
+
+| Name | Value | Unit | Duration |
+| - | - | :-: | :-: |
+| `LATEST_BLOCK_ROOTS_LENGTH` | `2**13` (= 8,192) | slots | ~13 hours |
+| `LATEST_RANDAO_MIXES_LENGTH` | `2**13` (= 8,192) | epochs | ~36 days |
+| `LATEST_INDEX_ROOTS_LENGTH` | `2**13` (= 8,192) | epochs | ~36 days |
+| `LATEST_PENALIZED_EXIT_LENGTH` | `2**13` (= 8,192) | epochs | ~36 days |
### Reward and penalty quotients
@@ -230,18 +252,11 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
| Name | Value |
| - | - |
| `MAX_PROPOSER_SLASHINGS` | `2**4` (= 16) |
-| `MAX_CASPER_SLASHINGS` | `2**4` (= 16) |
+| `MAX_ATTESTER_SLASHINGS` | `2**0` (= 1) |
| `MAX_ATTESTATIONS` | `2**7` (= 128) |
| `MAX_DEPOSITS` | `2**4` (= 16) |
| `MAX_EXITS` | `2**4` (= 16) |
-### Validator registry delta flags
-
-| Name | Value |
-| - | - |
-| `ACTIVATION` | `0` |
-| `EXIT` | `1` |
-
### Signature domains
| Name | Value |
@@ -254,6 +269,8 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
## 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.
+
### Beacon chain operations
#### Proposer slashings
@@ -263,7 +280,7 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
# Proposer index
- 'proposer_index': 'uint24',
+ 'proposer_index': 'uint64',
# First proposal data
'proposal_data_1': ProposalSignedData,
# First proposal signature
@@ -275,29 +292,29 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
}
```
-#### Casper slashings
+#### Attester slashings
-##### `CasperSlashing`
+##### `AttesterSlashing`
```python
{
- # First batch of votes
- 'slashable_vote_data_1': SlashableVoteData,
- # Second batch of votes
- 'slashable_vote_data_2': SlashableVoteData,
+ # First slashable attestation
+ 'slashable_attestation_1': SlashableAttestation,
+ # Second slashable attestation
+ 'slashable_attestation_2': SlashableAttestation,
}
```
-##### `SlashableVoteData`
+##### `SlashableAttestation`
```python
{
- # Validator indices with custody bit equal to 0
- 'custody_bit_0_indices': ['uint24'],
- # Validator indices with custody bit equal to 1
- 'custody_bit_1_indices': ['uint24'],
+ # Validator indices
+ 'validator_indices': ['uint64'],
# Attestation data
'data': AttestationData,
+ # Custody bitfield
+ 'custody_bitfield': 'bytes',
# Aggregate signature
'aggregate_signature': 'bytes96',
}
@@ -309,10 +326,10 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
- # Attestation data
- 'data': AttestationData,
# Attester aggregation bitfield
'aggregation_bitfield': 'bytes',
+ # Attestation data
+ 'data': AttestationData,
# Custody bitfield
'custody_bitfield': 'bytes',
# BLS aggregate signature
@@ -336,8 +353,8 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
'shard_block_root': 'bytes32',
# Last crosslink's hash of root
'latest_crosslink_root': 'bytes32',
- # Slot of the last justified beacon block
- 'justified_slot': 'uint64',
+ # Last justified epoch in the beacon state
+ 'justified_epoch': 'uint64',
# Hash of the last justified beacon block
'justified_block_root': 'bytes32',
}
@@ -348,9 +365,9 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
# Attestation data
- data: AttestationData,
+ 'data': AttestationData,
# Custody bit
- custody_bit: bool,
+ 'custody_bit': 'bool',
}
```
@@ -401,10 +418,10 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
- # Minimum slot for processing exit
- 'slot': 'uint64',
+ # Minimum epoch for processing exit
+ 'epoch': 'uint64',
# Index of the exiting validator
- 'validator_index': 'uint24',
+ 'validator_index': 'uint64',
# Validator signature
'signature': 'bytes96',
}
@@ -434,18 +451,13 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
'proposer_slashings': [ProposerSlashing],
- 'casper_slashings': [CasperSlashing],
+ 'attester_slashings': [AttesterSlashing],
'attestations': [Attestation],
- 'custody_reseeds': [CustodyReseed],
- 'custody_challenges': [CustodyChallenge],
- 'custody_responses': [CustodyResponse],
'deposits': [Deposit],
'exits': [Exit],
}
```
-`CustodyReseed`, `CustodyChallenge`, and `CustodyResponse` will be defined in phase 1; for now, put dummy classes as these lists will remain empty throughout phase 0.
-
#### `ProposalSignedData`
```python
@@ -473,32 +485,27 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
# Validator registry
'validator_registry': [Validator],
'validator_balances': ['uint64'],
- 'validator_registry_update_slot': 'uint64',
- 'validator_registry_exit_count': 'uint64',
- 'validator_registry_delta_chain_tip': 'bytes32', # For light clients to track deltas
+ 'validator_registry_update_epoch': 'uint64',
# Randomness and committees
'latest_randao_mixes': ['bytes32'],
- 'latest_vdf_outputs': ['bytes32'],
'previous_epoch_start_shard': 'uint64',
'current_epoch_start_shard': 'uint64',
- 'previous_epoch_calculation_slot': 'uint64',
- 'current_epoch_calculation_slot': 'uint64',
- 'previous_epoch_randao_mix': 'bytes32',
- 'current_epoch_randao_mix': 'bytes32',
-
- # Custody challenges
- 'custody_challenges': [CustodyChallenge],
+ 'previous_calculation_epoch': 'uint64',
+ 'current_calculation_epoch': 'uint64',
+ 'previous_epoch_seed': 'bytes32',
+ 'current_epoch_seed': 'bytes32',
# Finality
- 'previous_justified_slot': 'uint64',
- 'justified_slot': 'uint64',
+ 'previous_justified_epoch': 'uint64',
+ 'justified_epoch': 'uint64',
'justification_bitfield': 'uint64',
- 'finalized_slot': 'uint64',
+ 'finalized_epoch': 'uint64',
# Recent state
'latest_crosslinks': [Crosslink],
- 'latest_block_roots': ['bytes32'], # Needed to process attestations, older to newer
+ 'latest_block_roots': ['bytes32'],
+ 'latest_index_roots': ['bytes32'],
'latest_penalized_balances': ['uint64'], # Balances penalized at every withdrawal period
'latest_attestations': [PendingAttestation],
'batched_block_roots': ['bytes32'],
@@ -517,24 +524,16 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
'pubkey': 'bytes48',
# Withdrawal credentials
'withdrawal_credentials': 'bytes32',
- # Number of proposer slots since genesis
- 'proposer_slots': 'uint64',
- # Slot when validator activated
- 'activation_slot': 'uint64',
- # Slot when validator exited
- 'exit_slot': 'uint64',
- # Slot when validator withdrew
- 'withdrawal_slot': 'uint64',
- # Slot when validator was penalized
- 'penalized_slot': 'uint64',
- # Exit counter when validator exited
- 'exit_count': 'uint64',
+ # Epoch when validator activated
+ 'activation_epoch': 'uint64',
+ # Epoch when validator exited
+ 'exit_epoch': 'uint64',
+ # Epoch when validator withdrew
+ 'withdrawal_epoch': 'uint64',
+ # Epoch when validator was penalized
+ 'penalized_epoch': 'uint64',
# Status flags
'status_flags': 'uint64',
- # Slot of latest custody reseed
- 'latest_custody_reseed_slot': 'uint64',
- # Slot of second-latest custody reseed
- 'penultimate_custody_reseed_slot': 'uint64',
}
```
@@ -542,8 +541,8 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
- # Slot number
- 'slot': 'uint64',
+ # Epoch number
+ 'epoch': 'uint64',
# Shard block root
'shard_block_root': 'bytes32',
}
@@ -553,14 +552,14 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
- # Signed data
- 'data': AttestationData,
# Attester aggregation bitfield
'aggregation_bitfield': 'bytes',
+ # Attestation data
+ 'data': AttestationData,
# Custody bitfield
'custody_bitfield': 'bytes',
- # Slot the attestation was included
- 'slot_included': 'uint64',
+ # Inclusion slot
+ 'inclusion_slot': 'uint64',
}
```
@@ -572,20 +571,8 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
'previous_version': 'uint64',
# Current fork version
'current_version': 'uint64',
- # Fork slot number
- 'slot': 'uint64',
-}
-```
-
-#### `ValidatorRegistryDeltaBlock`
-
-```python
-{
- 'latest_registry_delta_root': 'bytes32',
- 'validator_index': 'uint24',
- 'pubkey': 'bytes48',
- 'slot': 'uint64',
- 'flag': 'uint64',
+ # Fork epoch number
+ 'epoch': 'uint64',
}
```
@@ -594,9 +581,9 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
# Root of the deposit tree
- 'deposit_root': 'hash32',
+ 'deposit_root': 'bytes32',
# Block hash
- 'block_hash': 'hash32',
+ 'block_hash': 'bytes32',
}
```
@@ -611,6 +598,711 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
}
```
+## Custom Types
+
+We define the following Python custom types for type hinting and readability:
+
+| Name | SSZ equivalent | Description |
+| - | - | - |
+| `SlotNumber` | `uint64` | a slot number |
+| `EpochNumber` | `uint64` | an epoch number |
+| `ShardNumber` | `uint64` | a shard number |
+| `ValidatorIndex` | `uint64` | an index in the validator registry |
+| `Gwei` | `uint64` | an amount in Gwei |
+| `Bytes32` | `bytes32` | 32 bytes of binary data |
+| `BLSPubkey` | `bytes48` | a BLS public key |
+| `BLSSignature` | `bytes96` | a BLS signature |
+
+## Helper functions
+
+Note: The definitions below are for specification purposes and are not necessarily optimal implementations.
+
+### `hash`
+
+The hash function is denoted by `hash`. In Phase 0 the beacon chain is deployed with the same hash function as Ethereum 1.0, i.e. Keccak-256 (also incorrectly known as SHA3).
+
+Note: We aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethereum 2.0 deployment phase.
+
+### `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).
+
+### `slot_to_epoch`
+
+```python
+def slot_to_epoch(slot: SlotNumber) -> EpochNumber:
+ """
+ Return the epoch number of the given ``slot``.
+ """
+ return slot // EPOCH_LENGTH
+```
+
+### `get_current_epoch`
+
+```python
+def get_current_epoch(state: BeaconState) -> EpochNumber:
+ """
+ Return the current epoch of the given ``state``.
+ """
+ return slot_to_epoch(state.slot)
+```
+
+### `get_epoch_start_slot`
+
+```python
+def get_epoch_start_slot(epoch: EpochNumber) -> SlotNumber:
+ """
+ Return the starting slot of the given ``epoch``.
+ """
+ return epoch * EPOCH_LENGTH
+```
+
+### `is_active_validator`
+```python
+def is_active_validator(validator: Validator, epoch: EpochNumber) -> bool:
+ """
+ Check if ``validator`` is active.
+ """
+ return validator.activation_epoch <= epoch < validator.exit_epoch
+```
+
+### `get_active_validator_indices`
+
+```python
+def get_active_validator_indices(validators: List[Validator], epoch: EpochNumber) -> List[ValidatorIndex]:
+ """
+ Get indices of active validators from ``validators``.
+ """
+ return [i for i, v in enumerate(validators) if is_active_validator(v, epoch)]
+```
+
+### `shuffle`
+
+```python
+def shuffle(values: List[Any], seed: Bytes32) -> List[Any]:
+ """
+ Return the shuffled ``values`` with ``seed`` as entropy.
+ """
+ values_count = len(values)
+
+ # Entropy is consumed from the seed in 3-byte (24 bit) chunks.
+ rand_bytes = 3
+ # The highest possible result of the RNG.
+ rand_max = 2 ** (rand_bytes * 8) - 1
+
+ # The range of the RNG places an upper-bound on the size of the list that
+ # may be shuffled. It is a logic error to supply an oversized list.
+ assert values_count < rand_max
+
+ output = [x for x in values]
+ source = seed
+ index = 0
+ while index < values_count - 1:
+ # Re-hash the `source` to obtain a new pattern of bytes.
+ source = hash(source)
+ # Iterate through the `source` bytes in 3-byte chunks.
+ for position in range(0, 32 - (32 % rand_bytes), rand_bytes):
+ # Determine the number of indices remaining in `values` and exit
+ # once the last index is reached.
+ remaining = values_count - index
+ if remaining == 1:
+ break
+
+ # Read 3-bytes of `source` as a 24-bit big-endian integer.
+ sample_from_source = int.from_bytes(source[position:position + rand_bytes], 'big')
+
+ # Sample values greater than or equal to `sample_max` will cause
+ # modulo bias when mapped into the `remaining` range.
+ sample_max = rand_max - rand_max % remaining
+
+ # Perform a swap if the consumed entropy will not cause modulo bias.
+ if sample_from_source < sample_max:
+ # Select a replacement index for the current index.
+ replacement_position = (sample_from_source % remaining) + index
+ # Swap the current index with the replacement index.
+ output[index], output[replacement_position] = output[replacement_position], output[index]
+ index += 1
+ else:
+ # The sample causes modulo bias. A new sample should be read.
+ pass
+
+ return output
+```
+
+### `split`
+
+```python
+def split(values: List[Any], split_count: int) -> List[List[Any]]:
+ """
+ Splits ``values`` into ``split_count`` pieces.
+ """
+ list_length = len(values)
+ return [
+ values[(list_length * i // split_count): (list_length * (i + 1) // split_count)]
+ for i in range(split_count)
+ ]
+```
+
+### `get_epoch_committee_count`
+
+```python
+def get_epoch_committee_count(active_validator_count: int) -> int:
+ """
+ Return the number of committees in one epoch.
+ """
+ return max(
+ 1,
+ min(
+ SHARD_COUNT // EPOCH_LENGTH,
+ active_validator_count // EPOCH_LENGTH // TARGET_COMMITTEE_SIZE,
+ )
+ ) * EPOCH_LENGTH
+```
+
+### `get_shuffling`
+
+```python
+def get_shuffling(seed: Bytes32,
+ validators: List[Validator],
+ epoch: EpochNumber) -> List[List[ValidatorIndex]]
+ """
+ Shuffle ``validators`` into crosslink committees seeded by ``seed`` and ``epoch``.
+ Return a list of ``committees_per_epoch`` committees where each
+ committee is itself a list of validator indices.
+ """
+
+ active_validator_indices = get_active_validator_indices(validators, epoch)
+
+ committees_per_epoch = get_epoch_committee_count(len(active_validator_indices))
+
+ # Shuffle
+ seed = xor(seed, int_to_bytes32(epoch))
+ shuffled_active_validator_indices = shuffle(active_validator_indices, seed)
+
+ # Split the shuffled list into committees_per_epoch pieces
+ return split(shuffled_active_validator_indices, committees_per_epoch)
+```
+
+**Invariant**: if `get_shuffling(seed, validators, epoch)` returns some value `x` for some `epoch <= get_current_epoch(state) + ENTRY_EXIT_DELAY`, it should return the same value `x` for the same `seed` and `epoch` and possible future modifications of `validators` forever in phase 0, and until the ~1 year deletion delay in phase 2 and in the future.
+
+**Note**: this definition and the next few definitions make heavy use of repetitive computing. Production implementations are expected to appropriately use caching/memoization to avoid redoing work.
+
+### `get_previous_epoch_committee_count`
+
+```python
+def get_previous_epoch_committee_count(state: BeaconState) -> int:
+ """
+ Return the number of committees in the previous epoch of the given ``state``.
+ """
+ previous_active_validators = get_active_validator_indices(
+ state.validator_registry,
+ state.previous_calculation_epoch,
+ )
+ return get_epoch_committee_count(len(previous_active_validators))
+```
+
+### `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,
+ state.current_calculation_epoch,
+ )
+ return get_epoch_committee_count(len(current_active_validators))
+```
+
+### `get_crosslink_committees_at_slot`
+
+```python
+def get_crosslink_committees_at_slot(state: BeaconState,
+ slot: SlotNumber) -> List[Tuple[List[ValidatorIndex], ShardNumber]]:
+ """
+ Return the list of ``(committee, shard)`` tuples for the ``slot``.
+ """
+ epoch = slot_to_epoch(slot)
+ current_epoch = get_current_epoch(state)
+ previous_epoch = current_epoch - 1 if current_epoch > GENESIS_EPOCH else current_epoch
+ next_epoch = current_epoch + 1
+
+ assert previous_epoch <= epoch < next_epoch
+
+ if epoch < current_epoch:
+ committees_per_epoch = get_previous_epoch_committee_count(state)
+ seed = state.previous_epoch_seed
+ shuffling_epoch = state.previous_calculation_epoch
+ shuffling_start_shard = state.previous_epoch_start_shard
+ else:
+ committees_per_epoch = get_current_epoch_committee_count(state)
+ seed = state.current_epoch_seed
+ shuffling_epoch = state.current_calculation_epoch
+ shuffling_start_shard = state.current_epoch_start_shard
+
+ shuffling = get_shuffling(
+ seed,
+ state.validator_registry,
+ shuffling_epoch,
+ )
+ offset = slot % EPOCH_LENGTH
+ committees_per_slot = committees_per_epoch // EPOCH_LENGTH
+ slot_start_shard = (shuffling_start_shard + committees_per_slot * offset) % SHARD_COUNT
+
+ return [
+ (
+ shuffling[committees_per_slot * offset + i],
+ (slot_start_shard + i) % SHARD_COUNT,
+ )
+ for i in range(committees_per_slot)
+ ]
+```
+
+**Note**: we plan to replace the shuffling algorithm with a pointwise-evaluable shuffle (see https://github.com/ethereum/eth2.0-specs/issues/323), which will allow calculation of the committees for each slot individually.
+
+### `get_block_root`
+
+```python
+def get_block_root(state: BeaconState,
+ slot: SlotNumber) -> Bytes32:
+ """
+ Return the block root at a recent ``slot``.
+ """
+ assert state.slot <= slot + LATEST_BLOCK_ROOTS_LENGTH
+ assert slot < state.slot
+ return state.latest_block_roots[slot % LATEST_BLOCK_ROOTS_LENGTH]
+```
+
+`get_block_root(_, s)` should always return `hash_tree_root` of the block in the beacon chain at slot `s`, and `get_crosslink_committees_at_slot(_, s)` should not change unless the [validator](#dfn-validator) registry changes.
+
+### `get_randao_mix`
+
+```python
+def get_randao_mix(state: BeaconState,
+ epoch: EpochNumber) -> Bytes32:
+ """
+ Return the randao mix at a recent ``epoch``.
+ """
+ assert get_current_epoch(state) - LATEST_RANDAO_MIXES_LENGTH < epoch <= get_current_epoch(state)
+ return state.latest_randao_mixes[epoch % LATEST_RANDAO_MIXES_LENGTH]
+```
+
+### `get_active_index_root`
+
+```python
+def get_active_index_root(state: BeaconState,
+ epoch: EpochNumber) -> Bytes32:
+ """
+ Return the index root at a recent ``epoch``.
+ """
+ assert get_current_epoch(state) - LATEST_INDEX_ROOTS_LENGTH < epoch <= get_current_epoch(state)
+ return state.latest_index_roots[epoch % LATEST_INDEX_ROOTS_LENGTH]
+```
+
+### `generate_seed`
+
+```python
+def generate_seed(state: BeaconState,
+ epoch: EpochNumber) -> Bytes32:
+ """
+ Generate a seed for the given ``epoch``.
+ """
+
+ return hash(
+ get_randao_mix(state, epoch - SEED_LOOKAHEAD) +
+ get_active_index_root(state, epoch)
+ )
+```
+
+### `get_beacon_proposer_index`
+
+```python
+def get_beacon_proposer_index(state: BeaconState,
+ slot: SlotNumber) -> ValidatorIndex:
+ """
+ Return the beacon proposer index for the ``slot``.
+ """
+ first_committee, _ = get_crosslink_committees_at_slot(state, slot)[0]
+ return first_committee[slot % len(first_committee)]
+```
+
+### `merkle_root`
+
+```python
+def merkle_root(values: List[Bytes32]) -> Bytes32:
+ """
+ Merkleize ``values`` (where ``len(values)`` is a power of two) and return the Merkle root.
+ """
+ o = [0] * len(values) + values
+ for i in range(len(values) - 1, 0, -1):
+ o[i] = hash(o[i * 2] + o[i * 2 + 1])
+ return o[1]
+```
+
+### `get_attestation_participants`
+
+```python
+def get_attestation_participants(state: BeaconState,
+ attestation_data: AttestationData,
+ bitfield: bytes) -> List[ValidatorIndex]:
+ """
+ Return the participant indices at for the ``attestation_data`` and ``bitfield``.
+ """
+ # Find the committee in the list with the desired shard
+ crosslink_committees = get_crosslink_committees_at_slot(state, attestation_data.slot)
+
+ assert attestation_data.shard in [shard for _, shard in crosslink_committees]
+ crosslink_committee = [committee for committee, shard in crosslink_committees if shard == attestation_data.shard][0]
+
+ assert verify_bitfield(bitfield, len(crosslink_committee))
+
+ # Find the participating attesters in the committee
+ participants = []
+ for i, validator_index in enumerate(crosslink_committee):
+ aggregation_bit = get_bitfield_bit(bitfield, i)
+ if aggregation_bit == 0b1:
+ participants.append(validator_index)
+ return participants
+```
+
+### `int_to_bytes1`, `int_to_bytes2`, ...
+
+`int_to_bytes1(x): return x.to_bytes(1, 'big')`, `int_to_bytes2(x): return x.to_bytes(2, 'big')`, and so on for all integers, particularly 1, 2, 3, 4, 8, 32, 48, 96.
+
+### `get_effective_balance`
+
+```python
+def get_effective_balance(state: State, index: ValidatorIndex) -> Gwei:
+ """
+ Return the effective balance (also known as "balance at stake") for a ``validator`` with the given ``index``.
+ """
+ return min(state.validator_balances[index], MAX_DEPOSIT_AMOUNT)
+```
+
+### `get_fork_version`
+
+```python
+def get_fork_version(fork: Fork,
+ epoch: EpochNumber) -> int:
+ """
+ Return the fork version of the given ``epoch``.
+ """
+ if epoch < fork.epoch:
+ return fork.previous_version
+ else:
+ return fork.current_version
+```
+
+### `get_domain`
+
+```python
+def get_domain(fork: Fork,
+ epoch: EpochNumber,
+ domain_type: int) -> int:
+ """
+ Get the domain number that represents the fork meta and signature domain.
+ """
+ fork_version = get_fork_version(fork, epoch)
+ return fork_version * 2**32 + domain_type
+```
+
+### `get_bitfield_bit`
+
+```python
+def get_bitfield_bit(bitfield: bytes, i: int) -> int:
+ """
+ Extract the bit in ``bitfield`` at position ``i``.
+ """
+ return (bitfield[i // 8] >> (7 - (i % 8))) % 2
+```
+
+### `verify_bitfield`
+
+```python
+def verify_bitfield(bitfield: bytes, committee_size: int) -> bool:
+ """
+ Verify ``bitfield`` against the ``committee_size``.
+ """
+ if len(bitfield) != (committee_size + 7) // 8:
+ return False
+
+ for i in range(committee_size + 1, committee_size - committee_size % 8 + 8):
+ if get_bitfield_bit(bitfield, i) == 0b1:
+ return False
+
+ return True
+```
+
+### `verify_slashable_attestation`
+
+```python
+def verify_slashable_attestation(state: BeaconState, slashable_attestation: SlashableAttestation) -> bool:
+ """
+ Verify validity of ``slashable_attestation`` fields.
+ """
+ if slashable_attestation.custody_bitfield != b'\x00' * len(slashable_attestation.custody_bitfield): # [TO BE REMOVED IN PHASE 1]
+ return False
+
+ if len(slashable_attestation.validator_indices) == 0:
+ return False
+
+ for i in range(len(slashable_attestation.validator_indices) - 1):
+ if slashable_attestation.validator_indices[i] >= slashable_attestation.validator_indices[i + 1]:
+ return False
+
+ if not verify_bitfield(slashable_attestation.custody_bitfield, len(slashable_attestation.validator_indices)):
+ return False
+
+ if len(slashable_attestation.validator_indices) > MAX_INDICES_PER_SLASHABLE_VOTE:
+ return False
+
+ custody_bit_0_indices = []
+ custody_bit_1_indices = []
+ for i, validator_index in enumerate(slashable_attestation.validator_indices):
+ if get_bitfield_bit(slashable_attestation.custody_bitfield, i) == 0b0:
+ custody_bit_0_indices.append(validator_index)
+ else:
+ custody_bit_1_indices.append(validator_index)
+
+ return bls_verify(
+ pubkeys=[
+ bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in custody_bit_0_indices]),
+ bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in custody_bit_1_indices]),
+ ],
+ messages=[
+ hash_tree_root(AttestationDataAndCustodyBit(data=slashable_attestation.data, custody_bit=0b0)),
+ hash_tree_root(AttestationDataAndCustodyBit(data=slashable_attestation.data, custody_bit=0b1)),
+ ],
+ signature=slashable_attestation.aggregate_signature,
+ domain=get_domain(
+ state.fork,
+ slot_to_epoch(vote_data.data.slot),
+ DOMAIN_ATTESTATION,
+ ),
+ )
+```
+
+### `is_double_vote`
+
+```python
+def is_double_vote(attestation_data_1: AttestationData,
+ attestation_data_2: AttestationData) -> bool:
+ """
+ Check if ``attestation_data_1`` and ``attestation_data_2`` have the same target.
+ """
+ target_epoch_1 = slot_to_epoch(attestation_data_1.slot)
+ target_epoch_2 = slot_to_epoch(attestation_data_2.slot)
+ return target_epoch_1 == target_epoch_2
+```
+
+### `is_surround_vote`
+
+```python
+def is_surround_vote(attestation_data_1: AttestationData,
+ attestation_data_2: AttestationData) -> bool:
+ """
+ Check if ``attestation_data_1`` surrounds ``attestation_data_2``.
+ """
+ source_epoch_1 = attestation_data_1.justified_epoch
+ source_epoch_2 = attestation_data_2.justified_epoch
+ target_epoch_1 = slot_to_epoch(attestation_data_1.slot)
+ target_epoch_2 = slot_to_epoch(attestation_data_2.slot)
+
+ return source_epoch_1 < source_epoch_2 and target_epoch_2 < target_epoch_1
+```
+
+### `integer_squareroot`
+
+```python
+def integer_squareroot(n: int) -> int:
+ """
+ The largest integer ``x`` such that ``x**2`` is less than or equal to ``n``.
+ """
+ assert n >= 0
+ x = n
+ y = (x + 1) // 2
+ while y < x:
+ x = y
+ y = (x + n // x) // 2
+ return x
+```
+
+### `get_entry_exit_effect_epoch`
+
+```python
+def get_entry_exit_effect_epoch(epoch: EpochNumber) -> EpochNumber:
+ """
+ An entry or exit triggered in the ``epoch`` given by the input takes effect at
+ the epoch given by the output.
+ """
+ return epoch + 1 + ENTRY_EXIT_DELAY
+```
+
+### `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_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_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).
+
+### `validate_proof_of_possession`
+
+```python
+def validate_proof_of_possession(state: BeaconState,
+ pubkey: BLSPubkey,
+ proof_of_possession: BLSSignature,
+ withdrawal_credentials: Bytes32) -> bool:
+ """
+ Verify the given ``proof_of_possession``.
+ """
+ proof_of_possession_data = DepositInput(
+ pubkey=pubkey,
+ withdrawal_credentials=withdrawal_credentials,
+ proof_of_possession=EMPTY_SIGNATURE,
+ )
+
+ return bls_verify(
+ pubkey=pubkey,
+ message=hash_tree_root(proof_of_possession_data),
+ signature=proof_of_possession,
+ domain=get_domain(
+ state.fork,
+ get_current_epoch(state),
+ DOMAIN_DEPOSIT,
+ )
+ )
+```
+
+### `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,
+ pubkey: BLSPubkey,
+ amount: Gwei,
+ proof_of_possession: BLSSignature,
+ withdrawal_credentials: Bytes32) -> None:
+ """
+ Process a deposit from Ethereum 1.0.
+ Note that this function mutates ``state``.
+ """
+ # Validate the given `proof_of_possession`
+ assert validate_proof_of_possession(
+ state,
+ pubkey,
+ proof_of_possession,
+ withdrawal_credentials,
+ )
+
+ validator_pubkeys = [v.pubkey for v in state.validator_registry]
+
+ if pubkey not in validator_pubkeys:
+ # Add new validator
+ validator = Validator(
+ pubkey=pubkey,
+ withdrawal_credentials=withdrawal_credentials,
+ activation_epoch=FAR_FUTURE_EPOCH,
+ exit_epoch=FAR_FUTURE_EPOCH,
+ withdrawal_epoch=FAR_FUTURE_EPOCH,
+ penalized_epoch=FAR_FUTURE_EPOCH,
+ status_flags=0,
+ )
+
+ # Note: In phase 2 registry indices that have been withdrawn for a long time will be recycled.
+ state.validator_registry.append(validator)
+ state.validator_balances.append(amount)
+ else:
+ # Increase balance by deposit amount
+ index = validator_pubkeys.index(pubkey)
+ assert state.validator_registry[index].withdrawal_credentials == withdrawal_credentials
+
+ state.validator_balances[index] += amount
+```
+
+### Routines for updating validator status
+
+Note: All functions in this section mutate `state`.
+
+#### `activate_validator`
+
+```python
+def activate_validator(state: BeaconState, index: ValidatorIndex, is_genesis: bool) -> None:
+ """
+ Activate the validator of the given ``index``.
+ Note that this function mutates ``state``.
+ """
+ validator = state.validator_registry[index]
+
+ validator.activation_epoch = GENESIS_EPOCH if is_genesis else get_entry_exit_effect_epoch(get_current_epoch(state))
+```
+
+#### `initiate_validator_exit`
+
+```python
+def initiate_validator_exit(state: BeaconState, index: ValidatorIndex) -> None:
+ """
+ Initiate the validator of the given ``index``.
+ Note that this function mutates ``state``.
+ """
+ validator = state.validator_registry[index]
+ validator.status_flags |= INITIATED_EXIT
+```
+
+#### `exit_validator`
+
+```python
+def exit_validator(state: BeaconState, index: ValidatorIndex) -> None:
+ """
+ Exit the validator of the given ``index``.
+ Note that this function mutates ``state``.
+ """
+ validator = state.validator_registry[index]
+
+ # The following updates only occur if not previous exited
+ if validator.exit_epoch <= get_entry_exit_effect_epoch(get_current_epoch(state)):
+ return
+
+ validator.exit_epoch = get_entry_exit_effect_epoch(get_current_epoch(state))
+```
+
+#### `penalize_validator`
+
+```python
+def penalize_validator(state: BeaconState, index: ValidatorIndex) -> None:
+ """
+ Penalize the validator of the given ``index``.
+ Note that this function mutates ``state``.
+ """
+ exit_validator(state, index)
+ validator = state.validator_registry[index]
+ state.latest_penalized_balances[get_current_epoch(state) % LATEST_PENALIZED_EXIT_LENGTH] += get_effective_balance(state, index)
+
+ whistleblower_index = get_beacon_proposer_index(state, state.slot)
+ whistleblower_reward = get_effective_balance(state, index) // WHISTLEBLOWER_REWARD_QUOTIENT
+ state.validator_balances[whistleblower_index] += whistleblower_reward
+ state.validator_balances[index] -= whistleblower_reward
+ validator.penalized_epoch = get_current_epoch(state)
+```
+
+#### `prepare_validator_for_withdrawal`
+
+```python
+def prepare_validator_for_withdrawal(state: BeaconState, index: ValidatorIndex) -> None:
+ """
+ Set the validator with the given ``index`` with ``WITHDRAWABLE`` flag.
+ Note that this function mutates ``state``.
+ """
+ validator = state.validator_registry[index]
+ validator.status_flags |= WITHDRAWABLE
+```
+
## Ethereum 1.0 deposit contract
The initial deployment phases of Ethereum 2.0 are implemented without consensus changes to Ethereum 1.0. A deposit contract at address `DEPOSIT_CONTRACT_ADDRESS` is added to Ethereum 1.0 for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in phase 2, i.e. when the EVM2.0 is deployed and the shards have state.
@@ -723,482 +1415,7 @@ def deposit(deposit_input: bytes[512]):
Note: to save ~10x on gas this contract uses a somewhat unintuitive progressive Merkle root calculation algo that requires only O(log(n)) storage. See https://github.com/ethereum/research/blob/master/beacon_chain_impl/progressive_merkle_tree.py for an implementation of the same algo in python tested for correctness.
-## Beacon chain processing
-
-The beacon chain is the system chain for Ethereum 2.0. The main responsibilities of the beacon chain are:
-
-* Store and maintain the registry of [validators](#dfn-validator)
-* Process crosslinks (see above)
-* Process its per-slot consensus, as well as the finality gadget
-
-Processing the beacon chain is similar to processing the Ethereum 1.0 chain. Clients download and process blocks, and maintain a view of what is the current "canonical chain", terminating at the current "head". However, because of the beacon chain's relationship with Ethereum 1.0, and because it is a proof-of-stake chain, there are differences.
-
-For a beacon chain block, `block`, to be processed by a node, the following conditions must be met:
-
-* The parent block with root `block.parent_root` has been processed and accepted.
-* The node has processed its `state` up to slot, `block.slot - 1`.
-* An Ethereum 1.0 block pointed to by the `state.latest_eth1_data.block_hash` has been processed and accepted.
-* The node's local clock time is greater than or equal to `state.genesis_time + block.slot * SLOT_DURATION`.
-
-If these conditions are not met, the client should delay processing the beacon block until the conditions are all satisfied.
-
-Beacon block production is significantly different because of the proof of stake mechanism. A client simply checks what it thinks is the canonical chain when it should create a block, and looks up what its slot number is; when the slot arrives, it either proposes or attests to a block as required. Note that this requires each node to have a clock that is roughly (i.e. within `SLOT_DURATION` seconds) synchronized with the other nodes.
-
-### Beacon chain fork choice rule
-
-The beacon chain fork choice rule is a hybrid that combines justification and finality with Latest Message Driven (LMD) Greediest Heaviest Observed SubTree (GHOST). At any point in time a [validator](#dfn-validator) `v` subjectively calculates the beacon chain head as follows.
-
-* Let `store` be the set of attestations and blocks that the [validator](#dfn-validator) `v` has observed and verified (in particular, block ancestors must be recursively verified). Attestations not part of any chain are still included in `store`.
-* Let `finalized_head` be the finalized block with the highest slot number. (A block `B` is finalized if there is a descendant of `B` in `store` the processing of which sets `B` as finalized.)
-* Let `justified_head` be the descendant of `finalized_head` with the highest slot number that has been justified for at least `EPOCH_LENGTH` slots. (A block `B` is justified if there is a descendant of `B` in `store` the processing of which sets `B` as justified.) If no such descendant exists set `justified_head` to `finalized_head`.
-* Let `get_ancestor(store, block, slot)` be the ancestor of `block` with slot number `slot`. The `get_ancestor` function can be defined recursively as `def get_ancestor(store, block, slot): return block if block.slot == slot else get_ancestor(store, store.get_parent(block), slot)`.
-* Let `get_latest_attestation(store, validator)` be the attestation with the highest slot number in `store` from `validator`. If several such attestations exist, use the one the [validator](#dfn-validator) `v` observed first.
-* Let `get_latest_attestation_target(store, validator)` be the target block in the attestation `get_latest_attestation(store, validator)`.
-* The head is `lmd_ghost(store, justified_head)` where the function `lmd_ghost` is defined below. Note that the implementation below is suboptimal; there are implementations that compute the head in time logarithmic in slot count.
-
-```python
-def lmd_ghost(store, start):
- validators = start.state.validator_registry
- active_validators = [validators[i] for i in
- get_active_validator_indices(validators, start.state.slot)]
- attestation_targets = [get_latest_attestation_target(store, validator)
- for validator in active_validators]
- def get_vote_count(block):
- return len([target for target in attestation_targets if
- get_ancestor(store, target, block.slot) == block])
-
- head = start
- while 1:
- children = get_children(head)
- if len(children) == 0:
- return head
- head = max(children, key=get_vote_count)
-```
-
-## Beacon chain state transition function
-
-We now define the state transition function. At a high level the state transition is made up of two parts:
-
-1. The per-slot transitions, which happens every slot, and only affects a parts of the `state`.
-2. The per-epoch transitions, which happens at every epoch boundary (i.e. `state.slot % EPOCH_LENGTH == 0`), and affects the entire `state`.
-
-The per-slot transitions generally focus on verifying aggregate signatures and saving temporary records relating to the per-slot activity in the `BeaconState`. 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.
-
-### Helper functions
-
-Note: The definitions below are for specification purposes and are not necessarily optimal implementations.
-
-#### `hash`
-
-The hash function is denoted by `hash`. In Phase 0 the beacon chain is deployed with the same hash function as Ethereum 1.0, i.e. Keccak-256 (also incorrectly known as SHA3).
-
-Note: We aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethereum 2.0 deployment phase.
-
-#### `hash_tree_root`
-
-`hash_tree_root` 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).
-
-#### `is_active_validator`
-```python
-def is_active_validator(validator: Validator, slot: int) -> bool:
- """
- Checks if ``validator`` is active.
- """
- return validator.activation_slot <= slot < validator.exit_slot
-```
-
-#### `get_active_validator_indices`
-
-```python
-def get_active_validator_indices(validators: [Validator], slot: int) -> List[int]:
- """
- Gets indices of active validators from ``validators``.
- """
- return [i for i, v in enumerate(validators) if is_active_validator(v, slot)]
-```
-
-#### `shuffle`
-
-```python
-def shuffle(values: List[Any], seed: Bytes32) -> List[Any]:
- """
- Returns the shuffled ``values`` with ``seed`` as entropy.
- """
- values_count = len(values)
-
- # Entropy is consumed from the seed in 3-byte (24 bit) chunks.
- rand_bytes = 3
- # The highest possible result of the RNG.
- rand_max = 2 ** (rand_bytes * 8) - 1
-
- # The range of the RNG places an upper-bound on the size of the list that
- # may be shuffled. It is a logic error to supply an oversized list.
- assert values_count < rand_max
-
- output = [x for x in values]
- source = seed
- index = 0
- while index < values_count - 1:
- # Re-hash the `source` to obtain a new pattern of bytes.
- source = hash(source)
- # Iterate through the `source` bytes in 3-byte chunks.
- for position in range(0, 32 - (32 % rand_bytes), rand_bytes):
- # Determine the number of indices remaining in `values` and exit
- # once the last index is reached.
- remaining = values_count - index
- if remaining == 1:
- break
-
- # Read 3-bytes of `source` as a 24-bit big-endian integer.
- sample_from_source = int.from_bytes(source[position:position + rand_bytes], 'big')
-
- # Sample values greater than or equal to `sample_max` will cause
- # modulo bias when mapped into the `remaining` range.
- sample_max = rand_max - rand_max % remaining
-
- # Perform a swap if the consumed entropy will not cause modulo bias.
- if sample_from_source < sample_max:
- # Select a replacement index for the current index.
- replacement_position = (sample_from_source % remaining) + index
- # Swap the current index with the replacement index.
- output[index], output[replacement_position] = output[replacement_position], output[index]
- index += 1
- else:
- # The sample causes modulo bias. A new sample should be read.
- pass
-
- return output
-```
-
-#### `split`
-
-```python
-def split(values: List[Any], split_count: int) -> List[List[Any]]:
- """
- Splits ``values`` into ``split_count`` pieces.
- """
- list_length = len(values)
- return [
- values[(list_length * i // split_count): (list_length * (i + 1) // split_count)]
- for i in range(split_count)
- ]
-```
-
-#### `get_committee_count_per_slot`
-
-```python
-def get_committee_count_per_slot(active_validator_count: int) -> int:
- return max(
- 1,
- min(
- SHARD_COUNT // EPOCH_LENGTH,
- active_validator_count // EPOCH_LENGTH // TARGET_COMMITTEE_SIZE,
- )
- )
-```
-
-#### `get_shuffling`
-
-```python
-def get_shuffling(seed: Bytes32,
- validators: List[Validator],
- slot: int) -> List[List[int]]
- """
- Shuffles ``validators`` into crosslink committees seeded by ``seed`` and ``slot``.
- Returns a list of ``EPOCH_LENGTH * committees_per_slot`` committees where each
- committee is itself a list of validator indices.
- """
-
- # Normalizes slot to start of epoch boundary
- slot -= slot % EPOCH_LENGTH
-
- active_validator_indices = get_active_validator_indices(validators, slot)
-
- committees_per_slot = get_committee_count_per_slot(len(active_validator_indices))
-
- # Shuffle
- seed = xor(seed, int_to_bytes32(slot))
- shuffled_active_validator_indices = shuffle(active_validator_indices, seed)
-
- # Split the shuffled list into epoch_length * committees_per_slot pieces
- return split(shuffled_active_validator_indices, committees_per_slot * EPOCH_LENGTH)
-```
-
-**Invariant**: if `get_shuffling(seed, validators, slot)` returns some value `x`, it should return the same value `x` for the same `seed` and `slot` and possible future modifications of `validators` forever in phase 0, and until the ~1 year deletion delay in phase 2 and in the future.
-
-**Note**: this definition and the next few definitions make heavy use of repetitive computing. Production implementations are expected to appropriately use caching/memoization to avoid redoing work.
-
-#### `get_previous_epoch_committee_count_per_slot`
-
-```python
-def get_previous_epoch_committee_count_per_slot(state: BeaconState) -> int:
- previous_active_validators = get_active_validator_indices(
- state.validator_registry,
- state.previous_epoch_calculation_slot,
- )
- return get_committee_count_per_slot(len(previous_active_validators))
-```
-
-#### `get_current_epoch_committee_count_per_slot`
-
-```python
-def get_current_epoch_committee_count_per_slot(state: BeaconState) -> int:
- current_active_validators = get_active_validator_indices(
- state.validator_registry,
- state.current_epoch_calculation_slot,
- )
- return get_committee_count_per_slot(len(current_active_validators))
-```
-
-#### `get_crosslink_committees_at_slot`
-
-```python
-def get_crosslink_committees_at_slot(state: BeaconState,
- slot: int) -> List[Tuple[List[int], int]]:
- """
- Returns the list of ``(committee, shard)`` tuples for the ``slot``.
- """
- state_epoch_slot = state.slot - (state.slot % EPOCH_LENGTH)
- assert state_epoch_slot <= slot + EPOCH_LENGTH
- assert slot < state_epoch_slot + EPOCH_LENGTH
- offset = slot % EPOCH_LENGTH
-
- if slot < state_epoch_slot:
- committees_per_slot = get_previous_epoch_committee_count_per_slot(state)
- shuffling = get_shuffling(
- state.previous_epoch_randao_mix,
- state.validator_registry,
- state.previous_epoch_calculation_slot,
- )
- slot_start_shard = (state.previous_epoch_start_shard + committees_per_slot * offset) % SHARD_COUNT
- else:
- committees_per_slot = get_current_epoch_committee_count_per_slot(state)
- shuffling = get_shuffling(
- state.current_epoch_randao_mix,
- state.validator_registry,
- state.current_epoch_calculation_slot,
- )
- slot_start_shard = (state.current_epoch_start_shard + committees_per_slot * offset) % SHARD_COUNT
-
- return [
- (
- shuffling[committees_per_slot * offset + i],
- (slot_start_shard + i) % SHARD_COUNT,
- )
- for i in range(committees_per_slot)
- ]
-```
-
-**Note**: we plan to replace the shuffling algorithm with a pointwise-evaluable shuffle (see https://github.com/ethereum/eth2.0-specs/issues/323), which will allow calculation of the committees for each slot individually.
-
-#### `get_block_root`
-
-```python
-def get_block_root(state: BeaconState,
- slot: int) -> Bytes32:
- """
- Returns the block root at a recent ``slot``.
- """
- assert state.slot <= slot + LATEST_BLOCK_ROOTS_LENGTH
- assert slot < state.slot
- return state.latest_block_roots[slot % LATEST_BLOCK_ROOTS_LENGTH]
-```
-
-`get_block_root(_, s)` should always return `hash_tree_root` of the block in the beacon chain at slot `s`, and `get_crosslink_committees_at_slot(_, s)` should not change unless the [validator](#dfn-validator) registry changes.
-
-#### `get_randao_mix`
-
-```python
-def get_randao_mix(state: BeaconState,
- slot: int) -> Bytes32:
- """
- Returns the randao mix at a recent ``slot``.
- """
- assert state.slot < slot + LATEST_RANDAO_MIXES_LENGTH
- assert slot <= state.slot
- return state.latest_randao_mixes[slot % LATEST_RANDAO_MIXES_LENGTH]
-```
-
-#### `get_beacon_proposer_index`
-
-```python
-def get_beacon_proposer_index(state: BeaconState,
- slot: int) -> int:
- """
- Returns the beacon proposer index for the ``slot``.
- """
- first_committee, _ = get_crosslink_committees_at_slot(state, slot)[0]
- return first_committee[slot % len(first_committee)]
-```
-
-#### `merkle_root`
-
-```python
-def merkle_root(values: List[Bytes32]) -> Bytes32:
- """
- Merkleize ``values`` (where ``len(values)`` is a power of two) and return the Merkle root.
- """
- o = [0] * len(values) + values
- for i in range(len(values) - 1, 0, -1):
- o[i] = hash(o[i * 2] + o[i * 2 + 1])
- return o[1]
-```
-
-#### `get_attestation_participants`
-
-```python
-def get_attestation_participants(state: BeaconState,
- attestation_data: AttestationData,
- aggregation_bitfield: bytes) -> List[int]:
- """
- Returns the participant indices at for the ``attestation_data`` and ``aggregation_bitfield``.
- """
-
- # Find the committee in the list with the desired shard
- crosslink_committees = get_crosslink_committees_at_slot(state, attestation_data.slot)
-
- assert attestation_data.shard in [shard for _, shard in crosslink_committees]
- crosslink_committee = [committee for committee, shard in crosslink_committees if shard == attestation_data.shard][0]
- assert len(aggregation_bitfield) == (len(crosslink_committee) + 7) // 8
-
- # Find the participating attesters in the committee
- participants = []
- for i, validator_index in enumerate(crosslink_committee):
- aggregation_bit = (aggregation_bitfield[i // 8] >> (7 - (i % 8))) % 2
- if aggregation_bit == 1:
- participants.append(validator_index)
- return participants
-```
-
-#### `int_to_bytes1`, `int_to_bytes2`, ...
-
-`int_to_bytes1(x): return x.to_bytes(1, 'big')`, `int_to_bytes2(x): return x.to_bytes(2, 'big')`, and so on for all integers, particularly 1, 2, 3, 4, 8, 32, 48, 96.
-
-#### `get_effective_balance`
-
-```python
-def get_effective_balance(state: State, index: int) -> int:
- """
- Returns the effective balance (also known as "balance at stake") for a ``validator`` with the given ``index``.
- """
- return min(state.validator_balances[index], MAX_DEPOSIT_AMOUNT)
-```
-
-#### `get_fork_version`
-
-```python
-def get_fork_version(fork: Fork,
- slot: int) -> int:
- if slot < fork.slot:
- return fork.previous_version
- else:
- return fork.current_version
-```
-
-#### `get_domain`
-
-```python
-def get_domain(fork: Fork,
- slot: int,
- domain_type: int) -> int:
- return get_fork_version(
- fork,
- slot
- ) * 2**32 + domain_type
-```
-
-#### `verify_slashable_vote_data`
-
-```python
-def verify_slashable_vote_data(state: BeaconState, vote_data: SlashableVoteData) -> bool:
- if len(vote_data.custody_bit_0_indices) + len(vote_data.custody_bit_1_indices) > MAX_CASPER_VOTES:
- return False
-
- return bls_verify_multiple(
- pubkeys=[
- bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in vote_data.custody_bit_0_indices]),
- bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in vote_data.custody_bit_1_indices]),
- ],
- messages=[
- hash_tree_root(AttestationDataAndCustodyBit(vote_data.data, False)),
- hash_tree_root(AttestationDataAndCustodyBit(vote_data.data, True)),
- ],
- signature=vote_data.aggregate_signature,
- domain=get_domain(
- state.fork,
- vote_data.data.slot,
- DOMAIN_ATTESTATION,
- ),
- )
-```
-
-#### `is_double_vote`
-
-```python
-def is_double_vote(attestation_data_1: AttestationData,
- attestation_data_2: AttestationData) -> bool
- """
- Assumes ``attestation_data_1`` is distinct from ``attestation_data_2``.
- Returns True if the provided ``AttestationData`` are slashable
- due to a 'double vote'.
- """
- target_epoch_1 = attestation_data_1.slot // EPOCH_LENGTH
- target_epoch_2 = attestation_data_2.slot // EPOCH_LENGTH
- return target_epoch_1 == target_epoch_2
-```
-
-#### `is_surround_vote`
-
-```python
-def is_surround_vote(attestation_data_1: AttestationData,
- attestation_data_2: AttestationData) -> bool:
- """
- Assumes ``attestation_data_1`` is distinct from ``attestation_data_2``.
- Returns True if the provided ``AttestationData`` are slashable
- due to a 'surround vote'.
- Note: parameter order matters as this function only checks
- that ``attestation_data_1`` surrounds ``attestation_data_2``.
- """
- source_epoch_1 = attestation_data_1.justified_slot // EPOCH_LENGTH
- source_epoch_2 = attestation_data_2.justified_slot // EPOCH_LENGTH
- target_epoch_1 = attestation_data_1.slot // EPOCH_LENGTH
- target_epoch_2 = attestation_data_2.slot // EPOCH_LENGTH
- return (
- (source_epoch_1 < source_epoch_2) and
- (source_epoch_2 + 1 == target_epoch_2) and
- (target_epoch_2 < target_epoch_1)
- )
-```
-
-#### `integer_squareroot`
-
-```python
-def integer_squareroot(n: int) -> int:
- """
- The largest integer ``x`` such that ``x**2`` is less than ``n``.
- """
- assert n >= 0
- x = n
- y = (x + 1) // 2
- while y < x:
- x = y
- y = (x + n // x) // 2
- return x
-```
-
-#### `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_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_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).
-
-### On startup
+## On startup
A valid block with slot `GENESIS_SLOT` (a "genesis block") has the following values. Other validity rules (e.g. requiring a signature) do not apply.
@@ -1215,11 +1432,8 @@ A valid block with slot `GENESIS_SLOT` (a "genesis block") has the following val
signature=EMPTY_SIGNATURE,
body=BeaconBlockBody(
proposer_slashings=[],
- casper_slashings=[],
+ attester_slashings=[],
attestations=[],
- custody_reseeds=[],
- custody_challenges=[],
- custody_responses=[],
deposits=[],
exits=[],
),
@@ -1232,6 +1446,9 @@ A valid block with slot `GENESIS_SLOT` (a "genesis block") has the following val
def get_initial_beacon_state(initial_validator_deposits: List[Deposit],
genesis_time: int,
latest_eth1_data: Eth1Data) -> BeaconState:
+ """
+ Get the initial ``BeaconState``.
+ """
state = BeaconState(
# Misc
slot=GENESIS_SLOT,
@@ -1239,38 +1456,33 @@ def get_initial_beacon_state(initial_validator_deposits: List[Deposit],
fork=Fork(
previous_version=GENESIS_FORK_VERSION,
current_version=GENESIS_FORK_VERSION,
- slot=GENESIS_SLOT,
+ epoch=GENESIS_EPOCH,
),
# Validator registry
validator_registry=[],
validator_balances=[],
- validator_registry_update_slot=GENESIS_SLOT,
- validator_registry_exit_count=0,
- validator_registry_delta_chain_tip=ZERO_HASH,
+ validator_registry_update_epoch=GENESIS_EPOCH,
# Randomness and committees
latest_randao_mixes=[ZERO_HASH for _ in range(LATEST_RANDAO_MIXES_LENGTH)],
- latest_vdf_outputs=[ZERO_HASH for _ in range(LATEST_RANDAO_MIXES_LENGTH // EPOCH_LENGTH)],
previous_epoch_start_shard=GENESIS_START_SHARD,
current_epoch_start_shard=GENESIS_START_SHARD,
- previous_epoch_calculation_slot=GENESIS_SLOT,
- current_epoch_calculation_slot=GENESIS_SLOT,
- previous_epoch_randao_mix=ZERO_HASH,
- current_epoch_randao_mix=ZERO_HASH,
-
- # Custody challenges
- custody_challenges=[],
+ previous_calculation_epoch=GENESIS_EPOCH,
+ current_calculation_epoch=GENESIS_EPOCH,
+ previous_epoch_seed=ZERO_HASH,
+ current_epoch_seed=ZERO_HASH,
# Finality
- previous_justified_slot=GENESIS_SLOT,
- justified_slot=GENESIS_SLOT,
+ previous_justified_epoch=GENESIS_EPOCH,
+ justified_epoch=GENESIS_EPOCH,
justification_bitfield=0,
- finalized_slot=GENESIS_SLOT,
+ finalized_epoch=GENESIS_EPOCH,
# Recent state
- latest_crosslinks=[Crosslink(slot=GENESIS_SLOT, shard_block_root=ZERO_HASH) for _ in range(SHARD_COUNT)],
+ latest_crosslinks=[Crosslink(epoch=GENESIS_EPOCH, shard_block_root=ZERO_HASH) for _ in range(SHARD_COUNT)],
latest_block_roots=[ZERO_HASH for _ in range(LATEST_BLOCK_ROOTS_LENGTH)],
+ latest_index_roots=[ZERO_HASH for _ in range(LATEST_INDEX_ROOTS_LENGTH)],
latest_penalized_balances=[0 for _ in range(LATEST_PENALIZED_EXIT_LENGTH)],
latest_attestations=[],
batched_block_roots=[],
@@ -1293,199 +1505,146 @@ def get_initial_beacon_state(initial_validator_deposits: List[Deposit],
# Process initial activations
for validator_index, _ in enumerate(state.validator_registry):
if get_effective_balance(state, validator_index) >= MAX_DEPOSIT_AMOUNT:
- activate_validator(state, validator_index, True)
+ activate_validator(state, validator_index, is_genesis=True)
+
+ state.latest_index_roots[GENESIS_EPOCH % LATEST_INDEX_ROOTS_LENGTH] = hash_tree_root(get_active_validator_indices(state.validator_registry, GENESIS_EPOCH))
+ state.current_epoch_seed = generate_seed(state, GENESIS_EPOCH)
return state
```
-### Routine for processing deposits
+## Beacon chain processing
-First, a helper function:
+The beacon chain is the system chain for Ethereum 2.0. The main responsibilities of the beacon chain are:
+
+* Store and maintain the registry of [validators](#dfn-validator)
+* Process crosslinks (see above)
+* Process its per-block consensus, as well as the finality gadget
+
+Processing the beacon chain is similar to processing the Ethereum 1.0 chain. Clients download and process blocks, and maintain a view of what is the current "canonical chain", terminating at the current "head". However, because of the beacon chain's relationship with Ethereum 1.0, and because it is a proof-of-stake chain, there are differences.
+
+For a beacon chain block, `block`, to be processed by a node, the following conditions must be met:
+
+* The parent block with root `block.parent_root` has been processed and accepted.
+* An Ethereum 1.0 block pointed to by the `state.latest_eth1_data.block_hash` has been processed and accepted.
+* The node's local clock time is greater than or equal to `state.genesis_time + block.slot * SLOT_DURATION`.
+
+If these conditions are not met, the client should delay processing the beacon block until the conditions are all satisfied.
+
+Beacon block production is significantly different because of the proof of stake mechanism. A client simply checks what it thinks is the canonical chain when it should create a block, and looks up what its slot number is; when the slot arrives, it either proposes or attests to a block as required. Note that this requires each node to have a clock that is roughly (i.e. within `SLOT_DURATION` seconds) synchronized with the other nodes.
+
+### Beacon chain fork choice rule
+
+The beacon chain fork choice rule is a hybrid that combines justification and finality with Latest Message Driven (LMD) Greediest Heaviest Observed SubTree (GHOST). At any point in time a [validator](#dfn-validator) `v` subjectively calculates the beacon chain head as follows.
+
+* Abstractly define `Store` as the type of storage object for the chain data and `store` be the set of attestations and blocks that the [validator](#dfn-validator) `v` has observed and verified (in particular, block ancestors must be recursively verified). Attestations not yet included in any chain are still included in `store`.
+* Let `finalized_head` be the finalized block with the highest epoch. (A block `B` is finalized if there is a descendant of `B` in `store` the processing of which sets `B` as finalized.)
+* Let `justified_head` be the descendant of `finalized_head` with the highest epoch that has been justified for at least 1 epoch. (A block `B` is justified if there is a descendant of `B` in `store` the processing of which sets `B` as justified.) If no such descendant exists set `justified_head` to `finalized_head`.
+* Let `get_ancestor(store: Store, block: BeaconBlock, slot: SlotNumber) -> BeaconBlock` be the ancestor of `block` with slot number `slot`. The `get_ancestor` function can be defined recursively as:
```python
-def validate_proof_of_possession(state: BeaconState,
- pubkey: Bytes48,
- proof_of_possession: Bytes96,
- withdrawal_credentials: Bytes32) -> bool:
- proof_of_possession_data = DepositInput(
- pubkey=pubkey,
- withdrawal_credentials=withdrawal_credentials,
- proof_of_possession=EMPTY_SIGNATURE,
- )
-
- return bls_verify(
- pubkey=pubkey,
- message=hash_tree_root(proof_of_possession_data),
- signature=proof_of_possession,
- domain=get_domain(
- state.fork,
- state.slot,
- DOMAIN_DEPOSIT,
- )
- )
-```
-
-Now, 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,
- pubkey: Bytes48,
- amount: int,
- proof_of_possession: Bytes96,
- withdrawal_credentials: Bytes32) -> None:
+def get_ancestor(store: Store, block: BeaconBlock, slot: SlotNumber) -> BeaconBlock:
"""
- Process a deposit from Ethereum 1.0.
- Note that this function mutates ``state``.
+ Get the ancestor of ``block`` with slot number ``slot``; return ``None`` if not found.
"""
- # Validate the given `proof_of_possession`
- assert validate_proof_of_possession(
- state,
- pubkey,
- proof_of_possession,
- withdrawal_credentials,
- )
-
- validator_pubkeys = [v.pubkey for v in state.validator_registry]
-
- if pubkey not in validator_pubkeys:
- # Add new validator
- validator = Validator(
- pubkey=pubkey,
- withdrawal_credentials=withdrawal_credentials,
- proposer_slots=0,
- activation_slot=FAR_FUTURE_SLOT,
- exit_slot=FAR_FUTURE_SLOT,
- withdrawal_slot=FAR_FUTURE_SLOT,
- penalized_slot=FAR_FUTURE_SLOT,
- exit_count=0,
- status_flags=0,
- latest_custody_reseed_slot=GENESIS_SLOT,
- penultimate_custody_reseed_slot=GENESIS_SLOT,
- )
-
- # Note: In phase 2 registry indices that have been withdrawn for a long time will be recycled.
- state.validator_registry.append(validator)
- state.validator_balances.append(amount)
+ if block.slot == slot:
+ return block
+ elif block.slot < slot:
+ return None
else:
- # Increase balance by deposit amount
- index = validator_pubkeys.index(pubkey)
- assert state.validator_registry[index].withdrawal_credentials == withdrawal_credentials
-
- state.validator_balances[index] += amount
+ return get_ancestor(store, store.get_parent(block), slot)
```
-### Routines for updating validator status
-
-Note: All functions in this section mutate `state`.
+* Let `get_latest_attestation(store: Store, validator: Validator) -> Attestation` be the attestation with the highest slot number in `store` from `validator`. If several such attestations exist, use the one the [validator](#dfn-validator) `v` observed first.
+* Let `get_latest_attestation_target(store: Store, validator: Validator) -> BeaconBlock` be the target block in the attestation `get_latest_attestation(store, validator)`.
+* Let `get_children(store: Store, block: BeaconBlock) -> List[BeaconBlock]` returns the child blocks of the given `block`.
+* Let `justified_head_state` be the resulting `BeaconState` object from processing the chain up to the `justified_head`.
+* The `head` is `lmd_ghost(store, justified_head_state, justified_head)` where the function `lmd_ghost` is defined below. Note that the implementation below is suboptimal; there are implementations that compute the head in time logarithmic in slot count.
```python
-def activate_validator(state: BeaconState, index: int, genesis: bool) -> None:
- validator = state.validator_registry[index]
+def lmd_ghost(store: Store, start_state: BeaconState, start_block: BeaconBlock) -> BeaconBlock:
+ """
+ Execute the LMD-GHOST algorithm to find the head ``BeaconBlock``.
+ """
+ validators = start_state.validator_registry
+ active_validators = [
+ validators[i]
+ for i in get_active_validator_indices(validators, start_state.slot)
+ ]
+ attestation_targets = [
+ get_latest_attestation_target(store, validator)
+ for validator in active_validators
+ ]
- validator.activation_slot = GENESIS_SLOT if genesis else (state.slot + ENTRY_EXIT_DELAY)
- state.validator_registry_delta_chain_tip = hash_tree_root(
- ValidatorRegistryDeltaBlock(
- latest_registry_delta_root=state.validator_registry_delta_chain_tip,
- validator_index=index,
- pubkey=validator.pubkey,
- slot=validator.activation_slot,
- flag=ACTIVATION,
- )
- )
+ def get_vote_count(block: BeaconBlock) -> int:
+ return len([
+ target
+ for target in attestation_targets
+ if get_ancestor(store, target, block.slot) == block
+ ])
+
+ head = start_block
+ while 1:
+ children = get_children(store, head)
+ if len(children) == 0:
+ return head
+ head = max(children, key=get_vote_count)
```
-```python
-def initiate_validator_exit(state: BeaconState, index: int) -> None:
- validator = state.validator_registry[index]
- validator.status_flags |= INITIATED_EXIT
-```
+## Beacon chain state transition function
-```python
-def exit_validator(state: BeaconState, index: int) -> None:
- validator = state.validator_registry[index]
+We now define the state transition function. At a high level the state transition is made up of three parts:
- # The following updates only occur if not previous exited
- if validator.exit_slot <= state.slot + ENTRY_EXIT_DELAY:
- return
+1. The per-slot transitions, which happens at the start of every slot.
+2. The per-block transitions, which happens at every block.
+3. The per-epoch transitions, which happens at the end of the last slot of every epoch (i.e. `(state.slot + 1) % EPOCH_LENGTH == 0`).
- validator.exit_slot = state.slot + ENTRY_EXIT_DELAY
+The per-slot transitions focus on the slot counter and block roots records updates; the per-block transitions generally focus on verifying aggregate signatures and saving temporary records relating to the per-block activity in the `BeaconState`; 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.
- state.validator_registry_exit_count += 1
- validator.exit_count = state.validator_registry_exit_count
- state.validator_registry_delta_chain_tip = hash_tree_root(
- ValidatorRegistryDeltaBlock(
- latest_registry_delta_root=state.validator_registry_delta_chain_tip,
- validator_index=index,
- pubkey=validator.pubkey,
- slot=validator.exit_slot,
- flag=EXIT,
- )
- )
-```
+_Note_: If there are skipped slots between a block and its parent block, run the steps in the [per-slot](#per-slot-processing) and [per-epoch](#per-epoch-processing) sections once for each skipped slot and then once for the slot containing the new block.
-```python
-def penalize_validator(state: BeaconState, index: int) -> None:
- exit_validator(state, index)
- validator = state.validator_registry[index]
- state.latest_penalized_balances[(state.slot // EPOCH_LENGTH) % LATEST_PENALIZED_EXIT_LENGTH] += get_effective_balance(state, index)
-
- whistleblower_index = get_beacon_proposer_index(state, state.slot)
- whistleblower_reward = get_effective_balance(state, index) // WHISTLEBLOWER_REWARD_QUOTIENT
- state.validator_balances[whistleblower_index] += whistleblower_reward
- state.validator_balances[index] -= whistleblower_reward
- validator.penalized_slot = state.slot
-```
-
-```python
-def prepare_validator_for_withdrawal(state: BeaconState, index: int) -> None:
- validator = state.validator_registry[index]
- validator.status_flags |= WITHDRAWABLE
-```
-
-## Per-slot processing
+### Per-slot processing
Below are the processing steps that happen at every slot.
-### Misc counters
+#### Slot
* Set `state.slot += 1`.
-* Set `state.validator_registry[get_beacon_proposer_index(state, state.slot)].proposer_slots += 1`.
-* Set `state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH] = state.latest_randao_mixes[(state.slot - 1) % LATEST_RANDAO_MIXES_LENGTH]`
-### Block roots
+#### Block roots
* Let `previous_block_root` be the `tree_hash_root` of the previous beacon block processed in the chain.
* Set `state.latest_block_roots[(state.slot - 1) % LATEST_BLOCK_ROOTS_LENGTH] = previous_block_root`.
* If `state.slot % LATEST_BLOCK_ROOTS_LENGTH == 0` append `merkle_root(state.latest_block_roots)` to `state.batched_block_roots`.
-## Per-block processing
+### Per-block processing
Below are the processing steps that happen at every `block`.
-### Slot
+#### Slot
* Verify that `block.slot == state.slot`.
-### Proposer signature
+#### Proposer signature
* Let `block_without_signature_root` be the `hash_tree_root` of `block` where `block.signature` is set to `EMPTY_SIGNATURE`.
* Let `proposal_root = hash_tree_root(ProposalSignedData(state.slot, BEACON_CHAIN_SHARD_NUMBER, block_without_signature_root))`.
-* Verify that `bls_verify(pubkey=state.validator_registry[get_beacon_proposer_index(state, state.slot)].pubkey, message=proposal_root, signature=block.signature, domain=get_domain(state.fork, state.slot, DOMAIN_PROPOSAL))`.
+* Verify that `bls_verify(pubkey=state.validator_registry[get_beacon_proposer_index(state, state.slot)].pubkey, message=proposal_root, signature=block.signature, domain=get_domain(state.fork, get_current_epoch(state), DOMAIN_PROPOSAL))`.
-### RANDAO
+#### RANDAO
* Let `proposer = state.validator_registry[get_beacon_proposer_index(state, state.slot)]`.
-* Verify that `bls_verify(pubkey=proposer.pubkey, message=int_to_bytes32(proposer.proposer_slots), signature=block.randao_reveal, domain=get_domain(state.fork, state.slot, DOMAIN_RANDAO))`.
-* Set `state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH] = hash(state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH] + block.randao_reveal)`.
+* Verify that `bls_verify(pubkey=proposer.pubkey, message=int_to_bytes32(get_current_epoch(state)), signature=block.randao_reveal, domain=get_domain(state.fork, get_current_epoch(state), DOMAIN_RANDAO))`.
+* Set `state.latest_randao_mixes[get_current_epoch(state) % LATEST_RANDAO_MIXES_LENGTH] = xor(get_randao_mix(state, get_current_epoch(state)), hash(block.randao_reveal))`.
-### Eth1 data
+#### Eth1 data
* If `block.eth1_data` equals `eth1_data_vote.eth1_data` for some `eth1_data_vote` in `state.eth1_data_votes`, set `eth1_data_vote.vote_count += 1`.
* Otherwise, append to `state.eth1_data_votes` a new `Eth1DataVote(eth1_data=block.eth1_data, vote_count=1)`.
-### Operations
+#### Operations
-#### Proposer slashings
+##### Proposer slashings
Verify that `len(block.body.proposer_slashings) <= MAX_PROPOSER_SLASHINGS`.
@@ -1495,47 +1654,69 @@ For each `proposer_slashing` in `block.body.proposer_slashings`:
* Verify that `proposer_slashing.proposal_data_1.slot == proposer_slashing.proposal_data_2.slot`.
* Verify that `proposer_slashing.proposal_data_1.shard == proposer_slashing.proposal_data_2.shard`.
* Verify that `proposer_slashing.proposal_data_1.block_root != proposer_slashing.proposal_data_2.block_root`.
-* Verify that `proposer.penalized_slot > state.slot`.
-* Verify that `bls_verify(pubkey=proposer.pubkey, message=hash_tree_root(proposer_slashing.proposal_data_1), signature=proposer_slashing.proposal_signature_1, domain=get_domain(state.fork, proposer_slashing.proposal_data_1.slot, DOMAIN_PROPOSAL))`.
-* Verify that `bls_verify(pubkey=proposer.pubkey, message=hash_tree_root(proposer_slashing.proposal_data_2), signature=proposer_slashing.proposal_signature_2, domain=get_domain(state.fork, proposer_slashing.proposal_data_2.slot, DOMAIN_PROPOSAL))`.
+* Verify that `proposer.penalized_epoch > get_current_epoch(state)`.
+* Verify that `bls_verify(pubkey=proposer.pubkey, message=hash_tree_root(proposer_slashing.proposal_data_1), signature=proposer_slashing.proposal_signature_1, domain=get_domain(state.fork, slot_to_epoch(proposer_slashing.proposal_data_1.slot), DOMAIN_PROPOSAL))`.
+* Verify that `bls_verify(pubkey=proposer.pubkey, message=hash_tree_root(proposer_slashing.proposal_data_2), signature=proposer_slashing.proposal_signature_2, domain=get_domain(state.fork, slot_to_epoch(proposer_slashing.proposal_data_2.slot), DOMAIN_PROPOSAL))`.
* Run `penalize_validator(state, proposer_slashing.proposer_index)`.
-#### Casper slashings
+##### Attester slashings
-Verify that `len(block.body.casper_slashings) <= MAX_CASPER_SLASHINGS`.
+Verify that `len(block.body.attester_slashings) <= MAX_ATTESTER_SLASHINGS`.
-For each `casper_slashing` in `block.body.casper_slashings`:
+For each `attester_slashing` in `block.body.attester_slashings`:
-* Let `slashable_vote_data_1 = casper_slashing.slashable_vote_data_1`.
-* Let `slashable_vote_data_2 = casper_slashing.slashable_vote_data_2`.
-* Let `indices(slashable_vote_data) = slashable_vote_data.custody_bit_0_indices + slashable_vote_data.custody_bit_1_indices`.
-* Let `intersection = [x for x in indices(slashable_vote_data_1) if x in indices(slashable_vote_data_2)]`.
-* Verify that `len(intersection) >= 1`.
-* Verify that `slashable_vote_data_1.data != slashable_vote_data_2.data`.
-* Verify that `is_double_vote(slashable_vote_data_1.data, slashable_vote_data_2.data)` or `is_surround_vote(slashable_vote_data_1.data, slashable_vote_data_2.data)`.
-* Verify that `verify_slashable_vote_data(state, slashable_vote_data_1)`.
-* Verify that `verify_slashable_vote_data(state, slashable_vote_data_2)`.
-* For each [validator](#dfn-validator) index `i` in `intersection` run `penalize_validator(state, i)` if `state.validator_registry[i].penalized_slot > state.slot`.
+* Let `slashable_attestation_1 = attester_slashing.slashable_attestation_1`.
+* Let `slashable_attestation_2 = attester_slashing.slashable_attestation_2`.
+* Verify that `slashable_attestation_1.data != slashable_attestation_2.data`.
+* Verify that `is_double_vote(slashable_attestation_1.data, slashable_attestation_2.data)` or `is_surround_vote(slashable_attestation_1.data, slashable_attestation_2.data)`.
+* Verify that `verify_slashable_attestation(state, slashable_attestation_1)`.
+* Verify that `verify_slashable_attestation(state, slashable_attestation_2)`.
+* Let `slashable_indices = [index for index in slashable_attestation_1.validator_indices if index in slashable_attestation_2.validator_indices and state.validator_registry[index].penalized_epoch > get_current_epoch(state)]`.
+* Verify that `len(slashable_indices) >= 1`.
+* Run `penalize_validator(state, index)` for each `index` in `slashable_indices`.
-#### Attestations
+##### Attestations
Verify that `len(block.body.attestations) <= MAX_ATTESTATIONS`.
For each `attestation` in `block.body.attestations`:
-* Verify that `attestation.data.slot + MIN_ATTESTATION_INCLUSION_DELAY <= state.slot`.
-* Verify that `attestation.data.slot + EPOCH_LENGTH >= state.slot`.
-* Verify that `attestation.data.justified_slot` is equal to `state.justified_slot if attestation.data.slot >= state.slot - (state.slot % EPOCH_LENGTH) else state.previous_justified_slot`.
-* Verify that `attestation.data.justified_block_root` is equal to `get_block_root(state, attestation.data.justified_slot)`.
+* Verify that `attestation.data.slot <= state.slot - MIN_ATTESTATION_INCLUSION_DELAY < attestation.data.slot + EPOCH_LENGTH`.
+* Verify that `attestation.data.justified_epoch` is equal to `state.justified_epoch if attestation.data.slot >= get_epoch_start_slot(get_current_epoch(state)) else state.previous_justified_epoch`.
+* Verify that `attestation.data.justified_block_root` is equal to `get_block_root(state, get_epoch_start_slot(attestation.data.justified_epoch))`.
* Verify that either `attestation.data.latest_crosslink_root` or `attestation.data.shard_block_root` equals `state.latest_crosslinks[shard].shard_block_root`.
-* `aggregate_signature` verification:
- * Let `participants = get_attestation_participants(state, attestation.data, attestation.aggregation_bitfield)`.
- * Let `group_public_key = bls_aggregate_pubkeys([state.validator_registry[v].pubkey for v in participants])`.
- * Verify that `bls_verify(pubkey=group_public_key, message=hash_tree_root(AttestationDataAndCustodyBit(attestation.data, False)), signature=attestation.aggregate_signature, domain=get_domain(state.fork, attestation.data.slot, DOMAIN_ATTESTATION))`.
-* [TO BE REMOVED IN PHASE 1] Verify that `attestation.data.shard_block_root == ZERO_HASH`.
-* Append `PendingAttestation(data=attestation.data, aggregation_bitfield=attestation.aggregation_bitfield, custody_bitfield=attestation.custody_bitfield, slot_included=state.slot)` to `state.latest_attestations`.
+* Verify bitfields and aggregate signature:
-#### Deposits
+```python
+ assert attestation.custody_bitfield == b'\x00' * len(attestation.custody_bitfield) # [TO BE REMOVED IN PHASE 1]
+ assert attestation.aggregation_bitfield != b'\x00' * len(attestation.aggregation_bitfield)
+
+ for i in range(len(crosslink_committee)):
+ if get_bitfield_bit(attestation.aggregation_bitfield, i) == 0b0:
+ assert get_bitfield_bit(attestation.custody_bitfield, i) == 0b0
+
+ participants = get_attestation_participants(state, attestation.data, attestation.aggregation_bitfield)
+ custody_bit_1_participants = get_attestation_participants(state, attestation.data, attestation.custody_bitfield)
+ custody_bit_0_participants = [i in participants for i not in custody_bit_1_participants]
+
+ assert bls_verify_multiple(
+ pubkeys=[
+ bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in custody_bit_0_participants]),
+ bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in custody_bit_1_participants]),
+ ],
+ messages=[
+ hash_tree_root(AttestationDataAndCustodyBit(data=attestation.data, custody_bit=0b0)),
+ hash_tree_root(AttestationDataAndCustodyBit(data=attestation.data, custody_bit=0b1)),
+ ],
+ signature=attestation.aggregate_signature,
+ domain=get_domain(state.fork, slot_to_epoch(attestation.data.slot), DOMAIN_ATTESTATION),
+ )
+```
+
+* [TO BE REMOVED IN PHASE 1] Verify that `attestation.data.shard_block_root == ZERO_HASH`.
+* Append `PendingAttestation(data=attestation.data, aggregation_bitfield=attestation.aggregation_bitfield, custody_bitfield=attestation.custody_bitfield, inclusion_slot=state.slot)` to `state.latest_attestations`.
+
+##### Deposits
Verify that `len(block.body.deposits) <= MAX_DEPOSITS`.
@@ -1548,7 +1729,10 @@ For each `deposit` in `block.body.deposits`:
* Verify that `verify_merkle_branch(hash(serialized_deposit_data), deposit.branch, DEPOSIT_CONTRACT_TREE_DEPTH, deposit.index, state.latest_eth1_data.deposit_root)` is `True`.
```python
-def verify_merkle_branch(leaf: Bytes32, branch: [Bytes32], depth: int, index: int, root: Bytes32) -> bool:
+def verify_merkle_branch(leaf: Bytes32, branch: List[Bytes32], depth: int, index: int, root: Bytes32) -> bool:
+ """
+ Verify that the given ``leaf`` is on the merkle branch ``branch``.
+ """
value = leaf
for i in range(depth):
if index // (2**i) % 2:
@@ -1570,53 +1754,50 @@ process_deposit(
)
```
-#### Exits
+##### Exits
Verify that `len(block.body.exits) <= MAX_EXITS`.
For each `exit` in `block.body.exits`:
* Let `validator = state.validator_registry[exit.validator_index]`.
-* Verify that `validator.exit_slot > state.slot + ENTRY_EXIT_DELAY`.
-* Verify that `state.slot >= exit.slot`.
-* Let `exit_message = hash_tree_root(Exit(slot=exit.slot, validator_index=exit.validator_index, signature=EMPTY_SIGNATURE))`.
-* Verify that `bls_verify(pubkey=validator.pubkey, message=exit_message, signature=exit.signature, domain=get_domain(state.fork, exit.slot, DOMAIN_EXIT))`.
+* Verify that `validator.exit_epoch > get_entry_exit_effect_epoch(get_current_epoch(state))`.
+* Verify that `get_current_epoch(state) >= exit.epoch`.
+* Let `exit_message = hash_tree_root(Exit(epoch=exit.epoch, validator_index=exit.validator_index, signature=EMPTY_SIGNATURE))`.
+* Verify that `bls_verify(pubkey=validator.pubkey, message=exit_message, signature=exit.signature, domain=get_domain(state.fork, exit.epoch, DOMAIN_EXIT))`.
* Run `initiate_validator_exit(state, exit.validator_index)`.
-#### Custody
+### Per-epoch processing
-[TO BE REMOVED IN PHASE 1] Verify that `len(block.body.custody_reseeds) == len(block.body.custody_challenges) == len(block.body.custody_responses) == 0`.
+The steps below happen when `(state.slot + 1) % EPOCH_LENGTH == 0`.
-## Per-epoch processing
+#### Helpers
-The steps below happen when `state.slot % EPOCH_LENGTH == 0`.
-
-### Helpers
-
-All [validators](#dfn-validator):
-
-* Let `active_validator_indices = get_active_validator_indices(state.validator_registry, state.slot)`.
-* Let `total_balance = sum([get_effective_balance(state, i) for i in active_validator_indices])`.
+* Let `current_epoch = get_current_epoch(state)`.
+* Let `previous_epoch = current_epoch - 1 if current_epoch > GENESIS_EPOCH else current_epoch`.
+* Let `next_epoch = current_epoch + 1`.
[Validators](#dfn-Validator) attesting during the current epoch:
-* Let `current_epoch_attestations = [a for a in state.latest_attestations if state.slot - EPOCH_LENGTH <= a.data.slot < state.slot]`. (Note: this is the set of attestations of slots in the epoch `state.slot-EPOCH_LENGTH...state.slot-1`, _not_ attestations that got included in the chain during the epoch `state.slot-EPOCH_LENGTH...state.slot-1`.)
+* Let `current_total_balance = sum([get_effective_balance(state, i) for i in get_active_validator_indices(state.validator_registry, current_epoch)])`.
+* Let `current_epoch_attestations = [a for a in state.latest_attestations if current_epoch == slot_to_epoch(a.data.slot)]`. (Note: this is the set of attestations of slots in the epoch `current_epoch`, _not_ attestations that got included in the chain during the epoch `current_epoch`.)
* Validators justifying the epoch boundary block at the start of the current epoch:
- * Let `current_epoch_boundary_attestations = [a for a in current_epoch_attestations if a.data.epoch_boundary_root == get_block_root(state, state.slot-EPOCH_LENGTH) and a.data.justified_slot == state.justified_slot]`.
+ * Let `current_epoch_boundary_attestations = [a for a in current_epoch_attestations if a.data.epoch_boundary_root == get_block_root(state, get_epoch_start_slot(current_epoch)) and a.data.justified_epoch == state.justified_epoch]`.
* Let `current_epoch_boundary_attester_indices` be the union of the [validator](#dfn-validator) index sets given by `[get_attestation_participants(state, a.data, a.aggregation_bitfield) for a in current_epoch_boundary_attestations]`.
* Let `current_epoch_boundary_attesting_balance = sum([get_effective_balance(state, i) for i in current_epoch_boundary_attester_indices])`.
[Validators](#dfn-Validator) attesting during the previous epoch:
+* Let `previous_total_balance = sum([get_effective_balance(state, i) for i in get_active_validator_indices(state.validator_registry, previous_epoch)])`.
* Validators that made an attestation during the previous epoch:
- * Let `previous_epoch_attestations = [a for a in state.latest_attestations if state.slot - 2 * EPOCH_LENGTH <= a.data.slot < state.slot - EPOCH_LENGTH]`.
+ * Let `previous_epoch_attestations = [a for a in state.latest_attestations if previous_epoch == slot_to_epoch(a.data.slot)]`.
* Let `previous_epoch_attester_indices` be the union of the validator index sets given by `[get_attestation_participants(state, a.data, a.aggregation_bitfield) for a in previous_epoch_attestations]`.
* Validators targeting the previous justified slot:
- * Let `previous_epoch_justified_attestations = [a for a in current_epoch_attestations + previous_epoch_attestations if a.data.justified_slot == state.previous_justified_slot]`.
+ * Let `previous_epoch_justified_attestations = [a for a in current_epoch_attestations + previous_epoch_attestations if a.data.justified_epoch == state.previous_justified_epoch]`.
* Let `previous_epoch_justified_attester_indices` be the union of the validator index sets given by `[get_attestation_participants(state, a.data, a.aggregation_bitfield) for a in previous_epoch_justified_attestations]`.
* Let `previous_epoch_justified_attesting_balance = sum([get_effective_balance(state, i) for i in previous_epoch_justified_attester_indices])`.
* Validators justifying the epoch boundary block at the start of the previous epoch:
- * Let `previous_epoch_boundary_attestations = [a for a in previous_epoch_justified_attestations if a.data.epoch_boundary_root == get_block_root(state, state.slot - 2 * EPOCH_LENGTH)]`.
+ * Let `previous_epoch_boundary_attestations = [a for a in previous_epoch_justified_attestations if a.data.epoch_boundary_root == get_block_root(state, get_epoch_start_slot(previous_epoch))]`.
* Let `previous_epoch_boundary_attester_indices` be the union of the validator index sets given by `[get_attestation_participants(state, a.data, a.aggregation_bitfield) for a in previous_epoch_boundary_attestations]`.
* Let `previous_epoch_boundary_attesting_balance = sum([get_effective_balance(state, i) for i in previous_epoch_boundary_attester_indices])`.
* Validators attesting to the expected beacon chain head during the previous epoch:
@@ -1624,9 +1805,9 @@ All [validators](#dfn-validator):
* Let `previous_epoch_head_attester_indices` be the union of the validator index sets given by `[get_attestation_participants(state, a.data, a.aggregation_bitfield) for a in previous_epoch_head_attestations]`.
* Let `previous_epoch_head_attesting_balance = sum([get_effective_balance(state, i) for i in previous_epoch_head_attester_indices])`.
-**Note**: `previous_epoch_boundary_attesting_balance` balance might be marginally different than `current_epoch_boundary_attesting_balance` during the previous epoch transition. Due to the tight bound on validator churn each epoch and small per-epoch rewards/penalties, the potential balance difference is very low and only marginally affects consensus safety.
+**Note**: `previous_total_balance` and `previous_epoch_boundary_attesting_balance` balance might be marginally different than the actual balances during previous epoch transition. Due to the tight bound on validator churn each epoch and small per-epoch rewards/penalties, the potential balance difference is very low and only marginally affects consensus safety.
-For every `slot in range(state.slot - 2 * EPOCH_LENGTH, state.slot)`, let `crosslink_committees_at_slot = get_crosslink_committees_at_slot(state, slot)`. For every `(crosslink_committee, shard)` in `crosslink_committees_at_slot`, compute:
+For every `slot in range(get_epoch_start_slot(previous_epoch), get_epoch_start_slot(next_epoch))`, let `crosslink_committees_at_slot = get_crosslink_committees_at_slot(state, slot)`. For every `(crosslink_committee, shard)` in `crosslink_committees_at_slot`, compute:
* Let `shard_block_root` be `state.latest_crosslinks[shard].shard_block_root`
* Let `attesting_validator_indices(crosslink_committee, shard_block_root)` be the union of the [validator](#dfn-validator) index sets given by `[get_attestation_participants(state, a.data, a.aggregation_bitfield) for a in current_epoch_attestations + previous_epoch_attestations if a.data.shard == shard and a.data.shard_block_root == shard_block_root]`.
@@ -1637,59 +1818,67 @@ For every `slot in range(state.slot - 2 * EPOCH_LENGTH, state.slot)`, let `cross
Define the following helpers to process attestation inclusion rewards and inclusion distance reward/penalty. For every attestation `a` in `previous_epoch_attestations`:
-* Let `inclusion_slot(state, index) = a.slot_included` for the attestation `a` where `index` is in `get_attestation_participants(state, a.data, a.aggregation_bitfield)`. If multiple attestations are applicable, the attestation with lowest `slot_included` is considered.
-* Let `inclusion_distance(state, index) = a.slot_included - a.data.slot` where `a` is the above attestation.
+* Let `inclusion_slot(state, index) = a.inclusion_slot` for the attestation `a` where `index` is in `get_attestation_participants(state, a.data, a.aggregation_bitfield)`. If multiple attestations are applicable, the attestation with lowest `inclusion_slot` is considered.
+* Let `inclusion_distance(state, index) = a.inclusion_slot - a.data.slot` where `a` is the above attestation.
-### Eth1 data
+#### Eth1 data
-If `state.slot % ETH1_DATA_VOTING_PERIOD == 0`:
+If `next_epoch % ETH1_DATA_VOTING_PERIOD == 0`:
-* Set `state.latest_eth1_data = eth1_data_vote.data` if `eth1_data_vote.vote_count * 2 > ETH1_DATA_VOTING_PERIOD` for some `eth1_data_vote` in `state.eth1_data_votes`.
+* If `eth1_data_vote.vote_count * 2 > ETH1_DATA_VOTING_PERIOD * EPOCH_LENGTH` for some `eth1_data_vote` in `state.eth1_data_votes` (ie. more than half the votes in this voting period were for that value), set `state.latest_eth1_data = eth1_data_vote.eth1_data`.
* Set `state.eth1_data_votes = []`.
-### Justification
+#### Justification
-* Set `state.previous_justified_slot = state.justified_slot`.
-* Set `state.justification_bitfield = (state.justification_bitfield * 2) % 2**64`.
-* Set `state.justification_bitfield |= 2` and `state.justified_slot = state.slot - 2 * EPOCH_LENGTH` if `3 * previous_epoch_boundary_attesting_balance >= 2 * total_balance`.
-* Set `state.justification_bitfield |= 1` and `state.justified_slot = state.slot - 1 * EPOCH_LENGTH` if `3 * current_epoch_boundary_attesting_balance >= 2 * total_balance`.
+First, update the justification bitfield:
-Set `state.finalized_slot = state.previous_justified_slot` if any of the following are true:
+* Let `new_justified_epoch = state.justified_epoch`.
+* Set `state.justification_bitfield = state.justification_bitfield << 1`.
+* Set `state.justification_bitfield |= 2` and `new_justified_epoch = previous_epoch` if `3 * previous_epoch_boundary_attesting_balance >= 2 * previous_total_balance`.
+* Set `state.justification_bitfield |= 1` and `new_justified_epoch = current_epoch` if `3 * current_epoch_boundary_attesting_balance >= 2 * current_total_balance`.
-* `state.previous_justified_slot == state.slot - 2 * EPOCH_LENGTH and state.justification_bitfield % 4 == 3`
-* `state.previous_justified_slot == state.slot - 3 * EPOCH_LENGTH and state.justification_bitfield % 8 == 7`
-* `state.previous_justified_slot == state.slot - 4 * EPOCH_LENGTH and state.justification_bitfield % 16 in (15, 14)`
+Next, update last finalized epoch if possible:
-### Crosslinks
+* Set `state.finalized_epoch = state.previous_justified_epoch` if `(state.justification_bitfield >> 1) % 8 == 0b111 and state.previous_justified_epoch == previous_epoch - 2`.
+* Set `state.finalized_epoch = state.previous_justified_epoch` if `(state.justification_bitfield >> 1) % 4 == 0b11 and state.previous_justified_epoch == previous_epoch - 1`.
+* Set `state.finalized_epoch = state.justified_epoch` if `(state.justification_bitfield >> 0) % 8 == 0b111 and state.justified_epoch == previous_epoch - 1`.
+* Set `state.finalized_epoch = state.justified_epoch` if `(state.justification_bitfield >> 0) % 4 == 0b11 and state.justified_epoch == previous_epoch`.
-For every `slot in range(state.slot - 2 * EPOCH_LENGTH, state.slot)`, let `crosslink_committees_at_slot = get_crosslink_committees_at_slot(state, slot)`. For every `(crosslink_committee, shard)` in `crosslink_committees_at_slot`, compute:
+Finally, update the following:
-* Set `state.latest_crosslinks[shard] = Crosslink(slot=state.slot, shard_block_root=winning_root(crosslink_committee))` if `3 * total_attesting_balance(crosslink_committee) >= 2 * total_balance(crosslink_committee)`.
+* Set `state.previous_justified_epoch = state.justified_epoch`.
+* Set `state.justified_epoch = new_justified_epoch`.
-### Rewards and penalties
+#### Crosslinks
+
+For every `slot in range(get_epoch_start_slot(previous_epoch), get_epoch_start_slot(next_epoch))`, let `crosslink_committees_at_slot = get_crosslink_committees_at_slot(state, slot)`. For every `(crosslink_committee, shard)` in `crosslink_committees_at_slot`, compute:
+
+* Set `state.latest_crosslinks[shard] = Crosslink(epoch=current_epoch, shard_block_root=winning_root(crosslink_committee))` if `3 * total_attesting_balance(crosslink_committee) >= 2 * total_balance(crosslink_committee)`.
+
+#### Rewards and penalties
First, we define some additional helpers:
-* Let `base_reward_quotient = integer_squareroot(total_balance) // BASE_REWARD_QUOTIENT`.
+* Let `base_reward_quotient = integer_squareroot(previous_total_balance) // BASE_REWARD_QUOTIENT`.
* Let `base_reward(state, index) = get_effective_balance(state, index) // base_reward_quotient // 5` for any validator with the given `index`.
* Let `inactivity_penalty(state, index, epochs_since_finality) = base_reward(state, index) + get_effective_balance(state, index) * epochs_since_finality // INACTIVITY_PENALTY_QUOTIENT // 2` for any validator with the given `index`.
-#### Justification and finalization
+##### Justification and finalization
Note: When applying penalties in the following balance recalculations implementers should make sure the `uint64` does not underflow.
-* Let `epochs_since_finality = (state.slot - state.finalized_slot) // EPOCH_LENGTH`.
+* Let `epochs_since_finality = next_epoch - state.finalized_epoch`.
Case 1: `epochs_since_finality <= 4`:
* Expected FFG source:
- * Any [validator](#dfn-validator) `index` in `previous_epoch_justified_attester_indices` gains `base_reward(state, index) * previous_epoch_justified_attesting_balance // total_balance`.
- * Any [active validator](#dfn-active-validator) `v` not in `previous_epoch_justified_attester_indices` loses `base_reward(state, index)`.
+ * Any [validator](#dfn-validator) `index` in `previous_epoch_justified_attester_indices` gains `base_reward(state, index) * previous_epoch_justified_attesting_balance // previous_total_balance`.
+ * Any [active validator](#dfn-active-validator) `index` not in `previous_epoch_justified_attester_indices` loses `base_reward(state, index)`.
* Expected FFG target:
- * Any [validator](#dfn-validator) `index` in `previous_epoch_boundary_attester_indices` gains `base_reward(state, index) * previous_epoch_boundary_attesting_balance // total_balance`.
+ * Any [validator](#dfn-validator) `index` in `previous_epoch_boundary_attester_indices` gains `base_reward(state, index) * previous_epoch_boundary_attesting_balance // previous_total_balance`.
* Any [active validator](#dfn-active-validator) `index` not in `previous_epoch_boundary_attester_indices` loses `base_reward(state, index)`.
* Expected beacon chain head:
- * Any [validator](#dfn-validator) `index` in `previous_epoch_head_attester_indices` gains `base_reward(state, index) * previous_epoch_head_attesting_balance // total_balance)`.
+ * Any [validator](#dfn-validator) `index` in `previous_epoch_head_attester_indices` gains `base_reward(state, index) * previous_epoch_head_attesting_balance // previous_total_balance)`.
* Any [active validator](#dfn-active-validator) `index` not in `previous_epoch_head_attester_indices` loses `base_reward(state, index)`.
* Inclusion distance:
* Any [validator](#dfn-validator) `index` in `previous_epoch_attester_indices` gains `base_reward(state, index) * MIN_ATTESTATION_INCLUSION_DELAY // inclusion_distance(state, index)`
@@ -1699,21 +1888,23 @@ Case 2: `epochs_since_finality > 4`:
* Any [active validator](#dfn-active-validator) `index` not in `previous_epoch_justified_attester_indices`, loses `inactivity_penalty(state, index, epochs_since_finality)`.
* Any [active validator](#dfn-active-validator) `index` not in `previous_epoch_boundary_attester_indices`, loses `inactivity_penalty(state, index, epochs_since_finality)`.
* Any [active validator](#dfn-active-validator) `index` not in `previous_epoch_head_attester_indices`, loses `base_reward(state, index)`.
-* Any [active_validator](#dfn-active-validator) `index` with `validator.penalized_slot <= state.slot`, loses `2 * inactivity_penalty(state, index, epochs_since_finality) + base_reward(state, index)`.
+* Any [active_validator](#dfn-active-validator) `index` with `validator.penalized_epoch <= current_epoch`, loses `2 * inactivity_penalty(state, index, epochs_since_finality) + base_reward(state, index)`.
* Any [validator](#dfn-validator) `index` in `previous_epoch_attester_indices` loses `base_reward(state, index) - base_reward(state, index) * MIN_ATTESTATION_INCLUSION_DELAY // inclusion_distance(state, index)`
-#### Attestation inclusion
+##### Attestation inclusion
For each `index` in `previous_epoch_attester_indices`, we determine the proposer `proposer_index = get_beacon_proposer_index(state, inclusion_slot(state, index))` and set `state.validator_balances[proposer_index] += base_reward(state, index) // INCLUDER_REWARD_QUOTIENT`.
-#### Crosslinks
+##### Crosslinks
-For every `slot in range(state.slot - 2 * EPOCH_LENGTH, state.slot - EPOCH_LENGTH)`, let `crosslink_committees_at_slot = get_crosslink_committees_at_slot(state, slot)`. For every `(crosslink_committee, shard)` in `crosslink_committees_at_slot`, compute:
+For every `slot in range(get_epoch_start_slot(previous_epoch), get_epoch_start_slot(current_epoch))`:
-* If `index in attesting_validators(crosslink_committee)`, `state.validator_balances[index] += base_reward(state, index) * total_attesting_balance(crosslink_committee) // total_balance(crosslink_committee))`.
-* If `index not in attesting_validators(crosslink_committee)`, `state.validator_balances[index] -= base_reward(state, index)`.
+* Let `crosslink_committees_at_slot = get_crosslink_committees_at_slot(state, slot)`.
+* For every `(crosslink_committee, shard)` in `crosslink_committees_at_slot`:
+ * If `index in attesting_validators(crosslink_committee)`, `state.validator_balances[index] += base_reward(state, index) * total_attesting_balance(crosslink_committee) // total_balance(crosslink_committee))`.
+ * If `index not in attesting_validators(crosslink_committee)`, `state.validator_balances[index] -= base_reward(state, index)`.
-### Ejections
+#### Ejections
* Run `process_ejections(state)`.
@@ -1723,22 +1914,24 @@ def process_ejections(state: BeaconState) -> None:
Iterate through the validator registry
and eject active validators with balance below ``EJECTION_BALANCE``.
"""
- for index in get_active_validator_indices(state.validator_registry, state.slot):
+ for index in get_active_validator_indices(state.validator_registry, current_epoch(state)):
if state.validator_balances[index] < EJECTION_BALANCE:
exit_validator(state, index)
```
-### Validator registry
+#### Validator registry and shuffling seed data
-First, update `previous_epoch_calculation_slot` and `previous_epoch_start_shard`:
+First, update the following:
-* Set `state.previous_epoch_calculation_slot = state.current_epoch_calculation_slot`
-* Set `state.previous_epoch_start_shard = state.current_epoch_start_shard`
+* Set `state.previous_calculation_epoch = state.current_calculation_epoch`.
+* Set `state.previous_epoch_start_shard = state.current_epoch_start_shard`.
+* Set `state.previous_epoch_seed = state.current_epoch_seed`.
+* Set `state.latest_index_roots[next_epoch % LATEST_INDEX_ROOTS_LENGTH] = hash_tree_root(get_active_validator_indices(state, next_epoch))`.
If the following are satisfied:
-* `state.finalized_slot > state.validator_registry_update_slot`
-* `state.latest_crosslinks[shard].slot > state.validator_registry_update_slot` for every shard number `shard` in `[(state.current_epoch_start_shard + i) % SHARD_COUNT for i in range(get_current_epoch_committee_count_per_slot(state) * EPOCH_LENGTH)]` (that is, for every shard in the current committees)
+* `state.finalized_epoch > state.validator_registry_update_epoch`
+* `state.latest_crosslinks[shard].epoch > state.validator_registry_update_epoch` for every shard number `shard` in `[(state.current_epoch_start_shard + i) % SHARD_COUNT for i in range(get_current_epoch_committee_count(state))]` (that is, for every shard in the current committees)
update the validator registry and associated fields by running
@@ -1748,8 +1941,9 @@ def update_validator_registry(state: BeaconState) -> None:
Update validator registry.
Note that this function mutates ``state``.
"""
+ current_epoch = get_current_epoch(state)
# The active validators
- active_validator_indices = get_active_validator_indices(state.validator_registry, state.slot)
+ active_validator_indices = get_active_validator_indices(state.validator_registry, current_epoch)
# The total effective balance of active validators
total_balance = sum([get_effective_balance(state, i) for i in active_validator_indices])
@@ -1762,19 +1956,19 @@ def update_validator_registry(state: BeaconState) -> None:
# Activate validators within the allowable balance churn
balance_churn = 0
for index, validator in enumerate(state.validator_registry):
- if validator.activation_slot > state.slot + ENTRY_EXIT_DELAY and state.validator_balances[index] >= MAX_DEPOSIT_AMOUNT:
+ if validator.activation_epoch > get_entry_exit_effect_epoch(current_epoch) and state.validator_balances[index] >= MAX_DEPOSIT_AMOUNT:
# Check the balance churn would be within the allowance
balance_churn += get_effective_balance(state, index)
if balance_churn > max_balance_churn:
break
# Activate validator
- activate_validator(state, index, False)
+ activate_validator(state, index, is_genesis=False)
# Exit validators within the allowable balance churn
balance_churn = 0
for index, validator in enumerate(state.validator_registry):
- if validator.exit_slot > state.slot + ENTRY_EXIT_DELAY and validator.status_flags & INITIATED_EXIT:
+ if validator.exit_epoch > get_entry_exit_effect_epoch(current_epoch) and validator.status_flags & INITIATED_EXIT:
# Check the balance churn would be within the allowance
balance_churn += get_effective_balance(state, index)
if balance_churn > max_balance_churn:
@@ -1783,50 +1977,60 @@ def update_validator_registry(state: BeaconState) -> None:
# Exit validator
exit_validator(state, index)
- state.validator_registry_update_slot = state.slot
+ state.validator_registry_update_epoch = current_epoch
```
and perform the following updates:
-* Set `state.previous_epoch_randao_mix = state.current_epoch_randao_mix`
-* Set `state.current_epoch_calculation_slot = state.slot`
-* Set `state.current_epoch_start_shard = (state.current_epoch_start_shard + get_current_epoch_committee_count_per_slot(state) * EPOCH_LENGTH) % SHARD_COUNT`
-* Set `state.current_epoch_randao_mix = get_randao_mix(state, state.current_epoch_calculation_slot - SEED_LOOKAHEAD)`
+* Set `state.current_calculation_epoch = next_epoch`
+* Set `state.current_epoch_start_shard = (state.current_epoch_start_shard + get_current_epoch_committee_count(state)) % SHARD_COUNT`
+* Set `state.current_epoch_seed = generate_seed(state, state.current_calculation_epoch)`
If a validator registry update does _not_ happen do the following:
-* Let `epochs_since_last_registry_change = (state.slot - state.validator_registry_update_slot) // EPOCH_LENGTH`.
-* If `epochs_since_last_registry_change` is an exact power of 2, set `state.current_epoch_calculation_slot = state.slot` and `state.current_epoch_randao_mix = get_randao_mix(state, state.current_epoch_calculation_slot - SEED_LOOKAHEAD)`. Note that `state.current_epoch_start_shard` is left unchanged.
+* Let `epochs_since_last_registry_update = current_epoch - state.validator_registry_update_epoch`.
+* If `epochs_since_last_registry_update` is an exact power of 2:
+ * Set `state.current_calculation_epoch = next_epoch`.
+ * Set `state.current_epoch_seed = generate_seed(state, state.current_calculation_epoch)`
+ * _Note_ that `state.current_epoch_start_shard` is left unchanged.
+
+**Invariant**: the active index root that is hashed into the shuffling seed actually is the `hash_tree_root` of the validator set that is used for that epoch.
Regardless of whether or not a validator set change happens, run the following:
```python
def process_penalties_and_exits(state: BeaconState) -> None:
+ """
+ Process the penalties and prepare the validators who are eligible to withdrawal.
+ Note that this function mutates ``state``.
+ """
+ current_epoch = get_current_epoch(state)
# The active validators
- active_validator_indices = get_active_validator_indices(state.validator_registry, state.slot)
+ active_validator_indices = get_active_validator_indices(state.validator_registry, current_epoch)
# The total effective balance of active validators
- total_balance = sum([get_effective_balance(state, i) for i in active_validator_indices])
+ total_balance = sum(get_effective_balance(state, i) for i in active_validator_indices)
for index, validator in enumerate(state.validator_registry):
- if (state.slot // EPOCH_LENGTH) == (validator.penalized_slot // EPOCH_LENGTH) + LATEST_PENALIZED_EXIT_LENGTH // 2:
- e = (state.slot // EPOCH_LENGTH) % LATEST_PENALIZED_EXIT_LENGTH
- total_at_start = state.latest_penalized_balances[(e + 1) % LATEST_PENALIZED_EXIT_LENGTH]
- total_at_end = state.latest_penalized_balances[e]
+ if current_epoch == validator.penalized_epoch + LATEST_PENALIZED_EXIT_LENGTH // 2:
+ epoch_index = current_epoch % LATEST_PENALIZED_EXIT_LENGTH
+ total_at_start = state.latest_penalized_balances[(epoch_index + 1) % LATEST_PENALIZED_EXIT_LENGTH]
+ total_at_end = state.latest_penalized_balances[epoch_index]
total_penalties = total_at_end - total_at_start
penalty = get_effective_balance(state, index) * min(total_penalties * 3, total_balance) // total_balance
state.validator_balances[index] -= penalty
def eligible(index):
validator = state.validator_registry[index]
- if validator.penalized_slot <= state.slot:
- PENALIZED_WITHDRAWAL_TIME = LATEST_PENALIZED_EXIT_LENGTH * EPOCH_LENGTH // 2
- return state.slot >= validator.penalized_slot + PENALIZED_WITHDRAWAL_TIME
+ if validator.penalized_epoch <= current_epoch:
+ penalized_withdrawal_epochs = LATEST_PENALIZED_EXIT_LENGTH // 2
+ return current_epoch >= validator.penalized_epoch + penalized_withdrawal_epochs
else:
- return state.slot >= validator.exit_slot + MIN_VALIDATOR_WITHDRAWAL_TIME
+ return current_epoch >= validator.exit_epoch + MIN_VALIDATOR_WITHDRAWAL_EPOCHS
all_indices = list(range(len(state.validator_registry)))
eligible_indices = filter(eligible, all_indices)
- sorted_indices = sorted(eligible_indices, key=lambda index: state.validator_registry[index].exit_count)
+ # Sort in order of exit epoch, and validators that exit within the same epoch exit in order of validator index
+ sorted_indices = sorted(eligible_indices, key=lambda index: state.validator_registry[index].exit_epoch)
withdrawn_so_far = 0
for index in sorted_indices:
prepare_validator_for_withdrawal(state, index)
@@ -1835,12 +2039,13 @@ def process_penalties_and_exits(state: BeaconState) -> None:
break
```
-### Final updates
+#### Final updates
-* Let `e = state.slot // EPOCH_LENGTH`. Set `state.latest_penalized_balances[(e+1) % LATEST_PENALIZED_EXIT_LENGTH] = state.latest_penalized_balances[e % LATEST_PENALIZED_EXIT_LENGTH]`
-* Remove any `attestation` in `state.latest_attestations` such that `attestation.data.slot < state.slot - EPOCH_LENGTH`.
+* Set `state.latest_penalized_balances[(next_epoch) % LATEST_PENALIZED_EXIT_LENGTH] = state.latest_penalized_balances[current_epoch % LATEST_PENALIZED_EXIT_LENGTH]`.
+* Set `state.latest_randao_mixes[next_epoch % LATEST_RANDAO_MIXES_LENGTH] = get_randao_mix(state, current_epoch)`.
+* Remove any `attestation` in `state.latest_attestations` such that `slot_to_epoch(attestation.data.slot) < current_epoch`.
-## State root processing
+### State root verification
Verify `block.state_root == hash_tree_root(state)` if there exists a `block` for the slot being processed.
diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md
index 8630c47c6..13cc47299 100644
--- a/specs/simple-serialize.md
+++ b/specs/simple-serialize.md
@@ -43,17 +43,19 @@ protocol for use in the Ethereum 2.0 Beacon Chain.
The core feature of `ssz` is the simplicity of the serialization with low
overhead.
-## Terminology
+## Variables and Functions
| Term | Definition |
|:-------------|:-----------------------------------------------------------------------------------------------|
| `little` | Little endian. |
-| `byte_order` | Specifies [endianness](https://en.wikipedia.org/wiki/Endianness): big endian or little endian. |
+| `byteorder` | Specifies [endianness](https://en.wikipedia.org/wiki/Endianness): big endian or little endian. |
| `len` | Length/number of bytes. |
-| `to_bytes` | Convert to bytes. Should take parameters ``size`` and ``byte_order``. |
-| `from_bytes` | Convert from bytes to object. Should take ``bytes`` and ``byte_order``. |
+| `to_bytes` | Convert to bytes. Should take parameters ``size`` and ``byteorder``. |
+| `from_bytes` | Convert from bytes to object. Should take ``bytes`` and ``byteorder``. |
| `value` | The value to serialize. |
| `rawbytes` | Raw serialized bytes. |
+| `deserialized_object` | The deserialized data in the data structure of your programming language. |
+| `new_index` | An index to keep track the latest position where the `rawbytes` have been deserialized. |
## Constants
@@ -72,7 +74,6 @@ overhead.
|:---------:|:-----------------------------------------------------------|
| `uintN` | Type of `N` bits unsigned integer, where ``N % 8 == 0``. |
-
Convert directly to bytes the size of the int. (e.g. ``uint16 = 2 bytes``)
All integers are serialized as **little endian**.
@@ -142,12 +143,8 @@ Lists are a collection of elements of the same homogeneous type.
|:--------------------------------------------|:----------------------------|
| Length of serialized list fits into 4 bytes | ``len(serialized) < 2**32`` |
-
-1. Get the number of raw bytes to serialize: it is ``len(list) * sizeof(element)``.
- * Encode that as a `4-byte` **little endian** `uint32`.
-2. Append the elements in a packed manner.
-
-* *Note on efficiency*: consider using a container that does not need to iterate over all elements to get its length. For example Python lists, C++ vectors or Rust Vec.
+1. Serialize all list elements individually and concatenate them.
+2. Prefix the concatenation with its length encoded as a `4-byte` **little-endian** unsigned integer.
**Example in Python**
@@ -171,7 +168,6 @@ A container represents a heterogenous, associative collection of key-value pairs
To serialize a container, obtain the list of its field's names in the specified order. For each field name in this list, obtain the corresponding value and serialize it. Tightly pack the complete set of serialized values in the same order as the field names into a buffer. Calculate the size of this buffer of serialized bytes and encode as a `4-byte` **little endian** `uint32`. Prepend the encoded length to the buffer. The result of this concatenation is the final serialized value of the container.
-
| Check to perform | Code |
|:--------------------------------------------|:----------------------------|
| Length of serialized fields fits into 4 bytes | ``len(serialized) < 2**32`` |
@@ -219,14 +215,21 @@ The decoding requires knowledge of the type of the item to be decoded. When
performing decoding on an entire serialized string, it also requires knowledge
of the order in which the objects have been serialized.
-Note: Each return will provide ``deserialized_object, new_index`` keeping track
-of the new index.
+Note: Each return will provide:
+- `deserialized_object`
+- `new_index`
At each step, the following checks should be made:
| Check to perform | Check |
|:-------------------------|:-----------------------------------------------------------|
-| Ensure sufficient length | ``length(rawbytes) >= current_index + deserialize_length`` |
+| Ensure sufficient length | ``len(rawbytes) >= current_index + deserialize_length`` |
+
+At the final step, the following checks should be made:
+
+| Check to perform | Check |
+|:-------------------------|:-------------------------------------|
+| Ensure no extra length | `new_index == len(rawbytes)` |
#### uint
@@ -295,7 +298,7 @@ entire length of the list.
| Check to perform | code |
|:------------------------------------------|:----------------------------------------------------------------|
-| rawbytes has enough left for length | ``len(rawbytes) > current_index + LENGTH_BYTES`` |
+| ``rawbytes`` has enough left for length | ``len(rawbytes) > current_index + LENGTH_BYTES`` |
| list is not greater than serialized bytes | ``len(rawbytes) > current_index + LENGTH_BYTES + total_length`` |
```python
@@ -323,7 +326,7 @@ Instantiate a container with the full set of deserialized data, matching each me
| Check to perform | code |
|:------------------------------------------|:----------------------------------------------------------------|
-| rawbytes has enough left for length | ``len(rawbytes) > current_index + LENGTH_BYTES`` |
+| ``rawbytes`` has enough left for length | ``len(rawbytes) > current_index + LENGTH_BYTES`` |
| list is not greater than serialized bytes | ``len(rawbytes) > current_index + LENGTH_BYTES + total_length`` |
To deserialize:
@@ -442,6 +445,5 @@ return hash(b''.join([hash_tree_root(getattr(x, field)) for field in value.field
| Go | [ https://github.com/prysmaticlabs/prysm/tree/master/shared/ssz ](https://github.com/prysmaticlabs/prysm/tree/master/shared/ssz) | Go implementation of SSZ mantained by Prysmatic Labs |
| Swift | [ https://github.com/yeeth/SimpleSerialize.swift ](https://github.com/yeeth/SimpleSerialize.swift) | Swift implementation maintained SSZ |
-
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
diff --git a/specs/validator/0_beacon-chain-validator.md b/specs/validator/0_beacon-chain-validator.md
new file mode 100644
index 000000000..cacfebe7d
--- /dev/null
+++ b/specs/validator/0_beacon-chain-validator.md
@@ -0,0 +1,358 @@
+# 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.
+
+## 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)
+ - [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)
+ - [Exits](#exits)
+ - [Attestations](#attestations-1)
+ - [Attestation data](#attestation-data)
+ - [Slot](#slot-1)
+ - [Shard](#shard)
+ - [Beacon block root](#beacon-block-root)
+ - [Epoch boundary root](#epoch-boundary-root)
+ - [Shard block root](#shard-block-root)
+ - [Latest crosslink root](#latest-crosslink-root)
+ - [Justified epoch](#justified-epoch)
+ - [Justified block root](#justified-block-root)
+ - [Construct attestation](#construct-attestation)
+ - [Data](#data)
+ - [Aggregation bitfield](#aggregation-bitfield)
+ - [Custody bitfield](#custody-bitfield)
+ - [Aggregate signature](#aggregate-signature)
+ - [How to avoid slashing](#how-to-avoid-slashing)
+ - [Proposer slashing](#proposer-slashing)
+ - [Attester slashing](#attester-slashing)
+
+
+
+## Introduction
+
+This document represents the expected behavior of an "honest validator" with respect to Phase 0 of the Ethereum 2.0 protocol. This document does not distinguish between a "node" (ie. the functionality of following and reading the beacon chain) and a "validator client" (ie. the functionality of actively participating in consensus). The separation of concerns between these (potentially) two pieces of software is left as a design decision that is out of scope.
+
+A validator is an entity that participates in the consensus of the Ethereum 2.0 protocol. This is an optional role for users in which they can post ETH as collateral and verify and attest to the validity of blocks to seek financial returns in exchange for building and securing the protocol. This is similar to proof of work networks in which a miner provides collateral in the form of hardware/hash-power to seek returns in exchange for building and securing the protocol.
+
+## 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.
+
+## Constants
+
+### Misc
+
+| Name | Value | Unit | Duration |
+| - | - | :-: | :-: |
+| `ETH1_FOLLOW_DISTANCE` | `2**10` (= 1,024) | blocks | ~4 hours |
+
+## Becoming a validator
+
+### Initialization
+
+A validator must initialize many parameters locally before submitting a deposit and joining the validator registry.
+
+#### 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.
+
+#### BLS withdrawal key
+
+A secondary withdrawal private key, `withdrawal_privkey`, must also be securely generated along with the resultant `withdrawal_pubkey`. This `withdrawal_privkey` does not have to be available for signing during the normal lifetime of a validator and can live in "cold storage".
+
+The validator constructs their `withdrawal_credentials` via the following:
+* Set `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX_BYTE`.
+* Set `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]`.
+
+### 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`.
+
+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.
+* Set `deposit_input.proof_of_possession = EMPTY_SIGNATURE`.
+* Let `proof_of_possession` be the result of `bls_sign` of the `hash_tree_root(deposit_input)` with `domain=DOMAIN_DEPOSIT`.
+* Set `deposit_input.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.
+
+_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`.
+
+### Process deposit
+
+Deposits cannot be processed into the beacon chain until the eth1.0 block in which they were deposited or any of its descendants is added to the beacon chain `state.eth1_data`. This takes _a minimum_ of `ETH1_FOLLOW_DISTANCE` eth1.0 blocks (~4 hours) plus `ETH1_DATA_VOTING_PERIOD` epochs (~1.7 hours). Once the requisite eth1.0 data is added, the deposit will normally be added to a beacon chain block and processed into the `state.validator_registry` within an epoch or two. The validator is then in a queue to be activated.
+
+### 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.
+
+### 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 `ENTRY_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 epoch. Usage is as follows:
+
+```python
+validator = state.validator_registry[validator_index]
+is_active = is_active_validator(validator, epoch)
+```
+
+Once a validator is activated, the validator is assigned [responsibilities](#beacon-chain-responsibilities) until exited.
+
+_Note_: There is a maximum validator churn per finalized epoch so the delay until activation is variable depending upon finality, total active validator balance, and the number of validators in the queue to be activated.
+
+## Beacon chain responsibilities
+
+A validator has two primary responsibilities to the beacon chain -- [proposing blocks](block-proposal) and [creating attestations](attestations-1). Proposals happen infrequently, whereas attestations should be created once per epoch.
+
+### 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`. 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).
+
+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).
+
+#### Block header
+
+##### Slot
+
+Set `block.slot = slot` where `slot` is the current slot at which the validator has been selected to propose. The `parent` selected must satisfy that `parent.slot < block.slot`.
+
+_Note:_ there might be "skipped" slots between the `parent` and `block`. These skipped slots are processed in the state transition function without per-block processing.
+
+##### Parent root
+
+Set `block.parent_root = hash_tree_root(parent)`.
+
+##### State root
+
+Set `block.state_root = hash_tree_root(state)` of the resulting `state` of the `parent -> block` state transition.
+
+_Note_: To calculate `state_root`, the validator should first run the state transition function on an unsigned `block` containing a stub for the `state_root`. It is useful to be able to run a state transition function that does _not_ validate signatures for this purpose.
+
+##### Randao reveal
+
+Set `block.randao_reveal = epoch_signature` where `epoch_signature` is defined as:
+
+```python
+epoch_signature = bls_sign(
+ privkey=validator.privkey, # privkey store locally, not in state
+ message=int_to_bytes32(slot_to_epoch(block.slot)),
+ domain=get_domain(
+ fork=fork, # `fork` is the fork object at the slot `block.slot`
+ epoch=slot_to_epoch(block.slot),
+ domain_type=DOMAIN_RANDAO,
+ )
+)
+```
+
+##### Eth1 Data
+
+`block.eth1_data` is a mechanism used by block proposers vote on a recent Ethereum 1.0 block hash and an associated deposit root found in the Ethereum 1.0 deposit contract. When consensus is formed, `state.latest_eth1_data` is updated, and validator deposits up to this root can be processed. The deposit root can be calculated by calling the `get_deposit_root()` function of the deposit contract using the post-state of the block hash.
+
+* Let `D` be the set of `Eth1DataVote` objects `vote` in `state.eth1_data_votes` where:
+ * `vote.eth1_data.block_hash` is the hash of an eth1.0 block that is (i) part of the canonical chain, (ii) >= `ETH1_FOLLOW_DISTANCE` blocks behind the head, and (iii) newer than `state.latest_eth1_data.block_data`.
+ * `vote.eth1_data.deposit_root` is the deposit root of the eth1.0 deposit contract at the block defined by `vote.eth1_data.block_hash`.
+* If `D` is empty:
+ * Let `block_hash` be the block hash of the `ETH1_FOLLOW_DISTANCE`'th ancestor of the head of the canonical eth1.0 chain.
+ * Let `deposit_root` be the deposit root of the eth1.0 deposit contract in the post-state of the block referenced by `block_hash`
+* If `D` is nonempty:
+ * Let `best_vote` be the member of `D` that has the highest `vote.eth1_data.vote_count`, breaking ties by favoring block hashes with higher associated block height.
+ * Let `block_hash = best_vote.eth1_data.block_hash`.
+ * Let `deposit_root = best_vote.eth1_data.deposit_root`.
+* Set `block.eth1_data = Eth1Data(deposit_root=deposit_root, block_hash=block_hash)`.
+
+##### Signature
+
+Set `block.signature = signed_proposal_data` where `signed_proposal_data` is defined as:
+
+```python
+proposal_data = ProposalSignedData(
+ slot=slot,
+ shard=BEACON_CHAIN_SHARD_NUMBER,
+ block_root=hash_tree_root(block), # where `block.sigature == EMPTY_SIGNATURE
+)
+proposal_root = hash_tree_root(proposal_data)
+
+signed_proposal_data = bls_sign(
+ privkey=validator.privkey, # privkey store locally, not in state
+ message=proposal_root,
+ domain=get_domain(
+ fork=fork, # `fork` is the fork object at the slot `block.slot`
+ epoch=slot_to_epoch(block.slot),
+ domain_type=DOMAIN_PROPOSAL,
+ )
+)
+```
+
+#### Block body
+
+##### 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-1). 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-1). 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-1). To maximize profit, the validator should attempt to create 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
+
+Up to `MAX_DEPOSITS` [`Deposit`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#deposit) objects can be included in the `block`. These deposits 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-1).
+
+##### Exits
+
+Up to `MAX_EXITS` [`Exit`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#exit) 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#exits-1).
+
+### Attestations
+
+A validator is expected to create, sign, and broadcast an attestation during each epoch. The slot during which the validator performs this role is any slot at which `get_crosslink_committees_at_slot(state, slot)` contains a committee that contains `validator_index`.
+
+A validator should create and broadcast the attestation halfway through the `slot` during which the validator is assigned -- that is `SLOT_DURATION * 0.5` seconds after the start of `slot`.
+
+#### 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.
+
+##### Slot
+
+Set `attestation_data.slot = slot` where `slot` is the current slot of which the validator is a member of a committee.
+
+##### Shard
+
+Set `attestation_data.shard = shard` where `shard` is the shard associated with the validator's committee defined by `get_crosslink_committees_at_slot`.
+
+##### Beacon block root
+
+Set `attestation_data.beacon_block_root = hash_tree_root(head)` where `head` is the validator's view of the `head` block of the beacon chain during `slot`.
+
+##### Epoch boundary root
+
+Set `attestation_data.epoch_boundary_root = hash_tree_root(epoch_boundary)` where `epoch_boundary` is the block at the most recent epoch boundary in the chain defined by `head` -- i.e. the `BeaconBlock` where `block.slot == get_epoch_start_slot(head.slot)`.
+
+_Note:_ This can be looked up in the state using `get_block_root(state, get_epoch_start_slot(head.slot))`.
+
+##### Shard block root
+
+Set `attestation_data.shard_block_root = ZERO_HASH`.
+
+_Note:_ This is a stub for phase 0.
+
+##### Latest crosslink root
+
+Set `attestation_data.latest_crosslink_root = state.latest_crosslinks[shard].shard_block_root` where `state` is the beacon state at `head` and `shard` is the validator's assigned shard.
+
+##### Justified epoch
+
+Set `attestation_data.justified_epoch = state.justified_epoch` where `state` is the beacon state at `head`.
+
+##### Justified block root
+
+Set `attestation_data.justified_block_root = hash_tree_root(justified_block)` where `justified_block` is the block at `state.justified_epoch` in the chain defined by `head`.
+
+_Note:_ This can be looked up in the state using `get_block_root(state, justified_epoch)`.
+
+#### 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.
+
+##### Data
+
+Set `attestation.data = attestation_data` where `attestation_data` is the `AttestationData` object defined in the previous section, [attestation data](#attestation-data).
+
+##### Aggregation bitfield
+
+* Let `aggregation_bitfield` be a byte array filled with zeros of length `(len(committee) + 7) // 8`.
+* Let `index_into_committee` be the index into the validator's `committee` at which `validator_index` is located.
+* Set `aggregation_bitfield[index_into_committee // 8] |= 2 ** (index_into_committee % 8)`.
+* Set `attestation.aggregation_bitfield = aggregation_bitfield`.
+
+_Note_: Calling `get_attestation_participants(state, attestation.data, attestation.aggregation_bitfield)` should return a list of length equal to 1, containing `validator_index`.
+
+##### Custody bitfield
+
+* Let `custody_bitfield` be a byte array filled with zeros of length `(len(committee) + 7) // 8`.
+* Set `attestation.custody_bitfield = custody_bitfield`.
+
+_Note:_ This is a stub for phase 0.
+
+##### Aggregate signature
+
+Set `attestation.aggregate_signature = signed_attestation_data` where `signed_attestation_data` is defined as:
+
+```python
+attestation_data_and_custody_bit = AttestationDataAndCustodyBit(
+ data=attestation.data,
+ custody_bit=0b0,
+)
+attestation_message_to_sign = hash_tree_root(attestation_data_and_custody_bit)
+
+signed_attestation_data = bls_sign(
+ privkey=validator.privkey, # privkey store locally, not in state
+ message=attestation_message_to_sign,
+ domain=get_domain(
+ fork=fork, # `fork` is the fork object at the slot, `attestation_data.slot`
+ epoch=slot_to_epoch(attestation_data.slot),
+ domain_type=DOMAIN_ATTESTATION,
+ )
+)
+```
+
+## How to avoid slashing
+
+"Slashing" is the burning of some amount of validator funds and immediate ejection from the active validator set. In Phase 0, there are two ways in which funds can be slashed -- [proposer slashing](#proposer-slashing) and [attester slashing](#attester-slashing). Although being slashed has serious repercussions, it is simple enough to avoid being slashed all together by remaining _consistent_ with respect to the messages a validator has previously signed.
+
+_Note_: Signed data must be within a sequential `Fork` context to conflict. Messages cannot be slashed across diverging forks. If the previous fork version is 1 and the chain splits into fork 2 and 102, messages from 1 can slashable against messages in forks 1, 2, and 102. Messages in 2 cannot be slashable against messages in 102 and vice versa.
+
+### Proposer slashing
+
+To avoid "proposer slashings", a validator must not sign two conflicting [`ProposalSignedData`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#proposalsigneddata) where conflicting is defined as having the same `slot` and `shard` but a different `block_root`. In phase 0, proposals are only made for the beacon chain (`shard == BEACON_CHAIN_SHARD_NUMBER`).
+
+_In phase 0, as long as the validator does not sign two different beacon chain proposals for the same slot, the validator is safe against proposer slashings._
+
+Specifically, when signing an `BeaconBlock`, a validator should perform the following steps in the following order:
+1. Save a record to hard disk that an beacon block has been signed for the `slot=slot` and `shard=BEACON_CHAIN_SHARD_NUMBER`.
+2. Generate and broadcast the block.
+
+If the software crashes at some point within this routine, then when the validator comes back online the hard disk has the record of the _potentially_ signed/broadcast block and can effectively avoid slashing.
+
+### 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).
+
+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.justified_epoch` -- and target -- `slot_to_epoch(attestation_data.slot)`.
+2. Generate and broadcast attestation.
+
+If the software crashes at some point within this routine, then when the validator comes back online the hard disk has the record of the _potentially_ signed/broadcast attestation and can effectively avoid slashing.