Add EIP-7805 (FOCIL) specs

specs/_features/eip7805/beacon-chain.md

@@ -0,0 +1,183 @@
+# EIP-7805 -- The Beacon Chain
+
+## Table of contents
+
+<!-- TOC -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Introduction](#introduction)
+- [Preset](#preset)
+  - [Domain types](#domain-types)
+  - [Inclusion List Committee](#inclusion-list-committee)
+  - [Execution](#execution)
+- [Containers](#containers)
+  - [New containers](#new-containers)
+    - [`InclusionList`](#inclusionlist)
+    - [`SignedInclusionList`](#signedinclusionlist)
+  - [Predicates](#predicates)
+    - [New `is_valid_inclusion_list_signature`](#new-is_valid_inclusion_list_signature)
+  - [Beacon State accessors](#beacon-state-accessors)
+    - [`get_inclusion_list_committee`](#get_inclusion_list_committee)
+- [Beacon chain state transition function](#beacon-chain-state-transition-function)
+  - [Execution engine](#execution-engine)
+    - [Request data](#request-data)
+      - [Modified `NewPayloadRequest`](#modified-newpayloadrequest)
+    - [Engine APIs](#engine-apis)
+      - [Modified `notify_new_payload`](#modified-notify_new_payload)
+      - [Modified `verify_and_notify_new_payload`](#modified-verify_and_notify_new_payload)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
+
+## Introduction
+
+This is the beacon chain specification to add EIP-7805 / fork-choice enforced, committee-based inclusion list (FOCIL) mechanism to allow forced transaction inclusion. Refers to the following posts:
+- [Fork-Choice enforced Inclusion Lists (FOCIL): A simple committee-based inclusion list proposal](https://ethresear.ch/t/fork-choice-enforced-inclusion-lists-focil-a-simple-committee-based-inclusion-list-proposal/19870/1)
+- [FOCIL CL & EL workflow](https://ethresear.ch/t/focil-cl-el-workflow/20526)
+*Note:* This specification is built upon [Electra](../../electra/beacon_chain.md) and is under active development.
+
+## Preset
+
+### Domain types
+
+| Name | Value |
+| - | - |
+| `DOMAIN_IL_COMMITTEE`       | `DomainType('0x0C000000')`  # (New in EIP-7805)|
+
+### Inclusion List Committee
+
+| Name | Value | 
+| - | - | 
+| `IL_COMMITTEE_SIZE` | `uint64(2**4)` (=16)  # (New in EIP-7805) |
+
+### Execution
+
+| Name | Value |
+| - | - |
+| `MAX_TRANSACTIONS_PER_INCLUSION_LIST` |  `uint64(1)` # (New in EIP-7805) TODO: Placeholder | 
+
+## Containers
+
+### New containers
+
+#### `InclusionList`
+
+```python
+class InclusionList(Container):
+    slot: Slot
+    validator_index: ValidatorIndex
+    inclusion_list_committee_root: Root
+    transactions: List[Transaction, MAX_TRANSACTIONS_PER_INCLUSION_LIST]
+```
+
+#### `SignedInclusionList`
+
+```python
+class SignedInclusionList(Container):
+    message: InclusionList
+    signature: BLSSignature
+```
+
+### Predicates
+
+#### New `is_valid_inclusion_list_signature`
+
+```python
+def is_valid_inclusion_list_signature(
+        state: BeaconState, 
+        signed_inclusion_list: SignedInclusionList) -> bool:
+    """
+    Check if ``signed_inclusion_list`` has a valid signature
+    """
+    message = signed_inclusion_list.message
+    index = message.validator_index
+    pubkey = state.validators[index].pubkey
+    domain = get_domain(state, DOMAIN_IL_COMMITTEE, compute_epoch_at_slot(message.slot))
+    signing_root = compute_signing_root(message, domain)
+    return bls.FastAggregateVerify(pubkey, signing_root, signed_inclusion_list.signature)
+```
+
+### Beacon State accessors
+
+#### `get_inclusion_list_committee`
+
+```python
+def get_inclusion_list_committee(state: BeaconState, slot: Slot) -> Vector[ValidatorIndex, IL_COMMITTEE_SIZE]:
+    epoch = compute_epoch_at_slot(slot)
+    seed = get_seed(state, epoch, DOMAIN_IL_COMMITTEE)
+    indices = get_active_validator_indices(state, epoch)
+    start = (slot % SLOTS_PER_EPOCH) * IL_COMMITTEE_SIZE
+    end = start + IL_COMMITTEE_SIZE
+    return [indices[compute_shuffled_index(uint64(i), uint64(len(indices)), seed)] for i in range(start, end)]
+```
+
+## Beacon chain state transition function
+
+### Execution engine
+
+#### Request data
+
+##### Modified `NewPayloadRequest`
+
+```python
+@dataclass
+class NewPayloadRequest(object):
+    execution_payload: ExecutionPayload
+    versioned_hashes: Sequence[VersionedHash]
+    parent_beacon_block_root: Root
+    execution_requests: ExecutionRequests 
+    il_transactions: List[Transaction, MAX_TRANSACTIONS_PER_INCLUSION_LIST]  # [New in EIP-7805]
+```
+
+#### Engine APIs
+
+##### Modified `notify_new_payload`
+
+*Note*: The function `notify_new_payload` is modified to include the additional `il_transactions` parameter in EIP-7805.
+
+```python
+def notify_new_payload(self: ExecutionEngine,
+                       execution_payload: ExecutionPayload,
+                       execution_requests: ExecutionRequests,
+                       parent_beacon_block_root: Root,
+                       il_transactions: List[Transaction, MAX_TRANSACTIONS_PER_INCLUSION_LIST] ) -> bool:
+    """
+    Return ``True`` if and only if ``execution_payload`` and ``execution_requests`` 
+    are valid with respect to ``self.execution_state``.
+    """
+    ...
+```
+
+##### Modified `verify_and_notify_new_payload`
+
+*Note*: The function `verify_and_notify_new_payload` is modified to pass the additional parameter `il_transactions`
+when calling `notify_new_payload` in EIP-7805.
+
+```python
+def verify_and_notify_new_payload(self: ExecutionEngine,
+                                  new_payload_request: NewPayloadRequest) -> bool:
+    """
+    Return ``True`` if and only if ``new_payload_request`` is valid with respect to ``self.execution_state``.
+    """
+    execution_payload = new_payload_request.execution_payload
+    execution_requests = new_payload_request.execution_requests
+    parent_beacon_block_root = new_payload_request.parent_beacon_block_root
+    il_transactions = new_payload_request.il_transactions # [New in EIP-7805]
+
+    if not self.is_valid_block_hash(execution_payload, parent_beacon_block_root):
+        return False
+
+    if not self.is_valid_versioned_hashes(new_payload_request):
+        return False
+
+    # [Modified in EIP-7805]
+    if not self.notify_new_payload(
+            execution_payload, 
+            execution_requests, 
+            parent_beacon_block_root,
+            il_transactions):
+        return False
+
+    return True
+```

specs/_features/eip7805/fork-choice.md

@@ -0,0 +1,109 @@
+# EIP-7805 -- Fork Choice
+
+## Table of contents
+<!-- TOC -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Introduction](#introduction)
+- [Helpers](#helpers)
+  - [New `validate_inclusion_lists`](#new-validate_inclusion_lists)
+  - [Modified `Store`](#modified-store)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
+
+## Introduction
+
+This is the modification of the fork choice accompanying the EIP-7805 upgrade.
+
+## Configuration
+
+| Name | Value | Unit | Duration |
+| - | - | :-: | :-: |
+| `VIEW_FREEZE_DEADLINE` | `uint64(9)` | seconds | 9 seconds | # [New in EIP-7805]
+
+## Helpers
+
+### New `validate_inclusion_lists`
+
+```python
+def validate_inclusion_lists(store: Store, inclusion_list_transactions: List[Transaction, MAX_TRANSACTIONS_PER_INCLUSION_LIST * IL_COMMITTEE_SIZE], execution_payload: ExecutionPayload) -> bool:
+    """
+    Return ``True`` if and only if the input ``inclusion_list_transactions`` satifies validation, that to verify if the `execution_payload` satisfies `inclusion_list_transactions` validity conditions either when all transactions are present in payload or when any missing transactions are found to be invalid when appended to the end of the payload unless the block is full.
+    """
+    ...
+```
+
+### Modified `Store` 
+**Note:** `Store` is modified to track the seen inclusion lists.
+
+```python
+@dataclass
+class Store(object):
+    time: uint64
+    genesis_time: uint64
+    justified_checkpoint: Checkpoint
+    finalized_checkpoint: Checkpoint
+    unrealized_justified_checkpoint: Checkpoint
+    unrealized_finalized_checkpoint: Checkpoint
+    proposer_boost_root: Root
+    equivocating_indices: Set[ValidatorIndex]
+    blocks: Dict[Root, BeaconBlock] = field(default_factory=dict)
+    block_states: Dict[Root, BeaconState] = field(default_factory=dict)
+    block_timeliness: Dict[Root, boolean] = field(default_factory=dict)
+    checkpoint_states: Dict[Checkpoint, BeaconState] = field(default_factory=dict)
+    latest_messages: Dict[ValidatorIndex, LatestMessage] = field(default_factory=dict)
+    unrealized_justifications: Dict[Root, Checkpoint] = field(default_factory=dict)
+    inclusion_lists: Dict[Tuple[Slot, Root], List[InclusionList]] = field(default_factory=dict) # [New in EIP-7805]
+    inclusion_list_equivocators: Dict[Tuple[Slot, Root], Set[ValidatorIndex]] = field(default_factory=dict) # [New in EIP-7805]
+```
+
+### New `on_inclusion_list`
+
+`on_inclusion_list` is called to import `signed_inclusion_list` to the fork choice store.
+```python
+def on_inclusion_list(
+        store: Store, 
+        signed_inclusion_list: SignedInclusionList, 
+        inclusion_list_committee: Vector[ValidatorIndex, IL_COMMITTEE_SIZE]]) -> None:
+    """
+    ``on_inclusion_list`` verify the inclusion list before importing it to fork choice store.
+    If there exists more than 1 inclusion list in store with the same slot and validator index, remove the original one.
+    """
+    message = signed_inclusion_list.message
+    # Verify inclusion list slot is either from the current or previous slot
+    assert get_current_slot(store) in [message.slot, message.slot + 1]
+
+    time_into_slot = (store.time - store.genesis_time) % SECONDS_PER_SLOT
+    is_before_attesting_interval = time_into_slot < SECONDS_PER_SLOT // INTERVALS_PER_SLOT
+    # If the inclusion list is from the previous slot, ignore it if already past the attestation deadline
+    if get_current_slot(store) == message.slot + 1:
+        assert is_before_attesting_interval
+
+    # Sanity check that the given `inclusion_list_committee` matches the root in the inclusion list
+    root = message.inclusion_list_committee_root
+    assert hash_tree_root(inclusion_list_committee) == root
+
+    # Verify inclusion list validator is part of the committee
+    validator_index = message.validator_index
+    assert validator_index in inclusion_list_committee
+
+    # Verify inclusion list signature
+    assert is_valid_inclusion_list_signature(state, signed_inclusion_list)
+
+    is_before_freeze_deadline = get_current_slot(store) == message.slot and time_into_slot < VIEW_FREEZE_DEADLINE
+
+    # Do not process inclusion lists from known equivocators
+    if validator_index not in inclusion_list_equivocators[(message.slot, root)]:
+        if validator_index in [il.validator_index for il in inclusion_lists[(message.slot, root)]]:
+            il = [il for il in inclusion_lists[(message.slot, root)] if il.validator_index == validator_index][0]
+            if not il == message:
+                # We have equivocation evidence for `validator_index`, record it as equivocator
+                inclusion_list_equivocators[(message.slot, root)].add(validator_index)
+        # This inclusion list is not an equivocation. Store it if prior to the view freeze deadline
+        elif is_before_freeze_deadline:
+            inclusion_lists[(message.slot, root)].append(message)
+```
+
+

specs/_features/eip7805/p2p-interface.md

@@ -0,0 +1,87 @@
+# EIP-7805 -- Networking
+
+This document contains the consensus-layer networking specification for EIP-7805.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Time parameters](#time-parameters)
+- [Configuration](#configuration)
+- [The gossip domain: gossipsub](#the-gossip-domain-gossipsub)
+  - [Topics and messages](#topics-and-messages)
+    - [Global topics](#global-topics)
+      - [`inclusion_list`](#inclusion_list)
+- [The Req/Resp domain](#the-reqresp-domain)
+  - [Messages](#messages)
+    - [InclusionListByCommitteeIndices v1](#inclusionlistbycommitteeindices-v1)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+### Time parameters
+
+| Name | Value | Unit | Duration |
+| - | - | :-: | :-: |
+| `attestation_deadline` | `uint64(4)` | seconds | 4 seconds |
+
+### Configuration
+
+| `MAX_REQUEST_INCLUSION_LIST` | `2**4` (= 16) | Maximum number of inclusion list in a single request |
+
+### The gossip domain: gossipsub
+
+#### Topics and messages
+
+The new topics along with the type of the `data` field of a gossipsub message are given in this table:
+
+| Name                          | Message Type                                         |
+|-------------------------------|------------------------------------------------------|
+| `inclusion_list`    | `SignedInclusionList` [New in EIP-7805] |
+
+##### Global topics
+
+EIP-7805 introduces a new global topic for inclusion lists.
+
+###### `inclusion_list`
+
+This topic is used to propagate signed inclusion list as `SignedInclusionList`.
+The following validations MUST pass before forwarding the `inclusion_list` on the network, assuming the alias `message = signed_inclusion_list.message`:
+
+- _[REJECT]_ The slot `message.slot` is equal to the previous or current slot.
+- _[IGNORE]_ The slot `message.slot` is equal to the current slot, or it is equal to the previous slot and the current time is less than `attestation_deadline` seconds into the slot.
+- _[IGNORE]_ The `inclusion_list_committee` for slot `message.slot` on the current branch corresponds to `message.inclusion_list_committee_root`, as determined by `hash_tree_root(inclusion_list_committee) == message.inclusion_list_committee_root`.
+- _[REJECT]_ The validator index `message.validator_index` is within the `inclusion_list_committee` corresponding to `message.inclusion_list_committee_root`.  
+- _[REJECT]_ The transactions `message.transactions` length is within upperbound `MAX_TRANSACTIONS_PER_INCLUSION_LIST`.
+- _[IGNORE]_ The `message` is either the first or second valid message received from the validator with index `message.validator_index`.
+- _[REJECT]_ The signature of `inclusion_list.signature` is valid with respect to the validator index.
+
+
+### The Req/Resp domain
+
+#### Messages
+
+##### InclusionListByCommitteeIndices v1
+
+**Protocol ID:** `/eth2/beacon_chain/req/inclusion_list_by_committee_indices/1/`
+
+The `<context-bytes>` field is calculated as `context = compute_fork_digest(fork_version, genesis_validators_root)`:
+
+[1]: # (eth2spec: skip)
+
+| `fork_version`         | Chunk SSZ type                           |
+|------------------------|------------------------------------------|
+| `EIP-7805_FORK_VERSION` | `EIP-7805.SignedInclusionList` |
+
+Request Content:
+```
+(
+  slot: Slot
+  committee_indices: Bitvector[IL_COMMITTEE_SIZE]
+)
+```
+
+Response Content:
+```
+(
+  List[SignedInclusionList, MAX_REQUEST_INCLUSION_LIST]
+)
+```