epbs documentation updates

Author: shane-moore

apis/validator/attestation_data.yaml

@@ -6,7 +6,7 @@ get:
   summary: "Produce an attestation data"
   description: |
     Requests that the beacon node produce an AttestationData. For `slot`s in
-    Electra and later, this AttestationData must have a `committee_index` of 0.
+    Electra and Fulu, this AttestationData must have a `committee_index` of 0. In Gloas, this `committee_index` field is repurposed to signal payload status: 0 if the execution payload is not present in the canonical chain (EMPTY), or 1 if the payload is present (FULL). For current slot attestations, always use 0.
 
     A 503 error must be returned if the block identified by the response
     `beacon_block_root` is optimistic (i.e. the attestation attests to a block
@@ -22,7 +22,7 @@ get:
       in: query
       description: |
         The committee index for which an attestation data should be created. For `slot`s in
-        Electra and later, this parameter MAY always be set to 0.
+        Electra and Fulu, this parameter MAY always be set to 0. In Gloas, it signals payload status: 0 for EMPTY payload status, 1 for FULL payload status.
       required: true
       schema:
         $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64"

validator-flow.md

@@ -36,15 +36,52 @@ Attesting:
       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
+    - Max wait: `SECONDS_PER_SLOT / 4` 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. If aggregator:
-    - Wait for `SECONDS_PER_SLOT * 2 / 3` seconds into the assigned slot
+    - Wait for `SECONDS_PER_SLOT / 2` seconds into the assigned slot
     - [Fetch aggregated Attestation](#/ValidatorRequiredApi/getAggregatedAttestation) from Beacon Node you've subscribed to your subnet
     - [Publish SignedAggregateAndProofs](#/ValidatorRequiredApi/publishAggregateAndProofs)
 
 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..
+
+### PTC Attesting
+
+On start of every epoch, validator should [fetch PTC duties](#/Validator/getPtcDuties) for epoch + 1.
+Result are array of objects with validator index and assigned slot for payload timeliness committee participation.
+
+PTC Attesting:
+1. Wait for new BeaconBlock for the assigned slot
+    - Max wait: `SECONDS_PER_SLOT / 4` seconds into the assigned slot
+2. [Fetch PayloadAttestationData](#/ValidatorRequiredApi/producePayloadAttestationData) for the assigned slot
+3. Sign PayloadAttestationData to create PayloadAttestationMessage
+4. [Submit PayloadAttestationMessage](#/ValidatorRequiredApi/submitPayloadAttestationMessage)
+    - Must be submitted by `3/4` of slot duration (`PAYLOAD_ATTESTATION_DUE_BPS` = 75% of slot)
+    - Attestation indicates whether execution payload envelope has been seen for the block and if blobs were received
+
+Monitor chain block reorganization events (TBD) as they could change PTC assignments.
+If reorg is detected, ask for new PTC duties and proceed from 1..
+
+### Builder (Optional)
+
+Validators may optionally act as builders to submit execution payload bids for block inclusion.
+This requires registering with builder-specific withdrawal credentials (`BUILDER_WITHDRAWAL_PREFIX`).
+
+Building:
+1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node
+    - Beacon node obtains payload via `engine_getPayload` call to execution client
+2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#executionpayloadenvelope)
+2. Sign ExecutionPayloadBid to create SignedExecutionPayloadBid
+3. [Submit SignedExecutionPayloadBid](#/Beacon/publishExecutionPayloadBid) to network for proposer consideration
+4. If bid is selected by proposer in their block:
+    - [Fetch ExecutionPayloadEnvelope](#/Validator/getExecutionPayloadEnvelope) from beacon node
+    - Sign envelope and [submit SignedExecutionPayloadEnvelope](#/Beacon/publishExecutionPayloadEnvelope)
+    - Must submit early enough for PTC attestation by `3/4` of slot duration
+
+Monitor for block proposals containing your bid to trigger envelope release.
+
+