From a911eaeba77143b4828fde32e55f014849a4b127 Mon Sep 17 00:00:00 2001 From: Jacek Sieka Date: Fri, 28 Oct 2022 09:23:35 +0200 Subject: [PATCH 1/2] Add `finalized` flag to chain data requests 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 --- 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 c6a4a77c..f4630fec 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 57d826d2..62e01187 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" @@ -36,7 +38,7 @@ get: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.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 479a746e..1de1bfb8 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 2c5fe225..e3e66fe6 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -237,6 +237,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 From 380270e08652f5ff516a30e59a226a79c47a9e8a Mon Sep 17 00:00:00 2001 From: Jacek Sieka Date: Fri, 28 Oct 2022 09:25:59 +0200 Subject: [PATCH 2/2] fix dots --- apis/debug/state.v2.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/debug/state.v2.yaml b/apis/debug/state.v2.yaml index 1de1bfb8..4945c764 100644 --- a/apis/debug/state.v2.yaml +++ b/apis/debug/state.v2.yaml @@ -30,7 +30,7 @@ get: execution_optimistic: $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" finalized: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: oneOf: - $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconState'