Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 6 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,12 @@ There are likely to be descriptions etc outside of the list below, but new query
| [#588](https://github.com/ethereum/beacon-APIs/pull/588) `execution_payload EVENT` added | | | | | |
| [#588](https://github.com/ethereum/beacon-APIs/pull/588) `execution_payload_gossip EVENT` added | | | | | |
| [#598](https://github.com/ethereum/beacon-APIs/pull/598) `fast_confirmation EVENT` added | | | | | |
| `GET /eth/v1/beacon/states/{state_id}/builders` added | | | | | |
| `POST /eth/v1/beacon/states/{state_id}/builders` added | | | | | |
| `GET /eth/v1/beacon/states/{state_id}/builders/{builder_id}` added | | | | | |
| `GET /eth/v1/beacon/states/{state_id}/builder_balances` added | | | | | |
| `POST /eth/v1/beacon/states/{state_id}/builder_balances` added | | | | | |
| `POST /eth/v1/beacon/states/{state_id}/builder_identities` added | | | | | |

The Following are no longer in the Standard API, removed since the latest version.

Expand Down
60 changes: 60 additions & 0 deletions apis/beacon/states/builder.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
get:
operationId: "getStateBuilder"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

why do we need this? I feel like this was already a mistake in the validators api, can't we just have getStateBuilders?

summary: "Get builder from state by id"
description: "Returns builder specified by state and id or public key along with status and balance."

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

nit

Suggested change
description: "Returns builder specified by state and id or public key along with status and balance."
description: "Returns builder specified by state and builder id."

tags:
- Beacon
parameters:
- name: state_id
in: path
$ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
- name: builder_id
description: "Either hex encoded public key (any bytes48 with 0x prefix) or builder index"
in: path
required: true
schema:
type: string

responses:
"200":
description: Success
content:
application/json:
schema:
title: GetStateBuilderResponse
type: object
required: [execution_optimistic, finalized, data]
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/BuilderResponse'
"400":
description: "Invalid state or builder ID"
content:
application/json:
schema:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
example:
code: 400
message: "Invalid state ID: current"
"404":
description: "Not Found"
content:
application/json:
schema:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
examples:
StateNotFound:
value:
code: 404
message: State not found
BuilderNotFound:
value:
code: 404
message: Builder not found

"500":
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
143 changes: 143 additions & 0 deletions apis/beacon/states/builder_balances.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
get:
operationId: "getStateBuilderBalances"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

why do we need a separate api for balances? seems overkill

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

im not against being easily able to get balances but we can probably just retain the 'post', and remove the get...

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

but why does it need to be a separate endpoint? we can just get that by accessing builder.balance

this is in contrast to validators, as balances are separatly stored in the state via state.balances which is different from validator.effective_balance (actual balance vs. effective balance)

summary: "Get builder balances from state"
description: |
Returns filterable list of builder balances.

Balances will be returned for all indices or public keys that match known builders. If an index or public key does not
match any known builder, no balance will be returned but this will not cause an error. There are no guarantees for the
returned data in terms of ordering; the index is returned for each balance, and can be used to confirm for which inputs a
response has been returned.
tags:
- Beacon
parameters:
- name: state_id
in: path
$ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
- name: id

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

getStateBuilder calls it builder_id maybe we should call it that

description: "Either hex encoded public key (any bytes48 with 0x prefix) or builder index"
in: query
required: false
schema:
type: array
maxItems: 64
uniqueItems: true
items:
description: "Either hex encoded public key (any bytes48 with 0x prefix) or builder index"
type: string

responses:
"200":
description: Success
content:
application/json:
schema:
title: GetStateBuilderBalancesResponse
type: object
required: [execution_optimistic, finalized, data]
properties:
execution_optimistic:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
finalized:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
data:
type: array
items:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/BuilderBalanceResponse'
"400":
description: "Invalid state or builder ID"
content:
application/json:
schema:
$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:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
example:
code: 404
message: "State not found"
"414":
description: "Too many builder IDs"
content:
application/json:
schema:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
example:
code: 414
message: "Too many builder IDs in request"
"500":
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
post:
operationId: "postStateBuilderBalances"
summary: "Get builder balances from state"
description: |
Returns filterable list of builder balances.

Balances will be returned for all indices or public keys that match known builders. If an index or public key does not
match any known builder, no balance will be returned but this will not cause an error. There are no guarantees for the
returned data in terms of ordering; the index is returned for each balance, and can be used to confirm for which inputs a
response has been returned.
tags:
- Beacon
parameters:
- name: state_id
in: path
$ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
requestBody:
description: |
An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a builder index.

If the supplied list is empty (i.e. the body is `[]`) or no body is supplied then balances will be returned for all builders.
required: false
content:
application/json:
schema:
type: array
uniqueItems: true
items:
description: "Either hex encoded public key (any bytes48 with 0x prefix) or builder index"
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
title: GetStateBuilderBalancesResponse
type: object
required: [execution_optimistic, finalized, data]
properties:
execution_optimistic:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
finalized:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
data:
type: array
items:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/BuilderBalanceResponse'
"400":
description: "Invalid state ID or malformed request"
content:
application/json:
schema:
$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:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
example:
code: 404
message: "State not found"
"500":
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
74 changes: 74 additions & 0 deletions apis/beacon/states/builder_identities.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
post:
operationId: "postStateBuilderIdentities"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I feel like this shouldn't be required, what's the most amount of builders a consumer needs to query? returning the full Builder spec object seems fine to me

summary: "Get builder identities from state"
description: |
Returns filterable list of builder identities.

Identities will be returned for all indices or public keys that match known builders. If an index or public key does not
match any known builder, no identity will be returned but this will not cause an error. There are no guarantees for the
returned data in terms of ordering.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
tags:
- Beacon
parameters:
- name: state_id
in: path
$ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
requestBody:
description: |
An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a builder index.

If the supplied list is empty (i.e. the body is `[]`) or no body is supplied then all builders will be returned.
required: false
content:
application/json:
schema:
type: array
uniqueItems: true
items:
description: "Either hex encoded public key (any bytes48 with 0x prefix) or builder index"
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
title: PostStateBuilderIdentitiesResponse
type: object
required: [execution_optimistic, finalized, data]
properties:
execution_optimistic:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
finalized:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
data:
type: array
items:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/BuilderIdentityResponse'
application/octet-stream:
schema:
description: "SSZ serialized results. Use Accept header to choose this response type"
"400":
description: "Invalid state ID or malformed request"
content:
application/json:
schema:
$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:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
example:
code: 404
message: "State not found"
"406":
$ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
"500":
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
Loading
Loading