Skip to content
Merged
1 change: 1 addition & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ There are likely to be descriptions etc outside of the list below, but new query
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/execution_payload_envelope/{block_id}` added | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/pool/payload_attestations` added | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added | | | | | |
| `POST /eth/v1/beacon/states/{state_id}/builders` added | | | | | |
Comment thread
rolfyone marked this conversation as resolved.
Resolved
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v2/beacon/blocks/{block_id}` updated | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v2/beacon/blocks` updated | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `execution_payload_available EVENT` added | | | | | |
Expand Down
81 changes: 81 additions & 0 deletions apis/beacon/states/builders.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
post:
operationId: "postStateBuilders"
Comment thread
rolfyone marked this conversation as resolved.
Resolved
summary: "Get builders from state"
description: |
Returns filterable list of builders with their status and index.

Information 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 information will be returned but this will not cause an error. There are no guarantees for the
returned data in terms of ordering; both the index and public key are returned for each builder, and can be used to confirm
for which inputs a response has been returned.

Returns 400 if the requested state is prior to Gloas.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
Comment thread
nflaig marked this conversation as resolved.
Resolved
tags:
- Beacon
parameters:
- name: state_id
in: path
$ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
requestBody:
description: "The list of builder IDs to filter on. Values are either hex encoded public keys (any bytes48 with 0x prefix) or builder indices. If no body is supplied then all builders will be returned."
required: false
content:
application/json:
schema:
type: object
required: []
properties:
ids:
type: array
uniqueItems: true
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 value is `[]`) or the property is omitted then all builders will be returned.
items:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
title: PostStateBuildersResponse
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/BuilderResponse'
application/octet-stream:
schema:
description: "SSZ serialized results. Use Accept header to choose this response type"
"400":
description: "Invalid state ID, builder 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'
8 changes: 8 additions & 0 deletions beacon-node-oapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ paths:
$ref: "./apis/beacon/states/validator_balances.yaml"
/eth/v1/beacon/states/{state_id}/validator_identities:
$ref: "./apis/beacon/states/validator_identities.yaml"
/eth/v1/beacon/states/{state_id}/builders:
$ref: "./apis/beacon/states/builders.yaml"
/eth/v1/beacon/states/{state_id}/committees:
$ref: "./apis/beacon/states/committee.yaml"
/eth/v1/beacon/states/{state_id}/sync_committees:
Expand Down Expand Up @@ -235,8 +237,12 @@ components:
$ref: './types/api.yaml#/ValidatorBalanceResponse'
ValidatorIdentityResponse:
$ref: './types/api.yaml#/ValidatorIdentityResponse'
BuilderResponse:
$ref: './types/api.yaml#/BuilderResponse'
ValidatorStatus:
$ref: './types/api.yaml#/ValidatorStatus'
BuilderStatus:
$ref: './types/api.yaml#/BuilderStatus'
Committee:
$ref: './types/api.yaml#/Committee'
AttesterDuty:
Expand Down Expand Up @@ -445,6 +451,8 @@ components:
$ref: "./types/gloas/block.yaml#/Gloas/BeaconBlock"
Gloas.SignedBeaconBlock:
$ref: "./types/gloas/block.yaml#/Gloas/SignedBeaconBlock"
Gloas.Builder:
$ref: "./types/gloas/builder.yaml#/Gloas/Builder"
Gloas.ExecutionPayloadBid:
$ref: "./types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid"
Gloas.SignedExecutionPayloadBid:
Expand Down
22 changes: 22 additions & 0 deletions types/api.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,18 @@ ValidatorIdentityResponse:
$ref: "./primitive.yaml#/Uint64"
description: "Epoch when validator activated. 'FAR_FUTURE_EPOCH' if not activated"

BuilderResponse:
type: object
required: [index, status, builder]
properties:
index:
$ref: './primitive.yaml#/Uint64'
description: "Index of builder in builder registry."
status:
$ref: "#/BuilderStatus"
builder:
$ref: "./gloas/builder.yaml#/Gloas/Builder"

ValidatorStatus:
description: |
Possible statuses:
Expand All @@ -57,6 +69,16 @@ ValidatorStatus:
enum: ["pending_initialized", "pending_queued", "active_ongoing", "active_exiting", "active_slashed", "exited_unslashed", "exited_slashed", "withdrawal_possible", "withdrawal_done"]
example: "active_ongoing"

BuilderStatus:
description: |
Possible statuses:
- **0** - pending
- **1** - active
- **2** - withdrawn
Comment thread
rolfyone marked this conversation as resolved.
Resolved
type: integer
enum: [0, 1, 2]

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.

echoing what @etan-status mentioned here #601 (comment), we might wanna follow the validators api for now and figure out a proper enum solution later, it's definitely not ideal that this api won't support ssz initially but especially for builders it should not be as problematic as there won't be that many compared to validators

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

It's fairly academic.
The thing i don't like about strings also is they also bloat the json output, but it does make it easier because you don't need to decode it i guess.
Also given how hard it is to change ssz this may be many hard forks.

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.

may be many hard forks.

enum ssz type doesn't require a hard fork, it will be optional so once we have a well-defined enum ssz type with a spec we can start implementing this already and clients that do have it can support ssz on the validators and builders api since adding it later is backward compatible

example: 1
Comment thread
nflaig marked this conversation as resolved.
Resolved


Committee:
description: Group of validators assigned to attest at specific slot and that have the same committee index (shard in phase 1)
Expand Down
23 changes: 23 additions & 0 deletions types/gloas/builder.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
Gloas:
Builder:
type: object
description: "The [`Builder`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.8/specs/gloas/beacon-chain.md#builder) object from the CL Gloas spec."
Comment thread
rolfyone marked this conversation as resolved.
Resolved
required: [pubkey, version, execution_address, balance, deposit_epoch, withdrawable_epoch]
properties:
pubkey:
$ref: "../primitive.yaml#/Pubkey"
version:
$ref: "../primitive.yaml#/Uint8"
description: "Builder version."
execution_address:
$ref: "../primitive.yaml#/ExecutionAddress"
description: "Execution-layer address that receives builder withdrawals."
balance:
$ref: "../primitive.yaml#/Gwei"
description: "Current builder balance in gwei."
deposit_epoch:
$ref: "../primitive.yaml#/Uint64"
description: "Epoch when the builder deposit was processed."
withdrawable_epoch:
$ref: "../primitive.yaml#/Uint64"
description: "Epoch when the builder can withdraw. 'FAR_FUTURE_EPOCH' if not exiting."
Loading