diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index cb89283d..68b6cf86 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -35,10 +35,10 @@ get: description: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format examples: head: - description: The node has finished processing, resulting in a new head + description: The node has finished processing, resulting in a new head. previous_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` and current_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`. Both dependent roots use the genesis block root in the case of underflow. value: | event: head\n - data: "{\"slot\": \"10\", \"block\": \"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"state\":\"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9\", \"epoch_transition\": false}"\n + data: "{\"slot\": \"10\", \"block\": \"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"state\":\"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9\", \"epoch_transition\": false, \"previous_duty_dependent_root\": \"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\", \"current_duty_dependent_root\": \"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\"}"\n \n block: description: The node has received a valid block (from P2P or API) diff --git a/apis/validator/duties/attester.yaml b/apis/validator/duties/attester.yaml index 379bac79..e3ffd806 100644 --- a/apis/validator/duties/attester.yaml +++ b/apis/validator/duties/attester.yaml @@ -9,7 +9,17 @@ post: Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, - resulting in a change of duties. For full safety, you should monitor chain reorganizations events." + resulting in a change of duties. For full safety, you should monitor head events and confirm the + dependent root in this response matches: + + - event.previous_duty_dependent_root when `compute_epoch_at_slot(event.slot) == epoch` + + - event.current_duty_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch` + + - event.block otherwise + + The dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` + or the genesis block root in the case of underflow." parameters: - name: epoch description: "Should only be allowed 1 epoch ahead" @@ -37,6 +47,8 @@ post: title: GetAttesterDutiesResponse type: object properties: + dependent_root: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/DependentRoot" data: type: array items: diff --git a/apis/validator/duties/proposer.yaml b/apis/validator/duties/proposer.yaml index 4f56bf96..d958e621 100644 --- a/apis/validator/duties/proposer.yaml +++ b/apis/validator/duties/proposer.yaml @@ -4,7 +4,18 @@ get: - Validator summary: "Get block proposers duties" operationId: "getProposerDuties" - description: "Request beacon node to provide all validators that are scheduled to propose a block in the given epoch" + description: "Request beacon node to provide all validators that are scheduled to propose a block in the given epoch. + + Duties should only need to be checked once per epoch, + however a chain reorganization could occur that results in a change of duties. For full safety, + you should monitor head events and confirm the dependent root in this response matches: + + - event.current_duty_dependent_root when `compute_epoch_at_slot(event.slot) == epoch` + + - event.block otherwise + + The dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)` + or the genesis block root in the case of underflow." parameters: - name: epoch in: path @@ -20,6 +31,8 @@ get: title: GetProposerDutiesResponse type: object properties: + dependent_root: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/DependentRoot" data: type: array items: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index b30bb037..b418be82 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -178,6 +178,8 @@ components: $ref: './types/primitive.yaml#/Version' ForkVersion: $ref: './types/primitive.yaml#/ForkVersion' + DependentRoot: + $ref: './types/primitive.yaml#/DependentRoot' Root: $ref: './types/primitive.yaml#/Root' Hex: diff --git a/types/primitive.yaml b/types/primitive.yaml index e1386c45..a6fc7f9c 100644 --- a/types/primitive.yaml +++ b/types/primitive.yaml @@ -28,6 +28,11 @@ Uint64: type: string example: "1" +DependentRoot: + allOf: + - $ref: "./primitive.yaml#/Root" + - description: "The block root that this response is dependent on." + Root: type: string example: "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"