From b3c4defa238aaa74bf22aa602aa1b24b68a4c78e Mon Sep 17 00:00:00 2001 From: Jacek Sieka Date: Wed, 9 Nov 2022 02:10:06 +0100 Subject: [PATCH] Add `finalized` flag to chain data requests (#254) Whether or not a request pertains to the finalized section of the chain (per the view of the client fork choice) is somewhat cumbersome to discover. This PR adds a boolean that allows clients to distinguish a response that has been finalized and thus is unlikely to change from one that may still change over time (specially when using slot-based requests). A flag like this can also be used for the purpose of verifying that a checkpoint root indeed is part of chain history and is likely to remain as such, as discussed in https://github.com/ethereum/beacon-APIs/pull/226 * fix dots Co-authored-by: Paul Harris --- apis/beacon/blocks/attestations.yaml | 4 +++- apis/beacon/blocks/blinded_block.yaml | 2 ++ apis/beacon/blocks/block.v2.yaml | 4 +++- apis/beacon/blocks/header.yaml | 2 ++ apis/beacon/blocks/headers.yaml | 4 +++- apis/beacon/blocks/root.yaml | 2 ++ apis/beacon/states/committee.yaml | 2 ++ apis/beacon/states/finality_checkpoints.yaml | 2 ++ apis/beacon/states/fork.yaml | 2 ++ apis/beacon/states/randao.yaml | 2 ++ apis/beacon/states/root.yaml | 2 ++ apis/beacon/states/sync_committees.yaml | 2 ++ apis/beacon/states/validator.yaml | 2 ++ apis/beacon/states/validator_balances.yaml | 2 ++ apis/beacon/states/validators.yaml | 2 ++ apis/debug/state.v2.yaml | 2 ++ apis/validator/duties/attester.yaml | 2 +- beacon-node-oapi.yaml | 2 ++ types/primitive.yaml | 6 ++++++ 19 files changed, 44 insertions(+), 4 deletions(-) diff --git a/apis/beacon/blocks/attestations.yaml b/apis/beacon/blocks/attestations.yaml index b996a41c..cd7946a7 100644 --- a/apis/beacon/blocks/attestations.yaml +++ b/apis/beacon/blocks/attestations.yaml @@ -9,7 +9,7 @@ get: in: path required: true $ref: '../../../beacon-node-oapi.yaml#/components/parameters/BlockId' - + responses: "200": description: Success @@ -21,6 +21,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: array items: diff --git a/apis/beacon/blocks/blinded_block.yaml b/apis/beacon/blocks/blinded_block.yaml index 696f9910..3690557e 100644 --- a/apis/beacon/blocks/blinded_block.yaml +++ b/apis/beacon/blocks/blinded_block.yaml @@ -29,6 +29,8 @@ get: example: "phase0" execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: oneOf: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock" diff --git a/apis/beacon/blocks/block.v2.yaml b/apis/beacon/blocks/block.v2.yaml index 6149b8d8..e0a57b2b 100644 --- a/apis/beacon/blocks/block.v2.yaml +++ b/apis/beacon/blocks/block.v2.yaml @@ -29,6 +29,8 @@ get: example: "phase0" execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: oneOf: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock" @@ -37,7 +39,7 @@ get: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock" application/octet-stream: schema: - + description: "SSZ serialized block bytes. Use Accept header to choose this response type" "400": description: "The block ID supplied could not be parsed" diff --git a/apis/beacon/blocks/header.yaml b/apis/beacon/blocks/header.yaml index 2939c1c7..e62d6be0 100644 --- a/apis/beacon/blocks/header.yaml +++ b/apis/beacon/blocks/header.yaml @@ -20,6 +20,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: object properties: diff --git a/apis/beacon/blocks/headers.yaml b/apis/beacon/blocks/headers.yaml index 8d661235..d913189e 100644 --- a/apis/beacon/blocks/headers.yaml +++ b/apis/beacon/blocks/headers.yaml @@ -19,7 +19,7 @@ get: allOf: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Root" - example: "" - + responses: "200": description: Success @@ -31,6 +31,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: array items: diff --git a/apis/beacon/blocks/root.yaml b/apis/beacon/blocks/root.yaml index bb950d7d..e3a08d83 100644 --- a/apis/beacon/blocks/root.yaml +++ b/apis/beacon/blocks/root.yaml @@ -26,6 +26,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: object properties: diff --git a/apis/beacon/states/committee.yaml b/apis/beacon/states/committee.yaml index cce26146..fa246f4c 100644 --- a/apis/beacon/states/committee.yaml +++ b/apis/beacon/states/committee.yaml @@ -44,6 +44,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: array items: diff --git a/apis/beacon/states/finality_checkpoints.yaml b/apis/beacon/states/finality_checkpoints.yaml index 370adfa5..ce1ec831 100644 --- a/apis/beacon/states/finality_checkpoints.yaml +++ b/apis/beacon/states/finality_checkpoints.yaml @@ -21,6 +21,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: object properties: diff --git a/apis/beacon/states/fork.yaml b/apis/beacon/states/fork.yaml index aca7b8ee..693bef0a 100644 --- a/apis/beacon/states/fork.yaml +++ b/apis/beacon/states/fork.yaml @@ -20,6 +20,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Fork' diff --git a/apis/beacon/states/randao.yaml b/apis/beacon/states/randao.yaml index b32b1352..5533565f 100644 --- a/apis/beacon/states/randao.yaml +++ b/apis/beacon/states/randao.yaml @@ -35,6 +35,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: object properties: diff --git a/apis/beacon/states/root.yaml b/apis/beacon/states/root.yaml index 017a52bf..0d176a98 100644 --- a/apis/beacon/states/root.yaml +++ b/apis/beacon/states/root.yaml @@ -19,6 +19,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: object properties: diff --git a/apis/beacon/states/sync_committees.yaml b/apis/beacon/states/sync_committees.yaml index 31f113aa..2dc739e8 100644 --- a/apis/beacon/states/sync_committees.yaml +++ b/apis/beacon/states/sync_committees.yaml @@ -28,6 +28,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.SyncCommittee' diff --git a/apis/beacon/states/validator.yaml b/apis/beacon/states/validator.yaml index 149570fd..e919c600 100644 --- a/apis/beacon/states/validator.yaml +++ b/apis/beacon/states/validator.yaml @@ -27,6 +27,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorResponse' "400": diff --git a/apis/beacon/states/validator_balances.yaml b/apis/beacon/states/validator_balances.yaml index ea1bb816..c68b208c 100644 --- a/apis/beacon/states/validator_balances.yaml +++ b/apis/beacon/states/validator_balances.yaml @@ -37,6 +37,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: array items: diff --git a/apis/beacon/states/validators.yaml b/apis/beacon/states/validators.yaml index 117c9714..de7ba26b 100644 --- a/apis/beacon/states/validators.yaml +++ b/apis/beacon/states/validators.yaml @@ -48,6 +48,8 @@ get: properties: execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: type: array items: diff --git a/apis/debug/state.v2.yaml b/apis/debug/state.v2.yaml index b0d9a139..417af137 100644 --- a/apis/debug/state.v2.yaml +++ b/apis/debug/state.v2.yaml @@ -29,6 +29,8 @@ get: example: "phase0" execution_optimistic: $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: oneOf: - $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconState' diff --git a/apis/validator/duties/attester.yaml b/apis/validator/duties/attester.yaml index 06b31be2..b02225b1 100644 --- a/apis/validator/duties/attester.yaml +++ b/apis/validator/duties/attester.yaml @@ -18,7 +18,7 @@ post: - 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: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 12e63eb1..dcf6b094 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -243,6 +243,8 @@ components: $ref: './types/primitive.yaml#/DependentRoot' ExecutionOptimistic: $ref: './types/primitive.yaml#/ExecutionOptimistic' + Finalized: + $ref: './types/primitive.yaml#/Finalized' Root: $ref: './types/primitive.yaml#/Root' Hex: diff --git a/types/primitive.yaml b/types/primitive.yaml index 474a3799..284a6cf9 100644 --- a/types/primitive.yaml +++ b/types/primitive.yaml @@ -45,6 +45,12 @@ ExecutionOptimistic: - example: false - description: "True if the response references an unverified execution payload. Optimistic information may be invalidated at a later time. If the field is not present, assume the False value." +Finalized: + allOf: + - type: boolean + - example: false + - description: "True if the response references the finalized history of the chain, as determined by fork choice. If the field is not present, additional calls are necessary to compare the epoch of the requested information with the finalized checkpoint." + Root: type: string format: hex