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

Refactor and add docstring.

This commit is contained in:
Hsiao-Wei Wang 2019-01-30 17:25:39 +08:00
parent a2e0ec5ec3
commit 5e0691f3df
No known key found for this signature in database
GPG Key ID: 95B070122902DEA4
1 changed files with 77 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -310,7 +310,7 @@ The following data structures are defined as [SimpleSerialize (SSZ)](https://git
```python ```python
{ {
# Validator indices # Validator indices
'validator_indices': '[uint64]', 'validator_indices': ['uint64'],
# Custody bitfield # Custody bitfield
'custody_bitfield': 'bytes', 'custody_bitfield': 'bytes',
# Attestation data # Attestation data
@ -634,6 +634,9 @@ Note: We aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethere
```python ```python
def slot_to_epoch(slot: SlotNumber) -> EpochNumber: def slot_to_epoch(slot: SlotNumber) -> EpochNumber:
"""
Returns the epoch number of the given ``slot``.
"""
return slot // EPOCH_LENGTH return slot // EPOCH_LENGTH
``` ```
@ -641,6 +644,9 @@ def slot_to_epoch(slot: SlotNumber) -> EpochNumber:
```python ```python
def get_current_epoch(state: BeaconState) -> EpochNumber: def get_current_epoch(state: BeaconState) -> EpochNumber:
"""
Returns the current epoch of the given ``state``.
"""
return slot_to_epoch(state.slot) return slot_to_epoch(state.slot)
``` ```
@ -648,6 +654,9 @@ def get_current_epoch(state: BeaconState) -> EpochNumber:
```python ```python
def get_epoch_start_slot(epoch: EpochNumber) -> SlotNumber: def get_epoch_start_slot(epoch: EpochNumber) -> SlotNumber:
"""
Returns the starting slot of the given ``epoch``.
"""
return epoch * EPOCH_LENGTH return epoch * EPOCH_LENGTH
``` ```
@ -741,6 +750,9 @@ def split(values: List[Any], split_count: int) -> List[List[Any]]:
```python ```python
def get_epoch_committee_count(active_validator_count: int) -> int: def get_epoch_committee_count(active_validator_count: int) -> int:
"""
Returns the number of committees in one epoch.
"""
return max( return max(
1, 1,
min( min(
@ -782,6 +794,9 @@ def get_shuffling(seed: Bytes32,
```python ```python
def get_previous_epoch_committee_count(state: BeaconState) -> int: def get_previous_epoch_committee_count(state: BeaconState) -> int:
"""
Returns the number of committees in the previous epoch of the given ``state``.
"""
previous_active_validators = get_active_validator_indices( previous_active_validators = get_active_validator_indices(
state.validator_registry, state.validator_registry,
state.previous_calculation_epoch, state.previous_calculation_epoch,
@ -793,6 +808,9 @@ def get_previous_epoch_committee_count(state: BeaconState) -> int:
```python ```python
def get_current_epoch_committee_count(state: BeaconState) -> int: def get_current_epoch_committee_count(state: BeaconState) -> int:
"""
Returns the number of committees in the current epoch of the given ``state``.
"""
current_active_validators = get_active_validator_indices( current_active_validators = get_active_validator_indices(
state.validator_registry, state.validator_registry,
state.current_calculation_epoch, state.current_calculation_epoch,
@ -970,6 +988,9 @@ def get_effective_balance(state: State, index: ValidatorIndex) -> Gwei:
```python ```python
def get_fork_version(fork: Fork, def get_fork_version(fork: Fork,
epoch: EpochNumber) -> int: epoch: EpochNumber) -> int:
"""
Returns the fork version of the given ``epoch``.
"""
if epoch < fork.epoch: if epoch < fork.epoch:
return fork.previous_version return fork.previous_version
else: else:
@ -982,10 +1003,11 @@ def get_fork_version(fork: Fork,
def get_domain(fork: Fork, def get_domain(fork: Fork,
epoch: EpochNumber, epoch: EpochNumber,
domain_type: int) -> int: domain_type: int) -> int:
return get_fork_version( """
fork, Get the domain number that represents the fork meta and signature domain.
epoch, """
) * 2**32 + domain_type fork_version = get_fork_version(fork, epoch)
return fork_version * 2**32 + domain_type
``` ```
### `get_bitfield_bit` ### `get_bitfield_bit`
@ -1052,8 +1074,8 @@ def verify_slashable_vote(state: BeaconState, slashable_vote: SlashableVote) ->
bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in custody_bit_1_indices]), bls_aggregate_pubkeys([state.validator_registry[i].pubkey for i in custody_bit_1_indices]),
], ],
messages=[ messages=[
hash_tree_root(AttestationDataAndCustodyBit(attestation_data=slashable_vote.data, custody_bit=0b0)), hash_tree_root(AttestationDataAndCustodyBit(data=slashable_vote.data, custody_bit=0b0)),
hash_tree_root(AttestationDataAndCustodyBit(attestation_data=slashable_vote.data, custody_bit=0b1)), hash_tree_root(AttestationDataAndCustodyBit(data=slashable_vote.data, custody_bit=0b1)),
], ],
signature=slashable_vote.aggregate_signature, signature=slashable_vote.aggregate_signature,
domain=get_domain( domain=get_domain(
@ -1068,7 +1090,7 @@ def verify_slashable_vote(state: BeaconState, slashable_vote: SlashableVote) ->
```python ```python
def is_double_vote(attestation_data_1: AttestationData, def is_double_vote(attestation_data_1: AttestationData,
attestation_data_2: AttestationData) -> bool attestation_data_2: AttestationData) -> bool:
""" """
Assumes ``attestation_data_1`` is distinct from ``attestation_data_2``. Assumes ``attestation_data_1`` is distinct from ``attestation_data_2``.
Returns True if the provided ``AttestationData`` are slashable Returns True if the provided ``AttestationData`` are slashable
@ -1148,6 +1170,9 @@ def validate_proof_of_possession(state: BeaconState,
pubkey: BLSPubkey, pubkey: BLSPubkey,
proof_of_possession: BLSSignature, proof_of_possession: BLSSignature,
withdrawal_credentials: Bytes32) -> bool: withdrawal_credentials: Bytes32) -> bool:
"""
Verify the given ``proof_of_possession``.
"""
proof_of_possession_data = DepositInput( proof_of_possession_data = DepositInput(
pubkey=pubkey, pubkey=pubkey,
withdrawal_credentials=withdrawal_credentials, withdrawal_credentials=withdrawal_credentials,
@ -1221,16 +1246,24 @@ Note: All functions in this section mutate `state`.
#### `activate_validator` #### `activate_validator`
```python ```python
def activate_validator(state: BeaconState, index: ValidatorIndex, genesis: bool) -> None: def activate_validator(state: BeaconState, index: ValidatorIndex, is_genesis: bool) -> None:
"""
Activate the validator of the given ``index``.
Note that this function mutates ``state``.
"""
validator = state.validator_registry[index] validator = state.validator_registry[index]
validator.activation_epoch = GENESIS_EPOCH if genesis else get_entry_exit_effect_epoch(get_current_epoch(state)) validator.activation_epoch = GENESIS_EPOCH if is_genesis else get_entry_exit_effect_epoch(get_current_epoch(state))
``` ```
#### `initiate_validator_exit` #### `initiate_validator_exit`
```python ```python
def initiate_validator_exit(state: BeaconState, index: ValidatorIndex) -> None: def initiate_validator_exit(state: BeaconState, index: ValidatorIndex) -> None:
"""
Initiate the validator of the given ``index``.
Note that this function mutates ``state``.
"""
validator = state.validator_registry[index] validator = state.validator_registry[index]
validator.status_flags |= INITIATED_EXIT validator.status_flags |= INITIATED_EXIT
``` ```
@ -1239,6 +1272,10 @@ def initiate_validator_exit(state: BeaconState, index: ValidatorIndex) -> None:
```python ```python
def exit_validator(state: BeaconState, index: ValidatorIndex) -> None: def exit_validator(state: BeaconState, index: ValidatorIndex) -> None:
"""
Exit the validator of the given ``index``.
Note that this function mutates ``state``.
"""
validator = state.validator_registry[index] validator = state.validator_registry[index]
# The following updates only occur if not previous exited # The following updates only occur if not previous exited
@ -1255,6 +1292,10 @@ def exit_validator(state: BeaconState, index: ValidatorIndex) -> None:
```python ```python
def penalize_validator(state: BeaconState, index: ValidatorIndex) -> None: def penalize_validator(state: BeaconState, index: ValidatorIndex) -> None:
"""
Penalize the validator of the given ``index``.
Note that this function mutates ``state``.
"""
exit_validator(state, index) exit_validator(state, index)
validator = state.validator_registry[index] validator = state.validator_registry[index]
state.latest_penalized_balances[get_current_epoch(state) % LATEST_PENALIZED_EXIT_LENGTH] += get_effective_balance(state, index) state.latest_penalized_balances[get_current_epoch(state) % LATEST_PENALIZED_EXIT_LENGTH] += get_effective_balance(state, index)
@ -1270,6 +1311,10 @@ def penalize_validator(state: BeaconState, index: ValidatorIndex) -> None:
```python ```python
def prepare_validator_for_withdrawal(state: BeaconState, index: ValidatorIndex) -> None: def prepare_validator_for_withdrawal(state: BeaconState, index: ValidatorIndex) -> None:
"""
Set the validator with the given ``index`` with ``WITHDRAWABLE`` flag.
Note that this function mutates ``state``.
"""
validator = state.validator_registry[index] validator = state.validator_registry[index]
validator.status_flags |= WITHDRAWABLE validator.status_flags |= WITHDRAWABLE
``` ```
@ -1398,6 +1443,9 @@ A valid block with slot `GENESIS_SLOT` (a "genesis block") has the following val
def get_initial_beacon_state(initial_validator_deposits: List[Deposit], def get_initial_beacon_state(initial_validator_deposits: List[Deposit],
genesis_time: int, genesis_time: int,
latest_eth1_data: Eth1Data) -> BeaconState: latest_eth1_data: Eth1Data) -> BeaconState:
"""
Get the initial ``BeaconState``.
"""
state = BeaconState( state = BeaconState(
# Misc # Misc
slot=GENESIS_SLOT, slot=GENESIS_SLOT,
@ -1456,7 +1504,7 @@ def get_initial_beacon_state(initial_validator_deposits: List[Deposit],
# Process initial activations # Process initial activations
for validator_index, _ in enumerate(state.validator_registry): for validator_index, _ in enumerate(state.validator_registry):
if get_effective_balance(state, validator_index) >= MAX_DEPOSIT_AMOUNT: if get_effective_balance(state, validator_index) >= MAX_DEPOSIT_AMOUNT:
activate_validator(state, validator_index, True) activate_validator(state, validator_index, is_genesis=True)
state.latest_index_roots[GENESIS_EPOCH % LATEST_INDEX_ROOTS_LENGTH] = hash_tree_root(get_active_validator_indices(state.validator_registry, GENESIS_EPOCH)) state.latest_index_roots[GENESIS_EPOCH % LATEST_INDEX_ROOTS_LENGTH] = hash_tree_root(get_active_validator_indices(state.validator_registry, GENESIS_EPOCH))
state.current_epoch_seed = generate_seed(state, GENESIS_EPOCH) state.current_epoch_seed = generate_seed(state, GENESIS_EPOCH)
@ -1495,6 +1543,9 @@ The beacon chain fork choice rule is a hybrid that combines justification and fi
```python ```python
def get_ancestor(store: Store, block: BeaconBlock, slot: SlotNumber) -> BeaconBlock: def get_ancestor(store: Store, block: BeaconBlock, slot: SlotNumber) -> BeaconBlock:
"""
Get the ancestor of ``block`` with slot number ``slot``; return ``None`` if not found.
"""
if block.slot == slot: if block.slot == slot:
return block return block
elif block.slot < slot: elif block.slot < slot:
@ -1511,6 +1562,9 @@ def get_ancestor(store: Store, block: BeaconBlock, slot: SlotNumber) -> BeaconBl
```python ```python
def lmd_ghost(store: Store, start_state: BeaconState, start_block: BeaconBlock) -> BeaconBlock: def lmd_ghost(store: Store, start_state: BeaconState, start_block: BeaconBlock) -> BeaconBlock:
"""
Execute the LMD-GHOST algorithm to find the head ``BeaconBlock``.
"""
validators = start_state.validator_registry validators = start_state.validator_registry
active_validators = [ active_validators = [
validators[i] validators[i]
@ -1676,6 +1730,9 @@ For each `deposit` in `block.body.deposits`:
```python ```python
def verify_merkle_branch(leaf: Bytes32, branch: List[Bytes32], depth: int, index: int, root: Bytes32) -> bool: def verify_merkle_branch(leaf: Bytes32, branch: List[Bytes32], depth: int, index: int, root: Bytes32) -> bool:
"""
Verify that the given ``leaf`` is on the merkle branch ``branch``.
"""
value = leaf value = leaf
for i in range(depth): for i in range(depth):
if index // (2**i) % 2: if index // (2**i) % 2:
@ -1906,7 +1963,7 @@ def update_validator_registry(state: BeaconState) -> None:
break break
# Activate validator # Activate validator
activate_validator(state, index, False) activate_validator(state, index, is_genesis=False)
# Exit validators within the allowable balance churn # Exit validators within the allowable balance churn
balance_churn = 0 balance_churn = 0
@ -1943,17 +2000,21 @@ Regardless of whether or not a validator set change happens, run the following:
```python ```python
def process_penalties_and_exits(state: BeaconState) -> None: def process_penalties_and_exits(state: BeaconState) -> None:
"""
Process the penalties and prepare the validators who are eligible to withdrawal.
Note that this function mutates ``state``.
"""
current_epoch = get_current_epoch(state) current_epoch = get_current_epoch(state)
# The active validators # The active validators
active_validator_indices = get_active_validator_indices(state.validator_registry, current_epoch) active_validator_indices = get_active_validator_indices(state.validator_registry, current_epoch)
# The total effective balance of active validators # The total effective balance of active validators
total_balance = sum([get_effective_balance(state, i) for i in active_validator_indices]) total_balance = sum(get_effective_balance(state, i) for i in active_validator_indices)
for index, validator in enumerate(state.validator_registry): for index, validator in enumerate(state.validator_registry):
if current_epoch == validator.penalized_epoch + LATEST_PENALIZED_EXIT_LENGTH // 2: if current_epoch == validator.penalized_epoch + LATEST_PENALIZED_EXIT_LENGTH // 2:
e = current_epoch % LATEST_PENALIZED_EXIT_LENGTH epoch_index = current_epoch % LATEST_PENALIZED_EXIT_LENGTH
total_at_start = state.latest_penalized_balances[(e + 1) % LATEST_PENALIZED_EXIT_LENGTH] total_at_start = state.latest_penalized_balances[(epoch_index + 1) % LATEST_PENALIZED_EXIT_LENGTH]
total_at_end = state.latest_penalized_balances[e] total_at_end = state.latest_penalized_balances[epoch_index]
total_penalties = total_at_end - total_at_start total_penalties = total_at_end - total_at_start
penalty = get_effective_balance(state, index) * min(total_penalties * 3, total_balance) // total_balance penalty = get_effective_balance(state, index) * min(total_penalties * 3, total_balance) // total_balance
state.validator_balances[index] -= penalty state.validator_balances[index] -= penalty