Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Checkpoint Sync API #226

Closed
wants to merge 8 commits into from
Closed

Checkpoint Sync API #226

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2077214
Add /eth/v1/beacon/finalized_blocks/{slot}/root
mkalinin Jul 29, 2022
654fcca
Define Checkpoint namespace
mkalinin Aug 3, 2022
7b13ea7
Be more specific on the finalized state to return
mkalinin Aug 3, 2022
a987a9d
Update apis/checkpoint/finalized_blocks/root.yaml
mkalinin Sep 7, 2022
499c8c5
Address Adrian's feedback fromt the review
mkalinin Sep 7, 2022
ea05ebc
Merge branch 'master' into finalized-block-root
rolfyone Oct 28, 2022
051b25c
Merge branch 'master' into finalized-block-root
rolfyone Nov 1, 2022
451f286
Merge branch 'master' into finalized-block-root
rolfyone Nov 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions apis/checkpoint/finalized_blocks/root.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
get:
operationId: getFinalizedBlockRoot
summary: Get finalized block root
description: Retrieves hashTreeRoot of finalized BeaconBlock/BeaconBlockHeader. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What should be returned if the specified slot is an empty slot? Should it return the last block before that slot or 404?

I don't think it overly matters because you can't calculate the correct block root from a state if it's had empty slots applied, so if you have a usable state it will be from a slot that contains a block. It's probably worth returning 404 for empty slots though just to be consistent with the /eth/v1/beacon/blocks/{blockId}/root API.

Responds with 'Block not found' if block at a slot is either unavailable or not yet finalized.
mkalinin marked this conversation as resolved.
Show resolved Hide resolved
tags:
- Checkpoint
parameters:
- name: slot
in: path
required: true
example: "1"
schema:
type: string
description: |
Slot number.

responses:
"200":
description: Success
content:
application/json:
schema:
type: object
title: GetBlockRootResponse
properties:
execution_optimistic:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
data:
type: object
properties:
root:
allOf:
- description: HashTreeRoot of BeaconBlock/BeaconBlockHeader object
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Root'
"400":
description: "The slot number supplied could not be parsed"
content:
application/json:
schema:
allOf:
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
- example:
code: 400
message: "Invalid slot number: current"
"404":
description: "Block not found"
content:
application/json:
schema:
allOf:
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
- example:
code: 404
message: "Block not found"
"500":
$ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError"
44 changes: 44 additions & 0 deletions apis/checkpoint/finalized_state.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
get:
operationId: "getFinalizedCheckpointState"
summary: "Get full BeaconState object for finalized checkpoint state"
description: |
Returns full BeaconState object for a finalized checkpoint state from the WS period.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is probably worth explicitly stating that the state should not have empty slots applied. That is it should be the state that is referenced by the block some finalized checkpoint root actually points to.

Depending on `Accept` header it can be returned either as json or as bytes serialized by SSZ
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see a reason for this API to support returning JSON. It makes the request significantly more expensive to serve and use more bandwidth, and any client needs to be able to support an SSZ BeaconState. The debug endpoint is available for humans or other tools that want a more readable version of the spec.

tags:
- Checkpoint
responses:
"200":
description: Success
headers:
Eth-Consensus-Version:
$ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version'
content:
application/json:
schema:
title: GetStateResponse
type: object
properties:
version:
type: string
enum: [ phase0, altair, bellatrix ]
example: "phase0"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't include the is_optimistic flag the existing getState has. Do we want to add that or should this endpoint simply refuse to return a state if it's optimistically syncing? We probably should be clear about that whichever way we go.

Also worth noting that the state being finalized would be affected by the chain head being optimistic even if the state returned itself is fully validated (because the optimistic head may have updated finalisation).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, we should be conservative on that and respond 404 if the node is optimistic. I'll add a respective note

data:
oneOf:
- $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconState'
- $ref: "../../beacon-node-oapi.yaml#/components/schemas/Altair.BeaconState"
- $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BeaconState"
application/octet-stream:
schema:
description: "SSZ serialized state bytes. Use Accept header to choose this response type"
"404":
description: "State not found"
content:
application/json:
schema:
allOf:
- $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
- example:
code: 404
message: "State not found"
"500":
$ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'
7 changes: 7 additions & 0 deletions beacon-node-oapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ servers:
tags:
- name: Beacon
description: Set of endpoints to query beacon chain.
- name: Checkpoint
description: Set of endpoints to query checkpoint sync data.
- name: Config
description: Endpoints to query chain configuration, specification, and fork schedules.
- name: Debug
Expand Down Expand Up @@ -159,6 +161,11 @@ paths:
/eth/v1/events:
$ref: "./apis/eventstream/index.yaml"

/eth/v1/checkpoint/finalized_blocks/{slot}/root:
$ref: "./apis/checkpoint/finalized_blocks/root.yaml"
/eth/v1/checkpoint/finalized_state:
$ref: "./apis/checkpoint/finalized_state.yaml"


components:
schemas:
Expand Down