Merge pull request #68 from ethereum/prepare-subnets

update validator subnet subscriptions and validator flow doc

apis/validator/beacon_committee_subscriptions.yaml

@@ -1,11 +1,12 @@
 post:
-  operationId: "subscribeToBeaconCommitteeSubnet"
-  summary: Subscribe beacon node to committee attestation subnet
+  operationId: "prepareBeaconCommitteeSubnet"
+  summary: Signal beacon node to prepare for a committee subnet
   description: |
-    After Beacon node receives this request it has to:
-    - add subnet to ENR
+    After beacon node receives this request,
+    search using discv5 for peers related to this subnet
+    and replace current peers with those ones if necessary
+    If validator `is_aggregator`, beacon node must:
     - announce subnet topic subscription on gossipsub
-    - search using discv5 for peers related to this subnet and replace current peers with those ones if neccessary
     - aggregate attestations received on that subnet
   tags:
     - ValidatorRequiredApi
@@ -25,16 +26,14 @@ post:
                 allOf:
                   - $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64'
                   - description: "Should be slot at which validator is assigned to attest"
-              slot_signature:
-                allOf:
-                  - $ref: '../../beacon-node-oapi.yaml#/components/schemas/Signature'
-                  - description: "Should be valid against given slot and validator pubkey."
-              aggregator_pubkey:
-                $ref: '../../beacon-node-oapi.yaml#/components/schemas/PublicKey'
+              is_aggregator:
+                type: boolean
+                description: "Signals to BN that a validator on the VC has been chosed for aggregator role."
+
   responses:
     "200":
       description: |
-        Slot signature is valid and beacon node is subscribed to given committee attestation subnet.
+        Slot signature is valid and beacon node has prepared the attestation subnet.
 
         Note that, we cannot be certain Beacon node will find peers for that subnet for various reasons,"
     "400":

beacon-node-oapi.yaml

@@ -151,8 +151,6 @@ components:
       $ref: './types/misc.yaml#/Fork'
     Checkpoint:
       $ref: './types/misc.yaml#/Checkpoint'
-    PublicKey:
-      $ref: './types/primitive.yaml#/Pubkey'
     Uint64:
       $ref: './types/primitive.yaml#/Uint64'
     NetworkIdentity:

validator-flow.md

@@ -8,7 +8,7 @@ Detail explanation how validator should utilize this API to perform his regular
 On start of every epoch, validator should [fetch proposer duties](#/Validator/getProposerDuties).
 Result is array of objects, each containing proposer pubkey and slot at which he is suppose to propose.
 
-Proposing block:
+If proposing block, then at immediate start of slot:
 1. [Ask Beacon Node for BeaconBlock object](#/Validator/produceBlock)
 2. Sign block
 3. [Submit SignedBeaconBlock](#/ValidatorRequiredApi/publishBlock) (BeaconBlock + signature)
@@ -22,18 +22,23 @@ On start of every epoch, validator should ask for attester duties for epoch + 1.
 Result are array of objects with validator, his committee and attestation slot.
 
 Attesting:
-1. [Upon receiving duty check if aggregator](https://github.com/ethereum/eth2.0-specs/blob/v0.11.3/specs/phase0/validator.md#aggregation-selection)
-    - Validator is aggregator
-    - [Ask beacon node to subscribe to your subnet](#/ValidatorRequiredApi/subscribeToBeaconCommitteeSubnet)                                             
-2. on start of attesting slot, [fetch AttestationData](#/ValidatorRequiredApi/produceAttestationData)
-3. wait for AttestationData block (TBD)
-    - max wait: SECONDS_PER_SLOT / 3 * 1000
-4. [submit Attestation](#/ValidatorRequiredApi/submitPoolAttestations) (AttestationData + aggregation bits)
+1. Upon receiving duty, have beacon node prepare committee subnet
+    - [Check if aggregator by computing `slot_signature`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/validator.md#attestation-aggregation)
+    - [Ask beacon node to prepare your subnet](#/ValidatorRequiredApi/prepareBeaconCommitteeSubnet)
+      -- Note, validator client only needs to submit one call to
+      `prepareBeaconCommitteeSubnet` per committee/slot its validators have
+      been assigned to. If any validators in the committee are aggregators,
+      set `is_aggregator` to `True`,
+2. Wait for new BeaconBlock for the assigned slot (either stream updates or poll)
+    - Max wait: `SECONDS_PER_SLOT / 3` seconds into the assigned slot
+3. [Fetch AttestationData](#/ValidatorRequiredApi/produceAttestationData)
+4. [Submit Attestation](#/ValidatorRequiredApi/submitPoolAttestations) (AttestationData + aggregation bits)
     - Aggregation bits are `Bitlist` with length of committee (received in AttesterDuty)
     with bit on position `validator_committee_index` (see AttesterDuty) set to true
-5. [Featch aggregated attestation](#/ValidatorRequiredApi/getAggregatedAttestation) from Beacon Node you've subscribed to your subnet
-6. wait for SECONDS_PER_SLOT * 2 / 3 of attesting slot
-7. [Publish SignedAggregateAndProof](#/ValidatorRequiredApi/publishAggregateAndProof)
+5. If aggregator:
+    - Wait for `SECONDS_PER_SLOT * 2 / 3` seconds into the assigned slot
+    - [Fetch aggregated Attestation](#/ValidatorRequiredApi/getAggregatedAttestation) from Beacon Node you've subscribed to your subnet
+    - [Publish SignedAggregateAndProof](#/ValidatorRequiredApi/publishAggregateAndProof)
 
 Monitor chain block reorganization events (TBD) as they could change attesters and aggregators. 
 If reorg is detected, ask for new attester duties and proceed from 1..