eth2.0-specs/specs/core/1_shard-data-chains.md

Ethereum 2.0 Phase 1 -- Shard Data Chains

Notice: This document is a work-in-progress for researchers and implementers.

Table of contents

• Ethereum 2.0 Phase 1 -- Shard Data Chains
  • Table of contents
  • Introduction
  • Configuration
    • Misc
    • Initial values
    • Time parameters
    • Signature domains
  • Data structures
    • ShardBlockBody
    • ShardAttestation
    • ShardBlock
    • ShardBlockHeader
  • Helper functions
    • get_period_committee
    • get_switchover_epoch
    • get_persistent_committee
    • get_shard_proposer_index
    • get_shard_header
    • verify_shard_attestation_signature
    • compute_crosslink_data_root
  • Object validity
    • Shard blocks
    • Shard attestations
    • Beacon attestations
  • Shard fork choice rule

Introduction

This document describes the shard data layer and the shard fork choice rule in Phase 1 of Ethereum 2.0.

Configuration

Misc

Name	Value
BYTES_PER_SHARD_BLOCK_BODY	2**14 (= 16,384)
MAX_SHARD_ATTESTIONS	2**4 (= 16)

Initial values

| Name | Value | | PHASE_1_FORK_EPOCH | TBD | | PHASE_1_FORK_SLOT | TBD | | GENESIS_SHARD_SLOT | 0 |

Time parameters

Name	Value	Unit	Duration
CROSSLINK_LOOKBACK	2**0 (= 1)	epochs	6.2 minutes
PERSISTENT_COMMITTEE_PERIOD	2**11 (= 2,048)	epochs	~9 days

Signature domains

Name	Value
DOMAIN_SHARD_PROPOSER	128
DOMAIN_SHARD_ATTESTER	129

TODO PLACEHOLDER

Name	Value
PLACEHOLDER	2**32

Data structures

ShardBlockBody

class ShardBlockBody(Container):
    data: Vector[Bytes[PLACEHOLDER], BYTES_PER_SHARD_BLOCK_BODY]

ShardAttestation

class ShardAttestation(Container):
    class data(Container):
        slot: Slot
        shard: Shard
        shard_block_root: Bytes32
    aggregation_bits: Bitlist[PLACEHOLDER]
    aggregate_signature: BLSSignature

ShardBlock

class ShardBlock(Container):
    slot: Slot
    shard: Shard
    beacon_chain_root: Bytes32
    parent_root: Bytes32
    data: ShardBlockBody
    state_root: Bytes32
    attestations: List[ShardAttestation, PLACEHOLDER]
    signature: BLSSignature

ShardBlockHeader

class ShardBlockHeader(Container):
    slot: Slot
    shard: Shard
    beacon_chain_root: Bytes32
    parent_root: Bytes32
    body_root: Bytes32
    state_root: Bytes32
    attestations: List[ShardAttestation, PLACEHOLDER]
    signature: BLSSignature

Helper functions

get_period_committee

def get_period_committee(state: BeaconState,
                         epoch: Epoch,
                         shard: Shard,
                         index: int,
                         count: int) -> Sequence[ValidatorIndex]:
    """
    Return committee for a period. Used to construct persistent committees.
    """
    return compute_committee(
        indices=get_active_validator_indices(state, epoch),
        seed=generate_seed(state, epoch),
        index=shard * count + index,
        count=SHARD_COUNT * count,
    )

get_switchover_epoch

def get_switchover_epoch(state: BeaconState, epoch: Epoch, index: ValidatorIndex) -> int:
    earlier_start_epoch = Epoch(epoch - (epoch % PERSISTENT_COMMITTEE_PERIOD) - PERSISTENT_COMMITTEE_PERIOD * 2)
    return (bytes_to_int(hash(generate_seed(state, earlier_start_epoch) + int_to_bytes(index, length=3)[0:8]))
            % PERSISTENT_COMMITTEE_PERIOD)

get_persistent_committee

def get_persistent_committee(state: BeaconState,
                             shard: Shard,
                             slot: Slot) -> Sequence[ValidatorIndex]:
    """
    Return the persistent committee for the given ``shard`` at the given ``slot``.
    """
    epoch = slot_to_epoch(slot)
    earlier_start_epoch = Epoch(epoch - (epoch % PERSISTENT_COMMITTEE_PERIOD) - PERSISTENT_COMMITTEE_PERIOD * 2)
    later_start_epoch = Epoch(epoch - (epoch % PERSISTENT_COMMITTEE_PERIOD) - PERSISTENT_COMMITTEE_PERIOD)

    committee_count = max(
        len(get_active_validator_indices(state, earlier_start_epoch)) //
        (SHARD_COUNT * TARGET_COMMITTEE_SIZE),
        len(get_active_validator_indices(state, later_start_epoch)) //
        (SHARD_COUNT * TARGET_COMMITTEE_SIZE),
    ) + 1

    index = slot % committee_count
    earlier_committee = get_period_committee(state, earlier_start_epoch, shard, index, committee_count)
    later_committee = get_period_committee(state, later_start_epoch, shard, index, committee_count)

    # Take not-yet-cycled-out validators from earlier committee and already-cycled-in validators from
    # later committee; return a sorted list of the union of the two, deduplicated
    return sorted(list(set(
        [i for i in earlier_committee if epoch % PERSISTENT_COMMITTEE_PERIOD < get_switchover_epoch(state, epoch, i)] +
        [i for i in later_committee if epoch % PERSISTENT_COMMITTEE_PERIOD >= get_switchover_epoch(state, epoch, i)]
    )))

get_shard_proposer_index

def get_shard_proposer_index(state: BeaconState,
                             shard: Shard,
                             slot: Slot) -> Optional[ValidatorIndex]:
    # Randomly shift persistent committee
    persistent_committee = list(get_persistent_committee(state, shard, slot))
    seed = hash(state.current_shuffling_seed + int_to_bytes(shard, length=8) + int_to_bytes(slot, length=8))
    random_index = bytes_to_int(seed[0:8]) % len(persistent_committee)
    persistent_committee = persistent_committee[random_index:] + persistent_committee[:random_index]

    # Search for an active proposer
    for index in persistent_committee:
        if is_active_validator(state.validators[index], get_current_epoch(state)):
            return index

    # No block can be proposed if no validator is active
    return None

get_shard_header

def get_shard_header(block: ShardBlock) -> ShardBlockHeader:
    return ShardBlockHeader(
        slot=block.slot,
        shard=block.shard,
        beacon_chain_root=block.beacon_chain_root,
        parent_root=block.parent_root,
        body_root=hash_tree_root(block.body),
        state_root=block.state_root,
        attestations=block.attestations,
        signature=block.signature,
    )

verify_shard_attestation_signature

def verify_shard_attestation_signature(state: BeaconState,
                                       attestation: ShardAttestation) -> None:
    data = attestation.data
    persistent_committee = get_persistent_committee(state, data.shard, data.slot)
    pubkeys = []
    for i, index in enumerate(persistent_committee):
        if attestation.aggregation_bits[i]:
            validator = state.validators[index]
            assert is_active_validator(validator, get_current_epoch(state))
            pubkeys.append(validator.pubkey)
    assert bls_verify(
        pubkey=bls_aggregate_pubkeys(pubkeys),
        message_hash=data.shard_block_root,
        signature=attestation.aggregate_signature,
        domain=get_domain(state, DOMAIN_SHARD_ATTESTER, slot_to_epoch(data.slot))
    )

compute_crosslink_data_root

def compute_crosslink_data_root(blocks: Sequence[ShardBlock]) -> Bytes32:
    def is_power_of_two(value: int) -> bool:
        return (value > 0) and (value & (value - 1) == 0)

    def pad_to_power_of_2(values: MutableSequence[bytes]) -> Sequence[bytes]:
        while not is_power_of_two(len(values)):
            values.append(b'\x00' * BYTES_PER_SHARD_BLOCK_BODY)
        return values

    def hash_tree_root_of_bytes(data: bytes) -> bytes:
        return hash_tree_root([data[i:i + 32] for i in range(0, len(data), 32)])

    def zpad(data: bytes, length: int) -> bytes:
        return data + b'\x00' * (length - len(data))

    return hash(
        # TODO untested code.
        #  Need to either pass a typed list to hash-tree-root, or merkleize_chunks(values, pad_to=2**x)
        hash_tree_root(pad_to_power_of_2([
            hash_tree_root_of_bytes(
                zpad(serialize(get_shard_header(block)), BYTES_PER_SHARD_BLOCK_BODY)
            ) for block in blocks
        ]))
        + hash_tree_root(pad_to_power_of_2([
            hash_tree_root_of_bytes(block.body) for block in blocks
        ]))
    )

Object validity

Shard blocks

Let:

• beacon_blocks be the BeaconBlock list such that beacon_blocks[slot] is the canonical BeaconBlock at slot slot
• beacon_state be the canonical BeaconState after processing beacon_blocks[-1]
• valid_shard_blocks be the list of valid ShardBlock, recursively defined
• candidate be a candidate ShardBlock for which validity is to be determined by running is_valid_shard_block

def is_valid_shard_block(beacon_blocks: Sequence[BeaconBlock],
                         beacon_state: BeaconState,
                         valid_shard_blocks: Sequence[ShardBlock],
                         candidate: ShardBlock) -> bool:
    # Check if block is already determined valid
    for _, block in enumerate(valid_shard_blocks):
        if candidate == block:
            return True

    # Check slot number
    assert candidate.slot >= PHASE_1_FORK_SLOT

    # Check shard number
    assert candidate.shard <= SHARD_COUNT

    # Check beacon block
    beacon_block = beacon_blocks[candidate.slot]
    assert candidate.beacon_block_root == signing_root(beacon_block)
    assert beacon_block.slot <= candidate.slot

    # Check state root
    assert candidate.state_root == ZERO_HASH  # [to be removed in phase 2]

    # Check parent block
    if candidate.slot == PHASE_1_FORK_SLOT:
        assert candidate.parent_root == ZERO_HASH
    else:
        parent_block = next(
            (block for block in valid_shard_blocks if signing_root(block) == candidate.parent_root),
            None
        )
        assert parent_block is not None
        assert parent_block.shard == candidate.shard
        assert parent_block.slot < candidate.slot
        assert signing_root(beacon_blocks[parent_block.slot]) == parent_block.beacon_chain_root

    # Check attestations
    assert len(candidate.attestations) <= MAX_SHARD_ATTESTIONS
    for _, attestation in enumerate(candidate.attestations):
        assert max(GENESIS_SHARD_SLOT, candidate.slot - SLOTS_PER_EPOCH) <= attestation.data.slot
        assert attestation.data.slot <= candidate.slot - MIN_ATTESTATION_INCLUSION_DELAY
        assert attestation.data.crosslink.shard == candidate.shard
        verify_shard_attestation_signature(beacon_state, attestation)

    # Check signature
    proposer_index = get_shard_proposer_index(beacon_state, candidate.shard, candidate.slot)
    assert proposer_index is not None
    assert bls_verify(
        pubkey=beacon_state.validators[proposer_index].pubkey,
        message_hash=signing_root(candidate),
        signature=candidate.signature,
        domain=get_domain(beacon_state, DOMAIN_SHARD_PROPOSER, slot_to_epoch(candidate.slot)),
    )

    return True

Shard attestations

Let:

• valid_shard_blocks be the list of valid ShardBlock
• beacon_state be the canonical BeaconState
• candidate be a candidate ShardAttestation for which validity is to be determined by running is_valid_shard_attestation

def is_valid_shard_attestation(valid_shard_blocks: Sequence[ShardBlock],
                               beacon_state: BeaconState,
                               candidate: ShardAttestation) -> bool:
    # Check shard block
    shard_block = next(
        (block for block in valid_shard_blocks if signing_root(block) == candidate.data.shard_block_root),
        None,
    )
    assert shard_block is not None
    assert shard_block.slot == candidate.data.slot
    assert shard_block.shard == candidate.data.shard

    # Check signature
    verify_shard_attestation_signature(beacon_state, candidate)

    return True

Beacon attestations

Let:

• shard be a valid Shard
• shard_blocks be the ShardBlock list such that shard_blocks[slot] is the canonical ShardBlock for shard shard at slot slot
• beacon_state be the canonical BeaconState
• valid_attestations be the set of valid Attestation objects, recursively defined
• candidate be a candidate Attestation which is valid under Phase 0 rules, and for which validity is to be determined under Phase 1 rules by running is_valid_beacon_attestation

def is_valid_beacon_attestation(shard: Shard,
                                shard_blocks: Sequence[ShardBlock],
                                beacon_state: BeaconState,
                                valid_attestations: Set[Attestation],
                                candidate: Attestation) -> bool:
    # Check if attestation is already determined valid
    for attestation in valid_attestations:
        if candidate == attestation:
            return True

    # Check previous attestation
    if candidate.data.previous_crosslink.epoch <= PHASE_1_FORK_EPOCH:
        assert candidate.data.previous_crosslink.data_root == ZERO_HASH
    else:
        previous_attestation = next(
            (attestation for attestation in valid_attestations if
                attestation.data.crosslink.data_root == candidate.data.previous_crosslink.data_root),
            None,
        )
        assert previous_attestation is not None
        assert candidate.data.previous_attestation.epoch < slot_to_epoch(candidate.data.slot)

    # Check crosslink data root
    start_epoch = beacon_state.crosslinks[shard].epoch
    end_epoch = min(slot_to_epoch(candidate.data.slot) - CROSSLINK_LOOKBACK, start_epoch + MAX_EPOCHS_PER_CROSSLINK)
    blocks = []
    for slot in range(start_epoch * SLOTS_PER_EPOCH, end_epoch * SLOTS_PER_EPOCH):
        blocks.append(shard_blocks[slot])
    assert candidate.data.crosslink.data_root == compute_crosslink_data_root(blocks)

    return True

Shard fork choice rule

The fork choice rule for any shard is LMD GHOST using the shard attestations of the persistent committee and the beacon chain attestations of the crosslink committee currently assigned to that shard, but instead of being rooted in the genesis it is rooted in the block referenced in the most recent accepted crosslink (i.e. state.crosslinks[shard].shard_block_root). Only blocks whose beacon_chain_root is the block in the main beacon chain at the specified slot should be considered. (If the beacon chain skips a slot, then the block at that slot is considered to be the block in the beacon chain at the highest slot lower than that slot.)