Add lightclient routes #181
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| get: | ||
| operationId: getCommitteeUpdates | ||
| summary: Get committee updates in an inclusive range of sync periods | ||
| description: | | ||
| Returns an array of best updates in the requested periods within the inclusive range `from` - `to`. | ||
| Best is defined by (in order of priority): | ||
| - Is finalized update + > 2/3 participations | ||
| - Highest participation (bit count) | ||
| - Oldest update | ||
| Tracks oldest instead of newest to reduce disk writes and the likelyhood of re-orgs. Clients may choose | ||
dapplion marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| a different set of "best" criteria if necessary. | ||
| tags: | ||
| - Lightclient | ||
| parameters: | ||
| - name: from | ||
| in: query | ||
| required: true | ||
| description: "Sync period start of requested range" | ||
| schema: | ||
| $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' | ||
| - name: to | ||
| in: query | ||
| required: true | ||
| description: "Sync period end of requested range (inclusive)" | ||
| schema: | ||
| $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' | ||
| responses: | ||
| "200": | ||
| description: Success | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetCommitteeUpdatesResponse | ||
| type: object | ||
| properties: | ||
| data: | ||
| type: array | ||
| items: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/LightClientUpdate" | ||
| "500": | ||
| $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| get: | ||
| operationId: getHeadUpdate | ||
| summary: Get latest best head update | ||
| description: | | ||
| Returns the latest best head update available. Clients should use the SSE type `lightclient_head_update` | ||
dapplion marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| unless to get the very first head update after syncing, or if SSE are not supported by the server. | ||
|
There was a problem hiding this comment. Events are part of the spec so the latter part is not a relevant comment. There was a problem hiding this comment.
Do you refer to the part where SSE may not be supported by the server? At least Lodestar allows to disable the events namespace individually. Also some reverse proxies may not support SSE depending on their buffering configuration. |
||
| tags: | ||
| - Lightclient | ||
| responses: | ||
| "200": | ||
| description: Success | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetHeadUpdateResponse | ||
| type: object | ||
| properties: | ||
| data: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/LightclientHeadUpdate" | ||
| "500": | ||
| $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| get: | ||
| operationId: getProof | ||
| summary: Get multiproof of `paths` for `state_id` | ||
| description: | | ||
| Returns a multiproof of `paths` at the requested `stateId`. | ||
| The requested `stateId` may not be available. Regular nodes only keep recent states in memory. | ||
| tags: | ||
| - Lightclient | ||
| parameters: | ||
| - name: state_id | ||
| in: path | ||
| required: true | ||
| $ref: '../../beacon-node-oapi.yaml#/components/parameters/StateId' | ||
| - name: paths | ||
| in: query | ||
| required: true | ||
| description: Array of JSON serialized array of paths | ||
| schema: | ||
| type: array | ||
| items: | ||
| type: string | ||
| description: | | ||
| example: "'[\"balances\", 0]'" | ||
|
|
||
| responses: | ||
| "200": | ||
| description: Success | ||
| content: | ||
| application/octet-stream: | ||
|
There was a problem hiding this comment. There should be a JSON response here as well. This will also give a location to explain the structure of the multiproof. There was a problem hiding this comment. The JSON representation of this format is widely inefficient. Since JSON is the default I'll argue into only offering |
||
| schema: | ||
| description: "Serialized TreeOffset multiproof" | ||
| "400": | ||
| description: "Invalid state ID" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| - example: | ||
| code: 400 | ||
| message: "Invalid state ID: current" | ||
| "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' | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| get: | ||
| operationId: getSnapshot | ||
| summary: Fetch a snapshot with a proof to a trusted block root. | ||
| description: | | ||
| Fetch a snapshot with a proof to a trusted block root. | ||
| The trusted block root should be fetched with similar means to a weak subjectivity checkpoint. | ||
| Only block roots for checkpoints within the weak subjectivity period must be guaranteed to be available. | ||
| If the node started with a recent weak subjectivity checkpoint, the node may not backfill snapshots | ||
| for older checkpoints. | ||
| tags: | ||
| - Lightclient | ||
| parameters: | ||
| - name: block_root | ||
| in: path | ||
| required: true | ||
| $ref: '../../beacon-node-oapi.yaml#/components/parameters/StateId' | ||
dapplion marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| responses: | ||
| "200": | ||
| description: Success | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetSnapshotResponse | ||
| type: object | ||
| properties: | ||
| data: | ||
| $ref: '../../beacon-node-oapi.yaml#/components/schemas/LightclientSnapshot' | ||
| "400": | ||
| description: "Invalid block root" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| - example: | ||
| code: 400 | ||
| message: "Invalid block root: head" | ||
| "404": | ||
| description: "Snapshot not found" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| - example: | ||
| code: 404 | ||
| message: "Snapshot not found for block root" | ||
| "500": | ||
| $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| Altair: | ||
| LightClientUpdate: | ||
| type: object | ||
| properties: | ||
| header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| nextSyncCommittee: | ||
| $ref: './sync_committee.yaml#/SyncCommittee' | ||
| nextSyncCommitteeBranch: | ||
| $ref: '#/Altair/SyncCommitteeBranch' | ||
| finalityHeader: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| finalityBranch: | ||
| $ref: '#/Altair/FinalityBranch' | ||
| syncCommitteeBits: | ||
| $ref: './sync_aggregate.yaml#/Altair/SyncCommitteeBits' | ||
| syncCommitteeSignature: | ||
| allOf: | ||
| - $ref: '../primitive.yaml#/Signature' | ||
| - description: 'Signature by the validator(s) over the block root of `slot`' | ||
| forkVersion: | ||
| $ref: '../primitive.yaml#/ForkVersion' | ||
|
|
||
| FinalityBranch: | ||
| type: array | ||
| description: "Branch to state.finalized_checkpoint.root" | ||
| items: | ||
| allOf: | ||
| - $ref: '../primitive.yaml#/Root' | ||
| minItems: 6 | ||
| maxItems: 6 | ||
|
|
||
| SyncCommitteeBranch: | ||
| type: array | ||
| description: "Branch to state.next_sync_committee or state.current_sync_committee" | ||
| items: | ||
| allOf: | ||
| - $ref: '../primitive.yaml#/Root' | ||
| minItems: 5 | ||
| maxItems: 5 | ||
|
|
||
| LightclientHeadUpdate: | ||
| type: object | ||
| properties: | ||
| header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| syncAggregate: | ||
| $ref: './sync_aggregate.yaml#/SyncAggregate' | ||
|
|
||
| LightclientSnapshot: | ||
| type: object | ||
| properties: | ||
| header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| currentSyncCommittee: | ||
| $ref: './sync_committee.yaml#/SyncCommittee' | ||
| currentSyncCommitteeBranch: | ||
| $ref: '#/Altair/SyncCommitteeBranch' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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 need for
_updatehere; the event is, by definition, an update.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point, tho I'm unsure if
lightclient_headcan also be confusing since you can get multiple events for the same head which is not the same behavior as theheadevent.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it was called
lightlcient_head_updatebecause the data structure emitted is called aLightClientHeadUpdatesomewhere.Similar to the
LightClientUpdatein the specs.Not saying its a great name, just saying..