Configurable Builder API Mock Server

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

Installation

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 .

Default config

The default secret key of the mock builder is 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f, which always yields the public key 0x95fde78acd5f6886ddaf5d0056610167c513d09c1c0efabbc7cdcc69beea113779c4a81e2d24daafc5387dbf6ac5fe48.

Mock Payload Building

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.

Payload Invalidation Types

• state_root: Inserts a random state root value in the built payload. Payload can only be deemed invalid after the payload has been unblinded
• parent_hash: Inserts a random parent hash value in the built payload. Payload can be deemed invalid without needing to unblind
• coinbase: Inserts a random address as coinbase in the built payload. Payload is not invalid
• base_fee: Increases the base fee value by 1 in the built payload. Payload can only be deemed invalid after the payload has been unblinded
• uncle_hash: Inserts a random uncle hash value in the built payload. Payload can be deemed invalid without needing to unblind
• receipt_hash: Inserts a random receipt hash value in the built payload. Payload can only be deemed invalid after the payload has been unblinded

Payload Attributes Invalidation Types

• remove_withdrawal: Removes a withdrawal from the correct list of expected withdrawals
• extra_withdrawal: Inserts an extra withdrawal to the correct list of expected withdrawals
• withdrawal_address, withdrawal_amount, withdrawal_validator_index, withdrawal_index: Invalidates a single withdrawal from the correct list of expected withdrawals
• timestamp: 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} using WithErrorOnHeaderRequest option
• /eth/v1/builder/blinded_blocks using WithErrorOnPayloadReveal 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.

Mock Builder REST API

Mock Error

• 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 specified
• DELETE /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

Mock Built Payloads

• 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

Statistics

• 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)