From 9c194b905086b1ae17fbef5aa9c812f1dd303981 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Wed, 18 Nov 2020 14:01:04 +1000 Subject: [PATCH 1/4] Add dependent_root metadata to attestation and block duties. --- apis/eventstream/index.yaml | 2 +- apis/validator/duties/attester.yaml | 6 +++++- apis/validator/duties/proposer.yaml | 10 +++++++++- beacon-node-oapi.yaml | 2 ++ types/primitive.yaml | 5 +++++ 5 files changed, 22 insertions(+), 3 deletions(-) diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index cb89283d..9850b45f 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -38,7 +38,7 @@ get: description: The node has finished processing, resulting in a new head 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..90820b6e 100644 --- a/apis/validator/duties/attester.yaml +++ b/apis/validator/duties/attester.yaml @@ -9,7 +9,9 @@ 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 + previous_duty_dependent_root or current_duty_dependent_root in the head event matches the + dependent_root in this response." parameters: - name: epoch description: "Should only be allowed 1 epoch ahead" @@ -37,6 +39,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..50c44ba2 100644 --- a/apis/validator/duties/proposer.yaml +++ b/apis/validator/duties/proposer.yaml @@ -4,7 +4,13 @@ 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 (of > MIN_SEED_LOOKAHEAD epochs) could occur, + resulting in a change of duties. For full safety, you should monitor head events and confirm the + previous_duty_dependent_root or current_duty_dependent_root in the head event matches the + dependent_root in this response." parameters: - name: epoch in: path @@ -20,6 +26,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..fc2fc9a5 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. The data in this response is accurate only when the block with this root is on the canonical chain." + Root: type: string example: "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" From 719f3e06ce7c0f18d188b28d1a8c12934022538b Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Wed, 18 Nov 2020 14:09:56 +1000 Subject: [PATCH 2/4] Add definition of how to calculate the dependent roots. --- apis/eventstream/index.yaml | 2 +- apis/validator/duties/attester.yaml | 5 ++++- apis/validator/duties/proposer.yaml | 5 ++++- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index 9850b45f..d722ade5 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -35,7 +35,7 @@ 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 use the genesis block root in the case of underflow value: | event: head\n data: "{\"slot\": \"10\", \"block\": \"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"state\":\"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9\", \"epoch_transition\": false, \"previous_duty_dependent_root\": \"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\", \"current_duty_dependent_root\": \"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\"}"\n diff --git a/apis/validator/duties/attester.yaml b/apis/validator/duties/attester.yaml index 90820b6e..a8d419ce 100644 --- a/apis/validator/duties/attester.yaml +++ b/apis/validator/duties/attester.yaml @@ -11,7 +11,10 @@ post: however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, you should monitor head events and confirm the previous_duty_dependent_root or current_duty_dependent_root in the head event matches the - dependent_root in this response." + dependent_root in this response. + + 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" diff --git a/apis/validator/duties/proposer.yaml b/apis/validator/duties/proposer.yaml index 50c44ba2..395513f4 100644 --- a/apis/validator/duties/proposer.yaml +++ b/apis/validator/duties/proposer.yaml @@ -10,7 +10,10 @@ get: however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, you should monitor head events and confirm the previous_duty_dependent_root or current_duty_dependent_root in the head event matches the - dependent_root in this response." + dependent_root in this response. + + 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 From 002277dd22e709645f10852ff7338e800755cc38 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Wed, 18 Nov 2020 14:24:49 +1000 Subject: [PATCH 3/4] Fix descriptions. --- apis/eventstream/index.yaml | 2 +- apis/validator/duties/attester.yaml | 9 +++++++-- apis/validator/duties/proposer.yaml | 7 +++++-- types/primitive.yaml | 2 +- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index d722ade5..68b6cf86 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -35,7 +35,7 @@ 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. 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 use the genesis block root in the case of underflow + 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, \"previous_duty_dependent_root\": \"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\", \"current_duty_dependent_root\": \"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\"}"\n diff --git a/apis/validator/duties/attester.yaml b/apis/validator/duties/attester.yaml index a8d419ce..e3ffd806 100644 --- a/apis/validator/duties/attester.yaml +++ b/apis/validator/duties/attester.yaml @@ -10,8 +10,13 @@ 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 head events and confirm the - previous_duty_dependent_root or current_duty_dependent_root in the head event matches the - dependent_root in this response. + 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." diff --git a/apis/validator/duties/proposer.yaml b/apis/validator/duties/proposer.yaml index 395513f4..101e426f 100644 --- a/apis/validator/duties/proposer.yaml +++ b/apis/validator/duties/proposer.yaml @@ -9,8 +9,11 @@ get: 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 head events and confirm the - previous_duty_dependent_root or current_duty_dependent_root in the head event matches the - dependent_root in this response. + 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." diff --git a/types/primitive.yaml b/types/primitive.yaml index fc2fc9a5..a6fc7f9c 100644 --- a/types/primitive.yaml +++ b/types/primitive.yaml @@ -31,7 +31,7 @@ Uint64: DependentRoot: allOf: - $ref: "./primitive.yaml#/Root" - - description: "The block root that this response is dependent on. The data in this response is accurate only when the block with this root is on the canonical chain." + - description: "The block root that this response is dependent on." Root: type: string From dce52a011a4afd7ec01c176da14f9431ed32c235 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Wed, 18 Nov 2020 18:31:20 +1000 Subject: [PATCH 4/4] Fix explanation of reorgs. --- apis/validator/duties/proposer.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/apis/validator/duties/proposer.yaml b/apis/validator/duties/proposer.yaml index 101e426f..d958e621 100644 --- a/apis/validator/duties/proposer.yaml +++ b/apis/validator/duties/proposer.yaml @@ -7,9 +7,8 @@ get: 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 (of > MIN_SEED_LOOKAHEAD epochs) could occur, - resulting in a change of duties. For full safety, you should monitor head events and confirm the - dependent root in this response matches: + 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`