Skip to content

Commit de4b023

Browse files
michaelsproulmichaelsproul
authored
Add broadcast_validation to block publishing (#317)
* New v2 APIs and explicit equivocation check
1 parent 435c140 commit de4b023

File tree

4 files changed

+170
-0
lines changed

4 files changed

+170
-0
lines changed

‎apis/beacon/blocks/blinded_blocks.v2.yaml

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
post:
2+
tags:
3+
- Beacon
4+
- ValidatorRequiredApi
5+
summary: "Publish a signed block."
6+
operationId: "publishBlindedBlockV2"
7+
description: |
8+
Instructs the beacon node to use the components of the `SignedBlindedBeaconBlock` to construct and publish a
9+
`SignedBeaconBlock` by swapping out the `transactions_root` for the corresponding full list of `transactions`.
10+
The beacon node should broadcast a newly constructed `SignedBeaconBlock` to the beacon network,
11+
to be included in the beacon chain. The beacon node is not required to validate the signed
12+
`BeaconBlock`, and a successful response (20X) only indicates that the broadcast has been
13+
successful. The beacon node is expected to integrate the new block into its state, and
14+
therefore validate the block internally, however blocks which fail the validation are still
15+
broadcast but a different status code is returned (202). Pre-Bellatrix, this endpoint will accept
16+
a `SignedBeaconBlock`. The broadcast behaviour may be adjusted via the `broadcast_validation`
17+
query parameter.
18+
parameters:
19+
- name: broadcast_validation
20+
in: query
21+
required: false
22+
description: |
23+
Level of validation that must be applied to a block before it is broadcast.
24+
25+
Possible values:
26+
- **`gossip`** (default): lightweight gossip checks only
27+
- **`consensus`**: full consensus checks, including validation of all signatures and
28+
blocks fields _except_ for the execution payload transactions.
29+
- **`consensus_and_equivocation`**: the same as `consensus`, with an extra equivocation
30+
check immediately before the block is broadcast. If the block is found to be an
31+
equivocation it fails validation.
32+
33+
If the block fails the requested level of a validation a 400 status MUST be returned
34+
immediately and the block MUST NOT be broadcast to the network.
35+
36+
If validation succeeds, the block must still be fully verified before it is
37+
incorporated into the state and a 20x status is returned to the caller.
38+
schema:
39+
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/BroadcastValidation'
40+
- in: header
41+
schema:
42+
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
43+
required: false
44+
name: Eth-Consensus-Version
45+
description: "Version of the block being submitted, if using SSZ encoding."
46+
requestBody:
47+
description: "The `SignedBlindedBeaconBlock` object composed of `BlindedBeaconBlock` object (produced by beacon node) and validator signature."
48+
required: true
49+
content:
50+
application/json:
51+
schema:
52+
oneOf:
53+
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock'
54+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Altair.SignedBeaconBlock"
55+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock"
56+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBlindedBeaconBlock"
57+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlindedBeaconBlock"
58+
application/octet-stream:
59+
schema:
60+
description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body."
61+
responses:
62+
"200":
63+
description: "The block was validated successfully and has been broadcast. It has also been integrated into the beacon node's database."
64+
"202":
65+
description: "The block failed validation, but was successfully broadcast anyway. It was not integrated into the beacon node's database."
66+
"400":
67+
description: "The `SignedBlindedBeaconBlock` object is invalid"
68+
content:
69+
application/json:
70+
schema:
71+
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
72+
example:
73+
code: 400
74+
message: "Invalid block: missing signature"
75+
"415":
76+
$ref: '../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType'
77+
"500":
78+
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
79+
"503":
80+
$ref: '../../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'

‎apis/beacon/blocks/blocks.v2.yaml

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
post:
2+
tags:
3+
- Beacon
4+
- ValidatorRequiredApi
5+
summary: "Publish a signed block."
6+
operationId: "publishBlockV2"
7+
description: |
8+
Instructs the beacon node to broadcast a newly signed beacon block to the beacon network,
9+
to be included in the beacon chain. A success response (20x) indicates that the block
10+
passed gossip validation and was successfully broadcast onto the network.
11+
The beacon node is also expected to integrate the block into the state, but may broadcast it
12+
before doing so, so as to aid timely delivery of the block. Should the block fail full
13+
validation, a separate success response code (202) is used to indicate that the block was
14+
successfully broadcast but failed integration. The broadcast behaviour may be adjusted via the
15+
`broadcast_validation` query parameter.
16+
parameters:
17+
- name: broadcast_validation
18+
in: query
19+
required: false
20+
description: |
21+
Level of validation that must be applied to a block before it is broadcast.
22+
23+
Possible values:
24+
- **`gossip`** (default): lightweight gossip checks only
25+
- **`consensus`**: full consensus checks, including validation of all signatures and
26+
blocks fields _except_ for the execution payload transactions.
27+
- **`consensus_and_equivocation`**: the same as `consensus`, with an extra equivocation
28+
check immediately before the block is broadcast. If the block is found to be an
29+
equivocation it fails validation.
30+
31+
If the block fails the requested level of a validation a 400 status MUST be returned
32+
immediately and the block MUST NOT be broadcast to the network.
33+
34+
If validation succeeds, the block must still be fully verified before it is
35+
incorporated into the state and a 20x status is returned to the caller.
36+
schema:
37+
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/BroadcastValidation'
38+
- in: header
39+
schema:
40+
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
41+
required: false
42+
name: Eth-Consensus-Version
43+
description: "Version of the block being submitted, if using SSZ encoding."
44+
requestBody:
45+
description: "The `SignedBeaconBlock` object composed of `BeaconBlock` object (produced by beacon node) and validator signature."
46+
required: true
47+
content:
48+
application/json:
49+
schema:
50+
oneOf:
51+
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock'
52+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Altair.SignedBeaconBlock"
53+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBeaconBlock"
54+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock"
55+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBeaconBlock"
56+
application/octet-stream:
57+
schema:
58+
description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body."
59+
responses:
60+
"200":
61+
description: "The block was validated successfully and has been broadcast. It has also been integrated into the beacon node's database."
62+
"202":
63+
description: "The block could not be integrated into the beacon node's database as it failed validation, but was successfully broadcast."
64+
"400":
65+
description: "The `SignedBeaconBlock` object is invalid and could not be broadcast"
66+
content:
67+
application/json:
68+
schema:
69+
allOf:
70+
- $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
71+
- example:
72+
code: 400
73+
message: "Invalid block: missing signature"
74+
"415":
75+
$ref: '../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType'
76+
"500":
77+
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
78+
"503":
79+
$ref: '../../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'

‎beacon-node-oapi.yaml

+6
Original file line numberDiff line numberDiff line change
@@ -89,8 +89,12 @@ paths:
8989
$ref: "./apis/beacon/blocks/header.yaml"
9090
/eth/v1/beacon/blinded_blocks:
9191
$ref: "./apis/beacon/blocks/blinded_blocks.yaml"
92+
/eth/v2/beacon/blinded_blocks:
93+
$ref: "./apis/beacon/blocks/blinded_blocks.v2.yaml"
9294
/eth/v1/beacon/blocks:
9395
$ref: "./apis/beacon/blocks/blocks.yaml"
96+
/eth/v2/beacon/blocks:
97+
$ref: "./apis/beacon/blocks/blocks.v2.yaml"
9498
/eth/v2/beacon/blocks/{block_id}:
9599
$ref: "./apis/beacon/blocks/block.v2.yaml"
96100
/eth/v1/beacon/blocks/{block_id}/root:
@@ -207,6 +211,8 @@ components:
207211
$ref: './types/state.yaml#/BeaconState'
208212
BeaconBlock:
209213
$ref: './types/block.yaml#/BeaconBlock'
214+
BroadcastValidation:
215+
$ref: './types/api.yaml#/BroadcastValidation'
210216
DepositSnapshotResponse:
211217
$ref: './types/api.yaml#/DepositSnapshotResponse'
212218
SignedBeaconBlock:

‎types/api.yaml

+5
Original file line numberDiff line numberDiff line change
@@ -81,3 +81,8 @@ Committee:
8181
description: "List of validator indices assigned to this committee"
8282
items:
8383
$ref: './primitive.yaml#/Uint64'
84+
85+
BroadcastValidation:
86+
description: Level of validation that must be applied to a block before it is broadcast.
87+
type: string
88+
enum: [gossip, consensus, consensus_and_equivocation]

0 commit comments

Comments
 (0)