eth2.0-specs/specs/core/0_beacon-chain.md

2078 lines
83 KiB
Markdown
Raw Normal View History

# Ethereum 2.0 Phase 0 -- The Beacon Chain
2018-09-20 05:20:49 +00:00
**NOTICE**: This document is a work in progress for researchers and implementers. It reflects recent spec changes and takes precedence over the Python proof-of-concept implementation [[python-poc]](#ref-python-poc).
2018-09-20 05:20:49 +00:00
2018-11-28 07:23:37 +00:00
## Table of contents
2018-12-01 05:29:19 +00:00
<!-- TOC -->
- [Ethereum 2.0 Phase 0 -- The Beacon Chain](#ethereum-20-phase-0----the-beacon-chain)
- [Table of contents](#table-of-contents)
- [Introduction](#introduction)
- [Notation](#notation)
- [Terminology](#terminology)
- [Constants](#constants)
- [Misc](#misc)
- [Deposit contract](#deposit-contract)
2019-02-06 16:34:19 +00:00
- [Gwei values](#gwei-values)
- [Initial values](#initial-values)
- [Time parameters](#time-parameters)
2019-01-28 00:25:29 +00:00
- [State list lengths](#state-list-lengths)
- [Reward and penalty quotients](#reward-and-penalty-quotients)
- [Max operations per block](#max-operations-per-block)
- [Signature domains](#signature-domains)
2018-12-01 05:29:19 +00:00
- [Data structures](#data-structures)
2019-03-07 18:02:13 +00:00
- [Misc dependencies](#misc-dependencies)
- [`Fork`](#fork)
2019-03-07 18:02:13 +00:00
- [`Crosslink`](#crosslink)
- [`Eth1Data`](#eth1data)
2019-03-07 18:02:13 +00:00
- [`AttestationData`](#attestationdata)
- [`AttestationDataAndCustodyBit`](#attestationdataandcustodybit)
2019-03-26 19:40:19 +00:00
- [`IndexedAttestation`](#indexedattestation)
2019-03-07 18:02:13 +00:00
- [`DepositData`](#depositdata)
- [`BeaconBlockHeader`](#beaconblockheader)
- [`Validator`](#validator)
- [`PendingAttestation`](#pendingattestation)
2019-03-08 17:13:05 +00:00
- [`HistoricalBatch`](#historicalbatch)
- [Beacon operations](#beacon-operations)
2019-03-07 18:02:13 +00:00
- [`ProposerSlashing`](#proposerslashing)
- [`AttesterSlashing`](#attesterslashing)
- [`Attestation`](#attestation)
- [`Deposit`](#deposit)
- [`VoluntaryExit`](#voluntaryexit)
- [`Transfer`](#transfer)
- [Beacon blocks](#beacon-blocks)
- [`BeaconBlockBody`](#beaconblockbody)
- [`BeaconBlock`](#beaconblock)
- [Beacon state](#beacon-state)
- [`BeaconState`](#beaconstate)
2019-01-19 07:58:24 +00:00
- [Custom Types](#custom-types)
- [Helper functions](#helper-functions)
2019-03-04 22:49:21 +00:00
- [`xor`](#xor)
- [`hash`](#hash)
- [`hash_tree_root`](#hash_tree_root)
2019-04-08 01:51:13 +00:00
- [`signing_root`](#signing_root)
- [`slot_to_epoch`](#slot_to_epoch)
2019-02-03 09:36:21 +00:00
- [`get_previous_epoch`](#get_previous_epoch)
- [`get_current_epoch`](#get_current_epoch)
- [`get_epoch_start_slot`](#get_epoch_start_slot)
- [`is_active_validator`](#is_active_validator)
2019-03-19 11:08:17 +00:00
- [`is_slashable_validator`](#is_slashable_validator)
- [`get_active_validator_indices`](#get_active_validator_indices)
2019-04-20 06:10:25 +00:00
- [`get_current_epoch_effective_balance`](#get_current_epoch_effective_balance)
2019-03-21 16:04:20 +00:00
- [`increase_balance`](#increase_balance)
- [`decrease_balance`](#decrease_balance)
2019-02-07 21:08:25 +00:00
- [`get_permuted_index`](#get_permuted_index)
- [`get_split_offset`](#get_split_offset)
- [`get_epoch_committee_count`](#get_epoch_committee_count)
- [`get_shard_delta`](#get_shard_delta)
- [`compute_committee`](#compute_committee)
- [`get_crosslink_committees_at_slot`](#get_crosslink_committees_at_slot)
- [`get_block_root`](#get_block_root)
2019-03-04 18:45:41 +00:00
- [`get_state_root`](#get_state_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)
- [`verify_merkle_branch`](#verify_merkle_branch)
2019-04-18 04:20:34 +00:00
- [`get_attesting_indices`](#get_attesting_indices)
- [`int_to_bytes1`, `int_to_bytes2`, ...](#int_to_bytes1-int_to_bytes2-)
2019-02-07 21:12:58 +00:00
- [`bytes_to_int`](#bytes_to_int)
- [`get_effective_balance`](#get_effective_balance)
2019-02-03 10:43:33 +00:00
- [`get_total_balance`](#get_total_balance)
- [`get_domain`](#get_domain)
- [`get_bitfield_bit`](#get_bitfield_bit)
- [`verify_bitfield`](#verify_bitfield)
2019-03-26 19:40:19 +00:00
- [`convert_to_indexed`](#convert_to_indexed)
- [`verify_indexed_attestation`](#verify_indexed_attestation)
- [`is_double_vote`](#is_double_vote)
- [`is_surround_vote`](#is_surround_vote)
- [`integer_squareroot`](#integer_squareroot)
2019-02-20 07:45:19 +00:00
- [`get_delayed_activation_exit_epoch`](#get_delayed_activation_exit_epoch)
2019-04-14 03:14:05 +00:00
- [`get_churn_limit`](#get_churn_limit)
- [`bls_verify`](#bls_verify)
- [`bls_verify_multiple`](#bls_verify_multiple)
- [`bls_aggregate_pubkeys`](#bls_aggregate_pubkeys)
2019-01-29 04:32:36 +00:00
- [Routines for updating validator status](#routines-for-updating-validator-status)
- [`activate_validator`](#activate_validator)
- [`initiate_validator_exit`](#initiate_validator_exit)
2019-02-12 12:24:19 +00:00
- [`slash_validator`](#slash_validator)
- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract)
- [Deposit arguments](#deposit-arguments)
- [Withdrawal credentials](#withdrawal-credentials)
- [`Deposit` logs](#deposit-logs)
2019-02-12 12:24:19 +00:00
- [`Eth2Genesis` log](#eth2genesis-log)
- [Vyper code](#vyper-code)
2019-02-12 12:24:19 +00:00
- [On genesis](#on-genesis)
2018-12-01 05:29:19 +00:00
- [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)
- [State caching](#state-caching)
2019-01-29 13:17:05 +00:00
- [Per-epoch processing](#per-epoch-processing)
2019-03-02 06:40:43 +00:00
- [Helper functions](#helper-functions-1)
- [Justification and finalization](#justification-and-finalization)
2019-01-29 13:17:05 +00:00
- [Crosslinks](#crosslinks)
- [Rewards and penalties](#rewards-and-penalties)
- [Registry updates](#registry-updates)
2019-04-06 10:07:03 +00:00
- [Slashings](#slashings)
2019-01-29 13:17:05 +00:00
- [Final updates](#final-updates)
2019-03-07 19:05:34 +00:00
- [Per-slot processing](#per-slot-processing)
- [Per-block processing](#per-block-processing)
- [Block header](#block-header)
- [RANDAO](#randao)
- [Eth1 data](#eth1-data)
- [Operations](#operations)
2019-03-08 17:34:51 +00:00
- [Proposer slashings](#proposer-slashings)
- [Attester slashings](#attester-slashings)
- [Attestations](#attestations)
- [Deposits](#deposits)
- [Voluntary exits](#voluntary-exits)
- [Transfers](#transfers)
2019-03-07 19:05:34 +00:00
- [State root verification](#state-root-verification)
2018-12-01 05:29:19 +00:00
<!-- /TOC -->
2018-11-28 07:23:37 +00:00
## Introduction
2018-09-20 05:20:49 +00:00
This document represents the specification for Phase 0 of Ethereum 2.0 -- The Beacon Chain.
At the core of Ethereum 2.0 is a system chain called the "beacon chain". The beacon chain stores and manages the registry of [validators](#dfn-validator). In the initial deployment phases of Ethereum 2.0, the only mechanism to become a [validator](#dfn-validator) is to make a one-way ETH transaction to a deposit contract on Ethereum 1.0. Activation as a [validator](#dfn-validator) happens when Ethereum 1.0 deposit receipts are processed by the beacon chain, the activation balance is reached, and a queuing process is completed. Exit is either voluntary or done forcibly as a penalty for misbehavior.
2018-09-20 05:20:49 +00:00
The primary source of load on the beacon chain is "attestations". Attestations are simultaneously availability votes for a shard block and proof-of-stake votes for a beacon block. A sufficient number of attestations for the same shard block create a "crosslink", confirming the shard segment up to that shard block into the beacon chain. Crosslinks also serve as infrastructure for asynchronous cross-shard communication.
2018-09-20 05:20:49 +00:00
2018-11-29 01:56:25 +00:00
## Notation
Code snippets appearing in `this style` are to be interpreted as Python code.
2018-11-28 07:23:37 +00:00
## Terminology
2018-09-20 05:20:49 +00:00
* **Validator** <a id="dfn-validator"></a> - a registered participant in the beacon chain. You can become one by sending ether into the Ethereum 1.0 deposit contract.
2019-01-28 19:16:11 +00:00
* **Active validator** <a id="dfn-active-validator"></a> - 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.
2018-11-30 17:31:09 +00:00
* **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.
2018-09-20 05:20:49 +00:00
* **Beacon chain** - the central PoS chain that is the base of the sharding system.
* **Shard chain** - one of the chains on which user transactions take place and account data is stored.
2018-12-14 04:01:32 +00:00
* **Block root** - a 32-byte Merkle root of a beacon chain block or shard chain block. Previously called "block hash".
* **Crosslink** - a set of signatures from a committee attesting to a block in a shard chain that can be included into the beacon chain. Crosslinks are the main means by which the beacon chain "learns about" the updated state of shard chains.
* **Slot** - a period during which one proposer has the ability to create a beacon chain block and some attesters have the ability to make attestations.
* **Epoch** - an aligned span of slots during which all [validators](#dfn-validator) get exactly one chance to make an attestation.
* **Finalized**, **justified** - see the [Casper FFG paper](https://arxiv.org/abs/1710.09437).
* **Withdrawal period** - the number of slots between a [validator](#dfn-validator) exit and the [validator](#dfn-validator) balance being withdrawable.
* **Genesis time** - the Unix time of the genesis beacon chain block at slot 0.
2018-09-20 05:20:49 +00:00
2018-11-28 07:23:37 +00:00
## Constants
2018-09-20 05:20:49 +00:00
2019-04-07 06:21:50 +00:00
Note: the default mainnet values for the constants are included here for spec-design purposes.
The different configurations for mainnet, testnets, and yaml-based testing can be found in the `configs/constant_presets/` directory.
These configurations are updated for releases, but may be out of sync during `dev` changes.
2019-04-03 02:35:40 +00:00
### Misc
2019-02-12 13:37:30 +00:00
| Name | Value |
| - | - |
2019-02-12 13:37:30 +00:00
| `SHARD_COUNT` | `2**10` (= 1,024) |
| `TARGET_COMMITTEE_SIZE` | `2**7` (= 128) |
2019-04-18 04:20:34 +00:00
| `MAX_INDICES_PER_ATTESTATION` | `2**12` (= 4,096) |
2019-04-14 03:14:05 +00:00
| `MIN_PER_EPOCH_CHURN_LIMIT` | `2**2` (= 4) |
2019-04-14 07:28:45 +00:00
| `CHURN_LIMIT_QUOTIENT` | `2**16` (= 65,536) |
2019-04-20 05:17:33 +00:00
| `BASE_REWARDS_PER_EPOCH` | `5` |
2019-02-12 13:37:30 +00:00
| `SHUFFLE_ROUND_COUNT` | 90 |
2019-03-16 12:46:45 +00:00
* 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 `SLOTS_PER_EPOCH * TARGET_COMMITTEE_SIZE`), the shuffling algorithm ensures committee sizes of at least `TARGET_COMMITTEE_SIZE`. (Unbiasable randomness with a Verifiable Delay Function (VDF) will improve committee robustness and lower the safe minimum committee size.)
### Deposit contract
2019-02-06 16:34:19 +00:00
| Name | Value |
| - | - |
| `DEPOSIT_CONTRACT_ADDRESS` | **TBD** |
| `DEPOSIT_CONTRACT_TREE_DEPTH` | `2**5` (= 32) |
### Gwei values
| Name | Value | Unit |
| - | - | :-: |
| `MIN_DEPOSIT_AMOUNT` | `2**0 * 10**9` (= 1,000,000,000) | Gwei |
| `MAX_DEPOSIT_AMOUNT` | `2**5 * 10**9` (= 32,000,000,000) | Gwei |
| `EJECTION_BALANCE` | `2**4 * 10**9` (= 16,000,000,000) | Gwei |
2019-03-12 10:02:52 +00:00
| `HIGH_BALANCE_INCREMENT` | `2**0 * 10**9` (= 1,000,000,000) | Gwei |
### Initial values
| Name | Value |
| - | - |
2019-04-11 12:28:42 +00:00
| `GENESIS_SLOT` | `0` |
| `GENESIS_EPOCH` | `0` |
2019-01-26 00:33:15 +00:00
| `FAR_FUTURE_EPOCH` | `2**64 - 1` |
| `ZERO_HASH` | `int_to_bytes32(0)` |
| `BLS_WITHDRAWAL_PREFIX_BYTE` | `int_to_bytes1(0)` |
### Time parameters
| Name | Value | Unit | Duration |
| - | - | :-: | :-: |
2019-02-12 22:38:29 +00:00
| `SECONDS_PER_SLOT` | `6` | seconds | 6 seconds |
| `MIN_ATTESTATION_INCLUSION_DELAY` | `2**2` (= 4) | slots | 24 seconds |
2019-02-12 22:38:29 +00:00
| `SLOTS_PER_EPOCH` | `2**6` (= 64) | slots | 6.4 minutes |
| `MIN_SEED_LOOKAHEAD` | `2**0` (= 1) | epochs | 6.4 minutes |
| `ACTIVATION_EXIT_DELAY` | `2**2` (= 4) | epochs | 25.6 minutes |
| `SLOTS_PER_ETH1_VOTING_PERIOD` | `2**10` (= 1,024) | slots | ~1.7 hours |
| `SLOTS_PER_HISTORICAL_ROOT` | `2**13` (= 8,192) | slots | ~13 hours |
| `MIN_VALIDATOR_WITHDRAWABILITY_DELAY` | `2**8` (= 256) | epochs | ~27 hours |
| `PERSISTENT_COMMITTEE_PERIOD` | `2**11` (= 2,048) | epochs | 9 days |
2019-04-13 01:56:55 +00:00
| `MAX_CROSSLINK_EPOCHS` | `2**6` (= 64) | epochs | ~7 hours |
2019-04-18 01:52:14 +00:00
| `MIN_EPOCHS_TO_INACTIVITY_PENALTY` | `2**2` (= 4) | epochs | 25.6 minutes |
2019-03-19 16:21:17 +00:00
* `MAX_CROSSLINK_EPOCHS` should be a small constant times `SHARD_COUNT // SLOTS_PER_EPOCH`
2019-01-28 00:25:29 +00:00
### State list lengths
| Name | Value | Unit | Duration |
| - | - | :-: | :-: |
| `LATEST_RANDAO_MIXES_LENGTH` | `2**13` (= 8,192) | epochs | ~36 days |
| `LATEST_ACTIVE_INDEX_ROOTS_LENGTH` | `2**13` (= 8,192) | epochs | ~36 days |
| `LATEST_SLASHED_EXIT_LENGTH` | `2**13` (= 8,192) | epochs | ~36 days |
### Reward and penalty quotients
2018-10-03 07:27:39 +00:00
| Name | Value |
| - | - |
2019-01-17 10:55:05 +00:00
| `BASE_REWARD_QUOTIENT` | `2**5` (= 32) |
| `WHISTLEBLOWING_REWARD_QUOTIENT` | `2**9` (= 512) |
2019-03-26 13:21:49 +00:00
| `PROPOSER_REWARD_QUOTIENT` | `2**3` (= 8) |
| `INACTIVITY_PENALTY_QUOTIENT` | `2**25` (= 33,554,432) |
| `MIN_PENALTY_QUOTIENT` | `2**5` (= 32) |
2018-10-03 07:27:39 +00:00
* The `BASE_REWARD_QUOTIENT` parameter dictates the per-epoch reward. It corresponds to ~2.54% annual interest assuming 10 million participating ETH in every epoch.
2019-03-20 08:16:39 +00:00
* The `INACTIVITY_PENALTY_QUOTIENT` equals `INVERSE_SQRT_E_DROP_TIME**2` where `INVERSE_SQRT_E_DROP_TIME := 2**12 epochs` (~18 days) is the time it takes the inactivity penalty to reduce the balance of non-participating [validators](#dfn-validator) to about `1/sqrt(e) ~= 60.6%`. Indeed, the balance retained by offline [validators](#dfn-validator) after `n` epochs is about `(1 - 1/INACTIVITY_PENALTY_QUOTIENT)**(n**2/2)` so after `INVERSE_SQRT_E_DROP_TIME` epochs it is roughly `(1 - 1/INACTIVITY_PENALTY_QUOTIENT)**(INACTIVITY_PENALTY_QUOTIENT/2) ~= 1/sqrt(e)`.
### Max operations per block
2018-10-04 13:16:31 +00:00
2018-12-07 01:02:23 +00:00
| Name | Value |
2018-12-07 01:07:26 +00:00
| - | - |
2018-12-07 01:02:23 +00:00
| `MAX_PROPOSER_SLASHINGS` | `2**4` (= 16) |
| `MAX_ATTESTER_SLASHINGS` | `2**0` (= 1) |
2018-12-07 01:02:23 +00:00
| `MAX_ATTESTATIONS` | `2**7` (= 128) |
| `MAX_DEPOSITS` | `2**4` (= 16) |
2019-02-12 12:24:19 +00:00
| `MAX_VOLUNTARY_EXITS` | `2**4` (= 16) |
| `MAX_TRANSFERS` | `2**4` (= 16) |
2018-10-04 13:16:31 +00:00
### Signature domains
2018-11-20 01:13:58 +00:00
2018-12-10 19:55:11 +00:00
| Name | Value |
| - | - |
2019-03-31 16:48:44 +00:00
| `DOMAIN_BEACON_PROPOSER` | `0` |
2019-03-03 11:04:28 +00:00
| `DOMAIN_RANDAO` | `1` |
| `DOMAIN_ATTESTATION` | `2` |
| `DOMAIN_DEPOSIT` | `3` |
| `DOMAIN_VOLUNTARY_EXIT` | `4` |
| `DOMAIN_TRANSFER` | `5` |
## Data structures
2019-04-12 23:33:53 +00:00
The following data structures are defined as [SimpleSerialize (SSZ)](../simple-serialize.md) objects.
2019-01-19 07:58:24 +00:00
2019-03-07 18:02:13 +00:00
The types are defined topologically to aid in facilitating an executable version of the spec.
2019-03-07 18:02:13 +00:00
### Misc dependencies
2019-03-07 18:02:13 +00:00
#### `Fork`
```python
{
2019-03-07 18:02:13 +00:00
# Previous fork version
'previous_version': 'bytes4',
2019-03-07 18:02:13 +00:00
# Current fork version
'current_version': 'bytes4',
2019-03-07 18:02:13 +00:00
# Fork epoch number
'epoch': 'uint64',
}
```
2019-03-07 18:02:13 +00:00
#### `Crosslink`
2018-09-20 05:20:49 +00:00
```python
{
2019-03-07 18:02:13 +00:00
# Epoch number
'epoch': 'uint64',
# Root of the previous crosslink
'previous_crosslink_root': 'bytes32',
2019-03-07 18:02:13 +00:00
# Shard data since the previous crosslink
'crosslink_data_root': 'bytes32',
2018-12-06 23:51:01 +00:00
}
```
2019-03-07 18:02:13 +00:00
#### `Eth1Data`
2018-12-06 23:51:01 +00:00
```python
{
2019-03-07 18:02:13 +00:00
# Root of the deposit tree
'deposit_root': 'bytes32',
# Total number of deposits
'deposit_count': 'uint64',
2019-03-07 18:02:13 +00:00
# Block hash
'block_hash': 'bytes32',
2018-12-06 23:51:01 +00:00
}
```
2019-03-07 18:02:13 +00:00
#### `AttestationData`
```python
{
2019-03-12 10:17:34 +00:00
# LMD GHOST vote
'slot': 'uint64',
2019-01-17 08:33:59 +00:00
'beacon_block_root': 'bytes32',
2019-03-12 10:17:34 +00:00
# FFG vote
'source_epoch': 'uint64',
'source_root': 'bytes32',
'target_root': 'bytes32',
# Crosslink vote
'shard': 'uint64',
'previous_crosslink_root': 'bytes32',
'crosslink_data_root': 'bytes32',
}
```
2019-03-07 18:02:13 +00:00
#### `AttestationDataAndCustodyBit`
```python
{
# Attestation data
2019-01-23 09:57:48 +00:00
'data': AttestationData,
# Custody bit
'custody_bit': 'bool',
}
```
2019-03-26 19:40:19 +00:00
#### `IndexedAttestation`
2018-12-07 01:02:23 +00:00
2019-03-07 18:02:13 +00:00
```python
{
# Validator indices
'custody_bit_0_indices': ['uint64'],
'custody_bit_1_indices': ['uint64'],
2019-03-07 18:02:13 +00:00
# Attestation data
'data': AttestationData,
# Aggregate signature
2019-04-17 00:16:01 +00:00
'signature': 'bytes96',
2019-03-07 18:02:13 +00:00
}
```
2019-03-15 11:18:06 +00:00
#### `DepositData`
```python
{
2019-03-07 18:02:13 +00:00
# BLS pubkey
'pubkey': 'bytes48',
# Withdrawal credentials
'withdrawal_credentials': 'bytes32',
# Amount in Gwei
'amount': 'uint64',
2019-03-15 11:18:06 +00:00
# Container self-signature
2019-03-31 16:45:57 +00:00
'signature': 'bytes96',
}
```
2019-03-07 18:02:13 +00:00
#### `BeaconBlockHeader`
```python
{
2019-03-07 18:02:13 +00:00
'slot': 'uint64',
'previous_block_root': 'bytes32',
'state_root': 'bytes32',
'block_body_root': 'bytes32',
'signature': 'bytes96',
}
```
#### `Validator`
```python
{
# BLS public key
'pubkey': 'bytes48',
# Withdrawal credentials
2019-01-17 08:33:59 +00:00
'withdrawal_credentials': 'bytes32',
2019-03-28 13:58:18 +00:00
# Epoch when became eligible for activation
'activation_eligibility_epoch': 'uint64',
2019-03-07 18:02:13 +00:00
# Epoch when validator activated
'activation_epoch': 'uint64',
# Epoch when validator exited
'exit_epoch': 'uint64',
# Epoch when validator is eligible to withdraw
'withdrawable_epoch': 'uint64',
# Was the validator slashed
'slashed': 'bool',
# Rounded balance
2019-04-20 05:17:33 +00:00
'effective_balance': 'uint64',
2019-03-07 18:02:13 +00:00
}
```
#### `PendingAttestation`
```python
{
# Attester aggregation bitfield
'aggregation_bitfield': 'bytes',
# Attestation data
'data': AttestationData,
# Inclusion slot
'inclusion_slot': 'uint64',
}
```
2019-03-08 17:13:05 +00:00
#### `HistoricalBatch`
```python
{
2019-03-08 17:14:00 +00:00
# Block roots
2019-03-08 17:13:05 +00:00
'block_roots': ['bytes32', SLOTS_PER_HISTORICAL_ROOT],
2019-03-08 17:14:00 +00:00
# State roots
2019-03-08 17:13:05 +00:00
'state_roots': ['bytes32', SLOTS_PER_HISTORICAL_ROOT],
}
```
### Beacon operations
2019-03-07 18:02:13 +00:00
#### `ProposerSlashing`
```python
{
# Proposer index
'proposer_index': 'uint64',
# First block header
'header_1': BeaconBlockHeader,
# Second block header
'header_2': BeaconBlockHeader,
}
```
#### `AttesterSlashing`
```python
{
# First attestation
2019-03-26 19:40:19 +00:00
'attestation_1': IndexedAttestation,
# Second attestation
2019-03-26 19:40:19 +00:00
'attestation_2': IndexedAttestation,
2019-03-07 18:02:13 +00:00
}
```
#### `Attestation`
```python
{
# Attester aggregation bitfield
'aggregation_bitfield': 'bytes',
# Attestation data
'data': AttestationData,
# Custody bitfield
'custody_bitfield': 'bytes',
# BLS aggregate signature
2019-04-17 00:16:01 +00:00
'signature': 'bytes96',
}
```
2019-03-07 18:02:13 +00:00
#### `Deposit`
2019-03-07 18:02:13 +00:00
```python
{
# Branch in the deposit tree
'proof': ['bytes32', DEPOSIT_CONTRACT_TREE_DEPTH],
# Index in the deposit tree
'index': 'uint64',
# Data
2019-03-15 11:18:06 +00:00
'data': DepositData,
2019-03-07 18:02:13 +00:00
}
```
#### `VoluntaryExit`
2018-12-07 01:02:23 +00:00
```python
{
2019-01-26 22:27:50 +00:00
# Minimum epoch for processing exit
'epoch': 'uint64',
2018-12-07 01:02:23 +00:00
# Index of the exiting validator
2019-01-27 09:01:11 +00:00
'validator_index': 'uint64',
2018-12-07 01:02:23 +00:00
# Validator signature
2019-01-17 19:19:38 +00:00
'signature': 'bytes96',
2018-12-07 01:02:23 +00:00
}
```
2019-03-07 18:02:13 +00:00
#### `Transfer`
```python
{
# Sender index
'sender': 'uint64',
# Recipient index
'recipient': 'uint64',
# Amount in Gwei
'amount': 'uint64',
# Fee in Gwei for block proposer
'fee': 'uint64',
# Inclusion slot
'slot': 'uint64',
# Sender withdrawal pubkey
'pubkey': 'bytes48',
# Sender signature
'signature': 'bytes96',
}
```
2019-03-07 18:02:13 +00:00
### Beacon blocks
2018-12-07 01:02:23 +00:00
2019-03-07 18:02:13 +00:00
#### `BeaconBlockBody`
```python
{
2019-03-07 18:02:13 +00:00
'randao_reveal': 'bytes96',
'eth1_data': Eth1Data,
'proposer_slashings': [ProposerSlashing],
'attester_slashings': [AttesterSlashing],
'attestations': [Attestation],
'deposits': [Deposit],
'voluntary_exits': [VoluntaryExit],
'transfers': [Transfer],
2019-03-03 11:04:28 +00:00
}
```
2019-03-07 18:02:13 +00:00
#### `BeaconBlock`
2019-03-03 11:04:28 +00:00
```python
{
2019-03-07 18:02:13 +00:00
# Header
2019-03-03 11:04:28 +00:00
'slot': 'uint64',
'previous_block_root': 'bytes32',
'state_root': 'bytes32',
2019-03-07 18:02:13 +00:00
'body': BeaconBlockBody,
2019-02-15 00:23:03 +00:00
'signature': 'bytes96',
}
```
2019-03-07 18:02:13 +00:00
### Beacon state
2018-09-20 05:20:49 +00:00
#### `BeaconState`
2018-09-20 05:20:49 +00:00
```python
{
# Misc
'slot': 'uint64',
'genesis_time': 'uint64',
'fork': Fork, # For versioning hard forks
# Validator registry
2019-01-17 11:01:13 +00:00
'validator_registry': [Validator],
2019-03-12 15:58:31 +00:00
'balances': ['uint64'],
# Randomness and committees
'latest_randao_mixes': ['bytes32', LATEST_RANDAO_MIXES_LENGTH],
2019-03-19 16:21:17 +00:00
'latest_start_shard': 'uint64',
# Finality
2019-03-03 10:28:13 +00:00
'previous_epoch_attestations': [PendingAttestation],
'current_epoch_attestations': [PendingAttestation],
'previous_justified_epoch': 'uint64',
2019-03-12 10:17:34 +00:00
'current_justified_epoch': 'uint64',
'previous_justified_root': 'bytes32',
2019-03-12 10:17:34 +00:00
'current_justified_root': 'bytes32',
'justification_bitfield': 'uint64',
'finalized_epoch': 'uint64',
2019-03-12 10:26:34 +00:00
'finalized_root': 'bytes32',
# Recent state
2019-04-02 05:00:36 +00:00
'current_crosslinks': [Crosslink, SHARD_COUNT],
'previous_crosslinks': [Crosslink, SHARD_COUNT],
'latest_block_roots': ['bytes32', SLOTS_PER_HISTORICAL_ROOT],
'latest_state_roots': ['bytes32', SLOTS_PER_HISTORICAL_ROOT],
'latest_active_index_roots': ['bytes32', LATEST_ACTIVE_INDEX_ROOTS_LENGTH],
'latest_slashed_balances': ['uint64', LATEST_SLASHED_EXIT_LENGTH], # Balances slashed at every withdrawal period
2019-03-03 11:04:28 +00:00
'latest_block_header': BeaconBlockHeader, # `latest_block_header.state_root == ZERO_HASH` temporarily
2019-03-07 16:44:55 +00:00
'historical_roots': ['bytes32'],
# Ethereum 1.0 chain data
'latest_eth1_data': Eth1Data,
'eth1_data_votes': [Eth1Data],
2019-03-16 04:16:47 +00:00
'deposit_index': 'uint64',
2018-09-20 05:20:49 +00:00
}
```
2019-01-19 07:58:24 +00:00
## Custom Types
2019-01-19 07:58:24 +00:00
We define the following Python custom types for type hinting and readability:
2019-01-27 09:01:11 +00:00
| Name | SSZ equivalent | Description |
2019-01-19 07:58:24 +00:00
| - | - | - |
2019-01-31 15:58:31 +00:00
| `Slot` | `uint64` | a slot number |
| `Epoch` | `uint64` | an epoch number |
| `Shard` | `uint64` | a shard number |
2019-02-12 12:24:19 +00:00
| `ValidatorIndex` | `uint64` | a validator registry index |
2019-01-27 09:01:11 +00:00
| `Gwei` | `uint64` | an amount in Gwei |
| `Bytes32` | `bytes32` | 32 bytes of binary data |
2019-02-02 04:42:11 +00:00
| `BLSPubkey` | `bytes48` | a BLS12-381 public key |
| `BLSSignature` | `bytes96` | a BLS12-381 signature |
## Helper functions
Note: The definitions below are for specification purposes and are not necessarily optimal implementations.
2019-03-04 22:49:21 +00:00
### `xor`
```python
def xor(bytes1: Bytes32, bytes2: Bytes32) -> Bytes32:
return bytes(a ^ b for a, b in zip(bytes1, bytes2))
```
### `hash`
The `hash` function is SHA256.
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`
2019-04-12 23:33:53 +00:00
`def hash_tree_root(object: SSZSerializable) -> Bytes32` is a function for hashing objects into a single root utilizing a hash tree structure. `hash_tree_root` is defined in the [SimpleSerialize spec](../simple-serialize.md#merkleization).
2019-04-08 01:51:13 +00:00
### `signing_root`
2019-02-15 00:23:03 +00:00
2019-04-12 23:33:53 +00:00
`def signing_root(object: SSZContainer) -> Bytes32` is a function defined in the [SimpleSerialize spec](../simple-serialize.md#self-signed-containers) to compute signing messages.
2019-02-15 00:23:03 +00:00
### `slot_to_epoch`
```python
2019-01-31 15:58:31 +00:00
def slot_to_epoch(slot: Slot) -> Epoch:
2019-01-30 09:25:39 +00:00
"""
2019-01-30 15:01:38 +00:00
Return the epoch number of the given ``slot``.
2019-01-30 09:25:39 +00:00
"""
2019-02-12 22:38:29 +00:00
return slot // SLOTS_PER_EPOCH
```
2019-02-03 09:36:21 +00:00
### `get_previous_epoch`
```python
2019-02-12 12:24:19 +00:00
def get_previous_epoch(state: BeaconState) -> Epoch:
2019-02-03 09:36:21 +00:00
"""`
Return the previous epoch of the given ``state``.
Return the current epoch if it's genesis epoch.
2019-02-03 09:36:21 +00:00
"""
current_epoch = get_current_epoch(state)
return (current_epoch - 1) if current_epoch > GENESIS_EPOCH else current_epoch
2019-02-03 09:36:21 +00:00
```
### `get_current_epoch`
2018-09-20 05:20:49 +00:00
2019-01-26 14:31:09 +00:00
```python
2019-01-31 15:58:31 +00:00
def get_current_epoch(state: BeaconState) -> Epoch:
2019-01-30 09:25:39 +00:00
"""
2019-01-30 15:01:38 +00:00
Return the current epoch of the given ``state``.
2019-01-30 09:25:39 +00:00
"""
2019-01-26 14:31:09 +00:00
return slot_to_epoch(state.slot)
```
2018-09-20 05:20:49 +00:00
### `get_epoch_start_slot`
2019-01-27 14:54:46 +00:00
```python
2019-01-31 15:58:31 +00:00
def get_epoch_start_slot(epoch: Epoch) -> Slot:
2019-01-30 09:25:39 +00:00
"""
2019-01-30 15:01:38 +00:00
Return the starting slot of the given ``epoch``.
2019-01-30 09:25:39 +00:00
"""
2019-02-12 22:38:29 +00:00
return epoch * SLOTS_PER_EPOCH
2019-01-27 14:54:46 +00:00
```
2018-12-14 15:29:49 +00:00
### `is_active_validator`
2018-12-12 19:00:53 +00:00
```python
2019-01-31 15:58:31 +00:00
def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
"""
2019-01-30 15:01:38 +00:00
Check if ``validator`` is active.
"""
return validator.activation_epoch <= epoch < validator.exit_epoch
```
2019-03-19 11:08:17 +00:00
### `is_slashable_validator`
```python
def is_slashable_validator(validator: Validator, epoch: Epoch) -> bool:
"""
Check if ``validator`` is slashable.
"""
return (
validator.activation_epoch <= epoch < validator.withdrawable_epoch and
validator.slashed is False
)
```
### `get_active_validator_indices`
2018-09-20 05:20:49 +00:00
```python
2019-04-14 07:28:45 +00:00
def get_active_validator_indices(state: BeaconState, epoch: Epoch) -> List[ValidatorIndex]:
"""
2019-04-14 07:28:45 +00:00
Get active validator indices at ``epoch``.
"""
2019-04-14 07:28:45 +00:00
return [i for i, v in enumerate(state.validator_registry) if is_active_validator(v, epoch)]
2018-09-20 05:20:49 +00:00
```
2019-04-20 05:31:15 +00:00
### `get_current_epoch_effective_balance`
```python
2019-04-20 06:10:25 +00:00
def get_current_epoch_effective_balance(state: BeaconState, index: ValidatorIndex) -> Gwei:
2019-03-22 04:56:54 +00:00
"""
2019-04-20 06:32:41 +00:00
Get validator effective balance for the current epoch
2019-03-22 04:56:54 +00:00
"""
2019-04-20 05:17:33 +00:00
balance = min(state.balances[index], MAX_DEPOSIT_AMOUNT)
validator = state.validator_registry[index]
HALF_INCREMENT = HIGH_BALANCE_INCREMENT // 2
2019-04-20 06:32:41 +00:00
if state.slot == GENESIS_SLOT or (validator.effective_balance > balance or validator.effective_balance + 3 * HALF_INCREMENT < balance):
2019-04-20 05:17:33 +00:00
return balance - balance % HIGH_BALANCE_INCREMENT
return validator.effective_balance
2019-03-21 16:04:20 +00:00
```
2019-03-21 16:04:20 +00:00
### `increase_balance`
2019-03-21 16:04:20 +00:00
```python
2019-03-22 04:56:54 +00:00
def increase_balance(state: BeaconState, index: ValidatorIndex, delta: Gwei) -> None:
"""
2019-04-20 05:17:33 +00:00
Increase validator balance by ``delta``.
2019-03-22 04:56:54 +00:00
"""
2019-04-20 05:17:33 +00:00
state.balances[index] += delta
2019-03-21 16:04:20 +00:00
```
2019-03-21 16:04:20 +00:00
### `decrease_balance`
2019-03-21 16:04:20 +00:00
```python
2019-03-22 04:56:54 +00:00
def decrease_balance(state: BeaconState, index: ValidatorIndex, delta: Gwei) -> None:
"""
2019-04-20 05:17:33 +00:00
Decrease validator balance by ``delta`` with underflow protection.
2019-03-22 04:56:54 +00:00
"""
2019-04-20 05:17:33 +00:00
state.balances[index] = state.balances[index] - delta if state.balances[index] >= delta else 0
2019-03-21 16:04:20 +00:00
```
2019-02-07 21:08:25 +00:00
### `get_permuted_index`
2018-09-20 05:20:49 +00:00
```python
2019-02-08 03:55:33 +00:00
def get_permuted_index(index: int, list_size: int, seed: Bytes32) -> int:
2018-10-07 06:21:37 +00:00
"""
2019-03-20 08:16:39 +00:00
Return `p(index)` in a pseudorandom permutation `p` of `0...list_size - 1` with ``seed`` as entropy.
2018-10-07 06:21:37 +00:00
Utilizes 'swap or not' shuffling found in
https://link.springer.com/content/pdf/10.1007%2F978-3-642-32009-5_1.pdf
See the 'generalized domain' algorithm on page 3.
2018-10-07 06:21:37 +00:00
"""
assert index < list_size
assert list_size <= 2**40
2019-02-08 03:55:33 +00:00
for round in range(SHUFFLE_ROUND_COUNT):
pivot = bytes_to_int(hash(seed + int_to_bytes1(round))[0:8]) % list_size
2019-02-07 21:08:25 +00:00
flip = (pivot - index) % list_size
position = max(index, flip)
source = hash(seed + int_to_bytes1(round) + int_to_bytes4(position // 256))
byte = source[(position % 256) // 8]
bit = (byte >> (position % 8)) % 2
index = flip if bit else index
2018-10-07 06:21:37 +00:00
2019-02-07 21:08:25 +00:00
return index
2018-09-20 05:20:49 +00:00
```
### `get_split_offset`
2018-09-20 05:20:49 +00:00
```python
def get_split_offset(list_size: int, chunks: int, index: int) -> int:
"""
Returns a value such that for a list L, chunk count k and index i,
split(L, k)[i] == L[get_split_offset(len(L), k, i): get_split_offset(len(L), k, i+1)]
"""
return (list_size * index) // chunks
2018-09-20 05:20:49 +00:00
```
### `get_epoch_committee_count`
2019-01-08 00:53:33 +00:00
```python
def get_epoch_committee_count(state: BeaconState, epoch: Epoch) -> int:
2019-01-30 09:25:39 +00:00
"""
2019-01-30 15:01:38 +00:00
Return the number of committees in one epoch.
2019-01-30 09:25:39 +00:00
"""
2019-04-14 07:28:45 +00:00
active_validators = get_active_validator_indices(state, epoch)
2019-01-08 00:53:33 +00:00
return max(
1,
min(
2019-02-12 22:38:29 +00:00
SHARD_COUNT // SLOTS_PER_EPOCH,
len(active_validators) // SLOTS_PER_EPOCH // TARGET_COMMITTEE_SIZE,
2019-01-08 00:53:33 +00:00
)
2019-02-12 22:38:29 +00:00
) * SLOTS_PER_EPOCH
2019-01-08 00:53:33 +00:00
```
### `get_shard_delta`
```python
def get_shard_delta(state: BeaconState, epoch: Epoch) -> int:
return min(get_epoch_committee_count(state, epoch), SHARD_COUNT - SHARD_COUNT // SLOTS_PER_EPOCH)
```
### `compute_committee`
2018-09-20 05:20:49 +00:00
```python
2019-03-15 09:43:38 +00:00
def compute_committee(validator_indices: List[ValidatorIndex],
seed: Bytes32,
index: int,
total_committees: int) -> List[ValidatorIndex]:
"""
2019-03-15 09:45:20 +00:00
Return the ``index``'th shuffled committee out of a total ``total_committees``
using ``validator_indices`` and ``seed``.
"""
start_offset = get_split_offset(len(validator_indices), total_committees, index)
end_offset = get_split_offset(len(validator_indices), total_committees, index + 1)
return [
validator_indices[get_permuted_index(i, len(validator_indices), seed)]
for i in range(start_offset, end_offset)
]
2019-01-08 00:53:33 +00:00
```
2018-10-07 06:21:37 +00:00
Note: this definition and the next few definitions are highly inefficient as algorithms, as they re-calculate many sub-expressions. Production implementations are expected to appropriately use caching/memoization to avoid redoing work.
2018-10-14 13:30:52 +00:00
### `get_crosslink_committees_at_slot`
2018-09-20 05:20:49 +00:00
```python
2019-01-15 00:06:33 +00:00
def get_crosslink_committees_at_slot(state: BeaconState,
slot: Slot) -> List[Tuple[List[ValidatorIndex], Shard]]:
"""
2019-01-30 15:01:38 +00:00
Return the list of ``(committee, shard)`` tuples for the ``slot``.
"""
2019-01-26 22:39:57 +00:00
epoch = slot_to_epoch(slot)
current_epoch = get_current_epoch(state)
2019-02-03 09:36:21 +00:00
previous_epoch = get_previous_epoch(state)
2019-01-26 22:39:57 +00:00
next_epoch = current_epoch + 1
2019-01-08 00:53:33 +00:00
2019-01-30 00:29:51 +00:00
assert previous_epoch <= epoch <= next_epoch
2019-04-14 07:28:45 +00:00
indices = get_active_validator_indices(state, epoch)
2019-01-26 22:39:57 +00:00
if epoch == current_epoch:
2019-03-19 17:13:25 +00:00
start_shard = state.latest_start_shard
elif epoch == previous_epoch:
previous_shard_delta = get_shard_delta(state, previous_epoch)
start_shard = (state.latest_start_shard - previous_shard_delta) % SHARD_COUNT
2019-01-30 00:29:51 +00:00
elif epoch == next_epoch:
current_shard_delta = get_shard_delta(state, current_epoch)
start_shard = (state.latest_start_shard + current_shard_delta) % SHARD_COUNT
committees_per_epoch = get_epoch_committee_count(state, epoch)
2019-02-12 22:38:29 +00:00
committees_per_slot = committees_per_epoch // SLOTS_PER_EPOCH
offset = slot % SLOTS_PER_EPOCH
2019-03-19 17:13:25 +00:00
slot_start_shard = (start_shard + committees_per_slot * offset) % SHARD_COUNT
seed = generate_seed(state, epoch)
2019-01-08 00:53:33 +00:00
return [
(
compute_committee(indices, seed, committees_per_slot * offset + i, committees_per_epoch),
(slot_start_shard + i) % SHARD_COUNT,
)
for i in range(committees_per_slot)
]
```
2018-09-20 05:20:49 +00:00
### `get_block_root`
```python
2018-12-11 17:53:56 +00:00
def get_block_root(state: BeaconState,
2019-01-31 15:58:31 +00:00
slot: Slot) -> Bytes32:
"""
2019-01-30 15:01:38 +00:00
Return the block root at a recent ``slot``.
"""
2019-03-03 11:04:28 +00:00
assert slot < state.slot <= slot + SLOTS_PER_HISTORICAL_ROOT
return state.latest_block_roots[slot % SLOTS_PER_HISTORICAL_ROOT]
2018-09-20 05:20:49 +00:00
```
`get_block_root(_, s)` should always return `signing_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.
2018-09-20 05:20:49 +00:00
2019-03-04 18:45:41 +00:00
### `get_state_root`
```python
def get_state_root(state: BeaconState,
slot: Slot) -> Bytes32:
"""
Return the state root at a recent ``slot``.
"""
assert slot < state.slot <= slot + SLOTS_PER_HISTORICAL_ROOT
return state.latest_state_roots[slot % SLOTS_PER_HISTORICAL_ROOT]
```
### `get_randao_mix`
```python
def get_randao_mix(state: BeaconState,
2019-01-31 15:58:31 +00:00
epoch: Epoch) -> Bytes32:
"""
2019-01-30 15:01:38 +00:00
Return the randao mix at a recent ``epoch``.
"""
assert get_current_epoch(state) - LATEST_RANDAO_MIXES_LENGTH < epoch <= get_current_epoch(state)
2019-01-27 17:22:27 +00:00
return state.latest_randao_mixes[epoch % LATEST_RANDAO_MIXES_LENGTH]
```
### `get_active_index_root`
```python
def get_active_index_root(state: BeaconState,
2019-01-31 15:58:31 +00:00
epoch: Epoch) -> Bytes32:
"""
2019-01-30 15:01:38 +00:00
Return the index root at a recent ``epoch``.
"""
assert get_current_epoch(state) - LATEST_ACTIVE_INDEX_ROOTS_LENGTH + ACTIVATION_EXIT_DELAY < epoch <= get_current_epoch(state) + ACTIVATION_EXIT_DELAY
return state.latest_active_index_roots[epoch % LATEST_ACTIVE_INDEX_ROOTS_LENGTH]
```
### `generate_seed`
```python
def generate_seed(state: BeaconState,
2019-01-31 15:58:31 +00:00
epoch: Epoch) -> Bytes32:
"""
2019-01-26 00:33:15 +00:00
Generate a seed for the given ``epoch``.
"""
return hash(
get_randao_mix(state, epoch - MIN_SEED_LOOKAHEAD) +
get_active_index_root(state, epoch) +
int_to_bytes32(epoch)
)
```
### `get_beacon_proposer_index`
```python
2019-04-20 05:17:33 +00:00
def get_beacon_proposer_index(state: BeaconState, slot: Slot=None) -> ValidatorIndex:
"""
2019-04-20 05:17:33 +00:00
Return the beacon proposer index at ``slot``.
"""
2019-04-20 05:37:12 +00:00
epoch = slot_to_epoch(slot if slot != None else state.slot)
2019-04-20 05:17:33 +00:00
first_committee, _ = get_crosslink_committees_at_slot(state, slot if slot != None else state.slot)[0]
2019-03-14 18:57:17 +00:00
i = 0
while True:
2019-04-20 05:37:12 +00:00
candidate = first_committee[(epoch + i) % len(first_committee)]
random_byte = hash(generate_seed(state, epoch) + int_to_bytes8(i // 32))[i % 32]
if get_effective_balance(state, candidate, epoch) * 256 > MAX_DEPOSIT_AMOUNT * random_byte:
return candidate
i += 1
```
### `verify_merkle_branch`
```python
2019-03-02 01:01:40 +00:00
def verify_merkle_branch(leaf: Bytes32, proof: List[Bytes32], depth: int, index: int, root: Bytes32) -> bool:
"""
2019-03-02 01:01:40 +00:00
Verify that the given ``leaf`` is on the merkle branch ``proof``
starting with the given ``root``.
"""
value = leaf
for i in range(depth):
if index // (2**i) % 2:
2019-03-02 01:01:40 +00:00
value = hash(proof[i] + value)
else:
2019-03-02 01:01:40 +00:00
value = hash(value + proof[i])
return value == root
```
2019-04-18 04:20:34 +00:00
### `get_attesting_indices`
```python
2019-04-18 04:20:34 +00:00
def get_attesting_indices(state: BeaconState,
attestation_data: AttestationData,
bitfield: bytes) -> List[ValidatorIndex]:
2019-04-04 15:11:12 +00:00
"""
2019-04-18 04:20:34 +00:00
Return the sorted attesting indices corresponding to ``attestation_data`` and ``bitfield``.
"""
crosslink_committees = get_crosslink_committees_at_slot(state, attestation_data.slot)
crosslink_committee = [committee for committee, shard in crosslink_committees if shard == attestation_data.shard][0]
2019-01-26 18:59:07 +00:00
assert verify_bitfield(bitfield, len(crosslink_committee))
return sorted([index for i, index in enumerate(crosslink_committee) if get_bitfield_bit(bitfield, i) == 0b1])
```
### `int_to_bytes1`, `int_to_bytes2`, ...
2019-02-03 00:41:59 +00:00
`int_to_bytes1(x): return x.to_bytes(1, 'little')`, `int_to_bytes2(x): return x.to_bytes(2, 'little')`, and so on for all integers, particularly 1, 2, 3, 4, 8, 32, 48, 96.
2018-09-20 05:20:49 +00:00
2019-02-07 21:12:58 +00:00
### `bytes_to_int`
```python
def bytes_to_int(data: bytes) -> int:
return int.from_bytes(data, 'little')
```
2018-09-20 05:20:49 +00:00
### `get_effective_balance`
2018-11-25 11:33:05 +00:00
2018-12-01 05:29:19 +00:00
```python
2019-04-20 05:17:33 +00:00
def get_effective_balance(state: BeaconState, index: ValidatorIndex, epoch: Epoch) -> Gwei:
"""
Return the effective balance (also known as "balance at stake") for a validator with the given ``index``.
"""
2019-04-20 05:31:15 +00:00
return get_current_epoch_effective_balance(state, index) if epoch == get_current_epoch(state) else state.validator_registry[index].effective_balance
2018-11-25 11:33:05 +00:00
```
2019-02-03 10:43:33 +00:00
### `get_total_balance`
2019-02-03 10:14:02 +00:00
```python
2019-04-20 05:17:33 +00:00
def get_total_balance(state: BeaconState, validators: List[ValidatorIndex], epoch: Epoch) -> Gwei:
2019-02-03 10:14:02 +00:00
"""
2019-03-04 14:45:55 +00:00
Return the combined effective balance of an array of ``validators``.
2019-02-03 10:14:02 +00:00
"""
2019-04-20 06:10:25 +00:00
return sum([get_effective_balance(state, index, epoch) for index in validators])
2019-02-03 10:14:02 +00:00
```
### `get_domain`
```python
def get_domain(state: BeaconState,
domain_type: int,
2019-04-02 18:30:26 +00:00
message_epoch: int=None) -> int:
2019-01-30 09:25:39 +00:00
"""
2019-04-02 18:30:26 +00:00
Return the signature domain (fork version concatenated with domain type) of a message.
2019-01-30 09:25:39 +00:00
"""
2019-04-02 18:30:26 +00:00
epoch = get_current_epoch(state) if message_epoch is None else message_epoch
fork_version = state.fork.previous_version if epoch < state.fork.epoch else state.fork.current_version
return bytes_to_int(fork_version + int_to_bytes4(domain_type))
```
### `get_bitfield_bit`
2019-01-23 12:40:59 +00:00
```python
def get_bitfield_bit(bitfield: bytes, i: int) -> int:
2019-01-23 13:52:52 +00:00
"""
Extract the bit in ``bitfield`` at position ``i``.
"""
return (bitfield[i // 8] >> (i % 8)) % 2
2019-01-23 12:40:59 +00:00
```
### `verify_bitfield`
2019-01-23 12:40:59 +00:00
```python
2019-01-26 18:59:07 +00:00
def verify_bitfield(bitfield: bytes, committee_size: int) -> bool:
2019-01-23 13:52:52 +00:00
"""
2019-01-26 18:59:07 +00:00
Verify ``bitfield`` against the ``committee_size``.
2019-01-23 13:52:52 +00:00
"""
2019-01-26 18:59:07 +00:00
if len(bitfield) != (committee_size + 7) // 8:
2019-01-23 12:40:59 +00:00
return False
2019-02-05 19:51:06 +00:00
# Check `bitfield` is padded with zero bits only
2019-02-05 19:49:52 +00:00
for i in range(committee_size, len(bitfield) * 8):
2019-01-27 09:01:11 +00:00
if get_bitfield_bit(bitfield, i) == 0b1:
2019-01-23 12:40:59 +00:00
return False
return True
```
2019-03-26 19:40:19 +00:00
### `convert_to_indexed`
2018-12-07 01:02:23 +00:00
```python
def convert_to_indexed(state: BeaconState, attestation: Attestation) -> IndexedAttestation:
2019-01-23 13:52:52 +00:00
"""
2019-04-03 19:24:46 +00:00
Convert ``attestation`` to (almost) indexed-verifiable form.
2019-01-23 13:52:52 +00:00
"""
2019-04-18 04:20:34 +00:00
attesting_indices = get_attesting_indices(state, attestation.data, attestation.aggregation_bitfield)
custody_bit_1_indices = get_attesting_indices(state, attestation.data, attestation.custody_bitfield)
custody_bit_0_indices = [index for index in attesting_indices if index not in custody_bit_1_indices]
2019-03-26 19:40:19 +00:00
return IndexedAttestation(
custody_bit_0_indices=custody_bit_0_indices,
custody_bit_1_indices=custody_bit_1_indices,
data=attestation.data,
signature=attestation.signature,
)
```
2019-03-26 19:40:19 +00:00
### `verify_indexed_attestation`
```python
2019-03-26 19:40:19 +00:00
def verify_indexed_attestation(state: BeaconState, indexed_attestation: IndexedAttestation) -> bool:
"""
2019-03-26 19:40:19 +00:00
Verify validity of ``indexed_attestation`` fields.
"""
custody_bit_0_indices = indexed_attestation.custody_bit_0_indices
custody_bit_1_indices = indexed_attestation.custody_bit_1_indices
2019-04-18 04:20:34 +00:00
# Ensure no duplicate indices across custody bits
2019-04-03 00:04:12 +00:00
assert len(set(custody_bit_0_indices).intersection(set(custody_bit_1_indices))) == 0
if len(custody_bit_1_indices) > 0: # [TO BE REMOVED IN PHASE 1]
2019-01-23 13:24:35 +00:00
return False
2019-04-18 04:20:34 +00:00
if not (1 <= len(custody_bit_0_indices) + len(custody_bit_1_indices) <= MAX_INDICES_PER_ATTESTATION):
2019-01-23 13:24:35 +00:00
return False
if custody_bit_0_indices != sorted(custody_bit_0_indices):
2019-01-23 12:40:59 +00:00
return False
if custody_bit_1_indices != sorted(custody_bit_1_indices):
return False
2019-01-23 13:24:35 +00:00
return bls_verify_multiple(
pubkeys=[
2019-01-23 13:24:35 +00:00
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]),
],
message_hashes=[
2019-03-26 19:40:19 +00:00
hash_tree_root(AttestationDataAndCustodyBit(data=indexed_attestation.data, custody_bit=0b0)),
hash_tree_root(AttestationDataAndCustodyBit(data=indexed_attestation.data, custody_bit=0b1)),
],
2019-04-17 00:16:01 +00:00
signature=indexed_attestation.signature,
domain=get_domain(state, DOMAIN_ATTESTATION, slot_to_epoch(indexed_attestation.data.slot)),
)
2018-12-07 01:02:23 +00:00
```
### `is_double_vote`
```python
def is_double_vote(attestation_data_1: AttestationData,
2019-01-30 09:25:39 +00:00
attestation_data_2: AttestationData) -> bool:
"""
2019-01-30 19:04:35 +00:00
Check if ``attestation_data_1`` and ``attestation_data_2`` have the same target.
"""
2019-01-26 00:33:15 +00:00
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,
2018-12-19 11:47:37 +00:00
attestation_data_2: AttestationData) -> bool:
"""
Check if ``attestation_data_1`` surrounds ``attestation_data_2``.
"""
2019-03-12 10:17:34 +00:00
source_epoch_1 = attestation_data_1.source_epoch
source_epoch_2 = attestation_data_2.source_epoch
2019-01-26 00:33:15 +00:00
target_epoch_1 = slot_to_epoch(attestation_data_1.slot)
target_epoch_2 = slot_to_epoch(attestation_data_2.slot)
2019-01-30 14:46:43 +00:00
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``.
"""
2019-01-11 00:09:58 +00:00
assert n >= 0
x = n
y = (x + 1) // 2
while y < x:
x = y
y = (x + n // x) // 2
return x
```
2019-02-20 07:45:19 +00:00
### `get_delayed_activation_exit_epoch`
```python
2019-02-20 07:45:19 +00:00
def get_delayed_activation_exit_epoch(epoch: Epoch) -> Epoch:
"""
2019-02-20 07:45:19 +00:00
Return the epoch at which an activation or exit triggered in ``epoch`` takes effect.
"""
return epoch + 1 + ACTIVATION_EXIT_DELAY
```
2019-04-14 03:14:05 +00:00
### `get_churn_limit`
```python
def get_churn_limit(state: BeaconState) -> int:
return max(
MIN_PER_EPOCH_CHURN_LIMIT,
2019-04-14 07:28:45 +00:00
len(get_active_validator_indices(state, get_current_epoch(state))) // CHURN_LIMIT_QUOTIENT
2019-04-14 03:14:05 +00:00
)
2019-04-14 06:49:17 +00:00
```
2019-04-14 03:14:05 +00:00
### `bls_verify`
2018-12-10 22:14:08 +00:00
2019-04-12 23:33:53 +00:00
`bls_verify` is a function for verifying a BLS signature, defined in the [BLS Signature spec](../bls_signature.md#bls_verify).
### `bls_verify_multiple`
2019-04-12 23:33:53 +00:00
`bls_verify_multiple` is a function for verifying a BLS signature constructed from multiple messages, defined in the [BLS Signature spec](../bls_signature.md#bls_verify_multiple).
### `bls_aggregate_pubkeys`
2019-04-12 23:33:53 +00:00
`bls_aggregate_pubkeys` is a function for aggregating multiple BLS public keys into a single aggregate key, defined in the [BLS Signature spec](../bls_signature.md#bls_aggregate_pubkeys).
2018-12-10 22:14:08 +00:00
### Routines for updating validator status
Note: All functions in this section mutate `state`.
2018-12-10 22:42:28 +00:00
#### `activate_validator`
2018-12-10 21:16:06 +00:00
```python
2019-04-12 03:38:58 +00:00
def activate_validator(state: BeaconState, index: ValidatorIndex) -> None:
2019-01-30 09:25:39 +00:00
"""
Activate the validator of the given ``index``.
Note that this function mutates ``state``.
"""
validator = state.validator_registry[index]
2019-04-12 03:38:58 +00:00
if state.slot == GENESIS_SLOT:
2019-04-06 22:45:43 +00:00
validator.activation_eligibility_epoch = GENESIS_EPOCH
validator.activation_epoch = GENESIS_EPOCH
else:
validator.activation_epoch = get_delayed_activation_exit_epoch(get_current_epoch(state))
```
#### `initiate_validator_exit`
2018-12-10 21:16:06 +00:00
```python
2019-01-19 07:58:24 +00:00
def initiate_validator_exit(state: BeaconState, index: ValidatorIndex) -> None:
2019-01-30 09:25:39 +00:00
"""
Initiate the validator of the given ``index``.
Note that this function mutates ``state``.
"""
2019-04-14 09:01:53 +00:00
# Return if validator already initiated exit
validator = state.validator_registry[index]
2019-04-13 23:13:53 +00:00
if validator.exit_epoch != FAR_FUTURE_EPOCH:
return
2019-04-14 09:01:53 +00:00
# Compute exit queue epoch
exit_epochs = [v.exit_epoch for v in state.validator_registry if v.exit_epoch != FAR_FUTURE_EPOCH]
2019-04-14 09:14:27 +00:00
exit_queue_epoch = sorted(exit_epochs + [get_delayed_activation_exit_epoch(get_current_epoch(state))])[-1]
2019-04-14 08:10:44 +00:00
exit_queue_churn = len([v for v in state.validator_registry if v.exit_epoch == exit_queue_epoch])
2019-04-14 08:50:05 +00:00
if exit_queue_churn >= get_churn_limit(state):
2019-04-14 08:10:44 +00:00
exit_queue_epoch += 1
2018-12-11 15:49:50 +00:00
2019-04-13 23:13:53 +00:00
# Set validator exit epoch and withdrawable epoch
2019-04-14 08:10:44 +00:00
validator.exit_epoch = exit_queue_epoch
2019-04-13 23:13:53 +00:00
validator.withdrawable_epoch = validator.exit_epoch + MIN_VALIDATOR_WITHDRAWABILITY_DELAY
```
2019-02-12 12:24:19 +00:00
#### `slash_validator`
```python
def slash_validator(state: BeaconState, slashed_index: ValidatorIndex, whistleblower_index: ValidatorIndex=None) -> None:
2019-01-30 09:25:39 +00:00
"""
Slash the validator with index ``slashed_index``.
2019-01-30 09:25:39 +00:00
Note that this function mutates ``state``.
"""
2019-04-20 05:17:33 +00:00
current_epoch = get_current_epoch(state)
2019-03-29 07:26:26 +00:00
initiate_validator_exit(state, slashed_index)
state.validator_registry[slashed_index].slashed = True
2019-04-20 05:17:33 +00:00
state.validator_registry[slashed_index].withdrawable_epoch = current_epoch + LATEST_SLASHED_EXIT_LENGTH
slashed_balance = get_effective_balance(state, slashed_index, current_epoch)
state.latest_slashed_balances[current_epoch % LATEST_SLASHED_EXIT_LENGTH] += slashed_balance
proposer_index = get_beacon_proposer_index(state)
if whistleblower_index is None:
whistleblower_index = proposer_index
whistleblowing_reward = slashed_balance // WHISTLEBLOWING_REWARD_QUOTIENT
proposer_reward = whistleblowing_reward // PROPOSER_REWARD_QUOTIENT
increase_balance(state, proposer_index, proposer_reward)
increase_balance(state, whistleblower_index, whistleblowing_reward - proposer_reward)
2019-03-25 14:54:43 +00:00
decrease_balance(state, slashed_index, whistleblowing_reward)
```
## 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.
### Deposit arguments
2019-03-15 11:18:06 +00:00
The deposit contract has a single `deposit` function which takes as argument a SimpleSerialize'd `DepositData`.
### Withdrawal credentials
2019-03-15 11:18:06 +00:00
One of the `DepositData` fields is `withdrawal_credentials`. It is a commitment to credentials for withdrawals to shards. The first byte of `withdrawal_credentials` is a version number. As of now the only expected format is as follows:
* `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX_BYTE`
* `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey
The private key corresponding to `withdrawal_pubkey` will be required to initiate a withdrawal. It can be stored separately until a withdrawal is required, e.g. in cold storage.
### `Deposit` logs
Every Ethereum 1.0 deposit, of size between `MIN_DEPOSIT_AMOUNT` and `MAX_DEPOSIT_AMOUNT`, emits a `Deposit` log for consumption by the beacon chain. The deposit contract does little validation, pushing most of the validator onboarding logic to the beacon chain. In particular, the proof of possession (a BLS12 signature) is not verified by the deposit contract.
2019-01-31 16:23:41 +00:00
### `Eth2Genesis` log
When a sufficient amount of full deposits have been made, the deposit contract emits the `Eth2Genesis` log. The beacon chain state may then be initialized by calling the `get_genesis_beacon_state` function (defined below) where:
2019-01-31 16:23:41 +00:00
* `genesis_time` equals `time` in the `Eth2Genesis` log
2019-02-12 12:24:19 +00:00
* `latest_eth1_data.deposit_root` equals `deposit_root` in the `Eth2Genesis` log
* `latest_eth1_data.deposit_count` equals `deposit_count` in the `Eth2Genesis` log
2019-02-12 12:24:19 +00:00
* `latest_eth1_data.block_hash` equals the hash of the block that included the log
* `genesis_validator_deposits` is a list of `Deposit` objects built according to the `Deposit` logs up to the deposit that triggered the `Eth2Genesis` log, processed in the order in which they were emitted (oldest to newest)
### Vyper code
The source for the Vyper contract lives in a [separate repository](https://github.com/ethereum/deposit_contract) at [https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py](https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py).
2019-01-30 19:55:26 +00:00
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.
For convenience, we provide the interface to the contract here:
* `__init__()`: initializes the contract
* `get_deposit_root() -> bytes32`: returns the current root of the deposit tree
* `deposit(bytes[512])`: adds a deposit instance to the deposit tree, incorporating the input argument and the value transferred in the given call. Note: the amount of value transferred *must* be within `MIN_DEPOSIT_AMOUNT` and `MAX_DEPOSIT_AMOUNT`, inclusive. Each of these constants are specified in units of Gwei.
2019-01-30 19:55:26 +00:00
2019-02-12 12:24:19 +00:00
## On genesis
2018-09-20 05:20:49 +00:00
2019-03-03 11:04:28 +00:00
When enough full deposits have been made to the deposit contract, an `Eth2Genesis` log is emitted. Construct a corresponding `genesis_state` and `genesis_block` as follows:
* Let `genesis_validator_deposits` be the list of deposits, ordered chronologically, up to and including the deposit that triggered the `Eth2Genesis` log.
* Let `genesis_time` be the timestamp specified in the `Eth2Genesis` log.
* Let `genesis_eth1_data` be the `Eth1Data` object where:
* `genesis_eth1_data.deposit_root` is the `deposit_root` contained in the `Eth2Genesis` log.
* `genesis_eth1_data.deposit_count` is the `deposit_count` contained in the `Eth2Genesis` log.
2019-03-03 11:04:28 +00:00
* `genesis_eth1_data.block_hash` is the hash of the Ethereum 1.0 block that emitted the `Eth2Genesis` log.
* Let `genesis_state = get_genesis_beacon_state(genesis_validator_deposits, genesis_time, genesis_eth1_data)`.
2019-04-19 08:26:54 +00:00
* Let `genesis_block = BeaconBlock(state_root=hash_tree_root(genesis_state))`.
2018-11-16 16:41:59 +00:00
```python
2019-02-12 12:24:19 +00:00
def get_genesis_beacon_state(genesis_validator_deposits: List[Deposit],
genesis_time: int,
2019-03-03 11:04:28 +00:00
genesis_eth1_data: Eth1Data) -> BeaconState:
2019-01-30 09:25:39 +00:00
"""
2019-02-12 12:24:19 +00:00
Get the genesis ``BeaconState``.
2019-01-30 09:25:39 +00:00
"""
2019-04-19 08:26:54 +00:00
state = BeaconState(genesis_time=genesis_time, latest_eth1_data=genesis_eth1_data)
2018-10-09 07:33:22 +00:00
2019-02-12 12:24:19 +00:00
# Process genesis deposits
for deposit in genesis_validator_deposits:
2019-02-15 00:23:03 +00:00
process_deposit(state, deposit)
2018-12-10 21:16:06 +00:00
2019-02-12 12:24:19 +00:00
# Process genesis activations
2019-04-20 05:17:33 +00:00
for index, validator in enumerate(state.validator_registry):
if validator.effective_balance >= MAX_DEPOSIT_AMOUNT:
2019-04-17 04:32:46 +00:00
activate_validator(state, index)
2018-12-10 21:16:06 +00:00
2019-04-14 07:28:45 +00:00
genesis_active_index_root = hash_tree_root(get_active_validator_indices(state, GENESIS_EPOCH))
for index in range(LATEST_ACTIVE_INDEX_ROOTS_LENGTH):
state.latest_active_index_roots[index] = genesis_active_index_root
2018-12-10 21:16:06 +00:00
return state
```
2018-09-20 05:20:49 +00:00
## Beacon chain processing
The beacon chain is the system chain for Ethereum 2.0. The main responsibilities of the beacon chain are as follows:
2018-12-18 17:18:04 +00:00
* Store and maintain the registry of [validators](#dfn-validator)
* Process crosslinks (see above)
* Process its per-block consensus, as well as the finality gadget
2018-12-18 17:18:04 +00:00
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.
2018-11-27 03:52:06 +00:00
For a beacon chain block, `block`, to be processed by a node, the following conditions must be met:
2018-12-13 20:03:22 +00:00
2019-03-03 11:04:28 +00:00
* The parent block with root `block.previous_block_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.
2019-04-12 03:18:10 +00:00
* The node's Unix time is greater than or equal to `state.genesis_time + block.slot * SECONDS_PER_SLOT`. (Note that leap seconds mean that slots will occasionally last `SECONDS_PER_SLOT + 1` or `SECONDS_PER_SLOT - 1` seconds, possibly several times a year.)
2018-12-10 19:55:11 +00:00
If these conditions are not met, the client should delay processing the beacon block until the conditions are all satisfied.
2019-03-28 19:15:38 +00:00
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 `SECONDS_PER_SLOT` seconds) synchronized with the other nodes.
### Beacon chain fork choice rule
2018-12-05 18:40:08 +00:00
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`.
2019-01-31 15:58:31 +00:00
* Let `get_ancestor(store: Store, block: BeaconBlock, slot: Slot) -> BeaconBlock` be the ancestor of `block` with slot number `slot`. The `get_ancestor` function can be defined recursively as:
2018-12-10 22:42:28 +00:00
2018-12-10 21:16:06 +00:00
```python
2019-01-31 15:58:31 +00:00
def get_ancestor(store: Store, block: BeaconBlock, slot: Slot) -> BeaconBlock:
2019-01-30 09:25:39 +00:00
"""
Get the ancestor of ``block`` with slot number ``slot``; return ``None`` if not found.
"""
2019-01-29 13:17:05 +00:00
if block.slot == slot:
return block
elif block.slot < slot:
return None
else:
return get_ancestor(store, store.get_parent(block), slot)
```
* Let `get_latest_attestation(store: Store, index: ValidatorIndex) -> Attestation` be the attestation with the highest slot number in `store` from the validator with the given `index`. If several such attestations exist, use the one the [validator](#dfn-validator) `v` observed first.
* Let `get_latest_attestation_target(store: Store, index: ValidatorIndex) -> BeaconBlock` be the target block in the attestation `get_latest_attestation(store, index)`.
* 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 lmd_ghost(store: Store, start_state: BeaconState, start_block: BeaconBlock) -> BeaconBlock:
2019-01-30 09:25:39 +00:00
"""
Execute the LMD-GHOST algorithm to find the head ``BeaconBlock``.
"""
validators = start_state.validator_registry
2019-02-13 16:38:03 +00:00
active_validator_indices = get_active_validator_indices(validators, slot_to_epoch(start_state.slot))
attestation_targets = [(i, get_latest_attestation_target(store, i)) for i in active_validator_indices]
2018-12-11 15:49:50 +00:00
# Use the rounded-balance-with-hysteresis supplied by the protocol for fork
# choice voting. This reduces the number of recomputations that need to be
# made for optimized implementations that precompute and save data
def get_vote_count(block: BeaconBlock) -> int:
2019-02-06 16:34:19 +00:00
return sum(
2019-04-20 05:17:33 +00:00
start_state.validator_registry[validator_index].effective_balance
2019-02-06 16:34:19 +00:00
for validator_index, target in attestation_targets
if get_ancestor(store, target, block.slot) == block
2019-02-06 16:34:19 +00:00
)
2018-12-11 15:49:50 +00:00
head = start_block
while 1:
children = get_children(store, head)
if len(children) == 0:
return head
# Ties broken by favoring block with lexicographically higher root
head = max(children, key=lambda x: (get_vote_count(x), hash_tree_root(x)))
```
## Beacon chain state transition function
We now define the state transition function. At a high level, the state transition is made up of four parts:
1. State caching, which happens at the start of every slot.
2019-03-07 19:05:34 +00:00
2. The per-epoch transitions, which happens at the start of the first slot of every epoch.
3. The per-slot transitions, which happens at every slot.
4. The per-block transitions, which happens at every block.
2019-03-07 20:36:22 +00:00
Transition section notes:
* The state caching caches the state root of the previous slot and updates block and state roots records.
* The per-epoch transitions focus on the [validator](#dfn-validator) registry, including adjusting balances and activating and exiting [validators](#dfn-validator), as well as processing crosslinks and managing block justification/finalization.
* The per-slot transitions focus on the slot counter.
2019-03-07 20:36:22 +00:00
* The per-block transitions generally focus on verifying aggregate signatures and saving temporary records relating to the per-block activity in the `BeaconState`.
Beacon blocks that trigger unhandled Python exceptions (e.g. out-of-range list accesses) and failed `assert`s during the state transition are considered invalid.
Note: If there are skipped slots between a block and its parent block, run the steps in the [state-root](#state-caching), [per-epoch](#per-epoch-processing), and [per-slot](#per-slot-processing) sections once for each skipped slot and then once for the slot containing the new block.
### State caching
2018-09-20 05:20:49 +00:00
2019-03-03 11:04:28 +00:00
At every `slot > GENESIS_SLOT` run the following function:
2019-03-03 11:04:28 +00:00
```python
def cache_state(state: BeaconState) -> None:
2019-04-18 01:09:30 +00:00
# Cache latest known state root (for previous slot)
latest_state_root = hash_tree_root(state)
state.latest_state_roots[state.slot % SLOTS_PER_HISTORICAL_ROOT] = latest_state_root
2019-04-18 01:09:30 +00:00
# Store latest known state root (for previous slot) in latest_block_header if it is empty
if state.latest_block_header.state_root == ZERO_HASH:
2019-04-18 01:09:30 +00:00
state.latest_block_header.state_root = latest_state_root
2019-04-18 01:09:30 +00:00
# Cache latest known block root (for previous slot)
latest_block_root = signing_root(state.latest_block_header)
state.latest_block_roots[state.slot % SLOTS_PER_HISTORICAL_ROOT] = latest_block_root
2019-03-03 11:04:28 +00:00
```
2018-09-20 05:20:49 +00:00
2019-03-07 19:05:34 +00:00
### Per-epoch processing
2019-03-07 19:05:34 +00:00
The steps below happen when `state.slot > GENESIS_SLOT and (state.slot + 1) % SLOTS_PER_EPOCH == 0`.
2019-03-07 19:05:34 +00:00
#### Helper functions
We define epoch transition helper functions:
2018-09-20 05:20:49 +00:00
2019-03-03 11:04:28 +00:00
```python
2019-04-20 05:17:33 +00:00
def get_total_active_balance(state: BeaconState, epoch: Epoch) -> Gwei:
return get_total_balance(state, get_active_validator_indices(state, epoch), epoch)
2019-03-07 19:05:34 +00:00
```
2019-03-07 19:05:34 +00:00
```python
2019-04-20 05:17:33 +00:00
def get_matching_source_attestations(state: BeaconState, epoch: Epoch) -> List[PendingAttestation]:
return state.current_epoch_attestations if epoch == get_current_epoch(state) else state.previous_epoch_attestations
2019-03-07 19:05:34 +00:00
```
2019-03-03 11:04:28 +00:00
```python
2019-04-20 05:17:33 +00:00
def get_matching_target_attestations(state: BeaconState, epoch: Epoch) -> List[PendingAttestation]:
2019-03-07 19:05:34 +00:00
return [
2019-04-20 05:17:33 +00:00
a for a in get_matching_source_attestations(state, epoch)
if a.data.target_root == get_block_root(state, get_epoch_start_slot(epoch))
2019-03-07 19:05:34 +00:00
]
2019-03-03 11:04:28 +00:00
```
2019-03-07 19:05:34 +00:00
```python
2019-04-20 05:17:33 +00:00
def get_matching_head_attestations(state: BeaconState, epoch: Epoch) -> List[PendingAttestation]:
2019-03-07 19:05:34 +00:00
return [
2019-04-20 05:17:33 +00:00
a for a in get_matching_source_attestations(state, epoch)
2019-03-07 19:05:34 +00:00
if a.data.beacon_block_root == get_block_root(state, a.data.slot)
]
```
2018-11-16 15:48:57 +00:00
```python
def get_unslashed_attesting_indices(state: BeaconState, attestations: List[PendingAttestation]) -> List[ValidatorIndex]:
output = set()
for a in attestations:
output = output.union(get_attesting_indices(state, a.data, a.aggregation_bitfield))
return sorted(filter(lambda index: not state.validator_registry[index].slashed, list(output)))
```
```python
2019-04-20 05:17:33 +00:00
def get_attesting_balance(state: BeaconState, attestations: List[PendingAttestation], epoch: Epoch) -> Gwei:
return get_total_balance(state, get_unslashed_attesting_indices(state, attestations), epoch)
```
2019-03-07 19:05:34 +00:00
```python
2019-04-18 09:33:38 +00:00
def get_crosslink_from_attestation_data(state: BeaconState, data: AttestationData) -> Crosslink:
return Crosslink(
epoch=min(slot_to_epoch(data.slot), state.current_crosslinks[data.shard].epoch + MAX_CROSSLINK_EPOCHS),
previous_crosslink_root=data.previous_crosslink_root,
2019-04-18 17:16:50 +00:00
crosslink_data_root=data.crosslink_data_root,
2019-04-18 09:33:38 +00:00
)
```
2019-03-07 19:05:34 +00:00
```python
2019-04-18 04:20:34 +00:00
def get_winning_crosslink_and_attesting_indices(state: BeaconState, epoch: Epoch, shard: Shard) -> Tuple[Crosslink, List[ValidatorIndex]]:
2019-04-20 05:17:33 +00:00
attestations = get_matching_source_attestations(state, epoch)
shard_attestations = [a for a in attestations if a.data.shard == shard]
2019-04-18 09:33:38 +00:00
shard_crosslinks = [get_crosslink_from_attestation_data(state, a.data) for a in shard_attestations]
2019-04-18 17:16:50 +00:00
candidate_crosslinks = [
c for c in shard_crosslinks
if hash_tree_root(state.current_crosslinks[shard]) in (c.previous_crosslink_root, hash_tree_root(c))
2019-04-18 08:53:22 +00:00
]
2019-04-18 04:33:45 +00:00
if len(candidate_crosslinks) == 0:
2019-04-18 08:53:02 +00:00
return Crosslink(epoch=GENESIS_EPOCH, previous_crosslink_root=ZERO_HASH, crosslink_data_root=ZERO_HASH), []
2019-03-07 19:05:34 +00:00
2019-04-18 09:33:38 +00:00
def get_attestations_for(crosslink: Crosslink) -> List[PendingAttestation]:
return [a for a in shard_attestations if get_crosslink_from_attestation_data(state, a.data) == crosslink]
2019-04-18 04:33:45 +00:00
# Winning crosslink has the crosslink data root with the most balance voting for it (ties broken lexicographically)
2019-04-18 09:33:38 +00:00
winning_crosslink = max(candidate_crosslinks, key=lambda crosslink: (
2019-04-20 05:17:33 +00:00
get_attesting_balance(state, get_attestations_for(crosslink), epoch), crosslink.crosslink_data_root
2019-04-18 09:33:38 +00:00
))
2019-03-07 19:05:34 +00:00
2019-04-18 09:33:38 +00:00
return winning_crosslink, get_unslashed_attesting_indices(state, get_attestations_for(winning_crosslink))
2019-03-07 19:05:34 +00:00
```
```python
def get_earliest_attestation(state: BeaconState, attestations: List[PendingAttestation], index: ValidatorIndex) -> PendingAttestation:
2019-03-07 19:05:34 +00:00
return min([
2019-04-18 04:20:34 +00:00
a for a in attestations if index in get_attesting_indices(state, a.data, a.aggregation_bitfield)
2019-03-07 19:05:34 +00:00
], key=lambda a: a.inclusion_slot)
```
#### Justification and finalization
2019-03-07 19:05:34 +00:00
Run the following function:
```python
def process_justification_and_finalization(state: BeaconState) -> None:
if get_current_epoch(state) <= GENESIS_EPOCH + 1:
2019-04-11 12:28:42 +00:00
return
2019-04-20 06:10:25 +00:00
previous_epoch = get_previous_epoch(state)
current_epoch = get_current_epoch(state)
old_previous_justified_epoch = state.previous_justified_epoch
old_current_justified_epoch = state.current_justified_epoch
2019-03-12 18:32:11 +00:00
# Process justifications
state.previous_justified_epoch = state.current_justified_epoch
state.previous_justified_root = state.current_justified_root
state.justification_bitfield = (state.justification_bitfield << 1) % 2**64
2019-04-20 06:10:25 +00:00
previous_epoch_matching_target_balance = get_attesting_balance(state, get_matching_target_attestations(state, previous_epoch), previous_epoch)
if previous_epoch_matching_target_balance * 3 >= get_total_active_balance(state, previous_epoch) * 2:
state.current_justified_epoch = get_previous_epoch(state)
state.current_justified_root = get_block_root(state, get_epoch_start_slot(state.current_justified_epoch))
state.justification_bitfield |= (1 << 1)
2019-04-20 06:10:25 +00:00
current_epoch_matching_target_balance = get_attesting_balance(state, get_matching_target_attestations(state, current_epoch), current_epoch)
if current_epoch_matching_target_balance * 3 >= get_total_active_balance(state, current_epoch) * 2:
state.current_justified_epoch = get_current_epoch(state)
state.current_justified_root = get_block_root(state, get_epoch_start_slot(state.current_justified_epoch))
state.justification_bitfield |= (1 << 0)
2019-03-07 19:05:34 +00:00
# Process finalizations
bitfield = state.justification_bitfield
# The 2nd/3rd/4th most recent epochs are justified, the 2nd using the 4th as source
if (bitfield >> 1) % 8 == 0b111 and old_previous_justified_epoch == current_epoch - 3:
state.finalized_epoch = old_previous_justified_epoch
state.finalized_root = get_block_root(state, get_epoch_start_slot(state.finalized_epoch))
# The 2nd/3rd most recent epochs are justified, the 2nd using the 3rd as source
if (bitfield >> 1) % 4 == 0b11 and old_previous_justified_epoch == current_epoch - 2:
state.finalized_epoch = old_previous_justified_epoch
state.finalized_root = get_block_root(state, get_epoch_start_slot(state.finalized_epoch))
# The 1st/2nd/3rd most recent epochs are justified, the 1st using the 3rd as source
if (bitfield >> 0) % 8 == 0b111 and old_current_justified_epoch == current_epoch - 2:
state.finalized_epoch = old_current_justified_epoch
state.finalized_root = get_block_root(state, get_epoch_start_slot(state.finalized_epoch))
# The 1st/2nd most recent epochs are justified, the 1st using the 2nd as source
if (bitfield >> 0) % 4 == 0b11 and old_current_justified_epoch == current_epoch - 1:
state.finalized_epoch = old_current_justified_epoch
state.finalized_root = get_block_root(state, get_epoch_start_slot(state.finalized_epoch))
```
2018-09-20 05:20:49 +00:00
2019-03-07 19:05:34 +00:00
#### Crosslinks
2019-03-07 19:05:34 +00:00
Run the following function:
2019-03-07 19:05:34 +00:00
```python
def process_crosslinks(state: BeaconState) -> None:
2019-04-18 17:16:50 +00:00
state.previous_crosslinks = [c for c in state.current_crosslinks]
2019-04-13 14:47:14 +00:00
previous_epoch = get_previous_epoch(state)
2019-04-12 03:38:58 +00:00
next_epoch = get_current_epoch(state) + 1
2019-03-07 19:05:34 +00:00
for slot in range(get_epoch_start_slot(previous_epoch), get_epoch_start_slot(next_epoch)):
2019-04-20 05:17:33 +00:00
epoch = slot_to_epoch(slot)
2019-03-07 19:05:34 +00:00
for crosslink_committee, shard in get_crosslink_committees_at_slot(state, slot):
2019-04-20 05:17:33 +00:00
winning_crosslink, attesting_indices = get_winning_crosslink_and_attesting_indices(state, epoch, shard)
if 3 * get_total_balance(state, attesting_indices, epoch) >= 2 * get_total_balance(state, crosslink_committee, epoch):
2019-04-18 04:20:34 +00:00
state.current_crosslinks[shard] = winning_crosslink
2019-03-07 19:05:34 +00:00
```
#### Rewards and penalties
First, we define additional helpers:
```python
2019-04-20 05:17:33 +00:00
def get_base_reward(state: BeaconState, index: ValidatorIndex, epoch: Epoch) -> Gwei:
2019-04-20 06:10:25 +00:00
adjusted_quotient = integer_squareroot(get_total_active_balance(state, epoch)) // BASE_REWARD_QUOTIENT
if adjusted_quotient == 0:
return 0
2019-04-20 05:17:33 +00:00
return get_effective_balance(state, index, epoch) // adjusted_quotient // BASE_REWARDS_PER_EPOCH
2019-04-20 06:10:25 +00:00
```
```python
2019-04-20 05:17:33 +00:00
def get_attestation_deltas(state: BeaconState) -> Tuple[List[Gwei], List[Gwei]]:
2019-04-20 06:10:25 +00:00
previous_epoch = get_previous_epoch(state)
total_balance = get_total_active_balance(state, previous_epoch)
2019-04-20 05:17:33 +00:00
eligible_validator_indices = [
index for index, validator in enumerate(state.validator_registry)
2019-04-20 06:10:25 +00:00
if is_active_validator(validator, previous_epoch) or (validator.slashed and previous_epoch < validator.withdrawable_epoch)
]
rewards = [0 for index in range(len(state.validator_registry))]
penalties = [0 for index in range(len(state.validator_registry))]
2019-04-20 05:17:33 +00:00
for index in eligible_validator_indices:
2019-04-20 06:10:25 +00:00
base_reward = get_base_reward(state, index, previous_epoch)
2019-04-20 05:17:33 +00:00
# Micro-incentives for attestations matching FFG source, FFG target, and head
for attestations in (
2019-04-20 06:10:25 +00:00
get_matching_source_attestations(state, previous_epoch),
get_matching_target_attestations(state, previous_epoch),
get_matching_source_attestations(state, previous_epoch),
):
if index in get_unslashed_attesting_indices(state, attestations):
2019-04-20 06:10:25 +00:00
rewards[index] += base_reward * get_attesting_balance(state, attestations, previous_epoch) // total_balance
else:
penalties[index] += base_reward
2019-04-20 06:10:25 +00:00
if index in get_unslashed_attesting_indices(state, get_matching_source_attestations(state, previous_epoch)):
earliest_attestation = get_earliest_attestation(state, get_matching_source_attestations(state, previous_epoch), index)
2019-04-20 05:17:33 +00:00
# Proposer micro-rewards
proposer_index = get_beacon_proposer_index(state, earliest_attestation.inclusion_slot)
rewards[proposer_index] += base_reward // PROPOSER_REWARD_QUOTIENT
# Inclusion delay micro-rewards
inclusion_delay = earliest_attestation.inclusion_slot - earliest_attestation.data.slot
2019-04-20 05:17:33 +00:00
rewards[index] += base_reward * MIN_ATTESTATION_INCLUSION_DELAY // inclusion_delay
# Inactivity penalty
2019-04-20 06:10:25 +00:00
finality_delay = previous_epoch - state.finalized_epoch
2019-04-20 05:17:33 +00:00
if finality_delay > MIN_EPOCHS_TO_INACTIVITY_PENALTY:
penalties[index] += BASE_REWARDS_PER_EPOCH * base_reward
2019-04-20 06:10:25 +00:00
if index not in get_unslashed_attesting_indices(state, get_matching_target_attestations(state, previous_epoch)):
penalties[index] += get_effective_balance(state, index, previous_epoch) * finality_delay // INACTIVITY_PENALTY_QUOTIENT
return [rewards, penalties]
```
2018-09-20 05:20:49 +00:00
```python
2019-03-04 16:45:55 +00:00
def get_crosslink_deltas(state: BeaconState) -> Tuple[List[Gwei], List[Gwei]]:
rewards = [0 for index in range(len(state.validator_registry))]
penalties = [0 for index in range(len(state.validator_registry))]
2019-04-18 04:20:34 +00:00
for slot in range(get_epoch_start_slot(get_previous_epoch(state)), get_epoch_start_slot(get_current_epoch(state))):
2019-04-20 05:17:33 +00:00
epoch = slot_to_epoch(slot)
for crosslink_committee, shard in get_crosslink_committees_at_slot(state, slot):
2019-04-20 05:17:33 +00:00
winning_crosslink, attesting_indices = get_winning_crosslink_and_attesting_indices(state, epoch, shard)
attesting_balance = get_total_balance(state, attesting_indices, epoch)
committee_balance = get_total_balance(state, crosslink_committee, epoch)
for index in crosslink_committee:
2019-04-20 05:17:33 +00:00
base_reward = get_base_reward(state, index, epoch)
2019-04-18 04:20:34 +00:00
if index in attesting_indices:
rewards[index] += base_reward * attesting_balance // committee_balance
else:
penalties[index] += base_reward
return [rewards, penalties]
```
Run the following function:
2018-09-20 05:20:49 +00:00
```python
def process_rewards_and_penalties(state: BeaconState) -> None:
2019-04-11 12:28:42 +00:00
if get_current_epoch(state) == GENESIS_EPOCH:
return
2019-04-20 05:17:33 +00:00
rewards1, penalties1 = get_attestation_deltas(state)
rewards2, penalties2 = get_crosslink_deltas(state)
for i in range(len(state.validator_registry)):
increase_balance(state, i, rewards1[i] + rewards2[i])
decrease_balance(state, i, penalties1[i] + penalties2[i])
```
2018-11-23 04:54:11 +00:00
#### Registry updates
Run the following function:
```python
def process_registry_updates(state: BeaconState) -> None:
# Process activation eligibility and ejections
2018-12-10 22:30:25 +00:00
for index, validator in enumerate(state.validator_registry):
2019-04-20 05:17:33 +00:00
if validator.activation_eligibility_epoch == FAR_FUTURE_EPOCH and validator.effective_balance >= MAX_DEPOSIT_AMOUNT:
validator.activation_eligibility_epoch = get_current_epoch(state)
2019-04-20 06:32:41 +00:00
if is_active_validator(validator, get_current_epoch(state)) and validator.effective_balance <= EJECTION_BALANCE:
initiate_validator_exit(state, index)
2019-03-07 19:05:34 +00:00
# Process activations
activation_queue = sorted([
index for index, validator in enumerate(state.validator_registry) if
2019-04-06 10:07:03 +00:00
validator.activation_eligibility_epoch != FAR_FUTURE_EPOCH and
2019-04-06 22:45:43 +00:00
validator.activation_epoch >= get_delayed_activation_exit_epoch(state.finalized_epoch)
2019-04-06 09:45:11 +00:00
], key=lambda index: state.validator_registry[index].activation_eligibility_epoch)
2019-04-14 03:14:05 +00:00
for index in activation_queue[:get_churn_limit(state)]:
activate_validator(state, index)
2019-03-07 19:05:34 +00:00
```
2019-04-06 10:07:03 +00:00
#### Slashings
2019-03-07 19:05:34 +00:00
Run the following function:
2019-03-07 19:05:34 +00:00
```python
def process_slashings(state: BeaconState) -> None:
current_epoch = get_current_epoch(state)
2019-04-14 07:28:45 +00:00
active_validator_indices = get_active_validator_indices(state, current_epoch)
2019-04-20 05:17:33 +00:00
total_balance = get_total_balance(state, active_validator_indices, current_epoch)
2019-03-07 19:05:34 +00:00
# Compute `total_penalties`
2019-03-07 22:13:06 +00:00
total_at_start = state.latest_slashed_balances[(current_epoch + 1) % LATEST_SLASHED_EXIT_LENGTH]
total_at_end = state.latest_slashed_balances[current_epoch % LATEST_SLASHED_EXIT_LENGTH]
2019-03-07 19:05:34 +00:00
total_penalties = total_at_end - total_at_start
for index, validator in enumerate(state.validator_registry):
if validator.slashed and current_epoch == validator.withdrawable_epoch - LATEST_SLASHED_EXIT_LENGTH // 2:
penalty = max(
2019-04-20 05:17:33 +00:00
get_effective_balance(state, index, current_epoch) * min(total_penalties * 3, total_balance) // total_balance,
get_effective_balance(state, index, current_epoch) // MIN_PENALTY_QUOTIENT
2019-03-07 19:05:34 +00:00
)
decrease_balance(state, index, penalty)
2019-03-07 19:05:34 +00:00
```
#### Final updates
Run the following function:
```python
def process_final_updates(state: BeaconState) -> None:
2019-03-07 19:05:34 +00:00
current_epoch = get_current_epoch(state)
next_epoch = current_epoch + 1
# Reset eth1 data votes
if state.slot % SLOTS_PER_ETH1_VOTING_PERIOD == 0:
state.eth1_data_votes = []
2019-04-20 05:17:33 +00:00
# Update effective balances
for index, validator in enumerate(state.validator_registry):
2019-04-20 05:31:15 +00:00
validator.effective_balance = get_current_epoch_effective_balance(state, index)
# Update start shard
state.latest_start_shard = (state.latest_start_shard + get_shard_delta(state, current_epoch)) % SHARD_COUNT
2019-03-07 19:05:34 +00:00
# Set active index root
index_root_position = (next_epoch + ACTIVATION_EXIT_DELAY) % LATEST_ACTIVE_INDEX_ROOTS_LENGTH
state.latest_active_index_roots[index_root_position] = hash_tree_root(
2019-04-14 07:28:45 +00:00
get_active_validator_indices(state, next_epoch + ACTIVATION_EXIT_DELAY)
2019-03-07 19:05:34 +00:00
)
# Set total slashed balances
state.latest_slashed_balances[next_epoch % LATEST_SLASHED_EXIT_LENGTH] = (
state.latest_slashed_balances[current_epoch % LATEST_SLASHED_EXIT_LENGTH]
)
# Set randao mix
state.latest_randao_mixes[next_epoch % LATEST_RANDAO_MIXES_LENGTH] = get_randao_mix(state, current_epoch)
# Set historical root accumulator
if next_epoch % (SLOTS_PER_HISTORICAL_ROOT // SLOTS_PER_EPOCH) == 0:
2019-03-08 17:13:05 +00:00
historical_batch = HistoricalBatch(
block_roots=state.latest_block_roots,
state_roots=state.latest_state_roots,
)
state.historical_roots.append(hash_tree_root(historical_batch))
2019-03-07 19:05:34 +00:00
# Rotate current/previous epoch attestations
state.previous_epoch_attestations = state.current_epoch_attestations
state.current_epoch_attestations = []
```
### Per-slot processing
At every `slot > GENESIS_SLOT` run the following function:
```python
def advance_slot(state: BeaconState) -> None:
2019-03-08 08:08:30 +00:00
state.slot += 1
2019-03-07 19:05:34 +00:00
```
### Per-block processing
For every `block` except the genesis block, run `process_block_header(state, block)`, `process_randao(state, block)` and `process_eth1_data(state, block)`.
#### Block header
```python
def process_block_header(state: BeaconState, block: BeaconBlock) -> None:
# Verify that the slots match
assert block.slot == state.slot
# Verify that the parent matches
2019-04-08 01:51:13 +00:00
assert block.previous_block_root == signing_root(state.latest_block_header)
2019-03-07 19:05:34 +00:00
# Save current block as the new latest block
2019-04-19 08:26:54 +00:00
state.latest_block_header = BeaconBlockHeader(
slot=block.slot,
previous_block_root=block.previous_block_root,
block_body_root=hash_tree_root(block.body),
)
2019-03-17 11:48:47 +00:00
# Verify proposer is not slashed
proposer = state.validator_registry[get_beacon_proposer_index(state)]
2019-03-11 22:07:34 +00:00
assert not proposer.slashed
# Verify proposer signature
assert bls_verify(proposer.pubkey, signing_root(block), block.signature, get_domain(state, DOMAIN_BEACON_PROPOSER))
2019-03-07 19:05:34 +00:00
```
#### RANDAO
```python
def process_randao(state: BeaconState, block: BeaconBlock) -> None:
proposer = state.validator_registry[get_beacon_proposer_index(state)]
2019-03-07 19:05:34 +00:00
# Verify that the provided randao value is valid
assert bls_verify(proposer.pubkey, hash_tree_root(get_current_epoch(state)), block.body.randao_reveal, get_domain(state, DOMAIN_RANDAO))
2019-03-07 19:05:34 +00:00
# Mix it in
state.latest_randao_mixes[get_current_epoch(state) % LATEST_RANDAO_MIXES_LENGTH] = (
xor(get_randao_mix(state, get_current_epoch(state)),
hash(block.body.randao_reveal))
)
```
#### Eth1 data
```python
def process_eth1_data(state: BeaconState, block: BeaconBlock) -> None:
state.eth1_data_votes.append(block.body.eth1_data)
if state.eth1_data_votes.count(block.body.eth1_data) * 2 > SLOTS_PER_ETH1_VOTING_PERIOD:
state.latest_eth1_data = block.body.eth1_data
2019-03-07 19:05:34 +00:00
```
#### Operations
2019-03-07 19:05:34 +00:00
##### Proposer slashings
Verify that `len(block.body.proposer_slashings) <= MAX_PROPOSER_SLASHINGS`.
For each `proposer_slashing` in `block.body.proposer_slashings`, run the following function:
```python
def process_proposer_slashing(state: BeaconState,
proposer_slashing: ProposerSlashing) -> None:
"""
Process ``ProposerSlashing`` operation.
2019-03-07 19:05:34 +00:00
Note that this function mutates ``state``.
"""
proposer = state.validator_registry[proposer_slashing.proposer_index]
# Verify that the epoch is the same
assert slot_to_epoch(proposer_slashing.header_1.slot) == slot_to_epoch(proposer_slashing.header_2.slot)
2019-03-08 17:34:51 +00:00
# But the headers are different
assert proposer_slashing.header_1 != proposer_slashing.header_2
2019-03-19 11:08:17 +00:00
# Check proposer is slashable
2019-03-19 11:12:50 +00:00
assert is_slashable_validator(proposer, get_current_epoch(state))
2019-03-07 19:05:34 +00:00
# Signatures are valid
for header in (proposer_slashing.header_1, proposer_slashing.header_2):
2019-03-31 16:48:44 +00:00
domain = get_domain(state, DOMAIN_BEACON_PROPOSER, slot_to_epoch(header.slot))
assert bls_verify(proposer.pubkey, signing_root(header), header.signature, domain)
2019-03-07 19:05:34 +00:00
slash_validator(state, proposer_slashing.proposer_index)
```
##### Attester slashings
2018-12-10 21:16:06 +00:00
2019-03-07 19:05:34 +00:00
Verify that `len(block.body.attester_slashings) <= MAX_ATTESTER_SLASHINGS`.
2019-03-07 19:05:34 +00:00
For each `attester_slashing` in `block.body.attester_slashings`, run the following function:
2019-01-08 00:53:33 +00:00
2019-03-02 01:49:28 +00:00
```python
2019-03-07 19:05:34 +00:00
def process_attester_slashing(state: BeaconState,
attester_slashing: AttesterSlashing) -> None:
"""
Process ``AttesterSlashing`` operation.
2019-03-07 19:05:34 +00:00
Note that this function mutates ``state``.
"""
attestation1 = attester_slashing.attestation_1
attestation2 = attester_slashing.attestation_2
2019-03-07 19:05:34 +00:00
# Check that the attestations are conflicting
assert attestation1.data != attestation2.data
assert (
is_double_vote(attestation1.data, attestation2.data) or
is_surround_vote(attestation1.data, attestation2.data)
)
2019-03-26 19:40:19 +00:00
assert verify_indexed_attestation(state, attestation1)
assert verify_indexed_attestation(state, attestation2)
2019-04-03 00:04:12 +00:00
attesting_indices_1 = attestation1.custody_bit_0_indices + attestation1.custody_bit_1_indices
attesting_indices_2 = attestation2.custody_bit_0_indices + attestation2.custody_bit_1_indices
2019-03-07 19:05:34 +00:00
slashable_indices = [
2019-04-03 00:04:12 +00:00
index for index in attesting_indices_1
2019-03-07 19:05:34 +00:00
if (
2019-04-03 00:04:12 +00:00
index in attesting_indices_2 and
2019-03-19 11:12:50 +00:00
is_slashable_validator(state.validator_registry[index], get_current_epoch(state))
2019-03-02 01:49:28 +00:00
)
2019-03-07 19:05:34 +00:00
]
assert len(slashable_indices) >= 1
for index in slashable_indices:
slash_validator(state, index)
2019-03-02 01:49:28 +00:00
```
2019-03-07 19:05:34 +00:00
##### Attestations
2019-01-08 00:53:33 +00:00
2019-03-07 19:05:34 +00:00
Verify that `len(block.body.attestations) <= MAX_ATTESTATIONS`.
2019-03-02 01:49:28 +00:00
2019-03-07 19:05:34 +00:00
For each `attestation` in `block.body.attestations`, run the following function:
```python
2019-03-07 19:05:34 +00:00
def process_attestation(state: BeaconState, attestation: Attestation) -> None:
2019-01-30 09:25:39 +00:00
"""
Process ``Attestation`` operation.
2019-01-30 09:25:39 +00:00
Note that this function mutates ``state``.
"""
2019-04-03 19:40:54 +00:00
data = attestation.data
min_slot = state.slot - SLOTS_PER_EPOCH if get_current_epoch(state) > GENESIS_EPOCH else GENESIS_SLOT
assert min_slot <= data.slot <= state.slot - MIN_ATTESTATION_INCLUSION_DELAY
2019-04-03 19:40:54 +00:00
# Check target epoch, source epoch, source root, and source crosslink
target_epoch = slot_to_epoch(data.slot)
assert (target_epoch, data.source_epoch, data.source_root, data.previous_crosslink_root) in {
(get_current_epoch(state), state.current_justified_epoch, state.current_justified_root, hash_tree_root(state.current_crosslinks[data.shard])),
(get_previous_epoch(state), state.previous_justified_epoch, state.previous_justified_root, hash_tree_root(state.previous_crosslinks[data.shard])),
}
2019-04-03 19:40:54 +00:00
# Check crosslink data root
assert data.crosslink_data_root == ZERO_HASH # [to be removed in phase 1]
# Check signature and bitfields
2019-03-26 19:40:19 +00:00
assert verify_indexed_attestation(state, convert_to_indexed(state, attestation))
# Cache pending attestation
2019-03-07 19:05:34 +00:00
pending_attestation = PendingAttestation(
2019-04-03 19:40:54 +00:00
data=data,
2019-03-07 19:05:34 +00:00
aggregation_bitfield=attestation.aggregation_bitfield,
inclusion_slot=state.slot
)
2019-03-15 12:51:46 +00:00
if target_epoch == get_current_epoch(state):
2019-03-07 19:05:34 +00:00
state.current_epoch_attestations.append(pending_attestation)
else:
2019-03-07 19:05:34 +00:00
state.previous_epoch_attestations.append(pending_attestation)
2019-02-12 12:24:19 +00:00
```
2019-03-07 19:05:34 +00:00
##### Deposits
Verify that `len(block.body.deposits) == min(MAX_DEPOSITS, state.latest_eth1_data.deposit_count - state.deposit_index)`.
2019-03-07 19:05:34 +00:00
For each `deposit` in `block.body.deposits`, run the following function:
```python
def process_deposit(state: BeaconState, deposit: Deposit) -> None:
"""
2019-04-20 06:32:41 +00:00
Process an Eth1 deposit, registering a validator or increasing its balance.
Note that this function mutates ``state``.
"""
# Verify the Merkle branch
2019-04-20 06:32:41 +00:00
assert verify_merkle_branch(
leaf=hash(serialize(deposit.data)), # 48 + 32 + 8 + 96 = 184 bytes serialization
proof=deposit.proof,
depth=DEPOSIT_CONTRACT_TREE_DEPTH,
index=deposit.index,
root=state.latest_eth1_data.deposit_root,
)
2019-04-20 06:35:02 +00:00
# Deposits must be processed in order
assert deposit.index == state.deposit_index
state.deposit_index += 1
validator_pubkeys = [v.pubkey for v in state.validator_registry]
pubkey = deposit.data.pubkey
amount = deposit.data.amount
if pubkey not in validator_pubkeys:
# Verify the deposit signature (proof of possession)
if not bls_verify(pubkey, signing_root(deposit.data), deposit.data.signature, get_domain(state, DOMAIN_DEPOSIT)):
return
# Add new validator
validator = Validator(
pubkey=pubkey,
withdrawal_credentials=deposit.data.withdrawal_credentials,
activation_eligibility_epoch=FAR_FUTURE_EPOCH,
activation_epoch=FAR_FUTURE_EPOCH,
exit_epoch=FAR_FUTURE_EPOCH,
withdrawable_epoch=FAR_FUTURE_EPOCH,
)
state.validator_registry.append(validator)
2019-04-20 05:17:33 +00:00
state.balances.append(amount)
2019-04-20 06:32:41 +00:00
validator.effective_balance = get_current_epoch_effective_balance(state, len(state.validator_registry) - 1)
else:
# Increase balance by deposit amount
index = validator_pubkeys.index(pubkey)
increase_balance(state, index, amount)
```
2019-03-07 19:05:34 +00:00
##### Voluntary exits
Verify that `len(block.body.voluntary_exits) <= MAX_VOLUNTARY_EXITS`.
For each `exit` in `block.body.voluntary_exits`, run the following function:
2019-02-12 12:24:19 +00:00
```python
2019-03-10 12:50:28 +00:00
def process_voluntary_exit(state: BeaconState, exit: VoluntaryExit) -> None:
2019-02-12 12:24:19 +00:00
"""
Process ``VoluntaryExit`` operation.
2019-02-12 12:24:19 +00:00
Note that this function mutates ``state``.
"""
2019-03-07 19:05:34 +00:00
validator = state.validator_registry[exit.validator_index]
2019-03-19 21:49:01 +00:00
# Verify the validator is active
assert is_active_validator(validator, get_current_epoch(state))
2019-03-07 19:05:34 +00:00
# Verify the validator has not yet exited
assert validator.exit_epoch == FAR_FUTURE_EPOCH
2019-03-07 19:05:34 +00:00
# Exits must specify an epoch when they become valid; they are not valid before then
assert get_current_epoch(state) >= exit.epoch
2019-03-19 20:43:05 +00:00
# Verify the validator has been active long enough
assert get_current_epoch(state) - validator.activation_epoch >= PERSISTENT_COMMITTEE_PERIOD
2019-03-07 19:05:34 +00:00
# Verify signature
domain = get_domain(state, DOMAIN_VOLUNTARY_EXIT, exit.epoch)
assert bls_verify(validator.pubkey, signing_root(exit), exit.signature, domain)
2019-03-19 20:43:05 +00:00
# Initiate exit
2019-03-07 19:05:34 +00:00
initiate_validator_exit(state, exit.validator_index)
```
2019-03-07 19:05:34 +00:00
##### Transfers
2018-09-20 05:20:49 +00:00
2019-03-07 19:05:34 +00:00
Note: Transfers are a temporary functionality for phases 0 and 1, to be removed in phase 2.
Verify that `len(block.body.transfers) <= MAX_TRANSFERS` and that all transfers are distinct.
For each `transfer` in `block.body.transfers`, run the following function:
2019-03-02 01:49:28 +00:00
```python
2019-03-07 19:05:34 +00:00
def process_transfer(state: BeaconState, transfer: Transfer) -> None:
"""
Process ``Transfer`` operation.
2019-03-07 19:05:34 +00:00
Note that this function mutates ``state``.
"""
2019-04-20 05:17:33 +00:00
# Verify the amount and fee are not individually too big (for anti-overflow purposes)
assert state.balances[transfer.sender] >= max(transfer.amount, transfer.fee)
2019-03-07 19:05:34 +00:00
# A transfer is valid in only one slot
assert state.slot == transfer.slot
# Only withdrawn or not-yet-deposited accounts can transfer
assert (
get_current_epoch(state) >= state.validator_registry[transfer.sender].withdrawable_epoch or
state.validator_registry[transfer.sender].activation_epoch == FAR_FUTURE_EPOCH
2019-03-02 01:49:28 +00:00
)
2019-03-07 19:05:34 +00:00
# Verify that the pubkey is valid
assert (
state.validator_registry[transfer.sender].withdrawal_credentials ==
BLS_WITHDRAWAL_PREFIX_BYTE + hash(transfer.pubkey)[1:]
)
# Verify that the signature is valid
assert bls_verify(transfer.pubkey, signing_root(transfer), transfer.signature, get_domain(state, DOMAIN_TRANSFER))
2019-03-07 19:05:34 +00:00
# Process the transfer
decrease_balance(state, transfer.sender, transfer.amount + transfer.fee)
increase_balance(state, transfer.recipient, transfer.amount)
increase_balance(state, get_beacon_proposer_index(state), transfer.fee)
# Verify balances are not dust
2019-04-20 05:17:33 +00:00
assert not (0 < state.balances[transfer.sender] < MIN_DEPOSIT_AMOUNT)
assert not (0 < state.balances[transfer.recipient] < MIN_DEPOSIT_AMOUNT)
2019-03-02 01:49:28 +00:00
```
2019-03-07 19:05:34 +00:00
#### State root verification
Verify the block's `state_root` by running the following function:
2018-12-05 19:03:24 +00:00
2019-03-07 19:05:34 +00:00
```python
def verify_block_state_root(state: BeaconState, block: BeaconBlock) -> None:
assert block.state_root == hash_tree_root(state)
```