Instantiates a server that listens for Builder API (https://github.com/ethereum/builder-specs/) directives and responds with payloads built using an execution client.
Currently, the builder will produce payloads with the following correct fields:
- PrevRandao
- Timestamp
- SuggestedFeeRecipient
- Withdrawals
For the builder to function properly, the following parameters are necessary:
- Execution client: Required to build the payloads
- Beacon client: Required to fetch the state of the previous slot, and calculate, e.g., the prevrandao value
To install mock-builder, you need to have Go installed on your machine. Once Go is installed, you can clone the repository and build the project.
git clone https://github.com/marioevz/mock-builder.git
cd mock-builder
go build .
The default secret key of the mock builder is 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
, which always yields the public key 0x95fde78acd5f6886ddaf5d0056610167c513d09c1c0efabbc7cdcc69beea113779c4a81e2d24daafc5387dbf6ac5fe48
.
The builder can inject modifications into the built payloads at predefined slots by using configurable callbacks:
- Before sending the ForkchoiceUpdated directive to the execution client, by modifying the payload attributes, using
WithPayloadAttributesModifier
option - Before responding with the build payload to the consensus client by modifying the any field in the payload, using
WithPayloadModifier
option
Both callbacks are supplied with either the PayloadAttributesV1
/PayloadAttributesV2
or the ExecutionPayloadV1
/ExecutionPayloadV2
object, and the beacon slot number of the payload request.
The callbacks must respond with a boolean indicating whether any modification was performed, and an error, if any.
Predefined invalidation can also be configured by using WithPayloadInvalidatorAtEpoch
, WithPayloadInvalidatorAtSlot
, WithPayloadAttributesInvalidatorAtEpoch
or WithPayloadAttributesInvalidatorAtSlot
.
state_root
: Inserts a random state root value in the built payload. Payload can only be deemed invalid after the payload has been unblindedparent_hash
: Inserts a random parent hash value in the built payload. Payload can be deemed invalid without needing to unblindcoinbase
: Inserts a random address as coinbase in the built payload. Payload is not invalidbase_fee
: Increases the base fee value by 1 in the built payload. Payload can only be deemed invalid after the payload has been unblindeduncle_hash
: Inserts a random uncle hash value in the built payload. Payload can be deemed invalid without needing to unblindreceipt_hash
: Inserts a random receipt hash value in the built payload. Payload can only be deemed invalid after the payload has been unblinded
remove_withdrawal
: Removes a withdrawal from the correct list of expected withdrawalsextra_withdrawal
: Inserts an extra withdrawal to the correct list of expected withdrawalswithdrawal_address
,withdrawal_amount
,withdrawal_validator_index
,withdrawal_index
: Invalidates a single withdrawal from the correct list of expected withdrawalstimestamp
: Modifies the expected timestamp value of the block (-2 epochs)prevrandao
/random
: Modifies the expected prevrandao
The builder can also be configured to insert an error on:
/eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}
usingWithErrorOnHeaderRequest
option/eth/v1/builder/blinded_blocks
usingWithErrorOnPayloadReveal
option
Both callbacks are supplied with the beacon slot number of the payload/blinded block request.
The callback can then use the slot number to determine whether to throw an error or not.
DELETE
/mock/errors/payload_request
: Disables errors on/eth/v1/builder/header/...
POST
/mock/errors/payload_request
: Enables errors on/eth/v1/builder/header/...
POST
/mock/errors/payload_request/<slot|epoch>/{slot/epoch number}
: Enables errors on/eth/v1/builder/header/...
starting at the slot or epoch specifiedDELETE
/mock/errors/payload_reveal
: Disables errors on/eth/v1/builder/blinded_blocks
POST
/mock/errors/payload_reveal
: Enables errors on/eth/v1/builder/blinded_blocks
POST
/mock/errors/payload_reveal/<slot|epoch>/{slot/epoch number}
: Enables errors on/eth/v1/builder/blinded_blocks
starting at the slot or epoch specified
-
DELETE
/mock/invalid/payload_attributes
: Disables any payload attributes modification -
POST
/mock/invalid/payload_attributes/{type}
: Enables specified type payload attributes modification -
POST
/mock/invalid/payload_attributes/{type}/<slot|epoch>/{slot/epoch number}
: Enables specified type payload attributes modification starting at the slot or epoch specified -
DELETE
/mock/invalid/payload
: Disables any modification to payload built -
POST
/mock/invalid/payload/{type}
: Enables specified type of modification to payload built -
POST
/mock/invalid/payload/{type}/<slot|epoch>/{slot/epoch number}
: Enables specified type of modification to payload built starting at the slot or epoch specified
GET
/mock/stats/validation_errors
: Returns a JSON containing all the errors encountered when validating the submitted signed blinded responses from the consensus client (e.g. Invalid signature on submitted blinded block)