status-im
/
eth2.0-specs
mirror of https://github.com/status-im/eth2.0-specs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'master' into end-of-epoch

This commit is contained in:
Danny Ryan 2019-01-27 07:07:52 -07:00
parent e34cfc8de8 1a41078768
commit 18273b088d
No known key found for this signature in database
GPG Key ID: 2765A792E42CE07A
2 changed files with 77 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
specs/core/0_beacon-chain.md
View File

@ -48,6 +48,7 @@
- [`Fork`](#fork)
- [`Eth1Data`](#eth1data)
- [`Eth1DataVote`](#eth1datavote)
- [Custom Types](#custom-types)
- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract)
- [Deposit arguments](#deposit-arguments)
- [Withdrawal credentials](#withdrawal-credentials)
@ -116,7 +117,7 @@
- [Attestation inclusion](#attestation-inclusion)
- [Crosslinks](#crosslinks-1)
- [Ejections](#ejections)
- [Validator registry](#validator-registry)
- [Validator registry and shuffling seed data](#validator-registry-and-shuffling-seed-data)
- [Final updates](#final-updates)
- [State root processing](#state-root-processing)
- [References](#references)
@ -249,6 +250,8 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
## Data structures
The following data structures are defined as [SimpleSerialize (SSZ)](https://github.com/ethereum/eth2.0-specs/blob/master/specs/simple-serialize.md) objects.
### Beacon chain operations
#### Proposer slashings
@ -512,8 +515,6 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
'pubkey': 'bytes48',
# Withdrawal credentials
'withdrawal_credentials': 'bytes32',
# Number of proposer slots since genesis
'proposer_slots': 'uint64',
# Slot when validator activated
'activation_slot': 'uint64',
# Slot when validator exited
@ -577,9 +578,9 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
```python
{
# Root of the deposit tree
'deposit_root': 'hash32',
'deposit_root': 'bytes32',
# Block hash
'block_hash': 'hash32',
'block_hash': 'bytes32',
}
```
@ -594,6 +595,20 @@ Code snippets appearing in `this style` are to be interpreted as Python code. Be
}
```
## Custom Types
We define the following Python custom types for type hinting and readability:
| Name | Type | Description |
| - | - | - |
| `SlotNumber` | unsigned 64-bit integer | the number of a slot |
| `ShardNumber` | unsigned 64-bit integer | the number of a shard |
| `ValidatorIndex` | unsigned 24-bit integer | the index number of a validator in the registry |
| `Gwei` | unsigned 64-bit integer | an amount in Gwei |
| `Bytes32` | 32-byte data | binary data with 32-byte length |
| `BLSPubkey` | 48-byte data | a public key in BLS signature scheme |
| `BLSSignature` | 96-byte data | a signature in BLS signature scheme |
## 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.
@ -712,28 +727,38 @@ Beacon block production is significantly different because of the proof of stake
The beacon chain fork choice rule is a hybrid that combines justification and finality with Latest Message Driven (LMD) Greediest Heaviest Observed SubTree (GHOST). At any point in time a [validator](#dfn-validator) `v` subjectively calculates the beacon chain head as follows.
* Let `store` be the set of attestations and blocks that the [validator](#dfn-validator) `v` has observed and verified (in particular, block ancestors must be recursively verified). Attestations not part of any chain are still included in `store`.
* 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 slot number. (A block `B` is finalized if there is a descendant of `B` in `store` the processing of which sets `B` as finalized.)
* Let `justified_head` be the descendant of `finalized_head` with the highest slot number that has been justified for at least `EPOCH_LENGTH` slots. (A block `B` is justified if there is a descendant of `B` in `store` the processing of which sets `B` as justified.) If no such descendant exists set `justified_head` to `finalized_head`.
* Let `get_ancestor(store, block, slot)` be the ancestor of `block` with slot number `slot`. The `get_ancestor` function can be defined recursively as `def get_ancestor(store, block, slot): return block if block.slot == slot else get_ancestor(store, store.get_parent(block), slot)`.
* Let `get_latest_attestation(store, validator)` be the attestation with the highest slot number in `store` from `validator`. If several such attestations exist, use the one the [validator](#dfn-validator) `v` observed first.
* Let `get_latest_attestation_target(store, validator)` be the target block in the attestation `get_latest_attestation(store, validator)`.
* The head is `lmd_ghost(store, justified_head)` where the function `lmd_ghost` is defined below. Note that the implementation below is suboptimal; there are implementations that compute the head in time logarithmic in slot count.
* Let `get_ancestor(store: Store, block: BeaconBlock, slot: SlotNumber) -> BeaconBlock` be the ancestor of `block` with slot number `slot`. The `get_ancestor` function can be defined recursively as `def get_ancestor(store: Store, block: BeaconBlock, slot: SlotNumber) -> BeaconBlock: return block if block.slot == slot else get_ancestor(store, store.get_parent(block), slot)`.
* Let `get_latest_attestation(store: Store, validator: Validator) -> Attestation` be the attestation with the highest slot number in `store` from `validator`. If several such attestations exist, use the one the [validator](#dfn-validator) `v` observed first.
* Let `get_latest_attestation_target(store: Store, validator: Validator) -> BeaconBlock` be the target block in the attestation `get_latest_attestation(store, validator)`.
* Let `get_children(store: Store, block: BeaconBlock) -> List[BeaconBlock]` returns the child blocks of the given `block`.
* Let `justified_head_state` be the resulting `BeaconState` object from processing the chain up to the `justified_head`.
* The `head` is `lmd_ghost(store, justified_head_state, justified_head)` where the function `lmd_ghost` is defined below. Note that the implementation below is suboptimal; there are implementations that compute the head in time logarithmic in slot count.
```python
def lmd_ghost(store, start):
validators = start.state.validator_registry
active_validators = [validators[i] for i in
get_active_validator_indices(validators, start.state.slot)]
attestation_targets = [get_latest_attestation_target(store, validator)
for validator in active_validators]
def get_vote_count(block):
return len([target for target in attestation_targets if
get_ancestor(store, target, block.slot) == block])
def lmd_ghost(store: Store, start_state: BeaconState, start_block: BeaconBlock) -> BeaconBlock:
validators = start_state.validator_registry
active_validators = [
validators[i]
for i in get_active_validator_indices(validators, start_state.slot)
]
attestation_targets = [
get_latest_attestation_target(store, validator)
for validator in active_validators
]
head = start
def get_vote_count(block: BeaconBlock) -> int:
return len([
target
for target in attestation_targets
if get_ancestor(store, target, block.slot) == block
])
head = start_block
while 1:
children = get_children(head)
children = get_children(store, head)
if len(children) == 0:
return head
head = max(children, key=get_vote_count)
@ -760,11 +785,11 @@ Note: We aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethere
#### `hash_tree_root`
`hash_tree_root` is a function for hashing objects into a single root utilizing a hash tree structure. `hash_tree_root` is defined in the [SimpleSerialize spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/simple-serialize.md#tree-hash).
`def hash_tree_root(object: SSZSerializable) -> Bytes32` is a function for hashing objects into a single root utilizing a hash tree structure. `hash_tree_root` is defined in the [SimpleSerialize spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/simple-serialize.md#tree-hash).
#### `is_active_validator`
```python
def is_active_validator(validator: Validator, slot: int) -> bool:
def is_active_validator(validator: Validator, slot: SlotNumber) -> bool:
"""
Checks if ``validator`` is active.
"""
@ -774,7 +799,7 @@ def is_active_validator(validator: Validator, slot: int) -> bool:
#### `get_active_validator_indices`
```python
def get_active_validator_indices(validators: [Validator], slot: int) -> List[int]:
def get_active_validator_indices(validators: List[Validator], slot: SlotNumber) -> List[ValidatorIndex]:
"""
Gets indices of active validators from ``validators``.
"""
@ -866,7 +891,7 @@ def get_committee_count_per_slot(active_validator_count: int) -> int:
```python
def get_shuffling(seed: Bytes32,
validators: List[Validator],
slot: int) -> List[List[int]]
slot: SlotNumber) -> List[List[ValidatorIndex]]
"""
Shuffles ``validators`` into crosslink committees seeded by ``seed`` and ``slot``.
Returns a list of ``EPOCH_LENGTH * committees_per_slot`` committees where each
@ -918,7 +943,7 @@ def get_current_epoch_committee_count_per_slot(state: BeaconState) -> int:
```python
def get_crosslink_committees_at_slot(state: BeaconState,
slot: int) -> List[Tuple[List[int], int]]:
slot: SlotNumber) -> List[Tuple[List[ValidatorIndex], ShardNumber]]:
"""
Returns the list of ``(committee, shard)`` tuples for the ``slot``.
"""
@ -960,7 +985,7 @@ def get_crosslink_committees_at_slot(state: BeaconState,
```python
def get_block_root(state: BeaconState,
slot: int) -> Bytes32:
slot: SlotNumber) -> Bytes32:
"""
Returns the block root at a recent ``slot``.
"""
@ -975,7 +1000,7 @@ def get_block_root(state: BeaconState,
```python
def get_randao_mix(state: BeaconState,
slot: int) -> Bytes32:
slot: SlotNumber) -> Bytes32:
"""
Returns the randao mix at a recent ``slot``.
"""
@ -988,7 +1013,7 @@ def get_randao_mix(state: BeaconState,
```python
def get_active_index_root(state: BeaconState,
slot: int) -> Bytes32:
slot: SlotNumber) -> Bytes32:
"""
Returns the index root at a recent ``slot``.
"""
@ -1023,7 +1048,7 @@ def generate_seed(state: BeaconState,
```python
def get_beacon_proposer_index(state: BeaconState,
slot: int) -> int:
slot: SlotNumber) -> ValidatorIndex:
"""
Returns the beacon proposer index for the ``slot``.
"""
@ -1049,7 +1074,7 @@ def merkle_root(values: List[Bytes32]) -> Bytes32:
```python
def get_attestation_participants(state: BeaconState,
attestation_data: AttestationData,
aggregation_bitfield: bytes) -> List[int]:
aggregation_bitfield: bytes) -> List[ValidatorIndex]:
"""
Returns the participant indices at for the ``attestation_data`` and ``aggregation_bitfield``.
"""
@ -1077,7 +1102,7 @@ def get_attestation_participants(state: BeaconState,
#### `get_effective_balance`
```python
def get_effective_balance(state: State, index: int) -> int:
def get_effective_balance(state: State, index: ValidatorIndex) -> Gwei:
"""
Returns the effective balance (also known as "balance at stake") for a ``validator`` with the given ``index``.
"""
@ -1088,7 +1113,7 @@ def get_effective_balance(state: State, index: int) -> int:
```python
def get_fork_version(fork: Fork,
slot: int) -> int:
slot: SlotNumber) -> int:
if slot < fork.slot:
return fork.previous_version
else:
@ -1099,7 +1124,7 @@ def get_fork_version(fork: Fork,
```python
def get_domain(fork: Fork,
slot: int,
slot: SlotNumber,
domain_type: int) -> int:
return get_fork_version(
fork,
@ -1318,8 +1343,8 @@ First, a helper function:
```python
def validate_proof_of_possession(state: BeaconState,
pubkey: Bytes48,
proof_of_possession: Bytes96,
pubkey: BLSPubkey,
proof_of_possession: BLSSignature,
withdrawal_credentials: Bytes32) -> bool:
proof_of_possession_data = DepositInput(
pubkey=pubkey,
@ -1343,9 +1368,9 @@ Now, to add a [validator](#dfn-validator) or top up an existing [validator](#dfn
```python
def process_deposit(state: BeaconState,
pubkey: Bytes48,
amount: int,
proof_of_possession: Bytes96,
pubkey: BLSPubkey,
amount: Gwei,
proof_of_possession: BLSSignature,
withdrawal_credentials: Bytes32) -> None:
"""
Process a deposit from Ethereum 1.0.
@ -1366,7 +1391,6 @@ def process_deposit(state: BeaconState,
validator = Validator(
pubkey=pubkey,
withdrawal_credentials=withdrawal_credentials,
proposer_slots=0,
activation_slot=FAR_FUTURE_SLOT,
exit_slot=FAR_FUTURE_SLOT,
withdrawal_slot=FAR_FUTURE_SLOT,
@ -1393,20 +1417,20 @@ def process_deposit(state: BeaconState,
Note: All functions in this section mutate `state`.
```python
def activate_validator(state: BeaconState, index: int, genesis: bool) -> None:
def activate_validator(state: BeaconState, index: ValidatorIndex, genesis: bool) -> None:
validator = state.validator_registry[index]
validator.activation_slot = GENESIS_SLOT if genesis else entry_exit_effect_slot(state.slot)
```
```python
def initiate_validator_exit(state: BeaconState, index: int) -> None:
def initiate_validator_exit(state: BeaconState, index: ValidatorIndex) -> None:
validator = state.validator_registry[index]
validator.status_flags |= INITIATED_EXIT
```
```python
def exit_validator(state: BeaconState, index: int) -> None:
def exit_validator(state: BeaconState, index: ValidatorIndex) -> None:
validator = state.validator_registry[index]
# The following updates only occur if not previous exited
@ -1420,7 +1444,7 @@ def exit_validator(state: BeaconState, index: int) -> None:
```
```python
def penalize_validator(state: BeaconState, index: int) -> None:
def penalize_validator(state: BeaconState, index: ValidatorIndex) -> None:
exit_validator(state, index)
validator = state.validator_registry[index]
state.latest_penalized_balances[(state.slot // EPOCH_LENGTH) % LATEST_PENALIZED_EXIT_LENGTH] += get_effective_balance(state, index)
@ -1433,7 +1457,7 @@ def penalize_validator(state: BeaconState, index: int) -> None:
```
```python
def prepare_validator_for_withdrawal(state: BeaconState, index: int) -> None:
def prepare_validator_for_withdrawal(state: BeaconState, index: ValidatorIndex) -> None:
validator = state.validator_registry[index]
validator.status_flags |= WITHDRAWABLE
```
@ -1445,7 +1469,6 @@ Below are the processing steps that happen at every slot.
### Misc counters
* Set `state.slot += 1`.
* Set `state.validator_registry[get_beacon_proposer_index(state, state.slot)].proposer_slots += 1`.
* Set `state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH] = state.latest_randao_mixes[(state.slot - 1) % LATEST_RANDAO_MIXES_LENGTH]`
### Block roots
@ -1471,8 +1494,8 @@ Below are the processing steps that happen at every `block`.
### RANDAO
* Let `proposer = state.validator_registry[get_beacon_proposer_index(state, state.slot)]`.
* Verify that `bls_verify(pubkey=proposer.pubkey, message=int_to_bytes32(proposer.proposer_slots), signature=block.randao_reveal, domain=get_domain(state.fork, state.slot, DOMAIN_RANDAO))`.
* Set `state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH] = hash(state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH] + block.randao_reveal)`.
* Verify that `bls_verify(pubkey=proposer.pubkey, message=int_to_bytes32(state.slot // EPOCH_LENGTH), signature=block.randao_reveal, domain=get_domain(state.fork, state.slot, DOMAIN_RANDAO))`.
* Set `state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH] = xor(state.latest_randao_mixes[state.slot % LATEST_RANDAO_MIXES_LENGTH], hash(block.randao_reveal))`.
### Eth1 data
@ -1544,7 +1567,7 @@ For each `deposit` in `block.body.deposits`:
* Verify that `verify_merkle_branch(hash(serialized_deposit_data), deposit.branch, DEPOSIT_CONTRACT_TREE_DEPTH, deposit.index, state.latest_eth1_data.deposit_root)` is `True`.
```python
def verify_merkle_branch(leaf: Bytes32, branch: [Bytes32], depth: int, index: int, root: Bytes32) -> bool:
def verify_merkle_branch(leaf: Bytes32, branch: List[Bytes32], depth: int, index: int, root: Bytes32) -> bool:
value = leaf
for i in range(depth):
if index // (2**i) % 2:
@ -1835,8 +1858,8 @@ def process_penalties_and_exits(state: BeaconState) -> None:
def eligible(index):
validator = state.validator_registry[index]
if validator.penalized_slot <= state.slot:
PENALIZED_WITHDRAWAL_TIME = LATEST_PENALIZED_EXIT_LENGTH * EPOCH_LENGTH // 2
return state.slot >= validator.penalized_slot + PENALIZED_WITHDRAWAL_TIME
penalized_withdrawal_time = LATEST_PENALIZED_EXIT_LENGTH * EPOCH_LENGTH // 2
return state.slot >= validator.penalized_slot + penalized_withdrawal_time
else:
return state.slot >= validator.exit_slot + MIN_VALIDATOR_WITHDRAWAL_TIME

6
specs/validator/0_beacon-chain-validator.md
View File

@ -158,12 +158,12 @@ _Note_: To calculate `state_root`, the validator should first run the state tran
##### Randao reveal
Set `block.randao_reveal = reveal_signature` where `reveal_signature` is defined as:
Set `block.randao_reveal = epoch_signature` where `epoch_signature` is defined as:
```python
reveal_signature = bls_sign(
epoch_signature = bls_sign(
privkey=validator.privkey, # privkey store locally, not in state
message=int_to_bytes32(validator.proposer_slots + 1),
message=int_to_bytes32(block.slot // EPOCH_LENGTH),
domain=get_domain(
fork_data, # `fork_data` is the fork_data at the slot `block.slot`
block.slot,