update validator subscriptioins 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:
+    After beacon node receives this request, and `slot_signature` is valid it must:
+    - search using discv5 for peers related to this subnet and replace current peers with those ones if necessary
+    If validator is aggregator based on `slot_signature`, beacon node must:
     - add subnet to ENR
     - 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
@@ -34,7 +35,7 @@ post:
   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":

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 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 it's validators have
+      been assigned to. If any validators are aggregators, be sure to use the aggregator's
+      `slot_signature` to properly signal aggregation to the beacon node
+2. Wait for new BeaconBlock for the assigned slot (either stream updates or poll)
+    - Max wait: `SECONDS_PER_SLOT / 3 * 1000` into the assigned slot
+2. [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` 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..