diff --git a/apis/relay/builder/blocks_with_proofs.yaml b/apis/relay/builder/blocks_with_proofs.yaml new file mode 100644 index 0000000..d46b96f --- /dev/null +++ b/apis/relay/builder/blocks_with_proofs.yaml @@ -0,0 +1,56 @@ +post: + operationId: "submitBlockWithProofs" + summary: Submit a new block with inclusion proofs to the relay. + description: | + * This endpoint allows submitting blocks with inclusion proofs to the relay. + + * Blocks can be submitted in JSON or SSZ format, optionally GZIP encoded. + + * For JSON, the content type should be `application/json`. For SSZ, the content type should be `application/octet-stream`. + + * To enable GZIP compression, the HTTP content encoding should be `gzip`. Compression is optional. + + * The relay will verify the block's properties and the proposer payment in the transaction from builder to proposer `fee_recipient`. + + * The builder signature is over the SSZ encoded `message`. + + * The `message`, excluding transactions, will be made public via the data API, allowing verification of the builder signature. + + * Any new submission by a builder will overwrite a previous one by the same `builder_pubkey`, even if it is less profitable. + tags: + - Builder + parameters: + - name: cancellations + in: query + required: false + description: If set to 1, opt into bid cancellations. + schema: + $ref: "../../../relay-oapi.yaml#/components/schemas/Uint64" + requestBody: + description: A signed bid with an execution payload and inclusion proofs. + required: true + content: + application/json: + schema: + $ref: "../../../relay-oapi.yaml#/components/schemas/Deneb.SubmitBlockWithProofsRequest" + examples: + deneb: + $ref: "../../../relay-oapi.yaml#/components/examples/Deneb.SubmitBlockWithProofsRequest" + application/octet-stream: + schema: + description: "SSZ serialized request. Use content type header to indicate that SSZ data is contained in the request body." + responses: + "200": + description: Success response. + "400": + description: Error response. + content: + application/json: + schema: + allOf: + - $ref: "../../../relay-oapi.yaml#/components/schemas/ErrorMessage" + - example: + code: 400 + message: "payload for this slot was already delivered" + "500": + $ref: "../../../relay-oapi.yaml#/components/responses/InternalError" diff --git a/apis/relay/builder/constraints.yaml b/apis/relay/builder/constraints.yaml new file mode 100644 index 0000000..7ba83ac --- /dev/null +++ b/apis/relay/builder/constraints.yaml @@ -0,0 +1,41 @@ +get: + operationId: "getConstraints" + summary: Get constraints stream from the relay. + description: | + * This endpoint allows fetching a stream of constraints from the relay. + + * The response is a stream of signed constraints, including messages and signatures. + + * The `backfill` parameter can be used to opt into backfilling constraints. + + * The headers `Content-Type` should be `text/event-stream` and `Connection` should be `keep-alive`. + tags: + - Builder + parameters: + - name: backfill + in: query + required: false + description: If set to true, opt into backfilling constraints. + schema: + type: boolean + headers: + Content-Type: + schema: + type: string + example: "text/event-stream" + Connection: + schema: + type: string + example: "keep-alive" + requestBody: + description: Empty request body. + required: false + responses: + "200": + description: Stream of signed constraints. + content: + text/event-stream: + schema: + $ref: "../../../relay-oapi.yaml#/components/schemas/Deneb.SignedConstraints" + "500": + $ref: "../../../relay-oapi.yaml#/components/responses/InternalError" \ No newline at end of file diff --git a/examples/deneb/submit_block_with_proofs_request.json b/examples/deneb/submit_block_with_proofs_request.json new file mode 100644 index 0000000..60e8e10 --- /dev/null +++ b/examples/deneb/submit_block_with_proofs_request.json @@ -0,0 +1,178 @@ +{ + "value": { + "inner": { + "message": { + "slot": "1", + "proposer_index": "1", + "parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "body": { + "randao_reveal": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505", + "eth1_data": { + "deposit_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "deposit_count": "1", + "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + }, + "graffiti": "0xdeadbeefc0ffeedeadbeefc0ffeedeadbeefc0ffeedeadbeefc0ffeedeadbeef", + "proposer_slashings": [ + { + "signed_header_1": { + "message": { + "slot": "1", + "proposer_index": "1", + "parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "body_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + }, + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + }, + "signed_header_2": { + "message": { + "slot": "1", + "proposer_index": "1", + "parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "body_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + }, + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + } + } + ], + "attester_slashings": [ + { + "attestation_1": { + "attesting_indices": ["1"], + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505", + "data": { + "slot": "1", + "index": "1", + "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "source": { + "epoch": "1", + "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + }, + "target": { + "epoch": "1", + "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + } + } + }, + "attestation_2": { + "attesting_indices": ["1"], + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505", + "data": { + "slot": "1", + "index": "1", + "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "source": { + "epoch": "1", + "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + }, + "target": { + "epoch": "1", + "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + } + } + } + } + ], + "attestations": [ + { + "aggregation_bits": "0x01", + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505", + "data": { + "slot": "1", + "index": "1", + "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "source": { + "epoch": "1", + "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + }, + "target": { + "epoch": "1", + "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + } + } + } + ], + "deposits": [ + { + "proof": [ + "0xeeffb6c21a01d3abf09cd6c56e5d48f5ea0fc3bb0de906e3beea3e73776329cb", + "0x601c3b24a99d023224d50811bed19449890febb719a31d09ac414c4632f3c0ba", + "..." + ], + "data": { + "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a", + "withdrawal_credentials": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "amount": "1", + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + } + } + ], + "voluntary_exits": [ + { + "message": { + "epoch": "1", + "validator_index": "1" + }, + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + } + ], + "sync_aggregate": { + "sync_committee_bits": "0x01", + "sync_committee_signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + }, + "execution_payload_header": { + "parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09", + "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "block_number": "1", + "gas_limit": "1", + "gas_used": "1", + "timestamp": "1", + "extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "base_fee_per_gas": "1", + "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "transactions_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + } + }, + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + } + }, + "proof": { + "indexes": [1], + "transaction_hashes": [ + "b190c3b9978f9bb065fa841358745bb05f1a26ba5b455ac10161ba066e4b2999" + ], + "merkle_hashes": [ + [ + "0x0000000000000000000000000000000000000000000000000000000000000000", + "0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b", + "0xdb56114e00fdd4c1f85c892bf35ac9a89289aaecb1ebd0a96cde606a748b5d71", + "0xc78009fdf07fc56a11f122370658a353aaa542ed63e44c4bc15ff4cd105ab33c", + "0x536d98837f2dd165a55d5eeae91485954472d56f246df256bf3cae19352a123c", + "0x9efde052aa15429fae05bad4d0b1d7c64da64d03d7a1854a588c2cb8430c0d30", + "0xd88ddfeed400a8755596b21942c1497e114c302e6118290f91e6772976041fa1", + "0x87eb0ddba57e35f6d286673802a4af5975e22506c7cf4c64bb6be5ee11527f2c", + "0x26846476fd5fc54a5d43385167c95144f2643f533cc85bb9d16b782f8d7db193", + "0x506d86582d252405b840018792cad2bf1259f1ef5aa5f887e13cb2f0094f51e1", + "0xffff0ad7e659772f9534c195c815efc4014ef1e1daed4404c06385d11192e92b", + "0x6cf04127db05441cd833107a52be852868890e4317e6a02ab47683aa75964220", + "0xb7d05f875f140027ef5118a2247bbb84ce8f2f0f1123623085daf7960c329f5f", + "0xdf6af5f5bbdb6be9ef8aa618e4bf8073960867171e29676f8b284dea6a08a85e", + "0xb58d900f5e182e3c50ef74969ea16c7726c549757cc23523c369587da7293784", + "0xd49a7502ffcfb0340b1d7885688500ca308161a7f96b62df9d083b71fcc8f2bb", + "0x8fe6b1689256c0d385f42f5bbe2027a22c1996e110ba97c171d3e5948de92beb", + "0x8d0d63c39ebade8509e0ae3c9c3876fb5fa112be18f905ecacfecb92057603ab", + "0x95eec8b2e541cad4e91de38385f2e046619f54496c2382cb6cacd5b98c26f5a4", + "0xf893e908917775b62bff23294dbbe3a1cd8e6cc1c35b4801887b646a6f81f17f", + "0x0100000000000000000000000000000000000000000000000000000000000000" + ] + ] + } + } +} \ No newline at end of file diff --git a/relay-oapi.yaml b/relay-oapi.yaml index 4138239..e3ab515 100644 --- a/relay-oapi.yaml +++ b/relay-oapi.yaml @@ -28,8 +28,12 @@ tags: paths: /relay/v1/builder/validators: $ref: "./apis/relay/builder/validators.yaml" + /relay/v1/builder/constraints: + $ref: "./apis/relay/builder/constraints.yaml" /relay/v1/builder/blocks: $ref: "./apis/relay/builder/blocks.yaml" + /relay/v1/builder/blocks_with_proofs: + $ref: "./apis/relay/builder/blocks_with_proofs.yaml" /relay/v1/data/bidtraces/proposer_payload_delivered: $ref: "./apis/relay/data/proposer_payload_delivered.yaml" /relay/v1/data/bidtraces/builder_blocks_received: @@ -55,6 +59,10 @@ components: $ref: "./types/capella/requests.yaml#/Capella/SubmitBlockRequest" Deneb.SubmitBlockRequest: $ref: "./types/deneb/requests.yaml#/Deneb/SubmitBlockRequest" + Deneb.SubmitBlockWithProofsRequest: + $ref: "./types/deneb/proof_requests.yaml#/Deneb/SubmitBlockWithProofsRequest" + Deneb.SignedConstraints: + $ref: "./types/deneb/constraints.yaml#/Deneb/SignedConstraints" ValidatorsResponse: $ref: "./types/responses.yaml#/ValidatorsResponse" DeliveredPayloadsResponse: @@ -73,3 +81,5 @@ components: $ref: "./examples/capella/submit_block_request.json" Deneb.SubmitBlockRequest: $ref: "./examples/deneb/submit_block_request.json" + Deneb.SubmitBlockWithProofsRequest: + $ref: "./examples/deneb/submit_block_with_proofs_request.json" diff --git a/types/deneb/constraints.yaml b/types/deneb/constraints.yaml new file mode 100644 index 0000000..2cf5f86 --- /dev/null +++ b/types/deneb/constraints.yaml @@ -0,0 +1,39 @@ +Deneb: + SignedConstraints: + type: object + properties: + message: + $ref: "#/Deneb/ConstraintsMessage" + signature: + type: string + description: | + The ECDSA signature of the ConstraintsMessage object, encoded as bytes and + hashed with the keccak256 hash. The signature must come from the key-pair + associated with the proposer opted-in into Bolt. + ConstraintsMessage: + type: object + properties: + validator_index: + type: string + items: + $ref: "../../relay-oapi.yaml#/components/schemas/Uint64" + slot: + type: string + items: + $ref: "../../relay-oapi.yaml#/components/schemas/Uint64" + constraints: + type: array + items: + $ref: "#/Deneb/Constraint" + Constraint: + type: object + properties: + tx: + type: string + description: Transaction bytes. + index: + type: integer + items: + $ref: "../../relay-oapi.yaml#/components/schemas/Uint64" + nullable: true + description: Position index in the block. diff --git a/types/deneb/proof_requests.yaml b/types/deneb/proof_requests.yaml new file mode 100644 index 0000000..e8eb5b3 --- /dev/null +++ b/types/deneb/proof_requests.yaml @@ -0,0 +1,27 @@ +Deneb: + SubmitBlockWithProofsRequest: + allOf: + - $ref: './requests.yaml#/Deneb/SubmitBlockRequest' + - type: object + properties: + execution_payload: + $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload" + + InclusionProof: + type: object + properties: + transaction_hashes: + type: array + items: + $ref: "../../beacon-apis/types/primitive.yaml#/Bytes32" + maxItems: 256 + generalized_indexes: + type: array + items: + $ref: "../../beacon-apis/types/primitive.yaml#/Uint64" + maxItems: 256 + merkle_hashes: + type: array + items: + type: array + maxItems: 256 \ No newline at end of file